matchvol(1)                                                        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 (-c) 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 3DTransform entries.  (Successive entries accumu-
              late)

       -order (-or) OR -InterpolationOrder      Integer
              Order of interpolation to use.  Currently only quadratic (2) and
              linear (1) interpolation are available; the default is
              quadratic.

       -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 768.

       -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.



BL3DEMC                              4.7.3                         matchvol(1)