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:
ANATOMICAL TYPES
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
FUNCTIONAL TYPES
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 DEPENDENT DATASETS [* NEW IN 1996 *]
-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.
Notes:
* 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]
COMMAND LINE GEOMETRY SPECIFICATION [* NEW IN 1996 *]
-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!
Z-AXIS SLICE OFFSET ONLY
-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.
INPUT IMAGE FORMATS [* SIGNIFICANTLY CHANGED IN 1996 *]
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 \
3D:0:0:64:64:2278:OutBrick_run_003+orig.BRIK
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.
NOTES:
* 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
datasets:
* 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
------------------
-2swap
This option will force all input 2 byte images to be byte-swapped
after they are read in.
-4swap
This option will force all input 4 byte images to be byte-swapped
after they are read in.
-8swap
This option will force all input 8 byte images to be byte-swapped
after they are read in.
BUT PLEASE NOTE:
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
function.
-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.
-nofloatscan
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).
-in:1
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:
-skip_outliers
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".
-text_outliers
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
defined.
* 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.
OTHER NEW OPTIONS:
-assume_dicom_mosaic
If present, this tells the program that any Siemens DICOM file
is a potential MOSAIC image, even without the indicator string.
-oblique_origin
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_list
reverse the input file list.
Convenience for Siemens non-mosaic flipped datasets
-use_last_elem
If present, search DICOM images for the last occurrence of each
element, not the first.
-use_old_mosaic_code
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.
-ushort2float
Convert input shorts to float, and add 2^16 to any negatives.
-verb
show debugging information for reading DICOM files
OPTIONS THAT AFFECT THE X11 IMAGE DISPLAY
-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 = Oct 17 2024 {AFNI_24.3.03:linux_ubuntu_24_64}
