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.
--outdir directoryName of the output directory where all the registration results are written. The default is SUBJECTS_DIR/mov/cvs. 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).
--mniUse the CVS atlas in MNI152 space as a target for 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.

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