conversion

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.

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.

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.

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.

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)
[]

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.

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)

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 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'.

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])

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])

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.

Parameters:

• offset (Tensor) –

  The offset tensor.

Returns:

• Tensor –

  The cumulative sequence lengths tensor.

Examples:

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

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])

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])

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.

Parameters:

• batch (Tensor) –

  The batch indices of the points.

Returns:

• Tensor –

  The cumulative sequence lengths tensor.

Examples:

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

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])

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])

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])

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])

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])

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 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.

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,)\).

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 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'

Utility function to ensure that items are converted in nested lists compatible with Multi-Scale Grouping (MSG) mode. This function will convert a list of list into a list of list of list.

>>> sa_channels = [[32, 64], [128, 256], [[256, 512, 512], [256, 512, 1024]]]
>>> ensure_msg_list(sa_channels)
[[[32, 64]], [[128, 256]], [[256, 512, 512], [256, 512, 1024]]]

Validate the length of a sequence, then nest it for Multi-Scale Grouping (MSG) compatibility.

Parameters:

• value (Sequence[Any]) –

  Sequence of per-block channel specifications.

• size (int) –

  Expected number of elements in value.

• extra_msg (str, default: '' ) –

  Extra context appended to the error message.

Returns:

• Sequence[Any] –

  The value converted to a list of lists of lists (one inner list per grouping scale).

Raises:

• ValueError –

  If value does not have exactly size elements.

>>> ensure_msg_list_size([[32, 64], [64, 128]], size=2)
[[[32, 64]], [[64, 128]]]