cpt2js

Color palette text 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 format notes
• cpt-city software notes

Install

npm install cpt2js

or

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

Usage

The library exposes a function parsePalette, which can be used to parse the color palette text or array.

Formats:

• text (string) - see Text format for details
• array ([string | number, PaletteColor][]) - PaletteColor is any object accepted by Chroma.js constructor

The second argument of parsePalette is an options object:

• bounds ([number, number]) - used for resolving relative values to absolute values, default [0, 1]

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.

From text

import { parsePalette } from 'cpt2js';

const palette = `
0   black
1   white
`;
const paletteScale = parsePalette(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 { parsePalette } from 'cpt2js';

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

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

From array

import { parsePalette } from 'cpt2js';

const palette = [
  [0, 'black'],
  [1, 'white'],
];
const paletteScale = parsePalette(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 { parsePalette } from 'cpt2js';

const palette = [
  ['0%',   'black'],
  ['100%', 'white'],
];
const paletteScale = parsePalette(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 { parsePalette, colorRampCanvas } from 'cpt2js';

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

Text format

Formats

GMT4	0 0 0 0 1 255 255 255
GMT5	0 0/0/0 1 255/255/255
GDAL, GRASS, PostGIS, ArcGIS	0 0 0 0 1 255 255 255

Values

Absolute	0 black
Relative	0% black
Nodata	N gray nv gray null gray nodata gray

Colors

Named	0 black 1 white
Hex	0 #000000 1 #ffffff
RGB	0 0 0 0 1 255 255 255
Alpha	0 0 0 0 0 1 255 255 255 255
HSL	# COLOR_MODEL = hsl 0 300 1 0.5 0.5 150 1 0.5 1 0 1 0.5
HSV	# COLOR_MODEL = hsv 0 300 1 1 0.5 150 1 1 1 0 1 1

Thanks

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