utils

Transforms that rename, copy, convert or combine the entries of a sample dict, and element-wise arithmetic.

Classes:

SetValue –

Set values for keys in the dictionary, creating or overwriting them.
ToFloat –

Cast dictionary tensor entries to float32.
ToDevice –

Convert dictionary tensor entries to the given device.
Relabel –

Remap integer labels in dictionary entries via a lookup table.
RenameItems –

Rename keys in the dictionary.
CopyItems –

Copy values from source keys to new destination keys.
ToTensor –

Convert dictionary entries to tensors.
OnesLike –

Adds a tensor of ones shaped like existing dictionary entries.
Cat –

Concatenates tensors from multiple keys into a single feature tensor.
OneHot –

One-hot encode integer-class tensors.
Reduce –

Reduce a tensor along a dimension and store the scalar/vector result.
KeepItems –

Keep only items in the data dictionary that are in the keys list.
Scale –

Multiply dictionary tensor entries by a scale factor.
Divide –

Divide dictionary tensor entries by a divisor.
DivideItems –

Divide target keys by the value of a reference key element-wise.
SubtractItems –

Subtract the value of a reference key from target keys element-wise.
Abs –

Make dictionary tensor entries absolute.
Clamp –

Clamp tensor entries to a range (a thin wrapper over torch.clamp).

ReduceOp `module-attribute` ¶

ReduceOp = Literal['min', 'max', 'mean', 'sum']

Allowed values for Reduce.op (per-key reduction operator).

SetValue [source] ¶

SetValue(keys: KeyCollection, values: Any)

Bases: DictTransform

Set values for keys in the dictionary, creating or overwriting them.

Unlike most DictTransform subclasses, SetValue does not read existing values, so allow_missing_keys has no meaning and is not accepted.

SetValue diagram

Parameters:

keys (KeyCollection) –

The keys to set.
values (Any) –

The values to set. Either a single value broadcast to every key, or a sequence of values the same length as keys.

ToFloat [source] ¶

ToFloat(
    keys: KeyCollection, allow_missing_keys: bool = False
)

Bases: DictTransform

Cast dictionary tensor entries to float32.

Useful when tensors are stored in integer formats (e.g. uint8 for colors) and need to be promoted to floating point before arithmetic transforms like Divide or Normalize.

ToFloat diagram

Parameters:

keys (KeyCollection) –

The keys to cast.
allow_missing_keys (bool, default: False ) –

If True, missing keys are silently ignored.

ToDevice [source] ¶

