render_vizarr

render_vizarr class

Reactively render a vizarr image viewer (for OME-NGFF/Zarr bioimages).

render_vizarr(
    _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,
)

@render_vizarr 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 numpy as np
import vizarr

from shinywidgets import render_vizarr


@render_vizarr
def viewer():
    v = vizarr.Viewer()
    v.add_image(np.random.default_rng(0).random((256, 256)))
    return v

The render function should return a vizarr.Viewer with one or more images added via .add_image() (requires pip install 'shinywidgets[vizarr]'). In a filling layout, the viewer grows or shrinks to fit its container.

Note

Accessing the rendered widget: the render function gains two read-only attributes: .value, the value it most recently returned, and .widget, the rendered vizarr.Viewer instance.

Responding to user interaction: panning and zooming syncs the camera to the view_state trait (a dict with target and zoom, debounced ~200ms), so it can drive reactive calculations (e.g., vz.read("view_state")). Note that the layer controls in the viewer’s side panel (channel colors, contrast limits, visibility) do not sync back to Python.

Mutating the widget: use .widget to update the rendered viewer in place: .widget.add_image(...) adds a layer without a full re-render, and .widget.view_state = {...} sets the camera; trait changes on the widget are synced to the browser.

Data sources: add_image() accepts a remote URL string (e.g., an OME-Zarr store on S3), which the browser fetches directly, or a local zarr.Array/zarr.Group/store/numpy array, in which case chunks are served on demand over the widget comm (base64-encoded, since Shiny has no binary message channel). Prefer remote URLs for large images: they avoid the ~33% base64 inflation and keep chunk traffic off the Shiny websocket.

Sizing: in a filling layout the viewer grows or shrinks to fit its container, and an explicit output_widget(height=...) sizes the viewer to that height. Otherwise the viewer’s own height trait applies (default "500px"); setting it (e.g., vizarr.Viewer(height="300px")) opts out of filling, and an explicit output_widget(height=...) takes precedence over it.

Network access: the widget loads its JavaScript (the vizarr viewer and viv) from CDNs at render time, so it requires an internet connection.

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 (see fill and fillable).
fill : Optional[bool] = None: Whether the output should grow or shrink to fit its parent container. When None (the default), this is True if height is not specified.
fillable : Optional[bool] = None: Whether the output container should fill available space (scrolling its contents on overflow). When None (the default), this is True if height is not specified.

render_vizarr class

Note

Parameters

See also