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¶

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

Add a mesh to an existing 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_faces, face_size, 3).
materials (list of Material) – list of material objects
material_assignments (torch.ShortTensor) – of shape (num_faces,) containing index of the material (in the above list) assigned to the corresponding face, or -1 if no material was assigned
time (convertible to float, 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 (convertible to float, 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 (convertible to float, 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, material_assignments=None, materials=None, up_axis='Y', time=None)¶

Export a single mesh to USD 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).
materials (list of Material) – list of material objects
material_assignments (torch.ShortTensor) – of shape (num_faces,) containing index of the material (in the above list) assigned to the corresponding face, or -1 if no material was assigned
up_axis (str, optional) – Specifies the scene’s up axis. Choose from ['Y', 'Z']
time (convertible to float, 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, material_assignments=None, materials=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 ofpaths 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_faces, face_size, 3).
materials (list of list of Material) – list of material objects
material_assignments (list of torch.ShortTensor) – of shape (text{num_faces},) containing index of the material (in the above list) assigned to the corresponding face, or -1 if no material was assigned
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 (convertible to float) – 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 (convertible to float, 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_or_stage)¶

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

Parameters: file_path_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
Returns: (list)

kaolin.io.usd.get_mesh_prim_materials(mesh_prim, stage_dir, num_faces, time=None)¶

Extracts and parses materials for a mesh_prim; currently only works for prims with a corresponding stage path (needs to be addressed).

Parameters

mesh_prim – USD Prim that should be of type Mesh
stage_dir – root stage directory
num_faces – number of faces
time – timecode to extract values for

Returns: (tuple) containing two items:

materials_dict (dict from string to material): mapping from material name to material

material_assignments_dict (dict of str to torch.LongTensor): mapping from material name
to face indices assigned to that material

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_or_stage)¶

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

Parameters: file_path_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
Returns: List of filtered scene paths.
Return type: (list of str)

kaolin.io.usd.get_raw_mesh_prim_geometry(mesh_prim, time=None, with_normals=False, with_uvs=False)¶

Extracts raw geometry properties from a mesh prim, converting them to torch tensors.

Parameters

mesh_prim – USD Prim that should be of type Mesh
time (convertible to float, optional) – timecode to extract values for
with_normals (bool) – if set, will extract normals (default: False)
with_uvs (bool) – if set, will also extract UV information (default: False)
time – positive integer indicating the time at which to retrieve parameters

Returns:

(dict):

vertices (torch.FloatTensor): vertex positions with any transforms already applied, of shape (N, 3)

transform (torch.FloatTensor): applied transform of shape (4, 4)

faces (torch.LongTensor): face vertex indices of original shape saved in the USD

face_sizes (torch.LongTensor): face vertex counts of original shape saved in the USD

normals (torch.FloatTensor, optional):
if with_normals=True, normal values of original shape saved in the USD

normals_interpolation (string, optional):
if with_normals=True, normal interpolation type saved in the USD, such as “faceVarying”

uvs (torch.FloatTensor, optional): if with_uvs=True, raw UV values saved in the USD

face_uvs_idx (torch.LongTensor, optional):
if with_uvs=True, raw indices into the UV for every vertex of every face

uv_interpolation (string, optional):
if with_uvs=True, UV interpolation type saved in the USD, such as “faceVarying”

kaolin.io.usd.get_scene_paths(file_path_or_stage, scene_path_regex=None, prim_types=None, conditional=<function <lambda>>)¶

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

Parameters

file_path_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
scene_path_regex (str, optional) – Optional regular expression used to select returned scene paths.
prim_types (list of str, str, optional) – Optional list of valid USD Prim types used to select scene paths, or a single USD Prim type string.
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_or_stage, scene_path=None, with_materials=False, with_normals=False, heterogeneous_mesh_handler=None, time=None, triangulate=False)¶

Import a single mesh from a USD file of Stage 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 attributes as CPU torch tensors in an easy-to-manage kaolin.rep.SurfaceMesh container.

Parameters

