@displayxr/inline3d 1.7.1 → 1.9.0

package/js/inline3d-splat.js

@@ -24,7 +24,27 @@ 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';
+import {
+  toArray3,
+  canvasNdc,
+  bindFocusGestures,
+  captureWindow,
+  captureVerticalFovDeg,
+  CAPTURE_FITS,
+  playcanvasCannotRead,
+  isStreamedUrl,
+  STREAMED_NEEDS_PLAYCANVAS,
+} from './inline3d-splat-shared.js';
+import {
+  resolveRig,
+  planeDistance,
+  sampleCloudRestSpace,
+  rigNeedsCloud,
+  sampleCloudCentres,
+  RIG_SAMPLE_CAP,
+  RIG_MIN_OPACITY,
+  resolveSplatEngine,
+} from './inline3d-splat-rig.js';
 
 export { applySplatPerf, SPLAT_PERF_PRESETS } from './inline3d-splat-perf.js';
 export { readSogCamera, readSogMeta } from './inline3d-sog.js';
@@ -40,9 +60,6 @@ export { resolveRig } from './inline3d-splat-rig.js';
  */
 const DEFAULT_SORT_INTERVAL_MS = 16;
 
-/** Cap on how many splat centres the fallback framing pass inspects. */
-const FRAME_SAMPLE_CAP = 200000;
-
 /**
  * three.js floor for THIS subpath — Spark's own floor, above the package-wide >=0.150 that the
  * core and ./three ask for.
@@ -140,6 +157,27 @@ function sniffFileType(bytes) {
  * good enough for a clean, isolated capture, weaker on a scene with a background wall.
  */
 export function addSplat(wall, canvas, src, opts = {}) {
+  if (opts.captureFit !== undefined && !CAPTURE_FITS.includes(opts.captureFit)) {
+    throw new Error(
+      `@displayxr/inline3d/splat: captureFit "${opts.captureFit}" — expected ` +
+        `${CAPTURE_FITS.map((f) => `'${f}'`).join(' or ')}.`,
+    );
+  }
+  // WHICH ENGINE. Unset (or 'spark') is everything below, untouched. 'playcanvas' goes to
+  // ./inline3d-splat-playcanvas.js, imported DYNAMICALLY so a page that never asks for it never
+  // resolves `playcanvas` — see addSplatDeferred.
+  if (resolveSplatEngine(opts) === 'playcanvas') {
+    // A format that engine provably cannot read (a .spz URL, gzip bytes, a Spark-only fileType)
+    // is a page bug: say so NOW rather than fail inside a loader later.
+    const why = playcanvasCannotRead(src, opts);
+    if (why) throw new Error(`@displayxr/inline3d/splat: ${why}`);
+    return addSplatDeferred(wall, canvas, src, opts);
+  }
+
+  // A Streamed SOG on Spark is a page bug (Spark has no lod-meta.json reader): say so now, by
+  // name, rather than let Spark fail on an "unknown file type" that reads like a corrupt asset.
+  if (isStreamedUrl(src)) throw new Error(`@displayxr/inline3d/splat: ${STREAMED_NEEDS_PLAYCANVAS}`);
+
   // Fail here, synchronously, and not through `ready`: a peer too old is an install-time mistake
   // in the page's dependencies, not a condition of this asset, and it will be true of every call.
   // Surfacing it as a load rejection would let a caller render an "asset unavailable" placeholder
@@ -168,6 +206,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
     sortIntervalMs = DEFAULT_SORT_INTERVAL_MS,
     perf = null,
     rig = 'auto',
+    captureFit = 'height',
     focusInput = true,
     convergence,
     fileName,
@@ -211,6 +250,19 @@ export function addSplat(wall, canvas, src, opts = {}) {
   // the console and a fit pipeline that provably never executed.
   let handle = null;
   const out = {
+    backend: 'spark',
+    /**
+     * ADVANCED, not covered by the semver promise: the three.js objects behind this window, for
+     * a page that wants to add its own content. `camera` is whichever camera draws the current
+     * frame (an eye in 3D, the mono camera flat).
+     */
+    engine: Object.freeze({
+      renderer: viewer.renderer,
+      scene: viewer.scene,
+      get camera() {
+        return (viewer.is3D && viewer._eye?.camera) || viewer.monoCamera;
+      },
+    }),
     viewer,
     // null until the bytes are read and the mesh is constructed; use `ready` to await it.
     mesh: null,
@@ -275,6 +327,21 @@ export function addSplat(wall, canvas, src, opts = {}) {
     },
     exclude: (el) => handle?.exclude(el),
     unexclude: (el) => handle?.unexclude(el),
+    /** Where the window is pointed, in the SPLAT's own space; null before load. */
+    getFocus(o) {
+      if (!out.mesh) return null;
+      const f = viewer.getFocus(o);
+      return toModelSpace(out.mesh, viewer.content.localToWorld(new THREE.Vector3(f.x, f.y, f.z)), THREE);
+    },
+    /** Called with the live focus, in the splat's own space, whenever it moves. */
+    onFocusChange: null,
+    /** Not on this backend: the crossfading asset swap is a PlayCanvas-backend feature. */
+    setSource() {
+      throw new Error(
+        "@displayxr/inline3d/splat: setSource() is implemented on the PlayCanvas backend " +
+          "only; with the Spark backend, remove() this handle and addSplat() the new asset.",
+      );
+    },
   };
 
   // `src` may be a URL or the bytes themselves.
@@ -362,7 +429,11 @@ export function addSplat(wall, canvas, src, opts = {}) {
     });
     handle?.setViewRig(out.viewRig);
   }
