Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells
WARPVOL(1) WARPVOL(1)
NAME
warpvol - to warp one volume into alignment with another
SYNOPSIS
warpvol
DESCRIPTION
Warpvol will transform a volume using a series of general linear
transformations. 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
tomograms into alignment so that theycan be stitched together.
For each position in the volume, it interpolates between adjacent
transformations to find the transformation appropriate for that
position. Any initial alignment transformation (from Solvematch) must
be already contained 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.
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
following options can be specified either as command line arguments (with
the -) or one per line in a command file or parameter file (without
the -):
-input OR -InputFile File name
Input image file to warp
-output OR -OutputFile File name
Output file for warped volume
-xforms OR -TransformFile File name
File with matrix of inverse transforms produced by Findwarp
-scale 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 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 OR -OutputSizeXYZ Three integers
X, Y, Z dimensions of the output file (Default is Z, Y, X size of input
file)
-same 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 -InterpolationOrder Integer
Order of interpolation to use. Currently only quadratic (2) and linear
(1) interpolation are available; the default is quadratic.
-memory 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 transformations rotate the data by 90
degrees. The default is 768.
-verbose OR -VerboseOutput Integer
1 for diagnostic output; 2 for output as each slice is loaded
-patch OR -PatchOutputFile File name
Output text file for vectors representing the displacement produced 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 OR -FilledInOutputFile File name
Output file for warping transforms after filling in empty positions. The
program will exit without making an output image file if this option is
given.
-param OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter file.
-help OR -usage
Print help output
-StandardInput
Read parameter entries from standard 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)
Format of Warping File
The warping file can have three forms, determined 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 positions 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 positions, 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.
If there are missing transforms, the array will be filled in at each empty
spot by taking a weighted average of the nearest 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 proportional 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