Giters

paytam / MRIcroGL

v1.2 GLSL volume rendering. Able to view NIfTI, DICOM, MGH, MHD, NRRD, AFNI format images.

Home Page:https://www.nitrc.org/plugins/mwiki/index.php/mricrogl:MainPage

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

About

MRIcroGL is a cross-platform tool for viewing DICOM and NIfTI format images. It provides a drag-and-drop user interface as well as a scripting language. Please see the wiki page from more details. Note that the wiki page describes version 1.0 of the software, while this Github page is for the upcoming version 1.2. The changes are in general subtle, but the scripting has changed quite a bit.

Chest CT

Requirements

By default, MRIcroGL 1.2 is compiled to require OpenGL 2.1 (from 2006). It can also be compiled to require OpenGL 3.3 Core (released in 2009). Alternatively, macOS users can also compile the tool for the Metal. From the user perspective, there should be no difference between these choices. If your computer does not support OpenGL 2.1, you can try MRIcron. The code can be compiled for the macOS, Linux or Windows operating system. For macOS, both ARM-based Apple Silicon and Intel-based computers are natively supported.

Installation

You can get MRIcroGL using three methods:

  • Download from NITRC.
  • Download from Github.
  • Run the following command to get the latest version for Linux, Macintosh or Windows:
    • 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

Once you have downloaded the software, extract the archive and run the executable. Visit the wiki for a full manual that includes troubleshooting.

MRI

Compiling with the Graphical Interface

It is generally recommended that download a pre-compiled executable (see previous section). However, you can compile your own copy from source code.

  • Download and install Lazarus 2.0.6 or later.
  • Get the Metal-Demos repository, for example: git clone https://github.com/neurolabusc/Metal-Demos.
  • Get the MRIcroGL repository, for example: git clone https://github.com/neurolabusc/MRIcroGL.
  • The Metal-Demos and MRIcroGL folders should share the same parent folder, e.g. ~/src/MRIcroGL and ~/src/Metal-Demos.
  • Option for Windows You you can decide to build with or without faster gzip decompression:
  • To build without faster GZip: Remove the text "{$DEFINE FASTGZ}" from the file opts.inc. Benefit: easier build, uses permissive BSD license.
  • To build with faster GZip. Preserve the text "{$DEFINE FASTGZ}" in the file opts.inc. Benefit: faster gzip decompression. However, this only supports CPUs that support SSE4 (2008 and later).
  • Option You you can decide to build with or without Python Scripting:
    • To build without Python: Open the project MRIcroGL_NoPython.lpi (or remove the text "-dMYPY" from the file MRIcroGL.lpi).
    • To build with Python using python4lazarus open the project MRIcroGL_Py4Laz.lpi. **Note, there are issues with the latest python4lazarus release, you should consider compiling without Python support (MRIcroGL_NoPython.lpi) or use and earlier (2020.07.31) release (this older release supports both Python 2.7 as well as Python 3.x). Therefore, this build is not recommended. Unlike the recommended PythonBridge, PythonForLazarus attempts to use an existing Python distribution for macOS and Linux. Like PythonBridge, the Windows executable uses a DLL.
    • To build with Python using the included PythonBridge API, open the MRIcroGL.lpi project. This will statically link Python into Unix executables (though you will need to include the Python libraries in your Resources folder). For Windows, this method will use a dynamic link library for Python, and also requires you to include the standard libraries in your Resources folder.
    • To build with Python. You will need python4lazarus_package, but hopefully Lazarus will detect and install this for you automatically. **Note, there are issues with the latest python4lazarus release, you should consider compiling without Python support (MRIcroGL_NoPython.lpi) or use and earlier (2020.07.31) release (this older release supports both Python 2.7 as well as Python 3.x).
  • Option macOS developers can build for the modern Metal API instead of the legacy OpenGL API:
    • Get the lazmetalcontrol repository.
    • Use the Lazarus Package menu to open and install the lazmetal control.
    • Open and compile the MRIcroGL_Metal.lpi project instead of the MRIcroGL.lpi project with Lazarus (if you do not want Python, remove the text "-dMYPY" from the file MRIcroGL_Metal.lpi).
  • Use the Run command from the Run menu compile and run your project.

