@opsydyn/effect-three 0.3.0 → 0.6.4

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/timeline.ts

@@ -0,0 +1,93 @@
+/**
+ * A timeline of physics steps, as data (ADR-014): inputs stamped with the step they apply
+ * at, and how far a world on `physics({ until })` may go. Peers (or a replay) that give
+ * the same inputs at the same steps to the same world get the same world, however their
+ * frames fell, because every change lands while the world waits at its step.
+ *
+ * The Model keeps a `Timeline`, `schedule`s inputs as they are agreed (a lockstep turn's,
+ * a recording's), moves the `frontier` as far as is known, `reach`es each step the world
+ * reports (`PhysicsReached`), and applies what `due` hands back. Its scene's physics is
+ * `physics({ until: Timeline.until(timeline) })`: the next step with inputs, or the
+ * frontier. Use it as a namespace: `Timeline.make()`.
+ *
+ * @module
+ */
+
+/** An input, and the step it applies at. */
+export type Scheduled<I> = { readonly step: number; readonly input: I };
+
+export type Timeline<I> = {
+  /** Every input, in the order they apply: by step, then as scheduled. */
+  readonly inputs: ReadonlyArray<Scheduled<I>>;
+  /** How many of `inputs` have been handed out by `due`. */
+  readonly applied: number;
+  /** The step the world last said it reached; `null` before it says any. */
+  readonly reached: number | null;
+  /** How far the world may go before more inputs could arrive. */
+  readonly frontier: number;
+};
+
+/** An empty timeline, the world allowed as far as `frontier`. */
+export const make = <I>(frontier = 0): Timeline<I> => ({
+  inputs: [],
+  applied: 0,
+  reached: null,
+  frontier,
+});
+
+/**
+ * `input` at `step`, after any already there. The step must be one the world has not
+ * passed: not before `until`. A lockstep session stamps a turn's inputs with that turn's
+ * step, which is the frontier until the turn applies.
+ */
+export const schedule = <I>(timeline: Timeline<I>, step: number, input: I): Timeline<I> => {
+  const at = timeline.inputs.findIndex((scheduled) => scheduled.step > step);
+  const index = at < 0 ? timeline.inputs.length : at;
+  return {
+    ...timeline,
+    inputs: [...timeline.inputs.slice(0, index), { step, input }, ...timeline.inputs.slice(index)],
+  };
+};
+
+/** The world may now go as far as `frontier` (a timeline's frontier never goes back). */
+export const extend = <I>(timeline: Timeline<I>, frontier: number): Timeline<I> =>
+  frontier <= timeline.frontier ? timeline : { ...timeline, frontier };
+
+/** The world said it reached `step`. */
+export const reach = <I>(timeline: Timeline<I>, step: number): Timeline<I> =>
+  timeline.reached === step ? timeline : { ...timeline, reached: step };
+
+/**
+ * The inputs for the step the world is at, to apply now, and the timeline without them.
+ * Applied while the world waits there, they land at that step.
+ */
+export const due = <I>(
+  timeline: Timeline<I>,
+): { readonly timeline: Timeline<I>; readonly inputs: ReadonlyArray<I> } => {
+  const { reached } = timeline;
+  if (reached === null) return { timeline, inputs: [] };
+  let applied = timeline.applied;
+  while ((timeline.inputs[applied]?.step ?? Infinity) <= reached) applied += 1;
+  if (applied === timeline.applied) return { timeline, inputs: [] };
+  return {
+    timeline: { ...timeline, applied },
+    inputs: timeline.inputs.slice(timeline.applied, applied).map((scheduled) => scheduled.input),
+  };
+};
+
+/**
+ * Where the world should stop next: at the next step with inputs not yet applied, or at
+ * the frontier. Give it as `physics({ until })`.
+ */
+export const until = <I>(timeline: Timeline<I>): number =>
+  Math.min(timeline.inputs[timeline.applied]?.step ?? Infinity, timeline.frontier);
+
+/**
+ * The same inputs from the start, for a new world (a newcomer to a session, a replay):
+ * nothing applied or reached yet, the frontier where it was.
+ */
+export const restart = <I>(timeline: Timeline<I>): Timeline<I> => ({
+  ...timeline,
+  applied: 0,
+  reached: null,
+});

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();
+    },
+  };
+};