Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

MATCHVOL(1)							    MATCHVOL(1)

NAME
  matchvol - transform a volume to match another with a general linear
			transformation

SYNOPSIS
  matchvol

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.

  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 (without 
  the -):

 -input OR -InputFile   File name
    Input image file to transform

 -output OR -OutputFile   File name
    Output file for transformed volume

 -inverse OR -InverseFile   File name
    Output file in which to write the inverse of the combined transformation. 
    This output is optional.

 -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 size of input file)

 -center OR -CenterXYZ   Three floats
    X, Y, Z index coordinates of the center of the region to transform
    (Default is center of input file).  Coordinates are numbered from zero.

 -xffile 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 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).  Multiple transforms are
    applied in the order that they are entered, and after any 3DTransform
    entries.
    (Successive entries accumulate)

 -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 stack of output slices, depending on the orientation
    of the output.  The default is 768.

 -verbose OR -VerboseOutput   Integer
    1 for diagnostic output

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