Home
open-dive is a command-line utility designed to simplify the visualization of medical imaging data stored in NIfTI (.nii or .nii.gz) format. With open-dive, users can extract slices from 3D or 4D medical images and render them interactively or save them as PNG files for further use.
This tool is part of a larger project or library and offers flexible options for visualization, including slice orientation, output resolution, and intensity value range adjustments.
To use open-dive, ensure that you have the required dependencies installed. Follow these steps to set up the environment:
- Install Python
Ensure that Python is installed on your system. We recommend using a virtual environment such as uv or conda. Then, install the package using:
pip install open-diveThe open-dive utility provides an easy-to-use command-line interface. Below are the available options and examples.
open-dive -n [NIfTI file path] [OPTIONS]| Argument | Type | Default | Description |
|---|---|---|---|
-h, --help
|
flag | None | Show help message and exit |
-n, --nifti_path
|
str | None | Path to scalar-valued NIFTI to plot (3D or 4D). If 4D, --volume_idx must be provided. |
-s, --slice
|
str or int | "m" |
Slice index to display, or "m" for middle slice |
-o, --orientation
|
str | "axial" |
Orientation to plot: "axial", "sagittal", or "coronal"
|
--value_range |
two floats | image min/max | Value range for plotting scalar data |
--volume_idx |
int | None | 4D volume index of the NIFTI to display |
--interpolation |
str | "nearest" |
Interpolation method: "nearest" or "linear"
|
--scalar_colorbar |
flag | False |
Show scalar colorbar |
--glass_brain |
str (path) | None | Binary mask path to overlay glass brain |
| Argument | Type | Default | Description |
|---|---|---|---|
--tractography_path |
list of str | None | Tractogram(s) to plot (.trk or .tck) |
--tractography_values |
list of float | None | Values for coloring each tractogram (must match number of tractography files) |
--tractography_cmap |
str |
"plasma" (if values provided) / "Set1"
|
Colormap for tractography. Use "rgb_standard" or "boys_standard" to color by orientation of streamlines. |
--tractography_cmap_range |
two floats | (0, 1) |
Range for tractography colormap |
--tractography_color_by_endpoints |
flag | False |
If using "rgb_standard"/"boys_standard" colormaps, will only color by direction of difference between streamline endpoints. |
--tractography_opacity |
list of float | [0.6] |
Opacity of tractograms (range (0, 1]) |
--tractography_colorbar |
flag | False |
Show tractography colorbar |
| Argument | Type | Default | Description |
|---|---|---|---|
--tensor_path |
str (path) | None | Path to tensor image (Dxx, Dxy, Dyy, Dxz, Dyz, Dzz format) |
--odf_path |
str (path) | None | Path to ODF image in spherical harmonics |
--sh_basis |
str | "descoteaux07" |
Spherical harmonics basis: "descoteaux07" or "tournier07". See https://docs.dipy.org/dev/theory/sh_basis.html for more information |
--scale |
float | 1 |
Scale of tensor or ODF glyphs relative to scalar image |
| Argument | Type | Default | Description |
|---|---|---|---|
--size |
two ints | (600, 400) |
Window size in pixels |
--zoom |
float | 1 |
Zoom value (must be positive, zoom in if > 1, zoom out if < 1) |
--save_path |
str (path) | None | Output path to save image |
--headless |
flag | False |
Run without displaying interactive window |
--azimuth, --az
|
float | None | Azimuth angle for the camera view |
--elevation, --el
|
float | None | Elevation angle for the camera view |
- Save coronal slice to a file without viewing interactively:
open-dive -n t1.nii.gz -s 50 -o coronal --save_path slice_50_coronal.png --headless
- Customize size and intensity range with colorbar:
open-dive -n dwi.nii.gz --size 800 600 --value_range 0 1500 --scalar_colorbar --volume_idx 1
- Show tractography on a colormap
open-dive -n fa.nii.gz --tractography_path my_tractogram1.trk my_tractogram2.trk --tractography_values -0.5 0.7 --tractography_cmap_range -1 1 --tractography_cmap plasma
- Show tensors and a glass brain
open-dive -n dwi.nii.gz --volume_idx 0 --tensor_path tensor.nii.gz --glass_brain_path mask.nii.gz -o sagittal --az 45 --el 60 -scale 2 --interactive
| Error | Cause | Solution |
|---|---|---|
FileNotFoundError |
Input NIfTI file path is incorrect or file missing. | Ensure the file exists and the path is correct. |
ImportError |
Required libraries are not installed. | Install dependencies using pip. |
| Image is not displayed | Missing display capability in the environment. | Use a system with GUI support or save the output. Make sure you use the --interactive flag. |
ValueError: Invalid range |
Incorrect --value_range arguments. |
Ensure range is within the NIfTI’s intensity values. |
If issues persist, refer to the project documentation or open an issue on the project’s GitHub page.
By following these guidelines, you can easily render and save 2D representations of NIfTI images with open-dive.