Skip to content

Open source CapCut alternative.

TypeScript
33.6 KB
Raw Blame
/**
 * The grade's pixel math: one pure transform on display values that every
 * renderer consumes through the clip LUT (colorPipeline.ts). A grade
 * resolves to at most two layers — the manual adjustments, which balance the
 * shot, and the preset on top, the look (scaled by its amount, optionally
 * kept off skin tones) — and each layer runs its stages in one order, on the
 * container the project delivers in (Rec.709/BT.1886 for SDR, Rec.2100 HLG or
 * PQ for HDR):
 *
 *   light, in linear light with headroom (the container's transfer inverted,
 *   then the shoulder below inverted):
 *     monochrome (a negative saturation slider, see below) → white balance
 *     (CAT02) → exposure (stops) → contrast (a power about 18% grey) →
 *     highlights / shadows / whites / blacks / brilliance (smooth luminance
 *     masks) → wheels (ASC CDL offset; lift / gamma / gain) → encode
 *   color, on display values:
 *     curves → hue / saturation / vibrance / HSL bands in OkLCh → fade
 *
 * Desaturation runs first. Toning — sepia and its relatives — is a black and
 * white image with a cast laid over it, so the chroma has to go before the
 * warmth and the wheels arrive; a saturation *increase* stays in the color
 * stage where it scales the chroma the light stage produced. The split keeps
 * the slider continuous through zero.
 *
 * Skin protection is one rule at the layer's end: the tone lands in full and
 * the chroma the layer moved blends back toward the pixel's own by the skin
 * weight.
 *
 * No control throws picture away. Linear light carries headroom above the
 * container's white, and leaving it for display values passes through a
 * shoulder that is the identity up to SHOULDER_KNEE and rolls everything up
 * to HEADROOM times white smoothly into white; entering inverts it exactly,
 * so an ungraded pixel round-trips unchanged and a brightened highlight
 * compresses where it used to clip. Every darkening move is a gain, never a
 * subtraction, so nothing crosses black: a shadow pushed down keeps its
 * detail. gradeRange.test.ts holds both.
 */

import {
  type ColorGrade,
  type CurvePoint,
  type GradePresetRef,
  type HslBand,
  type WheelZone,
  GRADE_LUT_SCALAR_KEYS,
  GRADE_MAX,
  HSL_BANDS,
  WHEEL_ZONES,
  normalizeGrade,
} from "./colorGrade";
import {
  type Mat3,
  type OutputSpace,
  type Primaries,
  D65,
  OKLAB_M2,
  OKLAB_M2_INV,
  REC2020_PRIMARIES,
  REC709_PRIMARIES,
  bt1886Decode,
  bt1886Encode,
  hlgOetf,
  hlgOetfInverse,
  illuminantXy,
  mat3Apply,
  oklabMatrices,
  pqDecode,
  pqEncode,
  rgbToXyzMatrix,
  spow,
  whiteBalanceMatrix,
} from "./colorSpace";
import { GRADE_PRESETS } from "./gradePresets";
import { monotoneCubic } from "./monotone";

const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);

/* ------------------------------------------------------------------ */
/* Slider semantics                                                    */
/* ------------------------------------------------------------------ */

/** Exposure at ±50 is ±2 stops. */
export const EXPOSURE_STOPS_AT_MAX = 2;
/** Temperature at ±50 assumes an illuminant 100 mireds from D65 (about
 * 3900 K warm, 18600 K cool). */
export const TEMPERATURE_MIREDS_AT_MAX = 100;
/** Tint at ±50 walks the isotherm by Δuv 0.035. */
export const TINT_DUV_AT_MAX = 0.035;
/** Contrast at ±50 is a power of 1.5 / 0.5 about 18% grey. */
export const CONTRAST_POWER_AT_MAX = 0.5;
/** Fade at 50 lifts black by this much of the display range. */
export const FADE_LIFT_AT_MAX = 0.22;

/** The luminance-mask amplitudes, in stops at their mask's peak. Highlights
 * is bounded so it never clips: 3.4·V²(1−V) stops keeps Y·2^stops ≤ 1 for
 * every V. */
const HIGHLIGHTS_STOPS = 3.4;
const SHADOWS_STOPS = 6.75;
const WHITES_STOPS = 0.7;
const BRILLIANCE_STOPS = 0.5;
/** Raised blacks are an additive lift in linear light, through the slider's
 * signed square: a linear offset shows on the encoded ramp as its 1/2.4
 * power, so the first notches would otherwise jump. */
const BLACKS_OFFSET = 0.03;
/** Lowered blacks are a gain on the darkest tones, this many stops at black
 * at full travel: dense shadows that keep their detail. */
const BLACKS_DARKEN_STOPS = 2;

/** Wheel amplitudes at a full puck / luma trim. A raised lift adds light
 * toward black; a lowered one is a gain that reaches WHEEL_LIFT_DARKEN at
 * black. Offset is a per-channel gain in stops, the printer light. */
