How to Write a Photoshop Plugin

Whither Photoshop

There are a lot of good reasons why you might want to implement your image manipulation research as a Photoshop plugin.

No need to package the code into a stand-alone process, so you won't need a full application library.
Can take advantage of Photoshop's import, export and processing options, so you can read and write any number of image formats and use various image filters and operations to make your research look better.
Done right, the result can be platform independent, working on Windows, Macs and Linux.
Easier for general public to use (including your Mom or even your advisor).
Avoids the "student code problem" where research programs become totally unusable a few days after graduation.

Getting the SDK

First step is to get Photoshop and then download the Photoshop SDK. If you don't have photoshop, it is available to staff (including RA's) from the CITES WebStore for $150. The SDK is available to students and faculty at http://www.adobe.com/devnet/photoshop/. You will need to register and get permission from Adobe to obtain and use it.

Compiling the Samples

Once you install the SDK, open samplecode/masterprojects/BuildAll.sln and build everything.

You can build some but not all of these plugins (Invert and Dissolve work) with the free version of Visual Studio Express, but it is better to get the full version of Visual Studio with Visual C++.

The built plugins are placed in samplecode/Output/win/debug so you'll need to tell Photoshop where to find them, via the Edit->Preferences->Plug-Ins->Additional Plug-Ins Folder. You have to restart Photoshop to get stuff to show up and to get the latest recompiled version of a plug-in. Photoshop CS3 boots up much faster than did CS2.

Simplifying the SDK

There are many kinds of plug-ins (e.g. importers & exporters) but the ones we are interested in are filters, and these should show up now in Filters->Adobe SDK (after you've opened an image, of course).

The sample code that is provided is really hard to understand and use. This is because the plug-in examples are designed for professional plugin developers that write Photoshop tools designed to integrate fully into the Photoshop package and work on all kinds and sizes of images. Thus the sample code contains a lot of extraneous details that interfere with the implementation of a research prototype including parameter persistence, images larger than 32Kx32K, tiled processing and arbitrary color spaces. All of these are good ideas when writing a commercial plugin but are mostly unnecessary for a research prototype, which can restrict itself to non-scripted processing of an entire 24-bit RGB image at typical resolutions.

Attached to this page is simple.zip containing the "Simple" photoshop plugin example. It applies some very simple channel math to an image (offsets red, inverts green and set blue to a constant) controlled by a small dialog window that opens up when the filter is invoked.

The simple plugin example captures the functionality I think is most needed for research prototypes, specifically an interface with a preview window to set parameters before running, but has specifically avoided the other functionality that interferes with a researcher's mental model of how a plugin would work.

Persistent parameters

The plugin SDK contains a lot of support and details for managing a plugin's parameters. This is because there is an option to rerun a plugin with the same parameters used last time, and because plugin parameters can be set in a script to automate filter sequences. Such parameter processing is great for production code, but requires a lot of coding that is unnecessary for a research prototype that will be likely run once on a single image.

Large image support

Photoshop was originally written using short ints for things like image resolution. But now we have large images (greater than 32,767 x 32,767) that exceed the short's range. The SDK includes support for large images using an auxilliary image-resolution structure that is filled when a flag is set. The samples include helper code for accessing the resolution based on this flag, but it is much simpler for research prototypes to work with images smaller than 32K (unless the research is on processing large images).

Tiled processing

Tiles image processing is perhaps the biggest, most confusing obstacle to writing a Photoshop filter plugin. The examples used tiled processing, which accesses a large image by breaking up the computation to work on small rectangular sections. This is a good ides for production code to promote a compact memory footprint, avoid page faults and work on arbitrarily large images. But for research code, especially when applying a filter, the management of tiles is cumbersome.

Photoshop does not require that you process an image in tiles. You can request the entire image at once and work on the whole thing.

Color spaces

The plugin examples support images in any of a variety of color spaces including CMYK and LAB, with a variety of channel depths. Research prototypes can safely focus on 24-bit RGB images, unless the research is on high-dynamic range images or color separation for printing. If an input image is in a different color space or color resolution, Photoshop can easily convert it into 24-bit RGB.

Compiling the Simple Plugin Example

Unpackage the simple.zip filter in the samplecode/filter subdirectory of your Photoshop SDK installation. (Default location is C:\Program Files\Adobe\Adobe Photoshop CS SDK\samplecode\filter.) Open simple/win/Simple.sln, build, and enjoy. The filter should show up with the others in Filter->Adobe SDK->Simple. You have to restart Photoshop to see any newly recompiled changes. You can also attach to Photoshop from Visual Studio (via Tools->Attach to Process) to debug your plugin.

Someone might want to make this work for the Mac.