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

 -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