ocnn.octree

key2xyz	Decodes the shuffled key to x, y, z coordinates and the batch index based on pre-computed look up tables.
xyz2key	Encodes x, y, z coordinates to the shuffled keys based on pre-computed look up tables.
Points	Represents a point cloud and contains some elementary transformations.
Octree	Builds an octree from an input point cloud.
merge_points	A wrapper of Points.merge_points().
merge_octrees	A wrapper of Octree.merge_octrees().
init_octree	A wrapper of Octree.init_octree().

key2xyz(key: Tensor, depth: int = 16)

Decodes the shuffled key to x, y, z coordinates and the batch index based on pre-computed look up tables.

Parameters:

• key (torch.Tensor) – The shuffled key.

• depth (int) – The depth of the shuffled key, and must be smaller than 17 (< 17).

xyz2key(x: Tensor, y: Tensor, z: Tensor, b: Tensor | int | None = None, depth: int = 16)

Encodes x, y, z coordinates to the shuffled keys based on pre-computed look up tables. The speed of this function is much faster than the method based on for-loop.

Parameters:

• x (torch.Tensor) – The x coordinate.

• y (torch.Tensor) – The y coordinate.

• z (torch.Tensor) – The z coordinate.

• b (torch.Tensor or int) – The batch index of the coordinates, and should be smaller than 32768. If b is torch.Tensor, the size of b must be the same as x, y, and z.

• depth (int) – The depth of the shuffled key, and must be smaller than 17 (< 17).

class Points(points: Tensor, normals: Tensor | None = None, features: Tensor | None = None, labels: Tensor | None = None, batch_id: Tensor | None = None, batch_size: int = 1)

Represents a point cloud and contains some elementary transformations.

Parameters:

• points (torch.Tensor) – The coordinates of the points with a shape of (N, 3), where N is the number of points.

• normals (torch.Tensor or None) – The point normals with a shape of (N, 3).

• features (torch.Tensor or None) – The point features with a shape of (N, C), where C is the channel of features.

• labels (torch.Tensor or None) – The point labels with a shape of (N, K), where K is the channel of labels.

• batch_id (torch.Tensor or None) – The batch indices for each point with a shape of (N, 1).

• batch_size (int) – The batch size.

check_input()

Checks the input arguments.

property npt

orient_normal(axis: str = 'x')

Orients the point normals along a given axis.

Parameters:

axis (int) – The coordinate axes, choose from x, y and z. (default: x)

scale(factor: Tensor)

Rescales the point cloud.

Parameters:

factor (torch.Tensor) – The scale factor with shape (3,).

rotate(angle: Tensor)

Rotates the point cloud.

Parameters:

angle (torch.Tensor) – The rotation angles in radian with shape (3,).

translate(dis: Tensor)

Translates the point cloud.

Parameters:

dis (torch.Tensor) – The displacement with shape (3,).

flip(axis: str)

Flips the point cloud along the given axis.

Parameters:

axis (str) – The flipping axis, choosen from x, y, and :obj`z`.

clip(min: float = -1.0, max: float = 1.0, esp: float = 0.01)

Clips the point cloud to [min+esp, max-esp] and returns the mask.

Parameters:

• min (float) – The minimum value to clip.

• max (float) – The maximum value to clip.

• esp (float) – The margin.

inbox_mask(bbmin: float | Tensor = -1.0, bbmax: float | Tensor = 1.0)

Returns a mask indicating whether the points are within the specified bounding box or not.

bbox()

Returns the bounding box.

centralize_scale(bbmin: Tensor, bbmax: Tensor, scale: float = 1.0)

Centralizes the point cloud to [-scale, scale].

Parameters:

• bbmin (torch.Tensor) – The minimum coordinates of the bounding box.

• bbmax (torch.Tensor) – The maximum coordinates of the bounding box.

• scale (float) – The scale factor

normalize(bbmin: Tensor, bbmax: Tensor, scale: float, inplace: bool = False)

Normalizes the point cloud to [0, scale].

Parameters:

• bbmin (torch.Tensor) – The minimum coordinates of the bounding box.

• bbmax (torch.Tensor) – The maximum coordinates of the bounding box.

• scale (float) – The scale factor.

• inplace (bool) – If True, the normalization is performed in-place; otherwise, directly returns the normalized points without modifying the original points.

to(device: device | str, non_blocking: bool = False)

Moves the Points to a specified device.

Parameters:

• device (torch.device or str) – The destination device.

• non_blocking (bool) – If True and the source is in pinned memory, the copy will be asynchronous with respect to the host. Otherwise, the argument has no effect. Default: False.

