(Difference between revisions)
Jump to: navigation, search
(Source Code)
(Source Code)
Line 41: Line 41:
== Source Code  ==
== Source Code  ==
The source code for ItkGray can be obtained using svn: '''SVN:''' Repo URL: <nowiki></nowiki> <br> # Linux Checkout Command svn checkout <nowiki></nowiki> '''COMPILE'''<br>
The source code for ItkGray can be obtained using git.  
:If the pre-compiled binaries don't work for you, you can build [[ItkGray]] on any reasonably modern linux system. Just get the [] shell script, save it to disk somewhere with a few hundred MB available, and run it. This script will download and build the [[ItkGray]] dependencies (CMake, FLTK, ITK, and VTK) and then download and build the latest version of [[ItkGray]]. The entire process should take a couple of hours.
'''GIT:''' Repo URL:<br>
Git clone Command:
  git clone
If the pre-compiled binaries don't work for you, you can build [[ItkGray]] on any reasonably modern linux system. Just get the [] shell script, save it to disk somewhere with a few hundred MB available, and run it. This script will download and build the [[ItkGray]] dependencies (CMake, FLTK, ITK, and VTK) and then download and build the latest version of [[ItkGray]]. The entire process should take a couple of hours.
= Using itkGray  =
= Using itkGray  =

Revision as of 09:31, 24 May 2017

ItkGray uses a T1-anatomical image as the basis for classifying gray and white matter tissue. Many MrVista analyses depend on an accurate classification of white matter. The classification is used to derive the gray matter, build meshes for visualizing data, measure the area and thickness of gray matter, and show the target destinations of fibers tracked from diffusion data.

ItkGray outputs a file that matches the T1 anatomical in size; each voxel is classified as white, gray, or CSF. In addition to the general classification, there are further classifications in terms of more specific labels for certain specific anatomical locations. We derive gray matter and 3D meshes from the white matter using Matlab tools.

And yes, we realize we should probably call this tool ITKWhite.




ITKGray is a segmentation tool adapted and developed from ITKSnap by Bob Dougherty. ITKGray is a branch of the ITKSnap project. Bob added functionality from MrGray-Retired, including topology checking/fixing and a new flood-fill paintbrush that is similar to the MrGray-Retired auto-segmentation methods, but is run on small sections of an image rather than the entire image at once.

If you use ITKGray in published work, please consider citing the ITKSnap folks with the following citation: Paul A. Yushkevich, Joseph Piven, Heather Cody Hazlett, Rachel Gimpel Smith, Sean Ho, James C. Gee, and Guido Gerig. User-guided 3D active contour segmentation of anatomical structures: Significantly improved efficiency and reliability. Neuroimage. 2006 Jul 1; 31(3):1116-28. bibtex | pubmed | doi:10.1016/j.neuroimage.2006.01.015.


The following information describes how to install the new software and get it working on your Linux box or Windows machine. You can get ITKSnap compiled for Macl from the ITKSnap downloads. ITKSnap is very similar to ITKGray, but lacks the topology checking tools.


ItkGray has been compiled to work with the latest versions of Linux, as well as some older versions, as a standalone program. Once the download is complete unpack the .zip and the executable file will be in the /bin folder.



The current version of ItkGray will run directly under Windows.


Note: The Windows 32-bit .exe will also run on 64-bit windows. However, some functions, such as rendering a 3D mesh, may not work in win64.

Source Code

The source code for ItkGray can be obtained using git.

GIT: Repo URL:

Git clone Command:

 git clone


If the pre-compiled binaries don't work for you, you can build ItkGray on any reasonably modern linux system. Just get the shell script, save it to disk somewhere with a few hundred MB available, and run it. This script will download and build the ItkGray dependencies (CMake, FLTK, ITK, and VTK) and then download and build the latest version of ItkGray. The entire process should take a couple of hours.

Using itkGray

Below we describe opening a T1-anatomical file, applying the ITKGray segmentation tools, and saving the classification file. Methods for integrating the classification data with visualization tools and mrLoadRet and mrDiffusion are described in those sections of the manual. mrGray segmentations may be edited with ITKGray following an update from mrGray format.

General Methods

Starting a new Segmentation:

ItkGray begins from the T1-anatomical, usually stored in a compressed NIFTI file (e.g., t1.nii.gz file). Instructions for acquiring and creating a T1 anatomical are in the anatomy processing section of this manual. Sample anatomical data are available for downloading.

  • To open a t1.nii.gz file you have to navigate to it using:
