AFNI program: @SUMA_AlignToExperiment

Usage: 
@SUMA_AlignToExperiment <-exp_anat Experiment_Anatomy> <-surf_anat Surface_Anatomy> 
              [dxyz] [-wd] [-prefix PREFIX] [-EA_clip_below CLP]
              [-align_centers] [-ok_change_view] [-strip_skull WHICH]

Creates a version of Surface Anatomy that is registered to Experiment Anatomy.

Mandatory parameters:
<-exp_anat Experiment_Anatomy>: Name of high resolution anatomical data set in register 
        with experimental data.
<-surf_anat Surface_Anatomy> Path and Name of high resolution antomical data set used to 
        create the surface.

  NOTE: In the old usage, there were no -exp_anat and -surf_anat flags and the two 
  volumes had to appear first on the command line and in the proper order.

Optional parameters:
   [-dxyz DXYZ]: This optional parameter indicates that the anatomical 
        volumes must be downsampled to dxyz mm voxel resolution before 
        registration. That is only necessary if 3dvolreg runs out of memory.
        You MUST have 3dvolreg that comes with afni distributions newer than 
        version 2.45l. It contains an option for reducing memory usage and 
        thus allow the registration of large data sets.
   [-out_dxyz DXYZ]: Output the final aligned volume at a cubic voxelsize
                     of DXYZmm. The default is based on the grid of ExpVol.
   [-wd]: Use 3dWarpDrive's general affine transform (12 param) instead of 
        3dvolreg's 6 parameters.
        If the anatomical coverage differs markedly between 'Experiment 
        Anatomy' and 'Surface Anatomy', you might need to use -EA_clip_below 
        option or you could end up with a very distorted brain.
        The default now is to use -coarserot option with 3dWarpDrive, this
        should make the program more robust. If you want to try running without it
        the add -ncr with -wd
        I would be interested in examining cases where -wd option failed to 
        produce a good alignment.
   [-al]: Use 3dAllineate to do the 12 parameter alignment. Cost function
          is lpa
   [-al_opt 'Options for 3dAllineate']: Specify set of options between quotes
                                           to pass to 3dAllineate.   
   [-ok_change_view]: Be quiet when view of registered volume is changed
                      to match that of the Experiment_Anatomy, even when
                      rigid body registration is used.
   [-strip_skull WHICH]: Use 3dSkullStrip to remove non-brain tissue and 
                         potentially improve the alignment. WHICH can be
                         one of 'exp_anat' or 'both'. In the first case,
                         the skull is removed from Experiment_Anatomy
                         dataset. With 'both' the skull is removed from
                         Experiment_Anatomy and Surface_Anatomy.
   [-skull_strip_opt 'Options For 3dSkullStrip']: Pass the options between
                         quotes to 3dSkullStrip.
   [-align_centers]: Adds an additional transformation to align the volume
                     centers. This is a good option to use when volumes
                     are severely out of alignment.
   [-EA_clip_below CLP]: Set slices below CLPmm in 'Experiment Anatomy' to zero.
        Use this if the coverage of 'Experiment Anatomy' dataset
        extends far below the data in 'Surface Anatomy' dataset.
        To get the value of CLP, use AFNI to locate the slice
        below which you want to clip and set CLP to the z coordinate
        from AFNI's top left corner. Coordinate must be in RAI, DICOM.
   [-prefix PREFIX]: Use PREFIX for the output volume. Default is the prefix 
   [-surf_anat_followers Fdset1 Fdset2 ...]: Apply the same alignment
                transform to datasets Fdset1, Fdset2, etc.
                This must be the last option on the command line.
                All parameters following it are considered datasets.
                You can transform other follower dsets manually by
                executing: 
         3dAllineate -master Experiment_Anatomy \
                     -1Dmatrix_apply Surface_Anatomy_Alnd_Exp.A2E.1D \
                     -input Fdset   \
                     -prefix Fdset_Alnd_Exp+orig \
                     -final NN
   [-followers_interp KERNEL]: Set the interpolation mode for the 
                               follower datasets. Default is NN, which 
                               is appropriate for ROI datasets.
                               Allowed KERNEL values are:
                               NN, linear, cubic, or quintic
        of the 'Surface Anatomy' suffixed by _Alnd_Exp.
   [-keep_tmp]: Keep temporary files for debugging. Note that you should
                delete temporary files before rerunning the script.


NOTE: You must run the script from the directory where Experiment Anatomy resides.

Example 1: For datasets with no relative distortion and comparable coverage.
           Using 6 param. rigid body transform.
@SUMA_AlignToExperiment -exp_anat DemoSubj_spgrsa+orig. \
                        -surf_anat ../FreeSurfer/SUMA/DemoSubj_SurfVol+orig.

Example 2: For datasets with some distortion and different coverage.
           Using 12 param. transform and clipping of areas below cerebellum:
@SUMA_AlignToExperiment -exp_anat ABanat+orig. -surf_anat DemoSubj_SurfVol+orig. \
                       -wd -prefix DemoSubj_SurfVol_WD_Alnd_Exp \
                       -EA_clip_below -30

Example 3: For two monkey T1 volumes with very different resolutions and severe
           shading artifacts.
@SUMA_AlignToExperiment    -surf_anat MOanat+orig. -al \
                           -exp_anat MoExpanat+orig. \
                           -strip_skull both -skull_strip_opt -monkey \
                           -align_centers \
                           -out_dxyz 0.3

Ziad Saad (saadz@mail.nih.gov)
SSCC/NIMH/ National Institutes of Health, Bethesda Maryland