Point/voxel core
Point/voxel helpers convert dense point rows into sparse voxel coordinates and
back. The core module exposes the metadata classes and lower-level builders
used by the operation wrappers.
The quantization contract is:
\[v = \left\lfloor \frac{p - o}{s} \right\rfloor,\]
where p is a point coordinate, o is the origin, and s is the voxel
size. The resulting sparse coordinate row is (batch, v_x, v_y, v_z).
Voxel feature aggregation supports sum and mean reductions over point
rows assigned to the same voxel. Devoxelization uses a fixed-width map with
eight voxel rows per point for linear interpolation and one effective row for
nearest interpolation.
Related pages
-
type mlx_lattice.core.coords.quantization.VoxelReduction = Literal['sum', 'mean']
-
type mlx_lattice.core.coords.quantization.PointVoxelInterpolation = Literal['nearest', 'linear']
-
class mlx_lattice.core.coords.quantization.SparseQuantization(coords, active_rows, inverse_rows, counts)[source]
Bases: object
Sparse voxel coordinates plus point-to-voxel metadata.
coords stores unique voxel coordinates in (batch, x, y, z) order.
inverse_rows maps each input point row to its voxel row, and counts
stores the number of active point rows accumulated into each voxel.
- Parameters:
coords (array)
active_rows (array)
inverse_rows (array)
counts (array)
-
coords: array
-
active_rows: array
-
inverse_rows: array
-
counts: array
-
property capacity: int
-
property active_count: array
-
class mlx_lattice.core.coords.quantization.PointVoxelMap(rows, weights)[source]
Bases: object
Fixed-width point-to-voxel interpolation rows and weights.
rows and weights both have shape (N, 8). Linear interpolation
may use up to eight neighboring voxel rows per point; nearest interpolation
uses one non-zero contribution.
- Parameters:
rows (array)
weights (array)
-
rows: array
-
weights: array
-
property point_count: int
-
mlx_lattice.core.coords.quantization.sparse_quantize(points, voxel_size=1.0, *, batch_indices=None, origin=0.0, active_rows=None)[source]
Voxelize floating-point points into sparse integer coordinates.
Points have shape (N, 3) and dtype float32. Optional
batch_indices assign points to batches; omitted batches default to
zero. The result includes voxel coordinates, active row count, inverse
point-to-voxel rows, and per-voxel counts.
- Return type:
SparseQuantization
- Parameters:
-
-
mlx_lattice.core.coords.quantization.voxelize_features(feats, quantization, *, active_rows=None, reduction='mean')[source]
Aggregate point features into voxels using sparse quantization data.
feats must be float32 with one row per original point. sum
accumulates point rows directly; mean divides by each voxel count.
- Return type:
array
- Parameters:
-
-
mlx_lattice.core.coords.quantization.build_point_voxel_map(points, voxel_coords, voxel_active_rows, voxel_size=1.0, *, batch_indices=None, point_active_rows=None, origin=0.0, interpolation='linear')[source]
Build fixed-width interpolation rows from points to voxel centers.
The map can be reused to sample multiple voxel feature arrays as long as
point geometry, batch indices, voxel coordinates, voxel size, and origin
are unchanged.
- Return type:
PointVoxelMap
- Parameters:
-
-
mlx_lattice.core.coords.quantization.interpolate_point_features(voxel_feats, point_voxel_map)[source]
Interpolate voxel features back to point rows.
voxel_feats must be float32 with shape (N_voxels, C). The
returned dense point feature array has shape (N_points, C).
- Return type:
array
- Parameters:
-