Tone Selection Script
– Usage Instructions –

This JavaScript helps the photographer analyze and select tones in an image by creating selections for each of the % brightness ranges of 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90% and 100%.  These percent brightness correspond to the Zone System ranges of Zones 0 through Zone X.  The selections are stored as alpha channels.

 

How The Script Works

The script has divided the 256 digital tones recognized by the Photoshop Curves command into the eleven zones of the Zone System.  It looks at your image and finds those pixels that fall into each of the zones and then creates a selection around those pixels and saves the selection as an alpha channel.  These channels are referred to in this document as the tone selection alpha channels.

When the script completes, you will not see anything different in the document window or the Layers panel.  However, you will see eleven new alpha channels in the Channels panel.  Figure 1B shows the Channels panel after the script was run for the image in Figure 1A.  As you can tell from Figure 1B, the image has areas in each of the eleven zones.

Figure 1A.  The image ...

Figure 1B.  ... and its eleven tone selection alpha channels

Tone

Why should you care about tone?  When taking a photograph, either on film or sensor, what you are recording is light (that may not be your subject, but it is your medium).  Light is composed of hue, saturation and tone.  Therefore, tone makes up a third of the information you are capturing.  And if you are a black and white photographer, tone makes up 100% of the information being captured.

Also, exposure is how we manage tone when taking a photograph.  An image that was over or under exposed did not have the proper shutter speed and/or f-stop for the film's or sensor's ISO speed.  To understand exposure, you must understand tone.  To understand light, you must understand tone.  In this document, tone, brightness and luminance are used interchangeably.

For most photographers, their first lesson in tone is usually learning about shadows and highlights.  Then they progress and learn about mid tones.  This takes them to 3 tonal ranges: shadows, highlights and mid tones.  The Zone System recognizes eleven tonal ranges based on full stop exposure changes ranging from solid black to solid white.  The Photoshop Curves command recognizes up to 256.  Who is right?  None of them and all of them.  One could argue there are an almost infinite number of tones.  But who can work with that many?  The Photoshop Color Range command allows the selection of shadows, mid tones and highlights.  The Curves command recognizes all 256 tones.  This script bridges the two by allowing us to work with the eleven zones of the Zone System.
 

Tonal Ranges

Table 1 below shows how the script divides the 256 digital tones into the eleven zones of the Zone System.  As you become more familiar with the Zone System, you may decide to define your own range.  The script allows you to define, and save, you own custom range.

 

Figure 1.  The Zone System

Zone	Min Digital Value	Mid Digital Value	Max Digital Value	% Brightness	Visible Detail	Gradient
0	0	6	12	0%	No
I	13	25	38	10%	No
II	39	51	63	20%	Barely
III	64	76	89	30%	Yes
IV	90	102	114	40%	Yes
V	115	127	140	50%	Yes
VI	141	153	165	60%	Yes
VII	166	179	191	70%	Yes
VIII	192	204	216	80%	Barely
IX	217	230	242	90%	No
X	243	249	255	100%	No

 

System Requirements

To run this script, you must have Photoshop CS or higher.  In Photoshop, you access scripts by clicking File > Scripts.  Since the script is written in JavaScript, it should run on both Windows and Macintosh operating systems.

The script must be executed from within Photoshop since it is processing Photoshop objects.

The Help feature needs an Internet connection in order to connect your web browser to the Support page on www.ZuberPhotographics.com.

 

Image Requirements

Color Modes and Bit Depth

The script will work with the following color modes:  RGB, CMYK, Grayscale, Duotone, and Lab.  The script will not work with the following color modes:  Bitmap, Indexed, Multichannel.

The script will work with both 8 bit and 16 bit per channel images.
 

Color Profile

As a serious photographer, your image file should be tagged with a color profile, but it does not have to be for this script to work.  For more about color profiles, visit the Profiles and Color Spaces page.
 

File Formats

The script can only be used with file formats that support layers and alpha channels, such as TIFF and PSD.  Since JPEG does not support alpha channels, the script cannot be used effectively with JPEG files.

 

Transparent Areas

Transparent areas in the image will be placed into Zone 0.
 

Your Prerequisites

To make full use of this script, you will want to have an understanding of tone, alpha channels, adjustment layers and layer masks.  You will also want a high level understanding of the Zone System.  It is a misconception that the Zone System only applies to black and white photography.  Every image, both color and black and white, both film and digital, has luminance, or tone.

Below are links to this web site that will take you to the page that describes the relevant topic.

• Tone page
• Alpha channels page
• Layers Panel page
• Zone System page

---

 

Create Tonal Range Selections

To create the tonal range selections, follow these steps.  If you have not already installed the script on your computer, read the download instructions page.
 

