Skip to content

Open source CapCut alternative.

TypeScript
9.3 KB
Raw Blame
import { describe, expect, test } from "bun:test";
import type { ColorGrade } from "./colorGrade";
import { createGradeTransform } from "./gradeMath";
import { type Lab, deltaE2000, displayToLab } from "./colorDifference";
import { type ClipColorRecipe, createClipTransform } from "./colorPipeline";
import { type SourceProfile, appleLogEncode, bt1886Decode } from "./colorSpace";
import { type StatsRender, autoGrade, colorStatsFromImageData, matchGrade, recipeStatsRender } from "./gradeMatch";
import type { ParsedLut } from "./lutFile";

/** A synthetic frame with tonal and color variety. */
function testFrame(): Uint8ClampedArray {
  const w = 64;
  const h = 64;
  const data = 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;
      data[o] = Math.round((x / (w - 1)) * 255);
      data[o + 1] = Math.round((y / (h - 1)) * 255);
      data[o + 2] = Math.round(((x + y) / (w + h - 2)) * 200 + 20);
      data[o + 3] = 255;
    }
  }
  return data;
}

/** A clip's code values rendered through its recipe with `grade`, as pixels. */
function rendered(px: Uint8ClampedArray, recipe: ClipColorRecipe, grade?: ColorGrade): Lab[] {
  const fn = createClipTransform({ ...recipe, grade });
  const out: Lab[] = [];
  for (let i = 0; i < px.length; i += 4) {
    const v = fn ? fn(px[i] / 255, px[i + 1] / 255, px[i + 2] / 255) : [px[i] / 255, px[i + 1] / 255, px[i + 2] / 255];
    out.push(displayToLab(Math.round(v[0] * 255), Math.round(v[1] * 255), Math.round(v[2] * 255)));
  }
  return out;
}

const meanDeltaE = (a: Lab[], b: Lab[]) => a.reduce((s, p, i) => s + deltaE2000(p, b[i]), 0) / a.length;

const recipeFor = (profile: SourceProfile): ClipColorRecipe => ({ profile, output: "sdr", size: 0 });

