@displayxr/inline3d 1.7.1 → 1.8.0

package/js/inline3d-splat-rig.js

@@ -9,7 +9,7 @@
 //
 //   RIG        caller › the block's `rig` › (a block at all ? camera : display)
 //   INTRINSICS the block › caller › ESTIMATED from the cloud › 28 mm-eq
-//   FOCUS      caller › the block's `focus.point` › MEDIAN DISPARITY › 2 m
+//   FOCUS      caller › the block's `focus.point` › NEAREST CLUMP › a block median › MEDIAN DISPARITY › 2 m
 //
 // The two capitalised steps are the interesting ones, and they exist because the fallbacks
 // underneath them are bad in a specific, silent way. A splat with no intrinsics rendered through
@@ -194,6 +194,123 @@ export function medianDisparityDistance(invz, n) {
   return m > 0 ? 1 / m : null;
 }
 
+/**
+ * NEAREST DISPARITY CLUMP — the nearest SUBSTANTIAL thing in the middle of the picture, put on the
+ * glass so the rest of the photograph recedes behind it (the pine trunk in front of the lake, the
+ * bowsprit in front of the harbour).
+ *
+ * Why it exists: a single-image lift is non-metric and its camera block carries a lens but no
+ * `focus`. The median-disparity rung below then answers "the typical depth of the WHOLE scene",
+ * which on an open landscape (tree, lake, mountains) lands tens of metres out (46.9 m measured) and
+ * puts every bit of actual subject in front of the display.
+ *
+ * Why not the nearest gaussian: the single nearest point is a floater or a grazing sliver. Why not
+ * the nearest point anywhere in frame: landscapes put their nearest content along the BOTTOM edge
+ * (grass, the dock at the photographer's feet). So — ported from the calibrated estimator the
+ * demo pages use (`nearestClumpPivot`, checked by eye on six photos) — the statistic is:
+ *
+ *   1. keep gaussians projecting into the CENTRAL HALF of the frame, each axis (needs the lens);
+ *   2. an OPACITY-weighted histogram of 1/z (disparity: well-behaved where depth has a long tail;
+ *      footprint weighting was tried and picked the sky — reconstructions give far gaussians huge
+ *      world scale);
+ *   3. a 3-bin moving average, so sampling noise between real plateaus is not a gap;
+ *   4. scan from the NEAR end for the first run of occupied bins (above a noise floor of 0.1 % of
+ *      the crop's mass) carrying at least 3 % of the crop's mass;
+ *   5. the weighted centroid of 1/z over that run, inverted to metres.
+ *
+ * @param {{tx:ArrayLike<number>,ty:ArrayLike<number>,invz:ArrayLike<number>,w?:ArrayLike<number>,n:number}} cloud
+ *        from sampleCloudRestSpace (rest-camera space, x/z, y/z, 1/z, opacity).
+ * @param {{fx:number,fy:number,cx:number,cy:number,width:number,height:number}} K  the lens.
+ * @returns {{distance:number, massFrac:number}|null} null without a lens, or when nothing in the
+ *          crop clears the mass floor.
+ */
+export function nearestClumpDistance(cloud, K) {
+  if (!cloud || !cloud.n) return null;
+  if (!K || !(K.fx > 0) || !(K.fy > 0) || !(K.width > 0) || !(K.height > 0)) return null;
+  const half = CLUMP_CENTRAL_FRAC / 2;
+  const iv = [];
+  const wt = [];
+  for (let i = 0; i < cloud.n; i++) {
+    const u = (K.fx * cloud.tx[i] + K.cx) / K.width - 0.5;
+    const v = (K.fy * cloud.ty[i] + K.cy) / K.height - 0.5;
+    if (Math.abs(u) > half || Math.abs(v) > half) continue;
+    iv.push(cloud.invz[i]);
+    wt.push(cloud.w ? cloud.w[i] : 1);
+  }
+  const n = iv.length;
+  if (!n) return null;
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (let i = 0; i < n; i++) {
+    if (iv[i] < lo) lo = iv[i];
+    if (iv[i] > hi) hi = iv[i];
+  }
+  if (!(hi > lo)) return null;
+  const B = CLUMP_N_BINS;
+  const binOf = (x) => Math.min(B - 1, Math.floor(((x - lo) / (hi - lo)) * B));
+  const bins = new Float64Array(B);
+  for (let i = 0; i < n; i++) bins[binOf(iv[i])] += wt[i];
+  let total = 0;
+  for (let i = 0; i < B; i++) total += bins[i];
+  if (!(total > 0)) return null;
+  const smooth = new Float64Array(B);
+  for (let i = 0; i < B; i++) smooth[i] = (bins[Math.max(0, i - 1)] + bins[i] + bins[Math.min(B - 1, i + 1)]) / 3;
+  const floor = total * CLUMP_NOISE_FLOOR_FRAC;
+  let i = B - 1; // the highest 1/z — the NEAREST
+  while (i >= 0) {
+    if (smooth[i] <= floor) {
+      i--;
+      continue;
+    }
+    let j = i;
+    let runMass = 0;
+    while (j >= 0 && smooth[j] > floor) {
+      runMass += bins[j];
+      j--;
+    }
+    if (runMass >= total * CLUMP_MIN_MASS_FRAC) {
+      let wSum = 0;
+      let vSum = 0;
+      for (let k = 0; k < n; k++) {
+        const b = binOf(iv[k]);
+        if (b <= i && b >= j + 1) {
+          wSum += wt[k];
+          vSum += wt[k] * iv[k];
+        }
+      }
+      const c = wSum > 0 ? vSum / wSum : (lo + hi) / 2;
+      if (!(c > 0)) return null;
+      return { distance: clamp(1 / c, FOCUS_MIN_M, FOCUS_MAX_M), massFrac: runMass / total };
+    }
+    i = j;
+  }
+  return null;
+}
+
+/** The central crop, each axis, as a fraction of the frame. */
+export const CLUMP_CENTRAL_FRAC = 0.5;
+/** 1/z histogram resolution. */
+export const CLUMP_N_BINS = 120;
+/** A clump must carry at least this fraction of the crop's opacity-weighted mass. */
+export const CLUMP_MIN_MASS_FRAC = 0.03;
+/** Below this fraction of the crop's mass a (smoothed) bin counts as empty. */
+export const CLUMP_NOISE_FLOOR_FRAC = 0.001;
+
+/**
+ * Block `focus.source` values that are themselves a WHOLE-CLOUD median — the same estimate as the
+ * median-disparity rung, written into the file by a converter. They rank BELOW the nearest clump:
+ * believing them first would reproduce the far-focus the clump exists to fix.
+ */
+export const CLOUD_MEDIAN_FOCUS_SOURCES = Object.freeze(['cloud-median', 'median-disparity']);
+
+/**
+ * Does the waterfall need a pass over the cloud for this block? Only a block with a lens AND a
+ * trusted focus answers every question itself.
+ */
+export function rigNeedsCloud(camera) {
+  return !(camera?.intrinsics && camera?.focus && !CLOUD_MEDIAN_FOCUS_SOURCES.includes(camera.focus.source));
+}
+
 /** Where a focus ends up when there is nothing at all to go on. */
 export const DEFAULT_FOCUS_M = 2.0;
 