const WHEEL_LIFT = 0.03;
const WHEEL_LIFT_DARKEN = 0.6;
const WHEEL_GAMMA = 0.35;
const WHEEL_GAIN = 0.5;
const WHEEL_OFFSET_STOPS = 1;

/** The shoulder between linear light and display values: identity up to
 * this share of the container's white, then a smooth roll into white that
 * reaches it at HEADROOM times white with zero slope. */
export const SHOULDER_KNEE = 0.5;
export const HEADROOM = 4;

/* ------------------------------------------------------------------ */
/* The container a grade works in                                      */
/* ------------------------------------------------------------------ */

export interface GradeSpace {
  output: OutputSpace;
  primaries: Primaries;
  /** Signal → linear light (display-linear for SDR and PQ, scene-linear for
   * HLG, as each standard defines it). */
  decode(v: number): number;
  encode(l: number): number;
  /** Linear value of an 18% grey card (BT.2408 for the HDR containers). */
  pivot: number;
  /** Linear value of the container's white, where the shoulder lands;
   * Infinity for scene light, whose encoding is its own shoulder. */
  white: number;
  /** Luminance weights of the container's primaries. */
  luma: [number, number, number];
  oklab: { toLms: Mat3; fromLms: Mat3 };
}

const spaces = new Map<OutputSpace, GradeSpace>();

export function gradeSpaceFor(output: OutputSpace): GradeSpace {
  let s = spaces.get(output);
  if (s) return s;
  if (output === "sdr") {
    s = {
      output,
      primaries: REC709_PRIMARIES,
      decode: bt1886Decode,
      encode: bt1886Encode,
      pivot: 0.18,
      white: 1,
      luma: [0.2126, 0.7152, 0.0722],
      oklab: oklabMatrices(REC709_PRIMARIES),
    };
  } else if (output === "hlg") {
    s = {
      output,
      primaries: REC2020_PRIMARIES,
      decode: (v) => (v < 0 ? -hlgOetfInverse(-v) : hlgOetfInverse(v)),
      encode: (l) => (l < 0 ? -hlgOetf(-l) : hlgOetf(l)),
      pivot: hlgOetfInverse(0.38),
      white: 1,
      luma: [0.2627, 0.678, 0.0593],
      oklab: oklabMatrices(REC2020_PRIMARIES),
    };
  } else {
    s = {
      output,
      primaries: REC2020_PRIMARIES,
      decode: (v) => (v < 0 ? -pqDecode(-v) / 1000 : pqDecode(v) / 1000),
      encode: (l) => (l < 0 ? -pqEncode(-l * 1000) : pqEncode(l * 1000)),
      pivot: 26 / 1000,
      white: 10,
      luma: [0.2627, 0.678, 0.0593],
      oklab: oklabMatrices(REC2020_PRIMARIES),
    };
  }
  spaces.set(output, s);
  return s;
}

/**
 * The grade space of scene light rendered by a display transform: linear is
 * scene-linear in `primaries` (18% grey at 0.18, no ceiling), and the
 * encoding is the transform's own response to a neutral, so curves, masks
 * and fade read a tone as the viewer will see it. `neutral` samples the
 * transform on grey from 2^LO to 2^HI; the encoding is piecewise linear in
 * log2 between the samples, and its inverse inverts that same function, so
 * the round trip is exact.
 */
export function sceneGradeSpace(output: OutputSpace, primaries: Primaries, neutral: (y: number) => number): GradeSpace {
  const LO = -16;
  const HI = 12;
  const N = 1024;
  const xs = new Float64Array(N);
  const vs = new Float64Array(N);
  for (let i = 0; i < N; i++) {
    xs[i] = LO + ((HI - LO) * i) / (N - 1);
    vs[i] = neutral(Math.pow(2, xs[i]));
    // A plateau at the top would make the inverse ambiguous; keep it rising.
    if (i && vs[i] <= vs[i - 1]) vs[i] = vs[i - 1] + 1e-9;
  }
  const y0 = Math.pow(2, LO);
  const encode = (y: number): number => {
    if (y <= y0) return (vs[0] * y) / y0;
    const x = Math.log2(y);
    if (x >= HI) return vs[N - 1];
    const f = ((x - LO) / (HI - LO)) * (N - 1);
    const i = Math.floor(f);
    return vs[i] + (vs[i + 1] - vs[i]) * (f - i);
  };
  const decode = (v: number): number => {
    if (v <= vs[0]) return (v / vs[0]) * y0;
    if (v >= vs[N - 1]) return Math.pow(2, HI);
    let lo = 0;
    let hi = N - 1;
    while (hi - lo > 1) {
      const mid = (lo + hi) >> 1;
      if (vs[mid] <= v) lo = mid;
      else hi = mid;
    }
    const x = xs[lo] + ((xs[hi] - xs[lo]) * (v - vs[lo])) / (vs[hi] - vs[lo]);
    return Math.pow(2, x);
  };
  const xyz = rgbToXyzMatrix(primaries);
  return {
    output,
    primaries,
    decode,
    encode,
    pivot: 0.18,
    white: Infinity,
    luma: [xyz[3], xyz[4], xyz[5]],
    oklab: oklabMatrices(primaries),
  };
}

