warpvol(1) General Commands Manual warpvol(1)
NAME
warpvol - to warp one volume into alignment with another
SYNOPSIS
warpvol [options] input_file output_file
DESCRIPTION
Warpvol will transform a volume using a series of general linear trans-
formations. Its original use was to "warp" one tomogram from a two-axis
tilt series so that it matches the other tomogram, but it is also used
for volume flattening and for transforming adjacent, overlapping tomo-
grams into alignment so that theycan be stitched together. For each
position in the volume, it interpolates between adjacent transforma-
tions to find the transformation appropriate for that position. Any
initial alignment transformation (from Solvematch) must be already con-
tained in the transformations entered into this program; this combining
of transformations is accomplished by Findwarp. It can work with
either a 2-D matrix of transformations (varying in X and Z) or with a
general 3-D matrix, as output by Findwarp. The program uses the same
algorithm as Rotatevol for rotating large volumes.
OPTIONS
Warpvol uses the PIP package for input (see the manual page for pip)
and can take input interactively for options that existed when it was
converted, to maintain compatibility with old command files. The fol-
lowing options can be specified either as command line arguments (with
the -) or one per line in a command file or parameter file (without the
-). Options can be abbreviated to unique letters; the currently valid
abbreviations for short names are shown in parentheses.
-input (-i) OR -InputFile File name
Input image file to warp
-output (-ou) OR -OutputFile File name
Output file for warped volume
-xforms (-x) OR -TransformFile File name
File with matrix of inverse transforms produced by Findwarp
-scale (-sc) OR -ScaleTransforms Floating point
Factor by which to scale transforms, to account for the input
image file having a different binning or scaling than the file
on which transforms were derived. For example, if transforms
were found on files binned by 2, enter 2 to apply the transforms
to an unbinned file.
-tempdir (-t) OR -TemporaryDirectory Text string
Directory to use for temporary files. The default is that the
temporary files will be placed in the current directory.
-size (-si) OR -OutputSizeXYZ Three integers
X, Y, Z dimensions of the output file (Default is Z, Y, X size
of input file)
-same (-sa) OR -SameSizeAsInput
Make default size of output file be same size as input file.
One or more of the dimensions can be overridden by a value in a
-size entry.
-order (-or) OR -InterpolationOrder Integer
Order of interpolation to use. Currently only quadratic (2) and
linear (1) interpolation are available; the default is quadrat-
ic.
-chunk (-c) OR -ChunkSizesForHDF Three integers
Size of chunks in X, Y, and Z for output to an HDF file orga-
nized in chunks. Storing data this way will prevent the need to
output cubes of transformed data to scratch files and read them
back in to make the final output, when the volume is too large
to fit in the allowed memory. Enter 0,0,0 for the default size,
which is for chunks the same size as the cubes that would ordi-
narily be written to scratch files, and for no chunks at all if
data are being handled in one cube per layer. If a specific
size is entered for one or more axes, then the program will
first determine the division into cubes, and then make the chunk
size be the minimum of the cube size and the specified value for
each axis. When using chunks, the memory is limited to 15000
megabytes even if a larger value is entered.
-memory (-m) OR -MemoryLimit Integer
Amount of memory to allocate for the major arrays needed by the
program, in megabytes. This always includes memory for input
images and may include memory for a plane of transformations or
for a stack of output slices, depending on whether transforma-
tions rotate the data by 90 degrees. The default is the minimum
of system memory minus 1 GB, 60% of system memory, and 12 GB for
system memory up to 30 GB, and 40% of system memory above 30 GB,
but at least 768 MB.
-verbose (-v) OR -VerboseOutput Integer
1 for diagnostic output; 2 for output as each slice is loaded
-patch (-pat) OR -PatchOutputFile File name
Output text file for vectors representing the displacement pro-
duced by each transform. It can be converted to a model with
patch2imod. The program will exit without making an output
file if this option is given.
-filled (-f) OR -FilledInOutputFile File name
Output file for warping transforms after filling in empty posi-
tions. The program will exit without making an output image
file if this option is given.
-param (-par) OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter
file.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
INTERACTIVE INPUT
If the program is started with no command line arguments, it reverts to
interactive input with the following entries:
Name of the input file to be transformed
Name of the output file for the transformed volume
Path name of directory (for example, /usr/tmp) where temporary files
can be placed, or Return to have files placed in the current
directory
X, Y, and Z dimensions of the output file, or / to accept the default
values, which are NZ, NY, and NX of the input volume (a 90-degree
rotation about the Y axis)
Name of the file with the matrix of inverse transformations
(produced by Findwarp)
Additional Notes
Format of Warping File: The warping file can have three forms, deter-
mined by the number of entries on the first line of the file. If there
are two entries on this line, they specify the number of positions in X
and in Z. If there are three entries, they specify the number of posi-
tions in X, Y, and Z. In either of these two cases, there must be a
transform in the file for every such location in the 2D or 3D array of
positions. In the third form, not all transforms need to be present,
and the header line contains 9 entries indicating the number of posi-
tions, the starting position, and the interval between positions in
each dimension:
#_in_X #_in_Y #_in_Z start_X start_Y start_Z delta_X delta_Y
delta_Z
For each position, there are four lines:
centered_X centered_Y centered_Z
a11 a12 a13 dx
a21 a22 a23 dy
a31 a32 a33 dz
where the coordinates are relative to the center of the volume, and the
next three lines specify an inverse transformation for getting from a
location in the output volume to a location in the input volume:
xi = a11 * xo + a12 * yo + a13 * zo + dx
yi = a21 * xo + a22 * yo + a23 * zo + dy
zi = a31 * xo + a32 * yo + a33 * zo + dz
where (xo, yo, zo) are coordinates relative to the center of the output
volume, and (xi, yi, xi) are coordinates relative to the center of the
input volume. The center coordinates of the transforms are used to
assign them to the regular array of positions, so transforms that are
not located at these regular positions will be relocated and will not
perform as expected.
Missing Transforms: If there are missing transforms, the array will be
filled in at each empty spot by taking a weighted average of the near-
est defined transforms. Once the nearest existing transform is found
to a particular spot, transforms are included from positions up to
twice as far away as the nearest one, and their weights are propor-
tional to the square of their distances from the position being filled
in. The same approach is used to extend the transform array to cover
all positions in the output volume being computed.
HISTORY
Written by David Mastronarde 11/15/96; modified for 3-D matrix of
transformations, 7/23/97
Converted to PIP/autodoc 10/10/03
Changed the way transforms are filled in and extrapolated, 6/7/09
Converted to Fortran 95, parallelized with OpenMP, 6/14/09
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.0.2 warpvol(1)