UsdContext

class omni.usd.UsdContext

Bases: pybind11_object

UsdContext is the container for a PXR_NS::UsdStage that manages the lifecycle of a UsdStage instance. Because of historical reasons, UsdContext also undertakes extra responsibilities, including managing Hydra Engines selections, and etc.

Methods

__init__(*args, **kwargs)
attach_stage_async(stage)	Asynchronous version of omni.usd.UsdContext.attach_stage_with_callback().
attach_stage_with_callback(self, stage_id[, ...])	Attaches an existing stage asynchronously.
can_close_stage(self)	Whether the current stage can be closed or not.
can_open_stage(self)	Whether a new stage can be opened or not.
can_save_stage(self)	Whether the current stage can be saved or not.
close_stage(self[, on_finish_fn])	Closes the current stage synchronously.
close_stage_async()	Asynchronous version of omni.usd.UsdContext.close_stage_with_callback().
close_stage_with_callback(self, on_finish_fn)	Closes the current stage asynchronously.
compute_path_world_bounding_box(self, arg0)	Compute world bound box for specified prim.
compute_path_world_transform(self, arg0)	Compute world transform for specified prim.
disable_save_to_recent_files(self)	Disable save to recent files for opened stage url.
enable_save_to_recent_files(self)	Enable save to rencet files for opened stage url.
export_as_stage(self, url[, on_finish_fn])	Export stage with all prims flattened synchronously, and it will include contents from session layer also.
export_as_stage_async(url)	Asynchronous version of omni.usd.UsdContext.export_as_stage_with_callback().
export_as_stage_with_callback(self, url, ...)	Export stage with all prims flattened asynchronously, and it will include contents from session layer also.
get_attached_hydra_engine_names(self)	Gets the attached hydra engine names to the UsdContext.
get_geometry_instance_path(self, arg0)	Gets the geometry instance path with instance id.
get_name(self)	Gets the name of the context.
get_rendering_event_stream(self)	Gets the rendering event stream.
get_selection(self)	Gets the selection interface.
get_stage()	Gets current opened pxr.Usd.Stage
get_stage_audio_manager(self)	Internal.
get_stage_event_stream(self)	Gets the stage event stream.
get_stage_id(self)	Gets the UsdStage Id that can be queried with Usd.StageCache.
get_stage_loading_status(self)	Gets the stage loading status.
get_stage_state(self)	Gets the current stage state.
get_stage_streaming_status(self)	Gets the status of all stage streaming systems.
get_stage_url(self)	Gets the Stage url.
get_timeline(self)	Gets the timeline interface.
get_timeline_name(self)	Gets current timeline used in this context.
has_pending_edit(self)	Whether it has unsaved edits or not.
is_new_stage(self)	Whether the current stage (root layer) is anonymous or not.
is_omni_stage(self)	Whether the URL of the current stage (root layer) is prefixed with 'omniverse:'.
is_writable(self)	Whether the current stage is writable or not
load_mdl_parameters_for_prim_async(prim[, ...])
load_render_settings_from_stage(self, arg0)	Loads render settings from stage.
new_stage([load_set])
new_stage_async([load_set])	Asynchronous version of omni.usd.UsdContext.new_stage_with_callback().
new_stage_with_callback([fn, load_set])	Asynchronous version of omni.usd.UsdContext.new_stage() that supports to customize load set of new stage.
next_frame_async([inViewportId])	Wait for frame complete event from Kit for specific viewport.
next_stage_event_async()	Wait for next stage event of omni.usd.
next_usd_async([inViewportId])	Wait for frame complete event from Kit for specific viewport.
open_stage(self, url, on_finish_fn, str], ...)	Opens a stage synchronously.
open_stage_async(url[, load_set, ...])	Asynchronous version of omni.usd.UsdContext.open_stage_with_callback().
open_stage_with_callback(self, url, ...)	Opens a stage asynchronously.
open_stage_with_session_layer(self, url, ...)	Opens a stage asynchronously with specified session layer.
register_selection_group(self)	Registers a selection group.
remove_all_hydra_engines(self)	Detach all attached hydra engines from the UsdContext.
reopen_stage(self, on_finish_fn, str], ...)	Re-opens the current stage synchronously.
reopen_stage_async([load_set])	Asynchronous version of omni.usd.UsdContext.reopen_stage_with_callback().
reopen_stage_with_callback(self, ...)	Re-opens the current stage asynchronously.
reset_renderer_accumulation(self)	Resets all accumulation state inside renderers so that rendering n frames after this point is deterministic independent of prior frame-history.
save_as_stage(self, url[, on_finish_fn])	Saves the current stage to another location synchronously.
save_as_stage_async(url)	Asynchronous version of omni.usd.UsdContext.save_as_stage_with_callback().
save_as_stage_with_callback(self, url, ...)	Saves the current stage to another location asynchronously.
save_layers(self, new_root_layer_path, ...)	Saves specified layers (only ones in the local layer stack) synchronously.
save_layers_async(new_root_layer_path, ...)	Asynchronous version of omni.usd.UsdContext.save_layers_with_callback().
save_layers_with_callback(self, ...)	Saves specified layers (only ones in the local layer stack) asynchronously.
save_render_settings_to_current_stage(self)	Saves render settings into the current stage.
save_stage(self[, on_finish_fn])	Saves the current stage (only layers in the local layer stack) synchronously.
save_stage_async()	Asynchronous version of omni.usd.UsdContext.save_stage_with_callback().
save_stage_with_callback(self, on_finish_fn)	Saves the current stage asynchronously.
selection_changed_async()	Wait for selection to be changed.
set_pending_edit(self, arg0)	Set or clear the stage dirtiness state manually no matter if it has pending edits to save.
set_pickable(self, arg0, arg1)	Sets the pickable state for a prim.
set_selection_group(self, groupId, path)	Assigns the prim to specified selection group.
set_selection_group_outline_color(self, ...)	Sets the outline color of the selection group.
set_selection_group_shade_color(self, ...)	Sets the shade color of the selection group.
set_timeline(self[, name])	Sets the timeline for this context.
try_cancel_save(self)	Try to cancel the saving process.

