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);

Authoring prims#

// Define a prim, creating ancestor Xform prims as needed.
definePrim(stageId, "/World/Prim", "Xform");

// Move a prim to a new path.
auto [ok, error] = movePrim(stageId, "/World/OldName", "/World/NewName");

// Remove a prim and all its descendants.
bool removed = removePrim(stageId, "/World/Prim");

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 path exists 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 , invoking callback for each prim.

Typedefs Summary#

AttributeValues

Holds attribute values as strings, nested string arrays, or a typed numeric array.