@motionscript/plot 0.0.0-stage → 0.1.0-alpha.3

package/src/graph3d/graph3d.ts

@@ -0,0 +1,615 @@
+import {
+  command,
+  easeInOut,
+  node,
+  type Command,
+  type CommandArgs,
+  Canvas3D,
+  Fills,
+  Geo,
+  Graphics3D,
+  Mat,
+  Scene3D,
+  lerpNumber,
+  property,
+  type Color,
+  type NodeConfig,
+  type NormalizedColor,
+  type Canvas3DProps,
+  type Vector3Input,
+} from "@motionscript/sdk"
+import { orbitProps, type OrbitTarget } from "@motionscript/sdk/component"
+
+import { compileExpressionCached } from "./expression"
+import {
+  lerpColor3D,
+  lerpCount,
+  lerpEquations,
+  lerpFinite,
+  cameraOrbit,
+  resolveColor3D,
+  sanitizeHeight,
+  snapFlag,
+  surfaceRevision,
+  type EquationResolved,
+} from "./shared"
+
+// --- Authored props --------------------------------------------------------
+// The loose shapes a caller writes. Each has a matching `*Resolved` type below:
+// what the `@property` mapper turns it into and what the tween interpolates.
+
+/** One plotted surface, `z = f(x, y)`. */
+export interface Graph3DEquation {
+  /** Identity across list changes — see {@link Graph3D.equations}. */
+  id: string | number
+  /** The expression, evaluated as `z = f(x, y)` (e.g. `sin(x) + cos(y)`). */
+  expression: string
+  /** The mesh's colour: any {@link Color} — a CSS string or an RGBA tuple. */
+  color: Color
+  /** Whether the surface is drawn. Defaults to true. */
+  visible?: boolean
+  /**
+   * How solid the mesh is, 0–1. Defaults to 1.
+   *
+   * Anything below 1 makes the surface blend rather than write depth, so
+   * overlapping surfaces layer instead of occluding each other. Left at 1 the
+   * surface is genuinely opaque and reads crisp — which is why that is the
+   * default, and why fading one in or out still looks right on the way through.
+   */
+  opacity?: number
+}
+
+/**
+ * Where the camera may go.
+ *
+ * Deliberately *not* OrbitControls. Those drive a camera from live mouse input,
+ * and a rendered timeline has no pointer — worse, their damping is an
+ * accumulator, so a scrubbed frame would differ from a played one and export
+ * would stop being deterministic. What is honoured here is the framing
+ * ({@link initialPosition}) and the limits; to *move* the camera, animate
+ * {@link Graph3DProps.orbit} / {@link Graph3DProps.elevation} /
+ * {@link Graph3DProps.zoom} from the timeline, which stays seekable.
+ */
+export interface Graph3DCamera {
+  /** Initial camera position, which seeds the three spherical props. */
+  initialPosition?: { x: number; y: number; z: number }
+  /** Closest the camera may come to the origin. */
+  minZoom?: number
+  /** Furthest it may pull back. */
+  maxZoom?: number
+}
+
+/** The helper grid and the axes drawn under the surfaces. */
+export interface Graph3DGrid {
+  /** Whether to draw the ground grid at all. Defaults to true. */
+  showGrid?: boolean
+  /** Total width and depth of the grid. Defaults to 20. */
+  size?: number
+  /** How many cells across. Defaults to 20. */
+  divisions?: number
+  /** Colour of the two lines through the origin. */
+  colorCenterLine?: Color
+  /** Colour of every other grid line. */
+  colorGrid?: Color
+  /** Whether to draw the X/Y/Z axes. Defaults to true. */
+  showAxes?: boolean
+  /** How far each axis reaches from the origin. Defaults to 10. */
+  axesSize?: number
+}
+
+export interface Graph3DProps extends Canvas3DProps {
+  /** The surfaces to plot, each evaluated as `z = f(x, y)` over the domain. */
+  equations: Graph3DEquation[]
+  camera: Graph3DCamera
+  grid: Graph3DGrid
+  /** Half-width of the plotted domain: x and y run `-domain … +domain`. Default 10. */
+  domain: number
+  /**
+   * Surface resolution per axis. Default 80, i.e. ~6.4k vertices per equation.
+   * Lower it when plotting several surfaces at once.
+   */
+  segments: number
+  /**
+   * Clamp on `|z|`. Default 20. Without it a function with an asymptote (`1/x`,
+   * `tan`) produces near-infinite vertices that stretch the mesh across the
+   * whole scene and wreck the framing.
+   */
+  maxHeight: number
+  /** Camera orbit about the vertical axis, in **degrees**. Animate this to spin. */
+  orbit: number
+  /** Camera elevation above the ground plane, in **degrees**. */
+  elevation: number
+  /** Camera distance from the origin, clamped by the camera's zoom limits. */
+  zoom: number
+  /** The 3D scene's background. */
+  background: Color
+  /** Skips the background entirely, letting the 2D scene behind show through. */
+  transparentBackground: boolean
+}
+
+// --- Resolved props --------------------------------------------------------
+// Canonical, fully defaulted, interpolatable. Nothing here is optional, so the
+// builder never re-derives a default and the tweens never test for one.
+
+/** {@link Graph3DCamera} after {@link resolveCamera}. */
+interface CameraResolved {
+  initialPosition: { x: number; y: number; z: number }
+  minZoom: number
+  maxZoom: number
+}
+
+/** {@link Graph3DGrid} after {@link resolveGrid}. */
+interface GridResolved {
+  showGrid: boolean
+  size: number
+  divisions: number
+  colorCenterLine: NormalizedColor
+  colorGrid: NormalizedColor
+  showAxes: boolean
+  axesSize: number
+}
+
+const DEFAULT_POSITION = { x: 15, y: 12, z: 18 }
+
+/**
+ * A 3D function grapher — any number of `z = f(x, y)` surfaces over a helper
+ * grid, with axes.
+ *
+ * Extends {@link Canvas3D} rather than `Node3D`: a grapher is a *viewport* on a
+ * scene it owns entirely, not a thing placed inside somebody else's. `Canvas3D`
+ * owns the bridge from the 2D scene graph into the 3D renderer, so subclassing
+ * it means this class only has to describe *what* to draw. It overrides
+ * `buildScene3D`, the single seam both the real render and the asset
+ * declaration pass go through.
+ *
+ *   <Graph3D
+ *     width="fill" height="fill"
+ *     equations={[{ id: 1, expression: "sin(sqrt(x^2 + y^2))", color: "#3B82F6" }]}
+ *   />
+ *
+ * Every prop is a `@property`, so a constant, a `() => signal()` binding, and
+ * `set()`/`to()` on a ref all work and agree. The non-scalar props each declare
+ * a `mapper` (loose authored shape → one canonical internal shape) and a `tween`
+ * (how that shape interpolates) — without the tween, `to({ grid: … })` would
+ * hold the old value and snap at the end, which is the standard trap for an
+ * object-valued attribute.
+ *
+ * **There is no OrbitControls and no pointer.** The camera is driven by the
+ * node's own `orbit`/`elevation`/`zoom` props, which is what keeps every frame
+ * reproducible under scrubbing and export — see {@link Graph3DCamera}.
+ */
+@node({
+  key: "graph3d",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+    acceptsChildren: true,
+  },
+  seed: {
+    width: 960,
+    height: 540,
+  },
+})
+export class Graph3D extends Canvas3D<Graph3DProps> {
+  /**
+   * The plotted surfaces.
+   *
+   * The mapper compiles each expression **once per write** (memoised by source),
+   * so the builder — which re-runs every frame — never re-parses; and it folds
+   * `visible`/`opacity` into a single number, so hiding is expressible as a
+   * fade. An expression that doesn't parse is dropped and the rest still draw,
+   * which is what lets the inspector commit on every keystroke.
+   *
+   * The tween matches the two lists by `id` — see `lerpEquations`.
+   */
+  @property({ default: [], mapper: resolveEquations, tween: lerpEquations })
+  declare equations: Graph3DEquation[]
+
+  /** The camera limits, and the framing that seeds the three spherical props. */
+  @property({ default: {}, mapper: resolveCamera, tween: lerpCamera })
+  declare camera: Graph3DCamera
+
+  /** The helper grid and axes. Flags snap at the end of a tween; the rest lerp. */
+  @property({ default: {}, mapper: resolveGrid, tween: lerpGrid })
+  declare grid: Graph3DGrid
+
+  @property({ default: 10 }) declare domain: number
+  /**
+   * Surface resolution. Tweenable, but *structural*: a geometry is immutable, so
+   * every intermediate value reallocates each surface's buffers. Set it once
+   * unless the resolution change is itself the point.
+   */
+  @property({ default: 80 }) declare segments: number
+  @property({ default: 20 }) declare maxHeight: number
+
+  @property({
+    default: "#111827",
+    mapper: resolveColor3D,
+    tween: lerpColor3D,
+  })
+  declare background: Color
+
+  @property({ default: false, tween: snapFlag })
+  declare transparentBackground: boolean
+
+  // No `default:` — the baseline is derived from `camera.initialPosition` in
+  // `applyCameraDefaults` below, which can't be expressed as a static default.
+  // So the control's kind is stated rather than inferred from one.
+  @property({ kind: "number" }) declare orbit: number
+  @property({ kind: "number" }) declare elevation: number
+  @property({ kind: "number" }) declare zoom: number
+
+  constructor(props?: NodeConfig<Graph3D, Graph3DProps>) {
+    super(props as NodeConfig<Canvas3D<Graph3DProps>, Graph3DProps>)
+    this.applyCameraDefaults(props)
+    // The backdrop is this node's own 2D fill: a `Canvas3D` composites its 3D
+    // pass over its fill layers, and there is no 3D background pass to reach
+    // for. Bound rather than copied so a tweened `background` carries, and so
+    // `transparentBackground` stays the *absence* of a fill — which is what
+    // lets the 2D scene behind actually show through.
+    if (props?.fill === undefined) {
+      this.applyProp("fill", () =>
+        this.transparentBackground ? [] : Fills.color(this.background)
+      )
+    }
+  }
+
+  /**
+   * Frame the scene at a spherical camera placement. Every axis is optional,
+   * so "pull back" and "spin round" stay separate intentions — see
+   * {@link OrbitTarget}.
+   */
+  @command({
+    args: [
+      {
+        key: "target", kind: "orbit", properties: {
+          orbit: { kind: "number", step: 1, unit: "°" },
+          elevation: { kind: "number", min: -89, max: 89, step: 1, unit: "°" },
+          zoom: { kind: "number", min: 0.2, max: 24, step: 0.1, unit: "×" },
+        },
+      },
+    ],
+  })
+  orbitTo(args: CommandArgs<{ target: OrbitTarget }> & { duration: number }): Command<Graph3DProps> {
+    return this.to({
+      data: orbitProps(args.data?.target ?? {}) as Partial<Graph3DProps>,
+      duration: args.duration,
+      easing: args.easing ?? easeInOut(),
+    })
+  }
+
+  /**
+   * Seeds `orbit`/`elevation`/`zoom` from `camera.initialPosition`, so a caller
+   * who gives a raw position gets that framing and one who gives none gets
+   * {@link DEFAULT_POSITION} — without having to restate the other two axes.
+   *
+   * Bound reactively rather than copied, so the default *tracks* the camera and
+   * a camera signal keeps working. Writing any of the three (a `set`, or the
+   * first frame of a `to`) replaces the binding with the explicit value, which
+   * is exactly the handover wanted.
+   */
+  private applyCameraDefaults(
+    props?: NodeConfig<Graph3D, Graph3DProps>
+  ): void {
+    const seed = (): Orbit3D =>
+      orbitOf((this.camera as CameraResolved).initialPosition)
+
+    if (props?.orbit === undefined) {
+      this.applyProp("orbit", () => seed().orbit)
+    }
+    if (props?.elevation === undefined) {
+      this.applyProp("elevation", () => seed().elevation)
+    }
+    if (props?.zoom === undefined) {
+      this.applyProp("zoom", () => seed().distance)
+    }
+  }
+
+
+  // ---- Drawing ------------------------------------------------------------
+
+  protected override buildScene3D(): Scene3D {
+    const scene = new Scene3D()
+    const g3 = new Graphics3D()
+    const camera = this.camera as unknown as CameraResolved
+    const grid = this.grid as unknown as GridResolved
+    const equations = this.equations as unknown as EquationResolved[]
+
+    // Polar placement is the camera's own vocabulary now, so these three pass
+    // straight through; `cameraOrbit` is the quarter turn between the stored
+    // zero and the camera's. `near`/`far` come from the scene's own bounds.
+    scene.perspective({
+      fov: 45,
+      orbit: cameraOrbit(this.orbit),
+      elevation: this.elevation,
+      // Clamped here rather than in the mapper: `zoom` and the limits are
+      // separate props, so either can be tweened and the clamp still holds.
+      distance: Math.min(Math.max(this.zoom, camera.minZoom), camera.maxZoom),
+    })
+
+    // The backdrop is the node's own 2D fill — a `Canvas3D` composites its 3D
+    // pass over its fill layers, and there is no 3D background pass to reach
+    // for. `transparentBackground` is therefore the *absence* of a fill rather
+    // than a clear colour, which is what the props mapper already emits.
+
+    // A soft ambient fill plus a key light and a weaker back light, so the
+    // underside of a surface stays readable when the camera orbits beneath it.
+    // A light's own parameters and its *placement* are separate arguments now —
+    // placement is a transform, and a transform is not a property of the lamp.
+    scene
+      .light({ type: "ambient", intensity: 0.4 })
+      .light({ type: "directional", intensity: 0.6 }, { position: [10, 20, 10] })
+      .light(
+        { type: "directional", intensity: 0.4 },
+        { position: [-10, -20, -10] }
+      )
+
+    if (grid.showGrid) this.addGrid(g3, grid)
+    if (grid.showAxes) this.addAxes(g3, grid.axesSize)
+
+    const domain = this.domain
+    const segments = Math.max(1, Math.round(this.segments))
+    const maxHeight = this.maxHeight
+    equations.forEach((equation, index) => {
+      this.addSurface(g3, equation, index, domain, segments, maxHeight)
+    })
+
+    return scene.draw(g3)
+  }
+
+  /**
+   * One `z = f(x, y)` surface, keyed by equation id rather than by position in
+   * the op list — see {@link Graph3D.equations}.
+   */
+  private addSurface(
+    g3: Graphics3D,
+    equation: EquationResolved,
+    index: number,
+    domain: number,
+    segments: number,
+    maxHeight: number
+  ): void {
+    // Fully faded out (hidden, or the far end of a cross-fade): emit nothing.
+    // Safe to skip precisely because identity is the `key`, not the slot.
+    if (equation.opacity <= 0.001) return
+
+    const span = domain * 2
+    const { sample, opacity } = equation
+    const solid = opacity >= 1
+
+    g3.mesh(
+      Geo.parametric({
+        segments,
+        // The maths plane is (x, y) and the result is height, so maths y becomes
+        // the renderer's z and the result becomes its y.
+        vertex: (u, v) => {
+          const x = u * span - domain
+          const z = v * span - domain
+          return { x, y: sanitizeHeight(sample(x, z), maxHeight), z }
+        },
+        computeNormals: true, // without this the surface is flat-lit
+        // Exactly the three things the callback above closes over. Without it the
+        // renderer re-runs `vertex` over the whole grid every frame — ~6.6k calls
+        // per surface at the default `segments: 80`, plus normals and a buffer
+        // re-upload — and a frame is drawn for all sorts of reasons that leave the
+        // surface untouched: the camera orbiting, a gizmo drag on an unrelated
+        // node repainting at pointer rate, a tween elsewhere in the scene.
+        //
+        // A morph still re-evaluates as it must: `blendEquation` hands out a fresh
+        // closure per frame mid-tween, and tweening `domain` or `maxHeight` moves
+        // the number directly.
+        revision: surfaceRevision(sample, domain, maxHeight),
+      }),
+      Mat.standard({
+        color: equation.color,
+        faces: "both", // a surface is infinitely thin; show both faces
+        roughness: 0.4,
+        metalness: 0.1,
+        // No `transparent`: the renderer derives blending from the opacity, so
+        // the flag and the value it was meant to accompany cannot disagree.
+        opacity,
+        // The fix for surfaces tearing holes in each other mid-fade. A
+        // translucent mesh that still writes depth occludes everything drawn
+        // after it, so a surface at 5% opacity renders as a near-invisible
+        // cut-out through the surfaces behind it — and it resolves only once the
+        // fade lands. Depth is written by fully opaque surfaces only; the rest
+        // blend, which is what asking for an opacity below 1 means.
+        depthWrite: solid,
+      }),
+      {
+        key: `equation:${equation.id}`,
+        // The renderer sorts the transparent pass back-to-front by centroid
+        // distance — and every surface here is centred on the origin, so their
+        // sort keys are identical and the order is arbitrary, which flickers as
+        // the camera orbits. An explicit order makes it stable.
+        renderOrder: index,
+      }
+    )
+  }
+
+  /**
+   * The ground grid, as two line ops — the centre cross and everything else —
+   * because a line op carries a single colour and the centre lines are drawn
+   * differently from the rest.
+   */
+  private addGrid(g3: Graphics3D, grid: GridResolved): void {
+    const divisions = Math.max(1, grid.divisions)
+    const half = grid.size / 2
+    const step = grid.size / divisions
+
+    const centre: Vector3Input[] = []
+    const lines: Vector3Input[] = []
+
+    for (let i = 0; i <= divisions; i++) {
+      const offset = -half + i * step
+      // A line is a centre line when it passes through the origin. With an odd
+      // division count no line does, which is the conventional behaviour.
+      const isCentre = Math.abs(offset) < step / 1000
+      const target = isCentre ? centre : lines
+      target.push([-half, 0, offset], [half, 0, offset]) // along X
+      target.push([offset, 0, -half], [offset, 0, half]) // along Z
+    }
+
+    if (lines.length > 0) {
+      // No key: a conditionally-emitted op used to shift every later op's cache
+      // slot, and the reconciler keys a drawable by its content now.
+      g3.line({
+        points: lines,
+        segments: true,
+        stroke: { fill: grid.colorGrid },
+      })
+    }
+    if (centre.length > 0) {
+      g3.line({
+        points: centre,
+        segments: true,
+        stroke: { fill: grid.colorCenterLine },
+      })
+    }
+  }
+
+  /** X/Y/Z axes in red/green/blue, the conventional colouring. */
+  private addAxes(g3: Graphics3D, length: number): void {
+    const axes: Array<[Vector3Input, string]> = [
+      [[length, 0, 0], "#ff4d4d"],
+      [[0, length, 0], "#4ade80"],
+      [[0, 0, length], "#60a5fa"],
+    ]
+
+    for (const [end, color] of axes) {
+      g3.line({ points: [[0, 0, 0], end], stroke: { fill: color } })
+    }
+  }
+}
+
+// --- Mappers & tweens ------------------------------------------------------
+
+/** Mapper for {@link Graph3D.equations}. */
+function resolveEquations(
+  input: Graph3DEquation[] | undefined
+): EquationResolved[] {
+  if (!input) return []
+  const out: EquationResolved[] = []
+  for (const equation of input) {
+    const sample = compileExpressionCached(equation.expression)
+    if (!sample) continue // unparseable or empty — drop it, keep the rest
+    out.push({
+      id: String(equation.id),
+      sample,
+      color: resolveColor3D(equation.color),
+      opacity: equation.visible === false ? 0 : (equation.opacity ?? 1),
+    })
+  }
+  return out
+}
+
+/**
+ * Mapper for {@link Graph3D.camera}.
+ *
+ * Merges onto `previous` rather than onto the bare defaults, which is what makes
+ * a partial write mean "change this much and leave the rest". It matters most on
+ * a `to` command, whose target states only the fields that command touches: a
+ * tween that raises `maxZoom` must not silently hand the framing back to
+ * {@link DEFAULT_POSITION} on its way.
+ */
+function resolveCamera(
+  input: Graph3DCamera | undefined,
+  previous?: CameraResolved
+): CameraResolved {
+  const base = previous ?? {
+    initialPosition: DEFAULT_POSITION,
+    minZoom: 0.1,
+    maxZoom: Number.POSITIVE_INFINITY,
+  }
+  return {
+    initialPosition: input?.initialPosition ?? base.initialPosition,
+    minZoom: input?.minZoom ?? base.minZoom,
+    maxZoom: input?.maxZoom ?? base.maxZoom,
+  }
+}
+
+/** Tween for {@link Graph3D.camera}. */
+function lerpCamera(
+  from: CameraResolved,
+  to: CameraResolved,
+  t: number
+): CameraResolved {
+  return {
+    initialPosition: {
+      x: lerpNumber(from.initialPosition.x, to.initialPosition.x, t),
+      y: lerpNumber(from.initialPosition.y, to.initialPosition.y, t),
+      z: lerpNumber(from.initialPosition.z, to.initialPosition.z, t),
+    },
+    // `maxZoom` defaults to Infinity, which a plain lerp turns into NaN.
+    minZoom: lerpFinite(from.minZoom, to.minZoom, t),
+    maxZoom: lerpFinite(from.maxZoom, to.maxZoom, t),
+  }
+}
+
+/** The grid a node with nothing said about it draws. */
+const DEFAULT_GRID: GridResolved = {
+  showGrid: true,
+  size: 20,
+  divisions: 20,
+  colorCenterLine: resolveColor3D("#4b5563"),
+  colorGrid: resolveColor3D("#1f2937"),
+  showAxes: true,
+  axesSize: 10,
+}
+
+/** Mapper for {@link Graph3D.grid}. Merges onto `previous` — see {@link resolveCamera}. */
+function resolveGrid(
+  input: Graph3DGrid | undefined,
+  previous?: GridResolved
+): GridResolved {
+  const base = previous ?? DEFAULT_GRID
+  return {
+    showGrid: input?.showGrid ?? base.showGrid,
+    size: input?.size ?? base.size,
+    divisions: input?.divisions ?? base.divisions,
+    colorCenterLine:
+      input?.colorCenterLine === undefined
+        ? base.colorCenterLine
+        : resolveColor3D(input.colorCenterLine),
+    colorGrid:
+      input?.colorGrid === undefined
+        ? base.colorGrid
+        : resolveColor3D(input.colorGrid),
+    showAxes: input?.showAxes ?? base.showAxes,
+    axesSize: input?.axesSize ?? base.axesSize,
+  }
+}
+
+/** Tween for {@link Graph3D.grid}. */
+function lerpGrid(from: GridResolved, to: GridResolved, t: number): GridResolved {
+  return {
+    showGrid: snapFlag(from.showGrid, to.showGrid, t),
+    size: lerpNumber(from.size, to.size, t),
+    divisions: lerpCount(from.divisions, to.divisions, t),
+    colorCenterLine: lerpColor3D(from.colorCenterLine, to.colorCenterLine, t),
+    colorGrid: lerpColor3D(from.colorGrid, to.colorGrid, t),
+    showAxes: snapFlag(from.showAxes, to.showAxes, t),
+    axesSize: lerpNumber(from.axesSize, to.axesSize, t),
+  }
+}
+
+/** A camera placement in spherical terms. */
+interface Orbit3D {
+  orbit: number
+  elevation: number
+  distance: number
+}
+
+/** Decomposes a raw camera position into spherical terms. */
+function orbitOf(position: { x: number; y: number; z: number }): Orbit3D {
+  const distance = Math.hypot(position.x, position.y, position.z) || 1
+  const sin = Math.min(1, Math.max(-1, position.y / distance))
+  return {
+    orbit: Math.atan2(position.z, position.x) * (180 / Math.PI),
+    elevation: Math.asin(sin) * (180 / Math.PI),
+    distance,
+  }
+}

package/src/graph3d/index.ts

@@ -0,0 +1,21 @@
+/**
+ * The Graph 3D node — a **native** node type (see `node-types.ts` /
+ * `NODE_CLASS_BY_KEY`) like the chart family beside it: built, themed and
+ * animated from the inspector rather than loaded as a code package.
+ *
+ * The one node in the app that draws in three dimensions. It plots any number of
+ * `z = f(x, y)` surfaces over a helper grid, sampling each from an expression
+ * the author types — which is why its own little language lives here
+ * (`expression.ts`) rather than reaching for a maths library: an expression is a
+ * value stored in a scene document, so compiling it as JavaScript would make
+ * every scene file an execution vector, and a 100×100 surface is ten thousand
+ * evaluations per equation per frame, which a general evaluator would not
+ * survive.
+ *
+ * There is no OrbitControls here and no pointer: the camera is three tweenable
+ * numbers, so every frame is reproducible under scrubbing and export. See
+ * {@link Graph3DCamera}.
+ */
+export * from "./expression";
+export * from "./graph3d";
+export * from "./shared";