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 5.2.0 edgepatches(1)