Scripting Photoshop

Additional topics:

Basic usage

A basic HelloWorld script accesses the singleton Application object, uses it to create a Document object, and uses that to create a text layer and its text content.

import com.adobe.csawlib.photoshop.Photoshop;
import com.adobe.photoshop.Application;

var app:Application =;

// Create a new 2x4 inch document and assign it to a variable
var docRef:Document = app.documents.add( "2in", "4in" );

// Create a new art layer containing text
var artLayerRef:ArtLayer = docRef.artLayers.add();
artLayerRef.kind = LayerKind.TEXT;

// Set the contents of the text layer
var textItemRef:TextItem = artLayerRef.textItem;
textItemRef.contents = "Hello, World";

Creating and obtaining objects

The collections in the Application and Document objects have add() methods that allow you create objects of the type contained in that collection. For example:

// Create a new layer in the first document

To work with an object in the Photoshop application, you must make it the front-most, or active object. For example, to work in a layer, you must first bring the layer to the front. To ensure that your methods affect the active document or layer, access it through the activeDocument or activeLayer property of its parent:

// Create 2 documents
var docRef:Document = app.documents.add("4in", "4in");
var otherDocRef:Document = app.documents.add ("4in", "6in");

// make docRef the active document
app.activeDocument = docRef;

// set the active layer in the active document
 docRef.activeLayer = docRef.layers.index(0);

More than one channel can be active at a time, so the document.activeChannels property takes an array of channels as a value. In order to set the active channels of a document, it must be the active document:

var theChannels:Array = new Array(docRef.channels.index(0), docRef.channels.index(2));
docRef.activeChannels = theChannels;

Alternatively, select all component channels by using the componentChannels property of the document:

app.activeDocument.activeChannels = app.activeDocument.componentChannels;

Opening existing documents

To open a document from a file, specify the path in the method. Because Photoshop supports many different file formats, you can specify the format of the document you are opening. If you do not specify the format, Photoshop infers the file’s default format from the filename extension:

var fileRef:File = app.path.resolvePath("Samples/Fish.psd");
var docRef:Document =;

For many of the supported file formats, the open operation can take various options, such as the width and height of the window in which the document is opened, or the page to which to open a multi-page document. The available options depend on the file type, so the open() method takes an options object of the appropriate type:


This example opens a generic (multi-page/multi-image) PDF document in RGB mode with a resolution of 72 pixels/inch. The document will open to page 3, and the document’s original shape will change to conform to the height and width properties if the original shape is not twice as wide as it is tall.

// Set the ruler units to pixels
var originalRulerUnits:Units = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;

// Get a reference to the file that we want to open
var fileRef:File = File.desktopDirectory.resolvePath("myPDF.pdf");

// Create a PDF options object
var pdfOpenOptions:PDFOpenOptions = new PDFOpenOptions;
pdfOpenOptions.mode = OpenDocumentMode.RGB;
pdfOpenOptions.resolution = 72; = 3;

// Open the file fileRef, pdfOpenOptions );

// restore unit settings
app.preferences.rulerUnits = originalRulerUnits;

Application preferences

Notice that this example follows good programming practice by saving and restoring the original user setting for the ruler-units application preference. The app.preferences property gives you access to the singleton Preferences object, which you use to set global preferences such as color picker, file saving options, guide-grid-slice settings, and so on. The preference properties correspond to the Photoshop CS5 Preferences dialog options, which are described in the Photoshop Help.

Saving documents

The method takes no parameters, and saves a document to the default Photoshop (PSD) format. Use document.saveAs() to save to another supported format, passing the appropriate type of save-options objects:


Some of these formats are available only when explicitly installed. The save options for a given format are not identical to the open options for that format. For complete details, see the API Reference documentation.

For example, this fragment saves the active document to a JPEG file:

// Create and initialize options object
var jpgSaveOptions:JPEGSaveOptions = new JPEGSaveOptions();

jpgSaveOptions.embedColorProfile = true;
jpgSaveOptions.formatOptions = FormatOptions.STANDARDBASELINE;
jpgSaveOptions.matte = MatteType.NONE;
jpgSaveOptions.quality = 1;

app.activeDocument.saveAs(File.desktopDirectory.resolvePath("test.jpg"), jpgSaveOptions, true, Extension.LOWERCASE);

You can also use document.exportDocument() to write the document to an Illustrator format, or to a web-optimized Photoshop format. In this case, use the appropriate export-options object:




Copyright © 2010 Adobe Systems Incorporated. All rights reserved.