Create Color Ramp

Description

“Create Color Ramp” is a color ramps script using the JSON Action Manager scripting library.

This stand-alone script written in JavaScript is used to create a 256-color ramp programmatically.

Since a color ramp is assumed to be defined as an ordered set of 256 RGB colors, the data it represents can be displayed in three different ways (identical to the contents of the document created by the script Visualize Adjustment Layers):

  • as a curves map,
  • as a gradient map,
  • as a color table.

Please note that the color ramp data is always displayed as RGB in the preview area of the script’s main dialog, regardless of the color model used to generate it.

Alt-clicking on the curves map preview area toggles between simple and detailed grid.

Double-clicking on any part of the preview area reverses the ordering of colors in the color ramp.

A color ramp can be calculated from a formula made of mathematical expressions:

  • as color components, in one color model among: RGB, HSB, HSL, HCL, Lab, XYZ, YCbCr;

Create Color Ramp Dialog (Mac OS X) - Components

  • as indexed colors, always in RGB.

Create Color Ramp Dialog (Mac OS X) - Indexed Colors

Formulas can be loaded from (and saved to) plain JSON text files. See: Examples of Color Ramp Formulas.

In input, a color ramp can be:

  • imported from a curves map file (.amp or .json) or a color table file (.act or .lut or .json);

In ouput, a color ramp can be:

  • exported to a curves map file (.amp or .json) or a color table file (.act or .json);

Export Color Ramp Dialog (Mac OS X)

  • created as a curves map adjustment layer or a (approximated) gradient map adjustment layer in the currently open RGB document.

Create Adjustment Layer Dialog (Mac OS X) - Curves Map

Create Adjustment Layer Dialog (Mac OS X) - Gradient Map

Components Formula Format

A components formula is made of three JavaScript expressions where (x) is a predefined local variable whose value varies within the selected range (integer: [0, 255] or float: [0.0, 1.0]). Each expression returns a value within the same range.

Color models

Seven color models are supported:

  • RGB: Red, Green, Blue
  • HSB: Hue, Saturation, Brightness
  • HSL: Hue, Saturation, Lightness
  • HCL: Hue, Chroma, Luminance
  • Lab: Luminance, A, B
  • XYZ: X, Y, Z
  • YCbCr: Y (Luma), Chroma Blue (Blue – Luma), Chroma Red (Red – Luma)

RGB and HSB (also called HSV) are color models natively handled by Photoshop, while HSL is extensively used in CSS3.

HCL stands for CIE-LCH, which is a more intuitive color model than CIE-LAB, usually simply called Lab. It uses the standard, widely-documented algorithm which assumes a 2° observer angle and a D65 illuminant, and applies a sRGB gamma correction. XYZ (CIE-XYZ) is an intermediate color model used to convert from RGB to Lab.

YCbCr makes use of the full-range format used for JPEG images.

Ranges

RGB
  Float range
false true
Red x: [0, 255]
R(x): [0, 255] (clipped)
x: [0.0, 1.0]
R(x): [0.0, 1.0] (clipped)
Green x: [0, 255]
G(x): [0, 255] (clipped)
x: [0.0, 1.0]
G(x): [0.0, 1.0] (clipped)
Blue x: [0, 255]
B(x): [0, 255] (clipped)
x: [0.0, 1.0]
B(x): [0.0, 1.0] (clipped)
HSB
  Float range
false true
Hue x: [0, 255]
H(x): [0, 360] (wrapped)
x: [0.0, 1.0]
H(x): [0.0, 1.0] (wrapped)
Saturation x: [0, 255]
S(x): [0, 100] (clipped)
x: [0.0, 1.0]
S(x): [0.0, 1.0] (clipped)
Brightness x: [0, 255]
B(x): [0, 100] (clipped)
x: [0.0, 1.0]
B(x): [0.0, 1.0] (clipped)
HSL
  Float range
false true
Hue x: [0, 255]
H(x): [0, 360] (wrapped)
x: [0.0, 1.0]
H(x): [0.0, 1.0] (wrapped)
Saturation x: [0, 255]
S(x): [0, 100] (clipped)
x: [0.0, 1.0]
S(x): [0.0, 1.0] (clipped)
Lightness x: [0, 255]
L(x): [0, 100] (clipped)
x: [0.0, 1.0]
L(x): [0.0, 1.0] (clipped)
HCL
  Float range