file_path_or_stage (str, Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
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.
with_materials (bool) – if True, load materials. Default: False.
with_normals (bool) – if True, load vertex normals. Default: False.
heterogeneous_mesh_handler (Callable, optional) – function that handles a heterogeneous mesh, homogenizing, returning None or throwing error, with the following signature: heterogeneous_mesh_handler(vertices, face_vertex_counts, *args, face_assignments) for example, see mesh_handler_naive_triangulate and heterogeneous_mesh_handler_skip. Default: will raise a NonHomogeneousMeshError.
time (convertible to float, optional) – Positive integer indicating the time at which to retrieve parameters.
triangulate – if True, will triangulate all non-triangular meshes using same logic as mesh_handler_naive_triangulate. If heterogeneous_mesh_handler is not set, this flag will cause non-homogeneous meshes to be triangulated and loaded without error; otherwise triangulation executes after heterogeneous_mesh_handler, which may skip or throw an error.

Returns

an unbatched instance of kaolin.rep.SurfaceMesh, where:

normals and face_normals_idx will only be filled if with_normals=True
materials will be a list of kaolin.io.materials.Material sorted by their material_name; filled only if with_materials=True.
material_assignments will be a tensor of shape (num_faces,) containing the index of the material (in the materials list) assigned to the corresponding face, or -1 if no material was assigned; filled only if with_materials=True.

Return type

(SurfaceMesh)

Examples

To load a mesh without loading normals or materials:

>>> from kaolin.io.usd.mesh import import_mesh
>>> mesh = import_mesh("sample_data/meshes/pizza.usda")
>>> print(mesh)
SurfaceMesh object with batching strategy NONE
            vertices: [482, 3] (torch.float32)[cpu]
                 uvs: [2880, 2] (torch.float32)[cpu]
               faces: [960, 3] (torch.int64)[cpu]
        face_uvs_idx: [960, 3] (torch.int64)[cpu]
       face_vertices: if possible, computed on access from: (faces, vertices)
        face_normals: if possible, computed on access from: (normals, face_normals_idx) or (vertices, faces)
      vertex_normals: if possible, computed on access from: (faces, face_normals)
            face_uvs: if possible, computed on access from: (uvs, face_uvs_idx)

>>> mesh.face_normals  # Causes face_normals and any attributes required to compute it to be auto-computed
>>> mesh.to_batched()  # Apply fixed topology batching, unsqueezing most attributes
>>> mesh = mesh.cuda(attributes=["vertices"])  # Moves just vertices to GPU
>>> print(mesh)
SurfaceMesh object with batching strategy FIXED
            vertices: [1, 482, 3] (torch.float32)[cuda:0]
       face_vertices: [1, 960, 3, 3] (torch.float32)[cpu]
        face_normals: [1, 960, 3, 3] (torch.float32)[cpu]
                 uvs: [1, 2880, 2] (torch.float32)[cpu]
               faces: [960, 3] (torch.int64)[cpu]
        face_uvs_idx: [1, 960, 3] (torch.int64)[cpu]
      vertex_normals: if possible, computed on access from: (faces, face_normals)
            face_uvs: if possible, computed on access from: (uvs, face_uvs_idx)

To load a mesh with normals and materials, while triangulating and homogenizing if needed:

>>> from kaolin.io.usd.mesh import import_mesh
>>> from kaolin.io.utils import mesh_handler_naive_triangulate
>>> mesh = import_mesh("sample_data/meshes/pizza.usda",
                      with_normals=True, with_materials=True,
                      heterogeneous_mesh_handler=mesh_handler_naive_triangulate,
                      triangulate=True)
>>> print(mesh)
SurfaceMesh object with batching strategy NONE
            vertices: [482, 3] (torch.float32)[cpu]
        face_normals: [960, 3, 3] (torch.float32)[cpu]
                 uvs: [2880, 2] (torch.float32)[cpu]
               faces: [960, 3] (torch.int64)[cpu]
        face_uvs_idx: [960, 3] (torch.int64)[cpu]
material_assignments: [960] (torch.int16)[cpu]
           materials: list of length 2
       face_vertices: if possible, computed on access from: (faces, vertices)
      vertex_normals: if possible, computed on access from: (faces, face_normals)
            face_uvs: if possible, computed on access from: (uvs, face_uvs_idx)

kaolin.io.usd.import_meshes(file_path_or_stage, scene_paths=None, with_materials=False, with_normals=False, heterogeneous_mesh_handler=None, times=None, triangulate=False)¶

Import one or more meshes from a USD file or Stage 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. Prims with no meshes or with heterogenous faces are skipped. Returns an unbatched attributes as CPU torch tensors in a list of easy-to-manage kaolin.rep.SurfaceMesh containers.

Parameters

file_path_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
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.
with_materials (bool) – if True, load materials. Default: False.
with_normals (bool) – if True, load vertex normals. Default: False.
heterogeneous_mesh_handler (Callable, optional) – function that handles a heterogeneous mesh, homogenizing, returning None or throwing error, with the following signature: heterogeneous_mesh_handler(vertices, face_vertex_counts, *args, face_assignments) for example, see mesh_handler_naive_triangulate and heterogeneous_mesh_handler_skip. Default: will raise a NonHomogeneousMeshError.
times (list of int) – Positive integers indicating the time at which to retrieve parameters.
triangulate – if True, will triangulate all non-triangular meshes using same logic as mesh_handler_naive_triangulate. If heterogeneous_mesh_handler is not set, this flag will cause non-homogeneous meshes to be triangulated and loaded without error; otherwise triangulation executes after heterogeneous_mesh_handler, which may skip or throw an error.

Returns

a list of unbatched instances of kaolin.rep.SurfaceMesh, where:

normals and face_normals_idx will only be filled if with_normals=True
materials will be a list of kaolin.io.materials.Material sorted by their material_name; filled only if with_materials=True.
material_assignments will be a tensor of shape (num_faces,) containing the index of the material (in the materials list) assigned to the corresponding face, or -1 if no material was assigned; filled only if with_materials=True.

Return type

(a list of SurfaceMesh)

Examples

To export and then import USD meshes:

>>> # 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('./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]])]

To load multiple meshes from file, including materials and normals, while homongenizing and triangulating:

>>> from kaolin.io.usd.mesh import import_meshes
>>> from kaolin.io.utils import mesh_handler_naive_triangulate
>>> meshes = import_meshes('sample_data/meshes/amsterdam.usda',
                           with_normals=True, with_materials=True,
                           heterogeneous_mesh_handler=mesh_handler_naive_triangulate,
                           triangulate=True)
>>> len(meshes)
18
>>> print(meshes[0])
SurfaceMesh object with batching strategy NONE
            vertices: [4, 3] (torch.float32)[cpu]
        face_normals: [2, 3, 3] (torch.float32)[cpu]
                 uvs: [4, 2] (torch.float32)[cpu]
               faces: [2, 3] (torch.int64)[cpu]
        face_uvs_idx: [2, 3] (torch.int64)[cpu]
material_assignments: [2] (torch.int16)[cpu]
           materials: list of length 1
       face_vertices: if possible, computed on access from: (faces, vertices)
      vertex_normals: if possible, computed on access from: (faces, face_normals)
            face_uvs: if possible, computed on access from: (uvs, face_uvs_idx)
>>> # If needed, concatenate meshes into a batch
>>> from kaolin.rep import SurfaceMesh
>>> mesh = SurfaceMesh.cat(meshes, fixed_topology=False)
>>> print(mesh)
SurfaceMesh object with batching strategy LIST
    vertices: [
              0: [4, 3] (torch.float32)[cpu]
              1: [98, 3] (torch.float32)[cpu]
              ...
             17: [4, 3] (torch.float32)[cpu]
              ]
face_normals: [
              0: [2, 3, 3] (torch.float32)[cpu]
              ...

kaolin.io.usd.import_pointcloud(file_path_or_stage, scene_path, time=None)¶

Import a single pointcloud from a USD file or stage.

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_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
scene_path (str) – Scene path within the USD file indicating which primitive to import.
time (convertible to float, 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_or_stage, scene_paths=None, times=None)¶

Import one or more pointclouds from a USD file or stage.

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_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
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) (not yet implemented)

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_or_stage, scene_path, time=None)¶

Import a single voxelgrid from a USD file or stage.

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_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
scene_path (str) – Scene path within the USD file indicating which PointInstancer primitive to import as a voxelgrid.
time (convertible to float, 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('./new_stage.usd',
...                                  scene_path='/World/voxelgrid')
>>> voxelgrid_imp.shape
torch.Size([32, 32, 32])

kaolin.io.usd.import_voxelgrids(file_path_or_stage, 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_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
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('./new_stage.usd')
>>> len(voxelgrid_imp)
2
>>> voxelgrid_imp[0].shape
torch.Size([32, 32, 32])