Results and saving
Most of ipyniivue sends commands from Python to the viewer. This page is about the other direction: getting something back.
Responding to clicks
import ipywidgets as widgets
where = widgets.Label()
def show_location(detail): where.value = detail["string"]
nv.on("locationChange", show_location)display(where)locationChange fires when the crosshair moves. Its detail is a
dictionary with the position in millimeters (mm) and in voxels (vox),
the value of each image at that point (values), and all of it as one line
of text (string).
nv.on returns a function that unsubscribes the callback, and
nv.off("locationChange") removes every callback for that event. The event
names are in ipyniivue.NIIVUE_EVENT_NAMES; a name that is not in the list
raises ValueError. If a callback raises, the traceback is printed and the
viewer carries on.
Events travel from the browser to Python over the notebook connection, so
keep them for things that happen now and then, like clicks. Large arrays in
an event arrive as None. To control the viewer, send commands from Python
instead, for example from a slider.
Asking the viewer for a value
Methods that return something, such as get_crosshair_pos,
get_descriptives or save_drawing, are async. The answer comes from the
browser, and the notebook only reads messages from the browser between
cells. So do not write await nv.get_crosshair_pos() in a cell: the cell
waits for an answer that cannot arrive until it ends, and hangs.
Start the request in one cell instead:
import asyncio
task = asyncio.ensure_future(nv.get_crosshair_pos())and read the answer in the next one:
task.result()Run that second cell on its own, after the first. When you run all cells in
one go, it runs before the answer arrives and raises InvalidStateError.
If NiiVue reports an error, task.result() raises RuntimeError.
To use an answer as soon as it comes, for example from a button, put the steps in an async function and start that. The example notebooks do it this way:
async def report(): where.value = str(await nv.get_crosshair_pos())
button = widgets.Button(description="Where am I?")button.on_click(lambda _button: asyncio.ensure_future(report()))display(button)Saving a picture
nv.download_bitmap("brain.png")The browser downloads a PNG of the viewer. It waits for any load sent before
it, so it can follow add_volume_from_url straight away. The pixels come
from the browser, so running a notebook without one, for example with
jupyter nbconvert --execute, saves nothing.
Saving the whole scene
nv.save_document("scene.nvd")This downloads the scene, with its images, meshes, drawing and view
settings, as an .nvd file that NiiVue can open again. To keep it in Python
instead, ask for the bytes:
from pathlib import Path
task = asyncio.ensure_future(nv.serialize_document())# in the next cell:Path("scene.nvd").write_bytes(bytes(task.result()))Drawing a mask
nv.create_empty_drawing()nv.draw_is_enabled = Truenv.draw_pen_value = 1Now clicking and dragging in the viewer paints with label 1, and
nv.draw_undo() takes back the last stroke. To work with the result in
Python, ask for the drawing with an empty file name, which returns it as
NIfTI bytes instead of downloading it:
import nibabel as nib
task = asyncio.ensure_future(nv.save_drawing(""))# in the next cell:mask = nib.Nifti1Image.from_bytes(bytes(task.result()))Pass a file name such as "mask.nii.gz" to download it instead. For
statistics of the background image inside the drawing, such as the mean and
the volume in milliliters:
task = asyncio.ensure_future(nv.get_descriptives({"isDrawingMask": True}))# in the next cell:stats = task.result()print(stats["mean"], stats["volumeML"])Filling in the slices between drawings
Draw on a few slices some distance apart, then let the viewer fill in the slices between them:
task = asyncio.ensure_future(nv.interpolate_drawing_slices(axis=0))axis is 0 for axial, 1 for coronal and 2 for sagittal slices. With
use_intensity_guided=True the fill follows the edges in the background
image. When it is done, task.result() tells you how many voxels were drawn
before and after. It uses nv-ext-drawing,
and Drawing covers the pen and its settings.
Running image processing
asyncio.ensure_future(nv.apply_image_transform("otsu", options={"levels": 3}))Four transforms come built in: otsu, connectedLabel, conform and
removeHaze. Each runs in a background worker in the browser and adds its
result as a new overlay. removeHaze cleans up the image itself, so pass
replace_background=True with it. nv.get_volume_transform_info("otsu")
describes a transform and its options; read its answer the same way. The
transforms come from
nv-ext-image-processing.