Is this page helpful?

usd_utils#

This module provides utility functions for working with USD prims and transformations.

Functions#

omni.physxclashdetectioncore.usd_utils.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. 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. Defaults to None.

Returns:

List of paths to child prims that match the filtering criteria.

Return type:

List[Sdf.Path]

omni.physxclashdetectioncore.usd_utils.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. 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. 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. For a collection input, returns paths of all prims in the collection. Returns empty list if prim/collection not found or on error.

Return type:

List[Sdf.Path]

omni.physxclashdetectioncore.usd_utils.matrix_to_list(matrix: Gf.Matrix4d) → List[float]#

Converts a Gf.Matrix4d to a flat list of 16 floats in row-major order.

Parameters:

matrix (Gf.Matrix4d) – The 4x4 matrix to convert.

Returns:

The matrix elements as a flat list in row-major order.

Return type:

List[float]

omni.physxclashdetectioncore.usd_utils.list_to_matrix(lst: List[float]) → Gf.Matrix4d | None#

Converts a flat list of 16 floats in row-major order to a Gf.Matrix4d.

Parameters:

lst (List[float]) – The list of 16 floats to convert.

Returns:

The resulting Gf.Matrix4d or None if input is invalid.

Return type:

Optional[Gf.Matrix4d]

omni.physxclashdetectioncore.usd_utils.serialize_matrix_to_json(matrix: Gf.Matrix4d) → str#

Creates json string out of matrix.

Parameters:

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

Returns:

The JSON string representation of the matrix.

Return type:

str

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

Creates matrix out of 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]

omni.physxclashdetectioncore.usd_utils.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 (Optional[float]) – 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]

Example#

Working with USD utilities:

from omni.physxclashdetectioncore.usd_utils import (
    get_list_of_prim_paths,
    get_prim_matrix,
    matrix_to_list,
    list_to_matrix
)
from pxr import Usd

# Open stage
stage = Usd.Stage.Open("/path/to/stage.usd")

# Get all prim paths under /World
prim_paths = get_list_of_prim_paths(
    stage,
    "/World",
    add_prim_children=True
)

# Get transformation matrix for a prim at time 1.0 seconds
matrix = get_prim_matrix(stage, "/World/Cube", time=1.0)

if matrix:
    # Convert to list
    matrix_list = matrix_to_list(matrix)
    print(f"Matrix as list: {matrix_list}")

    # Convert back to matrix
    restored_matrix = list_to_matrix(matrix_list)