C++ guide and API reference#
Include isaacsim/foundation/usd/ovstage/Usd.hpp and link
isaacsim::foundation-usd-ovstage. All declarations live in the
isaacsim::foundation::usd::ovstage namespace.
#include <isaacsim/foundation/usd/ovstage/Usd.hpp>
using namespace isaacsim::foundation::usd::ovstage;
Stages are identified by an opaque int64_t handle returned by
createStage or
openStage. Pass this
handle to every subsequent call. A value of -1 indicates failure or an
invalid stage.
Stage#
createStage and openStage return an opaque stage identifier. Every
other function in this section takes that identifier as its first argument.
All prim paths are absolute SdfPath strings (e.g. "/World/Prim").
// Create a new, empty in-memory stage.
int64_t stageId = createStage();
// Open an existing USD file.
int64_t stageId = openStage("/path/to/scene.usd");
// Validate and release.
bool valid = isStageValid(stageId);
bool closed = closeStage(stageId);
Traversal#
traversePrim visits every prim in the subtree rooted at path. Return
false from the callback to stop early:
traversePrim(stageId, "/World",
[](const std::string& primPath) -> bool
{
// process primPath ...
return true; // continue
});
// Find prims whose path string matches a pattern.
std::vector<std::string> matches =
findMatchingPrimPaths(stageId, "*Prim*", /*traverse=*/true);
Stage representation#
generateStageRepresentation produces a human-readable summary of the
stage hierarchy. Supported mode values are "tree" (indented
parent-child tree) and "list" (flat list of paths):
std::string tree = generateStageRepresentation(stageId, "tree");
std::string list = generateStageRepresentation(stageId, "list");
SdfPath#
bool valid = isValidPathString("/World/Prim"); // true
bool invalid = isValidPathString("not/absolute"); // false
Prim#
Validity and hierarchy#
bool exists = isPrimValid(stageId, "/World/Prim");
std::string name = getName(stageId, "/World/Prim"); // "Prim"
std::string typeName = getTypeName(stageId, "/World/Prim"); // e.g. "Xform"
std::string parent = getParent(stageId, "/World/Prim"); // "/World"
std::vector<std::string> children = getChildren(stageId, "/World");
Schema type and API schemas#
isA tests whether a prim’s type is or derives from a given schema type.
hasApi, applyApi, and removeApi operate on applied API schemas.
Pass a non-empty instanceName for multiple-apply schemas:
bool isMesh = isA(stageId, "/World/Mesh", "Mesh");
bool hasPhysics = hasApi(stageId, "/World/Prim", "PhysicsRigidBodyAPI");
// Single-apply API schema.
applyApi(stageId, "/World/Prim", "PhysicsRigidBodyAPI");
// Multiple-apply API schema (e.g. material binding).
applyApi(stageId, "/World/Prim", "MaterialBindingAPI", "preview");
removeApi(stageId, "/World/Prim", "MaterialBindingAPI", "preview");
std::vector<std::string> schemas = getAppliedSchemas(stageId, "/World/Prim");
Prim Attribute#
Creating and removing attributes#
// Create a "float" attribute named "mass" on the prim.
bool created = createPrimAttribute(stageId, "/World/Prim", "mass", "float");
// Remove it.
bool removed = removePrimAttribute(stageId, "/World/Prim", "mass");
Inspecting attributes#
std::string typeName =
getPrimAttributeTypeName(stageId, "/World/Prim", "mass"); // "float"
std::vector<std::string> attrNames =
getPrimAttributeNames(stageId, "/World/Prim");
Reading and writing values#
getPrimAttributeValues and setPrimAttributeValues operate on multiple
prims in a single call to minimize round-trips:
std::vector<std::string> paths = { "/World/Cube1", "/World/Cube2" };
// Read "size" from both prims.
auto values = getPrimAttributeValues(stageId, paths, "size");
if (auto* arr = std::get_if<array::Array>(&values))
{
// Numeric attribute - process arr ...
}
// Write new values to both prims.
array::Array newSizes(std::vector<float>{ 1.0f, 2.0f });
std::vector<bool> success = setPrimAttributeValues(stageId, paths, "size", newSizes);
Xform#
All Xform functions operate on Xformable prims (Xform, Mesh, etc.).
Translations and positions use [x, y, z] order. Orientations are quaternions
in [w, ix, iy, iz] order. Scale vectors use [sx, sy, sz] order.
Scales#
std::vector<std::string> paths = { "/World/A", "/World/B" };
// Read local scales - returns an Array of shape (N, 3).
array::Array scales = getXformLocalScales(stageId, paths);
// Write local scales - preserves the existing local translation and rotation.
array::Array newScales(std::vector<std::vector<double>>{ { 2.0, 3.0, 4.0 },
{ 5.0, 6.0, 7.0 } });
setXformLocalScales(stageId, paths, newScales);
Local poses#
getXformLocalPoses returns a tuple of two arrays:
the translations (shape (N, 3)) and the orientations (shape (N, 4)).
setXformLocalPoses accepts optional translations and orientations; pass
std::nullopt to leave a component unchanged. The existing local scale is
always preserved.
// Read local poses.
auto [translations, orientations] = getXformLocalPoses(stageId, paths);
auto t = translations.get<std::vector<std::vector<double>>>(); // [x, y, z]
auto q = orientations.get<std::vector<std::vector<double>>>(); // [w, ix, iy, iz]
// Write both translation and orientation.
array::Array newTranslations(std::vector<std::vector<double>>{ { 1.0, 2.0, 3.0 },
{ 4.0, 5.0, 6.0 } });
array::Array newOrientations(std::vector<std::vector<double>>{ { 1.0, 0.0, 0.0, 0.0 },
{ 1.0, 0.0, 0.0, 0.0 } });
setXformLocalPoses(stageId, paths, newTranslations, newOrientations);
World poses#
getXformWorldPoses returns the same tuple layout as getXformLocalPoses
but in world space. setXformWorldPoses back-computes the required local
transform so that the prim ends up at the requested world pose; the existing
local scale is preserved.
// Read world poses.
auto [positions, orientations] = getXformWorldPoses(stageId, paths);
// Move both prims to new world positions, keeping their current orientations.
array::Array newPositions(std::vector<std::vector<double>>{ { 10.0, 0.0, 0.0 },
{ 0.0, 5.0, 0.0 } });
setXformWorldPoses(stageId, paths, newPositions, std::nullopt);
// Set world orientation only.
const double s = std::sqrt(2.0) / 2.0; // 90° around Z
array::Array newOrientations(std::vector<std::vector<double>>{ { s, 0.0, 0.0, s } });
setXformWorldPoses(stageId, { "/World/A" }, std::nullopt, newOrientations);
API reference#
Fully qualified namespace: isaacsim::foundation::usd::ovstage
-
namespace ovstage#
Functions Summary#
- void addReferenceToStage(int64_t stageId, const std::string &path, const std::string &usdPath, const std::string &typeName="Xform")
Adds a USD reference arc to a prim, defining it first if it does not exist.
- bool applyApi(int64_t stageId, const std::string &path, const std::string &schemaType, const std::optional< std::string > &instanceName=std::nullopt)
Applies an API schema to a prim.
- bool closeStage(int64_t stageId)
Closes and releases a previously created or opened stage.
- bool createPrimAttribute(int64_t stageId, const std::string &path, const std::string &attributeName, const std::string &typeName)
Creates a new attribute on a prim.
- int64_t createStage()
Creates a new, empty in-memory USD stage.
- void definePrim(int64_t stageId, const std::string &path, const std::string &typeName="Xform")
Defines a prim at the given path, creating ancestor prims as needed.
- std::string exportStageToString(int64_t stageId)
Serializes the stage's root layer to a USDA string.
- std::vector< std::string > findMatchingPrimPaths(int64_t stageId, const std::string &path, bool traverse=false)
Finds prim paths on the stage whose path string matches a pattern.
- std::string generateStageRepresentation(int64_t stageId, const std::string &mode="tree")
Generates a human-readable representation of the stage hierarchy.
- std::vector< std::string > getAppliedSchemas(int64_t stageId, const std::string &path)
Returns the list of API schema names applied to a prim.
- std::vector< std::string > getChildren(int64_t stageId, const std::string &path)
Returns the absolute paths of a prim's direct children.
- std::string getName(int64_t stageId, const std::string &path)
Returns the name component of a prim's path.
- std::string getParent(int64_t stageId, const std::string &path)
Returns the absolute path of a prim's parent.
- std::vector< std::string > getPrimAttributeNames(int64_t stageId, const std::string &path)
Returns the names of all attributes on a prim.
- std::string getPrimAttributeTypeName(int64_t stageId, const std::string &path, const std::string &attributeName)
Returns the SdfValueTypeName string of an attribute (e.g.
- AttributeValues getPrimAttributeValues(int64_t stageId, const std::vector< std::string > &paths, const std::string &attributeName)
Reads an attribute's value from multiple prims in a single call.
- void * getStagePtr(int64_t stageId)
Returns an opaque pointer to the underlying ovstage_instance_t struct.
- std::tuple< float, float, float > getStageTimeCode(int64_t stageId)
Returns the stage's start time code, end time code, and time codes per second.
- std::tuple< float, float > getStageUnits(int64_t stageId)
Returns the stage's metersPerUnit and kilogramsPerUnit scale factors.
- std::string getStageUpAxis(int64_t stageId)
Returns the stage's up-axis token (e.g.
- std::string getTypeName(int64_t stageId, const std::string &path)
Returns the schema type name of a prim (e.g.
- std::unordered_map< std::string, std::vector< std::string > > getVariants(int64_t stageId, const std::string &path, bool selection=true)
Returns the variant sets and their available or selected variants for a prim.
- std::tuple< array::Array, array::Array > getXformLocalPoses(int64_t stageId, const std::vector< std::string > &paths)
Returns the local poses of the given Xformable prims.
- array::Array getXformLocalScales(int64_t stageId, const std::vector< std::string > &paths)
Returns the local scales of the given Xformable prims.
- std::tuple< array::Array, array::Array > getXformWorldPoses(int64_t stageId, const std::vector< std::string > &paths)
Returns the world poses of the given Xformable prims.
- bool hasApi(int64_t stageId, const std::string &path, const std::string &schemaType, const std::optional< std::string > &instanceName=std::nullopt)
Checks whether an applied API schema is applied to a prim.
- int64_t importStageFromString(const std::string &usdString)
Creates a new in-memory stage populated from a USDA string.
- bool isA(int64_t stageId, const std::string &path, const std::string &schemaType)
Checks whether a prim is or derives from a given schema type.
- bool isPrimValid(int64_t stageId, const std::string &path)
Checks whether the prim at
pathexists and is valid on the stage.- bool isStageValid(int64_t stageId)
Checks whether a stage identifier refers to a live stage.
- bool isValidPathString(const std::string &path)
Checks whether a string is a syntactically valid SdfPath.
- std::tuple< bool, std::string > movePrim(int64_t stageId, const std::string &targetPath, const std::string &destinationPath)
Moves a prim from one path to another within the same stage.
- int64_t openStage(const std::string &usdPath)
Opens a USD stage from a URL.
- bool removeApi(int64_t stageId, const std::string &path, const std::string &schemaType, const std::optional< std::string > &instanceName=std::nullopt)
Removes an applied API schema from a prim.
- bool removePrim(int64_t stageId, const std::string &path)
Removes a prim and all of its descendants from the stage.
- bool removePrimAttribute(int64_t stageId, const std::string &path, const std::string &attributeName)
Removes an attribute from a prim.
- void resetXformOpProperties(int64_t stageId, const std::string &path)
Ensures a prim has the canonical transform ops order [xformOp:translate, xformOp:orient, xformOp:scale].
- bool saveStage(int64_t stageId, const std::string &usdPath)
Saves a stage to a USD file.
- std::vector< bool > setPrimAttributeValues(int64_t stageId, const std::vector< std::string > &paths, const std::string &attributeName, const AttributeValues &values)
Writes an attribute's value to multiple prims in a single call.
- void setStageTimeCode(int64_t stageId, std::optional< float > startTimeCode=std::nullopt, std::optional< float > endTimeCode=std::nullopt, std::optional< float > timeCodesPerSecond=std::nullopt)
Sets the stage's time code range and rate.
- void setStageUnits(int64_t stageId, std::optional< float > metersPerUnit=std::nullopt, std::optional< float > kilogramsPerUnit=std::nullopt)
Sets the stage's physical unit scale factors.
- void setStageUpAxis(int64_t stageId, const std::string &upAxis)
Sets the stage's up-axis.
- void setVariants(int64_t stageId, const std::string &path, const std::unordered_map< std::string, std::vector< std::string > > &variants)
Sets variant selections on a prim's variant sets.
- void setXformLocalPoses(int64_t stageId, const std::vector< std::string > &paths, const std::optional< array::Array > &translations=std::nullopt, const std::optional< array::Array > &orientations=std::nullopt)
Sets the local poses of the given Xformable prims.
- void setXformLocalScales(int64_t stageId, const std::vector< std::string > &paths, const array::Array &scales)
Sets the local scales of the given Xformable prims.
- void setXformWorldPoses(int64_t stageId, const std::vector< std::string > &paths, const std::optional< array::Array > &positions=std::nullopt, const std::optional< array::Array > &orientations=std::nullopt)
Sets the world poses of the given Xformable prims.
- void traversePrim(int64_t stageId, const std::string &path, std::function< bool(const std::string &)> callback)
Traverses the prim subtree rooted at
path, invokingcallbackfor each prim.
Typedefs Summary#
- AttributeValues
Holds attribute values as strings, nested string arrays, or a typed numeric array.