Skip to content

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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..50
saturation?: 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, spatial
curves?: 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): ColorGrad
if (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.ts
index 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 pivot
highlights: 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.ts
index 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.ts
index 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[]; erro
errors.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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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
}
}
]