-  viewer.onFocusChange = () => pushViewRig(false);
+  viewer.onFocusChange = () => {
+    pushViewRig(false);
+    const cb = out.onFocusChange;
+    if (typeof cb === 'function' && out.mesh) cb(out.getFocus(), { focusSource: out.rig?.focusSource ?? null });
+  };
 
   /**
    * What is under a point on the canvas.
@@ -382,15 +453,9 @@ export function addSplat(wall, canvas, src, opts = {}) {
   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),
-    };
+    // NDC from the CSS box (./inline3d-splat-shared.js says why the box and not the store).
+    const ndc = canvasNdc(canvas, clientX, clientY);
+    if (!ndc) return null;
     const cam = (viewer.is3D && viewer._eye?.camera) || viewer.monoCamera;
     if (!raycaster) raycaster = new THREE.Raycaster();
     raycaster.setFromCamera(ndc, cam);
@@ -412,46 +477,27 @@ export function addSplat(wall, canvas, src, opts = {}) {
   // ── 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;
-    };
+    if (focusInput === false || unbindFocusInput) return;
+    const off = bindFocusGestures(canvas, {
+      onDoubleClick: (e) => {
+        const world = pickPoint(e.clientX, e.clientY);
+        if (!world) return false;
+        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())));
+        return true;
+      },
+      onReset: () => out.setFocus(null),
+    });
+    unbindFocusInput =
+      off &&
+      (() => {
+        off();
+        unbindFocusInput = null;
+      });
   }
 
   // Await the MESH first, then its load. Reading `mesh.initialized` here directly would
@@ -489,7 +535,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
       // 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
+        !rigNeedsCloud(out.camera)
           ? null
           : sampleRestSpace(out.mesh, out.camera?.rest);
       const box = canvas.getBoundingClientRect();
@@ -510,7 +556,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
         // 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);
+        applyCaptureCamera(viewer, resolved, flipY, THREE, captureFit, () => pushViewRig(true));
         // 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), {
@@ -555,6 +601,60 @@ export function addSplat(wall, canvas, src, opts = {}) {
   return out;
 }
 
+/**
+ * The `engine: 'playcanvas'` handle, returned SYNCHRONOUSLY like the Spark one.
+ *
+ * The adapter module is loaded on demand, so for a moment the handle exists before its
+ * implementation does. Rather than make every caller await something new, the handle starts as
+ * stubs that QUEUE: `exclude()` (which a product page calls on the very next line), `setPose`,
+ * `setFocus`, `remove` — and the adapter replays the queue into the real implementation, on the
+ * SAME object, the moment it arrives. `ready` resolves to this object, as it does on Spark.
+ * Fields (`viewer`, `mesh`, `rig`, …) are null until then; `viewer` in particular appears one
+ * module-load later than on Spark.
+ */
+function addSplatDeferred(wall, canvas, src, opts) {
+  const pending = [];
+  const queue = (name) => (...args) => {
+    pending.push([name, args]);
+    return name === 'setFocus' ? out : undefined;
+  };
+  const out = {
+    backend: 'playcanvas',
+    engine: null,
+    viewer: null,
+    mesh: null,
+    frame: null,
+    camera: null,
+    rig: null,
+    perf: null,
+    setPose: queue('setPose'),
+    resetPose: queue('resetPose'),
+    setFocus: queue('setFocus'),
+    // A swap requested before the first asset has landed runs once it has (the adapter's own
+    // setSource replaces this stub on the same object by then).
+    setSource: (...args) => out.ready.then(() => out.setSource(...args)),
+    getFocus: () => null,
+    // A plain data slot the adapter reads at call time, so a callback assigned on the very next
+    // line after addSplat — before the module has loaded — is the one that fires.
+    onFocusChange: null,
+    pick: () => null,
+    // Splat accounting (resident / budget / first frame); null until the adapter has loaded.
+    stats: () => null,
+    remove: queue('remove'),
+    exclude: queue('exclude'),
+    unexclude: queue('unexclude'),
+  };
+  // The ONE owner of `ready`: the adapter returns its load promise and never touches this field.
+  out.ready = import('./inline3d-splat-playcanvas.js')
+    .then((m) => m.attachPlayCanvasSplat(out, wall, canvas, src, opts, pending))
+    .catch((err) => {
+      // The adapter warns about its own load failures; this is for the module not arriving.
+      if (!out.viewer) console.warn('[inline3d/splat] engine:playcanvas failed to start', err);
+      throw err;
+    });
+  return out;
+}
+
 /**
  * Percentile bounds from the loaded splats — the fallback when no sidecar was supplied.
  *
@@ -594,10 +694,10 @@ export function addSplat(wall, canvas, src, opts = {}) {
  * 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_) {
+function applyCaptureCamera(viewer, rig, flipY, THREE_, captureFit = 'height', onFov = null) {
   const three = THREE_ || THREE;
   const camera = viewer.monoCamera;
-  const { fx, fy, cx, cy, width, height } = rig.intrinsics;
+  const { width, height } = rig.intrinsics;
 
   const q = new three.Quaternion(
     rig.rest.rotation[0],
@@ -626,7 +726,7 @@ function applyCaptureCamera(viewer, rig, flipY, THREE_) {
   q.multiply(flip);
   camera.position.copy(p);
   camera.quaternion.copy(q);
-  camera.fov = (2 * Math.atan(height / (2 * fy)) * 180) / Math.PI;
+  camera.fov = captureVerticalFovDeg(rig.intrinsics, NaN, camera.near, 'height');
   // 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
@@ -637,70 +737,45 @@ function applyCaptureCamera(viewer, rig, flipY, THREE_) {
 
   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);
+    // The window is shared with the PlayCanvas backend (./inline3d-splat-shared.js), `captureFit`
+    // included; on 'height' it is the same arithmetic this function always did.
+    const w = captureWindow(rig.intrinsics, aspect, near, captureFit);
+    camera.projectionMatrix.makePerspective(w.left, w.right, w.top, w.bottom, near, camera.far);
     camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
+    if (captureFit !== 'height') {
+      const fov = captureVerticalFovDeg(rig.intrinsics, aspect, near, captureFit);
+      if (fov !== camera.fov) {
+        camera.fov = fov;
+        onFov?.();
+      }
+    }
   };
   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.
+ * ONE walk over the cloud, in the REST CAMERA's frame — see `sampleCloudRestSpace` in
+ * ./inline3d-splat-rig.js, which holds the sampling rules for every backend. This is only the
+ * Spark adapter onto it: `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 in.
  *
  * @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;
+  return sampleCloudRestSpace(total, sparkCentres(mesh), rest);
 }
 
-/** [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];
+/** Spark's `forEachSplat` as the backend-neutral centre visitor ./inline3d-splat-rig.js walks. */
+function sparkCentres(mesh) {
+  return (visit) =>
+    mesh.forEachSplat((index, center, scales, quaternion, opacity) =>
+      visit(index, center.x, center.y, center.z, opacity),
+    );
 }
 
 /** A point in the splat's own (model) space, in the viewer's CONTENT space. */
