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 in NVIDIA Omniverse.

For easy mesh visualization, see also Kaolin Jupyter Visualizer recipe for meshes.

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

class kaolin.io.usd.Mapping

A Mapping is a generic container for associating key/value pairs.

This class provides concrete generic implementations of all methods except for __getitem__, __iter__, and __len__.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.
items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
values() → an object providing a view on D's values
class kaolin.io.usd.UsdMaterialIoManager

Material management utility for USD Material I/O, which allows expanding the USD material support. Allows material reader functions to be mapped against specific shaders. This allows USD import functions to determine if a reader is available, which material reader to use and which material representation to wrap the output with.

Also supports registering writers, with a more complicated signature due to the intricacies of dealing with saving / overwriting texture files. See register_usd_writer().

Default registered readers / writers:

Example

>>> # Register a new USD reader for mdl `MyCustomPBR`
>>> from kaolin.io.usd import materials
>>> dummy_reader = lambda params_dict, texture_path: UsdShade.Material()
>>> materials.MaterialManager.register_usd_reader('MyCustomPBR', dummy_reader)
classmethod read_material(usd_material, texture_path, time=None)

Read USD material into internal PyTorch material representation. The type returned will be the type returned by the registered reader function, selected based on shader name specified in the usd_material.

Parameters

  • usd_material (UsdShade.Material) – Valid USD Material prim

  • texture_path (str, optional) – Path to textures directory. If the USD has absolute paths to textures, set to an empty string. By default, the textures will be assumed to be under the same directory as the USD specified by file_path.

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

Returns

Material object determined by the corresponding reader function, or raw shader properties as a dictionary.

classmethod register_usd_reader(shader_name, reader_fn)

Register a shader reader function that will be used during USD material import.

Parameters

  • shader_name (str) – Name of the shader

  • reader_fn (Callable) – Function that will be called to read shader attributes. The function must take as input a dictionary of input parameters and a string representing the texture path (UsdShade.Shader, texture_path, time) and typically return a Material

classmethod register_usd_writer(shader_name, writer_fn)

Register a shader reader function that will be used during USD material import.

Parameters

  • shader_name (str) – Name of the shader

  • writer_fn (Callable) – Function that will be called to write a material. The function must take as input named parameters (material_object, stage, scene_path, time, write_texture_by_basename_fn), where write_texture_by_basename_fn is a callable that takes (pytorch_image, texture_file_basename), writes texture to file, and returns its relative path. Such a callable can be easily created using TextureExporter. The writer_fn must return created UsdShade.Material.

classmethod write_material(pbr_material, stage, scene_path, shader_name, relative_texture_dir, texture_file_prefix='', time=None, overwrite_textures=False, image_extension='.png')

Writes internal PyTorch based material to USD. Textures will be written to disk in with filename in the form: usd_file_path/{relative_texture_dir}/{texture_file_prefix}{attr}{image_extension} where attr is attributes like diffuse, roughness, metallic, specular, normals, etc.

Parameters

  • pbr_material (Material) – material object that has a registered writer.

  • stage (Usd.Stage) – Path to usd file (*.usd, *.usda).

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

  • shader_name (str) – Shader name with a registered writer for the input material type.

  • relative_texture_dir (str) – relative texture directory; must be relative to USD file root.

  • texture_file_prefix (str) – optional prefix to add to all texture files written (not a path, part of basename)

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

  • overwrite_textures (bool) – set to True to overwrite existing image files when writing textures; if False (default) will add index to filename to avoid any conflicts.

  • image_extension (str) – extension, including dot, to use for image files, such as “.jpg”, “.png” (default).

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, overwrite_textures=False)

Add a mesh to an existing USD stage. The stage is modified but not saved to disk; material textures are written 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.

  • overwrite_textures (bool) – set to True to overwrite existing image files when writing textures; if False (default) will add index to filename to avoid conflicts.

Returns

the generated mesh Prim.

Return type

(Usd.Prim)

Example

>>> vertices = torch.rand(3, 3)
>>> faces = torch.tensor([[0, 1, 2]])
>>> stage = create_stage('./new_stage.usd')
>>> prim = 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

The generated pointcloud Prim.

Return type

(Usd.Prim)

Example

