Getting Started – PsDotNet

You can receive support by emailing support@psdotnet.com

Download the QuickStart project OR Download the PsDotNet Library Demo and unzip to your local drive

Follow the Licensing instructions that apply to your use case.

If possible run Visual Studio as an administrator. Independent of PsDotNet, Photoshop sometimes has scratch disk issues. Best way to avoid them is to run as an administrator.

Add a reference to the PsDotNet.dll to your project

Make sure that Prefer 32-bit in your project settings is disabled.

At the appropriate initialization place in your code, add one of the following:

// Will start the highest version installed

PsConnection.StartAndConnect();

// OR

// Will start a specific version (if installed)

PsConnection.StartAndConnect(EPsVersion.CS6);

This only needs to be done once. If Photoshop is already started it will try to attach, otherwise it will start Photoshop and attach.

After initialization you can get the application by using the following code:

1	var app = PsConnection.Application;

Once you have the application you can do things like the following:

app.BackgroundColor = Color.Black.ToPsSolidColor();

app.ForegroundColor = Color.FromArgb(0, 0, 0, 128).ToPsSolidColor();

// Create a new document

IPsDocument document = app.Documents.Add(1024, 256, 72, "Welcome", EPsDocumentMode.psRGB);

//IPsDocument document = app.ActiveDocument;

// Add an alpha channel

document.Channels.Add("ExtraChannel", EPsChannelType.psMaskedAreaAlphaChannel);

// Create a new layer

IPsArtLayer cloudLayer = document.ArtLayers.AddNormalLayer("Clouds");

// Apply a few filters with default settings

cloudLayer.ApplyClouds();

cloudLayer.ApplyTwirl();

cloudLayer.ApplyAngledStrokes();

cloudLayer.ApplyAccentedEdges();

// Get a list of all of the available fonts

IEnumerable fonts = app.Fonts.Cast().ToList();

// Create a new text layer

IPsArtLayer textLayer = document.ArtLayers.AddTextLayer("Text");

textLayer.TextItem.Contents = ("Welcome to PsDotNet, " + Environment.UserName + "!");

var fontSize = 70;

textLayer.TextItem.Size = fontSize;

textLayer.TextItem.Position = new PointF((float)document.Width / 2, (float)document.Height / 2 + (float)fontSize / 2);

textLayer.TextItem.Justification = EPsJustification.psCenter;

textLayer.TextItem.Color = Color.OrangeRed.ToPsSolidColor();

textLayer.TextItem.Font = fonts.Skip(26).First();

textLayer.TextItem.HorizontalScale = 150;

// Create a layerStyle to apply to the Text layer

IPsLayerStyle layerStyle = app.CreateLayerStyle();

// Get the opposite color used from the foreground

IPsSolidColor pixelColor = app.ForegroundColor;

pixelColor.HSB.OffsetHue(180);

pixelColor.HSB.Saturation = 100;

pixelColor.HSB.Brightness = 100;

// Apply a glowStyle

IPsOuterGlowStyle glowStyle = layerStyle.AddOuterGlowStyle(pixelColor);

glowStyle.BlendMode = EPsLayerStyleBlendMode.Normal;

glowStyle.Opacity = 100;

glowStyle.Spread = 5;

glowStyle.Size = 50;

// Apply a strokeStyle

IPsStrokeStyleColorFillType strokeFill = app.CreateStrokeStyleColorFillType(Color.Black.ToPsSolidColor());

IPsStrokeStyle stroke = layerStyle.AddStrokeStyle(strokeFill);

stroke.Size = 2;

stroke.Position = EStrokePosition.Outside;

// Apply to the text layer

textLayer.ApplyLayerStyle(layerStyle);

// Flatten

document.Flatten();

Overview

Before you can do the obligatory “Hello World” example it is recommended that you understand a few key items. First off, if you are not already familiar with Photoshop’s object model, Adobe has some documentation that is worth reviewing in their scripting guides. You can get them here:http://www.adobe.com/devnet/photoshop/scripting.html

