@playcanvas/splat-transform 2.0.3 → 2.0.5

package/dist/lib/voxel/voxel-query.d.ts

@@ -24,14 +24,14 @@ interface BlockGridParams {
     strideZ: number;
 }
 /**
- * Build block lookup structures from the buffer's Morton codes.
+ * Build block lookup structures from the buffer's linear block indices.
+ * The buffer's keys are already linear block indices, so this is a direct
+ * copy into a Set / Map for O(1) random access.
  *
  * @param buffer - Block mask buffer containing voxelized blocks.
- * @param strideY - numBlocksX (stride for Y dimension).
- * @param strideZ - numBlocksX * numBlocksY (stride for Z dimension).
  * @returns Solid block set, mixed block map (linear index to masks array index), and masks.
  */
-declare const buildBlockLookup: (buffer: BlockMaskBuffer, strideY: number, strideZ: number) => BlockLookup;
+declare const buildBlockLookup: (buffer: BlockMaskBuffer) => BlockLookup;
 /**
  * Test whether a Gaussian's center lies inside an occupied voxel.
  *
@@ -45,11 +45,15 @@ declare const buildBlockLookup: (buffer: BlockMaskBuffer, strideY: number, strid
  */
 declare const isCenterInOccupiedVoxel: (px: number, py: number, pz: number, grid: BlockGridParams, lookup: BlockLookup, blockFilter?: Set<number>) => boolean;
 /**
- * Test whether a Gaussian has meaningful contribution at any occupied voxel
- * center within its AABB range.
+ * Test whether a Gaussian has meaningful contribution at occupied voxel
+ * centers in blocks that overlap its AABB.
  *
  * Iterates over blocks that overlap the Gaussian's AABB, then evaluates the
- * Gaussian's opacity contribution at each occupied voxel center in those blocks.
+ * Gaussian's opacity contribution at each occupied voxel center in those
+ * blocks. Returns true once `minHits` qualifying voxels are found. With the
+ * default `minHits = 1` this short-circuits on the first hit; larger values
+ * let callers reject elongated outliers (e.g. spikes) whose tails clip only
+ * a single cluster voxel.
  *
  * @param gaussianIdx - Index of the Gaussian.
  * @param columns - Gaussian column data arrays.
@@ -57,7 +61,8 @@ declare const isCenterInOccupiedVoxel: (px: number, py: number, pz: number, grid
  * @param lookup - Block lookup structures.
  * @param minContribution - Minimum contribution threshold.
  * @param blockFilter - Optional set of block indices to restrict the test to.
- * @returns True if the Gaussian contributes above threshold at any qualifying voxel.
+ * @param minHits - Minimum number of qualifying voxels required. Default 1.
+ * @returns True if at least `minHits` qualifying voxels were found.
  */
-declare const gaussianContributesToVoxels: (gaussianIdx: number, columns: GaussianColumns, grid: BlockGridParams, lookup: BlockLookup, minContribution: number, blockFilter?: Set<number>) => boolean;
+declare const gaussianContributesToVoxels: (gaussianIdx: number, columns: GaussianColumns, grid: BlockGridParams, lookup: BlockLookup, minContribution: number, blockFilter?: Set<number>, minHits?: number) => boolean;
 export { buildBlockLookup, isCenterInOccupiedVoxel, gaussianContributesToVoxels, type BlockLookup, type BlockGridParams };

package/dist/lib/writers/collision-glb.d.ts

@@ -1,18 +1,17 @@
 import type { Bounds } from '../data-table';
-import { BlockMaskBuffer } from '../voxel/block-mask-buffer';
+import type { CollisionMeshShape } from '../types';
+import { SparseVoxelGrid } from '../voxel/sparse-voxel-grid';
 /**
  * Extract a collision mesh from voxel data and encode it as a GLB file.
  *
- * Runs marching cubes on the voxel surface, then a lossless coplanar-merge
- * pass that fuses the redundant axis-aligned triangles inside each
- * voxel-face plane into greedy-style quads while leaving the corner-cutting
- * bevel triangles untouched. The output surface is identical to the raw MC
- * surface but typically has 1-2 orders of magnitude fewer triangles.
+ * Generates collision geometry from voxel data using either the smooth
+ * marching-cubes path or a direct watertight voxel-face mesh.
  *
- * @param blockBuffer - Voxel block data after filtering
+ * @param grid - Voxel grid after filtering / nav phases
  * @param gridBounds - Grid bounds aligned to block boundaries
  * @param voxelResolution - Size of each voxel in world units
+ * @param shape - Collision mesh shape to generate
  * @returns GLB bytes, or null if no triangles were generated
  */
-declare const buildCollisionMesh: (blockBuffer: BlockMaskBuffer, gridBounds: Bounds, voxelResolution: number) => Uint8Array | null;
+declare const buildCollisionMesh: (grid: SparseVoxelGrid, gridBounds: Bounds, voxelResolution: number, shape?: CollisionMeshShape) => Uint8Array | null;
 export { buildCollisionMesh };

package/dist/lib/writers/sparse-octree.d.ts

@@ -1,5 +1,5 @@
 import type { Bounds } from '../data-table';
-import { BlockMaskBuffer } from '../voxel/block-mask-buffer';
+import { SparseVoxelGrid } from '../voxel/sparse-voxel-grid';
 /**
  * Solid leaf node marker: childMask = 0xFF, baseOffset = 0.
  * This is unambiguous because BFS layout guarantees children always come after
@@ -29,26 +29,27 @@ interface SparseOctree {
     /** Voxel masks for mixed leaves: pairs of u32 (lo, hi) */
     leafData: Uint32Array;
 }
