[updated version: 1.1 at the end of this post]
At the end of this article you can find an as3 PSD document encoder that turns array of bitmaps into a layered photoshop document file.
I’ve decided to write this encoder because of several reasons:
- there is an actionScript PSD parser on the internet, but there are no encoders
- PSD encoders are parts of bigger projects and aren’t necessary fully compatible with PhotoShop
- I wanted to have a possibility of creation layered image files
- there are several formats that supports layers, but PSD is the most standard, supported by many apps
- Adobe specification of photoshop file format lacks some information that is necessary to create an encoder quickly and with no wandering in the dark
The encoder works like that:
//create two bitmaps, first will be a bottom layer, red rectangle, second will be a green rectangle in the center of the bottom layer
var bitmap1:Bitmap = new Bitmap( new BitmapData( 300, 300, true, 0xff0000 ) );
var bitmap2:Bitmap = new Bitmap( new BitmapData( 200, 200, true, 0x00ff00 ) );
bitmap2.x = 50; bitmap2.y = 50;
//encode 2 bitmaps into a PSD file
var byteArray:ByteArray = PSDEncoder.encodePSD( Vector.
// save the byteArray as a file
new FileReference().save( byteArray , "test_image.psd" );
This is the demo. The demo is very trivial, its just the code above in a button event handler, you just save the file after clicking, but I like demos, so here it is:
About the PSD specification pitfalls.
The specification can be found at: http://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577409_pgfId-1030196
I will discuss things that I stumbled upon when writing the encoder or things that appears to be unclear. I will focus on most common features of PSD.
File header section
The PSD file header is pretty straightforward. The “bitmap” color mode of file is special mode that is used to draw vector graphics, so better use CMYK or RGB
Color Mode Data Section
We will skip this one…
Image Resources Section
First field – “Length of image resource section.” – it is unclear whether this length should include 4 bytes of this field. Answer: NO it shouldn’t.
The thumbnail (image resource ID 0x040C)
- Supported formats for thumbnails, according to specification, are kJpegRGB and kRawRGB. The Raw RGB format however, doesn’t work on PhotoShop 7 (version that I’ve tested).
- Pay attention to data in 12th byte – widthbytes. It must be computed using the formula in the specification:
This is more fancy notation:widthbytes = width * 24 + 31 >> 5 << 2
This basically adds 1 to 3 bytes to width in bytes of the image, to make it divisible by 4. - Also - pay attention to the length of JFIF data (what is JFIF? Most today's .JPG images are contained in a JFIF container, if you paste JFIF data in a file and add .JPG extension, it will be an ordinary JPG image file). If the length is uneven, you must add 1 byte to the end of JFIF data (it is mentioned under Image Resources Section description). Most photoshop documents has thumbnails with size limited to 127x127 rectangle.
Layer and mask information section
First field - "Length of the layer and mask information section" - this length, just like in Image Resources section, shouldn't include length of itself.
Then we have "Layer info" section.
"Length of the layers info section, rounded up to a multiple of 2." - this also shouldn't include the length of itself. But what about "rounded up to a multiple of 2"? This means that in case if the length of layer info is odd, you should not only add 1 to the length, you must also add this one byte to the end of the "channel image data" section. The very end.
Now "Layer records".
Third field is the "Channel information". It contains channel IDs and lengths of channel data. Length of channel data must include also 2 bytes that tells what kind of compression it is.
The RGB channels in Photoshop are in the following order: R,G,B,A. Every channel data entry contains type of compression and then colors. Photoshop 7 saves PSD in RLE format, but also reads raw layers. Channel image data entry, when compressed using RLE, looks like this (this isn't very straightforward when looking at the specification):
[1st layer 1st channel compression type]
[1st layer 1st channel RLE lengths]
[1st layer 1st channel data]
[1st layer 2nd channel compression type]
[1st layer 2nd channel RLE lengths]
[1st layer 2nd channel data]
...
[2nd layer 1st channel compression type]
[2nd layer 1st channel RLE lengths]
[2nd layer 1st channel data]
...
In case of raw data, we have a description: If the layer's size, and therefore the data, is odd, a pad byte will be inserted at the end of the row. - this is actually not true, we only insert this one byte that I've mentioned earlier (in case of data oddity).
Layer records field "Flags", there is a description:
"bit 1 = visible" - this actually means, that when bit 1 equals 1 - the layer IS NOT visible.
Layer records field "Length of the extra data field (=the total length of the next five fields)" - but there are 3 fields in the specification. So where is the rest? By looking at the PSD document, I can tell that there's some data after the "Layer name", the last documented field. So probably this isn't a mistake in the specification, but these fields aren't documented. So this is a mystery. Stripping them (and of course correcting all the fields that says "length of...") didn't corrupt the PSD file.
Last field - "layer name: Pascal string (...)" - funny thing that I didn't know what's that "Pascal string". Of course I remember strings in Turbo Pascal, they could be up to 255 chars long. Google didn't tell anything valuable about "Pascal string", funny thing that this Specification appeared in the beginning of search results. So what is that "Pascal string"? It is a string with an integer at the beginning, telling how long this string is (in contrary to c-string when we have null at the end).
Image Data section
Image data section contains all the pixel colors. It is a bit different from "channel image data" section, esp. when yo use RLE encoding. This is the description from the specification: "RLE compressed the image data starts with the byte counts for all the scan lines (rows * channels)"
This is the scheme of data layout in image data section:
[1st channel RLE lengths]
[2nd channel RLE lengths]
...
[1st channel data][2nd channel data]
...
** By following the rules below, you will create identical data in PSD to Photoshop's output (this way there's a greater chance that the generated documents will be opened in all Photoshop versions). **
About RLE compression
The description in the specification says, that when parsing PSD documents, we must compress using RLE (packbits algorithm) every scanline separately. Actually, Photoshop does this in 128 byte chunks.
That is:
y := 0
1: take the scanline at y
use packbits on all 128 byte chunks of the scanline bytes
- if there are less than 128 bytes left, then take the rest
y := y + 1
go to 1.
Also, if you take a look at the MacPaint's packbits algorithm: http://telegraphics.com.au/svn/macpaintformat/trunk/packbits.c
These lines (written in C):
if(run <= (dataend-3) && run[1] == run[0] && run[2] == run[0]){
for( p = run+3 ; p < (run+maxrun) && *p == run[0] ; )
in Photoshop are changed to:
if(run <= (dataend-2) && run[1] == run[0] ){
for( p = run+2 ; p < (run+maxrun) && *p == run[0] ; )
... so that we are starting a RLE run in case we meet 2, not 3 similar bytes.
About colors in image data section.
Colors in image data section are premultiplied by alpha with white. Regardless of the "background" entry on "Image resources" section (personally I don't know what this entry does anyway). Alpha channel stays intact.
The premultiplication is done using following formula:
R = int( ( A * R + (255-A) * 255 ) / 255 + 0.5 )
G = int( ( A * G + (255-A) * 255 ) / 255 + 0.5 )
B = int( ( A * B + (255-A) * 255 ) / 255 + 0.5 )
(A = alpha channel byte, R = red byte, G = green byte, B = blue byte)
And these are the sources:
v. 1.0 PSD Encoder class
update 1.1:
v. 1.1 PSD Encoder class with 2 utility methods
as you can see in the comments section, a generous contributor (Tom Keen) made 2 routines that simplifies the usage of a class. Class works as previously, but has added 2 utility functions.
remark: DisplayObjects supplied to the method "exportDisplayObjects" must have a parent