@voluma/vlam 0.1.0 → 0.2.0

package/dist/splat-budget.d.ts

@@ -0,0 +1,404 @@
+/**
+ * Device profiling and the default active-splat budget.
+ *
+ * Streaming is splat-count budgeted rather than byte budgeted: every cost in
+ * the renderer (pool textures, sort buffers) scales with the number of
+ * resident splats - roughly 64 bytes of GPU memory per splat (three RGBA32F
+ * data textures + one RGBA8, plus the sort index/order/bucket buffers), or
+ * about 48 bytes when `poolFloatTextures: 'float16'` halves centers and
+ * covarianceA; plus about 52 more bytes of CPU-side backing per splat of
+ * pool capacity. Capping the active splat count therefore caps memory
+ * directly, which is what matters on mobile GPUs.
+ */
+import type { StreamedSplatFormat } from './loading';
+/**
+ * Desktop GPU capability class for budget / quality defaults.
+ *
+ * Mobile still keys off {@link SplatDeviceProfile.isMobile}; this splits
+ * non-mobile machines that would otherwise share the ~8M workstation path.
+ * Unset means "unknown" - keep the pre-existing desktop defaults (fail open).
+ */
+export type SplatGpuClass = 'discrete' | 'integrated' | 'fallback';
+/** Browser/device signals used for deterministic budget selection. */
+export interface SplatDeviceProfile {
+    /** Coarse memory estimate in GiB, when exposed by the browser. */
+    deviceMemoryGb?: number;
+    /** Whether the runtime is an iOS/iPadOS-class device. */
+    isIOS?: boolean;
+    /** Whether the runtime is a phone/tablet-class device (includes iOS). */
+    isMobile?: boolean;
+    /**
+     * Whether the runtime is a standalone XR headset browser (Quest, Pico, …).
+     * Headsets are mobile-class GPUs asked to fill a stereo framebuffer larger
+     * than a 4K desktop, so they get their own, tighter defaults.
+     */
+    isHeadset?: boolean;
+    /**
+     * Whether this is a *budget* phone rather than a flagship one.
+     *
+     * `isMobile` cannot tell a Galaxy A51 from an iPhone 15 Pro, and the memory
+     * signal cannot either - Chrome privacy-caps `deviceMemory` at 8 GiB, so the
+     * flagship and the mid-ranger both land on the same ceiling despite an order
+     * of magnitude between their GPUs. A coarse signal, and a *downward* one: a
+     * reading of ≤4 is trustworthy because the cap only ever lowers it, while a
+     * reading of 8 says nothing. {@link hasWebGpu} is the sharper signal where it
+     * applies, since it names a difference in how the sort runs rather than
+     * guessing capability from RAM.
+     */
+    isLowPower?: boolean;
+    /**
+     * Whether the runtime exposes WebGPU at all.
+     *
+     * `false` means the renderer will take the WebGL2 fallback, where the depth
+     * sort runs on the CPU rather than as a GPU compute pass - a different cost
+     * curve, not just a slower one. See {@link resolveSplatBudget}.
+     *
+     * Detected from the presence of `navigator.gpu`, which is a *browser support*
+     * signal rather than an adapter one: a runtime that exposes the API but whose
+     * `requestAdapter` fails (driver blocklist) still reports `true` here and will
+     * fall back to WebGL2 anyway. A host that knows its renderer's real backend
+     * can correct this by passing its own profile.
+     */
+    hasWebGpu?: boolean;
+    /**
+     * Desktop GPU class from {@link probeSplatGpuClass} / {@link classifySplatGpuClass}.
+     * Omit when unknown so workstations without adapter info keep the 8M path.
+     */
+    gpuClass?: SplatGpuClass;
+}
+/** Adapter identifying fields used by {@link classifySplatGpuClass}. */
+export interface SplatGpuAdapterInfo {
+    vendor?: string;
+    architecture?: string;
+    device?: string;
+    description?: string;
+    isFallbackAdapter?: boolean;
+}
+/**
+ * How expensive a format's splats are *per splat*, which is not the same across
+ * formats and is the reason one mobile budget cannot serve them all.
+ *
+ * - `'sampled'` - coarser LOD levels are subsamples of the same surface, so a
+ *   splat costs about the same however deep the cut is. Streamed SOG.
+ * - `'lcc'` - XGRIDS' levels are decimated *alternatives* whose splats merge
+ *   into wide flat discs (see {@link liftBudgetToFinestLevel}). Cost per splat
+ *   therefore *rises* as the budget falls, because a tighter budget serves
+ *   coarser levels and each of their splats covers more pixels. `.rad`, `.lcc`,
+ *   `.lcc2`.
+ *
+ * Measured on one iPhone 15 Pro, which is what the numbers below are worth:
+ * `oldtimers-route` (`.rad`) ran 31-39 fps at 750k and 45-50 at 600k, while
+ * `sandwijck` (streamed SOG) held 52-57 fps at 675k resident. Two streamed
+ * scenes, near-identical splat counts, ~20 fps apart - splat count is a poor
+ * proxy for cost, and the format is the only better signal available for free
+ * before a single byte is fetched.
+ */
+export type SplatCostClass = 'lcc' | 'sampled';
+/**
+ * Classifies a WebGPU adapter from its identifying strings.
+ *
+ * Heuristics only - browsers may blank fields for privacy. Prefer
+ * {@link probeSplatGpuClass} when both power-preference adapters are available.
+ */
+export declare function classifySplatGpuClass(info: SplatGpuAdapterInfo | undefined): SplatGpuClass;
+/** Minimal `navigator.gpu` surface for {@link probeSplatGpuClass}. */
+export interface SplatGpuProbeEntry {
+    requestAdapter(options?: {
+        powerPreference?: 'low-power' | 'high-performance';
+    }): Promise<SplatGpuProbeAdapter | null>;
+}
+/** Adapter handle with optional `.info` (WebGPU GPUAdapterInfo). */
+export interface SplatGpuProbeAdapter {
+    readonly info?: SplatGpuAdapterInfo;
+}
+/**
+ * Probes WebGPU adapters to choose a {@link SplatGpuClass}.
+ *
+ * Requests both `low-power` and `high-performance` adapters when possible. A
+ * hybrid laptop that exposes two different devices is `discrete`; a single
+ * shared / unified GPU (Apple Silicon, many iGPU-only machines) is classified
+ * from {@link classifySplatGpuClass}. Returns `undefined` when WebGPU is absent
+ * or the probe fails, so budget resolution keeps the legacy desktop path.
+ */
+export declare function probeSplatGpuClass(gpu?: SplatGpuProbeEntry | null | undefined): Promise<SplatGpuClass | undefined>;
+/**
+ * Whether fill-rate / laptop-class defaults apply (mobile, or desktop
+ * integrated / software fallback). Exported so hosts and the demo share one
+ * predicate for performance-mode defaults and adaptive DPR.
+ */
+export declare function isFillConstrainedSplatDevice(profile?: SplatDeviceProfile | undefined): boolean;
+/** Reads the available browser device signals without requiring a DOM runtime. */
+export declare function detectSplatDeviceProfile(): SplatDeviceProfile | undefined;
+/** Scene-side signals for {@link resolveSplatBudget}. */
+export interface SplatBudgetOptions {
+    /**
+     * The format about to be loaded, which selects the {@link SplatCostClass}
+     * whose mobile tier applies. Omit when it is not yet known - the `'sampled'`
+     * numbers are what every caller resolved before cost classes existed.
+     */
+    format?: StreamedSplatFormat;
+    /**
+     * A ceiling on the resolved default, for callers that want to tighten without
+     * overriding what this function knows.
+     *
+     * `override` is absolute: it wins over the device tier, the cost class and
+     * everything else, because a caller who names a number has said they know
+     * better. That is the right contract and the wrong tool for "the same as
+     * usual, but no more than N" - which is what a performance toggle or a host
+     * default actually means. Pinning a number there has twice shipped as a bug:
+     * a demo performance mode that *raised* the load on the weakest device tested,
+     * and a host default that bypassed every device tier.
+     *
+     * Applied only when `override` is omitted, and only downward.
+     */
+    cap?: number;
+}
+/**
+ * Chooses a default active-splat budget for the current device.
+ *
+ * The default is derived from the coarsest device-memory signal the platform
+ * exposes; callers who know better (or want a hard cap for a mobile test on
+ * desktop) should pass an explicit override.
+ *
+ * @param override - Explicit budget in splats; wins over device detection when
+ * positive. Throws `RangeError` if it is not a positive finite number.
+ * @param profile - Device signals to decide from; defaults to detecting them.
+ * @param options - Scene signals. `format` selects the {@link SplatCostClass}
+ * whose mobile tier applies; omitting it keeps the `'sampled'` numbers, which
+ * are what every caller resolved before cost classes existed. `cap` is a
+ * ceiling on the *resolved default*, for callers who want to tighten without
+ * overriding - see {@link SplatBudgetOptions.cap}.
+ * @returns A splat-count budget, clamped to a sensible range.
+ */
+export declare function resolveSplatBudget(override?: number, profile?: SplatDeviceProfile | undefined, options?: SplatBudgetOptions): number;
+/**
+ * The budget to run at **while an immersive session presents**, given whatever
+ * budget the page is using outside one.
+ *
+ * Stereo is the cost, and stereo is a property of the *session*, not of the
+ * device: every splat is drawn twice, into two eye viewports that together
+ * exceed a 4K desktop, on a GPU that must hold 72–90 Hz or the compositor
+ * reprojects. That is true of a standalone headset and equally true of a
+ * desktop machine driving a tethered one - which is exactly the case device
+ * sniffing cannot see, since such a machine is a desktop right up until the
+ * moment it is not.
+ *
+ * Keying off presentation instead of identity is also the only approach that
+ * survives new hardware. `detectSplatDeviceProfile`'s `isHeadset` is a
+ * user-agent guess: it misses Apple Vision Pro outright (visionOS Safari
+ * presents as desktop Safari, so a headset would otherwise take the multi-
+ * million desktop budget) and misses every headset released after it is
+ * written. This function needs to know none of that.
+ *
+ * Apply it on `sessionstart` and restore the original on `sessionend` - via
+ * `BudgetGovernor.setBudget` when several meshes share a pool, or a streamed
+ * mesh's own budget setter otherwise.
+ *
+ * @param pageBudget - The budget in use outside the session, typically from
+ * {@link resolveSplatBudget}. Throws `RangeError` if not a positive finite
+ * number.
+ * @returns `pageBudget` lowered to the stereo ceiling; never raised - a device
+ * already rendering below the ceiling stays where it is.
+ */
+export declare function resolveXrSplatBudget(pageBudget: number): number;
+/**
+ * Raises `budget` far enough to hold a scene's finest level in full, when
+ * that level is small enough to be worth taking whole.
+ *
+ * The LOD budget assumes coarser levels are cheap *approximations* of the
+ * same surface, so trading detail for memory is nearly free. XGRIDS' LCC
+ * LCC breaks that assumption: its five levels are decimated alternatives
+ * whose splats merge into wide flat discs (correct at distance, streaked up
+ * close), so any budget shortfall costs visible quality - sub-chunking gives
+ * the scheduler ~128k-splat granularity to thin cells with, but a thinned
+ * fine level is still sparser than the capture intends. A capture whose
+ * finest level fits under the desktop ceiling is better shown whole: Casino's
+ * level 0 is 4.74M splats and sits under the 8M default.
+ *
+ * Mobile and fill-constrained desktops (integrated / fallback GPU class) are
+ * exempt: their cap is a fill-rate limit, not a sizing accident.
+ *
+ * @param budget - The resolved device budget.
+ * @param finestLevelSplats - Splats in the scene's finest level.
+ * @returns `budget`, or the finest level's size when that is the better fit.
+ */
+export declare function liftBudgetToFinestLevel(budget: number, finestLevelSplats: number, profile?: SplatDeviceProfile | undefined): number;
+/** Options for {@link estimateSplatPoolBytes}. */
+export interface SplatPoolBytesOptions {
+    /**
+     * Pool texture precision, matching `SplatMeshOptions.poolFloatTextures`.
+     * `'float16'` halves centers and covarianceA. Default `'float32'`.
+     */
+    floatTextures?: 'float32' | 'float16';
+    /** Per-splat SH bands the pool allocates for. Default `0`. */
+    shBands?: 0 | 1 | 2 | 3;
+    /**
+     * Pool capacity as a multiple of `splats`. `StreamedSplatMesh` allocates
+     * 1.5× (the default here) so per-run row alignment and the
+     * append-before-remove window during LOD swaps have somewhere to go; pass
+     * `1.4` to model `experimentalStagedSwaps: false`, or `1` for a static mesh.
+     */
+    capacityFactor?: number;
+    /**
+     * Whether to include the CPU-side backing arrays. Default `true` - they are
+     * real host memory a device has to find, so the honest answer to "can I
+     * afford this ceiling" includes them.
+     */
+    includeCpuBacking?: boolean;
+}
+/**
+ * Estimates the memory a splat pool of `splats` costs.
+ *
+ * This exists to make a streamed mesh's `maxBudget` a computation rather than a
+ * guess. A pool is allocated **once, from the ceiling** and never
+ * grows, so several governed meshes cost the sum of their ceilings whatever the
+ * shared budget is set to - a `BudgetGovernor` redistributes *sharpness* within
+ * that envelope, it does not shrink it. Price the ceilings before choosing them:
+ *
+ * ```js
+ * // 1 main + 4 markers, each able to reach 1.5M splats
+ * const bytes = estimateSplatPoolBytes(4_000_000) + 4 * estimateSplatPoolBytes(1_500_000);
+ * ```
+ *
+ * Per splat of *capacity* (`splats × capacityFactor`), counted from what the
+ * constructor actually allocates:
+ *
+ * - **Pool textures** 52 B - centers RGBA32F 16, colors RGBA8 4,
+ *   covarianceA RGBA32F 16, covarianceB RGBA32F 16. `'float16'` drops centers
+ *   and covarianceA to 8 each (36 B); covarianceB stays float32 because it
+ *   packs integer IDs.
+ * - **Packed SH** 16 B per `RGBA32UI` texture, `ceil(coefficients / 4)` of them
+ *   - so 16 / 32 / 64 B at 1 / 2 / 3 bands.
+ * - **Sort storage** 16 B - the radix sorter's ping-pong key/value buffers.
+ * - **CPU backing** 68 B - the float32/uint8 arrays kept for partial uploads
+ *   (always full precision, even under `'float16'`): centers 16, colors 4,
+ *   covarianceA 16, covarianceB 16, plus four u32-per-splat arrays - draw-order
+ *   indices, the active-list source index, the pool-slot map, and the picker's
+ *   pool-index template (allocated lazily, counted because a picked scene pays
+ *   it). Under `'float16'` add a further 16 B: the half-encoded texture images
+ *   are held alongside the float32 backing, not instead of it, so that
+ *   precision saves GPU bytes only. Included unless `includeCpuBacking` is
+ *   `false`.
+ *
+ * The module header's "roughly 64 bytes per splat" rounds the GPU side of this.
+ *
+ * @param splats - The ceiling in splats (e.g. a mesh's `maxBudget`).
+ * @returns Estimated bytes. Indicative, not a device-memory guarantee: driver
+ * texture padding, staging allocations and the decoded-chunk CPU cache
+ * ({@link resolveCpuCacheBytes}) sit outside it.
+ * @throws {RangeError} if `splats` is not a positive finite number, or
+ * `capacityFactor` is not a finite number `>= 1`.
+ */
+export declare function estimateSplatPoolBytes(splats: number, options?: SplatPoolBytesOptions): number;
+/**
+ * Suggested ceiling for the renderer's pixel ratio on this device.
+ *
+ * Splat rendering is fragment-bound, so render resolution is one of the
+ * largest costs on a high-DPI phone: a 2.6x display renders ~7x the pixels of
+ * a 1x one, and every one of them blends the full depth-sorted splat stack.
+ * The library cannot apply this itself (it draws into a renderer the app
+ * owns), so it exports the policy - pass it to `renderer.setPixelRatio`:
+ *
+ * ```js
+ * renderer.setPixelRatio(Math.min(window.devicePixelRatio, recommendedMaxPixelRatio()));
+ * ```
+ *
+ * This is the *quality* ceiling. Viewers that offer a performance mode
+ * (SuperSplat halves mobile resolution in its own) should go lower still when
+ * it is on.
+ */
+export declare function recommendedMaxPixelRatio(profile?: SplatDeviceProfile | undefined): number;
+/**
+ * The Gaussian cutoff a `.rad` renders at, in standard deviations, or
+ * `undefined` to accept the device-wide default.
+ *
+ * Spark hard-codes `sqrt(8)` (≈2.83σ) for every device, and matching it is what
+ * makes a `.rad` look like Spark's render on a desktop. On a phone it is the
+ * wrong trade: rendering is fill-bound on mobile, so a format override bypasses
+ * the device policy that every other format accepts.
+ *
+ * Returning `undefined` on mobile lets `SplatMesh` apply its own 3σ cutoff and
+ * undersized-splat floor; `.rad` must not escape that mobile policy.
+ *
+ * @returns √8 on discrete desktop; `undefined` on fill-constrained devices,
+ * meaning "no format override".
+ */
+export declare function recommendedRadMaxStdDev(profile?: SplatDeviceProfile | undefined): number | undefined;
+/**
+ * Suggested WebXR framebuffer scale for this device. On three 0.185.x this is
+ * a **WebGL XR** policy: apply it once before the session starts with
+ * `renderer.xr.setFramebufferScaleFactor`. three's WebGPU XR path creates its
+ * `XRGPUBinding` projection layer at native scale and does not consume that
+ * setting, so WebGPU hosts should leave the native scale and use the presenting
+ * splat budget plus fixed foveation for runtime headroom instead.
+ *
+ * Splat rendering is fill-bound, and a headset's default framebuffer is
+ * already supersampled past its panels (~1680×1760 per eye on Quest 3):
+ * 0.8 cuts fragment work ~36% for a barely visible softening. Non-headset
+ * XR (desktop-tethered) keeps the native 1.0.
+ */
+export declare function recommendedXrFramebufferScale(profile?: SplatDeviceProfile | undefined): number;
+/** Inputs for {@link suggestAdaptivePixelRatio}. */
+export interface AdaptivePixelRatioInput {
+    /** Latest wall-frame time in milliseconds. */
+    frameMs: number;
+    /** Currently applied pixel ratio. */
+    current: number;
+    /** Quality ceiling (typically {@link recommendedMaxPixelRatio}). */
+    max: number;
+    /** Floor; defaults to `1`. */
+    min?: number;
+    /** EMA of frame time from the previous call; omit on the first sample. */
+    emaMs?: number;
+    /**
+     * Comfortable frame time (ms). Below this (with headroom) the helper may
+     * step the ratio up. Default `18` (~55 fps).
+     */
+    targetFrameMs?: number;
+    /**
+     * Sustained frame time (ms) that triggers a step down. Default `22`
+     * (~45 fps) so brief spikes do not thrash the canvas size.
+     */
+    pressureFrameMs?: number;
+}
+/** Result of {@link suggestAdaptivePixelRatio}. */
+export interface AdaptivePixelRatioResult {
+    /** Suggested pixel ratio after hysteresis (quarter steps). */
+    pixelRatio: number;
+    /** Updated EMA to pass back on the next call. */
+    emaMs: number;
+}
+/**
+ * Suggests a pixel ratio under frame-time pressure.
+ *
+ * The library cannot call `renderer.setPixelRatio` (the host owns the
+ * renderer); this is a pure policy helper. Pass the previous result's
+ * `emaMs` each frame for a stable EMA, and only re-size the canvas when
+ * `pixelRatio` changes.
+ *
+ * Steps are quarter-units with asymmetric thresholds (pressure to lower,
+ * comfortable headroom to raise) so the ratio does not oscillate.
+ */
+export declare function suggestAdaptivePixelRatio(input: AdaptivePixelRatioInput): AdaptivePixelRatioResult;
+/**
+ * Chooses a decoded-chunk CPU cache cap from the same safe device profile.
+ *
+ * **The unknown-memory fallback must not read as "tiny".** iOS Safari does not
+ * implement `navigator.deviceMemory` at all, so every iPhone lands on this
+ * branch - and an earlier version resolved it to 1 GiB, i.e. the 32 MiB floor,
+ * on hardware with 8 GiB. That is not a conservative guess, it is a wrong one,
+ * and it is invisible on `.rad`, whose page-table cache has its own floor.
+ *
+ * On streamed SOG there is no such floor and the cost is immediate: measured on
+ * an iPhone 15 Pro against `sandwijck`, the scheduler asked for 539,734 splats
+ * and the mesh could only hold 466,499 of them across 3 chunk files (desktop:
+ * 5), evicting continuously. The finest level is wanted *nearest the camera* and
+ * lives in the largest files, so those are what fail to stay resident - the
+ * middle of the view drops out and the scene renders as a donut.
+ *
+ * A device that declines to report its memory is far likelier to be a modern
+ * phone withholding a fingerprinting signal than an actual 1 GiB device, so the
+ * fallback assumes 4 GiB (128 MiB of cache). The floor stays for the genuinely
+ * profile-less case - SSR and Node tooling, which never stream a scene anyway.
+ */
+export declare function resolveCpuCacheBytes(profile?: SplatDeviceProfile | undefined): number;

