# NiiVue > NiiVue is a JavaScript library for viewing medical images in the browser: volumes such as MRI and CT, surface meshes, tractography, connectomes and physiological signals, drawn with WebGL2 or WebGPU. It needs only a canvas and a URL to the data, and no server beyond one that serves the files. This documentation covers the rewritten NiiVue, published on npm under the `next` tag. Things to know when writing NiiVue code: - Install `@niivue/niivue@next`. A plain `npm install @niivue/niivue` gets the 0.x releases, whose API is different: code written for 0.x does not work with this version. - Settings are properties, not setter methods: `nv.sliceType = SLICE_TYPE.AXIAL`, not `nv.setSliceType(...)`. Each assignment redraws the view. - Create a viewer, attach it to a canvas, then load data: `const nv = new NiiVue(); await nv.attachToCanvas(canvas); await nv.loadVolumes([{ url }])`. - Per-image options use the same keys at load time and afterwards: `loadVolumes([{ url, colormap: 'hot' }])`, then `nv.setVolume(0, { calMin: 2 })`. Meshes work the same way with `loadMeshes` and `setMesh`. - WebGL2 is the default renderer. `new NiiVue({ backend: 'webgpu' })` uses WebGPU and falls back to WebGL2 when WebGPU is unavailable. - A viewer is an `EventTarget`: `nv.addEventListener('locationChange', (e) => e.detail)`. - DICOM is not built in: convert it in the browser with `@niivue/dcm2niix`. OME-Zarr, TIFF and tiled slides load through `@niivue/nv-ext-tile@next`. React components are in `@niivue/nvreact@next`. ## Documentation sets - [Complete docs](https://niivue.com/docs/llms-full.txt): every guide and package page below in one file ## Start here - [Getting started](https://niivue.com/docs/guide/index.md): Install NiiVue, show an image on a canvas, choose WebGL2 or WebGPU, change settings, and see what changed from NiiVue 0.x. - [Loading images](https://niivue.com/docs/guide/loading/index.md): Load volumes and meshes from URLs or local files: load options, overlays, drag and drop, supported formats, and large 4D or OME-Zarr data. ## Displaying images - [Colormaps and contrast](https://niivue.com/docs/guide/colormaps/index.md): Set contrast with calMin and calMax, choose, invert or register colormaps, and show negative values and colorbars. - [CT colormaps](https://niivue.com/docs/guide/ct/index.md): Hounsfield units and the ct_ colormaps, which carry their own display window for each tissue. - [Overlays and thresholds](https://niivue.com/docs/guide/overlays/index.md): Show statistical maps over anatomy: positive and negative thresholds, colormap types, opacity, outlines and several overlays. - [Atlases and labels](https://niivue.com/docs/guide/atlases/index.md): Display label volumes (atlases) with label colormaps, read region names under the crosshair, and use outlines, probabilistic and mesh atlases. - [Clip planes and cutaways](https://niivue.com/docs/guide/clip-planes/index.md): Cut into the 3D render with up to six clip planes: describing and setting planes, cutaways and the cut surface. ## Meshes and tracts - [Meshes and layers](https://niivue.com/docs/guide/meshes/index.md): Load triangulated surfaces, change them after loading, add scalar layers such as curvature or statistics, and combine meshes with volumes. - [Tractography and connectomes](https://niivue.com/docs/guide/tracts/index.md): Load streamlines and connectomes, color streamlines by scalars or groups, and set node and edge display options. ## Views and interaction - [Layouts and slice types](https://niivue.com/docs/guide/layout/index.md): Arrange the canvas into 2D slices and a 3D render: slice types, multiplanar options, mosaics, custom layouts and several viewers on one canvas. - [Mouse, touch and events](https://niivue.com/docs/guide/interaction/index.md): Choose what mouse drags, the wheel, touch and keys do, and listen for viewer events. - [Events](https://niivue.com/docs/reference/events/index.md): Every event a NiiVue viewer fires, when it fires, and what its detail holds. - [Linking viewers](https://niivue.com/docs/guide/sync/index.md): Link viewers with broadcastTo so the crosshair, zoom, 3D camera and clip planes follow each other. - [Drawing and segmentation](https://niivue.com/docs/guide/drawing/index.md): Paint label volumes on the slices: pen settings, appearance, undo, the magic wand, saving as NIfTI, events and vector annotations. - [Animation](https://niivue.com/docs/guide/animation/index.md): Move the camera, clip planes and other properties smoothly over time with animateTo. - [Fonts and text](https://niivue.com/docs/guide/fonts/index.md): Change the size and color of on-canvas text, switch fonts at runtime, and make new MSDF font atlases. ## Plugins - [niimath](https://niivue.com/docs/plugins/niimath/index.md): Run niimath image processing (smoothing, thresholds, masks, meshes) in the browser with @niivue/niimath and show the results in NiiVue. - [dcm2niix](https://niivue.com/docs/plugins/dcm2niix/index.md): Convert DICOM to NIfTI in the browser with @niivue/dcm2niix and show the result in NiiVue: classic series, enhanced DICOM and local files. ## Resources - [Migrating from NiiVue 0.x](https://niivue.com/docs/reference/migrating/index.md): Where each NiiVue 0.x property and setter lives in the new API. - [Projects using NiiVue](https://niivue.com/docs/projects/index.md): Tools, platforms and research projects that build on NiiVue. - [Developing NiiVue](https://niivue.com/docs/guide/develop/index.md): Set up the niivue/mono monorepo, run the example pages and checks, and work on this documentation site. ## Packages Bindings for other frameworks and languages, and extensions for jobs the core package leaves out. - [nvreact](https://niivue.com/docs/packages/nv-react/index.md): Show NiiVue viewers in a React 19 app with @niivue/nvreact: one component for a single viewer, or a scene for a grid of them. - [nvreact: One viewer](https://niivue.com/docs/packages/nv-react/one-viewer/index.md): Show images with the NvViewer component, change them with props, and respond when the user clicks. - [nvreact: Several viewers](https://niivue.com/docs/packages/nv-react/several-viewers/index.md): Lay out a grid of NiiVue viewers with a scene, load images into each one, and link them so they move together. - [nvreact: Using NiiVue directly](https://niivue.com/docs/packages/nv-react/niivue-instance/index.md): Reach the NiiVue instance behind a viewer, listen for what the user does, and share a scene with any component. - [nv-web-component](https://niivue.com/docs/packages/nv-web-component/index.md): Put NiiVue viewers on any web page with plain HTML tags: one tag for a single viewer, another for a grid of viewers. - [nv-web-component: One viewer](https://niivue.com/docs/packages/nv-web-component/one-viewer/index.md): Show images with the niivue-viewer tag, change them, adjust the view, and respond when the user clicks. - [nv-web-component: Several viewers](https://niivue.com/docs/packages/nv-web-component/several-viewers/index.md): Lay out a grid of NiiVue viewers with the niivue-scene tag, load images into each one, and link them so they move together. - [uikit](https://niivue.com/docs/packages/uikit/index.md): Draw buttons, sliders, menus, text fields and measuring tools inside a NiiVue canvas with @niivue/uikit. - [uikit: Buttons, sliders and menus](https://niivue.com/docs/packages/uikit/controls/index.md): Put buttons, toggles, sliders, menus, drop-down lists and segmented controls on a NiiVue canvas and keep them in step with the viewer. - [uikit: Text fields, files and dialogs](https://niivue.com/docs/packages/uikit/forms/index.md): Let people type numbers and text, pick a color, open and save files, and answer dialogs, all inside the NiiVue canvas. - [uikit: Rulers, crosshairs and labels](https://niivue.com/docs/packages/uikit/measuring/index.md): Draw a measuring ruler, a crosshair with a scale, or labels pinned to a point over NiiVue images and whole-slide views. - [ipyniivue](https://niivue.com/docs/packages/ipyniivue/index.md): Show a NiiVue viewer in a Jupyter notebook with ipyniivue and drive it from Python: load images, change the view and read back results. - [ipyniivue: Loading images](https://niivue.com/docs/packages/ipyniivue/loading/index.md): Load volumes and meshes into the notebook viewer from a URL, a local file, raw bytes or a NumPy array, and show overlays and 4D images. - [ipyniivue: Changing the view](https://niivue.com/docs/packages/ipyniivue/view/index.md): Switch between slices and 3D, change colors and contrast, cut into the 3D view, and add sliders and buttons that control the viewer. - [ipyniivue: Results and saving](https://niivue.com/docs/packages/ipyniivue/results/index.md): React to clicks in the notebook viewer, ask it for values, save pictures and scenes, and bring drawings and processed images back into Python. - [NiiVueKit](https://niivue.com/docs/packages/niivue-swift/index.md): Show a NiiVue viewer in a SwiftUI app on iPhone, iPad, Mac or Vision Pro, and drive it from Swift with NiiVueKit. - [NiiVueKit: The viewer page](https://niivue.com/docs/packages/niivue-swift/viewer-page/index.md): Choose where the NiiVue web page comes from, reload it live while you work on it, and fix a viewer that stays blank. - [NiiVueKit: Controlling the viewer](https://niivue.com/docs/packages/niivue-swift/controlling-the-viewer/index.md): Bind viewer settings to SwiftUI controls, load and adjust images, follow the crosshair and switch between WebGL2 and WebGPU. - [NiiVueKit: Sending your own messages](https://niivue.com/docs/packages/niivue-swift/messages/index.md): Call your own code in the web page from Swift, let the page call Swift, send events both ways, and reuse the messaging without NiiVue. - [web-bridge](https://niivue.com/docs/packages/niivue-web-bridge/index.md): The JavaScript side of the bridge that lets a SwiftUI app drive a NiiVue viewer running inside a WKWebView. - [nv-ext-tile](https://niivue.com/docs/packages/nv-ext-tile/index.md): Open huge microscopy images in NiiVue, such as whole-slide scans and OME-Zarr volumes, reading only the parts you look at. - [nv-ext-tile: Viewing slides](https://niivue.com/docs/packages/nv-ext-tile/slides/index.md): Open whole-slide images from a URL or the user's computer, pick a slide, decode JPEG 2000 tiles and set up the server they come from. - [nv-ext-tile: DICOM slides](https://niivue.com/docs/packages/nv-ext-tile/dicom/index.md): Open DICOM whole-slide images from a local folder, a DICOMweb server or your own web server, including their labels, overviews and focal planes. - [nv-ext-tile: OME-Zarr volumes](https://niivue.com/docs/packages/nv-ext-tile/ome-zarr/index.md): Load OME-Zarr stores into a NiiVue scene, one resolution level at a time or streamed piece by piece, with their channels, time points and labels. - [nv-ext-tile: Memory and bandwidth](https://niivue.com/docs/packages/nv-ext-tile/resources/index.md): The settings that bound GPU memory, CPU memory, network load and prefetch for slides and streamed volumes, what each one trades, and which policies are fixed. - [nv-ext-image-processing](https://niivue.com/docs/packages/nv-ext-image-processing/index.md): Split a volume into classes by brightness, remove background haze, reslice it to a 1 mm grid and label separate blobs, with the work done in a Web Worker. - [nv-ext-drawing](https://niivue.com/docs/packages/nv-ext-drawing/index.md): Fill in the slices between hand-drawn outlines and grow regions with a magic wand, on NiiVue's drawing layer. - [nv-ext-drawing: Filling in between slices](https://niivue.com/docs/packages/nv-ext-drawing/interpolation/index.md): Outline a structure on a few slices and let nv-ext-drawing fill the slices in between, optionally following the edges in the image. - [nv-ext-drawing: Magic wand](https://niivue.com/docs/packages/nv-ext-drawing/magic-wand/index.md): Click a voxel to paint the connected region of similar brightness, choose how similar counts, keep it on one slice, and preview it under the pointer. - [nv-ext-save-html](https://niivue.com/docs/packages/nv-ext-save-html/index.md): Save a NiiVue scene as one HTML file that anyone can open in a browser, with no server and no install. - [nv-mcp](https://niivue.com/docs/packages/nv-mcp/index.md): Let an AI agent such as Claude drive a NiiVue page a person is looking at: load images, move the crosshair, cut planes, find atlas regions and take screenshots. - [nv-mcp: Connecting agents](https://niivue.com/docs/packages/nv-mcp/connecting-agents/index.md): Connect Claude, Codex, Gemini CLI, VS Code, Cursor, Windsurf or your own program to a NiiVue MCP server, and fix a connection that does not work. - [nv-mcp: Building your app](https://niivue.com/docs/packages/nv-mcp/your-app/index.md): Tell agents what your app offers, add an atlas, labels, controls and sample data, add tools of your own, and serve the page from another address. - [nv-ohif](https://niivue.com/docs/packages/nv-ohif/index.md): Show series in the OHIF Viewer with NiiVue: multiplanar and 3D views, overlays, measurements and whole-slide images in an OHIF viewport. - [nv-ohif: What it can show](https://niivue.com/docs/packages/nv-ohif/images/index.md): Which series the NiiVue viewport in OHIF can open: NIfTI and other volume files, DICOM series converted in the browser, and whole-slide microscopy. - [nv-ohif: Toolbar and controls](https://niivue.com/docs/packages/nv-ohif/toolbar/index.md): Add NiiVue's views, clip planes, window presets, colormaps and overlays to the OHIF toolbar, and see how OHIF's tools and shortcuts drive a NiiVue viewport. - [nv-ohif: Measuring](https://niivue.com/docs/packages/nv-ohif/measurements/index.md): Use OHIF's measurement tools on a NiiVue viewport: draw lengths, regions and arrows, and see them in OHIF's Measurements panel. ## Examples - [Gallery](https://niivue.com/docs/gallery/): 82 example pages, each running live beside its source code - [Example source](https://github.com/niivue/mono/tree/main/packages/niivue/examples): the HTML and JavaScript of every example page ## Source files - [API style guide](https://raw.githubusercontent.com/niivue/mono/main/packages/niivue/notes/api.md): naming rules, every viewer property by group, and the per-volume and per-mesh option types - [Package README](https://raw.githubusercontent.com/niivue/mono/main/packages/niivue/README.md): installation, backend-only builds and standalone ES modules ## Optional - [Feature parity](https://raw.githubusercontent.com/niivue/mono/main/packages/niivue/FEATURE_PARITY.md): which NiiVue 0.x features this version has, and which are still missing