false true
Hue x: [0, 255]
H(x): [0, 360] (wrapped)
x: [0.0, 1.0]
H(x): [0.0, 1.0] (wrapped)
Chroma x: [0, 255]
C(x): [0, 128] (unrestricted)
x: [0.0, 1.0]
C(x): [0.0, 1.0] (unrestricted)
Luminance x: [0, 255]
L(x): [0, 100] (unrestricted)
x: [0.0, 1.0]
L(x): [0.0, 1.0] (unrestricted)
Lab
  Float range
false true
Luminance x: [0, 255]
L(x): [0, 100] (unrestricted)
x: [0.0, 1.0]
L(x): [0.0, 1.0] (unrestricted)
A x: [0, 255]
a(x): [-128, 128] (unrestricted)
x: [0.0, 1.0]
a(x): [0.0, 1.0] (unrestricted)
B x: [0, 255]
b(x): [-128, 128] (unrestricted)
x: [0.0, 1.0]
b(x): [0.0, 1.0] (unrestricted)
XYZ
  Float range
false true
X x: [0, 255]
X(x): [0, 100] (unrestricted)
x: [0.0, 1.0]
X(x): [0.0, 1.0] (unrestricted)
Y x: [0, 255]
Y(x): [0, 100] (unrestricted)
x: [0.0, 1.0]
Y(x): [0.0, 1.0] (unrestricted)
Z x: [0, 255]
Z(x): [0, 100] (unrestricted)
x: [0.0, 1.0]
Z(x): [0.0, 1.0] (unrestricted)
YCbCr
  Float range
false true
Y (Luma) x: [0, 255]
Y(x): [0, 255] (unrestricted)
x: [0.0, 1.0]
Y(x): [0.0, 1.0] (unrestricted)
Chroma Blue
(Blue – Luma)
x: [0, 255]
Cb(x): [0, 255] (unrestricted)
x: [0.0, 1.0]
Cb(x): [0.0, 1.0] (unrestricted)
Chroma Red
(Red – Luma)
x: [0, 255]
Cr(x): [0, 255] (unrestricted)
x: [0.0, 1.0]
Cr(x): [0.0, 1.0] (unrestricted)

Built-in constants & functions

Formulas can use JavaScript’s native properties and methods of the Math global object:

Syntax Value Description
E 2.71828182845905 Euler’s constant, base of natural logarithms.
LN2 0.69314718055995 Natural logarithm of 2.
LN10 2.30258509299405 Natural logarithm of 10.
LOG2E 1.44269504088869 Base 2 logarithm of E.
LOG10E 0.43429448190325 Base 10 logarithm of E.
PI 3.14159265358979 π, the ratio of the circumference of a circle to its diameter.
SQRT1_2 0.70710678118655 Square root of 1/2; equivalently, 1 over the square root of 2.
SQRT2 1.41421356237310 Square root of 2.
Syntax Parameters Description
abs (a) a: number Returns the absolute value of (a).
acos (a) a: number Returns the arccosine of (a), from 0 to π.
asin (a) a: number Returns the arcsine of (a), from −π/2 to π/2.
atan (a) a: number Returns the arctangent of (a), from −π/2 to π/2.
atan2 (a, b) a, b: numbers Returns the arctangent of the quotient (a/b) of its arguments (a) and (b), from −π to π.
ceil (a) a: number Returns the smallest integer greater than or equal to (a).
cos (a) a: number Returns the cosine of (a).
exp (a) a: number Returns Ea, where E is Euler’s constant, the base of the natural logarithm.
floor (a) a: number Returns the largest integer less than or equal to (a).
log (a) a: number Returns the natural (base E) logarithm of (a).
max (a, b) a, b: numbers Returns the largest of two numbers (a) and (b).
min (a, b) a, b: numbers Returns the smallest of two numbers (a) and (b).
pow (a, b) a, b: numbers Returns base to the exponent power, that is, ab.
random ( )   Returns a pseudo-random number between 0 (inclusive) and 1 (exclusive).
round (a) a: number Returns the value of (a) rounded to the nearest integer.
sin (a) a: number Returns the sine of (a).
sqrt (a) a: number Returns the positive square root of (a).
tan (a) a: number Returns the tangent of (a).

