Skip to content

One viewer

View as Markdown

<niivue-viewer> is a single viewer. You give it a list of images, and it keeps the viewer in step with that list.

Showing images

Set volumes to a list. The first image is the background and the rest are drawn on top of it, in order:

import { SLICE_TYPE } from '@niivue/nv-web-component'
viewer.volumes = [
{ url: '/volumes/mni152.nii.gz' },
{ url: '/volumes/spmMotor.nii.gz', colormap: 'warm', calMin: 3, calMax: 6 },
]
viewer.sliceType = SLICE_TYPE.MULTIPLANAR

Each entry takes the same settings as NiiVue’s loading options. Without sliceType the viewer shows a single axial slice. In HTML, the slice-type attribute takes the same number, for example slice-type="3" for multiplanar.

Changing images

Assign a new list and the viewer follows. Images are matched by URL: new ones are loaded, missing ones are removed, and the order is updated to match the list.

viewer.volumes = [{ url: '/volumes/mni152.nii.gz', colormap: 'hot' }]

A change to colormap, calMin, calMax or opacity is applied without loading the image again. Other settings are only read when an image is first loaded. Always assign a new list: changing the old one in place is not noticed.

viewer.volumes = [] clears the viewer.

Opening a file from the user’s computer

A File works in place of a URL, for example one picked with a file input:

const input = document.querySelector('input[type="file"]')
input.addEventListener('change', () => {
const file = input.files?.[0]
if (file) viewer.volumes = [{ url: file }]
})

The viewer then matches that image by its file name.

Settings for when the viewer starts

options takes the same settings as new NiiVue(options). The viewer reads them once, when it starts, so set them before the element goes on the page. Building the element in code makes that easy:

const viewer = document.createElement('niivue-viewer')
viewer.options = { backgroundColor: [1, 1, 1, 1], isColorbarVisible: true }
viewer.style.height = '500px'
document.body.append(viewer)

Changing options later does nothing.

Adjusting the view

The viewer has methods for the common changes. The first number is the image’s position in the list, starting at 0:

await viewer.setColormap(0, 'hot')
await viewer.setOpacity(1, 0.5)
await viewer.setCalMinMax(0, 20, 120)

These do nothing until that image has loaded. Other methods change the whole viewer:

import { DRAG_MODE } from '@niivue/nv-web-component'
viewer.setColorbarVisible(true)
viewer.setCrosshairVisible(false)
viewer.setPrimaryDragMode(DRAG_MODE.pan)

setPrimaryDragMode sets what a left-button drag does and setSecondaryDragMode the right button. Out of the box, the left button moves the crosshair and the right one pans. Mouse, touch and events lists every drag mode.

Responding to the user

The viewer sends ordinary DOM events, with the useful part in event.detail:

viewer.addEventListener('location-change', (event) => {
console.log(event.detail.string)
})
viewer.addEventListener('image-loaded', (event) => {
console.log('loaded', event.detail.name)
})
viewer.addEventListener('niivue-error', (event) => {
console.error(event.detail)
})

location-change fires when the crosshair moves. Its detail holds the position in millimeters and voxels, each image’s value there, and a ready-made text readout in string. Events lists every field. The events bubble, so a listener on a parent element hears them too.

Using NiiVue directly

For everything else, such as drawing, meshes or saving the scene, use the NiiVue instance behind the viewer. It is viewer.nv:

viewer.addEventListener('image-loaded', () => {
viewer.nv.isRadiological = true
})

viewer.nv is null until the element has first rendered, so the image-loaded event is a safe place to start using it. All of the NiiVue guides apply to it.