Photoshop Custom Shapes File Format

Contents

This document provides information about the (undocumented yet) format of custom shapes files in Photoshop.

Note: all multi-byte values, i.e., integer numbers (including C-style 4-character constants), fixed-point numbers, and Unicode characters are coded in big-endian format.

Custom shapes file format

Custom shapes file

Name Type Kind Description
CustomShapes.psp '8BPF' Custom shapes file Adobe Photoshop preferences file containing all the custom shapes listed in the Preset Manager.
Warning: like most preferences files, the custom shapes file is not updated in real-time: it is read by the application only once at start-up (launch) time and written back at shut-down (quit) time.
*.csh '8BCS' Custom shapes file Adobe Photoshop custom shapes file; generally produced by saving a selected set of custom shapes from the Preset Manager.

Length (in bytes) Description Comments
4 Magic number (= 'cush') C-style 4-character constant.
4 Version (= 2) 32-bit integer.
4 Number of custom shapes 32-bit integer.
Variable Sequence of custom shapes Each in Custom shape format.

Custom shape

Length (in bytes) Description Comments
Variable Custom shape name Unicode string format.
0 or 2 Extra null padding Only if length of previous Unicode string is odd.
4 Unknown (= 1) 32-bit integer.
4 Length (in bytes) of remaining custom shape data 32-bit integer.
1 + 36 Custom shape ID (UUID) Pascal-style string format.
16 Reference bounds for anchor and control points Bounds rectangle format.
Variable Sequence of path records Each in Path record format.
1 or 3 Extra null padding To match the above length of remaining custom shape data (always a multiple of 4).

Unicode string

Length (in bytes) Description Comments
4 Number of Unicode characters 32-bit integer.
Variable String of Unicode characters Two bytes per character; includes terminating null.

Pascal-style string

Length (in bytes) Description Comments
1 Number of characters 8-bit integer (unsigned).
Variable String of characters One byte per character; no terminating null.

Bounds rectangle

Length (in bytes) Description Comments
4 Top coordinate (in pixels) 32-bit integer (signed).
4 Left coordinate (in pixels) 32-bit integer (signed).
4 Bottom coordinate (in pixels) 32-bit integer (signed).
4 Right coordinate (in pixels) 32-bit integer (signed).

Path record

Length (in bytes) Description Comments
2 Selector 16-bit integer:
  • 0 (closed subpath length record)
  • 1 (closed subpath Bezier knot, linked)
  • 2 (closed subpath Bezier knot, unlinked)
  • 3 (open subpath length record)
  • 4 (open subpath Bezier knot, linked)
  • 5 (open subpath Bezier knot, unlinked)
  • 6 (path fill rule record)
  • 7 (clipboard record)
  • 8 (initial fill rule record)
24 Path record data Depending on selector:

Cf. Path resource format of the page Adobe Photoshop File Formats Specification for more details about the way paths are stored in a Photoshop document.

Path fill rule record

Length (in bytes) Description Comments
24 Unused Should be zeroes.

Initial fill rule record

Length (in bytes) Description Comments
2 Initial fill (= 0) 16-bit integer (unsigned); should be 0 or 1 (fill starts with all pixels); not used.
22 Unused Should be zeroes.

Subpath length record

Length (in bytes) Description Comments
2 Subpath length (number of Bezier knots) 16-bit integer (unsigned).
22 Unused Should be zeroes.

Subpath Bezier knot

Length (in bytes) Description Comments
8 Backward control point for the Bezier segment preceding the knot Path point format.
8 Anchor point for the knot Path point format.
8 Forward control point for the Bezier segment leaving the knot Path point format.

Cf. Bezier curves.

Path point

Length (in bytes) Description Comments
4 Vertical component 32-bit fixed-point number (signed), in Q8.24 format.
4 Horizontal component 32-bit fixed-point number (signed), in Q8.24 format.

Fixed-point numbers are implemented here as 32-bit integers, with 8 bits before the binary point and 24 bits after the binary point. In JavaScript, since all numbers are represented as floating-point numbers, appropriate values are simply obtained by dividing the extracted 32-bit signed integer values by 0x1000000 (224).

The resulting horizontal and vertical component values of a path point always fall between 0.0 and 1.0 (both exclusive).
[0.0, 0.0] and [1.0, 1.0] correspond respectively to the top-left and bottom-right corners of the bounds rectangle, which appears to have an extra "safety" margin of 1 pixel in each direction (i.e.: top, left, bottom, right).

Path records order

For each custom shape, the first path record is always a "path fill rule record" (selector: 6), immediately followed by an "initial fill rule record" (selector: 8), whose initial fill value (0 or 1) is apparently not used.

Then, for each subpath:

or

Parsing custom shapes files

A practical set of JavaScript functions for parsing custom shapes files is contained in the module jamShapes, which is part of the JSON Action Manager scripting library. It is used by the following utility scripts:

All files are open-source and licensed under GPLv3; the utility scripts have been successfully tested in Photoshop CS4 on Mac OS X, but should be platform agnostic.



Doc version: 2.0
Date: 2017-03-23
Copyright: © 2013-2017 Michel MARIANI
Disclaimer: this information is provided 'as is' without warranty of any kind, express or implied; use it at your own risk.