Waypoint#

class omni.kit.waypoint.core.Waypoint#

Bases: object

A class to manage waypoints in the USD stage.

This class provides APIs for creating, editing, renaming, deleting, and recalling waypoints. It handles the registration of callbacks to notify consumers when a waypoint is created, changed, or deleted. In addition, it manages viewport icons and integrates with user settings to control the visibility and behavior of waypoint indicators.

Public methods allow you to create new waypoints either synchronously or asynchronously, begin and end editing of existing waypoints, and recall a waypoint to update the viewport state. The class also monitors USD stage events to update or remove waypoints and synchronizes the display of icons based on current settings.

Overall, this class offers a comprehensive interface to manage the lifecycle and presentation of waypoints within the omni.kit.waypoint.core extension.

Methods

`begin_edit_waypoint`(waypoint)	Starts editing the given waypoint if allowed by checking sidecar read-only and current editing status.
`can_edit_waypoint`(waypoint[, show_messages])	Checks whether the given waypoint can be edited.
`create_waypoint`([new_waypoint_path, ...])	Creates a new waypoint if no duplicate exists.
`create_waypoint_async`([new_waypoint_path, ...])	Creates a new waypoint asynchronously if no duplicate exists.
`delete_waypoint`(waypoint)	Deletes the specified waypoint if allowed.
`deregister_callback`(notification)	Deregisters a waypoint callback by removing it from the notifications list.
`end_edit_waypoint`(waypoint, save[, create])	Ends editing the provided waypoint.
`get_waypoint`(name)	Retrieves a viewport waypoint based on its name.
`get_waypoint_from_prim_path`(path)	Retrieves a waypoint using its USD prim path.
`get_waypoints`()	Returns all stored viewport waypoints.
`is_waypoint_prim`(prim_path[, exact])	Checks if the given prim_path represents a valid waypoint prim.
`on_shutdown`()	Handles cleanup on shutdown.
`on_startup`(ext_id)	Initializes the Waypoint and registers the related PlaylistCard.
`recall_waypoint`(waypoint[, without_camera, ...])	Recalls a waypoint by restoring its camera settings and timeline position.
`register_callback`(notification)	Registers a waypoint callback by appending it to the notifications list.
`rename_waypoint`(waypoint, new_name)	Renames the specified waypoint if the new name is different, valid as a USD path, and not already used.
`set_main_window_name`(main_window_name)	Sets the main window name.
`set_viewport_widget`(viewport_widget)	Sets the viewport widget.
`show_preference`(x, y)	Displays the preference window at the specified screen coordinates after setting the current tool.
`update_dirty`()	Create/remove dirty items that was collected from TfNotice.

Attributes

`current_waypoint`	Gets the current waypoint.
`edit_context`	Gets the current edit context for waypoint operations.
`edit_target`	Gets the edit_target property.
`editing_waypoint`	Gets the editing_waypoint property.
`hide_in_stage_window_disabled`	Gets the hide_in_stage_window_disabled flag.
`main_window_name`	Gets the main window name.
`viewport_widget`	Gets the viewport widget.

__init__()#

begin_edit_waypoint( waypoint: ViewportWaypoint, ) → bool#

Starts editing the given waypoint if allowed by checking sidecar read-only and current editing status.

Parameters:: waypoint (ViewportWaypoint) – Waypoint instance to begin editing.
Returns:: True if editing starts successfully, False otherwise.
Return type:: bool

can_edit_waypoint( waypoint: ViewportWaypoint, show_messages=True, ) → bool#

Checks whether the given waypoint can be edited. This method always returns True.

Parameters:

waypoint (ViewportWaypoint) – Waypoint instance to check for editability.
show_messages (bool) – Flag to display messages if editing is not permitted.

Returns:

True indicating the waypoint is editable.

Return type:

bool

create_waypoint( new_waypoint_path: str = '', icon_url: str = 'C:\\g\\0\\kit-windows\\_build\\windows-x86_64\\release\\exts\\omni.kit.waypoint.core\\icons/Waypoint_viewport.png', icon_click: callable = None, )#

Creates a new waypoint if no duplicate exists. Determines an available waypoint path and schedules a creation job with a wait prompt.

Parameters:

new_waypoint_path (str) – Base path for new waypoint; default is empty.
icon_url (str) – URL for waypoint icon.
icon_click (callable) – Callback invoked on icon click.

async create_waypoint_async( new_waypoint_path: str = '', icon_url: str = 'C:\\g\\0\\kit-windows\\_build\\windows-x86_64\\release\\exts\\omni.kit.waypoint.core\\icons/Waypoint_viewport.png', icon_click: callable = None, )#

Creates a new waypoint asynchronously if no duplicate exists. Determines an available waypoint path and triggers asynchronous creation with a wait prompt.

Parameters:

new_waypoint_path (str) – Base path for new waypoint; default is empty.
icon_url (str) – URL for waypoint icon.
icon_click (callable) – Callback invoked on icon click.

delete_waypoint( waypoint: ViewportWaypoint | None, ) → None#

Deletes the specified waypoint if allowed. Removes its icon from the display, removes it from the internal storage, and notifies observers about the deletion.

Parameters:: waypoint (Optional[ViewportWaypoint]) – Waypoint instance to delete.

deregister_callback( notification: WaypointChangeCallbacks, ) → None#

Deregisters a waypoint callback by removing it from the notifications list.

Parameters:: notification (WaypointChangeCallbacks) – Callback instance to remove.

