edgepatches(1)                                                  edgepatches(1)



NAME
       edgepatches - Initial steps in stitching montage of overlapping tomo-
       grams

SYNOPSIS
       edgepatches options supermontage_info_file

DESCRIPTION
       Edgepatches is a Python program that performs the first steps in
       stitching together tomograms that overlap laterally, which are referred
       to as a supermontage.  Stitching is done by running four different pro-
       grams in sequence: Edgepatches, Fitpatches, Stitchalign, and
       Tomostitch.  Edgepatches allows you to set up a master file with
       information about the tomograms and their overlap regions, referred to
       as a supermontage info file.  It performs 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 displace-
       ments in the overlap zones.  Next, you run Fitpatches to assess the
       quality of the patch displacements by seeing how well local transforma-
       tions fit to them.  Fitpatches also generates patch vector models
       that you can edit to improve these fits and to prevent aberrant vectors
       from subsequently giving bad warping transformations.  The next step is
       to run Stitchalign to take this information and determine how the
       volumes can be transformed into alignment.  That program first derives
       an overall linear transformation (including shifts, rotations, size
       changes, and stretches as appropriate) to apply to each volume, and it
       also produces a set of vectors for each volume indicating how that vol-
       ume needs to be warped to match up with adjacent ones where they over-
       lap.  Finally, you run Tomostitch to perform a series of tasks for
       building the stitched volume: 1) Deriving warping transformations from
       the warping vector fields; 2) Applying these warping transformations to
       each volume; 3) Adjusting densities of the volumes so that they match
       where they overlap; 4) Stacking the volumes so that they represent a
       montage readable by Blendmont; 5) Running Blendmont to blend the
       2D montaged images into one.

       Edgepatches can set up the info file when given the right information.
       For complex situations, you will probably want to name your volumes
       following one of the conventions supported by this program and let the
       program do this initial setup.  For simple situations, you have the
       option of starting the info file yourself with a text editor.  In any
       case, there are some situations that require manually inserting infor-
       mation about individual volumes into the info file.

       The info file is in the BL3DEMC autodoc format, which consists of sec-
       tions of defined types, each containing information as key-value pairs.
       In the abstract, this looks like:
       [section_type = name]
       key1 = value1
       key2 = value2

       The defined kinds of sections (not to be confused with the physical
       slices that were reconstructed) are:
       Section       Information about a slice as a whole; the name value
                     is the name of the physical slice; the default is
                     "rootname_Zvalue" if the slices have a defined Z value,
                     or just "rootname" if not.
       Piece         Information about a volume; the name value is the name
                     of the reconstruction file.
       Edge          Information about an overlap zone between two volumes.
                     The name value is a standard name based on the rootname
                     and the options that have been entered, such as
                     set1_x1-2y1 for an edge between piece 1,1 and piece 2,1

       The standard names for pieces and edges are determined from the root-
       name and the entries for three options: -ext, -underscore and -noz.
       The -ext option simply specifies an extension for the tomograms; the
       default is ".rec".  With the default extension, the names are:
         Options         Piece name                Edge name
                         rootname_x1y1z1.rec       rootname_x1-2y1z1
       -noz              rootname_x1y1.rec         rootname_x1-2y1
       -underscore       rootname_x1_y1_z1.rec     rootname_x1-2_y1_z1
       -noz -underscore  rootname_x1_y1.rec        rootname_x1-2_y1
       where in each case the piece names are for piece 1,1 and the edge names
       are for the edge between piece 1,1 and piece 2,1.  The expected names
       for specific patch region models would be the piece name with
       "_region.mod" instead of ".rec".

       To have the program set up the info file, decide on one of these naming
       conventions and have the volumes named appropriately.  Your choice will
       depend on whether you have multiple sections, and whether you want the
       section number to be represented by a Z at the end or as part of the
       rootname.  Then run Edgepatches with entries for -root, -xyadd (the
       number of frames in X and Y), -overlap (the expected overlap between
       frames in X and Y), and either -zadd (if you are doing multiple sec-
       tions with the above naming convention) or -noz (to indicate there are
       no Z values in the names).  The other option to specify at this time is
       -model (a default patch region model that is used if no specific model
       is found for a piece.)  When you run the program will all of these
       options, it will search for the piece volumes as well as patch region
       models under the names implied by your options.  Thus, if individual
       volumes need region models to constrain the area used for patch corre-
       lations, you should make them before running the program.

       To set up an info file yourself, you need to make a section for each
       piece with one or two entries:
         [Piece = left.rec]
         Frame = 1 1 0
         Model = left_region.mod

       Here the frame entry specifies the frame number in X, Y, and Z; you can
       leave out the Z value if you want.  If you need to use a region model,
       specify it as shown.  With a section already in place for each piece,
       you can then run the program with -root, -overlap, your choice of -noz
       and -underscore to govern the naming of edge-related files, and a
       -model entry for a default region model.

       Regardless of whether you add the supermontage using the program or
       specify pieces by hand, the first run of the program will add sections
       for all the edges and other data to the info file.  You can do the full
       analysis on this first run, or you can defer the analysis if you need
       to adjust entries in the info file.  There are two items that you may
       need to edit in by hand after creating an info file.  One would be a
       region model, specified in the section for a piece with
          Model = piecename_region.mod
       where the name can be whatever you want if you are inserting this your-
       self.  The second item would be lower and upper limits for the Z range
       from which patches can be taken for correlation.  These limits can be
       entered in the section for a piece, in which case they will be used
       when that piece is the lower one in a pair, or in the section for an
       edge, in which case the limits will apply only for that overlap zone.
       The entry is
          Zlimits = zlo zhi
       where zlo and zhi are the limits, numbered from 1.  For a particular
       edge, the Z limits are taken first from an entry for that edge if that
       exists; then from an entry for the lower piece if that exists; then
       from the Z border entered with the -borders option if neither exists.

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

       -info OR -InfoFile   File name
              Name of a supermontage info file in which all data about the
              files will be stored.  If the file exists, it will be read in
              when the program starts, and renamed to filename~ before writing
              a new version when the program exits.  If this option is not
              entered, the first non-option argument will be taken as the name
              of the info file.

       -noz OR -NoZValues
              Search for and create names without Z values and assume the Z
              value is zero.  This option cannot be used when adding a super-
              montage to an existing one, or when specifying a z range with
              -zadd.

       -root OR -RootName   Text string
              Rootname for existing files and ones to be created.  Existing
              files need not be named according to the conventions if they are
              already listed in the info file.

       -overlap OR -OverlapInXandY    Two integers
              Nominal overlap between adjacent volumes in X and Y.  This only
              needs to be a rough approximation.  This entry is required when
              adding a supermontage or the first time a manually prepared info
              file is read.

       -underscore OR -UnderscoreXYZ
              Use underscores between x, y, and z in composing names for files
              being searched for and created.

       -ext OR -ExtensionOnVolumes    Text string
              Extension on filenames when searching for volumes, including the
              period.  There may be characters before the true extension, such
              as if all files are named "binned.rec".  The default is .rec.

       -xyadd OR -AddMontageXandY     Two integers
              Add a supermontage with the given number of frames in X and Y.
              The program will search for pieces by rootname and frame number
              in X and Y, with numbers starting from 1.

       -xadd OR -AddMontageXRange     Two integers
              Starting and ending X values to search for when adding a super-
              montage.  Use this option and -yadd if the starting frame number
              is not 1 in X or in Y.  If one of the two options -xadd and
              -yadd is entered, then the other must be entered as well, and
              -xyadd must not be entered.

       -yadd OR -AddMontageYRange     Two integers
              Starting and ending Y values to search for when adding a super-
              montage.

       -zadd OR -AddMontageZRange     Two integers
              Starting and ending Z values to search for when adding a super-
              montage.  If this option is entered, then either -xyadd, or
              -xadd and -yadd, must be entered.

       -model OR -DefaultRegionModel       File name
              Patch region model to use for an overlap zone if one is not
              found when initially setting up the Edge entries in the info
              file.  This option will have an effect only when adding a super-
              montage or processing a manually prepared info file for the
              first time.

       -all 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 OR -XRunStartEnd    Two integers
              Starting and ending frame number in X for overlap zones to ana-
              lyze

       -yrun OR -YRunStartEnd    Two integers
              Starting and ending frame number in Y for overlap zones to ana-
              lyze

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

       -skip 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 OR -RedoShifts
              Recompute the shifts between frames for any that were already
              done.

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

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

       -intervals 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 OR -ForceNumberInZ      Integer
              Set the number of patches in Z to the given value, regardless of
              the interval between them.

       -borders 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 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 OR -TestMode   Integer
              Sum of 1 for verbose output and 2 to leave temporary files

       -StandardInput
              Read parameter entries from standard input


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, fitpatches,
       stitchalign, tomostitch

BUGS
       Comments in the info file will not be preserved.

       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.3.7                      edgepatches(1)