Skip to content

Loading images

View as Markdown

There are four ways to get an image into the viewer: from a URL, from a file the kernel can read, from bytes, or from a NumPy array. Every one of them can be called straight after display(nv).

From a URL

nv.add_volume_from_url(
"https://niivue.github.io/mono/volumes/mni152.nii.gz",
colormap="gray",
cal_min=30,
cal_max=80,
)

The browser fetches the file itself, which makes this the fastest way to load a large image. The keyword arguments are NiiVue’s volume options in snake case: cal_min and cal_max set the display range, and colormap and opacity do what their names say. See Loading images in the NiiVue guide for the others.

The example notebooks load their sample images from https://niivue.github.io/mono/volumes/ and https://niivue.github.io/mono/meshes/, and you can use them to try things out.

From a file on disk

nv.add_volume_from_path("scans/t1.nii.gz", colormap="gray")

Python reads the file and sends its bytes to the browser, so it works for any file the kernel can read, even when the browser cannot reach it. NiiVue picks the reader from the file extension. If the file name does not end in the right one, pass the name to use, such as name="t1.nii.gz".

For very large files a URL is faster, because the bytes do not have to pass through Python.

From a NumPy array

import nibabel as nib
img = nib.load("scans/t1.nii.gz")
data = img.get_fdata().astype("float32")
nv.add_volume_from_array(data, affine=img.affine, colormap="gray")

ipyniivue wraps the array in a NIfTI image with nibabel and sends that. Without affine it uses the identity matrix. The array’s data type is kept as it is, so if an image does not appear, cast it to float32 first. This needs NumPy and nibabel, which the examples extra installs.

If you already hold the bytes of an image file, for example from a download that needs a login, send them as they are. The name tells NiiVue the format:

nv.add_volume_from_bytes("t1.nii.gz", file_bytes)

An overlay on top of a background

Each add_volume_from_... call replaces the images already loaded. To show an overlay over a background, load them together with load_volumes. It takes a list of NiiVue’s volume options as dictionaries, with camelCase keys, and the first image is the background:

base = "https://niivue.github.io/mono/volumes"
nv.load_volumes([
{"url": f"{base}/mni152.nii.gz"},
{"url": f"{base}/spmMotor.nii.gz", "colormap": "warm", "calMin": 3, "calMax": 6},
])

To add one more image without replacing the others, use nv.add_volume({"url": ...}). nv.remove_volume(1) takes the second image away and nv.remove_all_volumes() clears them all. See Overlays and thresholds for thresholds and colormap types.

Stepping through a 4D image

nv.load_volumes([{"url": f"{base}/mpld_asl.nii.gz", "id": "asl"}])
nv.set_frame_4d("asl", 2)

Frames are numbered from 0. set_frame_4d finds the image by its id, which is its URL unless you choose one when loading, as here. For a large series, "limitFrames4D": 5 loads only the first five frames.

Meshes

nv.add_mesh_from_url(
"https://niivue.github.io/mono/meshes/BrainMesh_ICBM152.lh.mz3",
color=[1, 0.7, 0.6, 1],
)

add_mesh_from_path and add_mesh_from_bytes work like their volume versions, and load_meshes loads a list. Meshes and volumes are kept apart: loading a mesh replaces the other meshes but leaves the images, so a brain surface can sit inside a scan.

To change a mesh after it loads, pass its number and the options to change:

nv.set_mesh(0, {"shaderType": "toon", "opacity": 0.8})

nv.mesh_shaders lists the shader names. See Meshes for file formats and mesh layers.