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,
) → Generator[None, None, None]#

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,
) → str#

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 stage is 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,
) → Generator[None, None, None]#

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,
) → list[str]#

Find prim paths on the active stage that match a path expression.

For a literal path, traverse includes descendants. For a pattern, traverse chooses 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,
) → list[str]#

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 path even 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 None for 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,
) → str | 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 path even 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 None for unlimited traversal.

Returns:

First matching prim path, or None if 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,
) → str | None#

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 path before its ancestors.

Returns:

First matching prim path, or None if 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',
) → None#

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,
) → dict[str, list[str]]#

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,
) → None#

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 None to 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,
) → None#

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.