SpatialAssembler

Native Node.js addon for high-performance GLB assembly from point clouds and meshes.

Overview

Generates GLB (glTF Binary) 3D models from point clouds, indexed meshes, and typed atomic data — the geometry engine behind VOLT's 3D visualization pipeline.


Package	`@voltstack/spatial-assembler`
Language	C++17 with Node.js NAPI bindings
Platform	Linux x64
Links	GitHub · npm

Installation

npm install @voltstack/spatial-assembler

API

`generateGLB(positions, types, min, max)`

Generates a GLB buffer from a point cloud with type-based coloring (8 predefined colors). Atoms are Morton-sorted within the supplied bounding box for spatial coherence.

function generateGLB(
  positions: Float32Array,
  types: Uint16Array,
  min: number[],
  max: number[]
): Buffer

Parameter	Type	Description
`positions`	`Float32Array`	Vertex positions as `[x1, y1, z1, x2, y2, z2, ...]`
`types`	`Uint16Array`	Atom type index per vertex (clamped to 0–7 for color selection)
`min`	`number[]`	Bounding box minimum as `[x, y, z]`
`max`	`number[]`	Bounding box maximum as `[x, y, z]`

Returns: Buffer — GLB binary data.

`generateGLBToFile(positions, types, min, max, filePath)`

Same as generateGLB, but streams the result directly to disk (bypasses the Node.js buffer size limit, suitable for very large datasets).

function generateGLBToFile(
  positions: Float32Array,
  types: Uint16Array,
  min: number[],
  max: number[],
  filePath: string
): boolean

Parameters match generateGLB, plus filePath (string) — output file path.

Returns: boolean — true on success.

`generatePointCloudGLB(positions, colors, min, max)`

Generates a GLB from a point cloud with explicit, pre-computed vertex colors.

function generatePointCloudGLB(
  positions: Float32Array,
  colors: Float32Array,
  min: number[],
  max: number[]
): Buffer

Parameter	Type	Description
`positions`	`Float32Array`	Vertex positions as `[x, y, z, ...]`
`colors`	`Float32Array`	Per-vertex colors, either RGB (`[r, g, b, ...]`) or RGBA (`[r, g, b, a, ...]`). The layout is auto-detected from the array length.
`min`	`number[]`	Bounding box minimum as `[x, y, z]`
`max`	`number[]`	Bounding box maximum as `[x, y, z]`

Returns: Buffer — GLB binary data.

`generateMeshGLB(positions, normals, indices, hasColors, colors, bounds, material)`

Generates a GLB from an indexed triangle mesh with normals and PBR material properties.

function generateMeshGLB(
  positions: Float32Array,
  normals: Float32Array,
  indices: Uint32Array | Uint16Array,
  hasColors: boolean,
  colors: Float32Array,
  bounds: Bounds,
  material: Material
): Buffer

Parameter	Type	Description
`positions`	`Float32Array`	Vertex positions
`normals`	`Float32Array`	Vertex normals
`indices`	`Uint32Array \| Uint16Array`	Triangle indices
`hasColors`	`boolean`	Whether to include vertex colors
`colors`	`Float32Array`	RGBA colors (only read when `hasColors` is true; may be omitted/undefined otherwise)
`bounds`	`Bounds`	Bounding box `{ minX, minY, minZ, maxX, maxY, maxZ }`
`material`	`Material`	PBR material properties

interface Bounds {
  minX: number; minY: number; minZ: number;
  maxX: number; maxY: number; maxZ: number;
}

interface Material {
  baseColor: [number, number, number, number];
  metallic: number;
  roughness: number;
  emissive: [number, number, number];
  doubleSided?: boolean;
}

doubleSided defaults to true when omitted.

Returns: Buffer — GLB binary data.

`applyPropertyColors(values, minVal, maxVal, gradientType)`

Maps scalar property values onto a gradient color palette using a 1024-entry lookup table. Each value is normalized into the [minVal, maxVal] range, clamped, and sampled from the selected gradient.

function applyPropertyColors(
  values: Float32Array,
  minVal: number,
  maxVal: number,
  gradientType: number
): Float32Array

Parameter	Type	Description
`values`	`Float32Array`	One scalar value per vertex
`minVal`	`number`	Lower bound of the value range (maps to the start of the gradient)
`maxVal`	`number`	Upper bound of the value range (maps to the end of the gradient)
`gradientType`	`number`	Gradient selector: `0` = Viridis, `1` = Plasma, `2` = Blue-Red, `3` = Grayscale (out-of-range values fall back to `0`)

Returns: Float32Array — RGB colors per vertex as [r, g, b, ...] (3 components per vertex).

`taubinSmooth(positions, indices, iterations)`

Applies Taubin smoothing (bilateral mesh filtering) to a triangle mesh. Modifies positions in place. The lambda/mu smoothing factors are fixed internally (0.5 and -0.52).

function taubinSmooth(
  positions: Float32Array,
  indices: Uint32Array | Uint16Array,
  iterations: number
): boolean

Parameter	Type	Description
`positions`	`Float32Array`	Mesh vertex positions (modified in place)
`indices`	`Uint32Array \| Uint16Array`	Triangle indices
`iterations`	`number`	Number of smoothing passes (`<= 0` is a no-op)

Returns: boolean — true on success.

Performance

Optimized for large atomic datasets:

AVX2/BMI2 SIMD — Runtime CPU feature detection with vectorized operations.
Lock-free parallel radix sort — Per-thread histograms eliminate atomic operations.
Morton encoding — Z-order curve for spatial coherence.
32-byte aligned memory — Cache-friendly data layout.
Multi-threaded — Automatic hardware concurrency detection.
Compiled with -O3 -ffast-math -pthread.

SpatialAssembler

On this page