mricrogl:MainPage

MRIcroGL user interface.

Introduction

MRIcroGL is medical image viewer that allows you to load overlays (e.g. statistical maps), draw regions of interest (e.g. create lesion maps). MRIcroGL runs on Windows, Linux and OSX. This wiki provides some additional notes on using MRIcroGL.

Requirements

MRIcroGL runs on Linux, Windows, and MacOS. It requires OpenGL 2.1 (released 2006) or later. If you have problems see the trouble shooting web page.

Installation

To install MRIcroGL, download it from NITRC or Github. If you have problems running MRIcroGL, you may want to visit the troubleshooting page. One basic hint: if you are having trouble running MRIcroGL, try launching the program with the shift key down (or the control key if you are using Unix). This will allow you to choose between different settings to match your computers video card.

MRIcroGL is open source, and if you want you can download download and compile it yourself.

Viewing images

Adjusting the image contrast and brightness can change the appearance.

You should be able to view most medical images by dragging and dropping the image onto MRIcroGL, or by using the File/Open command. The software should be able to read most medical images, including those in the following formats: NIfTI (.nii, .nii.gz, .hdr/.img), Bio-Rad Pic (.pic), NRRD, Philips (.par/.rec), ITK MetaImage (.mhd, .mha), AFNI (.head/.brik), Freesurfer (.mgh, .mgz), basic DICOM (extensions vary). Since DICOM images are usually saved as 2D slices, it is usually a good idea to convert them to NIfTI format first, as described in the 'Converting Images' section.

You may want to adjust the image intensity range values and the color scheme to emphasize different tissues. For example, the image shows a high-quality CT scan from Philips, where we can adjust the contrast to either show the scalp, the bones or the soft tissue.

Basic tasks are shown in the basic usage and color settings videos.

Loading Overlays

After you open an image, you can add overlay images on top of the background image. To do this you will want to choose File/AddOverlay. The properties of the overlays (color, contrast, brightness) can be adjusted in the "Layer" panel.