describe("matchGrade", () => {
  test("a frame matched to itself is neutral", async () => {
    const render = recipeStatsRender(testFrame(), recipeFor("rec709"));
    expect(await matchGrade(render, render(undefined)!)).toBeUndefined();
  });

  test("a long fit hands the thread back while it runs", async () => {
    const base = recipeStatsRender(testFrame(), recipeFor("rec709"));
    // Every try costs a few milliseconds, as a log clip's does in the tab.
    const slow: StatsRender = (g) => {
      for (let i = 0; i < 8; i++) base(g);
      return base(g);
    };
    const order: string[] = [];
    setTimeout(() => order.push("tick"), 0);
    await matchGrade(slow, base({ exposure: 30 })!).then(() => order.push("fit"));
    expect(order).toEqual(["tick", "fit"]);
  });

  // The eval: a reference made by grading the clip's own frame with a known
  // grade, so a perfect match exists. The fitted grade has to land the frame
  // on that reference pixel for pixel — mean CIEDE2000 under 1, below what
  // an observer sees across a cut — on Rec.709 and on Apple Log graded in
  // scene light.
  const TARGETS: ColorGrade[] = [
    { exposure: 12, temperature: 20 },
    { contrast: 25, temperature: -18, saturation: 10 },
    { exposure: -10, tint: 12, saturation: -25 },
    { highlights: -20, shadows: 15, temperature: 10 },
  ];
  for (const profile of ["rec709", "apple-log-2"] as SourceProfile[]) {
    for (const target of TARGETS) {
      test(`${profile}: recovers ${JSON.stringify(target)}`, async () => {
        const px = testFrame();
        const recipe = recipeFor(profile);
        const render = recipeStatsRender(px, recipe);
        const grade = await matchGrade(render, render(target)!);
        expect(grade).toBeDefined();
        expect(meanDeltaE(rendered(px, recipe, grade), rendered(px, recipe, target))).toBeLessThan(1);
      });
    }
  }

  test("strength scales every fitted slider", async () => {
    const render = recipeStatsRender(testFrame(), recipeFor("rec709"));
    const reference = render({ exposure: 16, temperature: 24 })!;
    const full = (await matchGrade(render, reference))!;
    const half = (await matchGrade(render, reference, 0.5))!;
    for (const [k, v] of Object.entries(full)) {
      expect(Math.abs((half as Record<string, number>)[k] ?? 0) - Math.abs((v as number) / 2)).toBeLessThanOrEqual(0.5);
    }
    expect(await matchGrade(render, reference, 0)).toBeUndefined();
  });

  test("stats read lightness and each band's cast in CIELAB", () => {
    const grey = colorStatsFromImageData(frame([119, 119, 119]))!;
    // BT.1886 code 119 is 16% luminance: L* 47.
    expect(Math.abs(grey.lightness[3] - 47)).toBeLessThan(1);
    const mid = grey.tones[1];
    expect(mid.share).toBe(1);
    expect(Math.abs(mid.a) + Math.abs(mid.b)).toBeLessThan(0.5);
    const warm = colorStatsFromImageData(frame([160, 120, 90], [40, 60, 90]))!;
    expect(warm.tones[1].b).toBeGreaterThan(10);
    expect(warm.tones[0].b).toBeLessThan(-10);
  });

  test("stats expose warmth and saturation for the assistant", () => {
    const stats = colorStatsFromImageData(testFrame())!;
    expect(stats.meanSat).toBeGreaterThan(0);
    expect(stats.warmth).toBeGreaterThan(0);
    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;
}

const autoGrade709 = (px: Uint8ClampedArray) => autoGrade(px, recipeFor("rec709"));

/** A two-node cube that halves every channel: a LUT that darkens. */
function halvingLut(): ParsedLut {
  const data = new Float32Array(8 * 3);
  for (let i = 0; i < 8; i++) {
    data[i * 3] = (i & 1) * 0.5;
    data[i * 3 + 1] = ((i >> 1) & 1) * 0.5;
    data[i * 3 + 2] = ((i >> 2) & 1) * 0.5;
  }
  return { cube: { size: 2, data, min: [0, 0, 0], max: [1, 1, 1] } };
}

describe("autoGrade", () => {
  test("the fit sees the picture through the clip's LUT and preset", () => {
    const px = frame([125, 125, 125]);
    const recipe: ClipColorRecipe = { ...recipeFor("rec709"), grade: { lut: { id: "dark" } } };
    const bare = autoGrade709(px)?.exposure ?? 0;
    const through = autoGrade(px, recipe, halvingLut())?.exposure ?? 0;
    expect(through).toBeGreaterThan(bare + 10);
  });

  test("a mid-gray frame needs nearly nothing", () => {
    const g = autoGrade709(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 = autoGrade709(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 = autoGrade709(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 = autoGrade709(frame([90, 120, 170]));
    expect((cool?.temperature ?? 0) > 0).toBe(true);
    const warm = autoGrade709(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 = autoGrade709(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(autoGrade709(new Uint8ClampedArray(0))).toBeUndefined();
  });

  test("on Apple Log the exposure lands the rendered frame on its target in true stops", () => {
    // A flat log frame two stops under: grey card codes from a scene at 4.5%.
    const recipe = recipeFor("apple-log-2");
    const code = Math.round(appleLogEncode(0.045) * 255);
    const px = frame([code, code, code], [code + 30, code + 30, code + 30]);
    const g = autoGrade(px, recipe)!;
    const before = Math.log2(renderedLogAverage(px, recipe));
    const after = Math.log2(renderedLogAverage(px, recipe, { exposure: g.exposure }));
    const want = before + 0.8 * (Math.log2(0.18) - before);
    expect(Math.abs(after - want)).toBeLessThan(0.1);
  });
});

/** Geometric mean display luminance of a frame rendered through a recipe. */
function renderedLogAverage(px: Uint8ClampedArray, recipe: ClipColorRecipe, grade?: ColorGrade): number {
  const fn = createClipTransform({ ...recipe, grade });
  let sum = 0;
  let n = 0;
  for (let i = 0; i < px.length; i += 4) {
    const v = fn ? fn(px[i] / 255, px[i + 1] / 255, px[i + 2] / 255) : [px[i] / 255, px[i + 1] / 255, px[i + 2] / 255];
    const luma = 0.2126 * Math.round(v[0] * 255) + 0.7152 * Math.round(v[1] * 255) + 0.0722 * Math.round(v[2] * 255);
    sum += Math.log(Math.max(1e-4, bt1886Decode(luma / 255)));
    n++;
  }
  return Math.exp(sum / n);
}