Usage: to3d [options] image_files ...
       Creates 3D datasets for use with AFNI from 2D image files

****** PLEASE NOTE *******************************************************
****** If you are converting DICOM files to AFNI or NIfTI datasets, ******
****** you will likely be happier using the Dimon program, which    ******
****** can properly organize the Dicom files for you (knock wood).  ******
****** Example:                                                     ******
******   Dimon -infile_prefix im. -dicom_org -gert_create_dataset   ******
****** See the output of                                            ******
******   Dimon -help                                                ******
****** for more examples and the complete instructions for use.     ******

The available options are
  -help   show this message
  -'type' declare images to contain data of a given type
          where 'type' is chosen from the following options:
         spgr == Spoiled GRASS
          fse == Fast Spin Echo
         epan == Echo Planar
         anat == MRI Anatomy
           ct == CT Scan
         spct == SPECT Anatomy
          pet == PET Anatomy
          mra == MR Angiography
         bmap == B-field Map
         diff == Diffusion Map
         omri == Other MRI
         abuc == Anat Bucket
          fim == Intensity
         fith == Inten+Thr
         fico == Inten+Cor
         fitt == Inten+Ttest
         fift == Inten+Ftest
         fizt == Inten+Ztest
         fict == Inten+ChiSq
         fibt == Inten+Beta
         fibn == Inten+Binom
         figt == Inten+Gamma
         fipt == Inten+Poisson
         fbuc == Func-Bucket
                 [for paired (+) types above, images are fim first,]
                 [then followed by the threshold (etc.) image files]

  -statpar value value ... value [* NEW IN 1996 *]
     This option is used to supply the auxiliary statistical parameters
     needed for certain dataset types (e.g., 'fico' and 'fitt').  For
     example, a correlation coefficient computed using program 'fim2'
     from 64 images, with 1 ideal, and with 2 orts could be specified with
       -statpar 64 1 2

  -prefix  name      will write 3D dataset using prefix 'name'
  -session name      will write 3D dataset into session directory 'name'
  -geomparent fname  will read geometry data from dataset file 'fname'
                       N.B.: geometry data does NOT include time-dependence
  -anatparent fname  will take anatomy parent from dataset file 'fname'

  -nosave  will suppress autosave of 3D dataset, which normally occurs
           when the command line options supply all needed data correctly

  -nowritebrik  will suppress saving of the BRIK file. May be useful for
           realtime saving when symbolic links are used instead

  -view type [* NEW IN 1996 *]
    Will set the dataset's viewing coordinates to 'type', which
    must be one of these strings:  orig acpc tlrc

  -time:zt nz nt TR tpattern  OR  -time:tz nt nz TR tpattern

    These options are used to specify a time dependent dataset.
    '-time:zt' is used when the slices are input in the order
               z-axis first, then t-axis.
    '-time:tz' is used when the slices are input in the order
               t-axis first, then z-axis.

    nz  =  number of points in the z-direction (minimum 1)
    nt  =  number of points in the t-direction
            (thus exactly nt * nz slices must be read in)
    TR  =  repetition interval between acquisitions of the
            same slice, in milliseconds (or other units, as given below)

    tpattern = Code word that identifies how the slices (z-direction)
               were gathered in time.  The values that can be used:

       alt+z = altplus    = alternating in the plus direction
       alt+z2             = alternating, starting at slice #1
       alt-z = altminus   = alternating in the minus direction
       alt-z2             = alternating, starting at slice #nz-2
       seq+z = seqplus    = sequential in the plus direction
       seq-z = seqminus   = sequential in the minus direction
       zero  = simult     = simultaneous acquisition
       FROM_IMAGE         = (try to) read offsets from input images
       @filename          = read temporal offsets from 'filename'

    For example if nz = 5 and TR = 1000, then the inter-slice
    time is taken to be dt = TR/nz = 200.  In this case, the
    slices are offset in time by the following amounts:

                    S L I C E   N U M B E R
      tpattern        0    1    2    3    4  Comment
      ----------   ---- ---- ---- ---- ----  -------------------------------
      altplus         0  600  200  800  400  Alternating in the +z direction
      alt+z2        400    0  600  200  800  Alternating, but starting at #1
      altminus      400  800  200  600    0  Alternating in the -z direction
      alt-z2        800  200  600    0  400  Alternating, starting at #nz-2
      seqplus         0  200  400  600  800  Sequential  in the +z direction
      seqminus      800  600  400  200    0  Sequential  in the -z direction
      simult          0    0    0    0    0  All slices acquired at once

    If @filename is used for tpattern, then nz ASCII-formatted numbers are
    read from the file.  These are used to indicate the time offsets (in ms)
    for each slice. For example, if 'filename' contains
       0 600 200 800 400
    then this is equivalent to 'altplus' in the above example.

      * Time-dependent functional datasets are not yet supported by
          to3d or any other AFNI package software.  For many users,
          the proper dataset type for these datasets is '-epan'.
      * Time-dependent datasets with more than one value per time point
          (e.g., 'fith', 'fico', 'fitt') are also not allowed by to3d.
      * If you use 'abut' to fill in gaps in the data and/or to
          subdivide the data slices, you will have to use the @filename
          form for tpattern, unless 'simult' or 'zero' is acceptable.
      * At this time, the value of 'tpattern' is not actually used in
          any AFNI program.  The values are stored in the dataset
          .HEAD files, and will be used in the future.
      * The values set on the command line can't be altered interactively.
      * The units of TR can be specified by the command line options below:
            -t=ms or -t=msec  -->  milliseconds (the default)
            -t=s  or -t=sec   -->  seconds
            -t=Hz or -t=Hertz -->  Hertz (for chemical shift images?)
          Alternatively, the units symbol ('ms', 'msec', 's', 'sec',
            'Hz', or 'Hertz') may be attached to TR in the '-time:' option,
            as in '-time:zt 16 64 4.0sec alt+z'
 ****** 15 Aug 2005 ******
      * Millisecond time units are no longer stored in AFNI dataset
          header files.  For backwards compatibility, the default unit
          of TR (i.e., without a suffix 's') is still milliseconds, but
          this value will be converted to seconds when the dataset is
          written to disk.  Any old AFNI datasets that have millisecond
          units for TR will be read in to all AFNI programs with the TR
          converted to seconds.

  -Torg ttt = set time origin of dataset to 'ttt' [default=0.0]

   -xFOV   [dimen1][direc1]-[dimen2][direc2]
     or       or
   -xSLAB  [dimen1][direc1]-[direc2]

   (Similar -yFOV, -ySLAB, -zFOV and -zSLAB option are also present.)

 These options specify the size and orientation of the x-axis extent
 of the dataset.  [dimen#] means a dimension (in mm); [direc] is
 an anatomical direction code, chosen from
      A (Anterior)    P (Posterior)    L (Left)
      I (Inferior)    S (Superior)     R (Right)
 Thus, 20A-30P means that the x-axis of the input images runs from
 20 mm Anterior to 30 mm Posterior.  For convenience, 20A-20P can be
 abbreviated as 20A-P.

 -xFOV  is used to mean that the distances are from edge-to-edge of
          the outermost voxels in the x-direction.
 -xSLAB is used to mean that the distances are from center-to-center
          of the outermost voxels in the x-direction.

 Under most circumstance, -xFOV , -yFOV , and -zSLAB would be the
 correct combination of geometry specifiers to use.  For example,
 a common type of run at MCW would be entered as
    -xFOV 120L-R -yFOV 120A-P -zSLAB 60S-50I

 **NOTE WELL: -xFOV 240L-R does not mean a Field-of-View that is 240 mm
               wide!  It means one that stretches from 240R to 240L, and
               so is 480 mm wide.
              The 'FOV' indicates that this direction was acquired with
               with Fourier encoding, and so the distances are naturally
               specified from the edge of the volume.
              The 'SLAB' indicates that this direction was acquired with
               slice encoding (by the RF excitation), and so distances
               are naturally specified by the center of the slices.
              For non-MRI data (e.g., CT), I'm not sure what the correct
               input format to use here would be -- be careful out there!

 -zorigin distz  Puts the center of the 1st slice off at the
                 given distance ('distz' in mm).  This distance
                 is in the direction given by the corresponding
                 letter in the -orient code.  For example,
                   -orient RAI -zorigin 30
                 would set the center of the first slice at
                 30 mm Inferior.
    N.B.: This option has no effect if the FOV or SLAB options
          described above are used.

  Image files may be single images of unsigned bytes or signed shorts
  (64x64, 128x128, 256x256, 512x512, or 1024x1024) or may be grouped
  images (that is, 3- or 4-dimensional blocks of data).
  In the grouped case, the string for the command line file spec is like

    3D:hglobal:himage:nx:ny:nz:fname   [16 bit input]
    3Ds:hglobal:himage:nx:ny:nz:fname  [16 bit input, swapped bytes]
                   (consider also -ushort2float for unsigned shorts)
    3Db:hglobal:himage:nx:ny:nz:fname  [ 8 bit input]
    3Di:hglobal:himage:nx:ny:nz:fname  [32 bit input]
    3Df:hglobal:himage:nx:ny:nz:fname  [floating point input]
    3Dc:hglobal:himage:nx:ny:nz:fname  [complex input]
    3Dd:hglobal:himage:nx:ny:nz:fname  [double input]

  where '3D:' or '3Ds': signals this is a 3D input file of signed shorts
        '3Db:'          signals this is a 3D input file of unsigned bytes
        '3Di:'          signals this is a 3D input file of signed ints
        '3Df:'          signals this is a 3D input file of floats
        '3Dc:'          signals this is a 3D input file of complex numbers
                         (real and imaginary pairs of floats)
        '3Dd:'          signals this is a 3D input file of double numbers
                         (will be converted to floats)
        hglobal = number of bytes to skip at start of whole file
        himage  = number of bytes to skip at start of each 2D image
        nx      = x dimension of each 2D image in the file
        ny      = y dimension of each 2D image in the file
        nz      = number of 2D images in the file
        fname   = actual filename on disk to read

  * The ':' separators are required.  The k-th image starts at
      BYTE offset hglobal+(k+1)*himage+vs*k*nx*ny in file 'fname'
      for k=0,1,...,nz-1.
  * Here, vs=voxel length=1 for bytes, 2 for shorts, 4 for ints and floats,
      and 8 for complex numbers.
  * As a special case, hglobal = -1 means read data starting at
      offset len-nz*(vs*nx*ny+himage), where len=file size in bytes.
      (That is, to read the needed data from the END of the file.)
  * Note that there is no provision for skips between data rows inside
      a 2D slice, only for skips between 2D slice images.
  * The int, float, and complex formats presume that the data in
      the image file are in the 'native' format for this CPU; that is,
      there is no provision for data conversion (unlike the 3Ds: format).
  * Double input will be converted to floats (or whatever -datum is)
      since AFNI doesn't support double precision datasets.
  * Whether the 2D image data is interpreted as a 3D block or a 3D+time
      block depends on the rest of the command line parameters.  The
      various 3D: input formats are just ways of inputting multiple 2D
      slices from a single file.
  * SPECIAL CASE: If fname is ALLZERO, then this means not to read
      data from disk, but instead to create nz nx*ny images filled
      with zeros.  One application of this is to make it easy to create
      a dataset of a specified geometry for use with other programs.
  * ENVIRONMENT VARIABLE: You can set an environment variable
      (e.g., AFNI_IMSIZE_1) to put a '3D:' type of prefix in front
      of any filename whose file has a given size.  For example,
        setenv AFNI_IMSIZE_1 16384=3D:0:0:64:64:1
      means that any input file of size 16384 bytes will be read
      as a 64x64 image of floats.

  Example: create a 4D dataset from AFNI_data6/EPI_run1
           (first with Dimon, then with to3d ... 3D...)

     One could initially convert the EPI_run1 DICOM images into a
     dataset using Dimon, as in:
          Dimon -infile_prefix EPI_run1/8 -gert_create_dataset
     That would create OutBrick_run_003+orig (.BRIK and .HEAD).

     To create a similar dataset using to3d directly on the binary
     data file OutBrick_run_003+orig.BRIK (to practice 3D*:... usage),
     one could do:

          to3d -prefix to3d_direct          \
               -time:zt 34 67 3.0s alt+z    \
               -orient RAI                  \
               -xSLAB 121.404R-114.846L     \
               -ySLAB 132.526A-103.724P     \
               -zSLAB 43.9268I-71.5732S     \

     Then one could compare the location of the data in space:
          3dinfo -same_all_grid -prefix Out*HEAD to3d_direct*HEAD
     as well as verifying that the raw data BRIKs are identical:
          diff Out*BRIK to3d_direct*BRIK

The 'raw pgm' image format is also supported; it reads data into 'byte' images.

* ANALYZE (TM) .hdr/.img files can now be read - give the .hdr filename on
  the command line.  The program will detect if byte-swapping is needed on
  these images, and can also set the voxel grid sizes from the first .hdr file.
  If the 'funused1' field in the .hdr is positive, it will be used to scale the
  input values.  If the environment variable AFNI_ANALYZE_FLOATIZE is YES, then
  .img files will be converted to floats on input.

* Siemens .ima image files can now be read.  The program will detect if
  byte-swapping is needed on these images, and can also set voxel grid
  sizes and orientations (correctly, I hope).
* Some Siemens .ima files seems to have their EPI slices stored in
  spatial order, and some in acquisition (interleaved) order.  This
  program doesn't try to figure this out.  You can use the command
  line option '-sinter' to tell the program to assume that the images
  in a single .ima file are interleaved; for example, if there are
  7 images in a file, then without -sinter, the program will assume
  their order is '0 1 2 3 4 5 6'; with -sinter, the program will
  assume their order is '0 2 4 6 1 3 5' (here, the number refers
  to the slice location in space).

* GEMS I.* (IMGF) 16-bit files can now be read. The program will detect
  if byte-swapping is needed on these images, and can also set voxel
  grid sizes and orientations.  It can also detect the TR in the
  image header.  If you wish to rely on this TR, you can set TR=0
  in the -time:zt or -time:tz option.
* If you use the image header's TR and also use @filename for the
  tpattern, then the values in the tpattern file should be fractions
  of the true TR; they will be multiplied by the true TR once it is
  read from the image header.

  * Not all AFNI programs support all datum types.  Shorts and
      floats are safest. (See the '-datum' option below.)
  * If '-datum short' is used or implied, then int, float, and complex
      data will be scaled to fit into a 16 bit integer.  If the '-gsfac'
      option below is NOT used, then each slice will be SEPARATELY
      scaled according to the following choice:
      (a) If the slice values all fall in the range -32767 .. 32767,
          then no scaling is performed.
      (b) Otherwise, the image values are scaled to lie in the range
          0 .. 10000 (original slice min -> 0, original max -> 10000).
      This latter option is almost surely not what you want!  Therefore,
      if you use the 3Di:, 3Df:, or 3Dc: input methods and store the
      data as shorts, I suggest you supply a global scaling factor.
      Similar remarks apply to '-datum byte' scaling, with even more force.
  * To3d now incorporates POSIX filename 'globbing', which means that
      you can input filenames using 'escaped wildcards', and then to3d
      will internally do the expansion to the list of files.  This is
      only desirable because some systems limit the number of command-line
      arguments to a program.  It is possible that you would wish to input
      more slice files than your computer supports.  For example,
          to3d exp.?.*
      might overflow the system command line limitations.  The way to do
      this using internal globbing would be
          to3d exp.\?.\*
      where the \ characters indicate to pass the wildcards ? and *
      through to the program, rather than expand them in the shell.
      (a) Note that if you choose to use this feature, ALL wildcards in
          a filename must be escaped with \ or NONE must be escaped.
      (b) Using the C shell, it is possible to turn off shell globbing
          by using the command 'set noglob' -- if you do this, then you
          do not need to use the \ character to escape the wildcards.
      (c) Internal globbing of 3D: file specifiers is supported in to3d.
          For example, '3D:0:0:64:64:100:sl.\*' could be used to input
          a series of 64x64x100 files with names 'sl.01', 'sl.02' ....
          This type of expansion is specific to to3d; the shell will not
          properly expand such 3D: file specifications.
      (d) In the C shell (csh or tcsh), you can use forward single 'quotes'
          to prevent shell expansion of the wildcards, as in the command
              to3d '3D:0:0:64:64:100:sl.*'
    The globbing code is adapted from software developed by the
    University of California, Berkeley, and is copyrighted by the
    Regents of the University of California (see file mcw_glob.c).

RGB datasets [Apr 2002]
You can now create RGB-valued datasets.  Each voxel contains 3 byte values
ranging from 0..255.  RGB values may be input to to3d in one of two ways:
 * Using raw PPM formatted 2D image files.
 * Using JPEG formatted 2D files.
 * Using TIFF, BMP, GIF, PNG formatted 2D files [if netpbm is installed].
 * Using the 3Dr: input format, analogous to 3Df:, etc., described above.
RGB datasets can be created as functional FIM datasets, or as anatomical
 * RGB fim overlays are transparent in AFNI only where all three
    bytes are zero - that is, you can't overlay solid black.
 * At present, there is limited support for RGB datasets.
    About the only thing you can do is display them in 2D slice
    viewers in AFNI.
You can also create RGB-valued datasets using program 3dThreetoRGB.

Other Data Options
     This option will force all input 2 byte images to be byte-swapped
     after they are read in.
     This option will force all input 4 byte images to be byte-swapped
     after they are read in.
     This option will force all input 8 byte images to be byte-swapped
     after they are read in.
     Input images that are auto-detected to need byte-swapping
     (GEMS I.*, Siemens *.ima, ANALYZE *.img, and 3Ds: files)
     will NOT be swapped again by one of the above options.
     If you want to swap them again for some bizarre reason,
     you'll have to use the 'Byte Swap' button on the GUI.
     That is, -2swap/-4swap will swap bytes on input files only
     if they haven't already been swapped by the image input

  -zpad N   OR
  -zpad Nmm
     This option tells to3d to write 'N' slices of all zeros on each side
     in the z-direction.  This will make the dataset 'fatter', but make it
     simpler to align with datasets from other scanning sessions.  This same
     function can be accomplished later using program 3dZeropad.
   N.B.: The zero slices will NOT be visible in the image viewer in to3d, but
          will be visible when you use AFNI to look at the dataset.
   N.B.: If 'mm' follows the integer N, then the padding is measured in mm.
          The actual number of slices of padding will be rounded up.  So if
          the slice thickness is 5 mm, then '-zpad 16mm' would be the equivalent
          of '-zpad 4' -- that is, 4 slices on each z-face of the volume.
   N.B.: If the geometry parent dataset was created with -zpad, the spatial
          location (origin) of the slices is set using the geometry dataset's
          origin BEFORE the padding slices were added.  This is correct, since
          you need to set the origin on the current dataset as if the padding
          slices were not present.
   N.B.: Unlike the '-zpad' option to 3drotate and 3dvolreg, this adds slices
          only in the z-direction.
   N.B.: You can set the environment variable 'AFNI_TO3D_ZPAD' to provide a
          default for this option.

  -gsfac value
     will scale each input slice by 'value'.  For example,
     '-gsfac 0.31830989' will scale by 1/Pi (approximately).
     This option only has meaning if one of '-datum short' or
     '-datum byte' is used or implied.  Otherwise, it is ignored.

  -datum type
     will set the voxel data to be stored as 'type', which is currently
     allowed to be short, float, byte, or complex.
     If -datum is not used, then the datum type of the first input image
     will determine what is used.  In that case, the first input image will
     determine the type as follows:
        byte       --> byte
        short      --> short
        int, float --> float
        complex    --> complex
     If -datum IS specified, then all input images will be converted
     to the desired type.  Note that the list of allowed types may
     grow in the future, so you should not rely on the automatic
     conversion scheme.  Also note that floating point datasets may
     not be portable between CPU architectures.

     tells to3d NOT to scan input float and complex data files for
     illegal values - the default is to scan and replace illegal
     floating point values with zeros (cf. program float_scan).

     Input of huge 3D: files (with all the data from a 3D+time run, say)
     can cause to3d to fail from lack of memory.  The reason is that
     the images are from a file are all read into RAM at once, and then
     are scaled, converted, etc., as needed, then put into the final
     dataset brick.  This switch will cause the images from a 3D: file
     to be read and processed one slice at a time, which will lower the
     amount of memory needed.  The penalty is somewhat more I/O overhead.

NEW IN 1997:
  -orient code
     Tells the orientation of the 3D volumes.  The code must be 3 letters,
     one each from the pairs {R,L} {A,P} {I,S}.  The first letter gives
     the orientation of the x-axis, the second the orientation of the
     y-axis, the third the z-axis:
        R = right-to-left         L = left-to-right
        A = anterior-to-posterior P = posterior-to-anterior
        I = inferior-to-superior  S = superior-to-inferior
     Note that the -xFOV, -zSLAB constructions can convey this information.

NEW IN 2001:
     If present, this tells the program to skip the outlier check that is
     automatically performed for 3D+time datasets.  You can also turn this
     feature off by setting the environment variable AFNI_TO3D_OUTLIERS
     to "No".
    If present, tells the program to only print out the outlier check
     results in text form, not graph them.  You can make this the default
     by setting the environment variable AFNI_TO3D_OUTLIERS to "Text".
    N.B.: If to3d is run in batch mode, then no graph can be produced.
          Thus, this option only has meaning when to3d is run with the
          interactive graphical user interface.
  -save_outliers fname
    Tells the program to save the outliers count into a 1D file with
    name 'fname'.  You could graph this file later with the command
       1dplot -one fname
    If this option is used, the outlier count will be saved even if
    nothing appears 'suspicious' (whatever that means).
  NOTES on outliers:
    * See '3dToutcount -help' for a description of how outliers are
    * The outlier count is not done if the input images are shorts
       and there is a significant (> 1%) number of negative inputs.
    * There must be at least 6 time points for the outlier count to
       be carried out.

    If present, this tells the program that any Siemens DICOM file
    is a potential MOSAIC image, even without the indicator string.
    assume origin and orientation from oblique transformation matrix
    rather than traditional cardinal information (ignores FOV/SLAB
    options Sometimes useful for Siemens mosaic flipped datasets
    reverse the input file list.
    Convenience for Siemens non-mosaic flipped datasets

    If present, search DICOM images for the last occurrence of each
    element, not the first.
    If present, do not use the Dec 2010 updates to siemens mosaic code.
    By default, use the new code if this option is not provided.
    Convert input shorts to float, and add 2^16 to any negatives.
    show debugging information for reading DICOM files

   -gamma gg    the gamma correction factor for the
                  monitor is 'gg' (default gg is 1.0; greater than
                  1.0 makes the image contrast larger -- this may
                  also be adjusted interactively)
   -ncolors nn  use 'nn' gray levels for the image
                  displays (default is 80)
   -xtwarns     turn on display of Xt warning messages
   -quit_on_err Do not launch interactive to3d mode if input has errors.

++ Compile date = May 27 2024 {AFNI_24.1.15:linux_ubuntu_16_64}