__init__(*args, **kwargs)

async attach_stage_async(stage: Stage) → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.attach_stage_with_callback(). Attaches an opened stage to the context.

Parameters

stage (pxr.Usd.Stage) – The instance of UsdStage.

Returns

A tuple where the first element tells whether the operation is successful or not, and

the second one tells the error message if the operation is failed.

Return type

(bool, str)

attach_stage_with_callback(self: omni.usd._usd.UsdContext, stage_id: int, on_finish_fn: Callable[[bool, str], None] = None) → bool

Attaches an existing stage asynchronously.

Parameters

• stage_id (long int) – The stage id that can be queried with pxr.UsdUtils.StageCache.Get().Find.

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

can_close_stage(self: omni.usd._usd.UsdContext) → bool

Whether the current stage can be closed or not.

can_open_stage(self: omni.usd._usd.UsdContext) → bool

Whether a new stage can be opened or not.

can_save_stage(self: omni.usd._usd.UsdContext) → bool

Whether the current stage can be saved or not.

close_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None] = None) → bool

Closes the current stage synchronously.

Parameters

on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

Returns

Successful or not.

async close_stage_async() → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.close_stage_with_callback(). Closes the current stage.

Returns

A tuple where the first element tells whether the operation is successful or not, and

the second one tells the error message if the operation is failed.

Return type

(bool, str)

close_stage_with_callback(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None]) → bool

Closes the current stage asynchronously.

Parameters

on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

compute_path_world_bounding_box(self: omni.usd._usd.UsdContext, arg0: str) → Tuple[carb::Double3, carb::Double3]

Compute world bound box for specified prim. Unlike using USD API directly, it speeds up bound box computation with cache or Fabric when it’s enabled.

compute_path_world_transform(self: omni.usd._usd.UsdContext, arg0: str) → Annotated[List[float], FixedSize(16)]

Compute world transform for specified prim. Unlike using USD API directly, it speeds up transform computation with cache.

disable_save_to_recent_files(self: omni.usd._usd.UsdContext) → None

Disable save to recent files for opened stage url.