1. Turn off the visibility of any layer you do not want to be used when calculating tone, such as text layers, before running the script.
2. Within Photoshop, click File > Scripts > Tone Selection.  The dialog box shown in Figure 2 will be displayed.
3. Click the Create button.  The dialog box shown in Figure 3 will be displayed.
4. Either use the default range or create your own.  You create your own range by specifying new upper limits.
5. If more than one document is open, specify whether all open documents are to be processed or just the active one.
6. Click Continue.

 

The Create Ranges dialog box in Figure 3 functions as follows.  The TONAL RANGES panel is divided into three sections: Shadows, Mid Tones and Highlights.

• Each of these sections is divided into the appropriate zones.
• The first time you use the script, the default range will be shown in the text boxes.  You can change the upper limit of any zone except for Zone X.  The upper limit of Zone X is always 255.  Even though you can specify fractional limits, such as 140.5, it really makes no sense to do so.
• Within the TONAL RANGES panel are three buttons: Calc, Save and Default.
• The Calc button will recalculate the lower limits based on the upper limits you specify.  If it cannot derive a meaningful range, an Illogical range sequence error message will be displayed.
• The Save button will save your custom range as a text file on your computer.  From then on, whenever you use the script, it will use your custom range instead of the default range.  Only one custom range can be saved.  Fractional limits, such as 12.5, will not be saved correctly.
• The Default button will reset the dialog box to the hard coded upper and lower limits.  The Default button will not change or delete your saved custom range.  However, if you click the Default button and then click the Save button, the default range will be saved as your custom range.

 

The What would you like to do? panel has three options.

• Process all open documents will be active only if more than one document is open in Photoshop.  If only one document is open, then this option will be disabled, as seen in Figure 3.  Using this option will create tone selection alpha channels in all open documents.
• Process active document only is the default.  It will be the selected option even if more than one document is open in Photoshop.  Using this option will create tone selection alpha channels in the active document only, regardless of how many documents are actually open.
• Clean up active document.  Using this option will delete the tone selection alpha channels in the active document only, regardless of how many documents are actually open.  If selected, the TONAL RANGES panel will be disabled.

 

There are two main buttons: Continue and Cancel.

• If valid ranges are specified and either the Process all open documents or Process the active document is chosen, the Continue button will close the dialog box and the tone selection alpha channels will be created in the selected document(s).
• The Cancel button will close the dialog box and no processing will occur.

Once the document(s) has been processed, a finished dialog box will be displayed.  This dialog box is shown in Figure 4.  While the script creates the tone selection alpha channels, Photoshop will write many entries to the document's History panel.  The Finished dialog box gives you the option of deleting these entries in order to free up memory.  Unfortunately, the script cannot purge the history state for just one document.  Therefore, if you select Yes and then click OK, all history states for all open documents will be purged.

 

Cautions

• If the document being processed is in Quick Mask mode, the document will be placed in Standard Mode and you will lose your Quick Mask channel and selection.
• If any selections are active when the Create Ranges script begins, they will be automatically deselected by the script.

---

Loading Selections

Once the tone selection alpha channels have been created, you can use the script to load one or more of them as a single selection.
 

1. Within Photoshop, click File > Scripts > Tone Selection.  The main dialog box shown in Figure 5 will be displayed.
2. Click the Load button.  The dialog box shown in Figure 6 will be displayed.
3. Check which zone selections you want loaded.  You may check more than one.
4. If there is an active selection and you do not want the zone selections added to it, check Yes for deselect active selection first.
5. Click Continue.

 

The Load Tonal Ranges dialog box in Figure 6 functions as follows.  The TONAL RANGES panel is divided into three sections: Shadows, Mid Tones and Highlights.

• Each of these sections is divided into the appropriate zones.
• By default, none of the zones are selected.  Click the zones you would like to load as selections.  More than one zone can be selected.

 

The Deselect Active Selection First panel has two options.

• Yes is the default.  If a selection is active at the time the Continue button is clicked, it will be deselected before loading the selected zones as selections.
• If the No option is selected, then the selected zones will be added to the active selection.

The Clean up active document panel has the following options.

• Clicking Yes and then Continue will delete the tone selection alpha channels in the active document only, regardless of how many documents are actually open.  If selected, the TONAL RANGES panel will be disabled.
• The Reset button will reactivate the TONAL RANGES panel and unselect Yes.

There are two main buttons: Continue and Cancel.

• The Continue button will close the dialog box and either load the selected zones, or delete all tone selection alpha channels, depending on which options were chosen.  Only the active document is processed, regardless of how many documents are open.
• The Cancel button will close the dialog box and no processing will occur.