Note: shortened names (without Math.) are recommended.

Several convenient helper functions are available as well:

Syntax Parameters Description
bias (t, b) t, b: numbers Returns a value in the interval [0.0, 1.0] for a parameter (t) in the same interval.
bias defines a kind of brightness curve controlled by the parameter (b) in the interval ]0.0, 1.0[.
For (b) equal to 0.5, bias is the identity function.
coserp (a, b, t) a, b, t: numbers Returns a cosine interpolated value between two values (a) and (b) for a parameter (t) in the interval [0.0, 1.0].
coserp is a common function name for cosine interpolation.
cubic (coeffs, x) coeffs: JSON array of numbers [ a, b, c, d ]
x: number
Returns the value of the cubic function:
ax3 + bx2 + cx + d.
distribute
(values, bounds, position, smoothness)
values: array
bounds: array
position: number
smoothness: number
Returns an interpolated value at (position) from an array of (values) evenly distributed within (bounds).
The shape of the resulting interpolation curve is controlled by the optional parameter (smoothness) between 0 (by default) and 100: a value of 0 implies a linear interpolation, while 100 indicates a smooth pchip interpolation.
gain (t, g) t, g: numbers Returns a value in the interval [0.0, 1.0] for a parameter (t) in the same interval.
gain defines a kind of contrast curve controlled by the parameter (g) in the interval ]0.0, 1.0[.
For (g) equal to 0.5, gain is the identity function.
interpolate
(points, position, smoothness)
points: array
position: number
smoothness: number
Returns an interpolated value at (position) from an array of (points) in ascending order, each point being defined as an array of two numbers: [ position, value ].
The shape of the resulting interpolation curve is controlled by the optional parameter (smoothness) between 0 (by default) and 100: a value of 0 implies a linear interpolation, while 100 indicates a smooth pchip interpolation.
lerp (a, b, t) a, b, t: numbers Returns a linearly interpolated value between two values (a) and (b) for a parameter (t) in the interval [0.0, 1.0].
lerp is a common function name for linear interpolation.
linear (coeffs, x) coeffs: JSON array of numbers [ a, b ]
x: number
Returns the value of the linear function:
ax + b.
pchip
(points, position)
points: array
position: number
Returns a shape-preserving interpolated value at (position) from an array of (points) in strict ascending order, each point being defined as an array of two numbers: [ position, value ].
PCHIP stands for “Piecewise Cubic Hermite Interpolation Polynomial”.
polynomial (coeffs, x) coeffs: JSON array of n numbers
x: number
Returns the value of a generic polynomial function of degree n.
quadratic
(coeffs, x)
coeffs: JSON array of numbers [ a, b, c ]
x: number
Returns the value of the quadratic function:
ax2 + bx + c.
smootherstep
(a, b, t)
a, b, t: numbers Returns a smootherstep interpolated value between two values (a) and (b) for a parameter (t) in the interval [0.0, 1.0].
smoothstep
(a, b, t)
a, b, t: numbers Returns a smoothstep interpolated value between two values (a) and (b) for a parameter (t) in the interval [0.0, 1.0].
spline
(points, position, compatible)
points: array
position: number
compatible: boolean
Returns an interpolated value at (position) from a natural cubic spline passing through an array of (points) in ascending order, each point being defined as an array of two numbers: [ position, value ].
In Photoshop-compatible mode (true), extrapolated values are set to the endpoint values.

Notes:

The bias and gain functions were first described by Ken Perlin and Eric M. Hoffert (Hypertexture). This script makes use of the faster alternative method designed by Christophe Schlick (Fast Alternatives to Perlin’s Bias and Gain Functions).

The code for the shape-preserving pchip function is based on Piecewise Cubic Hermite Interpolation and Monotone cubic interpolation.

The code for spline interpolation is adapted from CSPL.js by Ivan Kuckir.

Example

Dark Blue to Light Cyan

Dark Blue to Light Cyan (Curves)
Dark Blue to Light Cyan

{
    "colorRampFormula":
    {
        "name": "Dark Blue to Light Cyan",
        "colorModel": "RGB",
        "components":
        [
            "1 - sin ((1 - x) * PI / 2)",
            "(1 - cos (x * PI)) / 2",
            "sin (x * PI / 2)"
        ],
        "floatRange": true
    }
}

More examples of components formulas are provided on the dedicated page: Examples of Color Ramp Formulas.

Indexed Colors Formula Format

An indexed colors formula is only one JavaScript expression where (x) is a predefined local variable whose value varies between 0 and 255, and which returns a RGB color as an array of three values between 0 and 255: [ red, green, blue ].

Built-in functions

Although the indexed colors formula format can make use of the functions intended for the components formula format, the following high-level helper functions will be the most convenient, since they all directly return a RGB color array:

Syntax Parameters Description
distributeColors (colors, bounds, location, colorModel, option) colors: array
bounds: array
location: number
colorModel: string
option: number or string
Returns an interpolated color at (location) from an array of (colors) evenly distributed within (bounds), according to (colorModel) among "rgb", "hsb", "hsl" or "hcl".
In "rgb" color model, the optional parameter (option) represents a smoothness value between 0 (by default) and 100: a value of 0 implies a linear interpolation, while 100 indicates a pchip interpolation.
In "hsb", "hsl" or "hcl" color models, the optional parameter (option) represents the hue mode, among "desc" or "dec", "asc" or "inc", "far" or "long", "near" or "short", or "none".
interpolateColors (stops, location, colorModel, option) stops: array
location: number
colorModel: string
option: number or string
Returns an interpolated color at (location) from an array of (stops) in ascending order, each stop being defined as an array of two elements: [ position, color ], according to (colorModel) among "rgb", "hsb", "hsl" or "hcl".
In "rgb" color model, the optional parameter (option) represents a smoothness value between 0 (by default) and 100: a value of 0 implies a linear interpolation, while 100 indicates a pchip interpolation.
In "hsb", "hsl" or "hcl" color models, the optional parameter (option) represents the hue mode, among "desc" or "dec", "asc" or "inc", "far" or "long", "near" or "short", or "none".
shiftHue (rgb, shift) rgb: array
shift: number
Returns a hue-shifted color.
(shift) is expressed in degrees (0 by default).
transformColor (rgb, hueShift, saturationMultiplier, brightnessMultiplier) rgb: array
hueShift: number
saturationMultiplier: number
brightnessMultiplier: number
Returns a transformed color.
(hueShift) is expressed in degrees (0 by default); (saturationMultiplier) and (brightnessMultiplier) represent a scalar value (1 by default).

Note:

When calling the functions interpolateColors and distributeColors, each RGB color can be defined in several ways:

  • as a RGB color array; ex: [ 0, 255, 0 ],
  • as a color string in HTML/CSS hexadecimal notation; ex: "#00FF00" or "#0F0",
  • as a CSS/SVG/W3C or X11 color name; ex: "lime" or "svg/lime" or "x11/green".

See the Color Names page for a list of available W3C and X11 color names, sorted alphabetically.

A RGB color can also be obtained by using one of the built-in color conversion functions:

Syntax Parameters Description
rgb (red, green, blue) red: number
green: number
blue: number
Returns a RGB color array.
Ex: rgb (0, 255, 0)
hsb (hue, saturation, brightness) hue: number
saturation: number
brightness: number
Returns a RGB color array.
Ex: hsb (120, 100, 100)
hsl (hue, saturation, lightness) hue: number
saturation: number
lightness: number
Returns a RGB color array.
Ex: hsl (120, 100, 50)
hcl (hue, chroma, luminance) hue: number
chroma: number
luminance: number
Returns a RGB color array.
Ex: hcl (136, 119.8, 87.7)
lab (luminance, a, b) luminance: number
a: number
b: number
Returns a RGB color array.
Ex: lab (100, 0, 0)
xyz (x, y, z) x: number
y: number
z: number
Returns a RGB color array.
Ex: xyz (0, 0, 0)
ycbcr (y, cb, cr) y: number
cb: number
cr: number
Returns a RGB color array.
Ex: ycbcr (149.7, 43.5, 21.2)

Example

Romantic

Romantic (Curves)
Romantic

{
    "colorRampFormula":
    {
        "name": "Romantic",
        "indexedColors": "interpolateColors ([ [ 45 , \"hot pink\" ], [ 255, \"white\" ] ], x, \"hcl\", \"near\")"
    }
}

More examples of indexed colors formulas are provided on the dedicated page: Examples of Color Ramp Formulas.

Requirements

This script can be used in Adobe Photoshop CS4 or later. It has been successfully tested in CS4 on Mac OS X, but should be platform agnostic.

Copyright

This Software is copyright © 2014-2016 by Michel MARIANI.

License

This Software is licensed under the GNU General Public License (GPL) v3.

Download

Installation

Download the Zip file and unzip it.

Move the script to the Presets/Scripts folder in the default preset location of the Adobe Photoshop application. On next launch, the script will appear in the File>Automate submenu.

Version History

  • 4.1

    • Added Lab and XYZ color models.
    • Moved YCbCr functions to jamColors module.
    • Used new version 4.4.5 of jamColors scripting library module.
  • 4.0

    • Added YCbCr color model.
  • 3.9

    • Removed helper function linear (); used plain interpolate () instead.
    • Added helper functions for components formula format: linear (), quadratic (), cubic () and polynomial ().
  • 3.8

    • Used new version 4.4.4 of jamEngine scripting library module.
  • 3.7

    • Used new version 4.4.3 of jamLayers scripting library module.
  • 3.6

    • Used new version 4.4.1 of scripting library modules.
  • 3.5

    • Added shiftHue () and transformColor () helper functions for indexed colors formula format.
    • Added check of non-integer color component values in imported JSON files.
  • 3.4

    • Fixed minor harmless bug in dialog handling.
  • 3.3

    • Added display options in steps info dialog.
    • Simplified expression of function segmentIndex ().
  • 3.2

    • Cleaned up user interface code.
    • Added helper function for components formula format: distribute ().
    • Fixed checking of number of color stops in function distributeColors ().
  • 3.1

    • Fixed event handler for float range checkbox.
    • Improved performance of pchip () and spline () functions.
    • Added steps info dialog to get sampled colors as JSON array.
  • 3.0

    • Added handling of discrete steps.
    • Allowed saving of invalid formulas.
    • Added new formula format: indexed colors.
    • Added optional smoothing in function interpolate ().
    • Added helper functions for components formula format: linear (), pchip (), coserp (), smoothstep (), smootherstep ().
    • Added helper functions for indexed colors formula format: interpolateColors () to interpolate colors between fixed locations, distributeColors () to distribute colors evenly and interpolate them.
    • Improved performance of function spline (), using a new cache strategy.
    • Used new version 4.4 of scripting library modules.
  • 2.1

    • Lifted restriction over strict ascending order in function interpolate ().
  • 2.0

    • Added a new helper function: spline () to build a “natural” interpolating cubic spline passing through several points, similar to Photoshop’s curves adjustement.
    • Lifted validity check of bound values for HSB/HSL.
  • 1.9

    • Added two helper functions: bias () and gain () to adjust brightness and contrast.
    • Added a new helper function: interpolate () to interpolate color components between several points.
    • Used new version 4.3.2 of jamColors scripting library module.
  • 1.8

    • Allowed the use of shortened names for math functions and constants in formulas.
  • 1.7

    • Renamed HCL lightness to luminance.
    • Used new version 4.3.1 of jamColors scripting library module.
  • 1.6

    • Used new version 4.3 of scripting library modules.
    • Moved color conversion functions to new jamColors module.
  • 1.5

    • Lifted validity check of bound values for HCL.
  • 1.4

    • Added internal helper function for formulas : lerp (linear interpolation).
    • Restricted scope of formula eval ().
    • Corrected a few typos.
    • Reorganized code.
  • 1.3

    • Changed calculation mode for HCL (no more dependency on Photoshop Lab).
    • Changed maximum value for HCL chroma, from 100 to 128.
    • Updated examples of color ramp formulas (JSON text files).
  • 1.2

    • Added import and export of color ramp in JSON text format.
    • Added creation of (approximated) gradient map adjustment layer.
  • 1.1

    • Cleaned up code.
    • Sanitized saved file name.
    • Added explicit validity check of JSON file.
    • Added CIE-LCH color model (named HCL here, to be consistent with HSL).
  • 1.0

    • Initial release.

Tags: , , , , , , , , , ,

Comments are closed.