>>> stage = create_stage('./new_stage.usd')
>>> pointcloud = torch.rand(100, 3)
>>> prim = add_pointcloud(stage, pointcloud, '/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

The generated voxelgrid Prim.

Return type

(Usd.Prim)

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_material(pbr_material, file_path_or_stage, scene_path=None, texture_path=None, bound_prims=None, texture_file_prefix=None, shader_name=None, time=None, overwrite_textures=False)

Exports a PyTorch Material object (e.g. see PBRMaterial) to USD. The shader used must have a corresponding registered writer function. Currently supports UsdPreviewSurface.

Parameters

  • pbr_material (Material) – instance of Material class with a writer registered

  • file_path_or_stage (str, Usd.Stage) – Path to usd file (*.usd, *.usda, *.usdc) or Usd.Stage.

  • scene_path (str, optional) – Absolute path to use for UsdShade.Material prim within the USD file scene. If not set, will suggest a scene_path that is not yet present in the scene (for example “/World/Looks/material_name_0”, avoiding collisions); the scene path used will be returned.

  • texture_path (str, optional) – Directory where to save textures. Will use the relative version of this path to save in USD. If not set, will use default “textures” directory relative to the USD path.

  • bound_prims (list of Usd.Prim, optional) – If provided, binds material to each prim.

  • texture_file_prefix (str, optional) – Prefix to use for saved texture files.

  • shader_name (str, optional) – Will be used to find appropriate writer. By default set to pbr_material.shader_name, e.g. UsdPreviewSurface.

  • time (convertible to float, optional) – Optional for writing USD files. Positive integer indicating the time at which to set parameters.

  • overwrite_textures (bool) – set to True to overwrite existing image files when writing textures; if False (default) will add index to filename to avoid conflicts.

Returns

scene_path where material was saved (e.g. if auto-set), and USD Material object.

Return type

(str, UsdShade.Material)

Raises

MaterialWriteError – if any error is encountered during write.

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, overwrite_textures=False, overwrite=False)

Export a single mesh to USD and save the stage to disk.

..note::

Since v0.18.0 this function can only overwrite existing file or raise an error. Use add_mesh() to modify existing usd file.

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.

  • overwrite_textures (bool) – Set to True to overwrite existing image files when writing textures; if False (default) will add index to filename to avoid conflicts.

  • overwrite (bool) – If True, overwrite existing .usda. If False (default) raise an error if files already exists.

Example

>>> vertices = torch.rand(3, 3)
>>> faces = torch.tensor([[0, 1, 2]])
>>> 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, overwrite_textures=False, overwrite=False)

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.

  • overwrite_textures (bool) – set to True to overwrite existing image files when writing textures; if False (default) will add index to filename to avoid conflicts.

  • overwrite (bool) – If True, overwrite existing .usda. If False (default) raise an error if files already exists.

Example

>>> vertices_list = [torch.rand(3, 3) for _ in range(3)]
>>> faces_list = [torch.tensor([[0, 1, 2]]) for _ in range(3)]
>>> 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', overwrite=False)

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’.

  • overwrite (bool) – If True, overwrite existing .usda. If False (default) raise an error if files already exists.

Example

>>> points = torch.rand(100, 3)
>>> 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', overwrite=False)

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’.

  • overwrite (bool) – If True, overwrite existing .usda. If False (default) raise an error if files already exists.

Example

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

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.

  • overwrite (bool) – If True, overwrite existing .usda. If False (default) raise an error if files already exists.

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, overwrite=False)

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.

  • overwrite (bool) – If True, overwrite existing .usda. If False (default) raise an error if files already exists.

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_material(file_path_or_stage, scene_path, texture_path=None, time=None)

Read material from file and return a PyTorch Material object (e.g. see PBRMaterial). The shader used must have a corresponding registered reader function. Currently supports UsdPreviewSurface.

Parameters

  • file_path_or_stage (str, Usd.Stage) – Path to usd file (*.usd, *.usda, *.usdc) or Usd.Stage.

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

  • texture_path (str, optional) – Path to textures directory. By default, the textures will be assumed to be under the same directory as the file specified by file_path.

  • time (convertible to float, optional) – Optional for reading USD files. Positive integer indicating the time at which to retrieve parameters.

Returns

Material object determined by the corresponding reader function.

Return type

(Material)

Raises

MaterialLoadError – if any error is encountered during load.

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])
kaolin.io.usd.read_usd_preview_surface(shader, texture_file_path, time)

Read UsdPreviewSurface material.

kaolin.io.usd.write_usd_preview_surface(pbr_material, stage, scene_path, write_texture_by_basename_fn, time)

Writes USD Preview Surface Material to stage at the specified scene_path.

Parameters

  • pbr_material (PBRMaterial) – material definition

  • stage (Usd.Stage) – the stage where to write

  • scene_path (str) – scene path where to write the top level material

  • write_texture_by_basename_fn (Callable) – function that takes (PyTorch image, basename) and writes it to the correct location with correct extension on disk, handling overwriting/non-overwriting logic, and returning path that is relative and should be added as the reference in USD. See kaolin.io.utils.TextureExporter.

  • () (time) – optional time code

Returns: UsdShade.Material