package/dist/splat-data-BZM5dhhx.js

@@ -0,0 +1,10 @@
+const z = 0.28209479177387814;
+function A(c, s, H, L, M, _, b, j, k) {
+  const h = Math.hypot(_, b, j, k) || 1, m = _ / h, t = b / h, n = j / h, o = k / h, r = (1 - 2 * (n * n + o * o)) * H, p = 2 * (t * n - m * o) * L, w = 2 * (t * o + m * n) * M, C = 2 * (t * n + m * o) * H, S = (1 - 2 * (t * t + o * o)) * L, f = 2 * (n * o - m * t) * M, g = 2 * (t * o - m * n) * H, v = 2 * (n * o + m * t) * L, y = (1 - 2 * (t * t + n * n)) * M;
+  c[s * 6 + 0] = r * r + p * p + w * w, c[s * 6 + 1] = r * C + p * S + w * f, c[s * 6 + 2] = r * g + p * v + w * y, c[s * 6 + 3] = C * C + S * S + f * f, c[s * 6 + 4] = C * g + S * v + f * y, c[s * 6 + 5] = g * g + v * v + y * y;
+}
+export {
+  z as S,
+  A as w
+};
+//# sourceMappingURL=splat-data-BZM5dhhx.js.map

package/dist/splat-data-BZM5dhhx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"splat-data-BZM5dhhx.js","sources":["../src/lib/splat-data.ts"],"sourcesContent":["import type { SplatSourceFormat } from './loading';\n\n/**\n * CPU-side representation of a set of 3D Gaussians, ready for GPU upload.\n *\n * Everything is stored in flat typed arrays (struct-of-arrays) so the data\n * can be copied straight into textures and transferred to workers.\n */\nexport interface SplatData {\n  /** Number of Gaussians. */\n  readonly count: number;\n  /** Gaussian centers, 3 floats (x, y, z) per splat. */\n  readonly positions: Float32Array;\n  /** Base color + opacity, 4 bytes (r, g, b, a) per splat. */\n  readonly colors: Uint8Array;\n  /**\n   * 3D covariance matrices, 6 floats per splat: the upper triangle\n   * (m00, m01, m02, m11, m12, m22) of the symmetric 3×3 matrix\n   * Σ = R·S·Sᵀ·Rᵀ, precomputed from the per-splat scale and rotation.\n   */\n  readonly covariances: Float32Array;\n  /** Higher-order spherical harmonics (view-dependent color), if present. */\n  readonly sh?: SplatShData;\n  /**\n   * Per-splat (rather than palette-compressed) higher-order SH, as LCC `Quality`\n   * delivers it. Unlike {@link sh}, this survives being appended into a\n   * shared pool, because there is no per-file palette to merge.\n   */\n  readonly shPacked?: SplatPackedShData;\n  /**\n   * Scene was trained/exported with antialiasing (e.g. the SOG `antialias`\n   * meta flag). When true, {@link SplatMesh} applies the Mip-Splatting 2D\n   * filter (dilation + opacity compensation). Absent/false = classic 3DGS.\n   */\n  readonly antialias?: boolean;\n  /**\n   * Per-splat LOD-tree links for a streamed `.rad` chunk (the merged coarse\n   * nodes and leaves are all present in {@link positions} etc.). The streamed\n   * reader uses this to pick the rendered cut across chunks; other formats and\n   * the one-shot path leave it undefined. See `parse-rad.ts` and `rad.ts`.\n   */\n  readonly radTree?: RadTreeData;\n  /**\n   * Per-splat parent LOD-node size for the frontier cut (`foveationMode:\n   * 'frontier'`), sign-encoding leaf-ness: `> 0` internal node, `< 0` leaf,\n   * `|value|` is the parent's world size (a large sentinel ≈ ∞ for a root or a\n   * splat whose parent is not yet decoded). Attached by `RadFoveatedSource` as\n   * chunks stream in; uploaded into `covarianceB.w`. See `docs/formats/rad-notes.md`.\n   */\n  readonly frontierParent?: Float32Array;\n  /** Internal RAD SH codebook retained while a streamed `.rad` scene is set\n   * up. It is passed back to later chunk decodes; consumers can ignore it. */\n  readonly radShCodebook?: RadShCodebook;\n  /**\n   * The self-contained format this scene was decoded from, stamped by the\n   * loaders ({@link loadScene}/{@link loadSceneFile}). {@link SplatMesh} reads\n   * it to pick the `orientation: 'y-up'` correction. Absent on hand-built data\n   * and streamed chunks, in which case no orientation is ever inferred.\n   */\n  readonly sourceFormat?: SplatSourceFormat;\n}\n\n/** Palette emitted once in chunk zero by Spark's clustered RAD SH encoding. */\nexport interface RadShCodebook {\n  readonly bands: 1 | 2 | 3;\n  /** RGB triples, coefficient-major and codebook-entry-major. */\n  readonly coefficients: Float32Array;\n  readonly count: number;\n}\n\n/** Per-splat LOD-tree links carried on a streamed `.rad` chunk's `SplatData`. */\nexport interface RadTreeData {\n  /** Number of children of splat `i`; 0 marks a leaf. */\n  readonly childCount: Uint16Array;\n  /** Global index of splat `i`'s first child; its children are the contiguous\n   * range `[childStart, childStart + childCount)`. */\n  readonly childStart: Uint32Array;\n  /**\n   * LOD node size (world units) of splat `i` - Spark's `2·expansion·avg(scale)`,\n   * the radius the runtime cut projects to a screen size. Drives foveation\n   * (see `docs/formats/rad-notes.md` M14.6): `pixel_scale = size / distance`.\n   */\n  readonly size: Float32Array;\n}\n\n/**\n * Palette-compressed higher-order SH coefficients, as in the SOG format:\n * each splat references one of up to 65,536 palette entries (its \"label\"),\n * and each entry holds the coefficients for all three color channels.\n */\nexport interface SplatShData {\n  /** SH bands beyond the DC term: 1, 2 or 3 → 3, 8 or 15 coefficients. */\n  readonly bands: number;\n  /** Per-splat palette index, `count` entries. */\n  readonly labels: Uint32Array;\n  /**\n   * Dequantized palette coefficients as an RGBA float image in the SOG\n   * centroids layout: palette entry n, coefficient c lives at column\n   * (n % 64) · coefficientCount + c, row ⌊n / 64⌋; the R, G, B channels\n   * hold that coefficient for the red, green and blue SH respectively.\n   * Uploadable directly as an RGBA32F texture.\n   */\n  readonly palette: Float32Array;\n  readonly paletteWidth: number;\n  readonly paletteHeight: number;\n}\n\n/**\n * Per-splat higher-order SH coefficients, still in their source packing:\n * one `uint32` per coefficient holding all three channels (R: bits 0-10,\n * G: bits 11-20, B: bits 21-31), dequantized across {@link range}.\n *\n * The words are kept packed all the way to the GPU - the shader unpacks them.\n * Expanding to floats would cost 45 floats per splat (~1.15 GB over a 6M-splat\n * pool) where the packed form costs 64 bytes (~384 MB) and is lossless.\n */\nexport interface SplatPackedShData {\n  /** SH bands beyond the DC term: 1, 2 or 3 → 3, 8 or 15 coefficients. */\n  readonly bands: 1 | 2 | 3;\n  /** `count * coefficients` words, splat-major. */\n  readonly packed: Uint32Array;\n  /** Per-channel dequantization range shared by every coefficient. */\n  readonly range: {\n    readonly min: readonly [number, number, number];\n    readonly max: readonly [number, number, number];\n  };\n}\n\n/** First-order spherical harmonics constant: Y₀₀ = 1 / (2√π). */\nexport const SH_C0 = 0.28209479177387814;\n\n/**\n * Folds a splat's linear scale and rotation quaternion into the upper\n * triangle of its 3D covariance matrix Σ = R·S·Sᵀ·Rᵀ (the 3DGS paper's\n * parameterization), written to `out` at `index * 6`.\n *\n * The quaternion (w, x, y, z) does not need to be normalized.\n */\nexport function writeCovariance(\n  out: Float32Array,\n  index: number,\n  scaleX: number,\n  scaleY: number,\n  scaleZ: number,\n  qw: number,\n  qx: number,\n  qy: number,\n  qz: number,\n): void {\n  const qLength = Math.hypot(qw, qx, qy, qz) || 1;\n  const w = qw / qLength;\n  const x = qx / qLength;\n  const y = qy / qLength;\n  const z = qz / qLength;\n\n  // M = R·S (rotation matrix from the quaternion, columns scaled).\n  const m00 = (1 - 2 * (y * y + z * z)) * scaleX;\n  const m01 = 2 * (x * y - w * z) * scaleY;\n  const m02 = 2 * (x * z + w * y) * scaleZ;\n  const m10 = 2 * (x * y + w * z) * scaleX;\n  const m11 = (1 - 2 * (x * x + z * z)) * scaleY;\n  const m12 = 2 * (y * z - w * x) * scaleZ;\n  const m20 = 2 * (x * z - w * y) * scaleX;\n  const m21 = 2 * (y * z + w * x) * scaleY;\n  const m22 = (1 - 2 * (x * x + y * y)) * scaleZ;\n\n  // Σ = M·Mᵀ is symmetric; store its upper triangle.\n  out[index * 6 + 0] = m00 * m00 + m01 * m01 + m02 * m02;\n  out[index * 6 + 1] = m00 * m10 + m01 * m11 + m02 * m12;\n  out[index * 6 + 2] = m00 * m20 + m01 * m21 + m02 * m22;\n  out[index * 6 + 3] = m10 * m10 + m11 * m11 + m12 * m12;\n  out[index * 6 + 4] = m10 * m20 + m11 * m21 + m12 * m22;\n  out[index * 6 + 5] = m20 * m20 + m21 * m21 + m22 * m22;\n}\n\n/**\n * Transforms an existing covariance Σ (upper triangle `m00,m01,m02,m11,m12,m22`)\n * by the 3×3 linear part `A` of a world matrix, writing Σ' = A·Σ·Aᵀ back as an\n * upper triangle. This is how a Gaussian's shape maps into a parent frame when a\n * splat cloud is placed with a world transform - the rotation/scale portion of\n * that transform (translation does not affect covariance) applied to the shape.\n *\n * Unlike {@link writeCovariance}, which *builds* Σ from a splat's scale and\n * rotation, this operates on an already-folded Σ. Non-uniform scale and shear in\n * `A` are handled exactly (the result is still a valid symmetric covariance).\n *\n * `a` is the linear part in **column-major** order - the first 9 elements of a\n * {@link https://threejs.org/docs/#api/en/math/Matrix4 | THREE.Matrix4}'s\n * `elements` layout for a matrix with no projective row, i.e.\n * `[a00, a10, a20, a01, a11, a21, a02, a12, a22]`. Reading `Matrix4.elements`\n * directly (ignoring the translation column and bottom row) yields exactly this.\n */\nexport function transformCovariance(\n  out: Float32Array,\n  outIndex: number,\n  cov: Float32Array,\n  covIndex: number,\n  a: ArrayLike<number>,\n): void {\n  // A, column-major: a[col*4 ... ] would be Matrix4; here we take the linear 3×3\n  // as elements[0..2] = column 0, [3..5] would skip - but Matrix4 stores a 4×4,\n  // so callers pass the compacted 9-element linear part described above.\n  const a00 = a[0] as number;\n  const a10 = a[1] as number;\n  const a20 = a[2] as number;\n  const a01 = a[3] as number;\n  const a11 = a[4] as number;\n  const a21 = a[5] as number;\n  const a02 = a[6] as number;\n  const a12 = a[7] as number;\n  const a22 = a[8] as number;\n\n  // Σ (symmetric) from the upper triangle.\n  const s00 = cov[covIndex * 6 + 0] as number;\n  const s01 = cov[covIndex * 6 + 1] as number;\n  const s02 = cov[covIndex * 6 + 2] as number;\n  const s11 = cov[covIndex * 6 + 3] as number;\n  const s12 = cov[covIndex * 6 + 4] as number;\n  const s22 = cov[covIndex * 6 + 5] as number;\n\n  // T = A·Σ (3×3). Rows of A dotted with columns of the symmetric Σ.\n  const t00 = a00 * s00 + a01 * s01 + a02 * s02;\n  const t01 = a00 * s01 + a01 * s11 + a02 * s12;\n  const t02 = a00 * s02 + a01 * s12 + a02 * s22;\n  const t10 = a10 * s00 + a11 * s01 + a12 * s02;\n  const t11 = a10 * s01 + a11 * s11 + a12 * s12;\n  const t12 = a10 * s02 + a11 * s12 + a12 * s22;\n  const t20 = a20 * s00 + a21 * s01 + a22 * s02;\n  const t21 = a20 * s01 + a21 * s11 + a22 * s12;\n  const t22 = a20 * s02 + a21 * s12 + a22 * s22;\n\n  // Σ' = T·Aᵀ; store the upper triangle (Σ' is symmetric).\n  out[outIndex * 6 + 0] = t00 * a00 + t01 * a01 + t02 * a02;\n  out[outIndex * 6 + 1] = t00 * a10 + t01 * a11 + t02 * a12;\n  out[outIndex * 6 + 2] = t00 * a20 + t01 * a21 + t02 * a22;\n  out[outIndex * 6 + 3] = t10 * a10 + t11 * a11 + t12 * a12;\n  out[outIndex * 6 + 4] = t10 * a20 + t11 * a21 + t12 * a22;\n  out[outIndex * 6 + 5] = t20 * a20 + t21 * a21 + t22 * a22;\n}\n"],"names":["SH_C0","writeCovariance","out","index","scaleX","scaleY","scaleZ","qw","qx","qy","qz","qLength","w","x","y","z","m00","m01","m02","m10","m11","m12","m20","m21","m22"],"mappings":"AAiIO,MAAMA,IAAQ;AASd,SAASC,EACdC,GACAC,GACAC,GACAC,GACAC,GACAC,GACAC,GACAC,GACAC,GACM;AACN,QAAMC,IAAU,KAAK,MAAMJ,GAAIC,GAAIC,GAAIC,CAAE,KAAK,GACxCE,IAAIL,IAAKI,GACTE,IAAIL,IAAKG,GACTG,IAAIL,IAAKE,GACTI,IAAIL,IAAKC,GAGTK,KAAO,IAAI,KAAKF,IAAIA,IAAIC,IAAIA,MAAMX,GAClCa,IAAM,KAAKJ,IAAIC,IAAIF,IAAIG,KAAKV,GAC5Ba,IAAM,KAAKL,IAAIE,IAAIH,IAAIE,KAAKR,GAC5Ba,IAAM,KAAKN,IAAIC,IAAIF,IAAIG,KAAKX,GAC5BgB,KAAO,IAAI,KAAKP,IAAIA,IAAIE,IAAIA,MAAMV,GAClCgB,IAAM,KAAKP,IAAIC,IAAIH,IAAIC,KAAKP,GAC5BgB,IAAM,KAAKT,IAAIE,IAAIH,IAAIE,KAAKV,GAC5BmB,IAAM,KAAKT,IAAIC,IAAIH,IAAIC,KAAKR,GAC5BmB,KAAO,IAAI,KAAKX,IAAIA,IAAIC,IAAIA,MAAMR;AAGxC,EAAAJ,EAAIC,IAAQ,IAAI,CAAC,IAAIa,IAAMA,IAAMC,IAAMA,IAAMC,IAAMA,GACnDhB,EAAIC,IAAQ,IAAI,CAAC,IAAIa,IAAMG,IAAMF,IAAMG,IAAMF,IAAMG,GACnDnB,EAAIC,IAAQ,IAAI,CAAC,IAAIa,IAAMM,IAAML,IAAMM,IAAML,IAAMM,GACnDtB,EAAIC,IAAQ,IAAI,CAAC,IAAIgB,IAAMA,IAAMC,IAAMA,IAAMC,IAAMA,GACnDnB,EAAIC,IAAQ,IAAI,CAAC,IAAIgB,IAAMG,IAAMF,IAAMG,IAAMF,IAAMG,GACnDtB,EAAIC,IAAQ,IAAI,CAAC,IAAImB,IAAMA,IAAMC,IAAMA,IAAMC,IAAMA;AACrD;"}

