@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/rulers.ts

@@ -0,0 +1,129 @@
+// The rulers' arithmetic (gap 5), kept out of the component so it is tested
+// without a canvas.
+//
+// A RULER READS THE INSPECTOR'S NUMBERS: centre origin, x right, y UP. So a
+// y ruler counts upward, and a guide placed at a reading sits exactly where a
+// layer with that X or Y would. The stage's design frame runs y DOWN, which is
+// why every y mapping below carries a negative scale.
+
+/** The ruler band's thickness, in screen px. */
+export const RULER_BAND_PX = 20;
+/** The least screen distance between two labelled ticks. */
+export const RULER_LABEL_GAP_PX = 50;
+
+/** Ruler units to screen px on one axis: `px = origin + scale * value`. */
+export interface AxisMap {
+  origin: number;
+  scale: number;
+}
+
+/** The labelled step for a zoom: 1, 2 or 5 times a power of ten, the
+ *  smallest one whose labels stand at least `RULER_LABEL_GAP_PX` apart. Never
+ *  under 1, so a label is always a whole pixel. */
+export function rulerStep(pxPerUnit: number): number {
+  const scale = Math.abs(pxPerUnit);
+  if (!(scale > 0) || !Number.isFinite(scale)) return 1;
+  const need = RULER_LABEL_GAP_PX / scale;
+  let power = 10 ** Math.floor(Math.log10(need));
+  for (;;) {
+    for (const m of [1, 2, 5]) {
+      const step = m * power;
+      if (step >= need) return Math.max(1, step);
+    }
+    power *= 10;
+  }
+}
+
+/** The minor interval under a labelled step: quarters of a 2, fifths of a 1
+ *  or a 5, so every minor tick lands on a round number. */
+export function minorStep(step: number): number {
+  const lead = Math.round(step / 10 ** Math.floor(Math.log10(step) + 1e-9));
+  return lead === 2 ? step / 4 : step / 5;
+}
+
+export interface RulerTicks {
+  major: { px: number; value: number }[];
+  minor: number[];
+}
+
+/** Every tick between two screen px on one ruler. */
+export function rulerTicks(map: AxisMap, from: number, to: number): RulerTicks {
+  const out: RulerTicks = { major: [], minor: [] };
+  if (!(Math.abs(map.scale) > 0) || !Number.isFinite(map.scale) || !Number.isFinite(map.origin)) return out;
+  const step = rulerStep(map.scale);
+  // A minor interval is at least a fifth of a step, so never under 10 px:
+  // every one is drawn.
+  const unit = minorStep(step);
+  const a = (from - map.origin) / map.scale;
+  const b = (to - map.origin) / map.scale;
+  const lo = Math.min(a, b);
+  const hi = Math.max(a, b);
+  // Counted in whole minor units so a long ruler does not drift off its grid.
+  const first = Math.ceil(lo / unit);
+  const last = Math.floor(hi / unit);
+  const perMajor = Math.round(step / unit);
+  for (let i = first; i <= last; i++) {
+    const value = i * unit;
+    const px = map.origin + map.scale * value;
+    if (i % perMajor === 0) out.major.push({ px, value });
+    else out.minor.push(px);
+  }
+  return out;
+}
+
+/** A ruler label: a whole number, and never "-0". */
+export function rulerLabel(value: number): string {
+  const n = Math.round(value);
+  return n === 0 ? "0" : String(n);
+}
+
+/** The ruler map on one axis from two projected design points. `a` is the
+ *  frame centre on screen and `b` the point 100 design px along the axis
+ *  (y DOWN, as the design frame runs); the y map is flipped to read y up. */
+export function axisMapFrom(axis: "x" | "y", a: readonly [number, number], b: readonly [number, number]): AxisMap {
+  const i = axis === "x" ? 0 : 1;
+  const scale = (b[i] - a[i]) / 100;
+  return { origin: a[i], scale: axis === "x" ? scale : -scale };
+}
+
+/** A screen px back to a ruler reading. */
+export function valueAt(map: AxisMap, px: number): number {
+  return map.scale === 0 ? 0 : (px - map.origin) / map.scale;
+}
+
+/**
+ * Where a dragged guide lands: rounded to a whole pixel, and with smart
+ * guides on, pulled onto the frame's centre or edges within `threshold`
+ * screen px. Holding Ctrl (`free`) drops the pull, as it does for a layer.
+ */
+export function snapGuide(
+  value: number,
+  axis: "x" | "y",
+  frame: { width: number; height: number },
+  thresholdPx: number,
+  pxPerUnit: number,
+  smart: boolean,
+  free: boolean,
+): number {
+  if (smart && !free) {
+    const half = (axis === "x" ? frame.width : frame.height) / 2;
+    const reach = thresholdPx / Math.max(Math.abs(pxPerUnit), 1e-6);
+    for (const target of [0, -half, half]) {
+      if (Math.abs(value - target) <= reach) return target;
+    }
+  }
+  const n = Math.round(value);
+  return n === 0 ? 0 : n;
+}
+
+/** A pane's clear rect with the rulers' bands taken off its top and left, so
+ *  a fit frames the shot clear of them. */
+export function clearOfRulers<R extends { x: number; y: number; width: number; height: number }>(rect: R): R {
+  return {
+    ...rect,
+    x: rect.x + RULER_BAND_PX,
+    y: rect.y + RULER_BAND_PX,
+    width: Math.max(0, rect.width - RULER_BAND_PX),
+    height: Math.max(0, rect.height - RULER_BAND_PX),
+  };
+}

