********************************************************************************
*                                                                              *
*  The Unofficial Photoshop Color Book File Format (.acb/8BCB) Specification   *
*                      [80-column plain text version 1.0]                      *
*                                                                              *
*                      by Ates Goral on Sep. 25-26, 2003                       *
*                   ates@magnetiq.com - http://magnetiq.com                    *
*                                                                              *
*               http://magnetiq.com/docs/PhotoshopColorBook.txt                *
*                                                                              *
********************************************************************************


================================================================================
1. NOMENCLATURE

There are 3 main different data structures used in an .acb file. All integers
are in Motorola (big-endian) order. If you're doing development on an Intel
machine, make sure to swap the bytes of the integer values. The words "word",
"longword" and "string" will be used to describe the following data structures:

--------------------------------------------------------------------------------
  1.1. Word

  2 consecutive bytes make up a word (short in C). The bytes are in Motorola
  order. The sequence 0x0001 represents 1, not 65536. I'm not sure if words in
  an .acb file should be treated as signed or unsigned. Signed has worked for
  me.

--------------------------------------------------------------------------------
  1.2. Longword
  
  4 consecutive bytes make up a longword (long in C). The bytes are again in
  Motorola order!
  
--------------------------------------------------------------------------------
  1.3. String
  
  A string starts with a longword (1.2) that denotes the string length. Strings
  are not null-terminated, therefore the string length gives the exact length of
  the string (without the length field). The length is followed by double-byte
  characters. These double byte characters are not in Unicode order! You have to
  swap each 2 byte character to get a wide (or Unicode) character.
  
  
  +--------+-----------------------//----------------------------------------+
  | Length | Characters            \\                                        |
  +--------+-----------------------//----------------------------------------+
 
    
================================================================================
2. THE FORMAT

--------------------------------------------------------------------------------
  2.1. File Signature
  
  4 consecutive ASCII characters that read "8BCB". This probably comes from
  "8B Color Book".
  
--------------------------------------------------------------------------------
  2.2. File Version
  
  This is a word (1.1) denoting the file version. Photoshop 7.0 only opens files
  with a version of 1 (0x0001).

--------------------------------------------------------------------------------
  2.3. Color Book Identifier
  
  A word. This probably is a unique identifier assigned by Adobe for every color
  book of every manufacturer. Reads something like 0x0b??.

--------------------------------------------------------------------------------
  2.4. Color Book Title
  
  A string. The title of the color book as it appears in Photoshop's color
  picker. A "^R" within the string stands for a registered trademark symbol.

--------------------------------------------------------------------------------
  2.5. Color Name Prefix
  
  This string is to be appended to the beginning of each color's name.

--------------------------------------------------------------------------------
  2.6. Color Name Postfix
  
  This string is to be appended to the end of each color's name.

--------------------------------------------------------------------------------
  2.6. Color Book Description
  
  This string usually contains copyright information. "^C" stands for the
  copyright symbol.

--------------------------------------------------------------------------------
  2.7. Color Count
  
  A word. This can be more (see 2.11) than the colors you see from inside
  Photoshop.

--------------------------------------------------------------------------------
  2.8. Colors per Page

  A word. Photoshop displays colors page by page. This field specifies the
  maximum (see 2.11) number of colors that can appear on a page.

--------------------------------------------------------------------------------
  2.9. Page Selector Offset

  The page selector in Photoshop's color picker displays sample colors from each
  page. This offset specifies which of the colors on a page will represent that
  page on the page selector. "0" means the first (topmost) color. "1" means the
  second one and so on. If the offset exceeds the number of colors on the page,
  the last color is used.

--------------------------------------------------------------------------------
  2.10. Color Space Identifier
  
  A word specifying in which color space the color book is. Values that
  Photoshop 7.0 recognizes are:

    0 = RGB
    2 = CMYK
    7 = Lab

  The rest can be found in "Adobe Photoshop 6.0 File Formats Specification", but
  they apparently don't work for color books. Note that the 6.0 specification
  has no information on color book files.

    1 = HSB
    3 = Pantone
    4 = Focaltone
    5 = Trumatch
    6 = Toyo
    8 = Grayscale
   10 = HKS
 
