cpt2js

Color palette file parser to a function, input compatible with GMT, GDAL, GRASS, PostGIS, ArcGIS

Demo

From GDAL docs:

The text-based color configuration file generally contains 4 columns per line: the elevation value and the corresponding Red, Green, Blue component (between 0 and 255). The elevation value can be any floating point value, or the nv keyword for the nodata value. The elevation can also be expressed as a percentage: 0% being the minimum value found in the raster, 100% the maximum value.

An extra column can be optionally added for the alpha component. If it is not specified, full opacity (255) is assumed.

Various field separators are accepted: comma, tabulation, spaces, ‘:’.

Common colors used by GRASS can also be specified by using their name, instead of the RGB triplet. The supported list is: white, black, red, green, blue, yellow, magenta, cyan, aqua, grey/gray, orange, brown, purple/violet and indigo.

GMT .cpt palette files are also supported (COLOR_MODEL = RGB only).

Note: the syntax of the color configuration file is derived from the one supported by GRASS r.colors utility. ESRI HDR color table files (.clr) also match that syntax. The alpha component and the support of tab and comma as separators are GDAL specific extensions.

Differences from GDAL:

• GMT color formats
• Chroma.js color formats
• Chroma.js color modes

Supported color formats and modes:

• color formats - named, hex, CSS, RGB, HSL, HSV
• color modes - RGB, HSL, HSV
• more color formats and modes can be added as needed

Color palette references:

• cpt-city - a large collection of color palette files (use cpt or pg formats)
• cpt-city formats notes
• cpt-city software notes

Install

npm install cpt2js

or

<script src="https://unpkg.com/cpt2js@1.2.4/dist/cpt2js.umd.min.js"></script>

Usage

From text

The library exposes a function parseCptText, which can be used to parse the color palette file content.

The second argument of parseCptText is an options object:

• bounds ([number, number]) - used for resolving relative values to absolute values, default [0, 1]
• mode (Chroma.js InterpolationMode) - intepolation color mode, default detected from the input or rgb

The parse result is a Chroma.js Scale, a function (value: number) => Color.

The colors returned are Chroma.js Color objects, with default toString method returning a hex color.

import { parseCptText } from 'cpt2js';

const palette = `
0   black
1   white
`;
const paletteScale = parseCptText(palette);

paletteScale(0.5).toString(); // '#808080'
paletteScale(0.5).css(); // 'rgb(128, 128, 128)' - use for CSS
paletteScale(0.5).rgba(); // [128, 128, 128, 1] - use for deck.gl, multiply alpha by 255

From text - Relative values

import { parseCptText } from 'cpt2js';

const palette = `
0%   black
100% white
`;
const paletteScale = parseCptText(palette, { bounds: [0, 100] });

paletteScale(50).toString(); // '#808080'

From array

The library exposes a function parseCptArray, which can be used to parse the color palette array [number | string, Color][].

The second argument of parseCptArray is an options object:

• bounds ([number, number]) - used for resolving relative values to absolute values, default [0, 1]
• mode (Chroma.js InterpolationMode) - intepolation color mode, default rgb

The parse result is a Chroma.js Scale, a function (value: number) => Color.

The colors returned are Chroma.js Color objects, with default toString method returning a hex color.

import { parseCptArray } from 'cpt2js';

const palette = [
  [0, 'black'],
  [1, 'white'],
];
const paletteScale = parseCptArray(palette);

paletteScale(0.5).toString(); // '#808080'
paletteScale(0.5).css(); // 'rgb(128, 128, 128)' - use for CSS
paletteScale(0.5).rgba(); // [128, 128, 128, 1] - use for deck.gl, multiply alpha by 255

From array - Relative values

import { parseCptArray } from 'cpt2js';

const palette = [
  ['0%',   'black'],
  ['100%', 'white'],
];
const paletteScale = parseCptArray(palette, { bounds: [0, 100] });

paletteScale(50).toString(); // '#808080'

Color ramp

The library exposes a function colorRampCanvas, which can be used to color ramp the scale function to a canvas. The canvas can be encoded to a Data URL and rendered as an image.

The second argument of colorRampCanvas is an options object:

• width (number) - width of the canvas, used also as a number of color ramp colors, default 256
• height (number) - height of the canvas, default 1

import { parseCptText, colorRampCanvas } from 'cpt2js';

const palette = `
0   black
1   white
`;
const paletteScale = parseCptText(palette);
const paletteCanvas = colorRampCanvas(scale);
const paletteCanvasDataUrl = paletteCanvas.toDataURL();
const html = `<img src="${paletteCanvasDataUrl}">`;

Supported color palette features

0   black
1   white

0   #000000
1   #ffffff

0   0   0   0
1   255 255 255

# COLOR_MODEL = hsl
0   300 1 0.5
0.5 150 1 0.5
1   0   1 0.5

# COLOR_MODEL = hsv
0   300 1 1
0.5 150 1 1
1   0   1 1

0   black
1   white
nv  gray

Thanks

Discussion at stac-extensions/raster#17 and Cloud-Native Geospatial Outreach Event 2022 that sparked the idea for the library.