If the overlay does not match the resolution of the background image, it will need to be replaced using interpolation. Overlays can either be loaded with nearest neighbor interpolation (which can lead to jagged artifacts) or linear interpolation (which yields smoother images, but can show edge artifacts for thresholded images). One can choose between interpolation by using the "Load Smooth Overlays" menu item in the "Options" pulldown menu of the layers tool. This issue is discussed in the [cluster threshold](https://www.nitrc.org/plugins/mwiki/index.php/mricrogl:MainPage#Cluster_Thresholds) example. You can also control the behavior with your scripts. For example, the Scripting/Templates/jagged menu item loads two overlays, one with jagged (nearest neighbor) and the other with smooth (linear) interpolation.

For demonstrations, see the basic overlays video. For advanced usage see the overlay shaders and the overlay glass videos.

Drawing Regions of Interest

After you open an image, you can draw regions of interest. This is useful for mapping lesions (for analysis with vlsm or NiiStat), or for analyzing your fMRI data (for analysis with marsbar).

The basic details for drawing a region of interest are described on the MRIcroGL drawing page. In brief you will want to do the following

Load an image with MRIcroGL
Choose a 2D view of your image (use the Display menu to select sagittal, coronal, axial or multislice views, but not the render view).
Choose Draw/DrawColor/Red
You can now drag the mouse on the image to create a filled object
Drag the mouse with the control key down to create an unfilled object
Alt+click to fill a contiguous region
Drag with the shift key down to erase a filled region
Drag with the shift and control keys down to erase an unfilled region
Alt+Shift+click to erase a contiguous region
Remember, you can use the arrow keys and the home/end keys to change which slice you are viewing. This allows you to draw one slice after the other. For OSX Mac computers, the command+left_arrow and command+right_arrow keys simulate home and end presses.

You may want to watch the drawing video.

Advanced Drawing

The Draw/Advanced menu provides several options to help with drawing regions of interest.

The "Overwrite Existing Colors" option is used when you are drawing regions of different colors on a single image. Consider you have marked one region with the red pen, and now want to draw a bordering region with a blue pen. This option controls regions where the blue drawing overlaps the existing red region. If overwrite is checked, the new blue drawing will take precedence over the existing red color. If this option is not checked, the blue pen can mark un-colored areas, but will not impact red areas. This option is helpful for drawing bordering regions: you only have to draw the border precisely with one color, and you can be imprecise using the other color.

The "Pen Draws Filled Region" option toggles whether drawing creates a thin outline versus a solid area.

The "Clone Slice" function allows you to duplicate very similar slices. Start by using the pen tool to draw your region on one slice, next use the arrow keys to navigate to a different slice. Finally, choose "Clone Slice" and the drawing from the previous slice will be pasted to the new location.

The "Smooth and Refine Drawing" function removes jagged edges from a drawing. This is useful when you have drawn many slices of region with one view (e.g. axial), and you notice jagged edges when looking at orthogonal views (e.g. coronal).

"Intensity Filter" is a new menu item that allows you to interactively modify a drawing based on image intensity. The image shows how this can be used to trim and excessively large drawing. Likewise, one can use this method to add all the bright (or dark) voxels in an image to a drawing. In the image above, the top row shows the impact of adding voxels to a drawing, and the bottom row shows the impact of removing voxels from an existing drawing. The columns show the impact of selecting dark voxels, selecting mid-range brightnesses, selecting bright voxels, and selecting extreme voxels.

You can dilate or erode an existing drawing.

"Delete or Erode" is a new feature that allows you to grow or shrink an existing drawing. Be aware that the erode will work well for 3D volumes, but is not suited to a drawing that only exists on a 2D slice. The image shows how this can be used to trim and excessively large drawing. Likewise, one can use this method to add all the bright (or dark) voxels in an image to a drawing. These morphological functions use distance fields to rapidly create nice, spherical dilations.

The "Automatic VOI" allows you to define a 3D volume of interest with a few basic morphological parameters. You can set the origin for the new drawing, the radius, and the image intensity. This is a pretty basic tool, so it will only help define regions that are clearly defined on a scan.

The "Binarize" option can be used if you have a drawing with multiple colors (e.g. red, green and blue). It consolidates all the colors to be red.

The "Interpolate Between Slices" functions allows the user to draw a region on only a sample of images (e.g. every 4th axial slice) and then use this function to fill-in the region for the slices without a drawing. This is a crude function, but it can allow quick drawings, or can form a rapid way to create a crude drawing that the user can refine with the pen tool.

The "Mask Image" function allows the drawing to modify the image that it is drawn on. Specifically, you can only preserve brightness in the voxels where there is a drawing. Alternatively, you can choose to remove brightness from voxels with a drawing. You can use the File/SaveNIfTI menu item to save the modified background image.

Use the "Create Overlap Image" to sum together a lot of drawings. Consider you have drawn the lesion location for 32 patients in standard space. This function can show you areas that were commonly injured in these patients.

The "Subtraction Plots" allow you to compare two groups of drawings. Say for example that you have lesion drawings from 32 stroke survivors who are experiencing aphasia and 42 stroke survivors who do not have this symptom. This method can show regions that are consistently damaged in one group, but spared in the other.

The "Descriptives" reveal information about the drawing and the background image beneath the drawing. This is a simple way to work out the volume of a drawing.

Neurological versus radiological convention

Neurolgical versus radiological convention as seen from the perspective of 3D rendering.

Recent versions of MRIcroGL allow you to choose whether the 2D axial and coronal slices are shown in neurological or radiological convention. You can select your preference with the Display/Radiological(FlipLR) menu item. When this is unchecked, a left hemisphere lesion is shown on the left side of coronal and axial slices (neurological convention). When this item is checked, a left hemisphere lesion will appear on the right side of the screen. Note this selection does not mirror reverse the 3D renderings. To understand this, take a look at the figure. Neurological convention shows coronal/axial slices with the camera posterior/superior to the brain. Radiological view shows coronal/axial slices with the camera anterior/inferior to the brain. Therefore, this left hemsiphere lesion appears on the left side of the image in the neurological views, but on the right side in the radiological views. Another way to think about this is that neurological and radiological convention are reversed with respect to the depth dimension (e.g. what is closer or further from the viewer). To help you remember the convention the "L" and "R" buttons in the 2D slices panel will be either in the order "LR" (neurological) or "RL" (radiological). Due to the brains' symmetry, left-right errors are easy to make, so be careful with this feature. This explains why your choice of radiological versus neurological convention does not influence the 3D renderings. With the 3D renderings we explicitly set the camera position with respect to the brain, and we can see the depth dimension: near occlude more distant features.

Mosaic Views

Mosaic renderings.

Choosing "Mosaic" from the "Display" menu shows the mosaic view, where multiple slices of the same image can be seen simultaneously. A panel named "Mosaic" appears in the tool panel, and this allows you to interactively adjust the mosaic view with sliders, check boxes, pulldown options and text editing. You can also create advanced mosaics using scripting. Unlike the other views, the appearance of mosaics may have substantially different aspect ratios when you view them onscreen versus when you use File/Save to save an image. The mosaic view is designed for generating publication quality images, and the resolution is driven by the volume you are viewing rather than your screen (to reduce interpolation artifacts). While you can add text labels in this mode, for publications you probably want to generate images without labels and add labels later using a vector-art tool that can create sharper text than is possible with bitmaps.

Mosaic slices.

Importing Images

MRIcroGL uses NIfTI as its native format. However, it should automatically detect and open images in many other formats including those supported by i2nii like NRRD, ECAT, BioRad PIC, and Interfile. It can also view DICOM images using dcm2niix. You can view DICOM images by dropping them on the program or using the import menu to convert them to NIfTI. The MRIcroGL Import menu also has an item for converting TIFF images for viewing data from morphosource and digimorph.

Scripting

MRIcroGL can use scripts to demonstrate features and automate laborious tasks. Scripts can be run from the graphical interface (the View/Scripting menu item) or can be invoked from the command line (allowing other programs to control MRIcroGL). See Github for a full listing of functions. You can also choose the menu item Scripting/Templates/Help to have MRIcroGL generate a full list of commands. The scripts below show the in-built Pascal scripts, but if you prefer you can use the popular Python language.

Loading a background image uses the `loadimage` command (`gl.loadimage('spm152')`), while loading an image on top of an existing background volume uses the `overlayload` command (`gl.overlayload('spmMotor')`). Windows users need to be careful that Python uses the backslash as the escape character. Therefore, you should use the forward slash for file paths (use `gl.loadimage('c:\dir\t1.nii')` instead of `gl.loadimage('c:/dir/t1.nii')`).

Kathleen Hupfeld has written a web page describing how to script figures in MRIcroGL.

Glass Brain

A script showing glass brain projection.

This script uses the provided example dataset from an individual conducting a tapping task whenever they see a visual stimulus. We expect to see the contralesional motor cortex, supplementary motor area and visual cortices active during the task. We overlay this on a standard brain. This script demonstrates the ‘overlay_glass’ shader released in 2014 that allows you to independently control the transparency of the background and overlay images. For a tutorial on using this see the demonstration YouTube video.

To reproduce this script choose View/Scripting and then insert the following code. When you are done choose Script/Run.

import gl
gl.resetdefaults()
gl.loadimage('spm152')
gl.overlayload('spmMotor')
gl.minmax(1, 4, 4)
gl.shadername('Shell')
gl.shaderadjust('boundThresh', 0.35)
gl.shaderadjust('edgeThresh', 0.42)
gl.shaderadjust('edgeBoundMix',0.05)
gl.shaderadjust('colorTemp', 0.8)
gl.backcolor(255, 255,255)

Clip Plane

A script showing a clip plane.

This script demonstrates the ‘overlay’ shader released in 2014 that allows you to independently control the transparency of the background and overlay images. This shader allows you to decide whether the clipping is only applied to the background (as shown) or to both the background and overlay images. You can also watch the overlay shader demonstration video on YouTube for hints on how to use this shader.

import gl
gl.resetdefaults()
#open background image
gl.loadimage('spm152')
#open overlay: show positive regions
gl.overlayload('spmMotor')
gl.minmax(1, 4, 4)
gl.opacity(1,50)
gl.clipazimuthelevation(0.4, 0, 160)

Cutout

A script showing a cutout.

This script demonstrates the ability to generate cutouts. Note that I load the statistical map ‘motor’ twice – once to show the regions more active when the left versus right hand was active and once to show the regions that were more active for movements of the right versus left hand (this was a [1 -1] t-test).

import gl
gl.resetdefaults()
gl.loadimage('spm152')
#open overlay: show positive regions
gl.overlayload('spmMotor')
gl.minmax(1, 4, 4)
gl.opacity(1,50)
#open overlay: show negative regions
gl.overlayload('spmMotor')
gl.minmax(2, -4, -4)
gl.colorname (2,"3blue")
gl.cutout(0.0, 0.45, 0.5, 0.75, 1.0, 1.0)

Overlay Surface

A script showing a overlay effect.

This is a simple variation of the previous cutout script. However, we now select the shader "overlay surface" which hides the statistical map unless it overlaps with the background image. The overlay vanishes in the region of the cutout.

import gl
gl.resetdefaults()
gl.loadimage('spm152')
#open overlay: show positive regions
gl.overlayload('spmMotor')
gl.minmax(1, 2, 4)
gl.opacity(1,50)
gl.colorname (1,"6warm")
#open overlay: show negative regions
gl.overlayload('spmMotor')
gl.minmax(2, -2, -4)
gl.colorname (2,"5winter")
gl.cutout(0.0, 0.50, 0.5, 0.75, 1.0, 1.0)
gl.shadername("overlaySurface")

Exploded Brain

A script showing merged slabs.

This is a way to create a an ‘exploded brain’ look. In this example, we will use the overlayClip to only show activations inside the brain.

ksteps = 12
ktime= 100
thick = 1.0/ksteps
gl.resetdefaults()
gl.loadimage('spm152')
gl.overlayload('spmMotor')
gl.minmax(1, 4, 4)
gl.shaderadjust('boundThresh', 0.35)
gl.shaderadjust('edgeThresh', 0.42)
gl.shaderadjust('edgeBoundMix',0.05)
gl.shaderadjust('colorTemp', 0.8)
gl.backcolor(255, 255,255)
gl.clipazimuthelevation(0.36, 0, 180)
gl.clipthick(thick)
gl.shaderadjust('overlayClip', 1)
for x in range(1, ksteps):
  gl.clipazimuthelevation(0.001+((x-1)*thick), 0, 180);
  gl.wait(ktime)
  #gl.savebmp(str(x)+'.png')

Exploded Brain 2

A script showing the exploded brain effect.

A variation of the previous script. By not applying the 'overlayClip' we can see the overlay activation protruding outside of the background brain.

ksteps = 12
ktime= 100
thick = 1.0/ksteps
gl.resetdefaults()
gl.loadimage('spm152')
gl.overlayload('spmMotor')
gl.minmax(1, 4, 4)
gl.shaderadjust('boundThresh', 0.35)
gl.shaderadjust('edgeThresh', 0.42)
gl.shaderadjust('edgeBoundMix',0.05)
gl.shaderadjust('colorTemp', 0.8)
gl.backcolor(255, 255,255)
gl.clipazimuthelevation(0.36, 0, 180)
gl.clipthick(thick)
#gl.shaderadjust('overlayClip', 1)
for x in range(1, ksteps):
  gl.clipazimuthelevation(0.001+((x-1)*thick), 0, 180);
  gl.wait(ktime)
  gl.savebmp(str(x)+'.png')

Cluster Thresholds

A script showing a shell effect.

The statistical maps generated by tools like SPM and FSL can either be unthresholded (green top left image) or thresholded (green bottom left). Since we typically reslice these low resolution images to map onto higher resolution images it is generally a good idea to use the unthresholded image: the thresholded image is artificially surrounded by bogus values so we can not interpolate the boundaries easily. The Layer panels Options/SmoothWhenLoading menu item allows you to choose your interpolation method. If this option is unchecked, nearest neighbor interpolation is used and you image will appear jagged (left glass brain) – this is most appropriate if your data was previously thresholded. However, MRIcroGL has commands to remove these small clusters (right image). If the SmoothWhenLoading item is checked, the image will be smoothed with a trilinear filter – this looks very nice (middle glass brain) and is typically appropriate if your raw data was not previously thresholded. However, closer inspection of these reveals that a few tiny clusters appear. If your original analysis used a cluster threshold, you will want to use Layer panel's Option/RemoveSmallClusters function. This will remove any clusters smaller than the specified size. You can also achieve this by calling the ‘ gl.removesmallclusters’ function from a script. You will supply the overlay index, the brightness threshold, and the minimum cluster size (in mm^3). Note that the cluster size is specified in volume not voxels: if you estimated a random field theory familywise error corrected threshold for clusters of at least 32 voxels with data that was 3mm isotropic (3x3x3 = 27mm^3 per voxel) then you would specify 864mm^3. In the example below we preserve voxels that exceed a brightness of 2.0, are part of clusters of at least 1cc (1000mm^3) and choose not to save the resliced image to disk. I would suggest using the function 'overlayloadsmooth(1)' prior to loading an overlay that you want to cluster threshold. This will ensure that trilinear interpolation is used when up-sampling the unthresholded data.

import gl
gl.resetdefaults()
gl.overlayloadsmooth(1)
gl.loadimage('spm152')
gl.overlayload('spmMotor')
gl.removesmallclusters(1, 3.5, 800)
gl.minmax(1, 3.5, 3.5)
gl.overlayload('spmMotor')
gl.removesmallclusters(2, -2.5, 800)
gl.minmax(2, -2.5, -2.5)
print("overlays only have large clusters");

Scripting from the command line and other programs

You can also call scripts from the command line or other programs, including those you create in Python and Matlab. MRIcroGL's scripting is similar to that of Surf Ice, so you may want to look at the Surf Ice wiki.

The command line '-s' argument allows you to specify a script, so you can have MRIcroGL run a script with the command "MRIcroGL -s ~/m.py". Be aware that on MacOS, the executable is inside a application package (.app), so your command line argument will look something like "/Applications/MRIcroGL.app/Contents/MacOS/MRIcroGL -s ~/m.py". Here is a basic script you could run from the command line. Notice the crucial command "gl.quit()" that has the application terminate after it has generated a screen shot. If you want to create screenshots, you might also want to consider the functions fullscreen, bmpzoom, scriptformvisible and toolformvisible. These can maximize the resolution of your image (an exception is mosaic images, where the resolution is based on the resolution of the volume, not the screen).

import gl
gl.resetdefaults()
gl.fullscreen(1)
gl.scriptformvisible(0)
gl.toolformvisible(0)
gl.bmpzoom(2)
gl.backcolor(255, 255,255)
gl.loadimage('CT_Philips')
gl.savebmp('myBitmap.png')
gl.quit()

In general, it is best to save scripts as separate files, as described above. However, for very simple scripts you can pass the whole script from the command line. Consider the call "MRIcroGL -s "import gl|gl.backcolor(255, 255,255)^gl.loadimage('CT_Abdo')"". You will need to use single quotes within your script and double quotes to define the beginning and end of the script (or vice versa). Python is very picky about line endings, so the caret (^) symbol is used to delimit lines. This does mean that you can not use the Python XOR function when providing command line input to MRIcroGL. Some Unix shells (but not Windows) allow you to provide multiple-line command-line arguments. Here would be a bash example:

./MRIcroGL -s 'import gl
gl.loadimage("spm152")'

Command Line Arguments

In general, the Python scripting described in the previous section will give you the most control over MRIcroGL. However, MRIcroGL can also parse a few command line arguments directly, without a script. The easiest example is launching and opening a NIfTI format image. To accomplish this, simply provide the path to the image as the first command line argument:

MRIcroGL D:/MRIcroGL/fmri.nii.gz

Note that MRIcroGL turns these command line arguments into a Python script. You can see the script and any errors associated by running the script by opening up the scripting panel on the right side of the MRIcroGL window. Windows users should be aware that Python uses the backslash as an escape character. Recent releases of MRIcroGL (1.2.20200331 and later) should convert the command line argument "D:\dir\t1.nii" to the Python-compatible "D:/dir/t1.nii".

MRIcroGL shares a few basic command line arguments with FSLeyes. Below you can see a script that opens the "spm152" image as the background image, sets the background image to use the "Viridis" color map, opens the overlay image "spmMotor", sets the display range for this overlay to 2 through 5, and sets the color scheme for this overlay to "4hot"

MRIcroGL spm152 -cm Viridis spmMotor -dr 2 5 -cm 4hot

Supported Formats

MRIcroGL's native format is NIfTI. However, it can also read images stored in other formats. Not all features of these formats may be supported, so use with caution:

AFNI format (.head/.brik)
Analyze format (predecessor to NIfTI, .hdr/.img files)
BioRad PIC format (.pic)
Blender voxel format (.bvox)
BrainVoyager (.vmr/.v16)
DeltaVision (.dv)
DICOM - simple drag and drop display or conversion to NIfTI (see below).
ECAT (.v)
FreeSurfer MGH/MGZ Volume(.mgh/.mgz)
Guys Image Processing Lab (.gipl)
ICS Image Cytometry Standard(.ics)
ITK format (.mha, .mhd)
MGH format (.mgh, .mgz)
Leica TIFF(.lsm).
MRtrix format n.b. currently only saves images saved as axial slices (.mif, .mih)
NRRD format (.nrrd, .nhdr)
POV-Ray Density_File(.df3).
Spectroscopic Imaging, VIsualization and Computing (SIVIC)(.idf).
Stimulate Sdt(.spr/.sdt)
Tagged Image File Format variations (.tif, .tiff, .lsm)
Vaa3D(.v3draw)
VTK legacy format of type STRUCTURED_POINTS (.vtk)

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.

Converting Images

Use the Import menu item to start dcm2nii. A new window appears, and you can set up your preferences by adjusting the values in the dcm2nii window toolbar. You then drag-and-drop the folder containing you DICOM images onto the dcm2nii window (note: if you drag the DICOM images onto the main MRIcroGL window you will view rather than convert the image). For more details see the dcm2nii wiki.

Additonal Images

MRIcroGL includes a few NIfTI format images to illustrate the software. These are intentionally low resolution to ensure quick downloads, minimal disk usage and compatibility with older computers. If you want higher resolution image, you can download the Extra Sample Images for MRIcroGL. The dcm2niix wiki includes details on many more datasets.

New Features

If you have used MRIcroGL before, but have updated to the latest version you may want to briefly find out what new functions have been added.

The MRIcroGL download includes a PDF file named "manual.pdf" - section 13 of the manual is named "New Features" and it describes changes and improvements to the software.
The latest/upcoming features are described on the beta page.

Wiki Search

Views

Actions