A real-time diffusion MRI slicing application for Linux and Windows using OpenGL 4.6. It can visualize tensor and multi-tensor images in MRtrix, DIPY and FSL format as well as spherical functions expressed as a series of spherical harmonics coefficients in DIPY's descoteaux07 legacy real symmetric or full SH basis (See this link for more details.). The application also supports grayscale and color background images. Several colormaps are available for tensor visualisation.
To start using dmri-explorer, clone this repository.
Before installing the software, please make sure you meet the requirements below.
Cmakeminimum version 3.11 is required for installing the application.- A compiler supporting
C++17features is required (for GCC,C++17is available for versions 5 and above). - You have an OpenGL implementation available on your system. On Ubuntu, it can be installed with
sudo apt install mesa-common-dev.mesa-common-devis an open-source implementation of OpenGL. See this link from wikipedia for more information. - If you are using Linux, please note that the generator used by default is
GNU Make. - If you are a Windows user, the expected generator is
Visual Studio 2019and the application must be built forx64architecture. You can get the latest MSVC compiler toolset here. - The application is tested with NVIDIA GPU and is not garanteed to work on other hardware. In particular, the application does not run on Intel integrated graphics card (CPU) on Windows.
The application is tested on both Ubuntu 20.04 and Windows 10.
To build the program, run the following commands from the project root directory:
mkdir build
cd build
cmake ..
make
Alternatively, a helper script containing the four commands shown above is made available for building the software. It can be launched using:
./install.sh
The above script creates the build directory, runs Cmake and make. The executable file will be in the folder ${project_root}/build/Engine.
The Windows build is also done using cmake. The build has been tested with msbuild version 16.9. Using the Developer Command Prompt for VS, the program can be built with:
cd /path/to/dmriexplorer/
mkdir build
cd build
cmake ..
msbuild dmriexplorer.sln
Alternatively, for Visual Studio users, the file dmriexplorer.sln generated by cmake can be opened with Visual Studio and built through the interface.
Once the program is built, you can add the path to the directory containing the executable to your .bashrc configuration to make it available system-wide. On Linux, this is done with
export PATH='${absolute_path_to_project}/build/Engine':$PATH
On Windows, this can be done manually from the Control panel.
The application can be launched using the command:
dmriexplorer [options] image
For visualizing spherical function images use the -f option
Example:
dmriexplorer -f path/to/odf.nii.gz
Ir order to visualize tensor images use the -t option
Example:
dmriexplorer -t path/to/tensor.nii.gz
Several tensor layers can be added for visualizing a multi-tensor image. Make sure that all layers have the same tensor format.
Example:
dmriexplorer -t path/to/tensor_layer1.nii.gz -t path/to/tensor_layer2.nii.gz -t path/to/tensor_layer3.nii.gz
The default tensor formating follows the MRtrix format (link here).
This behaviour can be altered using the -o option. All the supported formats are: mrtrix, dipy and fsl.
When working with a big image or several layers, you may encounter a "Window not responding" message at application startup. Don't worry, it will go away once the image is copied on the GPU.
To display all available command line arguments, use the flag --help.
The software has been presented as part of the CDMRI'21 workshop and the ISMRM'22 diffusion workshop. It has however evolved since then and will keep getting better over time. For the performances reported at the CDMRI workshop, please refer to the release v0.1. However, we highly encourage the user to use the latest version of the application on the main branch, as efforts have been made to lower GPU and CPU memory usage.
If you enjoy this application, please consider citing the following work:
-
Original SH visualisation method:
Poirier C., Descoteaux M., Gilet G. (2021) Accelerating Geometry-Based Spherical Harmonics Glyphs Rendering for dMRI Using Modern OpenGL. In: Cetin-Karayumak S. et al. (eds) Computational Diffusion MRI. CDMRI 2021. Lecture Notes in Computer Science, vol 13006. Springer, Cham. https://doi.org/10.1007/978-3-030-87615-9_13
-
Multi-tensor support:
Hernandez-Gutierrez E., Poirier C., Coronado-Leija R., Descoteaux M. (2022) Real-Time Rendering of Massive Multi-Tensor Fields Using Modern OpenGL. Proceedings of the International Society for Magnetic Resonance in Medicine.
Contributions are welcome and encouraged:
- If you discover bugs (installation problems, in-app bugs, etc.), please open an issue describing the error and the steps to reproduce it;
- If you have a feature request, you are also encouraged to open an issue describing your need;
- Pull-requests are of course welcome! Please refer to the contributing guidelines.