voxelization

Bases: DictTransform, Randomizable

Pad per-point tensors so each batch is divisible by num_samples.

Thin dict wrapper around divisible_pad; see its docstring for the full behavior of each pad_fill strategy ("cycle", "replicate", "random"). The tensor at ref_key defines the packed count \(n\) and the device. If a batch index tensor lives at batch_key, padding is done per-batch; otherwise a single zero batch is synthesized. Every tensor in the dict whose first dim equals \(n\) (positions, features, labels, ...) is re-indexed by the same gather map, so per-point correspondence is preserved.

When dst_inverse_key is set, the transform also records a source-to-padded index map under that dict key: a 1-D long tensor of length \(n\) with values in \([0, n_\text{padded})\) giving the canonical padded row for each source row. If the key already holds a prior inverse map (from an earlier invertible transform), the new map composes with it via gather, so the stored tensor always maps from the outermost source space to the current predictor space. Consumers such as SlidingWindowInferer read this key once and gather predictions back to the source rows.

Parameters:

• num_samples (int) –

  Target chunk size \(k\) for divisibility.

• pad_fill (PadFill, default: 'cycle' ) –

  Fill strategy passed through to divisible_pad.

• ref_key (str, default: POS ) –

  Key whose tensor defines \(n\) and the device.

• batch_key (str, default: BATCH ) –

  Key for an optional batch index tensor. When present in the data, padding runs per-batch; otherwise a single zero batch is synthesized for the whole scene.

• seed (Optional[int], default: None ) –

  Seed for the random padding (only used when pad_fill="random"); None draws from the global generator (see Randomizable).

• dst_inverse_key (Optional[str], default: None ) –

  Key for the source-to-padded row map (see the module docs on sampling keys); composes with any prior value at the same key. None (the default) disables it.

• allow_missing_keys (bool, default: False ) –

  If True, return the data unchanged when ref_key is missing instead of raising.

from torch_pointcloud.transforms import DivisiblePad

# Pad a 5000-point block to 8192 (= 2 * 4096) before sliding-window
# sub-chunking. Random fill duplicates points uniformly at random.
transform = DivisiblePad(num_samples=4096, pad_fill="random")

Bases: DictTransform

Hard-voxelize a single scene into the per-voxel point stack consumed by voxel detectors.

Moves the transform_points_to_voxels step of voxel detectors (PointPillars, SECOND) out of the model and into the data pipeline, mirroring how BuildOctree produces an octree for OctFormer. The model then receives already-voxelized input and focuses on the network math.

Reads pos_key (and optionally feature_key), runs hard_voxelize on the single sample (the batch index is all zeros), and adds three keys while keeping pos / x:

• dst_voxel_key: the per-voxel point stack.
• dst_pos_voxel_key: integer voxel grid indices \((z, y, x)\) (the single-sample batch column is dropped; the per-voxel scene index is synthesized at collation).
• dst_num_points_key: the per-voxel point counts.

Parameters:

• pos_key (str) –

  Key holding the point positions \((N, 3)\).

• 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.

• feature_key (Optional[str], default: None ) –

  Optional key holding extra point features \((N, C)\) concatenated after \(xyz\).

• dst_voxel_key (str, default: VOXEL ) –

  Output key for the per-voxel point stack.

• dst_pos_voxel_key (str, default: POS_VOXEL ) –

  Output key for the integer voxel grid indices.

• dst_num_points_key (str, default: VOXEL_NUM_POINTS ) –

  Output key for the per-voxel point counts.

• allow_missing_keys (bool, default: False ) –

  Unused (pos_key is always required); kept for interface parity.

import torch
import torch_pointcloud.transforms as T

data = {"pos": torch.rand(1000, 3) * 50.0, "x": torch.rand(1000, 1)}
transform = T.HardVoxelize(
    pos_key="pos",
    feature_key="x",
    voxel_size=(0.16, 0.16, 4.0),
    point_cloud_range=(0.0, -39.68, -3.0, 69.12, 39.68, 1.0),
    max_num_points=32,
    max_num_voxels=40000,
)
data = transform(data)
print(data["voxel"].shape, data["pos_voxel"].shape, data["voxel_num_points"].shape)

Bases: DictTransform, Randomizable

Voxelize a point cloud by grid-binning and per-voxel reduction.

Sub-samples a point cloud to one representative point per occupied voxel, and optionally records a source-to-voxel index map for full-resolution back-projection.

Operates on a single sample (pre-collate). With dst_inverse_key set, the stored tensor has shape \((N_\text{full},)\) with values in \([0, N_\text{voxel})\): for each original point \(i\), the voxel it belongs to. Downstream code can recover full-resolution predictions with preds_full = preds_voxel[inverse].

If the key already holds a prior inverse map (e.g. from an earlier invertible transform), the new map composes with it via gather, so the stored tensor always maps from the outermost source space to the current predictor space.

Parameters:

• pos_key (str) –

  Key holding the positions to sub-sample.

• pos_reduce (VoxelPosReduce) –

  How to reduce positions per voxel (mean/min/max/sum/first/grid).

• size (float) –

  Voxel edge length in the same units as the positions. Must be positive.

• method (VoxelMethod, default: 'grid' ) –

  How voxel ids are computed, which fixes the output voxel order: grid (the default) uses the linear grid index, fnv an FNV-1a hash of the grid coordinates, as hash-based reference pipelines do.

• reduce (Optional[ValueCollection[VoxelReduce]], default: None ) –

  Per-key reduction for keys. None (the default) resolves per key to mean for floating-point tensors and first for integer tensors (e.g. segment). Integer keys keep their dtype: non-first reductions compute in float and cast back. The first representative is the first point of each voxel in input order, deterministic across devices (unless random_first=True).

• keys (Optional[KeyCollection], default: None ) –

  Additional per-point keys to sub-sample (e.g. color, segment).

• dst_inverse_key (Optional[str], default: None ) –

  Key for the source-to-voxel row map (see the module docs on sampling keys); composes with any prior value at the same key. None (the default) disables it.

• dst_pos_grid_key (Optional[str], default: None ) –

  When set, also store the integer voxel-grid coordinates under this key. Useful when a model needs both real-valued positions (e.g. for rotary position embedding) and integer grid coordinates (for serialization / sparse-conv stems); with pos_reduce="grid" it holds the same grid as pos_key.

• random_first (bool, default: False ) –

  If True, the per-voxel representative used by reduce="first" (and the pos/grid_pos derivations) is chosen randomly within each voxel on every call. Per-voxel random sampling is a meaningful training augmentation; leave False (default) for deterministic validation.

• seed (Optional[int], default: None ) –

  Seed for the random voxel representative (random_first); None draws from the global generator (see Randomizable).

• allow_missing_keys (bool, default: False ) –

  If True, return the data unchanged when pos_key is missing and skip absent keys.

Raises:

• ValueError –

  If size is not positive, or pos_reduce / method / any reduce entry is not one of its allowed values.