ToDevice(
    keys: KeyCollection,
    device: ValueCollection[str | device],
    non_blocking: ValueCollection[bool] = False,
    copy: ValueCollection[bool] = True,
    memory_format: ValueCollection[
        memory_format | None
    ] = None,
    dst_keys: Optional[KeyCollection] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Convert dictionary tensor entries to the given device.

ToDevice diagram

Parameters:

keys (KeyCollection) –

The keys to convert the tensors to the given device.
device (ValueCollection[str | device]) –

The device to convert the tensors to.
non_blocking (ValueCollection[bool], default: False ) –

If True, the transfer will be done asynchronously.
copy (ValueCollection[bool], default: True ) –

If True, the tensor will be copied to the new device.
memory_format (ValueCollection[memory_format | None], default: None ) –

The memory format to use for the tensor.
dst_keys (Optional[KeyCollection], default: None ) –

The keys to store the converted tensors in.
allow_missing_keys (bool, default: False ) –

If True, the transform will not raise an error if the keys are not present in the data.

Relabel [source] ¶

Relabel(
    keys: KeyCollection,
    labels: Sequence[int] | Dict[int, int],
    default: int = 0,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Remap integer labels in dictionary entries via a lookup table.

labels can be either:

a sequence of source values (1:1) - each value at index i is mapped to i;
a dict[int, int] (general source → target) - supports N-to-1 merges (e.g. SemanticKITTI's moving-car and car both → 0).

Source values not listed in labels are set to default.

Relabel before / after

Parameters:

keys (KeyCollection) –

Keys holding label tensors to remap.
labels (Sequence[int] | Dict[int, int]) –

Source-value listing (1:1) or explicit {source: target} dict (N:1).
default (int, default: 0 ) –

Value assigned to source values not listed in labels.
allow_missing_keys (bool, default: False ) –

If True, skip missing keys instead of raising.

Example

import torch
import torch_pointcloud.transforms as T

# 1:1 - keep raw NYU40 ids 1, 2, 3, 4, 5 and remap them to 0..4
relabel = T.Relabel(keys="segment", labels=[1, 2, 3, 4, 5], default=255)
relabel({"segment": torch.tensor([1, 3, 5, 7])})["segment"]  # tensor([0, 2, 4, 255])

# N:1 - SemanticKITTI 19-class benchmark (merges moving-* into static)
relabel = T.Relabel(
    keys="segment",
    labels={
        10: 0, 252: 0,    # car        (+ moving-car)
        11: 1,             # bicycle
        15: 2,             # motorcycle
        18: 3, 258: 3,    # truck      (+ moving-truck)
        # ...
    },
    default=255,
)
relabel({"segment": torch.tensor([10, 252, 11, 99])})["segment"]  # tensor([0, 0, 1, 255])

RenameItems [source] ¶

RenameItems(
    keys: KeyCollection,
    dst_keys: KeyCollection,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Rename keys in the dictionary.

RenameItems diagram

Parameters:

keys (KeyCollection) –

Source keys to rename.
dst_keys (KeyCollection) –

New key names (same length as keys).
allow_missing_keys (bool, default: False ) –

If True, silently skip absent source keys.

CopyItems [source] ¶

CopyItems(
    keys: KeyCollection,
    dst_keys: KeyCollection,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Copy values from source keys to new destination keys.

CopyItems diagram

Parameters:

keys (KeyCollection) –

Source keys to copy from.
dst_keys (KeyCollection) –

Destination keys to copy to (same length as keys).
allow_missing_keys (bool, default: False ) –

If True, silently skip absent source keys.

ToTensor [source] ¶

ToTensor(
    keys: KeyCollection,
    dtype: ValueCollection[str | dtype] | None = None,
    device: ValueCollection[str | device] | None = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Convert dictionary entries to tensors.

ToTensor diagram

Parameters:

keys (KeyCollection) –

The keys to convert.
dtype (ValueCollection[str | dtype] | None, default: None ) –

Target dtype(s).
device (ValueCollection[str | device] | None, default: None ) –

Target device(s).
allow_missing_keys (bool, default: False ) –

If True, the transform will not raise an error if the keys are not present in the data.

OnesLike [source] ¶

OnesLike(
    keys: KeyCollection,
    memory_format: ValueCollection[memory_format]
    | None = None,
    dtype: ValueCollection[dtype] | None = None,
    layout: ValueCollection[layout] | None = None,
    device: ValueCollection[device] | None = None,
    pin_memory: ValueCollection[bool] | None = False,
    requires_grad: ValueCollection[bool] | None = False,
    dst_keys: KeyCollection | None = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Adds a tensor of ones shaped like existing dictionary entries.

OnesLike diagram

Parameters:

keys (KeyCollection) –

Reference keys used to determine tensor shape.
dst_keys (KeyCollection | None, default: None ) –

Keys under which the ones tensors are stored.

Cat [source] ¶

Cat(
    keys: KeyCollection,
    dst_key: str,
    dim: int = -1,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Concatenates tensors from multiple keys into a single feature tensor.

Note

This transform is mostly used to concatenate multiple features into a single tensor to feed into your model.

Integer inputs are cast to float32; floating inputs keep their dtype. When the inputs mix floating dtypes, the result uses the widest one (so float64 is preserved, never downcast).

Cat diagram

Parameters:

keys (KeyCollection) –

Keys whose tensors are concatenated (in order).
dst_key (str) –

Key under which the result is stored.
dim (int, default: -1 ) –

Dimension along which to concatenate.
allow_missing_keys (bool, default: False ) –

If True, silently skip absent keys.

Example

If you have a point cloud data containing position, color and normal and want to concatenate them into a single feature tensor (to feed into your model), you can do the following:

import torch

from torch_pointcloud.transforms import Cat

data = {
    "pos": torch.randn(10, 3),
    "color": torch.randn(10, 3),
    "normal": torch.randn(10, 3),
}
transform = Cat(keys=["pos", "color", "normal"], dst_key="x", dim=1)
data = transform(data)

Now, the data dictionary will contain the key x with the shape \((10, 9)\).

OneHot [source] ¶

OneHot(
    keys: KeyCollection,
    num_classes: ValueCollection[int],
    dst_keys: Optional[KeyCollection] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

One-hot encode integer-class tensors.

Wraps torch.nn.functional.one_hot and casts the result to float so the output is ready to feed into a model.

OneHot diagram

Parameters:

keys (KeyCollection) –

Keys holding integer (long) class indices.
num_classes (ValueCollection[int]) –

Number of classes \(C\) in the one-hot encoding.
dst_keys (Optional[KeyCollection], default: None ) –

Where to store the one-hot tensors. Defaults to keys.
allow_missing_keys (bool, default: False ) –

If True, silently skip absent keys.

Shape

Input class tensor of shape \((N,)\) becomes \((N, C)\). A scalar input becomes shape \((C,)\), which after batched collate stacks to \((B, C)\).

Reduce [source] ¶

Reduce(
    keys: KeyCollection,
    op: ValueCollection[ReduceOp],
    dim: ValueCollection[int] = 0,
    keepdim: bool = False,
    dst_keys: Optional[KeyCollection] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Reduce a tensor along a dimension and store the scalar/vector result.

Useful for capturing per-sample statistics (e.g. axis-wise scene maxima or centroids) as standalone keys that downstream transforms can reference.

Reduce diagram

Parameters:

keys (KeyCollection) –

Keys to reduce.
op (ValueCollection[ReduceOp]) –

Reduction operator: "min", "max", "mean", or "sum" (matches the vocabulary used by Voxelize). "mean" keeps the input's floating dtype (float64 included); integer inputs are cast to float32.
dim (ValueCollection[int], default: 0 ) –

Dimension to reduce. Defaults to 0.
keepdim (bool, default: False ) –

Pass keepdim=True to keep the reduced axis as size \(1\). This is helpful when the result is meant to broadcast against a \((N, D)\) tensor (e.g. per-sample bbox stats) and to survive the packed-batch collate - a \((1, D)\) tensor collates to \((B, D)\) via torch.cat, whereas a \((D,)\) tensor would concatenate to \((B \cdot D,)\).
dst_keys (Optional[KeyCollection], default: None ) –

Output keys. Defaults to keys (in-place overwrite).
allow_missing_keys (bool, default: False ) –

If True, silently skip absent keys.

KeepItems [source] ¶

KeepItems(
    keys: KeyCollection, allow_missing_keys: bool = False
)

Bases: DictTransform

Keep only items in the data dictionary that are in the keys list.

Note

This transform is useful if during augmentation process you constructed multiple tensors and want to drop intermediate tensors for memory efficiency.

KeepItems diagram

Parameters:

keys (KeyCollection) –

The keys to keep in the data dictionary.
allow_missing_keys (bool, default: False ) –

If True, the transform will not raise an error if the keys are not present in the data.

Example

If you have a data dictionary containing position, color and normal and want to keep only the position and color, you can do the following:

import torch

from torch_pointcloud.transforms import KeepItems

data = {
    "pos": torch.randn(10, 3),
    "color": torch.randn(10, 3),
    "normal": torch.randn(10, 3),
}
transform = KeepItems(keys=["pos", "color"])
data = transform(data)

Now, the data dictionary will contain only the keys pos and color. The key normal will be removed.

Scale [source] ¶

Scale(
    keys: KeyCollection,
    scale: float | Sequence[float],
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Multiply dictionary tensor entries by a scale factor.

ObjectScene

Scale on an object

Scale on a room

Parameters:

keys (KeyCollection) –

The keys to scale.
scale (float | Sequence[float]) –

The scale factor(s).
allow_missing_keys (bool, default: False ) –

If True, the transform will not raise an error if the keys are not present in the data.

Divide [source] ¶

Divide(
    keys: KeyCollection,
    divisor: float | Sequence[float],
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Divide dictionary tensor entries by a divisor.

ObjectScene

Divide on an object

Divide on a room

Parameters:

keys (KeyCollection) –

The keys to divide.
divisor (float | Sequence[float]) –

The divisor(s).
allow_missing_keys (bool, default: False ) –

If True, the transform will not raise an error if the keys are not present in the data.

DivideItems [source] ¶

DivideItems(
    keys: KeyCollection,
    div_keys: KeyCollection,
    dst_keys: Optional[KeyCollection] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Divide target keys by the value of a reference key element-wise.

Computes data[key] = data[key] / data[div_key] for each key.

DivideItems diagram

Parameters:

keys (KeyCollection) –

Keys whose tensors are divided.
div_keys (KeyCollection) –

Keys whose values are used as the divisors.
dst_keys (Optional[KeyCollection], default: None ) –

Where to store results. Defaults to keys.
allow_missing_keys (bool, default: False ) –

If True, silently skip absent target keys.

SubtractItems [source] ¶

SubtractItems(
    keys: KeyCollection,
    sub_keys: KeyCollection,
    dst_keys: Optional[KeyCollection] = None,
    axes: Optional[Sequence[int]] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Subtract the value of a reference key from target keys element-wise.

Computes data[key] = data[key] - data[sub_key] for each key. With axes set, only the listed last-dim indices are subtracted; the other components pass through unchanged (useful to shift only XY while keeping Z absolute).

ObjectScene

SubtractItems on an object

SubtractItems on a room

Parameters:

keys (KeyCollection) –

Keys whose tensors are modified (subtracted from).
sub_keys (KeyCollection) –

Keys whose values are subtracted from each target key.
dst_keys (Optional[KeyCollection], default: None ) –

Where to store results. Defaults to keys.
axes (Optional[Sequence[int]], default: None ) –

Optional indices into the last dim restricting which components are subtracted. None (default) subtracts every component.
allow_missing_keys (bool, default: False ) –

If True, silently skip absent target keys.

Abs [source] ¶

Abs(keys: KeyCollection, allow_missing_keys: bool = False)

Bases: DictTransform

Make dictionary tensor entries absolute.

Clamp [source] ¶

Clamp(
    keys: KeyCollection,
    min: Union[float, Sequence[float], None] = None,
    max: Union[float, Sequence[float], None] = None,
    dst_keys: Optional[KeyCollection] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Clamp tensor entries to a range (a thin wrapper over torch.clamp).

ObjectScene

Clamp on an object

Clamp on a room

Parameters:

keys (KeyCollection) –

Keys to clamp.
min (Union[float, Sequence[float], None], default: None ) –

Lower bound, one value or one per channel of the last dim. None disables the lower clamp.
max (Union[float, Sequence[float], None], default: None ) –

Upper bound, one value or one per channel of the last dim. None disables the upper clamp.
dst_keys (Optional[KeyCollection], default: None ) –

Where to store the result. Defaults to keys (in-place overwrite).
allow_missing_keys (bool, default: False ) –

If True, silently skip absent keys.

relabel [source] ¶

relabel(
    labels: Tensor,
    mapping: Union[Sequence[int], Dict[int, int]],
    default: int = 0,
) -> Tensor

Remap integer labels via a lookup table.

mapping can be either:

a sequence of source values (1:1): each value at index \(i\) is mapped to \(i\);
a dict[int, int] (general source → target): supports N-to-1 merges (e.g. SemanticKITTI's moving-car and car both → 0).

Source values not listed in mapping are set to default.

Parameters:

labels (Tensor) –

Integer label tensor (any integer dtype). Output preserves dtype.
mapping (Union[Sequence[int], Dict[int, int]]) –

Source-value listing (1:1) or explicit {source: target} dict (N:1).
default (int, default: 0 ) –

Value assigned to source values not listed in mapping.

Returns:

Tensor –

Remapped tensor with the same shape and dtype as labels.

Raises:

ValueError –

If mapping is empty.

absolute [source] ¶

absolute(x: Tensor, inplace: bool = False) -> Tensor

Make the input tensor absolute.

Parameters:

x (Tensor) –

The input tensor.

Returns:

Tensor –

The absolute tensor.

Examples:

>>> import torch
>>> import torch_pointcloud.transforms.functional as F
>>> x = torch.tensor([-1.0, 2.0, -3.0])
>>> F.absolute(x)
tensor([1., 2., 3.])

utils

ReduceOp module-attribute ¶

SetValue [source] ¶

ToFloat [source] ¶

ToDevice [source] ¶

Relabel [source] ¶

RenameItems [source] ¶

CopyItems [source] ¶

ToTensor [source] ¶

OnesLike [source] ¶

Cat [source] ¶

OneHot [source] ¶

Reduce [source] ¶

KeepItems [source] ¶

Scale [source] ¶

Divide [source] ¶

DivideItems [source] ¶

SubtractItems [source] ¶

Abs [source] ¶

Clamp [source] ¶

relabel [source] ¶

absolute [source] ¶

ReduceOp `module-attribute` ¶