fxusd

Module for creating and manipulating USD (Universal Scene Description) files.

Some functions coming from usd_scene_construction_utils. And here is the USD C++ API documentation.

add_box

add_box(stage: Stage, path: str, size: Tuple[float, float, float]) -> Prim

Adds a 3D box to a USD stage.

This adds a 3D box to the USD stage. The box is created with it's center at (x, y, z) = (0, 0, 0).

Parameters:

Name	Type	Description	Default
stage		class:Usd.Stage): The USD stage to modify.	required
path	str	The path to add the USD prim.	required
size	Tuple[float, float, float]	The size of the box (x, y, z sizes).	required

Returns:

Type	Description
Prim	Usd.Prim: The created USD prim.

add_camera

add_camera(
    stage: Stage,
    path: str,
    focal_length: float = 35,
    horizontal_aperature: float = 20.955,
    vertical_aperature: float = 20.955,
    clipping_range: Tuple[float, float] = (0.1, 100000),
) -> Camera

Adds a camera to a USD stage.

Parameters:

Name	Type	Description	Default
stage	Stage	The USD stage to modify.	required
path	str	The path to add the USD prim.	required
focal_length	float	The focal length of the camera (default 35).	35
horizontal_aperature	float	The horizontal aperature of the camera (default 20.955).	20.955
vertical_aperature	float	The vertical aperature of the camera (default 20.955).	20.955
clipping_range	Tuple[float, float]	The clipping range of the camera.	(0.1, 100000)

Returns:

Type	Description
Camera	UsdGeom.Camera: The created USD camera.

add_dome_light

add_dome_light(
    stage: Stage,
    path: str,
    intensity: float = 1000,
    angle: float = 180,
    exposure: float = 0.0,
) -> DomeLight

Adds a dome light to a USD stage.

Parameters:

Name	Type	Description	Default
stage	Stage	The USD stage to modify.	required
path	str	The path to add the USD prim.	required
intensity	float	The intensity of the dome light (default 1000).	1000
angle	float	The angle of the dome light (default 180)	180
exposure	float	THe exposure of the dome light (default 0)	0.0

Returns:

Type	Description
DomeLight	UsdLux.DomeLight: The created Dome light.

add_plane

add_plane(
    stage: Stage,
    path: str,
    size: Tuple[float, float],
    uv: Tuple[float, float] = (1, 1),
) -> Prim

Adds a 2D plane to a USD stage.

Parameters:

Name	Type	Description	Default
stage	Stage	The USD stage to modify.	required
path	str	The path to add the USD prim.	required
size	Tuple[float, float]	The size of the 2D plane (x, y).	required
uv	Tuple[float, float]	The UV mapping for textures applied to the plane. For example, uv=(1, 1), means the texture will be spread to fit the full size of the plane. uv=(10, 10) means the texture will repeat 10 times along each dimension. uv=(5, 10) means the texture will be scaled to repeat 5 times along the x dimension and 10 times along the y direction.	(1, 1)

Returns:

Type	Description
Prim	Usd.Prim: The created USD prim.

add_prim

add_prim(stage: Stage, path: str, prim_type: str) -> Prim

Adds a USD prim to a USD stage.

Parameters:

Name	Type	Description	Default
stage		class:Usd.Stage): The USD stage to modify.	required
path	str	The path to add the USD prim.	required
prim_type	str	The type of the USD prim to add.	required

Returns:

Type	Description
Prim	Usd.Prim: The created USD prim.

add_semantics

add_semantics(prim: Prim, type: str, name: str) -> Prim

Adds semantics to a USD prim.

This function adds semantics to a USD prim. This is useful for assigning classes to objects when generating synthetic data with Omniverse Replicator.

For example:

add_semantics(dog_prim, "class", "dog") add_semantics(cat_prim, "class", "cat")

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to modify.	required
type	str	The semantics type. This depends on how the data is ingested. Typically, when using Omniverse replicator you will set this to "class".	required
name	str	The value of the semantic type. Typically, this would correspond to the class label.	required

Returns:

Type	Description
Prim	Usd.Prim: The USD prim with added semantics.

add_sphere_light

add_sphere_light(
    stage: Stage, path: str, intensity=30000, radius=50, angle=180, exposure=0.0
) -> SphereLight

Adds a sphere light to a USD stage.

Parameters:

