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

UsdPreviewSurface: Import material with shader id UsdPreviewSurface. All parameters are supported, including textures. See https://graphics.pixar.com/usd/release/wp_usdpreviewsurface.html for more details on available material parameters.

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, 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
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, 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: 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_gaussiancloud(stage, scene_path, positions, orientations, scales, opacities, sh_coeff, local_to_world=None, time=None, overwrite=False)¶

Add a gaussiancloud as a ParticleField3DGaussianSplat 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.
scene_path (str) – Absolute path of gaussian cloud within the USD file scene. Must be a valid Sdf.Path.
positions (torch.Tensor) – Position of each gaussian, of shape \((\text{num_gaussians}, 3)\).
orientations (torch.Tensor) – Orientation of each gaussian as quaternions, as \((w, x, y, z)\), of shape \((\text{num_gaussians}, 4)\).
scales (torch.Tensor) – Scale of each gaussian, of shape \((\text{num_gaussians}, 3)\), post activation.
opacities (torch.Tensor) – Opacity of each gaussian, of shape \((\text{num_gaussians})\), post activation.
sh_coeff (torch.Tensor) – Spherical harmonics coefficients of each gaussian, of shape \((\text{num_gaussians}, (\text{num_degrees} + 1)^2, 3)\).
time (convertible to float, optional) – Positive integer defining the time at which the supplied parameters correspond to.
overwrite (bool) – If True, replace existing prim at scene_path. If False (default), raise ValueError when a ParticleField3DGaussianSplat already exists there.
local_to_world (torch.Tensor) – Local-to-world transform matrix of shape \((4, 4)\), or None if the prim has an identity transform.

Returns

The generated gaussian Prim.

Return type

(Usd.Prim)

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, local_to_world=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
local_to_world (torch.FloatTensor, optional) – local-to-world transform of shape (4, 4).
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_physics_material(file_path_or_stage, path_or_prim, physics_points: PhysicsPoints, material_name: Optional[str] = 'default', time: Optional[TimeCode] = None, overwrite: bool = False)¶

Add physics material to USD Prim.

Those contains the information necessary to define the physical property of an object, typically what output VoMP and the parameters that SimplicitsObject take as inputs for training.

see PhysicsPoints for more details.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
path_or_prim (str or Usd.Prim) – Usd.Prim, or absolute path within the USD file stage, must be a valid Sdf.Path.
physics_points (PhysicsPoints) – PhysicsPoints object to add to the USD Prim.
material_name (optional, str) – Name of the physics material attribute API. Default: ‘default’.
time (optional, Usd.TimeCode) – TimeCode defining the time at which the supplied parameters correspond to. Default: Usd.TimeCode.Default().
overwrite (optional, bool) – if True, and material already exist at path_or_prim, overwrite the material with new attributes. Otherwise raise FileExistsError.

Returns

The new material’s Prim.

Return type

(Usd.Prim)