enable_save_to_recent_files(self: omni.usd._usd.UsdContext) → None

Enable save to rencet files for opened stage url.

export_as_stage(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None] = None) → bool

Export stage with all prims flattened synchronously, and it will include contents from session layer also.

Parameters

• url (str) – New location to save the exported stage.

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

Returns

Successful or not.

async export_as_stage_async(url: str) → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.export_as_stage_with_callback(). Flattens and exports the current stage.

Returns

A tuple where the first element tells whether the operation is successful or not, and

the second one tells the error message if the operation is failed.

Return type

(bool, str)

export_as_stage_with_callback(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None]) → bool

Export stage with all prims flattened asynchronously, and it will include contents from session layer also.

Parameters

• url (str) – New location to save the exported stage.

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

get_attached_hydra_engine_names(self: omni.usd._usd.UsdContext) → List[str]

Gets the attached hydra engine names to the UsdContext.

get_geometry_instance_path(self: omni.usd._usd.UsdContext, arg0: int) → str

Gets the geometry instance path with instance id.

get_name(self: omni.usd._usd.UsdContext) → str

Gets the name of the context.

get_rendering_event_stream(self: omni.usd._usd.UsdContext) → carb::events::IEventStream

Gets the rendering event stream. See StageRenderingEventType for more details.

get_selection(self: omni.usd._usd.UsdContext) → omni::usd::Selection

Gets the selection interface. See Selection for more details.

get_stage()

Gets current opened pxr.Usd.Stage

get_stage_audio_manager(self: omni.usd._usd.UsdContext) → omni.usd._usd.AudioManager

Internal. Gets audio manager handle. See omni.usd.audio for wrapped python interfaces that manage audio play/capture.

get_stage_event_stream(self: omni.usd._usd.UsdContext) → carb::events::IEventStream

Gets the stage event stream. See StageEventType for more details.

get_stage_id(self: omni.usd._usd.UsdContext) → int

Gets the UsdStage Id that can be queried with Usd.StageCache.

get_stage_loading_status(self: omni.usd._usd.UsdContext) → Tuple[str, int, int]

Gets the stage loading status.

Returns

A tuple that the first element tells the current loading message, the second element tells how many files are loaded already, and the third one tells the total files to be loaded.

Return type

(str, int, int)

get_stage_state(self: omni.usd._usd.UsdContext) → omni.usd._usd.StageState

Gets the current stage state. See StageState for more details.

get_stage_streaming_status(self: omni.usd._usd.UsdContext) → bool

Gets the status of all stage streaming systems. :returns: whether any of the streaming systems is busy. :rtype: bool

get_stage_url(self: omni.usd._usd.UsdContext) → str

Gets the Stage url. The URL can be used as layer identifier to query layer handle from USD Layer Registry.

get_timeline(self: omni.usd._usd.UsdContext) → omni::timeline::TimelineWrapper

Gets the timeline interface. See omni.timeline for more details.

get_timeline_name(self: omni.usd._usd.UsdContext) → str

Gets current timeline used in this context.

has_pending_edit(self: omni.usd._usd.UsdContext) → bool

Whether it has unsaved edits or not.

is_new_stage(self: omni.usd._usd.UsdContext) → bool

Whether the current stage (root layer) is anonymous or not.

is_omni_stage(self: omni.usd._usd.UsdContext) → bool

Whether the URL of the current stage (root layer) is prefixed with ‘omniverse:’.

is_writable(self: omni.usd._usd.UsdContext) → bool

Whether the current stage is writable or not

load_render_settings_from_stage(self: omni.usd._usd.UsdContext, arg0: int) → None

Loads render settings from stage.

