Usage: 3dUndump [options] infile ...
Assembles a 3D dataset from an ASCII list of coordinates and
(optionally) values.
Options:
--------
-prefix ppp = 'ppp' is the prefix for the output dataset
[default = undump].
-master mmm = 'mmm' is the master dataset, whose geometry
*OR* will determine the geometry of the output.
-dimen I J K = Sets the dimensions of the output dataset to
be I by J by K voxels. (Each I, J, and K
must be >= 1.) This option can be used to
create a dataset of a specific size for test
purposes, when no suitable master exists.
** N.B.: Exactly one of -master or -dimen must be given.
==>> Unless -ROImask is used!
-mask MMM = This option specifies a mask dataset 'MMM', which
will control which voxels are allowed to get
values set. If the mask is present, only
voxels that are nonzero in the mask can be
set in the new dataset.
* A mask can be created from a pre-existing dataset
with program 3dAutomask.
* Combining a mask with sphere insertion makes
a lot of sense (to me, at least).
-datum type = 'type' determines the voxel data type of the
output, which may be byte, short, or float
[default = short].
-dval vvv = 'vvv' is the default value stored in each
input voxel that does not have a value
supplied in the input file [default = 1].
*** For example: '-dval 7' makes all the voxels
whose locations (via '-ijk' or '-xyz') are
given without a value get the value 7.
-fval fff = 'fff' is the fill value, used for each voxel
in the output dataset that is NOT listed
in the input file [default = 0].
*** For example: '-fval 1' makes all the completely
unspecified voxels get the value 1.
-ijk = Coordinates in the input file are (i,j,k) index
*OR* triples, as might be output by 3dmaskdump.
-xyz = Coordinates in the input file are (x,y,z)
spatial coordinates, in mm. If neither
-ijk or -xyz is given, the default is -ijk.
** N.B.: -xyz can only be used with -master. If -dimen
is used to specify the size of the output dataset,
(x,y,z) coordinates are not defined (until you
use 3drefit to define the spatial structure).
** N.B.: Also see the -ROImask option (infra) for another
way to specify what voxels in the output dataset
get what values:
-- with -ROImask, neither -xyz nor -ijk is used.
-srad rrr = Specifies that a sphere of radius 'rrr' will be
filled about each input (x,y,z) or (i,j,k) voxel.
If the radius is not given, or is 0, then each
input data line sets the value in only one voxel.
* If '-master' is used, then 'rrr' is in mm.
* If '-dimen' is used, then 'rrr' is in voxels.
*** For example: '-srad 7' means put a sphere of
radius 7 mm about each input point.
-cubes = Put cubes down instead of spheres. The "radius" then
is half the length of a side.
-orient code = Specifies the coordinate order used by -xyz.
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
If -orient isn't used, then the coordinate order of the
-master dataset is used to interpret (x,y,z) inputs.
** N.B.: If -dimen is used (which implies -ijk), then the
only use of -orient is to specify the axes ordering
of the output dataset. If -master is used instead,
the output dataset's axes ordering is the same as the
-master dataset's, regardless of -orient.
** You probably don't need this option, and it is kept
here only for historical purposes.
-head_only = A 'secret' option for creating only the .HEAD file which
gets exploited by the AFNI matlab library function
New_HEAD.m
-ROImask rrr = This option that lets you specify which voxels get what
numbers by using a dataset 'rrr', instead of coordinates.
==>>** With this method, the input file should have just
one number per line (trailing numbers will be ignored).
** Due to the special way that 3dUndump reads input files, you
CANNOT specify an input file using the 1D '[subscript]'
notation to pick out a single column of a multicolumn
file. Instead, you can do something like
1dcat file.1D'[3]' | 3dUndump -ROImask rmask+orig -prefix ppp -
where the last '-' says to read from standard input.
** A more complicated example, using an ROI mask dataset 'mmm+orig'
to extract average values from a functional dataset, then create
a dataset where the values stored are the ROI averages:
3dROIstats -mask mmm+orig -1Dformat func+orig'[1]' | \
| 1dcat stdin: | 3dUndump -prefix uuu -datum float -ROImask mmm+orig -
Again, the final '-' tells 3dUndump to read the values to be
stored from standard input (the pipe).
** If the numbers in the input file are fractional (e.g., '1.372'),
be sure to use the '-datum float' option -- otherwise, the
default output is '-datum short', which will truncate values!
* The 'rrr' dataset must be of integer type -- that is,
the values inside must be bytes or shorts. If you don't
know, use program 3dinfo to check.
* All voxels with value 1 in dataset 'rrr' get the number in
the first row of the input file.
* All voxels with value 2 in dataset 'rrr' get the number in
the second row of the input file.
* Et cetera -- all voxels with value 'n' in dataset 'rrr' get
the number in the n-th row of the input file.
* Zero or negative values in 'rrr' are ignored completely.
* The output dataset has the same spatial grid as 'rrr'
(i.e., as if '-master rrr' were used).
* The following options cannot be used with -ROImask:
-dimen -master -mask -dval
-ijk -xyz -srad -orient -head_only
* This option was added 09 Nov 2011:
-- Happy 280th Birthday to Benjamin Banneker!
-- http://en.wikipedia.org/wiki/Benjamin_Banneker
Input File Format:
------------------
The input file(s) are ASCII files, with one voxel specification per
line. A voxel specification is 3 numbers (-ijk or -xyz coordinates),
with an optional 4th number giving the voxel value. For example:
1 2 3
3 2 1 5
5.3 6.2 3.7
// this line illustrates a comment
The first line puts a voxel (with value given by '-dval') at point
(1,2,3). The second line puts a voxel (with value 5) at point (3,2,1).
The third line puts a voxel (with value given by '-dval') at point
(5.3,6.2,3.7). If -ijk is in effect, and fractional coordinates
are given, they will be rounded to the nearest integers; for example,
the third line would be equivalent to (i,j,k) = (5,6,4).
Notes:
------
* This program creates a 1 sub-brick file. You can 'glue' multiple
files together using 3dbucket or 3dTcat to make multi-brick datasets.
*** At this time, 3dUndump cannot create a multi-brick dataset :-(
* If one input filename is '-', then stdin will be used for input.
This feature is for the intrepid Unix user who wants to pipe the
input into 3dUndump from another program.
* If no input files are given, an 'empty' dataset is created.
For example, to create an all zero 3D dataset with 1 million voxels:
3dUndump -dimen 100 100 100 -prefix AllZeroAFNI
3dUndump -dimen 100 100 100 -prefix AllZeroNIFTI.nii
*** This is probably the simplest way to create an all zero dataset
with given grid dimensions in AFNI, without any pre-existing
'master' dataset to start with. If you want to further change
the voxel sizes (in mm), you can use 3drefit to alter such
parameters after the initial act of creation ab nihilo.
*** You can combine 3dUndump with 3dcalc to create an all zero
3D+time dataset from 'thin air', as in
3dUndump -dimen 128 128 32 -prefix AllZero_A -datum float
3dcalc -a AllZero_A+orig -b '1D: 100@' -expr 0 -prefix AllZero_B
If you replace the '0' expression with 'gran(0,1)', you'd get a
random 3D+time dataset, which might be useful for testing purposes.
* By default, the output dataset is of type '-fim', unless the -master
dataset is an anat type. You can change the output type later using 3drefit.
* You could use program 1dcat to extract specific columns from a
multi-column rectangular file (e.g., to get a specific sub-brick
from the output of 3dmaskdump), and use the output of 1dcat as input
to this program. If you know what you are doing, that is.
* [19 Feb 2004] The -mask and -srad options were added this day.
Also, a fifth value on an input line, if present, is taken as a
sphere radius to be used for that input point only. Thus, input
3.3 4.4 5.5 6.6 7.7
means to put the value 6.6 into a sphere of radius 7.7 mm centered
about (x,y,z)=(3.3,4.4,5.5).
* [10 Nov 2008] Commas (',') inside an input line are converted to
spaces (' ') before the line is interpreted. This feature is for
convenience for people writing files in CSV (Comma Separated Values)
format.
++ [14 Feb 2010] Semicolons (';') and colons (':') are now changed
to blanks, as well. In addition, any line that starts with
an alphabetic character, or with '#' or '/' will be skipped
(presumably it is some kind of comment).
* [31 Dec 2008] Inputs of 'NaN' are explicitly converted to zero, and
a warning message is printed. AFNI programs do not like with NaN
floating point values!
* [09 Jun 2021] The new option '-allow_NaN' will let NaN (not-a-number)
values be entered. This option must be used before any input values
are given (e.g., via '-dval').
++ NaN is a floating point concept. If you input (say) -dval as NaN,
but then use it in creating a short-valued dataset, you will get
the same as '-dval 0' -- there is no equivalent to Not-a-Number
in the 2's complement world of integer representations.
++ IN OTHER WORDS: use '-datum float' if you use '-allow_Nan',
OR you will end up mystified.
++ Please note that AFNI programs will convert NaN values to 0 on input,
from files stored in NIfTI and some other more obscure formats.
++ And: .BRIK files will be similarly scanned/fixed on input if
environment variable AFNI_FLOATSCAN is set to YES.
++ And: the AFNI GUI will not like you at some point if you are
trying to view a file containing NaNs.
++ In other words:
The only reason for '-allow_NaN' is to create files for testing.
And only for the semi-deranged amongst us. (You know who I mean.)
++ Sample command line:
echo '0 0 0' | 3dUndump -allow_NaN -datum float -dimen 50 50 50 -prefix Ubad -dval NaN -
float_scan Ubad+orig.BRIK
Program float_scan should tell you that Ubad+orig.BRIK has 1 bad value in it.
-- RWCox -- October 2000
++ Compile date = Oct 17 2024 {AFNI_24.3.03:linux_ubuntu_24_64}
