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). When entering data that is not in the pre-recognized formats, the onus is on the user to specify the location of the image data in the file. This is done with the following type of file specification:

 3D:hglobal:himage:nx:ny:nz:fname   [16 bit input]
 3Ds:hglobal:himage:nx:ny:nz:fname  [16 bit input, swapped bytes]
 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]

• The "3D" prefix, where
  • "3D:" signals that the image data are signed shorts (16 bit integers).
  • "3Ds:" signals that the image data are signed shorts that should be byte-swapped as they are read in.
  • "3Db:" signals that the image data are unsigned bytes (8 bit integers).
  • "3Di:" signals that the image data are signed ints (32 bit integers). Note that AFNI itself cannot deal with int datasets.
  • "3Df:" signals that the image data are 32 bit floats.
  • "3Dc:" signals that the image data are 64 bit complex numbers (real and imaginary pairs of floats).
• "hglobal" = the global header offset, which is the number of bytes to skip at start of whole file.
• "himage" = the per image header offset, which is the 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. You can input a single image using nz=1.
• "fname" = actual filename on disk to read.

  Further points about this file format specifier:

• The ":" separators between the elements are required.
• The k-th 2D image starts at BYTE offset into the file of hglobal+(k+1)*himage+vs*k*nx*ny in file "fname" for k=0,1,...,nz-1, where vs=voxel length=1 for bytes, 2 for shorts, 4 for ints and floats, and 8 for complex numbers.
• As a special case, using hglobal=-1 means to read data starting at offset len-nz*(vs*nx*ny+himage), where len=file size in bytes. That is, the image data will be read from as far into the file as possible. This is useful when you don't know the image header size, but do know that there is no "footer" at the end of the file.
• It is now legal to have hglobal<-1, as long as hglobal+himage>=0. This is to allow for the possibility of image "footers". [Requested by Gary Strangman of MGH; implemented 13 Apr 1999.]
• 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).
• Programs 2swap and 4swap can be used to swap bytes (2 at a time or 4 at a time) on arbitrary files, if necessary when transferring data between CPU types (e.g., MIPS to Intel).
  • The to3d command line options -2swap and -4swap can be used to have the same effect on each input image file, as they are read into memory.
    
  • The Byte Swap button in the interactive to3d control panel can also be used to swap the bytes in a dataset. Combined with the View Images button, this feature lets you visually inspect the images prior to output into the dataset .BRIK file.
    
  • Generally speaking, images you input from the scanner will be non-negative. (Most image reconstruction programs take the absolute value of the reconstructed data as the last step in the process.) If there are negative values in such images, this means that the data is probably byte-swapped relative to the CPU on which you are using to3d. Negative values can and do occur in derived images (e.g., correlation coefficient maps).
• Whether the 2D image data is interpreted by to3d 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 one or more 2D slices from a single file.
• to3d and AFNI incorporate POSIX filename "globbing", which means that you can input filenames using wildcards, and then the programs will internally do the expansion to the list of files. This is only desirable because some systems (e.g., SGI IRIX) limit the number of command-line arguments to a program. (Normally, the shell program to which you type input commands expands wildcard characters such as "*" and "?" to match filenames, and passes the list of matching filenames to the program. If the number of matching filenames is too large, the shell might give an error message and fail to run the 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 are needed so that the shell program doesn't try to expand the wildcard characters "?" and "*" itself.
• Internal globbing of the "3D:" type of file specifiers is also supported in to3d and AFNI. For example, '3D:-1:0:64:64:100:sl.\*' could be used to input a series of 64x64x100 files with names sl.01, sl.02 ....

  setenv AFNI_IMSIZE_1 8272=3D:-1:0:64:64:1:

The following shows how you can specify a variable length for such automatic recognition:

  setenv AFNI_IMSIZE_2 %16096+80=3D:80:7904:64:64:

Finally, the preset file sizes that the AFNI package functions recognize are listed below. In the cases with Signa headers, the header information is skipped at the front of the file (AFNI programs do not attempt to read any header information from any scanner manufacturer files). If you create an AFNI_IMSIZE_xx variable with one of these lengths, it will override the interpretation given below. (xx may range from 1 to 99.)

  4096    = 64x64 byte
  8192    = 64x64 short
  16096   = 64x64 short with GE Signa 5.x header
  16384   = 128x128 byte
  32768   = 128x128 short
  40672   = 128x128 short with GE Signa 5.x header
  65536   = 256x256 byte
  131072  = 256x256 short
  138976  = 256x256 short with GE Signa 5.x header
  145408  = 256x256 short with GE Signa 4.x header
  262144  = 512x512 byte
  524288  = 512x512 short
  1048576 = 1024x1024 byte
  2097152 = 1024x1024 short

[14 Sep 1999] Even more finally, to3d now checks float and complex input files for illegal values. See the answer to Q53 for more information.

[10 Feb 2000] Also see Q63.

[09 May 2000] Also see Q66.
In there, the issue of breaking up a set of images that have been assembled into a 2D layout is addressed (using the new program imcutup). The 3D: method can only deal with images that are assembled into a 1D layout, so that all the data bytes for one image are contiguous in the file.

[20 Mar 2001] to3d can now read Mayo ANALYZE75 files (.hdr/.img pairs; see Q13), and also makes an attempt to read Siemens Vision .ima files (which can be arranged into a 2D montage of sub-images, as described in the link immediately above). To input an ANALYZE .hdr/.img pair to to3d, specify the .hdr filename on the command line, as in

  to3d -time:zt 18 160 3s alt+z fred*.hdr

To input a Siemens Vision .ima file (which contains its own header data), just put the filename on the command line, as in

  to3d -time:zt 7 33 4s alt+z elvis*.ima

[30 Nov 2001] AFNI programs can now read MINC files directly as datasets, without the need to go through to3d. Also, the new program 3dMINCtoAFNI can convert a MINC file to an AFNI dataset; 3dAFNItoMINC will convert an AFNI dataset to a MINC file. (Don't input MINC files to to3d!)

[04 Dec 2001] to3d can now read GE I.* formatted ("ximg"/"IMGF") image files, extracting the voxel sizes, orientations, and offset from the header of each file, as well as determining if the image data in the file needs to be byte-swapped. For example:

  to3d -time:zt 18 100 0s alt+z I.*

[Answer last changed 04 Dec 2001]