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").
Path search#
findMatchingPrimPaths matches a literal path or regex pattern against prims
on the active stage:
// All descendants of /World/Robot
std::vector<std::string> paths =
findMatchingPrimPaths("/World/Robot", /*traverse=*/true);
// Prims whose path matches a pattern, segment by segment
std::vector<std::string> matches =
findMatchingPrimPaths(".*Cube.*", /*traverse=*/false);
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
pathfor whichpredicatereturnstrue.- 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
pathfor whichpredicatereturnstrue.- std::optional< std::string > getFirstMatchingParentPrim(const std::string &path, std::function< bool(const std::string &)> predicate, bool includeSelf=false)
Returns the first ancestor of
pathfor whichpredicatereturnstrue.- 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.