Skip to content

Commit 75fbb10

Browse files
vanceingallsclaude
andcommitted
feat(core): bake a colour grade into a 3D LUT (.cube)
bakeHfColorGradingCube evaluates the runtime shader's colour path on the CPU (primary, tonal wheels, RGB and hue curves, secondaries, output LUT, intensity mix) through the same 8-bit texture quantisation, and writes a red-fastest .cube for ffmpeg's lut3d. Grades with spatial stages (grain, vignette, effects) throw, as does a grade whose LUT was not passed in. A Chromium test draws a 4,096-colour lattice through the real runtime and compares every tile with the bake. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 67c7ec2 commit 75fbb10

4 files changed

Lines changed: 878 additions & 1 deletion

File tree

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
import { existsSync } from "node:fs";
2+
import { resolve } from "node:path";
3+
import { buildSync } from "esbuild";
4+
import puppeteer, { type Browser, type Page } from "puppeteer-core";
5+
import { afterAll, beforeAll, describe, expect, it } from "vitest";
6+
import { bakeHfColorGradingCube, type HfColorGrading } from "@hyperframes/core";
7+
import { findSystemBrowser } from "../browser/manager.js";
8+
9+
// The baked .cube must give what the runtime's WebGL shader draws. A 16-step lattice of 8x8 tiles,
10+
// drawn 1:1, goes through the real runtime, and each tile centre is compared with the size-16
11+
// bake, whose points are exactly the lattice's codes (k/15 = 17k/255).
12+
13+
interface GradingTestApi {
14+
setGrading(target: string, grading: HfColorGrading): boolean;
15+
redraw(): number;
16+
}
17+
18+
declare global {
19+
interface Window {
20+
__bakeProbe: { createColorGradingRuntime(): GradingTestApi };
21+
__bakeTestRuntime: GradingTestApi;
22+
}
23+
}
24+
25+
const configured = process.env.HYPERFRAMES_BROWSER_PATH ?? process.env.PUPPETEER_EXECUTABLE_PATH;
26+
const executablePath =
27+
configured && existsSync(configured) ? configured : findSystemBrowser()?.executablePath;
28+
const runsChromium =
29+
!!executablePath &&
30+
(process.platform !== "win32" || process.env.HYPERFRAMES_BROWSER_TESTS === "1");
31+
32+
const STEPS = 16;
33+
const TILE = 8;
34+
const TILES_PER_ROW = 64;
35+
const SIDE = TILE * TILES_PER_ROW;
36+
37+
async function renderLattice(page: Page, grading: HfColorGrading): Promise<number[]> {
38+
return page.evaluate(
39+
(grading, side) => {
40+
const runtime = window.__bakeTestRuntime;
41+
if (!runtime.setGrading("#lattice", grading)) throw new Error("grading unavailable");
42+
runtime.redraw();
43+
const canvas = document.querySelector("canvas.__hf_color_grading_canvas__");
44+
if (!(canvas instanceof HTMLCanvasElement)) throw new Error("missing grading canvas");
45+
if (canvas.width !== side || canvas.height !== side) {
46+
throw new Error(`grading canvas is ${canvas.width}x${canvas.height}, not ${side}`);
47+
}
48+
const output = document.createElement("canvas");
49+
output.width = side;
50+
output.height = side;
51+
const context = output.getContext("2d");
52+
if (!context) throw new Error("missing output context");
53+
context.drawImage(canvas, 0, 0);
54+
return [...context.getImageData(0, 0, side, side).data];
55+
},
56+
grading,
57+
SIDE,
58+
);
59+
}
60+
61+
interface Difference {
62+
max: number;
63+
mean: number;
64+
/** The most the grade moved any lattice code, so an ungraded draw cannot pass. */
65+
moved: number;
66+
worst: string;
67+
}
68+
69+
function compareWithBake(pixels: readonly number[], grading: HfColorGrading): Difference {
70+
const rows = bakeHfColorGradingCube(grading, { size: STEPS })
71+
.trim()
72+
.split("\n")
73+
.slice(3)
74+
.map((row) => row.split(" ").map((value) => Math.round(Number(value) * 255)));
75+
let max = 0;
76+
let total = 0;
77+
let moved = 0;
78+
let worst = "";
79+
for (let index = 0; index < STEPS ** 3; index += 1) {
80+
const column = index % TILES_PER_ROW;
81+
const row = Math.floor(index / TILES_PER_ROW);
82+
const offset = ((row * TILE + TILE / 2) * SIDE + column * TILE + TILE / 2) * 4;
83+
const expected = rows[index] ?? [];
84+
const source = [
85+
index % STEPS,
86+
Math.floor(index / STEPS) % STEPS,
87+
Math.floor(index / STEPS ** 2),
88+
];
89+
for (let channel = 0; channel < 3; channel += 1) {
90+
const baked = expected[channel] ?? 0;
91+
const difference = Math.abs((pixels[offset + channel] ?? -1000) - baked);
92+
total += difference;
93+
moved = Math.max(moved, Math.abs(baked - (source[channel] ?? 0) * 17));
94+
if (difference > max) {
95+
max = difference;
96+
worst = `lattice ${index} channel ${channel}: drawn ${pixels[offset + channel]}, baked ${baked}`;
97+
}
98+
}
99+
}
100+
return { max, mean: total / (STEPS ** 3 * 3), moved, worst };
101+
}
102+
103+
const PRIMARY: HfColorGrading = {
104+
adjust: {
105+
exposure: 0.2,
106+
contrast: 0.25,
107+
highlights: -0.3,
108+
shadows: 0.2,
109+
whites: 0.1,
110+
blacks: -0.1,
111+
temperature: 0.3,
112+
tint: -0.15,
113+
vibrance: 0.4,
114+
saturation: -0.1,
115+
},
116+
};
117+
118+
const ADVANCED: HfColorGrading = {
119+
adjust: { contrast: 0.1, saturation: 0.1 },
120+
wheels: {
121+
shadows: { hue: 215, amount: 0.4, level: -0.05 },
122+
midtones: { hue: 100, amount: 0.15, level: 0.02 },
123+
highlights: { hue: 40, amount: 0.3, level: 0.04 },
124+
},
125+
curves: {
126+
master: [
127+
[0, 0],
128+
[0.25, 0.2],
129+
[0.75, 0.82],
130+
[1, 1],
131+
],
132+
red: [
133+
[0, 0.02],
134+
[0.5, 0.55],
135+
[1, 1],
136+
],
137+
},
138+
hueCurves: {
139+
hueVsSaturation: [
140+
[0, 0.3],
141+
[120, -0.4],
142+
[240, 0.2],
143+
],
144+
},
145+
secondaries: [
146+
{
147+
key: {
148+
hue: { center: 30, range: 25, softness: 20 },
149+
saturation: { min: 0.15, max: 1, softness: 0.1 },
150+
luma: { min: 0.1, max: 0.9, softness: 0.1 },
151+
},
152+
correction: { hueShift: -10, saturation: -0.2, luma: 0.03, temperature: 0.2 },
153+
},
154+
],
155+
};
156+
157+
describe.skipIf(!runsChromium)("baked .cube against the color grading shader", () => {
158+
let browser: Browser;
159+
let page: Page;
160+
const browserErrors: string[] = [];
161+
162+
beforeAll(async () => {
163+
const bundle = buildSync({
164+
entryPoints: [resolve("../core/src/runtime/colorGrading.ts")],
165+
bundle: true,
166+
platform: "browser",
167+
format: "iife",
168+
globalName: "__bakeProbe",
169+
write: false,
170+
});
171+
const script = bundle.outputFiles[0]?.text;
172+
if (!script) throw new Error("missing grading runtime");
173+
browser = await puppeteer.launch({
174+
headless: true,
175+
executablePath,
176+
args: [
177+
"--no-sandbox",
178+
"--enable-unsafe-swiftshader",
179+
"--use-gl=angle",
180+
"--use-angle=swiftshader",
181+
],
182+
});
183+
page = await browser.newPage();
184+
page.on("pageerror", (error) => browserErrors.push(String(error)));
185+
await page.setViewport({ width: SIDE, height: SIDE, deviceScaleFactor: 1 });
186+
await page.setContent(
187+
`<body style="margin:0"><img id="lattice" style="width:${SIDE}px;height:${SIDE}px;display:block"></body>`,
188+
);
189+
await page.evaluate("self.__name = self.__name || ((fn) => fn);");
190+
await page.addScriptTag({ content: script });
191+
await page.evaluate(
192+
async (steps, tile, perRow, side) => {
193+
const source = document.createElement("canvas");
194+
source.width = side;
195+
source.height = side;
196+
const context = source.getContext("2d");
197+
if (!context) throw new Error("missing source context");
198+
const code = (step: number) => Math.round((step * 255) / (steps - 1));
199+
for (let index = 0; index < steps ** 3; index += 1) {
200+
const r = code(index % steps);
201+
const g = code(Math.floor(index / steps) % steps);
202+
const b = code(Math.floor(index / (steps * steps)));
203+
context.fillStyle = `rgb(${r},${g},${b})`;
204+
context.fillRect((index % perRow) * tile, Math.floor(index / perRow) * tile, tile, tile);
205+
}
206+
const image = document.getElementById("lattice");
207+
if (!(image instanceof HTMLImageElement)) throw new Error("missing lattice image");
208+
image.src = source.toDataURL();
209+
await image.decode();
210+
window.__bakeTestRuntime = window.__bakeProbe.createColorGradingRuntime();
211+
},
212+
STEPS,
213+
TILE,
214+
TILES_PER_ROW,
215+
SIDE,
216+
);
217+
}, 120_000);
218+
219+
afterAll(async () => {
220+
await browser?.close();
221+
});
222+
223+
it.each([
224+
["a primary-only grade", PRIMARY],
225+
["wheels, an RGB curve, a hue curve and a secondary", ADVANCED],
226+
] satisfies [string, HfColorGrading][])(
227+
"agrees within two codes for %s",
228+
async (_name, grading) => {
229+
const difference = compareWithBake(await renderLattice(page, grading), grading);
230+
expect(difference.moved).toBeGreaterThan(20);
231+
expect(difference.max, difference.worst).toBeLessThanOrEqual(2);
232+
expect(difference.mean).toBeLessThan(0.1);
233+
expect(browserErrors).toEqual([]);
234+
},
235+
60_000,
236+
);
237+
});

0 commit comments

Comments
 (0)