Types

Core type definitions used across all modules.

import type { QuantizedColor, HSL } from "colorscope/types";

ExtractionResult

Returned by extractColorsFromBuffer and extractColorsFromUrl. Wraps the color palette with background detection metadata.

interface ExtractionResult {
  colors: QuantizedColor[];  // Up to 12 dominant colors, sorted by proportion
  background: {
    detected: boolean;       // Whether a uniform light background was filtered
    hex: string | null;      // Hex color of background, or null if not detected
  };
}

Field	Type	Description
`colors`	`QuantizedColor[]`	Dominant colors (up to 12), sorted by proportion descending.
`background.detected`	`boolean`	`true` when a uniform light background was found in 3+ corners and filtered.
`background.hex`	`string \| null`	Hex color of the detected background (e.g., `"#e6e6e6"`), or `null` when no background was detected.

QuantizedColor

The primary color type returned by extraction. Used as input throughout the library.

interface QuantizedColor {
  hue: number;         // Quantized hue: 0, 15, 30, ... 345 (24 values)
  saturation: number;   // Quantized saturation: 0, 15, 30, 50, 75, 100
  lightness: number;    // Quantized lightness: 10, 30, 50, 70, 90
  proportion: number;   // Relative pixel proportion (0-1)
  oklab?: OKLab;        // Pre-computed OKLab (set by extraction)
  hex: string;          // Hex code from quantized HSL (e.g., "#3f5255")
  colorName?: string;   // Human-readable name (set by withColorNames)
  rawHsl?: HSL;         // Non-quantized HSL median from sampled pixels
}

Field	Type	Description
`hue`	`number`	Quantized to 15° steps (0-345). 24 possible values.
`saturation`	`number`	Quantized to 6 levels: 0, 15, 30, 50, 75, 100.
`lightness`	`number`	Quantized to 5 levels: 10, 30, 50, 70, 90.
`proportion`	`number`	Fraction of foreground pixels in this bucket (0-1).
`oklab`	`OKLab \| undefined`	OKLab values for perceptual comparison. Set by extraction.
`hex`	`string`	Hex color computed from quantized HSL values.
`colorName`	`string \| undefined`	Populated by `withColorNames()` from the barrel export.
`rawHsl`	`HSL \| undefined`	Median of raw (non-quantized) HSL samples for this bucket.

Why Quantized?

Quantization maps the continuous HSL space into a 600-cell grid (24 hues × 6 saturations × 5 lightnesses). This:

Prevents the histogram from fragmenting into thousands of near-identical entries
Groups perceptually similar pixels into meaningful buckets
Keeps the result set small (≤12 colors) without losing important distinctions

The oklab field provides continuous perceptual values for operations that need precision (merging, distance, harmony), while the quantized values define the bucket identity.

HSL

Standard HSL color values.

interface HSL {
  h: number; // Hue in degrees (0-360)
  s: number; // Saturation percentage (0-100)
  l: number; // Lightness percentage (0-100)
}

OKLab

Perceptually uniform color space. Defined in the extraction module.

interface OKLab {
  L: number; // Perceptual lightness (0-1)
  a: number; // Green-red axis
  b: number; // Blue-yellow axis
}

OKLCH

Cylindrical form of OKLab. Defined in the convert module.

interface OKLCH {
  L: number; // Perceptual lightness (0-1)
  C: number; // Chroma / colorfulness (0+, typically 0-0.4)
  h: number; // Hue angle in degrees (0-360)
}

RGB

Standard RGB with 0-255 channels. Defined in the convert module.

interface RGB {
  r: number; // 0-255
  g: number; // 0-255
  b: number; // 0-255
}

QuantizedHSL

Base quantized HSL values without computed fields. Defined in the extraction module.

interface QuantizedHSL {
  hue: number;       // 0, 15, 30, ... 345
  saturation: number; // 0, 15, 30, 50, 75, 100
  lightness: number;  // 10, 30, 50, 70, 90
}

Types

On this page