GUI API¶
- class viser.GuiApi[source]¶
Interface for working with the 2D GUI in viser.
Used by both our global server object, for sharing the same GUI elements with all clients, and by individual client handles.
- set_panel_label(label: str | None) None [source]¶
Set the main label that appears in the GUI panel.
- Parameters:
label (str | None) – The new label.
- Return type:
None
- configure_theme(*, titlebar_content: TitlebarConfig | None = None, control_layout: Literal[‘floating’, ‘collapsible’, ‘fixed’] = 'floating', control_width: Literal[‘small’, ‘medium’, ‘large’] = 'medium', dark_mode: bool = False, show_logo: bool = True, show_share_button: bool = True, brand_color: tuple[int, int, int] | None = None) None [source]¶
Configures the visual appearance of the viser front-end.
- Parameters:
titlebar_content (TitlebarConfig | None) – Optional configuration for the title bar.
control_layout (Literal[‘floating’, ‘collapsible’, ‘fixed’]) – The layout of control elements, options are “floating”, “collapsible”, or “fixed”.
control_width (Literal[‘small’, ‘medium’, ‘large’]) – The width of control elements, options are “small”, “medium”, or “large”.
dark_mode (bool) – A boolean indicating if dark mode should be enabled.
show_logo (bool) – A boolean indicating if the logo should be displayed.
show_share_button (bool) – A boolean indicating if the share button should be displayed.
brand_color (tuple[int, int, int] | None) – An optional tuple of integers (RGB) representing the brand color.
- Return type:
None
- add_folder(label: str, order: float | None = None, expand_by_default: bool = True, visible: bool = True) GuiFolderHandle [source]¶
Add a folder, and return a handle that can be used to populate it.
- Parameters:
label (str) – Label to display on the folder.
order (float | None) – Optional ordering, smallest values will be displayed first.
expand_by_default (bool) – Open the folder by default. Set to False to collapse it by default.
visible (bool) – Whether the component is visible.
- Returns:
A handle that can be used as a context to populate the folder.
- Return type:
- add_modal(title: str, order: float | None = None) GuiModalHandle [source]¶
Show a modal window, which can be useful for popups and messages, then return a handle that can be used to populate it.
- Parameters:
title (str) – Title to display on the modal.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used as a context to populate the modal.
- Return type:
GuiModalHandle
- add_tab_group(order: float | None = None, visible: bool = True) GuiTabGroupHandle [source]¶
Add a tab group.
- Parameters:
order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.
- Returns:
A handle that can be used as a context to populate the tab group.
- Return type:
- add_markdown(content: str, image_root: Path | None = None, order: float | None = None, visible: bool = True) GuiMarkdownHandle [source]¶
Add markdown to the GUI.
- Parameters:
content (str) – Markdown content to display.
image_root (Path | None) – Optional root directory to resolve relative image paths.
order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_image(image: ndarray, label: str | None = None, format: Literal[‘png’, ‘jpeg’] = 'jpeg', jpeg_quality: int | None = None, order: float | None = None, visible: bool = True) GuiImageHandle [source]¶
- Parameters:
image (ndarray)
label (str | None)
format (Literal[‘png’, ‘jpeg’])
jpeg_quality (int | None)
order (float | None)
visible (bool)
- Return type:
GuiImageHandle
- add_plotly(figure: go.Figure, aspect: float = 1.0, order: float | None = None, visible: bool = True) GuiPlotlyHandle [source]¶
Add a Plotly figure to the GUI. Requires the
plotly
package to be installed.- Parameters:
figure (go.Figure) – Plotly figure to display.
aspect (float) – Aspect ratio of the plot in the control panel (width/height).
order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_button(label: str, disabled: bool = False, visible: bool = True, hint: str | None = None, color: Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None = None, icon: IconName | None = None, order: float | None = None) GuiButtonHandle [source]¶
Add a button to the GUI. The value of this input is set to
True
every time it is clicked; to detect clicks, we can manually set it back toFalse
.- Parameters:
label (str) – Label to display on the button.
visible (bool) – Whether the button is visible.
disabled (bool) – Whether the button is disabled.
hint (str | None) – Optional hint to display on hover.
color (Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None) – Optional color to use for the button.
icon (IconName | None) – Optional icon to display on the button.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_upload_button(label: str, disabled: bool = False, visible: bool = True, hint: str | None = None, color: Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None = None, icon: IconName | None = None, mime_type: str = '*/*', order: float | None = None) GuiUploadButtonHandle [source]¶
Add a button to the GUI. The value of this input is set to
True
every time it is clicked; to detect clicks, we can manually set it back toFalse
.- Parameters:
label (str) – Label to display on the button.
visible (bool) – Whether the button is visible.
disabled (bool) – Whether the button is disabled.
hint (str | None) – Optional hint to display on hover.
color (Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None) – Optional color to use for the button.
icon (IconName | None) – Optional icon to display on the button.
mime_type (str) – Optional MIME type to filter the files that can be uploaded.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_button_group(label: str, options: Sequence[str], visible: bool = True, disabled: bool = False, hint: str | None = None, order: float | None = None) GuiButtonGroupHandle [source]¶
Add a button group to the GUI.
- Parameters:
label (str) – Label to display on the button group.
options (Sequence[str]) – Sequence of options to display as buttons.
visible (bool) – Whether the button group is visible.
disabled (bool) – Whether the button group is disabled.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_checkbox(label: str, initial_value: bool, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiCheckboxHandle [source]¶
Add a checkbox to the GUI.
- Parameters:
label (str) – Label to display on the checkbox.
initial_value (bool) – Initial value of the checkbox.
disabled (bool) – Whether the checkbox is disabled.
visible (bool) – Whether the checkbox is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_text(label: str, initial_value: str, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiTextHandle [source]¶
Add a text input to the GUI.
- Parameters:
label (str) – Label to display on the text input.
initial_value (str) – Initial value of the text input.
disabled (bool) – Whether the text input is disabled.
visible (bool) – Whether the text input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_number(label: str, initial_value: IntOrFloat, min: IntOrFloat | None = None, max: IntOrFloat | None = None, step: IntOrFloat | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiNumberHandle[IntOrFloat] [source]¶
Add a number input to the GUI, with user-specifiable bound and precision parameters.
- Parameters:
label (str) – Label to display on the number input.
initial_value (IntOrFloat) – Initial value of the number input.
min (IntOrFloat | None) – Optional minimum value of the number input.
max (IntOrFloat | None) – Optional maximum value of the number input.
step (IntOrFloat | None) – Optional step size of the number input. Computed automatically if not specified.
disabled (bool) – Whether the number input is disabled.
visible (bool) – Whether the number input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
GuiNumberHandle[IntOrFloat]
- add_vector2(label: str, initial_value: tuple[float, float] | ndarray, min: tuple[float, float] | ndarray | None = None, max: tuple[float, float] | ndarray | None = None, step: float | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiVector2Handle [source]¶
Add a length-2 vector input to the GUI.
- Parameters:
label (str) – Label to display on the vector input.
initial_value (tuple[float, float] | ndarray) – Initial value of the vector input.
min (tuple[float, float] | ndarray | None) – Optional minimum value of the vector input.
max (tuple[float, float] | ndarray | None) – Optional maximum value of the vector input.
step (float | None) – Optional step size of the vector input. Computed automatically if not
disabled (bool) – Whether the vector input is disabled.
visible (bool) – Whether the vector input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_vector3(label: str, initial_value: tuple[float, float, float] | ndarray, min: tuple[float, float, float] | ndarray | None = None, max: tuple[float, float, float] | ndarray | None = None, step: float | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiVector3Handle [source]¶
Add a length-3 vector input to the GUI.
- Parameters:
label (str) – Label to display on the vector input.
initial_value (tuple[float, float, float] | ndarray) – Initial value of the vector input.
min (tuple[float, float, float] | ndarray | None) – Optional minimum value of the vector input.
max (tuple[float, float, float] | ndarray | None) – Optional maximum value of the vector input.
step (float | None) – Optional step size of the vector input. Computed automatically if not
disabled (bool) – Whether the vector input is disabled.
visible (bool) – Whether the vector input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_dropdown(label: str, options: Sequence[TLiteralString], initial_value: TLiteralString | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiDropdownHandle[TLiteralString] [source]¶
- add_dropdown(label: str, options: Sequence[TString], initial_value: TString | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiDropdownHandle[TString]
Add a dropdown to the GUI.
- Parameters:
label – Label to display on the dropdown.
options – Sequence of options to display in the dropdown.
initial_value – Initial value of the dropdown.
disabled – Whether the dropdown is disabled.
visible – Whether the dropdown is visible.
hint – Optional hint to display on hover.
order – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- add_progress_bar(value: float, visible: bool = True, animated: bool = False, color: Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None = None, order: float | None = None) GuiProgressBarHandle [source]¶
Add a progress bar to the GUI.
- Parameters:
value (float) – Value of the progress bar. (0 - 100)
visible (bool) – Whether the progress bar is visible.
animated (bool) – Whether the progress bar is in a loading state (animated, striped).
color (Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None) – The color of the progress bar.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
GuiProgressBarHandle
- add_slider(label: str, min: IntOrFloat, max: IntOrFloat, step: IntOrFloat, initial_value: IntOrFloat, marks: tuple[IntOrFloat | tuple[IntOrFloat, str], …] | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiSliderHandle[IntOrFloat] [source]¶
Add a slider to the GUI. Types of the min, max, step, and initial value should match.
- Parameters:
label (str) – Label to display on the slider.
min (IntOrFloat) – Minimum value of the slider.
max (IntOrFloat) – Maximum value of the slider.
step (IntOrFloat) – Step size of the slider.
initial_value (IntOrFloat) – Initial value of the slider.
marks (tuple[IntOrFloat | tuple[IntOrFloat, str], …] | None) – tuple of marks to display below the slider. Each mark should either be a numerical or a (number, label) tuple, where the label is provided as a string.
disabled (bool) – Whether the slider is disabled.
visible (bool) – Whether the slider is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
GuiSliderHandle[IntOrFloat]
- add_multi_slider(label: str, min: IntOrFloat, max: IntOrFloat, step: IntOrFloat, initial_value: tuple[IntOrFloat, …], min_range: IntOrFloat | None = None, fixed_endpoints: bool = False, marks: tuple[IntOrFloat | tuple[IntOrFloat, str], …] | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiMultiSliderHandle[IntOrFloat] [source]¶
Add a multi slider to the GUI. Types of the min, max, step, and initial value should match.
- Parameters:
label (str) – Label to display on the slider.
min (IntOrFloat) – Minimum value of the slider.
max (IntOrFloat) – Maximum value of the slider.
step (IntOrFloat) – Step size of the slider.
initial_value (tuple[IntOrFloat, …]) – Initial values of the slider.
min_range (IntOrFloat | None) – Optional minimum difference between two values of the slider.
fixed_endpoints (bool) – Whether the endpoints of the slider are fixed.
marks (tuple[IntOrFloat | tuple[IntOrFloat, str], …] | None) – tuple of marks to display below the slider. Each mark should either be a numerical or a (number, label) tuple, where the label is provided as a string.
disabled (bool) – Whether the slider is disabled.
visible (bool) – Whether the slider is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
GuiMultiSliderHandle[IntOrFloat]
- add_rgb(label: str, initial_value: tuple[int, int, int], disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiRgbHandle [source]¶
Add an RGB picker to the GUI.
- Parameters:
label (str) – Label to display on the RGB picker.
initial_value (tuple[int, int, int]) – Initial value of the RGB picker.
disabled (bool) – Whether the RGB picker is disabled.
visible (bool) – Whether the RGB picker is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type:
- add_rgba(label: str, initial_value: tuple[int, int, int, int], disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) GuiRgbaHandle [source]¶
Add an RGBA picker to the GUI.
- Parameters:
label (str) – Label to display on the RGBA picker.
initial_value (tuple[int, int, int, int]) – Initial value of the RGBA picker.
disabled (bool) – Whether the RGBA picker is disabled.
visible (bool) – Whether the RGBA picker is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.
- Returns:
A handle that can be used to interact with the GUI element.
- Return type: