voxelization

Dense and sparse voxelization with trilinear devoxelization for packed point clouds.

Functions:

dense_voxelize –

Pool packed point features into a dense voxel grid, one grid per point cloud.
trilinear_dense_devoxelize –

Interpolate a dense voxel grid back to packed point features, trilinearly.
sparse_voxelize –

Pool packed point features into sparse voxels of a regular grid.
hard_voxelize –

Hard voxelization of a packed batch of point clouds (spconv voxel generator).

dense_voxelize ¶

dense_voxelize(
    x: Tensor,
    pos: Tensor,
    batch: Tensor,
    resolution: int,
    reduce: str = "mean",
) -> Tensor

Pool packed point features into a dense voxel grid, one grid per point cloud.

Parameters:

x (Tensor) –

Packed point features \((N, C)\).
pos (Tensor) –

Packed grid coordinates \((N, 3)\), clamped to \([0, \text{resolution} - 1)\).
batch (Tensor) –

Per-point batch index \((N,)\).
resolution (int) –

Number of voxels \(R\) per axis.
reduce (str, default: 'mean' ) –

Scatter reduction applied to the points of a voxel (e.g. mean, max).

Returns:

Tensor –

The voxel grid \((B, C, R, R, R)\), zero where a voxel holds no point.

trilinear_dense_devoxelize ¶

trilinear_dense_devoxelize(
    x_voxel: Tensor,
    pos: Tensor,
    batch: Tensor,
    resolution: int,
) -> Tensor

Interpolate a dense voxel grid back to packed point features, trilinearly.

Parameters:

x_voxel (Tensor) –

Voxel grid \((B, C, R, R, R)\).
pos (Tensor) –

Packed grid coordinates \((N, 3)\), clamped to \([0, \text{resolution} - 1)\).
batch (Tensor) –

Per-point batch index \((N,)\).
resolution (int) –

Number of voxels \(R\) per axis. Must match the grid.

Returns:

Tensor –

The interpolated point features \((N, C)\).

sparse_voxelize ¶

sparse_voxelize(
    x: Tensor,
    pos: Tensor,
    batch: Tensor,
    voxel_size: float,
    reduce: str,
    return_inverse: Literal[True],
) -> Tuple[Tensor, IntTensor, Tensor, Tensor]

sparse_voxelize(
    x: Tensor,
    pos: Tensor,
    batch: Tensor,
    voxel_size: float,
    reduce: str = "mean",
    return_inverse: Literal[False] = False,
) -> Tuple[Tensor, IntTensor, Tensor]

sparse_voxelize(
    x: Tensor,
    pos: Tensor,
    batch: Tensor,
    voxel_size: float,
    reduce: str = "mean",
    return_inverse: bool = False,
) -> Tuple[Tensor, ...]

Pool packed point features into sparse voxels of a regular grid.

Parameters:

x (Tensor) –

Packed point features \((N, C)\).
pos (Tensor) –

Packed point coordinates \((N, 3)\).
batch (Tensor) –

Per-point batch index \((N,)\).
voxel_size (float) –

Edge length of a voxel, in the units of pos.
reduce (str, default: 'mean' ) –

Scatter reduction applied to the points of a voxel (e.g. mean, max).
return_inverse (bool, default: False ) –

Also return the per-point voxel index, to broadcast voxel values back to the points.

Returns:

Tensor –

The voxel features \((V, C)\), their integer coordinates \((V, 3)\) and batch index \((V,)\), plus the
... –

per-point voxel index \((N,)\) when return_inverse is True.

hard_voxelize ¶

hard_voxelize(
    points: Tensor,
    batch: Tensor,
    voxel_size: Sequence[float],
    point_cloud_range: Sequence[float],
    max_num_points: int,
    max_num_voxels: int,
) -> Tuple[Tensor, Tensor, Tensor]

Hard voxelization of a packed batch of point clouds (spconv voxel generator).

Reproduces the transform_points_to_voxels step of voxel detectors (PointPillars, SECOND): each scene is voxelized independently (at most max_num_points points per voxel and max_num_voxels voxels per scene), then the per-scene voxels are concatenated with a leading batch index. Points outside point_cloud_range are dropped by the generator.

Parameters:

points (Tensor) –

Packed point features \((N, C)\) with the first three columns the \(xyz\) coordinates.
batch (Tensor) –

Per-point batch index \((N,)\).
voxel_size (Sequence[float]) –

Voxel size \((v_x, v_y, v_z)\).
point_cloud_range (Sequence[float]) –

Range \((x_\min, y_\min, z_\min, x_\max, y_\max, z_\max)\).
max_num_points (int) –

Maximum number of points kept per voxel.
max_num_voxels (int) –

Maximum number of voxels kept per scene.

Returns:

Tensor –

A tuple (voxels, voxel_indices, num_points) where voxels is \((V, \text{max\_num\_points}, C)\),
Tensor –

voxel_indices is \((V, 4)\) with columns \((\text{batch}, z, y, x)\) and num_points is \((V,)\).