/* ------------------------------------------------------------------ */
/* The shoulder                                                        */
/* ------------------------------------------------------------------ */

/** Linear light with headroom → the container's linear range: identity to
 * the knee, then k + (w − k)·(1 − (1 − u)ⁿ) up to HEADROOM·w, where u runs
 * 0..1 across the roll and n makes the slope 1 at the knee. */
export function shoulder(x: number, white: number): number {
  const k = SHOULDER_KNEE * white;
  if (x <= k) return x;
  const top = HEADROOM * white;
  if (x >= top) return white;
  const n = (top - k) / (white - k);
  const u = (x - k) / (top - k);
  return k + (white - k) * (1 - Math.pow(1 - u, n));
}

/** The shoulder's exact inverse: the container's linear range → linear light
 * with headroom. White maps to HEADROOM·white. */
export function unshoulder(y: number, white: number): number {
  const k = SHOULDER_KNEE * white;
  if (y <= k) return y;
  const top = HEADROOM * white;
  if (y >= white) return top;
  const n = (top - k) / (white - k);
  const t = (y - k) / (white - k);
  return k + (top - k) * (1 - Math.pow(1 - t, 1 / n));
}

/* ------------------------------------------------------------------ */
/* Monotone tone curves                                                */
/* ------------------------------------------------------------------ */

/**
 * Sample a control-point curve into a 256-entry LUT over [0,1] using the
 * Fritsch–Carlson monotone cubic — smooth through every point, no overshoot.
 * The curve holds flat outside its first and last points.
 */
export function curveLut(points: CurvePoint[]): Float32Array {
  const xs = points.map((p) => p[0] / 255);
  const ys = points.map((p) => p[1] / 255);
  const at = monotoneCubic(xs, ys);
  const out = new Float32Array(256);
  for (let s = 0; s < 256; s++) out[s] = clamp01(at(s / 255));
  return out;
}

const sampleCurve = (lut: Float32Array, v: number) => {
  const x = clamp01(v) * 255;
  const i = Math.floor(x);
  const f = x - i;
  return i >= 255 ? lut[255] : lut[i] * (1 - f) + lut[i + 1] * f;
};

/**
 * Build master-curve control points from two semantic knobs: `contrast`
 * (-50..50, an s-curve around mid-gray) and `fade` (0..50, lifted blacks).
 * Returns undefined when both are neutral.
 */
export function semanticMasterCurve(contrast: number, fade: number): CurvePoint[] | undefined {
  const c = Math.max(-GRADE_MAX, Math.min(GRADE_MAX, contrast || 0)) / GRADE_MAX;
  const f = Math.max(0, Math.min(GRADE_MAX, fade || 0)) / GRADE_MAX;
  if (!c && !f) return undefined;
  const bend = Math.round(c * 28);
  const lift = Math.round(f * 56);
  const pts: CurvePoint[] = [
    [0, lift],
    [64, Math.max(0, Math.min(255, 64 - bend + Math.round(lift * 0.4)))],
    [192, Math.max(0, Math.min(255, 192 + bend))],
    [255, 255],
  ];
  return pts;
}

/* ------------------------------------------------------------------ */
/* Hue helpers                                                         */
/* ------------------------------------------------------------------ */

export function rgbToHsl(r: number, g: number, b: number): [number, number, number] {
  const max = Math.max(r, g, b);
  const min = Math.min(r, g, b);
  const l = (max + min) / 2;
  const d = max - min;
  if (d < 1e-6) return [0, 0, l];
  const s = d / (1 - Math.abs(2 * l - 1) || 1e-6);
  let h: number;
  if (max === r) h = ((g - b) / d) % 6;
  else if (max === g) h = (b - r) / d + 2;
  else h = (r - g) / d + 4;
  h *= 60;
  if (h < 0) h += 360;
  return [h, Math.min(1, s), l];
}

function hslToRgb(h: number, s: number, l: number): [number, number, number] {
  const c = (1 - Math.abs(2 * l - 1)) * s;
  const hp = (((h % 360) + 360) % 360) / 60;
  const x = c * (1 - Math.abs((hp % 2) - 1));
  let r = 0;
  let g = 0;
  let b = 0;
  if (hp < 1) [r, g, b] = [c, x, 0];
  else if (hp < 2) [r, g, b] = [x, c, 0];
  else if (hp < 3) [r, g, b] = [0, c, x];
  else if (hp < 4) [r, g, b] = [0, x, c];
  else if (hp < 5) [r, g, b] = [x, 0, c];
  else [r, g, b] = [c, 0, x];
  const m = l - c / 2;
  return [r + m, g + m, b + m];
}

const smoothstep = (a: number, b: number, x: number) => {
  const t = clamp01((x - a) / (b - a || 1e-6));
  return t * t * (3 - 2 * t);
};

const hueDist = (a: number, b: number) => {
  const d = Math.abs(((a - b) % 360) + 360) % 360;
  return d > 180 ? 360 - d : d;
};

