fastdev.utils.struct
====================

.. py:module:: fastdev.utils.struct

.. autoapi-nested-parse::

   Reference: https://github.com/facebookresearch/pytorch3d/blob/89b851e64c7af3a13766462280597a9d06bf9ae7/pytorch3d/structures/utils.py





Module Contents
---------------

.. py:function:: list_to_padded(x: Union[List[torch.Tensor], Tuple[torch.Tensor]], pad_size: Union[Sequence[int], None] = None, pad_value: Union[float, int] = 0.0, equisized: bool = False) -> torch.Tensor

   Transforms a list of N tensors each of shape (Si_0, Si_1, ... Si_D)
   into:
   - a single tensor of shape (N, pad_size(0), pad_size(1), ..., pad_size(D))
     if pad_size is provided
   - or a tensor of shape (N, max(Si_0), max(Si_1), ..., max(Si_D)) if pad_size is None.

   :param x: list of Tensors
   :param pad_size: list(int) specifying the size of the padded tensor.
                    If `None` (default), the largest size of each dimension
                    is set as the `pad_size`.
   :param pad_value: float value to be used to fill the padded tensor
   :param equisized: bool indicating whether the items in x are of equal size
                     (sometimes this is known and if provided saves computation)

   :returns:

             tensor consisting of padded input tensors stored
               over the newly allocated memory.
   :rtype: x_padded


.. py:function:: padded_to_list(x: torch.Tensor, split_size: Union[Sequence[int], None] = None, dim: int = 0) -> List[torch.Tensor]

   Transforms a padded tensor of shape (N, S_1, S_2, ..., S_D) into a list
   of N tensors of shape:
   - (Si_1, Si_2, ..., Si_D) where (Si_1, Si_2, ..., Si_D) is specified in split_size(i)
   - or (S_1, S_2, ..., S_D) if split_size is None
   - or (Si_1, S_2, ..., S_D) if split_size(i) is an integer.

   :param x: tensor
   :param split_size: optional 1D list/tuple of ints defining the number of
                      items for each tensor.

   :returns: a list of tensors sharing the memory with the input.
   :rtype: x_list


.. py:function:: list_to_packed(x: List[torch.Tensor]) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

   Transforms a list of N tensors each of shape (Mi, K, ...) into a single
   tensor of shape (sum(Mi), K, ...).

   :param x: list of tensors.

   :returns: 4-element tuple containing

             - x_packed: tensor consisting of packed input tensors along the
               1st dimension.
             - num_items: tensor of shape N containing Mi for each element in x.
             - item_packed_first_idx: tensor of shape N indicating the index of
               the first item belonging to the same element in the original list.
             - item_packed_to_list_idx: tensor of shape sum(Mi) containing the
               index of the element in the list the item belongs to.


.. py:function:: packed_to_list(x: torch.Tensor, split_size: Union[Sequence[int], int]) -> List[torch.Tensor]

   Transforms a tensor of shape (sum(Mi), K, L, ...) to N set of tensors of
   shape (Mi, K, L, ...) where Mi's are defined in split_size

   :param x: tensor
   :param split_size: list, tuple or int defining the number of items for each tensor
                      in the output list.

   :returns: A list of Tensors
   :rtype: x_list


.. py:function:: list_to_padded_numpy(x: List[numpy.ndarray], pad_size: Union[Sequence[int], None] = None, pad_value: Union[float, int] = 0.0, equisized: bool = False) -> numpy.ndarray

   Transforms a list of N numpy arrays each of shape (Si_0, Si_1, ... Si_D)
   into:
   - a single array of shape (N, pad_size(0), pad_size(1), ..., pad_size(D))
     if pad_size is provided
   - or an array of shape (N, max(Si_0), max(Si_1), ..., max(Si_D)) if pad_size is None.

   :param x: list of numpy arrays
   :param pad_size: list(int) specifying the size of the padded array.
                    If `None` (default), the largest size of each dimension
                    is set as the `pad_size`.
   :param pad_value: float/int value to be used to fill the padded array
   :param equisized: bool indicating whether the items in x are of equal size

   :returns: numpy array consisting of padded input arrays
   :rtype: x_padded


.. py:function:: list_to_packed_numpy(x: List[numpy.ndarray]) -> Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Transforms a list of N numpy arrays each of shape (Mi, K, ...) into a single
   array of shape (sum(Mi), K, ...).

   :param x: list of numpy arrays.

   :returns: 4-element tuple containing

             - x_packed: array consisting of packed input arrays along the
               1st dimension.
             - num_items: array of shape N containing Mi for each element in x.
             - item_packed_first_idx: array of shape N indicating the index of
               the first item belonging to the same element in the original list.
             - item_packed_to_list_idx: array of shape sum(Mi) containing the
               index of the element in the list the item belongs to.