getPlaneContrastRegion

function getPlaneContrastRegion(
  planeDefinition: PlaneDefinition,
  query: PlaneContrastQueryOptions,
  trace?: InternalPlaneTraceContext | null,
): PlaneContrastRegionResult;

Each side of the reference (darker and lighter) that has passing colors yields one line, sorted longest first. A line runs between the chroma axis, the gamut edge and maxChroma, and every point on it passes the threshold and is in the target gamut. Points carry OKLCH l/c and plane x/y; stroke the lines with toSvgCompoundPath.

Only OKLCH lightness × chroma planes produce geometry (see usesLightnessAndChroma); any other plane returns an empty list, after the same option validation.

Parameters

planeDefinitionPlaneDefinition

Plane to project onto; a Plane or any PlaneDefinition.

queryPlaneContrastQueryOptions

Contrast options: reference color, optional hue override, and the metric, threshold and sampling options of ContrastRegionPathOptions (WCAG 'AA' against sRGB by default).

trace?InternalPlaneTraceContext | null

Internal trace hook; leave it out and use inspectPlaneQuery to capture a trace.

Returns

PlaneContrastRegionResultA new result with the resolved hue and contour lines.

Throws

• When gamut is not 'srgb' or 'display-p3', or an option removed with an earlier solver (such as lightnessSteps) is set.
• When the threshold or a sampling option is out of range.

Example

import { parse } from '@pbroom/color-kit';
import { definePlane, getPlaneContrastRegion } from '@pbroom/color-kit/plane';

const plane = definePlane({ fixed: { h: 264 } });
const { paths } = getPlaneContrastRegion(plane, {
  reference: parse('#ffffff'),
  metric: 'apca',
});
paths.map((path) => path.length); // → [43]

See also

Also exported from

• @pbroom/color-kitthe same declaration, re-exported