@displayxr/inline3d 1.0.0 → 1.1.0

package/model.d.ts

@@ -0,0 +1,64 @@
+// Type definitions for @displayxr/inline3d/model.
+// EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
+
+import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
+
+export interface ModelOptions {
+  /** Metres of world the tile's height spans (default 0.24). */
+  virtualDisplayHeight?: number;
+  /** Precomputed subject bounds. Rarely needed for a mesh — Box3 is exact. */
+  frame?: SubjectBounds;
+  /** Degrees/second of turntable once idle (default 8). */
+  idleSpin?: number;
+  orbit?: boolean;
+  fit?: 'contain' | 'height' | 'cover' | 'none';
+  /** Fraction of the tile the subject may occupy (default 0.8) — width AND height. */
+  margin?: number;
+  /** Backstop on total depth, in display heights (default 4.0). Rarely binds. */
+  depthLimit?: number;
+  /**
+   * Fit the horizontal against the box's DIAGONAL (width and depth) rather than width alone,
+   * so a long subject still fits once the turntable turns it (default true).
+   */
+  fitSweep?: boolean;
+  /** Per-eye buffer scale; 0.5–0.7 is usually free (default 1). */
+  renderScale?: number;
+  feather?: number;
+  /** Built-in three-point lighting. Meshes arrive unlit; splats do not need this. */
+  environment?: 'studio' | 'none';
+  /** A PMREM-processed environment texture. Better than `environment` for metal; overrides it. */
+  envMap?: object;
+  /** Hand in the GLTFLoader class instead of resolving it from `three/addons/`. */
+  GLTFLoader?: unknown;
+  /** Element whose visibility gates the lazy create/close lifecycle. */
+  observe?: Element;
+}
+
+/** What {@link addModel} returns — the same shape as addSplat's handle. */
+export interface ModelHandle {
+  readonly viewer: SceneViewer;
+  /** The loaded glTF scene root; null until `ready` resolves. */
+  model: object | null;
+  /** Bounds used for framing; null until `ready` resolves. */
+  frame: SubjectBounds | null;
+  /** Resolves once the model has loaded and been framed; rejects if the load failed. */
+  readonly ready: Promise<ModelHandle>;
+
+  setPose(pose?: OrbitPose): void;
+  resetPose(): void;
+
+  remove(): void;
+  exclude(el: Element): void;
+  unexclude(el: Element): void;
+}
+
+/**
+ * Load a glTF/GLB into an inline-3D window. Safe to call with an unsupported wall — it renders a
+ * flat, orbitable view instead, so pages need no branch.
+ */
+export function addModel(
+  wall: object | null | undefined,
+  canvas: HTMLCanvasElement,
+  src: string,
+  opts?: ModelOptions,
+): ModelHandle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.0.0",
+  "version": "1.1.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",
@@ -14,14 +14,33 @@
     "./three": {
       "types": "./three.d.ts",
       "import": "./js/inline3d-three.js"
+    },
+    "./viewer": {
+      "types": "./viewer.d.ts",
+      "import": "./js/inline3d-viewer.js"
+    },
+    "./splat": {
+      "types": "./splat.d.ts",
+      "import": "./js/inline3d-splat.js"
+    },
+    "./model": {
+      "types": "./model.d.ts",
+      "import": "./js/inline3d-model.js"
     }
   },
   "sideEffects": false,
   "files": [
     "js/inline3d.js",
     "js/inline3d-three.js",
+    "js/inline3d-viewer.js",
+    "js/inline3d-splat.js",
+    "js/inline3d-model.js",
     "index.d.ts",
     "three.d.ts",
+    "viewer.d.ts",
+    "splat.d.ts",
+    "model.d.ts",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -45,11 +64,15 @@
   },
   "license": "Apache-2.0",
   "peerDependencies": {
-    "three": ">=0.150.0"
+    "three": ">=0.150.0",
+    "@sparkjsdev/spark": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "three": {
       "optional": true
+    },
+    "@sparkjsdev/spark": {
+      "optional": true
     }
   },
   "publishConfig": {

package/splat.d.ts

@@ -0,0 +1,91 @@
+// Type definitions for @displayxr/inline3d/splat.
+// EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
+
+import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
+
+export interface SplatOptions {
+  /** Metres of world the tile's height spans (default 0.24). */
+  virtualDisplayHeight?: number;
+  /**
+   * Precomputed subject bounds. Strongly preferred — bake these at conversion time, where the
+   * full opacity-weighted subject detection is cheap, instead of paying for a weaker
+   * approximation in the page.
+   */
+  frame?: SubjectBounds;
+  /** Apply the 180° X flip most splat exports need (default true). */
+  flipY?: boolean;
+  /** Degrees/second of turntable once idle (default 8). */
+  idleSpin?: number;
+  orbit?: boolean;
+  fit?: 'contain' | 'height' | 'cover' | 'none';
+  /** Fraction of the tile the subject may occupy (default 0.8) — width AND height. */
+  margin?: number;
+  /** Backstop on total depth, in display heights (default 4.0). Rarely binds. */
+  depthLimit?: number;
+  /**
+   * Fit the horizontal against the box's DIAGONAL (width and depth) rather than width alone,
+   * so a long subject still fits once the turntable turns it (default true).
+   */
+  fitSweep?: boolean;
+  /** Per-eye buffer scale; 0.5–0.7 is usually free (default 1). */
+  renderScale?: number;
+  feather?: number;
+  /** Minimum ms between splat sorts. Defaults to 16 so both eyes share one sort per frame. */
+  sortIntervalMs?: number;
+  /**
+   * Disambiguates .splat from .ksplat when passing BYTES — content-sniffing cannot separate
+   * those two. Unnecessary for .sog/.ply/.spz, which are identifiable by magic number.
+   */
+  fileName?: string;
+  /**
+   * Container format, when passing bytes. Usually unnecessary — the magic number is sniffed —
+   * but note Spark's names are not the file extensions: a `.sog` is `pcsogszip`.
+   */
+  fileType?: 'ply' | 'spz' | 'splat' | 'ksplat' | 'pcsogs' | 'pcsogszip' | 'rad';
+  /** Element whose visibility gates the lazy create/close lifecycle. */
+  observe?: Element;
+}
+
+/** What {@link addSplat} returns: a TileHandle plus the objects behind it. */
+export interface SplatHandle {
+  readonly viewer: SceneViewer;
+  /** Spark's SplatMesh. */
+  readonly mesh: object;
+  /** Spark's SparkRenderer. */
+  readonly spark: object;
+  /** Bounds actually used for framing; null until `ready` resolves. */
+  frame: SubjectBounds | 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;
+
+  /** Close this window and release its GPU resources. */
+  remove(): void;
+  /** Mark a 2D element painted over this window so the weave leaves it crisp. */
+  exclude(el: Element): void;
+  unexclude(el: Element): void;
+}
+
+/**
+ * Load a splat into an inline-3D window. Safe to call with an unsupported wall — it renders a
+ * flat, orbitable view instead, so pages need no branch.
+ */
+export function addSplat(
+  wall: object | null | undefined,
+  canvas: HTMLCanvasElement,
+  /**
+   * A URL, or the bytes themselves.
+   *
+   * Prefer BYTES for anything generated rather than fetched. Spark reads a splat's format from
+   * the URL path, so an object URL from URL.createObjectURL() — which has no extension — fails
+   * with "Unknown file type" before it fetches anything, and that reads like a corrupt asset
+   * rather than a missing hint. Given bytes, Spark sniffs the magic number instead.
+   */
+  src: string | Blob | ArrayBuffer,
+  opts?: SplatOptions,
+): SplatHandle;
+
+/** Robust model-space bounds of a loaded SplatMesh, lifted through its own matrix. */
+export function measureSplatBounds(mesh: object, three?: object): SubjectBounds | null;

package/viewer.d.ts

@@ -0,0 +1,94 @@
+// Type definitions for @displayxr/inline3d/viewer.
+// EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
+
+/** Model-space bounds of the subject a viewer frames on. */
+export interface SubjectBounds {
+  center: number[];
+  extent: number[];
+}
+
+export interface SceneViewerOptions {
+  /** Metres of world the tile's HEIGHT spans. Pass the same value to addScene. */
+  virtualDisplayHeight?: number;
+  /**
+   * How `fitTo` sizes the subject. `contain` caps BOTH width and height at `margin` of the tile.
+   * `height` pins height to `margin` and only guards against running off the sides, giving a
+   * consistent apparent size across a catalogue.
+   */
+  fit?: 'contain' | 'height' | 'cover' | 'none';
+  /** Fraction of the tile the subject may occupy (default 0.8). */
+  margin?: number;
+  /** Backstop on total subject depth, in display heights (default 4.0). Rarely binds. */
+  depthLimit?: number;
+  /**
+   * Fit the horizontal against the box's DIAGONAL (width and depth) rather than width alone,
+   * so a long subject still fits once the turntable turns it (default true).
+   */
+  fitSweep?: boolean;
+  /** Drag to spin, wheel/pinch to zoom (default true). */
+  orbit?: boolean;
+  /** Degrees/second of turntable once idle. Ignored under prefers-reduced-motion. */
+  idleSpin?: number;
+  /** Per-eye buffer scale; 0.5–0.7 is usually free after the interlace (default 1). */
+  renderScale?: number;
+  /** Edge fade in buffer px (needs EdgeFeather from ./three). */
+  feather?: number;
+  /** Pitch clamp in degrees (default [-60, 60]). */
+  pitchLimit?: number[];
+}
+
+export interface OrbitPose {
+  yaw?: number;
+  pitch?: number;
+  zoom?: number;
+}
+
+/**
+ * Robust model-space bounds from a flat [x,y,z,…] array. The cheap path; prefer bounds computed
+ * at conversion time where you have them.
+ *
+ * Percentiles REJECT outliers, they do not measure extent: `lo`/`hi` bound a rejection window
+ * `expand` core-extents wide, and the returned extent is the true min/max inside it. Returning
+ * the trimmed box itself under-reports a dense subject by 10-15% — a uniform cube measures 0.899
+ * of its real size — which a fit then turns into a subject overflowing its tile. `expand: 0`
+ * restores the old percentile-only box.
+ */
+export function boundsFromPositions(
+  xyz: ArrayLike<number>,
+  opts?: { lo?: number; hi?: number; expand?: number },
+): SubjectBounds | null;
+
+/** A single framed object in an inline-3D window: SBS loop, framing, orbit, mono fallback. */
+export declare class SceneViewer {
+  constructor(THREE: object, canvas: HTMLCanvasElement, opts?: SceneViewerOptions);
+
+  readonly canvas: HTMLCanvasElement;
+  /** Put your three.js object in here. */
+  readonly content: object;
+  readonly scene: object;
+  readonly renderer: object;
+  readonly monoCamera: object;
+  /** True while the side-by-side backing store is in use. */
+  readonly is3D: boolean;
+
+  /** Centre the subject on the zero-disparity plane and scale it to the tile. */
+  fitTo(
+    center: number[] | { x: number; y: number; z: number },
+    extent: number[] | { x: number; y: number; z: number },
+  ): void;
+
+  setPose(pose?: OrbitPose): void;
+  resetPose(): void;
+
+  /** Pass straight to `wall.addScene(canvas, viewer.onFrame, …)`. Pre-bound. */
+  onFrame(views: readonly XRView[], layer: object): void;
+
+  /** Supply the ./three glue so the 3D path can build its eye camera. Returns `this`. */
+  useEyeCamera(EyeCameraClass: unknown, EdgeFeatherClass?: unknown): this;
+
+  /** Flat single-camera loop for browsers without inline-3D. */
+  startMono(): void;
+  stopMono(): void;
+
+  dispose(): void;
+}