jupyterlab-niivue 0.2.5

A JupyterLab extension for viewing NIfTI files with Niivue

JupyterLab NiiVue

WebGL 2.0 medical image viewer for JupyterLab

A JupyterLab extension that uses NiiVue to display neuroimaging files directly in JupyterLab. View NIfTI files, meshes, tractography, and DICOM images with an interactive, hardware-accelerated viewer integrated into your JupyterLab environment.

Installation

Install the extension using pip:

pip install jupyterlab-niivue

Usage

Opening Files

1. File Browser: Simply double-click any supported neuroimaging file in the JupyterLab file browser
2. Right-click Menu: Right-click on a file and select "Open With" → "NiiVue Viewer"
3. Compare Multiple Files: Select multiple files (2 or more), right-click, and choose "Compare in NiiVue" to view them side-by-side in a multi-panel layout

Screenshots

Keyboard Shortcuts

Mouse Controls

• Right Mouse: Drag to adjust contrast/brightness (windowing); when Zoom button is 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

Navigation

• ← →: Change volume in 4D image
• 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)

Supported Formats

NiiVue can open several formats popular with brain imaging:

• 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), NumPy (.npy, .npz)
• 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)

Requirements

• JupyterLab >= 4.0.0
• A modern web browser with WebGL 2.0 support (Chrome, Firefox, Edge, Safari)

Troubleshooting

Extension not appearing

If the extension doesn't appear after installation, try:

jupyter labextension list

You should see jupyterlab-niivue in the list. If not, try rebuilding JupyterLab:

jupyter lab build

Files not opening

If files don't open when double-clicked:

1. Check that the file format is supported (see list above)
2. Try right-clicking the file and selecting "Open With" → "NiiVue Viewer"
3. Check the browser console for any error messages

Development

This extension is part of the NiiVue monorepo. Contributions are welcome!

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 through a financial contribution:

License

BSD-2-Clause

Credits

• Built with NiiVue
• Part of Neurodesk, a flexible and scalable data analysis environment for reproducible neuroimaging
• Part of the NiiVue ecosystem for neuroimaging visualization

Related Projects

• NiiVue VS Code Extension - NiiVue for Visual Studio Code
• NiiVue - The core NiiVue library
• NiiVue Web App - Online NiiVue viewer