Name	Type	Description	Default
stage	Stage	The USD stage to modify.	required
path	str	The path to add the USD prim.	required
radius	float	The radius of the sphere light	50
intensity	float	The intensity of the sphere light (default 1000).	30000
angle	float	The angle of the sphere light (default 180)	180
exposure	float	THe exposure of the sphere light (default 0)	0.0

Returns:

Type	Description
SphereLight	UsdLux.SphereLight: The created sphere light.

add_usd_ref

add_usd_ref(stage: Stage, path: str, usd_path: str) -> Prim

Adds an external USD reference to a USD stage.

Parameters:

Name	Type	Description	Default
stage		class:Usd.Stage): The USD stage to modify.	required
path	str	The path to add the USD reference.	required
usd_path	str	The filepath or URL of the USD reference (ie: a Nucleus server URL).	required

Returns:

Type	Description
Prim	Usd.Prim: The created USD prim.

add_xform

add_xform(stage: Stage, path: str) -> Prim

Adds a USD transform (Xform) to a USD stage.

This method adds a USD Xform to the USD stage at a given path. This is helpful when you want to add hierarchy to a scene. After you create a transform, any USD prims located under the transform path will be children of the transform and can be moved as a group.

Parameters:

Name	Type	Description	Default
stage		class:Usd.Stage): The USD stage to modify.	required
path	str	The path to add the USD prim.	required

Returns:

Type	Description
Prim	Usd.Prim: The created USD prim.

apply_xform_matrix

apply_xform_matrix(prim: Prim, transform: ndarray) -> Prim

Applies a homogeneous transformation matrix to the current prim's xform list.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to transform.	required
transform	ndarray	The 4x4 homogeneous transform matrix to apply.	required

Returns:

Type	Description
Prim	Usd.Prim: The modified USD prim with the provided transform applied after current transforms.

bind_material

bind_material(prim: Prim, material: Material) -> Prim

Binds a USD material to a USD prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to modify.	required
material	Material	The USD material to bind to the USD prim.	required

Returns:

Type	Description
Prim	Usd.Prim: The modified USD prim with the specified material bound to it.

collapse_xform

collapse_xform(prim: Prim) -> Prim

Collapses all xforms on a given USD prim.

This method collapses all Xforms on a given prim. For example, a series of rotations, translations would be combined into a single matrix operation.

Parameters:

Name	Type	Description	Default
prim	Prim	The Usd.Prim to collapse the transforms of.	required

Returns:

Type	Description
Prim	Usd.Prim: The Usd.Prim.

compute_bbox

compute_bbox(
    prim: Prim,
) -> Tuple[Tuple[float, float, float], Tuple[float, float, float]]

Computes the axis-aligned bounding box for a USD prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to compute the bounding box of.	required

Returns:

Type	Description
Tuple[Tuple[float, float, float], Tuple[float, float, float]]	Tuple[Tuple[float, float, float], Tuple[float, float, float]] The ((min_x, min_y, min_z), (max_x, max_y, max_z)) values of the bounding box.

compute_bbox_center

compute_bbox_center(prim: Prim) -> Tuple[float, float, float]

Computes the (x, y, z) center of the axis-aligned bounding box for a prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to compute the center of.	required

Returns:

Type	Description
Tuple[float, float, float]	Tuple[float, float, float]: The (x, y, z) center of the bounding box.

compute_bbox_size

compute_bbox_size(prim: Prim) -> Tuple[float, float, float]

Computes the (x, y, z) size of the axis-aligned bounding box for a prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to compute the size of.	required

Returns:

Type	Description
Tuple[float, float, float]	Tuple[float, float, float]: The (x, y, z) size of the bounding box.

compute_look_at_matrix

compute_look_at_matrix(
    at: Tuple[float, float, float],
    up: Tuple[float, float, float],
    eye: Tuple[float, float, float],
) -> ndarray

Computes a 4x4 homogeneous "look at" transformation matrix.

Parameters:

Name	Type	Description	Default
at	Tuple[float, float, float]	The (x, y, z) location that the transform should be facing. For example (0, 0, 0) if the transformation should face the origin.	required
up	Tuple[float, float, float]	The up axis fot the transform. ie: (0, 0, 1) for the up-axis to correspond to the z-axis.	required
eye	Tuple[float, float]	The (x, y, z) location of the transform. For example, (100, 100, 100) if we want to place a camera at (x=100,y=100,z=100)	required

