PHOTOSHOP ACTIONS & SCRIPTING

What are Scripts?

Photoshop Scripts are programs that have been written in some supported underlying language and that perform automated actions in Photoshop.

What can you do with Scripts?

Scripts can do anything (within Photoshop, of course;-). They are fully functional computer programs that run within a self-contained Photoshop environment. The Script can be written in any supported underlying language. Some of the supported languages are platform dependent (e.g., Visual Basic is supported only on Windows platforms). This discussion addresses scripting in JavaScript which is platform independent.

What can't you do with Scripts?

You can't do Excel spreadsheet calculations within a Photoshop script because you are restricted to the Photoshop environment. Additionally, Photoshop scripts can't keep your coffee warm^¹.

How are Scripts related to Actions?

Actions are recorded keystrokes/mouse clicks that can be played back and Scripts are Photoshop programs that can be executed, thus they both represent a class of operations that “automate” Photoshop. And they both exist primarily to save you time.

Beyond this there is a deeper, more symbiotic relationship between Actions and Scripts. It is possible for Photoshop Scripts to execute/play Actions (i.e., the JavaScript doAction function) and for Photoshop Actions to call Scripts. The ability of Scripts to execute Actions is particularly important. This, in effect, combines the best of both worlds. Scripts can call Actions so that:

You have a quick modification and test capability by simply changing the Action versus having to rewrite the entire script
You can have a single script execute against multiple actions using the action files as a template. For example, you could have multiple picture frame types - wood, metal, plastic, matte - all invoked by the same script. This, of course, would limit what could be done within the Action to the template constraints.
Scripts add a dimension to Actions that they would not be capable of alone, for example Script/Action combinations:
- could provide a user friendly interface to invoke actions
- could have an Action execute a Script for things that are simple, but variable based on user input (e.g., increasing canvas size by a predetermined or a variable amount).

Enough Theory Already, Give me a Real World Example!

You bet. I just happened to have brought along a Script/Action integration example. The Action allows you to build any combination of wooden frames around a Photoshop image. There are 4 possible frame thicknesses and 14 possible types of woods to select from. Thus, picking a particular set of frames is an exercise in combinatorics. For example, if I would like to have 4 surrounding frames for my picture, then the possible number of selections would (or wood;-) be: 4x4x14 = 224! Finally, this is the type of action that could be easily grouped into a repeating set of questions; that is, for each frame you ask for the frame thickness and the wood type.

In the example provided, the Action does the underlying Photoshop work of actually building the frame and filling it with the selected wood type. So there are a total of 4x14=56 Actions. The job of the JavaScript program is to query the user and determine how many frames of what type are needed. Once the program determines what the user desires, it simply calls the appropriate Action from the set of 56 Actions in the right order to build the frames. The Action is named: GTH-WoodFrames.atn and the associated script is named: GTH-WoodFrames.jsx.

Note how well the Action compliments the Script and vice-versa. The Action, alone, would work but it would be an exercise in hand-eye coordination to find, click on, and play the appropriate set of frame Actions in the right order. The script, on the other hand, would be far more difficult to write (and update) if it were done entirely in JavaScript.

In order to execute the Action/Script combination, you need to first load the Action and make sure all of the on/off controls are checked. After this, you simply load and execute the script.

Advanced Actions

Actions can be called/played by other Actions. This is particularly advantageous when an Action Set contains many repetitive subcomponents that are reused. Any repetitive subcomponent can simply be an “underlying”, hidden Action that is called by a higher level Action.

If we use the current example of GTH-WoodFrames.atn, and analyze its structure, it breaks down as follows:

ACTION STEP	PURPOSE
*init	Gets things ready for processing (e.g., duplicates image, flattens image, creates working layer).
*thinBorder	Creates a thin border by increasing canvas size.
*medBorder	Creates a medium border by increasing canvas size.
*thickBorder	Creates a thick border by increasing canvas size.
*xtraThickBorder	Creates an extra thick border by increasing canvas size.
*makeFrameChannelMask	Creates a frame channel mask for the current frame.
*makeFrameLayerMask	Take the created frame channel mask and turns it into a layer mask for the frame layer and deletes the original channel. Mask.
*thinBorderFrame	Plays the previously defined Actions: init, thinBorder, and *makeFrameChannelMask in order.
*medBorderFrame	Plays the previously defined Actions: init, medBorder, and *makeFrameChannelMask in order.
*thickBorderFrame	Plays the previously defined Actions: init, thickBorder, and *makeFrameChannelMask in order.
*xtraThickBorderFrame	Plays the previously defined Actions: init, xtraThickBorder, and *makeFrameChannelMask in order.
*blackwood	Fills the frame layer with a blackwood pattern.
...	Fills the frame layer with a ... pattern.
*stripedMahogany	Fills the frame layer with a striped mahogany pattern.
ThinBlackwoodFrame	Plays the previously defined Actions: thinBorderFrame, blackwood, and *makeFrameLayerMask in order.
...	Plays the previously defined Actions: ...BorderFrame, ..., and *makeFrameLayerMask in order.
XtraThickStripedMahoganyFrame	Plays the previously defined Actions: xtraThickBorderFrame, stripedMahogany, and *makeFrameLayerMask in order.

