Photoshop Gradients File Format

Contents

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

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

File format

Gradients file

Name Type Kind Description
Gradients.psp '8BPF' Gradients file Adobe Photoshop preferences file containing all the gradients listed in the Preset Manager.
Warning: like most preferences files, the gradients 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.
*.grd '8BGR' Gradients file Adobe Photoshop gradients file; generally produced by saving a selected set of gradients from the Preset Manager.

Gradients file header

Length (in bytes) Description Comments
4 Magic number (= '8BGR') C-style 4-character constant.
2 Version (= 5) 16-bit integer.
Variable Serialized action descriptor Matches the serialized format expected by the ActionDescriptor.fromStream method (in JavaScript), or the HandleToDescriptor routine of the ActionDescriptor suite (in C/C++), i.e. prefixed by a 32-bit integer equal to 16. See Descriptor format below.

Descriptor

Here is the structure of the descriptor returned by calling the ActionDescriptor.fromStream method (in JavaScript), or the HandleToDescriptor routine of the ActionDescriptor suite (in C/C++), on the remaining part of the file following the magic number ('8BGR') and the version (5):

Key Type Value Comments
'GrdL' List List of gradient objects Each in Gradient object format.

Gradient object

Class Descriptor
'Grdn' Key Type Value Comments
'Grad' Object Custom stops gradient object
or
Color noise gradient object		 Custom stops gradient object format
or
Color noise gradient object format.

Custom stops gradient object

Class Descriptor
'Grdn' Key Type Value Comments
'Nm  ' String Gradient name Unicode string.
'GrdF' Enumerated Gradient form: custom stops
(= 'GrdF', 'CstS')		 Solid gradient.
'Intr' Double Interpolation 0 to 4096 (Smoothness: 0% to 100%).
'Clrs' List List of color stops Each in Color stop object format.
'Trns' List List of transparency stops Each in Transparency stop object format.

Color stop object

Class Descriptor
'Clrt' Key Type Value Comments
'Lctn' Integer Location 0 to 4096 (0% to 100%).
'Mdpn' Integer Midpoint 0% to 100%.
'Type' Enumerated Color stop type:
  • 'Clry', 'UsrS'
  • 'Clry', 'BckC'
  • 'Clry', 'FrgC'
 Type:
  • User stop
  • Background color
  • Foreground color
'Clr ' Object Color object:
  • Book color object
  • CMYK color object
  • Grayscale object
  • HSB color object
  • Lab color object
  • RGB color object
 Key present only if color stop type is user stop:

Transparency stop object

Class Descriptor
'TrnS' Key Type Value Comments
'Lctn' Integer Location 0 to 4096 (0% to 100%).
'Mdpn' Integer Midpoint 0% to 100%.
'Opct' Unit double Opacity (in '#Prc' units) 0% to 100%.

Color noise gradient object

Class Descriptor
'Grdn' Key Type Value Comments
'Nm  ' String Gradient name Unicode string.
'GrdF' Enumerated Gradient form: color noise
(= 'GrdF', 'ClNs')		 Noise gradient.
'RndS' Integer Random seed Randomize.
'ShTr' Boolean Show transparency Add Transparency.
'VctC' Boolean Vector color Restrict Colors.
'Smth' Integer Smoothness 0 to 4096 (Roughness: 0% to 100%).
'ClrS' Enumerated Color space:
  • 'ClrS', 'RGBC'
  • 'ClrS', 'HSBl'
  • 'ClrS', 'LbCl'
 Color Model:
  • RGB
  • HSB
  • LAB
'Mnm ' List of Integers Four minimum values Three color components (0% to 100%) + transparency (0%).
'Mxm ' List of Integers Four maximum values Three color components (0% to 100%) + transparency (100%).

Color format

Book color object

Class Descriptor
'BkCl' Key Type Value Comments
'Bk  ' String Book name Unicode string.
'Nm  ' String Color name Unicode string.
"bookID" Integer Book ID Signed number.
"bookKey" Raw data Book key Byte string.

CMYK color object

Class Descriptor
'CMYC' Key Type Value Comments
'Cyn ' Double Cyan 0% to 100%.
'Mgnt' Double Magenta 0% to 100%.
'Ylw ' Double Yellow 0% to 100%.
'Blck' Double Black 0% to 100%.

Grayscale object

Class Descriptor
'Grsc' Key Type Value Comments
'Gry ' Double Gray 0% to 100%.

HSB color object

Class Descriptor
'HSBC' Key Type Value Comments
'H   ' Unit double Hue (in '#Ang' units) 0° to 360°.
'Strt' Double Saturation 0% to 100%.
'Brgh' Double Brightness 0% to 100%.

Lab color object

Class Descriptor
'LbCl' Key Type Value Comments
'Lmnc' Double Luminance 0 to 100.
'A   ' Double A -128 to 127.
'B   ' Double B -128 to 127.

RGB color object

Class Descriptor
'RGBC' Key Type Value Comments
'Rd  ' Double Red 0 to 255.
'Grn ' Double Green 0 to 255.
'Bl  ' Double Blue 0 to 255.

Parsing gradients files

The utility script Parse Gradients File (for Photoshop CS3 or later) is a practical example of parser written in JavaScript; it shows how to make use of the information contained in the present document to extract relevant data from the gradients file's main action descriptor; this utility script uses both the JSON AM Data Format and the Gradient Object Simplified Format, but can be adapted to produce results into any other desired format through direct calls to appropriate ActionDescriptor and ActionList methods.

Generating gradients files

The utility script Generate Gradients File (for Photoshop CS3 or later) can be used to generate a gradients file from a JSON text file whose format is the same as the one returned by the above-mentioned script for parsing gradient files, i.e. consisting of an array of gradient objects in Gradient Object Simplified Format.

Doc version: 2.7
Date: 2018-04-16
Copyright: © 2012-2018 Michel MARIANI
Disclaimer: this information is provided 'as is' without warranty of any kind, express or implied; use it at your own risk.