Viewport Overlays

Viewport Overlays are specialized UI elements drawn directly on top of the 3D scene. They provide spatial context that would be lost in a traditional side panel, such as measurement labels floating over a point cloud, interactive legends, or custom handles (gizmos) for manipulating 3D objects.

Interactive 3D Interfaces

Unlike standard windows, an overlay is aware of the 3D world. It can be positioned relative to the screen (e.g., a “Tools Help” box in the bottom-right corner) or pinned to specific coordinates in the 3D world. This makes them the primary tool for building intuitive, spatially-aware interfaces.

The lifetime of an overlay is typically tied to the active Tool. When you activate a tool, the SDK automatically initializes its associated overlays; when the tool is closed, those overlays are cleaned up, ensuring the viewport remains uncluttered for the next task.

Communication Flow: Overlay to Tool

One of the most powerful uses of an overlay is capturing user intent within the 3D scene. For example, if you are building a “Wall Placement” tool, your overlay can detect where the user clicks in the viewport and send that coordinate back to the tool’s main logic.

This communication happens asynchronously:

1. The Overlay detects an action, such as a mouse click or a change to an on-screen slider.
2. The Overlay sends a message through the provided ViewportOverlayCtx.
3. The Tool receives this message in its asynchronous run method, allowing it to commit a Statement and update the project state.