An examination of the above Action Set shows that there is a well defined structure with Actions calling other Actions at multiple levels in order to reuse Action “code” and to simplify the overall process.

Without going into a lot of detail we note the following structure in terms of caller/callee relationship:

ACTION LEVEL	PURPOSE
Top Level	Creates the wooden frame by calling lower level Actions that: create the frame/border fill the frame layer with the appropriate pattern create the frame layer mask so that the picture and frame are integrated.
Frame/Border (2^nd) Level	Prepares frame layer by calling lower level Actions that: perform initialization steps create the frame/border create the frame channel mask
Pattern Fill (2^nd) Level	Fills the frame layer with the appropriate wood pattern.
Channel Mask (2^nd) Level	Creates a channel mask to be later linked to the frame layer.
Initialization (3^rd) Level	Prepares the “working” image from the initial image.
Frame/Border Creation (3^rd) Level	Create the appropriately sized border.
Channel Mask Creation (3^rd) Level	Create the frame channel mask.

A key point is that we have used multiple Actions at multiple levels to simplify and shorten the overall Action definition.

Some key points when using Action “subroutines” are:

Actions may call other Actions to any level of nesting; however you must have all "subroutines" enabled via the leftmost check box. Therefore, it would be reasonable to keep all subroutines local to the given Action.
Distinguish subroutines from top level callable actions (I use a "*" prefix) and place them at the end of the Action Set so they are not likely to be inadvertently played.
An Action played within another Action is "hard coded" as the Action's name; therefore if you change the Action file name, the play call is no longer valid. To correct this you must modify the binary .atn file by replacing all occurrences of the called name. This is a hex string preceded by the string count + 1. For example to replace "test01" with "GTH-WoodFrames" replace the string:
- 07 00 74 00 65 00 73 00 74 00 30 00 31 00
  - with
- 0F 00 47 00 54 00 48 00 2D 00 57 00 6F 00 6F 00 64 00 46 00 72 00 61 00 6D 00 65 00 73 00

Advanced Scripts

Photoshop JavaScript scripts are typically straightforward implementations of the corresponding Photoshop actions. The more advanced scripts employ sophisticated user interaction and allow more variety for a given script. Starting with Photoshop CS2, a complete User Interface capability at the Windows level was provided via the ScriptUI package. Programming details for the ScriptUI package can be found in the Adobe Photoshop CS2 Official JavaScript Reference (but not the CS3 reference). This reference is automatically included in .pdf format in the Photoshop release and is also available for Web download.

Finally, it should be noted in the example provided, the JavaScript program could simply call the Action sublevels directly and not use the 56 top-level Actions. This would greatly simplify the size of the Action Set at the cost of a slight increase in Script size. The key disadvantage of this approach would be that the Action Set would no longer be stand-alone and could only be invoked through the corresponding Script.

References

The most extensive Photoshop JavaScript references are available via the Web and are free. Some good Web sites that contain Script tutorials and downloads include:

http://www.ps-scripts.com/ (NOTE: This Web site is invaluable if you plan to get into serious scripting. They have a number of Forums and extensive help expertise. If you run into difficulty, particularly with ScriptUI, this is the only place that can help.)
http://www.tranberry.com/photoshop/photoshop_scripting/index.html
http://morris-photographics.com/photoshop/scripts/index.html
http://www.adobeforums.com/webx?13@@.3bbf2765

Available web scripting documents (JavaScript) include the Photoshop CS2 and CS3 Reference Manuals and User Manuals. They are available at:

There are also books on Photoshop scripting, but they do not have the depth that you will find in the free resources above. Some scripting books are:

Adobe Scripting (Chandler McWilliams)
The Photoshop CS2 Speed Clinic (Matt Kloskowski)
Working Smart in Adobe Photoshop CS2 (Conrad Chavez)

1Actually, they might. Scripts are tremendous time savers since they can perform in seconds operations that would otherwise take hours (or even be impossible). Thus it is conceivable that, by using scripts, you work so quickly that your coffee never has a chance to cool.