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
determine 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.5.6 edgepatches(1)