mri_cvs_register
Combined Volume and Surface Registration
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 regsitration. 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.
Argument | Explanation |
---|---|
--mov subjid | FreeSurfer subject name as found in $SUBJECTS_DIR. This identifies the subject that is to be moved / registered to the target. |
Argument | Explanation |
---|---|
--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. |
--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 implicitely 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. |
--asegfname fname | Name of the segmentation volume that should be used in order to guide the volumetric registration step. The default value is aseg. Note that both the template and the moving subject needs to have this file if you want to use this option. Also, do not use the file extension of the volume that you are including with this flag! |
Argument | Explanation |
---|---|
--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 only one of the hemispheres. For example, in case of single hemisphere ex-vivo cases. |
--useonlyhemiinvivomov | Use this possibly with the --hemi option. If the invivo scan is th moving subject, this would mask out the appropriate hemisphere in order to avoid strange artifacts resulting from moving a full brain to a single hemisphere. (The other way around it should not be a problem.) |
Argument | Explanation |
---|---|
--nocleanup | Do not delete temporary files (default is 0). If this option is set, make sure you have ~2G 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). |
Argument | Explanation |
---|---|
--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 speedup. |
--nolog | Do not produce a log file (default is 0). |
--version | Print version and exit. |
--help | Print help and exit. |
Output | Explanation |
---|---|
final_CVSmorph_toTEMPLATE.m3z (formerly: combined_toTEMPLATE_elreg_afteraseg-norm.m3z) | the final morph that combines correspondences recovered in steps (1), (2), (3) (i) and (3) (ii) |
final_CVSmorphed_toTEMPLATE_norm.mgz (formerly nlalign-afteraseg-norm.mgz) | the CVS morphed norm.mgz file; it is the final result of CVS and contains contributions from ALL registration steps (combination of the elatic morph and the two m3z files |
final_CVSmorphed_toTEMPLATE_aseg.mgz (formerly 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 elatic morph and the two m3z files |
step1_CVSmorphed_toTEMPLATE_aseg.mgz (formerly: 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 elatic morph and the aseg-based nonlinear registration |
step1_CVSmorphed_toTEMPLATE_norm.mgz (formerly: 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 elatic 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 |
! current version does not keep this file any more ! 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 |
! current version does not keep this file any more ! combined_toTEMPLATE_elreg_aseg.m3z | the morph that combines correspondences recovered in steps (1), (2) and (3) (i) |
! current version does not keep this file any more ! 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 |
Output | Explanation |
---|---|
final_CVSmorph_toTEMPLATE.m3z (formerly: combined_toTEMPLATE_elreg_norm.m3z) | The morph that combines correspondences recovered in steps (1), (2) and (3) (ii) |
final_CVSmorphed_toTEMPLATE_norm.mgz (formerly: nlalign-norm.mgz) | the morphed norm.mgz file; it is the final result of CVS and contains contributions from ALL registration steps (combination of the elatic morph and the above m3z file) |
el_reg_toTEMPLATE.mgz | the elastic morph applied to norm.mgz |
! current version does not keep this file any more ! nlalign-norm.m3z | the morph resulting from step(3) (intensity-based non-linear registration); it is NOT combined with the elastic registration morph |
Output | Explanation |
---|---|
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. |
Output | Explanation |
---|---|
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. |
Output | Explanation |
---|---|
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. |
Register Subj1 to average CVS space: mri_cvs_register --mov Subj1ID
Register Subj1 to average CVS space with outputs written into \"myFav\" directory: mri_cvs_register --mov Subj1ID --outdir myFav/Subj1ID/cvs
Register Subj1 to Subj2: mri_cvs_register --mov Subj1ID --template Subj2ID
Register Subj1 to Subj2 where the two subjects have different SUBJECTS_DIR's: mri_cvs_register --mov Subj1ID --template Subj2ID --templatedir $OTHER_SUBJECTS_DIR
If running mri_cvs_register on lanchpad, use \"-l nodes=1:ppn=5,vmem=35gb\"
Some timing estimates from launchpad with the above node settings:
cvs_avg35 (default) template; launchpad: t = 33.955hrs
--openmp = 8; cvs_avg35 (default) template; launchpad: t = 11.28hrs
cvs_avg35_inMNI152 template; launchpad: t = 21.69hrs
--openmp = 8; cvs_avg35_inMNI152template; launchpad: t = 7.66hrs
subject template; launchpad: t = 45.48hrs
--openmp = 8; subject template; launchpad: t = 15.07hrs
None
Report bugs to <freesurfer@nmr.mgh.harvard.edu>
Combined Volumetric and Surface Registration,
G.Postelnicu, L.Zollei, B. Fischl.
IEEE Transactions on Medical Imaging, Vol 28, No. 4, April 2009
mris_register, mri_nl_align, mris_resample, createMorph, applyMorph, exportGcam