@@ -784,18 +859,7 @@ export function measureSplatBounds(mesh, three = THREE) {
 function measureBounds(mesh, THREE) {
   const total = mesh.numSplats || 0;
   if (!total) return null;
-  const stride = Math.max(1, Math.ceil(total / FRAME_SAMPLE_CAP));
-  const xyz = new Float32Array(Math.ceil(total / stride) * 3);
-  let k = 0;
-  mesh.forEachSplat((index, center, scales, quaternion, opacity) => {
-    if (index % stride !== 0) return;
-    if (opacity !== undefined && opacity < 0.05) return;
-    if (k + 3 > xyz.length) return;
-    xyz[k++] = center.x;
-    xyz[k++] = center.y;
-    xyz[k++] = center.z;
-  });
-  const local = boundsFromPositions(xyz.subarray(0, k));
+  const local = boundsFromPositions(sampleCloudCentres(total, sparkCentres(mesh)));
   if (!local) return null;
 
   mesh.updateMatrix();

package/js/inline3d-three.js

@@ -212,14 +212,7 @@ function scratch(THREE) {
  * @returns {object} an XRViewRigInit-shaped plain object.
  */
 export function cameraRigFromCamera(THREE, camera, opts = {}) {
-  const {
-    convergence = 0,
-    attach = false,
-    ipdFactor = 1,
-    parallaxFactor = 1,
-    metersToVirtual = 1,
-    out = {},
-  } = opts;
+  const { attach = false, out = {} } = opts;
   out.type = 'camera';
   if (attach) {
     // Identity pose: the rig IS the camera, so the runtime reports eyes in camera space and the
@@ -236,12 +229,53 @@ export function cameraRigFromCamera(THREE, camera, opts = {}) {
     out.position = { x: p.x, y: p.y, z: p.z };
     out.orientation = { x: q.x, y: q.y, z: q.z, w: q.w };
   }
+  // three's fov is the FULL angle, in degrees
+  return fillCameraRig(out, THREE.MathUtils.degToRad(camera.fov), opts);
+}
+
+/**
+ * The same CAMERA-rig descriptor as {@link cameraRigFromCamera}, from a plain pose instead of a
+ * three.js camera — for a renderer that is not three (./splat's PlayCanvas backend), or a page
+ * that keeps its camera as numbers.
+ *
+ * Field for field the descriptor cameraRigFromCamera builds, in the same key order, and the
+ * degrees → radians step is the same multiplication three's `MathUtils.degToRad` does, so the
+ * two agree to the bit for the same pose (pinned in test/view-rig.test.mjs).
+ *
+ * @param {object} pose
+ * @param {{x:number,y:number,z:number}} pose.position  WORLD position.
+ * @param {{x:number,y:number,z:number,w:number}} pose.orientation  WORLD orientation.
+ * @param {number} pose.fov  FULL vertical angle, in DEGREES (three's `camera.fov` convention).
+ * @param {object} [opts]  as cameraRigFromCamera.
+ * @returns {object} an XRViewRigInit-shaped plain object.
+ */
+export function cameraRigFromPose(pose, opts = {}) {
+  const { attach = false, out = {} } = opts;
+  out.type = 'camera';
+  if (attach) {
+    out.position = { x: 0, y: 0, z: 0 };
+    out.orientation = { x: 0, y: 0, z: 0, w: 1 };
+  } else {
+    const p = pose.position;
+    const q = pose.orientation;
+    out.position = { x: p.x, y: p.y, z: p.z };
+    out.orientation = { x: q.x, y: q.y, z: q.z, w: q.w };
+  }
+  return fillCameraRig(out, pose.fov * DEG2RAD, opts);
+}
+
+/** three's `MathUtils.DEG2RAD`, so a pose-built rig matches a camera-built one to the bit. */
+const DEG2RAD = Math.PI / 180;
+
+/** The fields every camera rig carries after its pose. One writer, so the two builders agree. */
+function fillCameraRig(out, verticalFovRad, opts) {
+  const { convergence = 0, ipdFactor = 1, parallaxFactor = 1, metersToVirtual = 1 } = opts;
   out.ipdFactor = ipdFactor;
   out.parallaxFactor = parallaxFactor;
   // Diopters, not distance: the wire unit is 1/distance so that "infinity" is representable as
   // a finite 0 instead of a sentinel.
   out.convergenceDiopters = convergence > 0 ? 1 / convergence : 0;
-  out.verticalFov = THREE.MathUtils.degToRad(camera.fov); // three's fov is the FULL angle, in degrees
+  out.verticalFov = verticalFovRad;
   out.metersToVirtual = metersToVirtual;
   return out;
 }

package/js/inline3d-viewer.js

@@ -43,23 +43,27 @@
 // origin and scale it, instead of moving the display to the content. Identical framing, no
 // browser or runtime change.
 
-/**
- * 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.
- */
-const DEFAULT_DEPTH_LIMIT = 4.0;
-/** Milliseconds of no interaction before the idle turntable starts. */
-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.
- */
-const FOCUS_EASE = 0.18;
+// Every tuning constant — damping, idle delay, focus ease, wheel, zoom and pitch clamps, the
+// mono camera — lives in ./inline3d-splat-shared.js, where the PlayCanvas splat backend reads the
+// same numbers. The reasoning behind each value is documented there.
+import {
+  DEFAULT_DEPTH_LIMIT,
+  IDLE_DELAY_MS,
+  FOCUS_EASE,
+  DAMP_BASE,
+  MAX_DT_S,
+  PITCH_LIMIT,
+  DRAG_DEG_PER_TILE,
+  WHEEL_LINE_PX,
+  WHEEL_PAGE_PX,
+  WHEEL_MAX_PX,
+  ZOOM_PER_PX,
+  ZOOM_MIN,
+  ZOOM_MAX,
+  MONO_FOV,
+  MONO_NEAR,
+  MONO_FAR,
+} from './inline3d-splat-shared.js';
 
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
 // NaN/Infinity into a transform silently blanks the tile — three propagates it into the
@@ -193,7 +197,7 @@ export class SceneViewer {
       idleSpin = 0,
       renderScale = 1,
       feather = 0,
-      pitchLimit = [-60, 60],
+      pitchLimit = PITCH_LIMIT,
     } = opts;
 
     this._THREE = THREE;
@@ -286,7 +290,7 @@ export class SceneViewer {
 
     // Mono fallback camera. Deliberately a plain perspective camera: in 2D there is no display
     // plane to be in focus at, so we just look at the framed subject from the front.
-    this.monoCamera = new THREE.PerspectiveCamera(35, 1, 0.001, 1000);
+    this.monoCamera = new THREE.PerspectiveCamera(MONO_FOV, 1, MONO_NEAR, MONO_FAR);
 
     // Coalesced: ResizeObserver and window resize both fire in BURSTS during a drag-resize or a
     // zoom, and every genuine resize reallocates (and clears) the backing store. One rAF per
@@ -891,7 +895,7 @@ export class SceneViewer {
   /** Damping + idle turntable. Called once per rendered frame, 3D or mono. */
   _tick() {
     const t = now();
-    const dt = this._lastTick ? Math.min((t - this._lastTick) / 1000, 0.1) : 0;
+    const dt = this._lastTick ? Math.min((t - this._lastTick) / 1000, MAX_DT_S) : 0;
     this._lastTick = t;
 
     if (this.idleSpin && !this._reduceMotion && t - this._lastInput > IDLE_DELAY_MS) {
@@ -899,7 +903,7 @@ export class SceneViewer {
     }
     // Critically-damped-ish approach. Instant snapping reads as jitter on a head-tracked
     // display, where the viewer is already moving relative to the content.
-    const k = dt > 0 ? 1 - Math.pow(0.001, dt) : 1;
+    const k = dt > 0 ? 1 - Math.pow(DAMP_BASE, dt) : 1;
     this._yaw += (this._targetYaw - this._yaw) * k;
     this._pitch += (this._targetPitch - this._pitch) * k;
     // Zoom eases on the same curve. Multiplicatively, because zoom is a ratio: approaching 2x
@@ -973,9 +977,9 @@ export class SceneViewer {
       // toward −y (down), so pitch must also ADD dy — subtracting it sends the face the wrong
       // way and reads as an inverted axis next to a correct one, which is worse than both being
       // inverted.
-      this._targetYaw += ((ev.clientX - lastX) / Math.max(box.width, 1)) * 180;
+      this._targetYaw += ((ev.clientX - lastX) / Math.max(box.width, 1)) * DRAG_DEG_PER_TILE;
       this._targetPitch = clamp(
-        this._targetPitch + ((ev.clientY - lastY) / Math.max(box.height, 1)) * 180,
+        this._targetPitch + ((ev.clientY - lastY) / Math.max(box.height, 1)) * DRAG_DEG_PER_TILE,
         this.pitchLimit[0],
         this.pitchLimit[1],
       );
@@ -1034,24 +1038,6 @@ export class SceneViewer {
   }
 }
 
-/**
- * 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.
-const WHEEL_LINE_PX = 33;
-const WHEEL_PAGE_PX = 400; // a "page" in deltaMode 2; rare, but it must not be unbounded
-const WHEEL_MAX_PX = 120; // per-event ceiling, against OS pointer acceleration spikes
-const ZOOM_PER_PX = 0.001;
-const ZOOM_MIN = 0.2;
-const ZOOM_MAX = 6;
-
 function now() {
   return typeof performance !== 'undefined' ? performance.now() : Date.now();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "Turn any HTML <canvas> into a glasses-free-3D window on a DisplayXR display, inside an ordinary web page. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",
@@ -43,6 +43,8 @@
     "js/inline3d-sog.js",
     "js/inline3d-splat-perf.js",
     "js/inline3d-splat-rig.js",
+    "js/inline3d-splat-playcanvas.js",
+    "js/inline3d-splat-shared.js",
     "js/inline3d-model.js",
     "index.d.ts",
     "three.d.ts",
@@ -74,7 +76,8 @@
   "license": "Apache-2.0",
   "peerDependencies": {
     "three": ">=0.150.0",
-    "@sparkjsdev/spark": ">=2.0.0"
+    "@sparkjsdev/spark": ">=2.0.0",
+    "playcanvas": ">=2.22.3 <3"
   },
   "peerDependenciesMeta": {
     "three": {
@@ -82,6 +85,9 @@
     },
     "@sparkjsdev/spark": {
       "optional": true
+    },
+    "playcanvas": {
+      "optional": true
     }
   },
   "publishConfig": {