stitchalign(1)                                                  stitchalign(1)



NAME
       stitchalign - compute alignment for stitching montage of overlapping
       volumes

SYNOPSIS
       stitchalign  [options]  supermontage_info_file

DESCRIPTION
       Stitchalign computes an alignment between a montage of overlapping
       tomograms (referred to as a supermontage) so that they can be stitched
       into a single volume.  It does this using information about the local
       displacements in the overlap zones between each pair of adjacent vol-
       umes, i.e., the patch vectors produced by Corrsearch3d.  It also
       uses values for the overall displacements between the volumes computed
       by Edgepatches and stored in the supermontage info file.

       The first step is to compute a single rotation in the X/Y plane, and
       overall shifts of the volumes, that would bring their centers onto a
       regular rectangular grid.  This rotation can compensate for the effects
       of the tilt axis not being perpendicular in the original images.
       Specifically, if the data were acquired on a regular grid of positions
       in the camera coordinate system, the reconstructions end up being stag-
       gered from one another by the rotation of the tilt axis to the verti-
       cal, and this rotation will correct for the staggering.  If the value
       found is not appropriate, there is an option to supply a specific value
       instead.  In addition, if the angle between the pieces is not related
       to this tilt axis effect, you might want to prevent rotation entirely.

       The next step is to compute a set of single transformations, one per
       volume, that best aligns the volumes.  The parameters available for
       alignment are rotation about the three axes (referred to as alpha,
       beta, and gamma), an overall size change (referred to as magnifica-
       tion), stretch along one axis in the X/Y plane (expressed as stretch of
       the Y axis relative to the X axis and rotation of the Y axis relative
       to the X axis), and a thinning factor in the Z dimension.  Any subset
       of the parameters can be selected; the rotations are included by
       default and there is one option to exclude one or more of them; there
       are three separate options for including the magnification, stretch,
       and thinning.  The parameters are found using the same variable metric
       minimization routine used by Tiltalign.  The program can do a single
       search that includes the parameters for all volumes at once, but this
       turns out not to work, apparently because of multiple minima produced
       by competing alignments between different pairs of valumes.  Thus, the
       program will do a separate search for each pair of overlapping volumes,
       then resolve the relative alignment parameters between pairs of volumes
       into a set of parameters for the individual volumes.

       These single transformations may leave substantial misalignments in the
       overlap zones.  The final step uses the remaining local displacements
       in the overlap zones to compute the amount that each volume needs to be
       displaced locally to bring it into alignment with an adjacent volume
       (which is also being displaced locally).  The result is a set of patch
       vectors for each volume, which Findwarp can use to find a series of
       transformations for warping each volume into the final alignment.  By
       default, these vectors are produced on a finer grid than the original
       patch vectors for the overlap zones.  This oversampling may not be nec-
       essary if the original vectors are relatively finely spaced; it can be
       controlled by the -spacing option.  Tomostitch takes this spacing
       factor into account when running Findwarp so that the local fits
       will require about the same amount of original data as if the spacing
       were unchanged.

       Within this program, there is no local fitting to patch vectors in
       order to determine the quality of fit and to identify aberrant dis-
       placements.  Bad vectors in the input files will generally produce bad
       warping vectors that are hard to eliminate.  It is thus critical to get
       as reliable a set of patch vectors from Edgepatches as possible, to
       use Fitpatches to assess the quality of fit and provide local fit-
       ting information for Stitchalign, and to manually remove aberrant vec-
       tors from patch models where necessary.  Stitchalign will use the out-
       put from Fitpatches in several ways.  It will read all available
       patch vector files for an overlap zone: the original patch vectors, the
       "reduced" patch vectors with correlation coefficients produced by
       removing the large linear component from the patch vectors, and the
       patch vectors that have been passed through Findwarp to obtain
       residual and outlier information.  A vector will be eliminated from the
       analysis if it is not still present in all available patch files; thus,
       you can edit whichever patch model you prefer.  A vector will be elimi-
       nated if the fraction of times it has been removed from Findwarp
       fits as an outlier exceeds a criterion.  Vectors with high residuals
       can also be eliminated based on a criterion, but this does not happen
       by default because it is hard to set a default criterion.

       You can run the alignment on subsets of the data either for experimen-
       tation or if that subset is going to be stitched.  Ultimately, all of
       the volumes to be stitched must be included in one run of the program -
       it is not possible to run one subset with one set of parameters and
       another subset with other parameters then combine those results into a
       single alignment.

       The size of the volumes to be stitched together by Tomostitch is set
       when Stitchalign is run.  The default is the largest size of the input
       volumes, but it can be controlled with the -size parameter.  If over-
       sized tomograms were generated to retain data that would otherwise be
       lost because of the tilt axis rotation, then this is the point at which
       a size close to that of the original data can be specified.

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


       -info (-i) OR -InfoFile   File name
              Name of autodoc-type file with information about the supermon-
              tage.  If this option is not entered, the first non-option argu-
              ment will be taken as the name of the info file.

       -zvalues (-z) OR -ZvaluesToDo       List of integer ranges
              List of Z values at which to run the analysis (comma-separated
              ranges allowed).  The default is to do all Z values.

       -rotation (-ro) OR -RotationInXYplane    Floating point
              Angle to rotate all volumes in the X/Y plane.  If this option is
              not entered, the program will find the angle that brings the
              centers of the aligned volumes onto a rectangular grid.  Enter
              an angle or zero to override this behavior.

       -size (-si) OR -SizeOfOutputFramesXandY       Two integers
              Size in X and Y of transformed files to be created by Matchvol
              or Warpvol.  The default is the size of the largest input vol-
              ume.

       -mag (-ma) OR -FindMagnification
              Find overall magnification factors

       -stretch (-st) OR -FindStretch
              Find in-plane stretch parameters, which are expressed as size
              change and rotation of the Y axis relative to the X axis.

       -thinning (-t) OR -FindThinning
              Find thinning factors, factors by which to change the thickness
              of the volumes.

       -angles (-an) OR -FindAngles   Three integers
              Values or 1 or 0 indicating whether to find rotations around X,
              Y, and Z, respectively.  The default is 1,1,1, so this option
              would be used to turn off solutions for some angles.

       -metro (-me) OR -MetroFactor   Floating point
              Initial step size or "metro factor" in the minimization proce-
              dure; the default is 0.24.  Vary this value slightly if a mini-
              mization fails.

       -xrun (-x) OR -XRunStartEnd    Two integers
              Starting and ending volumes in X to analyze, numbered from 1.
              The default is to do all volumes in X.

       -yrun (-y) OR -YRunStartEnd    Two integers
              Starting and ending volumes in Y to analyze, numbered from 1.
              The default is to do all volumes in Y.

       -residual (-re) OR -WarpFitResidualCriterion       Floating point
              Criterion residual from fits in Findwarp for excluding vec-
              tors; vectors with mean residual greater than or equal this to
              value will be excluded.  The default value of 100 will generally
              not exclude any vectors.  Use Fitpatches to produce an appro-
              priate patch file with residuals.

       -outlier (-o) OR -OutlierFractionCriterion    Floating point
              Criterion fraction of times that a vector was excluded as an
              outlier from fits in Findwarp; vectors with an outlier frac-
              tion greater than or equal this to value will be excluded here.
              The default is 0.33.  Use Fitpatches to produce an appropri-
              ate patch file with outlier fractions.

       -spacing (-sp) OR -VectorSpacingFactor   Floating point
              This factor makes the spacing of the vectors put out in the
              warping fields for each volume be less than the spacing of the
              patch vectors measured in the overlap zones.  The default is
              0.7, which makes the density of warping vectors be about three
              times higher than the density of the patch vectors.

       -all (-al) OR -AllTogether
              Analyze all volumes in a single minimization procedure.  The
              default is to get a solution for each pair of overlapping vol-
              umes and resolve the results into a single solution.  When
              parameters are searched for all volumes together, the results
              are poor, probably due to multiple minima.

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

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

       -StandardInput
              Read parameter entries from standard input.

   FILES
       Stitchalign produces two files for each volume included in the analy-
       sis:
         piecename.matxf    File with single linear transformation
         piecename.patch    File with patch vectors for computing a warping
       It also produces a file "sectionmame.ecdstub" with the displacements
       between pieces needed when blending.

HISTORY
       Written by David Mastronarde, April 2007

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                      stitchalign(1)