kaolin.io.usd

Universal Scene Description

Universal Scene Description (USD) is an open-source 3D scene description file format developed by Pixar and designed to be versatile, extensible and interchangeable between different 3D tools.

Single models and animations as well as large organized scenes composed of any number of assets can be defined in USD, making it suitable for organizing entire datasets into interpretable, subsets based on tags, class or other metadata label.

Kaolin includes base I/O operations for USD and also leverages this format to export 3D checkpoints. Use kaolin.io.usd to read and write USD files (try tutorials/usd_kitcheset.py), and kaolin.visualize.Timelapse to export 3D checkpoints (try tutorials/visualize_main.py).

As a first step to familiarizing yourself with USD, we suggest following this tutorial. More tutorials and documentation can be found here.

Viewing USD Files

USD files can be visualized with realtime pathtracing using the [Omniverse Kaolin App](https://docs.omniverse.nvidia.com/app_kaolin/app_kaolin/user_manual.html#training-visualizer). Alternatively, you may use Pixar’s USDView which can be obtained by visiting https://developer.nvidia.com/usd and selecting the corresponding platform under .USD Pre-Built Libraries and Tools.

API

Functions

Export common 3D representations to USD format. Mesh (homogeneous), Voxelgrid and PointCloud representations are currently supported.

kaolin.io.usd.add_mesh(stage, scene_path, vertices=None, faces=None, uvs=None, face_uvs_idx=None, face_normals=None, time=None)

Add a mesh to an existing USD stage.

Add a mesh to the USD stage. The stage is modified but not saved to disk.

Parameters

  • stage (Usd.Stage) – Stage onto which to add the mesh.

  • scene_path (str) – Absolute path of mesh within the USD file scene. Must be a valid Sdf.Path.

  • vertices (torch.FloatTensor, optional) – Vertices with shape (num_vertices, 3).

  • faces (torch.LongTensor, optional) – Vertex indices for each face with shape (num_faces, face_size). Mesh must be homogenous (consistent number of vertices per face).

  • uvs (torch.FloatTensor, optional) – of shape (num_uvs, 2).

  • face_uvs_idx (torch.LongTensor, optional) – of shape (num_faces, face_size). If provided, uvs must also be specified.

  • face_normals (torch.Tensor, optional) – of shape (num_vertices, num_faces, 3).

  • time (int, optional) – Positive integer defining the time at which the supplied parameters correspond to.

Returns

(Usd.Stage)

Example

>>> vertices = torch.rand(3, 3)
>>> faces = torch.tensor([[0, 1, 2]])
>>> stage = create_stage('./new_stage.usd')
>>> mesh = add_mesh(stage, '/World/mesh', vertices, faces)
>>> stage.Save()
kaolin.io.usd.add_pointcloud(stage, points, scene_path, colors=None, time=None, points_type='point_instancer')

Add a pointcloud to an existing USD stage.

Create a pointcloud represented by point instances of a sphere centered at each point coordinate. The stage is modified but not saved to disk.

Parameters

  • stage (Usd.Stage) – Stage onto which to add the pointcloud.

  • points (torch.FloatTensor) – Pointcloud tensor containing N points of shape (N, 3).

  • scene_path (str) – Absolute path of pointcloud within the USD file scene. Must be a valid Sdf.Path.

  • colors (torch.FloatTensor, optional) – Color tensor corresponding each point in the pointcloud tensor of shape (N, 3). colors only works if points_type is “usd_geom_points”.

  • time (int, optional) – Positive integer defining the time at which the supplied parameters correspond to.

  • points_type (str) – String that indicates whether to save pointcloud as UsdGeomPoints or PointInstancer. “usd_geom_points” indicates UsdGeomPoints and “point_instancer” indicates PointInstancer. Please refer here for UsdGeomPoints: https://graphics.pixar.com/usd/docs/api/class_usd_geom_points.html and here for PointInstancer https://graphics.pixar.com/usd/docs/api/class_usd_geom_point_instancer.html. Default: “point_instancer”.

Returns

(Usd.Stage)

Example

>>> stage = create_stage('./new_stage.usd')
>>> points = torch.rand(100, 3)
>>> stage = add_pointcloud(stage, points, '/World/PointClouds/pointcloud_0')
>>> stage.Save()
kaolin.io.usd.add_voxelgrid(stage, voxelgrid, scene_path, time=None)

Add a voxelgrid to an existing USD stage.

Add a voxelgrid where occupied voxels are defined by non-zero values. The voxelgrid is represented by point instances of a cube centered at each occupied index coordinate and scaled. The stage is modified but not saved to disk.

Parameters

  • stage (Usd.Stage) – Stage onto which to add the voxelgrid.

  • voxelgrid (torch.BoolTensor) – Binary voxelgrid of shape (N, N, N).

  • scene_path (str) – Absolute path of voxelgrid within the USD file scene. Must be a valid Sdf.Path.

  • time (int, optional) – Positive integer defining the time at which the supplied parameters correspond to.

Returns

(Usd.Stage)

Example

>>> stage = create_stage('./new_stage.usd')
>>> voxelgrid = torch.rand(32, 32, 32) > 0.5
>>> stage = add_voxelgrid(stage, voxelgrid, '/World/VoxelGrids/voxelgrid_0')
>>> stage.Save()
kaolin.io.usd.create_stage(file_path, up_axis='Y')

Create a new USD file and return an empty stage.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • up_axis (['Y', 'Z']) – Specify the stage up axis. Choose from ['Y', 'Z'].

Returns

(Usd.Stage)

Example

>>> stage = create_stage('./new_stage.usd', up_axis='Z')
>>> type(stage)
<class 'pxr.Usd.Stage'>
kaolin.io.usd.export_mesh(file_path, scene_path='/World/Meshes/mesh_0', vertices=None, faces=None, uvs=None, face_uvs_idx=None, face_normals=None, materials=None, up_axis='Y', time=None)

Export a single mesh to USD.

Export a single mesh defined by vertices and faces and save the stage to disk.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_path (str, optional) – Absolute path of mesh within the USD file scene. Must be a valid Sdf.Path. If no path is provided, a default path is used.

  • vertices (torch.FloatTensor, optional) – Vertices with shape (num_vertices, 3).

  • faces (torch.LongTensor, optional) – Vertex indices for each face with shape (num_faces, face_size). Mesh must be homogenous (consistent number of vertices per face).

  • uvs (torch.FloatTensor, optional) – of shape (num_uvs, 2).

  • face_uvs_idx (torch.LongTensor, optional) – of shape (num_faces, face_size). If provided, uvs must also be specified.

  • face_normals (torch.Tensor, optional) – of shape (num_vertices, num_faces, 3).

  • up_axis (str, optional) – Specifies the scene’s up axis. Choose from ['Y', 'Z'].

  • time (int, optional) – Positive integer defining the time at which the supplied parameters correspond to.

Returns

(Usd.Stage)

Example

>>> vertices = torch.rand(3, 3)
>>> faces = torch.tensor([[0, 1, 2]])
>>> stage = export_mesh('./new_stage.usd', vertices=vertices, faces=faces)
kaolin.io.usd.export_meshes(file_path, scene_paths=None, vertices=None, faces=None, uvs=None, face_uvs_idx=None, face_normals=None, up_axis='Y', times=None)

Export multiple meshes to a new USD stage.

Export multiple meshes defined by lists vertices and faces and save the stage to disk.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_paths (list of str, optional) – Absolute paths of meshes within the USD file scene. Must have the same number of paths as the number of meshes N. Must be a valid Sdf.Path. If no path is provided, a default path is used.

  • vertices (list of torch.FloatTensor, optional) – Vertices with shape (num_vertices, 3).

  • faces (list of torch.LongTensor, optional) – Vertex indices for each face with shape (num_faces, face_size). Mesh must be homogenous (consistent number of vertices per face).

  • uvs (list of torch.FloatTensor, optional) – of shape (num_uvs, 2).

  • face_uvs_idx (list of torch.LongTensor, optional) – of shape (num_faces, face_size). If provided, uvs must also be specified.

  • face_normals (list of torch.Tensor, optional) – of shape (num_vertices, num_faces, 3).

  • up_axis (str, optional) – Specifies the scene’s up axis. Choose from ['Y', 'Z'].

  • times (list of int, optional) – Positive integers defining the time at which the supplied parameters correspond to.

Returns

(Usd.Stage)

Example

>>> vertices_list = [torch.rand(3, 3) for _ in range(3)]
>>> faces_list = [torch.tensor([[0, 1, 2]]) for _ in range(3)]
>>> stage = export_meshes('./new_stage.usd', vertices=vertices_list, faces=faces_list)
kaolin.io.usd.export_pointcloud(file_path, pointcloud, scene_path='/World/PointClouds/pointcloud_0', color=None, time=None, points_type='point_instancer')

Export a single pointcloud to a USD scene.

Export a single pointclouds to USD. The pointcloud will be added to the USD stage and represented by point instances of a sphere centered at each point coordinate. The stage is then saved to disk.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • pointcloud (torch.FloatTensor) – Pointcloud tensor containing N points of shape (N, 3).

  • scene_path (str, optional) – Absolute path of pointcloud within the USD file scene. Must be a valid Sdf.Path. If no path is provided, a default path is used.

  • color (torch.FloatTensor, optional) – Color tensor corresponding each point in the pointcloud tensor of shape (N, 3). colors only works if points_type is “usd_geom_points”.

  • time (int) – Positive integer defining the time at which the supplied parameters correspond to.

  • points_type (str) – String that indicates whether to save pointcloud as UsdGeomPoints or PointInstancer. “usd_geom_points” indicates UsdGeomPoints and “point_instancer” indicates PointInstancer. Please refer here for UsdGeomPoints: https://graphics.pixar.com/usd/docs/api/class_usd_geom_points.html and here for PointInstancer https://graphics.pixar.com/usd/docs/api/class_usd_geom_point_instancer.html. Default: “point_instancer”.

Returns

(Usd.Stage)

Example

>>> points = torch.rand(100, 3)
>>> stage = export_pointcloud('./new_stage.usd', points)
kaolin.io.usd.export_pointclouds(file_path, pointclouds, scene_paths=None, colors=None, times=None, points_type='point_instancer')

Export one or more pointclouds to a USD scene.

Export one or more pointclouds to USD. The pointclouds will be added to the USD stage and represented by point instances of a sphere centered at each point coordinate. The stage is then saved to disk.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • pointclouds (list of torch.FloatTensor) – List of pointcloud tensors of length N defining N pointclouds.

  • scene_paths (list of str, optional) – Absolute path(s) of pointcloud(s) within the USD file scene. Must be a valid Sdf.Path. If no path is provided, a default path is used.

  • times (list of int) – Positive integers defining the time at which the supplied parameters correspond to.

  • colors (list of tensors, optional) – Lits of RGB colors of length N, each corresponding to a pointcloud in the pointcloud list. colors only works if points_type is “usd_geom_points”.

  • points_type (str) – String that indicates whether to save pointcloud as UsdGeomPoints or PointInstancer. “usd_geom_points” indicates UsdGeomPoints and “point_instancer” indicates PointInstancer. Please refer here for UsdGeomPoints: https://graphics.pixar.com/usd/docs/api/class_usd_geom_points.html and here for PointInstancer https://graphics.pixar.com/usd/docs/api/class_usd_geom_point_instancer.html. Default: “point_instancer”.

Returns

(Usd.Stage)

Example

>>> points = torch.rand(100, 3)
>>> stage = export_pointcloud('./new_stage.usd', points)
kaolin.io.usd.export_voxelgrid(file_path, voxelgrid, scene_path='/World/VoxelGrids/voxelgrid_0', time=None)

Export a single voxelgrid to a USD scene.

Export a binary voxelgrid where occupied voxels are defined by non-zero values. The voxelgrid is represented by point instances of a cube centered at each occupied index coordinates. The voxelgrid will be scaled so that it fits within a unit cube. The stage is then saved to disk.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • voxelgrid (torch.BoolTensor) – Binary voxelgrid of shape (N, N, N).

  • scene_path (str, optional) – Absolute path of voxelgrid within the USD file scene. Must be a valid Sdf.Path. If no path is provided, a default path is used.

  • time (int, optional) – Positive integer defining the time at which the supplied parameters correspond to.

Returns

(Usd.Stage)

Example

>>> voxelgrid = torch.rand(32, 32, 32) > 0.5
>>> stage = export_voxelgrid('./new_stage.usd', voxelgrid)
kaolin.io.usd.export_voxelgrids(file_path, voxelgrids, scene_paths=None, times=None)

Export one or more voxelgrids to a USD scene.

Export one or more binary voxelgrids where occupied voxels are defined by non-zero values. The voxelgrids are represented by point instances of a cube centered at each occupied index coordinates and scaled. The voxelgrids will be scaled so that it fits within a unit cube. The stage is then saved to disk.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • voxelgrids (list of torch.BoolTensor) – List of binary voxelgrid(s) of shape (N, N, N).

  • scene_path (list of str, optional) – Absolute path(s) of voxelgrid within the USD file scene. Must be a valid Sdf.Path. If no path is provided, a default path is used.

  • times (list of int) – Positive integers defining the time at which the supplied parameters correspond to.

Returns

(Usd.Stage)

Example

>>> voxelgrid_1 = torch.rand(32, 32, 32) > 0.5
>>> voxelgrid_2 = torch.rand(32, 32, 32) > 0.5
>>> stage = export_voxelgrids('./new_stage.usd', [voxelgrid_1, voxelgrid_2])
kaolin.io.usd.get_authored_time_samples(file_path)

Returns all authored time samples within the USD, aggregated across all primitives.

Parameters

file_path (str) – Path to usd file (*.usd, *.usda).

Returns

(list)

kaolin.io.usd.get_pointcloud_bracketing_time_samples(stage, scene_path, target_time)

Returns two time samples that bracket target_time for point cloud attributes at a specified scene_path.

Parameters

  • stage (Usd.Stage) –

  • scene_path (str) –

  • target_time (Number) –

Returns

(iterable of 2 numbers)

kaolin.io.usd.get_pointcloud_scene_paths(file_path)

Returns all point cloud scene paths contained in specified file. Assumes that point clouds are exported using this API.

Parameters

file_path (str) – Path to usd file (*.usd, *.usda).

Returns

List of filtered scene paths.

Return type

(list of str)

kaolin.io.usd.get_root(file_path)

Return the root prim scene path.

Parameters

file_path (str) – Path to usd file (*.usd, *.usda).

Returns

Root scene path.

Return type

(str)

Example

>>> # Create a stage with some meshes
>>> vertices_list = [torch.rand(3, 3) for _ in range(3)]
>>> faces_list = [torch.tensor([[0, 1, 2]]) for _ in range(3)]
>>> stage = export_meshes('./new_stage.usd', vertices=vertices_list, faces=faces_list)
>>> # Retrieve root scene path
>>> root_prim = get_root('./new_stage.usd')
>>> mesh = import_mesh('./new_stage.usd', root_prim)
>>> mesh.vertices.shape
torch.Size([9, 3])
>>> mesh.faces.shape
torch.Size([3, 3])
kaolin.io.usd.get_scene_paths(file_path, scene_path_regex=None, prim_types=None, conditional=<function <lambda>>)

Return all scene paths contained in specified file. Filter paths with regular expression in scene_path_regex if provided.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_path_regex (str, optional) – Optional regular expression used to select returned scene paths.

  • prim_types (list of str, optional) – Optional list of valid USD Prim types used to select scene paths.

  • path (conditional (function) – Bool): Custom conditionals to check

Returns

List of filtered scene paths.

Return type

(list of str)

Example

>>> # Create a stage with some meshes
>>> vertices_list = [torch.rand(3, 3) for _ in range(3)]
>>> faces_list = [torch.tensor([[0, 1, 2]]) for _ in range(3)]
>>> stage = export_meshes('./new_stage.usd', vertices=vertices_list, faces=faces_list)
>>> # Retrieve scene paths
>>> get_scene_paths('./new_stage.usd', prim_types=['Mesh'])
[Sdf.Path('/World/Meshes/mesh_0'), Sdf.Path('/World/Meshes/mesh_1'), Sdf.Path('/World/Meshes/mesh_2')]
>>> get_scene_paths('./new_stage.usd', scene_path_regex=r'.*_0', prim_types=['Mesh'])
[Sdf.Path('/World/Meshes/mesh_0')]
kaolin.io.usd.import_mesh(file_path, scene_path=None, heterogeneous_mesh_handler=None, time=None)

Import a single mesh from a USD file in an unbatched representation.

Supports homogeneous meshes (meshes with consistent numbers of vertices per face). All sub-meshes found under the scene_path are flattened to a single mesh. The following interpolation types are supported for UV coordinates: vertex, varying and faceVarying. Returns an unbatched representation.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_path (str, optional) – Scene path within the USD file indicating which primitive to import. If not specified, the all meshes in the scene will be imported and flattened into a single mesh.

  • heterogeneous_mesh_handler (function, optional) – Optional function to handle heterogeneous meshes. The function’s input and output must be vertices (torch.FloatTensor), faces (torch.LongTensor), uvs (torch.FloatTensor), face_uvs_idx (torch.LongTensor), and face_normals (torch.FloatTensor). If the function returns None, the mesh will be skipped. If no function is specified, an error will be raised when attempting to import a heterogeneous mesh.

  • time (int, optional) – Positive integer indicating the time at which to retrieve parameters.

Returns:

namedtuple of:

  • vertices (torch.FloatTensor): of shape (num_vertices, 3)

  • faces (torch.LongTensor): of shape (num_faces, face_size)

  • uvs (torch.FloatTensor): of shape (num_uvs, 2)

  • face_uvs_idx (torch.LongTensor): of shape (num_faces, face_size)

  • face_normals (torch.FloatTensor): of shape (num_faces, face_size, 3)

  • materials (list of kaolin.io.materials.Material): Material properties (Not yet implemented)

Example

>>> # Create a stage with some meshes
>>> stage = export_mesh('./new_stage.usd', vertices=torch.rand(3, 3), faces=torch.tensor([[0, 1, 2]]),
... scene_path='/World/mesh1')
>>> # Import meshes
>>> mesh = import_mesh(file_path='./new_stage.usd', scene_path='/World/mesh1')
>>> mesh.vertices.shape
torch.Size([3, 3])
>>> mesh.faces
tensor([[0, 1, 2]])
kaolin.io.usd.import_meshes(file_path, scene_paths=None, heterogeneous_mesh_handler=None, times=None)

Import one or more meshes from a USD file in an unbatched representation.

Supports homogeneous meshes (meshes with consistent numbers of vertices per face). Custom handling of heterogeneous meshes can be achieved by passing a function through the heterogeneous_mesh_handler argument. The following interpolation types are supported for UV coordinates: vertex, varying and faceVarying. For each scene path specified in scene_paths, sub-meshes (if any) are flattened to a single mesh. Returns unbatched meshes list representation. Prims with no meshes or with heterogenous faces are skipped.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_paths (list of str, optional) – Scene path(s) within the USD file indicating which primitive(s) to import. If None, all prims of type Mesh will be imported.

  • heterogeneous_mesh_handler (function, optional) – Optional function to handle heterogeneous meshes. The function’s input and output must be vertices (torch.FloatTensor), faces (torch.LongTensor), uvs (torch.FloatTensor), face_uvs_idx (torch.LongTensor), and face_normals (torch.FloatTensor). If the function returns None, the mesh will be skipped. If no function is specified, an error will be raised when attempting to import a heterogeneous mesh.

  • times (list of int) – Positive integers indicating the time at which to retrieve parameters.

Returns:

list of namedtuple of:

  • vertices (list of torch.FloatTensor): of shape (num_vertices, 3)

  • faces (list of torch.LongTensor): of shape (num_faces, face_size)

  • uvs (list of torch.FloatTensor): of shape (num_uvs, 2)

  • face_uvs_idx (list of torch.LongTensor): of shape (num_faces, face_size)

  • face_normals (list of torch.FloatTensor): of shape (num_faces, face_size, 3)

  • materials (list of kaolin.io.materials.Material): Material properties (Not yet implemented)

Example

>>> # Create a stage with some meshes
>>> vertices_list = [torch.rand(3, 3) for _ in range(3)]
>>> faces_list = [torch.tensor([[0, 1, 2]]) for _ in range(3)]
>>> stage = export_meshes('./new_stage.usd', vertices=vertices_list, faces=faces_list)
>>> # Import meshes
>>> meshes = import_meshes(file_path='./new_stage.usd')
>>> len(meshes)
3
>>> meshes[0].vertices.shape
torch.Size([3, 3])
>>> [m.faces for m in meshes]
[tensor([[0, 1, 2]]), tensor([[0, 1, 2]]), tensor([[0, 1, 2]])]
kaolin.io.usd.import_pointcloud(file_path, scene_path, time=None)

Import a single pointcloud from a USD file.

Assumes that the USD pointcloud is interpreted using a point instancer or UsdGeomPoints. Converts the coordinates of each point instance to a point within the output pointcloud.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_path (str) – Scene path within the USD file indicating which primitive to import.

  • time (int, optional) – Positive integer indicating the time at which to retrieve parameters.

Returns

  • points (torch.FloatTensor): of shape (num_points, 3)

  • colors (torch.FloatTensor): of shape (num_points, 3)

  • normals (torch.FloatTensor): of shape (num_points, 3) (not yet implemented)

Return type

namedtuple of

Example

>>> points = torch.rand(100, 3)
>>> stage = export_pointcloud('./new_stage.usd', points, scene_path='/World/pointcloud')
>>> points_imp = import_pointcloud(file_path='./new_stage.usd',
...                                scene_path='/World/pointcloud')[0]
>>> points_imp.shape
torch.Size([100, 3])
kaolin.io.usd.import_pointclouds(file_path, scene_paths=None, times=None)

Import one or more pointclouds from a USD file.

Assumes that pointclouds are interpreted using point instancers or UsdGeomPoints. Converts the coordinates of each point instance to a point within the output pointcloud.

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_paths (list of str, optional) – Scene path(s) within the USD file indicating which primitive(s) to import. If None, will return all pointclouds found based on PointInstancer or UsdGeomPoints prims with kaolin_type primvar set to PointCloud.

  • times (list of int) – Positive integers indicating the time at which to retrieve parameters.

Returns

  • points (list of torch.FloatTensor): of shape (num_points, 3)

  • colors (list of torch.FloatTensor): of shape (num_points, 3)

  • normals (list of torch.FloatTensor): of shape (num_points, 2)

Return type

list of namedtuple of

Example

>>> points = torch.rand(100, 3)
>>> stage = export_pointclouds('./new_stage.usd', [points, points, points])
>>> pointclouds = import_pointclouds(file_path='./new_stage.usd')[0]
>>> len(pointclouds)
3
>>> pointclouds[0].shape
torch.Size([100, 3])
kaolin.io.usd.import_voxelgrid(file_path, scene_path, time=None)

Import a single voxelgrid from a USD file.

Assumes that the USD voxelgrid is defined by a point instancer. Converts the coordinates of each point instance to an occupied voxel. The output grid size is determined by the grid_size primvar. If not specified, grid size will be determined by the axis with the largest number of occupied voxels. The output voxelgrid will be of shape [grid_size, grid_size, grid_size].

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_path (str) – Scene path within the USD file indicating which PointInstancer primitive to import as a voxelgrid.

  • time (int, optional) – Positive integer indicating the time at which to retrieve parameters.

Returns

torch.BoolTensor

Example

>>> voxelgrid = torch.rand(32, 32, 32) > 0.5
>>> stage = export_voxelgrid('./new_stage.usd', voxelgrid, scene_path='/World/voxelgrid')
>>> voxelgrid_imp = import_voxelgrid(file_path='./new_stage.usd',
...                                  scene_path='/World/voxelgrid')
>>> voxelgrid_imp.shape
torch.Size([32, 32, 32])
kaolin.io.usd.import_voxelgrids(file_path, scene_paths=None, times=None)

Import one or more voxelgrids from a USD file.

Assumes that the USD voxelgrid is defined by a point instancer. Converts the coordinates of each point instance to an occupied voxel. The output grid size is determined from the grid_size primvar. If not specified, grid size will be determined by the axis with the largest number of occupied voxels. The output voxelgrid will be of shape [grid_size, grid_size, grid_size].

Parameters

  • file_path (str) – Path to usd file (*.usd, *.usda).

  • scene_paths (list of str, optional) – Scene path(s) within the USD file indicating which PointInstancer primitive(s) to import. If None, will return all pointclouds found based on PointInstancer prims with kaolin_type primvar set to VoxelGrid.

  • times (list of int) – Positive integers indicating the time at which to retrieve parameters.

Returns

(list of torch.BoolTensor)

Example

>>> voxelgrid_1 = torch.rand(32, 32, 32) > 0.5
>>> voxelgrid_2 = torch.rand(32, 32, 32) > 0.5
>>> stage = export_voxelgrids('./new_stage.usd', [voxelgrid_1, voxelgrid_2])
>>> voxelgrid_imp = import_voxelgrids(file_path='./new_stage.usd')
>>> len(voxelgrid_imp)
2
>>> voxelgrid_imp[0].shape
torch.Size([32, 32, 32])
class kaolin.io.usd.pointcloud_return_type(points, colors, normals)
property colors

Alias for field number 1

property normals

Alias for field number 2

property points

Alias for field number 0

Heterogeneous Mesh Handlers

kaolin.io.usd.heterogeneous_mesh_handler_empty(vertices, face_vertex_counts, faces, uvs, face_uvs_idx, face_normals)

Return empty tensors for vertices and faces of heterogeneous meshes.

kaolin.io.usd.heterogeneous_mesh_handler_naive_homogenize(vertices, face_vertex_counts, *args)

Homogenize list of faces containing polygons of varying number of edges to triangles using fan triangulation.

Parameters

  • vertices (torch.FloatTensor) – Vertices with shape (N, 3).

  • face_vertex_counts (torch.LongTensor) – Number of vertices for each face with shape (M) for M faces.

  • faces (torch.LongTensor) – Vertex indices for each face of with shape (F) where F is the sum of face_vertex_counts.

Returns

Homogeneous list of faces.

Return type

(list of list of int)

kaolin.io.usd.heterogeneous_mesh_handler_skip(*args)

Skip heterogeneous meshes.

Exceptions

class kaolin.io.usd.NonHomogeneousMeshError(message)

Raised when expecting a homogeneous mesh but a heterogenous mesh is encountered.

message
Type

str