Skip to content

Open source CapCut alternative.

TypeScript
7.7 KB
Raw Blame
/**
 * A camera over a world of elements, and the blur that comes with moving it.
 *
 * Explainer graphics are often a set of cards laid out like a board, with a
 * camera gliding over them: it steps from one card to the next, pushes onto
 * the one being talked about, pulls back. Moving every card's own keys to fake
 * that is a lot of bookkeeping, and the cards drift apart the moment one key
 * is off. So a group carries one camera pose track, and every element in the
 * group is drawn through it — the cards keep their own places and poses, and
 * the camera moves the whole board as one.
 *
 * A camera pose names the world point that sits at the frame's center (`x`,
 * `y`, fractions of the frame, like an element's position), how far the view
 * is zoomed in (`scale`, 2 shows the world twice as large), and how far the
 * world is turned clockwise about the frame's center (`rotation`, degrees).
 * The camera at rest — centered, unzoomed, level — changes nothing.
 *
 * Every member stores the same camera, with key times in seconds from its own
 * start like its pose keys, so the camera travels with the group when it is
 * moved on the timeline and every renderer reads it off the element alone.
 */

import type { EaseId } from "./ease";

/** A camera pose at `t` seconds into the element. `ease` is the curve out of
 * this key into the next. */
export interface CameraKey {
  t: number;
  x: number;
  y: number;
  scale: number;
  rotation: number;
  ease?: EaseId;
}

/** A group's camera, as each member carries it. `motionBlur` streaks what the
 * camera's movement does to the picture (shutter, SHUTTER_MIN..SHUTTER_MAX;
 * absent = off). */
export interface GroupCamera {
  kf: CameraKey[];
  motionBlur?: number;
}

export interface CameraPose {
  x: number;
  y: number;
  scale: number;
  rotation: number;
}

export const REST_CAMERA: CameraPose = { x: 0.5, y: 0.5, scale: 1, rotation: 0 };

/** The world a group's camera films, in frame fractions: the frame and one
 * frame beyond each edge. Its look-at point and its members sit inside it. */
export const CAMERA_WORLD_MIN = -1;
export const CAMERA_WORLD_MAX = 2;

/** How far the camera may pull back and push in. */
export const CAMERA_SCALE_MIN = 0.25;
export const CAMERA_SCALE_MAX = 8;

/** The softest an element may be, design px at the 1080 short side. */
export const ELEMENT_BLUR_MAX = 60;

/** Whether the camera has any keys to move by. */
export function hasCameraKeys(cam: GroupCamera | undefined): cam is GroupCamera {
  return !!cam && cam.kf.length > 0;
}

/**
 * Where a world point lands on screen under the camera. Positions are frame
 * fractions; the turn happens in a square space (x scaled by the aspect), so
 * the board turns rigidly on a frame of any shape.
 */
export function cameraPoint(
  cam: CameraPose,
  x: number,
  y: number,
  aspect: number
): { x: number; y: number } {
  const v = cameraVector(cam, (x - cam.x) * aspect, y - cam.y);
  return { x: 0.5 + v.x / aspect, y: 0.5 + v.y };
}

/** A world-space offset (any unit, same on both axes) as seen on screen: the
 * camera's zoom and turn, without its travel. */
export function cameraVector(cam: CameraPose, dx: number, dy: number): { x: number; y: number } {
  const r = (cam.rotation * Math.PI) / 180;
  const c = Math.cos(r) * cam.scale;
  const s = Math.sin(r) * cam.scale;
  return { x: c * dx - s * dy, y: s * dx + c * dy };
}

/** The world point that shows at a screen point: the inverse of
 * `cameraPoint`. A drag in the preview moves an element by this. */
export function worldPoint(
  cam: CameraPose,
  x: number,
  y: number,
  aspect: number
): { x: number; y: number } {
  const v = worldVector(cam, (x - 0.5) * aspect, y - 0.5);
  return { x: cam.x + v.x / aspect, y: cam.y + v.y };
}

/** A screen-space offset as a world-space one: `cameraVector` through the
 * inverse pose (the turn undone, the zoom inverted). */