PsDotNet is structured the same as Photoshop object model, which is to say a “containment hierarchy”. This means that objects are partially defined by the objects that contain them. There is very close parity between the Photoshop and PsDotNet object model (with a few exceptions that will be discussed later). In Photoshop, the top level object is the Photoshop.Application, in PsDotNet it is the interface IPsApplication. The IPsApplication contains a Documents collection, which is a collection of IPsDocument. A IPsDocument contains collections such as IPsLayers, IPsArtLayers, IPsLayerSets, IPsChannels, IPsColorSamplers, IPsPathItems, etc. From these collections you can get to individual objects and manipulate them. Each of these objects will have properties and methods specific to that class that you can use to manipulate them.

Important note: In Photoshop you can have certain elements within a document with the same name. For example you can have several layers named the same. I would strongly recommend against having elements named the same thing “living next” to one another. Or in other words, 2 IPsArtLayers named the same thing at the root of your IPsDocument. That said, if you have those same 2 IPsArtLayers in separate IPsLayerSets, that would be ok since they would have unique paths from the root.

Many of the collections implement a ILookup interface with the key being the name of the element and the value will be IEnumerable of the type of element. This was the best solution that I could come up with to account duplicates. More info on this will be found later on in the documentation when we discuss dealing with IPsArtLayers, IPsPathItems, etc.

To help visualize the dependencies please refer to the following dependency diagram:

IPsApplication

IPsApplication is the root interface and entry point to using PsDotNet. The properties and methods of this interface will give you access to Photoshop’s global values such as preferences, available fonts, color settings, recent files, documents, etc..

In addition to the settings and functionality you are familiar with inside Photoshop itself, there are a number of helper methods to create specific types of objects for use with PsDotNet. For example you are able to create IPsSaveOptions, IPsSolidColors, and IPsPathItems to name a few.

IPsDocuments

The IPsApplication.Documents property contains a collection of all of the images Photoshop currently has open. This is a ILookUp collection with the key being the name of the document and the value a list of IPsDocument that match. There are a few methods to help with getting an open document.

The following will get an IEnumerable of all documents that are named “Test Document”:

1	var docs = app.Documents.GetAllByName("Test Document");

This will get the first document with “Test Document”:

1	var doc = app.Documents.GetByName("Test Document");

To get a list of all of the open documents you could use the following:

1	var docs = app.Documents.SelectMany(x => x);

This class is also where you will find the IPsDocuments.Add() methods that will create new documents:

1	var doc = app.Documents.Add( 512, 512 , 72 , "Test Document" , EPsDocumentMode.psRGB);

IPsDocument Elements

Photoshop has two categories of layers. An ArtLayer contains image contents and a LayerSet can contain none or many ArtLayer or other LayerSet. Intuitively in PsDotNet ArtLayers are represented by the IPsArtLayer interface and the LayerSet is defined by IPsLayerSet. There are a number of collections that are worth mentioning.

IPsLayers

Is a collection of IPsLayer(which is the base interface for IPsArtLayer and IPsLayerSet, see below). The IPsLayers class is very basic and should really only be used as a read only collection of IPsLayer.

IPsLayerSets

Is a collection of IPsLayerSet and is used by IPsDocument.LayerSets and IPsLayerSet.LayerSets properties.

IPsArtLayers

Is a collection of IPsArtLayer and is used by IPsDocument.ArtLayers and IPsLayerSet.ArtLayers properties.

IPsLayer

Both IPsArtLayer and IPsLayerSet inherit from IPsLayer where methods and properties that are common to both are defined. For example getting and setting Visibiliy, Opacity, or BlendMode. You will also find methods such as MoveAfter, MoveBefore, Link, MakeActive, Merge, and Rotate to name a few. A IPsLayer has a LayerType property that will denote if it is a IPsArtLayer or IPsLayerSet. There is no way to create a IPsLayer instance by itself.

IPsLayerSet

A LayerSet can be thought of as group or folder and it can contain none or many IPsArtLayer or other IPsLayerSet objects.

You can access top level IPsLayerSets through the IPsDocuments.LayerSets property. And since sets can contain other sets, you can get nested sets from IPsLayerSet.LayerSets property.

IPsArtLayer

A IPsArtLayer is most likely the main element you are most used to using in Photoshop. It is an element within a document that contains the visuals. It can be one of the following EPsLayerKinds: NormalLayer, TextLayer, SolidFillLayer, GradientFillLayer, PatternFillLayer, LevelsLayer, CurvesLayer, ColorBalanceLayer, BrightnessContrastLayer, HueSaturationLayer, SelectiveColorLayer, ChannelMixerLayer, GradientMapLayer, InversionLayer, ThresholdLayer, PosterizeLayer, SmartObjectLayer, PhotoFilterLayer, ExposureLayer, Layer3D, VideoLayer, BlackAndWhiteLayer*, Vibrance**, or ColorLookup**.