---

Reviewing Selections

There are two ways to see which pixels were placed in a particular zone.  You can use the script to load the specific zone as a selection as described in the previous section.  Or, you can use the Channels panel.

To use the Channels panel, click on the Channels tab to activate the Channels panel, as seen in Figure 7A.  Make sure the top most composite channel is visible.  Make the alpha channel corresponding to the desired zone visible.  In Figure 7A, this is Zone I.  The document window will then be overlaid with a rubylith colored mask as seen in Figure 7B.  Those areas covered by the mask are not in the zone.  Those areas not covered by the mask are in the zone.  As you can see, most of the image is covered by the mask.  The areas not covered by the mask in Figure 7B are in Zone I.

Figure 7A.  The Zone I alpha channel is visible.

Figure 7B.  The areas not covered by the rubylith colored mask are in Zone I.

---

The following messages may be seen while running the script.
 

Message:  Custom Range saved successfully
Explanation:  The upper limits on the Create Ranges dialog box have been saved in the file TZ-Threshold.txt.  The file is saved on the same computer that is running Photoshop.

 

Message:  Error closing the <file name> file
Explanation:  An unknown error has occurred while trying to close one of the script's non-image files.  The script does not close Photoshop documents.

 

Message:  Error closing the threshold text file after read
Explanation:  The script successfully read the saved upper limits from the text file, but it encountered an unknown error closing the file after reading the data.

 

Message:  Error creating the <file name> file
Explanation:  An unknown error has occurred while trying to create and open one of the script's non-image files.
 

 

Message:  Error opening the threshold text file for reading
Explanation:  The script found the text file that contains the custom range, but encountered an unknown error trying to open the file so it could retrieve the custom range.

 

Message:  Error writing to the <file name> file
Explanation:  An unknown error has occurred while trying to write data to one of the script's non-image files.

Message:  Illogical range sequence
Explanation:  The upper limits specified in the Create Ranges dialog box do not specify a sequence that can be processed.  Adhere to the follow rules when specifying the upper limits.

• The limits must be a number.  They cannot be blank.
• The upper limit of Zone 0 cannot exceed 236.
• The upper limit of Zone IX cannot exceed 254.
• The upper limit of Zone 0 can be 0.
• The lower limit of Zone X can be 255.  To set a lower limit of 255 for Zone X, set the upper limit of Zone IX to 254.
• Only Zones 0 and X can be single integer zones.  All other zones must have a range of at least two.  For example, Zone 0 can be from 0 to 0, Zone I can be from 1 to 2, but Zone II cannot be from 3 to 3.
• Every integer from 0 to 255 must be accounted for.

Message:  No Photoshop documents are open.  Script ending.
Explanation:  The script was selected to be run, but no documents are open in Photoshop.  At least one document must be open in Photoshop for the script to run.

 

Message:  <subdirectory name> folder creation failed
Explanation:  An unknown error has occurred while trying to create the subdirectory where the script stores its non-image files.

Message:  The document <document name> has an unsupported color mode: (DocumentMode.<color mode>)  Script ending.
Explanation:  Create tone selections for the active document only was selected, but the active document is in a color mode that does not support alpha channels and/or adjustment layers.  The script cannot be used on this document unless the image's color mode is changed to one supported by the script.


Message:  The document <document name> has an unsupported color mode: (DocumentMode.<color mode>)  Script will continue.
Explanation:  Create tone selections for all open documents was selected, but the document currently being processed is in a color mode that does not support alpha channels and/or adjustment layers.  The script will continue processing the next document once OK is clicked.


Message:  The necessary channels are not present in the active document.  Script ending.
Explanation:  Load selections was chosen from the main dialog box, but the tone selection alpha channels do not exist in the active document, so the script will end.  To create them, rerun the script and choose the Create Ranges option.


Message:  Unexpected error.  Script terminating.  Message = <message text>
Explanation:  An unknown error has occurred.  The script will end.

---

Created Objects

The script will create the following objects.

• Temporary adjustment layer.  While creating the tone selection alpha channels, the script will create an adjustment layer.  This adjustment layer is deleted by the script when it is finished.
• Temporary alpha channels.  While creating the tone selection alpha channels, the script will create two additional working channels.  These channels are deleted by the script when it is finished.
• If you save a custom range, a file called TZ-Threshold.txt will be created in a directory called \Data\TZ-ScriptData.  This directory will be created in the \Presets\Scripts Photoshop directory.
• If you click the Help button, a file called TZ-SupportPage.html will be created in a directory called \Data\TZ-ScriptData.  This directory will be created in the \Presets\Scripts Photoshop directory.
• The eleven tone selection alpha channels.