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:

1. Add mrAlign to your matlab path. The easiest way to do this is to add the following lines to your startup.m file:

     addpath(genpath('<parent directory>/mrTools-4.5'));

2. Run matlab and cd to the directory containing the image volumes that you want to align. Run mrAlign by typing 'mrAlign' at the matlab prompt.

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.

1. The qform specifies the coordinates (in millimeters) for the center of each voxel relative to the center of the scanner bore (which is set to have cordinates [0,0,0]). This field of the header is not changed by mrAlign.
2. The sform specifies the transformation (rotation, translation, rescaling) from each voxel to a base coordinate system. The alignment between any two scans is the sform of one multiplied by the inverse of the sform of the other one.

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

1. Load the volume: File menu - Load Destination (volume). The “destination” is the coordinate frame that you will be aligning to.
2. If you get the warning message “No base coordinate frame in the volume header”, click ok.
3. [Optional] Set the base coordinate frame: File Menu - Set Base Coordinate Frame. 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.
4. Load the inplanes: File menu - Load Source (inplane). The “source” is the anatomy that will be aligned to the “destination”.
5. Initialize the alignment: Compute Alignment menu - Initialize Alignment from Header.
6. View the transformed inplanes superimposed on the volume. Page through the slices and slice orientations using the “Slice” slider and the “sagittal”, “coronal”, and “axial” radio buttons to view the alignment. Use the “Alpha” slider to adjust the transparency of the superposition. Use the “Overlay” button to toggle the overlay on and off.
7. [Optional] Manually adjust the alignment using the “Translation” and “Rotation” text fields (not always necessary).
8. [Optional] Set the crop region.
9. Compute the alignment: Compute Alignment menu - Robust Intensity-Based Alignment.
10. Check the alignment: Check Alignment menu - With Intensity/Contrast Correction.
11. Save the alignment: File menu - Save Alignment.

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:

1. Load the inplanes (instead of the usual volume) as the destination volume.
2. Load an example functional as the source. You will be prompted to select either the first frame or the mean (over time).
3. Proceed as usual (see above). Try using a very conservative crop region (cropping everything outside the brain) to make the automatic alignment work better, but you may need to rely on the manual alignment tools if the image contrasts are incompatible.

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.

1. Load the high resolution volume anatomy as the destination: File menu - Load Destination (volume).
2. If you get the warning message “No base coordinate frame in the volume header”, click ok and then set the base coordinate frame: File Menu - Set Base Coordinate Frame. If you don't get this warning then it has already been set and you don't need to do it again.
3. Load the inplanes: File menu - Load Source (enplane) from “Anatomy folder”.
4. Initialize the alignment: Compute Alignment menu - Initialize Alignment from Header.
5. Set the crop region
6. Proceed as described above to compute, check, and save the alignment

Part II: Once the inplane anatomy has been aligned, then, proceed to align the functionals to the inplane.

1. Load the inplane anatomy as the destination: File menu - Load Destination. Or, if you still have the inplane loaded as the source from Part I, you can simply do File menu - Reload Source as Destination.
2. Load the first functional as the source: File menu - Load Source. You will be prompted to select either the first frame or the mean over time. First try using the first frame (because it has more gray/white contrast). But if it looks lousy because of poor SNR then repeat this step using the mean.
3. Initialize the alignment: Compute Alignment menu - Initialize Alignment from Header. This should already give a pretty good alignment unless the subject moved a lot in between the inplanes and the first functional run.
4. [Optional] Manualy adjust the alignment using the “Translation” and “Rotation” text fields.

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)

1. Save the alignment to mrLoadRet by using File/export/mrLoadRet-4.5. You will be prompted to choose which groups to export to. This will update the nifti headers in the time series files as well as the mrSession variable (no need to run mrUpdateNiftiHdr).

If you have not yet run mrInitRet/mrInit

1. Save this alignment to all of the functionals: File menu - Save Alignment to File(s). This prompts you to select one or more files and you should choose all of the functionals.
2. Check the alignment for each of the functionals by loading each successively: File menu - Load Source. Optionally adjust the alignment manually using the “Translation” and “Rotation” text fields and then save it: File menu - Save Alignment

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.

Quit: Quits.

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.

1. Use the translation and rotation text fields to manually improve the alignment before running the automatic alignment algorithm. Save the manual alignment before running the automatic alignment so that you can reload it and try again if necessary.
2. Set a smaller crop region to improve the contrast correction (see above).
3. Check that the voxel sizes and volume sizes are correct by inspecting the global variable ALIGN. It is best to do this after loading the volume with the “Load Volume (raw orientation)” option in the File menu.
   1. ALIGN.volSize: size of the volume array
   2. ALIGN.volume: volume array. Note that ALIGN.volSize should equal size(ALIGN.volume).
   3. ALIGN.inplanes: inplane array.
   4. ALIGN.scaleFac: 2×3 array that specifies the voxel size. Top row is 1 over the voxel size for the inplanes. Bottom row is 1 over the voxel size for the volume.
4. Do the best you can with a manual alignment. If the image contrasts are not reasonably well matched then this is the best that can be done. Future versions of mrAlign will offer alternative alignment algorithms that will enable automatic alignments between images that differe more greatly in image contrast.

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;

results in:

h.qform44

ans =

   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

/share/wotan/heegerlab/mrAlign-4.x

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:

• Load the header into matlab

hdr = cbiReadNiftiHeader('your_anatomy_filename.hdr');

• check its qform

hdr.qform44

• the last column should have values that are half the dimensions of the volume. The dimesions of the volume are in hdr.dim
• Also, the sign of the values in the last column should be the opposite sign to its corresponding value on the diagonal.
• Make sure to set the qoffset_x, qoffset_y, qoffset_z to the same values
• and write back the header

cbiWriteNiftiHeader(hdr,'your_anatomy_filename.hdr');

• There is an ALIGN.origin field to specify the origin of the coordinate system. This was previously (in mrAlign-4.4) assumed to be [1,1,1]. It is now set by default to be [0,0,0] which I believe is the nifti convention. See interpVolume.m for an example of how this is done. There is partially redundant code in refreshAlignDisplay (awkward to modularize this to eliminate the redundancy).

• I got rid of the the x-y swap (at Jonas's request). This was harder than I expected it to be. The first complication is that meshgrid and interp3 actually work very nicely for [y,x,z] but very unintuitively for [x,y,z]. See interpVolume.m for an example of how this has to be done. The other complication is that the underlying image processing routines (e.g., estMotion3) assume [y,x,z]. I didn't want to change those functions so there is line in computeAlignment.m that looks like this:

       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.

• Changed names of a bunch of the functions (Oscar had been using unintuitive names).

• Added a feature for doing coarse alignment, that subsamples the source and destination volumes.

• Added a GUI to checkAlignment so that you use a slider to page through the slices rather than hitting the space bar.

• The rotation and translation text boxes behave more intuitively. Translation in x, y, and z corresponds to the cardinal axes of the volume (not the inplanes). Rotation axes are also the cardinal axes of the volume but the center of rotation is the center of the inplanes. I did not yet add sliders to go with these text boxes. But I'm hoping that the combination of having a more intuitive behavior from the text boxes coupled with the new coarse alignment feature will make that unnecessary.

I need your help with the following:

• Some examples of nifti files that are in correspondence (e.g., online vs offline reconstruction) to make sure that the origin bug has now been fixed.

• We need to find every line of mrLoadRet code that uses the alignment xform because the same change to the origin will have to be made in all of those places for consistency. At least it was internally consistent before with mrAlign-4.4.