dive-mri 2.0.0

DiVE

Diffusion Visualization and Explorer
Explore usage »

Report Bug · Request Feature

About The Project

Diffusion Visualization and Explorer (DiVE) is a command-line tool for visualizing diffusion MRI and medical imaging data. It supports tractography (TRK, TCK, TRX, TinyTrack), NIfTI masks, and VTK meshes, which can be displayed individually or overlaid with anatomical slices and a 3D glass brain. DiVE provides streamline coloring by orientation, labels, or along-tract statistics, supports linear and non-linear spatial transformations (ANTs/DSI Studio), and enables interactive visualization as well as high quality image and video export for presentations and publications.

Demo

A 360° rotation exported with DiVE's movie mode:

Prefer full quality? Watch it here: ▶ dive_movie.mp4

Getting Started

Requirements

Installation

Using pip:

pip install dive-mri

Using Bioconda:

conda config --add channels bioconda
conda install bioconda::dive-mri

# Opens a 3D window with a glass brain + MNI T1 slice
dive --brain_2d --mode interactive

# CLI
dive --glass_brain --mode cli --background 1 --output .

Modes

DiVE has one entry point (dive) and three rendering modes selected via --mode. The same data-loading pipeline runs in every mode; only where the frames go changes.

dive --mode interactive   # Default, open a 3D window with GUI
dive --mode cli           # Render PNGs to disk and exit
dive --mode movie         # Create movie

Usage

# Interactive mode: along-tract segments (CST_R) mask colored by CSV statistics, (color map RdBu_r, min/max to ±5, segments with p > 0.05 grayed out and a white-background glass brain)
dive --mask resources/meta_CST_R_15_segments.nii.gz \
     --stats_csv resources/stat_template.csv --map RdBu_r --threshold 0.05 \
     --value_range -5 5 --tract resources/CST_L.trk --tract_width 5 \
     --mode interactive --glass_brain --background 1

# Movie mode: two meshes (IFOF_R in green, AF_L in red) + along-tract segments (CST_L) mask + a CST_R TinyTrack bundle → a 16 s, 1080p rotation written to resources/dive_movie_1.mp4
dive --mesh resources/IFOF_R.vtk resources/AF_L.vtk --mesh_colors green red \
     --mask resources/meta_CST_L_15_segments.nii.gz \
     --tract resources/CST_R.tt.gz --tract_width 5 \
     --glass_brain --mode movie --background 1 \
     --output resources/dive_movie_1.mp4 \
     --movie_duration 16 --movie_fps 30 --movie_size 1920x1080

Transforms — subject ↔ MNI, on the fly (data on disk is never modified):

# DSI Studio, subject → MNI (the warp already includes the affine)
dive --tract subject.tt.gz --glass_brain --background 1 \
     --warp 1Warp.nii.gz --warp_source dsi_studio --warp_ref MNI_QA.nii.gz

# ANTs, subject → MNI (inverse affine + inverse warp)
dive --tract subject.tt.gz --glass_brain --background 1 \
     --transform 0GenericAffine.mat --inverse \
     --warp 1InverseWarp.nii.gz --warp_source ants

CLI Options

Run dive --help for the full list. Grouped reference below.

UI Interaction

1. Choose Type: Use the ROI type (Mask/Mesh/Tract/Brain) to open the drop-down of all files of that type, and select the one you want.
2. Change View: Click the buttons to switch to Sagittal / Coronal / Axial view.
3. Choose Slice: Change the brain slice value for the selected view (requires a --brain_2d file).
4. Change Opacity (Streamlines, Mask, Mesh, Slice): Use the sliders to change the opacity of the selected file.
5. Add Button: To add more items, click the add (+) button and choose the type of file to add.
6. Remove Button: To remove a file, select it via Choose Type, then click the remove (−) button.

Mouse: left-drag rotates, middle-drag pans, scroll zooms. R resets the camera, S/W toggle surface/wireframe. The full control panel is shown on the right in the overview above.

Contributing

Bug reports and feature requests are welcome via the issue tracker. For code contributions, fork the repo, create a feature branch, and open a pull request against main.

Acknowledgments

• Siddharth Narula, Iyad Ba Gari, Shruti P. Gadewar, Sunanda Somu, Neda Jahanshad, "Diffusion Visualization Explorer (DiVE)" Organization for Human Brain Mapping (OHBM 2024) June 26, 2024

• Iyad Ba Gari, Shayan Javid, Alyssa H. Zhu, Shruti P. Gadewar, Siddharth Narula, Abhinaav Ramesh, Sophia I. Thomopoulos et al. "Along-Tract Parameterization of White Matter Microstructure using Medial Tractography Analysis (MeTA)." In 2023 19th International Symposium on Medical Information Processing and Analysis (SIPAIM), pp. 1-5. IEEE, 2023.