function worldVector(cam: CameraPose, dx: number, dy: number): { x: number; y: number } {
  return cameraVector({ ...cam, rotation: -cam.rotation, scale: 1 / Math.max(1e-6, cam.scale) }, dx, dy);
}

/**
 * An element's frame state seen through the camera: its center moves to
 * where the camera shows it, the preset's travel turns and grows with the
 * world, and the camera's zoom and turn add to the element's own.
 */
export function composeCamera<
  S extends { x: number; y: number; dx: number; dy: number; scale: number; rotation: number },
>(state: S, cam: CameraPose, aspect: number): S {
  const p = cameraPoint(cam, state.x, state.y, aspect);
  const d = cameraVector(cam, state.dx, state.dy);
  return {
    ...state,
    x: p.x,
    y: p.y,
    dx: d.x,
    dy: d.y,
    scale: state.scale * cam.scale,
    rotation: state.rotation + cam.rotation,
  };
}

/** The camera with every key moved `by` seconds — what keeps a member on the
 * group's clock when its own start moves under it (a left trim, a split). */
export function shiftCamera(cam: GroupCamera, by: number): GroupCamera {
  return { ...cam, kf: cam.kf.map((k) => ({ ...k, t: Math.round((k.t + by) * 1000) / 1000 })) };
}

// --- Motion blur ---------------------------------------------------------
//
// A real shutter stays open for part of each frame, so anything that moves
// while it is open smears along its path. Here the exposure is a share of a
// 30fps frame — 0.5 is the classic half-open shutter — and the smear is the
// distance the element's center travels on screen while it is open. The
// exposure is measured in seconds, so a 24fps export, a 60fps export and the
// preview all draw the same streak for the same move. A still frame travels
// nowhere and stays sharp. A shutter past one frame is a stylized long
// exposure: the smear a whip cut wears while the shot settles.

/** The frame the shutter amount is a share of, seconds. */
export const MOTION_BLUR_FRAME = 1 / 30;
/** The shutter's range, in frames: a sliver of one up to a long exposure. */
export const SHUTTER_MIN = 0.05;
export const SHUTTER_MAX = 4;
/** A streak shorter than this, design px, draws nothing: the frame is sharp. */
export const STREAK_MIN = 0.75;
/** The longest streak a one-frame shutter draws, design px. A whip faster
 * than this reads as a blur either way, and the cap bounds what a frame
 * costs to draw. A longer shutter lengthens the cap in step (`streakCap`). */
export const STREAK_MAX = 96;
/** Design px between two taps along a streak. */
const STREAK_TAP_SPACING = 4;
/** The most copies one streak is drawn from. */
export const STREAK_TAPS_MAX = 24;

/** The longest streak `shutter` draws, design px: one frame's cap, or that
 * cap times the frames a long exposure stays open. */
export function streakCap(shutter = 1): number {
  return STREAK_MAX * Math.max(1, shutter);
}

/** The streak for a screen displacement over the exposure (design px): the
 * displacement itself, capped in length for the shutter, or null when it is
 * too short to see. */
export function capStreak(dx: number, dy: number, shutter = 1): { x: number; y: number } | null {
  const len = Math.hypot(dx, dy);
  if (!(len >= STREAK_MIN)) return null;
  const cap = streakCap(shutter);
  const k = len > cap ? cap / len : 1;
  return { x: dx * k, y: dy * k };
}

/** How many copies a streak of `len` design px is drawn from: enough that
 * neighbours sit a few pixels apart, never fewer than two. Counted in design
 * px so a preview and a 4K export split the same streak the same way. */
export function streakTaps(len: number): number {
  if (!(len >= STREAK_MIN)) return 0;
  return Math.max(2, Math.min(STREAK_TAPS_MAX, Math.ceil(len / STREAK_TAP_SPACING) + 1));
}

/** Design px of frame for an aspect (width / height), short side 1080. */
export function designFrame(aspect: number): { width: number; height: number } {
  return aspect >= 1 ? { width: 1080 * aspect, height: 1080 } : { width: 1080, height: 1080 / aspect };
}