Python guide and API reference#

Use setup() before importing a backend that needs the packaged OVStage runtime directly. get_native_handle() registers a Python stage for later lookup, while as_native_handle() normalizes integer and nanobind capsule representations.

setup()

Make the private OVStage runtime discoverable.

get_native_handle(stage)

Get the native address for a public OVStage object.

as_native_handle(value)

Normalize a native ovstage address from an int or nanobind void* capsule.

lookup_stage(handle)

Look up a Python OVStage previously registered via get_native_handle().

isaacsim.physics_engines.ovstage.setup() → None#

Make the private OVStage runtime discoverable.

Repeated calls are safe. On Linux, each call refreshes the loader hint to select an OVStage library that an engine binding has loaded since the prior call. This function does not import or modify pxr.

Raises:

RuntimeError – If the bundled runtime is missing.

Example:

>>> from isaacsim.physics_engines.ovstage import setup

>>> setup()
isaacsim.physics_engines.ovstage.get_native_handle(stage: object) → int#

Get the native address for a public OVStage object.

Registers stage so lookup_stage() can recover it from the integer handle passed through physics_manager.initialize.

Parameters:

stage – OVStage object whose native address is required by a consumer.

Returns:

Native OVStage address.

Raises:
  • TypeError – If stage is not an OVStage-compatible object.

  • RuntimeError – If the OVStage object has been destroyed.

isaacsim.physics_engines.ovstage.as_native_handle(value: object | None) → int#

Normalize a native ovstage address from an int or nanobind void* capsule.

physics_manager.initialize accepts an int handle, but when the manager invokes a Python SimulationFns.initialize callback the C++ void* is delivered as a nanobind PyCapsule named nb_handle.

Parameters:

value – Native address as int, nanobind PyCapsule, or None/0.

Returns:

Native address as int, or 0 when value is null.

Raises:

TypeError – If value is neither an integer nor a recognized capsule.

isaacsim.physics_engines.ovstage.lookup_stage(handle: object | None) → object | None#

Look up a Python OVStage previously registered via get_native_handle().

Parameters:

handle – Native OVStage address as int or nanobind void* capsule.

Returns:

Owning Python Stage when still alive, otherwise None.