render_nglview
render_nglview class
Reactively render an nglview molecular structure viewer.
Usage Source
render_nglview(
_fn: Optional[ValueFn[ValueT]] = None,
*,
width: Optional[str] = None,
height: Optional[str] = None,
fill: Optional[bool] = None,
fillable: Optional[bool] = None,
rate_policy: Optional[RatePolicy] = None,
rate_delay: Optional[float] = None,
listen_to: Optional[Sequence[str]] = None,
)@render_nglview is a decorator that creates a render function – a function that returns the viewer to display and re-runs when the reactive values it reads change:
import nglview
from shinywidgets import render_nglview
@render_nglview
def viewer():
return nglview.show_url("rcsb://1crn")The render function should return an nglview.NGLWidget (e.g., from nglview.show_file(), nglview.show_text(), or nglview.show_url(); requires pip install 'shinywidgets[nglview]').
Note
Accessing the rendered widget: the render function gains two read-only attributes: .value, the value it most recently returned, and .widget, the rendered NGLWidget instance.
Responding to user interaction: viewer.camera_orientation() reads the camera’s 4x4 orientation matrix as the user orbits. It’s opt-in (listen_to=["camera_orientation"]); see camera_orientation(). For other viewer state, read it reactively with .read() (a shortcut for reactive_read() on .widget, e.g., the picked atom via "picked").
Mutating the widget: use .widget to update the rendered viewer in place; trait changes on the widget are synced to the browser. Changes made with .widget methods (e.g., add_representation(), center(), clear_representations()) reach the browser even though nglview sends them from a background thread (requires shiny >= 1.9).
Parameters
width : Optional[str] = None-
A CSS length unit (e.g.,
"400px"or"100%") for the output’s width. height : Optional[str] = None-
A CSS length unit for the output’s height. When
None(the default), the output is designed to fill the height of its parent container (seefillandfillable). fill : Optional[bool] = None-
Whether the output should grow or shrink to fit its parent container. When
None(the default), this isTrueifheightis not specified. fillable : Optional[bool] = None-
Whether the output container should fill available space (scrolling its contents on overflow). When
None(the default), this isTrueifheightis not specified.
See also
output_widget(): in Shiny Core, the UI needs this to hold the output (Shiny Express displays it where the render function is defined).
Methods
camera_orientation() |
The camera’s flattened 4x4 orientation matrix, as the browser last reported it (None until the camera first moves). |
camera_orientation()
render_nglview.camera_orientation()The camera’s flattened 4x4 orientation matrix, as the browser last reported it (None until the camera first moves).
Opt-in (listen_to=["camera_orientation"]): nglview streams the matrix to Python every ~100 ms while the camera moves, so the trait is muted unless the accessor is enabled. Debounced (250 ms) by default; see rate_policy/rate_delay. nglview calls camera control “unstable” API; this trait is what nglview itself uses to sync cameras between linked views. For a one-off read, turn native events on app-wide with shinywidgets.config(native_events=True).