/** How strongly a pixel reads as skin: a feathered hue window around warm
 * orange, gated to plausibly-skin saturation. Used to keep a preset's color
 * shifts off faces when its `skin` flag is set. */
export function skinWeight(hueDeg: number, sat: number): number {
  const d = hueDist(hueDeg, 25);
  const hueW = d <= 12 ? 1 : 1 - smoothstep(12, 28, d);
  const satW = smoothstep(0.05, 0.15, sat) * (1 - smoothstep(0.55, 0.78, sat));
  return hueW * satW;
}

/** Feathered partition-of-unity weight of a hue band at a given hue: 1 at the
 * band's center, ramping linearly to 0 at each neighbor's center. */
export function hueBandWeight(hueDeg: number, band: HslBand): number {
  const idx = HSL_BANDS.findIndex((b) => b.id === band);
  if (idx < 0) return 0;
  const c = HSL_BANDS[idx].center;
  const prev = HSL_BANDS[(idx + HSL_BANDS.length - 1) % HSL_BANDS.length].center;
  const next = HSL_BANDS[(idx + 1) % HSL_BANDS.length].center;
  const h = ((hueDeg % 360) + 360) % 360;
  const span = (from: number, to: number) => (((to - from) % 360) + 360) % 360;
  const up = span(prev, c) || 360;
  const down = span(c, next) || 360;
  const fromPrev = span(prev, h);
  if (fromPrev <= up) return fromPrev / up;
  const fromC = span(c, h);
  if (fromC <= down) return 1 - fromC / down;
  return 0;
}

/* ------------------------------------------------------------------ */
/* White balance                                                       */
/* ------------------------------------------------------------------ */

/** The RGB matrix for the temperature and tint sliders in a container: the
 * assumed illuminant sits `temperature` mireds *toward cool* of D65 (a warm
 * result comes from neutralizing a cool light) and `tint` toward green
 * (a magenta result from neutralizing a green light). */
export function whiteBalanceFor(temperature: number, tint: number, primaries: Primaries): Mat3 | null {
  if (!temperature && !tint) return null;
  const mired = -(temperature / GRADE_MAX) * TEMPERATURE_MIREDS_AT_MAX;
  const duv = (tint / GRADE_MAX) * TINT_DUV_AT_MAX;
  const xy = illuminantXy(mired, duv);
  if (Math.abs(xy[0] - D65[0]) < 1e-9 && Math.abs(xy[1] - D65[1]) < 1e-9) return null;
  return whiteBalanceMatrix(primaries, xy);
}

/* ------------------------------------------------------------------ */
/* Preset resolution                                                   */
/* ------------------------------------------------------------------ */

/** Scale a grade's every parameter toward neutral: scalars and tuples by t,
 * curve points toward the identity diagonal. Values go fractional — this
 * shape feeds the transform, never the doc. */
export function scaleGradeToward(g: ColorGrade, t: number): ColorGrade {
  if (t >= 1) return g;
  const out: ColorGrade = {};
  for (const k of GRADE_LUT_SCALAR_KEYS) {
    const v = g[k];
    if (v) out[k] = v * t;
  }
  if (g.curves) {
    const curves: NonNullable<ColorGrade["curves"]> = {};
    for (const ch of ["m", "r", "g", "b"] as const) {
      const pts = g.curves[ch];
      if (pts) curves[ch] = pts.map(([x, y]) => [x, x + (y - x) * t] as CurvePoint);
    }
    out.curves = curves;
  }
  if (g.wheels) {
    const wheels: NonNullable<ColorGrade["wheels"]> = {};
    for (const z of WHEEL_ZONES) {
      const w = g.wheels[z];
      if (w) wheels[z] = [w[0] * t, w[1] * t, w[2] * t];
    }
    out.wheels = wheels;
  }
  if (g.hsl) {
    const hsl: NonNullable<ColorGrade["hsl"]> = {};
    for (const band of HSL_BANDS) {
      const v = g.hsl[band.id];
      if (v) hsl[band.id] = [v[0] * t, v[1] * t, v[2] * t];
    }
    out.hsl = hsl;
  }
  return out;
}

/** Look up a preset ref in the catalog and scale it by its amount. Unknown
 * ids resolve to nothing, so docs from newer catalogs render ungraded. */
export function resolvePreset(ref: GradePresetRef | undefined): ColorGrade | undefined {
  if (!ref?.id) return undefined;
  const preset = GRADE_PRESETS[ref.id];
  if (!preset) return undefined;
  const amount = typeof ref.amount === "number" ? Math.max(0, Math.min(1, ref.amount)) : 1;
  if (amount <= 0) return undefined;
  return scaleGradeToward(preset.grade, amount);
}

/* ------------------------------------------------------------------ */
/* Layers                                                              */
/* ------------------------------------------------------------------ */

interface Wheel {
  zone: WheelZone;
  /** Per-channel amount: the zero-sum chroma direction plus the luma trim. */
  amount: [number, number, number];
}

interface Band {
  /** Neighbor centers and own center, degrees, for the feathered weight. */
  prev: number;
  center: number;
  next: number;
  hueShift: number;
  sat: number;
  lum: number;
}