kaolin.io.usd.add_pointcloud(stage, scene_path, points=None, colors=None, local_to_world=None, time=None, overwrite=False, 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.
scene_path (str) – Absolute path of pointcloud within the USD file scene. Must be a valid Sdf.Path.
points (torch.FloatTensor) – Pointcloud tensor containing N points of shape (N, 3).
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.
local_to_world (torch.Tensor, optional) – Local-to-world transform matrix of shape \((4, 4)\). If provided, it is written onto the prim via set_local_to_world_transform().
overwrite (bool) – If True, allow replacing an existing prim at scene_path whose type does not match points_type. If False (default), raise ValueError in that case.
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')
>>> points = torch.rand(100, 3)
>>> prim = add_pointcloud(stage, '/World/PointClouds/pointcloud_0', points)
>>> stage.Save()

Note

Deprecated since v0.19: the positional order changed from add_pointcloud(stage, points, scene_path, ...) to add_pointcloud(stage, scene_path, points, ...). v0.18-style calls (tensor as the 2nd positional argument) still work but emit a DeprecationWarning.

kaolin.io.usd.add_skinned_physics(file_path_or_stage, path_or_prim, skinned_physics_points: SkinnedPhysicsPoints, instance_name: Optional[str] = 'default', time: Optional[TimeCode] = None, overwrite: bool = False)¶

Add Skinned physics attributes to USD Prim.

Contains the information necessary to simulate an object within a SimplicitsScene, see SkinnedPhysicsPoints for more details.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
path_or_prim (str or Usd.Prim) – Usd.Prim, or absolute path within the USD file stage, must be a valid Sdf.Path.
skinned_physics_points (SkinnedPhysicsPoints) – SkinnedPhysicsPoints object to add to the USD Prim.
instance_name (optional, str) – Name of the skinned physics instance name, allowing to store multiple skinned physics behavior per prim. Default: ‘default’.
time (optional, Usd.TimeCode) – TimeCode defining the time at which the supplied parameters correspond to. Default: Usd.TimeCode.Default().
overwrite (optional, bool) – if True, and setup already exist at path_or_prim, overwrite the setup with new attributes. Otherwise raise FileExistsError.

Returns

The Prim with skinned physics applied.

Return type

(Usd.Prim)

kaolin.io.usd.add_subset(file_path_or_stage, prim_or_path, name, indices, family_name='part', overwrite=False)¶

Add subset to an existing Prim.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to USD file to be opened. If a USD.Stage is provided, the stage is not saved at the end.
prim_or_path (str or Usd.Prim) – Usd.Prim on which to add the subset, or absolute path within the USD file scene. Must be a valid Sdf.Path.
name (str) – name of the subset.
indices (torch.LongTensor) – indices of the elements that represent the subset.
family_name (str) – The family groups subsets by purpose (e.g. 'part' for segmentation parts, 'materialBind' for material assignments). Default: 'part'.
overwrite (bool) – If True, reassign the indices on an existing subset with the same name. If False (default), raise a ValueError if a subset with that name already exists.

Returns

The Prim of the generated subset.

Return type

(Usd.Prim)

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_gaussiancloud(file_path, scene_path='/World/Gaussians/gaussian_0', positions=None, orientations=None, scales=None, opacities=None, sh_coeff=None, local_to_world=None, up_axis='Y', time=None, overwrite=False)¶

Export a single gaussian cloud to a USD scene.

The gaussian cloud will be added to the USD stage and represented by a ParticleField3DGaussianSplat. The stage is then saved to disk.

Parameters

file_path (str) – Path to usd file (*.usd, *.usda).
scene_path (str, optional) – Absolute path of gaussian cloud within the USD file scene. Must be a valid Sdf.Path. If no path is provided, a default path is used.
positions (torch.Tensor) – Position of each gaussian, of shape \((\text{num_gaussians}, 3)\).
orientations (torch.Tensor) – Orientation of each gaussian as quaternions, as \((w, x, y, z)\), of shape \((\text{num_gaussians}, 4)\).
scales (torch.Tensor) – Scale of each gaussian, of shape \((\text{num_gaussians}, 3)\).
opacities (torch.Tensor) – Opacity of each gaussian, of shape \((\text{num_gaussians})\).
sh_coeff (torch.Tensor) – Spherical harmonics coefficients of each gaussian, of shape \((\text{num_gaussians}, (\text{num_degrees} + 1)^2, 3)\).
local_to_world (torch.Tensor) – Local-to-world transform matrix of shape \((4, 4)\), or None if the prim has an identity transform.
up_axis (str, optional) – Axis to use for up direction. Must be one of ‘X’, ‘Y’, ‘Z’. Defaults to ‘Y’.
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.

kaolin.io.usd.export_material(pbr_material: 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 – 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, local_to_world=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
local_to_world (torch.FloatTensor, optional) – local-to-world transform of shape (4, 4).
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, local_to_world=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
local_to_world (torch.FloatTensor, optional) – local-to-world transforms as a single (4, 4) tensor (broadcast to every mesh) or a batched (N, 4, 4) tensor (one transform per mesh). Aligned with kaolin.rep.SurfaceMesh.transform.
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, scene_path='/World/PointClouds/pointcloud_0', points=None, colors=None, local_to_world=None, up_axis='Y', time=None, points_type='point_instancer', overwrite=False, pointcloud=None, color=None)¶

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).
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.
points (torch.FloatTensor) – Pointcloud tensor containing N points of shape (N, 3).
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) – Positive integer defining the time at which the supplied parameters correspond to.
local_to_world (torch.Tensor, optional) – Local-to-world transform matrix of shape \((4, 4)\).
up_axis (str, optional) – Axis to use for up direction. Must be one of ‘X’, ‘Y’, ‘Z’. Defaults to ‘Y’.
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=points)

