@displayxr/inline3d 1.6.1 → 1.7.0

package/js/inline3d-splat.js

@@ -20,8 +20,15 @@
 
 import * as THREE from 'three';
 import { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
-import { EyeCamera, EdgeFeather } from './inline3d-three.js';
+import { EyeCamera, EdgeFeather, cameraRigFromCamera } from './inline3d-three.js';
 import { SceneViewer, boundsFromPositions } from './inline3d-viewer.js';
+import { readSogCamera } from './inline3d-sog.js';
+import { applySplatPerf, splatPerfMeshOptions } from './inline3d-splat-perf.js';
+import { resolveRig, toRestSpace, planeDistance } from './inline3d-splat-rig.js';
+
+export { applySplatPerf, SPLAT_PERF_PRESETS } from './inline3d-splat-perf.js';
+export { readSogCamera, readSogMeta } from './inline3d-sog.js';
+export { resolveRig } from './inline3d-splat-rig.js';
 
 /**
  * Sort at most this often, in ms. THE stereo optimisation in this module.
@@ -96,6 +103,29 @@ function sniffFileType(bytes) {
  * @param {number} [opts.renderScale=1]  per-eye buffer scale; 0.5–0.7 is usually free.
  * @param {number} [opts.feather=0]  edge fade in buffer px.
  * @param {number} [opts.sortIntervalMs=16]  see DEFAULT_SORT_INTERVAL_MS.
+ * @param {true|'exact'|'balanced'|'aggressive'|object} [opts.perf]  cut overdraw. Unset (the
+ *        default) changes nothing: every Spark default stays where Spark put it. `'exact'` is the
+ *        bit-exact pair (each quad shrunk to its own 1/255 alpha radius, plus the 1/255 opacity
+ *        cull) and buys little on a mostly-opaque capture; `'balanced'` (also `true`) and
+ *        `'aggressive'` tighten the quad extent, which is the axis that measured. Every knob,
+ *        what it costs in pixels, and the measurements: ./inline3d-splat-perf.js.
+ * @param {'auto'|'display'|'camera'} [opts.rig='auto']  which view rig. `auto` asks the ASSET:
+ *        the `camera` block's own `rig`, or — for a block that does not say — a camera rig,
+ *        since a block at all means a camera was recorded. No block is a display rig with the
+ *        auto-frame, which is what every existing page already has. Only read from BYTES. On the
+ *        camera path the subject is NOT reframed and the idle turntable is off unless you asked
+ *        for one. Full waterfall: ./inline3d-splat-rig.js.
+ * @param {number[]} [opts.focus]  the point to converge on and orbit about, in the splat's own
+ *        space. Top of the focus waterfall; below it the block's `focus.point`, then the median
+ *        disparity of the cloud, then 2 m.
+ * @param {number} [opts.convergence]  the straight-ahead shorthand for `focus`: a distance in
+ *        world metres along the capture's view axis.
+ * @param {object} [opts.intrinsics]  override the lens ({fx,fy,cx,cy,width,height}, one eye,
+ *        OpenCV). Only consulted when the asset carries none.
+ * @param {number} [opts.ipdFactor=1]  camera rig eye separation, ABSOLUTE.
+ * @param {number} [opts.parallaxFactor=1]  camera rig head-tracking response, ABSOLUTE.
+ * @param {boolean} [opts.focusInput=true]  bind double-click (focus what was clicked) and Space
+ *        (back to the resolved focus).
  * @param {Element} [opts.observe=canvas]  element whose visibility gates the lazy lifecycle.
  * @returns {object} a TileHandle (remove/exclude/unexclude) plus `viewer`, `mesh`, `setPose`,
  *          `resetPose`, `frame` (the bounds used, null until loaded) and `ready` (a promise).
@@ -136,6 +166,10 @@ export function addSplat(wall, canvas, src, opts = {}) {
     renderScale = 1,
     feather = 0,
     sortIntervalMs = DEFAULT_SORT_INTERVAL_MS,
+    perf = null,
+    rig = 'auto',
+    focusInput = true,
+    convergence,
     fileName,
     fileType,
     observe,
@@ -158,6 +192,10 @@ export function addSplat(wall, canvas, src, opts = {}) {
   // GLB accessory in one scene.
   const spark = new SparkRenderer({ renderer: viewer.renderer, minSortIntervalMs: sortIntervalMs });
   viewer.scene.add(spark);
+  // Nothing happens unless the page asked: with no `perf` every Spark default stays where Spark
+  // put it, so an existing page's pixels do not move. See ./inline3d-splat-perf.js for the table
+  // of what each knob costs and whether it is bit-exact.
+  const perfApplied = perf ? applySplatPerf(spark, perf) : null;
 
   // THE HANDLE IS DECLARED BEFORE THE LOADER, and that is load-bearing — not style.
   //
@@ -178,9 +216,59 @@ export function addSplat(wall, canvas, src, opts = {}) {
     mesh: null,
     spark,
     frame: null,
+    /**
+     * The `.sog`'s `camera` block, once the bytes have been read — null for a URL source, a
+     * non-`.sog`, or an asset that carries no block (which is most of them, and means "this is
+     * an object, use the display rig"). See ./inline3d-sog.js.
+     */
+    camera: null,
+    /**
+     * What the WATERFALL resolved — the rig, the lens and the focus, each beside the step that
+     * produced it (`rig.focusSource`, `rig.intrinsicsSource`, `rig.typeSource`). Null until
+     * `ready`. See ./inline3d-splat-rig.js.
+     */
+    rig: null,
+    /** What `perf` actually applied, or null. Useful for a diagnostics readout. */
+    perf: perfApplied,
     setPose: (p) => viewer.setPose(p),
     resetPose: () => viewer.resetPose(),
+    /**
+     * Point the window at something — the orbit centre, the pivot plane and (on a camera rig)
+     * the convergence, which are one thing.
+     *
+     * @param {number[]|{x:number,y:number,z:number}|null} point  in the SPLAT's own space: the
+     *        same space the `camera` block's `focus.point` is in, so a host page can hand over a
+     *        point it read from the asset's metadata without knowing anything about this SDK's
+     *        scene graph. Null returns to whatever the waterfall resolved.
+     * @param {object} [o]
+     * @param {boolean} [o.snap=false]  arrive immediately instead of easing.
+     */
+    setFocus(point, o = {}) {
+      if (!out.mesh || !out.rig) return out;
+      const model = point == null ? out.rig.focusDefault : toArray3(point);
+      out.rig.focus = model;
+      out.rig.focusSource = point == null ? out.rig.focusDefaultSource : 'set';
+      // Keep the two in step on BOTH rigs. A camera rig re-derives this from the eased focus
+      // every frame (pushViewRig), but a display rig has no rig to push — and a `convergence`
+      // left describing a focus that has since moved is exactly the kind of quietly stale
+      // readback this handle exists to avoid.
+      out.rig.convergence = planeDistance(out.rig.rest, model);
+      viewer.setFocus(toContentSpace(out.mesh, model, THREE), o);
+      return out;
+    },
+    /**
+     * What is under a point on the canvas, in the splat's own space — the raycast behind the
+     * double-click, exposed so a page can build its own gesture.
+     *
+     * @returns {number[]|null}
+     */
+    pick(clientX, clientY) {
+      const p = pickPoint(clientX, clientY);
+      return p ? toModelSpace(out.mesh, p, THREE) : null;
+    },
     remove() {
+      unbindFocusInput?.();
+      viewer.onFocusChange = null;
       handle?.remove();
       viewer.dispose();
       out.mesh?.dispose?.();
@@ -211,8 +299,13 @@ export function addSplat(wall, canvas, src, opts = {}) {
         ...(sniffed ? { fileType: sniffed } : {}),
         ...(fileName ? { fileName } : {}),
       };
+      // Read the camera block off the SAME bytes, before Spark takes them. Only possible on the
+      // bytes path — a URL source would need a second fetch of ten megabytes to learn 200 of
+      // them, so that is deliberately not done. (It is also not a limitation in practice: the
+      // asset that HAS a camera block is a generated/streamed one, which is the bytes path.)
+      if (rig !== 'display') out.camera = await readSogCamera(fileBytes);
     }
-    mesh = new SplatMesh(init);
+    mesh = new SplatMesh({ ...init, ...splatPerfMeshOptions(perf) });
     // Most exporters write splats Y-down (the original 3DGS convention); three.js is Y-up.
     // Without this every capture arrives upside down, which reads as a broken asset rather than
     // a convention mismatch. w=0,x=1 is a half turn about X.
@@ -237,6 +330,130 @@ export function addSplat(wall, canvas, src, opts = {}) {
     viewer.startMono();
   }
 
+
+  // ── focus: declaring it, and the two gestures that change it ──────────────────────────
+  //
+  // The rig descriptor is re-DECLARED whenever the focus moves, which is every frame while it
+  // eases. That is the cheap half of the contract — `setViewRig` is a per-locate value, there is
+  // nothing to tween and nothing to tear down — and it is the only thing the runtime needs to
+  // re-converge. Nothing here computes an off-axis projection.
+  let lastConvergence = Number.NaN;
+  const rigScratch = { fwd: null, tmp: null };
+  function pushViewRig(force) {
+    if (!out.rig || out.rig.type !== 'camera') return;
+    const cam = viewer.monoCamera;
+    if (!rigScratch.fwd) {
+      rigScratch.fwd = new THREE.Vector3();
+      rigScratch.tmp = new THREE.Vector3();
+    }
+    const f = viewer.getFocus();
+    // three looks down -z; the convergence is the focus's distance along that axis — the PLANE,
+    // not the radius, because that is what a zero-disparity plane is.
+    rigScratch.fwd.set(0, 0, -1).applyQuaternion(cam.quaternion);
+    const d = rigScratch.tmp.set(f.x, f.y, f.z).sub(cam.position).dot(rigScratch.fwd);
+    if (!force && Math.abs(d - lastConvergence) < 1e-3) return;
+    lastConvergence = d;
+    out.rig.convergence = d;
+    out.viewRig = cameraRigFromCamera(THREE, cam, {
+      convergence: d > 0 ? d : 0,
+      ipdFactor: out.rig.ipdFactor,
+      parallaxFactor: out.rig.parallaxFactor,
+      out: out.viewRig || {},
+    });
+    handle?.setViewRig(out.viewRig);
+  }
+  viewer.onFocusChange = () => pushViewRig(false);
+
+  /**
+   * What is under a point on the canvas.
+   *
+   * Spark's `SplatMesh.raycast` is the real answer and is used when it produces one — it is the
+   * ordinary three.js hook, so it is `raycastable` (default true) and `minRaycastOpacity`
+   * (default 0.2) that decide what counts as solid. When it returns nothing (a thin or very
+   * transparent region, an older Spark, a mesh with raycasting turned off) this falls back to
+   * the NEAREST GAUSSIAN TO THE RAY by angular distance, preferring the closest one inside a
+   * small cone. That is an approximation and is documented as one: it picks a splat CENTRE
+   * rather than a surface, so on a thick soft surface it lands a little behind where the cursor
+   * appears to be. For a focus point — a plane to converge on and turn about — that is well
+   * within the tolerance; do not build a measuring tool on it.
+   */
+  const PICK_CONE_RAD = 0.02;
+  let raycaster = null;
+  function pickPoint(clientX, clientY) {
+    const mesh = out.mesh;
+    if (!mesh) return null;
+    const box = canvas.getBoundingClientRect();
+    if (!(box.width > 0) || !(box.height > 0)) return null;
+    // NDC from the CSS box. On a woven canvas the backing store is double-width and each eye
+    // owns half of it, but what the VIEWER sees is one image filling the box, so the box is the
+    // right frame to pick in; the eye camera supplies the parallax-correct ray.
+    const ndc = {
+      x: ((clientX - box.left) / box.width) * 2 - 1,
+      y: -(((clientY - box.top) / box.height) * 2 - 1),
+    };
+    const cam = (viewer.is3D && viewer._eye?.camera) || viewer.monoCamera;
+    if (!raycaster) raycaster = new THREE.Raycaster();
+    raycaster.setFromCamera(ndc, cam);
+    if (mesh.raycastable !== false && typeof mesh.raycast === 'function') {
+      const hits = [];
+      try {
+        mesh.raycast(raycaster, hits);
+      } catch (err) {
+        console.warn('[inline3d/splat] Spark raycast threw; falling back to nearest gaussian', err);
+      }
+      if (hits.length) {
+        hits.sort((a, b) => a.distance - b.distance);
+        if (hits[0].point) return hits[0].point.clone();
+      }
+    }
+    return nearestGaussianToRay(mesh, raycaster.ray, THREE);
+  }
+
+  // ── input ─────────────────────────────────────────────────────────────────────────────
+  let unbindFocusInput = null;
+  function bindFocusInput() {
+    if (focusInput === false || unbindFocusInput || typeof canvas.addEventListener !== 'function') {
+      return;
+    }
+    let hovering = false;
+    const onEnter = () => {
+      hovering = true;
+    };
+    const onLeave = () => {
+      hovering = false;
+    };
+    const onDblClick = (e) => {
+      const world = pickPoint(e.clientX, e.clientY);
+      if (!world) return;
+      e.preventDefault();
+      out.mesh.updateWorldMatrix(true, false);
+      out.rig.focus = toArray3(out.mesh.worldToLocal(world.clone()));
+      out.rig.focusSource = 'picked';
+      out.rig.convergence = planeDistance(out.rig.rest, out.rig.focus);
+      viewer.content.updateWorldMatrix(true, false);
+      viewer.setFocus(toArray3(viewer.content.worldToLocal(world.clone())));
+    };
+    const onKeyDown = (e) => {
+      // Scoped to this window on purpose: a page with four splat tiles must not have one key
+      // reset all four. Hover OR focus, so it works with a pointer and with a keyboard.
+      if (e.code !== 'Space' && e.key !== ' ') return;
+      if (!hovering && document.activeElement !== canvas) return;
+      e.preventDefault();
+      out.setFocus(null);
+    };
+    canvas.addEventListener('pointerenter', onEnter);
+    canvas.addEventListener('pointerleave', onLeave);
+    canvas.addEventListener('dblclick', onDblClick);
+    addEventListener('keydown', onKeyDown);
+    unbindFocusInput = () => {
+      canvas.removeEventListener('pointerenter', onEnter);
+      canvas.removeEventListener('pointerleave', onLeave);
+      canvas.removeEventListener('dblclick', onDblClick);
+      removeEventListener('keydown', onKeyDown);
+      unbindFocusInput = null;
+    };
+  }
+
   // Await the MESH first, then its load. Reading `mesh.initialized` here directly would
   // dereference null: constructing from bytes is async (the Blob has to be read), so `mesh` does
   // not exist yet on this line — only inside meshReady.
@@ -253,14 +470,74 @@ export function addSplat(wall, canvas, src, opts = {}) {
       // positions the renderer draws. It costs one pass over (a sample of) the centres at load,
       // which is what the working reference sample has always done.
       const bounds = measureBounds(out.mesh, THREE) || (frame ? liftBounds(frame, out.mesh, THREE) : null);
-      if (bounds) {
-        out.frame = bounds;
-        viewer.fitTo(bounds.center, bounds.extent);
+
+      // WHICH RIG. `rig:'auto'` (the default) reads it off the ASSET: a `camera` block means the
+      // splat was lifted from a photograph, and a photograph has a viewpoint to conserve — the
+      // capture's own FOV, at the capture's own position, in a metric scene. No block means an
+      // object, which is the display rig, the auto-frame, and everything this module did before.
+      //
+      // That is the subject-vs-viewpoint test from docs/authoring-inline-3d.md §"Which rig",
+      // answered by the file instead of by the page. It is the one case where a splat viewer
+      // cannot decide for itself: the same call site loads a product turntable and a lifted
+      // photograph, and they want opposite rigs.
+      // THE WATERFALL. Three questions — which rig, what lens, what is it looking at — each
+      // answered by the best source that has an answer, with the step that answered it recorded
+      // next to the value (`handle.rig.focusSource` and friends). js/inline3d-splat-rig.js holds
+      // the arithmetic and the reasoning; this is the plumbing.
+      //
+      // One pass over the cloud feeds two of the three: the angular extent about the rest camera
+      // is the lens, and the median of 1/z is the focus. Skipped entirely when the block already
+      // answers both, so an asset that carries a full camera pays nothing for it.
+      const cloud =
+        out.camera?.intrinsics && out.camera?.focus
+          ? null
+          : sampleRestSpace(out.mesh, out.camera?.rest);
+      const box = canvas.getBoundingClientRect();
+      const resolved = resolveRig({
+        camera: out.camera,
+        opts,
+        cloud,
+        canvasAspect: box.height > 0 ? box.width / box.height : 4 / 3,
+      });
+      // What Space goes back to. Kept beside the live value so a pick can be undone without
+      // re-running the waterfall (which would walk the cloud again).
+      resolved.focusDefault = resolved.focus.slice();
+      resolved.focusDefaultSource = resolved.focusSource;
+      out.rig = resolved;
+      out.frame = bounds;
+
+      if (resolved.type === 'camera') {
+        // A turntable on a photograph is nonsense, so the default spin stops here — but only the
+        // DEFAULT: a page that asked for one still gets it.
+        if (!('idleSpin' in opts)) viewer.idleSpin = 0;
+        applyCaptureCamera(viewer, resolved, flipY);
+        // The capture does not move; only what the rotation turns about does. Snapped, because
+        // this is the asset arriving, not a gesture.
+        viewer.setFocus(toContentSpace(out.mesh, resolved.focus, THREE), {
+          snap: true,
+          recentre: false,
+        });
+        pushViewRig(true);
       } else {
-        // Unframed means drawn at raw MODEL scale, which for a typical capture is several times
-        // the tile. Say so: silence here is what made the same condition read as a fit bug.
-        console.warn('[inline3d/splat] no usable bounds — subject is UNFRAMED (model scale)', src);
+        if (bounds) viewer.fitTo(bounds.center, bounds.extent);
+        else {
+          // Unframed means drawn at raw MODEL scale, which for a typical capture is several
+          // times the tile. Say so: silence here is what made the same condition read as a fit
+          // bug.
+          console.warn('[inline3d/splat] no usable bounds — subject is UNFRAMED (model scale)', src);
+        }
+        // A display rig takes the focus as its ORBIT CENTRE, which is the one thing the two rigs
+        // share. Only when something actually said where to look: a bare `median-disparity`
+        // guess has no business overriding an auto-frame that measured the subject.
+        if (resolved.focusSource === 'caller' || resolved.focusSource === 'block') {
+          viewer.setFocus(toContentSpace(out.mesh, resolved.focus, THREE), {
+            snap: true,
+            recentre: true,
+          });
+        }
       }
+      bindFocusInput();
+      return out;
       return out;
     })
     .catch((err) => {
@@ -293,6 +570,202 @@ export function addSplat(wall, canvas, src, opts = {}) {
  * columns rather than being re-projected onto world axes: same convention the native
  * ComputeAutoFrame uses, and exact for the axis-aligned flips that actually occur.
  */
+/**
+ * Pose and lens the viewer's mono camera AS THE RECORDING CAMERA.
+ *
+ * This is the 2D half of the camera rig, and the only place in this SDK that builds a projection
+ * matrix itself. That is not a contradiction of "declare the rig, never compute": the 3D path
+ * below sends a descriptor and consumes the runtime's views as always — but the mono fallback has
+ * no runtime and no stereo, so SOMETHING has to render the capture, and the honest thing to
+ * render is the capture's own frustum. Get it wrong and the flat view is a crop or a zoom of the
+ * photograph, which reads as a framing bug.
+ *
+ * THE FLIP MOVES THE CAMERA TOO. `flipY` puts a 180° X rotation on the MESH (most exports are
+ * Y-down; three is Y-up), so a rest pose recorded in the file's own frame has to ride the same
+ * rotation or the camera ends up mirrored through the origin — the identity pose the gallery's
+ * assets carry hides this completely, which is exactly why it is done properly here.
+ *
+ * ASPECT. The intrinsics fix the capture's aspect and the canvas has its own. The vertical is
+ * kept and the horizontal is widened or narrowed to the canvas — `fit:'height'`'s convention, and
+ * the one that keeps a face the same size whatever shape the tile is. The principal point rides
+ * along, so a deconverged capture (`cx` off centre) keeps its lens shift.
+ *
+ * `updateProjectionMatrix` is REPLACED, not just called: the viewer recomputes it on every
+ * resize, and three's symmetric version would silently throw the off-axis window away on the
+ * first layout nudge.
+ */
+function applyCaptureCamera(viewer, rig, flipY, THREE_) {
+  const three = THREE_ || THREE;
+  const camera = viewer.monoCamera;
+  const { fx, fy, cx, cy, width, height } = rig.intrinsics;
+
+  const q = new three.Quaternion(
+    rig.rest.rotation[0],
+    rig.rest.rotation[1],
+    rig.rest.rotation[2],
+    rig.rest.rotation[3],
+  );
+  const p = new three.Vector3(rig.rest.position[0], rig.rest.position[1], rig.rest.position[2]);
+  // TWO half-turns about X, and they are different things — conflating them points the camera
+  // backwards at an empty scene, which is what the first version did.
+  //
+  //   · RIGHT-multiplied, ALWAYS: the convention change. The block's rotation is a camera pose
+  //     in OpenCV axes (+y down, looking down +z); three's camera looks down -z with +y up. That
+  //     is a rotation in the camera's OWN frame, so it composes on the right, and it applies
+  //     whether or not the content was flipped.
+  //   · LEFT-multiplied, only under `flipY`: the same rotation applied to the CONTENT, which is
+  //     a world-space transform the camera has to ride along with.
+  //
+  // With the identity rest pose almost every capture carries, the two cancel exactly and the
+  // camera sits at the origin looking down -z at a scene the flip has just put there.
+  const flip = new three.Quaternion(1, 0, 0, 0);
+  if (flipY) {
+    p.applyQuaternion(flip);
+    q.premultiply(flip);
+  }
+  q.multiply(flip);
+  camera.position.copy(p);
+  camera.quaternion.copy(q);
+  camera.fov = (2 * Math.atan(height / (2 * fy)) * 180) / Math.PI;
+  // FAR, and why it is not the viewer's default. A deconverged capture parks its sky at the
+  // lifter's depth cap and the refinement scatters some gaussians beyond it (239 m measured on a
+  // street scene); anything past the far plane is CLIPPED in Spark's vertex shader and pops out
+  // as a black hole the moment an orbit pushes it over. Spark composites by SORTING, not by
+  // depth-testing, so there is no z precision to protect and a huge near:far ratio costs nothing.
+  camera.far = Math.max(camera.far, 5000);
+  camera.updateMatrixWorld(true);
+
+  camera.updateProjectionMatrix = () => {
+    const near = camera.near;
+    // OpenCV's y grows DOWN the image, so the TOP edge is the `cy` side.
+    const top = (near * cy) / fy;
+    const bottom = -(near * (height - cy)) / fy;
+    const box = viewer.canvas.getBoundingClientRect();
+    const aspect = box.height > 0 ? box.width / box.height : width / height;
+    const mid = (near * (width / 2 - cx)) / fx; // horizontal centre of the capture's frustum
+    const half = ((top - bottom) * aspect) / 2;
+    camera.projectionMatrix.makePerspective(mid - half, mid + half, top, bottom, near, camera.far);
+    camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
+  };
+  camera.updateProjectionMatrix();
+}
+
+
+/** Cap on how many splats the rig pass inspects. Percentiles of a uniform subsample converge. */
+const RIG_SAMPLE_CAP = 40000;
+
+/** Below this, a splat is haze — it is not where the camera was pointed and not what it saw. */
+const RIG_MIN_OPACITY = 0.05;
+
+/** Nearer than this, a splat is behind or on the lens and its x/z, y/z, 1/z are meaningless. */
+const RIG_MIN_Z = 0.05;
+
+/**
+ * ONE walk over the cloud, in the REST CAMERA's frame, producing everything the waterfall needs
+ * that is not in the file: the angular extent that is the lens (x/z, y/z) and the disparities
+ * whose median is the focus (1/z).
+ *
+ * Model space, deliberately — `forEachSplat` reports centres before the mesh's own transform, so
+ * this is the file's own OpenCV frame, which is the frame `rest` and `intrinsics` are expressed
+ * in. Doing it after the Y-flip would mean undoing the flip to compare with the block.
+ *
+ * @returns {{tx:Float64Array,ty:Float64Array,invz:Float64Array,n:number}|null}
+ */
+function sampleRestSpace(mesh, rest) {
+  const total = mesh?.numSplats || 0;
+  if (!total || typeof mesh.forEachSplat !== 'function') return null;
+  const r = rest || { position: [0, 0, 0], rotation: [0, 0, 0, 1] };
+  const stride = Math.max(1, Math.ceil(total / RIG_SAMPLE_CAP));
+  const cap = Math.ceil(total / stride) + 1;
+  const tx = new Float64Array(cap);
+  const ty = new Float64Array(cap);
+  const invz = new Float64Array(cap);
+  let n = 0;
+  const p = [0, 0, 0];
+  mesh.forEachSplat((index, center, scales, quaternion, opacity) => {
+    if (index % stride !== 0 || n >= cap) return;
+    if (opacity !== undefined && opacity < RIG_MIN_OPACITY) return;
+    p[0] = center.x;
+    p[1] = center.y;
+    p[2] = center.z;
+    const c = toRestSpace(r, p);
+    if (!(c[2] > RIG_MIN_Z)) return;
+    tx[n] = c[0] / c[2];
+    ty[n] = c[1] / c[2];
+    invz[n] = 1 / c[2];
+    n++;
+  });
+  return n ? { tx, ty, invz, n } : null;
+}
+
+/** [x,y,z] out of anything vector-shaped. */
+function toArray3(v) {
+  return Array.isArray(v) ? [v[0], v[1], v[2]] : [v.x, v.y, v.z];
+}
+
+/** A point in the splat's own (model) space, in the viewer's CONTENT space. */
+function toContentSpace(mesh, model, three) {
+  const v = new three.Vector3(model[0], model[1], model[2]);
+  mesh.updateWorldMatrix(true, false);
+  mesh.localToWorld(v);
+  const content = mesh.parent;
+  if (content) {
+    content.updateWorldMatrix(true, false);
+    content.worldToLocal(v);
+  }
+  return [v.x, v.y, v.z];
+}
+
+/** The inverse: a WORLD point in the splat's own space. */
+function toModelSpace(mesh, world, three) {
+  const v = world.isVector3 ? world.clone() : new three.Vector3(world[0], world[1], world[2]);
+  mesh.updateWorldMatrix(true, false);
+  return toArray3(mesh.worldToLocal(v));
+}
+
+/**
+ * The pick fallback: the gaussian whose CENTRE is closest to the ray.
+ *
+ * Nearest by ANGLE, then nearest along the ray among everything inside a small cone — so a near
+ * surface wins over the sky behind it even when the sky happens to be a hair closer to the exact
+ * ray. An approximation of a hit test, not a hit test: it returns a splat centre, so on a thick
+ * soft surface it lands slightly behind the apparent one. Good enough to converge and orbit
+ * about, which is all a focus is.
+ */
+function nearestGaussianToRay(mesh, ray, three, coneRad = 0.02) {
+  const total = mesh?.numSplats || 0;
+  if (!total || typeof mesh.forEachSplat !== 'function') return null;
+  const stride = Math.max(1, Math.ceil(total / RIG_SAMPLE_CAP));
+  mesh.updateWorldMatrix(true, false);
+  const m = mesh.matrixWorld;
+  const p = new three.Vector3();
+  const rel = new three.Vector3();
+  let bestInCone = null;
+  let bestInConeT = Infinity;
+  let bestAngle = Infinity;
+  let bestAnyPoint = null;
+  mesh.forEachSplat((index, center, scales, quaternion, opacity) => {
+    if (index % stride !== 0) return;
+    if (opacity !== undefined && opacity < RIG_MIN_OPACITY) return;
+    p.copy(center).applyMatrix4(m);
+    rel.copy(p).sub(ray.origin);
+    const t = rel.dot(ray.direction);
+    if (!(t > 0)) return;
+    const perp = Math.sqrt(Math.max(0, rel.lengthSq() - t * t));
+    const angle = perp / t;
+    if (angle <= coneRad) {
+      if (t < bestInConeT) {
+        bestInConeT = t;
+        bestInCone = p.clone();
+      }
+    } else if (!bestInCone && angle < bestAngle) {
+      bestAngle = angle;
+      bestAnyPoint = p.clone();
+    }
+  });
+  return bestInCone || bestAnyPoint;
+}
+
 /** Map model-space bounds through a mesh's own transform, matching the native ComputeAutoFrame. */
 function liftBounds(b, mesh, THREE) {
   if (!b || !mesh) return b;