Returns:

Type	Description
ndarray	np.ndarray: The 4x4 homogeneous transformation matrix.

compute_sphere_point

compute_sphere_point(
    elevation: float, azimuth: float, distance: float
) -> Tuple[float, float, float]

Compute a sphere point given an elevation, azimuth and distance.

Parameters:

Name	Type	Description	Default
elevation	float	The elevation in degrees.	required
azimuth	float	The azimuth in degrees.	required
distance	float	The distance.	required

Returns:

Type	Description
Tuple[float, float, float]	Tuple[float, float, float]: The sphere coordinate.

deg2rad

deg2rad(x)

Convert degrees to radians.

export_stage

export_stage(stage: Stage, filepath: str, default_prim=None)

Exports a USD stage to a given filepath.

Parameters:

Name	Type	Description	Default
stage	Stage	The USD stage to export.	required
filepath	str	The filepath to export the USD stage to.	required
default_prim	Optional[str]	The path of the USD prim in the stage to set as the default prim. This is useful when you want to use the exported USD as a reference, or when you want to place the USD in Omniverse.	None

get_material

get_material(stage: Stage, path: str) -> Material

Returns a material at the specified path in a USD stage.

Parameters:

Name	Type	Description	Default
stage	Stage	The USD stage to query.	required
path	str	The path of the material.	required

Returns:

Type	Description
Material	UsdShade.Material: The USD material at the specified path.

get_num_xform_ops

get_num_xform_ops(prim: Prim) -> int

Returns the number of xform ops on a given prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to query.	required

Returns:

Name	Type	Description
int	int	The number of xform ops on the prim.

get_prim

get_prim(stage: Stage, path: str) -> Prim

Returns a prim at the specified path in a USD stage.

Parameters:

Name	Type	Description	Default
stage	Stage	The USD stage to query.	required
path	str	The path of the prim.	required

Returns:

Type	Description
Prim	Usd.Prim: The USD prim at the specified path.

get_prim_info

get_prim_info(prim: Prim) -> Dict[str, Any]

Returns information about a given USD prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to query.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: A dictionary with information about the prim.

Examples:

>>> stage = Usd.Stage.Open("test.usda")
>>> prim = stage.GetPrimAtPath("/box")
>>> get_prim_info(prim)
>>> {
...     "name": "box",
...     "path": "/box",
...     "type": "Xform",
...     ...
... }

get_prim_prototype

get_prim_prototype(stage: Stage, prim: Prim) -> Optional[Prim]

Returns the prototype of a given instance prim.

Parameters:

Name	Type	Description	Default
stage	Stage	The USD stage to query.	required
prim	Prim	The USD prim to query.	required

Returns:

Type	Description
Optional[Prim]	Optional[Usd.Prim]: The prototype prim of the given prim.

get_visibility

get_visibility(prim: Prim)

Returns the visibility of a given prim.

See set_visibility for details.

get_xform_op_order

get_xform_op_order(prim: Prim) -> Optional[Sequence[str]]

Returns the order of Xform ops on a given prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to query.	required

Returns:

Type	Description
Optional[Sequence[str]]	Optional[Sequence[str]]: The order of the xform ops. For example: ["xformOp:translate", "xformOp:rotateX", "xformOp:rotateY"].

iterator

iterator(
    start_prim: Prim,
    predicate: Optional[_Term] = None,
    condition: Optional[Callable[[Prim], bool]] = None,
    prune_children: bool = True,
) -> List[Prim]

Iterates over the USD stage starting from a given prim, optionally filtering prims based on a condition.

Parameters:

Name	Type	Description	Default
start_prim	Prim	The starting point of the iteration.	required
predicate	_Term	A predicate that determines which prims are included in the iteration. Defaults to None.	None
condition	Callable[[Prim], bool]	A function that takes a Usd.Prim as input and returns True if the prim should be included in the result. If None, all prims are included. Defaults to None.	None
prune_children	bool	If True, children of matching prims are not included in the result. Defaults to True.	True

Returns:

Type	Description
List[Prim]	List[Usd.Prim]: A list of prims that match the condition (if provided).

Examples:

Example A

