mrAlign is a matlab utility for aligning (or registering) MRI image volumes. We use it to align all of our data from an individual subject across scanning sessions on different days. In one scanning session, we acquire a high resolution volume anatomy. In each successive scanning session we acquire what we call “inplane” anatomies because they are anatomical images (like the destination) but acquired in the same slices as the functional MRI data. The high resolution volume anatomy is referred to below as the “destination” of the alignment and the inplane anatomy is referred to as the “source”.
The current implementation of mrAlign supports only Nifti file format. Nifti files have two alignment fields: qform and sform. The qform field specifies the slice prescription with respect to the scanner coordinate system. The sform field is typically not set when an image volume is initially acquired. mrAlign uses the qform fields from the source and destination to get an initial alignment (“Initialize Alignment from Header”). The alignment is saved in the sform field of the source (“Save Alignment”). For a detailed explanation of the qform and sform fields and how they are used, you may want to read the Coordinate Transforms section of the mrTools documentation.
mrAlign uses an image processing algorithm to refine the alignment (“Robust Intensity-Based Alignment”). The algorithm is described in detail in: Nestares & Heeger, Robust multiresolution alignment of MRI brain volumes, Magnetic Resonance in Medicine, 43:705-715, 2000.
In principle, mrAlign can be used to align any Nifti file with any other Nifti file. However, the automatic alignment will only work accurately if the two image volumes have similar contrast. For example, some MRI acquisitions produce images in which the cerebral spinal fluid (CSF) is dark whereas others produce images in which the CSF is bright. This is a problem for the automatic alignment. Even so, the manual alignment tools can still be used and the automatic alignment is quite robust with an appropriate choice of the crop region. In the future, we will be adding capability for inverting image contrast along with other automatic alignment algorithms to extend to utility of mrAlign.
mrAlign also has an interface for setting Talairach coordinates, for later use in aligning across subjects. It's easiest to do this on the original volume, the first time you load it, so the appropriate information is then propagated throughout the subsequent steps.
To run mrAlign:
mrAlign-4 uses the NiFTi header information to align the Inplane anatomy to the 3D volume anatomy and to align the functionals to the Inplane anatomy.
The NiFTI headers contain two fields that specify the coordinates for each voxel.
mrAlign uses the sform in the NiFTI header to save the alignments.
Generally a 3D volume anatomy is used as base coordinate system to align inplanes and functionals. The base coordinate system is set by the user (when this is done, the qform is simply copied in the sform of that scan). Once the base coordinate system is set for the 3D volume anatomy, then you can align inplane anatomies to the 3D volume anatomy, which sets the sform of the inplanes. And then once the inplanes have been aligned, you can align the functionals to the inplanes which sets the sform of the functionals. You need to do it in this order: 1) set the base coordinate system of the 3D volume anatomy; 2) align inplanes to volume, 3) align functionals to inplane. This will set the sforms for every scan so that they are consistently aligned to one another. Trying to do it out of order won't work out correctly. For example, if you do step 3 before step 2 then the inplanes will be aligned to the volume but the functionals will not.
Usefull information regarding the NiFTI headers can be found here: http://nifti.nimh.nih.gov/pub/dist/src/niftilib/nifti1.h
mrAlign can be used to align inplane anatomy images with high resolution volume anatomies of the same subject's brain. It can also be used to align functional (EPI) MRI volumes with anatomical MRI volumes. For example, to align functionals to inplanes:
Note that if you first align the inplanes to the volume, and then align the functionals to the inplanes, then the functionals will be aligned to the volume. This is the nice feature of doing all of the alignments with respect to a base coordinate frame.
These are the procedures that we use in our lab for use with mrLoadRet.
Part I: Align the inplane anatomy to the high resolution volume anatomy.
Part II: Once the inplane anatomy has been aligned, then, proceed to align the functionals to the inplane.
If you have already run mrInitRet/mrInit (and there is an mrSession.mat file already existing. If you run “dofmrigru”, mrInit has run in the script. Please follow this step)
If you have not yet run mrInitRet/mrInit
Sagittal, coronal, and axial radio buttons: Select slice orientation.
Slice slider: Select slice. You can grab the slider and move it. You can click on the arrows at either end which moves by one slice at a time. Or you can click on the slider bar which moves by 10 slices at a time.
Alpha slider: Controls transparency of overlayed inplanes.
Transpose pushbutton: Transposes the displayed image (note that this effects the display only; it does not nothing the alignment parameters).
Flip pushbutton: Flips the displayed image (note that this effects the display only; it does not nothing the alignment parameters).
Overlay pushbutton: Toggles on and off the overlay.
Translation and rotation text fields: Enter numbers for manual adjustment to the alignment. The translation values are in mm. The rotation values are in degrees. These values are reset to zero whenever you load, initialize, or compute an alignment (from the File menu). Changing them to nonzero values will add an additional translation and/or rotation to the alignment that was just loaded or computed.
Load Destination (volume): (Re-)loads the destination volume file and displays it. The “destination” is the coordinate frame that you will be aligning to. Typically, this is a whole-brain high resolution volume anatomy. You can now use the “sagittal”, “coronal”, and “axial” buttons to display different slice orientations, and the “Slice” slider to display different slices.
Load Source (inplane): (Re-)loads the source volume file. The “source” is the anatomy that will be aligned to the “destination”. Typically, this is an inplane anatomy (i.e., that was acquired in the same slices as the fMRI data). The inplanes are superimposed on the volume as a semi-transparent overlay. Adjust the “Alpha” slider to change the level of transparency. Note that unless you have a reasonable alignment, the superposition of the inplanes and volume will be arbitrary. In fact, the inplanes might not even be visible.
Save Alignment: Saves the current alignment, overwriting the alignment (if any) that was in the source volume file. The alignment is saved in the sform field of the Nifti header.
Save Alignment to File(s): Saves the current alignment to multiple, overwriting the alignments (if any) that were in the source volume files. This is convenient, for example, if you have a series of fMRI scans in the same slice prescription so that you can set all of their alignments to be the same.
Save Aligned & Resampled Source: The above “save” options write only the alignment information to the header of the source volume file. This function resamples/interpolates/warps the source volume according to the alignment and saves the resampled volume. The result is a volume that is the same size as the destination volume. For a 4D file (a time series of volumes), it resamples and saves all time frames. You are advised to choose a new file name; if you overwrite the original source volume then the original data will be lost. This option will not normally be used for mrLoadRet but might come in handy for use with other software packages such as BrainVoyager and FSL.
Import Alignment: Imports the alignment from a separate file (instead of reading it from the header of the source and files). Note that this resets the “Translation” and “Rotation” text fields to zeros. This can be used to retrieve a different alignment already saved via “Export Alignment” if the current alignment is not good.
Import and Compose Alignments: Imports a pair alignments, each from a separate file, and composes them. Note that this resets the “Translation” and “Rotation” text fields to zeros.
Import Alignment from mrAlign-4.2 (or earlier): Imports using from the older file format.
Export Alignment: Exports the alignment to a separate file (instead of saving it in the header of the source files). This exports the alignment between the “source” and “destination”, ignoring the base coordinate frame. This is useful to save an initial alignment and be able to go back to it (by “Import Alignment”) if in any successive attempt to make such alignment better fails.
Export Alignment to mrLoadRet-3.1 (or earlier): Exports to the older file format.
Set Base Coordinate Frame: This is an advanced feature that can be used to define a base coordinate frame for the destination volume. This sets the base coordinate frame for the “destination” so that when the “source” is aligned to the “destination”, it will also be aligned with respect to that global frame of reference. Nifti files have two alignment fields: qform and sform. The qform field specifies the slice prescription with respect to the scanner coordinate system. The sform field is typically not set when an image volume is initially acquired. If the sform of your “destination” volume is not specified, then you will get a warning message when it is loaded (“No base coordinate frame in the volume header”). This is ok but it means that your “source” will be aligned only with respect to the “destination”. If, on the other hand, the sform field of the “destination” volume is specified, then that defines a base coordinate frame and your “source” will be aligned not only to the “destination” but also with respect to that global frame of reference. To do so, load the desired destination volume. Then choose “Set Base Coordinate Frame”. This overwrites the sform field in the destination volume to be equal to the qform, i.e., with respect to the scanner coordinate system. We typically use this feature to set the base coordinate frame only for the high resolution volume anatomy of each subject's brain. Once it has been set, all of the data that are aligned to that high res anatomy will share the same coordinate system. Warning: If the base coordinate frame (sform field) of the “destination” is changed, then the alignment between “source” and “destination” will no longer be valid. Before changing the base coordinate frame, it is wise to use “Export Alignment” which saves the alignment between “source” and “destination” in a separate file, ignore the base coordinate frame. Then after changing the base coordinate frame, use “Import Alignment” to reload it. Otherwise, you will have to re-align from scratch.
Write Tif Image: Saves the current display as a tif format image.
Set Alignment to Identity, FlipX, FlipY, FlipZ: These menu options are used for manual alignment, to be used in conjuction with the rotation and translation text boxes.
Initialize alignment from header: Computes an initial alignment from the slice prescriptions. Note that this resets the “Translation” and “Rotation” text fields to zeros.
Set Crop Region: One of the processing steps (during contrast correction) depends on fitting a model to the image intensity histogram. If the images include a lot of pixels from outside the head then the fitting procedure will fail, the contrast correction will be messed up, and there will be no hope for the automatic alignment to work well. This menu option allows you to select a crop region for the contrast correction step. It prompts you to select the first and last slice. Then it prompts you to select one of the remaining slices and to draw (left mouse clicks) a rectangle to choose the crop region. You want to do this to have your crop region filled mostly with brain. It's ok for this crop region to be too small (i.e., some of the brain can be outside the crop region). Note that the images are not actually cropped when computing the alignment. The crop region is used only for contrast correction. To confirm that you have chosen an adequate crop use the Check Alignment (with intensity/contrast correction) to see that the image intensity and contrast within the brain is well-matched (even if the alignment is bad). The same crop region is used for the automatic alignment algorithm; only the sub-volume within the crop region is included in the calculations.
Compute Coarse Alignment: This does an initial coarse alignment by subsampling the volumes. Useful optionally instead of adjusting the alignment manually before running “Compute Alignment”.
Compute Alignment: This is what you typically use to automatically refine the alignment. It will run for 10 iterations and then prompt you asking whether or not to continue. It will prompt again after the next 10 iterations. Iterating too many times likely means that the alignment is failing and you should stop to inspect the results (see Check Alignment and Trouble Shooting below). Once the automatic alignment stops (either because it has converged or because you have selected not to continue for more iterations), the display is refereshed and the “Translation” and “Rotation” text fields are reset to zero.
Invert Source Contrast: Not yet implemented. When implemented, this will be helpful when aligning functions to anatomical volumes because the image contrast is flipped.
With Intensity/Contrast Correction: Opens a new window with three panels. The first panel displays one of the source (inplane) slices. The last panel displays the corresponding slice interpolated from the destination (volume), using the current alignment. The middle panel displays a checkerboard of the source and destination slices. Use the slider to page through the slices then click “OK”. The image intensity and contrast should be well-matched in the middle panel. If it is not, then set a smaller crop region (see above).
Without Correction: Same as above but without the preprocessing steps that correct for intensity and contrast differences between the inplane and volume images. Useful mostly for debugging.
Joint Histogram: Not yet implemented.
Often you will find that when you try to align the epi images to the inplane that either the first or last overlay is missing (i.e. there is no red image overlay over the first or last slice). This is due to a slight roundoff error in the alignment matrices and is nothing to be worried about. Essentially what happens is that a small roundoff error causes the display code to try to interpolate in some points off the edge of the volume–these values get set to nan and therefore don't display. This will not affect your analysis or the alignment.
h.qform44(1:3,4) = -(h.dim(2:4)/2)+0.5;
1.0000 -0.0000 0.0000 -87.5000 0.0000 1.0000 -0.0000 -127.5000 0.0000 0.0000 1.0000 -127.5000 0 0 0 1.0000
It is best to compute the Talairach transformation immediately after loading the base volume, so that every subsequent step will seamlessly propogate the correct transformation. If you compute the transformation at a later stage, or if you want to go back and adjust the transformation, you can use the Export feature.
The Talairach transform is set by the user choosing anatomical landmarks, including the anterior commissure (AC), the posterior commissure (PC), and six additional points relative to these anchors (superior, inferior; right, left; and anterior, posterior) to define a cube around the brain volume. The cube is then transformed to the standard Talairach anatomy as described here. mrAlign has a Talairach function built-in to allow users to choose these points.
In the mrAlignGUI, there is a menu tab for Talairach. To set the transform, choose 'Set Talairach Transform'; to export the transform to other mrLR directories (to scans, anatomies, and ROIs), choose 'Export Talairach to mrLR4.5'. These are the steps you should follow whether you are defining the transform for the first time, or adjusting a previously determined transformation.
Click here for step by step instructions.
Current working versions of mrAlign can be found on
A cvs repository for the newest version of mrAlign can be downloaded from
cvs -d /share/wotan/heegerlab/CVS checkout mrAlign-4.5
Anatomies that have been manipulated with FSL tools do not have their qform matrix in the header set correctly. This can cause the compute alignment from header not to work properly. If you have averaged together three volume anatomies using the avw commands then this may be a problem. To fix it, you can do the following:
hdr = cbiReadNiftiHeader('your_anatomy_filename.hdr');
M = estMotion3(...); M = permuteM * M * permuteM; xform = xform * M;
where the permuteM matrix is used to swap x and y and then to swap them back again.
I need your help with the following: