edgepatches(1)              General Commands Manual             edgepatches(1)



NAME
       edgepatches - Initial alignment in stitching montage of overlapping
       tomograms

SYNOPSIS
       edgepatches  options  supermontage_info_file

DESCRIPTION
       Edgepatches is a Python program that performs the first alignment steps
       for stitching together tomograms that overlap laterally, which are
       referred to as a supermontage.  See the Setupstitch man page for an
       overview of the stitching process.  Edgepatches uses the master file
       with information about the tomograms and their overlap regions produced
       by Setupstitch, referred to as a supermontage info file.  It per-
       forms 2D and 3D cross-correlations to determine the shifts between the
       volumes, then correlates local patches between overlapping volumes to
       obtain a set of local displacements in the overlap zones.

       To analyze overlap zones, enter either the -all option to analyze all
       edges, or one or more of the options for specifying a range of X, Y, or
       Z to analyze.  By default, the program will not redo the global cross-
       correlations to find the shifts between pieces, but will redo the local
       patch correlations.  Use the -redo option to force it to redo the
       global correlations, or the -skip option to make it skip any patch cor-
       relations that were already done.

       The patch correlations are run similarly to when aligning dual-axis
       tomograms.  However, the default parameters are based on binned data
       (~2 nm pixel) and should not be relied on in general; patch sizes may
       need to be increased substantially for unbinned data.  Another differ-
       ence is that region models for both the upper and the lower piece are
       applied to determine the limits for patches in an overlap zone.
       Another important difference is in the consequences of having bad vec-
       tors.  With dual-axis tomograms, the vectors are fed directly into
       Findwarp, which has outlier elimination that usually eliminates the
       most aberrant vectors.  The vectors produced here are going to be pro-
       cessed by Stitchalign, which does not do its own outlier elimina-
       tion, so bad displacements will be carried through into the final
       warped volumes.  It is thus crucial to run Fitpatches after running
       this program, and after editing any patches.  Fitpatches will show
       you the results of finding local transformations in Findwarp and
       will store information on residuals and on which vectors are outliers
       into a new patch file.  This information will be used by Stitchalign
       to eliminate some bad vectors.  In general, you should use the informa-
       tion from Fitpatches in order to adjust the parameters used in
       Edgepatches to produce the best vectors possible, and then edit out bad
       vectors manually if necessary.

