definePlane

function definePlane(
  planeObject?: PlaneDefinition<'oklch'>,
): Plane<'oklch'>;

function definePlane<Model extends 'hsl' | 'hsv' | 'oklab' | 'display-p3' | 'rgb' | 'hct'>(
  planeObject: PlaneDefinitionFor<Model>,
): Plane<Model>;

The returned Plane is the input to every plane query (getPlaneGamutRegion, getPlaneContrastRegion, sense, …) and to the planeToColor / colorToPlane projections. Plane coordinates are normalized: { x: 0, y: 0 } maps to the start of each axis range and { x: 1, y: 1 } to its end. Ranges may be descending to flip an axis; the OKLCH chroma default [0.4, 0] puts high chroma at y = 0, the top of an SVG or canvas.

Defaults: model is 'oklch'; omitted axes come from PLANE_MODEL_DEFAULT_AXES (x: l, y: c for OKLCH) and omitted ranges from PLANE_MODEL_DEFAULT_RANGES. Channels not on an axis are resolved from fixed, then from the anchor color (converted into the model), then from model defaults, and clamped to the model's valid range (hue is wrapped into [0, 360)). alpha defaults to 1.

Type-level guarantees: channel names in x, y and fixed are checked against the chosen model (definePlane({ model: 'rgb', x: { channel: 'l' } }) and fixed: { h } on an RGB plane are compile errors), a non-OKLCH model must be spelled out, and the result is typed Plane<Model>. Use PlaneDefinitionFor to keep that narrowing when the definition is stored in a variable first, and resolvePlaneDefinition for definitions whose model is only known at runtime.

Overload 1 of 2

Parameters

planeObject?PlaneDefinition<'oklch'>

Plane input; see PlaneDefinition for each field. Omit it for the default OKLCH lightness × chroma plane at hue 0.

Returns

Plane<'oklch'>A new resolved plane with explicit axes, ranges and fixed channels.

Overload 2 of 2

Defines a 2D color plane for a non-OKLCH model (model is required).

Same behavior as the OKLCH overload; channel names in x, y and fixed are checked against Model and the result is typed Plane<Model>.

Parameters

planeObjectPlaneDefinitionFor<Model>

Plane input with an explicit model.

Returns

Plane<Model>A new resolved plane with explicit axes, ranges and fixed channels.

Throws

• When model is not a supported plane model (including the removed 'p3' spelling; use 'display-p3').
• When an axis or fixed channel is not valid for the model, both axes use the same channel, or a range or fixed value is not finite.

Example

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

const plane = definePlane({
  model: 'oklch',
  x: { channel: 'l' },
  y: { channel: 'c' },
  fixed: { h: 264 },
});
plane.y; // → { channel: 'c', range: [0.4, 0] }
plane.fixed; // → { l: 0.5, c: 0, h: 264, alpha: 1 }

See also

Also exported from

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