USD Utilities#

Overview#

File Name: usd_utils.py

This file provides utility functions for working with USD (Universal Scene Description) files. It includes functions to retrieve child prims, list prim paths, serialize and deserialize matrices, and compute transformation matrices for prims.

Functions#

get_prim_children_paths(
prim: Usd.Prim,
exclude_invisible: bool = True,
prim_accept_fn: Callable[[Usd.Prim], bool] | None = None,
) → List[Sdf.Path]#

Returns paths of all children of the given prim, optionally filtered by a custom predicate and visibility.

This function traverses the prim hierarchy starting from the given prim and returns paths to all child prims that match the specified filtering criteria. The traversal also handles instance proxies.

Inactive prims are always excluded from the results. If exclude_invisible is True, prims with visibility=invisible and all their descendants will be excluded.

Parameters:

  • prim (Usd.Prim) – The root prim to start traversal from.

  • exclude_invisible (bool) – If True, excludes prims with visibility=invisible and their descendants. If False, includes all prims regardless of visibility. Defaults to True.

  • prim_accept_fn (Optional[Callable[[Usd.Prim], bool]]) – Optional predicate function that takes a Usd.Prim and returns True if the prim should be included. If None, all active prims are accepted. Defaults to None.

Returns:

List of paths to child prims that match the filtering criteria. The paths are returned as Sdf.Path objects.

Return type:

List[Sdf.Path]

get_list_of_prim_paths(
stage: Usd.Stage,
prim_str_path: str,
add_prim_children: bool = False,
prim_accept_fn: Callable[[Usd.Prim], bool] | None = None,
) → List[Sdf.Path]#

Returns list of prim paths for a given prim or collection.

Can optionally include child prims but not for collections.

Parameters:

  • stage (Usd.Stage) – The stage containing the prims.

  • prim_str_path (str) – The path to the prim or collection.

  • add_prim_children (bool) – If True, includes paths of all child prims that match prim_accept_fn. If False, only returns the path of the specified prim. Defaults to False.

  • prim_accept_fn (Optional[Callable[[Usd.Prim], bool]]) – Optional predicate function that takes a Usd.Prim and returns True if the prim should be included. Only used when add_prim_children is True. If None, all active and visible prims are accepted. Defaults to None.

Returns:

List of prim paths. For a prim input, returns either just the prim path or paths of all matching child prims based on add_prim_children. For a collection input, returns paths of all prims in the collection (add_prim_children is ignored). Returns empty list if prim/collection not found or on error.

Return type:

List[Sdf.Path]

serialize_matrix_to_json(matrix: Gf.Matrix4d) → str#

Creates a JSON string representation of a matrix.

Parameters:

matrix (Gf.Matrix4d) – The matrix to serialize into a JSON string.

Returns:

The JSON string representation of the matrix.

Return type:

str

deserialize_matrix_from_json(
json_string: str,
) → Gf.Matrix4d | None#

Creates a matrix from a JSON string. Returns None in case of failure.

Parameters:

json_string (str) – The JSON string to deserialize into a matrix.

Returns:

The deserialized matrix or None if failed.

Return type:

Optional[Gf.Matrix4d]

get_prim_matrix(
stage: Usd.Stage,
prim_path: str,
time: float | None = None,
) → Gf.Matrix4d | None#

Returns world transformation of a prim on ‘prim_path’ or None in case of failure. If ‘time’ is None then Usd.TimeCode.Default() is used.

Parameters:

  • stage (Usd.Stage) – The stage containing the prim.

  • prim_path (str) – The path to the prim.

  • time (float, optional) – The time of the transformation in seconds. Defaults to Usd.TimeCode.Default().

Returns:

The world transformation matrix or None if failed.

Return type:

Optional[Gf.Matrix4d]

On this page