Point/voxel operations

These operation wrappers expose the point/voxel bridge as high-level sparse tensor functions. voxelize creates sparse voxel tensors from dense point features, while devoxelize samples sparse voxel features back to point rows.

The functions validate shape and dtype before entering the native backend: points are float32 (N, 3), optional batch indices are int32 (N,), and voxel feature aggregation currently uses float32 features.

Related pages

• Core metadata classes: Point/voxel core

• Backend implementation details: Point/voxel backend routes

• Sparse tensor output contract: Sparse tensor model

• Quickstart example: Quickstart

mlx_lattice.ops.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')

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:

• points (array)

• voxel_coords (array)

• voxel_active_rows (array)

• voxel_size (float | Sequence[float])

• batch_indices (array | None)

• point_active_rows (array | None)

• origin (float | Sequence[float])

• interpolation (PointVoxelInterpolation)

mlx_lattice.ops.quantization.devoxelize(points, voxels, voxel_size=1.0, *, batch_indices=None, point_active_rows=None, origin=0.0, interpolation='linear', point_voxel_map=None)

Sample sparse voxel features back onto dense point rows.

If point_voxel_map is not supplied, the function builds one from point coordinates, voxel coordinates, voxel size, origin, batch indices, and the selected interpolation mode. The returned dense array has one row per point and one column per voxel feature channel.

Return type:

array

Parameters:

• points (array)

• voxels (SparseTensor)

• voxel_size (float | Sequence[float])

• batch_indices (array | None)

• point_active_rows (array | None)

• origin (float | Sequence[float])

• interpolation (PointVoxelInterpolation)

• point_voxel_map (PointVoxelMap | None)

mlx_lattice.ops.quantization.interpolate_point_features(voxel_feats, point_voxel_map)

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:

• voxel_feats (array)

• point_voxel_map (PointVoxelMap)

mlx_lattice.ops.quantization.voxelize(points, feats, voxel_size=1.0, *, batch_indices=None, origin=0.0, active_rows=None, reduction='mean', stride=1)

Overloads:

• points (mx.array), feats (mx.array), voxel_size (float | Sequence[float]), batch_indices (mx.array | None), origin (float | Sequence[float]), active_rows (mx.array | None), reduction (VoxelReduction), stride (int | Sequence[int]) → SparseTensor

• points (mx.array), feats (mx.array), voxel_size (float | Sequence[float]), batch_indices (mx.array | None), origin (float | Sequence[float]), active_rows (mx.array | None), reduction (str), stride (int | Sequence[int]) → SparseTensor

Parameters:

• points (array)

• feats (array)

• voxel_size (float | Sequence[float])

• batch_indices (array | None)

• origin (float | Sequence[float])

• active_rows (array | None)

• reduction (str)

• stride (int | Sequence[int])

Return type:

SparseTensor

Quantize points and aggregate features into a sparse voxel tensor.

points must have shape (N, 3) and float32 dtype. feats must have shape (N, C). Optional batch_indices has shape (N,) and int32 dtype. The returned tensor uses coordinates (batch, floor((point - origin) / voxel_size)) and aggregated voxel features.

mlx_lattice.ops.quantization.voxelize_with_quantization(quantization, feats, *, active_rows=None, reduction='mean', stride=1, template=None)

Overloads:

• quantization (SparseQuantization), feats (mx.array), active_rows (mx.array | None), reduction (VoxelReduction), stride (int | Sequence[int]), template (SparseTensor | None) → SparseTensor

• quantization (SparseQuantization), feats (mx.array), active_rows (mx.array | None), reduction (str), stride (int | Sequence[int]), template (SparseTensor | None) → SparseTensor

Parameters:

• quantization (SparseQuantization)

• feats (array)

• active_rows (array | None)

• reduction (str)

• stride (int | Sequence[int])

• template (SparseTensor | None)

Return type:

SparseTensor

Apply precomputed sparse quantization metadata to feature rows.

This is the split form of voxelize for pipelines that reuse point to voxel assignments across multiple feature tensors. If template is supplied, it must share the quantization coordinate and active-row arrays.