ContrastRegionPathOptions

interface ContrastRegionPathOptions {
  gamut?: GamutTarget;
  metric?: ContrastMetric;
  threshold?: number;
  level?: ContrastRegionLevel;
  apcaPreset?: ContrastApcaPreset;
  apcaPolarity?: ContrastApcaPolarity;
  apcaRole?: ContrastApcaRole;
  maxChroma?: number;
  alpha?: number;
  simplifyTolerance?: number;
  initialSamples?: number;
  errorTolerance?: number;
  maxDepth?: number;
  engine?: undefined;
  samplingMode?: undefined;
  edgeInterpolation?: undefined;
  adaptiveBaseSteps?: undefined;
  adaptiveMaxDepth?: undefined;
  lightnessSteps?: undefined;
  chromaSteps?: undefined;
  hybridMaxDepth?: undefined;
  hybridErrorTolerance?: undefined;
  tolerance?: undefined;
  maxIterations?: undefined;
}

Properties

gamut?GamutTargetdefault 'srgb'

Target gamut. The reference and samples are measured as displayed in it, with channels clipped as contrastRatio / contrastAPCA clip them (an out-of-gamut reference is not gamut-mapped), and paths stay inside it.

metric?ContrastMetricdefault 'wcag'

Contrast metric used when evaluating region membership.

threshold?number

Explicit contrast threshold. If provided it overrides level / apcaPreset. For metric: 'wcag' this is a contrast ratio and must be greater than 1. For metric: 'apca' it is a normalized Lc magnitude, on the scale contrastAPCA returns (0.6 for Lc 60), and must be greater than 0. Other values throw an Error.

level?ContrastRegionLeveldefault 'AA'` (4.5:1)

WCAG threshold preset, used when metric is 'wcag' and threshold is omitted.

apcaPreset?ContrastApcaPresetdefault 'body'` (Lc 60, normalized 0.6)

APCA threshold preset used when metric is 'apca' and threshold is omitted.

apcaPolarity?ContrastApcaPolaritydefault 'absolute'

APCA polarity test mode used when metric is 'apca':

• 'absolute': |Lc| >= threshold
• 'positive': Lc >= threshold
• 'negative': Lc <= -threshold

apcaRole?ContrastApcaRoledefault 'sample-text'

APCA sample/reference role used when metric is 'apca':

• 'sample-text': Lc = contrastAPCA(sample, reference)
• 'sample-background': Lc = contrastAPCA(reference, sample)

maxChroma?numberdefault 0.4

Upper chroma bound of the region: paths end at this chroma.

alpha?numberdefault 1

Alpha channel used while sampling.

simplifyTolerance?number

If set, run Ramer-Douglas-Peucker simplification on each contour path. Tolerance is in normalized (l, c) space; e.g. 0.001–0.002. Points are kept wherever a simplified segment would leave the gamut, so every segment stays in gamut as without simplification. Omit or 0 to disable.

initialSamples?numberdefault 32

Initial samples per region side (integer >= 2, clamped to 512), spread evenly over the angles where that side is visible. Refinement adds samples where the contour bends.

errorTolerance?numberdefault 0.0015

Largest distance, in l/c units, a sampled midpoint may lie from the chord of its interval before the interval is split (finite and > 0, clamped to at least 1e-6).

maxDepth?numberdefault 6

Maximum halvings of an initial sample interval to meet errorTolerance (integer >= 0, clamped to 12). A few more are allowed while a chord leaves the gamut.

engine?undefined

Removed with the legacy marching-squares engine. Passing it is a type error and throws a TypeError.

samplingMode?undefined

Removed with the legacy engine; see engine.

edgeInterpolation?undefined

Removed with the legacy engine; see engine.

adaptiveBaseSteps?undefined

Removed with the legacy engine; see engine.

adaptiveMaxDepth?undefined

Removed with the legacy engine; see engine.

lightnessSteps?undefined

Removed with the hybrid solver; use initialSamples. Passing it is a type error and throws a TypeError.

chromaSteps?undefined

Removed with the hybrid solver; use initialSamples.

hybridMaxDepth?undefined

Removed with the hybrid solver; use maxDepth.

hybridErrorTolerance?undefined

Removed with the hybrid solver; use errorTolerance.

tolerance?undefined

Removed with the hybrid solver, which forwarded it to maxChromaAt.

maxIterations?undefined

Removed with the hybrid solver, which forwarded it to maxChromaAt.