@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/motionPathStage.ts

@@ -0,0 +1,279 @@
+// THE MOTION PATH ON SCREEN (gap 3): a `MotionPath` (parent-local design px)
+// projected through the layer's live parent `matrixWorld` and one pane camera.
+//
+// It does NOT use `toScreen`, which divides by w and so mirrors a point behind
+// the camera onto the screen. A path is a long line that can pass behind the
+// eye in the working pane, so every segment is clipped against the near plane
+// in VIEW space first, and a run that crosses it splits in two.
+import { Matrix4, Vector3 } from "three";
+import type { Camera } from "three";
+import type { Vec3 } from "@dailies-studio/engine";
+import type { MotionPath } from "@dailies-studio/shot/doc";
+
+/** A key dot on screen. A key behind the camera is left out. */
+export interface ScreenPathKey {
+  id: string;
+  frame: number;
+  x: number;
+  y: number;
+  /** The key sits under the playhead: drawn filled. */
+  current: boolean;
+  /** A bezier path's handle tips (schema v40), pane-local CSS px. Absent off
+   *  the bezier arm, on the side no segment uses, or behind the camera. */
+  in?: { x: number; y: number };
+  out?: { x: number; y: number };
+}
+
+export interface ScreenMotionPath {
+  layerId: string;
+  /** The playhead is outside the layer's lifetime: the path draws dimmed. */
+  dim: boolean;
+  /** Flat `[x0, y0, x1, y1, ...]` polylines, pane-local CSS px. A `jump` run
+   *  is a hold's step and draws dashed. */
+  runs: { jump: boolean; pts: number[] }[];
+  keys: ScreenPathKey[];
+  /** The current-frame tick: where the layer is, and the unit normal the
+   *  tick is drawn along. Null off the path's frames or behind the camera. */
+  tick: { x: number; y: number; nx: number; ny: number } | null;
+}
+
+export interface MotionPathSample {
+  /** Where the layer is at the playhead, parent-local design px. */
+  now: Vec3;
+  /** Half a frame either side, for the tick's direction. */
+  before: Vec3;
+  after: Vec3;
+}
+
+/** A key counts as under the playhead within this many frames. */
+const CURRENT_EPS = 1e-3;
+/** How far in front of the near plane a clipped end is placed, in view units. */
+const NEAR_PAD = 1e-4;
+
+const _view = new Matrix4();
+const _a = new Vector3();
+const _b = new Vector3();
+const _c = new Vector3();
+const _d = new Vector3();
+
+function cameraNear(cam: Camera): number {
+  const near = (cam as { near?: number }).near;
+  return typeof near === "number" && Number.isFinite(near) ? near : 0.1;
+}
+
+/** Design (+y down, +z away) parent-local into view space. */
+function toView(p: Vec3, view: Matrix4, out: Vector3): Vector3 {
+  return out.set(p[0], -p[1], -p[2]).applyMatrix4(view);
+}
+
+/** View space to pane-local CSS px. Only for points in front of the near plane. */
+function viewToScreen(v: Vector3, cam: Camera, width: number, height: number): [number, number] {
+  _c.copy(v).applyMatrix4(cam.projectionMatrix);
+  return [((_c.x + 1) / 2) * width, ((1 - _c.y) / 2) * height];
+}
+
+/** The matrix taking parent-local three coordinates into the camera's view. */
+function viewOf(parentWorld: Matrix4, cam: Camera): Matrix4 {
+  return _view.multiplyMatrices(cam.matrixWorldInverse, parentWorld);
+}
+
+/**
+ * Projects one path into one pane. `sample` is null when the playhead is
+ * outside the path's frames (no tick, no current key is possible then).
+ */
+export function projectMotionPath(
+  layerId: string,
+  path: MotionPath,
+  frame: number,
+  dim: boolean,
+  sample: MotionPathSample | null,
+  parentWorld: Matrix4,
+  cam: Camera,
+  width: number,
+  height: number,
+): ScreenMotionPath {
+  const view = viewOf(parentWorld, cam);
+  const limit = -cameraNear(cam) - NEAR_PAD;
+  const runs: ScreenMotionPath["runs"] = [];
+  for (const run of path.runs) {
+    let pts: number[] = [];
+    const flush = (): void => {
+      if (pts.length >= 4) runs.push({ jump: run.jump, pts });
+      pts = [];
+    };
+    for (let i = 0; i + 1 < run.points.length; i++) {
+      const a = toView(run.points[i]!, view, _a);
+      const b = toView(run.points[i + 1]!, view, _b);
+      const aIn = a.z <= limit;
+      const bIn = b.z <= limit;
+      if (!aIn && !bIn) {
+        flush();
+        continue;
+      }
+      // Clip the end that is behind the near plane onto it.
+      if (!aIn) a.lerp(b, (limit - a.z) / (b.z - a.z));
+      else if (!bIn) b.lerpVectors(a, b, (limit - a.z) / (b.z - a.z));
+      const sa = viewToScreen(a, cam, width, height);
+      if (pts.length === 0 || !aIn) {
+        if (!aIn) flush();
+        pts.push(sa[0], sa[1]);
+      }
+      const sb = viewToScreen(b, cam, width, height);
+      pts.push(sb[0], sb[1]);
+      if (!bIn) flush();
+    }
+    flush();
+  }
+
+  const keys: ScreenPathKey[] = [];
+  const tip = (p: Vec3, h: Vec3 | undefined): { x: number; y: number } | undefined => {
+    if (h === undefined) return undefined;
+    const v = toView([p[0] + h[0], p[1] + h[1], p[2] + h[2]], view, _b);
+    if (v.z > limit) return undefined;
+    const [x, y] = viewToScreen(v, cam, width, height);
+    return { x, y };
+  };
+  for (const key of path.keys) {
+    const v = toView(key.point, view, _a);
+    if (v.z > limit) continue;
+    const [x, y] = viewToScreen(v, cam, width, height);
+    const dot: ScreenPathKey = { id: key.id, frame: key.frame, x, y, current: Math.abs(key.frame - frame) < CURRENT_EPS };
+    const hIn = tip(key.point, key.spatialIn);
+    const hOut = tip(key.point, key.spatialOut);
+    if (hIn !== undefined) dot.in = hIn;
+    if (hOut !== undefined) dot.out = hOut;
+    keys.push(dot);
+  }
+
+  let tick: ScreenMotionPath["tick"] = null;
+  if (sample !== null && path.runs.length > 0) {
+    const v = toView(sample.now, view, _a);
+    if (v.z <= limit) {
+      const [x, y] = viewToScreen(v, cam, width, height);
+      const pb = toView(sample.before, view, _b);
+      const pa = toView(sample.after, view, _d);
+      let tx = 0;
+      let ty = 0;
+      if (pb.z <= limit && pa.z <= limit) {
+        const sb = viewToScreen(pb, cam, width, height);
+        const sa = viewToScreen(pa, cam, width, height);
+        tx = sa[0] - sb[0];
+        ty = sa[1] - sb[1];
+      }
+      const len = Math.hypot(tx, ty);
+      // A layer at rest has no direction; the tick stands upright.
+      tick = len < 1e-6 ? { x, y, nx: 0, ny: 1 } : { x, y, nx: -ty / len, ny: tx / len };
+    }
+  }
+  return { layerId, dim, runs, keys, tick };
+}
+
+/** The key dot nearest `(x, y)` within `radius` CSS px, across every path. */
+export function motionPathKeyAt(
+  paths: readonly ScreenMotionPath[],
+  x: number,
+  y: number,
+  radius: number,
+): { layerId: string; keyId: string } | null {
+  let best: { layerId: string; keyId: string } | null = null;
+  let bestD = radius;
+  for (const path of paths) {
+    for (const key of path.keys) {
+      const d = Math.hypot(key.x - x, key.y - y);
+      // `<=` so the LATER path wins a tie: it draws on top.
+      if (d <= bestD) {
+        bestD = d;
+        best = { layerId: path.layerId, keyId: key.id };
+      }
+    }
+  }
+  return best;
+}
+
+/** How far a handle tip must stand from its dot, in CSS px, to be drawn and
+ *  grabbed. Nearer, the dot wins the press: a corner's zero handles sit on it. */
+export const PATH_HANDLE_MIN_PX = 6;
+
+/** The selected key's handle tip nearest `(x, y)` within `radius` CSS px.
+ *  Only the selected key shows handles, so only its handles answer. */
+export function motionPathHandleAt(
+  paths: readonly ScreenMotionPath[],
+  selected: { layerId: string; keyId: string } | null,
+  x: number,
+  y: number,
+  radius: number,
+): { layerId: string; keyId: string; part: "in" | "out" } | null {
+  if (selected === null) return null;
+  const key = paths.find((p) => p.layerId === selected.layerId)?.keys.find((k) => k.id === selected.keyId);
+  if (key === undefined) return null;
+  let best: "in" | "out" | null = null;
+  let bestD = radius;
+  for (const part of ["in", "out"] as const) {
+    const h = key[part];
+    if (h === undefined || Math.hypot(h.x - key.x, h.y - key.y) < PATH_HANDLE_MIN_PX) continue;
+    const d = Math.hypot(h.x - x, h.y - y);
+    if (d <= bestD) {
+      bestD = d;
+      best = part;
+    }
+  }
+  return best === null ? null : { layerId: selected.layerId, keyId: selected.keyId, part: best };
+}
+
+/** Did any corner, key or tick move by more than half a CSS px, or appear? */
+export function motionPathsMoved(
+  before: readonly ScreenMotionPath[],
+  after: readonly ScreenMotionPath[],
+): boolean {
+  if (before.length !== after.length) return true;
+  const far = (a: number, b: number | undefined): boolean => b === undefined || Math.abs(a - b) > 0.5;
+  return after.some((next, i) => {
+    const prev = before[i]!;
+    if (prev.layerId !== next.layerId || prev.dim !== next.dim) return true;
+    if (prev.runs.length !== next.runs.length || prev.keys.length !== next.keys.length) return true;
+    for (let r = 0; r < next.runs.length; r++) {
+      const a = prev.runs[r]!;
+      const b = next.runs[r]!;
+      if (a.jump !== b.jump || a.pts.length !== b.pts.length) return true;
+      if (b.pts.some((v, k) => far(v, a.pts[k]))) return true;
+    }
+    for (let k = 0; k < next.keys.length; k++) {
+      const a = prev.keys[k]!;
+      const b = next.keys[k]!;
+      if (a.id !== b.id || a.current !== b.current || far(b.x, a.x) || far(b.y, a.y)) return true;
+      for (const part of ["in", "out"] as const) {
+        const ha = a[part];
+        const hb = b[part];
+        if (ha === undefined || hb === undefined ? ha !== hb : far(hb.x, ha.x) || far(hb.y, ha.y)) return true;
+      }
+    }
+    if (prev.tick === null || next.tick === null) return prev.tick !== next.tick;
+    return (
+      far(next.tick.x, prev.tick.x) ||
+      far(next.tick.y, prev.tick.y) ||
+      Math.abs(next.tick.nx - prev.tick.nx) > 0.02 ||
+      Math.abs(next.tick.ny - prev.tick.ny) > 0.02
+    );
+  });
+}
+
+/** The target nearest `value` within `radius`, else `value` unchanged: ctrl's
+ *  snap of a dragged key onto a neighbour's axis or the frame's centre line. */
+export function snapToNearest(value: number, targets: readonly number[], radius: number): number {
+  let best = value;
+  let bestD = radius;
+  for (const t of targets) {
+    const d = Math.abs(t - value);
+    if (d <= bestD) {
+      bestD = d;
+      best = t;
+    }
+  }
+  return best;
+}
+
+/** Which component of a delta is largest: shift's axis lock keeps only it. */
+export function dominantAxis(d: Vec3): 0 | 1 | 2 {
+  const [x, y, z] = d.map(Math.abs) as [number, number, number];
+  return x >= y && x >= z ? 0 : y >= z ? 1 : 2;
+}

