finddistort(1)                                                  finddistort(1)

       finddistort - Solves for image distortion field from overlapping images

       finddistort [options] input_file output_rootname

       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 differ-
       ent pairs provide largely independent rather than redundant informa-
       tion, 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 displace-
       ment.  This is done by running Tiltxcorr.  Next, this overall dis-
       placement 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 trans-
       formation 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 root-

       Other temporary files produced are: rootname.xcxf with the shifts for
       one image pair, output by Tiltxcorr; rootname.tmpxf with root-
       name.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 -).  Options can be abbreviated to
       unique letters; the currently valid abbreviations for short names are
       shown in parentheses.

       -input (-inp) 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 (-o) 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 (-pai) 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 (-bi) OR -ImageBinning     Integer
              Binning of images on the CCD camera (default 2)

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

       -data (-d) 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 (-g) OR -GridSpacing     Integer
              Pixel spacing for grid on which displacements will be measured
              in the overlap zones between paired images (default 16).

       -box (-bo) 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 (-ind) 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 (-it) OR -Iterations    Integer
              Maximum number of iterations when solving equations

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

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

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

       -coverage (-c) 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 vec-
              tors, 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 nonre-
              dundant coverage of each field position, use -data to set the
              data spacing the same as the field spacing.

       -redirect (-r) 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 (-m) OR -SolveWithMultr
              Use matrix inversion instead of iterative method to solve equa-

       -param (-par) OR -ParameterFile     Parameter file
              Read parameter entries as keyword-value pairs from a parameter

       -help (-h) OR -usage
              Print help output.

              Read parameter entries from standard input.

       Email bug reports to mast at colorado dot edu.

BL3DEMC                              4.7.3                      finddistort(1)