package/dist/splat-data.d.ts

@@ -0,0 +1,150 @@
+import type { SplatSourceFormat } from './loading';
+/**
+ * CPU-side representation of a set of 3D Gaussians, ready for GPU upload.
+ *
+ * Everything is stored in flat typed arrays (struct-of-arrays) so the data
+ * can be copied straight into textures and transferred to workers.
+ */
+export interface SplatData {
+    /** Number of Gaussians. */
+    readonly count: number;
+    /** Gaussian centers, 3 floats (x, y, z) per splat. */
+    readonly positions: Float32Array;
+    /** Base color + opacity, 4 bytes (r, g, b, a) per splat. */
+    readonly colors: Uint8Array;
+    /**
+     * 3D covariance matrices, 6 floats per splat: the upper triangle
+     * (m00, m01, m02, m11, m12, m22) of the symmetric 3×3 matrix
+     * Σ = R·S·Sᵀ·Rᵀ, precomputed from the per-splat scale and rotation.
+     */
+    readonly covariances: Float32Array;
+    /** Higher-order spherical harmonics (view-dependent color), if present. */
+    readonly sh?: SplatShData;
+    /**
+     * Per-splat (rather than palette-compressed) higher-order SH, as LCC `Quality`
+     * delivers it. Unlike {@link sh}, this survives being appended into a
+     * shared pool, because there is no per-file palette to merge.
+     */
+    readonly shPacked?: SplatPackedShData;
+    /**
+     * Scene was trained/exported with antialiasing (e.g. the SOG `antialias`
+     * meta flag). When true, {@link SplatMesh} applies the Mip-Splatting 2D
+     * filter (dilation + opacity compensation). Absent/false = classic 3DGS.
+     */
+    readonly antialias?: boolean;
+    /**
+     * Per-splat LOD-tree links for a streamed `.rad` chunk (the merged coarse
+     * nodes and leaves are all present in {@link positions} etc.). The streamed
+     * reader uses this to pick the rendered cut across chunks; other formats and
+     * the one-shot path leave it undefined. See `parse-rad.ts` and `rad.ts`.
+     */
+    readonly radTree?: RadTreeData;
+    /**
+     * Per-splat parent LOD-node size for the frontier cut (`foveationMode:
+     * 'frontier'`), sign-encoding leaf-ness: `> 0` internal node, `< 0` leaf,
+     * `|value|` is the parent's world size (a large sentinel ≈ ∞ for a root or a
+     * splat whose parent is not yet decoded). Attached by `RadFoveatedSource` as
+     * chunks stream in; uploaded into `covarianceB.w`. See `docs/formats/rad-notes.md`.
+     */
+    readonly frontierParent?: Float32Array;
+    /** Internal RAD SH codebook retained while a streamed `.rad` scene is set
+     * up. It is passed back to later chunk decodes; consumers can ignore it. */
+    readonly radShCodebook?: RadShCodebook;
+    /**
+     * The self-contained format this scene was decoded from, stamped by the
+     * loaders ({@link loadScene}/{@link loadSceneFile}). {@link SplatMesh} reads
+     * it to pick the `orientation: 'y-up'` correction. Absent on hand-built data
+     * and streamed chunks, in which case no orientation is ever inferred.
+     */
+    readonly sourceFormat?: SplatSourceFormat;
+}
+/** Palette emitted once in chunk zero by Spark's clustered RAD SH encoding. */
+export interface RadShCodebook {
+    readonly bands: 1 | 2 | 3;
+    /** RGB triples, coefficient-major and codebook-entry-major. */
+    readonly coefficients: Float32Array;
+    readonly count: number;
+}
+/** Per-splat LOD-tree links carried on a streamed `.rad` chunk's `SplatData`. */
+export interface RadTreeData {
+    /** Number of children of splat `i`; 0 marks a leaf. */
+    readonly childCount: Uint16Array;
+    /** Global index of splat `i`'s first child; its children are the contiguous
+     * range `[childStart, childStart + childCount)`. */
+    readonly childStart: Uint32Array;
+    /**
+     * LOD node size (world units) of splat `i` - Spark's `2·expansion·avg(scale)`,
+     * the radius the runtime cut projects to a screen size. Drives foveation
+     * (see `docs/formats/rad-notes.md` M14.6): `pixel_scale = size / distance`.
+     */
+    readonly size: Float32Array;
+}
+/**
+ * Palette-compressed higher-order SH coefficients, as in the SOG format:
+ * each splat references one of up to 65,536 palette entries (its "label"),
+ * and each entry holds the coefficients for all three color channels.
+ */
+export interface SplatShData {
+    /** SH bands beyond the DC term: 1, 2 or 3 → 3, 8 or 15 coefficients. */
+    readonly bands: number;
+    /** Per-splat palette index, `count` entries. */
+    readonly labels: Uint32Array;
+    /**
+     * Dequantized palette coefficients as an RGBA float image in the SOG
+     * centroids layout: palette entry n, coefficient c lives at column
+     * (n % 64) · coefficientCount + c, row ⌊n / 64⌋; the R, G, B channels
+     * hold that coefficient for the red, green and blue SH respectively.
+     * Uploadable directly as an RGBA32F texture.
+     */
+    readonly palette: Float32Array;
+    readonly paletteWidth: number;
+    readonly paletteHeight: number;
+}
+/**
+ * Per-splat higher-order SH coefficients, still in their source packing:
+ * one `uint32` per coefficient holding all three channels (R: bits 0-10,
+ * G: bits 11-20, B: bits 21-31), dequantized across {@link range}.
+ *
+ * The words are kept packed all the way to the GPU - the shader unpacks them.
+ * Expanding to floats would cost 45 floats per splat (~1.15 GB over a 6M-splat
+ * pool) where the packed form costs 64 bytes (~384 MB) and is lossless.
+ */
+export interface SplatPackedShData {
+    /** SH bands beyond the DC term: 1, 2 or 3 → 3, 8 or 15 coefficients. */
+    readonly bands: 1 | 2 | 3;
+    /** `count * coefficients` words, splat-major. */
+    readonly packed: Uint32Array;
+    /** Per-channel dequantization range shared by every coefficient. */
+    readonly range: {
+        readonly min: readonly [number, number, number];
+        readonly max: readonly [number, number, number];
+    };
+}
+/** First-order spherical harmonics constant: Y₀₀ = 1 / (2√π). */
+export declare const SH_C0 = 0.28209479177387814;
+/**
+ * Folds a splat's linear scale and rotation quaternion into the upper
+ * triangle of its 3D covariance matrix Σ = R·S·Sᵀ·Rᵀ (the 3DGS paper's
+ * parameterization), written to `out` at `index * 6`.
+ *
+ * The quaternion (w, x, y, z) does not need to be normalized.
+ */
+export declare function writeCovariance(out: Float32Array, index: number, scaleX: number, scaleY: number, scaleZ: number, qw: number, qx: number, qy: number, qz: number): void;
+/**
+ * Transforms an existing covariance Σ (upper triangle `m00,m01,m02,m11,m12,m22`)
+ * by the 3×3 linear part `A` of a world matrix, writing Σ' = A·Σ·Aᵀ back as an
+ * upper triangle. This is how a Gaussian's shape maps into a parent frame when a
+ * splat cloud is placed with a world transform - the rotation/scale portion of
+ * that transform (translation does not affect covariance) applied to the shape.
+ *
+ * Unlike {@link writeCovariance}, which *builds* Σ from a splat's scale and
+ * rotation, this operates on an already-folded Σ. Non-uniform scale and shear in
+ * `A` are handled exactly (the result is still a valid symmetric covariance).
+ *
+ * `a` is the linear part in **column-major** order - the first 9 elements of a
+ * {@link https://threejs.org/docs/#api/en/math/Matrix4 | THREE.Matrix4}'s
+ * `elements` layout for a matrix with no projective row, i.e.
+ * `[a00, a10, a20, a01, a11, a21, a02, a12, a22]`. Reading `Matrix4.elements`
+ * directly (ignoring the translation column and bottom row) yields exactly this.
+ */
+export declare function transformCovariance(out: Float32Array, outIndex: number, cov: Float32Array, covIndex: number, a: ArrayLike<number>): void;

