GUI Handles¶
- class viser.GuiButtonGroupHandle[source]¶
Handle for a button group input in our visualizer.
- on_click(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine][source]¶
Attach a function to call when a button in the group is clicked.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiButtonHandle[source]¶
Handle for a button input in our visualizer.
- value: bool¶
Value of the button. Set to True when the button is pressed. Can be manually set back to False.
- property icon: IconName | None¶
Icon to display on the button. When set to None, no icon is displayed.
- on_click(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine][source]¶
Attach a function to call when a button is pressed.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- on_hold(func: None = None, callback_hz: float = 10.0) Callable[[_HoldCallback], _HoldCallback][source]¶
- on_hold(func: _HoldCallback, callback_hz: float = 10.0) _HoldCallback
Attach a function to call repeatedly while a button is held down.
The callback will be triggered immediately when the button is pressed, and then repeatedly at the specified frequency until released.
- Can be used as a decorator with or without arguments:
@button.on_hold def callback(event): …
@button.on_hold(callback_hz=30.0) def callback(event): …
- Or called directly:
button.on_hold(callback) button.on_hold(callback, callback_hz=30.0)
- Parameters:
func – The callback function to attach. If None, returns a decorator.
callback_hz – The frequency in Hz at which to call the callback while the button is held. Defaults to 10.0 Hz.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiCheckboxHandle[source]¶
Handle for checkbox inputs.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiDropdownHandle[source]¶
Handle for a dropdown-style GUI input in our visualizer.
- value: StringType¶
Value of the input. Represents the currently selected option in the dropdown.
- property options: tuple[StringType, ...]¶
Options for our dropdown. Synchronized automatically when assigned.
For projects that care about typing: the static type of options should be consistent with the StringType associated with a handle. Literal types will be inferred where possible when handles are instantiated; for the most flexibility, we can declare handles as GuiDropdownHandle[str].
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiFolderHandle[source]¶
Use as a context to place GUI elements into a folder.
- class viser.GuiImageHandle[source]¶
Handle for updating and removing images.
- property image: ndarray¶
Current content of this image element. Synchronized automatically when assigned.
- class viser.GuiInputHandle[source]¶
A handle is created for each GUI element that is added in viser. Handles can be used to read and write state.
When a GUI element is added via
ViserServer.gui, state is synchronized between all connected clients. When a GUI element is added viaClientHandle.gui, state is local to a specific client.- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine][source]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiMultiSliderHandle[source]¶
Handle for multi-slider inputs.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiNumberHandle[source]¶
Handle for number inputs.
- value: IntOrFloat¶
Value of the input. Synchronized automatically when assigned.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiPlotlyHandle[source]¶
Handle for updating and removing Plotly figures.
- property figure: go.Figure¶
Current content of this markdown element. Synchronized automatically when assigned.
- class viser.GuiRgbHandle[source]¶
Handle for RGB color inputs.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiRgbaHandle[source]¶
Handle for RGBA color inputs.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiSliderHandle[source]¶
Handle for slider inputs.
- value: IntOrFloat¶
Value of the input. Synchronized automatically when assigned.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiTabGroupHandle[source]¶
Handle for a tab group. Call
add_tab()to add a tab.
- class viser.GuiTextHandle[source]¶
Handle for text inputs.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiUploadButtonHandle[source]¶
Handle for an upload file button in our visualizer.
The .value attribute will be updated with the contents of uploaded files.
- value: UploadedFile¶
Value of the input. Contains information about the uploaded file.
- property icon: IconName | None¶
Icon to display on the upload button. When set to None, no icon is displayed.
- on_upload(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine][source]¶
Attach a function to call when a file is uploaded.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiUplotHandle[source]¶
Handle for updating and removing Uplot figures.
- data: Tuple[npt.NDArray[np.float64], ...]¶
Tuple of 1D numpy arrays containing chart data. First array is x-axis data, subsequent arrays are y-axis data for each series. All arrays must have matching lengths. Minimum 2 arrays required.
- mode: Literal[1, 2] | None¶
1 = aligned (all series share axes), 2 = faceted (each series gets its own subplot panel). Defaults to 1.
- Type:
Chart layout mode
- series: Tuple[uplot.Series, ...]¶
Series configuration objects defining visual appearance (colors, line styles, labels) and behavior for each data array. Must match data tuple length.
- bands: Tuple[uplot.Band, ...] | None¶
High/low range visualizations between adjacent series indices. Useful for confidence intervals, error bounds, or min/max ranges.
- scales: Dict[str, uplot.Scale] | None¶
Scale definitions controlling data-to-pixel mapping and axis ranges. Enables features like auto-ranging, manual bounds, time-based scaling, and logarithmic distributions. Multiple scales support dual-axis charts.
- axes: Tuple[uplot.Axis, ...] | None¶
Axis configuration for positioning (top/right/bottom/left), tick formatting, grid styling, and spacing. Controls visual appearance of chart axes.
- legend: uplot.Legend | None¶
Legend display options including positioning, styling, and custom value formatting for hover states.
- cursor: uplot.Cursor | None¶
Interactive cursor behavior including hover detection, drag-to-zoom, and crosshair appearance. Controls user interaction with the chart.
- focus: uplot.Focus | None¶
Visual highlighting when hovering over series. Controls alpha transparency of non-focused series to emphasize the active one.
- class viser.GuiVector2Handle[source]¶
Handle for 2D vector inputs.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.
- class viser.GuiVector3Handle[source]¶
Handle for 3D vector inputs.
- on_update(func: Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]) Callable[[GuiEvent[TGuiHandle]], NoneOrCoroutine]¶
Attach a function to call when a GUI input is updated.
Note: - If func is a regular function (defined with def), it will be executed in a thread pool. - If func is an async function (defined with async def), it will be executed in the event loop.
Using async functions can be useful for reducing race conditions.