Taking a look at the methods and properties on an IPsArtLayer you will notice that there are a significant number of ApplyFilterXXX methods. You are also able to add and remove IPsLayerStyles utilizing the ApplyLayerStyle(), RemoveLayerStyle(), CopyLayerStyle(), and PasteLayerStyle() methods.

A collection of IPsArtLayer can be accessed from the IPsDocument.ArtLayers property or IPsLayerSet.ArtLayers properties.

IPsChannels

Is a collection of IPsChannel objects that is accessible via the IPsDocument.Channels property. The document’s Mode determines the number of default channels; for example, an RGB document has three channels, Red, Green, and Blue. You can create additional channels by using the IPsChannels.Add method. Since these non-default channels can technically be named the same, this collection is an ILookup just like the others in this library where the key is the name and value is an IEnumerable<IPsChannel>.

IPsChannel

Represents information about a color element in the document. A channel is analogous to a plate in the printing process that applies a single color. You can also have none or many alpha channels in your document.

Access through the IPsDocument.Channels collection.

IPsSelection

This class represents the selected area of a IPsDocument and also provides several ways to create and modify selections.

Access through the IPsDocument.Selection property.

IPsHistoryState

A version of the document stored automatically and added to the IPsDocument.HistoryStates collection, which preserves the document’s state, each time the document is changed.

IPsDocument.HistoryStates is an ILookup where the key is the name and the value is an IEnumerable<IPsHistoryState>.

IPsDocumentInfo

Contains metadata about a IPsDocument object. Contains info such as Author, Caption, CopyRighted, Keywords, etc.. These values are set manually in Photoshop via File -> File Info.

Access it through the IPsDocument.Info property.

IPsPathItem

A path or drawing object, such as the outline of a shape or a straight or curved line, which contains sub paths that define its geometry.

Access through the collection in the IPsDocument.PathItems property. Unlike the other collections in PsDotNet this one does not allow for path items to be named the same thing.

IPsSubPathItem

Represents a subpath; a collection of subpaths make up a IPsPathItem

Access through the IPsPathItem.SubPathItems collection.

IPsPathPoint

IPsPathPoint represents the anchor and control-handle endpoints for a path segment. Each point (the anchor point, left-direction point, and right-direction point) is an array containing X and Y position coordinates.

Access through the IPsSubPathItem.PathPoints collection. This collection is an ILookup where the key is the name of the path and the value is an IEnumberable<IPsPathItem>.

IPsSubPathInfo

IPsSubPathInfo objects are used to create IPsSubPathItem objects, which describes a straight or curves segment of a path.

IPsPathPointInfo

IPsPathPointInfo objects are used to create IPsPathPoint objects, which represents the anchor and control handles for a section of a sub path. For paths that are straight the coordinates of all three points are the same. For curved segments they would have different coordinates and the difference between determines the arc of the curve.

IPsPreferences

Represents application preferences for Photoshop.

Access this object through the IPsApplication.Preferences property. Setting values in this object is equivalent to selecting Edit -> Preferences.

IPsNotifier

An event-handler object that tells a script to execute specified code when a specified event occurs. Notifiers must be enabled using the IPsApplication.NotifiersEnabled property.

Access through the IPsApplication.Notifiers collection.

IPsColorSampler

Represents a color sampler point for a document.

Access through the IPsDocument.ColorSamplers collection.

IPsSolidColor

Represents a color definition used throughout Photoshop. Additionally it maps a color to equivalents to all supported color models.

IPsSaveOptions

Represents options for saving a document using the IPsDocument.SaveAs() method.

IPsGradient

IPsGradient and supporting interfaces are not found in the COM library but are included to help when creating and using gradients in Photoshop via PsDotNet. IPsGradient is the base interface that IPsSolidGradient and IPsNoiseGradient inherit from.

Creation of new IPsGradient objects is done by using the IPsApplication.CreateSolidGradient() and IPsApplication.CreateNoiseGradient() methods.