NiiVue for VS Code

WebGL 2.0 medical image viewer for Visual Studio Code

A VS Code extension that uses NiiVue to display neuroimaging files directly in VS Code. View NIfTI files, meshes, tractography, and DICOM images with an interactive, hardware-accelerated viewer. Works seamlessly in remote sessions (SSH, WSL, containers) - especially useful for analyzing data on clusters and servers.

Installation

Install from the VS Code Marketplace:

1. Open VS Code Extensions (Ctrl+Shift+X)
2. Search for "niivue" and install

Or install from the command line:

code --install-extension KorbinianEckstein.niivue

Usage

Opening Files

1. Explorer: Simply click any supported neuroimaging file in the VS Code Explorer
2. Compare Multiple Files: Select multiple files in Explorer, right-click → "NiiVue: Compare"
3. Add Overlays: Click the Overlay menu

Remote Development

NiiVue works with VS Code's remote development features:

• SSH: View images on remote servers without downloading
• WSL: Access Windows Subsystem for Linux files
• Containers: Work with images inside Docker containers
• Codespaces: Use in GitHub Codespaces environments
• Web Version: Works in vscode.dev and github.dev

Screenshots

Keyboard Shortcuts

All keyboard shortcuts are displayed in menus and button tooltips throughout the interface. Hover over any button or menu item to see its shortcut.

Mouse Controls

• Right Mouse: Adjust contrast/brightness (windowing); with Zoom button pressed: drag to zoom
• Middle Mouse: Drag to pan
• Mouse Scroll: Change slice in currently hovered image
• Shift + Mouse: 2D dragging and 3D viewplane rotation

Core NiiVue Shortcuts (Built-in)

These shortcuts are handled by the niivue.js library and cannot be customized:

Navigation:

• ← →: Change volume in 4D images
• V: Cycle through view modes
• C: Cycle through clip plane orientations in 3D render

Crosshair Movement:

• H: Move crosshair to R (Right)
• L: Move crosshair to L (Left)
• J: Move crosshair to P (Posterior)
• K: Move crosshair to A (Anterior)
• Ctrl+U: Move crosshair to S (Superior)
• Ctrl+D: Move crosshair to I (Inferior)
• Shift+U/Shift+D: Superior/Inferior (browser-friendly; Ctrl+U/D is intercepted by browsers)

UI Shortcuts (Customizable)

These shortcuts can be customized in VS Code's Keyboard Shortcuts editor (File → Preferences → Keyboard Shortcuts, search for "NiiVue"):

View Modes:

• 1: Axial view
• 2: Sagittal view
• 3: Coronal view
• 4: Render view
• 5: Multiplanar + Render view
• R: Reset view/zoom

Display Toggles:

• I: Toggle interpolation
• B: Toggle colorbar
• X: Toggle radiological convention
• M: Toggle crosshair visibility
• Z: Toggle zoom drag mode
• U: Cycle UI visibility (Show All → Hide UI → Hide All)

Actions:

• Ctrl+Shift+O (Cmd+Shift+O on Mac): Add image
• Ctrl+L (Cmd+L on Mac): Add overlay
• S: Open colorscale menu
• Ctrl+Shift+H (Cmd+Shift+H on Mac): Show header information

Tip: You can view all available shortcuts in the NiiVue menu bar at the top of the viewer, or by opening the VS Code Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and typing "NiiVue".

Supported Formats

• Voxel-based: NIfTI (.nii, .nii.gz), NRRD (.nrrd, .nhdr), MRtrix MIF (.mif), AFNI HEAD/BRIK, MGH/MGZ, ITK MHD (.mhd, .mha), ECAT7 (.v), DICOM (.dcm)
• Mesh-based: GIfTI (.gii), FreeSurfer (pial, white, inflated), MZ3 (.mz3), STL (.stl), Wavefront OBJ (.obj), PLY (.ply), BrainSuite DFS (.dfs), Legacy VTK (.vtk), X3D (.x3d), and others (ASC, BYU, GEO, ICO, TRI, OFF, SRF, NV)
• Mesh Overlays: GIfTI (.gii), CIfTI-2 (.nii), MZ3 (.mz3), FreeSurfer (CURV, ANNOT), SMP, STC
• Tractography: TCK (.tck), TRK (.trk), TRX (.trx), VTK (.vtk), AFNI (.niml.tract)

Web Version

A standalone web version is also available that can be installed as a Progressive Web App with file associations (Chrome/Edge only).

Troubleshooting

"Failed to load image: unable to get WebGL context" (Linux)

This viewer needs a WebGL2 context. If the editor cannot create one you will see "unable to get WebGL context. Maybe the browser doesn't support WebGL2." This is an environment / GPU issue, not a problem with the file, and it is most common on Linux.

Cause. Recent Chromium versions (the engine inside VS Code; WebGL context creation starts failing from around Chromium 144) no longer fall back to software WebGL automatically. When the webview has no working hardware WebGL2 - common with the snap build of VS Code, missing or blocklisted GPU drivers, or some Wayland setups - WebGL2 becomes unavailable. The same extension version works on Windows because Windows has a separate software fallback (Direct3D WARP) that is not affected.

Recommended fix (restore hardware acceleration).

• If VS Code was installed as a snap, reinstall the official .deb / apt build; snap confinement often blocks GPU access.
• Make sure GPU drivers are installed; on Wayland, trying an X11 session can also help.

Temporary workaround (software rendering). Re-enable Chromium's software renderer. Open the Command Palette, run Preferences: Configure Runtime Arguments, add the following to argv.json, then fully restart VS Code:

{
  "enable-unsafe-swiftshader": true
}

This renders in software: it works, but 3D is slower. Note that this Chromium flag is officially temporary and may be removed in a future release, so prefer the hardware-acceleration fix where possible.

For details and to report your environment, see [issue #236](https://github.com/niivue/niivue-vscode/issues/236).

Development

This extension is part of the niivue-vscode monorepo. Contributions are welcome!

For development instructions, see DEVELOPMENT.md.

If you encounter issues or have feature requests, please open an issue on GitHub.

Support This Project

If you find this extension useful, please consider supporting its development:

License

BSD-2-Clause

Credits

• Built with NiiVue
• Initial development at the Neurodesk team. Neurodesk is a flexible and scalable data analysis environment for reproducible neuroimaging

Related Projects

• NiiVue JupyterLab Extension - NiiVue for JupyterLab
• NiiVue - The core NiiVue library
• NiiVue Web App - Offline NiiVue viewer