@@ -280,8 +397,14 @@ export function resolveRig({ camera = null, opts = {}, cloud = null, canvasAspec
   //
   // ONE point, and it is the orbit centre, the pivot plane and the convergence distance at
   // once. Resolved as a point in model space; the distance falls out of it, never the reverse.
+  //   caller › caller-convergence › block (a considered focus) › NEAREST CLUMP (needs a lens)
+  //   › block (a whole-cloud median a converter wrote) › median disparity › 2 m
   let point = null;
   let focusSource = null;
+  const blockPoint = isVec3(camera?.focus?.point) ? camera.focus.point.slice(0, 3) : null;
+  const blockIsMedian = !!blockPoint && CLOUD_MEDIAN_FOCUS_SOURCES.includes(camera.focus.source);
+  const lens = intrinsicsSource === 'block' || intrinsicsSource === 'caller' ? intrinsics : null;
+  let clump = null;
   if (isVec3(opts.focus)) {
     point = opts.focus.slice(0, 3);
     focusSource = 'caller';
@@ -289,9 +412,15 @@ export function resolveRig({ camera = null, opts = {}, cloud = null, canvasAspec
     // The scalar shorthand: a focus straight ahead at this distance.
     point = aheadOfRest(rest, opts.convergence);
     focusSource = 'caller-convergence';
-  } else if (isVec3(camera?.focus?.point)) {
-    point = camera.focus.point.slice(0, 3);
+  } else if (blockPoint && !blockIsMedian) {
+    point = blockPoint;
     focusSource = 'block';
+  } else if (cloud && lens && (clump = nearestClumpDistance(cloud, lens))) {
+    point = aheadOfRest(rest, clump.distance);
+    focusSource = 'nearest-clump';
+  } else if (blockPoint) {
+    point = blockPoint;
+    focusSource = 'block-cloud-median';
   } else if (cloud) {
     const d = medianDisparityDistance(cloud.invz, cloud.n);
     if (d) {
@@ -315,6 +444,10 @@ export function resolveRig({ camera = null, opts = {}, cloud = null, canvasAspec
     focalEqMm,
     focus: point,
     focusSource,
+    /** The block's own `focus.source` (e.g. 'convergence', 'cloud-median'), for diagnostics. */
+    blockFocusSource: typeof camera?.focus?.source === 'string' ? camera.focus.source : null,
+    /** Fraction of the central crop's mass the winning clump carried (nearest-clump only). */
+    clumpMassFrac: clump ? clump.massFrac : null,
     // Advisory, straight from the block — a host page's depth budget or HUD may want them.
     focusDistances: camera?.focus
       ? { subject_m: camera.focus.subject_m, near_m: camera.focus.near_m, far_m: camera.focus.far_m }
@@ -328,3 +461,135 @@ export function resolveRig({ camera = null, opts = {}, cloud = null, canvasAspec
       : (camera?.dxr?.parallaxFactor ?? 1),
   };
 }
+
+// ── walking the cloud, for any backend ──────────────────────────────────────────────────
+//
+// The waterfall needs ONE pass over the splat centres (in the file's own space), and the
+// auto-frame needs another. Both used to be written against Spark's `mesh.forEachSplat`, which
+// is the only thing in them that is Spark. A second backend (./inline3d-splat-playcanvas.js)
+// has the same centres as a flat Float32Array instead, so the walk is expressed here against a
+// VISITOR — `forEachCentre(visit)` calls `visit(index, x, y, z, opacity)` once per splat, in
+// index order, with `opacity` undefined when the backend has none — and each backend supplies
+// the two-line adapter from what it holds. The sampling rules (stride, cap, opacity floor) live
+// here once, so the two backends cannot drift apart on what "the cloud" means.
+
+/** Cap on how many splats the rig pass inspects. Percentiles of a uniform subsample converge. */
+export const RIG_SAMPLE_CAP = 40000;
+
+/** Below this, a splat is haze — it is not where the camera was pointed and not what it saw. */
+export 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. */
+export const RIG_MIN_Z = 0.05;
+
+/** Cap on how many splat centres the fallback framing pass inspects. */
+export const FRAME_SAMPLE_CAP = 200000;
+
+/**
+ * A visitor over flat arrays: `xyz` is [x,y,z, x,y,z, …] and `opacity` (optional) is one peak
+ * opacity per splat in [0,1].
+ *
+ * @param {ArrayLike<number>} xyz
+ * @param {ArrayLike<number>|null} [opacity]
+ * @param {number} [count]  splats to visit; defaults to what `xyz` holds.
+ * @returns {(visit: Function) => void}
+ */
+export function centresVisitor(xyz, opacity = null, count = Math.floor(xyz.length / 3)) {
+  return (visit) => {
+    for (let i = 0; i < count; i++) {
+      visit(i, xyz[i * 3], xyz[i * 3 + 1], xyz[i * 3 + 2], opacity ? opacity[i] : undefined);
+    }
+  };
+}
+
+/**
+ * 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 — the centres are the file's own OpenCV frame, before any display
+ * flip, 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.
+ *
+ * @param {number} total  how many splats `forEachCentre` will visit.
+ * @param {(visit: Function) => void} forEachCentre
+ * @param {{position:number[],rotation:number[]}|null} rest
+ * @returns {{tx:Float64Array,ty:Float64Array,invz:Float64Array,w:Float64Array,n:number}|null}
+ */
+export function sampleCloudRestSpace(total, forEachCentre, rest) {
+  if (!total || typeof forEachCentre !== '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);
+  const w = new Float64Array(cap); // opacity (1 where the backend has none): the clump's weights
+  let n = 0;
+  const p = [0, 0, 0];
+  forEachCentre((index, x, y, z, opacity) => {
+    if (index % stride !== 0 || n >= cap) return;
+    if (opacity !== undefined && opacity < RIG_MIN_OPACITY) return;
+    p[0] = x;
+    p[1] = y;
+    p[2] = 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];
+    w[n] = opacity !== undefined ? opacity : 1;
+    n++;
+  });
+  return n ? { tx, ty, invz, w, n } : null;
+}
+
+/**
+ * A strided, opacity-filtered subsample of the centres, flat [x,y,z, …] — the input to
+ * `boundsFromPositions` for the fallback auto-frame. Skips near-transparent splats (haze and
+ * floaters drag a box outwards) and strides above FRAME_SAMPLE_CAP (percentiles of a uniform
+ * subsample are indistinguishable from the full set's, at a fraction of the cost).
+ *
+ * @param {number} total
+ * @param {(visit: Function) => void} forEachCentre
+ * @param {{cap?: number}} [o]  sample-size cap (default FRAME_SAMPLE_CAP; the pick set uses
+ *        RIG_SAMPLE_CAP).
+ * @returns {Float32Array|null}
+ */
+export function sampleCloudCentres(total, forEachCentre, { cap = FRAME_SAMPLE_CAP } = {}) {
+  if (!total || typeof forEachCentre !== 'function') return null;
+  const stride = Math.max(1, Math.ceil(total / cap));
+  const xyz = new Float32Array(Math.ceil(total / stride) * 3);
+  let k = 0;
+  forEachCentre((index, x, y, z, opacity) => {
+    if (index % stride !== 0) return;
+    if (opacity !== undefined && opacity < RIG_MIN_OPACITY) return;
+    if (k + 3 > xyz.length) return;
+    xyz[k++] = x;
+    xyz[k++] = y;
+    xyz[k++] = z;
+  });
+  return xyz.subarray(0, k);
+}
+
+/** The splat backends `addSplat` knows. The first is the default. */
+export const SPLAT_ENGINES = ['spark', 'playcanvas'];
+
+/**
+ * Which backend an `addSplat` call asked for. Unset is Spark — the path every page had before
+ * there was a choice. Anything unknown THROWS, synchronously: a typo'd engine name is a page bug
+ * that is true of every call, not a condition of one asset.
+ *
+ * @param {{engine?: string}} [opts]
+ * @returns {'spark'|'playcanvas'}
+ */
+export function resolveSplatEngine(opts) {
+  const engine = opts?.engine ?? 'spark';
+  if (!SPLAT_ENGINES.includes(engine)) {
+    throw new Error(
+      `@displayxr/inline3d/splat: unknown engine "${engine}" — expected ` +
+        `${SPLAT_ENGINES.map((e) => `'${e}'`).join(' or ')} (default 'spark').`,
+    );
+  }
+  return engine;
+}

package/js/inline3d-splat-shared.js

@@ -0,0 +1,269 @@
+// inline3d-splat-shared.js — the small pieces both splat backends use, written once.
+//
+// EXPERIMENTAL. Internal to `./splat` (Spark) and its `engine: 'playcanvas'` backend. Not covered
+// by the SDK's 1.x semver promise.
+//
+// Everything here is renderer-free: no three.js, no engine. The Spark path
+// (./inline3d-splat.js) and the PlayCanvas adapter (./inline3d-splat-playcanvas.js) both import
+// it, so a gesture or a coordinate convention cannot drift between the two.
+//
+// The VIEWER CONSTANTS below are read by BOTH SceneViewer (./inline3d-viewer.js, the Spark path)
+// and PlayCanvasSplatViewer (./inline3d-splat-playcanvas.js), so the two backends cannot drift
+// apart on how a drag, a wheel notch, an idle turntable or a focus change feels. Pinned by
+// test/splat-playcanvas.test.mjs (values, and a behavioural trace of both viewers side by side).
+
+/**
+ * Backstop on total subject depth, as a multiple of the display height. Generous on purpose:
+ * depth placement is a z decision (see fitTo), not a scale one, so this only catches the
+ * pathological case where a subject is so deep that no placement helps.
+ */
+export const DEFAULT_DEPTH_LIMIT = 4.0;
+/** Milliseconds of no interaction before the idle turntable starts. */
+export const IDLE_DELAY_MS = 2500;
+/**
+ * Per-frame easing factor for a focus change, matching the gallery's `EASE`.
+ *
+ * Deliberately per FRAME and not per second, because that is what the reference implementation
+ * does and a focus change is a one-off gesture response rather than a continuous motion — the
+ * difference between 60 and 120 Hz here is a settle that takes half as long, not a bug.
+ */
+export const FOCUS_EASE = 0.18;
+/** Yaw/pitch/zoom damping: each frame closes `1 − DAMP_BASE^dt` of the gap (dt in seconds). */
+export const DAMP_BASE = 0.001;
+/** Largest frame step the damping will take, seconds — a stall must not become a lurch. */
+export const MAX_DT_S = 0.1;
+/** Default pitch clamp, degrees: stops the viewer rolling under the subject. */
+export const PITCH_LIMIT = Object.freeze([-60, 60]);
+/** A full drag across the tile is this many degrees — a half turn, whatever the tile size. */
+export const DRAG_DEG_PER_TILE = 180;
+/**
+ * Wheel-zoom tuning.
+ *
+ * ZOOM_PER_PX is set so one ordinary mouse notch (~100 px in Chrome) is about a 10% step, which
+ * puts a trackpad's 1-10 px events at a fraction of a percent each — small enough that the easing
+ * reads as continuous rather than as a stack of jumps.
+ *
+ * A deltaMode-1 "line" is sized to match a wheel DETENT, not a line of text. Firefox reports a
+ * notch as deltaY 3 in lines where Chrome reports it as ~100 in pixels, so 33 makes one physical
+ * notch feel the same in both; 16 (a text line) would make Firefox roughly half as responsive as
+ * Chrome for identical hardware.
+ */
+export const WHEEL_LINE_PX = 33;
+/** A "page" in deltaMode 2; rare, but it must not be unbounded. */
+export const WHEEL_PAGE_PX = 400;
+/** Per-event ceiling, against OS pointer acceleration spikes. */
+export const WHEEL_MAX_PX = 120;
+export const ZOOM_PER_PX = 0.001;
+export const ZOOM_MIN = 0.2;
+export const ZOOM_MAX = 6;
+/** The mono fallback camera: a plain perspective camera, vertical FOV in degrees, near, far. */
+export const MONO_FOV = 35;
+export const MONO_NEAR = 0.001;
+export const MONO_FAR = 1000;
+/**
+ * The camera rig's far plane. 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 and pops out as a black hole the moment an orbit pushes it over.
+ */
+export const CAPTURE_FAR = 5000;
+
+export const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
+
+/** NaN/Infinity into a transform silently blanks the tile; reject at the setter instead. */
+export const finite = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
+
+export const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+/** [x,y,z] out of anything vector-shaped. */
+export function toArray3(v) {
+  return Array.isArray(v) ? [v[0], v[1], v[2]] : [v.x, v.y, v.z];
+}
+
+/**
+ * NDC of a client point, from the canvas's CSS box — null for an empty box.
+ *
+ * The CSS box, not the backing store: on a woven canvas the 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.
+ */
+export function canvasNdc(canvas, clientX, clientY) {
+  const box = canvas.getBoundingClientRect();
+  if (!(box.width > 0) || !(box.height > 0)) return null;
+  return {
+    x: ((clientX - box.left) / box.width) * 2 - 1,
+    y: -(((clientY - box.top) / box.height) * 2 - 1),
+  };
+}
+
+/**
+ * The two focus gestures: double-click focuses what was clicked, Space goes back to the resolved
+ * focus.
+ *
+ * Space is scoped to THIS window: a page with four splat tiles must not have one key reset all
+ * four. Hover OR keyboard focus, so it works with a pointer and with a keyboard.
+ *
+ * @param {HTMLCanvasElement} canvas
+ * @param {object} h
+ * @param {(e: MouseEvent) => boolean} h.onDoubleClick  apply the pick; return true when something
+ *        was hit (the event's default is then prevented), false to let it through.
+ * @param {() => void} h.onReset  Space.
+ * @returns {(() => void)|null} unbind, or null when the canvas cannot take listeners.
+ */
+export function bindFocusGestures(canvas, { onDoubleClick, onReset }) {
+  if (typeof canvas.addEventListener !== 'function') return null;
+  let hovering = false;
+  const onEnter = () => {
+    hovering = true;
+  };
+  const onLeave = () => {
+    hovering = false;
+  };
+  const onDblClick = (e) => {
+    if (onDoubleClick(e)) e.preventDefault();
+  };
+  const onKeyDown = (e) => {
+    if (e.code !== 'Space' && e.key !== ' ') return;
+    if (!hovering && document.activeElement !== canvas) return;
+    e.preventDefault();
+    onReset();
+  };
+  canvas.addEventListener('pointerenter', onEnter);
+  canvas.addEventListener('pointerleave', onLeave);
+  canvas.addEventListener('dblclick', onDblClick);
+  addEventListener('keydown', onKeyDown);
+  return () => {
+    canvas.removeEventListener('pointerenter', onEnter);
+    canvas.removeEventListener('pointerleave', onLeave);
+    canvas.removeEventListener('dblclick', onDblClick);
+    removeEventListener('keydown', onKeyDown);
+  };
+}
+
+/** URL path without query/hash; '' for non-strings. */
+export function pathOf(u) {
+  return typeof u === 'string' ? u.split(/[?#]/)[0] : '';
+}
+
+function extOf(u) {
+  const m = /\.([a-z0-9]+)$/i.exec(pathOf(u));
+  return m ? m[1].toLowerCase() : '';
+}
+
+/** Spark's `fileType` names, as the PlayCanvas engine's parser extensions (null = unreadable). */
+const PC_FILETYPE = { pcsogszip: 'sog', ply: 'ply' };
+
+/**
+ * Which PlayCanvas loader a source needs. The engine picks its parser from the URL's extension;
+ * a byte source gets a synthetic name so it does too.
+ *
+ * @param {string|null} src  the URL (ignored when `bytes` is given).
+ * @param {Uint8Array|null} [bytes]
+ * @param {string} [fileName]  the `.splat`/`.ksplat` disambiguator; its extension is a hint here.
+ * @param {string} [fileType]  Spark's type name, if the page passed one.
+ * @returns {{ext:'sog'|'ply'|'json', streamed:boolean}|null} null = not something the engine reads.
+ */
+export function engineFormatFor(src, bytes, fileName, fileType) {
+  if (fileType !== undefined) {
+    const ext = PC_FILETYPE[fileType];
+    return ext ? { ext, streamed: false } : null;
+  }
+  if (bytes) {
+    if (bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b && bytes[2] === 0x03 && bytes[3] === 0x04) {
+      return { ext: 'sog', streamed: false };
+    }
+    if (bytes.length >= 3 && bytes[0] === 0x70 && bytes[1] === 0x6c && bytes[2] === 0x79) return { ext: 'ply', streamed: false };
+    const e = extOf(fileName);
+    return e === 'sog' || e === 'ply' ? { ext: e, streamed: false } : null;
+  }
+  const e = extOf(src);
+  if (e === 'sog' || e === 'ply') return { ext: e, streamed: false };
+  if (e === 'json') return { ext: 'json', streamed: /lod-meta\.json$/i.test(pathOf(src)) };
+  return null;
+}
+
+// ── ORBIT: the PlayCanvas backend's built-in drag (tilt-and-relax) ──────────────────────────
+//
+// SceneViewer (the Spark path) still turns the subject cumulatively (DRAG_DEG_PER_TILE); switching
+// it to this mapping later is reading these three constants.
+
+/** Largest tilt a drag reaches, degrees, either axis; a half-width swipe gets there. */
+export const ORBIT_MAX_DEG = 15;
+/** Time constant while dragging, seconds: k = 1 − exp(−dt/τ) per frame toward the drag target. */
+export const ORBIT_TAU_DRAG_S = 0.2;
+/** Time constant of the relax back to rest after release, seconds. */
+export const ORBIT_TAU_REST_S = 0.6;
+
+/**
+ * The capture camera's off-axis WINDOW at the near plane — the one projection both backends'
+ * camera rigs draw the mono (flat) view through. Principal point honoured, so a deconverged
+ * capture (`cx` off centre) keeps its lens shift. OpenCV's y grows DOWN the image, so the TOP
+ * edge is the `cy` side.
+ *
+ * `captureFit` decides what gives when the canvas is not the capture's shape:
+ *   'height' (default) — the capture's VERTICAL extent is kept and the horizontal is widened or
+ *            narrowed to the canvas. Keeps a face the same size whatever shape the tile is; a
+ *            tile wider than the capture shows past the photograph's left/right edges.
+ *   'cover'  — the tile is always filled by photograph: when the canvas is WIDER than the capture
+ *            the horizontal extent is kept and the vertical is cropped (a 4:3 capture in a 16:9
+ *            tile loses top and bottom); when it is narrower this is 'height' (which already
+ *            crops the sides).
+ *
+ * @param {{fx:number,fy:number,cx:number,cy:number,width:number,height:number}} K  intrinsics.
+ * @param {number} aspect  canvas width / height (non-positive → the capture's own aspect).
+ * @param {number} near
+ * @param {'height'|'cover'} [captureFit='height']
+ * @returns {{left:number,right:number,top:number,bottom:number}}
+ */
+export function captureWindow(K, aspect, near, captureFit = 'height') {
+  const { fx, fy, cx, cy, width, height } = K;
+  const top = (near * cy) / fy;
+  const bottom = -(near * (height - cy)) / fy;
+  const a = aspect > 0 ? aspect : width / height;
+  if (captureFit === 'cover') {
+    const left0 = -(near * cx) / fx;
+    const right0 = (near * (width - cx)) / fx;
+    const capAspect = (right0 - left0) / (top - bottom);
+    if (a > capAspect) {
+      const vmid = (top + bottom) / 2;
+      const halfV = (right0 - left0) / a / 2;
+      return { left: left0, right: right0, top: vmid + halfV, bottom: vmid - halfV };
+    }
+  }
+  const mid = (near * (width / 2 - cx)) / fx; // horizontal centre of the capture's frustum
+  const half = ((top - bottom) * a) / 2;
+  return { left: mid - half, right: mid + half, top, bottom };
+}
+
+/** The camera-rig fits `captureFit` accepts. Anything else throws at addSplat time. */
+export const CAPTURE_FITS = Object.freeze(['height', 'cover']);
+
+/**
+ * Full vertical FOV, DEGREES, of what the capture camera shows under `captureFit` — what the
+ * camera-rig descriptor sends the runtime, so 3D crops like the flat view does. On 'height' it is
+ * the lens's own `2·atan(h / 2fy)`, bit for bit.
+ */
+export function captureVerticalFovDeg(K, aspect, near, captureFit = 'height') {
+  if (captureFit !== 'cover') return (2 * Math.atan(K.height / (2 * K.fy)) * 180) / Math.PI;
+  const w = captureWindow(K, aspect, near, captureFit);
+  // Symmetric-equivalent angle of an off-axis window: what `verticalFov` means on the wire.
+  return (2 * Math.atan((w.top - w.bottom) / (2 * near)) * 180) / Math.PI;
+}
+
+/**
+ * Can the PlayCanvas engine read this source — decidable WITHOUT loading anything? Returns a
+ * reason string when it provably cannot (so ./splat can throw at call time), null when it can or
+ * when that is only knowable later (a Blob, a URL with no extension).
+ */
+export function playcanvasCannotRead(src, { fileType, fileName } = {}) {
+  let bytes = null;
+  if (src instanceof Uint8Array) bytes = src;
+  else if (src instanceof ArrayBuffer) bytes = new Uint8Array(src, 0, Math.min(8, src.byteLength));
+  if (typeof src !== 'string' && !bytes && fileType === undefined) return null; // a Blob: known at load
+  if (typeof src === 'string' && fileType === undefined && !extOf(src)) return null;
+  if (engineFormatFor(typeof src === 'string' ? src : null, bytes, fileName, fileType)) return null;
+  const what = fileType ?? (typeof src === 'string' ? `.${extOf(src)}` : 'these bytes');
+  return (
+    `the PlayCanvas engine (the default) reads .sog, .ply and a Streamed-SOG lod-meta.json, not ` +
+    `${what}. Pass engine:'spark' for .spz / .splat / .ksplat / .rad.`
+  );
+}