@displayxr/inline3d 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,142 @@ 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.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**
+(`./viewer`, `./splat`, `./model`) with one additive option. A page that ignores everything below
+renders identically while it is weaving; the changes only decide what a canvas shows once nothing
+weaves it any more.
+
+### Fixed
+
+- **A canvas nothing is weaving can no longer be left holding a raw side-by-side pair**
+  ([#28](https://github.com/DisplayXR/displayxr-web/issues/28), field report
+  [browser-pvt#99](https://github.com/DisplayXR/displayxr-browser-pvt/issues/99)). Every fallback in
+  this SDK was decided once at boot, so four paths ended with a tile showing a flat squeezed
+  left|right pair, permanently — the symptom users report as "3D element shows SBS", usually on a
+  slow connection:
+  - session `end` tore down without the mono repaint `_deactivate` does — every image and video
+    canvas kept its last SBS frame; teardown, deactivate and a failed activate now share one
+    `_paintMono`;
+  - an image whose download landed **after** teardown painted a fresh SBS pair into a canvas with no
+    layer — `_paint` now forces the mono branch (and a 1:1 buffer) whenever the manager is stopped or
+    the window has no live layer, whatever `win.sbs` says;
+  - a throwing `new XRDisplayLayer()` was swallowed silently and left the canvas as it was — it now
+    warns once per window (with the error) and repaints mono; still no retry;
+  - a buffering video (`readyState < 2`) skipped its paint entirely, so its canvas layer went idle and
+    could drop out of the browser's aggregated frame — it now re-commits its last decoded frame with
+    an identity blit.
+- **One throwing scene no longer stops the windows after it from repainting.** `onFrame` is contained
+  per window and warned about once; an un-redrawn canvas is exactly what the browser's weave join
+  loses.
+
+### Added
+
+- **`addScene({ onLayerLost })`** (preview tier): called once when a scene window's layer goes away
+  for good (session end, or the layer could not be created) — not when a lazy tile scrolls off. The
+  SDK does not own a scene canvas's pixels, so this is how it tells the owner to go flat.
+  `SceneViewer.onLayerLost` is the ready-made handler (`startMono()`), and `./splat` / `./model` wire
+  it for you.
+
 ## 1.6.0 — 2026-09-08
 
 Touches the **preview tier** (`./viewer`) and fixes a **documentation error in the core 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/index.d.ts

@@ -179,6 +179,15 @@ export interface SceneOptions extends TileOptions {
   viewRig?: XRViewRigInit;
   /** Element whose visibility drives the lazy create/close lifecycle (defaults to the canvas). */
   observe?: Element;
+  /**
+   * Called once when this window's weave layer goes away for good — the session ended, or the
+   * layer could not be created. You own a scene canvas's pixels, so this is the SDK's only way
+   * to tell you that the side-by-side pair in it is no longer being woven and is now just
+   * squeezed 2D on the page: take the canvas flat here (`SceneViewer.startMono`, or your own
+   * mono path). NOT called when a lazy tile merely scrolls off screen — that layer is coming
+   * back. A throw is caught and warned about.
+   */
+  onLayerLost?: () => void;
 }
 
 /** The per-frame render callback passed to {@link Inline3D.addScene}. */

package/js/inline3d-model.js

@@ -393,6 +393,9 @@ export function addModel(wall, canvas, src, opts = {}) {
   if (wall && wall.supported) {
     handle = wall.addScene(canvas, viewer.onFrame, {
       virtualDisplayHeight,
+      // The layer can go away for good (the session ends, the constructor refuses): take the
+      // canvas flat rather than leave its last side-by-side frame on the page (web#28).
+      onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
     });
   } else {

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));
+}