@photivra/engine 1.5.0 → 2.0.0

package/docs/api/color-chromatic-adaptation.md

@@ -0,0 +1,82 @@
+# color/chromatic-adaptation.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateChromaticAdaptationMatrix
+
+Calculates a linear chromatic-adaptation matrix between two whites. Linear CATs are
+standard models, but they predict corresponding colours only approximately. The matrix
+itself is calculated exactly from the declared transform.
+
+```ts
+export function calculateChromaticAdaptationMatrix(input: CalculateChromaticAdaptationMatrixInput): CalculationResult<ChromaticAdaptationMatrix>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateChromaticAdaptationMatrixInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateChromaticAdaptationMatrixInput {
+  transform: ChromaticAdaptationTransform;
+  /** White of the source viewing/illumination condition (relative XYZ, Y > 0). */
+  sourceWhiteXyz: CieXyzTristimulus;
+  /** White of the destination condition (relative XYZ, Y > 0). */
+  destinationWhiteXyz: CieXyzTristimulus;
+  /** Degree of adaptation D in [0, 1]; defaults to 1 (complete adaptation). */
+  degreeOfAdaptation?: number;
+}
+```
+
+## calculateChromaticallyAdaptedXyz
+
+Adapts one XYZ colour between whites with the selected transform.
+
+```ts
+export function calculateChromaticallyAdaptedXyz(input: CalculateChromaticAdaptationMatrixInput & { xyz: CieXyzTristimulus }): CalculationResult<{ xyz: CieXyzTristimulus; matrix: ColorMatrix3x3 }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CHROMATIC_ADAPTATION_TRANSFORMS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CHROMATIC_ADAPTATION_TRANSFORMS: readonly ChromaticAdaptationTransform[] = Object.freeze(["bradford", "cat16", "xyz-scaling"])
+```
+
+## ChromaticAdaptationMatrix
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ChromaticAdaptationMatrix {
+  transform: ChromaticAdaptationTransform;
+  degreeOfAdaptation: number;
+  /** Row-major XYZ_source → XYZ_destination matrix. */
+  matrix: ColorMatrix3x3;
+  /** The per-channel cone-space gains Dᵢ. */
+  coneGains: readonly [number, number, number];
+}
+```
+
+## ChromaticAdaptationTransform
+
+Supported linear chromatic-adaptation transforms.
+
+```ts
+export type ChromaticAdaptationTransform = "bradford" | "cat16" | "xyz-scaling";
+```
+
+## resolveChromaticAdaptationConeMatrix
+
+Returns a copy of the XYZ → cone-space matrix of a transform.
+
+```ts
+export function resolveChromaticAdaptationConeMatrix(transform: ChromaticAdaptationTransform): ColorMatrix3x3;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/color-color-difference.md

