voxelization

Dense and sparse voxelization, FNV voxel hashing, the first point per voxel, and trilinear devoxelization.

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).
voxel_grid_fnv –

FNV-1a 64-bit hash of integer voxel-grid coordinates. \((N, D) \to (N,)\).
first_permutation –

Index of the first occurrence of each cluster id in a consecutive cluster tensor.

dense_voxelize [source] ¶

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 [source] ¶

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 [source] ¶

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 [source] ¶

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,)\).

voxel_grid_fnv [source] ¶

voxel_grid_fnv(
    pos: Tensor,
    size: float,
    start: Optional[Tensor] = None,
    *,
    return_inverse: Literal[False] = False,
    return_counts: Literal[False] = False,
) -> Tensor

voxel_grid_fnv(
    pos: Tensor,
    size: float,
    start: Optional[Tensor] = None,
    *,
    return_inverse: Literal[True],
    return_counts: Literal[False] = False,
) -> Tuple[Tensor, Tensor]

voxel_grid_fnv(
    pos: Tensor,
    size: float,
    start: Optional[Tensor] = None,
    *,
    return_inverse: Literal[False] = False,
    return_counts: Literal[True],
) -> Tuple[Tensor, Tensor]

voxel_grid_fnv(
    pos: Tensor,
    size: float,
    start: Optional[Tensor] = None,
    *,
    return_inverse: Literal[True],
    return_counts: Literal[True],
) -> Tuple[Tensor, Tensor, Tensor]

voxel_grid_fnv(
    pos: Tensor,
    size: float,
    start: Optional[Tensor] = None,
    *,
    return_inverse: bool = False,
    return_counts: bool = False,
) -> Union[Tensor, Tuple[Tensor, ...]]

FNV-1a 64-bit hash of integer voxel-grid coordinates. \((N, D) \to (N,)\).

Parameters:

pos (Tensor) –

Point positions of shape \((N, D)\).
size (float) –

Voxel side length in the same units as pos.
start (Optional[Tensor], default: None ) –

Optional voxel-grid origin. When None, the grid origin is implicit via the internal pos_grid -= pos_grid.min(0) shift.
return_inverse (bool, default: False ) –

If True, also return the per-point consecutive voxel index in \([0, V)\), following the semantics of torch.unique(..., return_inverse=True).
return_counts (bool, default: False ) –

If True, also return the per-voxel point count of shape \((V,)\).

Returns:

Union[Tensor, Tuple[Tensor, ...]] –

hashed of shape \((N,)\) when both flags are False. With return_inverse=True adds
Union[Tensor, Tuple[Tensor, ...]] –

inverse of shape \((N,)\); with return_counts=True adds count of shape \((V,)\); both
Union[Tensor, Tuple[Tensor, ...]] –

flags enabled returns (hashed, inverse, count).

first_permutation [source] ¶

first_permutation(
    cluster: Tensor, num_clusters: Optional[int] = None
) -> Tensor

Index of the first occurrence of each cluster id in a consecutive cluster tensor.

The permutation returned by consecutive_cluster picks a backend-dependent representative per cluster (the last occurrence on CPU, a nondeterministic one on CUDA). This helper always picks the first occurrence, so tensor[first_permutation(cluster)] is deterministic across devices.

Parameters:

cluster (Tensor) –

Consecutive cluster indices of shape \((N,)\) with values in \([0, V)\).
num_clusters (Optional[int], default: None ) –

Number of clusters \(V\). Inferred as cluster.max() + 1 when None.

Returns:

Tensor –

Long tensor of shape \((V,)\) holding, per cluster id, the smallest index in cluster with that id.

Example

>>> cluster = torch.tensor([1, 0, 1, 2, 0])
>>> first_permutation(cluster)
tensor([1, 0, 3])