Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

FINDDISTORT(1)						       FINDDISTORT(1)

NAME
  finddistort - Solves for image distortion field from overlapping images

SYNOPSIS
  finddistort [options] input_file output_rootname

DESCRIPTION
  Finddistort analyzes overlapping images and solves for the underlying image
  distortion field.  The basis for the analysis is the fact that after two
  overlapping images are shifted into best registration, the remaining image
  displacement at a particular point in the overlap zone is the difference
  between the distortion vectors at two locations in the original images.  The
  optimal input for this analysis is a set of 4 pairs of overlapping images.
  Each pair would overlap over a little more than 50% of their area.  The two
  paired images would be displaced from each other horizontally, vertically,
  and on 45 and 135 degree diagonals for the 4 kinds of pairs.  With this
  arrangement, the different pairs provide largely independent rather than
  redundant information, and the amount of data about image displacements is
  about twice as numerous as the number of vectors of the image distortion
  field to be solved for; thus a robust solution can be obtained.

  The program operates as follows.  First, each pair of images is
  cross-correlated with a large amount of padding to find the overall
  displacement.  This is done by running Tiltxcorr.  Next, this overall
  displacement is applied to align the two images where they overlap, then the
  local displacements are found at a grid of locations in the overlap zone,
  using the same subroutines that Blendmont uses to find "edge functions".
  The spacing of this grid is specified by the GridSpacing option.  Linear
  equations are set up relating data interpolated from this grid (at a spacing
  set by the DataSpacing option) to the unknown vectors of the underlying
  distortion field.  These unknowns are located on a grid at yet another
  spacing (set by the FieldSpacing option), and making this spacing larger
  than the data spacing makes the equations even more overdetermined.  The
  program solves these equations to find an initial distortion field.

  Once there is a distortion field, the procedure is iterated, except that the
  images are undistorted before being correlated to find the overall
  displacement.  However, this procedure will not converge to a unique
  solution unless the distortion field is modified by another operation at
  each step, because it is possible to change the overall displacement between
  overlapping images and stretch the distortion field to compensate.  Thus,
  every time a field is solved for, any net stretch in the field is removed to
  preduce a stretch-free distortion field.  With this step, the iterations
  converge to a stable solution for the stretch-free distortion field.  This
  distortion field is output to a file rootname.nosidf after each iteration.

  The stretch in the distortion field can be determined from the
  transformation needed to align two images of the same field rotated by an
  angle near 90 degrees.  When such a transformation is supplied, the program
  computes the implied stretch in the projection process, and then introduces
  this stretch into the distortion field.  Whether or not this transformation
  is given, the final field is output into rootname.idf.

  Other temporary files produced are: rootname.xcxf with the shifts for one
  image pair, output by Tiltxcorr; rootname.tmpxf with rootname.rawxf with
  the initial shifts between paired images; rootname.udxf with the shifts
  between undistorted imaged; rootname.udst with the undistorted images.

  Finddistort uses the PIP package for input exclusively (see the manual page
  for pip).  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 with distortion pairs.  If this option is not entered,
    the first non-option argument will be taken as the input file name.

 -output OR -OutputRoot   File name
    Root name for output files.  If this option is not entered, the second
    non-option argument will be used as the root name.

 -pairs OR -PairsToAnalyze   List of integer ranges
    List of images to analyze in pairs; for example 0-7 if sections 0 and 1, 2
    and 3, 4 and 5, and 6 and 7 are all image pairs.  The default is to assume
    that all images in the file form successive pairs.  Sections are numbered
    from 0.

 -binning OR -ImageBinning   Integer
    Binning of images on the CCD camera (default 2)

 -field OR -FieldSpacing   Integer
    Pixel spacing for output distortion field (default 40)

 -data OR -DataSpacing   Integer
    Pixel spacing for data used to solve linear equations for the distortion
    field.  This spacing should be about half of the spacing for the output
    field.  The default is 20.

 -grid OR -GridSpacing   Integer
    Pixel spacing for grid on which displacements will be measured in the
    overlap zones between paired images (default 16).

 -box OR -BoxSize   Integer
    Size of box used to measure local displacements.  Boxes of this size will
    be correlated between the two images at every position on the grid.  The
    default is 24.  This value should be increased if the solution is noisy.

 -indent OR -GridIndent   Integer
    Amount to indent the boxes in the grid of displacements from the edge of
    the overlap zone.  The default is 4 pixels; this vakue can be dropped to 2
    for larger than default boxes.

 -iterations OR -Iterations   Integer
    Maximum number of iterations when solving equations

 -usexf OR -UseOldTransforms
    Use existing transforms instead of running Tiltxcorr on the first
    iteration; these transforms are stored in the file rootname.rawxf when
    Tiltxcorr is run on the first iteration.

 -strfile OR -StretchFile   File name
    File with transformation that aligns two 90-degree rotated images of the
    same area.  This transformation is used to determine the absolute stretch
    in the distortion field.

 -patch OR -PatchOutput
    Output a patch file to convert to a model with patch2imod.  The patch file
    will be named rootname.patch.

 -coverage OR -CoverageImage   File name
    Name of file in which to place an image representing the amount of data
    available for solving each vector.  This is image is based on the sum of
    the coefficients for each distortion vectors, normalized so that the mean
    sum will equal the ratio of total measurements to unknowns (rows to
    columns in the data matrix).  To get a true representation of the amount
    of nonredundant coverage of each field position, use -data to set the data
    spacing the same as the field spacing.

 -redirect OR -RedirectOutput   Text string
    String for redirecting output from Tiltxcorr and Newstack.  The default is
    "> /dev/null", which will not work in Windows.  A valid Windows path must
    be entered; "> xcorr.tmp" would work.

 -multr OR -SolveWithMultr
    Use matrix inversion instead of iterative method to solve equations.

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