OPTIONS
       Edgepatches uses the PIP package for input (see the manual page for
       pip).  Options can be specified either as command line arguments
       (with the -) or one per line in a command file (without the -).
       Options can be abbreviated to unique letters; the currently valid
       abbreviations for short names are shown in parentheses.

       -info (-inf) OR -InfoFile      File name
              Name of a supermontage info file in which data about the files
              are stored.  The file must exists.  It will be read in when the
              program starts, and renamed to filename~ before writing a new
              version after various operations.  If this option is not
              entered, the first non-option argument will be taken as the name
              of the info file.

       -all (-a) OR -RunAll
              Analyze overlap zones for all frames.  No analysis will be done
              unless this option or one or more of -xrun, -yrun, or -zrun are
              entered.

       -xrun (-x) OR -XRunStartEnd    Two integers
              Starting and ending frame numbers in X surrounding the overlap
              zones to analyze.

       -yrun (-y) OR -YRunStartEnd    Two integers
              Starting and ending frame numbers in Y surrounding the overlap
              zones to analyze.  For example, to analyze one overlap zone
              between two pieces adjacent in X, enter the two frame numbers in
              X for -xrun and the Y frame number for -yrun, such as "-xrun 2,3
              -yrun 2,2".

       -zrun (-z) OR -ZRunStartEnd    Two integers
              Starting and ending Z value for overlap zones to analyze

       -skip (-sk) OR -SkipDone
              Skip any overlap zones that were already analyzed.  The default
              is to use any shifts that were found previously but to rerun
              patch correlations.

       -redo (-r) OR -RedoShifts
              Recompute the shifts between frames for any that were already
              done.

       -use OR -UseProjXformFile
              Redo the 3D cross-correlations in the center of the overlap
              zones, taking the initial shifts from existing ".projxf" for
              each overlap zone instead of redoing projections and 2D correla-
              tions.  Use this option after fixing the initial shift with
              Midas.  This option implies the "-redo" option.

       -ignore (-ig) OR -IgnoreLastShifts
              Use original overlap values as the basis for the starting shifts
              when redoing 2D correlations.  By default, the program uses the
              current shift from the info file to determine what areas to
              project and correlate in an overlap zone, so that one can edit a
              correct value into the file.  Use this option to make it ignore
              previous, incorrect values of the shift, such as if you need to
              rerun the correlations with a different long fraction value.

       -long (-l) OR -LongFraction    Floating point
              Fraction of long dimension of the overlap zone to use for find-
              ing the X/Y shift between the projections of the two pieces.
              The default is 0.5.  When pieces are significantly skewed from
              each other, rather than arranged nearly horizontally or verti-
              cally, this fraction should be made higher, such as 1.0.

       -overlap (-o) OR -OverlapToAssume   Integer
              Number of pixels of overlap to assume when finding initial
              shifts with correlations of 3D projections.  The nominal overlap
              determines how wide an area is projected for correlating; this
              entry overrides the overlap entered with Setupstitch.

       -size (-si) OR -PatchSizeXYZ   Three integers
              Size in X, Y, and Z of patches to correlate.  The default is 100
              x 100 x 50.

       -intervals (-int) OR -IntervalsShortLongZ     Three integers
              Interval between patches in the short, long, and Z dimensions of
              overlap zones.  The program will use these intervals to deter-
              mine how many patches to specify when running Corrsearch3d.
              The defaults are 80,120,50.

       -force (-f) OR -ForceNumberInZ      Integer
              Set the number of patches in Z to the given value, regardless of
              the interval between them.

       -borders (-b) OR -BordersInXYandZ   Two integers
              Borders in X/Y and in Z for region in which to do patch correla-
              tions.  These borders are distances from the edge of each image
              file, and thus define borders in the overlap zone.  The border
              is X and Y is redundant to limiting the region with a patch
              region model.  The border in Z is a default value that will be
              overriden by a Zlimits entry for an individual piece.  The
              default is 50,10.

       -kernel (-k) OR -KernelSigma   Floating point
              Sigma for real-space smoothing with 3D Gaussian kernel (in pix-
              els).  Patches will be smoothed before correlating with 3x3x3
              kernel (for sigma < 1.5) or a 5x5x5 kernel (sigma not < 1.5)
              whose coefficients are proportional to a Gaussian with the given
              sigma centered on the central pixel.

       -test (-t) OR -TestMode   Integer
              Sum of 1 for verbose output and 2 to leave temporary files

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

       -StandardInput
              Read parameter entries from standard input


   Dealing with Bad Initial Shifts
       There are several signs that the program has failed to find the correct
       initial shift between two volumes.  Although the most noticeable sign
       is that the patch vectors look terrible, the first indicator of such
       trouble is with output like this from the 3D correlation of subvolumes:

         Correlating subvolumes to find 3D shift
         Shift from correlation: 28.21, -17.78, 11.99    Total shift ...
         Computing patch correlations in edge test_x1y1-2z1
         Number of patches in X, Y, and Z: 61 31 5
          64.47 correlations per position, Fourier correlations computed  131
       times

       First, the X and Y shifts from this correlation should generally be
       much closer to 0 since an initial X and Y shift was already determined
       from projections, so the large values (28.21 and -17.78) indicate that
       the volumes do not really correspond.  Second, in the patch correla-
       tions, the large number of positions tested at each patch (64) and the
       large number of times that it resorts to global Fourier correlations
       (131) indicate that it is probably correlating patches that do not cor-
       respond.  When the initial 2D shift was correct, this data set gave:

         Shift from correlation: 2.56, -1.87, -9.24    Total shift ...
         Computing patch correlations in edge test_x1y1-2z1
         Number of patches in X, Y, and Z: 67 59 5
          31.45 correlations per position, Fourier correlations computed    2
       times

       The X and Y shifts are now much lower, and only 31 correlations needed
       to be evaluated at each patch position (a minimum of 27 is required).

       When there is evidence that the 2D correlation has failed for an edge,
       the first step is to examine the shift that was produced using
       Midas.  For each edge, files are produced with extensions ".projst"
       and ".projxf", containing the two projection images and the shift
       transformation, respectively.  Run:
          midas edgename.projst edgename.projxf

       There are several scenarios:

       1) The pieces are skewed and the projections do not overlap enough
       along the long dimension of the edge.  Rerun the affected edges with a
       command that includes "-redo -long 1.0 -ignore".

       2) The actual overlap zone is much wider than the nominal overlap used
       in Setupstitch, and the correlation failed because of insufficient
       overlap in the projections when they are lined up.  There are several
       options here: a) Rerun the affected edge with more overlap, using
       "-redo -over nnn -ignore", where "nnn" is an estimated overlap for the
       affected edge.  b) If many edges have this problem, you could start
       over with Setupstitch and a larger overlap.  c) If there is enough
       overlapping material in the two projections, you can adjust the shift
       in Midas until they line up, save the transform, and rerun with
       "-redo -use"

       3) The correlation failed and is unlikely ever to work, such as if the
       actual overlap is much less than the nominal one.  Here is there no
       choice but to adjust the shift in Midas and rerun with "-redo -use".

       Finally, note that existing "shift" entries in the Edge sections of the
       info file determine several things: the location and size of areas pro-
       jected for the 2D correlation; the location of the subvolumes for ini-
       tial 3D correlation; and the location where patch correlation starts.
       This means that if the shift is wrong, you need to include the
       "-ignore" option to make it use the original, nominal shifts instead.
       It also means that, if necessary, you can insert the correct shift in
       the file to bypass the initial correlations.  To do this, find an
       exactly corresponding feature in the two volumes in question and record
       its X, Y, Z coordinates in each volume.  Subtract the coordinates in
       the lower volume (the one to the left in X or below in Y) from the
       coordinates in the upper volume and insert the result into the shift
       entry.


FILES
       When the info file is modified, the existing copy is renamed to a
       backup with the ~ extension.  This is done only once per run of the
       program, although the program will save the info file after each over-
       lap zone is processed.

AUTHOR
       David Mastronarde

SEE ALSO
       corrsearch3d, xyzproj, tiltxcorr, setupstitch, fit-
       patches(1), stitchalign, tomostitch, midas

BUGS
       Standard comments in the info file, starting with #, will not be pre-
       served.  However, key-value pairs like
         comment1 = This is a difficult edge
       will be retained in the same section where they occur.

       Email bug reports to mast at colorado dot edu.

HISTORY
       Edgepatches originally included all the operations now performed by
       Setupstitch.



IMOD                                4.12.61                     edgepatches(1)