Skip to main content

Getting started

NiiVue is an all-in-one package for parsing, loading, and viewing medical imaging data directly in the browser. Its modular design allows you to embed interactive visualizations into your pages using any framework—such as Angular, Vue, or React—or even as pure HTML. Below is an example of NiiVue embedded in a Docusaurus MDX page using a custom React component:

Loading...

Installation​

To install NiiVue, you can use your favorite package manager (npm, pnpm, yarn, etc.):

npm install @niivue/niivue

Usage​

Basic - No framework​

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>NiiVue</title>
  </head>
  <body>
    <canvas id="gl" width="640" height="640"></canvas>
  </body>
  <script type="module" async>
    import { Niivue } from "https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js"
    var volumeList = [
      { url: "https://niivue.github.io/niivue-demo-images/mni152.nii.gz" },
    ];
    var nv = new Niivue({ isResizeCanvas: false });
    await nv.attachTo("gl");
    await nv.loadVolumes(volumeList);
  </script>
</html>

React​

import { useRef, useEffect } from "react";
import { Niivue } from "@niivue/niivue";

const NiiVue = ({ imageUrl }) => {
  const canvas = useRef();
  const nvRef = useRef();
  useEffect(() => {
    const volumeList = [
      {
        url: imageUrl,
      },
    ];
    async function setupAndLoad() {
      const nv = new Niivue();
      nv.attachToCanvas(canvas.current);
      await nv.loadVolumes(volumeList);
      const nvRef.current = nv
    }
    setupAndLoad()
  }, [imageUrl]);

  return <canvas ref={canvas} height={480} width={640} />;
};

// use as: <NiiVue imageUrl={someUrl}> </NiiVue>

Vue​

<script>
import {Niivue} from '@niivue/niivue'
const nv = new Niivue()


export default {
  name: 'App',
  props: {

  },
  data(){
    return {
      volumeList: [
        {
          url: "./mni152.nii.gz",
        }
      ]

    }
  },

  mounted() {
    nv.attachTo('gl')
    await nv.loadVolumes(this.volumeList)
  }
}

</script>

<template>
<canvas id="gl" height="480" width="640">
</canvas>
</template>

Angular​

import { Component, OnInit, ViewChild } from "@angular/core";

import { Niivue } from "@niivue/niivue";

@Component({
  selector: "app-niivue-view",
  templateUrl: "./niivue-view.component.html",
  styleUrls: ["./niivue-view.component.sass"],
})
export class NiivueViewComponent implements OnInit {
  @ViewChild("gl") canvas: HTMLCanvasElement | undefined;

  constructor() {}

  ngOnInit(): void {
    const url = "/assets/mni152.nii.gz";
    const volumeList = [
      {
        url,
      },
    ];
    const niivue = new Niivue();
    niivue.attachTo("gl");
    await niivue.loadVolumes(volumeList);
  }
}

Limitations​

NiiVue is a graphical visualization tool and therefore cannot be used as a command-line utility in Node.js environments. It is designed to be embedded in a web browser window. However, as demonstrated in the end-to-end regression tests, NiiVue can run headlessly using Playwright to render a WebGL canvas and save a screenshot to disk.