interface Layer {
  desaturate: number; // 0..1 chroma kept before the light stage (1 = all)
  wb: Mat3 | null;
  gain: number; // linear multiplier from exposure and legacy brightness
  contrast: number; // power about the pivot
  highlights: number;
  shadows: number;
  whites: number;
  blacks: number;
  brilliance: number;
  masks: boolean;
  wheels: Wheel[];
  light: boolean;
  curves: { m?: Float32Array; r?: Float32Array; g?: Float32Array; b?: Float32Array } | null;
  hue: number;
  saturate: number; // chroma multiplier ≥ 1 in the color stage
  vibrance: number;
  bands: Band[];
  color: boolean;
  fade: number;
  skinDamp: boolean;
}

function wheelAmount(w: [number, number, number]): [number, number, number] | null {
  if (!w[0] && !w[1] && !w[2]) return null;
  const radius = Math.min(1, Math.hypot(w[0], w[1]) / GRADE_MAX);
  let chroma: [number, number, number] = [0, 0, 0];
  if (radius > 0) {
    const hue = ((Math.atan2(w[1], w[0]) * 180) / Math.PI + 360) % 360;
    const p = hslToRgb(hue, 1, 0.5);
    const mean = (p[0] + p[1] + p[2]) / 3;
    chroma = [(p[0] - mean) * radius, (p[1] - mean) * radius, (p[2] - mean) * radius];
  }
  const luma = w[2] / GRADE_MAX;
  return [chroma[0] + luma, chroma[1] + luma, chroma[2] + luma];
}

function buildLayer(g: ColorGrade, space: GradeSpace, skinDamp: boolean): Layer | null {
  const s = (g.saturation || 0) / GRADE_MAX;
  const brightness = 1 + (g.brightness || 0) / 100;
  const layer: Layer = {
    desaturate: s < 0 ? 1 + s : 1,
    wb: whiteBalanceFor(g.temperature || 0, g.tint || 0, space.primaries),
    gain: Math.pow(2, ((g.exposure || 0) / GRADE_MAX) * EXPOSURE_STOPS_AT_MAX) * Math.pow(brightness, 2.4),
    contrast: 1 + ((g.contrast || 0) / GRADE_MAX) * CONTRAST_POWER_AT_MAX,
    highlights: (g.highlights || 0) / GRADE_MAX,
    shadows: (g.shadows || 0) / GRADE_MAX,
    whites: (g.whites || 0) / GRADE_MAX,
    blacks: (g.blacks || 0) / GRADE_MAX,
    brilliance: (g.brilliance || 0) / GRADE_MAX,
    masks: false,
    wheels: [],
    light: false,
    curves: null,
    hue: g.hue || 0,
    saturate: s > 0 ? 1 + s : 1,
    vibrance: (g.vibrance || 0) / GRADE_MAX,
    bands: [],
    color: false,
    fade: Math.max(0, g.fade || 0) / GRADE_MAX,
    skinDamp,
  };
  if (g.curves) {
    layer.curves = {};
    for (const ch of ["m", "r", "g", "b"] as const) {
      const pts = g.curves[ch];
      if (pts && pts.length >= 2) layer.curves[ch] = curveLut(pts);
    }
    if (!Object.keys(layer.curves).length) layer.curves = null;
  }
  if (g.wheels) {
    for (const zone of WHEEL_ZONES) {
      const w = g.wheels[zone];
      if (!w) continue;
      const amount = wheelAmount(w);
      if (amount) layer.wheels.push({ zone, amount });
    }
  }
  if (g.hsl) {
    HSL_BANDS.forEach((band, idx) => {
      const t = g.hsl?.[band.id];
      if (!t || (!t[0] && !t[1] && !t[2])) return;
      layer.bands.push({
        prev: HSL_BANDS[(idx + HSL_BANDS.length - 1) % HSL_BANDS.length].center,
        center: band.center,
        next: HSL_BANDS[(idx + 1) % HSL_BANDS.length].center,
        hueShift: (t[0] / GRADE_MAX) * 30,
        sat: t[1] / GRADE_MAX,
        lum: t[2] / GRADE_MAX,
      });
    });
  }
  layer.masks =
    layer.highlights !== 0 || layer.shadows !== 0 || layer.whites !== 0 || layer.blacks !== 0 || layer.brilliance !== 0;
  layer.light = layer.wb !== null || layer.gain !== 1 || layer.contrast !== 1 || layer.masks || layer.wheels.length > 0;
  layer.color = layer.hue !== 0 || layer.saturate !== 1 || layer.vibrance !== 0 || layer.bands.length > 0;
  const active = layer.desaturate !== 1 || layer.light || layer.curves !== null || layer.color || layer.fade !== 0;
  return active ? layer : null;
}

function bandWeight(h: number, b: Band): number {
  const span = (from: number, to: number) => (((to - from) % 360) + 360) % 360;
  const up = span(b.prev, b.center) || 360;
  const down = span(b.center, b.next) || 360;
  const fromPrev = span(b.prev, h);
  if (fromPrev <= up) return fromPrev / up;
  const fromC = span(b.center, h);
  if (fromC <= down) return 1 - fromC / down;
  return 0;
}

