Photoshop-Gradients-File-Format

[HTML version]

Photoshop Gradients File Format

• Contents
• File format
  • Gradients file
  • Gradients file header
  • Descriptor
  • Gradient object
  • Custom stops gradient object
    • Color stop object
    • Transparency stop object
  • Color noise gradient object
• Color format
  • Book color object
  • CMYK color object
  • Grayscale object
  • HSB color object
  • Lab color object
  • RGB color object
• Parsing gradients files
• Generating gradients files

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: Book color object format CMYK color object format Grayscale object format HSB color object format Lab color object format RGB color object format

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.