Open source CapCut alternative.
TypeScript
feat(effects-kit): color-managed grade math, Apple Log, ACES output and LUT files [rebuild]
David Le91d7acb13daf
diff --git a/site/packages/effects-kit/src/acesOutput.test.ts b/site/packages/effects-kit/src/acesOutput.test.tsnew file mode 100644index 00000000..38f07097--- /dev/null+++ b/site/packages/effects-kit/src/acesOutput.test.ts@@ -0,0 +1,154 @@+import { describe, expect, test } from "bun:test";+import { ACES_OUTPUT_PRESETS, acesOutputTransform, acesOutputTransformFor } from "./acesOutput";+import { P3D65_PRIMARIES, hlgOetfInverse, hlgOotf, pqDecode } from "./colorSpace";++/**+ * The port is held against OpenColorIO's fixed-function test vectors for the+ * ACES 2.0 output transform (P3-D65 limiting, 1000 nits): six extreme+ * primaries, three arbitrary colors, the ColorChecker patches, 18% grey and+ * the tonescale's white. Values are scene-linear AP0 in, display-linear+ * P3-D65 out, before the peak clamp.+ */+const OCIO_IN: [number, number, number][] = [+ [2.781808965, 0.179178253, -0.02210353],+ [3.344523751, 3.617862727, -0.006002689],+ [0.562714786, 3.438684474, 0.016100841],+ [1.218191035, 3.820821747, 4.02210353],+ [0.655476249, 0.382137273, 4.006002689],+ [3.437285214, 0.561315526, 3.983899159],+ [0.11, 0.02, 0.04],+ [0.71, 0.51, 0.81],+ [0.43, 0.82, 0.71],+ [0.11877, 0.08709, 0.05895],+ [0.40002, 0.31916, 0.23736],+ [0.18476, 0.20398, 0.31311],+ [0.10901, 0.13511, 0.06493],+ [0.26684, 0.24604, 0.40932],+ [0.32283, 0.46208, 0.40606],+ [0.38605, 0.22743, 0.05777],+ [0.13822, 0.13037, 0.33703],+ [0.30202, 0.13752, 0.12758],+ [0.0931, 0.06347, 0.13525],+ [0.34876, 0.43654, 0.10613],+ [0.48655, 0.36685, 0.08061],+ [0.08732, 0.07443, 0.27274],+ [0.15366, 0.25692, 0.09071],+ [0.21742, 0.0707, 0.0513],+ [0.58919, 0.53943, 0.09157],+ [0.30904, 0.14818, 0.27426],+ [0.14901, 0.23378, 0.35939],+ [0.86653, 0.86792, 0.85818],+ [0.57356, 0.57256, 0.57169],+ [0.35346, 0.35337, 0.35391],+ [0.20253, 0.20243, 0.20287],+ [0.09467, 0.0952, 0.09637],+ [0.03745, 0.03766, 0.03895],+ [0.18, 0.18, 0.18],+ [0.97784, 0.97784, 0.97784],+];+const OCIO_OUT: [number, number, number][] = [+ [4.966013432, -0.033002287, 0.041583523],+ [3.969460726, 3.825797558, -0.056160748],+ [-0.075460039, 3.689072609, 0.270235062],+ [-0.095436633, 3.650521517, 3.459975719],+ [-0.028881177, 0.19647342, 2.796123743],+ [4.900828362, -0.064385533, 3.838270903],+ [0.096890487, -0.001135427, 0.018971475],+ [0.809613585, 0.479857147, 0.814239979],+ [0.107417941, 0.920530438, 0.726379037],+ [0.115475342, 0.050812997, 0.030212998],+ [0.484880149, 0.301042914, 0.22676903],+ [0.098463453, 0.160814837, 0.277010798],+ [0.071130276, 0.107334509, 0.035097614],+ [0.207111374, 0.198474824, 0.375326097],+ [0.195447117, 0.48111254, 0.393299103],+ [0.571913302, 0.196873263, 0.041634843],+ [0.045791976, 0.069875412, 0.291233569],+ [0.424848884, 0.083199054, 0.102153927],+ [0.059589352, 0.022219239, 0.091246955],+ [0.360364884, 0.478741497, 0.086726815],+ [0.695661962, 0.371994466, 0.068298057],+ [0.01180624, 0.021665439, 0.19959487],+ [0.076526135, 0.256237596, 0.060564563],+ [0.300064713, 0.023416281, 0.030360531],+ [0.805483222, 0.596904039, 0.082996234],+ [0.388385385, 0.079899333, 0.245818958],+ [0.010951802, 0.196106046, 0.307181537],+ [0.921020269, 0.92170763, 0.912857533],+ [0.590191603, 0.588424563, 0.587825298],+ [0.337743223, 0.337686002, 0.33815524],+ [0.169266403, 0.169178575, 0.169557154],+ [0.058346011, 0.059387885, 0.060296256],+ [0.012581199, 0.012947144, 0.013654212],+ [0.145115077, 0.145115703, 0.14511548],+ [1.041565537, 1.04156661, 1.041566253],+];++describe("reference vectors", () => {+ test("P3-D65 1000-nit matches OpenColorIO within 1e-4", () => {+ const ot = acesOutputTransformFor(1000, P3D65_PRIMARIES);+ let maxErr = 0;+ OCIO_IN.forEach((c, i) => {+ const out = ot.forwardLinear(c[0], c[1], c[2]);+ for (let k = 0; k < 3; k++) maxErr = Math.max(maxErr, Math.abs(out[k] - OCIO_OUT[i][k]));+ });+ expect(maxErr).toBeLessThan(1e-4);+ });+});++describe("Rec.709 100-nit", () => {+ const ot = acesOutputTransform("rec709-100");++ test("18% grey renders at 10 nits and black stays black", () => {+ const lin = ot.forwardLinear(0.18, 0.18, 0.18);+ // ACES 2.0 puts 18% grey at 10.013 nits on a 100-nit display.+ expect(Math.abs(lin[0] * 100 - 10.013)).toBeLessThan(0.02);+ expect(ot.forward(0, 0, 0)).toEqual([0, 0, 0]);+ });++ test("the neutral axis is monotone and neutral", () => {+ let prev = -1;+ for (let i = 0; i <= 200; i++) {+ const s = Math.pow(2, (i / 200) * 16 - 10);+ const [r, g, b] = ot.forward(s, s, s);+ expect(Math.abs(r - g)).toBeLessThan(1e-4);+ expect(Math.abs(g - b)).toBeLessThan(1e-4);+ expect(r).toBeGreaterThanOrEqual(prev - 1e-9);+ expect(r).toBeLessThanOrEqual(1);+ prev = r;+ }+ });++ test("a saturated primary stays inside the display gamut", () => {+ const out = ot.forward(1, 0.02, 0.02);+ for (const v of out) {+ expect(v).toBeGreaterThanOrEqual(0);+ expect(v).toBeLessThanOrEqual(1);+ }+ expect(out[0]).toBeGreaterThan(out[1]);+ });+});++describe("HDR presets", () => {+ test("HLG and PQ deliver the same luminance for 18% grey", () => {+ const hlg = acesOutputTransform("rec2100-hlg-1000").forward(0.18, 0.18, 0.18);+ const pq = acesOutputTransform("rec2100-pq-1000").forward(0.18, 0.18, 0.18);+ const pqNits = pqDecode(pq[0]);+ const s = hlgOetfInverse(hlg[0]);+ const hlgNits = hlgOotf(s, s, s, 1000)[0];+ expect(Math.abs(pqNits - hlgNits)).toBeLessThan(0.5);+ // The 1000-nit tonescale places 18% grey near 14.5 nits.+ expect(Math.abs(pqNits - 14.5)).toBeLessThan(0.5);+ });++ test("presets restate the reference transforms", () => {+ expect(ACES_OUTPUT_PRESETS["rec709-100"].peakLuminance).toBe(100);+ expect(ACES_OUTPUT_PRESETS["rec2100-hlg-1000"].eotf).toBe("hlg");+ expect(ACES_OUTPUT_PRESETS["rec2100-pq-1000"].eotf).toBe("pq");+ for (const p of Object.values(ACES_OUTPUT_PRESETS)) expect(p.transformId.startsWith("Output.Academy.")).toBe(true);+ });++ test("transforms are built once per preset", () => {+ expect(acesOutputTransform("rec709-100")).toBe(acesOutputTransform("rec709-100"));+ });+});diff --git a/site/packages/effects-kit/src/acesOutput.ts b/site/packages/effects-kit/src/acesOutput.tsnew file mode 100644index 00000000..67d6157c--- /dev/null+++ b/site/packages/effects-kit/src/acesOutput.ts@@ -0,0 +1,1250 @@+/**+ * ACES 2.0 Output Transform, ported from the Academy's reference CTL+ * (github.com/aces-aswf/aces-core, lib/Lib.Academy.OutputTransform.ctl,+ * Lib.Academy.Tonescale.ctl, Lib.Academy.DisplayEncoding.ctl, and the preset+ * files under github.com/aces-aswf/aces-output).+ *+ * SPDX-License-Identifier: Apache-2.0+ * Copyright Contributors to the ACES Project. Licensed under the Apache+ * License, Version 2.0; a copy is at http://www.apache.org/licenses/LICENSE-2.0.+ * This file is a derivative work of that reference, restated in TypeScript.+ *+ * The transform takes scene-linear ACES2065-1 (AP0) and produces display+ * code values: a Hellwig 2022 / CAM16 appearance model, the tonescale, chroma+ * compression, hue-dependent gamut compression, then the display's EOTF+ * inverse. The heavy work is in the tables built once per preset; the per-+ * pixel path is `forward`.+ *+ * The reference's matrix convention is row-vector (v · M); this port keeps+ * it for every matrix built here, so the two can be read side by side.+ */++import type { Primaries } from "./colorSpace";+import { AP0_PRIMARIES, AP1_PRIMARIES, P3D65_PRIMARIES, REC2020_PRIMARIES, REC709_PRIMARIES } from "./colorSpace";++type M33 = number[][];+type V3 = [number, number, number];++/* ------------------------------------------------------------------ */+/* Row-vector matrix helpers (as the CTL library) */+/* ------------------------------------------------------------------ */++function multF3F33(v: V3, m: M33): V3 {+ return [+ v[0] * m[0][0] + v[1] * m[1][0] + v[2] * m[2][0],+ v[0] * m[0][1] + v[1] * m[1][1] + v[2] * m[2][1],+ v[0] * m[0][2] + v[1] * m[1][2] + v[2] * m[2][2],+ ];+}++function multF33F33(a: M33, b: M33): M33 {+ const out: M33 = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];+ for (let i = 0; i < 3; i++)+ for (let j = 0; j < 3; j++) out[i][j] = a[i][0] * b[0][j] + a[i][1] * b[1][j] + a[i][2] * b[2][j];+ return out;+}++function multFF33(s: number, m: M33): M33 {+ return m.map((row) => row.map((v) => v * s));+}++function invertF33(m: M33): M33 {+ const [[a, b, c], [d, e, f], [g, h, i]] = m;+ const A = e * i - f * h;+ const B = -(d * i - f * g);+ const C = d * h - e * g;+ const det = a * A + b * B + c * C;+ const s = 1 / det;+ return [+ [A * s, -(b * i - c * h) * s, (b * f - c * e) * s],+ [B * s, (a * i - c * g) * s, -(a * f - c * d) * s],+ [C * s, -(a * h - b * g) * s, (a * e - b * d) * s],+ ];+}++/** RGBtoXYZ_f33 from the reference: rows are the primaries' XYZ, scaled so+ * white lands on Y. */+function rgbToXyzF33(c: Primaries, Y: number): M33 {+ const X = (c.w[0] * Y) / c.w[1];+ const Z = ((1 - c.w[0] - c.w[1]) * Y) / c.w[1];+ const d =+ c.r[0] * (c.b[1] - c.g[1]) + c.b[0] * (c.g[1] - c.r[1]) + c.g[0] * (c.r[1] - c.b[1]);+ const Sr =+ (X * (c.b[1] - c.g[1]) -+ c.g[0] * (Y * (c.b[1] - 1) + c.b[1] * (X + Z)) ++ c.b[0] * (Y * (c.g[1] - 1) + c.g[1] * (X + Z))) /+ d;+ const Sg =+ (X * (c.r[1] - c.b[1]) ++ c.r[0] * (Y * (c.b[1] - 1) + c.b[1] * (X + Z)) -+ c.b[0] * (Y * (c.r[1] - 1) + c.r[1] * (X + Z))) /+ d;+ const Sb =+ (X * (c.g[1] - c.r[1]) -+ c.r[0] * (Y * (c.g[1] - 1) + c.g[1] * (X + Z)) ++ c.g[0] * (Y * (c.r[1] - 1) + c.r[1] * (X + Z))) /+ d;+ return [+ [Sr * c.r[0], Sr * c.r[1], Sr * (1 - c.r[0] - c.r[1])],+ [Sg * c.g[0], Sg * c.g[1], Sg * (1 - c.g[0] - c.g[1])],+ [Sb * c.b[0], Sb * c.b[1], Sb * (1 - c.b[0] - c.b[1])],+ ];+}++function xyzToRgbF33(c: Primaries, Y: number): M33 {+ return invertF33(rgbToXyzF33(c, Y));+}++const AP0_XYZ_TO_RGB = xyzToRgbF33(AP0_PRIMARIES, 1);+const AP0_RGB_TO_XYZ = rgbToXyzF33(AP0_PRIMARIES, 1);+const AP1_XYZ_TO_RGB = xyzToRgbF33(AP1_PRIMARIES, 1);+const AP1_RGB_TO_XYZ = rgbToXyzF33(AP1_PRIMARIES, 1);+const AP0_TO_AP1 = multF33F33(AP0_RGB_TO_XYZ, AP1_XYZ_TO_RGB);+const AP1_TO_AP0 = multF33F33(AP1_RGB_TO_XYZ, AP0_XYZ_TO_RGB);++/* ------------------------------------------------------------------ */+/* Constants */+/* ------------------------------------------------------------------ */++const REACH_PRI = AP1_PRIMARIES;++const tableSize = 360;+const additionalTableEntries = 2;+const totalTableSize = tableSize + additionalTableEntries;+const baseIndex = 1;+const hue_limit = 360;++const cuspCornerCount = 6;+const totalCornerCount = cuspCornerCount + 2;+const max_sorted_corners = 2 * cuspCornerCount;+const reach_cusp_tolerance = 1e-3;+const display_cusp_tolerance = 1e-7;++const gamma_minimum = 0;+const gamma_maximum = 5;+const gamma_search_step = 0.4;+const gamma_accuracy = 1e-5;++const ref_luminance = 100;+const L_A = 100;+const Y_b = 20;+const surround = [0.9, 0.59, 0.9];++const J_scale = 100;+const cam_nl_Y_reference = 100;+const cam_nl_offset = 0.2713 * cam_nl_Y_reference;+const cam_nl_scale = 4 * cam_nl_Y_reference;++const model_gamma = surround[1] * (1.48 + Math.sqrt(Y_b / ref_luminance));++const chroma_compress = 2.4;+const chroma_compress_fact = 3.3;+const chroma_expand = 1.3;+const chroma_expand_fact = 0.69;+const chroma_expand_thr = 0.5;++const smooth_cusps = 0.12;+const smooth_m = 0.27;+const cusp_mid_blend = 1.3;++const focus_gain_blend = 0.3;+const focus_adjust_gain = 0.55;+const focus_distance = 1.35;+const focus_distance_scaling = 1.75;++const compression_threshold = 0.75;++const MATRIX_IDENTITY: M33 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];++void focus_adjust_gain;++/* ------------------------------------------------------------------ */+/* Tonescale (Lib.Academy.Tonescale) */+/* ------------------------------------------------------------------ */++interface TSParams {+ n: number;+ n_r: number;+ g: number;+ t_1: number;+ c_t: number;+ s_2: number;+ u_2: number;+ m_2: number;+ forward_limit: number;+ inverse_limit: number;+ log_peak: number;+}++function initTSParams(peakLuminance: number): TSParams {+ const n = peakLuminance;+ const n_r = 100;+ const g = 1.15;+ const c = 0.18;+ const c_d = 10.013;+ const w_g = 0.14;+ const t_1 = 0.04;+ const r_hit_min = 128;+ const r_hit_max = 896;++ const r_hit = r_hit_min + ((r_hit_max - r_hit_min) * Math.log(n / n_r)) / Math.log(10000 / 100);+ const m_0 = n / n_r;+ const m_1 = 0.5 * (m_0 + Math.sqrt(m_0 * (m_0 + 4 * t_1)));+ const u = Math.pow(r_hit / m_1 / (r_hit / m_1 + 1), g);+ const m = m_1 / u;+ const w_i = Math.log(n / 100) / Math.log(2);+ const c_t = (c_d / n_r) * (1 + w_i * w_g);+ const g_ip = 0.5 * (c_t + Math.sqrt(c_t * (c_t + 4 * t_1)));+ const g_ipp2 = -(m_1 * Math.pow(g_ip / m, 1 / g)) / (Math.pow(g_ip / m, 1 / g) - 1);+ const w_2 = c / g_ipp2;+ const s_2 = w_2 * m_1;+ const u_2 = Math.pow(r_hit / m_1 / (r_hit / m_1 + w_2), g);+ const m_2 = m_1 / u_2;++ return {+ n,+ n_r,+ g,+ t_1,+ c_t,+ s_2,+ u_2,+ m_2,+ forward_limit: 8 * r_hit,+ inverse_limit: n / (u_2 * n_r),+ log_peak: Math.log10(n / n_r),+ };+}++function tonescaleFwd(x: number, p: TSParams): number {+ const f = p.m_2 * Math.pow(Math.max(0, x) / (x + p.s_2), p.g);+ const h = Math.max(0, (f * f) / (f + p.t_1));+ return h * p.n_r;+}++/* ------------------------------------------------------------------ */+/* CAM */+/* ------------------------------------------------------------------ */++interface JMhParams {+ MATRIX_RGB_to_CAM16_c: M33;+ MATRIX_CAM16_c_to_RGB: M33;+ MATRIX_cone_response_to_Aab: M33;+ MATRIX_Aab_to_cone_response: M33;+ F_L_n: number;+ cz: number;+ inv_cz: number;+ A_w_J: number;+ inv_A_w_J: number;+}++function compressionFwdAbs(Rc: number): number {+ const F_L_Y = Math.pow(Rc, 0.42);+ return F_L_Y / (cam_nl_offset + F_L_Y);+}++function compressionInvAbs(Ra: number): number {+ const Ra_lim = Math.min(Ra, 0.99);+ const F_L_Y = (cam_nl_offset * Ra_lim) / (1 - Ra_lim);+ return Math.pow(F_L_Y, 1 / 0.42);+}++function compressionFwd(v: number): number {+ const r = compressionFwdAbs(Math.abs(v));+ return v < 0 ? -r : r;+}++function compressionInv(v: number): number {+ const r = compressionInvAbs(Math.abs(v));+ return v < 0 ? -r : r;+}++function achromaticToJ(A: number, cz: number): number {+ return J_scale * Math.pow(A, cz);+}++function jToAchromatic(J: number, inv_cz: number): number {+ return Math.pow(J * (1 / J_scale), inv_cz);+}++function aToY(A: number, p: JMhParams): number {+ const Ra = p.A_w_J * A;+ return compressionInvAbs(Ra) / p.F_L_n;+}++function jToY(J: number, p: JMhParams): number {+ return aToY(jToAchromatic(Math.abs(J), p.inv_cz), p);+}++function yToJ(Y: number, p: JMhParams): number {+ const Ra = compressionFwdAbs(Math.abs(Y) * p.F_L_n);+ const J = achromaticToJ(Ra * p.inv_A_w_J, p.cz);+ return Y < 0 ? -J : J;+}++function wrapTo360(hue: number): number {+ let y = hue % 360;+ if (y < 0) y += 360;+ return y;+}++function rgbToAab(RGB: V3, p: JMhParams): V3 {+ const rgb_m = multF3F33(RGB, p.MATRIX_RGB_to_CAM16_c);+ const rgb_a: V3 = [compressionFwd(rgb_m[0]), compressionFwd(rgb_m[1]), compressionFwd(rgb_m[2])];+ return multF3F33(rgb_a, p.MATRIX_cone_response_to_Aab);+}++function aabToJMh(Aab: V3, p: JMhParams): V3 {+ if (Aab[0] <= 0) return [0, 0, 0];+ const J = achromaticToJ(Aab[0], p.cz);+ const M = Math.sqrt(Aab[1] * Aab[1] + Aab[2] * Aab[2]);+ const h = wrapTo360((Math.atan2(Aab[2], Aab[1]) * 180) / Math.PI);+ return [J, M, h];+}++function rgbToJMh(RGB: V3, p: JMhParams): V3 {+ return aabToJMh(rgbToAab(RGB, p), p);+}++function jmhToRgb(JMh: V3, p: JMhParams): V3 {+ const h_rad = (JMh[2] * Math.PI) / 180;+ const A = jToAchromatic(JMh[0], p.inv_cz);+ const Aab: V3 = [A, JMh[1] * Math.cos(h_rad), JMh[1] * Math.sin(h_rad)];+ const rgb_a = multF3F33(Aab, p.MATRIX_Aab_to_cone_response);+ const rgb_m: V3 = [compressionInv(rgb_a[0]), compressionInv(rgb_a[1]), compressionInv(rgb_a[2])];+ return multF3F33(rgb_m, p.MATRIX_CAM16_c_to_RGB);+}++function initJMhParams(prims: Primaries): JMhParams {+ const CAM16_PRI: Primaries = { r: [0.8336, 0.1735], g: [2.3854, -1.4659], b: [0.087, -0.125], w: [0.333, 0.333] };+ const MATRIX_16 = xyzToRgbF33(CAM16_PRI, 1);+ const base_cone_response_to_Aab: M33 = [+ [2, 1, 1 / 9],+ [1, -12 / 11, 1 / 9],+ [1 / 20, 1 / 11, -2 / 9],+ ];+ const RGB_TO_XYZ = rgbToXyzF33(prims, 1);+ const XYZ_w = multF3F33([ref_luminance, ref_luminance, ref_luminance], RGB_TO_XYZ);+ const Y_w = XYZ_w[1];+ const RGB_w = multF3F33(XYZ_w, MATRIX_16);++ const k = 1 / (5 * L_A + 1);+ const k4 = k * k * k * k;+ const F_L = 0.2 * k4 * (5 * L_A) + 0.1 * Math.pow(1 - k4, 2) * Math.pow(5 * L_A, 1 / 3);+ const F_L_n = F_L / ref_luminance;+ const cz = model_gamma;++ const D_RGB: V3 = [(F_L_n * Y_w) / RGB_w[0], (F_L_n * Y_w) / RGB_w[1], (F_L_n * Y_w) / RGB_w[2]];+ const RGB_wc: V3 = [D_RGB[0] * RGB_w[0], D_RGB[1] * RGB_w[1], D_RGB[2] * RGB_w[2]];+ const RGB_Aw: V3 = [compressionFwd(RGB_wc[0]), compressionFwd(RGB_wc[1]), compressionFwd(RGB_wc[2])];++ const cone_response_to_Aab = multF33F33(multFF33(cam_nl_scale, MATRIX_IDENTITY), base_cone_response_to_Aab);+ const A_w =+ cone_response_to_Aab[0][0] * RGB_Aw[0] + cone_response_to_Aab[1][0] * RGB_Aw[1] + cone_response_to_Aab[2][0] * RGB_Aw[2];+ const A_w_J = compressionFwdAbs(F_L);++ const M1 = multF33F33(RGB_TO_XYZ, MATRIX_16);+ const M2 = multFF33(ref_luminance, MATRIX_IDENTITY);+ const MATRIX_RGB_to_CAM16 = multF33F33(M1, M2);+ const diagD: M33 = [[D_RGB[0], 0, 0], [0, D_RGB[1], 0], [0, 0, D_RGB[2]]];+ const MATRIX_RGB_to_CAM16_c = multF33F33(MATRIX_RGB_to_CAM16, diagD);++ const s = 43 * surround[2];+ const MATRIX_cone_response_to_Aab: M33 = [+ [cone_response_to_Aab[0][0] / A_w, cone_response_to_Aab[0][1] * s, cone_response_to_Aab[0][2] * s],+ [cone_response_to_Aab[1][0] / A_w, cone_response_to_Aab[1][1] * s, cone_response_to_Aab[1][2] * s],+ [cone_response_to_Aab[2][0] / A_w, cone_response_to_Aab[2][1] * s, cone_response_to_Aab[2][2] * s],+ ];++ return {+ MATRIX_RGB_to_CAM16_c,+ MATRIX_CAM16_c_to_RGB: invertF33(MATRIX_RGB_to_CAM16_c),+ MATRIX_cone_response_to_Aab,+ MATRIX_Aab_to_cone_response: invertF33(MATRIX_cone_response_to_Aab),+ F_L_n,+ cz,+ inv_cz: 1 / cz,+ A_w_J,+ inv_A_w_J: 1 / A_w_J,+ };+}++/* ------------------------------------------------------------------ */+/* ODT parameters and tables */+/* ------------------------------------------------------------------ */++interface ODTParams {+ peakLuminance: number;+ input_params: JMhParams;+ reach_params: JMhParams;+ limit_params: JMhParams;+ ts: TSParams;+ limit_J_max: number;+ model_gamma_inv: number;+ TABLE_reach_M: Float64Array;+ sat: number;+ sat_thr: number;+ compr: number;+ chroma_compress_scale: number;+ mid_J: number;+ focus_dist: number;+ lower_hull_gamma_inv: number;+ TABLE_hues: Float64Array;+ TABLE_gamut_cusps: number[][];+ TABLE_upper_hull_gamma: Float64Array;+ hue_linearity_search_range: [number, number];+}++function huePositionInUniformTable(hue: number, table_size: number): number {+ return Math.floor((wrapTo360(hue) / hue_limit) * table_size);+}++function nextPositionInTable(entry: number, table_size: number): number {+ return (entry + 1) % table_size;+}++function baseHueForPosition(i_lo: number, table_size: number): number {+ return (i_lo * hue_limit) / table_size;+}++const lerp = (a: number, b: number, t: number) => a + t * (b - a);++/** The reference's round(): halves away from zero, then truncate. */+function ctlRound(x: number): number {+ return x < 0 ? Math.trunc(x - 0.5) : Math.trunc(x + 0.5);+}++function reachMFromTable(h: number, table: Float64Array): number {+ const base = huePositionInUniformTable(h, tableSize);+ const t = h - base;+ const i_lo = base + baseIndex;+ return lerp(table[i_lo], table[i_lo + 1], t);+}++function reinhardRemap(scale: number, nd: number): number {+ return (scale * nd) / (1 + nd);+}++function toe(x: number, limit: number, k1_in: number, k2_in: number): number {+ if (x > limit) return x;+ const k2 = Math.max(k2_in, 0.001);+ const k1 = Math.sqrt(k1_in * k1_in + k2 * k2);+ const k3 = (limit + k1) / (limit + k2);+ const minus_b = k3 * x - k1;+ const minus_c = k2 * k3 * x;+ return 0.5 * (minus_b + Math.sqrt(minus_b * minus_b + 4 * minus_c));+}++function chromaCompressNorm(h: number, chroma_compress_scale: number): number {+ const hr = (h * Math.PI) / 180;+ const a = Math.cos(hr);+ const b = Math.sin(hr);+ const cos_hr2 = a * a - b * b;+ const sin_hr2 = 2 * a * b;+ const cos_hr3 = 4 * a * a * a - 3 * a;+ const sin_hr3 = 3 * b - 4 * b * b * b;+ const M =+ 11.34072 * a ++ 16.46899 * cos_hr2 ++ 7.8838 * cos_hr3 ++ 14.66441 * b ++ -6.37224 * sin_hr2 ++ 9.19364 * sin_hr3 ++ 77.12896;+ return M * chroma_compress_scale;+}++function chromaCompressFwd(JMh: V3, tonemapped_J: number, p: ODTParams): V3 {+ const J = JMh[0];+ const M = JMh[1];+ const h = JMh[2];+ let M_compr = M;+ if (M !== 0) {+ const nJ = tonemapped_J / p.limit_J_max;+ const snJ = Math.max(0, 1 - nJ);+ const Mnorm = chromaCompressNorm(h, p.chroma_compress_scale);+ const limit = (Math.pow(nJ, p.model_gamma_inv) * reachMFromTable(h, p.TABLE_reach_M)) / Mnorm;+ const toe_limit = limit - 0.001;+ const toe_snJ_sat = snJ * p.sat;+ const toe_sqrt_nJ_sat_thr = Math.sqrt(nJ * nJ + p.sat_thr);+ const toe_nJ_compr = nJ * p.compr;+ M_compr = M * Math.pow(tonemapped_J / J, p.model_gamma_inv);+ M_compr = M_compr / Mnorm;+ M_compr = limit - toe(limit - M_compr, toe_limit, toe_snJ_sat, toe_sqrt_nJ_sat_thr);+ M_compr = toe(M_compr, limit, toe_nJ_compr, snJ);+ M_compr = M_compr * Mnorm;+ }+ return [tonemapped_J, M_compr, h];+}++function tonemapAndCompressFwd(JMh: V3, p: ODTParams): V3 {+ const linear = jToY(JMh[0], p.input_params) / ref_luminance;+ const tonemapped_Y = tonescaleFwd(linear, p.ts);+ const J_ts = yToJ(tonemapped_Y, p.input_params);+ return chromaCompressFwd(JMh, J_ts, p);+}++function computeCompressionVectorSlope(intersect_J: number, focus_J: number, limit_J_max: number, slope_gain: number): number {+ const direction_scalar = intersect_J < focus_J ? intersect_J : limit_J_max - intersect_J;+ return (direction_scalar * (intersect_J - focus_J)) / (focus_J * slope_gain);+}++function solveJIntersect(J: number, M: number, focusJ: number, maxJ: number, slope_gain: number): number {+ const M_scaled = M / slope_gain;+ const a = M_scaled / focusJ;+ if (J < focusJ) {+ const b = 1 - M_scaled;+ const c = -J;+ const det = b * b - 4 * a * c;+ const root = Math.sqrt(det);+ return (-2 * c) / (b + root);+ }+ const b = -(1 + M_scaled + maxJ * a);+ const c = maxJ * M_scaled + J;+ const det = b * b - 4 * a * c;+ const root = Math.sqrt(det);+ return (-2 * c) / (b - root);+}++function sminScaled(a: number, b: number, scale_reference: number): number {+ const s_scaled = smooth_cusps * scale_reference;+ const h = Math.max(s_scaled - Math.abs(a - b), 0) / s_scaled;+ return Math.min(a, b) - h * h * h * s_scaled * (1 / 6);+}++function estimateLineAndBoundaryIntersectionM(+ J_axis_intersect: number,+ slope: number,+ inv_gamma: number,+ J_max: number,+ M_max: number,+ J_intersection_reference: number+): number {+ const normalised_J = J_axis_intersect / J_intersection_reference;+ const shifted_intersection = J_intersection_reference * Math.pow(normalised_J, inv_gamma);+ return (shifted_intersection * M_max) / (J_max - slope * M_max);+}++function findGamutBoundaryIntersection(+ JM_cusp: [number, number],+ J_max: number,+ gamma_top_inv: number,+ gamma_bottom_inv: number,+ J_intersect_source: number,+ slope: number,+ J_intersect_cusp: number+): number {+ const M_boundary_lower = estimateLineAndBoundaryIntersectionM(+ J_intersect_source,+ slope,+ gamma_bottom_inv,+ JM_cusp[0],+ JM_cusp[1],+ J_intersect_cusp+ );+ const f_J_intersect_cusp = J_max - J_intersect_cusp;+ const f_J_intersect_source = J_max - J_intersect_source;+ const f_JM_cusp_J = J_max - JM_cusp[0];+ const M_boundary_upper = estimateLineAndBoundaryIntersectionM(+ f_J_intersect_source,+ -slope,+ gamma_top_inv,+ f_JM_cusp_J,+ JM_cusp[1],+ f_J_intersect_cusp+ );+ return sminScaled(M_boundary_lower, M_boundary_upper, JM_cusp[1]);+}++function getFocusGain(J: number, analytical_threshold: number, limit_J_max: number, focus_dist: number): number {+ let gain = limit_J_max * focus_dist;+ if (J > analytical_threshold) {+ let gain_adjustment = Math.log10((limit_J_max - analytical_threshold) / Math.max(0.0001, limit_J_max - J));+ gain_adjustment = gain_adjustment * gain_adjustment + 1;+ gain = gain * gain_adjustment;+ }+ return gain;+}++function remapM(M: number, gamut_boundary_M: number, reach_boundary_M: number): number {+ const boundary_ratio = gamut_boundary_M / reach_boundary_M;+ const proportion = Math.max(boundary_ratio, compression_threshold);+ const threshold = proportion * gamut_boundary_M;+ if (M <= threshold || proportion >= 1) return M;+ const m_offset = M - threshold;+ const gamut_offset = gamut_boundary_M - threshold;+ const reach_offset = reach_boundary_M - threshold;+ const scale = reach_offset / (reach_offset / gamut_offset - 1);+ const nd = m_offset / scale;+ return threshold + reinhardRemap(scale, nd);+}++interface HueDependentGamutParams {+ JMcusp: [number, number];+ gamma_bottom_inv: number;+ gamma_top_inv: number;+ focus_J: number;+ analytical_threshold: number;+}++function compressGamut(JMh: V3, Jx: number, p: ODTParams, hdp: HueDependentGamutParams): V3 {+ const J = JMh[0];+ const M = JMh[1];+ const h = JMh[2];+ const slope_gain = getFocusGain(Jx, hdp.analytical_threshold, p.limit_J_max, p.focus_dist);+ const J_intersect_source = solveJIntersect(J, M, hdp.focus_J, p.limit_J_max, slope_gain);+ const gamut_slope = computeCompressionVectorSlope(J_intersect_source, hdp.focus_J, p.limit_J_max, slope_gain);+ const J_intersect_cusp = solveJIntersect(hdp.JMcusp[0], hdp.JMcusp[1], hdp.focus_J, p.limit_J_max, slope_gain);+ const gamut_boundary_M = findGamutBoundaryIntersection(+ hdp.JMcusp,+ p.limit_J_max,+ hdp.gamma_top_inv,+ hdp.gamma_bottom_inv,+ J_intersect_source,+ gamut_slope,+ J_intersect_cusp+ );+ if (gamut_boundary_M <= 0) return [J, 0, h];+ const reach_max_M = reachMFromTable(h, p.TABLE_reach_M);+ const reach_boundary_M = estimateLineAndBoundaryIntersectionM(+ J_intersect_source,+ gamut_slope,+ p.model_gamma_inv,+ p.limit_J_max,+ reach_max_M,+ p.limit_J_max+ );+ const remapped_M = remapM(M, gamut_boundary_M, reach_boundary_M);+ return [J_intersect_source + remapped_M * gamut_slope, remapped_M, h];+}++function cuspFromTable(h: number, table: number[][]): [number, number] {+ let low_i = 0;+ let high_i = baseIndex + tableSize;+ let i = huePositionInUniformTable(h, tableSize) + baseIndex;+ while (low_i + 1 < high_i) {+ if (h > table[i][2]) low_i = i;+ else high_i = i;+ i = Math.trunc((low_i + high_i) / 2);+ }+ const lo = table[high_i - 1];+ const hi = table[high_i];+ const t = (h - lo[2]) / (hi[2] - lo[2]);+ return [lerp(lo[0], hi[0], t), lerp(lo[1], hi[1], t)];+}++function lookupHueInterval(h: number, hue_table: Float64Array, range: [number, number]): number {+ let i = baseIndex + huePositionInUniformTable(h, totalTableSize);+ let i_lo = Math.max(baseIndex, i + range[0]);+ let i_hi = Math.min(baseIndex + tableSize, i + range[1]);+ while (i_lo + 1 < i_hi) {+ if (h > hue_table[i]) i_lo = i;+ else i_hi = i;+ i = Math.trunc((i_lo + i_hi) / 2);+ }+ return Math.max(1, i_hi);+}++function computeFocusJ(cusp_J: number, mid_J: number, limit_J_max: number): number {+ return lerp(cusp_J, mid_J, Math.min(1, cusp_mid_blend - cusp_J / limit_J_max));+}++function initHueDependentGamutParams(hue: number, p: ODTParams): HueDependentGamutParams {+ const i_hi = lookupHueInterval(hue, p.TABLE_hues, p.hue_linearity_search_range);+ const t = hue - p.TABLE_hues[i_hi - 1];+ const JMcusp = cuspFromTable(hue, p.TABLE_gamut_cusps);+ return {+ JMcusp,+ gamma_bottom_inv: p.lower_hull_gamma_inv,+ gamma_top_inv: lerp(p.TABLE_upper_hull_gamma[i_hi - 1], p.TABLE_upper_hull_gamma[i_hi], t),+ focus_J: computeFocusJ(JMcusp[0], p.mid_J, p.limit_J_max),+ analytical_threshold: lerp(JMcusp[0], p.limit_J_max, focus_gain_blend),+ };+}++function gamutCompressFwd(JMh: V3, p: ODTParams): V3 {+ const J = JMh[0];+ const M = JMh[1];+ const h = JMh[2];+ if (J <= 0) return [0, 0, h];+ if (M < 0 || J > p.limit_J_max) return [J, 0, h];+ const hdp = initHueDependentGamutParams(h, p);+ return compressGamut(JMh, J, p, hdp);+}++/* — table building — */++function anyBelowZero(rgb: V3): boolean {+ return rgb[0] < 0 || rgb[1] < 0 || rgb[2] < 0;+}++function generateUnitCubeCuspCorners(corner: number): V3 {+ return [+ (corner + 1) % cuspCornerCount < 3 ? 1 : 0,+ (corner + 5) % cuspCornerCount < 3 ? 1 : 0,+ (corner + 3) % cuspCornerCount < 3 ? 1 : 0,+ ];+}++function buildLimitingCuspCornersTables(+ params: JMhParams,+ peakLuminance: number+): { RGB_corners: V3[]; JMh_corners: V3[] } {+ const temp_RGB: V3[] = [];+ const temp_JMh: V3[] = [];+ let min_index = 0;+ for (let i = 0; i < cuspCornerCount; i++) {+ const c = generateUnitCubeCuspCorners(i);+ const k = peakLuminance / ref_luminance;+ temp_RGB[i] = [c[0] * k, c[1] * k, c[2] * k];+ temp_JMh[i] = rgbToJMh(temp_RGB[i], params);+ if (temp_JMh[i][2] < temp_JMh[min_index][2]) min_index = i;+ }+ const RGB_corners: V3[] = new Array(totalCornerCount);+ const JMh_corners: V3[] = new Array(totalCornerCount);+ for (let i = 0; i < cuspCornerCount; i++) {+ RGB_corners[i + 1] = temp_RGB[(i + min_index) % cuspCornerCount];+ JMh_corners[i + 1] = [...temp_JMh[(i + min_index) % cuspCornerCount]] as V3;+ }+ RGB_corners[0] = RGB_corners[cuspCornerCount];+ RGB_corners[cuspCornerCount + 1] = RGB_corners[1];+ JMh_corners[0] = [...JMh_corners[cuspCornerCount]] as V3;+ JMh_corners[cuspCornerCount + 1] = [...JMh_corners[1]] as V3;+ JMh_corners[0][2] -= hue_limit;+ JMh_corners[cuspCornerCount + 1][2] += hue_limit;+ return { RGB_corners, JMh_corners };+}++function findReachCornersTable(params_reach: JMhParams, limit_J_max: number, forward_limit: number): V3[] {+ const temp_JMh: V3[] = [];+ const limitA = jToAchromatic(limit_J_max, params_reach.inv_cz);+ let min_index = 0;+ for (let i = 0; i < cuspCornerCount; i++) {+ const rgb_vector = generateUnitCubeCuspCorners(i);+ let lower = 0;+ let upper = forward_limit;+ while (upper - lower > reach_cusp_tolerance) {+ const test = (lower + upper) / 2;+ const A = rgbToAab([test * rgb_vector[0], test * rgb_vector[1], test * rgb_vector[2]], params_reach)[0];+ if (A < limitA) lower = test;+ else upper = test;+ }+ temp_JMh[i] = rgbToJMh([upper * rgb_vector[0], upper * rgb_vector[1], upper * rgb_vector[2]], params_reach);+ if (temp_JMh[i][2] < temp_JMh[min_index][2]) min_index = i;+ }+ const JMh_corners: V3[] = new Array(totalCornerCount);+ for (let i = 0; i < cuspCornerCount; i++) {+ JMh_corners[i + 1] = [...temp_JMh[(i + min_index) % cuspCornerCount]] as V3;+ }+ JMh_corners[0] = [...JMh_corners[cuspCornerCount]] as V3;+ JMh_corners[cuspCornerCount + 1] = [...JMh_corners[1]] as V3;+ JMh_corners[0][2] -= hue_limit;+ JMh_corners[cuspCornerCount + 1][2] += hue_limit;+ return JMh_corners;+}++function extractSortedCubeHues(reach_JMh: V3[], limit_JMh: V3[]): number[] {+ const sorted_hues = new Array<number>(max_sorted_corners).fill(0);+ let idx = 0;+ let reach_idx = 1;+ let limit_idx = 1;+ while (reach_idx < cuspCornerCount + 1 || limit_idx < cuspCornerCount + 1) {+ const reach_hue = reach_JMh[reach_idx][2];+ const limit_hue = limit_JMh[limit_idx][2];+ if (reach_hue === limit_hue) {+ sorted_hues[idx] = reach_hue;+ reach_idx++;+ limit_idx++;+ } else if (reach_hue < limit_hue) {+ sorted_hues[idx] = reach_hue;+ reach_idx++;+ } else {+ sorted_hues[idx] = limit_hue;+ limit_idx++;+ }+ idx++;+ }+ return sorted_hues;+}++function buildHueSampleInterval(samples: number, lower: number, upper: number, hue_table: Float64Array, base: number): void {+ const delta = (upper - lower) / samples;+ for (let i = 0; i < samples; i++) hue_table[base + i] = lower + i * delta;+}++function buildHueTable(sorted_hues: number[]): Float64Array {+ const hue_table = new Float64Array(totalTableSize);+ const ideal_spacing = tableSize / hue_limit;+ const samples_count = new Array<number>(2 * cuspCornerCount + 2).fill(0);+ let last_idx = 0;+ let min_index = sorted_hues[0] === 0 ? 0 : 1;+ for (let hue_idx = 0; hue_idx < max_sorted_corners; hue_idx++) {+ let nominal_idx = Math.min(Math.max(ctlRound(sorted_hues[hue_idx] * ideal_spacing), min_index), tableSize - 1);+ if (last_idx === nominal_idx) {+ if (hue_idx > 1 && samples_count[hue_idx - 2] !== samples_count[hue_idx - 1] - 1) {+ samples_count[hue_idx - 1] = samples_count[hue_idx - 1] - 1;+ } else {+ nominal_idx = nominal_idx + 1;+ }+ }+ samples_count[hue_idx] = Math.min(nominal_idx, tableSize - 1);+ min_index = nominal_idx;+ last_idx = min_index;+ }+ let total_samples = 0;+ let i = 0;+ buildHueSampleInterval(samples_count[i], 0, sorted_hues[i], hue_table, total_samples + 1);+ total_samples += samples_count[i];+ for (i = i + 1; i < max_sorted_corners; i++) {+ const samples = samples_count[i] - samples_count[i - 1];+ buildHueSampleInterval(samples, sorted_hues[i - 1], sorted_hues[i], hue_table, total_samples + 1);+ total_samples += samples;+ }+ buildHueSampleInterval(tableSize - total_samples, sorted_hues[i - 1], hue_limit, hue_table, total_samples + 1);+ hue_table[0] = hue_table[baseIndex + tableSize - 1] - hue_limit;+ hue_table[baseIndex + tableSize] = hue_table[baseIndex] + hue_limit;+ return hue_table;+}++function findDisplayCuspForHue(hue: number, RGB_corners: V3[], JMh_corners: V3[], params: JMhParams): [number, number] {+ let upper_corner = 1;+ let found = false;+ for (let i = upper_corner; i !== totalCornerCount && !found; i++) {+ if (JMh_corners[i][2] > hue) {+ upper_corner = i;+ found = true;+ }+ }+ const lower_corner = upper_corner - 1;+ if (JMh_corners[lower_corner][2] === hue) {+ return [JMh_corners[lower_corner][0], JMh_corners[lower_corner][1]];+ }+ const cusp_lower = RGB_corners[lower_corner];+ const cusp_upper = RGB_corners[upper_corner];+ let lower_t = 0;+ let upper_t = 1;+ let sample_t: number;+ let JMh: V3;+ const lerp3 = (t: number): V3 => [+ lerp(cusp_lower[0], cusp_upper[0], t),+ lerp(cusp_lower[1], cusp_upper[1], t),+ lerp(cusp_lower[2], cusp_upper[2], t),+ ];+ while (upper_t - lower_t > display_cusp_tolerance) {+ sample_t = (lower_t + upper_t) / 2;+ JMh = rgbToJMh(lerp3(sample_t), params);+ if (JMh[2] < JMh_corners[lower_corner][2]) upper_t = sample_t;+ else if (JMh[2] >= JMh_corners[upper_corner][2]) lower_t = sample_t;+ else if (JMh[2] > hue) upper_t = sample_t;+ else lower_t = sample_t;+ }+ sample_t = (lower_t + upper_t) / 2;+ JMh = rgbToJMh(lerp3(sample_t), params);+ return [JMh[0], JMh[1]];+}++function buildCuspTable(hue_table: Float64Array, RGB_corners: V3[], JMh_corners: V3[], params: JMhParams): number[][] {+ const output_table: number[][] = new Array(totalTableSize);+ for (let i = baseIndex; i !== totalTableSize; i++) {+ const hue = hue_table[i];+ const JM = findDisplayCuspForHue(hue, RGB_corners, JMh_corners, params);+ output_table[i] = [JM[0], JM[1] * (1 + smooth_m * smooth_cusps), hue];+ }+ output_table[0] = [output_table[tableSize][0], output_table[tableSize][1], hue_table[0]];+ output_table[baseIndex + tableSize] = [+ output_table[baseIndex][0],+ output_table[baseIndex][1],+ hue_table[baseIndex + tableSize],+ ];+ return output_table;+}++function makeUniformHueGamutTable(+ reach_params: JMhParams,+ limit_params: JMhParams,+ peakLuminance: number,+ limit_J_max: number,+ forward_limit: number+): number[][] {+ const reach_JMh_corners = findReachCornersTable(reach_params, limit_J_max, forward_limit);+ const { RGB_corners, JMh_corners } = buildLimitingCuspCornersTables(limit_params, peakLuminance);+ const sorted_hues = extractSortedCubeHues(reach_JMh_corners, JMh_corners);+ const hue_table = buildHueTable(sorted_hues);+ return buildCuspTable(hue_table, RGB_corners, JMh_corners, limit_params);+}++function makeReachMTable(params: JMhParams, limitJmax: number): Float64Array {+ const reachTable = new Float64Array(totalTableSize);+ for (let i = 0; i < tableSize; i++) {+ const hue = baseHueForPosition(i, tableSize);+ const search_range = 50;+ const search_maximum = 1300;+ let low = 0;+ let high = low + search_range;+ let outside = false;+ while (!outside && high < search_maximum) {+ const newLimitRGB = jmhToRgb([limitJmax, high, hue], params);+ outside = anyBelowZero(newLimitRGB);+ if (!outside) {+ low = high;+ high = high + search_range;+ }+ }+ while (high - low > 1e-2) {+ const sampleM = (high + low) / 2;+ const newLimitRGB = jmhToRgb([limitJmax, sampleM, hue], params);+ outside = anyBelowZero(newLimitRGB);+ if (outside) high = sampleM;+ else low = sampleM;+ }+ reachTable[i + baseIndex] = high;+ }+ reachTable[0] = reachTable[tableSize];+ reachTable[baseIndex + tableSize] = reachTable[baseIndex];+ return reachTable;+}++function outsideHull(rgb: V3, maxRGBtestVal: number): boolean {+ return rgb[0] > maxRGBtestVal || rgb[1] > maxRGBtestVal || rgb[2] > maxRGBtestVal;+}++const test_count = 5;+const testPositions = [0.01, 0.1, 0.5, 0.8, 0.99];++interface GammaTestData {+ test_JMh: V3[];+ J_intersect_source: number[];+ slopes: number[];+ J_intersect_cusp: number[];+}++function generateGammaTestData(+ JMcusp: [number, number],+ hue: number,+ limit_J_max: number,+ mid_J: number,+ focus_dist: number+): GammaTestData {+ const analytical_threshold = lerp(JMcusp[0], limit_J_max, focus_gain_blend);+ const focus_J = computeFocusJ(JMcusp[0], mid_J, limit_J_max);+ const out: GammaTestData = { test_JMh: [], J_intersect_source: [], slopes: [], J_intersect_cusp: [] };+ for (let testIndex = 0; testIndex < test_count; testIndex++) {+ const test_J = lerp(JMcusp[0], limit_J_max, testPositions[testIndex]);+ const slope_gain = getFocusGain(test_J, analytical_threshold, limit_J_max, focus_dist);+ const J_intersect = solveJIntersect(test_J, JMcusp[1], focus_J, limit_J_max, slope_gain);+ const slope = computeCompressionVectorSlope(J_intersect, focus_J, limit_J_max, slope_gain);+ const J_cusp = solveJIntersect(JMcusp[0], JMcusp[1], focus_J, limit_J_max, slope_gain);+ out.test_JMh[testIndex] = [test_J, JMcusp[1], hue];+ out.J_intersect_source[testIndex] = J_intersect;+ out.slopes[testIndex] = slope;+ out.J_intersect_cusp[testIndex] = J_cusp;+ }+ return out;+}++function evaluateGammaFit(+ JMcusp: [number, number],+ d: GammaTestData,+ top_gamma_inv: number,+ peakLuminance: number,+ limit_J_max: number,+ lower_hull_gamma_inv: number,+ limit_params: JMhParams+): boolean {+ const luminance_limit = peakLuminance / ref_luminance;+ for (let testIndex = 0; testIndex < test_count; testIndex++) {+ const approxLimit_M = findGamutBoundaryIntersection(+ JMcusp,+ limit_J_max,+ top_gamma_inv,+ lower_hull_gamma_inv,+ d.J_intersect_source[testIndex],+ d.slopes[testIndex],+ d.J_intersect_cusp[testIndex]+ );+ const approxLimit_J = d.J_intersect_source[testIndex] + d.slopes[testIndex] * approxLimit_M;+ const newLimitRGB = jmhToRgb([approxLimit_J, approxLimit_M, d.test_JMh[testIndex][2]], limit_params);+ if (!outsideHull(newLimitRGB, luminance_limit)) return false;+ }+ return true;+}++function makeUpperHullGammaTable(gamutCuspTable: number[][], p: ODTParams): Float64Array {+ const upper_hull_gamma = new Float64Array(totalTableSize);+ for (let i = baseIndex; i !== baseIndex + tableSize; i++) {+ const hue = gamutCuspTable[i][2];+ const JMcusp: [number, number] = [gamutCuspTable[i][0], gamutCuspTable[i][1]];+ const d = generateGammaTestData(JMcusp, hue, p.limit_J_max, p.mid_J, p.focus_dist);+ const search_range = gamma_search_step;+ let low = gamma_minimum;+ let high = low + search_range;+ let outside = false;+ while (!outside && high < gamma_maximum) {+ const gammaFound = evaluateGammaFit(+ JMcusp,+ d,+ 1 / high,+ p.peakLuminance,+ p.limit_J_max,+ p.lower_hull_gamma_inv,+ p.limit_params+ );+ if (!gammaFound) {+ low = high;+ high = high + search_range;+ } else {+ outside = true;+ }+ }+ while (high - low > gamma_accuracy) {+ const testGamma = (high + low) / 2;+ const gammaFound = evaluateGammaFit(+ JMcusp,+ d,+ 1 / testGamma,+ p.peakLuminance,+ p.limit_J_max,+ p.lower_hull_gamma_inv,+ p.limit_params+ );+ if (gammaFound) high = testGamma;+ else low = testGamma;+ }+ upper_hull_gamma[i] = 1 / high;+ }+ upper_hull_gamma[0] = upper_hull_gamma[tableSize];+ upper_hull_gamma[tableSize + baseIndex] = upper_hull_gamma[baseIndex];+ return upper_hull_gamma;+}++function determineHueLinearitySearchRange(hue_table: Float64Array): [number, number] {+ const lower_padding = 0;+ const upper_padding = 1;+ const range: [number, number] = [lower_padding, upper_padding];+ for (let i = baseIndex; i !== baseIndex + tableSize; i++) {+ const pos = huePositionInUniformTable(hue_table[i], totalTableSize);+ const delta = i - pos;+ range[0] = Math.min(range[0], delta + lower_padding);+ range[1] = Math.max(range[1], delta + upper_padding);+ }+ return range;+}++function initODTParams(peakLuminance: number, limitingPrimaries: Primaries): ODTParams {+ const input_params = initJMhParams(AP0_PRIMARIES);+ const reach_params = initJMhParams(REACH_PRI);+ const limit_params = initJMhParams(limitingPrimaries);+ const ts = initTSParams(peakLuminance);+ const limit_J_max = yToJ(peakLuminance, input_params);+ const model_gamma_inv = 1 / model_gamma;+ const TABLE_reach_M = makeReachMTable(reach_params, limit_J_max);+ const sat = Math.max(0.2, chroma_expand - chroma_expand * chroma_expand_fact * ts.log_peak);+ const sat_thr = chroma_expand_thr / peakLuminance;+ const compr = chroma_compress + chroma_compress * chroma_compress_fact * ts.log_peak;+ const chroma_compress_scale = Math.pow(0.03379 * peakLuminance, 0.30596) - 0.45135;+ const mid_J = yToJ(ts.c_t * ref_luminance, input_params);+ const focus_dist = focus_distance + focus_distance * focus_distance_scaling * ts.log_peak;+ const lower_hull_gamma = 1.14 + 0.07 * ts.log_peak;+ const lower_hull_gamma_inv = 1 / lower_hull_gamma;+ const TABLE_gamut_cusps = makeUniformHueGamutTable(reach_params, limit_params, peakLuminance, limit_J_max, ts.forward_limit);+ const TABLE_hues = new Float64Array(totalTableSize);+ for (let i = 0; i < totalTableSize; i++) TABLE_hues[i] = TABLE_gamut_cusps[i][2];+ const p: ODTParams = {+ peakLuminance,+ input_params,+ reach_params,+ limit_params,+ ts,+ limit_J_max,+ model_gamma_inv,+ TABLE_reach_M,+ sat,+ sat_thr,+ compr,+ chroma_compress_scale,+ mid_J,+ focus_dist,+ lower_hull_gamma_inv,+ TABLE_hues,+ TABLE_gamut_cusps,+ TABLE_upper_hull_gamma: new Float64Array(0),+ hue_linearity_search_range: [0, 1],+ };+ p.TABLE_upper_hull_gamma = makeUpperHullGammaTable(TABLE_gamut_cusps, p);+ p.hue_linearity_search_range = determineHueLinearitySearchRange(TABLE_hues);+ return p;+}++/* ------------------------------------------------------------------ */+/* Display encoding (Lib.Academy.DisplayEncoding) */+/* ------------------------------------------------------------------ */++export type AcesEotf = "bt1886" | "pq" | "hlg";++const pq_m1 = 0.1593017578125;+const pq_m2 = 78.84375;+const pq_c1 = 0.8359375;+const pq_c2 = 18.8515625;+const pq_c3 = 18.6875;+const pq_C = 10000;++function yToST2084(C: number): number {+ const L = C / pq_C;+ const Lm = Math.pow(L, pq_m1);+ const N = (pq_c1 + pq_c2 * Lm) / (1 + pq_c3 * Lm);+ return Math.pow(N, pq_m2);+}++function st2084ToY(N: number): number {+ const Np = Math.pow(N, 1 / pq_m2);+ let L = Np - pq_c1;+ if (L < 0) L = 0;+ L = L / (pq_c2 - pq_c3 * Np);+ L = Math.pow(L, 1 / pq_m1);+ return L * pq_C;+}++/** PQ signal → HLG signal for a 1000-nit display (BT.2390 section 7). */+function st2084ToHlg1000(PQ: V3): V3 {+ const displayLinear: V3 = [st2084ToY(PQ[0]), st2084ToY(PQ[1]), st2084ToY(PQ[2])];+ const Y_d = 0.2627 * displayLinear[0] + 0.678 * displayLinear[1] + 0.0593 * displayLinear[2];+ const L_w = 1000;+ const L_b = 0;+ const alpha = L_w - L_b;+ const beta = L_b;+ const gamma = 1.2;+ const sceneLinear: V3 = [0, 0, 0];+ if (Y_d !== 0) {+ const k = Math.pow((Y_d - beta) / alpha, (1 - gamma) / gamma);+ for (let i = 0; i < 3; i++) sceneLinear[i] = k * ((displayLinear[i] - beta) / alpha);+ }+ const a = 0.17883277;+ const b = 0.28466892;+ const c = 0.55991073;+ const out: V3 = [0, 0, 0];+ for (let i = 0; i < 3; i++) {+ const e = sceneLinear[i];+ out[i] = e <= 1 / 12 ? Math.sqrt(3 * e) : a * Math.log(12 * e - b) + c;+ }+ return out;+}++function bt1886Inv(L: number, gamma: number, Lw = 1, Lb = 0): number {+ const a = Math.pow(Math.pow(Lw, 1 / gamma) - Math.pow(Lb, 1 / gamma), gamma);+ const b = Math.pow(Lb, 1 / gamma) / (Math.pow(Lw, 1 / gamma) - Math.pow(Lb, 1 / gamma));+ return Math.pow(Math.max(L / a, 0), 1 / gamma) - b;+}++function eotfInv(rgb_linear_in: V3, eotf: AcesEotf): V3 {+ const rgb: V3 = [Math.max(0, rgb_linear_in[0]), Math.max(0, rgb_linear_in[1]), Math.max(0, rgb_linear_in[2])];+ if (eotf === "pq") {+ return [yToST2084(ref_luminance * rgb[0]), yToST2084(ref_luminance * rgb[1]), yToST2084(ref_luminance * rgb[2])];+ }+ if (eotf === "hlg") {+ const PQ: V3 = [yToST2084(ref_luminance * rgb[0]), yToST2084(ref_luminance * rgb[1]), yToST2084(ref_luminance * rgb[2])];+ return st2084ToHlg1000(PQ);+ }+ return [bt1886Inv(rgb[0], 2.4), bt1886Inv(rgb[1], 2.4), bt1886Inv(rgb[2], 2.4)];+}++/* ------------------------------------------------------------------ */+/* Presets and the public transform */+/* ------------------------------------------------------------------ */++export type AcesOutputPresetId = "rec709-100" | "rec2100-hlg-1000" | "rec2100-pq-1000";++export interface AcesOutputPreset {+ id: AcesOutputPresetId;+ /** The reference file this preset restates. */+ transformId: string;+ limiting: Primaries;+ encoding: Primaries;+ peakLuminance: number;+ eotf: AcesEotf;+}++export const ACES_OUTPUT_PRESETS: Record<AcesOutputPresetId, AcesOutputPreset> = {+ "rec709-100": {+ id: "rec709-100",+ transformId: "Output.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886",+ limiting: REC709_PRIMARIES,+ encoding: REC709_PRIMARIES,+ peakLuminance: 100,+ eotf: "bt1886",+ },+ "rec2100-hlg-1000": {+ id: "rec2100-hlg-1000",+ transformId: "Output.Academy.P3-D65_1000nit_in_Rec2100-D65_HLG",+ limiting: P3D65_PRIMARIES,+ encoding: REC2020_PRIMARIES,+ peakLuminance: 1000,+ eotf: "hlg",+ },+ "rec2100-pq-1000": {+ id: "rec2100-pq-1000",+ transformId: "Output.Academy.Rec2100-D65_1000nit_in_Rec2100-D65_ST2084",+ limiting: REC2020_PRIMARIES,+ encoding: REC2020_PRIMARIES,+ peakLuminance: 1000,+ eotf: "pq",+ },+};++export interface AcesOutputTransform {+ preset: AcesOutputPreset;+ /** Scene-linear AP0 → display-linear RGB in the limiting primaries, before+ * the peak clamp and display encoding (the value OpenColorIO's fixed+ * function reports). */+ forwardLinear(r: number, g: number, b: number): V3;+ /** Scene-linear AP0 → display code values in the encoding primaries. */+ forward(r: number, g: number, b: number): V3;+}++function buildTransform(preset: AcesOutputPreset): AcesOutputTransform {+ const p = initODTParams(preset.peakLuminance, preset.limiting);+ const limitToDisplay = multF33F33(rgbToXyzF33(preset.limiting, 1), xyzToRgbF33(preset.encoding, 1));+ const peak = preset.peakLuminance / ref_luminance;+ const forwardLinear = (r: number, g: number, b: number): V3 => {+ const ap1 = multF3F33([r, g, b], AP0_TO_AP1);+ const lim = p.ts.forward_limit;+ for (let i = 0; i < 3; i++) ap1[i] = ap1[i] < 0 ? 0 : ap1[i] > lim ? lim : ap1[i];+ const aces = multF3F33(ap1, AP1_TO_AP0);+ const JMh = rgbToJMh(aces, p.input_params);+ const tonemapped = tonemapAndCompressFwd(JMh, p);+ const compressed = gamutCompressFwd(tonemapped, p);+ return jmhToRgb(compressed, p.limit_params);+ };+ const forward = (r: number, g: number, b: number): V3 => {+ const rgb = forwardLinear(r, g, b);+ for (let i = 0; i < 3; i++) rgb[i] = rgb[i] < 0 ? 0 : rgb[i] > peak ? peak : rgb[i];+ const display = multF3F33(rgb, limitToDisplay);+ return eotfInv(display, preset.eotf);+ };+ return { preset, forwardLinear, forward };+}++const transforms = new Map<AcesOutputPresetId, AcesOutputTransform>();++/** The transform for a preset, built on first use (the tables take a few+ * dozen milliseconds) and kept for the life of the module. */+export function acesOutputTransform(id: AcesOutputPresetId): AcesOutputTransform {+ let t = transforms.get(id);+ if (!t) {+ t = buildTransform(ACES_OUTPUT_PRESETS[id]);+ transforms.set(id, t);+ }+ return t;+}++/** An ad-hoc transform for the given limiting primaries and peak, exposed for+ * verification against published vectors. Display encoding is skipped. */+export function acesOutputTransformFor(peakLuminance: number, limiting: Primaries): AcesOutputTransform {+ return buildTransform({+ id: "rec709-100",+ transformId: "custom",+ limiting,+ encoding: limiting,+ peakLuminance,+ eotf: "bt1886",+ });+}diff --git a/site/packages/effects-kit/src/colorDrawn.test.ts b/site/packages/effects-kit/src/colorDrawn.test.tsnew file mode 100644index 00000000..c421de44--- /dev/null+++ b/site/packages/effects-kit/src/colorDrawn.test.ts@@ -0,0 +1,87 @@+import { describe, expect, test } from "bun:test";+import {+ buildClipLut,+ buildSourceLattice,+ clearSourceLatticeCache,+ createClipTransform,+ decodeYcc,+ needsMatrixFix,+ recipeIsIdentity,+ recipeKey,+ sourceTransform,+ type DrawnColor,+} from "./colorPipeline";++const near = (a: number[], b: number[], eps: number) => {+ for (let i = 0; i < a.length; i++) expect(Math.abs(a[i] - b[i])).toBeLessThanOrEqual(eps);+};++/** A Rec.2020 limited file the browser drew through Rec.709 limited. */+const SKEWED: DrawnColor = { matrix: "bt2020nc", fullRange: false, drawnMatrix: "bt709", drawnFullRange: false };++describe("drawn matrix", () => {+ test("identity holds only when the drawn matrix and range are the file's", () => {+ expect(recipeIsIdentity("rec709", "sdr")).toBe(true);+ expect(recipeIsIdentity("rec709", "sdr", { matrix: "bt709", fullRange: false, drawnMatrix: "bt709", drawnFullRange: false })).toBe(true);+ expect(recipeIsIdentity("rec709", "sdr", { drawnMatrix: "bt709", drawnFullRange: false })).toBe(true);+ expect(recipeIsIdentity("rec709", "sdr", SKEWED)).toBe(false);+ expect(recipeIsIdentity("rec709", "sdr", { matrix: "bt709", fullRange: true, drawnMatrix: "bt709", drawnFullRange: false })).toBe(false);+ expect(needsMatrixFix({ matrix: "bt601", fullRange: false })).toBe(false);+ });++ test("the key carries the fix and drops it when there is none", () => {+ const plain = recipeKey({ profile: "hlg", output: "sdr", size: 17 });+ const fixed = recipeKey({ profile: "hlg", output: "sdr", size: 17, ...SKEWED });+ expect(fixed).not.toBe(plain);+ expect(fixed).toContain("bt709l>bt2020ncl");+ expect(recipeKey({ profile: "hlg", output: "sdr", size: 17, matrix: "bt2020nc", fullRange: false, drawnMatrix: "bt2020nc", drawnFullRange: false })).toBe(plain);+ expect(recipeKey({ profile: "rec709", output: "sdr", size: 17, ...SKEWED })).not.toBe("");+ });++ test("the fix recovers the code values the wrong matrix hid", () => {+ // Code values through the true matrix, then through the drawn one, then the fix.+ const codes: [number, number, number][] = [+ [135 / 255, 91 / 255, 157 / 255],+ [113 / 255, 164 / 255, 97 / 255],+ [124 / 255, 128 / 255, 128 / 255],+ [206 / 255, 128 / 255, 128 / 255],+ [40 / 255, 200 / 255, 60 / 255],+ ];+ const fix = sourceTransform("rec709", "sdr", SKEWED)!;+ for (const [y, cb, cr] of codes) {+ const truth = decodeYcc({ matrix: "bt2020nc", fullRange: false }, y, cb, cr);+ const drawn = decodeYcc({ matrix: "bt709", fullRange: false }, y, cb, cr);+ near(fix(drawn[0], drawn[1], drawn[2]), truth, 1e-9);+ }+ });++ test("a range mismatch is undone too", () => {+ const fix = sourceTransform("rec709", "sdr", { matrix: "bt709", fullRange: true, drawnMatrix: "bt709", drawnFullRange: false })!;+ const drawn = decodeYcc({ matrix: "bt709", fullRange: false }, 124 / 255, 128 / 255, 128 / 255);+ near(fix(drawn[0], drawn[1], drawn[2]), [124 / 255, 124 / 255, 124 / 255], 1e-9);+ });++ test("the fix sits before the scene decode", () => {+ const direct = sourceTransform("hlg", "sdr")!;+ const fixed = sourceTransform("hlg", "sdr", SKEWED)!;+ const drawn = decodeYcc({ matrix: "bt709", fullRange: false }, 135 / 255, 91 / 255, 157 / 255);+ const truth = decodeYcc({ matrix: "bt2020nc", fullRange: false }, 135 / 255, 91 / 255, 157 / 255);+ near(fixed(drawn[0], drawn[1], drawn[2]), direct(truth[0], truth[1], truth[2]), 1e-6);+ });++ test("lattices and the clip transform agree, and a lattice without the fix is never reused for it", () => {+ clearSourceLatticeCache();+ const recipe = { profile: "hlg" as const, output: "sdr" as const, size: 9, ...SKEWED };+ const withFix = buildClipLut(recipe)!;+ const plainLattice = buildSourceLattice("hlg", "sdr", 9)!;+ const viaPlain = buildClipLut(recipe, undefined, plainLattice)!;+ expect(Array.from(viaPlain.data)).toEqual(Array.from(withFix.data));+ const fn = createClipTransform(recipe)!;+ const lut = buildClipLut({ profile: "rec709", output: "sdr", size: 9, ...SKEWED })!;+ const fn709 = createClipTransform({ profile: "rec709", output: "sdr", size: 9, ...SKEWED })!;+ // Node (4,2,6) of a 9-cube.+ const i = ((6 * 9 + 2) * 9 + 4) * 3;+ near([lut.data[i], lut.data[i + 1], lut.data[i + 2]], fn709(4 / 8, 2 / 8, 6 / 8), 1e-6);+ expect(fn(0.5, 0.5, 0.5)).toHaveLength(3);+ });+});diff --git a/site/packages/effects-kit/src/colorGrade.test.ts b/site/packages/effects-kit/src/colorGrade.test.tsindex 2196d8fe..af214105 100644--- a/site/packages/effects-kit/src/colorGrade.test.ts+++ b/site/packages/effects-kit/src/colorGrade.test.ts@@ -1,123 +1,116 @@import { describe, expect, test } from "bun:test";import {- autoGradeFromImageData,- gradeTint,- gradeToCssFilter,- gradeToFfmpegFilter,+ GRADE_BASIC_FIELDS,+ GRADE_DETAIL_FIELDS,+ GRADE_LUT_SCALAR_KEYS,+ GRADE_SCALAR_FIELDS,+ WHEEL_ZONES,+ gradeToolDirty,+ gradeWithoutDetail,isNeutralGrade,normalizeGrade,} from "./colorGrade";--/** RGBA frame from repeating [r,g,b] pixel patterns. */-function frame(...pixels: [number, number, number][]): Uint8ClampedArray {- const per = 64;- const data = new Uint8ClampedArray(pixels.length * per * 4);- pixels.forEach(([r, g, b], p) => {- for (let i = 0; i < per; i++) {- const o = (p * per + i) * 4;- data[o] = r;- data[o + 1] = g;- data[o + 2] = b;- data[o + 3] = 255;- }- });- return data;-}+import { gradeCssApprox } from "./gradeMath";describe("neutrality", () => {test("absent, empty, and all-zero grades are neutral", () => {expect(isNeutralGrade(undefined)).toBe(true);expect(isNeutralGrade({})).toBe(true);- expect(isNeutralGrade({ brightness: 0, hue: 0 })).toBe(true);+ expect(isNeutralGrade({ brightness: 0, hue: 0, whites: 0, fade: 0 })).toBe(true);expect(isNeutralGrade({ saturation: -5 })).toBe(false);+ expect(isNeutralGrade({ lut: { id: "lut:a" } })).toBe(false);});test("normalize strips zeros and collapses to undefined", () => {- expect(normalizeGrade({ brightness: 0, contrast: 0 })).toBeUndefined();+ expect(normalizeGrade({ brightness: 0, contrast: 0, sharpen: 0 })).toBeUndefined();expect(normalizeGrade({ brightness: 10, contrast: 0 })).toEqual({ brightness: 10 });});- test("normalize clamps out-of-range and drops garbage input", () => {+ test("normalize clamps every scalar to its own range and drops garbage input", () => {expect(normalizeGrade({ brightness: 999, hue: -999 })).toEqual({ brightness: 50, hue: -180 });+ expect(normalizeGrade({ fade: -20, sharpen: 80, clarity: -3, whites: 70 })).toEqual({ sharpen: 50, whites: 50 });expect(normalizeGrade({ contrast: Number.NaN, saturation: Infinity })).toBeUndefined();});- test("neutral grades emit nothing", () => {- expect(gradeToCssFilter(undefined)).toBe("");- expect(gradeToFfmpegFilter({ brightness: 0 })).toBe("");- expect(gradeTint({})).toBe(null);- });-});--describe("css filter", () => {- test("brightness and exposure fold into one gain", () => {- // (1 + 20/100) · 2^(50/50) = 2.4- expect(gradeToCssFilter({ brightness: 20, exposure: 50 })).toBe("brightness(2.400)");+ test("normalize keeps preset and LUT references structurally", () => {+ expect(normalizeGrade({ preset: { id: "mono", amount: 0 } })).toEqual({ preset: { id: "mono", amount: 0 } });+ expect(normalizeGrade({ preset: { id: "mono", amount: 1, skin: false } })).toEqual({ preset: { id: "mono" } });+ expect(normalizeGrade({ lut: { id: "lut:a", amount: 2 } })).toEqual({ lut: { id: "lut:a" } });+ expect(normalizeGrade({ lut: { id: "lut:a", amount: 0.25 } })).toEqual({ lut: { id: "lut:a", amount: 0.25 } });+ expect(normalizeGrade({ lut: { id: "" } })).toBeUndefined();});- test("emits only non-neutral terms, in application order", () => {- expect(gradeToCssFilter({ contrast: 25, hue: -90 })).toBe("contrast(1.250) hue-rotate(-90.000deg)");- expect(gradeToCssFilter({ saturation: -50 })).toBe("saturate(0.000)");- });-- test("warmth keeps luminance: gain rises, tint dims the cool channel", () => {- // t=1 → gains (1.25, 1, 0.75), normalized by 1.25.- expect(gradeToCssFilter({ temperature: 50 })).toBe("brightness(1.250)");- expect(gradeTint({ temperature: 50 })).toBe("rgb(255, 204, 153)");- expect(gradeTint({ temperature: -50 })).toBe("rgb(153, 204, 255)");+ test("normalize keeps the offset wheel and drops identity tuples", () => {+ expect(normalizeGrade({ wheels: { o: [0, 0, 0], s: [10, 0, 0] } })).toEqual({ wheels: { s: [10, 0, 0] } });+ expect(normalizeGrade({ wheels: { o: [0, 20, 0] } })).toEqual({ wheels: { o: [0, 20, 0] } });+ expect(WHEEL_ZONES).toEqual(["s", "m", "h", "o"]);});});-describe("auto grade", () => {- test("a mid-gray frame needs nearly nothing", () => {- const g = autoGradeFromImageData(frame([118, 118, 118]));- expect(Math.abs(g?.exposure ?? 0) <= 1).toBe(true);- expect(g?.contrast).toBeUndefined(); // flat histogram = no tonal signal- expect(g?.temperature).toBeUndefined();- });-- test("a dark frame gets pushed up toward middle gray", () => {- const g = autoGradeFromImageData(frame([30, 30, 30], [50, 50, 50]));- expect((g?.exposure ?? 0) > 10).toBe(true);- });-- test("a compressed tonal range gets a contrast stretch", () => {- const g = autoGradeFromImageData(frame([100, 100, 100], [150, 150, 150]));- expect((g?.contrast ?? 0) > 0).toBe(true);- });-- test("gray-world counters color casts both ways, hue and saturation stay", () => {- const cool = autoGradeFromImageData(frame([90, 120, 170]));- expect((cool?.temperature ?? 0) > 0).toBe(true);- const warm = autoGradeFromImageData(frame([170, 120, 90]));- expect((warm?.temperature ?? 0) < 0).toBe(true);- expect(cool?.saturation).toBeUndefined();- expect(cool?.hue).toBeUndefined();- });-- test("an empty sample yields no grade", () => {- expect(autoGradeFromImageData(new Uint8ClampedArray(0))).toBeUndefined();+describe("field catalogs", () => {+ test("basic and detail fields are scalar fields, and the LUT keys leave out the spatial ones", () => {+ const scalar = new Set(GRADE_SCALAR_FIELDS.map(([k]) => k));+ for (const f of GRADE_BASIC_FIELDS) expect(scalar.has(f.key)).toBe(true);+ for (const f of GRADE_DETAIL_FIELDS) expect(scalar.has(f.key)).toBe(true);+ expect(GRADE_LUT_SCALAR_KEYS).not.toContain("sharpen");+ expect(GRADE_LUT_SCALAR_KEYS).not.toContain("clarity");+ expect(GRADE_LUT_SCALAR_KEYS).toContain("exposure");+ expect(GRADE_BASIC_FIELDS.map((f) => f.key)).toEqual([+ "exposure",+ "contrast",+ "highlights",+ "shadows",+ "whites",+ "blacks",+ "brilliance",+ "fade",+ "temperature",+ "tint",+ "saturation",+ "vibrance",+ ]);+ });++ test("tool dirtiness follows the field a tool owns", () => {+ expect(gradeToolDirty({ fade: 10 }, "basic")).toBe(true);+ expect(gradeToolDirty({ fade: 10 }, "detail")).toBe(false);+ expect(gradeToolDirty({ sharpen: 10 }, "detail")).toBe(true);+ expect(gradeToolDirty({ lut: { id: "lut:a" } }, "lut")).toBe(true);+ expect(gradeToolDirty({ wheels: { o: [1, 0, 0] } }, "wheels")).toBe(true);+ expect(gradeToolDirty({ curves: { m: [[0, 10], [255, 255]] } }, "curves")).toBe(true);+ expect(gradeToolDirty({ hsl: { red: [5, 0, 0] } }, "hsl")).toBe(true);+ expect(gradeToolDirty(undefined, "basic")).toBe(false);+ });++ test("gradeWithoutDetail keeps the LUT-baked part only", () => {+ expect(gradeWithoutDetail({ sharpen: 10, clarity: 5 })).toBeUndefined();+ expect(gradeWithoutDetail({ sharpen: 10, contrast: 5 })).toEqual({ contrast: 5 });});});-describe("ffmpeg filter", () => {- test("gain+contrast ride one lutrgb, trailing comma included", () => {- const expr = "clip((clip(val*1.100,0,255)-128)*1.200+128,0,255)";- expect(gradeToFfmpegFilter({ brightness: 10, contrast: 20 })).toBe(- `lutrgb=r='${expr}':g='${expr}':b='${expr}',`,- );- });-- test("saturation and hue share the hue filter", () => {- expect(gradeToFfmpegFilter({ saturation: 25, hue: 45 })).toBe("hue=h=45.000:s=1.500,");- });-- test("temperature emits the gain lut and the tint lut in preview order", () => {- expect(gradeToFfmpegFilter({ temperature: 50 })).toBe(- "lutrgb=r='clip((clip(val*1.250,0,255)-128)*1.000+128,0,255)'" +- ":g='clip((clip(val*1.250,0,255)-128)*1.000+128,0,255)'" +- ":b='clip((clip(val*1.250,0,255)-128)*1.000+128,0,255)'," +- "lutrgb=r='clip(val*1.000,0,255)':g='clip(val*0.800,0,255)':b='clip(val*0.600,0,255)',",- );+describe("gradeCssApprox", () => {+ test("neutral grades emit nothing", () => {+ expect(gradeCssApprox(undefined)).toEqual({ filter: "", tint: null });+ expect(gradeCssApprox({ brightness: 0 })).toEqual({ filter: "", tint: null });+ });++ test("exposure brightens, contrast and saturation map to their filters, warmth tints", () => {+ const up = gradeCssApprox({ exposure: 25 });+ expect(up.filter).toMatch(/brightness\(1\.\d+\)/);+ expect(gradeCssApprox({ exposure: -25 }).filter).toMatch(/brightness\(0\.\d+\)/);+ expect(gradeCssApprox({ contrast: 25 }).filter).toMatch(/contrast\(1\.\d+\)/);+ expect(gradeCssApprox({ saturation: -50 }).filter).toMatch(/saturate\(0\.0+\)/);+ expect(gradeCssApprox({ hue: 90 }).filter).toContain("hue-rotate(90");+ const warm = gradeCssApprox({ temperature: 50 });+ expect(warm.tint).toMatch(/^rgb\(/);+ const [r, , b] = warm.tint!.match(/\d+/g)!.map(Number);+ expect(r).toBeGreaterThan(b);+ const cool = gradeCssApprox({ temperature: -50 });+ const [cr, , cb] = cool.tint!.match(/\d+/g)!.map(Number);+ expect(cb).toBeGreaterThan(cr);+ });++ test("a monochrome preset reads as desaturated", () => {+ expect(gradeCssApprox({ preset: { id: "mono" } }).filter).toContain("saturate(0");});});diff --git a/site/packages/effects-kit/src/colorGrade.ts b/site/packages/effects-kit/src/colorGrade.tsindex 1b0e2ef8..b40d37f4 100644--- a/site/packages/effects-kit/src/colorGrade.ts+++ b/site/packages/effects-kit/src/colorGrade.ts@@ -14,11 +14,13 @@ export interface GradeCurves {* per-range brightness trim. */export type WheelTuple = [number, number, number];-/** Shadows / midtones / highlights color wheels; an absent wheel is neutral. */+/** The four wheels: lift (s), gamma (m), gain (h) and offset (o); an absent+ * wheel is neutral. */export interface GradeWheels {s?: WheelTuple;m?: WheelTuple;h?: WheelTuple;+ o?: WheelTuple;}export type HslBand =@@ -45,45 +47,89 @@ export interface GradePresetRef {skin?: boolean;}+/** A library LUT applied to the clip before the grade. `id` is the library+ * asset id (`lut:<contentKey>`); `amount` 0..1 mixes the LUT's result with+ * its input (default 1). */+export interface GradeLutRef {+ id: string;+ amount?: number;+}+/** Per-clip color adjustments. Integer sliders, 0 = neutral; every field is* absent when neutral, so untouched clips carry nothing. */export interface ColorGrade {- brightness?: number; // -50..50+ brightness?: number; // -50..50 (legacy; stored docs only)contrast?: number; // -50..50saturation?: number; // -50..50- exposure?: number; // -50..50 (±1 EV)- temperature?: number; // -50..50, positive = warm+ exposure?: number; // -50..50 (±2 stops)+ temperature?: number; // -50..50, positive = warm (±100 mireds)tint?: number; // -50..50, negative = green, positive = magenta- hue?: number; // -180..180 degrees- highlights?: number; // -50..50, luma-masked highlight trim- shadows?: number; // -50..50, luma-masked shadow lift/crush- vibrance?: number; // -50..50, low-saturation-weighted saturation+ hue?: number; // -180..180 degrees (legacy; stored docs only)+ highlights?: number; // -50..50+ shadows?: number; // -50..50+ whites?: number; // -50..50+ blacks?: number; // -50..50+ brilliance?: number; // -50..50+ vibrance?: number; // -50..50+ fade?: number; // 0..50, lifted blacks+ sharpen?: number; // 0..50, spatial+ clarity?: number; // 0..50, spatialcurves?: GradeCurves;wheels?: GradeWheels;hsl?: Partial<Record<HslBand, HslTuple>>;preset?: GradePresetRef;+ lut?: GradeLutRef;}/** Slider range for every grade parameter except hue. */export const GRADE_MAX = 50;export const GRADE_HUE_MAX = 180;+export type GradeBasicKey =+ | "exposure"+ | "contrast"+ | "highlights"+ | "shadows"+ | "whites"+ | "blacks"+ | "brilliance"+ | "fade"+ | "temperature"+ | "tint"+ | "saturation"+ | "vibrance";+/** The Basic tool's slider rows; the UI and the AI tool schema both derive* from this list. Legacy `brightness` and `hue` stay in the model and render- * everywhere, surfaced by the UI only when a stored grade carries them. */+ * everywhere, surfaced by the UI only when a stored grade carries them.+ * `min` is 0 for the one-sided sliders. */export const GRADE_BASIC_FIELDS: {- key: "exposure" | "contrast" | "highlights" | "shadows" | "temperature" | "tint" | "saturation" | "vibrance";+ key: GradeBasicKey;label: string;group: "light" | "color";+ min: number;}[] = [- { key: "exposure", label: "Exposure", group: "light" },- { key: "contrast", label: "Contrast", group: "light" },- { key: "highlights", label: "Highlights", group: "light" },- { key: "shadows", label: "Shadows", group: "light" },- { key: "temperature", label: "Temperature", group: "color" },- { key: "tint", label: "Tint", group: "color" },- { key: "saturation", label: "Saturation", group: "color" },- { key: "vibrance", label: "Vibrance", group: "color" },+ { key: "exposure", label: "Exposure", group: "light", min: -GRADE_MAX },+ { key: "contrast", label: "Contrast", group: "light", min: -GRADE_MAX },+ { key: "highlights", label: "Highlights", group: "light", min: -GRADE_MAX },+ { key: "shadows", label: "Shadows", group: "light", min: -GRADE_MAX },+ { key: "whites", label: "Whites", group: "light", min: -GRADE_MAX },+ { key: "blacks", label: "Blacks", group: "light", min: -GRADE_MAX },+ { key: "brilliance", label: "Brilliance", group: "light", min: -GRADE_MAX },+ { key: "fade", label: "Fade", group: "light", min: 0 },+ { key: "temperature", label: "Temperature", group: "color", min: -GRADE_MAX },+ { key: "tint", label: "Tint", group: "color", min: -GRADE_MAX },+ { key: "saturation", label: "Saturation", group: "color", min: -GRADE_MAX },+ { key: "vibrance", label: "Vibrance", group: "color", min: -GRADE_MAX },+];++export type GradeDetailKey = "sharpen" | "clarity";++/** The spatial controls: applied on the picture after the LUT, so they are+ * left out of the LUT and its key. */+export const GRADE_DETAIL_FIELDS: { key: GradeDetailKey; label: string; min: number }[] = [+ { key: "sharpen", label: "Sharpen", min: 0 },+ { key: "clarity", label: "Clarity", min: 0 },];/** The HSL tool's hue bands: chip swatch plus the band's center hue used by@@ -99,22 +145,38 @@ export const HSL_BANDS: { id: HslBand; label: string; center: number; swatch: st{ id: "magenta", label: "Magenta", center: 330, swatch: "hsl(320 65% 55%)" },];-/**- * One mapping, every renderer. Scalar-only grades (the fast path) derive both- * filter strings from the numbers computed here, so what the sliders show is- * what ffmpeg bakes: gain/contrast are per-channel multiplies and a mid-gray- * pivot, mathematically identical on both sides; saturation/hue lean on each- * side's native primitive (CSS saturate/hue-rotate vs ffmpeg's chroma-plane- * `hue`), visually indistinguishable over these ranges.- *- * Fast-path application order everywhere: gain+contrast → saturation+hue →- * cast tint. Grades that use curves, wheels, per-hue HSL, highlights/shadows,- * vibrance, or a preset render through one shared 3D LUT instead — built in- * gradeLut.ts from the transform in gradeMath.ts — applied by ffmpeg's lut3d,- * the preview's WebGL pass, and the headless CPU pass alike.- */+/** The wheels, in the order the tool shows them. */+export const WHEEL_ZONES = ["s", "m", "h", "o"] as const;+export type WheelZone = (typeof WHEEL_ZONES)[number];++export const WHEEL_LABELS: Record<WheelZone, string> = {+ s: "Lift",+ m: "Gamma",+ h: "Gain",+ o: "Offset",+};++/** Every scalar slider with its range: [key, min, max]. */+export const GRADE_SCALAR_FIELDS: [keyof ColorGrade & string, number, number][] = [+ ["brightness", -GRADE_MAX, GRADE_MAX],+ ["contrast", -GRADE_MAX, GRADE_MAX],+ ["saturation", -GRADE_MAX, GRADE_MAX],+ ["exposure", -GRADE_MAX, GRADE_MAX],+ ["temperature", -GRADE_MAX, GRADE_MAX],+ ["tint", -GRADE_MAX, GRADE_MAX],+ ["hue", -GRADE_HUE_MAX, GRADE_HUE_MAX],+ ["highlights", -GRADE_MAX, GRADE_MAX],+ ["shadows", -GRADE_MAX, GRADE_MAX],+ ["whites", -GRADE_MAX, GRADE_MAX],+ ["blacks", -GRADE_MAX, GRADE_MAX],+ ["brilliance", -GRADE_MAX, GRADE_MAX],+ ["vibrance", -GRADE_MAX, GRADE_MAX],+ ["fade", 0, GRADE_MAX],+ ["sharpen", 0, GRADE_MAX],+ ["clarity", 0, GRADE_MAX],+];-type ScalarKey =+export type GradeScalarKey =| "brightness"| "contrast"| "saturation"@@ -124,30 +186,25 @@ type ScalarKey =| "hue"| "highlights"| "shadows"- | "vibrance";+ | "whites"+ | "blacks"+ | "brilliance"+ | "vibrance"+ | "fade"+ | "sharpen"+ | "clarity";-const FIELDS: [ScalarKey, number][] = [- ["brightness", GRADE_MAX],- ["contrast", GRADE_MAX],- ["saturation", GRADE_MAX],- ["exposure", GRADE_MAX],- ["temperature", GRADE_MAX],- ["tint", GRADE_MAX],- ["hue", GRADE_HUE_MAX],- ["highlights", GRADE_MAX],- ["shadows", GRADE_MAX],- ["vibrance", GRADE_MAX],-];+/** The scalar fields that bake into the LUT; sharpen and clarity are spatial. */+export const GRADE_LUT_SCALAR_KEYS: GradeScalarKey[] = GRADE_SCALAR_FIELDS.map(([k]) => k as GradeScalarKey).filter(+ (k) => k !== "sharpen" && k !== "clarity"+);-const clamp = (v: unknown, max: number) => {+const clampRange = (v: unknown, min: number, max: number) => {const n = typeof v === "number" && Number.isFinite(v) ? v : 0;- return Math.max(-max, Math.min(max, n));+ return Math.max(min, Math.min(max, n));};-const fmt = (n: number) => (Math.round(n * 1000) / 1000).toFixed(3);-const CURVE_CHANNELS = ["m", "r", "g", "b"] as const;-const WHEEL_ZONES = ["s", "m", "h"] as const;/** Clamp a stored curve into shape: integer points inside 0..255, sorted by* input, one point per input; identity or degenerate curves become absent. */@@ -169,9 +226,9 @@ function normalizeCurve(pts: unknown): CurvePoint[] | undefined {function normalizeTuple(t: unknown, max = GRADE_MAX): [number, number, number] | undefined {if (!Array.isArray(t)) return undefined;const out: [number, number, number] = [- Math.round(clamp(t[0], max)),- Math.round(clamp(t[1], max)),- Math.round(clamp(t[2], max)),+ Math.round(clampRange(t[0], -max, max)),+ Math.round(clampRange(t[1], -max, max)),+ Math.round(clampRange(t[2], -max, max)),];return out.some((v) => v !== 0) ? out : undefined;}@@ -180,46 +237,33 @@ export function isNeutralGrade(g: ColorGrade | undefined | null): boolean {return !g || normalizeGrade(g) === undefined;}-/** True when the grade uses primitives beyond the cheap ctx.filter path —- * those render through the shared 3D LUT. Every legacy scalar-only grade- * stays false and keeps the original render path byte for byte. */-export function gradeNeedsLut(g: ColorGrade | undefined | null): boolean {- if (!g) return false;- return !!(- g.highlights ||- g.shadows ||- g.vibrance ||- g.curves ||- g.wheels ||- g.hsl ||- (g.preset?.id && (g.preset.amount ?? 1) > 0)- );-}-/** True when the given Adjust tool holds a non-neutral value; drives the* panel's per-tool dirty dots. */export function gradeToolDirty(g: ColorGrade | undefined | null,- tool: "basic" | "curves" | "wheels" | "hsl"+ tool: "basic" | "curves" | "wheels" | "hsl" | "detail" | "lut"): boolean {const n = normalizeGrade(g);if (!n) return false;if (tool === "curves") return !!n.curves;if (tool === "wheels") return !!n.wheels;if (tool === "hsl") return !!n.hsl;- return FIELDS.some(([k]) => n[k]);+ if (tool === "lut") return !!n.lut;+ if (tool === "detail") return GRADE_DETAIL_FIELDS.some((f) => n[f.key]);+ return GRADE_SCALAR_FIELDS.some(([k]) => k !== "sharpen" && k !== "clarity" && n[k as GradeScalarKey]);}/** Clamp to slider ranges, drop zeros and identity shapes; an all-neutral* grade becomes absent. Also the sanitizer for grades arriving as client- * JSON. Preset ids are kept structurally — an id the running catalog does not- * know renders as neutral instead of being stripped from the doc. */+ * JSON. Preset and LUT ids are kept structurally — an id the running catalog+ * or library does not know renders as neutral instead of being stripped from+ * the doc. */export function normalizeGrade(g: ColorGrade | undefined | null): ColorGrade | undefined {if (!g) return undefined;const out: ColorGrade = {};- for (const [k, max] of FIELDS) {- const v = clamp(g[k], max);- if (v !== 0) out[k] = v;+ for (const [k, min, max] of GRADE_SCALAR_FIELDS) {+ const v = clampRange(g[k as GradeScalarKey], min, max);+ if (v !== 0) out[k as GradeScalarKey] = v;}if (g.curves && typeof g.curves === "object") {const curves: GradeCurves = {};@@ -258,155 +302,23 @@ export function normalizeGrade(g: ColorGrade | undefined | null): ColorGrade | u...(g.preset.skin ? { skin: true } : {}),};}- return Object.keys(out).length ? out : undefined;-}--/** The shared numeric model behind both filter strings. */-export function deriveGrade(g: ColorGrade) {- const b = clamp(g.brightness, GRADE_MAX);- const c = clamp(g.contrast, GRADE_MAX);- const s = clamp(g.saturation, GRADE_MAX);- const e = clamp(g.exposure, GRADE_MAX);- const t = clamp(g.temperature, GRADE_MAX) / GRADE_MAX;- const m = clamp(g.tint, GRADE_MAX) / GRADE_MAX;- const H = clamp(g.hue, GRADE_HUE_MAX);- // Warm shifts red up and blue down; magenta lowers green, green raises it.- // Gains are normalized to ≤1 (a multiply tint can only darken); the excess- // folds into the shared gain so a cast shift keeps overall luminance- // instead of dimming the picture.- const gr = 1 + 0.25 * t;- const gg = 1 - 0.2 * m;- const gb = 1 - 0.25 * t;- const norm = Math.max(gr, gg, gb, 1);- return {- gain: (1 + b / 100) * Math.pow(2, e / GRADE_MAX) * norm,- contrast: 1 + c / 100,- saturate: Math.max(0, 1 + s / GRADE_MAX),- hue: H,- tint:- t === 0 && m === 0 ? null : { r: gr / norm, g: gg / norm, b: gb / norm },- };-}--/** Canvas 2D `ctx.filter` value; "" when nothing applies. The warm tint is not- * expressible as a CSS filter function — apply `gradeTint` as a multiply pass- * after drawing with this filter. */-export function gradeToCssFilter(g: ColorGrade | undefined | null): string {- if (isNeutralGrade(g)) return "";- const d = deriveGrade(g!);- const parts: string[] = [];- if (d.gain !== 1) parts.push(`brightness(${fmt(d.gain)})`);- if (d.contrast !== 1) parts.push(`contrast(${fmt(d.contrast)})`);- if (d.saturate !== 1) parts.push(`saturate(${fmt(d.saturate)})`);- if (d.hue !== 0) parts.push(`hue-rotate(${fmt(d.hue)}deg)`);- return parts.join(" ");-}--/** CSS color for the multiply tint pass, or null when temperature is neutral. */-export function gradeTint(g: ColorGrade | undefined | null): string | null {- if (isNeutralGrade(g)) return null;- const tint = deriveGrade(g!).tint;- if (!tint) return null;- const ch = (v: number) => Math.round(255 * v);- return `rgb(${ch(tint.r)}, ${ch(tint.g)}, ${ch(tint.b)})`;-}--/**- * Auto grade from a frame's RGBA pixels, following the classic auto-tone- * pipeline rather than invented heuristics:- *- * 1. Exposure — the photographic auto-exposure convention: map the frame's- * log-average (geometric mean) luminance onto 18% middle gray, projected- * into this pipeline's gamma-encoded gain.- * 2. Contrast — auto-levels: clip 0.5% off each end of the luma histogram- * (the common editor default) and stretch what remains toward full range,- * projected onto the symmetric mid-gray contrast knob.- * 3. Temperature — gray-world white balance: choose the warm/cool gains that- * equalize the red and blue channel means.- *- * Corrections are damped and capped inside the slider range so the result is- * a starting point the user refines. Classic auto-tone leaves saturation and- * hue alone, and so does this.- */-export function autoGradeFromImageData(data: Uint8ClampedArray): ColorGrade | undefined {- const hist = new Float64Array(256);- let count = 0;- let logSum = 0;- let sumR = 0;- let sumB = 0;- let mids = 0;- for (let i = 0; i < data.length; i += 4) {- const r = data[i];- const g = data[i + 1];- const b = data[i + 2];- const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;- hist[Math.min(255, Math.round(luma))]++;- // Approximate linear luminance for the log-average (γ≈2.2 decode).- logSum += Math.log(Math.max(1e-4, Math.pow(luma / 255, 2.2)));- count++;- // Cast statistics from the midtones only — near-black and clipped pixels- // carry no reliable illuminant signal.- if (luma >= 16 && luma <= 240) {- sumR += r;- sumB += b;- mids++;- }- }- if (!count) return undefined;- const percentile = (p: number) => {- let acc = 0;- for (let v = 0; v < 256; v++) {- acc += hist[v];- if (acc >= count * p) return v;- }- return 255;- };-- const grade: ColorGrade = {};- // EV against 18% gray in linear light; our gain multiplies gamma-encoded- // values, so one encoded stop is γ linear stops (slider v: 2^(v/50)).- const ev = Math.log2(0.18 / Math.exp(logSum / count));- grade.exposure = Math.round((GRADE_MAX * ev * 0.8) / 2.2);- // Auto-levels spread after the exposure shift moves it, on encoded values.- // A near-flat histogram (solid color, title card) carries no tonal-range- // signal — leave contrast alone rather than stretch noise.- const gain = Math.pow(2, grade.exposure / GRADE_MAX);- const lo = Math.min(255, percentile(0.005) * gain);- const hi = Math.min(255, percentile(0.995) * gain);- if (hi - lo >= 16) {- grade.contrast = Math.max(- -10,- Math.min(40, Math.round((255 / (hi - lo) - 1) * 100 * 0.6))+ if (g.lut && typeof g.lut.id === "string" && g.lut.id) {+ const amount = Math.max(+ 0,+ Math.min(1, typeof g.lut.amount === "number" && Number.isFinite(g.lut.amount) ? g.lut.amount : 1));+ out.lut = { id: g.lut.id, ...(amount !== 1 ? { amount } : {}) };}- if (mids) {- // Gray-world: t such that the temperature gains (1±0.25t) equalize the- // red/blue means — a blue cast warms, an orange cast cools.- const avgR = sumR / mids;- const avgB = sumB / mids;- const t = (avgB - avgR) / (0.25 * (avgR + avgB));- grade.temperature = Math.max(-40, Math.min(40, Math.round(t * 0.6 * GRADE_MAX)));- }- return normalizeGrade(grade);+ return Object.keys(out).length ? out : undefined;}-/** ffmpeg filter chain with a trailing comma, ready to sit between the color- * conversion and the terminal `format=` of a clip's core chain; "" when- * neutral. Uses only `lutrgb` and `hue` — the bundled build has no `eq`. */-export function gradeToFfmpegFilter(g: ColorGrade | undefined | null): string {- if (isNeutralGrade(g)) return "";- const d = deriveGrade(g!);- const parts: string[] = [];- if (d.gain !== 1 || d.contrast !== 1) {- const expr = `clip((clip(val*${fmt(d.gain)},0,255)-128)*${fmt(d.contrast)}+128,0,255)`;- parts.push(`lutrgb=r='${expr}':g='${expr}':b='${expr}'`);- }- if (d.saturate !== 1 || d.hue !== 0) {- parts.push(`hue=h=${fmt(d.hue)}:s=${fmt(d.saturate)}`);- }- if (d.tint) {- const ch = (v: number) => `'clip(val*${fmt(v)},0,255)'`;- parts.push(`lutrgb=r=${ch(d.tint.r)}:g=${ch(d.tint.g)}:b=${ch(d.tint.b)}`);- }- return parts.length ? parts.join(",") + "," : "";+/** The grade without its spatial controls: what the LUT bakes. */+export function gradeWithoutDetail(g: ColorGrade | undefined | null): ColorGrade | undefined {+ const n = normalizeGrade(g);+ if (!n) return undefined;+ if (!n.sharpen && !n.clarity) return n;+ const out = { ...n };+ delete out.sharpen;+ delete out.clarity;+ return Object.keys(out).length ? out : undefined;}diff --git a/site/packages/effects-kit/src/colorPipeline.test.ts b/site/packages/effects-kit/src/colorPipeline.test.tsnew file mode 100644index 00000000..fec65d8c--- /dev/null+++ b/site/packages/effects-kit/src/colorPipeline.test.ts@@ -0,0 +1,238 @@+import { describe, expect, test } from "bun:test";+import {+ buildClipLut,+ buildGradeLut,+ buildSourceLattice,+ buildTransferLut,+ clearSourceLatticeCache,+ compositeSpaceFor,+ createClipTransform,+ graphicsToHlg,+ hexToHlgHex,+ hlgToPq,+ pqToHlg,+ recipeIsIdentity,+ recipeKey,+ sourceTransform,+} from "./colorPipeline";+import { BT2408_HLG_WHITE, appleLogEncode, bt1886Encode, pqEncode } from "./colorSpace";+import { applyLutToImageData } from "./gradeLut";+import type { ParsedLut } from "./lutFile";++/** A two-node cube that inverts every channel. */+function invertLut(): ParsedLut {+ const data = new Float32Array(8 * 3);+ let i = 0;+ for (let b = 0; b < 2; b++)+ for (let g = 0; g < 2; g++)+ for (let r = 0; r < 2; r++) {+ data[i++] = 1 - r;+ data[i++] = 1 - g;+ data[i++] = 1 - b;+ }+ return { cube: { size: 2, data, min: [0, 0, 0], max: [1, 1, 1] } };+}++const near = (a: number[], b: number[], eps: number) => {+ for (let i = 0; i < a.length; i++) expect(Math.abs(a[i] - b[i])).toBeLessThanOrEqual(eps);+};+const neutral = (v: number[], eps = 1e-6) => {+ expect(Math.abs(v[0] - v[1])).toBeLessThan(eps);+ expect(Math.abs(v[1] - v[2])).toBeLessThan(eps);+};++describe("identity and keys", () => {+ test("Rec.709 and sRGB delivered as SDR need no mapping", () => {+ expect(recipeIsIdentity("rec709", "sdr")).toBe(true);+ expect(recipeIsIdentity("srgb", "sdr")).toBe(true);+ expect(recipeIsIdentity("rec709", "hlg")).toBe(false);+ expect(recipeIsIdentity("apple-log", "sdr")).toBe(false);+ expect(createClipTransform({ profile: "rec709", output: "sdr", size: 33 })).toBe(null);+ expect(buildClipLut({ profile: "srgb", output: "sdr", size: 33 })).toBe(null);+ });++ test("the key is empty for identity, blind to spatial controls, and stable", () => {+ expect(recipeKey({ profile: "srgb", output: "sdr", size: 33 })).toBe("");+ expect(recipeKey({ profile: "srgb", output: "sdr", size: 33, grade: { sharpen: 20, clarity: 5 } })).toBe("");+ const a = recipeKey({ profile: "rec709", output: "sdr", size: 33, grade: { contrast: 10, exposure: 5 } });+ const b = recipeKey({ profile: "srgb", output: "sdr", size: 33, grade: { exposure: 5, contrast: 10, sharpen: 30 } });+ expect(a).toBe(b);+ expect(a).not.toBe(recipeKey({ profile: "rec709", output: "sdr", size: 33, grade: { contrast: 11 } }));+ expect(a).not.toBe(recipeKey({ profile: "rec709", output: "sdr", size: 65, grade: { contrast: 10, exposure: 5 } }));+ expect(recipeKey({ profile: "apple-log", output: "sdr", size: 33 })).not.toBe("");+ expect(recipeKey({ profile: "rec709", output: "hlg", size: 33 })).not.toBe("");+ expect(recipeKey({ profile: "rec709", output: "sdr", size: 33, grade: { lut: { id: "lut:a" } } })).not.toBe(+ recipeKey({ profile: "rec709", output: "sdr", size: 33, grade: { lut: { id: "lut:b" } } })+ );+ });+});++describe("library LUT", () => {+ test("mixes by amount and sits before the grade", () => {+ const lut = invertLut();+ const full = createClipTransform({ profile: "rec709", output: "sdr", size: 33, grade: { lut: { id: "lut:x" } } }, lut)!;+ near(full(0.2, 0.5, 0.9), [0.8, 0.5, 0.1], 1e-6);+ const half = createClipTransform(+ { profile: "rec709", output: "sdr", size: 33, grade: { lut: { id: "lut:x", amount: 0.5 } } },+ lut+ )!;+ near(half(0.2, 0.5, 0.9), [0.5, 0.5, 0.5], 1e-6);+ // Without the parsed file the reference renders as neutral.+ expect(createClipTransform({ profile: "rec709", output: "sdr", size: 33, grade: { lut: { id: "lut:x" } } })).toBe(null);+ // Fade lifts black after the LUT: inverted white is black, then lifted.+ const faded = createClipTransform(+ { profile: "rec709", output: "sdr", size: 33, grade: { lut: { id: "lut:x" }, fade: 50 } },+ lut+ )!;+ expect(faded(1, 1, 1)[0]).toBeGreaterThan(0.15);+ });+});++describe("source conversion", () => {+ test("Apple Log 18% grey renders as ACES middle grey", () => {+ const v = appleLogEncode(0.18);+ const out = createClipTransform({ profile: "apple-log", output: "sdr", size: 33 })!(v, v, v);+ neutral(out);+ expect(Math.abs(out[0] - 0.3831)).toBeLessThan(2e-3);+ const out2 = createClipTransform({ profile: "apple-log-2", output: "sdr", size: 33 })!(v, v, v);+ neutral(out2);+ expect(Math.abs(out2[0] - out[0])).toBeLessThan(1e-3);+ });++ test("HLG and PQ sources agree on reference white in SDR", () => {+ const hlg = sourceTransform("hlg", "sdr")!(BT2408_HLG_WHITE, BT2408_HLG_WHITE, BT2408_HLG_WHITE);+ const p = pqEncode(203);+ const pq = sourceTransform("pq", "sdr")!(p, p, p);+ neutral(hlg);+ neutral(pq);+ expect(Math.abs(hlg[0] - pq[0])).toBeLessThan(2e-3);+ // The BT.2408 reference white lands where ACES puts diffuse white.+ expect(Math.abs(hlg[0] - 0.722)).toBeLessThan(2e-3);+ });++ test("an HDR source delivered in its own encoding is left alone, graded in place", () => {+ expect(recipeIsIdentity("hlg", "hlg")).toBe(true);+ expect(recipeIsIdentity("pq", "pq")).toBe(true);+ expect(recipeIsIdentity("hlg", "pq")).toBe(false);+ expect(recipeIsIdentity("apple-log", "hlg")).toBe(false);+ expect(createClipTransform({ profile: "hlg", output: "hlg", size: 33 })).toBeNull();+ expect(recipeKey({ profile: "hlg", output: "hlg", size: 33 })).toBe("");+ // A grade on it works in the HLG container: neutral stays neutral, the+ // order holds, and an exposure lift lands above the untouched signal.+ const t = createClipTransform({ profile: "hlg", output: "hlg", size: 33, grade: { exposure: 20 } })!;+ let prev = -1;+ for (let i = 0; i <= 20; i++) {+ const s = i / 20;+ const out = t(s, s, s);+ neutral(out, 1e-4);+ expect(out[0]).toBeGreaterThanOrEqual(prev - 1e-9);+ prev = out[0];+ }+ expect(t(0.5, 0.5, 0.5)[0]).toBeGreaterThan(0.5);+ });++ test("HLG and PQ cross into each other through the transfer at 1000 nits, and back", () => {+ const w = BT2408_HLG_WHITE;+ near(hlgToPq(w, w, w), [pqEncode(203), pqEncode(203), pqEncode(203)], 1e-3);+ near(hlgToPq(1, 1, 1), [pqEncode(1000), pqEncode(1000), pqEncode(1000)], 1e-6);+ for (const s of [0.1, 0.4, 0.75, 0.95]) {+ near(pqToHlg(...hlgToPq(s, s * 0.8, s * 0.5)), [s, s * 0.8, s * 0.5], 1e-5);+ }+ const hlgToPqRecipe = createClipTransform({ profile: "hlg", output: "pq", size: 33 })!;+ near(hlgToPqRecipe(w, w, w), hlgToPq(w, w, w), 1e-3);+ const pqToHlgRecipe = createClipTransform({ profile: "pq", output: "hlg", size: 33 })!;+ const p = pqEncode(203);+ near(pqToHlgRecipe(p, p, p), [w, w, w], 1e-3);+ });++ test("a log source delivered as HDR renders through the ACES HLG transform", () => {+ const t = createClipTransform({ profile: "apple-log", output: "hlg", size: 33 })!;+ const grey = appleLogEncode(0.18);+ const out = t(grey, grey, grey);+ neutral(out, 2e-3);+ // Middle grey lands below reference white and above black.+ expect(out[0]).toBeGreaterThan(0.2);+ expect(out[0]).toBeLessThan(BT2408_HLG_WHITE);+ });++ test("graphics map into HLG at reference white, the frame color with them", () => {+ near(graphicsToHlg(1, 1, 1), [BT2408_HLG_WHITE, BT2408_HLG_WHITE, BT2408_HLG_WHITE], 2e-4);+ near(graphicsToHlg(0, 0, 0), [0, 0, 0], 1e-9);+ expect(hexToHlgHex("#ffffff")).toBe("#bfbfbf");+ expect(hexToHlgHex("#000000")).toBe("#000000");+ expect(hexToHlgHex("nope")).toBe("nope");+ const lut = buildTransferLut(9, graphicsToHlg);+ expect(lut.size).toBe(9);+ // The last node is white in, reference white out.+ const last = lut.data.length - 3;+ near([lut.data[last], lut.data[last + 1], lut.data[last + 2]], [BT2408_HLG_WHITE, BT2408_HLG_WHITE, BT2408_HLG_WHITE], 2e-4);+ expect(compositeSpaceFor("sdr")).toBe("sdr");+ expect(compositeSpaceFor("hlg")).toBe("hlg");+ expect(compositeSpaceFor("pq")).toBe("hlg");+ });++ test("an SDR source delivered as HDR takes the BT.2408 mapping", () => {+ const hlg = createClipTransform({ profile: "rec709", output: "hlg", size: 33 })!;+ near(hlg(1, 1, 1), [BT2408_HLG_WHITE, BT2408_HLG_WHITE, BT2408_HLG_WHITE], 2e-4);+ const pq = createClipTransform({ profile: "srgb", output: "pq", size: 33 })!;+ near(pq(1, 1, 1), [pqEncode(203), pqEncode(203), pqEncode(203)], 1e-6);+ // The grade works on SDR values first: a stop of exposure doubles linear+ // light before the container change.+ const graded = createClipTransform({ profile: "rec709", output: "pq", size: 33, grade: { exposure: 25 } })!;+ const grey = bt1886Encode(0.18);+ expect(graded(grey, grey, grey)[0]).toBeGreaterThan(pq(grey, grey, grey)[0]);+ });+});++describe("lattices", () => {+ test("composing over a source lattice equals the direct build", () => {+ clearSourceLatticeCache();+ const recipe = { profile: "apple-log" as const, output: "sdr" as const, size: 17, grade: { contrast: 20, temperature: -10 } };+ const direct = buildClipLut(recipe)!;+ const lattice = buildSourceLattice("apple-log", "sdr", 17)!;+ const composed = buildClipLut(recipe, undefined, lattice)!;+ expect(composed.size).toBe(17);+ for (let i = 0; i < direct.data.length; i++) expect(Math.abs(direct.data[i] - composed.data[i])).toBeLessThan(1e-6);+ // A lattice of another size or profile is ignored, and the cached one used.+ const other = buildSourceLattice("hlg", "sdr", 17)!;+ const viaOther = buildClipLut(recipe, undefined, other)!;+ for (let i = 0; i < direct.data.length; i++) expect(Math.abs(direct.data[i] - viaOther.data[i])).toBeLessThan(1e-6);+ expect(buildSourceLattice("rec709", "sdr", 17)).toBe(null);+ });++ test("the LUT agrees with the transform through the tetrahedral pass", () => {+ const recipe = { profile: "apple-log" as const, output: "sdr" as const, size: 33, grade: { contrast: 15, saturation: 10 } };+ const lut = buildClipLut(recipe)!;+ const t = createClipTransform(recipe)!;+ const samples: [number, number, number][] = [+ [0.3, 0.4, 0.5],+ [0.48, 0.48, 0.48],+ [0.6, 0.45, 0.35],+ [0.2, 0.55, 0.5],+ ];+ const px = new Uint8ClampedArray(samples.length * 4);+ samples.forEach((c, i) => {+ px[i * 4] = Math.round(c[0] * 255);+ px[i * 4 + 1] = Math.round(c[1] * 255);+ px[i * 4 + 2] = Math.round(c[2] * 255);+ px[i * 4 + 3] = 255;+ });+ applyLutToImageData(px, lut);+ samples.forEach((c, i) => {+ const d = t(Math.round(c[0] * 255) / 255, Math.round(c[1] * 255) / 255, Math.round(c[2] * 255) / 255);+ for (let k = 0; k < 3; k++) expect(Math.abs(px[i * 4 + k] - d[k] * 255)).toBeLessThanOrEqual(4);+ });+ });++ test("buildGradeLut is the Rec.709 SDR recipe and stays in range", () => {+ expect(buildGradeLut(undefined)).toBe(null);+ expect(buildGradeLut({ contrast: 0 })).toBe(null);+ const lut = buildGradeLut({ exposure: 50, highlights: 50, wheels: { s: [50, 0, 0] } }, 9)!;+ expect(lut.size).toBe(9);+ expect(lut.data.length).toBe(9 * 9 * 9 * 3);+ for (const v of lut.data) {+ expect(v).toBeGreaterThanOrEqual(0);+ expect(v).toBeLessThanOrEqual(1);+ }+ });+});diff --git a/site/packages/effects-kit/src/colorPipeline.ts b/site/packages/effects-kit/src/colorPipeline.tsnew file mode 100644index 00000000..5fbdee92--- /dev/null+++ b/site/packages/effects-kit/src/colorPipeline.ts@@ -0,0 +1,491 @@+/**+ * One mapping per clip. A clip's color is a pure function from its source+ * code values to the project's output code values, baked into one 3D LUT+ * that the WebGL pass, the CPU pass and ffmpeg's lut3d consume unchanged:+ *+ * 1 source conversion → the output's display values (none for Rec.709 /+ * sRGB in SDR, and none for an HLG or PQ file delivered in its own+ * encoding; Apple Log and Apple Log 2 decode to scene-linear ACES and go+ * through the ACES 2.0 output transform — the Rec.709 100-nit transform+ * for an SDR project, the Rec.2100 1000-nit HLG one when the project+ * delivers HDR; HLG and PQ take the same transform into SDR, and cross+ * into each other through the BT.2100 transfer at 1000 nits, so an HDR+ * source keeps its range)+ * 2 the clip's library LUT, mixed by its amount+ * 3 the grade (preset layer, then manual), gradeMath.ts+ * 4 output: SDR as is; an SDR source delivered as HDR takes the BT.2408+ * mapping (Rec.709 white to 203 nits in the Rec.2020 container)+ *+ * Sharpen and clarity are spatial and run on the picture afterwards+ * (detail.ts); they never enter the LUT or its key.+ *+ * The source conversion is the expensive stage (the ACES transform), and it+ * never changes while sliders move, so it can be sampled once onto its own+ * lattice and the cheap stages composed on top per edit.+ */++import { type ColorGrade, gradeWithoutDetail } from "./colorGrade";+import { type AcesOutputPresetId, acesOutputTransform } from "./acesOutput";+import {+ type CodeFormat,+ type Mat3,+ type OutputSpace,+ type SourceProfile,+ AP0_PRIMARIES,+ APPLE_WIDE_GAMUT_PRIMARIES,+ BRADFORD,+ HLG_SCENE_WHITE,+ REC2020_PRIMARIES,+ appleLogDecode,+ bt1886Decode,+ hlgOetf,+ hlgOetfInverse,+ hlgOotf,+ hlgOotfInverse,+ mat3Apply,+ mat3Inv,+ pqDecode,+ pqEncode,+ rgbToRgbMatrix,+ sdrToHlg,+ sdrToPq,+} from "./colorSpace";+import { type GradeLut, GRADE_LUT_SIZE, stableJson } from "./gradeLut";+import { type GradeTransform, createGradeTransform } from "./gradeMath";+import { type ParsedLut, sampleLut } from "./lutFile";++/** The file's Y'CbCr matrix and range beside the ones the decoder drew the+ * picture with. A browser decoder reads its matrix from tags, and the tags+ * are rewritten to Rec.709 so it draws code values; the picture then holds+ * R'G'B' made through the wrong matrix, and the source stage undoes that+ * before anything else. */+export interface DrawnColor {+ matrix: CodeFormat["matrix"];+ fullRange: boolean;+ drawnMatrix: CodeFormat["matrix"];+ drawnFullRange: boolean;+}++export interface ClipColorRecipe extends Partial<DrawnColor> {+ profile: SourceProfile;+ grade?: ColorGrade | null;+ output: OutputSpace;+ /** Lattice nodes per axis. */+ size: number;+}++/** True when the picture was drawn through a matrix or range that differs+ * from the file's. Missing fields mean Rec.709 limited on both sides. */+export function needsMatrixFix(drawn: Partial<DrawnColor> | undefined): drawn is DrawnColor {+ if (!drawn || drawn.drawnMatrix === undefined) return false;+ return drawn.drawnMatrix !== (drawn.matrix ?? "bt709") || (drawn.drawnFullRange ?? false) !== (drawn.fullRange ?? false);+}++/** True when the source's code values already are the output's: Rec.709 or+ * sRGB delivered as SDR, or an HLG or PQ file delivered in its own encoding,+ * drawn through the file's own matrix. */+export function recipeIsIdentity(profile: SourceProfile, output: OutputSpace, drawn?: Partial<DrawnColor>): boolean {+ const same = output === "sdr" ? profile === "rec709" || profile === "srgb" : profile === output;+ return same && !needsMatrixFix(drawn);+}++/** The space an HDR delivery composites in: every clip, graphic and effect+ * meets in HLG, and a PQ file is the final pass over the finished picture. */+export function compositeSpaceFor(output: OutputSpace): OutputSpace {+ return output === "sdr" ? "sdr" : "hlg";+}++/** The fix spelled for a cache key: "" when the picture needs none. */+export const drawnColorKey = (drawn: Partial<DrawnColor> | undefined): string =>+ needsMatrixFix(drawn)+ ? `${drawn.drawnMatrix}${drawn.drawnFullRange ? "f" : "l"}>${drawn.matrix}${drawn.fullRange ? "f" : "l"}`+ : "";++const isSdrSource = (profile: SourceProfile) => profile === "rec709" || profile === "srgb";+const isHdrSource = (profile: SourceProfile) => profile === "hlg" || profile === "pq";++/** A stable identity for the recipe's baked result. The LUT is referenced by+ * its id; the spatial controls are left out. "" when the recipe is an+ * identity mapping with no grade. */+export function recipeKey(recipe: ClipColorRecipe): string {+ const grade = gradeWithoutDetail(recipe.grade);+ if (!grade && recipeIsIdentity(recipe.profile, recipe.output, recipe)) return "";+ const drawn = drawnColorKey(recipe);+ return stableJson({+ profile: isSdrSource(recipe.profile) ? "rec709" : recipe.profile,+ output: recipe.output,+ size: recipe.size,+ ...(drawn ? { drawn } : {}),+ ...(grade ? { grade } : {}),+ });+}++/* ------------------------------------------------------------------ */+/* Stage 0: the drawn matrix */+/* ------------------------------------------------------------------ */++/** Luma weights (Kr, Kb) of each matrix; Kg is what is left. */+const LUMA_WEIGHTS: Record<CodeFormat["matrix"], [number, number]> = {+ bt709: [0.2126, 0.0722],+ bt601: [0.299, 0.114],+ bt2020nc: [0.2627, 0.0593],+};++/** R'G'B' → Y'CbCr (Y' in [0,1], Cb/Cr centered on 0). */+function rgbToYccMatrix(matrix: CodeFormat["matrix"]): Mat3 {+ const [kr, kb] = LUMA_WEIGHTS[matrix];+ const kg = 1 - kr - kb;+ return [kr, kg, kb, -kr / (2 * (1 - kb)), -kg / (2 * (1 - kb)), 0.5, 0.5, -kg / (2 * (1 - kr)), -kb / (2 * (1 - kr))];+}++/** Y'CbCr code values (each in [0,1] of its 8-bit scale, chroma centered on+ * 128/255) → R'G'B' through the matrix at the range. What a decoder draws. */+export function decodeYcc(+ format: Pick<CodeFormat, "matrix" | "fullRange">,+ y: number,+ cb: number,+ cr: number+): [number, number, number] {+ const [yy, cbb, crr] = format.fullRange+ ? [y, cb - 128 / 255, cr - 128 / 255]+ : [((y * 255 - 16) / 219), ((cb * 255 - 128) / 224), ((cr * 255 - 128) / 224)];+ return mat3Apply(mat3Inv(rgbToYccMatrix(format.matrix)), yy, cbb, crr);+}++/** R'G'B' → Y'CbCr code values at the range: the inverse of `decodeYcc`. */+function encodeYcc(format: Pick<CodeFormat, "matrix" | "fullRange">, r: number, g: number, b: number): [number, number, number] {+ const [y, cb, cr] = mat3Apply(rgbToYccMatrix(format.matrix), r, g, b);+ return format.fullRange+ ? [y, cb + 128 / 255, cr + 128 / 255]+ : [(16 + 219 * y) / 255, (128 + 224 * cb) / 255, (128 + 224 * cr) / 255];+}++/** The affine map from the drawn R'G'B' back to the code values and out+ * through the file's own matrix and range. */+function matrixFixTransform(drawn: DrawnColor): GradeTransform {+ const fix = (r: number, g: number, b: number): [number, number, number] => {+ const [y, cb, cr] = encodeYcc({ matrix: drawn.drawnMatrix, fullRange: drawn.drawnFullRange }, r, g, b);+ return decodeYcc({ matrix: drawn.matrix, fullRange: drawn.fullRange }, y, cb, cr);+ };+ // The map is affine, so three basis probes and the offset pin it down.+ const t = fix(0, 0, 0);+ const cr = fix(1, 0, 0);+ const cg = fix(0, 1, 0);+ const cb = fix(0, 0, 1);+ const m: Mat3 = [+ cr[0] - t[0], cg[0] - t[0], cb[0] - t[0],+ cr[1] - t[1], cg[1] - t[1], cb[1] - t[1],+ cr[2] - t[2], cg[2] - t[2], cb[2] - t[2],+ ];+ return (r, g, b) => {+ const v = mat3Apply(m, r, g, b);+ return [v[0] + t[0], v[1] + t[1], v[2] + t[2]];+ };+}++/* ------------------------------------------------------------------ */+/* Stage 1: source conversion */+/* ------------------------------------------------------------------ */++const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);++const REC2020_TO_AP0 = rgbToRgbMatrix(REC2020_PRIMARIES, AP0_PRIMARIES, BRADFORD);+const AWG_TO_AP0 = rgbToRgbMatrix(APPLE_WIDE_GAMUT_PRIMARIES, AP0_PRIMARIES, BRADFORD);+const HLG_TO_ACES_SCALE = 1 / HLG_SCENE_WHITE;++function acesPresetFor(output: OutputSpace): AcesOutputPresetId {+ return output === "hlg" ? "rec2100-hlg-1000" : output === "pq" ? "rec2100-pq-1000" : "rec709-100";+}++/** Code values → scene-linear AP0 for the profiles that carry a scene. */+function sceneDecoder(profile: SourceProfile): ((r: number, g: number, b: number) => [number, number, number]) | null {+ const toAp0 = (m: Mat3, r: number, g: number, b: number): [number, number, number] => [+ m[0] * r + m[1] * g + m[2] * b,+ m[3] * r + m[4] * g + m[5] * b,+ m[6] * r + m[7] * g + m[8] * b,+ ];+ switch (profile) {+ case "apple-log":+ return (r, g, b) => toAp0(REC2020_TO_AP0, appleLogDecode(r), appleLogDecode(g), appleLogDecode(b));+ case "apple-log-2":+ return (r, g, b) => toAp0(AWG_TO_AP0, appleLogDecode(r), appleLogDecode(g), appleLogDecode(b));+ case "hlg":+ // BT.2100 inverse OETF gives the HLG scene; BT.2408 puts its reference+ // white at the 75% signal, and ACES puts diffuse white at 1.0.+ return (r, g, b) =>+ toAp0(+ REC2020_TO_AP0,+ hlgOetfInverse(r) * HLG_TO_ACES_SCALE,+ hlgOetfInverse(g) * HLG_TO_ACES_SCALE,+ hlgOetfInverse(b) * HLG_TO_ACES_SCALE+ );+ case "pq":+ // PQ is display-referred: the ST 2084 EOTF gives nits, and the BT.2390+ // inverse OOTF for a 1000-nit display recovers the HLG scene.+ return (r, g, b) => {+ const [rs, gs, bs] = hlgOotfInverse(pqDecode(r), pqDecode(g), pqDecode(b), 1000);+ return toAp0(REC2020_TO_AP0, rs * HLG_TO_ACES_SCALE, gs * HLG_TO_ACES_SCALE, bs * HLG_TO_ACES_SCALE);+ };+ default:+ return null;+ }+}++/** HLG signal → PQ signal on a 1000-nit display: the BT.2100 OOTF gives the+ * display light, and ST 2084 encodes it. What the final pass of a PQ+ * delivery runs over the HLG composite. */+export function hlgToPq(r: number, g: number, b: number): [number, number, number] {+ const [rd, gd, bd] = hlgOotf(hlgOetfInverse(r), hlgOetfInverse(g), hlgOetfInverse(b), 1000);+ return [pqEncode(rd), pqEncode(gd), pqEncode(bd)];+}++/** PQ signal → HLG signal, the inverse: display light back through the+ * BT.2390 inverse OOTF at 1000 nits and the HLG OETF. */+export function pqToHlg(r: number, g: number, b: number): [number, number, number] {+ const [rs, gs, bs] = hlgOotfInverse(pqDecode(r), pqDecode(g), pqDecode(b), 1000);+ return [hlgOetf(rs), hlgOetf(gs), hlgOetf(bs)];+}++/** The source conversion for a profile into the output's display values, or+ * null when the source already is display values in the grade's container.+ * A drawn matrix that differs from the file's is undone first. An HDR file+ * delivered as the other HDR encoding crosses through the transfer alone —+ * same range, same display, so nothing is re-rendered. */+export function sourceTransform(+ profile: SourceProfile,+ output: OutputSpace,+ drawn?: Partial<DrawnColor>+): GradeTransform | null {+ const fix = needsMatrixFix(drawn) ? matrixFixTransform(drawn) : null;+ if (recipeIsIdentity(profile, output)) return fix;+ if (isHdrSource(profile) && output !== "sdr") {+ const cross = output === "pq" ? hlgToPq : pqToHlg;+ return (r, g, b) => {+ const [fr, fg, fb] = fix ? fix(r, g, b) : [r, g, b];+ return cross(clamp01(fr), clamp01(fg), clamp01(fb));+ };+ }+ const scene = sceneDecoder(profile);+ if (!scene) return fix;+ const ot = acesOutputTransform(acesPresetFor(output));+ return (r, g, b) => {+ const [fr, fg, fb] = fix ? fix(r, g, b) : [r, g, b];+ const [ar, ag, ab] = scene(clamp01(fr), clamp01(fg), clamp01(fb));+ return ot.forward(ar, ag, ab);+ };+}++/* ------------------------------------------------------------------ */+/* Stage 4: output */+/* ------------------------------------------------------------------ */++/** SDR display values into the HDR container (BT.2408), or null when the+ * grade already worked in the output container. */+function outputTransform(profile: SourceProfile, output: OutputSpace): GradeTransform | null {+ if (output === "sdr" || !isSdrSource(profile)) return null;+ const map = output === "hlg" ? sdrToHlg : sdrToPq;+ return (r, g, b) => map(bt1886Decode(r), bt1886Decode(g), bt1886Decode(b));+}++/* ------------------------------------------------------------------ */+/* The composed mapping */+/* ------------------------------------------------------------------ */++/** Stages 2–4: the LUT, the grade and the output mapping on display values. */+function postSourceTransform(recipe: ClipColorRecipe, userLut: ParsedLut | undefined): GradeTransform | null {+ const grade = gradeWithoutDetail(recipe.grade);+ const gradeSpace: OutputSpace = isSdrSource(recipe.profile) ? "sdr" : recipe.output;+ const lutRef = grade?.lut;+ const lutAmount = lutRef && userLut ? (lutRef.amount ?? 1) : 0;+ const gradeFn = createGradeTransform(grade, gradeSpace);+ const outFn = outputTransform(recipe.profile, recipe.output);+ if (!lutAmount && !gradeFn && !outFn) return null;+ return (r, g, b) => {+ let v: [number, number, number] = [r, g, b];+ if (lutAmount && userLut) {+ const l = sampleLut(userLut, clamp01(v[0]), clamp01(v[1]), clamp01(v[2]));+ v = [+ v[0] + (l[0] - v[0]) * lutAmount,+ v[1] + (l[1] - v[1]) * lutAmount,+ v[2] + (l[2] - v[2]) * lutAmount,+ ];+ }+ if (gradeFn) v = gradeFn(v[0], v[1], v[2]);+ if (outFn) v = outFn(clamp01(v[0]), clamp01(v[1]), clamp01(v[2]));+ return v;+ };+}++/**+ * Compile the recipe into the pure mapping from source code values to output+ * code values, both in [0,1]. Returns null when the mapping is identity: an+ * SDR-in-SDR clip with no grade and no LUT.+ */+export function createClipTransform(recipe: ClipColorRecipe, userLut?: ParsedLut): GradeTransform | null {+ const source = sourceTransform(recipe.profile, recipe.output, recipe);+ const post = postSourceTransform(recipe, userLut);+ if (!source && !post) return null;+ return (r, g, b) => {+ let v: [number, number, number] = source ? source(r, g, b) : [r, g, b];+ if (post) v = post(v[0], v[1], v[2]);+ return [clamp01(v[0]), clamp01(v[1]), clamp01(v[2])];+ };+}++/* ------------------------------------------------------------------ */+/* Lattices */+/* ------------------------------------------------------------------ */++/** The source conversion sampled onto a lattice: display values of the+ * output container at every node of the source cube. */+export interface SourceLattice {+ profile: SourceProfile;+ output: OutputSpace;+ size: number;+ /** The drawn-matrix fix baked in, as `drawnKey` spells it; "" for none. */+ drawn: string;+ data: Float32Array;+}++function fillLattice(size: number, fn: GradeTransform): Float32Array {+ const data = new Float32Array(size * size * size * 3);+ const step = 1 / (size - 1);+ let i = 0;+ for (let b = 0; b < size; b++) {+ for (let g = 0; g < size; g++) {+ for (let r = 0; r < size; r++) {+ const out = fn(r * step, g * step, b * step);+ data[i++] = out[0];+ data[i++] = out[1];+ data[i++] = out[2];+ }+ }+ }+ return data;+}++/** A fixed mapping sampled onto a lattice: the HLG → PQ pass a PQ delivery+ * ends with, and the sRGB → HLG mapping every graphic takes into an HDR+ * composite. */+export function buildTransferLut(size: number, fn: GradeTransform): GradeLut {+ return {+ size,+ data: fillLattice(size, (r, g, b) => {+ const v = fn(r, g, b);+ return [clamp01(v[0]), clamp01(v[1]), clamp01(v[2])];+ }),+ };+}++/** The mapping a graphic drawn in sRGB — a title, a caption, a sticker, the+ * frame color — takes into the HLG composite: BT.2408, white at 75%. */+export function graphicsToHlg(r: number, g: number, b: number): [number, number, number] {+ return sdrToHlg(bt1886Decode(clamp01(r)), bt1886Decode(clamp01(g)), bt1886Decode(clamp01(b)));+}++/** A CSS hex color mapped into the HLG composite, as hex again. */+export function hexToHlgHex(hex: string): string {+ const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());+ if (!m) return hex;+ const n = parseInt(m[1], 16);+ const [r, g, b] = graphicsToHlg(((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255);+ const q = (v: number) => Math.round(clamp01(v) * 255).toString(16).padStart(2, "0");+ return `#${q(r)}${q(g)}${q(b)}`;+}++/** Sample the source conversion alone. Null when the profile needs none. */+export function buildSourceLattice(+ profile: SourceProfile,+ output: OutputSpace,+ size: number,+ drawn?: Partial<DrawnColor>+): SourceLattice | null {+ const source = sourceTransform(profile, output, drawn);+ if (!source) return null;+ return { profile, output, size, drawn: drawnColorKey(drawn), data: fillLattice(size, source) };+}++/** A few source lattices kept for the grade-only rebuilds while sliders+ * move; the cap is bytes, so four 65³ lattices at most. */+const SOURCE_LATTICE_CACHE_BYTES = 16 * 1024 * 1024;+const sourceLatticeCache = new Map<string, SourceLattice>();+let sourceLatticeBytes = 0;++function cachedSourceLattice(+ profile: SourceProfile,+ output: OutputSpace,+ size: number,+ drawn: Partial<DrawnColor> | undefined+): SourceLattice | null {+ const key = `${profile}|${output}|${size}|${drawnColorKey(drawn)}`;+ const hit = sourceLatticeCache.get(key);+ if (hit) {+ sourceLatticeCache.delete(key);+ sourceLatticeCache.set(key, hit);+ return hit;+ }+ const built = buildSourceLattice(profile, output, size, drawn);+ if (!built) return null;+ const bytes = built.data.byteLength;+ while (sourceLatticeBytes + bytes > SOURCE_LATTICE_CACHE_BYTES && sourceLatticeCache.size) {+ const oldest = sourceLatticeCache.keys().next().value as string;+ sourceLatticeBytes -= sourceLatticeCache.get(oldest)!.data.byteLength;+ sourceLatticeCache.delete(oldest);+ }+ sourceLatticeCache.set(key, built);+ sourceLatticeBytes += bytes;+ return built;+}++export function clearSourceLatticeCache(): void {+ sourceLatticeCache.clear();+ sourceLatticeBytes = 0;+}++/**+ * Sample the whole recipe onto the lattice. Returns null for an identity+ * mapping. A source lattice of the same profile, output and size composes the+ * cheap stages over it; without one the cached lattice is used, built on+ * first sight.+ */+export function buildClipLut(recipe: ClipColorRecipe, userLut?: ParsedLut, source?: SourceLattice): GradeLut | null {+ const size = recipe.size;+ const post = postSourceTransform(recipe, userLut);+ const lattice =+ source &&+ source.profile === recipe.profile &&+ source.output === recipe.output &&+ source.size === size &&+ source.drawn === drawnColorKey(recipe)+ ? source+ : cachedSourceLattice(recipe.profile, recipe.output, size, recipe);+ if (!lattice) {+ if (!post) return null;+ return {+ size,+ data: fillLattice(size, (r, g, b) => {+ const v = post(r, g, b);+ return [clamp01(v[0]), clamp01(v[1]), clamp01(v[2])];+ }),+ };+ }+ const src = lattice.data;+ const data = new Float32Array(src.length);+ if (!post) {+ for (let i = 0; i < src.length; i++) data[i] = clamp01(src[i]);+ return { size, data };+ }+ for (let i = 0; i < src.length; i += 3) {+ const v = post(src[i], src[i + 1], src[i + 2]);+ data[i] = clamp01(v[0]);+ data[i + 1] = clamp01(v[1]);+ data[i + 2] = clamp01(v[2]);+ }+ return { size, data };+}++/** The LUT of a grade alone on a Rec.709 source delivered as SDR: preset+ * tiles, thumbnails and the grade tests. */+export function buildGradeLut(g: ColorGrade | undefined | null, size = GRADE_LUT_SIZE): GradeLut | null {+ return buildClipLut({ profile: "rec709", grade: g, output: "sdr", size });+}diff --git a/site/packages/effects-kit/src/colorSpace.test.ts b/site/packages/effects-kit/src/colorSpace.test.tsnew file mode 100644index 00000000..da32d5d0--- /dev/null+++ b/site/packages/effects-kit/src/colorSpace.test.ts@@ -0,0 +1,202 @@+import { describe, expect, test } from "bun:test";+import {+ APPLE_WIDE_GAMUT_PRIMARIES,+ BRADFORD,+ BT2408_HLG_WHITE,+ BT2408_REFERENCE_WHITE_NITS,+ CAT02,+ D65,+ D65_KELVIN,+ HLG_SCENE_WHITE,+ MAT3_IDENTITY,+ REC2020_PRIMARIES,+ REC709_PRIMARIES,+ appleLogDecode,+ appleLogEncode,+ bt1886Decode,+ bt1886Encode,+ chromaticAdaptation,+ hlgOetf,+ hlgOetfInverse,+ hlgOotf,+ hlgOotfInverse,+ illuminantXy,+ lchToOklab,+ linearToOklab,+ mat3Apply,+ mat3Inv,+ mat3Mul,+ oklabMatrices,+ oklabToLch,+ oklabToLinear,+ planckianXy,+ pqDecode,+ pqEncode,+ rgbToRgbMatrix,+ rgbToXyzMatrix,+ sdrToHlg,+ sdrToPq,+ uvToXy,+ whiteBalanceMatrix,+ xyToUv,+ xyzToRgbMatrix,+} from "./colorSpace";++const near = (a: number[], b: number[], eps: number) => {+ expect(a.length).toBe(b.length);+ for (let i = 0; i < a.length; i++) expect(Math.abs(a[i] - b[i])).toBeLessThanOrEqual(eps);+};++describe("matrices", () => {+ test("inverse and product agree with identity", () => {+ const m = rgbToXyzMatrix(REC709_PRIMARIES);+ near(mat3Mul(m, mat3Inv(m)), MAT3_IDENTITY, 1e-12);+ near(mat3Mul(xyzToRgbMatrix(REC709_PRIMARIES), m), MAT3_IDENTITY, 1e-12);+ });++ test("the luminance row of a primaries matrix is its channel weights", () => {+ const m = rgbToXyzMatrix(REC709_PRIMARIES);+ near([m[3], m[4], m[5]], [0.2126, 0.7152, 0.0722], 1e-4);+ const m2020 = rgbToXyzMatrix(REC2020_PRIMARIES);+ near([m2020[3], m2020[4], m2020[5]], [0.2627, 0.678, 0.0593], 1e-4);+ });++ test("white maps to the white point of its primaries", () => {+ for (const p of [REC709_PRIMARIES, REC2020_PRIMARIES, APPLE_WIDE_GAMUT_PRIMARIES]) {+ const [X, Y, Z] = mat3Apply(rgbToXyzMatrix(p), 1, 1, 1);+ const sum = X + Y + Z;+ near([X / sum, Y / sum], D65, 1e-6);+ expect(Math.abs(Y - 1)).toBeLessThan(1e-9);+ }+ });++ test("Rec.709 to Rec.2020 is the BT.2087 matrix", () => {+ const m = rgbToRgbMatrix(REC709_PRIMARIES, REC2020_PRIMARIES);+ near(m, [0.6274, 0.3293, 0.0433, 0.0691, 0.9195, 0.0114, 0.0164, 0.088, 0.8956], 5e-4);+ });++ test("chromatic adaptation to the same white is identity, and D65 to D50 is the Bradford matrix", () => {+ near(chromaticAdaptation(D65, D65), MAT3_IDENTITY, 1e-12);+ near(chromaticAdaptation(D65, D65, CAT02), MAT3_IDENTITY, 1e-12);+ const m = chromaticAdaptation(D65, [0.3457, 0.3585], BRADFORD);+ // Lindbloom's D65 → D50 Bradford matrix.+ near(m, [1.0478, 0.0229, -0.0501, 0.0295, 0.9905, -0.0171, -0.0092, 0.0151, 0.7517], 2e-3);+ });+});++describe("Apple Log", () => {+ test("18% grey encodes near 48.8% and the curve is continuous at its joins", () => {+ expect(Math.abs(appleLogEncode(0.18) - 0.4883)).toBeLessThan(1e-3);+ const Rt = 0.01;+ const Pt = appleLogEncode(Rt);+ expect(Math.abs(appleLogEncode(Rt - 1e-9) - appleLogEncode(Rt + 1e-9))).toBeLessThan(1e-6);+ expect(Math.abs(appleLogDecode(Pt - 1e-9) - appleLogDecode(Pt + 1e-9))).toBeLessThan(1e-6);+ });++ test("decode inverts encode across the range, including below black", () => {+ for (const r of [-0.05, -0.01, 0, 0.005, 0.01, 0.05, 0.18, 1, 4, 16]) {+ expect(Math.abs(appleLogDecode(appleLogEncode(r)) - r)).toBeLessThan(1e-9 + Math.abs(r) * 1e-9);+ }+ expect(appleLogDecode(0)).toBeLessThan(0);+ });+});++describe("display curves", () => {+ test("BT.1886 round trips and pins its ends", () => {+ expect(bt1886Decode(0)).toBe(0);+ expect(bt1886Decode(1)).toBeCloseTo(1, 12);+ for (const v of [0.05, 0.2, 0.5, 0.9]) expect(Math.abs(bt1886Encode(bt1886Decode(v)) - v)).toBeLessThan(1e-9);+ });++ test("HLG OETF pins 1/12 → 0.5, 1 → 1, and inverts", () => {+ expect(hlgOetf(1 / 12)).toBeCloseTo(0.5, 9);+ expect(hlgOetf(1)).toBeCloseTo(1, 6);+ for (const s of [0.1, 0.5, 0.75, 0.9]) expect(Math.abs(hlgOetf(hlgOetfInverse(s)) - s)).toBeLessThan(1e-9);+ });++ test("HLG OOTF puts scene white at the peak and inverts", () => {+ const [r] = hlgOotf(1, 1, 1, 1000);+ expect(r).toBeCloseTo(1000, 6);+ const back = hlgOotfInverse(...hlgOotf(0.2, 0.4, 0.1, 1000), 1000);+ near(back, [0.2, 0.4, 0.1], 1e-9);+ });++ test("PQ pins 10000 nits at 1.0, 100 nits near 0.508, and inverts", () => {+ expect(pqEncode(10000)).toBeCloseTo(1, 9);+ expect(Math.abs(pqEncode(100) - 0.5081)).toBeLessThan(1e-3);+ for (const n of [0.5, 10, 203, 1000]) expect(Math.abs(pqDecode(pqEncode(n)) - n)).toBeLessThan(1e-6 * n);+ });+});++describe("BT.2408 SDR in HDR", () => {+ test("Rec.709 white lands at 75% HLG and 203 nits PQ", () => {+ expect(BT2408_REFERENCE_WHITE_NITS).toBe(203);+ near(sdrToHlg(1, 1, 1), [BT2408_HLG_WHITE, BT2408_HLG_WHITE, BT2408_HLG_WHITE], 2e-4);+ near(sdrToPq(1, 1, 1), [pqEncode(203), pqEncode(203), pqEncode(203)], 1e-9);+ expect(HLG_SCENE_WHITE).toBeCloseTo(hlgOetfInverse(0.75), 12);+ });++ test("a neutral stays neutral through the container change", () => {+ const [r, g, b] = sdrToHlg(0.18, 0.18, 0.18);+ expect(Math.abs(r - g)).toBeLessThan(1e-6);+ expect(Math.abs(g - b)).toBeLessThan(1e-6);+ });+});++describe("illuminants", () => {+ test("the Planckian locus passes near D65 at 6504 K and warms toward 3200 K", () => {+ near(planckianXy(D65_KELVIN), D65, 6e-3);+ const warm = planckianXy(3200);+ expect(warm[0]).toBeGreaterThan(D65[0]);+ expect(warm[1]).toBeGreaterThan(D65[1]);+ });++ test("uv and xy convert both ways", () => {+ const [u, v] = xyToUv(...D65);+ near(uvToXy(u, v), D65, 1e-12);+ });++ test("a mired shift walks warm, a Δuv walks green", () => {+ const warmer = illuminantXy(50, 0);+ const cooler = illuminantXy(-50, 0);+ expect(warmer[0]).toBeGreaterThan(D65[0]);+ expect(cooler[0]).toBeLessThan(D65[0]);+ near(illuminantXy(0, 0), D65, 1e-9);+ const green = illuminantXy(0, 0.02);+ // Above the locus (positive Δuv) is toward green: higher y for its x.+ expect(green[1]).toBeGreaterThan(D65[1]);+ });++ test("white balance neutralizes the assumed illuminant", () => {+ const assumed = planckianXy(4000);+ const m = whiteBalanceMatrix(REC709_PRIMARIES, assumed);+ // A surface lit by 4000 K reads warm in Rec.709; the matrix returns it to grey.+ const lit = mat3Apply(xyzToRgbMatrix(REC709_PRIMARIES), assumed[0] / assumed[1], 1, (1 - assumed[0] - assumed[1]) / assumed[1]);+ expect(lit[0]).toBeGreaterThan(lit[2]);+ const out = mat3Apply(m, lit[0], lit[1], lit[2]);+ expect(Math.abs(out[0] - out[1])).toBeLessThan(2e-2);+ expect(Math.abs(out[1] - out[2])).toBeLessThan(2e-2);+ near(whiteBalanceMatrix(REC709_PRIMARIES, D65), MAT3_IDENTITY, 1e-9);+ });+});++describe("Oklab", () => {+ test("white is L=1 with no chroma and colors round trip", () => {+ const { toLms, fromLms } = oklabMatrices(REC709_PRIMARIES);+ const white = linearToOklab(toLms, 1, 1, 1);+ expect(Math.abs(white[0] - 1)).toBeLessThan(1e-4);+ expect(Math.abs(white[1])).toBeLessThan(1e-3);+ expect(Math.abs(white[2])).toBeLessThan(1e-3);+ for (const c of [[0.2, 0.5, 0.8], [1, 0, 0], [0.05, 0.05, 0.05]] as const) {+ const lab = linearToOklab(toLms, c[0], c[1], c[2]);+ near(oklabToLinear(fromLms, lab[0], lab[1], lab[2]), [...c], 1e-9);+ const lch = oklabToLch(lab[0], lab[1], lab[2]);+ near(lchToOklab(lch[0], lch[1], lch[2]), lab, 1e-12);+ }+ });++ test("Rec.709 red matches the published Oklab coordinates", () => {+ const { toLms } = oklabMatrices(REC709_PRIMARIES);+ near(linearToOklab(toLms, 1, 0, 0), [0.628, 0.2249, 0.1258], 1e-3);+ });+});diff --git a/site/packages/effects-kit/src/colorSpace.ts b/site/packages/effects-kit/src/colorSpace.tsnew file mode 100644index 00000000..5d8f35e4--- /dev/null+++ b/site/packages/effects-kit/src/colorSpace.ts@@ -0,0 +1,446 @@+/**+ * Color science primitives, each one a published standard: Apple Log, the+ * Rec.709 / Rec.2020 / P3 / Apple Wide Gamut / ACES primaries and their XYZ+ * matrices, BT.1886, BT.2100 HLG and PQ, the BT.2408 SDR-in-HDR mapping,+ * CAT02 and Bradford chromatic adaptation, the Planckian locus for white+ * balance, and Oklab. Every transform in the grade pipeline is built from+ * these; nothing here is tuned by eye.+ *+ * Matrices are 9 numbers, row-major, applied to column vectors: out_i =+ * Σ_j M[i*3+j] · v_j.+ */++/* ------------------------------------------------------------------ */+/* Profiles */+/* ------------------------------------------------------------------ */++/** What a clip's code values mean. The first two need no conversion; the+ * rest go through a scene-linear decode and the ACES 2.0 output transform. */+export type SourceProfile = "rec709" | "srgb" | "apple-log" | "apple-log-2" | "hlg" | "pq";++export const SOURCE_PROFILES: { id: SourceProfile; label: string; detail: string }[] = [+ { id: "rec709", label: "Rec.709", detail: "Display-referred video; no conversion." },+ { id: "srgb", label: "sRGB", detail: "Screen recordings and images; no conversion." },+ { id: "apple-log", label: "Apple Log", detail: "iPhone ProRes Log in the Rec.2020 gamut." },+ { id: "apple-log-2", label: "Apple Log 2", detail: "iPhone Log in the Apple Wide Gamut." },+ { id: "hlg", label: "HLG", detail: "Rec.2100 hybrid log-gamma HDR video." },+ { id: "pq", label: "PQ", detail: "Rec.2100 PQ (HDR10) video." },+];++/** The project's delivery space. */+export type OutputSpace = "sdr" | "hlg" | "pq";++export const OUTPUT_SPACES: { id: OutputSpace; label: string; detail: string }[] = [+ { id: "sdr", label: "SDR", detail: "Rec.709, BT.1886, 100 nits." },+ { id: "hlg", label: "HDR (HLG)", detail: "Rec.2100 HLG, 1000-nit reference display." },+ { id: "pq", label: "HDR (PQ)", detail: "Rec.2100 PQ, 1000-nit reference display." },+];++/** How a file's Y'CbCr code values decode to R'G'B'. */+export interface CodeFormat {+ matrix: "bt709" | "bt601" | "bt2020nc";+ fullRange: boolean;+ bitDepth: number;+}++/* ------------------------------------------------------------------ */+/* Matrices */+/* ------------------------------------------------------------------ */++export type Mat3 = number[];++export const MAT3_IDENTITY: Mat3 = [1, 0, 0, 0, 1, 0, 0, 0, 1];++export function mat3Mul(a: Mat3, b: Mat3): Mat3 {+ const out = new Array<number>(9);+ for (let i = 0; i < 3; i++)+ for (let j = 0; j < 3; j++)+ out[i * 3 + j] = a[i * 3] * b[j] + a[i * 3 + 1] * b[3 + j] + a[i * 3 + 2] * b[6 + j];+ return out;+}++export function mat3Inv(m: Mat3): Mat3 {+ const [a, b, c, d, e, f, g, h, i] = m;+ const A = e * i - f * h;+ const B = -(d * i - f * g);+ const C = d * h - e * g;+ const det = a * A + b * B + c * C;+ if (Math.abs(det) < 1e-18) throw new Error("singular matrix");+ const s = 1 / det;+ return [+ A * s,+ -(b * i - c * h) * s,+ (b * f - c * e) * s,+ B * s,+ (a * i - c * g) * s,+ -(a * f - c * d) * s,+ C * s,+ -(a * h - b * g) * s,+ (a * e - b * d) * s,+ ];+}++export function mat3Apply(m: Mat3, r: number, g: number, b: number): [number, number, number] {+ return [+ m[0] * r + m[1] * g + m[2] * b,+ m[3] * r + m[4] * g + m[5] * b,+ m[6] * r + m[7] * g + m[8] * b,+ ];+}++export function mat3Diag(x: number, y: number, z: number): Mat3 {+ return [x, 0, 0, 0, y, 0, 0, 0, z];+}++/* ------------------------------------------------------------------ */+/* Primaries */+/* ------------------------------------------------------------------ */++export interface Primaries {+ r: [number, number];+ g: [number, number];+ b: [number, number];+ w: [number, number];+}++export const D65: [number, number] = [0.3127, 0.329];+/** The ACES white point (~D60). */+export const ACES_WHITE: [number, number] = [0.32168, 0.33767];++export const REC709_PRIMARIES: Primaries = { r: [0.64, 0.33], g: [0.3, 0.6], b: [0.15, 0.06], w: D65 };+export const REC2020_PRIMARIES: Primaries = { r: [0.708, 0.292], g: [0.17, 0.797], b: [0.131, 0.046], w: D65 };+export const P3D65_PRIMARIES: Primaries = { r: [0.68, 0.32], g: [0.265, 0.69], b: [0.15, 0.06], w: D65 };+/** Apple Wide Gamut, the container of Apple Log 2 (Apple Log 2 white paper). */+export const APPLE_WIDE_GAMUT_PRIMARIES: Primaries = {+ r: [0.725, 0.301],+ g: [0.221, 0.814],+ b: [0.068, -0.076],+ w: D65,+};+export const AP0_PRIMARIES: Primaries = { r: [0.7347, 0.2653], g: [0, 1], b: [0.0001, -0.077], w: ACES_WHITE };+export const AP1_PRIMARIES: Primaries = { r: [0.713, 0.293], g: [0.165, 0.83], b: [0.128, 0.044], w: ACES_WHITE };++export function xyToXYZ(x: number, y: number, Y = 1): [number, number, number] {+ return [(x * Y) / y, Y, ((1 - x - y) * Y) / y];+}++/** RGB → XYZ for a set of primaries, derived from their chromaticities so+ * the white maps to XYZ with Y = 1. */+export function rgbToXyzMatrix(p: Primaries): Mat3 {+ const P: Mat3 = [+ p.r[0], p.g[0], p.b[0],+ p.r[1], p.g[1], p.b[1],+ 1 - p.r[0] - p.r[1], 1 - p.g[0] - p.g[1], 1 - p.b[0] - p.b[1],+ ];+ const W = xyToXYZ(p.w[0], p.w[1]);+ const S = mat3Apply(mat3Inv(P), W[0], W[1], W[2]);+ return mat3Mul(P, mat3Diag(S[0], S[1], S[2]));+}++export function xyzToRgbMatrix(p: Primaries): Mat3 {+ return mat3Inv(rgbToXyzMatrix(p));+}++/* ------------------------------------------------------------------ */+/* Chromatic adaptation */+/* ------------------------------------------------------------------ */++/** CAT02 cone response matrix (CIECAM02). */+export const CAT02: Mat3 = [0.7328, 0.4296, -0.1624, -0.7036, 1.6975, 0.0061, 0.003, 0.0136, 0.9834];+/** Bradford cone response matrix, the ACES convention for gamut matrices. */+export const BRADFORD: Mat3 = [0.8951, 0.2664, -0.1614, -0.7502, 1.7135, 0.0367, 0.0389, -0.0685, 1.0296];++/** A von Kries adaptation in XYZ from one white to another through the given+ * cone response matrix. */+export function chromaticAdaptation(from: [number, number], to: [number, number], cone: Mat3 = CAT02): Mat3 {+ const src = xyToXYZ(from[0], from[1]);+ const dst = xyToXYZ(to[0], to[1]);+ const s = mat3Apply(cone, src[0], src[1], src[2]);+ const d = mat3Apply(cone, dst[0], dst[1], dst[2]);+ return mat3Mul(mat3Inv(cone), mat3Mul(mat3Diag(d[0] / s[0], d[1] / s[1], d[2] / s[2]), cone));+}++/** RGB → RGB between two sets of primaries, adapting the white with the+ * given cone matrix when the whites differ. */+export function rgbToRgbMatrix(from: Primaries, to: Primaries, cone: Mat3 = BRADFORD): Mat3 {+ const sameWhite = from.w[0] === to.w[0] && from.w[1] === to.w[1];+ const cat = sameWhite ? MAT3_IDENTITY : chromaticAdaptation(from.w, to.w, cone);+ return mat3Mul(xyzToRgbMatrix(to), mat3Mul(cat, rgbToXyzMatrix(from)));+}++/* ------------------------------------------------------------------ */+/* Apple Log */+/* ------------------------------------------------------------------ */++const AL_R0 = -0.05641088;+const AL_RT = 0.01;+const AL_C = 47.28711236;+const AL_BETA = 0.00964052;+const AL_GAMMA = 0.08550479;+const AL_DELTA = 0.69336945;+const AL_PT = AL_C * (AL_RT - AL_R0) * (AL_RT - AL_R0);++/** Apple Log code value → scene-linear (18% grey at 0.18). Constants from the+ * Apple Log white paper, as carried in OCIO and ACES. */+export function appleLogDecode(p: number): number {+ if (p >= AL_PT) return Math.pow(2, (p - AL_DELTA) / AL_GAMMA) - AL_BETA;+ if (p >= 0) return Math.sqrt(p / AL_C) + AL_R0;+ return AL_R0;+}++/** Scene-linear → Apple Log code value. */+export function appleLogEncode(r: number): number {+ if (r >= AL_RT) return AL_GAMMA * Math.log2(r + AL_BETA) + AL_DELTA;+ if (r >= AL_R0) return AL_C * (r - AL_R0) * (r - AL_R0);+ return 0;+}++/* ------------------------------------------------------------------ */+/* Transfer functions */+/* ------------------------------------------------------------------ */++/** Signed power: negative inputs mirror, so an out-of-range intermediate+ * value stays continuous through an encode and the final clamp decides. */+export function spow(x: number, e: number): number {+ return x < 0 ? -Math.pow(-x, e) : Math.pow(x, e);+}++/** BT.1886 EOTF, L = a·(V + b)^2.4 with Lw = 1, Lb = 0. */+export function bt1886Decode(v: number): number {+ return spow(v, 2.4);+}++export function bt1886Encode(l: number): number {+ return spow(l, 1 / 2.4);+}++const HLG_A = 0.17883277;+const HLG_B = 0.28466892;+const HLG_C = 0.55991073;++/** BT.2100 HLG OETF: scene-linear (0..1) → signal. */+export function hlgOetf(e: number): number {+ if (e <= 0) return 0;+ return e <= 1 / 12 ? Math.sqrt(3 * e) : HLG_A * Math.log(12 * e - HLG_B) + HLG_C;+}++/** BT.2100 HLG inverse OETF: signal → scene-linear. */+export function hlgOetfInverse(s: number): number {+ if (s <= 0) return 0;+ return s <= 0.5 ? (s * s) / 3 : (Math.exp((s - HLG_C) / HLG_A) + HLG_B) / 12;+}++/** BT.2100 HLG system gamma for a display of the given peak (1.2 at 1000 nits). */+export function hlgGamma(peakNits = 1000): number {+ return 1.2 + 0.42 * Math.log10(peakNits / 1000);+}++const REC2020_LUMA = [0.2627, 0.678, 0.0593];++/** BT.2100 HLG OOTF: scene-linear RGB → display light in nits. */+export function hlgOotf(r: number, g: number, b: number, peakNits = 1000): [number, number, number] {+ const ys = REC2020_LUMA[0] * r + REC2020_LUMA[1] * g + REC2020_LUMA[2] * b;+ const k = ys > 0 ? peakNits * Math.pow(ys, hlgGamma(peakNits) - 1) : 0;+ return [k * r, k * g, k * b];+}++/** BT.2100 HLG inverse OOTF: display light in nits → scene-linear RGB. */+export function hlgOotfInverse(r: number, g: number, b: number, peakNits = 1000): [number, number, number] {+ const yd = REC2020_LUMA[0] * r + REC2020_LUMA[1] * g + REC2020_LUMA[2] * b;+ if (yd <= 0) return [0, 0, 0];+ const gamma = hlgGamma(peakNits);+ const k = Math.pow(yd / peakNits, (1 - gamma) / gamma) / peakNits;+ return [k * r, k * g, k * b];+}++const PQ_M1 = 0.1593017578125;+const PQ_M2 = 78.84375;+const PQ_C1 = 0.8359375;+const PQ_C2 = 18.8515625;+const PQ_C3 = 18.6875;++/** SMPTE ST 2084 EOTF: signal → nits. */+export function pqDecode(n: number): number {+ if (n <= 0) return 0;+ const np = Math.pow(n, 1 / PQ_M2);+ const l = Math.max(0, np - PQ_C1) / (PQ_C2 - PQ_C3 * np);+ return Math.pow(l, 1 / PQ_M1) * 10000;+}++/** SMPTE ST 2084 inverse EOTF: nits → signal. */+export function pqEncode(nits: number): number {+ if (nits <= 0) return 0;+ const lm = Math.pow(nits / 10000, PQ_M1);+ return Math.pow((PQ_C1 + PQ_C2 * lm) / (1 + PQ_C3 * lm), PQ_M2);+}++/* ------------------------------------------------------------------ */+/* BT.2408: SDR inside an HDR container */+/* ------------------------------------------------------------------ */++/** Reference white for SDR graphics and video placed in HDR (BT.2408). */+export const BT2408_REFERENCE_WHITE_NITS = 203;+/** HLG signal at reference white: 75%. */+export const BT2408_HLG_WHITE = 0.75;+/** HLG scene-linear value at reference white; the scale between the HLG+ * scene and a scene where diffuse white is 1.0. */+export const HLG_SCENE_WHITE = hlgOetfInverse(BT2408_HLG_WHITE);++const REC709_TO_REC2020 = rgbToRgbMatrix(REC709_PRIMARIES, REC2020_PRIMARIES);++/** Rec.709 display-linear (1.0 = 100 nits) → Rec.2020 display light in nits+ * with SDR white at 203 nits. */+export function sdrToHdrNits(r: number, g: number, b: number): [number, number, number] {+ const k = BT2408_REFERENCE_WHITE_NITS;+ return mat3Apply(REC709_TO_REC2020, r * k, g * k, b * k);+}++/** Rec.709 display-linear → Rec.2100 HLG signal (BT.2408: white at 75%). */+export function sdrToHlg(r: number, g: number, b: number): [number, number, number] {+ const [rd, gd, bd] = sdrToHdrNits(r, g, b);+ const [rs, gs, bs] = hlgOotfInverse(rd, gd, bd, 1000);+ return [hlgOetf(rs), hlgOetf(gs), hlgOetf(bs)];+}++/** Rec.709 display-linear → Rec.2100 PQ signal (BT.2408: white at 203 nits). */+export function sdrToPq(r: number, g: number, b: number): [number, number, number] {+ const [rd, gd, bd] = sdrToHdrNits(r, g, b);+ return [pqEncode(rd), pqEncode(gd), pqEncode(bd)];+}++/* ------------------------------------------------------------------ */+/* White balance: the Planckian locus and its isotherms */+/* ------------------------------------------------------------------ */++/** CIE 1931 chromaticity of a Planckian radiator (Kim et al. 2002; valid+ * 1667–25000 K). */+export function planckianXy(kelvin: number): [number, number] {+ const T = Math.max(1667, Math.min(25000, kelvin));+ const t2 = T * T;+ const t3 = t2 * T;+ const x =+ T <= 4000+ ? -0.2661239e9 / t3 - 0.234358e6 / t2 + 0.8776956e3 / T + 0.17991+ : -3.0258469e9 / t3 + 2.1070379e6 / t2 + 0.2226347e3 / T + 0.24039;+ const x2 = x * x;+ const x3 = x2 * x;+ const y =+ T <= 2222+ ? -1.1063814 * x3 - 1.3481102 * x2 + 2.18555832 * x - 0.20219683+ : T <= 4000+ ? -0.9549476 * x3 - 1.37418593 * x2 + 2.09137015 * x - 0.16748867+ : 3.081758 * x3 - 5.8733867 * x2 + 3.75112997 * x - 0.37001483;+ return [x, y];+}++export function xyToUv(x: number, y: number): [number, number] {+ const d = -2 * x + 12 * y + 3;+ return [(4 * x) / d, (6 * y) / d];+}++export function uvToXy(u: number, v: number): [number, number] {+ const d = 2 * u - 8 * v + 4;+ return [(3 * u) / d, (2 * v) / d];+}++export const D65_KELVIN = 6504;++/**+ * The chromaticity of an illuminant described by a mired shift from D65 and a+ * distance along the isotherm, in CIE 1960 uv: the locus point moves with the+ * mired shift, and Δuv (positive toward green) walks the isotherm, the normal+ * to the locus at that temperature. D65 itself sits a little off the+ * Planckian locus, so the walk is relative to its own position.+ */+export function illuminantXy(miredShift: number, duv: number): [number, number] {+ const mired = 1e6 / D65_KELVIN + miredShift;+ const kelvin = 1e6 / Math.max(40, mired);+ const [xd, yd] = D65;+ const [ud, vd] = xyToUv(xd, yd);+ const at = (k: number) => {+ const [x, y] = planckianXy(k);+ return xyToUv(x, y);+ };+ const [u0, v0] = at(D65_KELVIN);+ const [u1, v1] = at(kelvin);+ // Tangent along increasing mired (toward warm); the normal points to the+ // green side, above the locus in uv.+ const [ua, va] = at(1e6 / (1e6 / kelvin - 1));+ const [ub, vb] = at(1e6 / (1e6 / kelvin + 1));+ let nu = -(vb - va);+ let nv = ub - ua;+ const len = Math.hypot(nu, nv) || 1;+ nu /= len;+ nv /= len;+ if (nv < 0) {+ nu = -nu;+ nv = -nv;+ }+ const u = ud + (u1 - u0) + duv * nu;+ const v = vd + (v1 - v0) + duv * nv;+ return uvToXy(u, v);+}++/**+ * The RGB matrix that neutralizes an illuminant: a CAT02 adaptation from the+ * assumed scene white to D65, wrapped in the container primaries. A warm+ * result comes from assuming a cool light, so a positive mired shift on the+ * slider means the assumed illuminant sits that many mireds *below* D65.+ */+export function whiteBalanceMatrix(primaries: Primaries, assumed: [number, number]): Mat3 {+ const cat = chromaticAdaptation(assumed, D65, CAT02);+ return mat3Mul(xyzToRgbMatrix(primaries), mat3Mul(cat, rgbToXyzMatrix(primaries)));+}++/* ------------------------------------------------------------------ */+/* Oklab (Björn Ottosson, CSS Color 4) */+/* ------------------------------------------------------------------ */++const OK_M1_XYZ: Mat3 = [+ 0.8189330101, 0.3618667424, -0.1288597137,+ 0.0329845436, 0.9293118715, 0.0361456387,+ 0.0482003018, 0.2643662691, 0.633851707,+];+const OK_M2: Mat3 = [+ 0.2104542553, 0.793617785, -0.0040720468,+ 1.9779984951, -2.428592205, 0.4505937099,+ 0.0259040371, 0.7827717662, -0.808675766,+];+const OK_M2_INV = mat3Inv(OK_M2);+const OK_M1_XYZ_INV = mat3Inv(OK_M1_XYZ);++/** LMS' → Lab and back, for callers that inline the conversion. */+export { OK_M2 as OKLAB_M2, OK_M2_INV as OKLAB_M2_INV };++/** Linear RGB in the given primaries → Oklab, through XYZ (D65). */+export function oklabMatrices(p: Primaries): { toLms: Mat3; fromLms: Mat3 } {+ const toLms = mat3Mul(OK_M1_XYZ, rgbToXyzMatrix(p));+ return { toLms, fromLms: mat3Inv(toLms) };+}++export function linearToOklab(toLms: Mat3, r: number, g: number, b: number): [number, number, number] {+ const l = Math.cbrt(toLms[0] * r + toLms[1] * g + toLms[2] * b);+ const m = Math.cbrt(toLms[3] * r + toLms[4] * g + toLms[5] * b);+ const s = Math.cbrt(toLms[6] * r + toLms[7] * g + toLms[8] * b);+ return mat3Apply(OK_M2, l, m, s);+}++export function oklabToLinear(fromLms: Mat3, L: number, a: number, b: number): [number, number, number] {+ const [l, m, s] = mat3Apply(OK_M2_INV, L, a, b);+ return mat3Apply(fromLms, l * l * l, m * m * m, s * s * s);+}++export { OK_M1_XYZ_INV as OKLAB_LMS_TO_XYZ };++/** Oklab → OkLCh: hue in degrees [0, 360). */+export function oklabToLch(L: number, a: number, b: number): [number, number, number] {+ const c = Math.hypot(a, b);+ let h = (Math.atan2(b, a) * 180) / Math.PI;+ if (h < 0) h += 360;+ return [L, c, h];+}++export function lchToOklab(L: number, c: number, h: number): [number, number, number] {+ const rad = (h * Math.PI) / 180;+ return [L, c * Math.cos(rad), c * Math.sin(rad)];+}diff --git a/site/packages/effects-kit/src/detail.test.ts b/site/packages/effects-kit/src/detail.test.tsnew file mode 100644index 00000000..2e29c708--- /dev/null+++ b/site/packages/effects-kit/src/detail.test.ts@@ -0,0 +1,123 @@+import { describe, expect, test } from "bun:test";+import { applyDetail, detailActive, detailGain, detailRadius, gaussianBlur } from "./detail";++/** A w×h RGBA frame from a luma function, grey. */+function frame(w: number, h: number, f: (x: number, y: number) => number): Uint8ClampedArray {+ const px = new Uint8ClampedArray(w * h * 4);+ for (let y = 0; y < h; y++)+ for (let x = 0; x < w; x++) {+ const v = Math.max(0, Math.min(255, Math.round(f(x, y) * 255)));+ const o = (y * w + x) * 4;+ px[o] = v;+ px[o + 1] = v;+ px[o + 2] = v;+ px[o + 3] = 255;+ }+ return px;+}++describe("settings", () => {+ test("gain scales with the slider and radii scale with the frame", () => {+ expect(detailGain("sharpen", 0)).toBe(0);+ expect(detailGain("sharpen", 50)).toBe(1.5);+ expect(detailGain("clarity", 25)).toBeCloseTo(0.75, 9);+ expect(detailRadius("sharpen", 1080)).toBe(1);+ expect(detailRadius("sharpen", 2160)).toBe(2);+ expect(detailRadius("clarity", 1080)).toBe(24);+ expect(detailRadius("clarity", 540)).toBe(12);+ expect(detailActive(undefined)).toBe(false);+ expect(detailActive({ sharpen: 0 })).toBe(false);+ expect(detailActive({ clarity: 1 })).toBe(true);+ });+});++describe("gaussianBlur", () => {+ test("keeps a flat plane and smooths a step", () => {+ const w = 16;+ const h = 4;+ const flat = new Float32Array(w * h).fill(0.4);+ const tmp = new Float32Array(w * h);+ const out = new Float32Array(w * h);+ gaussianBlur(flat, w, h, 1, tmp, out);+ for (const v of out) expect(Math.abs(v - 0.4)).toBeLessThan(1e-6);+ const step = new Float32Array(w * h);+ for (let i = 0; i < w * h; i++) step[i] = i % w < 8 ? 0 : 1;+ gaussianBlur(step, w, h, 1, tmp, out);+ expect(out[7]).toBeGreaterThan(0);+ expect(out[8]).toBeLessThan(1);+ expect(out[0]).toBeLessThan(1e-3);+ expect(out[15]).toBeGreaterThan(1 - 1e-3);+ });+});++describe("applyDetail", () => {+ test("zero settings leave pixels alone and a flat frame stays flat", () => {+ const px = frame(32, 32, () => 0.5);+ const before = [...px];+ applyDetail(px, 32, 32, {});+ expect([...px]).toEqual(before);+ applyDetail(px, 32, 32, { sharpen: 50, clarity: 50 });+ expect([...px]).toEqual(before);+ });++ test("sharpen steepens an edge without moving the flat field", () => {+ const w = 64;+ const h = 64;+ const px = frame(w, h, (x) => (x < 32 ? 0.3 : 0.7));+ applyDetail(px, w, h, { sharpen: 50 });+ const at = (x: number) => px[(32 * w + x) * 4];+ // Overshoot on each side of the edge, the field far away untouched.+ expect(at(31)).toBeLessThan(Math.round(0.3 * 255));+ expect(at(32)).toBeGreaterThan(Math.round(0.7 * 255));+ expect(at(4)).toBe(Math.round(0.3 * 255));+ expect(at(60)).toBe(Math.round(0.7 * 255));+ });++ test("clarity lifts a soft feature and keeps a hard edge nearly free of halo", () => {+ const w = 256;+ const h = 256;+ // A flat field with a soft bump wider than the clarity window and a+ // four-pixel spike inside it.+ const px = frame(w, h, (x) => 0.5 + 0.15 * Math.exp(-((x - 100) ** 2) / 200) + (x >= 180 && x < 184 ? 0.25 : 0));+ const before = [...px];+ applyDetail(px, w, h, { clarity: 50 });+ const row = (x: number) => px[(128 * w + x) * 4];+ const was = (x: number) => before[(128 * w + x) * 4];+ expect(row(100)).toBeGreaterThan(was(100));+ expect(row(40)).toBe(was(40));+ expect(row(181)).toBeGreaterThan(was(181));+ // A hard step: the guided base follows the edge, so the overshoot beside+ // it stays under a third of what an unsharp mask at the same gain leaves.+ const step = frame(w, h, (x) => (x < 128 ? 0.3 : 0.7));+ applyDetail(step, w, h, { clarity: 50 });+ const at = (x: number) => step[(128 * w + x) * 4];+ const halo = Math.max(Math.round(0.3 * 255) - at(127), at(128) - Math.round(0.7 * 255));+ expect(halo).toBeGreaterThan(0);+ expect(halo).toBeLessThan((detailGain("clarity", 50) * 0.4 * 255) / 3);+ });++ test("detail lands on every channel equally, keeping hue", () => {+ const w = 64;+ const h = 64;+ const px = new Uint8ClampedArray(w * h * 4);+ for (let y = 0; y < h; y++)+ for (let x = 0; x < w; x++) {+ const o = (y * w + x) * 4;+ const dark = x < 32;+ px[o] = dark ? 60 : 180;+ px[o + 1] = dark ? 40 : 120;+ px[o + 2] = dark ? 20 : 60;+ px[o + 3] = 255;+ }+ const before = [...px];+ applyDetail(px, w, h, { sharpen: 30 });+ const o = (32 * w + 31) * 4;+ const dr = px[o] - before[o];+ const dg = px[o + 1] - before[o + 1];+ const db = px[o + 2] - before[o + 2];+ expect(dr).not.toBe(0);+ expect(Math.abs(dr - dg)).toBeLessThanOrEqual(1);+ expect(Math.abs(dg - db)).toBeLessThanOrEqual(1);+ expect(px[o + 3]).toBe(255);+ });+});diff --git a/site/packages/effects-kit/src/detail.ts b/site/packages/effects-kit/src/detail.tsnew file mode 100644index 00000000..994612c2--- /dev/null+++ b/site/packages/effects-kit/src/detail.ts@@ -0,0 +1,123 @@+/**+ * Sharpen and clarity: the two spatial controls, on luma only. Both add+ * back detail — the difference between the picture and a smoothed base —+ * with a gain. Sharpen's base is a Gaussian blur about a pixel wide, so it+ * lifts fine edges; clarity's base is a guided filter over a wide window,+ * edge-preserving, so it lifts local contrast without haloing the edges+ * (He, Sun and Tang, "Guided Image Filtering", the detail-enhancement use).+ * Radii scale with frame height so a setting reads the same at every+ * resolution. This is the CPU reference; the GPU and ffmpeg paths follow+ * the same radii and gains.+ */++import { guidedFilterRefine } from "./guidedFilter";+import { GRADE_MAX } from "./colorGrade";++/** Gaussian sigma of the sharpen base, as a fraction of frame height (one+ * pixel at 1080p). */+export const SHARPEN_SIGMA_FRAC = 1 / 1080;+/** Window radius of the clarity base, as a fraction of frame height. */+export const CLARITY_RADIUS_FRAC = 24 / 1080;+/** Edge threshold of the clarity guided filter, in squared luma. */+export const CLARITY_EPS = 0.01;+/** Detail gain at a full slider. */+export const SHARPEN_GAIN_AT_MAX = 1.5;+export const CLARITY_GAIN_AT_MAX = 1.5;++export function detailRadius(kind: "sharpen" | "clarity", frameHeight: number): number {+ return kind === "sharpen"+ ? Math.max(0.5, frameHeight * SHARPEN_SIGMA_FRAC)+ : Math.max(1, Math.round(frameHeight * CLARITY_RADIUS_FRAC));+}++export function detailGain(kind: "sharpen" | "clarity", slider: number): number {+ const t = Math.max(0, Math.min(GRADE_MAX, slider || 0)) / GRADE_MAX;+ return t * (kind === "sharpen" ? SHARPEN_GAIN_AT_MAX : CLARITY_GAIN_AT_MAX);+}++function gaussianKernel(sigma: number): Float32Array {+ const radius = Math.max(1, Math.ceil(sigma * 3));+ const k = new Float32Array(radius * 2 + 1);+ let sum = 0;+ for (let i = -radius; i <= radius; i++) {+ const v = Math.exp(-(i * i) / (2 * sigma * sigma));+ k[i + radius] = v;+ sum += v;+ }+ for (let i = 0; i < k.length; i++) k[i] /= sum;+ return k;+}++/** Separable Gaussian blur of a plane into `out` through `tmp`. */+export function gaussianBlur(src: Float32Array, w: number, h: number, sigma: number, tmp: Float32Array, out: Float32Array): void {+ const k = gaussianKernel(sigma);+ const r = (k.length - 1) >> 1;+ for (let y = 0; y < h; y++) {+ const row = y * w;+ for (let x = 0; x < w; x++) {+ let acc = 0;+ for (let i = -r; i <= r; i++) {+ const xx = x + i < 0 ? 0 : x + i >= w ? w - 1 : x + i;+ acc += src[row + xx] * k[i + r];+ }+ tmp[row + x] = acc;+ }+ }+ for (let y = 0; y < h; y++) {+ for (let x = 0; x < w; x++) {+ let acc = 0;+ for (let i = -r; i <= r; i++) {+ const yy = y + i < 0 ? 0 : y + i >= h ? h - 1 : y + i;+ acc += tmp[yy * w + x] * k[i + r];+ }+ out[y * w + x] = acc;+ }+ }+}++export interface DetailSettings {+ sharpen?: number; // 0..50+ clarity?: number; // 0..50+}++/** True when the settings change any pixel. */+export function detailActive(d: DetailSettings | undefined | null): boolean {+ return !!d && (detailGain("sharpen", d.sharpen || 0) > 0 || detailGain("clarity", d.clarity || 0) > 0);+}++/**+ * Apply sharpen and clarity to RGBA pixels in place. Both details are taken+ * from the same input luma and added together, so the two controls do not+ * feed each other; the luma change lands on every channel equally, so hue+ * and saturation hold. Alpha passes through.+ */+export function applyDetail(px: Uint8ClampedArray, w: number, h: number, d: DetailSettings): void {+ const ks = detailGain("sharpen", d.sharpen || 0);+ const kc = detailGain("clarity", d.clarity || 0);+ if (!ks && !kc) return;+ const n = w * h;+ const luma = new Float32Array(n);+ for (let i = 0; i < n; i++) {+ luma[i] = (0.2126 * px[i * 4] + 0.7152 * px[i * 4 + 1] + 0.0722 * px[i * 4 + 2]) / 255;+ }+ const delta = new Float32Array(n);+ if (ks) {+ const tmp = new Float32Array(n);+ const base = new Float32Array(n);+ gaussianBlur(luma, w, h, detailRadius("sharpen", h), tmp, base);+ for (let i = 0; i < n; i++) delta[i] += ks * (luma[i] - base[i]);+ }+ if (kc) {+ const base = new Float32Array(luma);+ guidedFilterRefine(base, luma, w, h, detailRadius("clarity", h), CLARITY_EPS);+ for (let i = 0; i < n; i++) delta[i] += kc * (luma[i] - base[i]);+ }+ for (let i = 0; i < n; i++) {+ const dv = delta[i] * 255;+ if (!dv) continue;+ const o = i * 4;+ px[o] = Math.max(0, Math.min(255, Math.round(px[o] + dv)));+ px[o + 1] = Math.max(0, Math.min(255, Math.round(px[o + 1] + dv)));+ px[o + 2] = Math.max(0, Math.min(255, Math.round(px[o + 2] + dv)));+ }+}diff --git a/site/packages/effects-kit/src/effects.test.ts b/site/packages/effects-kit/src/effects.test.tsindex 70c96750..14f940fc 100644--- a/site/packages/effects-kit/src/effects.test.ts+++ b/site/packages/effects-kit/src/effects.test.ts@@ -1,5 +1,5 @@import { describe, expect, test } from "bun:test";-import { EFFECT_IDS, effectFilterLines, effectPreviewState } from "./effects";+import { codeScale, EFFECT_IDS, effectFilterLines, effectPreviewState } from "./effects";// The bundled engine ffmpeg is LGPL: a recipe reaching for a GPL-only filter// renders on a dev machine (Homebrew ffmpeg) and fails in the shipped app.@@ -61,6 +61,37 @@ describe("effect recipes", () => {}});+ test("the 8-bit code values in geq scale to a 10-bit composite", () => {+ expect(codeScale(8)).toBe(1);+ expect(codeScale(undefined)).toBe(1);+ expect(codeScale(10)).toBeCloseTo(1023 / 255, 9);+ const flash8 = effectFilterLines("in", "out", "flash", 1, 0, 1, 1920, 1080, "t")![0];+ const flash10 = effectFilterLines("in", "out", "flash", 1, 0, 1, 1920, 1080, "t", undefined, undefined, {+ pixFmt: "yuv420p10le",+ overlay: ":format=yuv420p10",+ depth: 10,+ })![0];+ expect(flash8).toContain("min(235,");+ expect(flash8).toContain("+200*exp(");+ expect(flash10).toContain("min(942.765,");+ expect(flash10).toContain("+802.353*exp(");+ const leak10 = effectFilterLines("in", "out", "lightleak", 1, 0, 1, 1920, 1080, "t", undefined, undefined, {+ pixFmt: "yuv420p10le",+ overlay: ":format=yuv420p10",+ depth: 10,+ })![0];+ expect(leak10).toContain("(942.765-lum(X,Y))");+ expect(leak10).toContain("cb(X,Y)-160.471*");+ expect(leak10).toContain("cr(X,Y)+104.306*");+ // A look effect hands the depth on to its chain.+ const hal10 = effectFilterLines("in", "out", "halation", 1, 0, 1, 1920, 1080, "t", undefined, undefined, {+ pixFmt: "yuv420p10le",+ overlay: ":format=yuv420p10",+ depth: 10,+ })!.join(";");+ expect(hal10).toContain("clip((val-641.882)*3,0,1023)");+ });+test("unknown ids return null instead of breaking the graph", () => {expect(effectFilterLines("in", "out", "nope", 1, 0, 1, 1080, 1920, "t")).toBe(null);});diff --git a/site/packages/effects-kit/src/effects.ts b/site/packages/effects-kit/src/effects.tsindex a6e08ea6..bfc7c9d9 100644--- a/site/packages/effects-kit/src/effects.ts+++ b/site/packages/effects-kit/src/effects.ts@@ -558,16 +558,27 @@ export function applyEffectToCanvas(* out of quoted expressions). */const gate = (a: number, b: number) => `enable='gte(t,${fmt(a)})*lt(t,${fmt(b)})'`;-/** The pixel family a chain works in: the format its branches carry, and the- * option that keeps `overlay` blending in the same one. A 4:2:0 graph is the- * default, which is what `overlay` picks on its own. */+/** The pixel family a chain works in: the format its branches carry, the+ * option that keeps `overlay` blending in the same one, and the bits a plane+ * holds — the recipes below are written in 8-bit code values and scale to+ * the plane's depth. A 4:2:0 8-bit graph is the default, which is what+ * `overlay` picks on its own. */export interface ChainChroma {pixFmt: string;overlay: string;+ /** Bits a plane; absent = 8. An HDR composite carries 10. */+ depth?: 8 | 10;}export const CHROMA_420: ChainChroma = { pixFmt: "yuv420p", overlay: "" };+/** The factor an 8-bit code value scales by to land on a plane of `depth`+ * bits: 1 at 8, (1023 / 255) at 10. */+export const codeScale = (depth: 8 | 10 | undefined): number => ((1 << (depth ?? 8)) - 1) / 255;++/** An 8-bit code value spelled at the chain's depth. */+const code = (v: number, depth: 8 | 10 | undefined): string => fmt(v * codeScale(depth));+/*** ffmpeg filter_complex lines rendering one effect from `[inLabel]` into* `[outLabel]`, active only inside [start, end). Every filter used is in the@@ -601,7 +612,7 @@ export function effectFilterLines(// The graded copy renders on its own branch and replaces the frame only// inside the window, the same shape the shake recipe uses — a look chain// is several filters deep and not all of them take a timeline gate.- const lines = lookFilterLines(`lkfi${tag}`, `lkfo${tag}`, look, k, height, chroma.pixFmt, tag);+ const lines = lookFilterLines(`lkfi${tag}`, `lkfo${tag}`, look, k, height, chroma.pixFmt, tag, chroma.depth);if (!lines) return null;return [`[${inLabel}]split[lkfb${tag}][lkfi${tag}]`,@@ -690,7 +701,7 @@ export function effectFilterLines(`colortemperature=temperature=${Math.round(6500 - 500 * k)}:${en},` +`vignette=angle=${fmt((k * Math.PI) / 5)}:mode=backward:` +`x0='w*(0.84-0.14*sin(t*0.9))':y0='h*(0.8-0.11*cos(t*0.6))':eval=frame:${en},` +- `geq=lum='lum(X,Y)+(235-lum(X,Y))*${G}':cb='cb(X,Y)-40*${G}':cr='cr(X,Y)+26*${G}':${en}[${outLabel}]`,+ `geq=lum='lum(X,Y)+(${code(235, chroma.depth)}-lum(X,Y))*${G}':cb='cb(X,Y)-${code(40, chroma.depth)}*${G}':cr='cr(X,Y)+${code(26, chroma.depth)}*${G}':${en}[${outLabel}]`,];}case "flash":@@ -698,7 +709,7 @@ export function effectFilterLines(// frame by geq — `T` is the frame's time, so the decay rides every// frame of the window.return [- `[${inLabel}]geq=lum='min(235,lum(X,Y)+${fmt(200 * k)}*exp(-9*(T-${fmt(start)})))':` ++ `[${inLabel}]geq=lum='min(${code(235, chroma.depth)},lum(X,Y)+${code(200 * k, chroma.depth)}*exp(-9*(T-${fmt(start)})))':` +`cb='cb(X,Y)':cr='cr(X,Y)':${en}[${outLabel}]`,];case "shake": {diff --git a/site/packages/effects-kit/src/gradeEval.test.ts b/site/packages/effects-kit/src/gradeEval.test.tsindex 281ff1fc..42b549dc 100644--- a/site/packages/effects-kit/src/gradeEval.test.ts+++ b/site/packages/effects-kit/src/gradeEval.test.ts@@ -1,5 +1,8 @@import { describe, expect, test } from "bun:test";-import { applyLutToImageData, buildGradeLut, type GradeLut } from "./gradeLut";+import { buildGradeLut } from "./colorPipeline";+import { bt1886Decode } from "./colorSpace";+import { applyLutToImageData, type GradeLut } from "./gradeLut";+import { createGradeTransform } from "./gradeMath";import { GRADE_PRESETS, type GradePreset } from "./gradePresets";/**@@ -24,6 +27,11 @@ import { GRADE_PRESETS, type GradePreset } from "./gradePresets";** Both tiers measure through the preset's real lookup table with the same* tetrahedral pass the preview, the export, and the worker apply.+ *+ * A third tier holds the slider physics: the light controls work in linear+ * light, so a stop of exposure doubles luminance, the highlight control+ * compresses without clipping, saturation keeps skin on its hue, and the+ * whole chart survives a neutral grade within a small color difference.*//** ColorChecker Classic, sRGB. */@@ -610,6 +618,115 @@ const IDENTITY: Record<string, Signature> = {},};+/* ------------------------------------------------------------------ */+/* Tier 3: slider physics */+/* ------------------------------------------------------------------ */++/** CIE ΔE76 between two sRGB colors, through Lab. */+function deltaE(a: number[], b: number[]): number {+ const lab = (c: number[]) => {+ const [r, g, bl] = c.map((v) => bt1886Decode(v / 255));+ const x = (0.4124 * r + 0.3576 * g + 0.1805 * bl) / 0.95047;+ const y = 0.2126 * r + 0.7152 * g + 0.0722 * bl;+ const z = (0.0193 * r + 0.1192 * g + 0.9505 * bl) / 1.08883;+ const f = (t: number) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);+ return [116 * f(y) - 16, 500 * (f(x) - f(y)), 200 * (f(y) - f(z))];+ };+ const p = lab(a);+ const q = lab(b);+ return Math.hypot(p[0] - q[0], p[1] - q[1], p[2] - q[2]);+}++describe("slider physics", () => {+ test("a stop of exposure doubles linear light on every grey", () => {+ const t = createGradeTransform({ exposure: 25 })!;+ for (const v of [0.1, 0.3, 0.5, 0.7]) {+ const out = t(v, v, v);+ expect(Math.abs(bt1886Decode(out[0]) / bt1886Decode(v) - 2)).toBeLessThan(1e-6);+ }+ });++ test("highlights at full never clip and keep the ramp in order, even a stop over", () => {+ for (const grade of [{ highlights: 50 }, { highlights: 50, exposure: 25 }, { highlights: -50 }]) {+ const t = createGradeTransform(grade)!;+ let prev = -1;+ for (let i = 0; i <= 255; i++) {+ const v = i / 255;+ const out = t(v, v, v)[0];+ expect(out).toBeGreaterThanOrEqual(prev - 1e-9);+ prev = out;+ }+ if (!("exposure" in grade)) {+ expect(t(1, 1, 1)[0]).toBeLessThanOrEqual(1 + 1e-9);+ // Highlights alone never push a value past white.+ expect(prev).toBeLessThanOrEqual(1 + 1e-9);+ }+ }+ });++ test("every light slider keeps the grey ramp monotone at both ends of its range", () => {+ for (const key of ["whites", "shadows", "blacks", "brilliance", "fade", "contrast", "exposure"] as const) {+ for (const value of [50, -50]) {+ const t = createGradeTransform({ [key]: value });+ if (!t) continue; // fade has no negative side+ let prev = -Infinity;+ for (let i = 0; i <= 255; i++) {+ const v = i / 255;+ const out = t(v, v, v)[0];+ expect(out).toBeGreaterThanOrEqual(prev - 1e-9);+ prev = out;+ }+ }+ }+ });++ test("saturation holds skin on its hue", () => {+ const lut = buildGradeLut({ saturation: 30 })!;+ const [dark, light] = through(lut, [CHART.darkSkin, CHART.lightSkin]);+ expect(hueDelta(hsv(CHART.darkSkin).h, hsv(dark).h)).toBeLessThanOrEqual(8);+ expect(hueDelta(hsv(CHART.lightSkin).h, hsv(light).h)).toBeLessThanOrEqual(8);+ expect(hsv(light).s).toBeGreaterThan(hsv(CHART.lightSkin).s);+ const down = buildGradeLut({ saturation: -50 })!;+ for (const c of through(down, [CHART.red, CHART.blue, CHART.lightSkin])) {+ expect(Math.max(...c) - Math.min(...c)).toBeLessThanOrEqual(2);+ }+ });++ test("a neutral-in-effect grade keeps the ColorChecker within a small ΔE", () => {+ // Opposing moves that cancel in linear light: contrast −20 is the 0.8+ // power about grey and +25 the 1.25 power, so the pair is an identity+ // that only the two lattices' quantization can disturb.+ const lut = buildGradeLut({ contrast: -20 }, 33)!;+ const back = buildGradeLut({ contrast: 25 }, 33)!;+ const once = through(lut, PATCHES.map((n) => CHART[n]));+ const px = new Uint8ClampedArray(once.length * 4);+ once.forEach((c, i) => {+ px[i * 4] = c[0];+ px[i * 4 + 1] = c[1];+ px[i * 4 + 2] = c[2];+ px[i * 4 + 3] = 255;+ });+ applyLutToImageData(px, back);+ let worst = 0;+ PATCHES.forEach((n, i) => {+ const dE = deltaE(CHART[n], [px[i * 4], px[i * 4 + 1], px[i * 4 + 2]]);+ worst = Math.max(worst, dE);+ });+ // A round trip through two 33³ lattices costs under 2.5 ΔE on any patch.+ expect(worst).toBeLessThan(2.5);+ });++ test("a preset at full strength stays within a colorist's ΔE budget of a small move", () => {+ // Every preset is a look, and a look is bounded: the mean chart shift+ // stays under ΔE 45 so nothing turns the picture into something else.+ for (const p of presets) {+ const m = measure(lutOf(p));+ const mean = PATCHES.reduce((a, n) => a + deltaE(CHART[n], m.patch[n]), 0) / PATCHES.length;+ expect(mean).toBeLessThan(45);+ }+ });+});+describe("every preset declares what it emulates", () => {test("the catalog and the identity table cover each other", () => {const catalog = presets.map((p) => p.id).sort();diff --git a/site/packages/effects-kit/src/gradeLut.test.ts b/site/packages/effects-kit/src/gradeLut.test.tsindex 12e810b9..3206d32d 100644--- a/site/packages/effects-kit/src/gradeLut.test.ts+++ b/site/packages/effects-kit/src/gradeLut.test.ts@@ -1,8 +1,17 @@import { describe, expect, test } from "bun:test";import type { ColorGrade } from "./colorGrade";-import { gradeNeedsLut, normalizeGrade } from "./colorGrade";-import { applyLutToImageData, buildGradeLut, gradeKey, lutToCube } from "./gradeLut";-import { createGradeTransform, curveLut, scaleGradeToward, skinWeight } from "./gradeMath";+import { normalizeGrade } from "./colorGrade";+import { buildGradeLut } from "./colorPipeline";+import { bt1886Encode } from "./colorSpace";+import { applyLutToImageData, gradeKey, lutToCube } from "./gradeLut";+import {+ CONTRAST_POWER_AT_MAX,+ EXPOSURE_STOPS_AT_MAX,+ createGradeTransform,+ curveLut,+ scaleGradeToward,+ skinWeight,+} from "./gradeMath";const px = (...rgb: [number, number, number][]): Uint8ClampedArray => {const data = new Uint8ClampedArray(rgb.length * 4);@@ -16,15 +25,17 @@ const px = (...rgb: [number, number, number][]): Uint8ClampedArray => {};describe("gradeKey", () => {- test("neutral is empty, key order is stable", () => {+ test("neutral is empty, key order is stable, spatial controls are left out", () => {expect(gradeKey(undefined)).toBe("");expect(gradeKey({ contrast: 0 })).toBe("");- expect(gradeKey({ contrast: 10, exposure: 5 })).toBe(gradeKey({ exposure: 5, contrast: 10 }));+ expect(gradeKey({ sharpen: 20 })).toBe("");+ expect(gradeKey({ contrast: 10, exposure: 5 })).toBe(gradeKey({ exposure: 5, contrast: 10, clarity: 30 }));});test("distinct grades get distinct keys", () => {expect(gradeKey({ contrast: 10 })).not.toBe(gradeKey({ contrast: 11 }));expect(gradeKey({ preset: { id: "mono" } })).not.toBe(gradeKey({ preset: { id: "silver" } }));+ expect(gradeKey({ lut: { id: "lut:a" } })).not.toBe(gradeKey({ lut: { id: "lut:a", amount: 0.5 } }));});});@@ -32,6 +43,7 @@ describe("buildGradeLut", () => {test("neutral grade builds no LUT", () => {expect(buildGradeLut(undefined)).toBe(null);expect(buildGradeLut({ contrast: 0 })).toBe(null);+ expect(buildGradeLut({ sharpen: 30 })).toBe(null);});test("an identity-adjacent grade stays near identity through the LUT", () => {@@ -63,7 +75,7 @@ describe("buildGradeLut", () => {const data = px(...samples);applyLutToImageData(data, lut);samples.forEach(([r, g, b], i) => {- const direct = transform(r / 255, g / 255, b / 255);+ const direct = transform(r / 255, g / 255, b / 255).map((v) => Math.max(0, Math.min(1, v)));for (let c = 0; c < 3; c++) {// Tetrahedral interpolation over a 33³ lattice of a smooth transform// lands within a few 8-bit steps of the exact evaluation.@@ -72,18 +84,22 @@ describe("buildGradeLut", () => {});});- test("fast-path scalar fields match the LUT within quantization", () => {- // gain + contrast are the exact fast-path formulas; a LUT-only render of- // them must agree with the direct math.- const grade: ColorGrade = { exposure: 10, contrast: 15, brightness: 5 };- const transform = createGradeTransform(grade)!;- const gain = (1 + 5 / 100) * Math.pow(2, 10 / 50);- const c = 1 + 15 / 100;- for (const v of [0.1, 0.4, 0.7]) {- const expected = Math.min(1, Math.max(0, (Math.min(1, v * gain) - 0.5) * c + 0.5));- const got = transform(v, v, v);- for (let ch = 0; ch < 3; ch++) expect(Math.abs(got[ch] - expected)).toBeLessThan(1e-6);- }+ test("exposure is stops of linear light and contrast pivots on 18% grey", () => {+ const grey = bt1886Encode(0.18);+ const stop = createGradeTransform({ exposure: 50 / EXPOSURE_STOPS_AT_MAX })!;+ for (let ch = 0; ch < 3; ch++) expect(Math.abs(stop(grey, grey, grey)[ch] - bt1886Encode(0.36))).toBeLessThan(1e-6);+ const contrast = createGradeTransform({ contrast: 50 })!;+ for (let ch = 0; ch < 3; ch++) expect(Math.abs(contrast(grey, grey, grey)[ch] - grey)).toBeLessThan(1e-6);+ // Full contrast is the 1.5 power about the pivot: a stop above grey lands+ // 1.5 stops above.+ const up = bt1886Encode(0.36);+ const out = contrast(up, up, up)[0];+ expect(Math.abs(out - bt1886Encode(0.18 * Math.pow(2, 1 + CONTRAST_POWER_AT_MAX)))).toBeLessThan(1e-6);+ });++ test("a brightness slider is a linear gain", () => {+ const t = createGradeTransform({ brightness: 20 })!;+ for (const v of [0.1, 0.4, 0.7]) expect(Math.abs(t(v, v, v)[0] - v * 1.2)).toBeLessThan(1e-6);});});@@ -121,6 +137,12 @@ describe("intensity", () => {for (let c = 0; c < 3; c++) expect(Math.abs(out[c] - v[c])).toBeLessThan(0.01);}});++ test("a preset turned all the way down stays applied and renders neutral", () => {+ const g = normalizeGrade({ preset: { id: "mono", amount: 0 } })!;+ expect(g.preset).toEqual({ id: "mono", amount: 0 });+ expect(buildGradeLut(g)).toBe(null);+ });});describe("skin protection", () => {@@ -134,7 +156,6 @@ describe("skin protection", () => {test("a skin-flagged preset damps color shifts on skin but grades the rest", () => {const grade: ColorGrade = { preset: { id: "teal-orange", skin: true } };const plain: ColorGrade = { preset: { id: "teal-orange" } };- // A skin tone: warm orange, mid saturation.const skin: [number, number, number] = [0.8, 0.55, 0.42];const sky: [number, number, number] = [0.4, 0.6, 0.85];const withSkin = createGradeTransform(grade)!(...skin);@@ -142,35 +163,12 @@ describe("skin protection", () => {const dWith = Math.hypot(withSkin[0] - skin[0], withSkin[1] - skin[1], withSkin[2] - skin[2]);const dWithout = Math.hypot(noSkin[0] - skin[0], noSkin[1] - skin[1], noSkin[2] - skin[2]);expect(dWith).toBeLessThan(dWithout);- // Non-skin pixels still take the full grade.const skySkin = createGradeTransform(grade)!(...sky);const skyPlain = createGradeTransform(plain)!(...sky);for (let c = 0; c < 3; c++) expect(Math.abs(skySkin[c] - skyPlain[c])).toBeLessThan(0.02);});});-describe("gradeNeedsLut", () => {- test("legacy scalar grades keep the fast path", () => {- expect(gradeNeedsLut({ brightness: 10, contrast: -5, hue: 90, temperature: 20 })).toBe(false);- expect(gradeNeedsLut({ tint: 10 })).toBe(false);- });-- test("new primitives take the LUT path", () => {- expect(gradeNeedsLut({ highlights: 5 })).toBe(true);- expect(gradeNeedsLut({ curves: { m: [[0, 10], [255, 255]] } })).toBe(true);- expect(gradeNeedsLut({ preset: { id: "mono" } })).toBe(true);- });-- test("a preset turned all the way down stays applied and renders neutral", () => {- // Intensity 0 keeps the pick (the tile stays selected, the slider can ride- // back up) while costing the renderer nothing.- const g = normalizeGrade({ preset: { id: "mono", amount: 0 } })!;- expect(g.preset).toEqual({ id: "mono", amount: 0 });- expect(gradeNeedsLut(g)).toBe(false);- expect(buildGradeLut(g)).toBe(null);- });-});-describe("curveLut", () => {test("monotone through control points without overshoot", () => {const lut = curveLut([diff --git a/site/packages/effects-kit/src/gradeLut.ts b/site/packages/effects-kit/src/gradeLut.tsindex 5459d923..eaee3e87 100644--- a/site/packages/effects-kit/src/gradeLut.ts+++ b/site/packages/effects-kit/src/gradeLut.ts@@ -1,14 +1,13 @@/**- * The 3D LUT every renderer shares. buildGradeLut samples gradeMath's- * transform onto a cubic lattice; ffmpeg consumes it as a .cube file- * (lut3d, tetrahedral), the preview's WebGL pass uploads it as a 3D- * texture, and headless export applies it on the CPU. All three- * interpolate tetrahedrally so they agree to within 8-bit quantization.+ * The 3D LUT every renderer shares: colorPipeline.ts samples a clip's color+ * mapping onto this cubic lattice; ffmpeg consumes it as a .cube file (lut3d,+ * tetrahedral), the preview's WebGL pass uploads it as a 3D texture, and+ * headless export applies it on the CPU. All three interpolate tetrahedrally+ * so they agree to within 8-bit quantization.*/import type { ColorGrade } from "./colorGrade";-import { normalizeGrade } from "./colorGrade";-import { createGradeTransform } from "./gradeMath";+import { gradeWithoutDetail } from "./colorGrade";export interface GradeLut {/** Lattice nodes per axis. */@@ -19,45 +18,26 @@ export interface GradeLut {export const GRADE_LUT_SIZE = 33;-/** A stable identity for a grade's rendered result: normalized, key-sorted- * JSON. Two grades with the same key produce the same LUT. */-export function gradeKey(g: ColorGrade | undefined | null): string {- const n = normalizeGrade(g);- if (!n) return "";- const sort = (v: unknown): unknown => {- if (Array.isArray(v)) return v.map(sort);- if (v && typeof v === "object") {+/** Key-sorted JSON of a plain value: the stable identity used by the LUT keys. */+export function stableJson(v: unknown): string {+ const sort = (x: unknown): unknown => {+ if (Array.isArray(x)) return x.map(sort);+ if (x && typeof x === "object") {const out: Record<string, unknown> = {};- for (const k of Object.keys(v).sort()) out[k] = sort((v as Record<string, unknown>)[k]);+ for (const k of Object.keys(x as object).sort()) out[k] = sort((x as Record<string, unknown>)[k]);return out;}- return v;+ return x;};- return JSON.stringify(sort(n));+ return JSON.stringify(sort(v));}-/** Sample the grade's transform onto the lattice. Returns null for a grade- * that resolves to neutral. */-export function buildGradeLut(- g: ColorGrade | undefined | null,- size = GRADE_LUT_SIZE-): GradeLut | null {- const transform = createGradeTransform(g);- if (!transform) return null;- const data = new Float32Array(size * size * size * 3);- const step = 1 / (size - 1);- let i = 0;- for (let b = 0; b < size; b++) {- for (let gg = 0; gg < size; gg++) {- for (let r = 0; r < size; r++) {- const out = transform(r * step, gg * step, b * step);- data[i++] = out[0];- data[i++] = out[1];- data[i++] = out[2];- }- }- }- return { size, data };+/** A stable identity for a grade's baked result: normalized, key-sorted JSON+ * without the spatial controls. Two grades with the same key produce the+ * same LUT. */+export function gradeKey(g: ColorGrade | undefined | null): string {+ const n = gradeWithoutDetail(g);+ return n ? stableJson(n) : "";}/** Serialize to the .cube text ffmpeg's lut3d reads. */diff --git a/site/packages/effects-kit/src/gradeMatch.test.ts b/site/packages/effects-kit/src/gradeMatch.test.tsindex d908cfd8..ed87446f 100644--- a/site/packages/effects-kit/src/gradeMatch.test.ts+++ b/site/packages/effects-kit/src/gradeMatch.test.ts@@ -1,6 +1,6 @@import { describe, expect, test } from "bun:test";import { createGradeTransform } from "./gradeMath";-import { colorStatsFromImageData, matchGrade } from "./gradeMatch";+import { autoGradeFromImageData, colorStatsFromImageData, matchGrade } from "./gradeMatch";/** A synthetic frame with tonal and color variety. */function testFrame(): Uint8ClampedArray {@@ -88,3 +88,62 @@ describe("matchGrade", () => {expect(stats.luma.length).toBe(7);});});++/** RGBA frame from repeating [r,g,b] pixel patterns. */+function frame(...pixels: [number, number, number][]): Uint8ClampedArray {+ const per = 64;+ const data = new Uint8ClampedArray(pixels.length * per * 4);+ pixels.forEach(([r, g, b], p) => {+ for (let i = 0; i < per; i++) {+ const o = (p * per + i) * 4;+ data[o] = r;+ data[o + 1] = g;+ data[o + 2] = b;+ data[o + 3] = 255;+ }+ });+ return data;+}++describe("autoGradeFromImageData", () => {+ test("a mid-gray frame needs nearly nothing", () => {+ const g = autoGradeFromImageData(frame([125, 125, 125]));+ expect(Math.abs(g?.exposure ?? 0) <= 1).toBe(true);+ expect(g?.contrast).toBeUndefined();+ expect(g?.temperature).toBeUndefined();+ });++ test("a dark frame gets pushed up toward middle gray, in stops", () => {+ const g = autoGradeFromImageData(frame([30, 30, 30], [50, 50, 50]));+ expect((g?.exposure ?? 0) > 10).toBe(true);+ expect(g?.exposure ?? 0).toBeLessThanOrEqual(50);+ });++ test("a compressed tonal range gets a contrast stretch", () => {+ const g = autoGradeFromImageData(frame([100, 100, 100], [150, 150, 150]));+ expect((g?.contrast ?? 0) > 0).toBe(true);+ });++ test("gray-world counters color casts both ways and leaves hue and saturation alone", () => {+ const cool = autoGradeFromImageData(frame([90, 120, 170]));+ expect((cool?.temperature ?? 0) > 0).toBe(true);+ const warm = autoGradeFromImageData(frame([170, 120, 90]));+ expect((warm?.temperature ?? 0) < 0).toBe(true);+ expect(cool?.saturation).toBeUndefined();+ expect(cool?.hue).toBeUndefined();+ expect(Math.abs(cool?.temperature ?? 0)).toBeLessThanOrEqual(40);+ });++ test("the fitted white balance neutralizes the cast it measured", () => {+ const cast: [number, number, number] = [150, 120, 95];+ const g = autoGradeFromImageData(frame(cast))!;+ const t = createGradeTransform({ temperature: g.temperature })!;+ const out = t(cast[0] / 255, cast[1] / 255, cast[2] / 255);+ // Damped correction: the red/blue gap closes by at least half.+ expect(Math.abs(out[0] - out[2])).toBeLessThan((cast[0] - cast[2]) / 255 / 2);+ });++ test("an empty sample yields no grade", () => {+ expect(autoGradeFromImageData(new Uint8ClampedArray(0))).toBeUndefined();+ });+});diff --git a/site/packages/effects-kit/src/gradeMatch.ts b/site/packages/effects-kit/src/gradeMatch.tsindex cb204378..306a5714 100644--- a/site/packages/effects-kit/src/gradeMatch.ts+++ b/site/packages/effects-kit/src/gradeMatch.ts@@ -1,12 +1,16 @@/**- * Reference matching: read color statistics off two frames and compute the- * grade that carries one onto the other. The match is per-channel quantile- * mapping compiled into tone-curve control points — the same curves the- * panel edits — plus a saturation delta, so the result is an ordinary- * ColorGrade the user (or the assistant) can refine afterward.+ * Measuring pictures and fitting grades to them: color statistics off a+ * frame, the auto grade, and reference matching. Every fit is expressed in+ * the grade's own parameters (exposure in stops, white balance as an+ * illuminant, contrast about grey, curves), so the result is an ordinary+ * ColorGrade the user or the assistant refines afterward. Callers hand these+ * the pixels of the base rendering — the picture after the source+ * conversion — so a log clip is measured as the display sees it.*/import { type ColorGrade, type CurvePoint, GRADE_MAX, normalizeGrade } from "./colorGrade";+import { REC709_PRIMARIES, bt1886Decode, mat3Apply } from "./colorSpace";+import { CONTRAST_POWER_AT_MAX, EXPOSURE_STOPS_AT_MAX, whiteBalanceFor } from "./gradeMath";/** Quantile probes used by stats and matching. */export const STAT_QUANTILES = [0.02, 0.1, 0.25, 0.5, 0.75, 0.9, 0.98] as const;@@ -83,6 +87,103 @@ export function colorStatsFromImageData(data: Uint8ClampedArray): ColorStats | u};}+/* ------------------------------------------------------------------ */+/* Auto grade */+/* ------------------------------------------------------------------ */++/**+ * Auto grade from a frame's RGBA pixels, the classic auto-tone pipeline:+ *+ * 1. Exposure — map the frame's log-average (geometric mean) luminance onto+ * 18% middle grey, in stops.+ * 2. Contrast — auto-levels: clip 0.5% off each end of the luma histogram+ * and stretch what remains toward full range, expressed as the power+ * about grey the contrast slider applies.+ * 3. White balance — grey-world: the illuminant whose CAT02 correction+ * equalizes the red and blue means of the midtones, found on the+ * temperature slider.+ *+ * Corrections are damped and capped inside the slider range so the result+ * is a starting point the user refines. Saturation and hue are left alone.+ */+export function autoGradeFromImageData(data: Uint8ClampedArray): ColorGrade | undefined {+ const hist = new Float64Array(256);+ let count = 0;+ let logSum = 0;+ let sumR = 0;+ let sumG = 0;+ let sumB = 0;+ let mids = 0;+ for (let i = 0; i < data.length; i += 4) {+ const r = data[i];+ const g = data[i + 1];+ const b = data[i + 2];+ const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;+ hist[Math.min(255, Math.round(luma))]++;+ logSum += Math.log(Math.max(1e-4, bt1886Decode(luma / 255)));+ count++;+ // Cast statistics from the midtones only — near-black and clipped pixels+ // carry no reliable illuminant signal.+ if (luma >= 16 && luma <= 240) {+ sumR += bt1886Decode(r / 255);+ sumG += bt1886Decode(g / 255);+ sumB += bt1886Decode(b / 255);+ mids++;+ }+ }+ if (!count) return undefined;+ const percentile = (p: number) => {+ let acc = 0;+ for (let v = 0; v < 256; v++) {+ acc += hist[v];+ if (acc >= count * p) return v;+ }+ return 255;+ };++ const grade: ColorGrade = {};+ const ev = Math.log2(0.18 / Math.exp(logSum / count));+ grade.exposure = Math.round((GRADE_MAX * ev * 0.8) / EXPOSURE_STOPS_AT_MAX);+ // Auto-levels spread after the exposure shift moves it, on encoded values.+ // A near-flat histogram (solid color, title card) carries no tonal-range+ // signal — leave contrast alone rather than stretch noise.+ const gain = Math.pow(2, ((grade.exposure / GRADE_MAX) * EXPOSURE_STOPS_AT_MAX) / 2.4);+ const lo = Math.min(255, percentile(0.005) * gain);+ const hi = Math.min(255, percentile(0.995) * gain);+ if (hi - lo >= 16) {+ const power = 255 / (hi - lo);+ grade.contrast = Math.max(+ -10,+ Math.min(40, Math.round(((power - 1) * 0.6 * GRADE_MAX) / CONTRAST_POWER_AT_MAX))+ );+ }+ if (mids) {+ const mean: [number, number, number] = [sumR / mids, sumG / mids, sumB / mids];+ // Grey-world on the temperature axis: the slider value whose white+ // balance brings red and blue to the same level.+ const imbalance = (t: number) => {+ const wb = whiteBalanceFor(t, 0, REC709_PRIMARIES);+ const c = wb ? mat3Apply(wb, mean[0], mean[1], mean[2]) : mean;+ return c[0] - c[2];+ };+ let best = 0;+ let bestErr = Math.abs(imbalance(0));+ for (let t = -GRADE_MAX; t <= GRADE_MAX; t++) {+ const err = Math.abs(imbalance(t));+ if (err < bestErr) {+ bestErr = err;+ best = t;+ }+ }+ grade.temperature = Math.max(-40, Math.min(40, Math.round(best * 0.6)));+ }+ return normalizeGrade(grade);+}++/* ------------------------------------------------------------------ */+/* Reference matching */+/* ------------------------------------------------------------------ */+function quantileCurve(src: number[], ref: number[]): CurvePoint[] | undefined {const pts: CurvePoint[] = [];let lastX = -1;@@ -119,8 +220,8 @@ function quantileCurve(src: number[], ref: number[]): CurvePoint[] | undefined {/*** Compute the grade that moves `source` toward `reference`: per-channel- * quantile curves plus a saturation delta. Returns undefined when the frames- * already agree.+ * quantile curves, or a saturation delta when the tones already agree.+ * Returns undefined when the frames already agree.*/export function matchGrade(source: ColorStats, reference: ColorStats): ColorGrade | undefined {const grade: ColorGrade = {};@@ -133,7 +234,10 @@ export function matchGrade(source: ColorStats, reference: ColorStats): ColorGradif (g) grade.curves.g = g;if (b) grade.curves.b = b;}- if (source.meanSat > 0.01) {+ // Per-channel curves already stretch or squeeze chroma along with the+ // channels, so the saturation term is for frames that agree in tone and+ // differ in chroma alone.+ if (!grade.curves && source.meanSat > 0.01) {const delta = Math.round((reference.meanSat / source.meanSat - 1) * GRADE_MAX);if (Math.abs(delta) >= 2) {grade.saturation = Math.max(-GRADE_MAX, Math.min(GRADE_MAX, delta));diff --git a/site/packages/effects-kit/src/gradeMath.ts b/site/packages/effects-kit/src/gradeMath.tsindex 3b662f7a..9dd47878 100644--- a/site/packages/effects-kit/src/gradeMath.ts+++ b/site/packages/effects-kit/src/gradeMath.ts@@ -1,23 +1,28 @@/**- * The extended grade's pixel math: one pure transform [0,1]³ → [0,1]³ that- * every renderer consumes through the 3D LUT in gradeLut.ts. A grade resolves- * to at most two layers — the preset (scaled by its amount, optionally kept- * off skin tones) and the manual adjustments on top — and each layer applies- * its stages in one canonical order:+ * 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 preset (scaled by its amount,+ * optionally kept off skin tones) and the manual adjustments on top — 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):*- * gain → contrast → wheels → highlights/shadows → curves →- * HSL (global hue/saturation, vibrance, feathered hue bands) → cast tint →- * clamp+ * light, in linear light (the container's transfer 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*- * The cast lands last because a cast is a print-side process — the silver is- * replaced by a colored compound, a density multiply over the finished image.- * Applying it before the saturation stage would let a desaturating grade strip- * the very tone it just laid down, which is what makes a toned monochrome- * (sepia and its relatives) expressible at all.+ * 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.*- * The tonal stages reuse the exact fast-path formulas from colorGrade.ts, so- * a scalar grade evaluated through the LUT lands on the fast path's result to- * within quantization.+ * 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.*/import {@@ -25,19 +30,130 @@ import {type CurvePoint,type GradePresetRef,type HslBand,+ type WheelZone,+ GRADE_LUT_SCALAR_KEYS,GRADE_MAX,HSL_BANDS,- deriveGrade,- gradeTint,- gradeToCssFilter,- isNeutralGrade,+ 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,+ spow,+ whiteBalanceMatrix,+} from "./colorSpace";import { GRADE_PRESETS } from "./gradePresets";import { monotoneCubic } from "./monotone";const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);-const luma = (r: number, g: number, b: number) => 0.2126 * r + 0.7152 * g + 0.0722 * b;++/* ------------------------------------------------------------------ */+/* 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;+/** Blacks is an additive offset in linear light, so it reaches black. The+ * slider maps to it through its 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;++/** Wheel amplitudes at a full puck / luma trim. */+const WHEEL_LIFT = 0.03;+const WHEEL_GAMMA = 0.35;+const WHEEL_GAIN = 0.5;+const WHEEL_OFFSET = 0.05;++/* ------------------------------------------------------------------ */+/* 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;+ /** 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,+ 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),+ 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,+ luma: [0.2627, 0.678, 0.0593],+ oklab: oklabMatrices(REC2020_PRIMARIES),+ };+ }+ spaces.set(output, s);+ return s;+}/* ------------------------------------------------------------------ *//* Monotone tone curves */@@ -64,10 +180,6 @@ const sampleCurve = (lut: Float32Array, v: number) => {return i >= 255 ? lut[255] : lut[i] * (1 - f) + lut[i + 1] * f;};-/* ------------------------------------------------------------------ */-/* Semantic curve helpers (chat tools compile to real control points) */-/* ------------------------------------------------------------------ */-/*** Build master-curve control points from two semantic knobs: `contrast`* (-50..50, an s-curve around mid-gray) and `fade` (0..50, lifted blacks).@@ -89,10 +201,10 @@ export function semanticMasterCurve(contrast: number, fade: number): CurvePoint[}/* ------------------------------------------------------------------ */-/* Color space */+/* Hue helpers *//* ------------------------------------------------------------------ */-function rgbToHsl(r: number, g: number, b: number): [number, number, number] {+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;@@ -164,6 +276,23 @@ export function hueBandWeight(hueDeg: number, band: HslBand): number {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 *//* ------------------------------------------------------------------ */@@ -174,18 +303,7 @@ export function hueBandWeight(hueDeg: number, band: HslBand): number {export function scaleGradeToward(g: ColorGrade, t: number): ColorGrade {if (t >= 1) return g;const out: ColorGrade = {};- for (const k of [- "brightness",- "contrast",- "saturation",- "exposure",- "temperature",- "tint",- "hue",- "highlights",- "shadows",- "vibrance",- ] as const) {+ for (const k of GRADE_LUT_SCALAR_KEYS) {const v = g[k];if (v) out[k] = v * t;}@@ -199,7 +317,7 @@ export function scaleGradeToward(g: ColorGrade, t: number): ColorGrade {}if (g.wheels) {const wheels: NonNullable<ColorGrade["wheels"]> = {};- for (const z of ["s", "m", "h"] as const) {+ for (const z of WHEEL_ZONES) {const w = g.wheels[z];if (w) wheels[z] = [w[0] * t, w[1] * t, w[2] * t];}@@ -228,38 +346,85 @@ export function resolvePreset(ref: GradePresetRef | undefined): ColorGrade | und}/* ------------------------------------------------------------------ */-/* The transform */+/* 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 {- gain: number;- contrast: number;- saturate: number;- hue: number;- tint: { r: number; g: number; b: number } | null;+ 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 pivothighlights: number;shadows: number;- vibrance: number;+ whites: number;+ blacks: number;+ brilliance: number;+ masks: boolean;+ wheels: Wheel[];+ light: boolean;curves: { m?: Float32Array; r?: Float32Array; g?: Float32Array; b?: Float32Array } | null;- wheels: { zone: "s" | "m" | "h"; chroma: [number, number, number]; luma: number }[];- bands: { band: HslBand; hueShift: number; sat: number; lum: number }[];+ hue: number;+ saturate: number; // chroma multiplier ≥ 1 in the color stage+ vibrance: number;+ bands: Band[];+ color: boolean;+ fade: number;skinDamp: boolean;}-function buildLayer(g: ColorGrade, skinDamp: boolean): Layer | null {- const d = deriveGrade(g);+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 = {- gain: d.gain,- contrast: d.contrast,- saturate: d.saturate,- hue: d.hue,- tint: d.tint,+ 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,- vibrance: (g.vibrance || 0) / GRADE_MAX,- curves: null,+ 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) {@@ -271,164 +436,295 @@ function buildLayer(g: ColorGrade, skinDamp: boolean): Layer | null {if (!Object.keys(layer.curves).length) layer.curves = null;}if (g.wheels) {- for (const zone of ["s", "m", "h"] as const) {+ for (const zone of WHEEL_ZONES) {const w = g.wheels[zone];- if (!w || (!w[0] && !w[1] && !w[2])) continue;- 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 * 0.35,- (p[1] - mean) * radius * 0.35,- (p[2] - mean) * radius * 0.35,- ];- }- layer.wheels.push({ zone, chroma, luma: (w[2] / GRADE_MAX) * 0.25 });+ if (!w) continue;+ const amount = wheelAmount(w);+ if (amount) layer.wheels.push({ zone, amount });}}if (g.hsl) {- for (const band of HSL_BANDS) {- const t = g.hsl[band.id];- if (!t || (!t[0] && !t[1] && !t[2])) continue;+ HSL_BANDS.forEach((band, idx) => {+ const t = g.hsl?.[band.id];+ if (!t || (!t[0] && !t[1] && !t[2])) return;layer.bands.push({- band: band.id,+ 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,});- }+ });}- const active =- layer.gain !== 1 ||- layer.contrast !== 1 ||- layer.saturate !== 1 ||- layer.hue !== 0 ||- layer.tint !== null ||- layer.highlights !== 0 ||- layer.shadows !== 0 ||- layer.vibrance !== 0 ||- layer.curves !== null ||- layer.wheels.length > 0 ||- layer.bands.length > 0;+ 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 applyLayer(v: [number, number, number], L: Layer, skinW: number): void {- // Skin protection is one rule applied at the layer's end: the layer's tone- // lands in full, and the chroma it moved blends back toward the pixel's own- // by the skin weight. Every stage — casts, curves, hue bands, saturation —- // is covered by construction, so a stage added later cannot leak color onto- // faces and no stage has to remember to damp itself.+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 = space.decode(R);+ G = space.decode(G);+ B = space.decode(B);+ LIN = true;+}++function toDisplay(space: GradeSpace): void {+ if (!LIN) return;+ R = space.encode(R);+ G = space.encode(G);+ B = space.encode(B);+ 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;+}++function applyLayer(v: [number, number, number], L: Layer, space: GradeSpace, skinW: number): void {const damp = L.skinDamp ? skinW : 0;- const pre: [number, number, number] | null = damp > 0 ? [v[0], v[1], v[2]] : null;- // Tonal: the fast path's exact gain + mid-gray contrast, clipped like the- // combined lutrgb expression.- for (let c = 0; c < 3; c++) {- v[c] = clamp01((clamp01(v[c] * L.gain) - 0.5) * L.contrast + 0.5);+ 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);}- if (L.wheels.length) {- const Y = luma(v[0], v[1], v[2]);- const wS = (1 - Y) * (1 - Y);- const wH = Y * Y;- const wM = Math.max(0, 1 - wS - wH);++ // ---- 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;+ const yl = clamp01(y);+ const V = clamp01(space.encode(yl));+ 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 (stops) {+ const k = Math.pow(2, stops);+ R *= k;+ G *= k;+ B *= k;+ }+ if (L.blacks) {+ // 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 * Math.abs(L.blacks) * BLACKS_OFFSET * iy * iy * iy;+ R += off;+ G += off;+ B += off;+ }+ }for (const w of L.wheels) {- const weight = w.zone === "s" ? wS : w.zone === "h" ? wH : wM;- if (weight <= 0) continue;- for (let c = 0; c < 3; c++) {- const shift = w.chroma[c] + w.luma;- if (w.zone === "s") v[c] += shift * weight;- else if (w.zone === "h") v[c] *= 1 + shift * weight;- else v[c] = Math.pow(clamp01(v[c]), 1 / Math.max(0.2, 1 + shift * weight * 1.5));+ const a = w.amount;+ if (w.zone === "s") {+ R += WHEEL_LIFT * a[0] * (1 - R);+ G += WHEEL_LIFT * a[1] * (1 - G);+ B += WHEEL_LIFT * a[2] * (1 - B);+ } 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 += WHEEL_OFFSET * a[0];+ G += WHEEL_OFFSET * a[1];+ B += WHEEL_OFFSET * a[2];}}- for (let c = 0; c < 3; c++) v[c] = clamp01(v[c]);- }- if (L.highlights || L.shadows) {- const Y = luma(v[0], v[1], v[2]);- const sh = L.shadows * 0.3 * (1 - Y) * (1 - Y);- const hi = L.highlights * 0.3 * Y * Y;- for (let c = 0; c < 3; c++) v[c] = clamp01(v[c] + sh + hi);}++ // ---- color stage, on display values ----if (L.curves) {- for (let c = 0; c < 3; c++) {- let x = v[c];- if (L.curves.m) x = sampleCurve(L.curves.m, x);- const ch = c === 0 ? L.curves.r : c === 1 ? L.curves.g : L.curves.b;- if (ch) x = sampleCurve(ch, x);- v[c] = x;+ 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);}- const needsHslStage =- L.hue !== 0 || L.saturate !== 1 || L.vibrance !== 0 || L.bands.length > 0;- if (needsHslStage) {- let [h, s, l] = rgbToHsl(v[0], v[1], v[2]);- const entryHue = h;+ 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) s *= L.saturate;- if (L.vibrance) s += L.vibrance * 0.8 * s * (1 - s);- for (const b of L.bands) {- const w = hueBandWeight(entryHue, b.band);+ 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 += b.hueShift * w;- s *= 1 + b.sat * w;- l *= 1 + b.lum * 0.5 * w;+ h += band.hueShift * w;+ C *= 1 + band.sat * w;+ Lk *= 1 + band.lum * 0.5 * w;}- const rgb = hslToRgb(h, clamp01(s), clamp01(l));- v[0] = clamp01(rgb[0]);- v[1] = clamp01(rgb[1]);- v[2] = clamp01(rgb[2]);+ 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.tint) {- v[0] = clamp01(v[0] * L.tint.r);- v[1] = clamp01(v[1] * L.tint.g);- v[2] = clamp01(v[2] * L.tint.b);+ 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);}- if (pre) {+ 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,- // where holding the chroma difference instead would raise saturation- // whenever the layer darkened.- const y0 = luma(pre[0], pre[1], pre[2]);- const y1 = luma(v[0], v[1], v[2]);+ // 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;- for (let c = 0; c < 3; c++) {- v[c] = clamp01(v[c] * (1 - damp) + clamp01(pre[c] * k) * damp);- }+ 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. Values are gamma-encoded- * BT.709 RGB in [0,1]. Returns null for a neutral grade.+ * 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): GradeTransform | null {+export function createGradeTransform(+ g: ColorGrade | undefined | null,+ output: OutputSpace = "sdr"+): GradeTransform | null {const n = normalizeGrade(g);if (!n) return null;+ const space = gradeSpaceFor(output);const layers: Layer[] = [];const presetGrade = resolvePreset(n.preset);if (presetGrade) {- const layer = buildLayer(presetGrade, !!n.preset?.skin);+ const layer = buildLayer(presetGrade, space, !!n.preset?.skin);if (layer) layers.push(layer);}const manual: ColorGrade = { ...n };delete manual.preset;- const manualLayer = buildLayer(manual, false);+ delete manual.lut;+ delete manual.sharpen;+ delete manual.clarity;+ const manualLayer = buildLayer(manual, space, false);if (manualLayer) layers.push(manualLayer);if (!layers.length) return null;const anySkin = layers.some((l) => l.skinDamp);return (r, g2, b) => {- const v: [number, number, number] = [clamp01(r), clamp01(g2), clamp01(b)];+ const v: [number, number, number] = [r, g2, b];let skinW = 0;if (anySkin) {- const [h, s] = rgbToHsl(v[0], v[1], v[2]);+ const [h, s] = rgbToHsl(clamp01(r), clamp01(g2), clamp01(b));skinW = skinWeight(h, s);}- for (const layer of layers) applyLayer(v, layer, skinW);+ for (const layer of layers) applyLayer(v, layer, space, skinW);return v;};}@@ -437,13 +733,16 @@ export function createGradeTransform(g: ColorGrade | undefined | null): GradeTra/* Filmstrip approximation *//* ------------------------------------------------------------------ */+const fmt = (n: number) => (Math.round(n * 1000) / 1000).toFixed(3);+/**- * A DOM-CSS approximation of the whole grade for tiny always-on surfaces- * (timeline filmstrips, preset tiles). Exact for the fast-path scalars with- * the preset's scalars folded in by its amount; highlights/shadows and- * vibrance become small brightness/contrast/saturation nudges; curves,- * wheels, and hue bands are left out by design — the preview canvas and- * exports render them for real.+ * 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@@ -451,32 +750,42 @@ export function gradeCssApprox(const n = normalizeGrade(g);if (!n) return { filter: "", tint: null };const presetGrade = resolvePreset(n.preset);- const eff: ColorGrade = {};- const keys = [- "brightness",- "contrast",- "saturation",- "exposure",- "temperature",- "tint",- "hue",- "highlights",- "shadows",- "vibrance",- ] as const;- for (const k of keys) {+ 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 approx: ColorGrade = {- brightness: (eff.brightness || 0) + ((eff.shadows || 0) + (eff.highlights || 0)) * 0.2,- contrast: (eff.contrast || 0) + ((eff.highlights || 0) - (eff.shadows || 0)) * 0.15,- saturation: (eff.saturation || 0) + (eff.vibrance || 0) * 0.5,- exposure: eff.exposure,- temperature: eff.temperature,- tint: eff.tint,- hue: eff.hue,- };- if (isNeutralGrade(approx)) return { filter: "", tint: null };- return { filter: gradeToCssFilter(approx), tint: gradeTint(approx) };+ 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 };}diff --git a/site/packages/effects-kit/src/gradePresets.test.ts b/site/packages/effects-kit/src/gradePresets.test.tsindex 89de6214..d13f9f8e 100644--- a/site/packages/effects-kit/src/gradePresets.test.ts+++ b/site/packages/effects-kit/src/gradePresets.test.ts@@ -47,6 +47,15 @@ describe("shipped catalog", () => {}});+ test("no recipe carries a LUT or a spatial control", () => {+ for (const id of GRADE_PRESET_IDS) {+ const grade = GRADE_PRESETS[id].grade;+ expect(grade.lut).toBeUndefined();+ expect(grade.sharpen).toBeUndefined();+ expect(grade.clarity).toBeUndefined();+ }+ });+test("catalog text names every category and preset id", () => {const text = gradePresetCatalogText();for (const cat of GRADE_PRESET_CATEGORIES) expect(text).toContain(cat.label);@@ -70,9 +79,12 @@ describe("parseGradePresets", () => {{ id: "neutral", label: "X", category: "mood", grade: { contrast: 0 } },{ id: "nested", label: "X", category: "mood", grade: { preset: { id: "mono" } } },{ id: "good-one", label: "Duplicate", category: "mood", grade: { contrast: 5 } },+ { id: "with-lut", label: "X", category: "mood", grade: { contrast: 5, lut: { id: "lut:a" } } },+ { id: "spatial", label: "X", category: "mood", grade: { contrast: 5, sharpen: 10 } },+ { id: "clarity", label: "X", category: "mood", grade: { clarity: 10 } },]);expect(presets.map((p) => p.id)).toEqual(["good-one"]);- expect(errors.length).toBe(6);+ expect(errors.length).toBe(9);});test("recipes are normalized on the way in", () => {diff --git a/site/packages/effects-kit/src/gradePresets.ts b/site/packages/effects-kit/src/gradePresets.tsindex f6cd04ac..f9a55886 100644--- a/site/packages/effects-kit/src/gradePresets.ts+++ b/site/packages/effects-kit/src/gradePresets.ts@@ -78,6 +78,14 @@ export function parseGradePresets(json: unknown): { presets: GradePreset[]; erroerrors.push(`"${id}": a preset recipe cannot reference another preset`);return;}+ if ((e.grade as ColorGrade).lut) {+ errors.push(`"${id}": a preset recipe cannot reference a library LUT`);+ return;+ }+ if ((e.grade as ColorGrade).sharpen || (e.grade as ColorGrade).clarity) {+ errors.push(`"${id}": a preset recipe cannot carry the spatial controls`);+ return;+ }const grade = normalizeGrade(e.grade as ColorGrade);if (!grade) {errors.push(`"${id}": grade is neutral or carries no known fields`);diff --git a/site/packages/effects-kit/src/index.ts b/site/packages/effects-kit/src/index.tsindex 0d3faf6b..1bd5554b 100644--- a/site/packages/effects-kit/src/index.ts+++ b/site/packages/effects-kit/src/index.ts@@ -16,7 +16,11 @@ export * from "./strokeInk";export * from "./lottie";export * from "./looks";export * from "./colorGrade";+export * from "./colorSpace";+export * from "./acesOutput";export * from "./gradeMath";+export * from "./colorPipeline";+export * from "./detail";export * from "./monotone";export * from "./retime";export * from "./gradeLut";@@ -24,3 +28,4 @@ export * from "./gradePresets";export * from "./gradeMatch";export * from "./effects";export * from "./audioFx";+export * from "./lutFile";diff --git a/site/packages/effects-kit/src/looks.test.ts b/site/packages/effects-kit/src/looks.test.tsindex 305924bf..532d7a9c 100644--- a/site/packages/effects-kit/src/looks.test.ts+++ b/site/packages/effects-kit/src/looks.test.ts@@ -19,6 +19,21 @@ describe("lookFilterLines", () => {expect(lookFilterLines("a", "b", "dreamy", 1, 1920, "yuv420p", "t")!.length).toBe(3);});+ test("halation's luma knee scales to the plane's depth", () => {+ expect(lookFilterLines("a", "b", "halation", 1, 1920, "yuv420p", "t")!.join(";")).toContain(+ "lutyuv=y='clip((val-160)*3,0,255)'"+ );+ expect(lookFilterLines("a", "b", "halation", 1, 1920, "yuv420p10le", "t", 10)!.join(";")).toContain(+ "lutyuv=y='clip((val-641.882)*3,0,1023)'"+ );+ // Every other look is written in ratios and carries no code value.+ for (const style of ["vintage", "vhs", "horror", "tech", "noir", "grain", "pastel", "blockbuster", "dreamy"]) {+ const at8 = lookFilterLines("a", "b", style, 1, 1920, "yuv420p", "t")!.join(";");+ const at10 = lookFilterLines("a", "b", style, 1, 1920, "yuv420p10le", "t", 10)!.join(";");+ expect(at10).toBe(at8.replaceAll("format=yuv420p", "format=yuv420p10le"));+ }+ });+test("an unknown id returns null instead of failing the job", () => {expect(lookFilterLines("a", "b", "sparkle", 1, 1920, "yuv420p", "t")).toBe(null);expect(lookFilterLines("a", "b", "", 1, 1920, "yuv420p", "t")).toBe(null);diff --git a/site/packages/effects-kit/src/looks.ts b/site/packages/effects-kit/src/looks.tsindex 91189fbf..92eb7b68 100644--- a/site/packages/effects-kit/src/looks.ts+++ b/site/packages/effects-kit/src/looks.ts@@ -271,7 +271,9 @@ function lookChain(style: LookStyle, k: number): string | null {* invariant holds through xfade/concat joins. Null for an unknown style — the* segment renders ungraded rather than failing the job (the spec carries only* ids, never filter text). `hPx` scales blur radii so 720p drafts and 1080p- * exports bloom proportionally; `tag` uniquifies inner labels.+ * exports bloom proportionally; `tag` uniquifies inner labels; `depth` is+ * the bits a plane holds, so the 8-bit code values the recipes are written+ * in land on a 10-bit composite.*/export function lookFilterLines(inLabel: string,@@ -280,13 +282,15 @@ export function lookFilterLines(amount: number | undefined,hPx: number,pixFmt: string,- tag: string+ tag: string,+ depth: 8 | 10 = 8): string[] | null {const k = clampAmount(amount);+ const scale = ((1 << depth) - 1) / 255;if (style === "halation") {return [`[${inLabel}]split=2[lkb${tag}][lkh${tag}]`,- `[lkh${tag}]lutyuv=y='clip((val-160)*3,0,255)',` ++ `[lkh${tag}]lutyuv=y='clip((val-${fmt(160 * scale)})*3,0,${fmt(255 * scale)})',` +`gblur=sigma=${fmt((18 * hPx) / 1920)},` +`colorchannelmixer=rr=1:gg=0.55:bb=0.35[lkg${tag}]`,`[lkb${tag}][lkg${tag}]blend=all_mode=screen:all_opacity=${fmt(0.6 * k)},format=${pixFmt}[${outLabel}]`,diff --git a/site/packages/effects-kit/src/lutFile.test.ts b/site/packages/effects-kit/src/lutFile.test.tsnew file mode 100644index 00000000..f31e3dd1--- /dev/null+++ b/site/packages/effects-kit/src/lutFile.test.ts@@ -0,0 +1,131 @@+import { describe, expect, test } from "bun:test";+import { lutFacts, parse3dl, parseCube, parseLutFile, sampleLut } from "./lutFile";++const close = (got: readonly number[], want: readonly number[], eps = 1e-5) => {+ expect(got.length).toBe(want.length);+ for (let i = 0; i < want.length; i++) expect(Math.abs(got[i] - want[i])).toBeLessThan(eps);+};++/** An identity cube of `size` nodes per axis, red fastest, as the spec lays it out. */+function identityCubeText(size: number, eol = "\n"): string {+ const out = [`LUT_3D_SIZE ${size}`];+ for (let b = 0; b < size; b++)+ for (let g = 0; g < size; g++)+ for (let r = 0; r < size; r++)+ out.push(`${r / (size - 1)} ${g / (size - 1)} ${b / (size - 1)}`);+ return out.join(eol) + eol;+}++const PROBES: [number, number, number][] = [+ [0, 0, 0],+ [1, 1, 1],+ [0.5, 0.5, 0.5],+ [0.2, 0.7, 0.1],+ [0.9, 0.1, 0.6],+ [0.33, 0.33, 0.8],+];++describe("parseCube", () => {+ test("an identity cube samples to its input", () => {+ const lut = parseCube(`TITLE "Identity"\n# a comment\n${identityCubeText(3)}`);+ expect(lut.title).toBe("Identity");+ expect(lutFacts(lut)).toEqual({ kind: "3d", size: 3 });+ for (const p of PROBES) close(sampleLut(lut, ...p), p);+ });++ test("CRLF files parse the same", () => {+ const lut = parseCube(identityCubeText(2, "\r\n"));+ for (const p of PROBES) close(sampleLut(lut, ...p), p);+ });++ test("a two-point shaper interpolates linearly", () => {+ const lut = parseCube("LUT_1D_SIZE 2\n0 0 0\n0.5 1 2\n");+ expect(lutFacts(lut)).toEqual({ kind: "1d", size: 2 });+ close(sampleLut(lut, 0.5, 0.5, 0.5), [0.25, 0.5, 1]);+ close(sampleLut(lut, 1, 0.25, 2), [0.5, 0.25, 2]);+ });++ test("DOMAIN_MIN/MAX map the input before the lattice", () => {+ const lut = parseCube(`DOMAIN_MIN -1 -1 -1\nDOMAIN_MAX 1 1 1\n${identityCubeText(2)}`);+ close(sampleLut(lut, 0, 0, 0), [0.5, 0.5, 0.5]);+ close(sampleLut(lut, -1, 1, 0.5), [0, 1, 0.75]);+ });++ test("a shaper followed by a cube applies both", () => {+ // Shaper halves every channel over 0..2; the cube inverts.+ const cube = ["LUT_3D_SIZE 2", "LUT_3D_INPUT_RANGE 0 1"];+ for (let b = 0; b < 2; b++)+ for (let g = 0; g < 2; g++) for (let r = 0; r < 2; r++) cube.push(`${1 - r} ${1 - g} ${1 - b}`);+ const text = ["LUT_1D_SIZE 2", "LUT_1D_INPUT_RANGE 0 2", "0 0 0", "1 1 1", ...cube].join("\n");+ const lut = parseCube(text);+ expect(lutFacts(lut)).toEqual({ kind: "shaper+3d", size: 2 });+ close(sampleLut(lut, 2, 0, 1), [0, 1, 0.5]);+ });++ test("a graded cube is sampled tetrahedrally, red fastest", () => {+ // Output = (g, b, r): the data column order tells red from blue.+ const out = ["LUT_3D_SIZE 2"];+ for (let b = 0; b < 2; b++) for (let g = 0; g < 2; g++) for (let r = 0; r < 2; r++) out.push(`${g} ${b} ${r}`);+ const lut = parseCube(out.join("\n"));+ close(sampleLut(lut, 0.2, 0.7, 0.1), [0.7, 0.1, 0.2]);+ });++ test("malformed files name the problem", () => {+ expect(() => parseCube("LUT_3D_SIZE 2\n0 0 0\n")).toThrow(/2 lines|8/);+ expect(() => parseCube("LUT_3D_SIZE 1\n")).toThrow(/2\.\.256/);+ expect(() => parseCube("LUT_1D_SIZE 70000\n")).toThrow(/2\.\.65536/);+ expect(() => parseCube("LUT_3D_SIZE 2\n0 0 x\n")).toThrow(/not a number/);+ expect(() => parseCube("0 0 0\n")).toThrow(/before/);+ expect(() => parseCube("# nothing\n")).toThrow(/no LUT_1D_SIZE/);+ expect(() => parseCube(`${identityCubeText(2)}0 0 0\n`)).toThrow(/more lines/);+ });+});++describe("parse3dl", () => {+ const SAMPLES = [0, 64, 128, 192, 256, 320, 384, 448, 512, 576, 640, 704, 768, 832, 896, 960, 1023];++ /** An identity at 10-bit over 17 sample points, blue fastest. */+ function identity3dl(eol = "\n"): string {+ const n = SAMPLES.length;+ const out = [SAMPLES.join(" ")];+ for (let r = 0; r < n; r++)+ for (let g = 0; g < n; g++)+ for (let b = 0; b < n; b++) out.push(`${SAMPLES[r]} ${SAMPLES[g]} ${SAMPLES[b]}`);+ return out.join(eol) + eol;+ }++ test("a 10-bit identity samples to its input", () => {+ const lut = parse3dl(identity3dl());+ expect(lutFacts(lut)).toEqual({ kind: "3d", size: 17 });+ for (const p of PROBES) close(sampleLut(lut, ...p), p, 2e-3);+ });++ test("blue-fastest data is reordered to red fastest", () => {+ // Output = (b, r, g) in 10-bit, over 2 sample points.+ const out = ["0 1023"];+ for (let r = 0; r < 2; r++) for (let g = 0; g < 2; g++) for (let b = 0; b < 2; b++) out.push(`${b * 1023} ${r * 1023} ${g * 1023}`);+ const lut = parse3dl(out.join("\r\n"));+ close(sampleLut(lut, 0.2, 0.7, 0.1), [0.1, 0.2, 0.7], 1e-3);+ });++ test("output depth follows the Mesh header, then the largest value", () => {+ const twelve = ["3DMESH", "Mesh 1 12", "0 1023", ...Array(8).fill("4095 4095 4095")].join("\n");+ close(sampleLut(parse3dl(twelve), 0.5, 0.5, 0.5), [1, 1, 1]);+ const sixteen = ["0 1023", ...Array(8).fill("65535 0 0")].join("\n");+ close(sampleLut(parse3dl(sixteen), 0.5, 0.5, 0.5), [1, 0, 0]);+ });++ test("malformed files name the problem", () => {+ expect(() => parse3dl("0 1023\n0 0 0\n")).toThrow(/1 lines/);+ expect(() => parse3dl("0 1023\n0 0 1.5\n")).toThrow(/whole numbers/);+ expect(() => parse3dl("# only comments\n")).toThrow(/sample points/);+ });+});++describe("parseLutFile", () => {+ test("picks the parser by extension", () => {+ expect(lutFacts(parseLutFile("look.CUBE", identityCubeText(2))).kind).toBe("3d");+ expect(lutFacts(parseLutFile("look.3dl", "0 1023\n" + Array(8).fill("0 0 0").join("\n"))).size).toBe(2);+ expect(() => parseLutFile("look.txt", "")).toThrow(/\.cube or \.3dl/);+ });+});diff --git a/site/packages/effects-kit/src/lutFile.ts b/site/packages/effects-kit/src/lutFile.tsnew file mode 100644index 00000000..9afccf08--- /dev/null+++ b/site/packages/effects-kit/src/lutFile.ts@@ -0,0 +1,309 @@+/**+ * Colour lookup-table files as people download them: `.cube`+ * and Autodesk `.3dl`.+ *+ * A parsed file is a shaper (a 1D table), a cube (a 3D table), or both, each+ * with its own input domain. Data is stored normalized to 0..1 with red+ * running fastest, which is the order ffmpeg's lut3d, the WebGL 3D texture+ * and the CPU path already share. Malformed files throw an Error whose+ * message is short enough to show the person who dropped the file.+ *+ * Specs: Adobe Cube LUT Specification 1.0; the widely written+ * `LUT_1D_INPUT_RANGE` / `LUT_3D_INPUT_RANGE` extension and its+ * shaper-then-cube layout; Autodesk+ * `.3dl` (sample-point header, integer triplets, blue fastest).+ */++type Triple = [number, number, number];++export interface LutTable {+ size: number;+ /** Normalized outputs: `size*3` for a shaper, `size³*3` (red fastest) for a cube. */+ data: Float32Array;+ min: Triple;+ max: Triple;+}++export interface ParsedLut {+ title?: string;+ shaper?: LutTable;+ cube?: LutTable;+}++export type LutKind = "1d" | "3d" | "shaper+3d";++const SHAPER_MIN = 2;+const SHAPER_MAX = 65536;+const CUBE_MIN = 2;+const CUBE_MAX = 256;++const lines = (text: string): string[] =>+ text+ .split(/\r?\n/)+ .map((l) => l.trim())+ .filter((l) => l.length > 0 && !l.startsWith("#"));++const NUMBER = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;++function numbers(line: string, what: string): number[] {+ const parts = line.split(/\s+/);+ const out: number[] = [];+ for (const p of parts) {+ if (!NUMBER.test(p)) throw new Error(`${what}: "${line}" is not a number.`);+ out.push(Number(p));+ }+ return out;+}++function triple(line: string, what: string): Triple {+ const n = numbers(line, what);+ if (n.length !== 3) throw new Error(`${what}: "${line}" should be three numbers.`);+ return [n[0], n[1], n[2]];+}++function range(min: Triple, max: Triple): void {+ for (let i = 0; i < 3; i++) {+ if (!(max[i] > min[i])) throw new Error("LUT input range is empty.");+ }+}++/** Adobe Cube LUT Spec 1.0, with the input-range keywords and the+ * shaper-followed-by-cube layout. */+export function parseCube(text: string): ParsedLut {+ let title: string | undefined;+ let domainMin: Triple | undefined;+ let domainMax: Triple | undefined;+ type Block = {+ kind: "1d" | "3d";+ size: number;+ data: Float32Array;+ filled: number;+ range?: [number, number];+ };+ let shaper: Block | undefined;+ let cube: Block | undefined;+ let current: Block | undefined;++ for (const line of lines(text)) {+ const word = /^[A-Za-z_][A-Za-z0-9_]*/.exec(line)?.[0];+ if (word) {+ const rest = line.slice(word.length).trim();+ switch (word) {+ case "TITLE":+ title = rest.replace(/^"(.*)"$/, "$1");+ break;+ case "DOMAIN_MIN":+ domainMin = triple(rest, "DOMAIN_MIN");+ break;+ case "DOMAIN_MAX":+ domainMax = triple(rest, "DOMAIN_MAX");+ break;+ case "LUT_1D_SIZE": {+ if (shaper) throw new Error("LUT_1D_SIZE appears twice.");+ const size = Number(rest);+ if (!Number.isInteger(size) || size < SHAPER_MIN || size > SHAPER_MAX)+ throw new Error(`LUT_1D_SIZE must be ${SHAPER_MIN}..${SHAPER_MAX}.`);+ shaper = current = { kind: "1d", size, data: new Float32Array(size * 3), filled: 0 };+ break;+ }+ case "LUT_3D_SIZE": {+ if (cube) throw new Error("LUT_3D_SIZE appears twice.");+ const size = Number(rest);+ if (!Number.isInteger(size) || size < CUBE_MIN || size > CUBE_MAX)+ throw new Error(`LUT_3D_SIZE must be ${CUBE_MIN}..${CUBE_MAX}.`);+ cube = current = { kind: "3d", size, data: new Float32Array(size * size * size * 3), filled: 0 };+ break;+ }+ case "LUT_1D_INPUT_RANGE":+ case "LUT_3D_INPUT_RANGE": {+ const n = numbers(rest, word);+ if (n.length !== 2) throw new Error(`${word} should be two numbers.`);+ const block = word === "LUT_1D_INPUT_RANGE" ? shaper : cube;+ if (!block) throw new Error(`${word} comes before its size.`);+ block.range = [n[0], n[1]];+ break;+ }+ default:+ // Vendor keywords ride along in real files; they change nothing here.+ break;+ }+ continue;+ }+ if (!current) throw new Error("LUT data comes before LUT_1D_SIZE or LUT_3D_SIZE.");+ if (current.filled >= current.data.length) throw new Error("The LUT has more lines than its size says.");+ const [r, g, b] = triple(line, "LUT data");+ current.data[current.filled++] = r;+ current.data[current.filled++] = g;+ current.data[current.filled++] = b;+ }++ if (!shaper && !cube) throw new Error("The file has no LUT_1D_SIZE or LUT_3D_SIZE.");+ const finish = (block: Block): LutTable => {+ if (block.filled !== block.data.length)+ throw new Error(+ `The LUT has ${block.filled / 3} lines; its size says ${block.data.length / 3}.`,+ );+ const min: Triple = block.range ? [block.range[0], block.range[0], block.range[0]] : domainMin ?? [0, 0, 0];+ const max: Triple = block.range ? [block.range[1], block.range[1], block.range[1]] : domainMax ?? [1, 1, 1];+ range(min, max);+ return { size: block.size, data: block.data, min, max };+ };+ const out: ParsedLut = {};+ if (title) out.title = title;+ if (shaper) out.shaper = finish(shaper);+ if (cube) out.cube = finish(cube);+ return out;+}++/** Autodesk `.3dl`: a line of input sample points, then integer output+ * triplets with blue running fastest. Bit depths are read off the file: input+ * from the last sample point, output from a `Mesh` header when there is one+ * and from the largest value otherwise. */+export function parse3dl(text: string): ParsedLut {+ const body = lines(text);+ let meshBits: number | undefined;+ let samples: number[] | undefined;+ const values: number[] = [];+ for (const line of body) {+ if (/^3DMESH\b/i.test(line)) continue;+ const mesh = /^Mesh\s+(\d+)\s+(\d+)/i.exec(line);+ if (mesh) {+ meshBits = Number(mesh[2]);+ continue;+ }+ if (/^[A-Za-z]/.test(line)) continue;+ if (!samples) {+ samples = numbers(line, "3dl sample points");+ if (samples.length < CUBE_MIN || samples.length > CUBE_MAX)+ throw new Error(`A 3dl LUT has ${CUBE_MIN}..${CUBE_MAX} sample points per axis.`);+ continue;+ }+ const n = numbers(line, "3dl data");+ if (n.length !== 3) throw new Error(`3dl data: "${line}" should be three numbers.`);+ for (const v of n) {+ if (!Number.isInteger(v) || v < 0) throw new Error(`3dl data: "${line}" should be whole numbers.`);+ values.push(v);+ }+ }+ if (!samples) throw new Error("The 3dl file has no sample points line.");+ const size = samples.length;+ if (values.length !== size * size * size * 3)+ throw new Error(`The 3dl LUT has ${values.length / 3} lines; ${size} sample points need ${size ** 3}.`);+ const top = samples[size - 1];+ const inputBits = Math.max(1, Math.ceil(Math.log2(top + 1)));+ const inputScale = 2 ** inputBits - 1;+ let peak = 0;+ for (const v of values) if (v > peak) peak = v;+ const detected = peak <= 1023 ? 10 : peak <= 4095 ? 12 : 16;+ const outputBits = meshBits ?? Math.max(inputBits, detected);+ const outputScale = 2 ** outputBits - 1;+ const data = new Float32Array(size * size * size * 3);+ for (let r = 0; r < size; r++) {+ for (let g = 0; g < size; g++) {+ for (let b = 0; b < size; b++) {+ const from = ((r * size + g) * size + b) * 3;+ const to = ((b * size + g) * size + r) * 3;+ data[to] = values[from] / outputScale;+ data[to + 1] = values[from + 1] / outputScale;+ data[to + 2] = values[from + 2] / outputScale;+ }+ }+ }+ const lo = samples[0] / inputScale;+ const hi = top / inputScale;+ const min: Triple = [lo, lo, lo];+ const max: Triple = [hi, hi, hi];+ range(min, max);+ return { cube: { size, data, min, max } };+}++/** Parse by the file's extension — a technical field, never the user's words. */+export function parseLutFile(fileName: string, text: string): ParsedLut {+ const ext = /\.([a-z0-9]+)$/i.exec(fileName)?.[1]?.toLowerCase();+ if (ext === "cube") return parseCube(text);+ if (ext === "3dl") return parse3dl(text);+ throw new Error("LUT files are .cube or .3dl.");+}++const unit = (v: number, lo: number, hi: number): number => {+ const t = (v - lo) / (hi - lo);+ return t <= 0 ? 0 : t >= 1 ? 1 : t;+};++function sampleShaper(t: LutTable, v: number, c: number): number {+ const x = unit(v, t.min[c], t.max[c]) * (t.size - 1);+ const i0 = Math.min(t.size - 2, Math.floor(x));+ const f = x - i0;+ const a = t.data[i0 * 3 + c];+ const b = t.data[(i0 + 1) * 3 + c];+ return a + (b - a) * f;+}++/** Tetrahedral interpolation on the cube: the scheme ffmpeg's lut3d defaults+ * to and the one the preview and the CPU path use for grade lattices. */+function sampleCube(t: LutTable, r: number, g: number, b: number): Triple {+ const { size, data } = t;+ const rf = unit(r, t.min[0], t.max[0]) * (size - 1);+ const gf = unit(g, t.min[1], t.max[1]) * (size - 1);+ const bf = unit(b, t.min[2], t.max[2]) * (size - 1);+ const r0 = Math.min(size - 2, Math.floor(rf));+ const g0 = Math.min(size - 2, Math.floor(gf));+ const b0 = Math.min(size - 2, Math.floor(bf));+ const dr = rf - r0;+ const dg = gf - g0;+ const db = bf - b0;+ const R = 3;+ const G = size * 3;+ const B = size * size * 3;+ const c0 = (b0 * size * size + g0 * size + r0) * 3;+ let w1: number, w2: number, w3: number, o1: number, o2: number, o3: number;+ if (dr >= dg) {+ if (dg >= db) {+ w1 = dr - dg; w2 = dg - db; w3 = db; o1 = R; o2 = R + G; o3 = R + G + B;+ } else if (dr >= db) {+ w1 = dr - db; w2 = db - dg; w3 = dg; o1 = R; o2 = R + B; o3 = R + G + B;+ } else {+ w1 = db - dr; w2 = dr - dg; w3 = dg; o1 = B; o2 = R + B; o3 = R + G + B;+ }+ } else if (db >= dg) {+ w1 = db - dg; w2 = dg - dr; w3 = dr; o1 = B; o2 = G + B; o3 = R + G + B;+ } else if (db >= dr) {+ w1 = dg - db; w2 = db - dr; w3 = dr; o1 = G; o2 = G + B; o3 = R + G + B;+ } else {+ w1 = dg - dr; w2 = dr - db; w3 = db; o1 = G; o2 = R + G; o3 = R + G + B;+ }+ const w0 = 1 - w1 - w2 - w3;+ const out: Triple = [0, 0, 0];+ for (let c = 0; c < 3; c++) {+ out[c] =+ w0 * data[c0 + c] ++ w1 * data[c0 + o1 + c] ++ w2 * data[c0 + o2 + c] ++ w3 * data[c0 + o3 + c];+ }+ return out;+}++/** The LUT's output for one colour: the shaper per channel (linear), then the+ * cube (tetrahedral), each mapped through its own input domain. Outputs are+ * returned as the file gives them, unclamped. */+export function sampleLut(lut: ParsedLut, r: number, g: number, b: number): Triple {+ if (lut.shaper) {+ r = sampleShaper(lut.shaper, r, 0);+ g = sampleShaper(lut.shaper, g, 1);+ b = sampleShaper(lut.shaper, b, 2);+ }+ if (lut.cube) return sampleCube(lut.cube, r, g, b);+ return [r, g, b];+}++/** What a card or a chip says about the file. */+export function lutFacts(lut: ParsedLut): { kind: LutKind; size: number } {+ if (lut.cube) return { kind: lut.shaper ? "shaper+3d" : "3d", size: lut.cube.size };+ if (lut.shaper) return { kind: "1d", size: lut.shaper.size };+ throw new Error("The LUT has no table.");+}++/** Bytes the parsed tables stand on, for a cache that counts them. */+export const lutBytes = (lut: ParsedLut): number =>+ (lut.shaper?.data.byteLength ?? 0) + (lut.cube?.data.byteLength ?? 0);diff --git a/site/packages/effects-kit/src/presets/bw.json b/site/packages/effects-kit/src/presets/bw.jsonindex f7fc4335..19d14115 100644--- a/site/packages/effects-kit/src/presets/bw.json+++ b/site/packages/effects-kit/src/presets/bw.json@@ -5,7 +5,8 @@"category": "bw","grade": {"saturation": -50,- "contrast": 10+ "contrast": 8,+ "blacks": -14}},{@@ -14,10 +15,11 @@"category": "bw","grade": {"saturation": -50,- "contrast": -4,+ "contrast": -7,"exposure": 6,"shadows": 8,- "highlights": -4+ "highlights": -3,+ "blacks": 20}},{@@ -26,9 +28,10 @@"category": "bw","grade": {"saturation": -50,- "contrast": 24,- "shadows": -8,- "curves": { "m": [[0, 0], [48, 32], [128, 134], [208, 244], [255, 255]] }+ "contrast": 13,+ "shadows": -3,+ "curves": { "m": [[0, 0], [48, 32], [128, 134], [208, 244], [255, 255]] },+ "blacks": -33}},{@@ -38,9 +41,10 @@"grade": {"saturation": -50,"exposure": 10,- "contrast": -6,- "shadows": 10,- "highlights": -2+ "contrast": -12,+ "shadows": 7,+ "highlights": 9,+ "blacks": 24}},{@@ -50,9 +54,10 @@"grade": {"saturation": -50,"exposure": -8,- "contrast": 16,- "shadows": -10,- "highlights": -4+ "contrast": 4,+ "shadows": -16,+ "highlights": 7,+ "blacks": -34}},{@@ -61,8 +66,9 @@"category": "bw","grade": {"saturation": -50,- "contrast": 6,- "curves": { "m": [[0, 16], [128, 120], [255, 240]] }+ "contrast": 4,+ "curves": { "m": [[0, 16], [128, 120], [255, 240]] },+ "blacks": -8}},{@@ -71,9 +77,10 @@"category": "bw","grade": {"saturation": -50,- "contrast": -10,+ "contrast": -7,"exposure": 3,- "curves": { "m": [[0, 12], [255, 244]] }+ "curves": { "m": [[0, 12], [255, 244]] },+ "blacks": 16}},{@@ -82,10 +89,11 @@"category": "bw","grade": {"saturation": -50,- "contrast": 16,+ "contrast": 13,"exposure": -2,- "highlights": 10,- "curves": { "m": [[0, 16], [48, 38], [128, 138], [200, 226], [255, 255]] }+ "highlights": 7,+ "curves": { "m": [[0, 16], [48, 38], [128, 138], [200, 226], [255, 255]] },+ "blacks": -16}}]diff --git a/site/packages/effects-kit/src/presets/cinematic.json b/site/packages/effects-kit/src/presets/cinematic.jsonindex ae41e686..4676e160 100644--- a/site/packages/effects-kit/src/presets/cinematic.json+++ b/site/packages/effects-kit/src/presets/cinematic.json@@ -4,10 +4,11 @@"label": "Teal & Orange","category": "cinematic","grade": {- "contrast": 10,- "vibrance": 10,+ "contrast": 7,+ "vibrance": -2,"saturation": 6,- "wheels": { "s": [-22, 0, 0], "h": [12, 7, 0] }+ "wheels": { "s": [-39, -1, -16], "h": [6, 6, 3] },+ "blacks": 13}},{@@ -15,10 +16,11 @@"label": "Bleach Bypass","category": "cinematic","grade": {- "contrast": 22,- "saturation": -30,- "highlights": -6,- "shadows": -8+ "contrast": 8,+ "saturation": -27,+ "highlights": 10,+ "shadows": -14,+ "blacks": -33}},{@@ -26,11 +28,12 @@"label": "Matinee","category": "cinematic","grade": {- "exposure": 3,- "contrast": 8,+ "exposure": 9,+ "contrast": -7,"temperature": 4,"saturation": 18,- "vibrance": 8+ "vibrance": 6,+ "blacks": -25}},{@@ -38,11 +41,12 @@"label": "Thriller","category": "cinematic","grade": {- "temperature": -14,- "contrast": 16,- "shadows": -10,- "saturation": -10,- "wheels": { "s": [-8, -14, 0] }+ "temperature": -17,+ "contrast": 10,+ "shadows": -9,+ "saturation": -6,+ "wheels": { "s": [-6, -12, 0] },+ "blacks": -28}},{@@ -51,11 +55,12 @@"category": "cinematic","grade": {"temperature": -6,- "tint": 8,- "contrast": 10,- "shadows": 6,- "vibrance": 16,- "hsl": { "magenta": [0, 12, 4], "aqua": [0, 10, 0] }+ "tint": 4,+ "contrast": 1,+ "shadows": -1,+ "vibrance": 20,+ "hsl": { "aqua": [-4, 2, 5], "magenta": [4, 8, 7] },+ "blacks": -7}},{@@ -63,11 +68,12 @@"label": "Sci-Fi","category": "cinematic","grade": {- "temperature": -18,- "tint": -8,- "contrast": 12,- "saturation": -6,- "highlights": -4+ "temperature": -21,+ "tint": -9,+ "contrast": 1,+ "saturation": -2,+ "highlights": 5,+ "blacks": -19}},{@@ -75,12 +81,13 @@"label": "Western","category": "cinematic","grade": {- "temperature": 16,- "tint": 4,- "contrast": 6,- "shadows": 4,- "saturation": -4,- "hsl": { "green": [-10, -25, -4] }+ "temperature": 18,+ "tint": 7,+ "contrast": 3,+ "shadows": 3,+ "saturation": -2,+ "hsl": { "green": [-6, -32, -16] },+ "blacks": 3}},{@@ -88,10 +95,11 @@"label": "Indie","category": "cinematic","grade": {- "temperature": 3,+ "temperature": 4,"contrast": -4,- "saturation": -12,- "curves": { "m": [[0, 18], [128, 128], [255, 244]] }+ "saturation": -10,+ "curves": { "m": [[0, 18], [128, 128], [255, 244]] },+ "blacks": 3}}]diff --git a/site/packages/effects-kit/src/presets/film.json b/site/packages/effects-kit/src/presets/film.jsonindex 24e8ed63..c587ba18 100644--- a/site/packages/effects-kit/src/presets/film.json+++ b/site/packages/effects-kit/src/presets/film.json@@ -6,8 +6,8 @@"grade": {"saturation": -2,"vibrance": 6,- "contrast": 4,- "highlights": -6,+ "contrast": 3,+ "highlights": -9,"shadows": 3,"curves": {"r": [[0, 10], [24, 24], [64, 64], [128, 133], [192, 199], [224, 230], [255, 248]],@@ -15,15 +15,16 @@"b": [[0, 17], [24, 31], [64, 68], [128, 125], [192, 187], [224, 217], [255, 239]]},"hsl": {- "red": [4, 2, 0],- "orange": [-4, 2, 1],- "yellow": [6, -10, 6],- "green": [10, -8, 4],- "aqua": [8, 6, -6],- "blue": [6, -6, 3],- "purple": [-2, -6, 1],- "magenta": [4, 0, -1]- }+ "red": [5, 2, 0],+ "orange": [-5, 1, 1],+ "yellow": [5, -6, -2],+ "green": [4, -7, 2],+ "aqua": [17, 7, -10],+ "blue": [5, -2, 3],+ "purple": [-1, -5, 1],+ "magenta": [3, 0, -1]+ },+ "blacks": 2}},{@@ -31,12 +32,13 @@"label": "Super 8","category": "film","grade": {- "temperature": 14,- "tint": -3,- "contrast": 8,- "saturation": -6,- "shadows": 8,- "curves": { "m": [[0, 12], [255, 246]] }+ "temperature": 18,+ "tint": 1,+ "contrast": 4,+ "saturation": -4,+ "shadows": 9,+ "curves": { "m": [[0, 12], [255, 246]] },+ "blacks": 7}},{@@ -44,11 +46,12 @@"label": "Faded Film","category": "film","grade": {- "contrast": -8,- "saturation": -18,- "tint": 14,- "temperature": 2,- "curves": { "m": [[0, 30], [64, 80], [255, 232]] }+ "contrast": -14,+ "saturation": -13,+ "tint": 17,+ "temperature": 3,+ "curves": { "m": [[0, 30], [64, 80], [255, 232]] },+ "blacks": 4}},{@@ -56,11 +59,12 @@"label": "Chrome","category": "film","grade": {- "contrast": 14,+ "contrast": -2,"saturation": 14,- "vibrance": 6,- "highlights": -6,- "temperature": 2+ "vibrance": 7,+ "highlights": 14,+ "temperature": 2,+ "blacks": -23}},{@@ -69,10 +73,11 @@"category": "film","grade": {"exposure": 4,- "contrast": 20,- "saturation": -22,- "shadows": -10,- "curves": { "m": [[0, 0], [32, 14], [128, 132], [224, 238], [255, 255]] }+ "contrast": 17,+ "saturation": -21,+ "shadows": -5,+ "curves": { "m": [[0, 0], [32, 14], [128, 132], [224, 238], [255, 255]] },+ "blacks": -31}},{@@ -80,10 +85,11 @@"label": "Cine Print","category": "film","grade": {- "contrast": 18,- "saturation": -4,- "wheels": { "s": [-10, -6, 0], "m": [8, 4, 0] },- "curves": { "m": [[0, 6], [32, 20], [128, 130], [192, 204], [255, 250]] }+ "contrast": 12,+ "saturation": -2,+ "wheels": { "s": [-14, -10, -10], "m": [0, 1, 2] },+ "curves": { "m": [[0, 6], [32, 20], [128, 130], [192, 204], [255, 250]] },+ "blacks": -15}},{@@ -92,14 +98,15 @@"category": "film","grade": {"temperature": 6,- "tint": 2,- "contrast": 5,+ "tint": 3,+ "contrast": 4,"vibrance": 4,"curves": {"r": [[0, 14], [128, 134], [255, 250]],"g": [[0, 8], [128, 126], [255, 243]],"b": [[0, 2], [128, 114], [255, 230]]- }+ },+ "blacks": -8}},{@@ -107,14 +114,15 @@"label": "Instant","category": "film","grade": {- "exposure": 5,- "contrast": -10,- "saturation": -14,+ "exposure": 6,+ "contrast": -13,+ "saturation": -11,"curves": {"r": [[0, 20], [64, 78], [128, 138], [255, 240]],"g": [[0, 30], [64, 84], [128, 136], [255, 234]],"b": [[0, 33], [64, 84], [128, 128], [255, 222]]- }+ },+ "blacks": 9}},{@@ -122,14 +130,15 @@"label": "Expired","category": "film","grade": {- "saturation": -20,- "contrast": -6,+ "saturation": -16,+ "contrast": -1,"curves": {"r": [[0, 28], [64, 74], [128, 132], [255, 236]],"g": [[0, 20], [64, 79], [128, 140], [255, 242]],"b": [[0, 32], [64, 71], [128, 118], [255, 212]]},- "hsl": { "yellow": [10, -8, 4], "green": [8, -6, 2] }+ "hsl": { "yellow": [0, -34, -4], "green": [15, -12, 8] },+ "blacks": 11}}]diff --git a/site/packages/effects-kit/src/presets/mood.json b/site/packages/effects-kit/src/presets/mood.jsonindex 015cca4a..e373c184 100644--- a/site/packages/effects-kit/src/presets/mood.json+++ b/site/packages/effects-kit/src/presets/mood.json@@ -5,11 +5,12 @@"category": "mood","grade": {"exposure": -8,- "temperature": -12,- "contrast": 12,- "saturation": -12,- "shadows": -6,- "wheels": { "s": [-8, -12, 0] }+ "temperature": -14,+ "contrast": 5,+ "saturation": -9,+ "shadows": -8,+ "wheels": { "s": [-8, -12, -14] },+ "blacks": -5}},{@@ -17,11 +18,12 @@"label": "Moss","category": "mood","grade": {- "tint": -14,- "temperature": 4,- "saturation": -8,- "contrast": 6,- "hsl": { "green": [0, 8, 0] }+ "tint": -10,+ "temperature": 6,+ "saturation": -5,+ "contrast": 3,+ "hsl": { "green": [-2, 4, 5] },+ "blacks": -7}},{@@ -29,10 +31,11 @@"label": "Slate","category": "mood","grade": {- "temperature": -8,- "tint": -2,- "saturation": -20,- "contrast": 8+ "temperature": -9,+ "tint": -3,+ "saturation": -18,+ "contrast": 4,+ "blacks": -8}},{@@ -41,11 +44,12 @@"category": "mood","grade": {"temperature": -4,- "tint": 8,+ "tint": 2,"exposure": -3,- "contrast": 4,- "vibrance": 8,- "wheels": { "h": [6, -10, 0] }+ "contrast": 3,+ "vibrance": 6,+ "wheels": { "h": [5, -10, -6] },+ "blacks": -7}},{@@ -54,10 +58,11 @@"category": "mood","grade": {"vibrance": 22,- "contrast": 10,+ "contrast": -4,"saturation": 10,- "temperature": -6,- "tint": 10+ "temperature": -2,+ "tint": 6,+ "blacks": -22}},{@@ -65,12 +70,13 @@"label": "Arctic","category": "mood","grade": {- "temperature": -20,- "tint": -2,- "exposure": 2,- "contrast": 6,- "saturation": -6,- "highlights": 4+ "temperature": -26,+ "tint": -6,+ "exposure": -5,+ "contrast": -6,+ "saturation": -1,+ "highlights": 39,+ "blacks": -9}},{@@ -79,10 +85,11 @@"category": "mood","grade": {"temperature": -10,- "contrast": 14,- "saturation": -16,+ "contrast": 8,+ "saturation": -13,"exposure": -4,- "shadows": -8+ "shadows": -10,+ "blacks": -26}},{@@ -90,13 +97,14 @@"label": "Velvet","category": "mood","grade": {- "contrast": 10,+ "contrast": 6,"exposure": -4,"saturation": 12,- "temperature": 4,- "tint": 6,+ "temperature": 3,+ "tint": 4,"shadows": -6,- "curves": { "m": [[0, 6], [64, 56], [255, 252]] }+ "curves": { "m": [[0, 6], [64, 56], [255, 252]] },+ "blacks": -19}}]diff --git a/site/packages/effects-kit/src/presets/warm.json b/site/packages/effects-kit/src/presets/warm.jsonindex d949ffdd..6ec02ab3 100644--- a/site/packages/effects-kit/src/presets/warm.json+++ b/site/packages/effects-kit/src/presets/warm.json@@ -5,12 +5,13 @@"category": "warm","grade": {"exposure": 6,- "temperature": 18,+ "temperature": 17,"tint": 3,- "contrast": 4,- "highlights": -6,- "vibrance": 10,- "hsl": { "orange": [0, 10, 4] }+ "contrast": 1,+ "highlights": 2,+ "vibrance": 13,+ "hsl": { "orange": [-14, 2, 0] },+ "blacks": -8}},{@@ -18,11 +19,11 @@"label": "Amber","category": "warm","grade": {- "temperature": 22,- "tint": 2,- "contrast": 6,- "shadows": 6,- "saturation": 4+ "temperature": 23,+ "tint": 6,+ "shadows": 7,+ "saturation": 6,+ "blacks": 5}},{@@ -30,12 +31,13 @@"label": "Honey","category": "warm","grade": {- "temperature": 14,- "tint": 6,+ "temperature": 15,+ "tint": 8,"exposure": 4,- "contrast": -2,- "vibrance": 8,- "highlights": -4+ "contrast": -4,+ "vibrance": 9,+ "highlights": -4,+ "blacks": 1}},{@@ -43,11 +45,11 @@"label": "Sunbaked","category": "warm","grade": {- "temperature": 16,- "contrast": 10,- "saturation": -8,+ "temperature": 17,+ "contrast": 4,+ "saturation": -4,"highlights": -10,- "shadows": -4+ "blacks": -18}},{@@ -55,12 +57,13 @@"label": "Peach","category": "warm","grade": {- "temperature": 10,- "tint": 8,- "exposure": 5,- "saturation": 6,+ "temperature": 11,+ "tint": 9,+ "exposure": 4,+ "saturation": 7,"contrast": -4,- "curves": { "m": [[0, 10], [255, 250]] }+ "curves": { "m": [[0, 10], [255, 250]] },+ "blacks": 2}},{@@ -69,9 +72,10 @@"category": "warm","grade": {"saturation": -50,- "temperature": 34,- "tint": 5,- "contrast": 4+ "temperature": 42,+ "tint": 14,+ "contrast": -4,+ "blacks": -8}},{@@ -79,11 +83,12 @@"label": "Ember","category": "warm","grade": {- "temperature": 20,- "shadows": -8,+ "temperature": 19,+ "shadows": -1,"contrast": 12,- "vibrance": 4,- "hsl": { "red": [0, 4, 0] }+ "vibrance": 3,+ "hsl": { "red": [0, 5, 6] },+ "blacks": -21}},{@@ -91,11 +96,12 @@"label": "Bronze","category": "warm","grade": {- "temperature": 18,- "tint": -4,- "contrast": 8,- "saturation": -6,- "wheels": { "m": [10, 5, 0] }+ "temperature": 21,+ "tint": 1,+ "contrast": 10,+ "saturation": -5,+ "wheels": { "m": [6, 2, 5] },+ "blacks": -6}}]