/** Scratch for the per-pixel work, module-level so a layer application
 * allocates nothing and the functions below stay monomorphic. */
const M2 = OKLAB_M2;
const M2I = OKLAB_M2_INV;
let R = 0;
let G = 0;
let B = 0;
/** Whether R, G, B currently hold linear light (true) or display values. */
let LIN = false;

function toLinear(space: GradeSpace): void {
  if (LIN) return;
  R = unshoulder(space.decode(clamp01(R)), space.white);
  G = unshoulder(space.decode(clamp01(G)), space.white);
  B = unshoulder(space.decode(clamp01(B)), space.white);
  LIN = true;
}

function toDisplay(space: GradeSpace): void {
  if (!LIN) return;
  R = space.encode(shoulder(R, space.white));
  G = space.encode(shoulder(G, space.white));
  B = space.encode(shoulder(B, space.white));
  LIN = false;
}

/** Chroma scale in Oklab on the linear scratch values, lightness kept. */
function scaleChroma(space: GradeSpace, k: number): void {
  const T = space.oklab.toLms;
  const F = space.oklab.fromLms;
  const l = Math.cbrt(T[0] * R + T[1] * G + T[2] * B);
  const m = Math.cbrt(T[3] * R + T[4] * G + T[5] * B);
  const s = Math.cbrt(T[6] * R + T[7] * G + T[8] * B);
  const Lk = M2[0] * l + M2[1] * m + M2[2] * s;
  const a = (M2[3] * l + M2[4] * m + M2[5] * s) * k;
  const bb = (M2[6] * l + M2[7] * m + M2[8] * s) * k;
  fromOklab(F, Lk, a, bb);
}

function fromOklab(F: Mat3, Lk: number, a: number, bb: number): void {
  const l2 = M2I[0] * Lk + M2I[1] * a + M2I[2] * bb;
  const m2 = M2I[3] * Lk + M2I[4] * a + M2I[5] * bb;
  const s2 = M2I[6] * Lk + M2I[7] * a + M2I[8] * bb;
  const l3 = l2 * l2 * l2;
  const m3 = m2 * m2 * m2;
  const s3 = s2 * s2 * s2;
  R = F[0] * l3 + F[1] * m3 + F[2] * s3;
  G = F[3] * l3 + F[4] * m3 + F[5] * s3;
  B = F[6] * l3 + F[7] * m3 + F[8] * s3;
}

/** One channel through the lift wheel: a raise adds light toward black, a
 * lowering scales toward black, so the channel never crosses zero. Both
 * fade out at white and leave the headroom above it alone. */
function lift(c: number, a: number): number {
  const toBlack = 1 - Math.min(1, Math.max(0, c));
  if (a >= 0) return c + WHEEL_LIFT * a * toBlack;
  return c * (1 + WHEEL_LIFT_DARKEN * a * toBlack);
}

