adjunct_deob_around_origin

Overview

This is a simple program to wrap around the 3drefit functionality to
remove obliquity from a dataset whilst preserving its origin.

In many cases, this is very useful to run on oblique anatomicals
before processing.

ver  = 1.0
auth = PA Taylor, RC Reynolds (SSCC, NIMH, NIH)

Options

-input                 : (req) input volumetric dataset name
-prefix                : (req) output dataset name
-oblique_origin        : style of preserving origin, via 3drefit (def)
-oblique_recenter      : style of preserving origin, via 3drefit (def)
-oblique_recenter_raw  : style of preserving origin, via 3drefit (def)
-write_aff_mats        : write out affine matrix that would send output
                         dset here to same place
                         would send input (see Notes -> Affine Matrix)
-workdir               : working directory name (just name, no path;
                         will be subdirectory of the output location)
-overwrite             : when writing output, overwrite any preexisting
                         dataset (def: do not overwrite)
-no_clean              : when done, do not remove temporary working
                         directory (def: do remove working directory)
-echo                  : run very verbosely (with 'set echo' on)
-ver                   : display program version
-help                  : show help
-hview                 : show help in text editor

Notes

Comment on functionality

This program is mostly used to remove obliquity from an input
dataset's header.  This is because obliquity presents some hassles,
esp. when trying to view a dataset: the dataset FOV edges would not be
parallel to the graphical viewer edges. To apply the obliquity and
view data in the more global 'scanner coords' requires regridding of
the data, which is a blurring process.  To ignore the obliquity and
live in the more local 'FOV coords' means that xyz-based locations
might not be well-centered nor match with other datasets.

So, for some datasets (particularly anatomicals before processing
begins) it is convenient to deoblique the data.  That is, to remove
the extra obliquity considerations from the dset.  There are different
ways to do it, each of which has some benefit but also some annoying
properties. Two other basic programs in AFNI deoblique as follows:

+ '3drefit -deoblique ..'  _purges_ the obliquity information from the
  header.  This does not regrid/blur the data, but it does tend to
  throw off the coordinates, even drastically recentering the dset
  with regards to where its coordinate origin in the scanner should
  be.  That can be annoying for losing reasonable overlap with other
  dsets.

+ '3dWarp -deoblique ..' _applies_ the obliquity information to the
  dataset. This regrids/blurs the data, but it puts the data back into
  the coordinates of the scanner and will help it overlap more
  appropriately with other dsets acquired at the same time.

This program deobliques by removing obliquity from the header *but* in
a way that preserves the coordinate origin, (x, y, z) = (0, 0, 0).
This means the dataset is not regridded/blurred.  And it also means
that while the overlap with other datasets in the same scanner coords
might not be perfect, it has a good chance of being quite
decent---particularly as a starting point for real alignment by
3dAllineate, 3dQwarp, or another similar program.

That is why in general we consider this program's functionality
preferable to either 3drefit or 3dWarp.

Affine Matrix

If you add the '-write_aff_mats' option, the program will save a text
file that contains the affine matrix that would transform the output
dset to the same space as applying '3dWarp -deoblique ..' would send
the input dset (see the prior note, above).  The matrix will be
written to the same output directory as the main output, with the same
prefix (sans extension) as the  dset, and having the
postfix '_mat.aff12.1D'. This program also creates the inverse affine
matrix, having postfix '_mat_INV.aff12.1D'.

So, consider if you had run this program like:

    adjunct_deob_around_origin        \
        -input    DSET_IN             \
        -prefix   DSET_OUT.nii.gz     \
        -write_aff_mats

We will compare results with the result of _applying_ the obliquity,
too, from running this program:

    3dWarp                                \
        -deoblique                        \
        -prefix     DSET_WARP_DEOB.nii.gz \
        DSET_IN

The matrix DSET_OUT_mat.aff12.1D can be applied as follows, for a source
dset here called DSET_OUT.nii.gz:

    3dAllineate                               \
        -overwrite                            \
        -1Dmatrix_apply DSET_OUT_mat.aff12.1D \
        -prefix DSET_OUT_in_WARP_DEOB.nii.gz  \
        -source DSET_OUT.nii.gz               \
        -final  wsinc5


After this, we would expect DSET_IN_in_WARP_DEOB.nii.gz to have very
good alignment with a DSET_WARP_DEOB.nii.gz that was created with
'3dWarp -deoblique ..'.  Check overlap:

    afni DSET_WARP_DEOB.nii.gz DSET_IN_in_WARP_DEOB.nii.gz &

Sidenote: Above, we have included the '-final wsinc5' option
here, to provide sharp alignment for a floating point dataset. If
applying the DSET_OUT_mat.aff12.1D matrix to an integer-valued atlas
dataset, for example, one would not want that option, instead
preferring '-final NN'.

One could also apply the inverse matrix DSET_OUT_mat_INV.aff12.1D to the
DSET_WARP_DEOB.nii.gz dset, mapping it to the dset output by this
prog, which might be called DSET_OUT.nii.gz, like:

    3dAllineate                                    \
        -overwrite                                 \
        -1Dmatrix_apply  DSET_OUT_mat_INV.aff12.1D \
        -prefix DSET_WARP_DEOB_in_ADAO_DEOB.nii.gz \
        -source DSET_WARP_DEOB.nii.gz              \
        -final  wsinc5

The output dset DSET_WARP_DEOB_in_ADAO_DEOB.nii.gz should have good
alignment with DSET_OUT.nii.gz. Check overlap:

    afni DSET_OUT.nii.gz DSET_WARP_DEOB_in_ADAO_DEOB.nii.gz &

Examples

1) Basic usage:
     adjunct_deob_around_origin                       \
         -input   sub-001_T1w.nii.gz                  \
         -prefix  sub-001_T1w_DEOB.nii.gz

2) Different origin-preservation choice:
     adjunct_deob_around_origin                       \
         -oblique_recenter_raw                        \
         -input   sub-001_T1w.nii.gz                  \
         -prefix  sub-001_T1w_DEOB.nii.gz