viser

The dock-ux-spec.md file contains the design decisions (D1-D58) governing the behavior of the Dock and Panel system in Viser. It defines how panels dock, collapse, resize, and interact with the layout. Key concepts include:

• Docking Behavior: Side-docking grows the region by the newcomer's width; existing panels do not shrink (D3).
• Collapse & Minimization: Collapse is a container-scoped state (D38). A window is a vertical stack of cells where the header persists even when collapsed (D17). Minimizing a group of stacked panels minimizes them together (D47).
• Rails: A railed column is rendered as a fixed 36px strip (D21, D28). Rails never merge; a packed region consists of N independent strips (D44, D46).
• Layout Model: The system uses a columns-only layout model. Regions are side-by-side full-height columns, each containing a stack of leaves (D46).
• Mobile Support: Below the xs breakpoint, panels render as an accordion of bars in a bottom sheet (D45).
• Resizing & Dividers: Width dividers are inert beside a railed column (D24). Height dividers support content-height snapping (D56).

Viser uses a specific hierarchy of terms to describe the layout and docking system. Understanding these terms is essential for working with the UI structure:

Core Units

• Pane / Panel / Tab: A pane is the atomic unit of content (PaneId/PaneSpec). A panel is the user-facing container (represented by a PanelHandle in Python). A tab is how a pane is presented within a strip.
• Group: An ordered set of one or more panes (tabs) with one active tab. This represents the PANEL scope and does not carry collapse state.
• Area: A nested dockable surface located inside a panel body (a flat tab group without splits).

Layout Containers

• Region: A docked container on the left or right screen edge consisting of one or more columns side by side. Column widths divide the region.
• Column: A full-height vertical stack of one or more cells. Columns carry the docked collapse flag (railed).
• Cell (leaf): A single tab group at a specific dock position.
• Floating window: A free-floating box containing a vertical stack of one or more groups (the STACK scope).

Collapsed States

• Bar: The collapsed rendering of a Floating window (a 26px handle).
• Rail: The collapsed rendering of a Docked column (a 36px vertical strip of spine rows).
• Rail header: The handle atop a rail; used to drag the column into a floating window or to expand it.
• Cap: The collapsed panel handle located inside a rail; used to drag a specific group.

Special Panels

• Main panel: The control panel. It behaves like an ordinary group but is unmergeable and includes a titleNode header (e.g., for connection status).
• Unmergeable panel: A panel that cannot be merged into another group. It renders a full-width header instead of a tab strip.

The Viser Dock system uses a 'correct by construction' model to prevent common layout bugs. Developers should be aware of the following structural constraints:

• Three-level shape: The hierarchy follows DockRegion { columns } $\rightarrow$ DockColumn { children } $\rightarrow$ leaves. Vertical stacking is only permitted inside a column.
• Identity and Types: The system uses distinct, mutually unassignable types for identifiers: PaneId, GroupId, WindowId, NodeId, and AreaId.
• Window Height: Height is defined as either {mode: "auto"} or {mode: "pinned"; px}.
• Float Ownership: Floating elements use an optional anchor: {x; y} object. The presence of this object indicates the element is anchored.
• Tab Groups: TabGroup.activeId can be a PaneId or null (it does not use an empty string sentinel).
• Placement Protocol: Layout is managed via per-axis (counter, runId) stamps. Reconnects are handled via an explicit phase that ends when the server sends a ReplayDoneMessage.

You can create smooth camera animations by interpolating between the current camera pose and a target pose using SE(3) transformations.

1. Calculate the current transformation matrix ($T_{world_current}$) from client.camera.wxyz and client.camera.position.
2. Calculate the target transformation matrix ($T_{world_target}$) based on the target frame's pose.
3. Compute the relative transformation: $T_{current_target} = T_{world_current}^{-1} \times T_{world_target}$.
4. Use tf.SE3.exp(T_current_target.log() * alpha) to interpolate between the two poses over a series of steps.
5. Apply updates within a client.atomic() block to maintain smoothness.

import time
import numpy as np
import viser
import viser.transforms as tf

# ... inside a client callback ...
# T_world_current and T_world_target are pre-calculated SE(3) matrices
T_current_target = T_world_current.inverse() @ T_world_target

for j in range(20):
    # Interpolate using SE(3) exponential map
    T_world_set = T_world_current @ tf.SE3.exp(
        T_current_target.log() * j / 19.0
    )

    with client.atomic():
        client.camera.wxyz = T_world_set.rotation().wxyz
        client.camera.position = T_world_set.translation()

    client.flush()
    time.sleep(1.0 / 60.0)

# Set look_at to the target position so mouse orbit works correctly
client.camera.look_at = target_position