| Deletions are marked like this. | Additions are marked like this. |
| Line 8: | Line 8: |
|
'''Index''' <<TableOfContents>> |
'''Index''' <<TableOfContents>> |
| Line 17: | Line 14: |
| mri_cvs_register--mov arg1 --template arg2 | mri_cvs_register --mov arg1 --template arg2 |
| Line 21: | Line 18: |
|
||--mov subjid|| subjid for subject to be moved / registered||Subject id of the subject (as found in SUBJECTS_DIR) whose scan is to be moved in registration with that of the template. || ||--template subjid||subjid for subject to be kept fixed (template)|| Subject id of the subject (as found in SUBJECTS_DIR) whose scan is to be used and the template / target for the registration.|| |
||--mov subjid ||subjid for subject to be moved / registered ||Subject id of the subject (as found in SUBJECTS_DIR) whose scan is to be moved in registration with that of the template. || ||--template subjid ||subjid for subject to be kept fixed (template) ||Subject id of the subject (as found in SUBJECTS_DIR) whose scan is to be used and the template / target for the registration. || |
| Line 25: | Line 23: |
|
|| --outdir directory || output directory where all the results are written || Output directory where the resulting morphs should be written. NOTE, the morphs require quite a lot of space so make sure that there is enough disk space available before your analysis. The default location for the output is: $SUBJECTS_DIR/$subjid/cvs || || --noaseg || do not use aseg volumes in the registration pipeline (default is 0) || || || --nocleanup || do not delete temporary files (default is 0) || || || --nolog || do not produce a log file (default is 0) || || || --step1 || only do step 1 (spherical registration) || || || --step2 || only do step 2 (elastic registration) || || || --step3 || only do step 3 (volumetric registration) || || || --version || print version and exit || || || --help || print (most up-to-date) help and exit || || |
||--outdir directory ||output directory where all the results are written ||Output directory where the resulting morphs should be written. NOTE, the morphs require quite a lot of space so make sure that there is enough disk space available before your analysis. The default location for the output is: $SUBJECTS_DIR/$subjid/cvs || ||--noaseg ||do not use aseg volumes in the registration pipeline (default is 0) || || ||--nocleanup ||do not delete temporary files (default is 0) || || ||--nolog ||do not produce a log file (default is 0) || || ||--step1 ||only do step 1 (spherical registration) || || ||--step2 ||only do step 2 (elastic registration) || || ||--step3 ||only do step 3 (volumetric registration) || || ||--version ||print version and exit || || ||--help ||print (most up-to-date) help and exit || || |
| Line 43: | Line 42: |
|
(a) Full CVS (with both (i) and (ii)) 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 nlalign-afteraseg-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 two m3z files) |
(a) Full CVS (with both (i) and (ii)) 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 nlalign-afteraseg-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 two m3z files) |
| Line 47: | Line 44: |
|
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 nlalign-aseg.mgz : the 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 above m3z file |
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 nlalign-aseg.mgz : the 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 above m3z file |
| Line 50: | Line 46: |
|
el_reg_toTEMPLATE_aseg.mgz : the elastic morph applied to aseg.mgz el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) el_reg_toTEMPLATE.mgz : the elastic morph applied to norm.mgz |
el_reg_toTEMPLATE_aseg.mgz : the elastic morph applied to aseg.mgz el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) el_reg_toTEMPLATE.mgz : the elastic morph applied to norm.mgz |
| Line 56: | Line 50: |
|
nlalign-norm.m3z : the morph resulting from step(3) (intensity-based non-linear registration); it is NOT combined with the elastic registration morph 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) |
nlalign-norm.m3z : the morph resulting from step(3) (intensity-based non-linear registration); it is NOT combined with the elastic registration morph 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) |
| Line 59: | Line 52: |
|
el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) el_reg_toTEMPLATE.mgz : the elastic morph applied to norm.mgz |
el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) el_reg_toTEMPLATE.mgz : the elastic morph applied to norm.mgz |
| Line 64: | Line 56: |
|
(a) el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) combined_elreg_aseg.tm3d : the morph that combines correspondences recovered in steps (1), (2) and (3) (i) combined_elreg_afteraseg-norm.tm3d : the morph that combines correspondences recovered in steps (1), (2), (3) (i) and (3) (ii) (b) el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) combined_elreg_norm.tm3d : the morph that combines correspondences recovered in steps (1), (2) and (3) (ii) |
(a) el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) combined_elreg_aseg.tm3d : the morph that combines correspondences recovered in steps (1), (2) and (3) (i) combined_elreg_afteraseg-norm.tm3d : the morph that combines correspondences recovered in steps (1), (2), (3) (i) and (3) (ii) (b) el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) combined_elreg_norm.tm3d : the morph that combines correspondences recovered in steps (1), (2) and (3) (ii) |
| Line 74: | Line 60: |
|
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) an d(2) , if it already exists, just run (2). |
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) an d(2) , if it already exists, just run (2). |
| Line 77: | Line 62: |
|
(1) createMorph --out fullCVSmorph.tm3d --template template.mgz \ --subject movingvol.mgz --in gcam nlalign-afteraseg-norm.m3z \ morph el_reg_toTEMPLATE.tm3d |
(1) createMorph --out fullCVSmorph.tm3d --template template.mgz \ |
| Line 82: | Line 64: |
|
(2) applyMorph --template template.mgz --transform fullCVSmorph.tm3d \ vol movingvol.mgz outputvol.mgz linear |
. --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 |
| Line 88: | Line 70: |
|
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. |
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. |
| Line 93: | Line 74: |
|
You will not be able to use fsaverage as a template as it does not have a corresponding surface and volumetric atlas. We are in the process of building and releasing a CVS atlas, but it is not ready yet, so for now the best thing to do would be to register all your subjects to a randomly selected one. |
You will not be able to use fsaverage as a template as it does not have a corresponding surface and volumetric atlas. We are in the process of building and releasing a CVS atlas, but it is not ready yet, so for now the best thing to do would be to register all your subjects to a randomly selected one. |
| Line 114: | Line 91: |
| Report bugs to <analysis-bugs@nmr.mgh.harvard.edu> | Report bugs to < analysis-bugs@nmr.mgh.harvard.edu > |
Index
Contents
Name
mri_cvs_register - registers MRI scans of two subjects (or a subject and the CVS atlas) using the combined volume and surface-based registration method, CVS. Make sure that SUBJECTS_DIR is properly set before calling this script!
Synopsis
mri_cvs_register --mov arg1 --template arg2
Arguments
Required Flagged Arguments
--mov subjid |
subjid for subject to be moved / registered |
Subject id of the subject (as found in SUBJECTS_DIR) whose scan is to be moved in registration with that of the template. |
--template subjid |
subjid for subject to be kept fixed (template) |
Subject id of the subject (as found in SUBJECTS_DIR) whose scan is to be used and the template / target for the registration. |
Optional Flagged Arguments
--outdir directory |
output directory where all the results are written |
Output directory where the resulting morphs should be written. NOTE, the morphs require quite a lot of space so make sure that there is enough disk space available before your analysis. The default location for the output is: $SUBJECTS_DIR/$subjid/cvs |
--noaseg |
do not use aseg volumes in the registration pipeline (default is 0) |
|
--nocleanup |
do not delete temporary files (default is 0) |
|
--nolog |
do not produce a log file (default is 0) |
|
--step1 |
only do step 1 (spherical registration) |
|
--step2 |
only do step 2 (elastic registration) |
|
--step3 |
only do step 3 (volumetric registration) |
|
--version |
print version and exit |
|
--help |
print (most up-to-date) help and exit |
|
Outputs
See below.
Description
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, butthe (i) step could be eliminated if quicker execution time is required by using the "--noaseg" flag.
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)) 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 nlalign-afteraseg-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 two m3z files)
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 nlalign-aseg.mgz : the 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 above m3z file
el_reg_toTEMPLATE_aseg.mgz : the elastic morph applied to aseg.mgz el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) el_reg_toTEMPLATE.mgz : the elastic morph applied to norm.mgz
(b) shorter version of CVS (using only (ii) in step (3) of the algorithm):
nlalign-norm.m3z : the morph resulting from step(3) (intensity-based non-linear registration); it is NOT combined with the elastic registration morph 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.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) el_reg_toTEMPLATE.mgz : the elastic morph applied to norm.mgz
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) el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) combined_elreg_aseg.tm3d : the morph that combines correspondences recovered in steps (1), (2) and (3) (i) combined_elreg_afteraseg-norm.tm3d : the morph that combines correspondences recovered in steps (1), (2), (3) (i) and (3) (ii) (b) el_reg_toTEMPLATE.tm3d : the elastic morph that combines correspondences recovered in steps (1) and (2) combined_elreg_norm.tm3d : the morph that combines correspondences recovered in steps (1), (2) and (3) (ii)
***********
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) an d(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. We are in the process of building and releasing a CVS atlas, but it is not ready yet, so for now the best thing to do would be to register all your subjects to a randomly selected one.
Bugs
None
See Also
mris_register, mri_nl_align, mris_resample, mri_cvs_check, mri_cvs_data_copy
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 >