cuda(non_blocking: bool = False)

Moves the Points to the GPU.

cpu()

Moves the Points to the CPU.

save(filename: str, info: str = 'PNFL')

Save the Points into npz or xyz files.

Parameters:

• filename (str) – The output filename.

• info (str) – The infomation for saving: ‘P’ -> ‘points’, ‘N’ -> ‘normals’, ‘F’ -> ‘features’, ‘L’ -> ‘labels’, ‘B’ -> ‘batch_id’.

copy_from(points: Points)

Shallow copy from another Points.

merge_points(points: List[Points], update_batch_info: bool = True)

Merges a list of points into one batch.

Parameters:

points (List[Octree]) – A list of points to merge. The batch size of each points in the list is assumed to be 1, and the batch_size, batch_id, and batch_npt in the points are ignored.

split_points()

Splits the batched points into a list of Points.

classmethod init_points(device: device | str | None = None, batch_size: int = 1)

Initialzes a Points object with dummy data on a specified device.

Parameters:

• device (torch.device or str or None) – The device of the Points. If None, the device is set to cpu.

• batch_size (int) – The batch size.

class Octree(depth: int, full_depth: int = 2, batch_size: int = 1, device: device | str = 'cpu', **kwargs)

Builds an octree from an input point cloud.

Parameters:

• depth (int) – The octree depth.

• full_depth (int) – The octree layers with a depth small than full_depth are forced to be full.

• batch_size (int) – The octree batch size.

• device (torch.device or str) – Choose from cpu and gpu. (default: cpu)

Note

The octree data structure requires that if an octree node has children nodes, the number of children nodes is exactly 8, in which some of the nodes are empty and some nodes are non-empty. The properties of an octree, including keys, children and neighs, contain both non-empty and empty nodes, and other properties, including features, normals and points, contain only non-empty nodes.

Note

The point cloud must be strictly in range [-1, 1]. A good practice is to normalize it into [-0.99, 0.99] or [0.9, 0.9] to retain some margin.

reset()

Resets the Octree status and constructs several lookup tables.

key(depth: int, nempty: bool = False)

Returns the shuffled key of each octree node.

Parameters:

• depth (int) – The depth of the octree.

• nempty (bool) – If True, returns the results of non-empty octree nodes.

xyzb(depth: int, nempty: bool = False)

Returns the xyz coordinates and the batch indices of each octree node.

Parameters:

• depth (int) – The depth of the octree.

• nempty (bool) – If True, returns the results of non-empty octree nodes.

batch_id(depth: int, nempty: bool = False)

Returns the batch indices of each octree node.

Parameters:

• depth (int) – The depth of the octree.

• nempty (bool) – If True, returns the results of non-empty octree nodes.

nempty_mask(depth: int, reset: bool = False)

Returns a binary mask which indicates whether the cooreponding octree node is empty or not.

Parameters:

• depth (int) – The depth of the octree.

• reset (bool) – If True, recomputes the mask.

nempty_index(depth: int, reset: bool = False)

Returns the indices of non-empty octree nodes.

Parameters:

• depth (int) – The depth of the octree.

• reset (bool) – If True, recomputes the indices.

nempty_neigh(depth: int, reset: bool = False)

Returns the neighborhoods of non-empty octree nodes. :param depth: The depth of the octree. :type depth: int :param reset: If True, recomputes the neighborhoods. :type reset: bool

remap_nempty_neigh(neigh: Tensor, depth: int)

Remaps the neighborhood indices to the non-empty octree nodes.

Parameters:

• neigh (torch.Tensor) – The input neighborhoods with shape (N, 27).

• depth (int) – The depth of the octree.

build_octree(point_cloud: Points, bbmin: float | Tensor = -1.0, bbmax: float | Tensor = 1.0)

Builds an octree from a point cloud.

Parameters:

• point_cloud (Points) – The input point cloud.

• bbmin (float or torch.Tensor) – The minimum coordinates of the bounding box.

• bbmax (float or torch.Tensor) – The maximum coordinates of the bounding box.

Note

For a point cloud in range [-1, 1], a good practice is to normalize it into [0.9, 0.9] to retain some margin.

octree_grow_full(depth: int, update_neigh: bool = True)

Builds the full octree, which is essentially a dense volumetric grid.

Parameters:

• depth (int) – The depth of the octree.

• update_neigh (bool) – If True, construct the neighborhood indices.

octree_split(split: Tensor, depth: int)

Sets whether the octree nodes in depth are splitted or not.

Parameters:

