Skip to content

Open source CapCut alternative.

TypeScript
8.8 KB
Raw Blame
// Fits the shipped grade presets to the color-science spec
// (packages/effects-kit/src/gradeSpec.ts): each recipe's own numbers, plus
// orange and red hue bands that hold skin, move by coordinate descent until
// every bound the spec sets — identity, skin, saturation, levels, range on
// every source — is met with a small margin, staying as close to the
// original recipe as the bounds allow. Only presets that miss a bound move.
//
//   cd site && ./node_modules/.bin/bun scripts/tune-grade-presets.ts [preset ids…] [--write]

import { readFileSync, writeFileSync } from "node:fs";
import path from "node:path";
import {
  type ColorGrade,
  GRADE_SCALAR_FIELDS,
  createGradeTransform,
  normalizeGrade,
} from "../packages/effects-kit/src/index";
import { GRADE_PRESETS, type GradePreset } from "../packages/effects-kit/src/gradePresets";
import {
  type Expect,
  IDENTITY,
  LOOK_LOSS_MAX,
  PREMISE,
  isMonotone,
  levelsHold,
  measure,
  monochrome,
  rangeRamp,
  saturationBounded,
  skinStaysSkin,
  stopsLost,
} from "../packages/effects-kit/src/gradeSpec";
import type { OutputSpace, SourceProfile } from "../packages/effects-kit/src/colorSpace";

const PRESET_DIR = path.join(import.meta.dir, "../packages/effects-kit/src/presets");
const FILES = ["cinematic", "film", "warm", "mood", "bw"];

/** The sources and outputs a look has to keep its range on. */
const RANGE_CASES: [SourceProfile, OutputSpace][] = [
  ["rec709", "sdr"],
  ["apple-log", "sdr"],
  ["apple-log-2", "sdr"],
  ["hlg", "sdr"],
  ["apple-log-2", "hlg"],
];

/** How far inside each bound the fit aims, so LUT quantization cannot tip a
 * fitted value back over: a few percent of the bound. */
const margin = (n: number) => Math.max(Math.abs(n) * 0.03, 0.01);

/** An expect that records how far each bound is missed and keeps going. */
function recorder(): { expect: Expect; total: () => number } {
  let miss = 0;
  const expect: Expect = (v) => ({
    toBe: (want) => {
      if (v !== want) miss += 1;
    },
    toBeLessThan: (n) => (miss += Math.max(0, (v as number) - (n - margin(n))) / Math.max(1, Math.abs(n))),
    toBeLessThanOrEqual: (n) => (miss += Math.max(0, (v as number) - (n - margin(n))) / Math.max(1, Math.abs(n))),
    toBeGreaterThan: (n) => (miss += Math.max(0, n + margin(n) - (v as number)) / Math.max(1, Math.abs(n))),
    toBeGreaterThanOrEqual: (n) => (miss += Math.max(0, n + margin(n) - (v as number)) / Math.max(1, Math.abs(n))),
  });
  return { expect, total: () => miss };
}

/** Every bound the spec sets for a preset, summed as misses. */
function misses(p: GradePreset, grade: ColorGrade): number {
  const t = createGradeTransform(grade);
  if (!t) return 1e6;
  const m = measure((colors) =>
    colors.map((c) => t(c[0] / 255, c[1] / 255, c[2] / 255).map((v) => Math.max(0, Math.min(255, Math.round(v * 255)))))
  );
  const { expect, total } = recorder();
  IDENTITY[p.id]?.holds(m, expect);
  PREMISE[p.category]?.(m, expect);
  levelsHold(m, expect);
  if (p.category === "bw") monochrome(m, expect);
  else {
    skinStaysSkin(m, expect);
    saturationBounded(m, expect);
  }
  let range = 0;
  for (const [profile, output] of RANGE_CASES) {
    const base = rangeRamp(profile, output);
    const graded = rangeRamp(profile, output, grade);
    range += Math.max(0, stopsLost(base, graded) - (LOOK_LOSS_MAX - 0.1));
    if (!isMonotone(graded)) range += 1;
  }
  return total() + range;
}

/** A tunable number inside a grade, by path. */
type Knob = { path: (string | number)[]; min: number; max: number };

const SCALAR_RANGE = new Map(GRADE_SCALAR_FIELDS.map(([k, min, max]) => [k, [min, max] as const]));

function knobsOf(g: ColorGrade): Knob[] {
  const knobs: Knob[] = [];
  for (const [k, v] of Object.entries(g)) {
    if (typeof v === "number") {
      const [min, max] = SCALAR_RANGE.get(k) ?? [-50, 50];
      knobs.push({ path: [k], min, max });
    }
  }
  for (const zone of Object.keys(g.wheels ?? {})) for (let i = 0; i < 3; i++) knobs.push({ path: ["wheels", zone, i], min: -50, max: 50 });
  for (const band of new Set([...Object.keys(g.hsl ?? {}), "orange", "red"]))
    for (let i = 0; i < 2; i++) knobs.push({ path: ["hsl", band, i], min: -50, max: 50 });
  for (const [ch, pts] of Object.entries(g.curves ?? {}))
    for (let i = 0; i < (pts as unknown[]).length; i++) knobs.push({ path: ["curves", ch, i, 1], min: 0, max: 255 });
  return knobs;
}