async new_stage_async(load_set: ~omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.new_stage_with_callback(). Creates a new stage with anonymous root layer.

Parameters

load_set (omni.usd.UsdContextInitialLoadSet) – Whether it should open stage with payloads loaded or not. By default, it loads all payloads.

Returns

A tuple where the first element tells whether the operation is successful or not, and

the second one tells the error message if the operation is failed.

Return type

(bool, str)

new_stage_with_callback(fn=None, load_set: ~omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>)

Asynchronous version of omni.usd.UsdContext.new_stage() that supports to customize load set of new stage.

async next_frame_async(inViewportId=0) → None

Wait for frame complete event from Kit for specific viewport.

async next_stage_event_async() → Tuple[StageEventType, Dict[Any, Any]]

Wait for next stage event of omni.usd.

async next_usd_async(inViewportId=0) → None

Wait for frame complete event from Kit for specific viewport.

open_stage(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None] = None, load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → bool

Opens a stage synchronously.

Parameters

• url (str) – The stage URL that can be resolved.

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

• load_set (omni.usd.UsdContextInitialLoadSet) – Whether it should open stage with payloads loaded or not. By default, it loads all payloads.

Returns

Successful or not.

async open_stage_async(url: str, load_set: ~omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>, session_layer_url: ~typing.Optional[str] = None) → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.open_stage_with_callback(). Opens a new stage.

Parameters

• url (str) – Stage URL to open.

• load_set (omni.usd.UsdContextInitialLoadSet) – If it’s to open all payloads or none.

• session_layer_url (str) – Specified session layer.

Returns

A tuple where the first element tells whether the operation is successful or not, and

the second one tells the error message if the operation is failed.

Return type

(bool, str)

open_stage_with_callback(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str], None], load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → bool

Opens a stage asynchronously.

Parameters

• url (str) – The stage URL that can be resolved.

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

• load_set (omni.usd.UsdContextInitialLoadSet) – Whether it should open stage with payloads loaded or not. By default, it loads all payloads.

open_stage_with_session_layer(self: omni.usd._usd.UsdContext, url: str, session_layer_url: str, on_finish_fn: Callable[[bool, str], None], load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → bool

Opens a stage asynchronously with specified session layer.

Parameters

• url (str) – The stage URL that can be resolved.

• session_layer_url (str) – The specified session layer URL.

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

• load_set (omni.usd.UsdContextInitialLoadSet) – Whether it should open stage with payloads loaded or not. By default, it loads all payloads.

register_selection_group(self: omni.usd._usd.UsdContext) → int

Registers a selection group. Prims can be assigned to selection group with customized outline colors than the default. It supports 255 selection groups at most.

remove_all_hydra_engines(self: omni.usd._usd.UsdContext) → None

Detach all attached hydra engines from the UsdContext.

reopen_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None] = None, load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → bool

Re-opens the current stage synchronously.

Parameters

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

• load_set (omni.usd.UsdContextInitialLoadSet) – Whether it should open stage with payloads loaded or not. By default, it loads all payloads.

Returns

Successful or not.

async reopen_stage_async(load_set: ~omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.reopen_stage_with_callback(). Re-opens the current stage.

Parameters

load_set (omni.usd.UsdContextInitialLoadSet) – If it’s to open all payloads or none.

Returns

A tuple where the first element tells whether the operation is successful or not, and

the second one tells the error message if the operation is failed.

Return type

(bool, str)

reopen_stage_with_callback(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str], None], load_set: omni.usd._usd.UsdContextInitialLoadSet = <UsdContextInitialLoadSet.LOAD_ALL: 0>) → bool

Re-opens the current stage asynchronously.

Parameters

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

• load_set (omni.usd.UsdContextInitialLoadSet) – Whether it should open stage with payloads loaded or not. By default, it loads all payloads.

reset_renderer_accumulation(self: omni.usd._usd.UsdContext) → None

Resets all accumulation state inside renderers so that rendering n frames after this point is deterministic independent of prior frame-history.

save_as_stage(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str, List[str]], None] = None) → bool

Saves the current stage to another location synchronously.

Parameters

• url (str) – New location to save the current stage.

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

Returns

Successful or not.

async save_as_stage_async(url: str) → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.save_as_stage_with_callback(). Saves the current stage to a new location.

Parameters

url (str) – New location to save the current stage.

Returns

A tuple where the first element tells whether the operation is successful or not, and

the second one tells the error message if the operation is failed.

Return type

(bool, str)

save_as_stage_with_callback(self: omni.usd._usd.UsdContext, url: str, on_finish_fn: Callable[[bool, str, List[str]], None]) → bool

Saves the current stage to another location asynchronously.

