serialization

Space-filling curve serialization of voxel coordinates using Z-order and Hilbert encodings.

Functions:

serialize_coords –

Encode / serialize grid coordinates into a code depending on the serialization order.

serialize_coords ¶

serialize_coords(
    pos_grid: Tensor,
    batch: OptTensor,
    depth: int,
    order: SerializationOrder,
) -> Tensor

Encode / serialize grid coordinates into a code depending on the serialization order. The code can be used to sort the grid coordinates or to index them, and was introduced in the paper Point Transformer V3: Simpler, Faster, Stronger by Xiaoyang Wu, Li Jiang, Peng-Shuai Wang, Zhijian Liu, Xihui Liu, Yu Qiao, Wanli Ouyang, Tong He, Hengshuang Zhao.

Note

To get the code's order and inverse, you can use torch.argsort twice:

>>> code = serialize_coords(pos_grid, batch, depth, order)  # doctest: +SKIP
>>> order = torch.argsort(code)  # doctest: +SKIP
>>> inverse = torch.argsort(order)  # doctest: +SKIP

Parameters:

pos_grid (Tensor) –

A int tensor of shape \((N, 3)\) containing the grid coordinates. Every coordinate must lie in \([0, 2^{\text{depth}})\) per axis: the encoders keep only the low depth bits, so out-of-range values (e.g. a negative coordinate) silently wrap around to a valid code. Grids produced by Voxelize or Quantize are shifted by the per-axis minimum and satisfy this.
batch (OptTensor) –

A int tensor of contiguous values from 0 to \(B - 1\) of shape \((N)\) containing the batch \(B\) indices.
depth (int) –

The depth of the serialization cube.
order (SerializationOrder) –

The serialization order. Available orders are: - "z": Z-order curve. - "z-trans": Z-order curve transposed. - "hilbert": Hilbert curve. - "hilbert-trans": Hilbert curve transposed.

Returns:

Tensor –

A int tensor of shape \((N)\) containing the serialized grid coordinates.

Examples:

>>> pos = torch.randn(10, 3)
>>> grid_size = 0.1
>>> pos_grid = torch.div(pos - pos.min(0).values, grid_size, rounding_mode="trunc")
>>> batch = torch.zeros(10, dtype=torch.long)
>>> code = serialize_coords(pos_grid, batch, depth=5, order="z")  # doctest: +SKIP