Note

Deprecated since v0.19: the positional order changed and two kwargs were renamed. v0.18-style calls continue to work but emit a DeprecationWarning:

2nd positional was pointcloud (tensor); it is now scene_path (str).
pointcloud= keyword has been renamed to points=.
color= keyword has been renamed to colors=.

kaolin.io.usd.export_pointclouds(file_path, scene_paths=None, points=None, colors=None, local_to_world=None, up_axis='Y', times=None, points_type='point_instancer', overwrite=False, pointclouds=None)¶

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).
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.
points (list of torch.FloatTensor) – List of pointcloud tensors of length N defining N pointclouds.
colors (list of tensors, optional) – List of RGB colors of length N, each corresponding to a pointcloud in the points list. colors only works if points_type is ‘usd_geom_points’.
times (list of int) – Positive integers defining the time at which the supplied parameters correspond to.
local_to_world (torch.FloatTensor, optional) – local-to-world transforms as a single (4, 4) tensor (broadcast to every pointcloud) or a batched (N, 4, 4) tensor (one transform per pointcloud).
up_axis (str, optional) – Axis to use for up direction. Must be one of ‘X’, ‘Y’, ‘Z’. Defaults to ‘Y’.
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_pointclouds('./new_stage.usd', points=[points])

Note

Deprecated since v0.19: the positional order changed and the 2nd positional argument was renamed. v0.18-style calls continue to work but emit a DeprecationWarning:

2nd positional was pointclouds (list of tensors); it is now scene_paths (list of str).
pointclouds= keyword has been renamed to 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_all_physics_materials(file_path_or_stage, prim_or_path, time: Optional[TimeCode] = None)¶

Get all physics materials from a prim. See get_physics_material() for more details.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
prim_or_path (str or Usd.Prim) – Usd.Prim, or absolute path within the USD file stage, must be a valid Sdf.Path.
time (optional, Usd.TimeCode) – TimeCode defining the time at which the supplied parameters correspond to. Default: Usd.TimeCode.Default().

Returns

Dictionary of physics materials namespaces and their corresponding physics materials.

Return type

(dict)

kaolin.io.usd.get_all_skinned_physics(file_path_or_stage, prim_or_path, time: Optional[TimeCode] = None, attribute: Optional[str] = None)¶

Get all skinned physics instances from a prim. see get_skinned_physics() for more details.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
prim_or_path (str or Usd.Prim) – Usd.Prim, or absolute path within the USD file stage, must be a valid Sdf.Path.
time (optional, Usd.TimeCode) – TimeCode defining the time at which the supplied parameters correspond to. Default: Usd.TimeCode.Default().
attribute (optional, str) – Name of the attribute to get the skinned physics from. Default: Attempt to automatically get the renderable points from the prim, works for Mesh, Points, PointInstancer, and ParticleField3DGaussianSplat.

Returns

Dictionary of skinned physics namespaces and their corresponding skinned physics.

Return type

