Events

We define a small set of event types, which are passed to callback functions when events like clicks or GUI updates are triggered.

class viser.CommandEvent

Information associated with a command trigger from the command palette.

Passed as input to callback functions.

client and client_id are typed Optional for parity with GuiEvent (which can fire server-side) and to leave room for a future programmatic handle.trigger() path. In practice, every command trigger today originates from a real client – the dispatcher drops the event if the client can’t be resolved, so callbacks only see non-None values.

client: ClientHandle | None

Client that triggered this command.

client_id: int | None

ID of client that triggered this command.

target: CommandHandle

Command handle that was triggered.

class viser.GuiEvent

Information associated with a GUI event, such as an update or click.

Passed as input to callback functions.

client: ClientHandle | None

Client that triggered this event.

client_id: int | None

ID of client that triggered this event.

target: TGuiHandle

GUI element that was affected.

class viser.SceneClickEvent

Event passed to scene-level click callbacks (SceneApi.on_click).

client: ClientHandle

Client that triggered this event.

client_id: int

ID of client that triggered this event.

ray_origin: tuple[float, float, float]

Origin of the 3D ray corresponding to this click, in world coordinates.

ray_direction: tuple[float, float, float]

Direction of the 3D ray corresponding to this click, in world coordinates.

screen_pos: tuple[float, float]

Screen position of the click in OpenCV image coordinates (0 to 1). (0, 0) is the upper-left corner, (1, 1) is the bottom-right corner.

modifier: _messages.KeyModifier | None

Modifier-combo held at click time. None if no modifiers were held; otherwise a canonical KeyModifier string.

class viser.SceneNodeDragEvent

Event passed to scene-node drag callbacks.

client: ClientHandle

Client that triggered this event.

client_id: int

ID of client that triggered this event.

target: TSceneNodeHandle

Scene node that is being dragged.

phase: DragPhase

"start" at press, "update" on every throttled pointermove (~20Hz), "end" at release. A single drag fires exactly one "start", zero or more "update"``s, and exactly one ``"end".

Type:

Drag lifecycle phase

instance_index: int | None

Instance index within a batched scene node (e.g. batched meshes, batched GLBs, batched axes); None for non-batched nodes. Frozen at drag-start – the drag always refers to the instance that was under the cursor when the gesture began.

start_position: Tuple[float, float, float]

World-coords position of the click point on the object. Live – updates each event as the object moves, so it always reflects where the grab point currently is in world coords (useful for rotate-around-grab gestures).

start_screen_pos: Tuple[float, float]

Live OpenCV screen-space projection of the click point.

end_position: Tuple[float, float, float]

Current pointer projected onto the camera-aligned drag plane, in world coords.

end_screen_pos: Tuple[float, float]

Current pointer in OpenCV screen-space coordinates.

button: Literal['left', 'middle', 'right']

Mouse button that initiated the drag.

modifier: _messages.KeyModifier | None

Modifier-combo held at drag-start (frozen for the drag’s lifetime). None if no modifiers were held; otherwise a canonical KeyModifier string.

class viser.SceneNodePointerEvent

Event passed to pointer callbacks for scene nodes (currently only clicks).

client: ClientHandle

Client that triggered this event.

client_id: int

ID of client that triggered this event.

event: Literal['click']

Type of event that was triggered. Currently we only support clicks.

target: TSceneNodeHandle

Scene node that was clicked.

ray_origin: tuple[float, float, float]

Origin of 3D ray corresponding to this click, in world coordinates.

ray_direction: tuple[float, float, float]

Direction of 3D ray corresponding to this click, in world coordinates.

screen_pos: tuple[float, float]

Screen position of the click on the screen (OpenCV image coordinates, 0 to 1). (0, 0) is the upper-left corner, (1, 1) is the bottom-right corner.

instance_index: int | None

Instance ID of the clicked object, if applicable. Currently this is None for all objects except for the output of SceneApi.add_batched_axes().

modifier: _messages.KeyModifier | None

Modifier-combo held when this event fired. None if no modifiers were held; otherwise a canonical KeyModifier string.

class viser.ScenePointerEvent

Event passed to scene pointer callbacks (legacy on_pointer_event).

Deprecated since version Use: SceneApi.on_click() with SceneClickEvent or SceneApi.on_rect_select() with SceneRectSelectEvent instead. This shape unions the click and rect-select cases into a single dataclass with awkward Optional/variable-length fields.

client: ClientHandle

Client that triggered this event.

client_id: int

ID of client that triggered this event.

event_type: _messages.ScenePointerEventType

Type of event that was triggered. Currently we only support clicks and box selections.

ray_origin: tuple[float, float, float] | None

Origin of 3D ray corresponding to this click, in world coordinates.

ray_direction: tuple[float, float, float] | None

Direction of 3D ray corresponding to this click, in world coordinates.

screen_pos: tuple[tuple[float, float], ...]

Screen position of the click on the screen (OpenCV image coordinates, 0 to 1). (0, 0) is the upper-left corner, (1, 1) is the bottom-right corner. For a box selection, this includes the min- and max- corners of the box.

modifier: _messages.KeyModifier | None

Modifier-combo held when this event fired. None if no modifiers were held; otherwise a canonical KeyModifier string.

property event

Deprecated. Use event_type instead.

Deprecated since version 0.2.23: The event property is deprecated. Use event_type instead.

class viser.SceneRectSelectEvent

Event passed to scene rectangle-select callbacks (SceneApi.on_rect_select).

client: ClientHandle

Client that triggered this event.

client_id: int

ID of client that triggered this event.

screen_min: tuple[float, float]

Min-corner of the selection rectangle in OpenCV image coordinates (0 to 1).

screen_max: tuple[float, float]

Max-corner of the selection rectangle.

modifier: _messages.KeyModifier | None

Modifier-combo held at gesture start. None if no modifiers were held; otherwise a canonical KeyModifier string.

class viser.TransformControlsEvent

Event passed to callbacks for transform control updates.

client: ClientHandle | None

Client that triggered this event.

client_id: int | None

ID of client that triggered this event.

target: TransformControlsHandle

Transform controls handle that was affected.

phase: DragPhase

"start" when the user grabs a handle, "update" on every pose change while dragging, "end" at release. target.wxyz and target.position reflect the current pose on every phase (start/end fire at the same pose as the surrounding update).

Type:

Drag lifecycle phase