stitchalign(1) General Commands Manual 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.
IMOD 5.2.0 stitchalign(1)