Image mapping options after registration
Overview
After the registration/spatial normalization step, DTI-TK outputs, for each subject, two transformations that together defines the mapping from the subject to the template space:
- the affine transformation stored in a text file with suffix aff, which minimizes the global difference between the subject and the template, and
- the displacement field stored in a NIfTI formatted vector volume with suffix df.nii.gz, which minimizes the residual local difference between the subject and the template.
Two common needs arise here:
- to warp the subject data in its native space to the template space with a single interpolation operation;
- to warp the template to the native space of a particular subject with a single interpolation operation.
Meeting these needs require the ability to combine the affine transformation and the displacement field into one single displacement field, as well as the ability to invert this single displacement field. This tutorial will describe the procedure to accomplish these goals.
In addition, we will also describe how to
- warp images with the affine transform only;
- warp images to voxel sizes different from the target volume.
Combined displacement field from the native space to the template space (:showhide init=hide div=combined_displacement_native_to_template:)
Recall that when registering some subject data with the filename subj.nii.gz, the output affine transformation file will be subj.aff and the output displacement field will be subj_aff_diffeo.df.nii.gz. The command to combine these two transformations is dfRightComposeAffine
dfRightComposeAffine -aff subj.aff -df subj_aff_diffeo.df.nii.gz -out subj_combined.df.nii.gz
The combined displacement field will be stored in subj_combined.df.nii.gz.The diagram below illustrates the relationship between all the transformations and images.
Mapping the subject data to the template space (:showhide init=hide div=mapping_to_template_space:)
During the registration/normalization step, the subject data subj.nii.gz will be first warped by the affine transformation to produce subj_aff.nii.gz, which will be subsequently warped by the deformable transformation to produce subj_aff_diffeo.nii.gz. Evidently, the two steps require two image interpolation/resampling operations. Using the combined displacement field we have just computed above, we can map the subject data directly to the template space with a single interpolation operation. This is usually more desirable to minimize the smoothing effect of interpolation. This is achieved with the command deformationSymTensor3DVolume.
deformationSymTensor3DVolume -in subj.nii.gz -trans subj_combined.df.nii.gz -target mean_initial.nii.gz -out subj_combined.nii.gz
The option -target allows you to specify the desired voxel space to output the warped data. In our example, the warped data will have the same voxel space as mean_initial.nii.gz. You can provide a different image with a different voxel space as you wish, e.g., to output the warped image at a lower or higher spatial resolution.
Extra Goodies
Warping your DTI data to the template space with a different voxel size
Often, we need the warped data in a voxel space with a different voxel size, i.e., to have higher spatial resolutions for subsequent analyses. This can be achieved by specifying the desired voxel size with the flag
-vsize". For example, adding -vsize 1 1 1" to the command above will result in a warped volume with isotropic voxels of 1x1x1 mm^3.
A pair of convenience scripts for warping your DTI data to the template space
Given how often we need to do this, we provide two convenience scripts for this task:
dti_warp_to_template and
dti_warp_to_template_group. The former combines the computation of the combined warp described above and the warping into a single command. The latter makes this even easier for a collection of subjects.
dti_warp_to_template subj1.nii.gz template.nii.gz 2 2 2
This warps the
native subject DTI data
subj1.nii.gz to the space defined by the DTI template
template.nii.gz using the DTI-TK estimated transformations
subj1.aff and
subj1_aff_diffeo.df.nii.gz, such that the output voxel spacing is 2x2x2. The output from the script includes the normalized DTI data
subj1_diffeo.nii.gz and the combined transformation (displacement field)
subj1_combined.df.nii.gz.
dti_warp_to_template_group subjs.txt template.nii.gz 2 2 2
This applies the same command as above to a collection of the
native subject DTI data.
Warping your scalar-valued data
There is a similar command for warping scalar volumes called
deformationScalarVolume. The example below shows how to warp the FA map of the same image with this command.
deformationScalarVolume -in subj_fa.nii.gz -trans subj_combined.df.nii.gz -target mean_initial.nii.gz -out subj_fa_combined.nii.gz
Note that you can compute the warped FA map of a subject DTI volume in two ways. One is to warp the DTI volume and then compute the FA map. Or you can first compute the FA map then warp the FA map. Many people in the DTI community argue that the former is preferred because the interpolation accounts for the tensorial properties.
Combined displacement field from the template space to the native space (:showhide init=hide div=combined_displacement_template_to_native:)
Use the same example as the one above. We will compute the inverse of the affine transformation and that of the deformable transformation, then combine them appropriately. The steps are as follows:
1. compute the inverse of the affine transformation with the command
affine3Dtool
affine3Dtool -in subj.aff -invert -out subj_inv.aff
The computed inverse will be stored in subj_inv.aff.
2. compute the inverse of the deformable transformation with the command
dfToInverse
dfToInverse -in subj_aff_diffeo.df.nii.gz
The computed inverse will be output as subj_aff_diffeo.df_inv.nii.gz.
3. combine the two inverted transformations with the command
dfLeftComposeAffine (not
dfRightComposeAffine)
dfLeftComposeAffine -df subj_aff_diffeo.df_inv.nii.gz -aff subj_inv.aff -out subj_combined.df_inv.nii.gz
The combined displacement field will be stored in subj_combined.df_inv.nii.gz.
Mapping the atlas space data to the subject space (:showhide init=hide div=mapping_to_subject_space:)
The command to achieve this is the same as the ones described in the section on mapping the subject space data to the atlas space. Obviously, you will need to use the appropriate combined displacement from the template space to the native space of the subject data. This is useful for atlas-based segmentation in which you create some region definition in the atlas space then segment the corresponding region in the subject space by warping. The command will look like this
deformationScalarVolume -in roi_atlas.nii.gz -trans subj_combined.df_inv.nii.gz -target subj.nii.gz -interp 1 -out roi_subj_space.nii.gz
where roi_atlas.nii.gz is some segmentation in the template space and the output roi_subj_space.nii.gz will be the same segmentation mapped onto the native space of subj.nii.gz. The additional flag -interp is used to choose the nearest neighbor interpolation, rather than the default trilinear setting. This usually makes the most sense for propagating binary segmentations.
Warping the images with affine transforms only (:showhide init=hide div=affine_warping:)
The commands for warping scalar and tensor volumes are the affineScalarVolume and affineSymTensor3DVolume, respectively. For scalar volumes, the typical usage is
affineScalarVolume -in input.nii.gz -out output.nii.gz -trans input.aff -target reference.nii.gz
Most of the options are self-explanatory. The -target option serves the same purpose as the one described above. Additional options can be viewed with the -h option.
For tensor volumes, the typical usage is the same, which is
affineSymTensor3DVolume -in input.nii.gz -out output.nii.gz -trans input.aff -target reference.nii.gz
