conversion

Conversions between iterables, batch index representations (offset, bincount, cu_seqlens), and tensor formats.

Functions:

is_iterable –

Check if a value is iterable.
ensure_iterable –

Convert a value to the given iterable type. If the value is a scalar, it will be wrapped in it.
ensure_iterable_size –

Convert a value to a list of a given size.
ensure_list –

Convert a value to a list. If the value is a numpy array or torch tensor,
ensure_list_size –

Convert a value to a list of a given size.
ensure_tuple –

Convert a value to a tuple. If the value is a scalar or single element,
ensure_tuple_size –

Convert a value to a tuple of a given size.
ensure_option –

Ensure that the provided value is one of the given options.
offset_to_bincount –

Convert an offset tensor to a bincount tensor.
offset_to_batch –

Convert an offset tensor to a batch index tensor.
offset_to_cu_seqlens –

Convert an offset tensor to a cumulative sequence lengths tensor.
batch_to_offset –

Convert a batch index tensor to an offset tensor.
batch_to_bincount –

Convert a batch index tensor to a bincount tensor.
batch_to_cu_seqlens –

Convert a batch index tensor to a cumulative sequence lengths tensor.
bincount_to_offset –

Convert a bincount tensor to an offset tensor.
bincount_to_batch –

Convert a bincount tensor to a batch index tensor.
bincount_to_cu_seqlens –

Convert a bincount tensor to a cumulative sequence lengths tensor.
cu_seqlens_to_offset –

Convert a cumulative sequence lengths tensor to an offset tensor.
cu_seqlens_to_bincount –

Convert a cumulative sequence lengths tensor to a bincount tensor.
cu_seqlens_to_batch –

Convert a cumulative sequence lengths tensor to a batch index tensor.
convert_to_spconv_tensor –

Convert point features and coordinates to a spconv.SparseConvTensor sparse tensor.
convert_from_spconv_tensor –

Convert a spconv.SparseConvTensor back to packed features, coordinates, and batch indices.
convert_to_tensor –

Utility function to convert data to a tensor object. It will convert data following these rules:
convert_to_numpy –

Convert data to a numpy array. It will convert data following these rules:

is_iterable ¶

is_iterable(value: Any) -> TypeGuard[Iterable[Any]]

Check if a value is iterable. A value is considered iterable if it is an instance of Iterable (i.e. list, tuple, set or any iterable defining the __iter__ method) and not an instance of str or bytes.

It is worth noting that torch.Tensor and np.ndarray are considered iterable (here) only if they have a dimension greater than 0 (i.e. not scalars).

Parameters:

value (Any) –

The value to check.

Returns:

TypeGuard[Iterable[Any]] –

True if the value is iterable, False otherwise.

ensure_iterable ¶

ensure_iterable(
    value: Any,
    type: Type[T],
    recursive: bool = False,
    none_as_empty: bool = False,
) -> T

Convert a value to the given iterable type. If the value is a scalar, it will be wrapped in it.

Numpy arrays and torch tensors are converted to nested lists first, so their elements come back as Python scalars.

Parameters:

value (Any) –

The value to convert.
type (Type[T]) –

The iterable type to build (e.g. list, tuple).
recursive (bool, default: False ) –

If True, the function will recursively apply itself to the elements of the iterable.
none_as_empty (bool, default: False ) –

If True, and the value is None, an empty iterable will be returned.

Returns:

T –

The value as an iterable of the given type.

ensure_iterable_size ¶

ensure_iterable_size(
    value: Any,
    type: Type[T],
    size: int,
    recursive: bool = False,
    none_as_empty: bool = False,
    extra_msg: str = "",
) -> T

Convert a value to a list of a given size. If the value is a scalar, it will be repeated to match the size. If the value's length does not match the size, an error will be raised.

ensure_list ¶

ensure_list(
    value: Any,
    recursive: bool = False,
    none_as_empty: bool = False,
) -> List[Any]

Convert a value to a list. If the value is a numpy array or torch tensor, it will be converted to a list. If the value is a scalar, it will be wrapped in a list.

Note

If the value is None, it will be wrapped in a list.

Parameters:

value (Any) –

The value to convert.
recursive (bool, default: False ) –

If True, the function will recursively apply itself to the elements of the list.
none_as_empty (bool, default: False ) –

If True, and the value is None, an empty list will be returned.

Returns:

List[Any] –

The value as a list.

Examples:

