Index

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

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

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)

(b)

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:

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 \

(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

FreeSurfer

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 >

Author/s

LillaZollei

mri_cvs_register (last edited 2018-02-05 12:34:44 by MorganFogarty)