File > Open > Grayscale Image
  • To get to the data in Windows you need to have the drive mapped. Once you have the drive mapped you can go to the assigned drive letter in the /cygdrive/ directory. For example, if you have biac1 mapped to the Y: drive you would go to:
  • The same intuition applies if you use the Browse function.
  • Click Next - the SnAP Image Input Wizard (shown below) will appear
  • Image Orientation - For data processed through our pipeline, the correct RAI code is 'LPI'.
    Click Next
  • Image Summary - Shows information including Image Dimensions and Voxel Size
    Click Finish
  • Restore Settings - Use this option for files you have opened before to restore the settings you have used previously.
    Click Restore Settings

Thus, to begin a manual segmentation all that is needed is a T1 in nifti format.

  • Load the t1.nii.gz
File> Load Data> Greyscale Image

You can now use ITKGray tools to begin Segmentation. If you chose not to do an initial segmentation, or if you wish to pick up where you left off on a previous segmentation, you can manually segment using the tools in ITKGray (see below).

Segmentation Tools:

The following describes the usage of each of the tools shown in the image below.
1. Crosshairs Tool: Used to move the position of the cursor. You can also move through slices (with any tool selected) by rotating the mouse wheel.
Left Click - Moves the cursor. 2. Zoom Tool: Use this tool to increase the image size for a better view when segmenting. You can also check the box Zoom slices together to apply the same zoom to all three views.
Right Click - Drag up zooms in, Drag down zooms out.
Left Click - Moves the image in the window. 3. Polygon Tool: Provides slice by slice segmentation.
Left Click - With Continuous selected: - drag to create a polygon. With line segments selected - click once to set a point of the polygon.
Right Click - Close the polygon.
Accept - Click to apply the segmentation.
Delete - Click to remove the polygon. 4. Topology Tool: This tool provides information regarding the removal of excess volumes, the filling of cavities, and the location of handles as well as the option to smooth the segmentation.
Update - Click to update information regarding the segmentation. The number of volumes, cavities, and handles will be displayed.
# Volumes - Click Del to remove excess volumes.
# Cavities - Click Fill to fill cavities.
# Handles - Click Find to locate the handles. The coordinates for all the handles that are found will be listed under 'Handle Locations:'.
Smooth - Click to apply a smoothing function to your segmentation. This will remove a number of handles. 5. Paintbrush Tool: This tool is the one we use most often for manual segmentation and editing.
Left Click - Adds area to the selected segmentation label
Right Click - Removes area from the selected segmentation label
Tool Options:
Shape - Changes the shape of the segmentation brush. Note that Floodfill is a feature often used to segment large areas and works quite well.
Size - Sets the size of the tool.
Smooth - Sets the smoothness for the tool, larger smoothness values result in a less detailed segmentation.
Tolerance - Sets the tolerance level for the Floodfill tool. Smaller numbers result in a more detailed and strict segmentation.
3D Brush - Applies the segmentation across all three dimensions. Un-check this box if you want to do a 2D segmentation, or edit a segmentation in one plane. 6. Snap Tool: ITKGray's automatic segmentation tool. This tool allows you to select a region of interest for automatic segmentation.
Left Click - Click and drag the dashed red lines to select the region for automatic segmentation.
Reset Region - Resets the ROI to cover the entire volume.
Segment 3D - Starts the automatic segmentation.

Editing an Initial Segmentation:

If you have already have an initial segmentation using the FSL pipeline, or if you are coming back to an earlier segmentation, you can edit the segmentation with ITKGray.

Load an existing segmentation
  • Load the greyscale image (averaged T1) - File> Load Data> Greyscale Image
  • Load the segmentation (e.g., t1_class.nii.gz) -File> Load Data> Segmentation Data
  • Load the segmentation labels (e.g., t1_class.lbl) - File> Load Data> Label Descriptions
  • Edit the segmentation using ITKGray tools.

Saving a Segmentation:

As with any segmentation it's a good idea to save frequently. When you save a segmentation image note that the labels are not automatically saved. If you have not loaded label description you must save them separately. They are saved as a .lbl file.

Save a segmentation image:
File > Save Data > Segmentation Image
Save label descriptions:
File > Save Data > Label Descriptions

Segmentation Options:

Active Drawing Label
This is the label with which you draw when you use the polygon tool, the paintbrush tool and various other segmentation tools in ITKGray. You can select from a list of labels, or you can create your own using the label editor (see below).
Draw Over
This dropdown gives you more control over drawing. It specifies which voxels may or may not be overridden by the active drawing labels during drawing operations.
  • All labels - Segmentation operations will label all voxels with the active drawing label.
  • Clear label - Segmentation operations will override only those voxels that have not already been assigned another label.

Editing Labels:

You can create a new label and edit/delete an existing label by clicking the Edit Labels button.

Creating a new label
Click Edit Labels > Choose New at the bottom of the dialogue.
In the description field you can enter the name for the new label and choose a color, set the opacity and choose the visibility options for that label.

Advanced Methods

Below you will find sections that describe some advanced methods and additional tasks relevant to using ITKGray