>>> ensure_list(1)
[1]
>>> ensure_list([1, 2, 3])
[1, 2, 3]
>>> ensure_list(np.array([1, 2, 3]))
[1, 2, 3]
>>> ensure_list(torch.tensor([1, 2, 3]))
[1, 2, 3]
>>> ensure_list(None)
[None]
>>> ensure_list(None, none_as_empty=True)
[]

ensure_list_size ¶

ensure_list_size(
    value: Any,
    size: int,
    recursive: bool = False,
    none_as_empty: bool = False,
    extra_msg: str = "",
) -> List[Any]

Convert a value to a list of a given size. If the value is a scalar, it will be repeated to match the size. If the value's length does not match the size, an error will be raised.

ensure_tuple ¶

ensure_tuple(
    value: Any,
    recursive: bool = False,
    none_as_empty: bool = False,
) -> Tuple[Any, ...]

Convert a value to a tuple. If the value is a scalar or single element, it will be wrapped in a tuple.

Parameters:

value (Any) –

The value to convert.
recursive (bool, default: False ) –

If True, the function will recursively apply itself to the elements of the tuple.
none_as_empty (bool, default: False ) –

If True, and the value is None, an empty tuple will be returned.

Returns:

Tuple[Any, ...] –

The value as a tuple.

Examples:

>>> ensure_tuple(1)
(1,)
>>> ensure_tuple([1, 2, 3])
(1, 2, 3)
>>> ensure_tuple("test")
('test',)
>>> ensure_tuple(np.array([1, 2, 3]))
(1, 2, 3)
>>> ensure_tuple(torch.tensor([1, 2, 3], device="cuda"))  # doctest: +SKIP
(1, 2, 3)

ensure_tuple_size ¶

ensure_tuple_size(
    value: Any,
    size: int,
    recursive: bool = False,
    none_as_empty: bool = False,
    extra_msg: str = "",
) -> Tuple[Any, ...]

Convert a value to a tuple of a given size. If the value is a scalar, it will be repeated to match the size. If the value's length does not match the size, an error will be raised.

Parameters:

value (Any) –

The value to convert.
size (int) –

The size of the tuple.
recursive (bool, default: False ) –

If True, the function will recursively apply itself to the elements of the tuple.
none_as_empty (bool, default: False ) –

If True, and the value is None, an empty tuple will be returned.
extra_msg (str, default: '' ) –

An additional message to include in the error.

Returns:

Tuple[Any, ...] –

The value as a tuple of the given size.

Examples:

>>> ensure_tuple_size(1, 3)
(1, 1, 1)
>>> ensure_tuple_size([1, 2, 3], 3)
(1, 2, 3)
>>> ensure_tuple_size(torch.tensor([1, 2, 3]), 3)
(1, 2, 3)
>>> ensure_tuple_size(np.array([1, 2, 3]), 3)
(1, 2, 3)

ensure_option ¶

ensure_option(
    value: T, options: Any, /, *, name: str = "option"
) -> T

Ensure that the provided value is one of the given options. This function will return the value if it is one of the given options. If the value is not a member of the options, a ValueError will be raised.

Supported options are iterables of hashable values, enums, or literal types.

Parameters:

value (T) –

The value to check.
options (Any) –

The options to check against.
name (str, default: 'option' ) –

The name of the option displayed in error messages. This is used to track which parameter is invalid.

Returns:

T –

The option.

Examples:

>>> ensure_option("one", ["one", "two"])  # Ok
'one'
>>> ensure_option("one", Literal["one", "two"])  # Ok
'one'
>>> ensure_option(1, Enum("Number", "ONE, TWO"))  # Ok
1
>>> ensure_option("three", ["one", "two"])  # Error
Traceback (most recent call last):
    ...
ValueError: Invalid option: 'three'. Valid options are: 'one', 'two'.

offset_to_bincount ¶

offset_to_bincount(offset: Tensor) -> Tensor

Convert an offset tensor to a bincount tensor.

Parameters:

offset (Tensor) –

The offset tensor.

Returns:

Tensor –

The bincount tensor.

Examples:

>>> import torch
>>> offset = torch.tensor([4, 7, 12])
>>> offset_to_bincount(offset)
tensor([4, 3, 5])

offset_to_batch ¶

offset_to_batch(offset: Tensor) -> Tensor

Convert an offset tensor to a batch index tensor.

Parameters:

offset (Tensor) –

The offset tensor.

Returns:

Tensor –

The batch index tensor.

Examples:

>>> import torch
>>> offset = torch.tensor([4, 7, 12])
>>> offset_to_batch(offset)
tensor([0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 2])

offset_to_cu_seqlens ¶