package/dist/splat-depth-pack.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 24-bit RGB packing for linear view-space depth used by GPU splat picking.
+ *
+ * Depth is stored as a normalized value in [0, 1] mapped across the camera
+ * near/far range, then quantized into three 8-bit channels (R = high byte).
+ * This matches an RGBA8 render target without a depth-texture readback path.
+ */
+import * as THREE from 'three/webgpu';
+/**
+ * Packs a normalized depth in [0, 1] into 8-bit RGB (high → low).
+ * Values outside [0, 1] are clamped.
+ */
+export declare function packNormalizedDepth(normalized: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Unpacks 8-bit RGB channels back to a normalized depth in [0, 1].
+ */
+export declare function unpackNormalizedDepth(r: number, g: number, b: number): number;
+/**
+ * Maps a positive linear view-space depth (OpenGL: −z) into [0, 1] using the
+ * camera near/far plane. Clamps to the range.
+ */
+export declare function normalizeViewDepth(viewDepth: number, near: number, far: number): number;
+/**
+ * Inverse of {@link normalizeViewDepth}.
+ */
+export declare function denormalizeViewDepth(normalized: number, near: number, far: number): number;
+/**
+ * Reconstructs a world-space hit from NDC and a positive view-space depth
+ * (−z in OpenGL camera space). Writes into `outPoint` and returns camera
+ * distance. The camera must have an up-to-date world matrix.
+ */
+export declare function unprojectViewDepth(ndcX: number, ndcY: number, viewDepth: number, camera: THREE.Camera, outPoint: THREE.Vector3): {
+    point: THREE.Vector3;
+    distance: number;
+};