package/src/stage/motionPreview.ts

@@ -0,0 +1,74 @@
+// THE MOTION PREVIEW (bridge v53): the Motion section's active preset drawn on
+// some layers, without a document write.
+//
+// `motionPreviewDoc` derives the document the RUNTIME draws, and only the
+// runtime, exactly as `fontPreviewDoc` does: picking, the overlays, health,
+// coverage and every export keep the real one. It runs the very
+// `stampMotionPreset` an apply runs, on the stage's own copy, so what a hover
+// shows is what a pick writes. A preset that refuses on every layer derives
+// nothing, and the runtime draws the document.
+import { motionPreset, stampMotionPreset } from "@dailies-studio/shot/doc";
+import type { Doc3D, MotionPresetRequest } from "@dailies-studio/shot/doc";
+import type { Ease } from "@dailies-studio/engine";
+import type { ShotMotionPreview } from "../bridgeTypes.js";
+
+/** The most layers one preview stamps: a selection a person could make. */
+export const MAX_MOTION_PREVIEW_LAYERS = 256;
+
+/** The preview as the chrome sent it, checked field by field; null for one
+ *  that names no known preset or no layer. */
+export function sanitizeMotionPreview(raw: ShotMotionPreview | null): ShotMotionPreview | null {
+  if (raw === null || typeof raw !== "object") return null;
+  const { containerId, layerIds, request, contracts } = raw;
+  if (typeof containerId !== "string" || containerId.length === 0 || !Array.isArray(layerIds)) return null;
+  const ids = [...new Set((layerIds as unknown[]).filter((id): id is string => typeof id === "string" && id.length > 0))];
+  if (ids.length === 0 || request === null || typeof request !== "object") return null;
+  if (typeof request.preset !== "string" || motionPreset(request.preset) === null) return null;
+  const frames = (n: unknown, min: number): n is number => typeof n === "number" && Number.isInteger(n) && n >= min;
+  const ease = easeOf(request.ease);
+  const clean: MotionPresetRequest = {
+    preset: request.preset,
+    ...(frames(request.lengthFrames, 1) ? { lengthFrames: request.lengthFrames } : {}),
+    ...(frames(request.at, 0) ? { at: request.at } : {}),
+    ...(ease === null ? {} : { ease }),
+  };
+  return {
+    containerId,
+    layerIds: ids.slice(0, MAX_MOTION_PREVIEW_LAYERS),
+    request: clean,
+    ...(contracts !== null && typeof contracts === "object" ? { contracts } : {}),
+  };
+}
+
+/** An ease the engine can evaluate, or null: the shapes `easeWrite` admits. */
+function easeOf(raw: unknown): Ease | null {
+  if (raw === null || typeof raw !== "object") return null;
+  const e = raw as Record<string, unknown>;
+  const finite = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n);
+  if (e["type"] === "hold") return { type: "hold" };
+  if (e["type"] === "bezier" && Array.isArray(e["handles"]) && e["handles"].length === 4 && e["handles"].every(finite)) {
+    const [x1, y1, x2, y2] = e["handles"] as number[];
+    return { type: "bezier", handles: [x1!, y1!, x2!, y2!] };
+  }
+  if (e["type"] === "spring" && finite(e["stiffness"]) && finite(e["damping"]) && finite(e["mass"]) && e["stiffness"] > 0 && e["mass"] > 0 && e["damping"] >= 0) {
+    return { type: "spring", stiffness: e["stiffness"], damping: e["damping"], mass: e["mass"] };
+  }
+  return null;
+}
+
+/** The last derivation, so a render that asks again for the same document and
+ *  preview does not stamp again (StageApp and the bridge both ask). */
+let last: { doc: Doc3D; preview: ShotMotionPreview; out: Doc3D } | null = null;
+
+/** The document the runtime draws while `preview` shows: `doc` itself when
+ *  there is none, or when the stamp lands nothing. */
+export function motionPreviewDoc(doc: Doc3D, preview: ShotMotionPreview | null): Doc3D {
+  if (preview === null) return doc;
+  if (last !== null && last.doc === doc && last.preview === preview) return last.out;
+  const contracts = preview.contracts;
+  const out = stampMotionPreset(doc, preview.containerId, preview.layerIds, preview.request, {
+    contractOf: (id) => contracts?.[id],
+  }).doc;
+  last = { doc, preview, out };
+  return out;
+}