NiiVue VSCode README
WebGL 2.0 medical image viewer
This extension uses NiiVue to display images selected in VSCode.
VS Code version
The VS Code extension is published on the VS Code marketplace and can be installed via the extension tab in VS Code, searching for niivue
Browser version
The web version can be installed as a local app with file associations (only supported in Chrome)
Development
Currently my time that I can spend on this project is quite limited. I'm very happy for contributions in the form of pull requests.
Otherwise, if you would like to see a certain feature implemented, please let me know so I can prioritize the development. Either create a new issue or comment/react on an existing issue.
VS Code screenshots
List of Hotkeys
Right Mouse: Drag with the right mouse button to zoomMiddle Mouse: Drag with the right mouse button to panMouse Scroll: Change slice in currently hovered image← →: change volume in 4D imageV: Cycle through viewmodesC: Cycle through clip plane orientations in 3D rendershift: Changes mouse behaviour to 2D dragging and 3D viewplane rotationH: Move the cross to RL: Move the cross to LJ: Move the cross to PK: Move the cross to Actrl+U: Move the cross to Sctrl+D: Move the cross to I
Features
- Open local files by selecting them in the VSCode explorer
- Selecting multiple files -> right click -> NiiVue: Compare
- Open web links to files with the command "NiiVue: Open Image" (
Ctr+Shift+P)
- Open local or remote files when hovering over the link in an open editor
- Add overlays
- Works in web-based VSCode
NiiVue can open several formats popular with brain imaging:
- Voxel-based formats: NIfTI, NRRD, MRtrix MIF, AFNI HEAD/BRIK, MGH/MGZ, ITK MHD, ECAT7.
- Mesh-based formats: GIfTI, ASC, BYU/GEO/G, BrainSuite DFS, ICO/TRI, PLY, BrainNet NV, BrainVoyager SRF, FreeSurfer, MZ3, OFF, Wavefront OBJ, STL, Legacy VTK, X3D.
- Mesh overlay formats: GIfTI, CIfTI-2, MZ3, SMP, STC, FreeSurfer (CURV/ANNOT)
- Tractography formats: TCK, TRK, TRX, VTK, AFNI .niml.tract
- DICOM: DICOM and DICOM Manifests
If niivue-vscode fails to open any of these files, please create an issue.
Developing this extension in VSCode
- Fork this repository;
- Clone this repository and open in VSCode
- Run inside the
niivue-vscode folder
Installing
This project uses pnpm for package management and Turborepo for build orchestration.
pnpm install
Development Workflow
For development with live reload:
# Start the VS Code extension in watch mode
pnpm --filter @niivue/vscode watch
Debugging the extension in vscode
- Ensure the watch task is running (see above)
- Press
F5 (a new VSCode window opens: Extension Development Host)
- Test the extension in the Extension Development Host by opening an image file
- Press
Ctrl+R in the Extension Development Host for reload after a code change
Building
To build the extension:
# Build all dependencies and the extension
pnpm build
# Or build just the VS Code extension and its dependencies
pnpm --filter @niivue/vscode build
Testing
Run tests across the monorepo:
pnpm test
Publishing
Option 1: Automated Release via GitHub Actions
Tag-based release:
# Create and push a tag (replace x.y.z with actual version)
git tag vscode-vx.y.z
git push origin vscode-vx.y.z
The GitHub Action will automatically:
- Build the extension
- Publish to VS Code Marketplace
- Publish to Open VSX Registry
- Create a GitHub release
- Upload the
.vsix file as an artifact
Prerequisites:
- Repository secrets must be configured (for automated releases):
VSCE_PAT: Personal Access Token for VS Code MarketplaceOVSX_PAT: Personal Access Token for Open VSX Registry
Option 2: Manual Publishing
For manual publishing, you'll need to install the publishing tools and have the necessary access tokens:
# Install publishing tools globally
npm install -g @vscode/vsce ovsx
# Navigate to the VS Code extension directory
cd apps/vscode
# Build the extension
pnpm build
# Update version in package.json (optional - vsce can do this automatically)
# Then publish to VS Code Marketplace
vsce publish patch|minor|major [--pre-release]
# Publish to Open VSX Registry
ovsx publish --pat <openVSX access key>
Prerequisites:
