Spectrum Palettes - Terminal Color Definitions

Overview

When Spectrum quantizes a 24-bit color to fit a terminal's capabilities, it needs to know what RGB value each ANSI color code actually displays. There is no way to introspect this from the terminal — Spectrum can detect how many colors are supported, but not what those colors look like. These palette modules define the assumed mapping: the standard xterm color definitions that the vast majority of terminals use by default.

These modules are generated at compile time from JSON definitions using the [%palette] PPX extension. The same PPX can be used to create custom palette modules for non-standard terminal themes, though this is rarely needed.

Using Palettes

Color Lookup

Convert color names to palette values and ANSI codes:

let red = Spectrum_palettes.Terminal.Xterm256.of_string "red"
(* val red : Spectrum_palettes.Terminal.Xterm256.t *)

let code = Spectrum_palettes.Terminal.Xterm256.to_code red
(* val code : int = 9 *)

let color = Spectrum_palettes.Terminal.Xterm256.to_color red
(* val color : Gg.v4 — RGBA float values (1.0, 0.0, 0.0, 1.0) *)

Find the closest palette color to an arbitrary RGB value:

let orange = Gg.Color.v_srgb 0.9 0.4 0.3
(* val orange : Gg.v4 — RGBA (0.9, 0.4, 0.3, 1.0) *)

let nearest = Spectrum_palettes.Terminal.Xterm256.nearest orange
(* val nearest : Gg.v4 — nearest xterm-256 color by perceptual distance *)

let nearest_basic = Spectrum_palettes.Terminal.Basic.nearest orange
(* val nearest_basic : Gg.v4 — nearest ANSI-16 color *)

The nearest-color search uses an octree spatial index in LAB color space for O(log n) average-case performance.

Palette Structure

Basic Palette (ANSI-16)

The Basic palette contains 16 colors with ANSI codes 30-37 (dark) and 90-97 (bright). Color names are prefixed with "basic-" to avoid collisions with the xterm-256 palette.

Full color reference: basic_palette

Xterm256 Palette (ANSI-256)

The Xterm256 palette contains 256 colors organized as:

Color names follow the xterm convention with hyphenation:

Full color reference: xterm256_palette

Generated Code

These modules are generated at compile time from JSON palette definitions in lib/spectrum_palette. The PPX extension generates OCaml modules with nearest-color lookup functions.

Each palette module implements the Spectrum_palette_ppx.Palette.M signature.

API Reference

See Also