Making of the SGI Image Plugin

Why this plugin?
In our studio, we use Silicon Graphics (SGI) workstations to do visual effects work for movies and television. Consequently, a lot of images are generated and stored in the SGI image file format (referred hereafter as SGI images). Personal Computers (PCs) are fast replacing our SGI workstations as a cost-effective alternative. But our film scanners and recorders are still connected to SGI workstations and process only SGI images. We too want to work with SGI images because we are comfortable with it and have pulled off so many successful projects with it. On the PC front, Photoshop is a great program for analyzing images. But Photoshop does not read or write SGI images. So our artists convert the SGI images into TIFF images, load them into Photoshop, manipulate them, save them in TIFF format and convert them back to SGI format. The only problem with this approach apart from the time spent on two way conversion is the amount of disk space required to store the temporary TIFF images. A frame scanned at film resolution (2048w x 1736h) takes 10 MB of disk space if the image data is stored verbatim. A typical shot may have (at least) 100 frames amounting to 1 GB of disk space. The temporary TIFF files with image compression turned on take (at least) 250 MB. Manipulated TIFF files will take another 250 MB (because you don't want to overwrite the original, just in case you wanted to start all over). Conversion back to SGI uncompressed images will take another 1 GB. Therefore, there is a waste of about 500 MB due to lack of direct support for SGI images in Photoshop. All this for a shot with a typical minimum of frames. Imagine a bigger shot of say 2000 frames. That will amount to 10 GB of disk space wastage. This is enough requirement to develop a plugin that would read and write SGI images directly in Photoshop.

Adobe Photoshop Plugin Architecture:
There are two things that need to be defined first.  One is the term plugin host.  A plugin host is responsible for loading plugin modules and calling them.  Photoshop is a plugin host.  The second term is the plugin itself.  A plugin for Photoshop is a code module that extends the features of Photoshop without modifying the program itself.  To support SGI images inside Photoshop,  we need to write what Photoshop calls a Format Plugin.  Such a plugin can be accessed by the user from a pop-up menu in Open ..., Save As ... and Save A Copy... dialogs.

A Format plugin module, defines a function called ENTRYPOINT (in Windows 95/NT).  As the name suggests, ENTRYPOINT is the first function Photoshop calls when the user runs your plugin.  The following are the parameters for this function

The selector value indicates the type of operation requested by Photoshop for the plugin to perform.  The following table lists the values selector can take and what the plugin should do in each case.

Essentially the code in ENTRYPOINT transfers control to the corresponding handler for a given selector value.  If the plugin fails to handle a particular request, it sets an error value in result.   If this error value is positive, the plugin has handled the error situation and Photoshop does not worry about it.  If the error value is negative, Photoshop displays its standard error dialog and terminates the plugin.  The plugin will in other normal cases set the value of result equal to noErr. 

Through formatParamBlock, the plugin passes information back and forth to Photoshop.  The formatParamBlock is a huge structure containing a lot of parameters of which we will see an important few :

pluginData is a pointer to a chunk of global data the plugin maintains.   This usually includes the header information of the image. 

Implementation:

We will develop our plugin by modifying an example format plugin called SimpleFormat supplied with the Photoshop Plugin Software Development Kit.  A SimpleFormat image contains an image header followed by image data.  The image data has red channel of all pixels listed first, followed by green, blue and alpha (if present) channels.  The data is stored verbatim.  Even an SGI image contains a header that is followed by image data if it is stored verbatim.  The SGI header differs from the SimpleFormat header but the structure of the verbatim image data is the same.   Thus we can reuse the code section in the SimpleFormat plugin that reads its image data.  However, we need to replace code that reads the SimpleFormat header with one that reads the SGI header.   If the image data in an SGI image is run length encoded (RLE) (ie) compressed, we need to handle that situation too.  We have decided to write the image data verbatim, so we can reuse the code that writes the image data in the SimpleFormat plugin.  However, we need to make sure that the SGI header gets written and not the SimpleFormat header. 

The meat of the SimpleFormat plugin is in two files SimpleFormat.c and SimpleFormat.h.  In SimpleFormat.h, we find the definition of the SimpleFormat image header.  We modify it to represent the SGI image header instead.    The structure of the SGI image header is displayed in the following table:

In SimpleFormat.c, the function ENTRYPOINT is defined.  Based on the selector parameter value, it transfers control to an handler.  The following table lists the range of selector values supported and names of their corresponding handlers.

Reading the SGI image:
When the user selects a particular image file for loading,  Photoshop calls DoFilterFile to know if our plugin can handle the file.  In DoFilterFile, we check if the first two bytes of the file evaluate to 474.  If yes,  the selected file is an SGI image and we express our desire to handle it.  Otherwise, we set an error value in the result parameter.

When Photoshop finds that our plugin is willing to handle the file, it calls DoReadPrepare.  We now have the option of specifying the amount of memory we require to do the job.  In our plugin, we will allocate memory as we want it and hence set the field of required memory to zero.

The plugin is now ready to read the image file.  Photoshop calls DoReadStart to begin the process.  We read the image header in DoReadStart and set some important parameters of the formatParamBlock structure.  We set imageMode to pluginModeRGBColor,    height of the image in imageSize.v and the width in imageSize.h and  the number of color components of the image in planes.    SGI images may store only the alpha channel.  But Photoshop cannot accept a value less than 3 in the planes parameter when the imageMode parameter is set to pluginModeRGBColor.  Therefore, we fool Photoshop by setting the planes value to 4, dont load anything into red, green and blue channels (thus leaving them empty) and load the alpha channel in channel #4. 

We read the image data component by component, one scan line at a time in DoReadContinue.  As we know, SGI images can have their data stored verbatim or be compressed using the RLE scheme.  If the data is stored verbatim it is processed in DoVerbatimReadContinue else it goes to DoRLEReadContinue.   The code in DoVerbatimReadContinue is the same as the code that reads the image data in the SimpleFormat plugin.  We will now discuss how the compressed image data is parsed in DoRLEReadContinue. 

When the image data is compressed, two tables follow the image header.  These tables are of type long and their length is equal to the product of the number of components and the number of scan lines in the image.   For example, If the image has red, green and blue components and has 500 scan lines, then these tables will have 1500 entries each.  The first compressed red scan line will begin in the file at value of table entry 0, the first compressed green scan line will begin at the value of table entry 500 and the first compressed blue scan line will begin at the value of table entry 1000.  The corresponding entries in the second table will give the size of the compressed scan lines in bytes.    To parse a given scan line, we position the file pointer to the location suggested by the appropriate first table entry.  We read the compressed scan line into a buffer.  The amount of bytes to read is got from the corresponding second table entry.  We begin by reading a byte from this buffer.  We construct a runCount  from the first 7 bits (bit 0 through bit 6) and a  runCountFlag from bit 7.  If the runCountFlag is 0,  we read an another byte from the buffer and copy it runCount number of times into the data parameter of formatParamBlock.  If the runCountFlag is 1, we copy runCount number of bytes from the buffer to data.   We repeat this procedure until all bytes are consumed from the buffer.  The result is the scan line. 

Writing the SGI image:
When the user decides to save the image in memory in SGI format, Photoshop initiates the write sequence of the plugin.  The write sequence has the following sections:

We ignore the Options section.  In DoEstimatePrepare (Estimate section), we inform Photoshop how much disk space we want to save the file successfully.  Photoshop checks whether the requested space exists on the disk and if not terminates the plugin.   In DoWriteStart (Write section), we write the image header and the verbatim image data to disk.

Resources:
The user invokes our plugin by choosing the option "SGI" from the popups that appear in Open..., Save As..., and Save A Copy dialogs.  To get the text "SGI" to show up in those popups  we need to edit the resource identifiers in SimpleFormat.r.  The following table lists the resource identifiers that our plugin sets.

The plugInName along with the extensions appear in the popups.  We also use the plugInName and pluginDescription in the about box displayed when DoAbout is called.   

Conclusion:
As you know, this plugin reads only 8 bit SGI images at this time.  Though Photoshop supports conversion of 8 bit images into 16 bit images, all its image manipulation tools work only on 8 bit images.  Thus there is no point in reading into Photoshop a 16 bit image.  We will wait for the day when Photoshop can finally give us 16 bit image manipulation tools.  Until then, good bye.

References:

Best viewed in Netscape 4.x or IE 4.x @ 1024 | 768 | 16-bit colors
Please send bouquets or brickbats to sjagan@hotmail.com
Copyright (c) 1998 Jaganathan Sampath
All Rights Reserved