dive-mri 1.0.0

The Diffusion Visualization Explorer (DiVE) Tool

DiVE

Diffusion Visualization and Explorer
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. UI Interaction
4. Usage CLI
5. Usage GUI
6. Contributing
7. Contact
8. Acknowledgments

About The Project

Diffusion Visualization and Explorer (DiVE) is a tool designed for visualizing medical imaging data. It allows users to visualize tractography in various formats (TRK, TCK, VTK), binary masks in NIfTI format, and meshes in VTK format. Users also have the flexibility to load multiple Regions of Interest (ROIs) in different combinations, whether they are exclusively of one type (mesh, mask, or tract) or a combination of types. Additionally, users can toggle between 3D visualization and saving the output by specifying a designated path.

(back to top)

Built With

(back to top)

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

Linux and Windows are supported, but we recommend Linux for performance and compatibility reasons. 1–8 GPUs with at least 12 GB of memory. 64-bit Python 3.8.

Installation

1. Get a free Python 3.8 https://www.python.org/downloads/release/python-3810/ and latest version of pip.
2. Clone the repo and go to the folder

   git clone https://github.com/github_username/repo_name.git
   

3. Install the required packages using requrements.txt

   pip install -r requirements.txt
   

(back to top)

UI Interaction

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

USAGE CLI

Here are few example of how to use the code for specific features.

• [1] Rendering Tract/Mask/Mesh with a single color : python main.py --mask mask1.nii.gz mask2.nii.gz --tract tract1.trk tract2.trk --mesh mesh1.vtk mesh2.vtk --brain_2d brain.nii.gz --colors_mask red,#FF0000 --colors_mesh green,#96be25 --colors_tract blue,#2596be

  Note: For multiple files in Mask/Mesh/Tract use "SPACE" to separate For colors you can be provide either name or the hex , If colors_tract is not provided then uses direction of tracts to color it. If colors_mask/colors_mesh is not provided then uses a random color

• [2] Rendering Tract/Mask/Mesh with a multi labeled mask : python main.py --mask mask1.nii.gz mask2.nii.gz --tract tract1.trk tract2.trk --mesh mesh1.vtk mesh2.vtk --glass_brain brain_wm.nii.gz --width_tract 4 --background 1

  Note: Provide a mask that has multiple labels, it is automatically detected and colored using disctinctipy library. These colors are used to color the tract and mesh as well. Keep the order of files of same ROI constant e.g. if CST_L is < mask1.nii.gz > in mask then it should be the 1st in Mesh and Tract < tract1.trk> Use Glass Brain for a 3D white matter brain, background 0/1 (black/white) and width_tract to specify the width of all the tracts

• [3] Rendering Tract/Mask/Mesh with a multi labeled mask using a stas file (csv) : python main.py --mask mask1.nii.gz mask2.nii.gz --tract tract1.trk tract2.trk --stats_mask_csv_value stats_file1.csv,stats_file2.csv --range_t_value -14 14 --threshold_mask 5 --map Spectral_r Note: Provide a mask that has multiple labels, it is automatically detected and colored using the stats file (It should have few values like labels,p_value and t_value). Labels column is used to map colors to the same label number present in the mask. P_value is used as the thresholding factor to make a label significant or not (color it grey). T_value is normalized and used to choose a color from color_map (Matplotlib color_map). These colors are used to color the tract and mesh as well.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Contact

Lobes -

Project Link: https://github.com/USC-LoBeS/DiVE/

(back to top)

Acknowledgments

• I. B. Gari et al., "Along-Tract Parameterization of White Matter Microstructure using Medial Tractography Analysis (MeTA)," 2023 19th International Symposium on Medical Information Processing and Analysis (SIPAIM), Mexico City, Mexico, 2023, pp. 1-5, doi: 10.1109/SIPAIM56729.2023.10373540.
• OHBM abstract

(back to top)