NAME

mri_cvs_register

SYNOPSIS

Combined Volume and Surface Registration

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 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.

POSITIONAL ARGUMENTS

None

REQUIRED-FLAGGED ARGUMENTS

ArgumentExplanation
--mov subjidFreeSurfer subject name as found in $SUBJECTS_DIR. This identifies the subject that is to be moved / registered to the target.

OPTIONAL-FLAGGED ARGUMENTS

ArgumentExplanation
--template subjidFreeSurfer 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 directoryThis 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.
--mniUse the CVS atlas in MNI152 space as a target for registration (as opposed to the default CVS template).
--outdir directoryName 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 fnameName 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!

Partial run of the registration

ArgumentExplanation
--step1Only do step 1 (spherical registration).
--step2Only do step 2 (elastic registration).
--step3Only do step 3 (volumetric registration).
--noasegDo 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.
--nointensityDo 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.
--hemiRun the CVS registration only one of the hemispheres. For example, in case of single hemisphere ex-vivo cases.
--useonlyhemiinvivomovUse 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.)

Cleanup Arguments

ArgumentExplanation
--nocleanupDo not delete temporary files (default is 0). If this option is set, make sure you have ~2G space in the output directory.
--keepelregDo not delete elastic registration (default is 0) outcome. If this option is set, make sure ~1G of space is available in the output directory.
--keepallm3zDo not delete m3z morph files that are computed during the CVS process (default is 0).
--cleanallOverwrite / recompute all CVS-related morphs that might have been computed prior to the current CVS run (default is 0).
--cleansurfregOverwrite / recompute CVS-related surface registration morphs that might have been computed prior to the current CVS run (default is 0).
--cleanelregOverwrite /recompute the CVS-related elastic registration morph that might have been computed prior to the current CVS run (default is 0).
--cleanvolregOverwrite / recompute CVS-related volumetric morphs that might have been computed prior to the current CVS run (default is 0).

Others

ArgumentExplanation
--m3dUse m3d instead of m3z in order to represent the registration morphs (and to avoid potential gzip errors).
--openmp NAssign the number of nodes for openmp runs to be N. The default is = 1. Note, with N = 8, you can get a threefold speedup.
--nologDo not produce a log file (default is 0).
--versionPrint version and exit.
--help Print help and exit.

OUTPUTS

******************************************************************
(a) Full CVS (with both (i) and (ii))

OutputExplanation
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.mgzthe elastic morph applied to aseg.mgz
el_reg_toTEMPLATE.mgzthe elastic morph applied to norm.mgz
! current version does not keep this file any more ! nlalign-afteraseg-norm.m3zthe 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.m3zthe morph that combines correspondences recovered in steps (1), (2) and (3) (i)
! current version does not keep this file any more ! nlalign-aseg.m3zthe morph resulting from (i) of step (3) (aseg-based non-linear registration); it is NOT combined with the elastic registration morph

(b) Shorter version of CVS (using only (ii) in step (3) of the algorithm)

OutputExplanation
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.mgzthe elastic morph applied to norm.mgz
! current version does not keep this file any more ! nlalign-norm.m3zthe morph resulting from step(3) (intensity-based non-linear registration); it is NOT combined with the elastic registration morph

When the "--nocleanup" option is set: three more files will exist, called combined*tm3d and el_reg*tm3d. These files take up a lot of memory so by default are deleted. These files are
(a)

OutputExplanation
combined_toTEMPLATE_elreg_aseg.tm3dthe morph that combines correspondences recovered in steps (1), (2) and (3) (i)
combined_toTEMPLATE_elreg_afteraseg-norm.tm3dthe morph that combines correspondences recovered in steps (1), (2), (3) (i) and (3) (ii)
el_reg_toTEMPLATE.tm3dthe 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)

OutputExplanation
combined_toTEMPLATE_elreg_norm.tm3dthe morph that combines correspondences recovered in steps (1), (2) and (3) (ii)
el_reg_toTEMPLATE.tm3dthe 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:

OutputExplanation
el_reg_toTEMPLATE.tm3dthe 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.

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.

EXAMPLE 1

Register Subj1 to average CVS space: mri_cvs_register --mov Subj1ID

EXAMPLE 2

Register Subj1 to average CVS space with outputs written into \"myFav\" directory: mri_cvs_register --mov Subj1ID --outdir myFav/Subj1ID/cvs

EXAMPLE 3

Register Subj1 to Subj2: mri_cvs_register --mov Subj1ID --template Subj2ID

EXAMPLE 4

Register Subj1 to Subj2 where the two subjects have different SUBJECTS_DIR's: mri_cvs_register --mov Subj1ID --template Subj2ID --templatedir $OTHER_SUBJECTS_DIR

EXAMPLE 5

If running mri_cvs_register on lanchpad, use \"-l nodes=1:ppn=5,vmem=35gb\"

EXAMPLE 6

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

BUGS

None

REPORTING

Report bugs to <freesurfer@nmr.mgh.harvard.edu>

REFERENCES


Combined Volumetric and Surface Registration,
G.Postelnicu, L.Zollei, B. Fischl.
IEEE Transactions on Medical Imaging, Vol 28, No. 4, April 2009

SEE-ALSO

mris_register, mri_nl_align, mris_resample, createMorph, applyMorph, exportGcam