octree

Octree construction, interpolation, and upsampling helpers built on ocnn.

Functions:

build_octree –

Build an ocnn.octree.Octree from a packed point cloud.
octree_interpolate –

Functional interface for ocnn.nn.OctreeInterp, for ease of use.
octree_upsample –

Upsample octree features from src_depth to the finer dst_depth.

build_octree ¶

build_octree(
    pos: Tensor,
    normal: OptTensor = None,
    x: OptTensor = None,
    batch: OptTensor = None,
    labels: OptTensor = None,
    depth: int = 11,
    full_depth: int = 2,
    batch_size: int = 1,
    *,
    return_points: Literal[False] = False,
) -> Octree

build_octree(
    pos: Tensor,
    normal: OptTensor = None,
    x: OptTensor = None,
    batch: OptTensor = None,
    labels: OptTensor = None,
    depth: int = 11,
    full_depth: int = 2,
    batch_size: int = 1,
    *,
    return_points: Literal[True],
) -> tuple[Octree, Points]

build_octree(
    pos: Tensor,
    normal: OptTensor = None,
    x: OptTensor = None,
    batch: OptTensor = None,
    labels: OptTensor = None,
    depth: int = 11,
    full_depth: int = 2,
    batch_size: int = 1,
    *,
    return_points: bool = False,
) -> Octree | tuple[Octree, Points]

Build an ocnn.octree.Octree from a packed point cloud.

Wraps ocnn.octree.Points construction and Octree.build_octree. Coordinates are expected in the ocnn convention, i.e. normalized to \([-1, 1]\).

Parameters:

pos (Tensor) –

Point coordinates of shape \((N, 3)\), normalized to \([-1, 1]\).
normal (OptTensor, default: None ) –

Optional per-point normals of shape \((N, 3)\).
x (OptTensor, default: None ) –

Optional per-point features of shape \((N, C)\).
batch (OptTensor, default: None ) –

Optional per-point batch indices of shape \((N,)\); None for a single sample.
labels (OptTensor, default: None ) –

Optional per-point labels of shape \((N,)\).
depth (int, default: 11 ) –

Depth of the octree.
full_depth (int, default: 2 ) –

Depth up to which all octree nodes are kept, empty or not.
batch_size (int, default: 1 ) –

Number of samples in the batch.
return_points (bool, default: False ) –

If True, also return the intermediate ocnn.octree.Points object.

Returns:

Octree | tuple[Octree, Points] –

The octree, or the tuple (octree, points) when return_points is True.

Example

>>> import torch
>>> from torch_pointcloud.utils.octree import build_octree
>>> pos = torch.rand(100, 3) * 2 - 1
>>> octree = build_octree(pos, depth=5, full_depth=2)  # doctest: +SKIP

octree_interpolate ¶

octree_interpolate(
    x: Tensor,
    octree: Octree,
    depth: int,
    pts: Tensor,
    method: Literal["linear", "nearest"] = "linear",
    nempty: bool = False,
    bound_check: bool = False,
    rescale_pts: bool = True,
) -> Tensor

Functional interface for ocnn.nn.OctreeInterp, for ease of use. This function will interpolate the points with an octree feature.

Note

In comparison to the original ocnn.nn.OctreeInterp, this function signature expects (x, pos, octree, depth) instead of (x, octree, depth, pos), to be consistent with other functions and the design philosophy of this library.

Parameters:

x (Tensor) –

The octree features to interpolate, of shape \((M, C)\) with \(M\) the number of octree nodes at depth.
octree (Octree) –

The octree structure.
depth (int) –

The depth of the octree.
pts (Tensor) –

The points to interpolate at, of shape \((N, 4)\) in the format \((x, y, z, \text{batch})\). The input is not modified.
method (Literal['linear', 'nearest'], default: 'linear' ) –

The method to use for interpolation, "linear" or "nearest".
nempty (bool, default: False ) –

Whether the features x only cover non-empty octree nodes.
bound_check (bool, default: False ) –

Whether to check if the points are within the bounds of the octree.
rescale_pts (bool, default: True ) –

Whether to rescale the point coordinates from \([-1, 1]\) to \([0, 2^\text{depth}]\).

Returns:

Tensor –

The interpolated features of shape \((N, C)\).

octree_upsample ¶

octree_upsample(
    x: Tensor,
    octree: Octree,
    src_depth: int,
    dst_depth: int,
    method: Literal["linear", "nearest"] = "linear",
    nempty: bool = False,
) -> Tensor

Upsample octree features from src_depth to the finer dst_depth.

Interpolates the features of the octree nodes at src_depth at the node centers of dst_depth. When dst_depth == src_depth the features are returned unchanged; a single-level nearest upsample uses the dedicated ocnn kernel.

Parameters:

x (Tensor) –

The octree features at src_depth, of shape \((M_\text{src}, C)\).
octree (Octree) –

The octree structure.
src_depth (int) –

The depth the features live at.
dst_depth (int) –

The target depth; must be greater than or equal to src_depth.
method (Literal['linear', 'nearest'], default: 'linear' ) –

The method to use for interpolation, "linear" or "nearest".
nempty (bool, default: False ) –

Whether the features x only cover non-empty octree nodes.

Returns:

Tensor –

The upsampled features of shape \((M_\text{dst}, C)\).