@displayxr/inline3d 1.6.1 → 1.7.1

package/CHANGELOG.md

@@ -5,6 +5,148 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.7.1 — 2026-09-20
+
+Touches the **preview tier** (`./model`) only, and fixes exactly one thing: under a bundler, a
+compressed glTF never loaded at all. Uncompressed assets are unaffected, and so is every page that
+loads compressed ones through a bare importmap — same pixels, same timing. If your page builds with
+webpack / Turbopack / Vite / rollup and loads a Draco-, KTX2- or meshopt-compressed model, the tile
+that used to stay empty with a rejected `handle.ready` now renders the product.
+
+### Fixed
+
+- **`addModel` could not load ANY compressed asset under a bundler — all three decoders**
+  (preview tier). The decoders were resolved with `await import(spec.module)`, the specifier read
+  out of the `DECODERS` table — an *expression*, which no bundler can follow. The build printed
+
+  ```
+  Critical dependency: the request of a dependency is an expression
+  ```
+
+  and shipped a stub that throws `Cannot find module 'three/addons/…'` at runtime, which `addModel`
+  then reported honestly as a module-resolution failure in its own decoder error. Draco, KTX2/Basis
+  **and** meshopt all went through that one call, so the blast radius was the whole compressed path
+  — and a catalogue GLB out of a real pipeline is nearly always compressed, which is precisely the
+  case `/model` exists for. Each decoder now has a literal `import()` of its own
+  (`load: () => import('three/addons/loaders/DRACOLoader.js')`, and so on): that is what a build
+  tool can analyse, and it resolves unchanged under the `"three/addons/"` importmap prefix the
+  samples use.
+
+  It survived four releases because neither path that was exercised has the fault — `samples/` runs
+  on a bare importmap, which resolves specifiers at runtime and does not care, and the test suite is
+  deliberately dependency-free, so it never imported a decoder at all. The guard added with this fix
+  is therefore a source-level one: it reads `js/` the way a bundler does and fails if any `import()`
+  is handed a computed specifier again.
+
+  Nothing else moved. Injection (`{ DRACOLoader }`, `{ KTX2Loader }`, `{ meshoptDecoder }`, a class
+  or a ready instance you configured yourself), the shared ref-counted decoder cache, `decoderPath`
+  and the serve-the-decoder-files-yourself requirement are all as they were, and a decoder is still
+  imported only for an asset that declares its extension — bundlers now code-split each one into its
+  own chunk, so an uncompressed GLB downloads none of them.
+
+  Verified in Chrome against a Next.js 15 / webpack app loading an `EXT_meshopt_compression` GLB:
+  before, the build warning above plus `Cannot find module
+  'three/addons/libs/meshopt_decoder.module.js'` and an empty stage; after, no warning, the meshopt
+  decoder arriving as its own chunk, and the model on screen.
+
+## 1.7.0 — 2026-09-19
+
+Touches the **preview tier** (`./splat`) only, and additively: `addSplat` with no new options
+renders exactly as it did in 1.6.1 — every Spark default stays where Spark put it and the display
+rig with its auto-frame is still what an asset without a `camera` block gets.
+
+### Added
+
+- **`addSplat({ perf })` — cut a splat's overdraw** (preview tier). A splat scene's cost is the
+  per-fragment composite, and splat COUNT is the weakest axis on it: decimating the reference
+  1.18M-gaussian capture to 25 % breaks it visibly while removing less cost than these settings,
+  which remove none of the picture. Two presets (`'balanced'`, `'aggressive'`) or an object of your
+  own over Spark's `minAlpha` / `maxStdDev` / `minPixelRadius` / `maxPixelRadius` / `falloff` and
+  its LOD budget, plus two of this SDK's own:
+  - **`alphaRadius`** shrinks each splat's quad to the radius where its own alpha reaches
+    `minAlpha`. Spark's fragment shader already discards everything past that radius, so this
+    removes work and not pixels — **bit-exact**, measured: 457 of 3,686,400 channel bytes differ
+    at 1280×720, every one of them by exactly 1. Spark 2.1.0 has no option for it (`maxStdDev` is
+    one global uniform), so the SDK patches Spark's splat vertex shader through its supported
+    `vertexShader` surface, rewriting Spark's OWN source off the live material rather than shipping
+    a copy — a Spark upgrade brings its shader fixes along, and if the lines stop matching the
+    patch declines with one warning and everything still renders.
+  - **`alphaFloor`** moves that cut up: each tail is dropped where IT reaches the floor rather than
+    where an 8-bit framebuffer stops representing it — the per-splat version of turning
+    `maxStdDev` down.
+
+  Two results from measuring it that are worth more than the options themselves, because both are
+  the opposite of the obvious move (M1 Pro, Chrome/ANGLE-Metal, GPU timer queries, configs
+  interleaved frame by frame):
+  - **Decimating the asset buys nothing.** 50 % and 25 % decimations measured within noise of the
+    full 1.18M-gaussian scene. Decimation drops the small gaussians and the few huge ones that
+    cover the frame survive it. A decimated `.sog` is a download win, not a render-cost win.
+  - **The bit-exact shrink buys little on a lifted photograph**, because 86 % of its gaussians are
+    near-opaque and an opaque splat's own 1/255 radius is already wider than the σ Spark draws it
+    at. It is exact and it stays — the scene it was built for is large low-alpha haze — but the
+    preset that pays on the web (`'balanced'`, −5…−20 %) tightens the quad extent instead.
+
+  `handle.perf` reports what was applied, and `applySplatPerf(spark, perf)` is exported for pages
+  that build their own `SparkRenderer` — the knobs are live, so a quality menu can call it at any
+  time. Measured numbers, and which knob is worth which pixels, are in
+  [docs/authoring-inline-3d.md](docs/authoring-inline-3d.md#gaussian-splats-performance-and-the-camera-block).
+
+- **A `.sog`'s `camera` block now picks the view rig, and a WATERFALL fills in the rest**
+  (preview tier). A splat viewer needs BOTH rigs and the same call site loads both kinds of asset
+  — a product hero wants the display rig and its auto-frame, while a photograph lifted into 3D
+  wants the camera it was taken with. Nothing in the page can tell them apart; the file can.
+  `addSplat` reads the `camera` block out of the `.sog` (a PKZip — ~40 bytes of central directory,
+  never the webp planes, and only on the BYTES path) and resolves three questions from it:
+
+  | | 1st | 2nd | 3rd | last |
+  |---|---|---|---|---|
+  | **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 ahead |
+
+  Each resolved value carries the step that produced it (`handle.rig.focusSource`,
+  `intrinsicsSource`, `typeSource`), because a number from a lower step is not a wrong number, it
+  is a wrong SOURCE, and that is invisible in the picture.
+
+  The block is now a **v2 superset**: `rig`, `focus` (one point that is the orbit centre, the pivot
+  plane AND the convergence) and `dxr` (the camera rig's absolute scalars) join it, `intrinsics`
+  becomes optional, and a v1 block still reads. `rig: "display"` beside a `rest` is meaningful —
+  *a display rig, opened at this viewpoint*.
+
+  **Estimating the lens** works because a capture's gaussians only exist where its camera could see
+  them: P1/P99 of `x/z` and `y/z` about the rest camera ARE the frustum that made it, principal
+  point included. Measured against a capture whose true half-tangents are ±0.857 and ±0.482:
+  0.8635 and 0.4827, +0.75 % and +0.12 %. The implied 35 mm-equivalent focal is gated to
+  [14, 85] mm, outside which the cloud is describing something that is not a camera. It matters
+  because a splat rendered through the wrong focal is drawn at the wrong SIZE and nothing else —
+  no artefact, just a picture that feels zoomed out.
+
+  **Estimating the focus** is the median of 1/z, inverted — not of z. On the reference capture that
+  is 2.17 m against the gallery's own 2.14 m; the centre of the measured bounds, which this
+  replaced, was 39.8 m, because an open scene's percentile bounds are 128 m wide.
+
+  On the camera path the subject is not reframed, the turntable is off, the mono camera is posed
+  and lensed as the capture, and the rig is **declared** with `cameraRigFromCamera` — the off-axis
+  projection stays in the runtime.
+
+- **Pointing the window: double-click, Space and `handle.setFocus(point|null)`** (preview tier).
+  The focus is one point — the orbit centre, the pivot plane and the convergence — and it is now
+  something a viewer can move. Double-click focuses what was clicked (Spark's own
+  `SplatMesh.raycast`, ~57 ms over 1.18M gaussians, with a nearest-gaussian-to-the-ray fallback
+  documented as the approximation it is); Space returns to the resolved value; both ease at 0.18
+  per frame, and while the ease runs a camera rig re-declares its convergence every frame. What
+  moves depends on the rig and only on that: a camera rig moves the rotation centre and leaves the
+  capture where it was placed, a display rig brings the focused point to the middle of the tile.
+  `focusInput: false` turns the gestures off for a page that owns them itself, and
+  `handle.pick(x, y)` exposes the raycast.
+
+  New on the handle: **`handle.camera`** (the raw block), **`handle.rig`** (the resolved waterfall),
+  `handle.viewRig`, `handle.perf`, `handle.setFocus`, `handle.pick`. New exports from `./splat`:
+  `readSogCamera(bytes)`, `readSogMeta(bytes)`, `resolveRig`, `applySplatPerf`,
+  `SPLAT_PERF_PRESETS`. **`SceneViewer` gains `setFocus` / `getFocus` / `onFocusChange` / `onTick`**
+  (`./viewer`), and `fitTo` now goes through the focus, so a refit cannot leave the orbit turning
+  about somewhere the framing has moved away from.
+
 ## 1.6.1 — 2026-09-09
 
 Touches the **core tier** (`.`) with a behaviour fix only — no API changes — and the **preview tier**

package/README.md

@@ -113,6 +113,7 @@ js/
   inline3d-viewer.js  experimental: SceneViewer — framing, orbit, idle turntable, mono fallback,
                       and the placement readback (getSubjectBounds / getPose / depthOffset)
   inline3d-splat.js   experimental: addSplat() — a Gaussian splat window via Spark
+                      (`perf` cuts overdraw; a `.sog`'s `camera` block picks the view rig)
   inline3d-model.js   experimental: addModel() — a glTF/GLB window; wires Draco / meshopt / KTX2
                       from what the asset declares (you serve the decoder files — see the guide)
 docs/

package/js/inline3d-model.js

@@ -63,12 +63,23 @@ async function resolveLoader(injected) {
  * One entry per decoder: the glTF extension that demands it, where its class lives, where its
  * runtime files live, and which option overrides each. The error messages are generated from
  * this table, so a message can never name an option that does not exist.
+ *
+ * `load` is a thunk around a **literal** `import()` and `module` is the same specifier as a
+ * string, and the duplication is deliberate. A bundler can only follow an import whose specifier
+ * is written out at the call site: `import(spec.module)` — reading the string out of this table —
+ * is an *expression*, which webpack/Turbopack/rollup cannot resolve, so they emit
+ * "Critical dependency: the request of a dependency is an expression" at build time and a stub
+ * that throws `Cannot find module …` at runtime. That made EVERY compressed asset unloadable for
+ * every bundler consumer, while the bare-importmap path (which resolves at runtime and does not
+ * care) kept working — so it survived the samples. The string stays because the error messages
+ * quote it; the thunk is what actually loads.
  */
 const DECODERS = {
   draco: {
     ext: 'KHR_draco_mesh_compression',
     label: 'Draco mesh compression',
     module: 'three/addons/loaders/DRACOLoader.js',
+    load: () => import('three/addons/loaders/DRACOLoader.js'),
     exportName: 'DRACOLoader',
     option: 'DRACOLoader',
     pathKey: 'draco',
@@ -79,6 +90,7 @@ const DECODERS = {
     ext: 'KHR_texture_basisu',
     label: 'KTX2 / Basis Universal textures',
     module: 'three/addons/loaders/KTX2Loader.js',
+    load: () => import('three/addons/loaders/KTX2Loader.js'),
     exportName: 'KTX2Loader',
     option: 'KTX2Loader',
     pathKey: 'basis',
@@ -89,6 +101,7 @@ const DECODERS = {
     ext: 'EXT_meshopt_compression',
     label: 'meshopt compression',
     module: 'three/addons/libs/meshopt_decoder.module.js',
+    load: () => import('three/addons/libs/meshopt_decoder.module.js'),
     exportName: 'MeshoptDecoder',
     option: 'meshoptDecoder',
     pathKey: null, // pure JS + inlined wasm; nothing for the page to serve
@@ -159,7 +172,10 @@ async function buildDecoder(kind, paths, injected) {
   const spec = DECODERS[kind];
   let thing = injected;
   if (!thing) {
-    const mod = await import(spec.module);
+    // spec.load(), never `import(spec.module)` — see the note on DECODERS. One literal specifier
+    // per kind is what makes this analysable, and a bundler then code-splits each decoder into
+    // its own chunk, still fetched only for an asset that declares the extension.
+    const mod = await spec.load();
     thing = mod[spec.exportName];
     if (!thing) throw new Error(`${spec.module} has no export "${spec.exportName}"`);
   }

package/js/inline3d-sog.js

@@ -0,0 +1,295 @@
+// inline3d-sog.js — read the `meta.json` out of a `.sog`, and the optional `camera` block in it.
+//
+// EXPERIMENTAL. Internal to `./splat`, which re-exports `readSogCamera`. Not covered by the SDK's
+// 1.x semver promise — see docs/sdk-stability.md.
+//
+// WHY A ZIP READER IS IN THIS SDK AT ALL. A `.sog` from `splat-transform` is a PKZip of webp
+// planes plus a `meta.json`, and Spark reads exactly the fields it needs to build splats out of
+// it — it neither surfaces the rest of the file nor hands back the parsed metadata. But whether a
+// splat is an OBJECT (a product hero, a scan, a turntable subject) or a PHOTOGRAPH LIFTED INTO 3D
+// is not a rendering detail: it decides which VIEW RIG the window should be on, and getting that
+// wrong is the difference between a picture you can lean into and an arbitrary cloud framed by a
+// bounding box. The `camera` block records the recording camera so the viewer can conserve it.
+//
+// So the choice is between asking every page to parse its own assets and reading ~40 bytes of
+// central directory here. The reader below does the second: it is deliberately the smallest thing
+// that can find ONE named entry in a zip, and it never touches the webp planes (which are
+// megabytes, and Spark's business).
+//
+// It is BYTES-ONLY on purpose. The gallery hands the SDK bytes rather than a URL (Spark infers a
+// splat's format from the URL path, so an extension-less `blob:` URL fails inside a worker), and
+// those same bytes are the ones this reads — one download, no second fetch, no range request, and
+// no chance of reading metadata from a different build of the asset than the one on screen.
+
+/** `PK\x05\x06` — end of central directory. */
+const EOCD_SIG = 0x06054b50;
+/** `PK\x01\x02` — a central-directory file header. */
+const CEN_SIG = 0x02014b50;
+/** `PK\x03\x04` — a local file header. */
+const LOC_SIG = 0x04034b50;
+
+/** EOCD is 22 bytes plus a comment of at most 64 KiB. */
+const EOCD_MAX_BACK = 22 + 0xffff;
+
+/**
+ * A `meta.json` this large is not a `meta.json`. The guard is against a malformed/hostile
+ * central directory, not against real assets: the largest one seen is ~4 KB.
+ */
+const META_MAX_BYTES = 4 << 20;
+
+/** Locate the end-of-central-directory record, scanning backwards. */
+function findEocd(dv) {
+  const len = dv.byteLength;
+  if (len < 22) return -1;
+  const stop = Math.max(0, len - EOCD_MAX_BACK);
+  for (let i = len - 22; i >= stop; i--) {
+    if (dv.getUint32(i, true) === EOCD_SIG) return i;
+  }
+  return -1;
+}
+
+/** Inflate a raw deflate stream. Returns null where the platform has no DecompressionStream. */
+async function inflateRaw(slice) {
+  if (typeof DecompressionStream !== 'function') return null;
+  const ds = new DecompressionStream('deflate-raw');
+  const stream = new Blob([slice]).stream().pipeThrough(ds);
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/**
+ * Read one named entry out of a PKZip, as bytes.
+ *
+ * Handles the two compression methods a `.sog` actually uses — 0 (stored) and 8 (deflate) — and
+ * returns null for anything else rather than guessing. Zip64 is refused the same way: a `.sog`
+ * big enough to need it would have to be over 4 GB.
+ *
+ * @param {Uint8Array} bytes  the whole archive.
+ * @param {string} name  exact entry name, e.g. `meta.json`.
+ * @returns {Promise<Uint8Array|null>}
+ */
+export async function readZipEntry(bytes, name) {
+  if (!bytes || bytes.byteLength < 22) return null;
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const eocd = findEocd(dv);
+  if (eocd < 0) return null;
+
+  const count = dv.getUint16(eocd + 10, true);
+  let p = dv.getUint32(eocd + 16, true);
+  // 0xffffffff in either field is the zip64 escape; we do not follow it (see above).
+  if (p === 0xffffffff || p >= dv.byteLength) return null;
+
+  const dec = new TextDecoder();
+  for (let i = 0; i < count; i++) {
+    if (p + 46 > dv.byteLength || dv.getUint32(p, true) !== CEN_SIG) return null;
+    const method = dv.getUint16(p + 10, true);
+    const compSize = dv.getUint32(p + 20, true);
+    const rawSize = dv.getUint32(p + 24, true);
+    const nameLen = dv.getUint16(p + 28, true);
+    const extraLen = dv.getUint16(p + 30, true);
+    const commentLen = dv.getUint16(p + 32, true);
+    const localOff = dv.getUint32(p + 42, true);
+    const entry = dec.decode(bytes.subarray(p + 46, p + 46 + nameLen));
+    p += 46 + nameLen + extraLen + commentLen;
+    if (entry !== name) continue;
+
+    if (compSize === 0xffffffff || rawSize === 0xffffffff || localOff === 0xffffffff) return null;
+    if (rawSize > META_MAX_BYTES) return null;
+    // The central directory's sizes are authoritative; the LOCAL header's may be zeroed (a
+    // streaming writer defers them to a data descriptor). Only its two length fields are read.
+    if (localOff + 30 > dv.byteLength || dv.getUint32(localOff, true) !== LOC_SIG) return null;
+    const lNameLen = dv.getUint16(localOff + 26, true);
+    const lExtraLen = dv.getUint16(localOff + 28, true);
+    const start = localOff + 30 + lNameLen + lExtraLen;
+    if (start + compSize > dv.byteLength) return null;
+    const slice = bytes.subarray(start, start + compSize);
+    if (method === 0) return slice;
+    if (method === 8) return inflateRaw(slice);
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Parse a `.sog`'s `meta.json`.
+ *
+ * @param {Uint8Array|ArrayBuffer} bytes
+ * @returns {Promise<object|null>} the parsed object, or null if this is not a `.sog`, has no
+ *          `meta.json`, or the entry cannot be read on this platform.
+ */
+export async function readSogMeta(bytes) {
+  const u8 = bytes instanceof Uint8Array ? bytes : bytes ? new Uint8Array(bytes) : null;
+  if (!u8 || u8.length < 4) return null;
+  // PK\x03\x04 — cheap reject before the backwards scan, so a `.ply`/`.spz`/`.splat` costs
+  // four byte comparisons.
+  if (!(u8[0] === 0x50 && u8[1] === 0x4b && u8[2] === 0x03 && u8[3] === 0x04)) return null;
+  let raw;
+  try {
+    raw = await readZipEntry(u8, 'meta.json');
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  try {
+    return JSON.parse(new TextDecoder().decode(raw));
+  } catch {
+    return null;
+  }
+}
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+
+/**
+ * Validate the `camera` block of a `.sog` `meta.json`.
+ *
+ * THE BLOCK IS THE RIG SWITCH — present means "this splat was lifted from a photograph, and here
+ * is the camera that took it"; absent means "this is an object", which is the display rig and the
+ * behaviour every existing page already has. That is the whole contract, and it is why this is
+ * strict: a half-parsed block that silently keeps some defaults would put a photo scene on a
+ * plausible-looking rig that is not the capture, which is indistinguishable from a framing bug.
+ *
+ * Shape (`meta.json`, top level, right after `count`; `version` stays 2). v2 is a SUPERSET of
+ * v1 — every key below except `convention` is optional, and a v1 block still reads:
+ *
+ *     "camera": {
+ *       "convention": "opencv",
+ *       "rig":        "camera",                        // v2: which rig this asset wants
+ *       "rest":       { "position": [0,0,0], "rotation": [0,0,0,1] },
+ *       "intrinsics": { "fx":…, "fy":…, "cx":…, "cy":…, "width":…, "height":… },
+ *       "stereo":     { "baseline_m": 0.063 },
+ *       "focus":      { "point": [0,0,1.68], "subject_m":…, "near_m":…, "far_m":…,
+ *                       "source": "convergence|manual|auto" },   // v2
+ *       "dxr":        { "ipd_factor": 1.0, "parallax_factor": 1.0 }   // v2
+ *     }
+ *
+ * `intrinsics` BECAME OPTIONAL IN v2, which is the change with teeth: a block can now say "this
+ * is a camera rig, open it at this viewpoint" without claiming a lens, and the consumer is
+ * expected to estimate one. So this returns a descriptor with null intrinsics rather than
+ * refusing the block — refusing it would silently demote a camera-rig asset to the display rig,
+ * which is the failure this whole mechanism exists to prevent.
+ *
+ * `focus.point` is THE point: the orbit centre, the pivot plane and the convergence distance,
+ * which are one thing and are stored once.
+ *
+ * `convention` is REQUIRED to be `opencv` (+x right, +y DOWN, +z forward, pixel (0,0) at the top
+ * left) rather than defaulted: it is the frame the intrinsics are expressed in, and a reader that
+ * assumed it would mis-sign the principal-point offset on any other convention — a wrong answer
+ * with no error, which is the one failure mode a metadata block must not have.
+ *
+ * @param {object|null} meta  a parsed `meta.json`.
+ * @returns {object|null} a normalised camera descriptor, or null.
+ */
+export function sogCameraFromMeta(meta) {
+  const c = meta && typeof meta === 'object' ? meta.camera : null;
+  if (!c || typeof c !== 'object') return null;
+  if (c.convention !== 'opencv') {
+    console.warn(
+      `[inline3d/splat] .sog camera block has convention "${c.convention}" — only "opencv" is ` +
+        'understood, so the block is IGNORED and this asset stays on the display rig.',
+    );
+    return null;
+  }
+  const i = c.intrinsics;
+  let intrinsics = null;
+  if (i && typeof i === 'object') {
+    const fx = num(i.fx);
+    const fy = num(i.fy);
+    const cx = num(i.cx);
+    const cy = num(i.cy);
+    const width = num(i.width);
+    const height = num(i.height);
+    if (!(fx > 0) || !(fy > 0) || !(width > 0) || !(height > 0) || cx === null || cy === null) {
+      // Half-believing a lens is worse than having none: with intrinsics optional in v2 there is
+      // a well-defined thing to do instead, which is estimate one from the cloud.
+      console.warn(
+        '[inline3d/splat] .sog camera block has unusable intrinsics — they are DROPPED and the ' +
+          'lens is estimated from the cloud instead; the rest of the block still applies.',
+        i,
+      );
+    } else {
+      intrinsics = { fx, fy, cx, cy, width, height };
+    }
+  }
+  const pos = Array.isArray(c.rest?.position) ? c.rest.position.map((v) => num(v) ?? 0) : [0, 0, 0];
+  const rot = Array.isArray(c.rest?.rotation) ? c.rest.rotation.map((v) => num(v) ?? 0) : [0, 0, 0, 1];
+  const baseline = num(c.stereo?.baseline_m);
+
+  // v2 `rig`. Anything unrecognised is dropped rather than guessed at — the waterfall's next
+  // step (a block means a camera) is a better answer than a typo taken literally.
+  let rig = null;
+  if (c.rig === 'camera' || c.rig === 'display') rig = c.rig;
+  else if (c.rig !== undefined) {
+    console.warn(`[inline3d/splat] .sog camera block has rig "${c.rig}" — ignored`, c.rig);
+  }
+
+  // v2 `focus`. The point is the only required part; the three distances are advisory and are
+  // carried through untouched for a host page that wants them (a depth budget, a HUD).
+  let focus = null;
+  const fp = c.focus?.point;
+  if (Array.isArray(fp) && fp.length >= 3 && fp.every((v) => num(v) !== null)) {
+    focus = {
+      point: [fp[0], fp[1], fp[2]],
+      subject_m: num(c.focus.subject_m),
+      near_m: num(c.focus.near_m),
+      far_m: num(c.focus.far_m),
+      source: typeof c.focus.source === 'string' ? c.focus.source : null,
+    };
+  } else if (c.focus !== undefined) {
+    console.warn('[inline3d/splat] .sog camera block has an unusable focus — ignored', c.focus);
+  }
+
+  // v2 `dxr`. These are the camera rig's ABSOLUTE scalars, and they stay absolute: normalising
+  // them against the convergence distance would make the scene's depth breathe every time the
+  // viewer re-focused.
+  const ipdFactor = num(c.dxr?.ipd_factor);
+  const parallaxFactor = num(c.dxr?.parallax_factor);
+
+  return {
+    convention: 'opencv',
+    rig,
+    focus,
+    dxr: {
+      ipdFactor: ipdFactor !== null && ipdFactor >= 0 ? ipdFactor : null,
+      parallaxFactor: parallaxFactor !== null && parallaxFactor >= 0 ? parallaxFactor : null,
+    },
+    rest: {
+      position: [pos[0] ?? 0, pos[1] ?? 0, pos[2] ?? 0],
+      rotation: [rot[0] ?? 0, rot[1] ?? 0, rot[2] ?? 0, rot[3] ?? 1],
+    },
+    intrinsics,
+    stereo: baseline > 0 ? { baseline_m: baseline } : null,
+    /**
+     * Derived, because every consumer needs them and each is one line to get subtly wrong.
+     *
+     * Null when the block carried no usable intrinsics (legal in v2) — the caller estimates a
+     * lens from the cloud instead.
+     *
+     * `verticalFov` is the FULL vertical angle the capture subtends, in RADIANS — the unit an
+     * XRViewRigInit wants (three's `camera.fov` is the same angle in degrees).
+     *
+     * `principalOffset` is the principal point's offset from the frame centre as a fraction of
+     * the frame, x rightwards and **y upwards** — i.e. already out of OpenCV's y-down frame and
+     * into the GL/three one, so a consumer never has to remember which way `cy` grows. A
+     * rectified stereo pair carries its deconvergence here: shifting the principal point is what
+     * "deconverging" DOES to a pair, so a non-zero x is the capture's zero-disparity plane
+     * expressed as a lens shift rather than as a distance.
+     */
+    verticalFov: intrinsics ? 2 * Math.atan(intrinsics.height / (2 * intrinsics.fy)) : null,
+    principalOffset: intrinsics
+      ? {
+          x: (intrinsics.cx - intrinsics.width / 2) / intrinsics.width,
+          y: -(intrinsics.cy - intrinsics.height / 2) / intrinsics.height,
+        }
+      : null,
+  };
+}
+
+/**
+ * Read the `camera` block straight out of `.sog` bytes. Convenience over
+ * {@link readSogMeta} + {@link sogCameraFromMeta}.
+ *
+ * @param {Uint8Array|ArrayBuffer} bytes
+ * @returns {Promise<object|null>}
+ */
+export async function readSogCamera(bytes) {
+  return sogCameraFromMeta(await readSogMeta(bytes));
+}