Scripting Photoshop: Working with the Document Model

Additional topics:

Manipulating an entire document

The document object provides properties and methods that affect the entire document, and provides access to the objects that describe and control specific parts or features of the document, such as the layers and channels.

You can use document methods, for example, to change the document size in various ways with document.resizeImage(), document.resizeCanvas(), or document.crop(). You can use document.flipCanvas() to flip the entire document vertically or horizontally. You can directly set properties such as document.resolution and document.pixelAspectRatio. You can change the currently active layer or channel in the document by setting activeLayer or activeChannel.

Other read-only properties provide information about the document's content, including the contained layers, associated guides, channels and color information. In many cases, these properties contains another type of object or collection of objects.

Document-wide operations

This example uses Document methods to perform some document-wide operations on the active document. It resizes both the image and the canvas, trims the top and bottom of the image, crops it, and flips it horizontally.

// get active document
var docRef:Document = app.activeDocument;

// set size in inches
docRef.resizeImage( "4in","4in" );
docRef.resizeCanvas( "4in","4in" );
docRef.trim(TrimType.TOPLEFT, true, false, true, false);

// change the ruler units to pixels, crop in pixels
app.preferences.rulerUnits =Units.PIXELS;
docRef.crop (new Array(100,200,400,500), 45, 20, 20);

// flip horizontally

History state

Photoshop keeps a history of the actions that affect documents. Each time you apply a change to an image in the Photoshop application, you create a history state; you can access a document’s history states from the History palette by selecting Window > History. In a script, you can access history states using the HistoryStates collection object, in the Document.historyStates property. You can use a HistoryState object to reset a document to a previous state, for example,  or to fill a Selection object.

You can use history states to undo modifications to the document; this example reverts the document contained in the variable docRef back to the form and properties it had when it was first opened or created.

docRef.activeHistoryState = docRef.historyStates.index(0);

Reverting back to a previous history state does not remove any later states from the history collection. Use the app.purge() method to remove later states from the HistoryStates collection:


This example saves the current state, applies a filter, and then reverts back to the saved history state.

var savedState:HistoryState = docRef.activeHistoryState;
docRef.artLayers.index(0).applyMotionBlur( 20, 20 );
docRef.activeHistoryState = savedState;

Document metadata

Document status information, such as whether the document has been saved since changes were made to it, and whether it is managed as a workgroup document, is available to scripts through Document properties:

if (docRef.managed){...}
if (!docRef.saved) {...}

File metadata for a document (which is accessible through the File > File Info menu in the UI) is stored in the DocumentInfo object, found in the property:

docInfoRef:DocumentInfo =;
docInfoRef.copyrighted = CopyrightedType.COPYRIGHTEDWORK;
docInfoRef.ownerUrl = "";

For camera RAW image files, XMP metadata is stored in a sidecar file; that is, a file in the same folder as the RAW file with the same base name and an XMP extension. This data is accessible to scripts through the Document.xmpMetadata property. This contains an xmpMetadata object, whose rawData property contains the metadata as a string, in XML/RDF format. For more information, see the XMP ActionScript Library.

Working with layers

The ArtLayer objects in a document contain the image contents, and correspond to the "layers" that the user works with in the UI. All of the ArtLayer objects in a document can be accessed directly through the Document.artLayers collection. In addition, you can collect subsets of art layers in a LayerSet collection object. Layer sets can be nested; that is, a set can contain another set. All of the LayerSet objects in a document can be accessed through the Document.layerSets collection.

Both ArtLayer and LayerSet derive from the base class Layer. All layers, both art layers and layer sets, are collected in Document.layers. To create either type of object, you can use the Document.layers.add() method, specifying the type. However, the easiest way to create either type of object is with the add() method of the respective collection object, ArtLayers or LayerSets:

// Create a new art layer at the top of the current document
var layerRef:Layer = app.activeDocument.artLayers.add();

// Create a new layer set at the top of the document
var newLayerSetRef:LayerSet = app.activeDocument.layerSets.add();

Another way to group layers is with layer compositions (LayerComp objects, collected in Document.layerComps). A LayerComp represents a snapshot of a state of layers in the document; it can be used to view different page layouts or compositions. Create a new LayerComp using the collection object's add() method:

var myComp:LayerComp = app.activeDocument.layerComps.add("myComp", "View from Shoreline", true, true, true);

Referencing and ordering layers

Layer sets (including the set of all layers contained in the Document.layers property) have a stacking order, which you can manipulate using the LayerSet.move() method:

// Get a reference to the first layer in the document
var layerRef:Layer = app.activeDocument.layers.index(0);

// Create a new LayerSet, by default at the top of the document
var newLayerSetRef:Layer = app.activeDocument.layerSets.add();

// Move the new layer set to after the previously first layer
newLayerSetRef.move(layerRef, ElementPlacement.PLACEAFTER);

When you create a layer in the Photoshop application (rather than a script), the layer is added to the Layers palette and given a number. These numbers act as layer names, but do not correspond to the index numbers of ArtLayer objects you create in a script. In scripting, the first layer in the collection (at index 0) is the one that is added last; it is the one at the top of the stacking order.  For example, if your document has four layers, the Photoshop application names them Background Layer, Layer 1, Layer 2, and Layer 3. Normally, Layer 3 would be at the top of the document, and at the top of the list in the Layers palette because you added it last. It is also at index 0 in the Document.artLayers collection.

You can access a layer by its name, as well as by its index number:

var baseLayer:Layer = app.activeDocument.artLayers.getByName("Background");

Because layer sets can be nested, you may have to drill down through contained layer sets to reach a particular layer or layer set:


Working with art layers

The ArtLayer object has properties that reflect and control various aspects of the layer, such as whether it is visible or locked, various mask values associated with it, and so on. These settings affect any art on that layer. For example, this script creates an art layer filled with red at the beginning of the current document:

// Create a new art layer at the beginning of the current document
var layerRef:Layer = app.activeDocument.artLayers.add(); = "MyBlendLayer";
layerRef.blendMode = BlendMode.NORMAL

// Select all so we can apply a fill to the selection

// Create a color to be used with the fill command
var colorRef:Color = new SolidColor(); = 255; = 100; = 0;

// Apply fill to the current selection

Your script can apply a style to an art layer, the equivalent of dragging a style from the Photoshop Styles palette to the layer. Use the ArtLayer.applyStyle() method, specifying the style name enclosed in straight double quotes. Style names are case sensitive, and are listed in the application Help.

docRef.artLayers.getByName("L1").applyStyle("Puzzle (Image)");

Working with text layers

The ArtLayer.kind property, whose value is a LayerKind constant, allows you to make the layer one of many specialized types. You can change an existing ArtLayer object to a text layer, that is, a TextItem object, if the layer is empty. Conversely you can change a TextItem object to an ArtLayer object; this operation rasterizes the text in the layer object.

To create a text layer, set the kind to LayerKind.text. To set or manipulate text in a text layer, use the TextItem object in the ArtLayer.textItem property.   

var myTextLayerRef:ArtLayer = docRef.artLayers.add();
myTextLayerRef.kind = LayerKind.TEXT;
var textRef:TextItem = myTextLayerRef.textItem;
textItem.contents = "This is new text in the layer."
textItem.color = colorRef; //previously assigned to red

For details of the TextItem and related text objects, see the scripting API reference documentation.




Copyright © 2010 Adobe Systems Incorporated. All rights reserved.