pytorch3d.renderer.utils
utils
- class pytorch3d.renderer.utils.TensorAccessor(class_object, index: int | slice)[source]
Bases:
Module
A helper class to be used with the __getitem__ method. This can be used for getting/setting the values for an attribute of a class at one particular index. This is useful when the attributes of a class are batched tensors and one element in the batch needs to be modified.
- __init__(class_object, index: int | slice) None [source]
- Parameters:
class_object – this should be an instance of a class which has attributes which are tensors representing a batch of values.
index – int/slice, an index indicating the position in the batch. In __setattr__ and __getattr__ only the value of class attributes at this index will be accessed.
- class pytorch3d.renderer.utils.TensorProperties(dtype: dtype = torch.float32, device: str | device = 'cpu', **kwargs)[source]
Bases:
Module
A mix-in class for storing tensors as properties with helper methods.
- __init__(dtype: dtype = torch.float32, device: str | device = 'cpu', **kwargs) None [source]
- Parameters:
dtype – data type to set for the inputs
device – Device (as str or torch.device)
kwargs – any number of keyword arguments. Any arguments which are of type (float/int/list/tuple/tensor/array) are broadcasted and other keyword arguments are set as attributes.
- __getitem__(index: int | slice) TensorAccessor [source]
- Parameters:
index – an int or slice used to index all the fields.
- Returns:
if index is an index int/slice return a TensorAccessor class with getattribute/setattribute methods which return/update the value at the index in the original class.
- to(device: str | device = 'cpu') TensorProperties [source]
In place operation to move class properties which are tensors to a specified device. If self has a property “device”, update this as well.
- cpu() TensorProperties [source]
- cuda(device: int | None = None) TensorProperties [source]
- clone(other) TensorProperties [source]
Update the tensor properties of other with the cloned properties of self.
- gather_props(batch_idx) TensorProperties [source]
This is an in place operation to reformat all tensor class attributes based on a set of given indices using torch.gather. This is useful when attributes which are batched tensors e.g. shape (N, 3) need to be multiplied with another tensor which has a different first dimension e.g. packed vertices of shape (V, 3).
Example
self.specular_color = (N, 3) tensor of specular colors for each mesh
A lighting calculation may use
verts_packed = meshes.verts_packed() # (V, 3)
To multiply these two tensors the batch dimension needs to be the same. To achieve this we can do
batch_idx = meshes.verts_packed_to_mesh_idx() # (V)
This gives index of the mesh for each vertex in verts_packed.
self.gather_props(batch_idx) self.specular_color = (V, 3) tensor with the specular color for each packed vertex.
torch.gather requires the index tensor to have the same shape as the input tensor so this method takes care of the reshaping of the index tensor to use with class attributes with arbitrary dimensions.
- Parameters:
batch_idx – shape (B, …) where … represents an arbitrary number of dimensions
- Returns:
self with all properties reshaped. e.g. a property with shape (N, 3) is transformed to shape (B, 3).
- pytorch3d.renderer.utils.format_tensor(input, dtype: dtype = torch.float32, device: str | device = 'cpu') Tensor [source]
Helper function for converting a scalar value to a tensor.
- Parameters:
input – Python scalar, Python list/tuple, torch scalar, 1D torch tensor
dtype – data type for the input
device – Device (as str or torch.device) on which the tensor should be placed.
- Returns:
input_vec – torch tensor with optional added batch dimension.
- pytorch3d.renderer.utils.convert_to_tensors_and_broadcast(*args, dtype: dtype = torch.float32, device: str | device = 'cpu')[source]
Helper function to handle parsing an arbitrary number of inputs (*args) which all need to have the same batch dimension. The output is a list of tensors.
- Parameters:
*args –
an arbitrary number of inputs Each of the values in args can be one of the following
Python scalar
Torch scalar
Torch tensor of shape (N, K_i) or (1, K_i) where K_i are an arbitrary number of dimensions which can vary for each value in args. In this case each input is broadcast to a tensor of shape (N, K_i)
dtype – data type to use when creating new tensors.
device – torch device on which the tensors should be placed.
- Output:
args: A list of tensors of shape (N, K_i)
- pytorch3d.renderer.utils.ndc_grid_sample(input: Tensor, grid_ndc: Tensor, *, align_corners: bool = False, **grid_sample_kwargs) Tensor [source]
Samples a tensor input of shape (B, dim, H, W) at 2D locations specified by a tensor grid_ndc of shape (B, …, 2) using the torch.nn.functional.grid_sample function. grid_ndc is specified in PyTorch3D NDC coordinate frame.
- Parameters:
input – The tensor of shape (B, dim, H, W) to be sampled.
grid_ndc – A tensor of shape (B, …, 2) denoting the set of 2D locations at which input is sampled. See [1] for a detailed description of the NDC coordinates.
align_corners – Forwarded to the torch.nn.functional.grid_sample call. See its docstring.
grid_sample_kwargs – Additional arguments forwarded to the torch.nn.functional.grid_sample call. See the corresponding docstring for a listing of the corresponding arguments.
- Returns:
sampled_input –
- A tensor of shape (B, dim, …) containing the samples
of input at 2D locations grid_ndc.
References
- pytorch3d.renderer.utils.ndc_to_grid_sample_coords(xy_ndc: Tensor, image_size_hw: Tuple[int, int]) Tensor [source]
Convert from the PyTorch3D’s NDC coordinates to torch.nn.functional.grid_sampler’s coordinates.
- Parameters:
xy_ndc – Tensor of shape (…, 2) containing 2D points in the PyTorch3D’s NDC coordinates.
image_size_hw – A tuple (image_height, image_width) denoting the height and width of the image tensor to sample.
- Returns:
xy_grid_sample –
- Tensor of shape (…, 2) containing 2D points in the
torch.nn.functional.grid_sample coordinates.
- pytorch3d.renderer.utils.parse_image_size(image_size: List[int] | Tuple[int, int] | int) Tuple[int, int] [source]
- Parameters:
image_size – A single int (for square images) or a tuple/list of two ints.
- Returns:
A tuple of two ints.
- Throws:
ValueError if got more than two ints, any negative numbers or non-ints.