Skip to content

Commit 20ef48a

Browse files
committed
feat(studio): add professional grading controls
1 parent 20f4bde commit 20ef48a

24 files changed

Lines changed: 3585 additions & 351 deletions

‎packages/studio/src/components/editor/PropertyPanelFlat.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,7 @@ export function PropertyPanelFlat({
427427
mediaMetadata={colorGradingController.mediaMetadata}
428428
presetPreviews={colorGradingController.presetPreviews}
429429
onRequestPresetPreviews={colorGradingController.requestPresetPreviews}
430+
captureGradedFrame={colorGradingController.captureGradedFrame}
430431
/>
431432
),
432433
});
Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
import { describe, expect, it } from "vitest";
2+
import {
3+
normalizeHfColorGrading,
4+
type HfColorGradingSecondary,
5+
} from "@hyperframes/core/color-grading";
6+
import {
7+
analyzeColorGradingFrame,
8+
buildColorGradingSecondaryMatte,
9+
colorGradingSecondaryMask,
10+
sampleColorGradingSecondary,
11+
} from "./colorGradingFrameAnalysis";
12+
13+
function pixels(...rgba: number[]): Uint8ClampedArray {
14+
return new Uint8ClampedArray(rgba);
15+
}
16+
17+
function secondaryKey(key: HfColorGradingSecondary["key"]) {
18+
const secondary = normalizeHfColorGrading({
19+
secondaries: [{ key, correction: {} }],
20+
})?.secondaries?.[0];
21+
if (!secondary) throw new Error("Expected a normalized secondary");
22+
return secondary.key;
23+
}
24+
25+
describe("colorGradingFrameAnalysis", () => {
26+
it("places black and white at the Rec.709 scope endpoints", () => {
27+
const result = analyzeColorGradingFrame(pixels(0, 0, 0, 255, 255, 255, 255, 255), 2, 1);
28+
29+
expect(result.histogram[0]).toBe(255);
30+
expect(result.histogram[255]).toBe(255);
31+
expect(result.waveform[255]).toBe(255);
32+
expect(result.waveform[256]).toBe(255);
33+
expect(result.parade.reduce((sum, value) => sum + value, 0)).toBe(6 * 255);
34+
});
35+
36+
it("alpha-weights all scopes and excludes transparent pixels", () => {
37+
const result = analyzeColorGradingFrame(pixels(0, 0, 0, 0, 255, 255, 255, 64), 2, 1);
38+
39+
expect(result.histogram.reduce((sum, value) => sum + value, 0)).toBe(64);
40+
expect(result.waveform.reduce((sum, value) => sum + value, 0)).toBe(64);
41+
expect(result.parade.reduce((sum, value) => sum + value, 0)).toBe(3 * 64);
42+
expect(result.vectorscope.reduce((sum, value) => sum + value, 0)).toBe(64);
43+
});
44+
45+
it("averages hue circularly when an eyedropper sample crosses red", () => {
46+
const sampled = sampleColorGradingSecondary(
47+
pixels(255, 0, 10, 255, 255, 10, 0, 255),
48+
2,
49+
1,
50+
0.5,
51+
0,
52+
1,
53+
);
54+
55+
expect(sampled).not.toBeNull();
56+
if (!sampled) throw new Error("Expected a sample");
57+
expect(Math.min(sampled.hue.center, 360 - sampled.hue.center)).toBeLessThan(3);
58+
expect(sampled.hue.range).toBe(18);
59+
});
60+
61+
it("does not invent a hue qualifier for a neutral sample", () => {
62+
const sampled = sampleColorGradingSecondary(pixels(128, 128, 128, 255), 1, 1, 0, 0);
63+
64+
expect(sampled?.hue).toEqual({ center: 0, range: 180, softness: 0 });
65+
expect(sampled?.saturation.max).toBeCloseTo(0.2);
66+
});
67+
68+
it("matches the shader's half-softness edge convention", () => {
69+
const key = secondaryKey({
70+
hue: { center: 0, range: 180, softness: 0 },
71+
saturation: { min: 0.5, max: 1, softness: 0.4 },
72+
luma: { min: 0, max: 1, softness: 0 },
73+
});
74+
75+
const belowOuterEdge = colorGradingSecondaryMask(77, 77, 77, key);
76+
const middleOfFeather = colorGradingSecondaryMask(112, 77, 77, key);
77+
expect(belowOuterEdge).toBe(0);
78+
expect(middleOfFeather).toBeGreaterThan(0);
79+
expect(middleOfFeather).toBeLessThan(1);
80+
});
81+
82+
it("builds an alpha-preserving black-and-white selection matte", () => {
83+
const key = secondaryKey({
84+
hue: { center: 0, range: 15, softness: 0 },
85+
saturation: { min: 0.5, max: 1, softness: 0 },
86+
luma: { min: 0, max: 1, softness: 0 },
87+
});
88+
const matte = buildColorGradingSecondaryMatte(
89+
pixels(255, 0, 0, 255, 0, 255, 0, 128, 0, 0, 0, 0),
90+
3,
91+
1,
92+
key,
93+
);
94+
95+
expect([...matte.slice(0, 4)]).toEqual([255, 255, 255, 255]);
96+
expect([...matte.slice(4, 8)]).toEqual([0, 0, 0, 128]);
97+
expect([...matte.slice(8, 12)]).toEqual([0, 0, 0, 0]);
98+
});
99+
});
Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
import type { NormalizedHfColorGradingSecondary } from "@hyperframes/core/color-grading";
2+
import { clampNumber } from "../../utils/studioHelpers";
3+
4+
const BYTE_MAX = 255;
5+
const SCOPE_SIZE = 256;
6+
7+
export type ColorGradingScopeMode = "histogram" | "waveform" | "parade" | "vectorscope";
8+
9+
export interface ColorGradingScopeAnalysis {
10+
width: number;
11+
histogram: Uint32Array;
12+
waveform: Uint32Array;
13+
parade: Uint32Array;
14+
vectorscope: Uint32Array;
15+
}
16+
17+
export async function readColorGradingFramePixels(frame: {
18+
dataUrl: string;
19+
width: number;
20+
height: number;
21+
}): Promise<Uint8ClampedArray | null> {
22+
const image = new Image();
23+
image.src = frame.dataUrl;
24+
await image.decode();
25+
const canvas = document.createElement("canvas");
26+
canvas.width = frame.width;
27+
canvas.height = frame.height;
28+
const context = canvas.getContext("2d", { willReadFrequently: true });
29+
if (!context) return null;
30+
context.drawImage(image, 0, 0, frame.width, frame.height);
31+
return context.getImageData(0, 0, frame.width, frame.height).data;
32+
}
33+
34+
function rec709Luma(red: number, green: number, blue: number): number {
35+
return red * 0.2126 + green * 0.7152 + blue * 0.0722;
36+
}
37+
38+
function rgbToHsv(red: number, green: number, blue: number) {
39+
const max = Math.max(red, green, blue);
40+
const min = Math.min(red, green, blue);
41+
const chroma = max - min;
42+
let hue = 0;
43+
if (chroma > 0) {
44+
if (max === red) hue = ((green - blue) / chroma) % 6;
45+
else if (max === green) hue = (blue - red) / chroma + 2;
46+
else hue = (red - green) / chroma + 4;
47+
hue = (hue * 60 + 360) % 360;
48+
}
49+
return {
50+
hue,
51+
saturation: max === 0 ? 0 : chroma / max,
52+
value: max,
53+
};
54+
}
55+
56+
function softRangeMask(value: number, min: number, max: number, softness: number): number {
57+
if (value < min) {
58+
if (softness <= 0 || value <= min - softness) return 0;
59+
const t = (value - (min - softness)) / softness;
60+
return t * t * (3 - 2 * t);
61+
}
62+
if (value > max) {
63+
if (softness <= 0 || value >= max + softness) return 0;
64+
const t = (value - max) / softness;
65+
return 1 - t * t * (3 - 2 * t);
66+
}
67+
return 1;
68+
}
69+
70+
export function colorGradingSecondaryMask(
71+
red: number,
72+
green: number,
73+
blue: number,
74+
key: NormalizedHfColorGradingSecondary["key"],
75+
): number {
76+
const hsv = rgbToHsv(red / BYTE_MAX, green / BYTE_MAX, blue / BYTE_MAX);
77+
const hueDistance = Math.abs(((((hsv.hue - key.hue.center + 540) % 360) + 360) % 360) - 180);
78+
const hueMask =
79+
key.hue.range >= 179.999
80+
? 1
81+
: hsv.saturation < 0.001
82+
? 0
83+
: softRangeMask(
84+
hueDistance,
85+
0,
86+
key.hue.range,
87+
Math.min(key.hue.softness, 180 - key.hue.range),
88+
);
89+
return (
90+
hueMask *
91+
softRangeMask(
92+
hsv.saturation,
93+
key.saturation.min,
94+
key.saturation.max,
95+
key.saturation.softness * 0.5,
96+
) *
97+
softRangeMask(
98+
rec709Luma(red / BYTE_MAX, green / BYTE_MAX, blue / BYTE_MAX),
99+
key.luma.min,
100+
key.luma.max,
101+
key.luma.softness * 0.5,
102+
)
103+
);
104+
}
105+
106+
export function buildColorGradingSecondaryMatte(
107+
pixels: Uint8ClampedArray,
108+
width: number,
109+
height: number,
110+
key: NormalizedHfColorGradingSecondary["key"],
111+
): Uint8ClampedArray {
112+
const matte = new Uint8ClampedArray(width * height * 4);
113+
for (let offset = 0; offset < pixels.length; offset += 4) {
114+
const alpha = pixels[offset + 3] ?? 0;
115+
const mask =
116+
alpha === 0
117+
? 0
118+
: colorGradingSecondaryMask(
119+
pixels[offset] ?? 0,
120+
pixels[offset + 1] ?? 0,
121+
pixels[offset + 2] ?? 0,
122+
key,
123+
);
124+
const value = Math.round(mask * BYTE_MAX);
125+
matte[offset] = value;
126+
matte[offset + 1] = value;
127+
matte[offset + 2] = value;
128+
matte[offset + 3] = alpha;
129+
}
130+
return matte;
131+
}
132+
133+
function pixelOffset(width: number, x: number, y: number): number {
134+
return (y * width + x) * 4;
135+
}
136+
137+
function byteIndex(value: number): number {
138+
return Math.round(clampNumber(value, 0, 1) * BYTE_MAX);
139+
}
140+
141+
export function analyzeColorGradingFrame(
142+
pixels: Uint8ClampedArray,
143+
width: number,
144+
height: number,
145+
): ColorGradingScopeAnalysis {
146+
const histogram = new Uint32Array(SCOPE_SIZE);
147+
const waveform = new Uint32Array(width * SCOPE_SIZE);
148+
const parade = new Uint32Array(width * SCOPE_SIZE * 3);
149+
const vectorscope = new Uint32Array(SCOPE_SIZE * SCOPE_SIZE);
150+
151+
for (let y = 0; y < height; y += 1) {
152+
for (let x = 0; x < width; x += 1) {
153+
const offset = pixelOffset(width, x, y);
154+
const alpha = pixels[offset + 3] ?? 0;
155+
if (alpha === 0) continue;
156+
const red = (pixels[offset] ?? 0) / BYTE_MAX;
157+
const green = (pixels[offset + 1] ?? 0) / BYTE_MAX;
158+
const blue = (pixels[offset + 2] ?? 0) / BYTE_MAX;
159+
const normalizedLuma = rec709Luma(red, green, blue);
160+
const luma = byteIndex(normalizedLuma);
161+
histogram[luma] += alpha;
162+
waveform[x * SCOPE_SIZE + (BYTE_MAX - luma)] += alpha;
163+
parade[x * SCOPE_SIZE + (BYTE_MAX - byteIndex(red))] += alpha;
164+
parade[width * SCOPE_SIZE + x * SCOPE_SIZE + (BYTE_MAX - byteIndex(green))] += alpha;
165+
parade[width * SCOPE_SIZE * 2 + x * SCOPE_SIZE + (BYTE_MAX - byteIndex(blue))] += alpha;
166+
167+
const chromaBlue = (blue - normalizedLuma) / 1.8556;
168+
const chromaRed = (red - normalizedLuma) / 1.5748;
169+
const vectorX = byteIndex(chromaBlue + 0.5);
170+
const vectorY = BYTE_MAX - byteIndex(chromaRed + 0.5);
171+
vectorscope[vectorY * SCOPE_SIZE + vectorX] += alpha;
172+
}
173+
}
174+
175+
return { width, histogram, waveform, parade, vectorscope };
176+
}
177+
178+
export function sampleColorGradingSecondary(
179+
pixels: Uint8ClampedArray,
180+
width: number,
181+
height: number,
182+
x: number,
183+
y: number,
184+
radius = 2,
185+
): NormalizedHfColorGradingSecondary["key"] | null {
186+
const minX = clampNumber(Math.floor(x) - radius, 0, width - 1);
187+
const maxX = clampNumber(Math.floor(x) + radius, 0, width - 1);
188+
const minY = clampNumber(Math.floor(y) - radius, 0, height - 1);
189+
const maxY = clampNumber(Math.floor(y) + radius, 0, height - 1);
190+
let hueX = 0;
191+
let hueY = 0;
192+
let saturation = 0;
193+
let luma = 0;
194+
let weight = 0;
195+
196+
for (let sampleY = minY; sampleY <= maxY; sampleY += 1) {
197+
for (let sampleX = minX; sampleX <= maxX; sampleX += 1) {
198+
const offset = pixelOffset(width, sampleX, sampleY);
199+
const alpha = (pixels[offset + 3] ?? 0) / BYTE_MAX;
200+
if (alpha === 0) continue;
201+
const red = (pixels[offset] ?? 0) / BYTE_MAX;
202+
const green = (pixels[offset + 1] ?? 0) / BYTE_MAX;
203+
const blue = (pixels[offset + 2] ?? 0) / BYTE_MAX;
204+
const hsv = rgbToHsv(red, green, blue);
205+
const hueRadians = (hsv.hue * Math.PI) / 180;
206+
const hueWeight = hsv.saturation * alpha;
207+
hueX += Math.cos(hueRadians) * hueWeight;
208+
hueY += Math.sin(hueRadians) * hueWeight;
209+
saturation += hsv.saturation * alpha;
210+
luma += rec709Luma(red, green, blue) * alpha;
211+
weight += alpha;
212+
}
213+
}
214+
215+
if (weight === 0) return null;
216+
const averageHue = ((Math.atan2(hueY, hueX) * 180) / Math.PI + 360) % 360;
217+
const averageSaturation = saturation / weight;
218+
const averageLuma = luma / weight;
219+
const neutralSample = averageSaturation < 0.02;
220+
return {
221+
hue: neutralSample
222+
? { center: 0, range: 180, softness: 0 }
223+
: { center: averageHue, range: 18, softness: 12 },
224+
saturation: {
225+
min: clampNumber(averageSaturation - 0.2, 0, 1),
226+
max: clampNumber(averageSaturation + 0.2, 0, 1),
227+
softness: 0.1,
228+
},
229+
luma: {
230+
min: clampNumber(averageLuma - 0.2, 0, 1),
231+
max: clampNumber(averageLuma + 0.2, 0, 1),
232+
softness: 0.1,
233+
},
234+
};
235+
}

0 commit comments

Comments
 (0)