end_edit_waypoint( waypoint: ViewportWaypoint, save: bool, create: bool = False, ) → None#

Ends editing the provided waypoint. If the waypoint is not the currently editing one, a warning is logged and the operation is aborted. Within an appropriate edit context, if create is True a new waypoint is created; if save is True, changes are saved; else the waypoint is recalled. Resets the editing waypoint and current tool.

Parameters:

waypoint (ViewportWaypoint) – Waypoint instance that is being edited.
save (bool) – Flag to save modifications.
create (bool) – Flag to create a new waypoint if needed.

get_waypoint( name, ) → ViewportWaypoint | None#

Retrieves a viewport waypoint based on its name.

Parameters:: name (str) – Name of the waypoint to look up.
Returns:: The waypoint instance if found, otherwise None.
Return type:: Optional[ViewportWaypoint]

get_waypoint_from_prim_path( path: str, ) → ViewportWaypoint | None#

Retrieves a waypoint using its USD prim path. Extracts the waypoint name from the path and returns the matching waypoint if it exists.

Parameters:: path (str) – USD prim path used to determine the waypoint.
Returns:: The waypoint instance if found, otherwise None.
Return type:: Optional[ViewportWaypoint]

get_waypoints() → List[ViewportWaypoint]#

Returns all stored viewport waypoints.

Returns:: List of viewport waypoint instances.
Return type:: List[ViewportWaypoint]

is_waypoint_prim(prim_path: str, exact: bool = False) → bool#

Checks if the given prim_path represents a valid waypoint prim. When exact is true, the prim must be an immediate child of the waypoint root.

Parameters:

prim_path (str) – USD prim path to check.
exact (bool) – If true, require prim_path to be a direct child.

Returns:

True if prim_path corresponds to a waypoint prim, otherwise false.

Return type:

bool

on_shutdown()#: Handles cleanup on shutdown. Deregisters the PlaylistCard, hotkeys, and stage updates; unsubscribes from settings change events; destroys the preference window; clears notifications; and resets the current and editing waypoints.

on_startup(ext_id)#

Initializes the Waypoint and registers the related PlaylistCard. Extracts the extension name from ext_id, sets up sidecar data if available, subscribes to settings and stage events, and initializes hotkeys.

Parameters:: ext_id (str) – The current extension id used for initialization.

recall_waypoint( waypoint: ViewportWaypoint | None, without_camera=False, enable_settings: List[str] | None = None, disable_settings: List[str] | None = None, force: bool = False, recall_timeline: bool = True, ) → None#

Recalls a waypoint by restoring its camera settings and timeline position. If the waypoint is already current and force is not set, the recall is skipped.

Parameters:

waypoint (Optional[ViewportWaypoint]) – Waypoint instance to recall.
without_camera (bool) – If True, does not adjust the camera.
enable_settings (Optional[List[str]]) – List of settings to enable during recall.
disable_settings (Optional[List[str]]) – List of settings to disable during recall.
force (bool) – If True, forces the recall even if already current.
recall_timeline (bool) – If True, updates the timeline to the waypoint’s frame.

register_callback( notification: WaypointChangeCallbacks, ) → None#

Registers a waypoint callback by appending it to the notifications list.

Parameters:: notification (WaypointChangeCallbacks) – Callback instance to register.

rename_waypoint( waypoint: ViewportWaypoint, new_name: str, ) → bool#

Renames the specified waypoint if the new name is different, valid as a USD path, and not already used. Updates the waypoint icon and notifies observers on a successful rename.

Parameters:

waypoint (ViewportWaypoint) – Waypoint instance to rename.
new_name (str) – The new name proposed for the waypoint.

Returns:

True if the renaming is successful, False otherwise.

Return type:

bool

set_main_window_name(main_window_name) → None#

Sets the main window name.

Parameters:: main_window_name (object) – The name to be set for the main window.

set_viewport_widget(viewport_widget) → None#

Sets the viewport widget.

Parameters:: viewport_widget (object) – The widget to be used as the viewport.

show_preference(x: float, y: float)#

Displays the preference window at the specified screen coordinates after setting the current tool.

Parameters:

x (float) – The x coordinate for the preference window position.
y (float) – The y coordinate for the preference window position.

update_dirty()#: Create/remove dirty items that was collected from TfNotice. Can be called any time to pump changes.

property current_waypoint: ViewportWaypoint | None#

Gets the current waypoint.

Returns:: The currently active waypoint.
Return type:: Optional[ViewportWaypoint]

property edit_context: EditContext#

Gets the current edit context for waypoint operations. Considers sidecar data and edit target overrides.

Returns:: The effective edit context.
Return type:: Usd.EditContext

property edit_target: Layer#

Gets the edit_target property. Returns the current Sdf.Layer used as the edit target.

Returns:: The current edit target layer.
Return type:: Sdf.Layer

property editing_waypoint: ViewportWaypoint | None#

Gets the editing_waypoint property. Returns the current viewport waypoint being edited.

Returns:: The editing waypoint instance.
Return type:: Optional[ViewportWaypoint]

property hide_in_stage_window_disabled#

Gets the hide_in_stage_window_disabled flag.

Returns:: True if saving of the hide in stage window metadata is disabled.
Return type:: bool

property main_window_name: None#

Gets the main window name.

Returns:: The main window name is stored internally.
Return type:: None

property viewport_widget: None#

Gets the viewport widget.

Returns:: The viewport widget is stored internally.
Return type:: None