Python guide and API reference#
Summary#
Backend#
Provides a context manager that activates a named backend for the current thread and restores the previous state on exit.
- isaacsim.foundation.utils.backend.use_backend(
- backend: str,
- *,
- raise_on_unsupported: bool = False,
- raise_on_fallback: bool = False,
Context manager that sets a thread-local backend value.
- Parameters:
backend – The value to set in the context.
raise_on_unsupported – Whether to raise an exception if the backend is not supported when requested.
raise_on_fallback – Whether to raise an exception if the backend is supported, but a fallback is being used at a particular point in time when requested.
Example:
>>> import isaacsim.foundation.utils.backend as backend_utils >>> >>> with backend_utils.use_backend("usd"): ... # operate on the specified backend ... pass >>> # operate on the default backend
- isaacsim.foundation.utils.backend.get_current_backend(
- supported_backends: list[str],
- *,
- raise_on_unsupported: bool | None = None,
Get the current backend value if it exists.
- Parameters:
supported_backends – The list of supported backends.
raise_on_unsupported – Whether to raise an error if the backend is not supported when requested. If set to a value other than
None, this parameter has precedence over the context value.
- Returns:
The current backend value or the default value (first supported backend) if no backend is active.
- isaacsim.foundation.utils.backend.is_backend_set() bool#
Check whether a backend is active on the calling thread.
- Returns:
Whether a thread-local backend is active.
- isaacsim.foundation.utils.backend.should_raise_on_unsupported() bool#
Check whether the active backend context rejects unsupported backends.
- Returns:
Whether unsupported backends should raise an exception.
- isaacsim.foundation.utils.backend.should_raise_on_fallback() bool#
Check whether the active backend context rejects fallback backends.
- Returns:
Whether use of a fallback backend should raise an exception.
Stage#
Utilities for managing the process-wide default stage and the thread-local active stage used by prim and semantics functions.
- isaacsim.foundation.utils.stage.set_default_stage(stage: isaacsim.foundation.objects.Stage) None#
Set the process-wide default stage.
- Parameters:
stage – Valid stage to use when the calling thread has no active-stage override.
- Raises:
RuntimeError – If
stageis invalid.
- isaacsim.foundation.utils.stage.get_default_stage() isaacsim.foundation.objects.Stage#
Get the process-wide default stage.
- Returns:
Current default stage.
- Raises:
RuntimeError – If no default stage has been set.
- isaacsim.foundation.utils.stage.get_active_stage() isaacsim.foundation.objects.Stage#
Get the active stage for the calling thread.
Return the thread-local override when it is valid, or the process-wide default stage otherwise.
- Returns:
Active stage.
- Raises:
RuntimeError – If neither a valid thread-local stage nor a default stage exists.
- isaacsim.foundation.utils.stage.use_stage(
- stage: Stage,
Context manager that temporarily overrides the thread-local active stage.
- Parameters:
stage – The stage to activate for the duration of the context.
Example:
>>> import isaacsim.foundation.utils.stage as stage_utils >>> >>> with stage_utils.use_stage(some_stage): ... # active stage is `some_stage` on this thread ... active_stage = stage_utils.get_active_stage() ... >>> # previous active stage is restored
Prim#
All prim functions operate on the active stage returned by
get_active_stage (thread-local override via use_stage, falling back
to the process-wide default set by set_default_stage).
Paths are absolute USD path strings (e.g. "/World/Cube").
- isaacsim.foundation.utils.prim.find_matching_prim_paths(
- path: str,
- *,
- traverse: bool = False,
Find prim paths on the active stage that match a path expression.
For a literal path,
traverseincludes descendants. For a pattern,traversechooses between matching each path segment level by level and matching the complete expression against every prim path.- Parameters:
path – Literal USD prim path or regular-expression pattern.
traverse – Whether to traverse descendants for a literal path or match a pattern against the full stage.
- Returns:
Matching prim paths in stage traversal order.
- Raises:
RuntimeError – If no active or default stage is available.
- isaacsim.foundation.utils.prim.get_all_matching_child_prims(
- path: str,
- *,
- predicate: collections.abc.Callable[[str], bool],
- include_self: bool = False,
- max_depth: int | None = None,
Get all matching prims in a subtree using breadth-first traversal.
The predicate is called synchronously with each visited prim path. Depth is measured from
patheven when the root is excluded.- Parameters:
path – USD path of the subtree root on the active stage.
predicate – Callable that returns whether to include a visited prim path.
include_self – Whether to test the subtree root.
max_depth – Maximum depth to visit relative to the root, or
Nonefor unlimited traversal.
- Returns:
Matching prim paths in breadth-first order.
- Raises:
RuntimeError – If no active or default stage is available.
- isaacsim.foundation.utils.prim.get_first_matching_child_prim(
- path: str,
- *,
- predicate: collections.abc.Callable[[str], bool],
- include_self: bool = False,
- max_depth: int | None = None,
Get the first matching prim in a subtree using breadth-first traversal.
The predicate is called synchronously with each visited prim path. Depth is measured from
patheven when the root is excluded.- Parameters:
path – USD path of the subtree root on the active stage.
predicate – Callable that returns whether to select a visited prim path.
include_self – Whether to test the subtree root first.
max_depth – Maximum depth to visit relative to the root, or
Nonefor unlimited traversal.
- Returns:
First matching prim path, or
Noneif no prim matches.- Raises:
RuntimeError – If no active or default stage is available.
- isaacsim.foundation.utils.prim.get_first_matching_parent_prim(
- path: str,
- *,
- predicate: collections.abc.Callable[[str], bool],
- include_self: bool = False,
Get the first matching ancestor of a prim.
Walk toward the stage pseudoroot and call the predicate synchronously for each visited path. The pseudoroot is not tested or returned.
- Parameters:
path – USD prim path whose ancestors to search on the active stage.
predicate – Callable that returns whether to select a visited prim path.
include_self – Whether to test
pathbefore its ancestors.
- Returns:
First matching prim path, or
Noneif no ancestor matches.- Raises:
RuntimeError – If no active or default stage is available.
Semantics#
Semantic labels are stored under SemanticsLabelsAPI keyed by taxonomy
(default: "class").
- isaacsim.foundation.utils.semantics.add_labels(
- path: str,
- *,
- labels: str | collections.abc.Sequence[str],
- taxonomy: str = 'class',
Add unique semantic labels to a prim under a taxonomy.
Apply the semantic-label schema when needed and preserve existing labels. Descendants are not modified.
- Parameters:
path – USD path of the target prim on the active stage.
labels – Label or labels to add.
taxonomy – Taxonomy under which to store the labels.
- Raises:
RuntimeError – If no active or default stage is available.
- isaacsim.foundation.utils.semantics.get_labels(
- path: str,
- *,
- include_descendants: bool = False,
Get semantic labels grouped by taxonomy.
When descendants are included, concatenate their labels in traversal order; labels repeated across prims remain in the result.
- Parameters:
path – USD path of the target prim on the active stage.
include_descendants – Whether to aggregate labels from the complete subtree.
- Returns:
Taxonomy names mapped to their ordered label lists.
- Raises:
RuntimeError – If no active or default stage is available.
- isaacsim.foundation.utils.semantics.remove_labels(
- path: str,
- *,
- labels: str | collections.abc.Sequence[str],
- taxonomy: str | None = None,
- include_descendants: bool = False,
Remove selected semantic labels from a prim or subtree.
Keep semantic taxonomy schemas applied even when their label lists become empty.
- Parameters:
path – USD path of the target prim on the active stage.
labels – Label or labels to remove.
taxonomy – Taxonomy to modify, or
Noneto modify every taxonomy.include_descendants – Whether to apply the removal to the complete subtree.
- Raises:
RuntimeError – If no active or default stage is available.
- isaacsim.foundation.utils.semantics.remove_all_labels(
- path: str,
- *,
- remove_taxonomies: bool = False,
- include_descendants: bool = False,
Remove all semantic labels from a prim or subtree.
- Parameters:
path – USD path of the target prim on the active stage.
remove_taxonomies – Whether to remove semantic taxonomy schemas as well as their labels.
include_descendants – Whether to apply the removal to the complete subtree.
- Raises:
RuntimeError – If no active or default stage is available.