package/src/stage/sceneExtent.ts

@@ -0,0 +1,75 @@
+// How big is the scene a driven camera lives in?
+//
+// The camera body (frustumGeometry.ts) is sized against the SCENE'S extent. On
+// the rig that is the design frame; when a component drives the camera the
+// scene is whatever that component built, at whatever scale it chose (the
+// future-2035 city is ~200 units across inside a 1920-unit frame), and the only
+// honest measure of it is the live content's bounding box.
+//
+// Three-typed but GPU-free, so it is testable in node like the geometry it
+// feeds.
+import { BackSide, Box3, Vector3 } from "three";
+import type { Material, Object3D } from "three";
+import { GLYPH_DRAW_ORDER, GLYPH_TEXT_MARK } from "@dailies-studio/shot/doc";
+
+const _box = new Box3();
+const _size = new Vector3();
+
+/**
+ * A mesh whose material(s) are ALL `BackSide`: a shell meant to be seen from
+ * inside (a sky dome, an environment sphere). Under a single-sided override it
+ * is a wall around everything else (see `hideInsideOut`), and in a bounds walk
+ * it is a 1000-unit sphere that says nothing about where the content is.
+ */
+export function isInsideOutShell(o: Object3D): boolean {
+  const m = o as Object3D & { isMesh?: boolean; material?: Material | Material[] };
+  if (m.isMesh !== true || m.material === undefined) return false;
+  const mats = Array.isArray(m.material) ? m.material : [m.material];
+  return mats.length > 0 && mats.every((mat) => mat.side === BackSide);
+}
+
+/**
+ * The largest axis of the visible content's bounding box, or NaN when there is
+ * nothing to measure.
+ *
+ * Counts MESHES the shot camera can see (layer bit 0: every editor-only object,
+ * the grid, the gizmos and the marks live on bit 1 alone) and skips inside-out
+ * shells. Each mesh contributes its own geometry box under its own world
+ * matrix, never its children's, so an editor object parented under a layer
+ * cannot leak in. `out` is the caller's scratch and holds the box afterwards,
+ * for anyone who also wants its centre.
+ *
+ * GLYPH TEXT IS THE ONE EXCEPTION, and it has to be. A glyph draw is an
+ * instanced mesh whose geometry is a unit quad and whose world matrix is the
+ * publication object's identity: every glyph on screen is a row in an instanced
+ * attribute, so the geometry box says the whole paragraph is a 1-unit square at
+ * the origin. Counting it would pull the extent to the origin and shrink the
+ * camera body against a scene it measured wrongly. The PARAGRAPH object knows,
+ * so the draws are skipped and the paragraphs unioned instead.
+ */
+export function sceneExtent(root: Object3D, out: Box3): number {
+  out.makeEmpty();
+  root.traverseVisible((o) => {
+    if ((o.layers.mask & 1) === 0) return;
+    if (o.userData[GLYPH_TEXT_MARK] === true) {
+      const local = (o as Object3D & { boundingBox?: Box3 }).boundingBox;
+      if (local === undefined || local.isEmpty()) return;
+      _box.copy(local).applyMatrix4(o.matrixWorld);
+      out.union(_box);
+      return;
+    }
+    const m = o as Object3D & { isMesh?: boolean; geometry?: { boundingBox: Box3 | null; computeBoundingBox(): void } };
+    if (m.isMesh !== true || m.geometry === undefined) return;
+    if (o.userData[GLYPH_DRAW_ORDER] !== undefined) return;
+    if (isInsideOutShell(o)) return;
+    if (m.geometry.boundingBox === null) m.geometry.computeBoundingBox();
+    const local = m.geometry.boundingBox;
+    if (local === null || local.isEmpty()) return;
+    _box.copy(local).applyMatrix4(o.matrixWorld);
+    out.union(_box);
+  });
+  if (out.isEmpty()) return Number.NaN;
+  out.getSize(_size);
+  const extent = Math.max(_size.x, _size.y, _size.z);
+  return Number.isFinite(extent) && extent > 0 ? extent : Number.NaN;
+}

package/src/stage/shading.ts

@@ -16,6 +16,26 @@ export type ShadingMode = "solid" | "wireframe" | "material" | "rendered";
 /** Bar order, which is also Z's cycle order: cheapest first, truest last. */
 export const SHADING_MODES: readonly ShadingMode[] = ["solid", "wireframe", "material", "rendered"];
 
+/**
+ * The word for each mode, in the one place that has it.
+ *
+ * The App menu used to title-case the id and the ShadingBar hand-wrote the
+ * same four words beside its glyphs, so renaming a mode moved the menu row and
+ * left the bar's tooltip on the old name. A `Record` over the union, so a
+ * fifth mode fails to compile here rather than arriving unnamed.
+ */
+export const SHADING_LABELS: Record<ShadingMode, string> = {
+  solid: "Solid",
+  wireframe: "Wireframe",
+  material: "Material",
+  rendered: "Rendered",
+};
+
+/** What to call this mode on a control or a menu row. */
+export function shadingLabel(mode: ShadingMode): string {
+  return SHADING_LABELS[mode];
+}
+
 /** Z's cycle, wrapping. */
 export function nextShading(mode: ShadingMode): ShadingMode {
   const at = SHADING_MODES.indexOf(mode);