ITKGray-Using

From VISTA LAB WIKI

Jump to: navigation, search

This page describes how to use ITKGray, a software tool we use for white matter classification. We derive gray matter and 3D meshes from the white matter using Matlab tools. Installation instructions can be found on the installation page. And yes, we realize we should probably call this tool ITKWhite.


Contents

[edit] Overview

Many of the mrVista analyses depend on an accurate classification of white matter. The classification file is used for creating the gray matter, building meshes for visualizing data, measuring the area and thickness of gray matter, and showing the target destinations of fibers tracked from diffusion data.

ITKGray uses a T1-anatomical image as the basis for classifying gray and white matter tissue. The program then outputs a file that matches the 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 run ITKGray on Windows-32 platform and several Linux systems directly.

Prior to March 2009, we Windows implementations only ran ITKGray under Cygwin. (See below for older Cygwin-based installations). I am not sure about the current status of the 64-bit Windows implementation - it seems to be the same as for the old Cygwin (partially working).

[edit] Using ITKGray

Below we describe opening a T1-natomical file, applying the ITGray 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.

[edit] Starting a new Segmentation

ITKGray begins from the T1 anatomical, usually stored in a compressed NIFTI file such as t1.nii.gz file. Instructions for acquiring and creating a T1 anatomical. are in the anatomy processing section of this manual. Anatomical data are also available for downloading.

  • To open a t1.nii.gz file you have to navigate to it using:
File > Load Data > 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:
/cygdrive/y/data/anatomy/subSurname/t1.nii.gz
  • The same intuition applies if you use the Browse function.
  • Click Next - the SnAP Image Input Wizard (shown below) will appear
    The SnAP Image Input Wizard dialog windows.
  • 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).

[edit] Automatic segmentation tools

The following describes the usage of each of the tools shown in the image below.
The ITKGray Toolbox.

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.
# Cavitites - 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.


[edit] 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.

[edit] 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

[edit] Segmentation Options

Active Drawing Label
This is the label with which you draw when you use the polygon tool, the paintbrush tool and variou 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.

[edit] 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.

[edit] 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);
   writeFileNifti(roini);

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');
   ni.data = zeros(size(ni.data),'uint8');
   ni.fname = '/path/to/empty/segmentation.nii.gz';
   writeFileNifti(ni);

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

[edit] 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';
 writeFileNifti(ni);

[edit] Creating a mesh

See the Mesh Visualization to create meshes from ITKGray output.

There were also methods for creating meshes with mrGray.

[edit] Cygwin

Initially ITKGray was compiled to run in Windows under Cygwin, a Unix emulation. If you are using an older Cygwin install, you should probably just get the Windows-32bit version.

If you want to keep using the cygwin version, follow the old installation instructions. Then in a Cygwin terminal change directory to the ITKGray folder.

> cd /ITKGray, or
> cd /cygdrive/c/cygwin/ITKGray

Note that changing directories through /cygdrive will allow you to access all of the drives that you have mapped on your computer. This will be crucial for opening a t1.nii.gz file later. Now you can run the executable as

> ./InsightSNAP
Personal tools