contrastRegionPaths

function contrastRegionPaths(
  reference: Color,
  hue: number,
  options?: ContrastRegionPathOptions,
  trace?: InternalPlaneTraceContext | null,
): ContrastRegionPoint[][];

Each side of the region (darker or lighter than the reference) is traced as one luminance level curve along rays from black. Contour pieces start and end exactly where the curve meets the gamut edge (with the GAMUT_EPSILON slack of inSrgbGamut / inP3Gamut), the chroma axis, or maxChroma; initialSamples, errorTolerance, and maxDepth only set how finely the curve between those ends is sampled. Every returned point passes contrastRatio / contrastAPCA with the region's gamut and is in that gamut.

A reference with room on both sides typically yields two paths (darker and lighter); paths are sorted by point count, longest first. A non-finite hue or a non-positive maxChroma returns [].

Parameters

referenceColor

Color the samples are measured against.

huenumber

OKLCH hue in degrees (wrapped).

options?ContrastRegionPathOptionsdefault {}

Gamut, metric, threshold and sampling options.

trace?InternalPlaneTraceContext | null

Internal tracing context used by the plane query layer; omit it.

Returns

ContrastRegionPoint[][]Contour paths of { l, c } points, longest first.

Throws

• When options.gamut is not 'srgb' or 'display-p3', or when an option removed with an earlier solver (such as lightnessSteps or engine) is set.
• When the threshold is out of range, initialSamples is not an integer >= 2, maxDepth is not an integer >= 0, or errorTolerance is not a finite number > 0.

Example

import { contrastRegionPaths, parse } from '@pbroom/color-kit';

const paths = contrastRegionPaths(parse('#808080'), 250, {
  level: 'AA-large',
});
paths.length; // → 2 (one darker side, one lighter side)
paths[0][0]; // → { l: ≈ 0.338, c: 0 }

See also