Skip to content

Commit f78f8a6

Browse files
vanceingallsclaude
andcommitted
feat(core): capture motion blur pose, discovery and compositor
Add the three pure modules capture motion blur is built from: pose (an element's box as an affine in composition space, and the poses between two times), discover (find the elements that move fast enough for a smear to show) and composite (redraw each mover along its path into one frame). Nothing calls them yet; the runtime that wires them up lands in the next change. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent 234ebc4 commit f78f8a6

6 files changed

Lines changed: 831 additions & 0 deletions

File tree

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
2+
import { createCompositor, type MoverFrame } from "./composite";
3+
import { IDENTITY, translate } from "./pose";
4+
5+
function fakeContext() {
6+
return {
7+
drawImage: vi.fn(),
8+
clearRect: vi.fn(),
9+
setTransform: vi.fn(),
10+
globalAlpha: 1,
11+
globalCompositeOperation: "source-over",
12+
};
13+
}
14+
let offscreen: Array<ReturnType<typeof fakeContext>> = [];
15+
16+
beforeEach(() => {
17+
offscreen = [];
18+
vi.stubGlobal(
19+
"OffscreenCanvas",
20+
class {
21+
constructor(
22+
public width: number,
23+
public height: number,
24+
) {}
25+
getContext() {
26+
const ctx = fakeContext();
27+
offscreen.push(ctx);
28+
return ctx;
29+
}
30+
},
31+
);
32+
});
33+
afterEach(() => vi.unstubAllGlobals());
34+
35+
const capture = {} as CanvasImageSource;
36+
const background = {} as CanvasImageSource;
37+
const slide = (from: number, to: number, n = 16) =>
38+
Array.from({ length: n }, (_, k) => translate(IDENTITY, from + ((to - from) * (k + 0.5)) / n, 0));
39+
const mover = (w: number, h: number, taps: ReturnType<typeof slide>): MoverFrame => ({
40+
w,
41+
h,
42+
now: translate(IDENTITY, 50, 0),
43+
taps,
44+
});
45+
46+
describe("createCompositor", () => {
47+
it("keeps no crop for a mover that does not travel a pixel, and draws only the background", () => {
48+
const c = createCompositor(100, 100);
49+
const movers = [mover(10, 10, slide(0, 0.5))];
50+
const kept = c.crop(capture, movers);
51+
expect(kept).toEqual([false]);
52+
const out = fakeContext();
53+
expect(c.draw(background, out as never, movers, kept)).toEqual({ blurred: 0, taps: 0 });
54+
expect(out.drawImage).toHaveBeenCalledTimes(1);
55+
expect(out.drawImage.mock.calls[0]?.[0]).toBe(background);
56+
});
57+
58+
it("crops a moving mover once and lays one tap per draw over the background", () => {
59+
const c = createCompositor(1000, 100);
60+
const movers = [mover(10, 10, slide(0, 100))];
61+
const kept = c.crop(capture, movers);
62+
expect(kept).toEqual([true]);
63+
const crop = offscreen.at(-1);
64+
expect(crop?.drawImage).toHaveBeenCalledWith(capture, 0, 0);
65+
const out = fakeContext();
66+
const stats = c.draw(background, out as never, movers, kept);
67+
const accum = offscreen[0];
68+
expect(stats.blurred).toBe(1);
69+
expect(accum?.drawImage).toHaveBeenCalledTimes(stats.taps);
70+
expect(accum?.globalAlpha).toBeCloseTo(1 / stats.taps, 9);
71+
// Background first, then the trail over it.
72+
expect(out.drawImage.mock.calls[0]).toEqual([background, 0, 0]);
73+
expect(out.drawImage).toHaveBeenCalledTimes(2);
74+
});
75+
76+
it("leaves a mover sharp when its box is too big to copy every frame", () => {
77+
const c = createCompositor(100, 100);
78+
expect(c.crop(capture, [mover(1000, 1000, slide(0, 100))])).toEqual([false]);
79+
});
80+
});
Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
/**
2+
* The per-frame draw: a background, then each mover's own pixels redrawn along its path.
3+
*
4+
* Each mover is cropped from a capture of the scene and drawn at every tap pose into a float
5+
* buffer, additive at weight 1/n: the shutter integral. Its coverage fades at the path ends, so
6+
* the trail needs a background without the mover (a second capture, movers hidden); falling back
7+
* to the sharp frame leaves thin lines looking unblurred.
8+
*
9+
* Image-space approximation: a mover's box contents move with it; ink outside it is not redrawn.
10+
*/
11+
12+
import { type Affine, invert, sweep, thinTaps } from "./pose";
13+
14+
export interface MoverFrame {
15+
w: number;
16+
h: number;
17+
/** The pose the capture shows (frame time). */
18+
now: Affine;
19+
/** Poses across the shutter. */
20+
taps: Affine[];
21+
}
22+
23+
interface CompositeStats {
24+
blurred: number;
25+
taps: number;
26+
}
27+
28+
type Context2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
29+
interface Layer {
30+
canvas: OffscreenCanvas;
31+
ctx: OffscreenCanvasRenderingContext2D;
32+
}
33+
34+
// Float16 keeps n additive 1/n-weighted taps exact; 8-bit loses up to ~n/2 levels per channel.
35+
function makeLayer(w: number, h: number): Layer {
36+
const canvas = new OffscreenCanvas(w, h);
37+
let ctx: OffscreenCanvasRenderingContext2D | null = null;
38+
try {
39+
ctx = canvas.getContext("2d", { colorType: "float16" } as CanvasRenderingContext2DSettings);
40+
} catch {
41+
ctx = null;
42+
}
43+
ctx = ctx ?? canvas.getContext("2d");
44+
if (!ctx) throw new Error("capture motion blur: no 2D context for the accumulation buffer");
45+
return { canvas, ctx };
46+
}
47+
48+
/** Whether a mover travels far enough within this shutter to draw a trail at all. */
49+
function moves(mover: MoverFrame, frameW: number, frameH: number): boolean {
50+
const { travel, rect } = sweep(mover.taps, mover.w, mover.h, frameW, frameH);
51+
return rect !== null && travel >= 1;
52+
}
53+
54+
export function createCompositor(width: number, height: number) {
55+
const accum = makeLayer(width, height);
56+
const crops: Layer[] = [];
57+
// A mover box this many times the frame is too big to copy every frame; it is left sharp.
58+
const maxCropArea = width * height * 4;
59+
60+
const cropLayer = (i: number, w: number, h: number): Layer => {
61+
let layer = crops[i];
62+
if (!layer || layer.canvas.width < w || layer.canvas.height < h) {
63+
layer = makeLayer(
64+
Math.max(w, layer?.canvas.width ?? 1),
65+
Math.max(h, layer?.canvas.height ?? 1),
66+
);
67+
crops[i] = layer;
68+
}
69+
return layer;
70+
};
71+
72+
/** Copy each mover's frame-time pixels out of `src`; false marks a mover to leave sharp. */
73+
function crop(src: CanvasImageSource, movers: MoverFrame[]): boolean[] {
74+
return movers.map((mover, i) => {
75+
const { w, h } = mover;
76+
const back = invert(mover.now);
77+
if (!back || w * h > maxCropArea || !moves(mover, width, height)) return false;
78+
const c = cropLayer(i, w, h).ctx;
79+
c.setTransform(1, 0, 0, 1, 0, 0);
80+
c.globalCompositeOperation = "source-over";
81+
c.globalAlpha = 1;
82+
c.clearRect(0, 0, w, h);
83+
c.setTransform(back.a, back.b, back.c, back.d, back.e, back.f);
84+
c.drawImage(src, 0, 0);
85+
return true;
86+
});
87+
}
88+
89+
function trail(out: Context2D, mover: MoverFrame, layer: Layer): number {
90+
const { w, h } = mover;
91+
const { travel, rect } = sweep(mover.taps, w, h, width, height);
92+
if (!rect) return 0;
93+
const taps = thinTaps(mover.taps, travel);
94+
const a = accum.ctx;
95+
a.setTransform(1, 0, 0, 1, 0, 0);
96+
a.globalCompositeOperation = "source-over";
97+
a.globalAlpha = 1;
98+
a.clearRect(rect.x, rect.y, rect.w, rect.h);
99+
a.globalCompositeOperation = "lighter";
100+
a.globalAlpha = 1 / taps.length;
101+
for (const m of taps) {
102+
a.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
103+
a.drawImage(layer.canvas, 0, 0, w, h, 0, 0, w, h);
104+
}
105+
out.drawImage(accum.canvas, rect.x, rect.y, rect.w, rect.h, rect.x, rect.y, rect.w, rect.h);
106+
return taps.length;
107+
}
108+
109+
/** `background` into `out`, then the trail of every mover `crop` kept. */
110+
function draw(
111+
background: CanvasImageSource,
112+
out: Context2D,
113+
movers: MoverFrame[],
114+
kept: boolean[],
115+
): CompositeStats {
116+
out.setTransform(1, 0, 0, 1, 0, 0);
117+
out.globalAlpha = 1;
118+
out.globalCompositeOperation = "copy";
119+
out.drawImage(background, 0, 0);
120+
out.globalCompositeOperation = "source-over";
121+
const stats: CompositeStats = { blurred: 0, taps: 0 };
122+
movers.forEach((mover, i) => {
123+
const layer = crops[i];
124+
if (!kept[i] || !layer) return;
125+
const n = trail(out, mover, layer);
126+
if (n > 0) {
127+
stats.blurred++;
128+
stats.taps += n;
129+
}
130+
});
131+
return stats;
132+
}
133+
134+
return { crop, draw };
135+
}
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
import { afterEach, describe, expect, it, vi } from "vitest";
2+
import { discoverMovers } from "./discover";
3+
4+
// jsdom lays nothing out: each element's rect follows the x its fake timeline writes.
5+
function element(parent: Element, id: string): HTMLElement {
6+
const el = document.createElement("div");
7+
el.id = id;
8+
parent.append(el);
9+
el.getBoundingClientRect = () => {
10+
const x = parseFloat(el.style.transform.replace("translateX(", "")) || 0;
11+
return { left: x, top: 0, right: x + 10, bottom: 10, width: 10, height: 10 } as DOMRect;
12+
};
13+
return el;
14+
}
15+
16+
function setup() {
17+
const scene = document.createElement("div");
18+
const fast = element(scene, "fast");
19+
const fastChild = element(fast, "fast-child");
20+
const slow = element(scene, "slow");
21+
const still = element(scene, "still");
22+
const off = element(scene, "off");
23+
off.setAttribute("data-motion-blur", "off");
24+
// 1 s at 30 fps: `fast` and `off` cross 300 px (10 px/frame), `slow` 15 px (0.5 px/frame).
25+
const seek = (t: number): void => {
26+
fast.style.transform = `translateX(${300 * t}px)`;
27+
fastChild.style.transform = `translateX(${200 * t}px)`;
28+
slow.style.transform = `translateX(${15 * t}px)`;
29+
off.style.transform = `translateX(${300 * t}px)`;
30+
};
31+
seek(0);
32+
return { scene, fast, fastChild, slow, still, off, seek };
33+
}
34+
35+
describe("discoverMovers", () => {
36+
afterEach(() => vi.restoreAllMocks());
37+
38+
it("keeps fast, outermost movers that are not opted out", () => {
39+
const { scene, fast, seek } = setup();
40+
const { movers } = discoverMovers({ scene, durationSeconds: 1, fps: 30, seek });
41+
expect(movers).toEqual([fast]);
42+
});
43+
44+
it("marks every changing element dynamic, slow and opted-out ones included", () => {
45+
const { scene, fast, fastChild, slow, still, off, seek } = setup();
46+
const { dynamic } = discoverMovers({ scene, durationSeconds: 1, fps: 30, seek });
47+
expect(
48+
dynamic.has(fast) && dynamic.has(fastChild) && dynamic.has(slow) && dynamic.has(off),
49+
).toBe(true);
50+
expect(dynamic.has(still)).toBe(false);
51+
});
52+
53+
it("drops a mover in a 3D context", () => {
54+
const { scene, fast, seek } = setup();
55+
const real = window.getComputedStyle;
56+
vi.spyOn(window, "getComputedStyle").mockImplementation((el: Element) => {
57+
if (el === fast)
58+
return {
59+
transform: "matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1)",
60+
transformStyle: "flat",
61+
perspective: "none",
62+
} as CSSStyleDeclaration;
63+
return real(el);
64+
});
65+
expect(discoverMovers({ scene, durationSeconds: 1, fps: 30, seek }).movers).toEqual([]);
66+
});
67+
});

0 commit comments

Comments
 (0)