Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

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 volumes, 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 staggered from one another by the
  rotation of the tilt axis to the vertical, 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 magnification), 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 necessary 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 displacements.  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 fitting information for
  Stitchalign, and to manually remove aberrant vectors from patch models where
  necessary.  Stitchalign will use the output 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 eliminated
  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 experimentation
  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 oversized 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.

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

 -info OR -InfoFile   File name
    Name of autodoc-type file with information about the supermontage.  If
    this option is not entered, the first non-option argument will be taken as
    the name of the info file.

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

 -mag OR -FindMagnification
    Find overall magnification factors

 -stretch 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 OR -FindThinning
    Find thinning factors, factors by which to change the thickness of the
    volumes.

 -angles 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 OR -MetroFactor   Floating point
    Initial step size or "metro factor" in the minimization procedure; the
    default is 0.24.  Vary this value slightly if a minimization fails.

 -xrun 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 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 OR -WarpFitResidualCriterion   Floating point
    Criterion residual from fits in Findwarp for excluding vectors; 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 appropriate patch file with residuals.

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

 -spacing 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 OR -AllTogether
    Analyze all volumes in a single minimization procedure.  The default is to
    get a solution for each pair of overlapping volumes 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 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.

FILES
  Stitchalign produces two files for each volume included in the analysis:
    piecename.matxf    File with single linear transformation
    piecename.patch    File with patch vectors for computing a warping

HISTORY
  Written by David Mastronarde, April 2007