The purpose of this function is to help convert one or more sets
of DWIs in DICOM format into 'nicer' volume+grad format. If
multiple directories of DICOMS exist for a given AP or PA set,
then those can be combined into a single volume+grad file with a
single call of this function. Data sets are also converted to have
a single orientation. For data acquired with dual phase encoding
(such as AP/PA, or what is often known as 'blip up'/'blip down'),
separate calls of this function need to be made for each encode
set; however, one can pass origin information to have the same
origin across all volumes during recentering.

This program can be used to: convert dicoms to NIFTI (with bvals
and bvecs); reorient volumetric data; and glue together multiple
sessions/directories of data (may the user choose what is
appropriate to combine!).  More functionality could be demanded by
demanding users.

REQUIRES: AFNI (which should now contain dcm2niix_afni, the
version of dcm2niix [by C. Rorden] distributed in AFNI).

Ver. 3.4 (PA Taylor, Aug 15, 2018)


  fat_proc_convert_dcm_dwis  \
    -indir   DIR                             \
    {-innii NNN -inbvec CCC -inbval LLL}     \
    -prefix PPP                              \
    {-workdir   WWW}                         \
    {-orient    ORIENT}                      \
    {-origin_xyz X0 Y0 Z0}                   \
    {-flip_x | -flip_y | -flip_z | -no_flip} \
    {-reorig_reorient_off}                   \
    {-no_clean}                              \
    {-qc_prefix    QCPREF}                   \
    {-no_cmd_out}                            \
    {-no_qc_view}                            \
    {-do_movie AGIF|MPEG}

  -indir  DIR     :directory name(s) of (only) DICOM files of the
                   DWI data,designated as having 'AP' phase
                   encoding.  DIR can actually contain a wildcard
                   expression for several directories, if, for
                   example, multiple DWI sets should be glued
                   together into one set.  NOTE: if specifying more
                   than one directory, put double quotes around your
                   entry, like: "file*".
     *or* the user can input one or more sets of nifti+bvec+bval files;
          the program will concatenate each set of files in the order
          input using the following argument flags, so the user
          must be careful that the ordering is correct!  These files
          go through the same post-dicom-conversion processing (setting
          the orientation, origin, flipping, etc.) as those of
          the "-indir .." files -->
  -innii NNN      :one or more nifti files of DWIs; the '-inbvec .."
                   and "-inbal .." arguments, below, must also be used
                   to input the corresponding text files for each
                   NIFTI NNN.
  -inbvec CCC     :one or more row-wise, gradient (unit-magnitude)
                   files, such as would be produced by
                   dcm2niix(_afni).  If there are "N" NIFTI files
                   input, there must be "N" CCC files in the same order.
  -inbval LLL     :one or more bvalue files, such as would be
                   produced by dcm2niix(_afni).  If there are "N"
                   NIFTI files input, there must be "N" LLL files in
                   the same order.

  -prefix   PPP   :set prefix (and path) for output data; will be prefix
                   for the *.nii.gz, *.bvec and *.bval files. Required.

  -orient  ORIENT :optional chance to reset orientation of the volume
                   files (default is currently 'RAI').

  -origin_xyz X0 Y0 Z0
                  :by default, dset will be given an origin value
                   such that the center of mass of the dset is located
                   at (x, y, z) = (0, 0, 0), for niceness's sake.
                   However, an explicit origin can also be given with
                   this option (NB: this depends on the orientation of
                   the data, which can various be: explicitly chosen or
                   set to a default value, or not changed at all).
                   Three numbers are required to be input (i.e., the
                   xyz origin values), and this might be useful if, for
                   example, you've already processed one set of a dual-
                   phase encoded acquisition, so that you can get the
                   origin from the first and ensure that the second
                   has the same values afterwards, making it easier
                   to overlay the data, should you wish.
                  :switch to turn of the nicety of putting (0, 0, 0)
                   at brain's center of mass (-> 'reorigin' calc) and to
                   not reorient data (-> 'reorient' calc).  Could lead
                   to weirdness later on down the road, depending on the
                   data and headers (ergo, not recommended.)

  -flip_x  |
  -flip_y  |
  -flip_z  |
  -no_flip        :use any one of these for the ability to flip grads
                   while processing with 1dDW_Grad_o_Mat++. (Default is
                   to not flip; it is not necessary to provide that
                   "-no_flip" option for no flipping to occur.)

 -no_clean        :switch to not remove working directory of intermediate,
                   temporary files (default is to delete it).

-qc_prefix QCPREF :can set the prefix of the QC image files separately
                   (default is '').
 -no_qc_view      :can turn off generating QC image files (why?)
 -no_cmd_out      :don't save the command line call of this program
                   and the location where it was run (otherwise, it is
                   saved by default in the ODIR/).

  -do_movie AGIF | MPEG
                  :one can use this option with either of the given
                   arguments to output a movie of the newly created
                   dset.  Only those arguments can be used at


For a given phase encoding set, the output files are:

    PREFIX.nii.gz     # a NIFTI file with N volumes;
    PREFIX.rvec       # a row-wise (3xN) bvec file of
                        the (unit-magnitude) gradient orientations;
    PREFIX.bval       # a row-wise (1xN) bval file of the
                        gradient magnitudes;
    PREFIX_matA.dat   # a column-wise (Nx6) AFNI-style matrix file of
                        the (scaled) b-matrix values;
    PREFIX_matT.dat   # a column-wise (Nx6) TORTOISE-style matrix file
                        of the (scaled) b-matrix values;
    PREFIX_cvec.dat   # a column-wise (Nx3) bvec file of
                        the (b-magn scaled) gradient orientations;

with the first three meant to mimic the trio of files output by
dcm2niix_afni, and the rest there for convenience.


fat_proc_convert_dcm_dwis  \
    -indir  "DWI_DICOMS"                 \
    -prefix  DWI_UNFILT/dwi

fat_proc_convert_dcm_dwis  \
    -indir    dwi_ap                 \
    -prefix   DWI_UNFILT/dwi
    -do_movie AGIF

fat_proc_convert_dcm_dwis  \
    -innii    study/subj-001/acq_piece_0*.nii.gz     \
    -inbvec   study/subj-001/acq_piece_0*.bvec       \
    -inbval   study/subj-001/acq_piece_0*.bval       \
    -prefix   study/subj-001/dwi_all
    -do_movie AGIF