(dict of str to SkinnedPhysicsPoints)

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_gaussiancloud_scene_paths(file_path_or_stage, scene_path=None)¶

Returns all gaussian cloud scene paths contained in specified file. Assuming ParticleField3DGaussianSplat.

Parameters

file_path_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
scene_path (str, optional) – If specified, only return paths under this scene path prefix.

Returns

List of filtered scene paths.

Return type

(list of str)

kaolin.io.usd.get_local_to_world_transform(file_path_or_stage, prim_or_path, time=None)¶

Get a prim’s local xform so that ComputeLocalToWorldTransform equals local_to_world.

Parameters

file_path_or_stage (Usd.Stage or str) – Path to usd file (*.usd, *.usda) or Usd.Stage.
prim_or_path (Usd.Prim or str) – The prim or path to the prim to get the transform from.
time – USD time code.

Returns

The local-to-world transform matrix of shape (4, 4).

Return type

torch.Tensor

kaolin.io.usd.get_mesh_prim_materials(mesh_prim, 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
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_mesh_scene_paths(file_path_or_stage, scene_path=None)¶

Returns all mesh scene paths contained in specified file.

Parameters

file_path_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
scene_path (str, optional) – If specified, only return paths under this scene path prefix.

Returns

List of filtered scene paths.

Return type

(list of str)

kaolin.io.usd.get_physics_material(file_path_or_stage, prim_or_path, material_name: Optional[str] = 'default', time: Optional[TimeCode] = None)¶

Get physics material parameters from a prim with a given material name.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
prim_or_path (str or Usd.Prim) – Usd.Prim, or absolute path within the USD file stage, must be a valid Sdf.Path.
material_name (optional, str) – Name of the physics material. Default: ‘default’.
time (optional, Usd.TimeCode) – TimeCode defining the time at which the supplied parameters correspond to. Default: Usd.TimeCode.Default().

Returns

PhysicsPoints populated from the prim’s attributes if the API binding for material_name is found, otherwise None.

Return type

(PhysicsPoints or None)

kaolin.io.usd.get_physics_materials_instance_names(file_path_or_stage, prim_or_path)¶

Get all physics materials namespaces from a prim with a given attribute API namespace.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
prim_or_path (str or Usd.Prim) – Usd.Prim, or absolute path within the USD file stage, must be a valid Sdf.Path.

Returns

List of physics materials namespaces found in the prim.

Return type

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

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.
scene_path (str, optional) – If specified, only return paths under this scene path prefix.

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 in the prim’s local space, of shape (N, 3)

transform (torch.FloatTensor): local-to-world transform of shape (4, 4), in USD convention (translation in last row)

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.get_skinned_physics(file_path_or_stage, prim_or_path, instance_name: Optional[str] = 'default', time: Optional[TimeCode] = None, attribute: Optional[str] = None)¶

Get skinned physics parameters from a prim with a given instance name.

Contains the information necessary to simulate an object within a SimplicitsScene, see SkinnedPhysicsPoints for more details.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
prim_or_path (str or Usd.Prim) – Usd.Prim, or absolute path within the USD file stage, must be a valid Sdf.Path.
instance_name (optional, str) – Name of the skinned physics instance. Default: ‘default’.
time (optional, Usd.TimeCode) – TimeCode defining the time at which the supplied parameters correspond to. Default: Usd.TimeCode.Default().
attribute (optional, str) – Name of the attribute to get the renderable points from. Default: Attempt to automatically get the renderable points from the prim, works for Mesh, Points, PointInstancer, and ParticleField3DGaussianSplat.

Returns

SkinnedPhysicsPoints populated from the prim’s attributes if the API binding for instance_name is found, otherwise None. The renderable field is populated from the prim geometry (or attribute if provided).

Return type

(SkinnedPhysicsPoints or None)

kaolin.io.usd.get_skinned_physics_instance_names(file_path_or_stage, prim_or_path)¶

Get all skinned physics instances from a prim with a given attribute API namespace.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
prim_or_path (str or Usd.Prim) – Usd.Prim, or absolute path within the USD file stage, must be a valid Sdf.Path.

Returns

List of skinned physics instances found in the prim.

Return type

(list)

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

Import all gaussianclouds from a USD file, apply their transforms, and merge into a single world-space cloud.

Each prim’s local_to_world transform (if not identity) is applied to positions, orientations, scales, and spherical-harmonics coefficients before merging. If clouds have different numbers of SH coefficients the higher-degree coefficients are truncated to the minimum present across all clouds.

Parameters

file_path_or_stage (Usd.Stage or str) – Path to usd file (*.usd, *.usda) or Usd.Stage.
scene_path (str, optional) – If specified, only import gaussians under this scene path prefix. Default: import all gaussians in the file.
time (convertible to float, optional) – Positive integer defining the time at which the supplied parameters correspond to.

Returns

A single merged gaussian cloud object, or None if no gaussian clouds are found.

Return type

(GaussianSplatModel)

kaolin.io.usd.import_gaussianclouds(file_path_or_stage, scene_paths=None, times=None, return_list=True)¶

Import gaussians from Usd file.

Parameters

file_path_or_stage (Usd.Stage or str) – Path to usd file (*.usd, *.usda) or Usd.Stage.
scene_paths (list of str) – Scene paths within the USD file indicating which primitive(s) to import.
times (list of Float or Float, optional) – Positive integer defining the time at which the supplied parameters correspond to.
return_list (bool, optional) – If True (default), return a list of GaussianSplatModel in the order of scene_paths. If False, return a dict keyed by scene path.

Returns

Either a list of GaussianSplatModel (when return_list=True, the default), or a dict[str, GaussianSplatModel] keyed by scene path (when return_list=False). Each model’s transform is set to the computed local-to-world matrix of shape \((4, 4)\), or None if the prim has an identity transform.

Return type

(list or dict of GaussianSplatModel)

kaolin.io.usd.import_material(file_path_or_stage, scene_path, texture_path=None, time=None) → Material¶

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 mesh scene from a USD file or Stage, all the prims under scene_path are merged into a single kaolin.rep.SurfaceMesh with their local-to-world transforms applied.

Supports homogeneous meshes (meshes with consistent numbers of vertices per face). The following interpolation types are supported for UV coordinates: vertex, varying and faceVarying. Returns an unbatched 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) – If specified, only import meshes under this scene path prefix. Default: import all meshes in the file.
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

