@opsydyn/effect-three 0.2.0 → 0.4.0

package/src/kernel/seeded.ts

@@ -0,0 +1,18 @@
+/**
+ * A small seeded random generator (mulberry32): the same numbers for the same seed on
+ * every page load, so randomly scattered scene parts are reproducible.
+ *
+ * @module
+ */
+
+/** A generator of numbers in [0, 1) from `seed`, as `Math.random` would give them. */
+export const seededRandom = (seed: number): (() => number) => {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+};

package/src/kernel/shots.ts

@@ -0,0 +1,167 @@
+/**
+ * Setting up a shot by name (roadmap, "Beyond parity" 3): a vocabulary an assistant (or
+ * a person) can use instead of numbers. `shotCamera` frames a box from a named angle, as
+ * a photographer would ask for it, through `fitCamera`; `moodStaging` turns a lighting
+ * mood into lights, image-based lighting and a sky. Both return descriptions to keep in
+ * the Model, so a shot is undoable and replayable like any other change.
+ *
+ * @module
+ */
+import { Vector3 } from 'three';
+
+import {
+  directionalLight,
+  environment,
+  hemisphereLight,
+  sky,
+  sunPositionFromAngles,
+} from './build.ts';
+import type { Camera, Environment, SceneNode, Sky, Vec3 } from './description.ts';
+import { type Box, fitCamera } from './orbit.ts';
+
+/** Where the camera looks from, round the subject. */
+export type ShotAngle = 'front' | 'back' | 'left' | 'right' | 'top' | 'three-quarter' | 'low';
+
+export const shotAngles: ReadonlyArray<ShotAngle> = [
+  'front',
+  'back',
+  'left',
+  'right',
+  'top',
+  'three-quarter',
+  'low',
+];
+
+/**
+ * From the subject towards the camera, for each angle: in front is +z, as three's
+ * cameras look down −z; the top view stays a hair off the pole, as `OrbitControls` does.
+ */
+const directionOf: Record<ShotAngle, Vec3> = {
+  front: [0, 0.15, 1],
+  back: [0, 0.15, -1],
+  left: [-1, 0.15, 0],
+  right: [1, 0.15, 0],
+  top: [0, 1, 1e-4],
+  'three-quarter': [1, 0.7, 1],
+  low: [0.35, -0.02, 1],
+};
+
+/**
+ * The camera looking at `subject` from `angle`, as close as it can be with the box
+ * still inside the frame (`margin` 1.3 leaves room round it). `area` is the canvas's
+ * size, or its shape: only the ratio matters to a perspective camera.
+ */
+export const shotCamera = <C extends Camera>(
+  camera: C,
+  subject: Box,
+  angle: ShotAngle,
+  area: { readonly width: number; readonly height: number } = { width: 16, height: 10 },
+  margin = 1.3,
+): C => {
+  const centre = new Vector3(...subject.min).add(new Vector3(...subject.max)).multiplyScalar(0.5);
+  const from = new Vector3(...directionOf[angle]).normalize().add(centre);
+  const aimed = {
+    ...camera,
+    position: [from.x, from.y, from.z],
+    lookAt: [centre.x, centre.y, centre.z],
+  } as C;
+  // SAFETY: `fitCamera` returns the camera it was given with only its position, aim and
+  // zoom changed, so the kind of camera is the one passed in.
+  return fitCamera(aimed, subject, area, margin) as C;
+};
+
+/** A lighting mood, from the even light of a studio to a clear night. */
+export type Mood = 'studio' | 'daylight' | 'sunset' | 'night';
+
+export const moods: ReadonlyArray<Mood> = ['studio', 'daylight', 'sunset', 'night'];
+
+/** What a mood stages: lights (keyed under the prefix), image-based light and a sky. */
+export type Staging = {
+  readonly lights: ReadonlyArray<SceneNode>;
+  readonly environment: Environment | null;
+  readonly sky: Sky | null;
+};
+
+/** The staging for `mood`, its lights keyed `${prefix}:…`. */
+export const moodStaging = (mood: Mood, prefix = 'mood'): Staging => {
+  switch (mood) {
+    case 'studio':
+      return {
+        lights: [
+          hemisphereLight({
+            key: `${prefix}:fill`,
+            color: 0xffffff,
+            groundColor: 0x6f6a62,
+            intensity: 0.8,
+          }),
+          directionalLight({
+            key: `${prefix}:key`,
+            position: [4, 7, 3],
+            intensity: 2,
+            castShadow: true,
+          }),
+        ],
+        environment: environment({ environmentIntensity: 0.35 }),
+        sky: null,
+      };
+    case 'daylight':
+      return {
+        lights: [
+          hemisphereLight({
+            key: `${prefix}:sky`,
+            color: 0xcfe6ff,
+            groundColor: 0x8a7a60,
+            intensity: 1,
+          }),
+          directionalLight({
+            key: `${prefix}:sun`,
+            position: [6, 9, 4],
+            intensity: 3,
+            castShadow: true,
+          }),
+        ],
+        environment: environment({ environmentIntensity: 0.25 }),
+        sky: sky({ sunPosition: sunPositionFromAngles(0.85, 0.35) }),
+      };
+    case 'sunset':
+      return {
+        lights: [
+          hemisphereLight({
+            key: `${prefix}:sky`,
+            color: 0xffb27a,
+            groundColor: 0x3a2a40,
+            intensity: 0.6,
+          }),
+          directionalLight({
+            key: `${prefix}:sun`,
+            color: 0xff9a5a,
+            position: [-8, 2.5, 3],
+            intensity: 2.5,
+            castShadow: true,
+          }),
+        ],
+        environment: null,
+        sky: sky({ sunPosition: sunPositionFromAngles(0.52, 0.25), turbidity: 8, rayleigh: 3 }),
+      };
+    case 'night':
+      return {
+        lights: [
+          hemisphereLight({
+            key: `${prefix}:sky`,
+            color: 0x3a4a80,
+            groundColor: 0x101018,
+            intensity: 0.35,
+          }),
+          directionalLight({
+            key: `${prefix}:moon`,
+            color: 0xaabfff,
+            position: [-3, 8, -4],
+            intensity: 0.8,
+            castShadow: true,
+          }),
+        ],
+        environment: null,
+        sky: null,
+      };
+  }
+};