• split (torch.Tensor) – The input tensor with its element indicating status of each octree node: 0 - empty, 1 - non-empty or splitted.

• depth (int) – The depth of current octree.

octree_grow(depth: int, update_neigh: bool = True)

Grows the octree and updates the relevant properties. And in most cases, call Octree.octree_split() to update the splitting status of the octree before this function.

Parameters:

• depth (int) – The depth of the octree.

• update_neigh (bool) – If True, construct the neighborhood indices.

construct_neigh(depth: int)

Constructs the 3x3x3 neighbors for each octree node.

Parameters:

depth (int) – The octree depth with a value larger than 0 (>0).

construct_all_neigh()

A convenient handler for constructing all neighbors.

search_xyzb(query: Tensor, depth: int, nempty: bool = False)

Searches the octree nodes given the query points.

Parameters:

• query (torch.Tensor) – The coordinates of query points with shape (N, 4). The first 3 channels of the coordinates are x, y, and z, and the last channel is the batch index. Note that the coordinates must be in range [0, 2^depth).

• depth (int) – The depth of the octree layer. nemtpy (bool): If true, only searches the non-empty octree nodes.

search_key(query: Tensor, depth: int, nempty: bool = False)

Searches the octree nodes given the query points.

Parameters:

• query (torch.Tensor) – The keys of query points with shape (N,), which are computed from the coordinates of query points.

• depth (int) – The depth of the octree layer. nemtpy (bool): If true, only searches the non-empty octree nodes.

get_neigh(depth: int, kernel: str = '333', stride: int = 1, nempty: bool = False)

Returns the neighborhoods given the depth and a kernel shape.

Parameters:

• depth (int) – The octree depth with a value larger than 0 (>0).

• kernel (str) – The kernel shape from 333, 311, 131, 113, 222, 331, 133, and 313.

• stride (int) – The stride of neighborhoods (1 or 2). If the stride is 2, always returns the neighborhood of the first siblings.

• nempty (bool) – If True, only returns the neighborhoods of the non-empty octree nodes.

get_input_feature(feature: str, nempty: bool = False)

Returns the initial input feature stored in octree.

Parameters:

• feature (str) – A string used to indicate which features to extract from the input octree. If the character N is in feature, the normal signal is extracted (3 channels). Similarly, if D is in feature, the local displacement is extracted (1 channels). If L is in feature, the local coordinates of the averaged points in each octree node is extracted (3 channels). If P is in feature, the global coordinates are extracted (3 channels). If F is in feature, other features (like colors) are extracted (k channels).

• nempty (bool) – If false, gets the features of all octree nodes.

to_points(rescale: bool = True)

Converts averaged points in the octree to a point cloud.

Parameters:

rescale (bool) – rescale the xyz coordinates to [-1, 1] if True.

to(device: device | str, non_blocking: bool = False)

Moves the octree to a specified device.

Parameters:

• device (torch.device or str) – The destination device.

• non_blocking (bool) – If True and the source is in pinned memory, the copy will be asynchronous with respect to the host. Otherwise, the argument has no effect. Default: False.

cuda(non_blocking: bool = False)

Moves the octree to the GPU.

cpu()

Moves the octree to the CPU.

merge_octrees(octrees: List[Octree])

Merges a list of octrees into one batch.

Parameters:

octrees (List[Octree]) – A list of octrees to merge.

Returns:

The merged octree.

Return type:

Octree

classmethod init_like(octree: Octree, device: device | str | None = None)

Initializes the octree like another octree.

Parameters:

• octree (Octree) – The reference octree.

• device (torch.device or str) – The device to use for computation.

classmethod init_octree(depth: int, full_depth: int = 2, batch_size: int = 1, device: device | str = 'cpu')

Initializes an octree to full_depth.

Parameters:

• depth (int) – The depth of the octree.

• full_depth (int) – The octree layers with a depth small than full_depth are forced to be full.

• batch_size (int, optional) – The batch size.

• device (torch.device or str) – The device to use for computation.

Returns:

The initialized Octree object.

Return type:

Octree

merge_points(points: List[Points], update_batch_info: bool = True)

A wrapper of Points.merge_points().

Deprecated since version 2.2.7: Use Points.merge_points() instead.

merge_octrees(octrees: List[Octree])

A wrapper of Octree.merge_octrees().

Deprecated since version 2.2.7: Use Octree.merge_octrees() instead.

init_octree(depth: int, full_depth: int = 2, batch_size: int = 1, device: device | str = 'cpu')

A wrapper of Octree.init_octree().

Deprecated since version 2.2.7: Use Octree.init_octree() instead.