Skip to content

Getting started

View as Markdown

Install

Terminal window
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>

WebGPU or WebGL2

NiiVue uses WebGL2 by default. Ask for WebGPU with backend; if the browser can’t run it, NiiVue falls back to WebGL2:

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

In Safari, and every browser on iOS, WebGPU is about 4x slower with anti-aliasing on, so turn it off there:

const isWebKit =
/AppleWebKit/.test(navigator.userAgent) &&
!/Chrome|Chromium|Edg\//.test(navigator.userAgent)
const nv = new NiiVue({ backend: 'webgpu', isAntiAlias: !isWebKit })

To ship one renderer, import its build instead. It’s smaller, and asking it for the other backend throws:

import NiiVue from '@niivue/niivue/webgpu' // or '@niivue/niivue/webgl2'

Settings

Settings are properties. Pass them to the constructor, or change them at any time and the view redraws:

import NiiVue, { SLICE_TYPE } from '@niivue/niivue'
const nv = new NiiVue({ sliceType: SLICE_TYPE.MULTIPLANAR })
nv.isColorbarVisible = true
nv.sliceType = SLICE_TYPE.RENDER

Each volume and mesh has its own settings, changed with 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 migration table lists the renames, the API style guide lists the properties by group, and FEATURE_PARITY.md tracks what has not been ported yet.