matchvol(1) General Commands Manual matchvol(1)
NAME
matchvol - transform a volume to match another with a general linear
transformation
SYNOPSIS
matchvol [options input_file output_file
DESCRIPTION
Matchvol will transform a volume using a general linear transformation.
Its main use is to transform one tomogram from a two-axis tilt series
so that it matches the other tomogram. To do so, it can combine an
initial alignment transformation and any number of successive refining
transformations. The program uses the same algorithm as Rotatevol for
rotating large volumes.
The format of the 3D transform when stored in a file is to consist of 3
lines:
a11 a12 a13 dx
a21 a22 a23 dy
a31 a32 a33 dz
which specify a transformation for getting from a location in the input
volume to a location in the output volume:
xo = a11 * xi + a12 * yi + a13 * zi + dx
yo = a21 * xi + a22 * yi + a23 * zi + dy
zo = a31 * xi + a32 * yi + a33 * zi + 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.
OPTIONS
Matchvol 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 (with-
out the -). Options can be abbreviated to unique letters; the cur-
rently valid abbreviations for short names are shown in parentheses.
-input (-inp) OR -InputFile File name
Input image file to transform
-output (-ou) OR -OutputFile File name
Output file for transformed volume
-inverse (-inv) OR -InverseFile File name
Output file in which to write the inverse of the combined trans-
formation. This output is optional.
-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 (-s) OR -OutputSizeXYZ Three integers
X, Y, Z dimensions of the output file (Default is size of input
file)
-center (-ce) OR -CenterXYZ Three floats
X, Y, Z index coordinates of the center of the region to trans-
form (Default is center of input file). Coordinates are num-
bered from zero.
-xffile (-x) OR -TransformFile File name
Name of file with 3D transform to apply. Multiple transforms
are applied in the order that they are entered, and before any
3DTransform entries. (Successive entries accumulate)
-3dxform (-3) OR -3DTransform Multiple floats
A 3D transform to apply, consisting of 12 values on one line
(a11, a12, a13, dx, a21, a22, a23, dy, a31, a32, a33, dz). Mul-
tiple transforms are applied in the order that they are entered,
and after any TransformFile entries. (Successive entries accu-
mulate)
-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 (-ch) 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 stack of output slices,
depending on the orientation of the output. 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
-param (-p) 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 INPUTS
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)
Number of successive transformations to combine and apply
For each transformation, either enter the name of a file with
the transformation, or enter a Return, then enter the 12-element
transformation directly. Transform files need not all occur before
direct entries.
Name of a file in which to place the inverse of the combined
transformation, or Return for no such output
HISTORY
Written by David Mastronarde, 1995
Converted to PIP/autodoc 10/10/03
Converted to Fortran 95, parallelized with OpenMP, 6/14/09
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.11.0 matchvol(1)