@displayxr/inline3d 1.6.1 → 1.7.0

package/js/inline3d-viewer.js

@@ -52,6 +52,15 @@ 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;
+
 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
 // matrix and every vertex lands undefined. Reject at the setter instead.
@@ -226,6 +235,23 @@ export class SceneViewer {
 
     this._fitScale = 1;
     this._zoom = 1;
+    // FOCUS — the point everything turns about, eased. `_focus` is where it is now, `_target`
+    // where it is going; `_orbitCentre` is where the pivot sits afterwards, and it is what
+    // separates the two rigs: a DISPLAY rig brings the focused point to the middle of the tile
+    // (centre 0), a CAMERA rig leaves the capture exactly where it was placed and only moves
+    // what the rotation turns about (centre = the focus point). See setFocus().
+    // Plain triples, not THREE.Vector3: this module takes its THREE by injection and is tested
+    // against a stub, so every three.js type it reaches for is one more thing a consumer has to
+    // supply. Three numbers need no library.
+    this._focus = { x: 0, y: 0, z: 0 };
+    this._targetFocus = { x: 0, y: 0, z: 0 };
+    this._orbitCentre = { x: 0, y: 0, z: 0 };
+    this._focusRecentres = true;
+    this._focusSettled = true;
+    /** Called after every focus ease step, with the live focus. Set by ./splat. */
+    this.onFocusChange = null;
+    /** Called at the end of every _tick, after the transform is applied. */
+    this.onTick = null;
     this._targetZoom = 1;
     // Author-driven slide along the depth axis, display metres, +z toward the viewer. Applied
     // by _applyTransform, PRESERVED by fitTo, cleared by resetPose. Default 0 means every page
@@ -307,7 +333,10 @@ export class SceneViewer {
     const c = Array.isArray(center) ? center : [center.x, center.y, center.z];
     const e = Array.isArray(extent) ? extent : [extent.x, extent.y, extent.z];
 
-    this._centering.position.set(-c[0], -c[1], -c[2]);
+    // Through the focus, not around it: framing a subject IS pointing the viewer at its centre,
+    // and keeping the two in one place is what stops an orbit turning about somewhere the fit
+    // has since moved away from. Snapped — a refit is not a gesture.
+    this.setFocus(c, { snap: true });
     // Recorded for getSubjectBounds(). Model units; the fit scale is applied at read time so a
     // later zoom or orbit needs no re-measure.
     this._subjectHalf = [Math.abs(e[0]) / 2, Math.abs(e[1]) / 2, Math.abs(e[2]) / 2];
@@ -480,6 +509,57 @@ export class SceneViewer {
     this._applyTransform();
   }
 
+  /**
+   * Point the viewer at something — the one point that is simultaneously the orbit centre, the
+   * pivot plane and (on a camera rig) the convergence distance.
+   *
+   * Those three are the same thing and saying so is the point of this method. A viewer that lets
+   * them drift apart orbits about one place, converges at another and rotates the picture around
+   * a third, which is how "the scene swings away when I turn it" happens.
+   *
+   * The two rigs differ in what MOVES, and only in that:
+   *
+   * - **`recentre: true`** (a display rig, the default) — the focused point is brought to the
+   *   middle of the tile and onto the zero-disparity plane. That is what a portal does: you
+   *   chose a subject, so the subject is what the window shows.
+   * - **`recentre: false`** (a camera rig) — the capture stays exactly where it was placed and
+   *   only the rotation centre moves. Translating a camera-rig scene would move the viewpoint,
+   *   and the neutral view IS the photograph; nothing may move it.
+   *
+   * Eased at {@link FOCUS_EASE} per frame unless `snap`.
+   *
+   * @param {{x:number,y:number,z:number}|number[]|null} point  in CONTENT space (the space your
+   *        object sits in, i.e. `viewer.content`'s local space). Null resets to the origin.
+   * @param {object} [opts]
+   * @param {boolean} [opts.snap=false]  arrive immediately.
+   * @param {boolean} [opts.recentre]  see above. Sticky: set once when the rig is chosen.
+   */
+  setFocus(point, { snap = false, recentre } = {}) {
+    if (recentre !== undefined) this._focusRecentres = !!recentre;
+    const p = point == null ? [0, 0, 0] : Array.isArray(point) ? point : [point.x, point.y, point.z];
+    this._targetFocus = { x: finite(p[0], 0), y: finite(p[1], 0), z: finite(p[2], 0) };
+    this._focusSettled = false;
+    if (snap) {
+      this._focus = { ...this._targetFocus };
+      this._focusSettled = true;
+      this._applyFocus();
+      this._applyTransform();
+      this.onFocusChange?.(this._focus);
+    }
+    return this;
+  }
+
+  /**
+   * Where the viewer is pointed, in content space.
+   *
+   * @param {object} [opts]
+   * @param {boolean} [opts.target=false]  the value being eased TOWARD, as with getPose().
+   */
+  getFocus({ target = false } = {}) {
+    const v = target ? this._targetFocus : this._focus;
+    return { x: v.x, y: v.y, z: v.z };
+  }
+
   /** Return to the framed default pose, depth slide included. */
   resetPose() {
     this.setPose({ yaw: 0, pitch: 0, zoom: 1, depthOffset: 0 });
@@ -757,7 +837,13 @@ export class SceneViewer {
     // The depth slide lives here, not in fitTo, so it survives a refit and cannot be left
     // stale by a code path that forgets it. x/y are never written: the fit centres the subject
     // on the tile and sliding it sideways is a scene concern, not a viewer one.
-    this._pivot.position.z = this._depthOffset;
+    // The orbit centre is where the pivot SITS; the depth slide rides on top of it. Both are
+    // zero for the ordinary framed subject, so this is identity for every existing page.
+    this._pivot.position.set(
+      this._orbitCentre.x,
+      this._orbitCentre.y,
+      this._orbitCentre.z + this._depthOffset,
+    );
     // Order 'XYZ' == R = Rx(pitch) · Ry(yaw), and the order is the whole point.
     //
     // Yaw must act in the subject's OWN frame (spin it on its axis); pitch must act in the
@@ -824,7 +910,44 @@ export class SceneViewer {
     } else {
       this._zoom = this._targetZoom;
     }
+    this._easeFocus();
     this._applyTransform();
+    this.onTick?.();
+  }
+
+  /**
+   * Walk the live focus toward its target. A no-op — not even a vector compare — for every
+   * viewer that never sets one.
+   */
+  _easeFocus() {
+    if (this._focusSettled) return;
+    const f = this._focus;
+    const t = this._targetFocus;
+    const dx = t.x - f.x;
+    const dy = t.y - f.y;
+    const dz = t.z - f.z;
+    if (dx * dx + dy * dy + dz * dz < 1e-10) {
+      f.x = t.x;
+      f.y = t.y;
+      f.z = t.z;
+      this._focusSettled = true;
+    } else {
+      f.x += dx * FOCUS_EASE;
+      f.y += dy * FOCUS_EASE;
+      f.z += dz * FOCUS_EASE;
+    }
+    this._applyFocus();
+    this.onFocusChange?.(f);
+  }
+
+  /** Write the current focus into the scene graph. */
+  _applyFocus() {
+    const f = this._focus;
+    this._centering.position.set(-f.x, -f.y, -f.z);
+    const c = this._orbitCentre;
+    c.x = this._focusRecentres ? 0 : f.x;
+    c.y = this._focusRecentres ? 0 : f.y;
+    c.z = this._focusRecentres ? 0 : f.z;
   }
 
   _bindOrbit() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.6.1",
+  "version": "1.7.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",
@@ -40,6 +40,9 @@
     "js/inline3d-three.js",
     "js/inline3d-viewer.js",
     "js/inline3d-splat.js",
+    "js/inline3d-sog.js",
+    "js/inline3d-splat-perf.js",
+    "js/inline3d-splat-rig.js",
     "js/inline3d-model.js",
     "index.d.ts",
     "three.d.ts",

package/splat.d.ts

@@ -3,6 +3,114 @@
 
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
 
+/**
+ * The knobs behind `SplatOptions.perf`. Every one is a Spark 2.1.0 setting except `alphaRadius`,
+ * which is a patch to Spark's own vertex shader (there is no option for it). Bit-exact vs lossy,
+ * and the defaults each one overrides, are tabled in `js/inline3d-splat-perf.js`.
+ */
+export interface SplatPerfOptions {
+  /** Shrink each quad to the radius where its alpha reaches `alphaFloor`. Bit-exact by default. */
+  alphaRadius?: boolean;
+  /**
+   * The alpha each splat's tail may be cut at, PER SPLAT. Defaults to `minAlpha`, which is the
+   * bit-exact cut; above it this is a lossy crop that scales with each splat's own opacity.
+   */
+  alphaFloor?: number;
+  /** Drop splats and fragments under this alpha. Spark's default is `0.5/255`. */
+  minAlpha?: number;
+  /** Quad extent in σ, globally. Spark's default is `Math.sqrt(8)`. */
+  maxStdDev?: number;
+  /** Drop splats smaller than this, in pixels. Spark's default is 0. */
+  minPixelRadius?: number;
+  /** Clamp on quad size in pixels — note it SQUASHES rather than crops. Default 512. */
+  maxPixelRadius?: number;
+  /** 1 = Gaussian falloff, 0 = flat. Not a perf knob; 0 costs MORE. */
+  falloff?: number;
+  /** Build LOD data at load, so Spark can substitute merged splats against a budget. */
+  lod?: boolean | 'quality';
+  /** LOD budget multiplier (needs `lod`). */
+  lodSplatScale?: number;
+  /** Absolute LOD budget in splats (needs `lod`). */
+  lodSplatCount?: number;
+  /** Minimum on-screen splat size multiplier (needs `lod`); up to ~5 is often invisible. */
+  lodRenderScale?: number;
+}
+
+/** Camera intrinsics for ONE eye, in pixels, OpenCV convention. */
+export interface SogIntrinsics {
+  fx: number;
+  fy: number;
+  cx: number;
+  cy: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * The `camera` block of a `.sog`'s `meta.json` (v2), plus the fields this SDK derives from it.
+ * v2 is a superset of v1: everything but `convention` is optional, `intrinsics` included.
+ */
+export interface SogCamera {
+  convention: 'opencv';
+  /** Which rig the asset asks for. Null when the block does not say. */
+  rig: 'camera' | 'display' | null;
+  rest: { position: number[]; rotation: number[] };
+  /** Null when the block carried none, or none that were usable — estimate one instead. */
+  intrinsics: SogIntrinsics | null;
+  stereo: { baseline_m: number } | null;
+  /**
+   * The point that is simultaneously the orbit centre, the pivot plane and the convergence
+   * distance. In the splat's own space. The three distances are advisory.
+   */
+  focus: {
+    point: number[];
+    subject_m: number | null;
+    near_m: number | null;
+    far_m: number | null;
+    source: string | null;
+  } | null;
+  /** The camera rig's ABSOLUTE scalars. Null when unstated. */
+  dxr: { ipdFactor: number | null; parallaxFactor: number | null };
+  /** Full vertical angle of the capture in RADIANS; null without intrinsics. */
+  verticalFov: number | null;
+  /** Principal point off the frame centre, fraction of the frame, y UP; null without intrinsics. */
+  principalOffset: { x: number; y: number } | null;
+}
+
+/**
+ * What the waterfall resolved, with the step that produced each value beside it — which is the
+ * point of it. `intrinsicsSource: 'fallback-28mm'` on an asset that looks zoomed out says more
+ * than any amount of staring at the picture.
+ */
+export interface ResolvedRig {
+  type: 'camera' | 'display';
+  typeSource: 'caller' | 'block' | 'block-present' | 'default';
+  rest: { position: number[]; rotation: number[] };
+  intrinsics: SogIntrinsics;
+  intrinsicsSource: 'block' | 'caller' | 'estimated' | 'fallback-28mm';
+  /** 35 mm-equivalent focal of whatever lens was resolved. */
+  focalEqMm: number;
+  /** The live focus, in the splat's own space. */
+  focus: number[];
+  focusSource:
+    | 'caller'
+    | 'caller-convergence'
+    | 'block'
+    | 'median-disparity'
+    | 'default'
+    | 'picked'
+    | 'set';
+  /** What Space returns to. */
+  focusDefault: number[];
+  focusDefaultSource: string;
+  /** The block's advisory distances, when it carried any. */
+  focusDistances: { subject_m: number | null; near_m: number | null; far_m: number | null } | null;
+  /** Focus distance along the rest camera's view axis — the zero-disparity PLANE. */
+  convergence: number;
+  ipdFactor: number;
+  parallaxFactor: number;
+}
+
 export interface SplatOptions {
   /** Metres of world the tile's height spans (default 0.24). */
   virtualDisplayHeight?: number;
@@ -32,6 +140,41 @@ export interface SplatOptions {
   feather?: number;
   /** Minimum ms between splat sorts. Defaults to 16 so both eyes share one sort per frame. */
   sortIntervalMs?: number;
+  /**
+   * Cut overdraw. UNSET changes nothing — every Spark default stays where Spark put it, so an
+   * existing page's pixels do not move.
+   *
+   * `'exact'` is the bit-exact pair — each quad shrunk to where its own alpha reaches 1/255
+   * (those fragments were already being discarded), plus the 1/255 peak-opacity cull. It buys
+   * little on a mostly-opaque capture, which is what a lifted photograph is. `'balanced'` (or
+   * `true`, −5…−20 % measured) and `'aggressive'` (−22 %) tighten the quad extent instead, which
+   * is the axis that actually pays on the web; both move pixels.
+   */
+  perf?: true | 'exact' | 'balanced' | 'aggressive' | SplatPerfOptions;
+  /**
+   * Which view rig. `'auto'` (the default) reads it off the ASSET — a `.sog` carrying a `camera`
+   * block was lifted from a photograph and gets a camera rig that conserves the recording
+   * camera; anything else is an object and gets the display rig with the auto-frame. Only
+   * detectable when `src` is BYTES.
+   */
+  rig?: 'auto' | 'display' | 'camera';
+  /** Camera rig only: the distance in world metres that sits ON the glass. */
+  convergence?: number;
+  /**
+   * The point to converge on and orbit about, in the splat's own space — the highest step of the
+   * focus waterfall. Wins over `convergence`, which is the straight-ahead shorthand for it.
+   */
+  focus?: number[];
+  /** Override the lens, when the asset carries none and the estimate is wrong. */
+  intrinsics?: SogIntrinsics;
+  /** Camera rig scalars. ABSOLUTE, never normalised against the convergence. */
+  ipdFactor?: number;
+  parallaxFactor?: number;
+  /**
+   * Bind double-click (focus what was clicked) and Space (back to the resolved focus). Default
+   * true; pass false when the page owns those gestures itself.
+   */
+  focusInput?: boolean;
   /**
    * Disambiguates .splat from .ksplat when passing BYTES — content-sniffing cannot separate
    * those two. Unnecessary for .sog/.ply/.spz, which are identifiable by magic number.
@@ -55,11 +198,32 @@ export interface SplatHandle {
   readonly spark: object;
   /** Bounds actually used for framing; null until `ready` resolves. */
   frame: SubjectBounds | null;
+  /**
+   * The `.sog`'s `camera` block — the recording camera, when the asset carries one. Null for a
+   * URL source, a non-`.sog`, or an object splat (which is most of them).
+   */
+  camera: SogCamera | null;
+  /** What the waterfall resolved, sources included. Null until `ready` resolves. */
+  rig: ResolvedRig | null;
+  /** The view-rig descriptor sent to the runtime, on the camera path. */
+  viewRig?: object;
+  /** What `perf` actually applied, or null. */
+  perf: object | null;
   /** Resolves once the asset has loaded and been framed; rejects if the load failed. */
   readonly ready: Promise<SplatHandle>;
 
   setPose(pose?: OrbitPose): void;
   resetPose(): void;
+  /**
+   * Point the window at something, in the SPLAT's own space (the space the `camera` block's
+   * `focus.point` is in). Null returns to whatever the waterfall resolved. Eased unless `snap`.
+   */
+  setFocus(
+    point: number[] | { x: number; y: number; z: number } | null,
+    opts?: { snap?: boolean },
+  ): SplatHandle;
+  /** What is under a point on the canvas, in the splat's own space — the double-click's raycast. */
+  pick(clientX: number, clientY: number): number[] | null;
 
   /** Close this window and release its GPU resources. */
   remove(): void;

package/viewer.d.ts

@@ -105,6 +105,22 @@ export declare class SceneViewer {
 
   /** Snap the pose. Writes the eased value and its target together. */
   setPose(pose?: OrbitPose): void;
+  /**
+   * Point the viewer at something: the orbit centre, the pivot plane and (on a camera rig) the
+   * convergence distance are ONE point, and this is it. `recentre: true` (a display rig) brings
+   * that point to the middle of the tile; `recentre: false` (a camera rig) leaves the capture
+   * where it was placed and moves only the rotation centre. Eased 0.18/frame unless `snap`.
+   */
+  setFocus(
+    point: { x: number; y: number; z: number } | number[] | null,
+    opts?: { snap?: boolean; recentre?: boolean },
+  ): SceneViewer;
+  /** Where the viewer is pointed, in content space. */
+  getFocus(opts?: { target?: boolean }): { x: number; y: number; z: number };
+  /** Called after every focus ease step, with the live focus. */
+  onFocusChange: ((focus: { x: number; y: number; z: number }) => void) | null;
+  /** Called at the end of every tick, after the transform is applied. */
+  onTick: (() => void) | null;
 
   /**
    * The pose as it is right now. `target: true` reports what it is easing TOWARD, which differs