MRIcroGL

repository·master·Indexed 43 days ago

https://github.com/rordenlab/mricrogl

A cross-platform tool for viewing DICOM and NIfTI format neuroimaging data. It features a drag-and-drop GUI, Python scripting for automation, and high-performance rendering via OpenGL or Metal. The software supports single-pass raycasting for 3D visualizations, custom colormap (.clut) integration, and specialized tools for removing haze from medical images using multi-Otsu thresholding.

Tokens
5K
Snippets
11
Records
19
Agent score
55%

What's inside MRIcroGL

  1. Use Smooth Edges and Largest Object extraction in haze removal

    master

    When using Remove Haze with Options, you can refine the extraction using two additional settings:

    • Smooth Edges: When enabled, this checkbox accounts for partial volume effects. It preserves the intensity of 'air' voxels that neighbor 'tissue' voxels to prevent the creation of jagged surfaces, which is particularly important for maintaining accurate gradient maps.
    • Only extract largest object: When enabled, the tool assumes the image contains a single contiguous object. Any voxels not connected to the largest identified object are automatically treated as air.
  2. How MRIcroGL rendering works

    master
    MRIcroGL utilizes single-pass raycasting to generate volume renderings. This technique is used to create interactive 3D visualizations of voxel data. For technical details on the implementation, the project references several seminal descriptions and WebGL2 implementations (such as those by Philip Rideout and Will Usher).
  3. Writing to the depth buffer in volume ray casting

    master

    In volume ray casting, the default depth buffer only records the front face of the bounding cube, not the actual rendered surface. To enable occlusion (e.g., for crosshairs) and mouse picking, you must explicitly set gl_FragDepth in your fragment shader when the first non-transparent voxel is encountered.

    To implement this, use an isHit flag within your ray marching loop. When isHit is 0 and you find a voxel with sufficient opacity, set isHit = 1 and calculate gl_FragDepth using the Model-View-Projection matrix to map the hit position to the depth buffer.

    	int isHit = 0; //used to detect first non-transparent voxel
    	for (float t = t_hit.x; t < t_hit.y; t += dt) {
    		float val = texture(volume, p).r;
    		vec4 val_color = vec4(texture(transfer_fcn, vec2(val, 0.5)).rgb, val);
    		p += ray_dir * dt;
    		if (val_color.a < 0.01) continue; //skip transparent samples
    		if (!isHit) { //our first non-transparent voxel
    			isHit = 1;
    			gl_FragDepth = ((ModelViewProjectionMatrix * vec4(pos, 1.0)).z + 1.0) * 0.5;
    		}
    		color.rgb += (1.0 - color.a) * val_color.a * val_color.rgb;
    		color.a += (1.0 - color.a) * val_color.a;
    		if (color.a >= 0.95) {
    			break;
    		}
    	}
  4. Remove haze from medical images

    master

    Medical images (CT and MRI) often contain noise in the air surrounding the scanned object, which can cause hazy volume renderings and interfere with DepthPicking. MRIcroGL provides tools to remove this noise by identifying dark voxels (air) and setting them to the intensity of the darkest voxel in the volume.

    To remove haze, use the following commands in the View menu:

    • Remove Haze: A quick option that uses a conservative threshold (equivalent to level 5 in the options menu).
    • Remove Haze with Options: Provides granular control over the thresholding method.
    • Extract Brain: An alternative approach using BET (Brain Extraction Tool).
  5. Compile MRIcroGL from source

    master

    While downloading pre-compiled executables is recommended, you can compile MRIcroGL from source using Lazarus 2.0.6 or later.

    Using the Graphical Interface

    1. Install Lazarus.
    2. Clone the MRIcroGL repository.
    3. In Lazarus, go to Project > Open Project and select MRIcroGL.lpi.
    4. Use the Run menu to compile and run.

    Using the Command Line

    For Linux (QT5) or Windows, use lazbuild as follows:

    git clone https://github.com/rordenlab/MRIcroGL.git
    # Add the python4lazarus package
    lazbuild --build-ide= --add-package lazopenglcontext ./Python27-for-Lazarus/python4lazarus/python4lazarus_package.lpk
    cd MRIcroGL
    # Build the project
    lazbuild -B MRIcroGL.lpr

    For macOS, use the modern Cocoa widgetset:

    git clone https://github.com/rordenlab/MRIcroGL.git
    cd MRIcroGL
    lazbuild -B --ws=cocoa MRIcroGL.lpi
    git clone https://github.com/rordenlab/MRIcroGL.git
    cd MRIcroGL
    # macOS specific build
    lazbuild -B --ws=cocoa MRIcroGL.lpi
  6. Convert scientific colormaps to MRIcroGL .clut files

    master

    You can use the provided color2clut.py script to convert scientific colormaps from the cmap Python library into MRIcroGL-compatible .clut files.

    Prerequisites: Install the cmap package via pip:

    pip install cmap

    Usage Patterns:

    • Convert a specific colormap: Pass the name of the colormap (e.g., davos) as an argument.
    • Batch conversion: Run the script without arguments to convert a default set of colormaps.
    • Adjust precision: Use the -t argument to set the interpolation tolerance, which allows you to balance the number of nodes against color precision.
    # Convert the 'davos' colormap
    python color2clut.py davos
    
    # Batch convert default colormaps
    python color2clut.py
    
    # Batch convert with specific interpolation tolerance
    python color2clut.py -t <tolerance>
  7. Install MRIcroGL

    master

    You can install MRIcroGL using one of the following three methods:

    1. Download from NITRC: Visit the NITRC project page.
    2. Download from GitHub: Visit the GitHub releases page.
    3. Command Line (Latest Version):
      • Linux: curl -fLO https://github.com/rordenlab/MRIcroGL/releases/latest/download/MRIcroGL_linux.zip
      • macOS: curl -fLO https://github.com/rordenlab/MRIcroGL/releases/latest/download/MRIcroGL_macOS.dmg
      • Windows: curl -fLO https://github.com/rordenlab/MRIcroGL/releases/latest/download/MRIcroGL_windows.zip

    After downloading, extract the archive and run the executable.

    curl -fLO https://github.com/rordenlab/MRIcroGL/releases/latest/download/MRIcroGL_linux.zip
    curl -fLO https://github.com/rordenlab/MRIcroGL/releases/latest/download/MRIcroGL_macOS.dmg
    curl -fLO https://github.com/rordenlab/MRIcroGL/releases/latest/download/MRIcroGL_windows.zip
  8. How to add custom colormaps to MRIcroGL

    master

    MRIcroGL automatically loads all .clut files located in the /Resources/lut folder upon launch. To add your own colormaps, place your .clut files into this directory.

    File Locations:

    • General/Linux/Windows: /Resources/lut within the MRIcroGL installation directory.
    • macOS: Inside the app bundle at MRIcroGL.app/Contents/Resources/lut.

    Technical Specifications:

    • Each .clut file can define up to 256 colors.
    • For continuous colormaps, using fewer nodes is recommended to facilitate easier editing via the Color Editor (found in the Color menu).
  9. Compile MRIcroGL using Docker and Lazarus

    master

    If you need to compile MRIcroGL from source, you can use a Debian-based Docker container. This process involves setting up a Lazarus development environment, installing dependencies like libgl1-mesa-dev, cloning the necessary repositories, and using lazbuild to compile the project.

    Requirements & Dependencies:

    • Lazarus: Version 2.0.4 or later is suggested for Debian systems.
    • OpenGL: MRIcroGL requires OpenGL 3.3 or later.
    • Recommended Tools: For optimal performance, install pigz and dcm2niix via apt.

    Compilation Steps:

    1. Pull and run a Debian base image.
    2. Download and install Lazarus and FPC (Free Pascal Compiler) .deb packages.
    3. Install system dependencies: git, libgl1-mesa-dev, and build-essential.
    4. Clone the MRIcroGL12 repository along with Metal-Demos and Python-for-Lazarus.
    5. Use lazbuild to add required packages (python4lazarus and lazopenglcontext).
    6. Run lazbuild on the MRIcroGL.lpr project file.
    # 1. Setup Docker environment
    docker pull jgoerzen/debian-base-standard
    docker run -td --stop-signal=SIGPWR --name=name jgoerzen/debian-base-standard
    docker run -it jgoerzen/debian-base-standard /bin/bash
    
    # 2. Install Lazarus and FPC
    cd ~
    wget --no-check-certificate https://sourceforge.net/projects/lazarus/files/Lazarus%20Linux%20amd64%20DEB/Lazarus%202.0.4/lazarus-project_2.0.4-0_amd64.deb
    wget --no-check-certificate https://sourceforge.net/projects/lazarus/files/Lazarus%20Linux%20amd64%20DEB/Lazarus%202.0.4/fpc-src_3.0.4-2_amd64.deb
    wget --no-check-certificate https://sourceforge.net/projects/lazarus/files/Lazarus%20Linux%20amd64%20DEB/Lazarus%202.0.4/fpc-laz_3.0.4-1_amd64.deb
    apt-get update
    apt -yq install ./fpc-src_3.0.4-2_amd64.deb
    apt -yq install ./fpc-laz_3.0.4-1_amd64.deb 
    apt -yq install ./lazarus-project_2.0.4-0_amd64.deb 
    
    # 3. Install dependencies
    apt-get -yq install git
    apt-get -yq install libgl1-mesa-dev
    apt install build-essential 
    
    # 4. Clone repositories
    git clone https://github.com/rordenlab/MRIcroGL12.git
    git clone https://github.com/neurolabusc/Metal-Demos
    git clone https://github.com/Alexey-T/Python-for-Lazarus.git
    
    # 5. Build project
    lazbuild --add-package ~/Python-for-Lazarus/python4lazarus/python4lazarus_package.lpk  --build-ide=
    lazbuild --add-package lazopenglcontext --build-ide=
    cd MRIcroGL12
    lazbuild -B ./MRIcroGL.lpr
  10. Install MRIcroGL via pre-compiled executable

    master

    The fastest way to install MRIcroGL on Linux is to download the latest pre-compiled zip archive directly from GitHub releases.

    curl -fLO https://github.com/rordenlab/MRIcroGL12/releases/latest/download/MRIcroGL_linux.zip
  11. Configure MRIcroGL deployment and Resources

    master

    MRIcroGL requires access to a Resources folder for full functionality (containing LUTs, Python scripts, shaders, atlases, etc.).

    • macOS: The Resources folder must be inside the application bundle: MRIcroGL.app/Resources.
    • Windows: Place the Resources folder in the same directory as MRIcroGL.exe.
    • Linux: Place the Resources folder in the same directory as the MRIcroGL executable. If not found locally, it searches paths defined by the $MRICROGL_DIR environment variable, checking locations like /opt/MRIcroGL/Resources or /usr/local/share/MRIcroGL/Resources.

    Linux Dependency: Users of the Linux (qt5) widgetset must install libqt5pas (e.g., sudo apt install libqt5pas).