function read(g: ColorGrade, p: (string | number)[]): number {
  let o: unknown = g;
  for (const k of p) o = (o as Record<string | number, unknown> | undefined)?.[k];
  return typeof o === "number" ? o : 0;
}

function write(g: ColorGrade, p: (string | number)[], v: number): ColorGrade {
  const out = structuredClone(g) as Record<string, unknown>;
  let o: Record<string | number, unknown> = out;
  for (let i = 0; i < p.length - 1; i++) {
    if (o[p[i]] === undefined) o[p[i]] = p[i] === "hsl" ? {} : [0, 0, 0];
    o = o[p[i]] as Record<string | number, unknown>;
  }
  o[p[p.length - 1]] = v;
  return out as ColorGrade;
}

/** A curve keeps its points rising: a point moves only between its neighbors. */
function curveOk(g: ColorGrade, p: (string | number)[]): boolean {
  if (p[0] !== "curves") return true;
  const pts = g.curves?.[p[1] as "m"] ?? [];
  return pts.every((pt, i) => i === 0 || pt[1] >= pts[i - 1][1]);
}

/** Squared distance from the original recipe, each knob over its span. */
function drift(g: ColorGrade, from: ColorGrade, knobs: Knob[]): number {
  return knobs.reduce((a, k) => a + ((read(g, k.path) - read(from, k.path)) / (k.max - k.min)) ** 2, 0);
}

const DRIFT_WEIGHT = 0.5;
const STEPS = [8, 4, 2, 1];

function fit(p: GradePreset): { grade: ColorGrade; before: number; after: number } {
  const from = p.grade;
  const knobs = knobsOf(from);
  const cost = (g: ColorGrade) => misses(p, g) * 100 + DRIFT_WEIGHT * drift(g, from, knobs);
  let best = from;
  let bestCost = cost(from);
  const before = misses(p, from);
  // Steepest coordinate descent: each round takes the single knob move that
  // helps most, so the recipe changes only where the bounds need it.
  for (const step of STEPS) {
    for (;;) {
      let move: ColorGrade | null = null;
      let moveCost = bestCost;
      for (const k of knobs) {
        for (const dir of [-1, 1]) {
          const v = Math.max(k.min, Math.min(k.max, read(best, k.path) + dir * step));
          const g = write(best, k.path, v);
          if (!curveOk(g, k.path)) continue;
          const c = cost(g);
          if (c < moveCost - 1e-9) {
            move = g;
            moveCost = c;
          }
        }
      }
      if (!move) break;
      best = move;
      bestCost = moveCost;
    }
  }
  return { grade: normalizeGrade(best) ?? from, before, after: misses(p, best) };
}

/* ------------------------------------------------------------------ */
/* Writing the catalog back in its own layout                          */
/* ------------------------------------------------------------------ */

const inline = (v: unknown): string =>
  Array.isArray(v)
    ? `[${v.map(inline).join(", ")}]`
    : v && typeof v === "object"
      ? `{ ${Object.entries(v).map(([k, x]) => `"${k}": ${inline(x)}`).join(", ")} }`
      : JSON.stringify(v);

function gradeText(g: ColorGrade): string {
  const lines = Object.entries(g).map(([k, v]) => {
    if (k === "curves" && Object.keys(v as object).length > 1) {
      const chans = Object.entries(v as object).map(([c, pts]) => `        "${c}": ${inline(pts)}`);
      return `      "curves": {\n${chans.join(",\n")}\n      }`;
    }
    return `      "${k}": ${inline(v)}`;
  });
  return `{\n${lines.join(",\n")}\n    }`;
}

function writeCatalog(file: string, presets: GradePreset[]): void {
  const entries = presets.map(
    (p) =>
      `  {\n    "id": ${JSON.stringify(p.id)},\n    "label": ${JSON.stringify(p.label)},\n    "category": ${JSON.stringify(p.category)},\n    "look": ${JSON.stringify(p.look)},\n    "grade": ${gradeText(p.grade)}\n  }`
  );
  writeFileSync(path.join(PRESET_DIR, `${file}.json`), `[\n${entries.join(",\n")}\n]\n`);
}

const args = process.argv.slice(2);
const shouldWrite = args.includes("--write");
const wanted = new Set(args.filter((a) => !a.startsWith("--")));
const tuned = new Map<string, ColorGrade>();
for (const p of Object.values(GRADE_PRESETS)) {
  if (wanted.size && !wanted.has(p.id)) continue;
  if (!wanted.size && misses(p, p.grade) === 0) continue;
  const { grade, before, after } = fit(p);
  tuned.set(p.id, grade);
  console.log(`${p.id.padEnd(14)} misses ${before.toFixed(3)} → ${after.toFixed(3)}  ${JSON.stringify(grade)}`);
}
if (shouldWrite) {
  for (const file of FILES) {
    const raw = JSON.parse(readFileSync(path.join(PRESET_DIR, `${file}.json`), "utf8")) as GradePreset[];
    writeCatalog(
      file,
      raw.map((p) => (tuned.has(p.id) ? { ...p, grade: tuned.get(p.id)! } : p))
    );
  }
  console.log(`wrote ${tuned.size} presets`);
}