+interface BuildSparseOctreeOptions {
+    /** Release the input grid's backing storage after the octree has copied the data it needs. */
+    consumeGrid?: boolean;
+    /** Force dense-mip construction; intended for tests and benchmarks. */
+    dense?: boolean;
+}
 /**
- * Build a sparse octree from accumulated voxelization blocks.
- *
- * Uses Structure-of-Arrays (SoA) representation and linear scans on sorted
- * Morton codes instead of Maps and per-node objects for performance.
+ * Build a sparse octree from a SparseVoxelGrid.
  *
- * **Mutates `buffer` in place.** Phase 1 sorts the buffer's solid-morton,
- * mixed-morton, and mixed-mask typed arrays directly (no SoA copy) to keep
- * peak memory low on very large grids. After this call the buffer's blocks
- * are still semantically equivalent — same morton/mask pairs — but reordered
- * by morton ascending. Callers must not rely on insertion order being
- * preserved across this call.
+ * Walks the grid's `types` array word-by-word (skipping empty words), counts
+ * solid + mixed blocks, then emits Morton-keyed (solidStream, mixedStream,
+ * mixedMasks) typed arrays sized exactly. The streams are then sorted; this
+ * is the only place Morton encoding is paid in the post-voxelization pipeline.
  *
- * @param buffer - BlockMaskBuffer containing voxelized blocks. Mutated:
- * solid mortons, mixed mortons, and mixed masks are sorted in place.
+ * @param grid - SparseVoxelGrid containing voxelized blocks.
  * @param gridBounds - Grid bounds aligned to block boundaries
  * @param sceneBounds - Original scene bounds
  * @param voxelResolution - Size of each voxel in world units
+ * @param options - Build options.
  * @returns Sparse octree structure
  */
-declare function buildSparseOctree(buffer: BlockMaskBuffer, gridBounds: Bounds, sceneBounds: Bounds, voxelResolution: number): SparseOctree;
+declare function buildSparseOctree(grid: SparseVoxelGrid, gridBounds: Bounds, sceneBounds: Bounds, voxelResolution: number, options?: BuildSparseOctreeOptions): SparseOctree;
 export { buildSparseOctree, SOLID_LEAF_MARKER };
 export type { SparseOctree };

package/dist/lib/writers/write-voxel.d.ts

@@ -1,6 +1,7 @@
 import { DataTable } from '../data-table';
 import { type FileSystem } from '../io/write';
-import type { DeviceCreator } from '../types';
+import type { CollisionMeshShape, DeviceCreator } from '../types';
+import { type SparseOctree } from './sparse-octree';
 import { type NavSeed } from '../voxel';
 /**
  * Options for writing a voxel octree file.
@@ -29,8 +30,8 @@ type WriteVoxelOptions = {
     floorFill?: boolean;
     /** When `floorFill` is enabled, dilation radius in world units used to identify "interior" XZ columns to patch. Empty XZ areas larger than `2 * floorFillDilation` from any solid column are treated as exterior and left empty. Default: 0 (patch every empty column). */
     floorFillDilation?: number;
-    /** When `true`, a collision mesh (.collision.glb) is generated alongside the voxel output, using marching cubes followed by lossless coplanar merge. */
-    collisionMesh?: boolean;
+    /** When set, a collision mesh (.collision.glb) is generated alongside the voxel output. `true` is equivalent to `smooth`. */
+    collisionMesh?: boolean | CollisionMeshShape;
 };
 /**
  * Metadata for a voxel octree file.
@@ -63,6 +64,14 @@ interface VoxelMetadata {
     /** Total number of Uint32 entries in the leafData array */
     leafDataCount: number;
 }
+/**
+ * Write octree data to files.
+ *
+ * @param fs - File system for writing output files.
+ * @param jsonFilename - Output filename for JSON metadata.
+ * @param octree - Sparse octree structure to write.
+ */
+declare const writeOctreeFiles: (fs: FileSystem, jsonFilename: string, octree: SparseOctree) => Promise<void>;
 /**
  * Voxelizes Gaussian splat data and writes the result as a sparse voxel octree.
  *
@@ -70,7 +79,7 @@ interface VoxelMetadata {
  * and outputs two or three files:
  * - `filename` (.voxel.json) - JSON metadata including bounds, resolution, and array sizes
  * - Corresponding .voxel.bin - Binary octree data (nodes + leafData as Uint32 arrays)
- * - Corresponding .collision.glb - Triangle mesh extracted via marching cubes (GLB format, optional)
+ * - Corresponding .collision.glb - Triangle mesh extracted from the voxel output (GLB format, optional)
  *
  * The binary file layout is:
  * - Bytes 0 to (nodeCount * 4 - 1): nodes array (Uint32, little-endian)
@@ -95,4 +104,4 @@ interface VoxelMetadata {
  * ```
  */
 declare const writeVoxel: (options: WriteVoxelOptions, fs: FileSystem) => Promise<void>;
-export { writeVoxel, type WriteVoxelOptions, type VoxelMetadata };
+export { writeVoxel, writeOctreeFiles, type WriteVoxelOptions, type VoxelMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/splat-transform",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "author": "PlayCanvas<support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Library and CLI tool for 3D Gaussian splat format conversion and transformation",