Code-first video & image, rendered natively on WebGPU.
/**
* Cubic Bezier and Speed Curve Solver for Motion Graphics
* Provides analytical/Newton-Raphson solvers for unit easing curves and 2D spatial trajectory splines.
*/
import { solveCubicBezier } from "@framefields/compositions/program";
export interface Point2D {
x: number;
y: number;
}
export interface SpatialKeyframePoint {
frame: number;
x: number;
y: number;
spatialTangentIn?: Point2D;
spatialTangentOut?: Point2D;
}
export interface SplineSegment {
p0: Point2D;
c1: Point2D;
c2: Point2D;
p1: Point2D;
startFrame: number;
endFrame: number;
}
export { solveCubicBezier };
/**
* Calculates the instantaneous speed (derivative |dy/dt|) at parameter t in [0, 1].
*/
export function solveBezierDerivative(
x1: number,
y1: number,
x2: number,
y2: number,
t: number,
): number {
const clampedT = Math.max(0, Math.min(1, t));
const eps = 1e-4;
const t0 = Math.max(0, clampedT - eps);
const t1 = Math.min(1, clampedT + eps);
const dt = t1 - t0;
if (dt <= 0) return 0;
const y0 = solveCubicBezier(x1, y1, x2, y2, t0);
const y1Val = solveCubicBezier(x1, y1, x2, y2, t1);
return Math.abs((y1Val - y0) / dt);
}
/**
* Generates an array of samples along the cubic bezier curve for visualization.
*/
export function sampleBezierCurve(
x1: number,
y1: number,
x2: number,
y2: number,
steps = 60,
): Array<{ t: number; value: number; speed: number }> {
const samples: Array<{ t: number; value: number; speed: number }> = [];
for (let i = 0; i <= steps; i++) {
const t = i / steps;
const value = solveCubicBezier(x1, y1, x2, y2, t);
const speed = solveBezierDerivative(x1, y1, x2, y2, t);
samples.push({ t, value, speed });
}
return samples;
}
/**
* Converts Catmull-Rom four-point configuration to cubic Bezier control points.
*/
export function catmullRomToBezier(
p0: Point2D,
p1: Point2D,
p2: Point2D,
p3: Point2D,
): { c1: Point2D; c2: Point2D } {
return {
c1: {
x: p1.x + (p2.x - p0.x) / 6,
y: p1.y + (p2.y - p0.y) / 6,
},
c2: {
x: p2.x - (p3.x - p1.x) / 6,
y: p2.y - (p3.y - p1.y) / 6,
},
};
}
/**
* Builds smooth Bezier spline segments between an ordered array of spatial keyframes.
* Respects custom spatial tangents if authored; otherwise uses smooth Catmull-Rom.
*/
export function buildSpatialSplineSegments(
points: SpatialKeyframePoint[],
): SplineSegment[] {
if (points.length < 2) return [];
const segments: SplineSegment[] = [];
for (let i = 0; i < points.length - 1; i++) {
const curr = points[i];
const next = points[i + 1];
let c1: Point2D;
let c2: Point2D;
if (curr.spatialTangentOut) {
c1 = {
x: curr.x + curr.spatialTangentOut.x,
y: curr.y + curr.spatialTangentOut.y,
};
} else {
// Natural Catmull-Rom tangent
const prev = i > 0 ? points[i - 1] : curr;
const pNextNext = i + 2 < points.length ? points[i + 2] : next;
const cr = catmullRomToBezier(prev, curr, next, pNextNext);
c1 = cr.c1;
}
if (next.spatialTangentIn) {
c2 = {
x: next.x + next.spatialTangentIn.x,
y: next.y + next.spatialTangentIn.y,
};
} else {
const prev = i > 0 ? points[i - 1] : curr;
const pNextNext = i + 2 < points.length ? points[i + 2] : next;
const cr = catmullRomToBezier(prev, curr, next, pNextNext);
c2 = cr.c2;
}
segments.push({
p0: { x: curr.x, y: curr.y },
c1,
c2,
p1: { x: next.x, y: next.y },
startFrame: curr.frame,
endFrame: next.frame,
});
}
return segments;
}
/**
* Samples points along a cubic bezier segment between p0 and p1 with control points c1, c2.
*/
export function sampleCubicBezierSegment(
p0: Point2D,
c1: Point2D,
c2: Point2D,
p1: Point2D,
steps = 20,
): Point2D[] {
const pts: Point2D[] = [];
for (let i = 0; i <= steps; i++) {
const u = i / steps;
const oU = 1 - u;
const oU2 = oU * oU;
const oU3 = oU2 * oU;
const u2 = u * u;
const u3 = u2 * u;
const x = oU3 * p0.x + 3 * oU2 * u * c1.x + 3 * oU * u2 * c2.x + u3 * p1.x;
const y = oU3 * p0.y + 3 * oU2 * u * c1.y + 3 * oU * u2 * c2.y + u3 * p1.y;
pts.push({ x, y });
}
return pts;
}