A single merged unbatched kaolin.rep.SurfaceMesh in world space, or None if no meshes are found.

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 or None)

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

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)

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, return_list=True)¶

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.

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. Default: all mesh prims in the file are 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.
return_list (bool, optional) – If True (default), return a list of kaolin.rep.SurfaceMesh in the order of scene_paths (v0.18-compatible behaviour). If False, return a dict keyed by scene path.

Returns

A list of kaolin.rep.SurfaceMesh (when return_list=True, the default) or a dict[str, SurfaceMesh] keyed by scene path (when return_list=False), where each mesh has:

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.

Meshes skipped due to heterogeneous_mesh_handler returning None are omitted.

Return type

(list or dict 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 (auto-discovers all mesh prims)
>>> meshes = import_meshes('./new_stage.usd')
>>> len(meshes)
3
>>> meshes[0].vertices.shape
torch.Size([3, 3])

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
>>> # If needed, concatenate meshes into a batch
>>> from kaolin.rep import SurfaceMesh
>>> mesh = SurfaceMesh.cat(meshes, fixed_topology=False)

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

Import a pointcloud scene from a USD file or Stage, all the prims under scene_path are merged into a single world-space pointcloud.

Each prim’s local_to_world transform (if not identity) is applied to the points before concatenation. Colors and normals are concatenated only when every contributing prim provides them; otherwise the merged field is None.

Parameters

file_path_or_stage (str or Usd.Stage) – Path to usd file (*.usd, *.usda) or Usd.Stage.
scene_path (str, optional) – If specified, only import pointclouds under this scene path prefix. Default: import all pointclouds in the file.
time (convertible to float, optional) – Positive integer indicating the time at which to retrieve parameters.

Returns

namedtuple with fields:

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

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

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

transform (torch.FloatTensor or None): always None, since the per-prim local_to_world transforms have already been applied to the merged points.

Returns None if no pointclouds are found.

Return type

(namedtuple or None)

Example

>>> points = torch.rand(100, 3)
>>> export_pointcloud('./new_stage.usd', scene_path='/World/pointcloud', points=points)
>>> merged = import_pointcloud('./new_stage.usd')
>>> merged.points.shape
torch.Size([100, 3])

kaolin.io.usd.import_pointclouds(file_path_or_stage, scene_paths=None, times=None, return_list=True)¶

Import one or more pointclouds from a USD file or stage in their local space.

Assumes that pointclouds are interpreted using point instancers or UsdGeomPoints. Each prim’s points are returned in the prim’s local space, and its local_to_world transform is returned in the transform field (or None if the prim has an identity transform) rather than being applied to the points.

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 paths within the USD file indicating which primitive(s) to import. Default: import every pointcloud found in the file.
times (list of Number or Number, optional) – Positive integers indicating the time at which to retrieve parameters. A single value is broadcast across all scene_paths.
return_list (bool, optional) – If True (default), return a list of pointcloud_return_type namedtuples in the order of scene_paths. If False, return a dict keyed by scene path.

Returns

Either a list of pointcloud_return_type namedtuples (when return_list=True, the default), or a dict[str, pointcloud_return_type] keyed by scene path (when return_list=False). Each namedtuple has fields:

points (torch.FloatTensor): of shape (num_points, 3), in the prim’s local space

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

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

transform (torch.FloatTensor or None): local-to-world transform of shape (4, 4), or None if the prim has an identity transform

Return type

(list or dict of namedtuple)

Example

>>> points = torch.rand(100, 3)
>>> export_pointclouds('./new_stage.usd', points=[points, points, points])
>>> pointclouds = import_pointclouds('./new_stage.usd', return_list=False)
>>> len(pointclouds)
3
>>> next(iter(pointclouds.values())).points.shape
torch.Size([100, 3])

kaolin.io.usd.import_subsets(file_path_or_stage, prim_or_path, family_name=None)¶

Import subset from Prims.

Parameters

file_path_or_stage (str or Usd.Stage) – USD.Stage or path to file to stage to be opened.
prim_or_path (str or Usd.Prim) – Usd.Prim on which to get the subsets, or absolute path within the USD file scene. Must be a valid Sdf.Path.
family_name (optional, str) – The family groups subsets by purpose (e.g. 'part' for segmentation parts, 'materialBind' for material assignments). Default: None, i.e. return all subsets regardless of family.

Returns

dict mapping each subset’s USD path to a dict with the following fields:

indices (torch.Tensor): indices of the subset.
family_name (str): family name.

Return type

(dict of dict)

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, time)¶: Read UsdPreviewSurface material.

kaolin.io.usd.set_local_to_world_transform(file_path_or_stage, prim_or_path, local_to_world, time=None)¶

Set a prim’s local xform so that ComputeLocalToWorldTransform equals local_to_world.

Parameters

file_path_or_stage (Usd.Stage or str) – Path to usd file (*.usd, *.usda) or Usd.Stage.
prim_or_path (Usd.Prim or str) – The prim or path to the prim to set the transform on.
local_to_world (torch.Tensor) – \((4, 4)\) local-to-world matrix
time (convertible to float, optional) – Optional for writing USD files. Positive integer indicating the time at which to set parameters.

kaolin.io.usd.write_usd_preview_surface(pbr_material: PBRMaterial, 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