kaolin.rep

API

class kaolin.rep.Spc(octrees, lengths, max_level=None, pyramids=None, exsum=None, point_hierarchies=None, features=None)

Bases: object

Data class holding all Structured Point Cloud (SPC) information.

This class supports batching through packed representation: a single Spc object can pack multiple SPC structures of variable sizes.

SPC data structures are represented through the combination various tensors detailed below:

octrees compress the information required to build a full SPC. In practice, they are a low level structure which also constitute the core part of the SPC data structure.

octrees are kept as a torch.ByteTensor, where each byte represents a single octree parent cell, and each bit represents the occupancy of a child octree cell. e.g: 8 bits for 8 cells.

Bits describe the octree cells in Morton Order:

. . . . . . . .
| .   3  .  7  | .                    3   7
|   . . . . . . . .           ===>    1   5
|   | .   1  . | 5   .
|   |   . . . . . . . .
|   |    |     |       |              2   6
 . .|. . | . . .       |      ===>    0   4
   .| 2  |.  6   .     |
     . . | . . . . .   |
       . | 0  .  4   . |
         . . . . . . . .

If a cell is occupied, an additional cell byte may be generated in the next level, up till the argument level.

For example, a SPC.octrees field may, look as follows:

tensor([255, 128,  64,  32,  16,   8,   4,   2,  23], dtype=torch.uint8)

Here “octrees” represents an octree of 9 nodes. The binary representation should be interpreted as follows:

Level #1, Path*,      11111111    (All cells are occupied, therefore 8 bytes are allocated for level 2)
Level #2, Path*-1,    10000000
Level #2, Path*-2,    01000000
Level #2, Path*-3,    00100000
Level #2, Path*-4,    00010000
Level #2, Path*-5,    00001000
Level #2, Path*-6,    00000100
Level #2, Path*-7,    00000010
Level #2, Path*-8,    00010111

lengths is a tensor of integers required to support batching. Since we assume a packed representation, all octree cells are shaped as a single stacked 1D tensor. lengths specifies the number of cells (bytes) each octree uses.

features represent an optional per-point feature vector. When features is not None, a feature is kept for each point at the highest-resolution level in the octree.

max_level is an integer which specifies how many recursive levels an octree should have.

point_hierarchies, pyramid, exsum are auxilary structures, which are generated upon request and enable efficient indexing to SPC entries.

KEYS = {'exsum', 'lengths', 'max_level', 'octrees', 'point_hierarchies', 'pyramids'}
property batch_size
cpu(memory_format=torch.preserve_format)
cuda(device='cuda', non_blocking=False, memory_format=torch.preserve_format)
property exsum
classmethod from_features(feature_grids, masks=None)

Creates a sparse Spc object from the feature grid.

Parameters

  • feature_grids (torch.Tensor) – The sparse 3D feature grids, of shape \(( ext{batch_size}, ext{feature_dim}, X, Y, Z)\)

  • masks (optional, torch.BoolTensor) – The topology mask, showing where are the features, of shape \(( ext{batch_size}, X, Y, Z)\). Default: A feature is determined when not full of zeros.

Returns

a tuple containing:

  • The octree, of size \(( ext{num_nodes})\)

  • The lengths of each octree, of size \(( ext{batch_size})\)

  • The coalescent features, of same dtype than feature_grids, of shape \(( ext{num_features}, ext{feature_dim})\).

Return type

(torch.ByteTensor, torch.IntTensor, torch.Tensor)

Returns

a Spc, with length of \(( ext{batch_size})\), an octree of size octree, of size \(( ext{num_nodes})\), and the features field of the same dtype as feature_grids and of shape \(( ext{num_features}, ext{feature_dim})\).

Return type

(kaolin.rep.Spc)

classmethod from_list(octrees_list)

Generate an Spc from a list of octrees.

Parameters

octrees_list (list of torch.ByteTensor) – list containing multiple 1D torch.ByteTensor, each representing an octree.

Returns

a new Spc.

Return type

(kaolin.rep.Spc)

classmethod make_dense(level, device='cuda')

Creates a dense, fully occupied Spc object. The Spc will have level levels of detail.

Parameters

  • level (int) – Number of levels to use for the dense Spc.

  • device (torch.device) – Torch device to keep the spc octree

Returns

a new fully occupied Spc.

Return type

(kaolin.rep.Spc)

property max_level
num_points(lod: int)

Returns how many points the SPC holds at a given level of detail.

Parameters

lod (int) – Index of a level of detail. Level 0 is considered the root and always holds a single point, level 1 holds up to \(( ext{num_points}=8)\) points, level 2 holds up to \(( ext{num_points}=8^{2})\), and so forth.

Returns

The number of points each SPC entry holds for the given level of detail.

Return type

(torch.Tensor)

property point_hierarchies
property pyramids
to(device, non_blocking=False, memory_format=torch.preserve_format)
to_dict(keys=None)