Skip to content

Loading images

View as Markdown

NiiVue loads volumes with loadVolumes. Pass it an array of options objects, one per volume. The only required field is url.

await nv.loadVolumes([{ url: '/volumes/mni152.nii.gz' }])

loadVolumes replaces whatever was loaded before. The old volumes stay on screen until the new ones are ready, so switching images does not flash a blank canvas. Pick another image below to see it:

Volume options

Each entry can set its display options at load time. These are the same keys that setVolume takes later, so you load and adjust with one vocabulary:

Option What it does
url A URL string or a File
name Display name (defaults to the file name)
colormap Colormap name, 'Gray' by default. See Colormaps
calMin, calMax The intensity window mapped onto the colormap
opacity 0 to 1
visible Hide a volume without changing its opacity
isColorbarVisible Whether this volume gets a colorbar
urlImageData The data file for formats with a separate header, such as AFNI .HEAD/.BRIK
limitFrames4D Load only the first N frames of a 4D series

Several volumes

The first volume in the list is the background, and it sets the space the scene is drawn in. Every later volume is an overlay: it is resampled onto the background grid and drawn on top of it.

To append one volume without replacing the rest, use addVolume:

await nv.addVolume({ url: '/volumes/spmMotor.nii.gz', colormap: 'warm' })

Overlays and thresholds covers statistical maps in depth.

Meshes

Meshes load the same way, with loadMeshes, and can share the scene with volumes:

await nv.loadMeshes([
{ url: '/meshes/BrainMesh_ICBM152.lh.mz3', color: [1, 0.8, 0.6, 1] },
])

Like loadVolumes, it replaces the meshes already loaded; addMesh appends one. See Meshes and layers for layers and shaders.

Local files and drag and drop

Any url can be a File instead of a string. That is how you load from an <input type="file">:

input.onchange = async () => {
const file = input.files?.[0]
if (file) await nv.loadVolumes([{ url: file }])
}

If you do not know whether a file is a volume, a mesh or a signal, call nv.loadImage(file). It picks the loader from the file extension.

Drag and drop is on by default. Drop a file on the canvas and NiiVue loads it with loadImage, replacing what was shown. A dropped .nvd document goes to loadDocument, and a .json sidecar dropped together with its data file is paired with it. To turn it off:

nv.isDragDropEnabled = false

Supported formats

Volumes: NIfTI (.nii, .nii.gz), NRRD, MRtrix MIF, AFNI HEAD/BRIK, MGH/MGZ, ITK MHD/MHA, ECAT7, DSI Studio FIB/SRC, BMP, V16, VMR, NPY/NPZ, TIFF (including OME-TIFF and ImageJ stacks) and the Allen JSON+PNG atlas. OME-Zarr loads through @niivue/nv-ext-tile/zarr.

Meshes: GIfTI, FreeSurfer, PLY, STL, OBJ, VTK, MZ3, OFF, GEO/BYU, BrainSuite DFS, ICO/TRI, BrainNet NV, BrainVoyager SRF, X3D, ASC, WRL and IWM. Tractography: TCK, TRK, TRX, TT, TSF, VTK lines and AFNI .niml.tract (binary).

DICOM is not built in: see DICOM files below. The MINC and VOX loader plugins from NiiVue 0.x have not been ported.

DICOM files

NiiVue does not read DICOM directly. The @niivue/dcm2niix package runs dcm2niix (compiled to WebAssembly) in the browser and returns NIfTI series you can load:

Terminal window
npm install @niivue/dcm2niix
import { convert } from '@niivue/dcm2niix'
// <input id="dicomFolder" type="file" webkitdirectory multiple />
input.addEventListener('change', async () => {
// A nonzero exit still returns the series that converted.
const { series } = await convert(input.files)
await nv.loadVolumes([{ url: series[0].image }])
})

Each series also carries its json sidecar and any bval/bvec. For a dropped folder, filesFromDataTransfer(e.dataTransfer.items) collects the files first; listSeries lists series without converting them. The Dcm2niix class gives full control over the dcm2niix flags:

import { Dcm2niix } from '@niivue/dcm2niix'
const dcm2niix = new Dcm2niix()
await dcm2niix.init()
const result = await dcm2niix.input(files).compressionLevel(9).bids('n').run()

See dcm2niix for a live demo and more options.

Large data

limitFrames4D opens a long 4D series partially: NiiVue reads the header and the first frames only. The Timeseries example uses it.

OME-Zarr stores load one pyramid level at a time. loadOmeZarrVolumes (from @niivue/nv-ext-tile/zarr) returns ordinary volume options for loadVolumes:

import { loadOmeZarrVolumes } from '@niivue/nv-ext-tile/zarr'
const volumes = await loadOmeZarrVolumes(storeUrl, { level: 2 })
await nv.loadVolumes(volumes)

Stores too large to load whole stream brick by brick with streamOmeZarr(nv, storeUrl) (through nv.loadChunkedVolume), with finer levels near the crosshair. These pages show the streaming paths: