@voluma/vlam 0.3.2 → 0.4.0

package/README.md

@@ -51,7 +51,7 @@ renderer.setAnimationLoop(() => {
 ```
 
 
-Supported formats: `.sog`, `.ply`, `.spz`, `.splat`, `.ksplat`, `.lcc`, `.lcc2`, `.rad`, `.radc`. 
+Supported formats: `.sog`, `.ply`, `.spz`, `.splat`, `.ksplat`, `.lcc`, `.lcc2`, `.rad`. 
 
 
 ## Contributing
@@ -62,4 +62,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/architecture.md](docs/architect
 
 [MIT](LICENSE). Third-party notices: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
-Made in the EU by [Voluma](https://voluma.ai).
+Made by [Voluma](https://voluma.ai).

package/dist/core/compute-sorter.d.ts

@@ -1,5 +1,6 @@
 import * as THREE from 'three/webgpu';
 import type { SplatSorter } from './sorter';
+import type { SplatSortMetric } from './splat-mesh-types';
 import type { uniformArray } from 'three/tsl';
 /**
  * Optional per-source world transform for a unified {@link MergedSplatMesh} pool.
@@ -78,7 +79,9 @@ export declare class ComputeSorter implements SplatSorter {
     private readonly mirrors;
     /** Set by {@link dispose}; makes a second dispose a no-op. */
     private disposed;
-    /** Row 2 of the model-view matrix; view-space z = row2 · (position, 1). */
+    /** Rows of the model-view matrix used by the selected sort metric. */
+    private readonly viewRow0;
+    private readonly viewRow1;
     private readonly viewRow2;
     private readonly depthMin;
     private readonly depthScale;
@@ -87,6 +90,7 @@ export declare class ComputeSorter implements SplatSorter {
     /** Highest bucket index this sort uses; see {@link effectiveBucketCount}. */
     private readonly bucketMax;
     private readonly viewCenter;
+    private readonly sortMetric;
     constructor(options: {
         renderer: THREE.WebGPURenderer;
         /** Pool capacity in splats; all buffers are sized once from this. */
@@ -103,6 +107,8 @@ export declare class ComputeSorter implements SplatSorter {
         sourceIndexAttribute: THREE.StorageBufferAttribute;
         /** Per-source world transform for a unified pool; omit for a single mesh. */
         perSource?: PerSourceSortTransform;
+        /** Camera-space ordering key. Default `'depth'`. */
+        sortMetric?: SplatSortMetric;
     });
     /**
      * Buckets to actually use for `activeCount` splats, rounded up to a power of

package/dist/core/index.d.ts

@@ -14,7 +14,7 @@
  *  - `@voluma/vlam/effects` - tree-shakeable modifier presets
  *  - `@voluma/vlam/formats/ply` - 3DGS `.ply`, raw and compressed
  *  - `@voluma/vlam/formats/sog` - PlayCanvas SOG, bundled and unbundled
- *  - `@voluma/vlam/formats/rad` - Spark `.rad`/`.radc`
+ *  - `@voluma/vlam/formats/rad` - Spark `.rad`
  *  - `@voluma/vlam/formats/lcc` - XGRIDS LCC / `.lcc2` + collision helpers
  *  - `@voluma/vlam/formats/spz` - Niantic `.spz`
  *  - `@voluma/vlam/formats/splat` - antimatter15 `.splat`
@@ -25,7 +25,7 @@
  *
  * @module core
  */
-export { SplatMesh, MAX_SH_BANDS, DEFAULT_FOVEATION_TARGET_PX, DEFAULT_FOVEATION_DRAW_BUDGET, resolveSplatPerformanceProfile, type UnifiedSourceView, type SplatMeshOptions, type SplatUpdateOptions, type SplatSortStrategy, type SplatPerformanceProfile, type SplatFoveationMode, type SplatRange, type SplatPickOptions, type SplatPickResult, type SplatNearestResult, type SplatRayResult, type SplatHeightResult, type SplatChannelType, type SplatChannelOptions, } from './splat-mesh';
+export { SplatMesh, MAX_SH_BANDS, DEFAULT_FOVEATION_TARGET_PX, DEFAULT_FOVEATION_DRAW_BUDGET, resolveSplatPerformanceProfile, type UnifiedSourceView, type SplatMeshOptions, type SplatUpdateOptions, type SplatSortStrategy, type SplatSortMetric, type SplatPerformanceProfile, type SplatFoveationMode, type SplatRange, type SplatPickOptions, type SplatPickResult, type SplatNearestResult, type SplatRayResult, type SplatHeightResult, type SplatChannelType, type SplatChannelOptions, } from './splat-mesh';
 export { SplatPool, type SplatPoolOptions } from './splat-mesh-pool';
 export { SPLAT_DATA_TEXTURE_WIDTH, deviceMaxTextureSize, assertPoolRowsFitDevice, } from './splat-mesh-pool';
 export { MAX_DOF_RADIUS_PX, MAX_DOF_VARIANCE, apertureAngleFromSize, computeDofCocVariancePx2, computeDofOpacityFade, clampDepthOfFieldSettings, type DepthOfFieldSettings, } from './depth-of-field';

package/dist/core/radix-sorter.d.ts

@@ -4,6 +4,7 @@
  */
 import * as THREE from 'three/webgpu';
 import type { SplatSorter } from './sorter';
+import type { SplatSortMetric } from './splat-mesh-types';
 /**
  * Stable four-bit-per-pass WebGPU radix sorter.
  *
@@ -22,6 +23,8 @@ export declare class RadixSorter implements SplatSorter {
     private readonly mirrors;
     /** Set by {@link dispose}; makes a second dispose a no-op. */
     private disposed;
+    private readonly viewRow0;
+    private readonly viewRow1;
     private readonly viewRow2;
     private readonly depthMin;
     private readonly depthScale;
@@ -29,6 +32,7 @@ export declare class RadixSorter implements SplatSorter {
     private readonly viewCenter;
     /** Exact mode avoids scene-bounds quantization entirely. */
     private readonly exactDepth;
+    private readonly sortMetric;
     constructor(options: {
         renderer: THREE.WebGPURenderer;
         capacity: number;
@@ -40,6 +44,8 @@ export declare class RadixSorter implements SplatSorter {
         sourceIndexAttribute: THREE.StorageBufferAttribute;
         /** Keep every Float32 depth bit instead of quantizing to 24 bits. */
         exactDepth?: boolean;
+        /** Camera-space ordering key. Default `'depth'`. */
+        sortMetric?: SplatSortMetric;
     });
     sort(modelView: THREE.Matrix4, activeCount: number, bounds: THREE.Sphere): boolean;
     dispose(): void;

package/dist/core/sort-worker-protocol.d.ts

@@ -21,6 +21,8 @@ export interface WriteMessage {
 }
 export interface SortMessage {
     type: 'sort';
+    /** Camera-space ordering key. */
+    sortMetric: 'depth' | 'radial';
     /** Column-major 4×4 model-view matrix elements. */
     modelView: Float32Array;
     /** Active ranges as (start, count) pairs of pool splat indices, in

package/dist/core/sorter.d.ts

@@ -5,10 +5,10 @@ import type * as THREE from 'three/webgpu';
  *
  *  - `ComputeSorter`: GPU counting sort in TSL compute (WebGPU backend);
  *    supports dynamic-capacity meshes via source-index indirection.
- *  - `WorkerSorter`: CPU counting sort in a Web Worker (WebGL2 fallback,
- *    which has no compute shaders); handles static and dynamic-capacity
- *    (streamed) meshes alike by mirroring the pool's centers and sorting
- *    the active spans.
+ *  - `WorkerSorter`: stable CPU radix sort in a Web Worker (the WebGL2
+ *    fallback and an explicit WebGPU stability option); handles static and
+ *    dynamic-capacity meshes alike by mirroring the pool's centers and
+ *    sorting the active spans.
  *  - `RadixSorter`: experimental GPU radix (opt-in via `sortStrategy: 'radix'`).
  */
 export type SplatSorterKind = 'counting' | 'radix' | 'worker';

package/dist/core/splat-mesh-types.d.ts

@@ -66,18 +66,33 @@ export interface SplatMeshOptions {
     /**
      * Minimum interval between WebGPU sorts while the camera moves. When
      * omitted, the interval adapts to the active splat count. Use `0` to sort
-     * every changed frame. WebGL worker sorting is unaffected.
+     * every changed frame. WebGL worker sorting is unaffected; a worker selected
+     * explicitly on WebGPU still observes this submission cadence.
      */
     sortIntervalMs?: number;
     /**
      * WebGPU sorter used for A/B validation. Defaults to the proven counting
-     * sorter. `'radix'` keeps the fast 24-bit key path; `'exact'` lazy-loads a
-     * stable 32-bit Float32-depth radix path that avoids scene-range
-     * quantization. The first frames may skip sorting until the module resolves.
+     * sorter. `'worker'` keeps rendering on WebGPU but sorts asynchronously in
+     * the stable CPU worker also used by the WebGL fallback; this is useful for
+     * Spark-like temporal stability on captures with extreme position outliers.
+     * `'radix'` keeps the fast 24-bit GPU key path; `'exact'` lazy-loads a 32-bit
+     * Float32-depth GPU radix path. The first frames may skip GPU radix sorting
+     * until the module resolves.
      *
      * @experimental Radix strategies may change in a minor release.
      */
     sortStrategy?: SplatSortStrategy;
+    /**
+     * Geometric key used to order transparent splats back-to-front.
+     *
+     * `'depth'` (default) sorts along the camera's view axis and gives the most
+     * accurate alpha order for a fixed view. `'radial'` sorts by distance from
+     * the camera, matching Spark's stable default: camera rotation alone leaves
+     * the order unchanged, which greatly reduces whole-scene shimmer while
+     * orbiting dense captures. Pair it with `sortStrategy: 'exact'` when extreme
+     * position outliers would make quantized buckets too coarse.
+     */
+    sortMetric?: SplatSortMetric;
     /**
      * Render-quality policy. `smooth` rejects negligible projected contributions.
      *
@@ -272,7 +287,9 @@ export interface SplatMeshOptions {
     maxTextureSize?: number;
 }
 /** Available WebGPU depth-sort implementations. */
-export type SplatSortStrategy = 'counting' | 'radix' | 'exact';
+export type SplatSortStrategy = 'counting' | 'worker' | 'radix' | 'exact';
+/** Camera-space key used for back-to-front splat ordering. */
+export type SplatSortMetric = 'depth' | 'radial';
 /** Controls optional work during a per-frame source update. */
 export interface SplatUpdateOptions {
     /** Leave sorting to {@link UnifiedSplatMesh}; uploads and LOD state still update. */

package/dist/core/splat-mesh.d.ts

@@ -194,8 +194,10 @@ export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
      * storage-attribute GPU buffers that never sat in a geometry. */
     private lastRenderer;
     private readonly currentModelView;
+    /** Pose components that can actually change the selected sort key. */
+    private readonly currentSortState;
     /** Initialized to an impossible matrix so the first frame always sorts. */
-    private readonly lastSortedModelView;
+    private readonly lastSortedState;
     private readonly sortScheduler;
     /** One-frame queue-headroom hint used before a staged atomic commit. */
     private deferSortRequestOnce;
@@ -204,6 +206,7 @@ export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
     /** The active list the current depth order was built from. */
     private sortedActiveListVersion;
     private readonly sortStrategy;
+    private readonly sortMetric;
     /** Resolved only when `sortStrategy === 'radix'`; see {@link ensureRadixSorter}. */
     private RadixSorterCtor;
     private radixSorterLoad;
@@ -604,7 +607,7 @@ export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
     renderView(camera: THREE.PerspectiveCamera, renderer: THREE.WebGPURenderer, target?: THREE.RenderTarget | null): void;
     /**
      * Sorts the shared order buffer for a secondary view's camera, bypassing the
-     * primary view's sort scheduler and its `lastSortedModelView` record (that
+     * primary view's sort scheduler and its last-sorted pose record (that
      * state belongs to `update()`'s camera). WebGPU dispatches synchronously into
      * the render queue, so the following draw reads this order.
      */
@@ -722,6 +725,12 @@ export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
      * order then changes without any camera motion.
      */
     protected invalidateSort(): void;
+    /**
+     * Writes the camera/mesh state that can change the selected ordering key.
+     * Radial distance is invariant under camera rotation, so its state contains
+     * the mesh's world linear transform and camera-relative translation only.
+     */
+    private writeSortState;
     private createSorter;
     /** Prefetches the experimental radix sorter; safe to call repeatedly. */
     private ensureRadixSorter;

package/dist/core/splat-sort-bounds.d.ts

@@ -9,3 +9,20 @@ import type * as THREE from 'three/webgpu';
  * compose into a shear.
  */
 export declare function viewDepthRadius(modelView: THREE.Matrix4, radius: number): number;
+/**
+ * A conservative camera-space radius for radial-distance quantization.
+ *
+ * Uses `sqrt(||A^T A||∞)`, an upper bound on the linear part's largest
+ * singular value. Unlike `Matrix4.getMaxScaleOnAxis()`, it cannot under-bound
+ * a sphere when a transformed hierarchy introduces shear.
+ */
+export declare function viewRadialRadius(modelView: THREE.Matrix4, radius: number): number;
+/**
+ * Builds the pose signature relevant to radial sorting.
+ *
+ * World-space distance depends on the mesh's linear transform and its
+ * translation relative to the camera, but not on camera orientation. The
+ * scheduler compares this matrix so rotating in place does not dispatch an
+ * identical radial sort.
+ */
+export declare function radialSortState(meshWorld: THREE.Matrix4, cameraWorld: THREE.Matrix4, out: THREE.Matrix4): THREE.Matrix4;

package/dist/core/worker-sorter.d.ts

@@ -1,10 +1,11 @@
 import type * as THREE from 'three/webgpu';
 import type { SplatSorter } from './sorter';
+import type { SplatSortMetric } from './splat-mesh-types';
 /**
- * CPU depth sorter: counting sort in a Web Worker. Used on the WebGL2
- * fallback backend, which has no compute shaders. Works for static and
- * dynamic-capacity (streamed) meshes alike: the worker keeps a mirror of
- * the pool's centers, and each sort covers only the active pool spans.
+ * Stable CPU radix sorter in a Web Worker. Used by the WebGL2 fallback and,
+ * when explicitly selected, alongside WebGPU rendering for Spark-like sort
+ * cadence. Works for static and dynamic-capacity meshes alike: the worker
+ * keeps a mirror of the pool's centers and sorts only the active spans.
  *
  * One sort runs at a time; requests that arrive while the worker is busy
  * are declined so the caller retries with the then-current camera on a
@@ -15,6 +16,7 @@ export declare class WorkerSorter implements SplatSorter {
     private readonly worker;
     private readonly splatIndexAttribute;
     private readonly host;
+    private readonly sortMetric;
     private inFlight;
     /** Set by {@link dispose}; drops any already-delivered order message. */
     private disposed;
@@ -25,7 +27,7 @@ export declare class WorkerSorter implements SplatSorter {
     private lastSubmittedAt;
     private lastCompletedAt;
     private lastLatencyMs;
-    constructor(host: WorkerSorterHost);
+    constructor(host: WorkerSorterHost, sortMetric?: SplatSortMetric);
     sort(modelView: THREE.Matrix4, _activeCount: number, _bounds: THREE.Sphere): boolean;
     /** Internal timing diagnostics used by the demo's opt-in XR A/B harness. */
     snapshot(): {