Overview#

The omni.kit.waypoint.core extension provides a robust set of APIs for managing waypoint data within a USD stage. It defines interfaces to create, edit, rename, delete, and recall waypoints while integrating viewport configurations and UI elements. The extension enables developers to register callbacks for waypoint changes and exposes both synchronous and asynchronous methods for waypoint creation.

Concepts#

Waypoint Lifecycle The extension encapsulates the complete lifecycle of a waypoint—from creation to recall—using the central Waypoint class. It manages changes through registered callbacks via the WaypointChangeCallbacks API and synchronizes viewport icon display with user settings.
Viewport Integration Through the ViewportWaypoint API, waypoint data can be tied to viewport settings such as camera state and thumbnail generation. This supports operations like recalling a waypoint to adjust the viewport without necessarily updating the camera.

Functionality#

Management APIs Developers can create waypoints either synchronously with create_waypoint or asynchronously with create_waypoint_async. Methods to begin and end the editing of waypoints (begin_edit_waypoint and end_edit_waypoint) allow for safe modifications, while recalling a waypoint applies its stored viewport configuration.
Editing and Callbacks The API supports registering and deregistering waypoint change callbacks so that any creation, deletion, or modifications are communicated to other parts of the application. Additionally, renaming and deleting operations ensure that the underlying USD prim paths remain consistent.
User Interface Support The extension provides several UI components, such as WaypointBrowserWidget for listing available waypoints, and WaypointListWindow for managing waypoint entries. The WaypointDelegate and WaypointItemEditWidget further support customized editing and context menu interactions.

Key Components#

Waypoint and ViewportWaypoint The core Waypoint class offers methods to manage waypoint state and synchronization with USD stage events. In contrast, the ViewportWaypoint class focuses on managing viewport-related settings such as thumbnail data, camera prim references, and edit contexts.
WaypointCard Acting as a visual representation derived from the playlist system, WaypointCard retrieves waypoint data from the extension instance and provides interactive methods (active and clean) for recalling waypoints.
Browser and List Widgets The WaypointModel and WaypointItem classes offer structured data for representing waypoints in a browser context. The WaypointBrowserWidget and WaypointListWindow provide UIs for browsing, editing, and selecting waypoints, including support for click, hover, and context menu actions.
Editing and Delegation The WaypointItemEditWidget enables in-place editing of waypoint details, while the WaypointDelegate implements display logic to generate labels and thumbnails, as well as manage interactions through right-click and hover events.
Integration with Other Extensions The extension leverages existing APIs such as those in omni.kit.playlist.core (which is utilized by WaypointCard) and omni.kit.browser.core (supporting the structured browser model). This ensures that waypoint data is presented consistently with other stage-related tools within the USD environment.

Overall, omni.kit.waypoint.core delivers a set of precise, interoperable APIs that simplify managing waypoint information and integrating it with viewport settings and UI elements. Its design enables both programmatic control and interactive editing of waypoints, offering flexibility in how scene locations and configurations are saved and recalled.