function applyLayer(v: [number, number, number], L: Layer, space: GradeSpace, skinW: number): void {
  const damp = L.skinDamp ? skinW : 0;
  const pre0 = v[0];
  const pre1 = v[1];
  const pre2 = v[2];
  R = v[0];
  G = v[1];
  B = v[2];
  // The stages alternate between linear light and display values; a stage
  // only converts when the one before it left the other representation.
  LIN = false;

  if (L.desaturate !== 1) {
    toLinear(space);
    scaleChroma(space, L.desaturate);
  }

  // ---- light stage, in linear light ----
  if (L.light) {
    toLinear(space);
    if (L.wb) {
      const m = L.wb;
      const r2 = m[0] * R + m[1] * G + m[2] * B;
      const g2 = m[3] * R + m[4] * G + m[5] * B;
      const b2 = m[6] * R + m[7] * G + m[8] * B;
      R = r2;
      G = g2;
      B = b2;
    }
    if (L.gain !== 1) {
      R *= L.gain;
      G *= L.gain;
      B *= L.gain;
    }
    if (L.contrast !== 1) {
      const p = space.pivot;
      R = p * spow(R / p, L.contrast);
      G = p * spow(G / p, L.contrast);
      B = p * spow(B / p, L.contrast);
    }
    if (L.masks) {
      const y = space.luma[0] * R + space.luma[1] * G + space.luma[2] * B;
      // The masks read the tone as it will show: through the shoulder.
      const ys = shoulder(Math.max(0, y), space.white);
      const yl = clamp01(ys);
      const V = clamp01(space.encode(ys));
      const iv = 1 - V;
      let stops = 0;
      if (L.highlights) stops += L.highlights * HIGHLIGHTS_STOPS * V * V * iv;
      if (L.shadows) stops += L.shadows * SHADOWS_STOPS * iv * iv * V;
      if (L.whites) stops += L.whites * WHITES_STOPS * V * V * V * V;
      if (L.brilliance) stops += L.brilliance * BRILLIANCE_STOPS * (1 - 2 * V) * 4 * V * iv;
      if (L.blacks < 0) stops += L.blacks * BLACKS_DARKEN_STOPS * iv * iv * iv * iv;
      if (stops) {
        const k = Math.pow(2, stops);
        R *= k;
        G *= k;
        B *= k;
      }
      if (L.blacks > 0) {
        // The mask is on linear luminance: an offset masked on the encoded
        // value would rise faster than the signal near black and fold the
        // ramp over.
        const iy = 1 - yl;
        const off = L.blacks * L.blacks * BLACKS_OFFSET * iy * iy * iy;
        R += off;
        G += off;
        B += off;
      }
    }
    for (const w of L.wheels) {
      const a = w.amount;
      if (w.zone === "s") {
        R = lift(R, a[0]);
        G = lift(G, a[1]);
        B = lift(B, a[2]);
      } else if (w.zone === "m") {
        R = spow(R, 1 / (1 + WHEEL_GAMMA * a[0]));
        G = spow(G, 1 / (1 + WHEEL_GAMMA * a[1]));
        B = spow(B, 1 / (1 + WHEEL_GAMMA * a[2]));
      } else if (w.zone === "h") {
        R *= 1 + WHEEL_GAIN * a[0];
        G *= 1 + WHEEL_GAIN * a[1];
        B *= 1 + WHEEL_GAIN * a[2];
      } else {
        R *= Math.pow(2, WHEEL_OFFSET_STOPS * a[0]);
        G *= Math.pow(2, WHEEL_OFFSET_STOPS * a[1]);
        B *= Math.pow(2, WHEEL_OFFSET_STOPS * a[2]);
      }
    }
  }

  // ---- color stage, on display values ----
  if (L.curves) {
    toDisplay(space);
    if (L.curves.m) {
      R = sampleCurve(L.curves.m, R);
      G = sampleCurve(L.curves.m, G);
      B = sampleCurve(L.curves.m, B);
    }
    if (L.curves.r) R = sampleCurve(L.curves.r, R);
    if (L.curves.g) G = sampleCurve(L.curves.g, G);
    if (L.curves.b) B = sampleCurve(L.curves.b, B);
  }
  if (L.color) {
    let entryHue = 0;
    if (L.bands.length) {
      entryHue = LIN
        ? rgbToHsl(clamp01(space.encode(R)), clamp01(space.encode(G)), clamp01(space.encode(B)))[0]
        : rgbToHsl(clamp01(R), clamp01(G), clamp01(B))[0];
    }
    toLinear(space);
    const T = space.oklab.toLms;
    const l = Math.cbrt(T[0] * R + T[1] * G + T[2] * B);
    const m = Math.cbrt(T[3] * R + T[4] * G + T[5] * B);
    const s = Math.cbrt(T[6] * R + T[7] * G + T[8] * B);
    let Lk = M2[0] * l + M2[1] * m + M2[2] * s;
    const a0 = M2[3] * l + M2[4] * m + M2[5] * s;
    const b0 = M2[6] * l + M2[7] * m + M2[8] * s;
    let C = Math.hypot(a0, b0);
    let h = (Math.atan2(b0, a0) * 180) / Math.PI;
    if (L.hue) h += L.hue;
    if (L.saturate !== 1) C *= L.saturate;
    // Vibrance boosts muted colors most; 0.3 is about the chroma of a pure
    // display primary in Oklab, so a saturated color is left alone.
    if (L.vibrance) C *= 1 + L.vibrance * 0.8 * (1 - Math.min(1, C / 0.3));
    for (const band of L.bands) {
      const w = bandWeight(entryHue, band);
      if (w <= 0) continue;
      h += band.hueShift * w;
      C *= 1 + band.sat * w;
      Lk *= 1 + band.lum * 0.5 * w;
    }
    if (C < 0) C = 0;
    const rad = (h * Math.PI) / 180;
    fromOklab(space.oklab.fromLms, Lk, C * Math.cos(rad), C * Math.sin(rad));
  }
  if (L.fade) {
    toDisplay(space);
    const lift = L.fade * FADE_LIFT_AT_MAX;
    R = clamp01(R);
    G = clamp01(G);
    B = clamp01(B);
    R += lift * (1 - R) * (1 - R);
    G += lift * (1 - G) * (1 - G);
    B += lift * (1 - B) * (1 - B);
  }
  toDisplay(space);

  if (damp > 0) {
    // The protected color is the pixel's own, carried to wherever the layer's
    // tone landed: scaling by the luma ratio keeps hue and saturation exactly.
    const y0 = space.luma[0] * pre0 + space.luma[1] * pre1 + space.luma[2] * pre2;
    const y1 = space.luma[0] * R + space.luma[1] * G + space.luma[2] * B;
    const k = y0 > 1e-4 ? y1 / y0 : 1;
    R = R * (1 - damp) + pre0 * k * damp;
    G = G * (1 - damp) + pre1 * k * damp;
    B = B * (1 - damp) + pre2 * k * damp;
  }
  v[0] = R;
  v[1] = G;
  v[2] = B;
}

export type GradeTransform = (r: number, g: number, b: number) => [number, number, number];

