Skip to main content

Getting started

NiiVue shows volumes, meshes, tractography and signals in the browser. It renders with WebGPU or WebGL2 and needs no server beyond something that can serve your files.

Install​

npm install @niivue/niivue@next

A first viewer​

Add a <canvas>, attach a viewer to it, and load an image:

<canvas id="gl1"></canvas>
<script type="module">
  import NiiVue from '@niivue/niivue'

  const nv = new NiiVue()
  await nv.attachToCanvas(document.getElementById('gl1'))
  await nv.loadVolumes([{ url: '/volumes/mni152.nii.gz' }])
</script>

The viewer fills its canvas, so size the canvas (or its parent) with CSS. The same few lines run live here:

import NiiVue from '@niivue/niivue'

const demo = async (canvas, { asset }) => {
  const nv = new NiiVue()
  await nv.attachToCanvas(canvas)
  await nv.loadVolumes([{ url: asset('volumes/mni152.nii.gz') }])
  return nv
}

export default demo

Every demo on this site is a small module: it receives a canvas and returns the viewer, and the code under each one is the code that runs. The Gallery has every example page from the repository with its source.

WebGPU or WebGL2​

@niivue/niivue includes both renderers and uses WebGL2 by default. Ask for WebGPU with the backend option; if the browser has no WebGPU, or it fails to start, NiiVue falls back to WebGL2:

const nv = new NiiVue({ backend: 'webgpu' })

Backend-only builds are smaller:

import NiiVueWebGPU from '@niivue/niivue/webgpu'
import NiiVueWebGL2 from '@niivue/niivue/webgl2'

In a backend-only build, asking for the missing backend throws.

Settings are properties​

Viewer settings are plain properties. Set them in the constructor or at any time later, and the view redraws:

const nv = new NiiVue({ isColorbarVisible: true, sliceType: 3 })
nv.backgroundColor = [0.2, 0.2, 0.2, 1]
nv.sliceType = 4 // render only

Per-volume and per-mesh settings go through setVolume and setMesh:

nv.setVolume(0, { colormap: 'hot', calMin: 2, calMax: 6 })

Coming from NiiVue 0.x​

This package is a rewrite. Most features carry over, but the API is different: setter methods such as setSliceType(v) became properties such as nv.sliceType = v. The API reference lists the renames, and FEATURE_PARITY.md tracks what has not been ported yet.