Open source CapCut alternative.
TypeScript
fix(site): color presets are measured against what they emulate [rebuild]
David Le4698c0af1aee
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.mdindex 7917eef4..0fb386e5 100644--- a/docs/guides/cut/README.md+++ b/docs/guides/cut/README.md@@ -58,6 +58,12 @@ A clip's color is one field on the clip: an optional preset underneath and manuaPresets are JSON documents beside the effects kit, one file per category, and the kit's parser is the only doorway that data has into the engine — the shipped catalog loads through the same validation a user-imported or shared grade will use later. Every shipped recipe is an original design on this model.+Every preset is measured, not eyeballed, in two tiers. The first is safety, held to the references a colorist grades against: the ColorChecker chart pushed through each preset's real lookup table, skin kept on the vectorscope's skin-tone line and under a saturation ceiling, the gray ramp monotonic, shadow detail preserved, and any white-balance cast kept inside warming-gel range.++The second tier is identity. Every preset names something real — a film stock, a lab process, a lighting condition — and has to measure like the thing it names, so each one declares its referent alongside the signature that referent leaves on a chart. A bleach bypass has to actually drain color while contrast climbs; an expired stock has to show the crossover uneven dye decay produces; a sepia has to collapse the frame onto one tone rather than tinting surviving color. Presets also have to differ from each other: two recipes that land on the chart together are one look wearing two names, which is how a pair of near-duplicates can otherwise sit on the shelf unnoticed. Both tiers walk the catalog itself, so a preset added to the JSON must declare what it is and is held to the same standard without being registered anywhere.++Skin protection is one rule rather than a habit each stage has to keep. A preset marked to protect skin applies its tone in full and then blends the color it moved back toward the pixel's own, scaled to wherever the tone landed — so hue and saturation survive while brightness follows the grade. Because the rule sits at the end of a layer, a stage added later cannot leak color onto faces by forgetting to damp itself.+One transform renders everywhere. Grades that stay within the original scalar sliders keep the long-standing cheap path — a CSS filter string in the canvas and a lutrgb/hue chain in ffmpeg, derived from the same numbers — and saved grades from before the extension render byte-for-byte as they always did. Anything richer compiles to a single 3D lookup table sampled from one pure function: ffmpeg applies it as a .cube file through lut3d, the browser preview applies it in a WebGL pass, and a headless export applies it on the CPU, all three interpolating the same way. The timeline filmstrip alone approximates, carrying the scalar part of the grade as CSS and stating so in code; the preview and every export render the whole grade.The assistant grades through the same model: tools for presets, sliders, curves, wheels and hue bands, a stats reader so it grades from measured numbers, and a matcher that computes a grade carrying one shot onto a reference image or neighboring clip by quantile-mapping the channels into curves.diff --git a/site/packages/effects-kit/src/gradeEval.test.ts b/site/packages/effects-kit/src/gradeEval.test.tsnew file mode 100644index 00000000..281ff1fc--- /dev/null+++ b/site/packages/effects-kit/src/gradeEval.test.ts@@ -0,0 +1,672 @@+import { describe, expect, test } from "bun:test";+import { applyLutToImageData, buildGradeLut, type GradeLut } from "./gradeLut";+import { GRADE_PRESETS, type GradePreset } from "./gradePresets";++/**+ * Color-science evals for the shipped preset catalog, in two tiers.+ *+ * The first tier is safety, held against the references colorists grade with.+ * The chart is the X-Rite ColorChecker Classic in its published sRGB+ * renderings — the card every camera and pipeline is verified against. Skin is+ * held to the vectorscope's skin-tone line, where graded skin of every+ * complexion sits in one narrow warm band and saturation pushed past it reads+ * sunburned. Levels follow broadcast practice in the spirit of EBU R103: the+ * gray ramp stays monotonic, chart blacks keep shadow detail, and a+ * white-balance cast stays in warming-gel range.+ *+ * The second tier is identity: every preset names something real — a film+ * stock, a lab process, a lighting condition — and has to measure like the+ * thing it names. A "bleach bypass" that does not retain silver, or an+ * "expired" stock with no dye crossover, is a mislabeled look however+ * pleasant it is on one frame. Each entry states its referent and the+ * signature that referent has on a chart, and the catalog is walked so a+ * preset added to the JSON must declare one.+ *+ * Both tiers measure through the preset's real lookup table with the same+ * tetrahedral pass the preview, the export, and the worker apply.+ */++/** ColorChecker Classic, sRGB. */+const CHART: Record<string, [number, number, number]> = {+ darkSkin: [115, 82, 68],+ lightSkin: [194, 150, 130],+ blueSky: [98, 122, 157],+ foliage: [87, 108, 67],+ blueFlower: [133, 128, 177],+ bluishGreen: [103, 189, 170],+ orange: [214, 126, 44],+ purplishBlue: [80, 91, 166],+ moderateRed: [193, 90, 99],+ purple: [94, 60, 108],+ yellowGreen: [157, 188, 64],+ orangeYellow: [224, 163, 46],+ blue: [56, 61, 150],+ green: [70, 148, 73],+ red: [175, 54, 60],+ yellow: [231, 199, 31],+ magenta: [187, 86, 149],+ cyan: [8, 133, 161],+ white95: [243, 243, 242],+ neutral8: [200, 200, 200],+ neutral65: [160, 160, 160],+ neutral5: [122, 122, 121],+ neutral35: [85, 85, 85],+ black2: [52, 52, 52],+};++const PATCHES = Object.keys(CHART);+const SKIN = ["darkSkin", "lightSkin"];+const COLORFUL = PATCHES.filter((n) => !/^(white|neutral|black)/.test(n) && !SKIN.includes(n));+/** The chart's gray ramp, darkest first. */+const RAMP = ["black2", "neutral35", "neutral5", "neutral65", "neutral8", "white95"];+/** A synthetic exposure ramp for tone-response readings: index 0 is black. */+const GRAY = [0, 32, 64, 128, 192, 224, 255];+const [, SHADOW, , MID, , HIGH, WHITE] = GRAY.map((_, i) => i);++const hsv = ([r, g, b]: number[]) => {+ const mx = Math.max(r, g, b);+ const mn = Math.min(r, g, b);+ const d = mx - mn;+ let h = 0;+ if (d) {+ if (mx === r) h = ((g - b) / d) % 6;+ else if (mx === g) h = (b - r) / d + 2;+ else h = (r - g) / d + 4;+ h = (h * 60 + 360) % 360;+ }+ return { h, s: mx ? d / mx : 0 };+};+const luma = ([r, g, b]: number[]) => 0.2126 * r + 0.7152 * g + 0.0722 * b;+const hueDelta = (a: number, b: number) => {+ let d = (b - a) % 360;+ if (d > 180) d -= 360;+ if (d < -180) d += 360;+ return Math.abs(d);+};++/** Push a list of colors through a LUT with the production tetrahedral pass. */+function through(lut: GradeLut, colors: number[][]): number[][] {+ const px = new Uint8ClampedArray(colors.length * 4);+ colors.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, lut);+ return colors.map((_, i) => [px[i * 4], px[i * 4 + 1], px[i * 4 + 2]]);+}++interface Measured {+ /** The graded chart, by patch name. */+ patch: Record<string, number[]>;+ /** Pure black and pure white as rendered — the film toe and shoulder. */+ black: number;+ white: number;+ /** Mid gray as rendered: the look's overall level. */+ mid: number;+ /** Tone-curve slope across the middle of the range: contrast. */+ slope: number;+ /** R−B at shadow / mid / highlight. Positive is warm. */+ warm: { s: number; m: number; h: number };+ /** G − (R+B)/2 at shadow / mid / highlight. Positive is green, negative magenta. */+ green: { s: number; m: number; h: number };+ /** Mean saturation multiplier over the chart's colorful patches. */+ sat: number;+ /** Hue variety left in the chart: 1 is the full wheel, 0 is a single tone. */+ spread: number;+ /** R−B on the light-skin patch. */+ skinWarm: number;+}++function measure(lut: GradeLut): Measured {+ const chart = through(+ lut,+ PATCHES.map((n) => CHART[n])+ );+ const patch: Record<string, number[]> = {};+ PATCHES.forEach((n, i) => (patch[n] = chart[i]));+ const gray = through(+ lut,+ GRAY.map((s) => [s, s, s])+ );+ const warmOf = (c: number[]) => c[0] - c[2];+ const greenOf = (c: number[]) => Math.round(c[1] - (c[0] + c[2]) / 2);+ const mults = COLORFUL.map((n) => {+ const before = hsv(CHART[n]).s;+ return before > 0.05 ? hsv(patch[n]).s / before : 1;+ });+ // Circular mean of the surviving hues: a toning process collapses them all+ // onto one, which shows up here as a spread near zero.+ const hues = COLORFUL.filter((n) => hsv(patch[n]).s > 0.08).map((n) => hsv(patch[n]).h);+ const cx = hues.reduce((a, h) => a + Math.cos((h * Math.PI) / 180), 0) / (hues.length || 1);+ const cy = hues.reduce((a, h) => a + Math.sin((h * Math.PI) / 180), 0) / (hues.length || 1);+ return {+ patch,+ black: luma(gray[0]),+ white: luma(gray[WHITE]),+ mid: luma(gray[MID]),+ slope: (luma(gray[HIGH]) - luma(gray[SHADOW])) / (GRAY[HIGH] - GRAY[SHADOW]),+ warm: { s: warmOf(gray[SHADOW]), m: warmOf(gray[MID]), h: warmOf(gray[HIGH]) },+ green: { s: greenOf(gray[SHADOW]), m: greenOf(gray[MID]), h: greenOf(gray[HIGH]) },+ sat: mults.reduce((a, b) => a + b, 0) / mults.length,+ spread: 1 - Math.hypot(cx, cy),+ skinWarm: warmOf(patch.lightSkin),+ };+}++const lutOf = (p: GradePreset, extra: { amount?: number; skin?: boolean } = {}): GradeLut => {+ const lut = buildGradeLut({ preset: { id: p.id, ...extra } });+ if (!lut) throw new Error(`${p.id}: preset builds no LUT`);+ return lut;+};++const presets = Object.values(GRADE_PRESETS);+const colorPresets = presets.filter((p) => p.category !== "bw");+const bwPresets = presets.filter((p) => p.category === "bw");+/** A toning process puts one hue over the whole frame, so the rails that+ * assume the grade preserved color relationships do not apply to it. */+const isToned = (m: Measured) => m.spread <= 0.1;++/* ------------------------------------------------------------------ */+/* Tier 1: safety */+/* ------------------------------------------------------------------ */++describe("skin stays skin", () => {+ for (const p of colorPresets)+ test(p.id, () => {+ const m = measure(lutOf(p));+ for (const name of SKIN) {+ const before = hsv(CHART[name]);+ const after = hsv(m.patch[name]);+ // Saturation may deepen by at most about a fifth of the scale, and a+ // face never reads more saturated than sunburn territory.+ expect(after.s - before.s).toBeLessThanOrEqual(0.22);+ expect(after.s).toBeLessThanOrEqual(0.7);+ // While the face still carries color it holds the skin-tone line: the+ // warm band, close to where it started. A muted face may drift — with+ // little chroma its hue no longer reads — and a toned monochrome puts+ // every subject on the tone's hue by definition, so only the band+ // applies there.+ if (after.s >= 0.3) {+ expect(after.h).toBeGreaterThanOrEqual(5);+ expect(after.h).toBeLessThanOrEqual(45);+ if (!isToned(m)) expect(hueDelta(before.h, after.h)).toBeLessThanOrEqual(12);+ }+ }+ });+});++describe("saturation energy is bounded", () => {+ for (const p of colorPresets)+ test(p.id, () => {+ const m = measure(lutOf(p));+ const mults = COLORFUL.map((n) => {+ const before = hsv(CHART[n]).s;+ return before > 0.05 ? hsv(m.patch[n]).s / before : 1;+ });+ // A grade may accent a hue; it never approaches doubling one, and the+ // chart as a whole gains at most ~40%.+ expect(m.sat).toBeLessThanOrEqual(1.4);+ expect(Math.max(...mults)).toBeLessThanOrEqual(1.75);+ });+});++describe("levels hold broadcast discipline", () => {+ for (const p of presets)+ test(p.id, () => {+ const m = measure(lutOf(p));+ // The gray ramp stays monotonic — a reversal is solarization.+ const ramp = RAMP.map((n) => luma(m.patch[n]));+ for (let i = 1; i < ramp.length; i++) expect(ramp[i]).toBeGreaterThanOrEqual(ramp[i - 1] - 1);+ // Chart black keeps shadow detail.+ expect(luma(m.patch.black2)).toBeGreaterThanOrEqual(12);+ // A cast on the mid grays stays in warming-gel range. A toning process+ // is a deliberate wash over the whole frame, judged by its own rail+ // below instead.+ if (!isToned(m)) {+ for (const name of ["neutral5", "neutral65"]) {+ const c = m.patch[name];+ expect(Math.max(...c) - Math.min(...c)).toBeLessThanOrEqual(48);+ }+ }+ });+});++describe("black & white means black & white", () => {+ for (const p of bwPresets)+ test(p.id, () => {+ const m = measure(lutOf(p));+ for (const name of PATCHES) {+ const c = m.patch[name];+ expect(Math.max(...c) - Math.min(...c)).toBeLessThanOrEqual(2);+ }+ });+});++describe("intensity scales toward neutral", () => {+ for (const p of presets)+ test(p.id, () => {+ const full = measure(lutOf(p));+ const half = measure(lutOf(p, { amount: 0.5 }));+ // At half intensity every skin channel sits between the original and the+ // full grade (small tolerance for LUT quantization), so the slider walks+ // the look in rather than to somewhere else.+ for (const name of SKIN) {+ for (let ch = 0; ch < 3; ch++) {+ const lo = Math.min(CHART[name][ch], full.patch[name][ch]) - 6;+ const hi = Math.max(CHART[name][ch], full.patch[name][ch]) + 6;+ expect(half.patch[name][ch]).toBeGreaterThanOrEqual(lo);+ expect(half.patch[name][ch]).toBeLessThanOrEqual(hi);+ }+ }+ });+});++describe("the skin flag protects faces", () => {+ for (const p of colorPresets)+ test(p.id, () => {+ const plain = measure(lutOf(p));+ const guarded = measure(lutOf(p, { skin: true }));+ for (const name of SKIN) {+ const before = hsv(CHART[name]);+ const plainShift = Math.abs(hsv(plain.patch[name]).s - before.s);+ const guardedShift = Math.abs(hsv(guarded.patch[name]).s - before.s);+ // Protection never adds chroma shift, and where the plain grade moved+ // skin saturation meaningfully it takes most of that move off.+ expect(guardedShift).toBeLessThanOrEqual(plainShift + 0.02);+ if (plainShift > 0.1) expect(guardedShift).toBeLessThanOrEqual(plainShift * 0.6);+ }+ });+});++/* ------------------------------------------------------------------ */+/* Tier 2: identity */+/* ------------------------------------------------------------------ */++interface Signature {+ /** What this preset is emulating, in the world. */+ process: string;+ /** What emulating it has to measure like on the chart. */+ holds(m: Measured): void;+}++const IDENTITY: Record<string, Signature> = {+ /* — cinematic ---------------------------------------------------- */+ "teal-orange": {+ process: "the complementary blockbuster split: shadows toward teal, skin and highlights toward orange",+ holds: (m) => {+ expect(m.warm.s).toBeLessThanOrEqual(-15);+ expect(m.warm.h - m.warm.s).toBeGreaterThanOrEqual(30);+ expect(m.skinWarm).toBeGreaterThanOrEqual(40);+ },+ },+ "bleach-bypass": {+ process: "silver retention: the bleach step is skipped so metallic silver stays in the print — contrast climbs and color drains",+ holds: (m) => {+ expect(m.sat).toBeLessThanOrEqual(0.75);+ expect(m.slope).toBeGreaterThanOrEqual(1.15);+ expect(m.black).toBeLessThanOrEqual(10);+ },+ },+ matinee: {+ process: "an old Hollywood matinee print: bright, warm, and full-blooded in color",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(3);+ expect(m.mid).toBeGreaterThanOrEqual(130);+ expect(m.sat).toBeGreaterThanOrEqual(1.1);+ },+ },+ thriller: {+ process: "the hard, cold tension grade: contrast up, everything pulled off warm",+ holds: (m) => {+ expect(m.warm.m).toBeLessThanOrEqual(-10);+ expect(m.slope).toBeGreaterThanOrEqual(1.12);+ expect(m.black).toBeLessThanOrEqual(10);+ },+ },+ "night-market": {+ process: "a neon-lit street after dark: cool highlights over saturated signage color",+ holds: (m) => {+ expect(m.warm.h).toBeLessThanOrEqual(-6);+ expect(m.sat).toBeGreaterThanOrEqual(1.08);+ },+ },+ "sci-fi": {+ process: "cold blue-cyan futurism, the cast deepening as it climbs the range",+ holds: (m) => {+ expect(m.warm.h).toBeLessThanOrEqual(-25);+ expect(m.warm.h).toBeLessThan(m.warm.m);+ },+ },+ western: {+ process: "sun-baked dust: strongly warm, and muted by the haze rather than punchy",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(12);+ expect(m.sat).toBeLessThanOrEqual(1.0);+ },+ },+ indie: {+ process: "the flat lifted-contrast indie look: milky blacks, gentle slope, drained color",+ holds: (m) => {+ expect(m.black).toBeGreaterThanOrEqual(14);+ expect(m.slope).toBeLessThanOrEqual(0.94);+ expect(m.sat).toBeLessThanOrEqual(0.82);+ },+ },++ /* — film --------------------------------------------------------- */+ "16mm": {+ process: "16mm color negative: a base-plus-fog toe, a gentle shoulder, and the stock's crossover from cool shadows into warm highlights",+ holds: (m) => {+ expect(m.black).toBeGreaterThanOrEqual(8);+ expect(m.white).toBeLessThanOrEqual(252);+ expect(m.warm.h - m.warm.s).toBeGreaterThanOrEqual(8);+ expect(m.sat).toBeLessThanOrEqual(1.05);+ },+ },+ "super-8": {+ process: "Super 8 home-movie reversal: warm, soft-shouldered, and lifted",+ holds: (m) => {+ expect(m.black).toBeGreaterThanOrEqual(14);+ expect(m.warm.m).toBeGreaterThanOrEqual(10);+ expect(m.slope).toBeLessThanOrEqual(1.0);+ expect(m.sat).toBeLessThanOrEqual(0.95);+ },+ },+ "faded-film": {+ process: "a faded release print: the cyan dye layer goes first, so the image drifts pink as it flattens",+ holds: (m) => {+ expect(m.black).toBeGreaterThanOrEqual(25);+ expect(m.slope).toBeLessThanOrEqual(0.82);+ expect(m.sat).toBeLessThanOrEqual(0.68);+ expect(m.green.m).toBeLessThanOrEqual(-4);+ },+ },+ chrome: {+ process: "Kodachrome-style reversal: dense blacks under famously rich color",+ holds: (m) => {+ expect(m.sat).toBeGreaterThanOrEqual(1.18);+ expect(m.black).toBeLessThanOrEqual(8);+ },+ },+ "push-process": {+ process: "pushed development: underexposure bought back in the tank — contrast and grain climb, the toe crushes, highlights blow, and color goes flat",+ holds: (m) => {+ expect(m.slope).toBeGreaterThanOrEqual(1.2);+ expect(m.black).toBeLessThanOrEqual(6);+ expect(m.sat).toBeLessThanOrEqual(0.96);+ },+ },+ "cine-print": {+ process: "print stock, the contrastiest link in the photochemical chain: dense blacks and controlled color",+ holds: (m) => {+ expect(m.slope).toBeGreaterThanOrEqual(1.12);+ expect(m.black).toBeLessThanOrEqual(12);+ },+ },+ tungsten: {+ process: "daylight stock under 3200K tungsten light: a source warming the whole scene, so the cast reaches the shadows rather than washing only the highlights",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(18);+ expect(m.warm.s).toBeGreaterThanOrEqual(12);+ expect(m.warm.h - m.warm.s).toBeLessThanOrEqual(28);+ },+ },+ instant: {+ process: "integral-tripack instant film: a milky toe, muted dyes, and cool shadows running into warm highlights",+ holds: (m) => {+ expect(m.black).toBeGreaterThanOrEqual(25);+ expect(m.slope).toBeLessThanOrEqual(0.88);+ expect(m.sat).toBeLessThanOrEqual(0.72);+ expect(m.warm.s).toBeLessThan(0);+ expect(m.warm.h).toBeGreaterThanOrEqual(5);+ },+ },+ expired: {+ process: "expired stock: the emulsion layers lose sensitivity at different rates, so a green-yellow cast settles over a fogged toe",+ holds: (m) => {+ expect(m.black).toBeGreaterThanOrEqual(20);+ expect(m.green.m).toBeGreaterThanOrEqual(6);+ expect(m.sat).toBeLessThanOrEqual(0.68);+ expect(m.slope).toBeLessThanOrEqual(0.92);+ },+ },++ /* — warm --------------------------------------------------------- */+ "golden-hour": {+ process: "low sun near the horizon: warm and bright, the light itself lifting the frame",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(16);+ expect(m.mid).toBeGreaterThanOrEqual(130);+ },+ },+ amber: {+ process: "an amber wash laid over the grade, weighted to the highlights the way a gel reads rather than a room light",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(20);+ expect(m.warm.h - m.warm.s).toBeGreaterThanOrEqual(30);+ },+ },+ honey: {+ process: "a soft honeyed warmth that leaves contrast where it found it",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(12);+ expect(m.slope).toBeLessThanOrEqual(1.08);+ },+ },+ sunbaked: {+ process: "hard sun on dry ground: warm and slightly bleached",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(12);+ expect(m.sat).toBeLessThanOrEqual(1.02);+ },+ },+ peach: {+ process: "a pale peach cast over a softly lifted toe",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(9);+ expect(m.black).toBeGreaterThanOrEqual(8);+ },+ },+ sepia: {+ process: "sepia toning: the print's silver is converted to silver sulfide, so the whole frame carries one brown tone rather than a tint over surviving color",+ holds: (m) => {+ expect(m.spread).toBeLessThanOrEqual(0.08);+ expect(m.warm.m).toBeGreaterThanOrEqual(28);+ },+ },+ ember: {+ process: "firelight: warm and contrasty, the glow strongest up top",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(17);+ expect(m.slope).toBeGreaterThanOrEqual(1.08);+ },+ },+ bronze: {+ process: "a burnished bronze cast, warm and slightly muted",+ holds: (m) => {+ expect(m.warm.m).toBeGreaterThanOrEqual(18);+ expect(m.sat).toBeLessThanOrEqual(1.02);+ },+ },++ /* — mood --------------------------------------------------------- */+ midnight: {+ process: "deep night: cool throughout and genuinely dark",+ holds: (m) => {+ expect(m.warm.m).toBeLessThanOrEqual(-8);+ expect(m.mid).toBeLessThanOrEqual(120);+ },+ },+ moss: {+ process: "damp woodland green, strengthening through the highlights",+ holds: (m) => {+ expect(m.green.m).toBeGreaterThanOrEqual(4);+ expect(m.green.h).toBeGreaterThanOrEqual(m.green.m);+ },+ },+ slate: {+ process: "cool grey stone: the cast pulled off warm and the color drained down",+ holds: (m) => {+ expect(m.warm.m).toBeLessThanOrEqual(-4);+ expect(m.sat).toBeLessThanOrEqual(0.85);+ },+ },+ dusk: {+ process: "the light after sundown: cool, dimming, and going magenta up top",+ holds: (m) => {+ expect(m.warm.m).toBeLessThan(0);+ expect(m.mid).toBeLessThanOrEqual(126);+ },+ },+ neon: {+ process: "neon: color pushed hard against a cool ground",+ holds: (m) => {+ expect(m.sat).toBeGreaterThanOrEqual(1.18);+ expect(m.warm.h).toBeLessThan(0);+ },+ },+ arctic: {+ process: "cold open daylight off snow: a strong blue cast climbing with the tone",+ holds: (m) => {+ expect(m.warm.h).toBeLessThanOrEqual(-28);+ expect(m.warm.h).toBeLessThan(m.warm.m);+ },+ },+ storm: {+ process: "storm light: cool, dark, and drained",+ holds: (m) => {+ expect(m.warm.m).toBeLessThanOrEqual(-5);+ expect(m.sat).toBeLessThanOrEqual(0.96);+ expect(m.mid).toBeLessThanOrEqual(124);+ },+ },+ velvet: {+ process: "deep low-light richness: color held up while the frame sits down",+ holds: (m) => {+ expect(m.sat).toBeGreaterThanOrEqual(1.15);+ expect(m.mid).toBeLessThanOrEqual(118);+ },+ },++ /* — black & white ------------------------------------------------ */+ mono: {+ process: "a straight panchromatic conversion: neutral, with normal contrast",+ holds: (m) => {+ expect(m.black).toBeLessThanOrEqual(8);+ expect(m.slope).toBeGreaterThanOrEqual(1.0);+ },+ },+ silver: {+ process: "a silver-gelatin print: a gently lifted toe and a soft slope",+ holds: (m) => {+ expect(m.black).toBeGreaterThanOrEqual(10);+ expect(m.slope).toBeLessThanOrEqual(1.05);+ },+ },+ ink: {+ process: "a hard graphic conversion: solid ink blacks, a steep clean slope, no veil in the toe",+ holds: (m) => {+ expect(m.slope).toBeGreaterThanOrEqual(1.2);+ expect(m.black).toBeLessThanOrEqual(8);+ },+ },+ "high-key": {+ process: "high-key lighting: the whole frame carried up, shadows opened",+ holds: (m) => {+ expect(m.mid).toBeGreaterThanOrEqual(140);+ expect(m.black).toBeGreaterThanOrEqual(14);+ },+ },+ "low-key": {+ process: "low-key lighting: the frame carried down onto dense blacks",+ holds: (m) => {+ expect(m.mid).toBeLessThanOrEqual(116);+ expect(m.black).toBeLessThanOrEqual(8);+ },+ },+ charcoal: {+ process: "charcoal on paper: a lifted toe under a soft, slightly dark rendering",+ holds: (m) => {+ expect(m.black).toBeGreaterThanOrEqual(10);+ expect(m.slope).toBeLessThanOrEqual(1.0);+ expect(m.mid).toBeLessThanOrEqual(126);+ },+ },+ "soft-mono": {+ process: "a soft monochrome: low slope over an open toe",+ holds: (m) => {+ expect(m.slope).toBeLessThanOrEqual(0.92);+ expect(m.black).toBeGreaterThanOrEqual(16);+ },+ },+ grit: {+ process: "pushed reportage monochrome: steep and harsh, but grain veils the toe — a pushed negative never scans to a clean black",+ holds: (m) => {+ expect(m.slope).toBeGreaterThanOrEqual(1.15);+ expect(m.black).toBeGreaterThanOrEqual(10);+ },+ },+};++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();+ const declared = Object.keys(IDENTITY).sort();+ // A preset added to the JSON has to say what it is; an entry left behind+ // by a removed preset has to go with it.+ expect(declared).toEqual(catalog);+ });+});++describe("a preset measures like the thing it names", () => {+ for (const p of presets) {+ const sig = IDENTITY[p.id];+ if (!sig) continue; // the coverage test above is what reports this+ test(`${p.id} — ${sig.process}`, () => {+ sig.holds(measure(lutOf(p)));+ });+ }+});++describe("no two presets are the same look", () => {+ // The whole graded chart is the signature; two recipes that land on it+ // together are one preset wearing two names, and a shelf of those wastes+ // the user's time however good each one is on its own.+ const signature = (p: GradePreset) => {+ const lut = lutOf(p);+ return through(+ lut,+ PATCHES.map((n) => CHART[n])+ ).flat();+ };+ const signed = presets.map((p) => ({ id: p.id, sig: signature(p) }));+ for (let i = 0; i < signed.length; i++)+ for (let j = i + 1; j < signed.length; j++) {+ const a = signed[i];+ const b = signed[j];+ test(`${a.id} vs ${b.id}`, () => {+ const apart = a.sig.reduce((sum, v, k) => sum + Math.abs(v - b.sig[k]), 0) / a.sig.length;+ expect(apart).toBeGreaterThanOrEqual(3);+ });+ }+});++describe("presets in a category share its premise", () => {+ const premise: Partial<Record<GradePreset["category"], (m: Measured) => void>> = {+ // A warm preset is warm — no exceptions, that is what the shelf means.+ warm: (m) => expect(m.warm.m).toBeGreaterThanOrEqual(8),+ // A film preset emulates a stock, and a stock has a characteristic curve:+ // a toe that lifts black, a shoulder that rolls highlights, or a slope+ // away from straight-through. A recipe that only shifts color is a cast,+ // not a stock.+ film: (m) =>+ expect(m.black >= 8 || m.white <= 250 || Math.abs(m.slope - 1) >= 0.1).toBe(true),+ };+ for (const p of presets) {+ const check = premise[p.category];+ if (!check) continue;+ test(`${p.category}: ${p.id}`, () => check(measure(lutOf(p))));+ }+});diff --git a/site/packages/effects-kit/src/gradeMath.ts b/site/packages/effects-kit/src/gradeMath.tsindex dff739e1..8f394bed 100644--- a/site/packages/effects-kit/src/gradeMath.ts+++ b/site/packages/effects-kit/src/gradeMath.ts@@ -5,8 +5,15 @@* off skin tones) and the manual adjustments on top — and each layer applies* its stages in one canonical order:*- * gain → contrast → wheels → highlights/shadows → curves → cast tint →- * HSL (global hue/saturation, vibrance, feathered hue bands) → clamp+ * gain → contrast → wheels → highlights/shadows → curves →+ * HSL (global hue/saturation, vibrance, feathered hue bands) → cast tint →+ * clamp+ *+ * 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.** 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@@ -362,7 +369,13 @@ function buildLayer(g: ColorGrade, skinDamp: boolean): Layer | null {}function applyLayer(v: [number, number, number], L: Layer, skinW: number): void {- const chromaScale = L.skinDamp ? 1 - skinW : 1;+ // 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.+ 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++) {@@ -377,7 +390,7 @@ function applyLayer(v: [number, number, number], L: Layer, skinW: number): voidconst 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] * chromaScale + w.luma;+ 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));@@ -400,24 +413,19 @@ function applyLayer(v: [number, number, number], L: Layer, skinW: number): voidv[c] = x;}}- if (L.tint) {- v[0] = clamp01(v[0] * (1 + (L.tint.r - 1) * chromaScale));- v[1] = clamp01(v[1] * (1 + (L.tint.g - 1) * chromaScale));- v[2] = clamp01(v[2] * (1 + (L.tint.b - 1) * chromaScale));- }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.hue) h += L.hue * chromaScale;- if (L.saturate !== 1) s *= 1 + (L.saturate - 1) * chromaScale;- if (L.vibrance) s += L.vibrance * 0.8 * s * (1 - s) * chromaScale;+ 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 (w <= 0) continue;- h += b.hueShift * w * chromaScale;- s *= 1 + b.sat * w * chromaScale;+ h += b.hueShift * w;+ s *= 1 + b.sat * w;l *= 1 + b.lum * 0.5 * w;}const rgb = hslToRgb(h, clamp01(s), clamp01(l));@@ -425,6 +433,23 @@ function applyLayer(v: [number, number, number], L: Layer, skinW: number): voidv[1] = clamp01(rgb[1]);v[2] = clamp01(rgb[2]);}+ 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 (pre) {+ // 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]);+ 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);+ }+ }}export type GradeTransform = (r: number, g: number, b: number) => [number, number, number];diff --git a/site/packages/effects-kit/src/presets/bw.json b/site/packages/effects-kit/src/presets/bw.jsonindex fb8ef58b..f7fc4335 100644--- a/site/packages/effects-kit/src/presets/bw.json+++ b/site/packages/effects-kit/src/presets/bw.json@@ -27,7 +27,8 @@"grade": {"saturation": -50,"contrast": 24,- "shadows": -10+ "shadows": -8,+ "curves": { "m": [[0, 0], [48, 32], [128, 134], [208, 244], [255, 255]] }}},{@@ -81,10 +82,10 @@"category": "bw","grade": {"saturation": -50,- "contrast": 20,+ "contrast": 16,"exposure": -2,- "shadows": -6,- "highlights": 6+ "highlights": 10,+ "curves": { "m": [[0, 16], [48, 38], [128, 138], [200, 226], [255, 255]] }}}]diff --git a/site/packages/effects-kit/src/presets/film.json b/site/packages/effects-kit/src/presets/film.jsonindex f9a1fc74..24e8ed63 100644--- a/site/packages/effects-kit/src/presets/film.json+++ b/site/packages/effects-kit/src/presets/film.json@@ -4,26 +4,25 @@"label": "16mm","category": "film","grade": {- "saturation": 4,- "vibrance": 25,- "tint": 4,- "highlights": -23,- "shadows": 6,- "contrast": 11,+ "saturation": -2,+ "vibrance": 6,+ "contrast": 4,+ "highlights": -6,+ "shadows": 3,"curves": {- "r": [[0, 12], [24, 13], [48, 26], [80, 50], [112, 101], [144, 148], [176, 204], [208, 232], [232, 245], [255, 244]],- "g": [[0, 12], [24, 18], [48, 21], [80, 50], [112, 102], [144, 150], [176, 208], [208, 235], [232, 246], [255, 248]],- "b": [[0, 24], [24, 18], [48, 22], [80, 56], [112, 105], [144, 163], [176, 212], [208, 233], [232, 238], [255, 238]]+ "r": [[0, 10], [24, 24], [64, 64], [128, 133], [192, 199], [224, 230], [255, 248]],+ "g": [[0, 11], [24, 25], [64, 64], [128, 129], [192, 194], [224, 225], [255, 245]],+ "b": [[0, 17], [24, 31], [64, 68], [128, 125], [192, 187], [224, 217], [255, 239]]},"hsl": {- "red": [16, 7, 4],- "orange": [-16, 8, 2],- "yellow": [16, -23, 25],- "green": [16, -10, 16],- "aqua": [14, 15, -16],- "blue": [16, -8, 6],- "purple": [-4, -12, 2],- "magenta": [16, 0, -2]+ "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]}}},@@ -45,9 +44,11 @@"label": "Faded Film","category": "film","grade": {- "contrast": -6,- "saturation": -14,- "curves": { "m": [[0, 26], [64, 74], [255, 235]] }+ "contrast": -8,+ "saturation": -18,+ "tint": 14,+ "temperature": 2,+ "curves": { "m": [[0, 30], [64, 80], [255, 232]] }}},{@@ -68,9 +69,10 @@"category": "film","grade": {"exposure": 4,- "contrast": 18,- "saturation": -8,- "shadows": -6+ "contrast": 20,+ "saturation": -22,+ "shadows": -10,+ "curves": { "m": [[0, 0], [32, 14], [128, 132], [224, 238], [255, 255]] }}},{@@ -78,10 +80,10 @@"label": "Cine Print","category": "film","grade": {- "contrast": 10,- "saturation": 4,+ "contrast": 18,+ "saturation": -4,"wheels": { "s": [-10, -6, 0], "m": [8, 4, 0] },- "curves": { "m": [[0, 10], [192, 198], [255, 248]] }+ "curves": { "m": [[0, 6], [32, 20], [128, 130], [192, 204], [255, 250]] }}},{@@ -89,11 +91,15 @@"label": "Tungsten","category": "film","grade": {- "temperature": 20,+ "temperature": 6,"tint": 2,- "shadows": 4,- "contrast": 6,- "vibrance": 4+ "contrast": 5,+ "vibrance": 4,+ "curves": {+ "r": [[0, 14], [128, 134], [255, 250]],+ "g": [[0, 8], [128, 126], [255, 243]],+ "b": [[0, 2], [128, 114], [255, 230]]+ }}},{@@ -101,12 +107,14 @@"label": "Instant","category": "film","grade": {- "exposure": 6,- "contrast": -8,- "temperature": 5,- "tint": 6,- "saturation": -10,- "curves": { "m": [[0, 20], [255, 240]] }+ "exposure": 5,+ "contrast": -10,+ "saturation": -14,+ "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]]+ }}},{@@ -114,12 +122,14 @@"label": "Expired","category": "film","grade": {- "tint": -12,- "temperature": 6,- "saturation": -16,- "contrast": -4,- "hsl": { "yellow": [8, -10, 0] },- "curves": { "m": [[0, 14], [255, 240]] }+ "saturation": -20,+ "contrast": -6,+ "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] }}}]diff --git a/site/packages/effects-kit/src/presets/warm.json b/site/packages/effects-kit/src/presets/warm.jsonindex 9007a5ef..d949ffdd 100644--- a/site/packages/effects-kit/src/presets/warm.json+++ b/site/packages/effects-kit/src/presets/warm.json@@ -68,9 +68,9 @@"label": "Sepia","category": "warm","grade": {- "temperature": 30,- "tint": 4,- "saturation": -35,+ "saturation": -50,+ "temperature": 34,+ "tint": 5,"contrast": 4}},@@ -79,11 +79,11 @@"label": "Ember","category": "warm","grade": {- "temperature": 24,+ "temperature": 20,"shadows": -8,"contrast": 12,- "vibrance": 6,- "hsl": { "red": [0, 12, 0] }+ "vibrance": 4,+ "hsl": { "red": [0, 4, 0] }}},{