masking

Transforms that build or apply point masks.

Classes:

RemoveNearOrigin –

Remove points that are within a given radius of the origin from dictionary entries.
BoxMask –

Create a boolean mask for points inside an axis-aligned bounding box (AABB).
ApplyMask –

Apply a mask stored in a dictionary to other dictionary entries.
CubeMask –

Create a boolean mask for points inside an axis-aligned cube (L∞ / Chebyshev ball).
SphereMask –

Create a boolean mask for points inside an L2 (Euclidean) ball.

RemoveNearOrigin [source] ¶

RemoveNearOrigin(
    pos_key: str,
    keys: Optional[KeyCollection] = None,
    radius: float = 0.001,
    dst_index_key: Optional[str] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Remove points that are within a given radius of the origin from dictionary entries.

ObjectScene

RemoveNearOrigin on an object

RemoveNearOrigin on a room

See Also

torch_pointcloud.transforms.functional.remove_near_origin

Parameters:

pos_key (str) –

The key containing the positions / coordinates, used to compute the distance from the origin.
keys (Optional[KeyCollection], default: None ) –

Extra keys to filter with the same mask.
radius (float, default: 0.001 ) –

The radius of the sphere.
dst_index_key (Optional[str], default: None ) –

Key for the output-to-input row map (see the module docs on sampling keys); None (the default) disables it.
allow_missing_keys (bool, default: False ) –

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

BoxMask [source] ¶

BoxMask(
    keys: KeyCollection,
    bbox: tuple[float, ...],
    dst_keys: Optional[KeyCollection] = None,
    dim: int = -1,
    strict: bool = False,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Create a boolean mask for points inside an axis-aligned bounding box (AABB).

Membership condition along dim (default, boundary points included):

\[ \text{bbmin}_j \leq x_j \leq \text{bbmax}_j \quad \forall j \]

where bbox = (*bbmin, *bbmax) is the AABB. With strict=True the inequalities are strict, so boundary points are excluded.

Sibling masks:

CubeMask - L∞ ball (center + radius)
SphereMask - L2 ball (center + radius)

ObjectScene

BoxMask on an object

BoxMask on a room

See Also

torch_pointcloud.transforms.functional.box_mask

Parameters:

keys (KeyCollection) –

The keys to create the mask for.
bbox (tuple[float, ...]) –

The bounding box used to mask input tensors, as (*bbmin, *bbmax).
dst_keys (Optional[KeyCollection], default: None ) –

The keys to store the mask in.
dim (int, default: -1 ) –

The dimension to create the mask over.
strict (bool, default: False ) –

If True, use strict inequalities (points exactly on the boundary are excluded).
allow_missing_keys (bool, default: False ) –

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

ApplyMask [source] ¶

ApplyMask(
    keys: KeyCollection,
    mask_key: str,
    dst_keys: Optional[KeyCollection] = None,
    dst_index_key: Optional[str] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Apply a mask stored in a dictionary to other dictionary entries.

See Also

torch_pointcloud.transforms.functional.apply_mask

ObjectScene

ApplyMask on an object

ApplyMask on a room

Parameters:

keys (KeyCollection) –

The keys to apply the mask to.
mask_key (str) –

The key containing the mask.
dst_keys (Optional[KeyCollection], default: None ) –

The keys to store the transformed data in.
dst_index_key (Optional[str], default: None ) –

Key for the output-to-input row map (see the module docs on sampling keys); None (the default) disables it. Leave it unset when dst_keys differ from keys, since the map would describe the dst_keys rows.
allow_missing_keys (bool, default: False ) –

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

CubeMask [source] ¶

CubeMask(
    keys: KeyCollection,
    center: ValueCollection[float],
    radius: float,
    dim: int = -1,
    dst_keys: Optional[KeyCollection] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Create a boolean mask for points inside an axis-aligned cube (L∞ / Chebyshev ball).

Membership condition along dim:

\[ \| x - c \|_{\infty} \leq r \]

Geometrically, the L∞ ball of radius \(r\) centered at \(c\) is a hypercube with edge \(2r\) aligned to the axes. Pair with SphereMask (L2) and BoxMask (AABB) for the mask family.

ObjectScene

CubeMask on an object

CubeMask on a room

See Also

torch_pointcloud.transforms.functional.cube_mask

Parameters:

keys (KeyCollection) –

The keys to create the mask for.
center (ValueCollection[float]) –

The center of the cube.
radius (float) –

The radius (half-edge) of the cube.
dim (int, default: -1 ) –

The dimension to create the mask over.
dst_keys (Optional[KeyCollection], default: None ) –

The keys to store the mask 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.

SphereMask [source] ¶

SphereMask(
    keys: KeyCollection,
    center: ValueCollection[float],
    radius: float,
    dim: int = -1,
    dst_keys: Optional[KeyCollection] = None,
    allow_missing_keys: bool = False,
)

Bases: DictTransform

Create a boolean mask for points inside an L2 (Euclidean) ball.

Membership condition along dim:

\[ \| x - c \|_2 \leq r \]

Pair with CubeMask (L∞) and BoxMask (AABB) for the mask family. RemoveNearOrigin(radius=r) is equivalent to Compose([SphereMask(center=(0,0,0), radius=r, invert=True), ApplyMask(...)]).

ObjectScene

SphereMask on an object

SphereMask on a room

See Also

torch_pointcloud.transforms.functional.sphere_mask

Parameters:

keys (KeyCollection) –

The keys to create the mask for.
center (ValueCollection[float]) –

The center of the sphere.
radius (float) –

The radius of the sphere.
dim (int, default: -1 ) –

The dimension to compute the Euclidean norm over.
dst_keys (Optional[KeyCollection], default: None ) –

The keys to store the mask 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.

sphere_mask [source] ¶

sphere_mask(
    x: Tensor,
    center: Union[Tensor, Sequence[float], float],
    radius: float,
    dim: int = -1,
) -> Tensor

Create a boolean mask for points inside an L2 (Euclidean) ball.

Membership condition along dim:

\[ \| x - c \|_2 \leq r \]

Pair with cube_mask (L∞) and box_mask (explicit AABB).

Parameters:

x (Tensor) –

The input tensor of shape \((\ldots, D)\) along dim.
center (Union[Tensor, Sequence[float], float]) –

The center of the sphere, shape \((D,)\) or broadcastable.
radius (float) –

The radius of the sphere.
dim (int, default: -1 ) –

The dimension to compute the Euclidean norm over.

Returns:

Tensor –

The boolean mask, with dim reduced.

remove_near_origin [source] ¶

remove_near_origin(
    pos: Tensor, radius: float, return_mask: Literal[True]
) -> Tuple[Tensor, Tensor]

remove_near_origin(
    pos: Tensor,
    radius: float,
    return_mask: Literal[False] = False,
) -> Tensor

remove_near_origin(
    pos: Tensor, radius: float, return_mask: bool
) -> Union[Tensor, Tuple[Tensor, Tensor]]

remove_near_origin(
    pos: Tensor,
    radius: float = 0.001,
    return_mask: bool = False,
) -> Any

Remove points that are within a given radius (L2) of the origin.

Equivalent to inverting sphere_mask(pos, center=0, radius=r) and indexing.

Parameters:

pos (Tensor) –

The input tensor of shape \((N, D)\).
radius (float, default: 0.001 ) –

The L2 radius (Euclidean distance) below which points are removed.
return_mask (bool, default: False ) –

If True, also return the keep-mask.

Returns:

Any –

The filtered tensor; or (filtered, mask) if return_mask=True.

bounding_box [source] ¶

bounding_box(x: Tensor, dim: int = 0) -> tuple[float, ...]

Returns the min and max values along a given dimension.

Parameters:

x (Tensor) –

The input tensor of shape (..., D, ...).
dim (int, default: 0 ) –

The dimension to compute bounds over.

Returns:

tuple[float, ...] –

A tuple of (*min, *max) values.

box_mask [source] ¶

box_mask(
    x: Tensor,
    bbox: tuple[float, ...],
    dim: int = -1,
    strict: bool = False,
) -> Tensor

Create a boolean mask for points inside an axis-aligned bounding box (AABB).

Membership condition along dim (default, boundary points included):

\[ \text{bbmin}_j \leq x_j \leq \text{bbmax}_j \quad \forall j \]

With strict=True the inequalities are strict, so boundary points are excluded.

Parameters:

x (Tensor) –

The input tensor of shape \((\ldots, D)\) along dim.
bbox (tuple[float, ...]) –

AABB as a flat tuple (*bbmin, *bbmax) of length \(2 \cdot D\); a row longer than \(D\) is tested by its first \(D\) coordinates, so a box row \((c_x, c_y, c_z, \ldots)\) is tested by its center.
dim (int, default: -1 ) –

The dimension to compute the mask over.
strict (bool, default: False ) –

If True, use strict inequalities (points exactly on the boundary are excluded).

Returns:

Tensor –

The boolean mask, with dim reduced.

Raises:

ValueError –

If len(bbox) is odd or larger than 2 * x.shape[dim].

apply_mask [source] ¶

apply_mask(x: Tensor, mask: Tensor) -> Tensor

Apply a mask to a tensor.

Parameters:

x (Tensor) –

The input tensor.
mask (Tensor) –

The mask.

Returns:

Tensor –

The tensor with the mask applied.

Examples:

>>> import torch
>>> import torch_pointcloud.transforms.functional as F
>>> x = torch.tensor([1.0, 2.0, 3.0])
>>> mask = torch.tensor([True, False, True])
>>> F.apply_mask(x, mask)
tensor([1., 3.])

cube_mask [source] ¶

cube_mask(
    x: Tensor,
    center: Union[Tensor, Sequence[float], float],
    radius: float,
    dim: int = -1,
) -> Tensor

Create a boolean mask for points inside an axis-aligned cube (L∞ / Chebyshev ball).

Membership condition along dim:

\[ \| x - c \|_{\infty} \leq r \]

Geometrically, the L∞ ball of radius \(r\) centered at \(c\) is a hypercube with edge \(2r\) aligned to the axes. Pair with sphere_mask (L2) and box_mask (explicit AABB).

Parameters:

x (Tensor) –

The input tensor of shape \((\ldots, D)\) along dim.
center (Union[Tensor, Sequence[float], float]) –

The center of the cube, shape \((D,)\) or broadcastable.
radius (float) –

The half-edge (radius) of the cube.
dim (int, default: -1 ) –

The dimension to reduce the per-axis comparison over.

Returns:

Tensor –

The boolean mask, with dim reduced.