Index
Contents
Name
mri_cvs_register
Synopsis
mri_cvs_register --mov arg1 --template arg2
Arguments
Required Flagged Arguments
--mov subjid |
FreeSurfer subject name as found in $SUBJECTS_DIR. This identifies the subject that is to be moved/registered to the target |
--template subjid |
FreeSurfer subject name as found in $SUBJECTS_DIR (or --templatedir). This identifies the subject that is to be kept fixed (template). If this argument is missing from the function call, the CVS template is used. |
Optional Flagged Arguments
--templatedir directory |
This option needs to be used if the template subject's SUBJECTS_DIR directory is different from that of the moving subject. All the relevant FS recon files should be located here. By default, without using this option, this parameter is set to be SUBJECTS_DIR. If the --template argument is not specified, so the registration is to the CVS template, this parameter is not implicitly set. |
--mni |
Use the CVS atlas in MNI152 space as a target for registration (as opposed to the default CVS template) |
--outdir directory |
Name of the output directory where all the registration results are written. The default is SUBJECTS_DIR/subjid/cvs, where subjid is the subject id of the moving subject. The final output directory is going to be ~.6G, but make sure that there is around double that amount of space available for the computations. |
--m3d |
Use m3d instead of m3z in order to represent the registration morphs (and to avoid potential gzip errors) |
--openmp N |
Assign the number of nodes for openmp runs to be N. The default is 1. Note, with N=8 you can get a threefold speed up. |
--nolog |
Do not produce a log file (default is 0) |
--version |
Print version and exit |
--help |
Print help and exit |
Partial Run of the Registration
--step1 |
Only do step 1 (spherical registration) |
--step2 |
Only do step 2 (elastic registration) |
--step3 |
Only do step 3 (volumetric registration) |
--noaseg |
Do not use aseg volumes in the volumetric registration pipeline (default is 0). Setting this option could shorten significantly the time of registration, however, might also take away from the accuracy of the final results. |
--nointensity |
Do not use the intensity volumes in the volumetric registration pipeline (default is 0). Setting this option could shorten significantly the time of registration. It also indicates that the intensity values are not to be trusted during the registration. |
--hemi |
Run the CVS registration on only one of the hemispheres. For example, in case of single hemisphere ex vivo cases |
--masktargethemi |
Use this with the --hemi flag when hemi is registered to full brain (in vivo) target. This will mask out the appropriate hemisphere in the target in order to avoid strange artifacts resulting from registering a single hemi to a full brain. |
--maskmovinghemi |
Use this with the --hemi option when full (in vivo) brain is registered to a single hemi (ex vivo) target. This will mask out the appropriate hemisphere in the moving volume in order to avoid strange artifacts resulting from registering a full brain to a single hemisphere. |
Cleanup Arguments
--nocleanup |
Do not delete temporary files (default is 0). If this option is set, make sure you have ~2G of space in the output directory |
--keepelreg |
Do not delete elastic registration (default is 0) outcome. If this option is set, make sure ~1G of space is available in the output directory |
--keepallm3z |
Do not delete m3z morph files that are computed during the CVS process (default is 0). |
--cleanall |
Overwrite/recompute all CVS-related morphs that might have been computed prior to the current CVS run (default is 0). |
--cleansurfreg |
Overwrite/recompute CVS-related surface registration morphs that might have been computed prior to the current CVS run (default is 0). |
--cleanelreg |
Overwrite/recompute the CVS-related elastic registration morph that might have been computed prior to the current CVS run (default is 0). |
--cleanvolreg |
Overwrite/recompute CVS-related volumetric morphs that might have been computed prior to the current CVS run (default is 0). |
Outputs
Relevant files that you should have in your directory (most recent on the top and the oldest in the bottom):
(a) Full CVS (with both (i) and (ii))
- final_CVSmorph_toTEMPLATE.m3z (formally: combined_toTEMPLATE_elreg_afteraseg-norm.m3z) : the final morph that combines correspondences recoved in steps (1), (2), (3) (i), and (3) (ii).
- final_CVSmorphed_toTEMPLAT_norm.mgz (formally: nlalign-afteraseg-norm.mgz) : the CVS morphed norm.mgz files; it is the final result of CVS and contains contributions from ALL registration steps (combination of the elastic morph and the two m3z files).
- final_CVSmorphed_toTEMPLATE_aseg.mgz (formally combined_toTEMPLATE_elreg_afteraseg-norm_aseg.mgz) : the CVS morphed aseg.mgz file; it is the final result of CVS and contains contributions from ALL registration steps (combination of the elastic morph and the two m3z files)
- step1_CVSmorphed_toTEMPLATE_aseg.mgz (formally: nlalign-aseg.mgz) : a morphed aseg.mgz file; it is the result of CVS up to (i) of step (3) and contains contributions from registration steps of the elastic morph and the aseg-based nonlinear registration.
- step1_CVSmorphed_toTEMPLATE_norm.mgz (formally: combined_toTEMPLATE_elreg_aseg_norm.mgz) : a morphed norm.mgz file; it is the result of CVS up to (i) of step (3) and contains contributions from registration steps of the elastic morph and the aseg-based nonlinear registration.
- el_reg_toTEMPLATE_aseg.mgz : the elastic morph applied to aseg.mgz
- el_reg_toTEMPLATE.mgz : the elastic morph applied to norm.mgz
- nlalign-afteraseg-norm.m3z : the morph resulting from (ii) of step (3) (intensity-based non-linear registration); it is not combined with the elastic registration morph. NOTE: current version does not keep this file anymore.
- combined_toTEMPLATE_elreg_aseg.m3z : the morph that combines correspondences recovered in steps (1), (2), (3) (i). NOTE: current version does not keep this file anymore.
- nlalign-aseg.m3z : the morph resulting from (i) of step (3) (aseg-based non-linear registration); it is NOT combined with the elastic registration morph. NOTE: current version does not keep this file anymore.
(b) shorter version of CVS (using only (ii) in step (3) of the algorithm):
- final_CVSmorph_toTEMPLATE.m3z (formally: combined_toTEMPLATE_elreg_norm.m3z) : the morph combines correspondences recovered in steps (1), (2), (3) (ii).
- final_CVSmorphed_toTEMPLATE_norm.mgz (formally: nlalign-norm.mgz) : the morphed norm.mgz files; it is the final result of CVS and contains contributions from ALL registration steps (combination of the elastic morph and the above m3z file)
- el_reg_toTEMPLATE.mgz : the elastic morph applied to norm.mgz
- nlalign-norm.m3z : the morph resulting from step(3) (intensity-based non-linear registration); it is NOT combined with the elastic registration morph. NOTE: current version does not keep this file anymore.
If you ran the mri_cvs_registration script with the "--nocleanup" option then you will see two more files called combined*tm3d. These files take up a lot of memory so by default are deleted. They can be recreated in case the cvs morph needs to be applied to another volume at a later time. The morphs left behind when using the "--nocleanup" option are:
(a)
- combined_toTEMPLATE_elreg_aseg.tm3d : the morph that combines correspondences recovered in steps (1), (2) and (3) (i)
- combined_toTEMPLATE_elreg_afteraseg-norm.tm3d : the morph that combines correspondences recovered in steps (1), (2), (3) (i) and (3) (ii)
- el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2). This file takes up a lot of memory so, by default, is deleted. It can only be recreated if the elastic registration step (--step 2) is re-run.
(b)
- combined_toTEMPLATE_elreg_norm.tm3d : the morph that combines correspondences recovered in steps (1), (2) and (3) (ii)
- el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2). This file takes up a lot of memory so, by default, is deleted. It can only be recreated if the elastic registration step (--step 2) is re-run.
If you ran the mri_cvs_registration script with the "--keepelreg" option then you will also see the output morph from the elastic registration step:
- el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2). This file takes up a lot of memory so, by default, is deleted. It can only be recreated if the elastic registration step (--step2) is re-run.
The command also produces two log files. These will be created in the output directory with a .log extension and contain the function calls that are initiated by the registration. The one that has a summary prefix is easier to read and does not contain all the function outputs. The longer version is to be consulted if looking for more details or explanations for possible errors.
Description
This program performs subject-to-subject or subject-to-atlas volume registration using the combined volumetric and surface based (CVS) registration algorithm (Postelnicu-Zollei-Fischl, TMI09).
The CVS registration stream consists of 3 steps: (1) surface-based registration, (2) elastic registration and (3) volumetric registration. By default, in the current implementation of the script, step (3) consists of two steps: (i) registration using aseg volumes and (ii) registration using intensity volumes. This combination of the non-linear volumetric registrations proved to be very robust and accurate, but the (i) step could be eliminated if quicker execution time is required by using the "--noaseg" flag. Make sure that SUBJECTS_DIR is properly set before calling this script.
***********
If you want to reconstruct the resulting warp (as it was deleted to save space after the processing) and apply it to a new volume, you would need to call two functions. If the warp combined*tm3d does not exist run both (1) and (2) , if it already exists, just run (2).
(1) createMorph --out fullCVSmorph.tm3d --template template.mgz \
- --subject movingvol.mgz --in gcam nlalign-afteraseg-norm.m3z \ morph el_reg_toTEMPLATE.tm3d
(2) applyMorph --template template.mgz --transform fullCVSmorph.tm3d \ vol movingvol.mgz outputvol.mgz linear
************
Note, the longest processing step in the CVS pipeline at the moment is the volumetric registration which might take about 15 hrs. The rest takes about 2 hours.
************
You will not be able to use fsaverage as a template as it does not have a corresponding surface and volumetric atlas. Instead, you can use one of the CVS atlases as a template (cvs or cvs_mni152).
Examples
Example 1
mri_cvs_register --mov Subj1ID
Register Subj1 to average CVS space.
Example 2
mri_cvs_register --mov Subj1ID --outdir myFav/Subj1ID/cvs
Register Subj1 to average CVS space with outputs written into "myFav" directory
Example 3
mri_cvs_register --mov Subj1ID --template Subj2ID
Register Subj1 to Subj2.
Example 4
mri_cvs_register --mov Subj1ID --template Subj2Id --templatedir $OTHER_SUBJECTS_DIR
Register Subj1 to Subj2 where the two subjects have different SUBJECTS_DIR's
Bugs
None
See Also
mris_register, mri_nl_align, mris_resample, createMorph, applyMorph, exportGcam
Links
References
G.M. Postelnicu*, L. Zöllei*, B. Fischl: "Combined Volumetric and Surface Registration", IEEE Transactions on Medical Imaging (TMI), Vol 28 (4), April 2009, p. 508-522
L. Zöllei, A. Stevens, K. Huber, S. Kakunoori, B. Fischl: "Improved Tractography Alignment Using Combined Volumetric and Surface Registration", NeuroImage 51 (2010), 206-213
Reporting Bugs
Report bugs to < analysis-bugs@nmr.mgh.harvard.edu >