offset_to_cu_seqlens(offset: Tensor) -> Tensor

Convert an offset tensor to a cumulative sequence lengths tensor. A cumulative sequence length is a tensor of shape $ (N + 2,)$ where $N$ is the size of the batch. The first element is 0 and the last element is the size of the batch. The other elements are the cumulative sum of the batch sizes.

Note

This function was provided to ease the conversion between offset tensor and cu_seqlens tensor format required by spconv.

batch_to_offset ¶

batch_to_offset(batch: Tensor) -> Tensor

Convert a batch index tensor to an offset tensor.

Parameters:

batch (Tensor) –

The batch indices of the points.

Returns:

Tensor –

The offset tensor.

Examples:

>>> import torch
>>> batch = torch.tensor([0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 2])
>>> batch_to_offset(batch)
tensor([ 4,  7, 12])

batch_to_bincount ¶

batch_to_bincount(batch: Tensor) -> Tensor

Convert a batch index tensor to a bincount tensor.

Parameters:

batch (Tensor) –

The batch indices of the points.

Returns:

Tensor –

The bincount tensor.

Examples:

>>> import torch
>>> batch = torch.tensor([0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 2])
>>> batch_to_bincount(batch)
tensor([4, 3, 5])

batch_to_cu_seqlens ¶

batch_to_cu_seqlens(batch: Tensor) -> Tensor

Convert a batch index tensor to a cumulative sequence lengths tensor. A cumulative sequence length is a tensor of shape $ (N + 2,)$ where $N$ is the size of the batch. The first element is 0 and the last element is the size of the batch. The other elements are the cumulative sum of the batch sizes.

Note

This function was provided to ease the conversion between batch tensor and cu_seqlens tensor format required by spconv.

bincount_to_offset ¶

bincount_to_offset(bincount: Tensor) -> Tensor

Convert a bincount tensor to an offset tensor.

Parameters:

bincount (Tensor) –

The bincount tensor.

Returns:

Tensor –

The offset tensor.

Examples:

>>> import torch
>>> bincount = torch.tensor([4, 3, 5])
>>> bincount_to_offset(bincount)
tensor([ 4,  7, 12])

bincount_to_batch ¶

bincount_to_batch(bincount: Tensor) -> Tensor

Convert a bincount tensor to a batch index tensor.

Parameters:

bincount (Tensor) –

The bincount tensor.

Returns:

Tensor –

The batch index tensor.

Examples:

>>> import torch
>>> bincount = torch.tensor([4, 3, 5])
>>> bincount_to_batch(bincount)
tensor([0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 2])

bincount_to_cu_seqlens ¶

bincount_to_cu_seqlens(bincount: Tensor) -> Tensor

Convert a bincount tensor to a cumulative sequence lengths tensor.

Parameters:

bincount (Tensor) –

The bincount tensor.

Returns:

Tensor –

The cumulative sequence lengths tensor.

Examples:

>>> import torch
>>> bincount = torch.tensor([4, 3, 5])
>>> bincount_to_cu_seqlens(bincount)
tensor([ 0,  4,  7, 12])

cu_seqlens_to_offset ¶

cu_seqlens_to_offset(cu_seqlens: Tensor) -> Tensor

Convert a cumulative sequence lengths tensor to an offset tensor.

Parameters:

cu_seqlens (Tensor) –

The cumulative sequence lengths tensor.

Returns:

Tensor –

The offset tensor.

Examples:

>>> import torch
>>> cu_seqlens = torch.tensor([0, 4, 7, 12])
>>> cu_seqlens_to_offset(cu_seqlens)
tensor([ 4,  7, 12])

cu_seqlens_to_bincount ¶

cu_seqlens_to_bincount(cu_seqlens: Tensor) -> Tensor

Convert a cumulative sequence lengths tensor to a bincount tensor.

Parameters:

cu_seqlens (Tensor) –

The cumulative sequence lengths tensor.

Returns:

Tensor –

The bincount tensor.

Examples:

>>> import torch
>>> cu_seqlens = torch.tensor([0, 4, 7, 12])
>>> cu_seqlens_to_bincount(cu_seqlens)
tensor([4, 3, 5])

cu_seqlens_to_batch ¶

cu_seqlens_to_batch(cu_seqlens: Tensor) -> Tensor

Convert a cumulative sequence lengths tensor to a batch index tensor.

Parameters:

cu_seqlens (Tensor) –

The cumulative sequence lengths tensor.

Returns:

Tensor –

The batch index tensor.

Examples:

>>> import torch
>>> cu_seqlens = torch.tensor([0, 4, 7, 12])
>>> cu_seqlens_to_batch(cu_seqlens)
tensor([0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 2])

convert_to_spconv_tensor ¶

convert_to_spconv_tensor(
    x: Tensor,
    pos: Tensor,
    batch: Tensor,
    spatial_shape: Optional[Sequence[int]] = None,
    padding: int = 96,
    batch_size: Optional[int] = None,
) -> SparseConvTensor

Convert point features and coordinates to a spconv.SparseConvTensor sparse tensor.

Parameters:

x (Tensor) –

The point features of shape $(N, C)$.
pos (Tensor) –

The integer voxel coordinates of shape $(N, 3)$.
batch (Tensor) –

The batch indices of the points of shape $(N,)$.
spatial_shape (Optional[Sequence[int]], default: None ) –

The spatial shape of the sparse tensor. When None, it is inferred as the per-axis maximum of pos plus padding.
padding (int, default: 96 ) –

Padding (in voxels) added to the inferred spatial shape.
batch_size (Optional[int], default: None ) –

Number of scenes in the batch. When None, it is inferred as batch.max() + 1, which drops trailing empty scenes; pass it explicitly when those must be preserved.

Returns:

SparseConvTensor –

The spconv.SparseConvTensor sparse tensor.

Shape

x: $(N, C)$
pos: $(N, 3)$
batch: $(N,)$

convert_from_spconv_tensor ¶

convert_from_spconv_tensor(
    spconv_tensor: SparseConvTensor,
) -> Tuple[Tensor, Tensor, Tensor]

Convert a spconv.SparseConvTensor back to packed features, coordinates, and batch indices.

Parameters:

spconv_tensor (SparseConvTensor) –

The sparse tensor to unpack.

Returns:

Tensor –

Tuple (x, pos, batch) with features $(N, C)$, integer voxel coordinates $(N, 3)$,
Tensor –

and batch indices $(N,)$.

convert_to_tensor ¶

convert_to_tensor(data: Any, /, strict: bool = True) -> Any

Utility function to convert data to a tensor object. It will convert data following these rules:

If the data is a tensor, it will be returned as is.
If the data is a numpy array, it will be converted to a tensor.
If the data is a scalar, it will be converted to a tensor scalar.
If the data is a dictionary, each value will be converted recursively.
If the data is not supported, a TypeError will be raised unless strict is False.

Parameters:

data (Any) –

The data to convert.
strict (bool, default: True ) –

If True, a TypeError will be raised if the data type is not supported. If False, the data will be returned as is.

Returns:

Any –

The converted data.

Examples:

>>> convert_to_tensor([1, 2, 3])
tensor([1, 2, 3])
>>> convert_to_tensor(np.array([1, 2, 3]))
tensor([1, 2, 3])
>>> convert_to_tensor(torch.tensor([1, 2, 3]))
tensor([1, 2, 3])
>>> convert_to_tensor({"a": [1, 2, 3], "b": 4})
{'a': tensor([1, 2, 3]), 'b': tensor(4)}
>>> convert_to_tensor(None)
Traceback (most recent call last):
    ...
TypeError: Unsupported data type...
>>> print(convert_to_tensor(None, strict=False))
None
>>> convert_to_tensor("value", strict=False)
'value'

convert_to_numpy ¶

convert_to_numpy(data: Any, /, strict: bool = True) -> Any

Convert data to a numpy array. It will convert data following these rules:

If the data is a numpy array, it will be returned as is.
If the data is a tensor, it will be converted to a numpy array.
If the data is a scalar, it will be converted to a numpy scalar.
If the data is a dictionary, each value will be converted recursively.
If the data is not supported, a TypeError will be raised unless strict is False.

Parameters:

data (Any) –

The data to convert.
strict (bool, default: True ) –

If True, a TypeError will be raised if the data type is not supported. If False, the data will be returned as is.

Returns:

Any –

The converted data.

Examples:

>>> convert_to_numpy([1, 2, 3])
array([1, 2, 3])
>>> convert_to_numpy(np.array([1, 2, 3]))
array([1, 2, 3])
>>> convert_to_numpy(torch.tensor([1, 2, 3]))
array([1, 2, 3])
>>> convert_to_numpy({"a": [1, 2, 3], "b": 4})
{'a': array([1, 2, 3]), 'b': array(4)}
>>> convert_to_numpy(None)
Traceback (most recent call last):
    ...
TypeError: Unsupported data type...
>>> print(convert_to_numpy(None, strict=False))
None
>>> convert_to_numpy("value", strict=False)
'value'