Parameters

• url (str) – New location to save the current stage.

• on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

save_layers(self: omni.usd._usd.UsdContext, new_root_layer_path: str, layer_identifiers: List[str], on_finish_fn: Callable[[bool, str, List[str]], None] = None) → bool

Saves specified layers (only ones in the local layer stack) synchronously.

Parameters

• new_root_layer_path (str) – New location for root layer if it’s to save-as the current stage. If it’s empty, it will save specified layers only.

• layer_identifiers (List[str]) – List of layer identifiers to be saved.

• on_finish_fn (Callable[[bool, str, List[str]], None]) – Finish callback that the first param is to tell if the operation is successful, the second one tells the error message if it’s faled and the third param is the list of layer identifiers that are saved successfully.

Returns

Successful or not.

async save_layers_async(new_root_layer_path: str, layer_identifiers: List[str]) → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.save_layers_with_callback(). Saves specified layers.

Parameters

• new_root_layer_path (str) – New location for root layer if it’s to save-as the current stage. If it’s empty, it will save specified layers only.

• layer_identifiers (List[str]) – List of layer identifiers to be saved.

Returns

A tuple where the first element tells whether the operation is successful or not, the second one tells the error message if it’s faled and

the third param is the list of layer identifiers that are saved successfully.

Return type

(bool, str, List[str])

save_layers_with_callback(self: omni.usd._usd.UsdContext, new_root_layer_path: str, layer_identifiers: List[str], on_finish_fn: Callable[[bool, str, List[str]], None]) → bool

Saves specified layers (only ones in the local layer stack) asynchronously.

Parameters

• new_root_layer_path (str) – New location for root layer if it’s to save-as the current stage. If it’s empty, it will save specified layers only.

• layer_identifiers (List[str]) – List of layer identifiers to be saved.

• on_finish_fn (Callable[[bool, str, List[str]], None]) – Finish callback that the first param is to tell if the operation is successful, the second one tells the error message if it’s faled and the third param is the list of layer identifiers that are saved successfully.

save_render_settings_to_current_stage(self: omni.usd._usd.UsdContext) → None

Saves render settings into the current stage. Render settings will be serialized into the custom layer data of root layer.

save_stage(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str, List[str]], None] = None) → bool

Saves the current stage (only layers in the local layer stack) synchronously.

Parameters

on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

Returns

Successful or not.

async save_stage_async() → Tuple[bool, str]

Asynchronous version of omni.usd.UsdContext.save_stage_with_callback(). Saves the current stage.

Returns

A tuple where the first element tells whether the operation is successful or not, and

the second one tells the error message if the operation is failed.

Return type

(bool, str)

save_stage_with_callback(self: omni.usd._usd.UsdContext, on_finish_fn: Callable[[bool, str, List[str]], None]) → bool

Saves the current stage asynchronously.

Parameters

on_finish_fn (Callable[[bool, str], None]) – Finish callback that the first param is to tell if the operation is successful, and the second one tells the error message if it’s faled.

async selection_changed_async() → List[str]

Wait for selection to be changed. Return a list of newly selected paths.

set_pending_edit(self: omni.usd._usd.UsdContext, arg0: bool) → None

Set or clear the stage dirtiness state manually no matter if it has pending edits to save.

set_pickable(self: omni.usd._usd.UsdContext, arg0: str, arg1: bool) → None

Sets the pickable state for a prim.

set_selection_group(self: omni.usd._usd.UsdContext, groupId: int, path: str) → None

Assigns the prim to specified selection group.

set_selection_group_outline_color(self: omni.usd._usd.UsdContext, groupId: int, color: carb::Float4) → None

Sets the outline color of the selection group.

set_selection_group_shade_color(self: omni.usd._usd.UsdContext, groupId: int, color: carb::Float4) → None

Sets the shade color of the selection group.

set_timeline(self: omni.usd._usd.UsdContext, name: str = '') → None

Sets the timeline for this context.

try_cancel_save(self: omni.usd._usd.UsdContext) → None

Try to cancel the saving process. It only take effects when it’s called immediately after receiving event StageEventType::eSaving or StageEventType::eSettingsSaving.