render_k3d

render_k3d class

Reactively render a k3d 3D plot.

Usage Source

render_k3d(
    _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_k3d is a decorator that creates a render function – a function that returns the plot to display and re-runs when the reactive values it reads change:

import k3d

from shinywidgets import render_k3d


@render_k3d
def scene():
    plot = k3d.plot()
    plot += k3d.points([[0, 0, 0], [1, 1, 1]])
    return plot

The render function should return a k3d.Plot (i.e., the result of k3d.plot() with objects added to it; requires pip install 'shinywidgets[k3d]'), or a bare k3d object such as k3d.points(...), which is placed on a new plot. By default, the plot fills its container; pass height to k3d.plot() to use a fixed pixel height instead (a height of 512, the k3d default, is treated as unspecified).

Note

Accessing the rendered widget: the render function gains two read-only attributes: .value, the value it most recently returned, and .widget, the rendered Plot instance. Widget state can also be read reactively with reactive_read().

Responding to user interaction: plot.camera() reads the camera after the browser’s auto-fit and every orbit, much like input.my_slider() reads an input. Call it in a reactive function (a @render.* function, @reactive.calc, or @reactive.effect), which then re-runs whenever the camera changes.

There is deliberately no clicked(): k3d only reports clicks with plot.mode = "callback", a user-visible change to the plot’s interaction mode, which the accessor API doesn’t make. To react to clicks, set the mode and a click_callback on the objects yourself (and set a value inside it).

Mutating the widget: use .widget to update the rendered plot in place; trait changes on the widget are synced to the browser.

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.

rate_policy : Optional[RatePolicy] = None

How to rate-limit reactive_read() on the widget: "debounce" or "throttle". None (the default) debounces reactive_read() only if rate_delay is given; no accessor on this renderer declares a default.

rate_delay : Optional[float] = None

The rate-limit window in seconds (default 0.25). 0 disables rate limiting.

Each :

which :

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()

The plot’s camera as a flat list of 9 floats (camera position, look-at target, and up vector).

camera()

render_k3d.camera()

The plot’s camera as a flat list of 9 floats (camera position, look-at target, and up vector).

The camera is [] until the browser auto-fits it, so reading camera() before that cancels silently (like req(False)): downstream outputs just wait. With camera_auto_fit=False and no explicit camera it cancels forever – set plot.camera to seed it. Never returns None once it returns. Not rate-limited (k3d throttles camera updates to roughly one per 200 ms upstream).