@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/view.ts

@@ -144,16 +144,63 @@ export function designToScreen(
 /** Space left around the frame when fitting, as a fraction of the viewport. */
 export const FIT_MARGIN = 0.08;
 
-/** The view that shows the whole frame with a margin. Pure in the viewport and
- *  the frame, so the chrome's "fit" button and a window resize agree. */
-export function fitView(viewport: Viewport, frame: FrameSize): ShotView {
+/**
+ * The view that shows the whole frame with a margin. Pure in the viewport and
+ * the frame, so the chrome's "fit" button and a window resize agree.
+ *
+ * ── WHY IT CAN FIT A SUB-RECT ────────────────────────────────────────────
+ *
+ * The stage renders full-bleed and every chrome panel is docked over it, so the
+ * viewport is the whole window and fitting to it framed the shot behind the
+ * header and the timeline dock — the author pressed Fit and got a frame with
+ * its top and bottom covered. `within` is the part of that viewport the chrome
+ * is NOT covering, in the SAME coordinates as `viewport` (pane-local: the
+ * caller hands this a pane's size, so it hands `within` a pane-local rect).
+ * The render still fills the viewport; only what the frame is sized and
+ * centred against moves.
+ *
+ * Defaulting `within` to the whole viewport keeps `panX/panY` at 0 for every
+ * caller that does not pass one, so nothing that fits an unobstructed viewport
+ * changed.
+ */
+export function fitView(
+  viewport: Viewport,
+  frame: FrameSize,
+  within: { x: number; y: number; width: number; height: number } = {
+    x: 0,
+    y: 0,
+    width: viewport.width,
+    height: viewport.height,
+  },
+  /** Per side, as a fraction. A preview hole IS the frame, so it passes 0. */
+  margin: number = FIT_MARGIN,
+): ShotView {
   if (viewport.width <= 0 || viewport.height <= 0) return { zoom: 1, panX: 0, panY: 0 };
-  const usable = 1 - FIT_MARGIN * 2;
-  const zoom = Math.min(
-    (viewport.width * usable) / frame.width,
-    (viewport.height * usable) / frame.height,
-  );
-  return { zoom: clampZoom(zoom), panX: 0, panY: 0 };
+  const usable = 1 - margin * 2;
+  const zoom = Math.min((within.width * usable) / frame.width, (within.height * usable) / frame.height);
+  // `panX/panY` are the frame CENTRE's displacement from the VIEWPORT centre
+  // (see `ShotView`, and `frameRect` which derives the screen rect from it), so
+  // centring in `within` is the difference between the two centres — not
+  // `within`'s origin, which is the sign error this shape invites.
+  return {
+    zoom: clampZoom(zoom),
+    panX: finitePan(within.x + within.width / 2 - viewport.width / 2),
+    panY: finitePan(within.y + within.height / 2 - viewport.height / 2),
+  };
+}
+
+/**
+ * 0 for a pan that is not a number, for the same reason `clampZoom` answers 1.
+ *
+ * The pan used to be the constant 0, so `fitView` was TOTAL: no input could
+ * make it return a view the camera could not use. Two centres subtracted is
+ * not — a non-finite viewport or sub-rect (a first-frame measure, a mid-resize
+ * `Infinity`) makes it NaN, and a NaN pan is a `setViewOffset` of NaN, which is
+ * a projection matrix of NaN: the pane draws nothing at all, with no error
+ * anywhere. `paneRects` guards the same class of input for the same reason.
+ */
+function finitePan(n: number): number {
+  return Number.isFinite(n) ? n : 0;
 }
 
 /**

package/src/stage/workingView.ts

@@ -1,4 +1,4 @@
-// The working pane's free-orbit camera, as pure spherical arithmetic.
+// The working pane's free-orbit camera, as pure spherical arithmetic.
 //
 // ── COORDINATE CONVENTION, STATED ONCE ──────────────────────────────────
 //
@@ -32,7 +32,7 @@
 //
 // THREE-FREE: plain arrays and numbers, so the chrome can render a readout of
 // the view and these functions are testable in node.
-import { DEFAULT_FOV_DEG, planeDistance } from "@dailies-studio/shot/doc";
+import { DEFAULT_FOV_DEG, MAX_CAMERA_PITCH_DEG, planeDistance } from "@dailies-studio/shot/doc";
 import { FIT_MARGIN } from "./view.js";
 import type { FrameSize } from "./view.js";
 
@@ -87,6 +87,26 @@ export interface WorkingView {
   ortho?: boolean;
 }
 
+/**
+ * How far behind the orbit position the ORTHOGRAPHIC eye stands.
+ *
+ * An orthographic projection does not depend on where along the view axis the
+ * eye sits, so this is free to the picture — and `StageTools` needs it because
+ * `Raycaster.setFromCamera` starts an ortho ray AT the near plane, so anything
+ * behind that plane draws perfectly and answers no click. Standing the eye back
+ * puts the whole slab in front of a positive near plane.
+ *
+ * NAMED, rather than inlined at the one call site, because it is the reason
+ * `GridPlane` cannot measure its fade from `cameraPosition` in ortho: this is
+ * many times `gridFade`'s far end at every legal dolly, so measured from here
+ * the entire floor resolves to the backdrop colour and disappears. Two places
+ * reasoning about the same number by restating it is how that shipped;
+ * `gizmoMath.test.ts` now pins the relationship against this export.
+ */
+export function orthoEyePushBack(distance: number): number {
+  return Math.max(distance * 8, 10_000);
+}
+
 export const ORBIT_DEG_PER_PX = 0.3;
 
 /**
@@ -100,12 +120,32 @@ export const ORBIT_DEG_PER_PX = 0.3;
 export const ORBIT_STEP_DEG = 15;
 
 
-/** Off the poles, both ends. At phi 0 or 180 the eye is straight above or below
- *  the target, `lookAt`'s up vector is parallel to the view direction, and the
- *  camera's roll is undefined — which shows up as the view snapping to an
- *  arbitrary rotation exactly at the top of a drag. */
-export const MIN_PHI_DEG = 5;
-export const MAX_PHI_DEG = 175;
+/**
+ * The poles are REACHABLE, and Numpad7 really does look straight down.
+ *
+ * ── WHAT USED TO BREAK, AND WHERE ───────────────────────────────────────
+ *
+ * The clamp was [5, 175], so "top" and "bottom" landed five degrees short and
+ * an author could never get a true plan or elevation view — the one thing a
+ * numpad axis key is for. The reason given was that at phi 0 or 180 the
+ * camera's roll is undefined, and that is true of `lookAt` WITH A WORLD-UP
+ * VECTOR: up becomes parallel to the view direction, the cross product is zero,
+ * and the quaternion comes out NaN.
+ *
+ * But `viewBasis` never had that problem. Its closed form for up is
+ * `[-cosφ·sinθ, sinφ, -cosφ·cosθ]`, which at φ = 0 is `[-sinθ, 0, -cosθ]` — a
+ * unit vector, perpendicular to the view direction, and continuous through the
+ * pole. The turntable convention: at the pole the roll is decided by theta,
+ * which is exactly what an author spinning a top view expects.
+ *
+ * So the fix was never a bigger epsilon. `StageTools` sets `cam.up` from
+ * `viewBasis(view).up` instead of from world +y, and the clamp opens to the
+ * full range. For every interior phi the two are the same vector (`viewBasis`'s
+ * own header states that identity, and gizmoMath.test.ts pins it against a real
+ * `Matrix4.lookAt`), so nothing between the poles moved by a float.
+ */
+export const MIN_PHI_DEG = 0;
+export const MAX_PHI_DEG = 180;
 
 /** A degenerate distance is not a far-away camera, it is a camera AT the target:
  *  `lookAt` gets a zero-length direction and writes a NaN quaternion, and every
@@ -224,11 +264,50 @@ export function workingPose(view: WorkingView): { position: [number, number, num
  * `panBy` states, for the same reason.
  */
 export function orbitBy(view: WorkingView, dxPx: number, dyPx: number): WorkingView {
-  return {
+  const next: WorkingView = {
     ...view,
     theta: wrapDeg(view.theta - dxPx * ORBIT_DEG_PER_PX),
     phi: clampPhi(clampPhi(view.phi) - dyPx * ORBIT_DEG_PER_PX),
   };
+  // ── AUTO PERSPECTIVE, ON THE WAY OUT OF AN AXIS VIEW ──────────────────
+  //
+  // `presetWorkingView` puts the pane in ORTHOGRAPHIC, because that is what a
+  // front or a top view is FOR: a plan and an elevation with no vanishing point
+  // to read a size wrong from. Turning away from one and staying flat is the
+  // other half of that — an orthographic three-quarter view of a scene with
+  // depth in it reads as broken, which is why Blender enables Auto Perspective
+  // by default and why leaving it out would make the preset key a trap.
+  //
+  // STATELESS, on the pose rather than on a remembered flag: "was this view
+  // reached by a preset" is a question that needs one more field on a record
+  // three lanes copy, and "is this view ON an axis" answers the same question
+  // from what is already there. Manual orthographic (Numpad5) at a
+  // three-quarter angle is untouched, which is the case the flag would have
+  // been for.
+  if (view.ortho === true && next.ortho === true && isAxisView(view) && !isAxisView(next)) {
+    const { ortho: _drop, ...perspective } = next;
+    return perspective;
+  }
+  return next;
+}
+
+/** Within this many degrees of an axis, a pose IS that axis view. Half of one
+ *  numpad step, so a single Numpad4 press always leaves the neighbourhood. */
+const AXIS_VIEW_EPSILON_DEG = 1e-6;
+
+/**
+ * Is the eye on one of the six axis views?
+ *
+ * The poles (phi 0 / 180) are axis views whatever theta is — straight down is
+ * straight down. Otherwise it is the equator with theta on a quarter turn.
+ */
+export function isAxisView(view: WorkingView): boolean {
+  const phi = clampPhi(view.phi);
+  const near = (a: number, b: number): boolean => Math.abs(a - b) <= AXIS_VIEW_EPSILON_DEG;
+  if (near(phi, MIN_PHI_DEG) || near(phi, MAX_PHI_DEG)) return true;
+  if (!near(phi, 90)) return false;
+  const theta = Math.abs(wrapDeg(view.theta));
+  return near(theta, 0) || near(theta, 90) || near(theta, 180);
 }
 
 /**
@@ -367,6 +446,101 @@ export function dollyBy(view: WorkingView, wheelDeltaY: number, bounds?: DollyBo
   return { ...view, distance };
 }
 
+/**
+ * Point the orbit at a new place WITHOUT moving the eye.
+ *
+ * ── ORBIT AROUND THE SELECTION ──────────────────────────────────────────
+ *
+ * `orbitBy` always pivots on `view.target`, and nothing ever fed the selection
+ * into it — so after a few pans the pivot was wherever the target had drifted
+ * to, and orbiting swung the thing the author was working on straight off the
+ * pane. Blender's "Orbit Around Selection" fixes it by re-pointing the pivot,
+ * and the whole trick is that the EYE STAYS PUT: `workingPose` run backwards,
+ * so the picture at the moment of re-targeting is identical to the pixel and
+ * only the next turn behaves differently. A re-target that moved the eye would
+ * be a jump cut on the way into a gesture.
+ *
+ * `workingPose` puts the eye at `target + r(sinφ sinθ, cosφ, sinφ cosθ)`, so
+ * inverting is one length and two inverse trig calls — the same convention
+ * `workingViewForIsolation` inverts, stated once more rather than shared
+ * because that one also has an ortho flag and a fit to answer for.
+ *
+ * Refuses (returns the view unchanged) when the new target is where the eye
+ * already is: there is no direction to derive angles from, and `lookAt` on a
+ * zero-length direction writes a NaN quaternion.
+ */
+export function retargetKeepingEye(
+  view: WorkingView,
+  target: readonly [number, number, number],
+): WorkingView {
+  if (target.some((n) => !Number.isFinite(n))) return view;
+  const eye = workingPose(view).position;
+  const dx = eye[0] - target[0];
+  const dy = eye[1] - target[1];
+  const dz = eye[2] - target[2];
+  const distance = Math.hypot(dx, dy, dz);
+  if (!(distance > MIN_DISTANCE)) return view;
+  return {
+    ...view,
+    // acos of the y component over the radius, which is phi by construction.
+    // Clamped for the float that lands a hair outside [-1, 1].
+    phi: (Math.acos(Math.max(-1, Math.min(1, dy / distance))) * 180) / Math.PI,
+    theta: wrapDeg((Math.atan2(dx, dz) * 180) / Math.PI),
+    distance: clampDistance(distance),
+    target: [target[0], target[1], target[2]],
+  };
+}
+
+/**
+ * Dolly TOWARDS A POINT: the world point under the cursor holds still while
+ * everything else moves in or out around it.
+ *
+ * ── THE GAP THIS CLOSES ─────────────────────────────────────────────────
+ *
+ * The camera pane has anchored its wheel at the cursor since it shipped
+ * (`wheelToView`), and the working pane did not: a plain `dollyBy` only
+ * shortens the distance to the TARGET, so wheeling toward a layer off to one
+ * side approached the middle of the pane instead and the author had to pan
+ * after every notch. Blender calls it "Zoom to Mouse Position" and everyone
+ * turns it on.
+ *
+ * ── WHY THE RATIO IS TAKEN AFTER THE CLAMP ──────────────────────────────
+ *
+ * The whole rig scales UNIFORMLY about `anchor`, which makes that point a fixed
+ * point of the map — and a fixed point is what lets the wheel coalescer's
+ * summed deltas compose. Re-raycasting a stationary cursor after each flush
+ * returns the same anchor, so clamping per-step and clamping the composed step
+ * land on the same view, exactly as `dollyBy`'s own note requires.
+ *
+ * That only holds if the scale factor is the one the DISTANCE actually took.
+ * Deriving it from the raw `exp(dy / 320)` instead would keep sliding the
+ * target after the distance had hit a wall — the picture would go on drifting
+ * while the dolly had stopped, which is the one thing a wall must not do.
+ *
+ * `dollyBy` itself is untouched: this is a second function, so every caller
+ * that wants the plain dolly (the zoom buttons, the numpad, the fallback when
+ * the cursor's ray meets nothing) keeps it byte-identical.
+ */
+export function dollyTowards(
+  view: WorkingView,
+  anchor: readonly [number, number, number],
+  wheelDeltaY: number,
+  bounds?: DollyBounds,
+): WorkingView {
+  const next = dollyBy(view, wheelDeltaY, bounds);
+  const was = clampDistance(view.distance);
+  const k = was > 0 ? next.distance / was : 1;
+  if (!Number.isFinite(k) || anchor.some((n) => !Number.isFinite(n))) return next;
+  return {
+    ...next,
+    target: [
+      anchor[0] + (view.target[0] - anchor[0]) * k,
+      anchor[1] + (view.target[1] - anchor[1]) * k,
+      anchor[2] + (view.target[2] - anchor[2]) * k,
+    ],
+  };
+}
+
 /**
  * The view an author gets before they touch anything: an off-axis three-quarter
  * look with the WHOLE canvas in shot.
@@ -461,25 +635,38 @@ export type WorkingViewPreset = "front" | "back" | "right" | "left" | "top" | "b
  * to lean on mid-layout. Front is theta 0 (the shot camera's own axis, per
  * this file's convention) and back wraps to -180 via `wrapDeg`.
  *
- * TOP AND BOTTOM LAND ON THE POLE CLAMPS, not on 0/180: straight down the
- * pole the camera's roll is undefined (see MIN_PHI_DEG), so "top" is the
- * closest pose that still has a stable up — 5 degrees off vertical, keeping
- * the author's theta so the horizon stays where they left it.
+ * TOP AND BOTTOM ARE THE POLES. They used to land five degrees short, because
+ * `lookAt` with world-up writes a NaN quaternion straight down the pole — so
+ * "top" was a nearly-plan view and a true plan view was unreachable, which is
+ * the one thing a numpad axis key exists for. `StageTools` now takes `cam.up`
+ * from `viewBasis`, whose closed form is well defined AT the pole (see
+ * MIN_PHI_DEG), and the clamp opens to the full range.
+ *
+ * The author's THETA is kept, which is what decides the roll up there — spin
+ * the view before pressing Numpad7 and the plan view arrives rotated the same
+ * way, which is the turntable behaviour Blender has.
  */
 export function presetWorkingView(view: WorkingView, preset: WorkingViewPreset): WorkingView {
+  // ── AND IT GOES ORTHOGRAPHIC ────────────────────────────────────────────
+  //
+  // Which is what a front or a top view is FOR: a plan and an elevation, with
+  // no vanishing point to read a size wrong from. Blender's Auto Perspective,
+  // on by default there and now here; `orbitBy` is the other half, dropping
+  // back to perspective on the way out of an axis view.
+  const flat = { ...view, ortho: true } as const;
   switch (preset) {
     case "front":
-      return { ...view, theta: 0, phi: 90 };
+      return { ...flat, theta: 0, phi: 90 };
     case "back":
-      return { ...view, theta: wrapDeg(180), phi: 90 };
+      return { ...flat, theta: wrapDeg(180), phi: 90 };
     case "right":
-      return { ...view, theta: 90, phi: 90 };
+      return { ...flat, theta: 90, phi: 90 };
     case "left":
-      return { ...view, theta: -90, phi: 90 };
+      return { ...flat, theta: -90, phi: 90 };
     case "top":
-      return { ...view, phi: MIN_PHI_DEG };
+      return { ...flat, phi: MIN_PHI_DEG };
     case "bottom":
-      return { ...view, phi: MAX_PHI_DEG };
+      return { ...flat, phi: MAX_PHI_DEG };
   }
 }
 
@@ -498,15 +685,39 @@ export const INITIAL_WORKING_VIEW: WorkingView = defaultWorkingView(
   WORKING_FOV_DEG,
 );
 
+/**
+ * Frame a WORLD of a given extent around a point, keeping the caller's angles:
+ * `defaultWorkingView`'s own derivation with the extent substituted for the
+ * canvas diagonal. Home inside a component-driven camera fits the component's
+ * world with this rather than an empty canvas thousands of units away.
+ */
+export function workingViewForExtent(
+  view: WorkingView,
+  centre: readonly [number, number, number],
+  extent: number,
+  fovDeg: number = WORKING_FOV_DEG,
+): WorkingView {
+  const span = Number.isFinite(extent) && extent > 0 ? extent : 1;
+  return {
+    theta: view.theta,
+    phi: view.phi,
+    distance: clampDistance(planeDistance(span, fovDeg, 1) / (1 - FIT_MARGIN * 2)),
+    target: [centre[0], centre[1], centre[2]],
+    ...(view.ortho === undefined ? {} : { ortho: view.ortho }),
+  };
+}
+
 /**
  * The working view, projected onto the FRAMING model — "align the camera to
  * this view", and the half of the round trip that can fail.
  *
  * ── WHY THIS CAN REFUSE, AND WHY REFUSING IS THE FEATURE ────────────────
  *
- * A `Framing` is four numbers (x, y, zoom, roll) describing a camera that looks
- * straight down -z from the +z side. A free orbit is five, and most of them
- * describe a pose no framing can name. Writing "the closest framing" for a pose
+ * A `Framing` is five numbers (x, y, zoom, rollDeg, focusZ), of which only four
+ * are POSE — `focusZ` picks the focus plane, not where the camera stands — and
+ * all four describe a camera that looks straight down -z from the +z side. A
+ * free orbit has five pose degrees of freedom, and most of them describe a pose
+ * no framing can name. Writing "the closest framing" for a pose
  * the author is looking at from behind the canvas would hand them a camera
  * pointing at something else and call it aligned; naming the reason costs one
  * message and is the only answer they can act on.
@@ -530,7 +741,7 @@ export const INITIAL_WORKING_VIEW: WorkingView = defaultWorkingView(
  * the framing already had.
  */
 export type ViewFramingResult =
-  | { ok: true; x: number; y: number; zoom: number }
+  | { ok: true; x: number; y: number; zoom: number; yawDeg: number; pitchDeg: number }
   | { ok: false; refusal: string };
 
 /**
@@ -564,7 +775,7 @@ export function framingFromWorkingView(
     return {
       ok: false,
       refusal:
-        "The working camera is not looking anywhere a framing could describe — press Home to " +
+        "The working camera is not looking anywhere a framing could describe. Press Home to " +
         "put it back, then align.",
     };
   }
@@ -574,7 +785,7 @@ export function framingFromWorkingView(
       ok: false,
       refusal:
         "The working camera is behind the canvas, and the shot camera always looks at it from the " +
-        "front — orbit back round to the front of the layers, then align.",
+        "front. Orbit back round to the front of the layers, then align.",
     };
   }
   // Towards the plane means -z: the eye is in front of it, so the axis has to
@@ -585,7 +796,7 @@ export function framingFromWorkingView(
       ok: false,
       refusal:
         "The working camera is looking along the canvas rather than at it, so there is no " +
-        "rectangle for the shot camera to frame — orbit until the canvas faces you, then align.",
+        "rectangle for the shot camera to frame. Orbit until the canvas faces you, then align.",
     };
   }
 
@@ -607,10 +818,21 @@ export function framingFromWorkingView(
   const span = view.ortho === true ? clampDistance(view.distance) : t;
   const zoom = frame.height / (2 * span * Math.tan((fovDeg * DEG) / 2));
   if (!Number.isFinite(zoom) || zoom <= 0) {
-    return { ok: false, refusal: "The working camera is too close to the canvas to express as a framing — dolly back, then align." };
+    return { ok: false, refusal: "The working camera is too close to the canvas to express as a framing. Dolly back, then align." };
   }
-  // The one mapping, undone: world y is design -y.
-  return { ok: true, x: hit[0], y: -hit[1], zoom };
+  // The one mapping, undone: world y is design -y. And THE ANGLES (schema
+  // v26): the shot camera stands on the same sphere the working view orbits,
+  // so its yaw is the view's azimuth and its pitch the view's elevation. The
+  // orbit pivot moves from the view's target to the hit on the plane, but the
+  // eye and the direction are the same, so the picture is.
+  return {
+    ok: true,
+    x: hit[0],
+    y: -hit[1],
+    zoom,
+    yawDeg: wrapDeg(view.theta),
+    pitchDeg: Math.max(-MAX_CAMERA_PITCH_DEG, Math.min(MAX_CAMERA_PITCH_DEG, 90 - clampPhi(view.phi))),
+  };
 }
 
 /**
@@ -622,15 +844,37 @@ export function framingFromWorkingView(
  * claim, and so the fitter has one place to derive a distance from a lens.
  */
 export function workingViewForFraming(
-  framing: { x: number; y: number; zoom: number },
+  framing: { x: number; y: number; zoom: number; yawDeg?: number; pitchDeg?: number },
   frame: FrameSize,
   fovDeg: number = WORKING_FOV_DEG,
+  /**
+   * Which extent has to fit inside the pane.
+   *
+   * ── "height" IS THE ROUND TRIP; "diagonal" IS THE FIT ───────────────────
+   *
+   * `framingFromWorkingView` derives a zoom from the framed HEIGHT, so the
+   * inverse has to use the height too or "align, then look at what you aligned
+   * to" stops being an identity. That is what this function is for and it
+   * stays the default, byte-identical.
+   *
+   * But FRAME SELECTED keeps the author's angles, and a rectangle seen from an
+   * angle is turned: the extent that has to fit is its DIAGONAL. Framing the
+   * height instead under-fits at every oblique view, which is the ponytail
+   * ceiling `fitWorkingViewToSelection` used to carry — the box lands correct
+   * head-on and creeps off the pane the further round the author has orbited.
+   * The diagonal is rotation-invariant, so no angle can push a corner out; it
+   * is `defaultWorkingView`'s own derivation with the framed rectangle
+   * substituted for the canvas.
+   */
+  fit: "height" | "diagonal" = "height",
 ): WorkingView {
   const zoom = framing.zoom > 0 ? framing.zoom : 1;
+  const extent = fit === "diagonal" ? Math.hypot(frame.width, frame.height) : frame.height;
+  // The framing's own orbit angles (v26): the inverse of `framingFromWorkingView`.
   return {
-    theta: 0,
-    phi: 90,
-    distance: clampDistance(frame.height / (2 * zoom * Math.tan((fovDeg * DEG) / 2))),
+    theta: wrapDeg(framing.yawDeg ?? 0),
+    phi: clampPhi(90 - (framing.pitchDeg ?? 0)),
+    distance: clampDistance(extent / (2 * zoom * Math.tan((fovDeg * DEG) / 2))),
     target: [framing.x, -framing.y, 0],
   };
 }