@@ -0,0 +1,134 @@
+# color/color-difference.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateCielabFromCielch
+
+CIE LCh(ab) → CIELAB.
+
+```ts
+export function calculateCielabFromCielch(input: { lch: CielchColor }): CalculationResult<CielabColor>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateCielabFromXyz
+
+CIE XYZ → CIELAB relative to a reference white (same XYZ scale).
+
+```ts
+export function calculateCielabFromXyz(input: { xyz: CieXyzTristimulus; referenceWhiteXyz: CieXyzTristimulus }): CalculationResult<CielabColor>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateCielchFromCielab
+
+CIELAB → CIE LCh(ab): C*ab = √(a*² + b*²), h_ab = atan2(b*, a*) in degrees.
+
+```ts
+export function calculateCielchFromCielab(input: { lab: CielabColor }): CalculationResult<CielchColor>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateColorDifference
+
+Colour difference between two CIELAB colours with an explicit formula.
+
+```ts
+export function calculateColorDifference(input: CalculateColorDifferenceInput): CalculationResult<{ deltaE: number; formula: ColorDifferenceFormula }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateColorDifferenceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateColorDifferenceInput {
+  /** Reference (standard) colour; ΔE94 is asymmetric in it. */
+  reference: CielabColor;
+  sample: CielabColor;
+  formula: ColorDifferenceFormula;
+  /** CIEDE2000 only; defaults to 1, 1, 1. */
+  parametricFactors?: Ciede2000ParametricFactors;
+  /** CIE94 only; all five fields are required when given. Defaults to the reference conditions 1, 1, 1, 0.045, 0.015. */
+  cie94Factors?: Cie94ParametricFactors;
+}
+```
+
+## calculateXyzFromCielab
+
+CIELAB → CIE XYZ relative to a reference white.
+
+```ts
+export function calculateXyzFromCielab(input: { lab: CielabColor; referenceWhiteXyz: CieXyzTristimulus }): CalculationResult<CieXyzTristimulus>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## Cie94ParametricFactors
+
+CIE94 parametric factors k_L, k_C, k_H and weighting constants K₁, K₂ (S_C = 1 + K₁C*₁,
+S_H = 1 + K₂C*₁). The default is the reference conditions: 1, 1, 1, 0.045, 0.015.
+
+```ts
+export interface Cie94ParametricFactors {
+  /** k_L, greater than zero. */
+  lightness: number;
+  /** k_C, greater than zero. */
+  chroma: number;
+  /** k_H, greater than zero. */
+  hue: number;
+  /** K₁ in S_C = 1 + K₁C*₁; finite and not negative. */
+  k1: number;
+  /** K₂ in S_H = 1 + K₂C*₁; finite and not negative. */
+  k2: number;
+}
+```
+
+## Ciede2000ParametricFactors
+
+CIEDE2000 parametric factors (default 1, 1, 1 for reference conditions).
+
+```ts
+export interface Ciede2000ParametricFactors {
+  lightness: number;
+  chroma: number;
+  hue: number;
+}
+```
+
+## CielabColor
+
+CIE 1976 L*a*b* coordinates.
+
+```ts
+export interface CielabColor {
+  lStar: number;
+  aStar: number;
+  bStar: number;
+}
+```
+
+## CielchColor
+
+CIE 1976 L*C*h(ab) coordinates; hue in degrees [0, 360).
+
+```ts
+export interface CielchColor {
+  lStar: number;
+  chromaStar: number;
+  hueDegrees: number;
+}
+```
+
+## ColorDifferenceFormula
+
+Colour-difference formula.
+
+```ts
+export type ColorDifferenceFormula = "cie76" | "cie94" | "ciede2000";
+```

package/docs/api/color-color-matching-functions.md