/**
 * Compile a grade into the pure pixel transform on display values of the
 * given container, in [0,1] (values may leave the range between stages; the
 * pipeline clamps once at the end). Returns null for a neutral grade.
 */
export function createGradeTransform(
  g: ColorGrade | undefined | null,
  output: OutputSpace | GradeSpace = "sdr"
): GradeTransform | null {
  const n = normalizeGrade(g);
  if (!n) return null;
  const space = typeof output === "string" ? gradeSpaceFor(output) : output;
  // The manual adjustments balance the shot first, so the look lands on a
  // corrected picture the same way on every clip.
  const layers: Layer[] = [];
  const manual: ColorGrade = { ...n };
  delete manual.preset;
  delete manual.lut;
  delete manual.sharpen;
  delete manual.clarity;
  const manualLayer = buildLayer(manual, space, false);
  if (manualLayer) layers.push(manualLayer);
  const presetGrade = resolvePreset(n.preset);
  if (presetGrade) {
    const layer = buildLayer(presetGrade, space, !!n.preset?.skin);
    if (layer) layers.push(layer);
  }
  if (!layers.length) return null;
  const anySkin = layers.some((l) => l.skinDamp);
  return (r, g2, b) => {
    const v: [number, number, number] = [r, g2, b];
    let skinW = 0;
    if (anySkin) {
      const [h, s] = rgbToHsl(clamp01(r), clamp01(g2), clamp01(b));
      skinW = skinWeight(h, s);
    }
    for (const layer of layers) applyLayer(v, layer, space, skinW);
    return v;
  };
}

/* ------------------------------------------------------------------ */
/* Filmstrip approximation                                             */
/* ------------------------------------------------------------------ */

const fmt = (n: number) => (Math.round(n * 1000) / 1000).toFixed(3);

/**
 * A DOM-CSS approximation of the grade for tiny always-on surfaces on
 * Rec.709 sources (timeline filmstrips, preset tiles): exposure and the
 * luminance masks become a brightness gain, contrast a contrast(), the
 * saturation and vibrance a saturate(), hue a hue-rotate(), and white
 * balance a multiply tint from the CAT02 matrix's response to white. Curves,
 * wheels, hue bands, LUTs and the source conversion are left out by design —
 * the preview canvas and exports render them for real.
 */
export function gradeCssApprox(
  g: ColorGrade | undefined | null
): { filter: string; tint: string | null } {
  const n = normalizeGrade(g);
  if (!n) return { filter: "", tint: null };
  const presetGrade = resolvePreset(n.preset);
  const eff: Record<string, number> = {};
  for (const k of GRADE_LUT_SCALAR_KEYS) {
    const v = (presetGrade?.[k] || 0) + (n[k] || 0);
    if (v) eff[k] = v;
  }
  const u = (k: string) => (eff[k] || 0) / GRADE_MAX;
  // A linear gain shows on encoded values as its 1/2.4 power.
  const stops =
    u("exposure") * EXPOSURE_STOPS_AT_MAX +
    (u("shadows") + u("highlights") * 0.5 + u("whites") * 0.3 + u("blacks") * 0.3 + u("brilliance") * 0.2) * 0.35;
  const gain = Math.pow(2, stops / 2.4) * (1 + (eff.brightness || 0) / 100) * (1 + u("fade") * 0.08);
  const contrast = (1 + u("contrast") * CONTRAST_POWER_AT_MAX) * (1 - u("fade") * 0.2) * (1 - u("brilliance") * 0.1);
  const saturate = Math.max(0, 1 + u("saturation") + u("vibrance") * 0.5);
  const hue = eff.hue || 0;
  const parts: string[] = [];
  if (Math.abs(gain - 1) > 1e-3) parts.push(`brightness(${fmt(gain)})`);
  if (Math.abs(contrast - 1) > 1e-3) parts.push(`contrast(${fmt(contrast)})`);
  if (Math.abs(saturate - 1) > 1e-3) parts.push(`saturate(${fmt(saturate)})`);
  if (hue) parts.push(`hue-rotate(${fmt(hue)}deg)`);
  let tint: string | null = null;
  const wb = whiteBalanceFor(eff.temperature || 0, eff.tint || 0, REC709_PRIMARIES);
  if (wb) {
    // The matrix's response to white, normalized so the multiply pass only
    // ever dims a channel; the lost level rides the brightness term.
    const w = mat3Apply(wb, 1, 1, 1);
    const top = Math.max(w[0], w[1], w[2], 1e-6);
    const ch = (x: number) => Math.max(0, Math.min(255, Math.round(255 * bt1886Encode(Math.max(0, x / top)))));
    tint = `rgb(${ch(w[0])}, ${ch(w[1])}, ${ch(w[2])})`;
    const lift = bt1886Encode(top);
    if (Math.abs(lift - 1) > 1e-3) {
      const i = parts.findIndex((p) => p.startsWith("brightness("));
      const total = gain * lift;
      const term = `brightness(${fmt(total)})`;
      if (i >= 0) parts[i] = term;
      else parts.unshift(term);
    }
  }
  return { filter: parts.join(" "), tint };
}