--------------------------------------------------------------------------------
  2.11. Color Records

  Until the end of the file, come the individual color records. There are
  exactly as many color records as there was specified by the "Color Count"
  field (2.7).
 
  Photoshop may display fewer colors then there are in the color book file
  because some color records are intentionally blank (see 2.11.1) records used
  for padding purposes. When a page should contain less than the number of
  colors specified by "Colors per Page" (2.8), blank records are inserted and
  Photoshop doesn't display these records.

  The structure of a single color record is as follows:
   
  ------------------------------------------------------------------------------
    2.11.1. Color Name
    
    A string. Concatenating the "Color Name Prefix" (2.5), the "Color Name" and
    the "Color Name Postfix" (2.6) gives us the full name of a color as it
    appears in Photoshop's color picker. If this string is a zero-length string,
    this color record is considered "blank". The remaining fields of the record
    still exist, but are also "blank" in their own sense...
    
  ------------------------------------------------------------------------------
    2.11.2. Color Code
    
    6 consecutive ASCII characters. This could perhaps be a catalog code.
    Sometimes there are padding spaces on either side. Photoshop doesn't seem to
    be using this information at all.
 
  ------------------------------------------------------------------------------
    2.11.3. Color Components
    
    Depending on the color space (see 2.10), there can be 3 or 4 bytes, one byte
    for each component.
   
    ----------------------------------------------------------------------------
      2.11.3.a. RGB
      
      
        +-----+-------+------+
        | Red | Green | Blue |
        +-----+-------+------+
      
        
      3 bytes for the Red, Green and Blue components. Each is an unsigned value
      ranging from 0 to 255 that directly translate to the corresponding Red,
      Green and Blue levels.

    ----------------------------------------------------------------------------
      2.11.3.b. CMYK


        +------+---------+--------+-------+
        | Cyan | Magenta | Yellow | Black |
        +------+---------+--------+-------+


      4 bytes for the Cyan, Magenta, Yellow and Black components. Each is an
      unsigned value ranging from 0 to 255, representing 100 minus the
      percentage saturation, quantized to 255. To calculate the percentage
      saturation, divide a value by 255, subtract from 1, multiply with 100 and
      round to the nearest integer.
   
    ----------------------------------------------------------------------------
      2.11.3.c. Lab


        +-----------+---------------+---------------+
        | Lightness | a chrominance | b chrominance |
        +-----------+---------------+---------------+
  
  
      3 bytes for the Lightness, a chrominance and b chrominance components. The
      lightness percentage is quantized to 255. To its value, divide by 255,
      multiply with 100 and round to the nearest integer. The a and b
      chrominance values are offset by 128. To calculate their values, subtract
      128.
      
================================================================================
3. ILLUSTRATED EXAMPLE