Importing an ItkGray segmentation nifti in dtiFiberUI

You may want to use an ROI created in ITKGray to track fibers in dtiFiberUI. If you are lucky, File --> ROIs --> Load/import ROI from nifti should work fine.

However, you may receive the following error:

  Error using ==> sub2ind
Out of range subscript.
Index exceeds matrix dimensions.

An ROI imported from an ITKGray nifti with this error yields strange coordinates upon further investigation (ROIs --> Find Current ROI; mrAnatXformCoords; -147, -242, -7). It looks like the problem in the ROI coords is that the qto xform in the nifti files isn't correct.

There is a known issue in ITKGray in that the NIFTI qto xform is not set correctly when you create a new segmentation within ITKGray. This issue will be solved in the next official release of ITKGray, which is due out this summer.

In the meantime, to solve the problem, take the qto from the t1 file that you used as the gray image in ITKGray when you edited the ROI and copy it into the qto xform field in the ROI nifti file, using the following code:

   t1Ni  = readFileNifti('/path/to/t1.nii.gz');
 roiNi = readFileNifti('/path/to/roi.nii.gz');
 roiNi = niftiSetQto(roiNi,t1Ni.qto_xyz);

Or, you can fix the problem before starting to define the ROI by creating a segmentation in matlab from the t1 nifti:

   ni = readFileNifti('/path/to/t1.nii.gz'); = zeros(size(,'uint8');
 ni.fname = '/path/to/empty/segmentation.nii.gz';

If you then open that segmentation file, edit your ROIs, and save it, then all should be fine.

Updating mrGray Segmentations

We have utilities to import the many mrGray segmentations into ITKGray format. This involves both converting the vAnatomy.dat file into a NIFTI file, and then transforming the mrGray class files for the left and right hemisphere segmentations into a NIFTI class file that ITKGraycan use.

To convert from the older vAnatomy.dat format to the newer NIFTI format, we recommend reprocessing your raw anatomical I-files to create a high quality NIFTI anatomical, as described in the Anatomical section of the manual.

Then convert your mrGray class files using

mrGrayConvertClassToNifti(leftClassFile, rightClassFile, vAnatFile, t1NiftiFile)

If you don't have a t1NiftiFile, or the original I-files, but you do have the older vAnatomy.dat file, you can create a new NIFTI format anatomical using

 [vData,mmPerVox] = readVolAnat('path/to/vAnatomy.dat');
 % Convert mrgray sagittal format to our preferred axial format for NIFTI
vData = flipdim(flipdim(permute(vData,[3 2 1]),2),3);
mmPerVox = mmPerVox([3 2 1]);
xform = [diag(1./mmPerVox), size(vData)'/2; 0 0 0 1];
ni = niftiGetStruct(vData, inv(xform));
ni.fname = '/path/to/new/nifti/file.nii.gz';

Creating a Mesh

See the Mesh Visualization to create meshes from ITKGray output.

There were also methods for creating meshes with mrGray.

Tutorial: Segmentation of T1-Anatomicals

This outlines the general segmentation method. You can use this as a starting point, but you may adjust these methods (tolerance levels, optimal view, etc.) as you become a more experienced 'segmenter'.

T1 anatomicals are typically stored in NIFTI format (compressed) with a name such as t1.nii.gz

Coarse Segmentation

  • Using the Polygon tool in the saggital view, make a CSF border between the two hemispheres. Check the axial view to ensure that no white matter is overlapped by CSF in the first hemisphere to be segmented.
    NOTE: See below in order to figure out whether you will make two separate NIFTI files for each hemisphere or one file containing both segmentations. If you decide to do both hemispheres on one NIFTI, you will have to make sure no CSF leaks onto white matter in either hemisphere (or just redo the CSF barrier for the second hemisphere you segment).
  • Paste and accept into a few slices away from the midline.
    Csf polygon.png
    Csf polygon2.png

  • Set the active drawing label to 'white' with the correct hemisphere.
  • Use the Paintbrush tool to fill in most of the white matter and the ventricles.
    The axial view works well for this; using Floodfill with the 3D brush on at a tolerance of ~5 and/or the square and round brush.
  • It may help to start dorsally and work down, cleaning up the subcortical areas as you progress.
    Segment coarse1.png

Fine Segmentation

  • Once you have filled in most of the brain with Floodfill set to 3D brush on, use the Paintbrush tool and go through each of the other two views, doing a more careful, slice by slice segmentation.
    • The saggital view works well to start; using Floodfill with the 3D brush off at a tolerance of ~2-3. (The tolerance may shift depending on individual t1 contrast and quality.)

Segmenting Difficult Brain Sections

  • Temporal lobe: the best view is the coronal slices, but be sure that it also looks correct in the saggital slices.
    Temporal sagg.png
    Temporal coronal.png

  • Occipital lobe: working in the axial slices allows for the best view when trying to distinguish occipital white matter and CSF/sinus. However, occipital segmentation requires that you check all three views carefully.
  • Subcortical Structures:
    • This is the trickiest area to segment; it is done best with 3D brush off because you don't want white matter leakage from the other slices.
    • The best tool for this job (in Kathleen and Alina's opinion) is the Polygon Tool. Since the subcortical areas are not integral to our research, this allows you to fill in large areas neatly and quickly.
      With the Polygon Tool, trace a subcortical area that you want to fill with white matter.
      Segment coarse2.png

    • Paste and accept into a few slices down, until the white matter is distinct from the brain stem. (See below for example)
      Segment coarse3.png

  • Kathleen will add more subcortical tips.

Handle & Hole Checking

  • After you have sufficiently segmented a hemisphere, use the Topology tool to check for handles.
    If you segmented pretty well, the topology check should have less than ~10 handles. If there are considerably more, you may want to go through slice-by-slice again, focusing on the difficult areas.
    • Delete any volumes and fill any cavities, and Update the topology check.
    • When you have relatively few handles, select Find.
      • With the pull down box, you can navigate to each handle and fix it.
      • This work best with the 3D brush off, to avoid creating more handles. However, it may be necessary to check all three views, and to scroll through a few slices on either side to sufficiently delete each handle.
    • Work through each location until the Topology Check Update shows 1 volume, 0 cavities, and 0 handles.
  • Although the Topology tool will find many of the handles, it is not perfect. You also need to manually check the brain for holes.
    • Select Update Mesh to see your segmentation.
      • The 3D trackball tool allows you to rotate and zoom on the segmentation. Left click to rotate; right click and drag to zoom.
      • The 3D navigation tool allows you to move the crosshairs to select a point on the segmentation.
    • Look over the segmentation for any holes or handles the topology check may have missed.
      • It may be helpful to scroll through the slices to precisely locate and position the crosshairs on a hole.
        Mesh holecheck1.png
  • Look at the three views to fix the hole/handle. Again, it may be necessary to check multiple views, and scroll through a few slices on either side of the hole.
  • Select Update Mesh, before moving the segmentation, to make sure the hole is fixed.
    Mesh holecheck2.png
  • When you have looked carefully over the entire hemisphere for holes, it may be a good idea to update the topology check again.

Installing the Completed Segmentation

  • If you segmented each hemisphere separately (in a separate .nii.gz file), you will need a .gray and .class file for each hemisphere:
    • Follow these instructions to make the .gray and .class file: Converting NIFTI to mrGray Files
    • Follow these instructions to install the segmentation:
      • To specify the segmentation files for a given session, enabling the gray view, go to the Inplane window and select:
      • Gray -> Gray/White Segmentation -> Install or Reinstall Segmentation OR type installSegmentation; in the MATLAB window.
      • Select the .class and .gray file for each hemisphere when prompted.
  • If you segmented both hemispheres in the same .nii.gz file, you can directly install the nifti containing the segmentation without making .class or .gray files:
    • Follow these instructions to install the segmentation:
      • To specify the segmentation files for a given session, enabling the gray view, go to the Inplane window and select:
      • Gray -> Gray/White Segmentation -> Install or Reinstall Segmentation OR type installSegmentation; in the MATLAB window.
      • Select the .nii.gz file containing the segmentation for one hemisphere. You will not need to install the other hemisphere.
      • If it asks you for the number of Gray Layers, we usually specify 4 layers for a 1mm isotropic T1 anatomical image. This results in a gray layer of 4 mm, which is sufficient for our brain areas of interest.

Methods for Checking the Mesh (optional)

There are several ways that you can check the gray matter grown based on your segmentation:

  • If you have saved both hemispheres in one NIFTI file you can use:
    • mrgSaveClassWithGray(nGrayLayers, classFileIn, classFileOut)
    • This function outputs a new NIFTI file which now contains the gray matter grown based on the number of layers that you've specified.
    • You can open this file in itkGray and make sure that your gray matter is to your satisfaction.
  • If your hemispheres are in separate NIFTI files or you have already installed segmentation, you can check your gray layers in mrVista:
    • Go to Volume view (type mrVista 3 in the command window)
    • From the Volume window, go to ROI->Create->Create Gray Roi
  • You can also build a mesh in MATLAB using meshBuildFromClass or meshBuildFromNiftiClass. Example:
    • set classFile to hemi.classfile (classFile = 'Right.Class')
    • Build mesh (msh = meshBuildFromClass(classFile))
    • Smooth mesh (msh = meshSmooth(msh))
    • Smooth mesh (msh = meshSmooth(msh,1))
    • Color mesh (msh = meshColor(msh))
    • Visualize mesh (meshVisualize(msh))
Personal tools