Plot (handle)
What a bound Plot offers code: fit, settle, selections, the camera, the animation clock and exports.
with hm.Plot() as plot:
...
await plot.when_settled()
await plot.export_png("plot.png", scale=2)Get a handle
In Svelte, use bind:this={plot} on Plot. The member table describes that JavaScript handle.
Wait for whenSettled() before reading a newly updated plot or exporting it; use whenAnimationsFinished() when the final transition state is required.
Python members
In Python the node itself is the handle: keep the context manager’s result, with hm.Plot(...) as plot:. Its members are of three kinds.
- sync members run at once and need no browser. They change the scene, which every view of it then shows: a displayed notebook view, or a later standalone export.
- await members are coroutines that ask a displayed view. They need the plot shown in a
notebook (JupyterLab, Notebook 7 or VS Code, in a browser with WebGPU) and
awaitin a running event loop, as a notebook cell’s top level has. Without a displayed view they raisehm.SceneErrorwith codebridge.missing_view; with several views of one scene, passview=, one of the scene’sviews. Each waits at mosttimeoutseconds (default 60), then raisesSceneErrorwith codebridge.timeout. - property and attribute members are read in Python. A property the browser reports
(
description) isNoneuntil a view has shown the plot.
These are the members of every node (a transform’s, a mark’s, a Facet’s), and description is a Plot’s own. Python does not use the JavaScript names in the table above.
| Member | Kind | What it does |
|---|---|---|
id | attribute | The node’s id in the scene: a string. |
kind | attribute | The component’s name, "Plot". |
props | attribute | The props as the scene sends them, camelCase; change them with update. |
children | attribute | The child nodes, in draw order. |
parent | attribute | The node that contains this one, or None. |
description | property | The description screen readers get (description=, else the generated summary), synced from the browser after the plot settles; None before a view has shown it. |
update(**props) | sync | Set props, snake_case keywords checked as the constructor checks them, and redraw every view. Returns the node. |
add(*children) | sync | Append components; one already here moves to the end (child order is draw order), one in another container is an error. Returns the node. |
remove(child) | sync | Detach a child; returns it. |
clear() | sync | Remove every child. Returns the node. |
batch_update() | sync | A context manager, with plot.batch_update():. The changes inside it reach the views as one update, and none of them stays if the block raises. |
on_event(event, callback) | sync | Call callback(event) when a view reports event: click, dblclick, pointermove, pointerenter, pointerleave, contextmenu, camerachange, viewportchange, drag or dragend. Returns the callback. Events come only from displayed views. |
on_click(callback) | sync | on_event("click", callback). |
on_hover(callback) | sync | on_event("pointermove", callback). |
selection | property | The selection of the plot’s data (data=, or the nearest Data above): a SelectionResource to read and set. A node without data raises RuntimeError. |
brush | property | The data’s brush, a SelectionResource. |
hover | property | The data’s hover state, a SelectionResource. |
nearby | property | The data’s nearby rows, a SelectionResource. |
nearest | property | The data’s nearest row, a SelectionResource. |
endpoint(name=None, *, at=None) | sync | This node as an endpoint for hm.connect: a mark with an attachment at, or the mark name that an embedded Facet or a Partition repeats. See connect. |
when_settled(*, view=None, timeout=60) | await | Returns once the view has drawn every change made before the call, loads in flight included. |
when_animations_finished(*, view=None, timeout=60) | await | Returns once the view’s transitions have finished. |
fit(*, view=None, timeout=60) | await | Reset the view: a 2D plot to its full domain, a 3D one to a new camera. |
get_camera(*, view=None, timeout=60) | await | The 3D camera: a dict of position, target, up, fov, near, far, zoom and mode. |
set_camera(state=None, *, animate=False, view=None, timeout=60, **fields) | await | Merge a partial camera (a dict, or keywords: position, target, up, fov, near, far, zoom), easing there with animate=True; returns the camera. |
get_viewport(*, view=None, timeout=60) | await | The 2D viewport: x, y, zoom, zoomX and zoomY, and an orthographic globe’s center. |
set_viewport(state=None, *, view=None, timeout=60, **fields) | await | Merge a partial viewport (x, y, zoom, zoom_x, zoom_y, center) and return the result. |
get_time(*, view=None, timeout=60) | await | The scene’s animation clock, in milliseconds. |
set_time(time, *, freeze=True, view=None, timeout=60) | await | Set the clock (milliseconds), frozen there until set_time(None) unless freeze=False; returns the clock. |
export_png(path=None, *, scale=2, view=None, timeout=60) | await | This view as PNG bytes, scale pixels per CSS pixel, also written to path when given. |
export_svg(path=None, **options) | await | This view as SVG bytes. The options are DocumentExportOptions in snake_case (width, height, mode, raster_dpi, text, primitive_budget) with view and timeout. |
export_pdf(path=None, **options) | await | The SVG export printed to PDF in a private headless Chrome; bytes. |
export_html(path=None, *, snapshot='svg', page=True, view=None, timeout=60, **options) | await | A standalone page of the scene and this view’s camera, showing a snapshot first ("svg", "png" or False); bytes. page= lays the page out: a 24 px margin and the content at most 960 px wide by default, {"max_width": ..., "margin": ...} in pixels, or False for a bare page. A page over the 10 MiB a notebook can send to the kernel is exported headlessly instead, as hm.export_html does, with a warning. Other options are an error. |
export_mp4(path, *, duration, fps=30, start=0, scale=2, encoder='ffmpeg', view=None, timeout=60) | await | The @time animation as an MP4 at path: a PNG per frame at a frozen clock, encoded by ffmpeg or, with encoder="browser", by the view’s WebCodecs. The clock is restored. Returns the path. |
groups(*, view=None, timeout=60) | await | A Partition’s mounted groups: key, values, label and mark labels; other nodes raise. |
action(action, *, view=None, timeout=60) | await | Run an action the node has, such as Force’s "reset" or a Provider’s "refresh". |
Without a notebook
A script exports with module functions instead. They are synchronous, need no displayed view,
and draw the scene in a private headless Chrome (an installed Chrome, Edge or Chromium, else one
downloaded once; see docs/DOCUMENT-EXPORT.md). Each returns what the matching await member
returns, and writes path when given. From async code, hm.export_png_async and the other _async functions run them in a thread.
| Function | Kind | What it does |
|---|---|---|
hm.export_png(target, path=None, **options) | sync | PNG bytes; options scale (default 2), and cells=True for a Facet’s cells one by one. |
hm.export_svg(target, path=None, **options) | sync | SVG bytes, with the DocumentExportOptions in snake_case. |
hm.export_pdf(target, path=None, **options) | sync | PDF bytes, printed from the SVG export. |
hm.export_html(target, path=None, **options) | sync | A page, with its snapshot drawn in the headless Chrome (snapshot="svg", "png" or False), laid out by page= as above. |
hm.export_mp4(target, path, *, duration, fps=30, start=0, scale=2, encoder='ffmpeg') | sync | The @time animation as an MP4; returns the path. |
hm.ExportSession() | sync | with hm.ExportSession() as session: reuses one browser for several exports: session.png, session.svg, session.pdf, session.html and session.mp4 take the functions’ arguments, and session.set_time, session.get_viewport and session.set_viewport set a plot up first. |
SVG and PDF keep axes, text, legends and most 2D marks as vector shapes and draw the rest as
images at raster_dpi; what is not exported as vector lists what.