@@ -0,0 +1,259 @@
+# color/color-matching-functions.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## ANALYTIC_CIE_1931_CMF_DOMAIN_NANOMETERS
+
+Wavelength domain over which the analytic CIE 1931 fit is accepted (the domain it was fitted on).
+
+```ts
+ANALYTIC_CIE_1931_CMF_DOMAIN_NANOMETERS: Readonly<SpectralWavelengthRangeNanometers> = Object.freeze({ minimum: 360, maximum: 830 })
+```
+
+## ColorimetricObserver
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ColorimetricObserver = "cie-1931-2-degree" | "cie-1964-10-degree" | "caller-defined";
+```
+
+## ColorimetricQuadratureNode
+
+One wavelength quadrature node; d-lambda is in nanometres.
+
+```ts
+export interface ColorimetricQuadratureNode {
+  wavelengthNanometers: number;
+  wavelengthMeasureNanometers: number;
+}
+```
+
+## ColorimetricSpectralSample
+
+One tabulated spectral value at one wavelength.
+
+```ts
+export interface ColorimetricSpectralSample extends SpectralWavelengthSample {
+  value: number;
+}
+```
+
+## ColorimetricSpectrum
+
+A spectral distribution or spectral factor (reflectance, transmittance, relative SPD,
+sensitivity).
+- `tabulated` is the JSON form: strictly increasing wavelengths, linear interpolation, and an
+  error (fail closed) outside the table.
+- `function` is an in-process evaluator (for example a Planckian SPD). It must be finite over
+  its declared range.
+
+```ts
+export type ColorimetricSpectrum =
+  | { kind: "tabulated"; samples: readonly ColorimetricSpectralSample[] }
+  | { kind: "function"; wavelengthRangeNanometers: SpectralWavelengthRangeNanometers; evaluate: (wavelengthNanometers: number) => number };
+```
+
+## COLORIMETRY_MODEL_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+COLORIMETRY_MODEL_VERSION = "2.0.0" as const
+```
+
+## ColorMatchingFunctionsSource
+
+Selects a colour-matching-function source.
+
+```ts
+export type ColorMatchingFunctionsSource =
+  | { kind: "analytic-cie-1931-multi-lobe-fit" }
+  | {
+      kind: "tabulated";
+      observer: ColorimetricObserver;
+      /** Caller identity for the dataset (for example a DOI); recorded in provenance. */
+      datasetId: string;
+      samples: readonly TabulatedColorMatchingSample[];
+    };
+```
+
+## createColorimetricMidpointQuadrature
+
+Builds deterministic uniform midpoint wavelength nodes covering the range. Every
+node carries its d-lambda measure in nm; the measures sum to the range width.
+
+```ts
+export function createColorimetricMidpointQuadrature(input: CreateColorimetricMidpointQuadratureInput): ColorimetricQuadratureNode[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateColorimetricMidpointQuadratureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateColorimetricMidpointQuadratureInput {
+  wavelengthRangeNanometers: SpectralWavelengthRangeNanometers;
+  /** Hard upper bound on each midpoint subinterval width, nm. */
+  maximumSubintervalWidthNanometers: number;
+}
+```
+
+## estimateCie1931ColorMatchingFunctions
+
+Evaluates the engine's multi-lobe analytic approximation of the CIE 1931 2° colour-matching
+functions at one wavelength (nm, standard-air wavelength as in the CIE tables). Approximation:
+see the module notes for the measured fit error. The values are non-negative over the domain.
+
+```ts
+export function estimateCie1931ColorMatchingFunctions(wavelengthNanometers: number): CieXyzTristimulus;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## IntegratedSpectrumXyz
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IntegratedSpectrumXyz {
+  xyz: CieXyzTristimulus;
+  /** Tristimulus values of S(λ) alone under the same normalization (the adopted white). */
+  whiteXyz: CieXyzTristimulus;
+  chromaticity: CieXyChromaticity | null;
+  normalizationFactor: number;
+  observer: ColorimetricObserver;
+  nodeCount: number;
+}
+```
+
+## integrateSpectrumToXyz
+
+Integrates a spectrum (optionally multiplied by a reflectance/transmittance factor)
+against colour-matching functions with caller-explicit quadrature (the tristimulus integral of
+Wyman, Sloan & Shirley 2013, Eq. 1; also CIE 15:2018 §7).
+Provenance is `approximation` for the analytic CMF fit and `calculated` for
+caller-tabulated CMFs. Either way, the caller chooses the quadrature.
+
+```ts
+export function integrateSpectrumToXyz(input: IntegrateSpectrumToXyzInput): CalculationResult<IntegratedSpectrumXyz>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## IntegrateSpectrumToXyzInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IntegrateSpectrumToXyzInput {
+  quadratureNodes: readonly ColorimetricQuadratureNode[];
+  /** Illuminant SPD or emitted spectral radiance S(λ). */
+  spectralDistribution: ColorimetricSpectrum;
+  /** Optional spectral reflectance/transmittance factor R(λ); omitted means R = 1. */
+  spectralFactor?: ColorimetricSpectrum;
+  colorMatchingFunctions: ColorMatchingFunctionsSource;
+  normalization: TristimulusNormalization;
+}
+```
+
+## MAX_COLORIMETRIC_QUADRATURE_NODES
+
+Upper bound on quadrature nodes per integration call.
+
+```ts
+MAX_COLORIMETRIC_QUADRATURE_NODES = 100_000
+```
+
+## MAX_COLORIMETRIC_TABLE_SAMPLES
+
+Upper bound on samples in a caller-supplied tabulated spectrum or CMF table.
+
+```ts
+MAX_COLORIMETRIC_TABLE_SAMPLES = 100_000
+```
+
+## parseColorimetricQuadratureNodes
+
+Validates explicit quadrature nodes (positive wavelengths and positive measures).
+
+```ts
+export function parseColorimetricQuadratureNodes(nodes: unknown): ColorimetricQuadratureNode[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## prepareColorimetricSpectrum
+
+Validates a tabulated or functional spectrum (values must be finite; sign is not restricted).
+
+```ts
+export function prepareColorimetricSpectrum(spectrum: ColorimetricSpectrum, path = "spectrum"): PreparedColorimetricSpectrum;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## prepareColorMatchingFunctions
+
+Validates a colour-matching-function source once for repeated evaluation.
+Tabulated values may be signed only for `caller-defined` observers; CIE observers
+require non-negative values.
+
+```ts
+export function prepareColorMatchingFunctions(source: ColorMatchingFunctionsSource): PreparedColorMatchingFunctions;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PreparedColorimetricSpectrum
+
+A validated spectrum ready for evaluation.
+
+```ts
+export interface PreparedColorimetricSpectrum {
+  wavelengthRangeNanometers: SpectralWavelengthRangeNanometers;
+  evaluate(wavelengthNanometers: number): number;
+}
+```
+
+## PreparedColorMatchingFunctions
+
+Validated, reusable colour-matching functions.
+
+```ts
+export interface PreparedColorMatchingFunctions {
+  observer: ColorimetricObserver;
+  sourceKind: ColorMatchingFunctionsSource["kind"];
+  datasetId: string;
+  scientificStatus: "approximation" | "caller-tabulated";
+  wavelengthRangeNanometers: SpectralWavelengthRangeNanometers;
+  /** x̄, ȳ, z̄ at one wavelength in nm; throws outside the declared range. */
+  evaluate(wavelengthNanometers: number): CieXyzTristimulus;
+}
+```
+
+## TabulatedColorMatchingSample
+
+One tabulated colour-matching sample.
+
+```ts
+export interface TabulatedColorMatchingSample extends SpectralWavelengthSample {
+  xBar: number;
+  yBar: number;
+  zBar: number;
+}
+```
+
+## TristimulusNormalization
+
+Normalization of integrated tristimulus values.
+- `white-luminance-one`: k = 1 / Σ S ȳ Δλ, so the perfect reflecting diffuser (or the
+  illuminant itself) has Y = 1 (relative colorimetry with Y scaled to 1; also CIE 15:2018).
+- `scale`: X = factor · Σ …; for example 683.002 lm/W with spectral radiance in
+  W·m⁻²·sr⁻¹·nm⁻¹ yields luminance in cd/m² (the caller owns the unit semantics).
+
+```ts
+export type TristimulusNormalization = { kind: "white-luminance-one" } | { kind: "scale"; factor: number };
+```

package/docs/api/color-colorimetry-math.md

@@ -0,0 +1,54 @@
+# color/colorimetry-math.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## Cie1960UvChromaticity
+
+CIE 1960 UCS (u, v) chromaticity coordinates (dimensionless).
+
+```ts
+export interface Cie1960UvChromaticity {
+  u: number;
+  v: number;
+}
+```
+
+## CieXyChromaticity
+
+CIE 1931 (x, y) chromaticity coordinates (dimensionless).
+
+```ts
+export interface CieXyChromaticity {
+  x: number;
+  y: number;
+}
+```
+
+## CieXyzTristimulus
+
+Relative CIE XYZ tristimulus values. Units are relative (dimensionless);
+a normalized white has `y = 1` unless a function documents another scale.
+
+```ts
+export interface CieXyzTristimulus {
+  x: number;
+  y: number;
+  z: number;
+}
+```
+
+## ColorMatrix3x3
+
+Row-major 3×3 matrix; `m[row][column]`. Applied as `m · v` to column vectors.
+
+```ts
+export type ColorMatrix3x3 = readonly [ColorVector3, ColorVector3, ColorVector3];
+```
+
+## ColorVector3
+
+Three-component vector (dimensionless unless documented otherwise).
+
+```ts
+export type ColorVector3 = readonly [number, number, number];
+```

package/docs/api/color-gamut-mapping.md

@@ -0,0 +1,72 @@
+# color/gamut-mapping.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateGamutMappedColor
+
+Maps one D65-relative XYZ colour into a target RGB gamut (see module notes).
+
+```ts
+export function calculateGamutMappedColor(input: PrepareRgbGamutMappingInput & { xyz: CieXyzTristimulus }): CalculationResult<GamutMappedColor>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## GamutMappedColor
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GamutMappedColor {
+  /** Linear RGB in the target space, each component in [0, 1]. */
+  linearRgb: ColorVector3;
+  /** True when lightness or chroma was changed. */
+  adjusted: boolean;
+  /** Lightness was outside [0, 100] and was clipped to black or white. */
+  lightnessClipped: boolean;
+}
+```
+
+## GamutMappingMethod
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type GamutMappingMethod = "cielab-hue-preserving-chroma-compression";
+```
+
+## PreparedRgbGamutMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PreparedRgbGamutMapping {
+  colorSpace: RgbColorSpaceId;
+  kneeFraction: number;
+  /** Maps one XYZ colour (D65-relative, white Y = 1). */
+  map(xyz: ColorVector3): GamutMappedColor;
+}
+```
+
+## prepareRgbGamutMapping
+
+Validates the target space once and returns a reusable per-colour mapper.
+
+```ts
+export function prepareRgbGamutMapping(input: PrepareRgbGamutMappingInput): PreparedRgbGamutMapping;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PrepareRgbGamutMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrepareRgbGamutMappingInput {
+  colorSpace: RgbColorSpaceId;
+  method: GamutMappingMethod;
+  /** Fraction of the boundary chroma left untouched, in [0, 1]. 1 means clip to the boundary. */
+  kneeFraction: number;
+}
+```