package/src/kernel/tape.ts

@@ -0,0 +1,124 @@
+/**
+ * A measuring tape as data (roadmap, "Beyond parity" 5): two ends placed on the scene
+ * by clicks, the distance between them, and a dashed preview from the first end to the
+ * pointer while the second is being placed. Neither three.js nor Drei has one; it is
+ * built the way the gizmos are: `placeTapeEnd` and `pointTape` return the next tape for
+ * the Model to keep, `tapeNodes` describes it, and `tapeLength` measures it.
+ *
+ * A first click places one end, a second the other; a third starts a new tape there.
+ * With `snap`, each end is rounded to that step on every axis.
+ *
+ * @module
+ */
+import { basic, group, line, mesh, sphere } from './build.ts';
+import type { Rgb, SceneNode, Vec3 } from './description.ts';
+
+export type Tape = {
+  /** The first end, once placed. */
+  readonly from: Vec3 | null;
+  /** The second end, once placed: the tape is then measured. */
+  readonly to: Vec3 | null;
+  /** Where the pointer is on the scene while the second end is being placed. */
+  readonly pointer: Vec3 | null;
+  /** Rounds each end to this step on every axis, or not when `null`. */
+  readonly snap: number | null;
+};
+
+/** An empty tape, snapping to `snap` when given. */
+export const tape = (options: { readonly snap?: number | null } = {}): Tape => ({
+  from: null,
+  to: null,
+  pointer: null,
+  snap: options.snap ?? null,
+});
+
+const snapped = (state: Tape, point: Vec3): Vec3 => {
+  const step = state.snap;
+  if (step === null) return point;
+  return [
+    Math.round(point[0] / step) * step,
+    Math.round(point[1] / step) * step,
+    Math.round(point[2] / step) * step,
+  ];
+};
+
+/** A click at `point`: the first end, the second, or (when both are placed) a new tape. */
+export const placeTapeEnd = (state: Tape, point: Vec3): Tape => {
+  const at = snapped(state, point);
+  if (state.from !== null && state.to === null) return { ...state, to: at, pointer: null };
+  return { ...state, from: at, to: null, pointer: null };
+};
+
+/** The pointer over the scene at `point` (or off it, `null`), for the preview. */
+export const pointTape = (state: Tape, point: Vec3 | null): Tape =>
+  state.from !== null && state.to === null
+    ? { ...state, pointer: point === null ? null : snapped(state, point) }
+    : state;
+
+/** An empty tape, keeping its snap. */
+export const clearTape = (state: Tape): Tape => ({ ...tape({ snap: state.snap }) });
+
+/** Where the tape's far end is: the second end, or the pointer while it is placed. */
+const farEnd = (state: Tape): Vec3 | null => state.to ?? state.pointer;
+
+const distance = (a: Vec3, b: Vec3): number => Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+
+/** The tape's length: between its ends, or to the pointer while the second is placed. */
+export const tapeLength = (state: Tape): number | undefined => {
+  const end = farEnd(state);
+  return state.from === null || end === null ? undefined : distance(state.from, end);
+};
+
+/** The middle of the tape, for a label there. */
+export const tapeMiddle = (state: Tape): Vec3 | undefined => {
+  const end = farEnd(state);
+  if (state.from === null || end === null) return undefined;
+  return [(state.from[0] + end[0]) / 2, (state.from[1] + end[1]) / 2, (state.from[2] + end[2]) / 2];
+};
+
+export type TapeLook = {
+  readonly color: Rgb;
+  /** The line's width in pixels. */
+  readonly width: number;
+  /** The end balls' radius in scene units. */
+  readonly endRadius: number;
+};
+
+const endBall = (key: string, at: Vec3, look: TapeLook): SceneNode =>
+  mesh({
+    key,
+    position: at,
+    geometry: sphere({ radius: look.endRadius, widthSegments: 16, heightSegments: 8 }),
+    material: basic({ color: look.color }),
+  });
+
+/**
+ * The tape under `key`: a ball at each placed end and a line between them, dashed while
+ * it runs to the pointer. Nothing in it is picked, so clicks reach the scene beneath.
+ */
+export const tapeNodes = (key: string, state: Tape, look: Partial<TapeLook> = {}): SceneNode => {
+  const shown: TapeLook = {
+    color: look.color ?? 0xffcc33,
+    width: look.width ?? 3,
+    endRadius: look.endRadius ?? 0.03,
+  };
+  const end = farEnd(state);
+  const ends = [state.from, state.to].flatMap((at, index) =>
+    at === null ? [] : [endBall(`${key}:end:${index}`, at, shown)],
+  );
+  const span =
+    state.from === null || end === null
+      ? []
+      : [
+          line({
+            key: `${key}:line`,
+            points: [state.from, end],
+            color: shown.color,
+            width: shown.width,
+            dashed: state.to === null,
+            dashSize: 0.08,
+            gapSize: 0.05,
+          }),
+        ];
+  return group({ key, children: [...span, ...ends] });
+};

