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
- File Browser: Simply double-click any supported neuroimaging file in the JupyterLab file browser
- Right-click Menu: Right-click on a file and select "Open With" → "NiiVue Viewer"
- 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:
- Check that the file format is supported (see list above)
- Try right-clicking the file and selecting "Open With" → "NiiVue Viewer"
- 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
1 maintainer
Release files for jupyterlab-niivue 0.2.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| jupyterlab_niivue-0.2.7.tar.gz | 3.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| jupyterlab_niivue-0.2.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 10.8 MB
Release files / jupyterlab_niivue-0.2.7.tar.gz
| Download URL | jupyterlab_niivue-0.2.7.tar.gz |
|---|---|
| Size | 3.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6dc15ed3a7c83f725c4c0938b77ec69ab044972c8df33afb7dba3360beae9c0b
|
|
BLAKE2b-256 checksum How to use checksums |
99fbb638fc41f4b4302dcbfc11f09071f594e5109d8d38497392023df6b7382c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Release files / jupyterlab_niivue-0.2.7-py3-none-any.whl
| Download URL | jupyterlab_niivue-0.2.7-py3-none-any.whl |
|---|---|
| Size | 7.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
192d71973065358fd6151ad2c6fef2e207275d3323f175e682ab7d30686b33a7
|
|
BLAKE2b-256 checksum How to use checksums |
d1c755e53845b18d38ac09f9290d4ba798bc33c2a941e15cdb4d0930bc39c69e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
