Add collision mesh generation for voxel output

[slimbuck]

Summary

• Add optional collision mesh generation (--collision-mesh / -K) that extracts a triangle mesh from voxel data using marching cubes and writes it as a .collision.glb file alongside the existing voxel output
• Mesh is simplified using meshoptimizer with a configurable triangle reduction ratio (--mesh-simplify / -T, default 0.25)
• GLB output is a minimal glTF 2.0 binary containing only positions and indices, suitable for runtime collision detection

Details

New modules:

• src/lib/voxel/marching-cubes.ts — Marching cubes surface extraction from the BlockAccumulator voxel data, with vertex deduplication and proper handling of block boundaries
• src/lib/voxel/collision-glb.ts — Minimal GLB file builder (positions + triangle indices, no materials/normals)

The pipeline runs after voxel filtering: marching cubes extracts the raw surface, MeshoptSimplifier reduces triangle count (with absolute error bounded by voxel resolution), unused vertices are compacted, and the result is written as a .collision.glb.

New CLI options:

• -K, --collision-mesh — Enable collision mesh generation
• -T, --mesh-simplify <n> — Ratio of triangles to keep (0–1, default 0.25)

New library options in WriteVoxelOptions:

• collisionMesh?: boolean
• meshSimplify?: number

New public exports:

• marchingCubes(accumulator, gridBounds, voxelResolution) → MarchingCubesMesh

New dependency:

• meshoptimizer (runtime)

Usage

# Generate voxel data with collision mesh
splat-transform -K input.ply output.voxel.json

# Custom simplification ratio (keep 50% of triangles)
splat-transform -K -T 0.5 input.ply output.voxel.json

[Copilot]

Pull request overview

Adds optional collision-mesh generation to the voxel export pipeline, producing a simplified .collision.glb alongside the existing .voxel.json/.voxel.bin outputs.

Changes:

• Add --collision-mesh (-K) and --mesh-simplify (-T) CLI options and plumb them through library Options into writeVoxel.
• Implement marching-cubes surface extraction from voxel blocks and a minimal GLB (glTF 2.0) binary writer for positions + indices.
• Integrate mesh simplification via meshoptimizer and emit .collision.glb next to voxel output.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/lib/writers/write-voxel.ts	Adds collision-mesh extraction + simplification + optional .collision.glb write in voxel pipeline
src/lib/write.ts	Forwards new voxel collision options into writeVoxel
src/lib/voxel/marching-cubes.ts	New marching-cubes implementation over BlockAccumulator voxel data
src/lib/voxel/collision-glb.ts	New minimal GLB builder (positions + indices)
src/lib/voxel/index.ts	Re-exports marchingCubes, types, and buildCollisionGlb from voxel module barrel
src/lib/types.ts	Extends public Options with collisionMesh and meshSimplify
src/lib/index.ts	Exposes marchingCubes and MarchingCubesMesh at top-level library API
src/cli/index.ts	Adds CLI flags, parses values, updates help text/examples
package.json	Adds runtime dependency on meshoptimizer
package-lock.json	Locks new dependency and updates dependency graph metadata

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Adds optional collision-mesh generation to the voxel output pipeline, extracting a triangle surface from the voxelized scene (marching cubes), simplifying it (meshoptimizer), and writing it as a sibling .collision.glb file for runtime collision use.

Changes:

• Add --collision-mesh/-K and --mesh-simplify/-T CLI options and plumb them through library options.
• Implement marching-cubes surface extraction from BlockAccumulator voxel data.
• Implement a minimal GLB builder (positions + indices) and integrate mesh simplification + GLB writing into writeVoxel.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/lib/writers/write-voxel.ts	Integrates optional collision mesh extraction/simplification/GLB writing into the voxel writer.
src/lib/write.ts	Passes new collision-mesh options through the high-level write dispatcher.
src/lib/voxel/marching-cubes.ts	New marching-cubes implementation over sparse voxel blocks with boundary handling + vertex dedup.
src/lib/voxel/collision-glb.ts	New minimal GLB (glTF 2.0) binary writer for collision meshes.
src/lib/voxel/index.ts	Re-exports marching cubes types/functions and GLB builder from voxel module entrypoint.
src/lib/types.ts	Extends global options typing with collision mesh settings.
src/lib/index.ts	Exposes marching cubes types/functions at the top-level library entrypoint.
src/cli/index.ts	Adds CLI flags, parsing, and validation for collision mesh generation + simplify ratio.
package.json	Adds meshoptimizer runtime dependency.
package-lock.json	Locks meshoptimizer dependency and updates lockfile entries accordingly.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Adds an optional post-voxelization pipeline to extract a surface mesh from voxel occupancy (marching cubes), simplify it with meshoptimizer, and emit a minimal .collision.glb alongside the existing .voxel.json/.voxel.bin outputs.

Changes:

• Introduces marching-cubes surface extraction and a minimal collision GLB writer.
• Adds CLI + library options to enable collision mesh generation and control simplification ratio.
• Integrates mesh extraction/simplification/GLB write into the voxel writer and wires options through the high-level writeFile path.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/lib/writers/write-voxel.ts	Adds collision-mesh extraction, simplification, GLB generation, and writing alongside voxel output.
src/lib/write.ts	Passes new collision-mesh options through to writeVoxel.
src/lib/voxel/marching-cubes.ts	New marching cubes implementation over BlockAccumulator with vertex deduplication and boundary handling.
src/lib/voxel/collision-glb.ts	New minimal GLB builder for positions + indices.
src/lib/voxel/index.ts	Re-exports marching cubes types/functions (and currently also exports the GLB builder).
src/lib/types.ts	Adds collisionMesh / meshSimplify to shared Options.
src/lib/index.ts	Exposes marching cubes as a top-level library export.
src/cli/index.ts	Adds -K/--collision-mesh and -T/--mesh-simplify with validation + help text updates.
package.json	Adds runtime dependency on meshoptimizer.
package-lock.json	Locks meshoptimizer and updates lock metadata accordingly.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.