pytorch3d.renderer.utils

utils

class pytorch3d.renderer.utils.TensorAccessor(class_object, index: int | slice)

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

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.

__setattr__(name: str, value: Any)

Update the attribute given by name to the value given by value at the index specified by self.index.

Parameters:

• name – str, name of the attribute.

• value – value to set the attribute to.

__getattr__(name: str)

Return the value of the attribute given by “name” on self.class_object at the index specified in self.index.

Parameters:

name – string of the attribute name

class pytorch3d.renderer.utils.TensorProperties(dtype: dtype = torch.float32, device: str | device = 'cpu', **kwargs)

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

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.

isempty() → bool

__getitem__(index: int | slice) → TensorAccessor

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

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

cuda(device: int | None = None) → TensorProperties

clone(other) → TensorProperties

Update the tensor properties of other with the cloned properties of self.

gather_props(batch_idx) → TensorProperties

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

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

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

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

[1] https://pytorch3d.org/docs/cameras

pytorch3d.renderer.utils.ndc_to_grid_sample_coords(xy_ndc: Tensor, image_size_hw: Tuple[int, int]) → Tensor

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]

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.