C++ guide and API reference#

All declarations live in the isaacsim::foundation::utils namespace.

#include <isaacsim/foundation/utils/Backend.hpp>
#include <isaacsim/foundation/utils/Prim.hpp>
#include <isaacsim/foundation/utils/Semantics.hpp>
#include <isaacsim/foundation/utils/Stage.hpp>

using namespace isaacsim::foundation::utils;

Backend#

BackendGuard activates a named backend for the current thread within a scope and restores the previous context on destruction. Declare it as a named local variable — a temporary is destroyed immediately:

{
    BackendGuard guard("tensor");
    // getCurrentBackend({"usd", "tensor"}) returns "tensor" here
}
// previous backend restored

getCurrentBackend returns the active backend, falling back to the first entry of supportedBackends when none is set or when the active backend is not in the list:

std::string backend = getCurrentBackend({"usd", "tensor"});

bool set = isBackendSet();
bool raiseUnsupported = shouldRaiseOnUnsupported();
bool raiseFallback    = shouldRaiseOnFallback();

Stage#

StageGuard temporarily overrides the thread-local active stage and restores the previous one on destruction. Declare it as a named local variable — a temporary is destroyed immediately:

// Create a new stage (becomes the default automatically)
objects::Stage stage = objects::Stage("ovstage").createStage();

// Manage the process-wide default stage explicitly
setDefaultStage(stage);
objects::Stage defaultStage = getDefaultStage(); // throws if none set

// Temporarily override the thread-local active stage
{
    StageGuard guard(otherStage);
    objects::Stage activeStage = getActiveStage();  // throws if neither is set (default or active)
    findMatchingPrimPaths("/World/Robot", /*traverse=*/true);
}

Prim#

All prim functions operate on the active stage returned by getActiveStage. Paths are absolute USD path strings (e.g. "/World/Cube").

BFS traversal#

getAllMatchingChildPrims collects every prim in a subtree that satisfies a predicate. getFirstMatchingChildPrim stops at the first match:

auto isMesh = [](const std::string& p) { return p.find("Mesh") != std::string::npos; };

std::vector<std::string> meshes =
    getAllMatchingChildPrims("/World", isMesh,
                            /*includeSelf=*/false,
                            /*maxDepth=*/std::nullopt);

std::optional<std::string> first =
    getFirstMatchingChildPrim("/World", isMesh);

getFirstMatchingParentPrim walks up the parent chain and returns the first ancestor that satisfies the predicate:

std::optional<std::string> root =
    getFirstMatchingParentPrim("/World/Robot/Arm/Link",
                               [](const std::string& p) { return p == "/World/Robot"; });

Semantics#

Semantic labels are stored as SemanticsLabelsAPI multiple-apply schemas keyed by taxonomy (default: "class").

// Add labels
addLabels("/World/Cube", "vehicle");
addLabels("/World/Cube", std::vector<std::string>{"vehicle", "car"}, "type");

// Query labels (optionally including descendants)
std::unordered_map<std::string, std::vector<std::string>> labels =
    getLabels("/World/Cube", /*includeDescendants=*/false);
// e.g. { "class": ["vehicle"], "type": ["vehicle", "car"] }

// Remove specific labels
removeLabels("/World/Cube", "vehicle");
removeLabels("/World/Cube", std::vector<std::string>{"vehicle", "car"},
             /*taxonomy=*/"type", /*includeDescendants=*/false);

// Clear all labels; pass removeTaxonomies=true to also unapply the schema
removeAllLabels("/World/Cube", /*removeTaxonomies=*/false,
                /*includeDescendants=*/false);

API reference#

Fully qualified namespace: isaacsim::foundation::utils

namespace utils#

Classes Summary#

BackendGuard

RAII guard that sets the active backend for the current thread within a scope.

StageGuard

RAII guard that temporarily overrides the thread-local active stage.

Functions Summary#

void addLabels(const std::string &path, const std::variant< std::string, std::vector< std::string > > &labels, const std::string &taxonomy="class")

Adds semantic labels to a prim under the given taxonomy.

std::vector< std::string > findMatchingPrimPaths(const std::string &path, bool traverse=false)

Returns all prim paths on the default stage that match the given path expression.

objects::Stage getActiveStage()

Get the active stage for the calling thread.

std::vector< std::string > getAllMatchingChildPrims(const std::string &path, std::function< bool(const std::string &)> predicate, bool includeSelf=false, std::optional< std::size_t > maxDepth=std::nullopt)

Returns all prims in the subtree rooted at path for which predicate returns true .

std::string getCurrentBackend(const std::initializer_list< std::string > &supportedBackends, std::optional< bool > raiseOnUnsupported=std::nullopt)

Returns the currently active backend name for this thread.

std::string getCurrentBackend(const std::vector< std::string > &supportedBackends, std::optional< bool > raiseOnUnsupported=std::nullopt)

Returns the currently active backend name for this thread.

objects::Stage getDefaultStage()

Get the process-wide default stage.

std::optional< std::string > getFirstMatchingChildPrim(const std::string &path, std::function< bool(const std::string &)> predicate, bool includeSelf=false, std::optional< std::size_t > maxDepth=std::nullopt)

Returns the first prim in the subtree rooted at path for which predicate returns true .

std::optional< std::string > getFirstMatchingParentPrim(const std::string &path, std::function< bool(const std::string &)> predicate, bool includeSelf=false)

Returns the first ancestor of path for which predicate returns true .

std::unordered_map< std::string, std::vector< std::string > > getLabels(const std::string &path, bool includeDescendants=false)

Returns all semantic labels on a prim, grouped by taxonomy.

bool isBackendSet()

Checks whether a backend is currently set on this thread.

void removeAllLabels(const std::string &path, bool removeTaxonomies=false, bool includeDescendants=false)

Removes all semantic labels from a prim.

void removeLabels(const std::string &path, const std::variant< std::string, std::vector< std::string > > &labels, const std::optional< std::string > &taxonomy=std::nullopt, bool includeDescendants=false)

Removes specific semantic labels from a prim.

void setDefaultStage(objects::Stage stage)

Set the process-wide default stage.

bool shouldRaiseOnFallback()

Checks whether the current context requests an exception on a fallback backend.

bool shouldRaiseOnUnsupported()

Checks whether the current context requests an exception on an unsupported backend.

Namespaces Summary#