inspectPlaneQuery

function inspectPlaneQuery<Result extends PlaneQuery = PlaneQuery>(
  planeDefinition: PlaneDefinition,
  query: Result,
  options?: PlaneQueryTraceOptions,
): PlaneQueryInspection<Extract<PlaneGamutBoundaryResult, { kind: Result['kind'] }> | Extract<PlaneGamutRegionResult, { kind: Result['kind'] }> | Extract<PlaneContrastBoundaryResult, { kind: Result['kind'] }> | Extract<PlaneContrastRegionResult, { kind: Result['kind'] }> | Extract<PlaneChromaBandResult, { kind: Result['kind'] }> | Extract<PlaneFallbackPointResult, { kind: Result['kind'] }> | Extract<PlaneGradientResult, { kind: Result['kind'] }>>;

result is identical to what runPlaneQuery returns. trace is a PlaneQueryTrace with:

• summary: the query kind and trace level; the solver that ran (gamut-region solvers such as 'analytic-lc' or 'implicit-contour', or 'contrast-rays') and its sampling mode; the viewport relation ('inside', 'outside' or 'intersects'); work counters (samples, scalar evaluations, marching-squares cells and segments, intermediate paths and points); the result's path and point counts; fidelity settings; and wall-clock time in milliseconds (totalTimeMs, plus per-phase timings where a solver records them).
• stages: an ordered list of solver steps ('solver', 'scalarGrid', 'viewportClassification', 'marchingSquares', 'paths' with the intermediate paths, and a final 'metrics' snapshot). Empty when level is 'summary'.

Which counters and stages appear depends on the query kind: gamut-region and contrast queries record solver detail; gamut-boundary, chroma-band, fallback-point and gradient queries record only result counts, total time and the 'metrics' stage. Times vary between runs; never compare them for equality.

Parameters

planeDefinitionPlaneDefinition

Plane to query; a Plane or any PlaneDefinition.

queryResult

Query payload; kind selects the query type and narrows the returned result.

options?PlaneQueryTraceOptions

Trace detail. level defaults to 'stages'; 'full' also records per-cell marching-squares events and (unless includeScalarGrid is false) the sampled scalar grid. maxStageEntries (default 128, clamped to [8, 512]) caps how many cells, paths and points per path each stage keeps.

Returns

PlaneQueryInspection<Extract<PlaneGamutBoundaryResult, { kind: Result['kind'] }> | Extract<PlaneGamutRegionResult, { kind: Result['kind'] }> | Extract<PlaneContrastBoundaryResult, { kind: Result['kind'] }> | Extract<PlaneContrastRegionResult, { kind: Result['kind'] }> | Extract<PlaneChromaBandResult, { kind: Result['kind'] }> | Extract<PlaneFallbackPointResult, { kind: Result['kind'] }> | Extract<PlaneGradientResult, { kind: Result['kind'] }>>A new { result, trace } pair.

Throws

• When query.gamut is not 'srgb' or 'display-p3'.
• When query.kind is unknown or the plane or query options are invalid.

Example

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

const plane = definePlane({ fixed: { h: 264 } }); // OKLCH, x: l, y: c
const { result, trace } = inspectPlaneQuery(plane, { kind: 'gamutRegion' });
result.viewportRelation; // → 'intersects'
trace.summary.solver; // → 'analytic-lc'
trace.summary.resultPointCount; // → 131
trace.stages.map((stage) => stage.kind);
// → ['solver', 'marchingSquares', 'viewportClassification', 'paths',
//    'paths', 'marchingSquares', 'paths', 'metrics']

See also

Also exported from

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