Getting started
Install
npm install @niivue/niivue@nextpnpm add @niivue/niivue@nextyarn add @niivue/niivue@nextbun add @niivue/niivue@nextA 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>import NiiVue from '@niivue/niivue'import { useEffect, useRef } from 'react'
export function Viewer({ url }: { url: string }) { const canvasRef = useRef<HTMLCanvasElement>(null) const nvRef = useRef<NiiVue>(null)
useEffect(() => { const canvas = canvasRef.current if (!canvas) return const nv = new NiiVue() nvRef.current = nv const attached = nv.attachToCanvas(canvas) return () => { attached.then(() => nv.destroy()) } }, [])
useEffect(() => { nvRef.current?.loadVolumes([{ url }]) }, [url])
return <canvas ref={canvasRef} />}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 = truenv.sliceType = SLICE_TYPE.RENDEREach 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.