Alternatively, Debian/Ubuntu Linux users may want to look at the docker script that provides a line-by-line recipt for compiling MRIcroGL from the command line.

Compiling with the Command Line

It is generally recommended that download a pre-compiled executable (see previous section). However, you can compile your own copy from source code. Download and install Lazarus 2.0.6 or later, at which point the lazbuild command should be available from the command line.

**Note, there are issues with the latest python4lazarus release, you should consider compiling without Python support (MRIcroGL_NoPython.lpi) or use and earlier (2020.07.31) release.

For Linux (GTK2) or Windows (though see notes above), the compilation will look like this :

git clone https://github.com/rordenlab/MRIcroGL.git
git clone https://github.com/neurolabusc/Metal-Demos.git
git clone https://github.com/neurolabusc/Python27-for-Lazarus.git
lazbuild --build-ide= --add-package lazopenglcontext ./Python27-for-Lazarus/python4lazarus/python4lazarus_package.lpk
cd MRIcroGL
lazbuild  -B MRIcroGL.lpr

For MacOS, you will want to specify the modern Cocoa widgetset, rather than the legacy Cocoa widgetset:

git clone https://github.com/rordenlab/MRIcroGL.git
git clone https://github.com/neurolabusc/Metal-Demos.git
git clone https://github.com/neurolabusc/Python27-for-Lazarus.git
lazbuild --build-ide=  --ws=cocoa --add-package lazopenglcontext ./Python27-for-Lazarus/python4lazarus/python4lazarus_package.lpk
cd MRIcroGL
lazbuild  -B --ws=cocoa MRIcroGL.lpi

One can also compile for Linux (qt5). Users will need to install libqt5pas 1.2.8 or later. This version is more recent than the version provided with Ubuntu 18.04 and Mageia 7.1, so users of many operating systems will have to download the library from Github rather than the conventional install (e.g. sudo apt install libqt5pas):

git clone https://github.com/rordenlab/MRIcroGL.git
git clone https://github.com/neurolabusc/Metal-Demos.git
git clone https://github.com/neurolabusc/Python27-for-Lazarus.git
lazbuild --build-ide= --add-package lazopenglcontext ./Python27-for-Lazarus/python4lazarus/python4lazarus_package.lpk
cd MRIcroGL
lazbuild  -B --ws=qt5 MRIcroGL.lpi

One can also make minor adjustments to these command line options.

  • --ws=gtk3 will compile for the GTK3 widgetset. Support for GTK3 is experimental and not all features work (e.g. color selection dialog). GTK3 requires OpenGL 3.3 Core, so you must make sure that the glopts.inc file in the Metal-Demos folder has the line "{$DEFINE COREGL}" uncommented. Unfortunately, GTK3 does not support OpenGL multi-sampling so the results can never match GTK2 or QT5.
  • Compiling MRIcroGL_NoPython.lpi will compile without Python scripting support ().

Head CT

Deploying MRIcroGL

The MRIcroGL executable has more functionality if it can access its Resources folder. This folder includes color lookup tables (lut folder), Python scripts (script), Material Capture (matcap), GLSL Shaders (shader), default NIfTI images (standard), NIfTI atlases (atlas), as well as fonts and icons. Therefore, for full functionality, you want the executable to have access to this folder.

  • For MacOS, the Resources folder is placed inside the application package bundle. In other words, if your application is MRIcroGL.app, the software expects MRIcroGL.app/Resources.
  • For Windows, place the Resources folder in the same folder as MRIcroGL.exe.
  • For Linux, you can place the Resources folder in the same folder as the MRIcroGL exectuable. If this fails, it will look for the folder $MRICROGL_DIR where $MRICROGL_DIR is an environment variable. It will then look a folder in the following order (for the first pass, where the applications actual name is used MRIcroGL_QT, and for a second pass using MRIcroGL):
 /opt/MRIcroGL/Resources
 /opt/MRIcroGL
 /opt/MRIcroGL/Resources
 /opt/MRIcroGL
 /usr/local/MRIcroGL/Resources
 /usr/local/MRIcroGL
 /usr/local/MRIcroGL/Resources
 /usr/local/MRIcroGL
 /usr/local/share/MRIcroGL/Resources
 /usr/local/share/MRIcroGL
 /usr/local/share/MRIcroGL/Resources
 /usr/local/share/MRIcroGL

