NIfTI Viewer for VS Code

View NIfTI neuroimaging files directly in VS Code — no external tools needed.

Open .nii and .nii.gz files with a single click. Compare multiple volumes side by side. Overlay segmentation masks with contour or filled rendering. Build reusable viewer templates for reproducible analysis workflows.

Highlights

• Zero-config viewing — Double-click any .nii or .nii.gz file to open it instantly
• Multi-panel layouts — Display multiple images side by side with synchronized crosshairs and slice navigation
• Overlays — Load segmentation masks and probability maps with adjustable opacity, colormaps, and contour/filled modes
• Template system — Define reusable JSON configurations for consistent viewing across datasets
• Auto-template — Right-click any folder to auto-detect NIfTI files and generate a smart template
• Findings panel — Display lesion classifications alongside the viewer with click-to-navigate
• 14+ colormaps — Including a discrete colormap with 20 maximally distinct colors for label maps
• Keyboard-driven — Full keyboard navigation for fast clinical and research workflows

Getting Started

Open a single file

Double-click any .nii or .nii.gz file in the VS Code Explorer. The viewer opens automatically.

View a folder of results

Right-click a folder containing NIfTI files and select:

• NIfTI: Generate Template from Files — auto-detects images, overlays, and masks
• NIfTI: Open with Template — use a pre-defined template

Add overlays interactively

Press Shift+O to add an overlay (segmentation mask, probability map) on top of the current image. Press Shift+F to add another image side by side.

Template System

Templates are JSON files that define multi-panel viewer configurations. Place them in any of these locations (highest priority last):

1. ~/.viewer/templates/ — global templates
2. <workspace>/.viewer/templates/ — project templates
3. <folder>/.viewer/templates/ — folder-specific templates

Example template

{
  "version": 1,
  "name": "Lesion Review",
  "viewer": {
    "view": "axial",
    "alpha": 0.7,
    "crosshairColor": "#00ff00",
    "showOverlay": true
  },
  "panels": [
    {
      "title": "T1c Follow-up",
      "image": "fwup_preproc_n4.nii.gz",
      "imageCmap": "gray"
    },
    {
      "title": "T1c + Lesions",
      "image": "fwup_preproc_n4.nii.gz",
      "overlay": "lesion_numbered.nii.gz",
      "overlayCmap": "rainbow",
      "overlayMode": "contour"
    },
    {
      "title": "T1c + Vessels",
      "image": "fwup_preproc_n4.nii.gz",
      "overlay": "vessel_fm_prob.nii.gz",
      "overlayCmap": "hot",
      "overlayMode": "filled"
    }
  ],
  "grid": [[0, 1, 2]],
  "findings": "lesion_numbered_clf.json"
}

Panel fields

Viewer settings

Grid layout

The grid field controls panel arrangement. Each inner array is a row:

"grid": [[0, 1], [2, 3]]   // 2x2 grid
"grid": [[0, 1, 2]]         // single row, 3 columns
"grid": [[0], [1]]           // single column, 2 rows

Findings panel

Set "findings": "classification.json" to display a classification sidebar. The JSON should contain a findings array with objects having id_json_nel, pred_class, and lesion_volume fields. Click any finding to navigate to its location.

Colormaps

Keyboard Shortcuts

Views

Display

Navigation

Panels

Building from Source

git clone https://github.com/tensormedical/nifti-viewer-vscode
cd nifti-viewer-vscode
npm install
npm run build

Press F5 in VS Code to launch the Extension Development Host.

License

MIT