package/src/kernel/trail.ts

@@ -0,0 +1,170 @@
+/**
+ * Trails, as Drei's `Trail` (`bf6f4ad`, `src/core/Trail.tsx`): a ribbon behind a moving
+ * node through the places it has been. Drei records the target once a frame into
+ * `length × 10` points, shifting in `decay` new ones each time it moves at least
+ * `stride`, every `interval` frames, and draws them with `meshline`. Here the same rules
+ * run on a clock of 60 steps a second of scene time rather than per frame, so a trail is
+ * as long at 30 frames a second as at 120; and the ribbon is a plain mesh turned to face
+ * the camera each frame, with vertex colours, so either renderer draws it. Its width is
+ * Drei's: a tenth of `width`, in scene units, `taper` and `fade` narrowing and fading it
+ * towards the tail (Drei takes an `attenuation` function).
+ *
+ * @module
+ */
+import {
+  BufferAttribute,
+  BufferGeometry,
+  Color,
+  DoubleSide,
+  Mesh,
+  MeshBasicMaterial,
+  Vector3,
+} from 'three';
+
+import type { Trail } from './description.ts';
+
+/** Drei records a point a frame; this records one a step of this many a second. */
+const stepsPerSecond = 60;
+
+export type TrailRibbon = {
+  /** The ribbon, in the space the positions are in; never picked. */
+  readonly object: Mesh;
+  /** Records the node at `position` for every step up to scene time `now`. */
+  readonly record: (position: Vector3, now: number) => void;
+  /** Turns the ribbon to face a camera at `eye`. */
+  readonly face: (eye: Vector3) => void;
+  /** Whether every recorded point is where the node is: the trail has caught up. */
+  readonly settled: () => boolean;
+  /** Applies a new look; a new length starts the trail again at `position`. */
+  readonly restyle: (trail: Trail, position: Vector3, now: number) => void;
+  readonly dispose: () => void;
+};
+
+/** How wide the ribbon is `along` the way from tail (0) to head (1). */
+const widthAt = (trail: Trail, along: number): number => {
+  const full = trail.width * 0.1;
+  if (trail.taper === 'linear') return full * along;
+  if (trail.taper === 'quadratic') return full * along * along;
+  return full;
+};
+
+/** A ribbon of `trail.length × 10` points, all at `start`. Allocation-free once made. */
+export const createTrailRibbon = (first: Trail, start: Vector3, now: number): TrailRibbon => {
+  let trail = first;
+  let count = 0;
+  let points = new Float32Array(0);
+  const geometry = new BufferGeometry();
+  const material = new MeshBasicMaterial({
+    vertexColors: true,
+    transparent: true,
+    side: DoubleSide,
+    depthWrite: false,
+  });
+  const object = new Mesh(geometry, material);
+  object.frustumCulled = false;
+  object.raycast = () => undefined;
+  // Not a node: marked so tools walking the scene can tell it apart.
+  object.name = 'effect-three:trail';
+  const last = new Vector3();
+  const here = new Vector3();
+  const ahead = new Vector3();
+  const behind = new Vector3();
+  const side = new Vector3();
+  const toEye = new Vector3();
+  const tint = new Color();
+  let clock = now;
+  let phase = 0;
+
+  /** Sizes the buffers for the trail's length and fills every point with `at`. */
+  const reset = (at: Vector3, time: number): void => {
+    count = Math.max(2, Math.round(trail.length * 10));
+    points = new Float32Array(count * 3);
+    for (let point = 0; point < count; point++) at.toArray(points, point * 3);
+    const index: Array<number> = [];
+    for (let point = 0; point < count - 1; point++) {
+      const a = point * 2;
+      index.push(a, a + 1, a + 2, a + 1, a + 3, a + 2);
+    }
+    geometry.setIndex(index);
+    geometry.setAttribute('position', new BufferAttribute(new Float32Array(count * 6), 3));
+    geometry.setAttribute('color', new BufferAttribute(new Float32Array(count * 8), 4));
+    paint();
+    last.copy(at);
+    clock = time;
+    phase = 0;
+  };
+
+  /** Colours each pair of vertices: the trail's colour, fading to the tail with `fade`. */
+  const paint = (): void => {
+    const colors = geometry.getAttribute('color');
+    tint.setHex(trail.color);
+    for (let point = 0; point < count; point++) {
+      const alpha = trail.fade ? point / (count - 1) : 1;
+      colors.setXYZW(point * 2, tint.r, tint.g, tint.b, alpha);
+      colors.setXYZW(point * 2 + 1, tint.r, tint.g, tint.b, alpha);
+    }
+    colors.needsUpdate = true;
+  };
+
+  /** Drei's `shiftLeft` and push: the oldest point drops, `at` joins as the newest. */
+  const push = (at: Vector3): void => {
+    points.copyWithin(0, 3);
+    at.toArray(points, (count - 1) * 3);
+  };
+
+  reset(start, now);
+
+  return {
+    object,
+    record: (position, time) => {
+      // At most a trail's worth of steps: an idle scene catches up at once.
+      const due = Math.min(count, Math.floor((time - clock) * stepsPerSecond));
+      if (due <= 0) return;
+      clock += due / stepsPerSecond;
+      for (let step = 0; step < due; step++) {
+        if (phase === 0) {
+          for (let shift = 0; shift < trail.decay; shift++) {
+            if (position.distanceTo(last) < trail.stride) continue;
+            push(position);
+          }
+          last.copy(position);
+        }
+        phase = (phase + 1) % Math.max(1, Math.round(trail.interval));
+      }
+    },
+    face: (eye) => {
+      const position = geometry.getAttribute('position');
+      for (let point = 0; point < count; point++) {
+        here.fromArray(points, point * 3);
+        ahead.fromArray(points, Math.min(point + 1, count - 1) * 3);
+        behind.fromArray(points, Math.max(point - 1, 0) * 3);
+        // Across the ribbon: square to its direction here and to the view of it.
+        side.subVectors(ahead, behind).cross(toEye.subVectors(eye, here));
+        const length = side.length();
+        if (length > 1e-9) side.multiplyScalar(widthAt(trail, point / (count - 1)) / 2 / length);
+        else side.set(0, 0, 0);
+        position.setXYZ(point * 2, here.x + side.x, here.y + side.y, here.z + side.z);
+        position.setXYZ(point * 2 + 1, here.x - side.x, here.y - side.y, here.z - side.z);
+      }
+      position.needsUpdate = true;
+    },
+    settled: () => {
+      const end = (count - 1) * 3;
+      for (let point = 0; point < end; point += 3) {
+        if (points[point] !== points[end] || points[point + 1] !== points[end + 1]) return false;
+        if (points[point + 2] !== points[end + 2]) return false;
+      }
+      return true;
+    },
+    restyle: (next, position, time) => {
+      const resized = Math.round(next.length * 10) !== Math.round(trail.length * 10);
+      trail = next;
+      if (resized) reset(position, time);
+      else paint();
+    },
+    dispose: () => {
+      geometry.dispose();
+      material.dispose();
+    },
+  };
+};

package/src/kernel/viewportGizmo.ts

@@ -0,0 +1,194 @@
+/**
+ * A viewport gizmo as data, after Drei's `GizmoHelper` with `GizmoViewport` (`bf6f4ad`,
+ * `src/core/GizmoHelper.tsx`, `src/core/GizmoViewport.tsx`): three coloured axes, turned
+ * as the camera sees the world, with a head at each end. Drei draws it in a `Hud` and,
+ * when a head is pressed, tweens the camera to look from that axis; here
+ * `viewportGizmoNodes` describes it for a scene's `hud`, `viewportAxisOf` names the head
+ * a hit is on, and `cameraAlong` returns the camera looking from that axis, for the
+ * Model to keep (a camera's `damping` eases it round, as Drei's tween does).
+ *
+ * The positive heads carry their letters, drawn with bars, as Drei's canvas textures
+ * carry theirs; the negative heads are smaller and fainter, as Drei's.
+ *
+ * @module
+ */
+import { Euler, Matrix4, Quaternion, Vector3 } from 'three';
+
+import { basic, billboard, box, circle, fixed, group, mesh } from './build.ts';
+import type { Camera, SceneNode, Vec3 } from './description.ts';
+
+/** An axis end: a positive or negative world axis. */
+export type ViewAxis = 'x' | 'y' | 'z' | '-x' | '-y' | '-z';
+
+export type ViewportGizmoOptions = {
+  /** Pixels from the middle to a head: Drei's `scale` of 40. */
+  readonly size: number;
+  /** The head under the pointer, drawn larger, as Drei's. */
+  readonly hovered: ViewAxis | null;
+  /** Leaves out the negative heads (Drei's `hideNegativeAxes`). */
+  readonly hideNegativeAxes: boolean;
+};
+
+/** Drei's `axisColors`. */
+const colours = { x: 0xff2060, y: 0x20df80, z: 0x2080ff } as const;
+/** Drei's `labelColor`. */
+const ink = 0x000000;
+
+const directions: Record<ViewAxis, Vec3> = {
+  x: [1, 0, 0],
+  y: [0, 1, 0],
+  z: [0, 0, 1],
+  '-x': [-1, 0, 0],
+  '-y': [0, -1, 0],
+  '-z': [0, 0, -1],
+};
+
+const axes = ['x', 'y', 'z', '-x', '-y', '-z'] as const;
+
+/** How the camera is turned: three's `Object3D.lookAt` for a camera, up the world's y. */
+const cameraTurn = (camera: Camera): Quaternion =>
+  new Quaternion().setFromRotationMatrix(
+    new Matrix4().lookAt(
+      new Vector3(...camera.position),
+      new Vector3(...camera.lookAt),
+      new Vector3(0, 1, 0),
+    ),
+  );
+
+/** The gizmo's turn: the camera's undone, so the axes show as the camera sees the world. */
+const gizmoTurn = (camera: Camera): Vec3 => {
+  const turn = new Euler().setFromQuaternion(cameraTurn(camera).invert());
+  return [turn.x, turn.y, turn.z];
+};
+
+/** A bar of a letter: length and angle (radians from across) in head units, at `at`. */
+const stroke = (key: string, length: number, angle: number, at: readonly [number, number]) =>
+  mesh({
+    key,
+    position: [at[0], at[1], 0.01],
+    rotation: fixed([0, 0, angle]),
+    geometry: box({ width: length, height: 0.07, depth: 0.001 }),
+    material: basic({ color: ink }),
+  });
+
+/** The letters, in bars, about the middle of a head 0.5 across. */
+const letters: Record<
+  'x' | 'y' | 'z',
+  ReadonlyArray<readonly [number, number, readonly [number, number]]>
+> = {
+  x: [
+    [0.34, Math.PI / 4, [0, 0]],
+    [0.34, -Math.PI / 4, [0, 0]],
+  ],
+  y: [
+    [0.14, Math.PI / 2, [0, -0.07]],
+    [0.17, Math.PI / 3, [0.04, 0.06]],
+    [0.17, -Math.PI / 3, [-0.04, 0.06]],
+  ],
+  z: [
+    [0.22, 0, [0, 0.11]],
+    [0.22, 0, [0, -0.11]],
+    [0.3, Math.PI / 4, [0, 0]],
+  ],
+};
+
+const isPositive = (axis: ViewAxis): axis is 'x' | 'y' | 'z' => axis.length === 1;
+
+const colourOf = (axis: ViewAxis): number =>
+  colours[isPositive(axis) ? axis : (axis.slice(1) as 'x' | 'y' | 'z')];
+
+/** Drei's head sizes: a labelled head whole, a bare one three quarters, 1.2 under the pointer. */
+const headScale = (axis: ViewAxis, hovered: ViewAxis | null): number =>
+  (isPositive(axis) ? 1 : 0.75) * (axis === hovered ? 1.2 : 1);
+
+const labelOf = (key: string, axis: ViewAxis): ReadonlyArray<SceneNode> =>
+  isPositive(axis)
+    ? letters[axis].map(([length, angle, at], index) =>
+        stroke(`${key}:${axis}:letter:${index}`, length, angle, at),
+      )
+    : [];
+
+/** A head: a disc facing the eye, in its axis's colour, with its letter on it. */
+const head = (key: string, axis: ViewAxis, hovered: ViewAxis | null): SceneNode => {
+  const scale = headScale(axis, hovered);
+  return group({
+    key: `${key}:${axis}`,
+    position: directions[axis],
+    rotation: billboard(),
+    scale: [scale, scale, scale],
+    interactive: true,
+    children: [
+      mesh({
+        key: `${key}:${axis}:disc`,
+        geometry: circle({ radius: 0.25, segments: 32 }),
+        material: basic({
+          color: colourOf(axis),
+          opacity: isPositive(axis) ? 1 : 0.75,
+          transparent: !isPositive(axis),
+        }),
+      }),
+      ...labelOf(key, axis),
+    ],
+  });
+};
+
+/** An axis's bar from the middle, as Drei's `Axis` (0.8 × 0.05 × 0.05). */
+const bar = (key: string, axis: 'x' | 'y' | 'z'): SceneNode => {
+  const [x, y, z] = directions[axis];
+  return mesh({
+    key: `${key}:${axis}:bar`,
+    position: [x * 0.4, y * 0.4, z * 0.4],
+    geometry: box({
+      width: axis === 'x' ? 0.8 : 0.05,
+      height: axis === 'y' ? 0.8 : 0.05,
+      depth: axis === 'z' ? 0.8 : 0.05,
+    }),
+    material: basic({ color: colours[axis] }),
+  });
+};
+
+/**
+ * The gizmo for `camera`, keyed under `key` (`${key}:x`, `${key}:-y` and so on), for a
+ * scene's `hud`: Drei's defaults, 40 pixels to a head, every head shown.
+ */
+export const viewportGizmoNodes = (
+  key: string,
+  camera: Camera,
+  options: Partial<ViewportGizmoOptions> = {},
+): SceneNode => {
+  const size = options.size ?? 40;
+  const hovered = options.hovered ?? null;
+  const shown = options.hideNegativeAxes === true ? axes.filter(isPositive) : axes;
+  return group({
+    key,
+    rotation: fixed(gizmoTurn(camera)),
+    scale: [size, size, size],
+    children: [
+      bar(key, 'x'),
+      bar(key, 'y'),
+      bar(key, 'z'),
+      ...shown.map((axis) => head(key, axis, hovered)),
+    ],
+  });
+};
+
+/** The head a hit `key` (or any part of one) is on, if it is one of this gizmo's. */
+export const viewportAxisOf = (key: string, hit: string): ViewAxis | undefined => {
+  const [owner, axis] = hit.split(':');
+  if (owner !== key) return undefined;
+  return axes.find((candidate) => candidate === axis);
+};
+
+/**
+ * `camera` looking from `axis` at what it looks at, as far away as it was: Drei's
+ * `tweenCamera` to that head, where it ends. Looking straight up or down, it stays a
+ * hair off the pole toward +z, as `OrbitControls` keeps its camera off them.
+ */
+export const cameraAlong = <C extends Camera>(camera: C, axis: ViewAxis): C => {
+  const target = new Vector3(...camera.lookAt);
+  const distance = new Vector3(...camera.position).distanceTo(target);
+  const direction = new Vector3(...directions[axis]);
+  if (axis === 'y' || axis === '-y') direction.z = 1e-6;
+  const position = direction.normalize().multiplyScalar(distance).add(target);
+  return { ...camera, position: [position.x, position.y, position.z] };
+};