Linux GNOME users may also want to setup a desktop file with a name like MRIcroGL.desktop. A sample is provided in the Resources folder, but this will require minor editing since the Exec and Icon path must be absolute not relative.

Scripting and Command Line

You can use all the functions of MRIcroGL using the graphical interface. You can also create Python scripts to get precise results our automate laborious tasks.

You can also control MRIcroGL from the command line.

  • Launch MRIcroGL and have it automatically run a Python script: mricrogl myscript.py. This method also allows you to control MRIcroGL from your preferred programming languages.
  • MacOS uses may find it useful to make an alias to MRIcroGL. This will allow you to simply run mricrogl from the command line instead of typing the full path. You can do this by running open -a TextWrangler ~/.bash_profile and then adding an alias, for example adding the line mricrogl='/Applications/MRIcroGL.app/Contents/MacOS/MRIcroGL' (assuming the application is in this folder).
  • Reset MRIcroGL to its defaults (forget user preferences): mricrogl -R.
  • You can choose the images to load from the command line: MRIcroGL -std -dr 2000 6000 motor -cm actc -dr 2 4. In this example, the FSL standard image is loaded as a background with a display range of 2000...6000, and the image 'motor' is loaded as an overlay with the 'actc' colormap and a display range of 2...4. Note that the options are a subset of those available for fsleyes.
    • You can provide an image name: 'motor', 'mni152.nii.gz', etc.
    • If you have FSL installed, you can choose one of the standard images: '-std', '-std1mm', '--standard', '--standard1mm'.
    • You can specify a color map. For example '-cm bone'.
    • You can specify a display range, for example '-dr 3 4'.
    • Note that you can load multiple images, and the color map and display range is applied to the most recently specified image.

Primate

Supported Image Formats

MRIcroGL uses NIfTI as its native format. However, you can drag-and-drop files of various formats and the software should automatically detect and load these images.

If your image format is not supported directly by MRIcroGL, you may want to see if it is supported by the Bio-Formats module of ImageJ/Fiji. If so, you can open the image with the module and save it as NIfTI or NRRD to read it with MRIcroGL.

Rendering Technique

MRIcroGL uses single-pass raycasting to generate volume renderings.

Alternatives

There are many terrific free tools for viewing medical imaging data. Since they are free, consider downloading a few and using the best tool for the task at hand. Below are a couple of my personal favorites.

  • MRIcron is similar and does not require OpenGL, but it is unable to generate interactive renderings.
  • DragonFly is not open source, but it does provide a non-commercial licenses are granted free-of-charge.
  • Drishti has powerful rendering abilities, though support for medical imaging formats is limited.
  • FSLeyes has many similar features, as well as rich support for FSL. Variants require either OpenGL 1.4 or OpenGL 2.1.
  • InVesalius provides useful segmentation tools.
  • Mango is a nice viewer.
  • Slicer 3D is daunting at first, but provides tremendous power and flexibility.
  • Seg3D has powerful segmentation routines.
  • For DICOM images (but not other formats), Horos is outstanding.

About

v1.2 GLSL volume rendering. Able to view NIfTI, DICOM, MGH, MHD, NRRD, AFNI format images.

https://www.nitrc.org/plugins/mwiki/index.php/mricrogl:MainPage

License:Other

Languages

Language:Python 55.6%Language:Pascal 32.7%Language:Metal 4.0%Language:GLSL 3.9%Language:C 3.6%Language:C++ 0.1%Language:Shell 0.0%Language:Batchfile 0.0%