Below is a portion from the beginning of "ANPA Color.acb" that ships with Adobe
Photoshop 7.0 for PC. Separate fields can be seen as rectangles. A verbal walk-
through will follow.


            +-----------+-----+-----+-----------+------------
  00000000h:|38 42 43 42|00 01|0B B8|00 00 00 23|00 24 00 24 ; 8BCB......#.$.$
            +-----------+-----+-----+-----------+------------
  00000010h: 00 24 00 2F 00 63 00 6F 00 6C 00 6F 00 72 00 62 ; .$./.c.o.l.o.r.b
            -------------------------------------------------
  00000020h: 00 6F 00 6F 00 6B 00 2F 00 41 00 4E 00 50 00 41 ; .o.o.k./.A.N.P.A
            -------------------------------------------------
  00000030h: 00 2F 00 74 00 69 00 74 00 6C 00 65 00 3D 00 41 ; ./.t.i.t.l.e.=.A
            -------------------------------------------------
  00000040h: 00 4E 00 50 00 41 00 20 00 43 00 6F 00 6C 00 6F ; .N.P.A. .C.o.l.o
            ------+-----------+------------------------------
  00000050h: 00 72|00 00 00 1F|00 24 00 24 00 24 00 2F 00 63 ; .r.....$.$.$./.c
            ------+-----------+------------------------------
  00000060h: 00 6F 00 6C 00 6F 00 72 00 62 00 6F 00 6F 00 6B ; .o.l.o.r.b.o.o.k
            -------------------------------------------------
  00000070h: 00 2F 00 41 00 4E 00 50 00 41 00 2F 00 70 00 72 ; ./.A.N.P.A./.p.r
            -------------------------------------------------
  00000080h: 00 65 00 66 00 69 00 78 00 3D 00 41 00 4E 00 50 ; .e.f.i.x.=.A.N.P
            ------------+-----------+------------------------
  00000090h: 00 41 00 20|00 00 00 21|00 24 00 24 00 24 00 2F ; .A. ...!.$.$.$./
            ------------+-----------+------------------------
  000000a0h: 00 63 00 6F 00 6C 00 6F 00 72 00 62 00 6F 00 6F ; .c.o.l.o.r.b.o.o
            -------------------------------------------------
  000000b0h: 00 6B 00 2F 00 41 00 4E 00 50 00 41 00 2F 00 70 ; .k./.A.N.P.A./.p
            -------------------------------------------------
  000000c0h: 00 6F 00 73 00 74 00 66 00 69 00 78 00 3D 00 20 ; .o.s.t.f.i.x.=. 
            ------------------------------+-----------+------
  000000d0h: 00 41 00 64 00 50 00 72 00 6F|00 00 00 1F|00 24 ; .A.d.P.r.o.....$
            ------------------------------+-----------+------
  000000e0h: 00 24 00 24 00 2F 00 63 00 6F 00 6C 00 6F 00 72 ; .$.$./.c.o.l.o.r
            -------------------------------------------------
  000000f0h: 00 62 00 6F 00 6F 00 6B 00 2F 00 41 00 4E 00 50 ; .b.o.o.k./.A.N.P
            -------------------------------------------------
  00000100h: 00 41 00 2F 00 64 00 65 00 73 00 63 00 72 00 69 ; .A./.d.e.s.c.r.i
            ------------------------------------+-----+-----+
  00000110h: 00 70 00 74 00 69 00 6F 00 6E 00 3D|01 2C|00 06|; .p.t.i.o.n.=.,..
            +-----+-----+-----------+-----------+-----+-----+
  00000120h:|00 05|00 07|00 00 00 04|00 37 00 31 00 2D 00 31|; .........7.1.-.1
            +-----+-----+-----+--+--+--+-----------+--------+
  00000130h:|20 37 31 2D 31 44|F8|7B|7B|00 00 00 04|00 37 00 ;  71-1D{{.....7.
            +--------------+--+--+--+--+-----+--+--+--+------
  00000140h: 31 00 2D 00 32|20 37 31 2D 32 44|F1|78|78|00 00 ; 1.-.2 71-2Dxx..
            ------+--------+--------------+--+--+--+--+-----+          /\    /
  00000150h: 00 04|00 37 00 31 00 2D 00 34|20 37 31 2D 34 44|;/\..7.1./  \71/  
            +--+--+--+-----------+--------+------------/\+--+/  \    /    \/
  00000160h:|E3|72|7/\00 00 00 04|00 37 00 31 00 2D 00/  \20/    \../          
            +--+--+/  \----/\-+--+--+----/\----/\----/    \/      \/
  00000170/\ 37 31/    \ 4/  \|68|67|00 /  \0 /  \0 /
   /\    /  \----/      \/    \--+-/\--/    \/    \/
  /  \01/    \0 /              \1 /  \/ 
      \/      \/                \/ 


The file starts with the mandatory "8BCB" signature. Following that, the file
version comes. The version must be 1 for Photoshop 7.0 to open the file. Then
comes the unique color book identifier: 0x0bb8 (whatever).

Next, the length of the title string is reported to be 0x23 (35) wide characters
long. The title string is: "$$$/colorbook/ANPA/title=ANPA Color". The 31-
character prefix string is: "$$$/colorbook/ANPA/prefix=ANPA ". Note the extra
space character at the end. The postfix, "$$$/colorbook/ANPA/postfix= AdPro" is
33 characters long. This also has an extra space just after the equal sign. This
file has no description, but the description string is there anyway. Having a
length of 31 characters, it reads: "$$$/colorbook/ANPA/description=".

The following 0x012c gives us the number of colors in this book (300). There
will be a maximum of 6 colors per page with a page offset of 5, which in turn
means that the right-hand page selector in Photoshop's color picker will use the
last color of each page. The color space is 7 (Lab).

The color records start here. The first color name is 4 characters long: "71-1".
This should be concatenated with the prefix and postfix we saw earlier to
produce the full color name: "ANPA 71-1 AdPro". The 6-character short name for
this color is: " 71-1D". Notice the padding space at the left. The lightness
component reads 0xf8 (248). This rounds down to a percentage of
248 / 255 * 100 = 97. The a and b chrominance values are both 0x7b (123).
Subtracting 128 gives -5 for both components.

Immediately after this, the second color record starts. The name length is again
4, etc...

================================================================================
4. HISTORY

I dug into this file format to extract the color catalog data for a project. I
started by guessing from the hex dump of .acb files. After figuring out most of
the file format, I generated my own experimental .acb files, and by observing
Photoshop's reactions towards my files, I think I succeeded in figuring out what
every single byte in an .acb does. To my luck, the file wasn't in a compressed
form :)

================================================================================
5. EPILOGUE

Please report any missing or false information, grammatical or technical
problems and spelling errors to ates@magnetiq.com. You may also check
magnetiq.com for revisions of this document.

- Ates