>>> def is_mesh(prim):
...     return prim.IsA(UsdGeom.Mesh)
>>> stage = Usd.Stage.Open("test.usda")
>>> start_prim = stage.GetPrimAtPath("/")
>>> predicate = Usd.PrimIsActive & Usd.PrimIsLoaded
>>> selected_prims = standard_iterator(
...     start_prim, predicate, condition=is_mesh
... )
[Usd.Prim(</boxA>), Usd.Prim(</boxB>), Usd.Prim(</boxC>)]

Example B

>>> iterator(
...     stage.GetPseudoRoot(),
...     condition=lambda x: x.IsA(UsdGeom.Camera)
...     )
[Usd.Prim(</camera>)]

new_anonymous_layer

new_anonymous_layer() -> Layer

Creates a new anonymous USD layer.

Returns:

Type	Description
Layer	Sdf.Layer: The USD layer.

new_in_memory_stage

new_in_memory_stage() -> Stage

Creates a new in memory USD stage.

Returns:

Type	Description
Stage	Usd.Stage: The USD stage.

rad2deg

rad2deg(x: float) -> float

Convert radians to degrees.

Parameters:

Name	Type	Description	Default
x	float	The angle in radians.	required

rotate_x

rotate_x(prim: Prim, angle: float) -> Prim

Rotates a prim around the X axis.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to rotate.	required
angle	float	The rotation angle in degrees.	required

Returns:

Type	Description
Prim	Usd.Prim: The rotated prim.

rotate_y

rotate_y(prim: Prim, angle: float) -> Prim

Rotates a prim around the Y axis.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to rotate.	required
angle	float	The rotation angle in degrees.	required

Returns:

Type	Description
Prim	Usd.Prim: The rotated prim.

rotate_z

rotate_z(prim: Prim, angle: float) -> Prim

Rotates a prim around the Z axis.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to rotate.	required
angle	float	The rotation angle in degrees.	required

Returns:

Type	Description
Prim	Usd.Prim: The rotated prim.

scale

scale(prim: Prim, scale: Tuple[float, float, float]) -> Prim

Scales a prim along the (x, y, z) dimensions.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to scale.	required
scale	Tuple[float, float, float]	The scaling factors for the (x, y, z) dimensions.	required

Returns:

Type	Description
Prim	Usd.Prim: The scaled prim.

set_visibility

set_visibility(
    prim: Prim, visibility: Literal["inherited", "invisible"] = "inherited"
) -> Prim

Sets the visibility of a prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The prim to control the visibility of.	required
visibility	str	The visibility of the prim. "inherited" if the prim is visibile as long as it's parent is visible, or invisible if it's parent is invisible. Otherwise, "invisible" if the prim is invisible regardless of it's parent's visibility.	'inherited'

Returns:

Type	Description
Prim	Usd.Prim: The USD prim.

set_xform_op_order

set_xform_op_order(prim: Prim, op_order: Sequence[str]) -> Prim

Sets the order of Xform ops on a given prim.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to modify.	required
op_order	Sequence[str]	The order of the xform ops. For example: ["xformOp:translate", "xformOp:rotateX", "xformOp:rotateY"]	required

Returns:

Type	Description
Prim	Usd.Prim: The modified USD prim with the specified xform op order.

stack_prims

stack_prims(
    prims: Sequence[Prim], axis: int = 2, gap: float = 0, align_center=False
) -> Sequence[Prim]

Stacks prims on top of each other (or side-by-side).

This function stacks prims by placing them so their bounding boxes are adjacent along a given axis.

Parameters:

Name	Type	Description	Default
prims	Prim	The USD prims to stack.	required
axis	int	The axis along which to stack the prims. x=0, y=1, z=2. Defaults to 2.	2
gap	float	The spacing to add between stacked elements.	0

Returns:

Type	Description
Sequence[Prim]	Sequence[Usd.Prim]: The stacked prims.

translate

translate(prim: Prim, offset: Tuple[float, float, float]) -> Prim

Translates a prim along the (x, y, z) dimensions.

Parameters:

Name	Type	Description	Default
prim	Prim	The USD prim to translate.	required
offset	Tuple[float, float, float]	The offsets for the (x, y, z) dimensions.	required

Returns:

Type	Description
Prim	Usd.Prim: The translated prim.

xform_op_move_end_to_front

xform_op_move_end_to_front(prim: Prim) -> Prim

Pops the last xform op on a given prim and adds it to the front.