tomostitch(1) General Commands Manual tomostitch(1)
NAME
tomostitch - Warps, stacks, and blends a montage of overlapping volumes
SYNOPSIS
tomostitch options supermontage_info_file
DESCRIPTION
Tomostitch is a Python program for performing the final steps in
stitching together adjacent, overlapping volumes. These steps are: 1)
running Findwarp on the warping patch vectors produced by
Stitchalign; 2) running Warpvol to produce the aligned volumes;
3) running Densmatch to match their densities and Newstack to
stack them into a single file; and 4) running Blendmont to produce
the final stitched volume. By default, the program will run all of
these steps, but there are options to run just a subset of consecutive
steps.
There are options for running with a subset of the volumes. These
options can be used either for experimenting or for building a subset
of the stitched reconstruction. They apply to all of the steps except
blending, since whichever volumes have been stacked are the ones that
will be blended. It may be useful to run the first step alone, inter-
actively, since it might fail on some volumes and require editing of
patch vectors or adjustment of parameters. If necessary, the step can
then be rerun just on the volumes that failed. The other steps might
be better run from a command file so that output can be collected in a
log.
The size of the warped volumes in X and Y was set when Stitchalign
was run and cannot be adjusted in this program. The thickness can be
specified.
The density scaling is a point where problems may occur with byte data.
The program will use Densmatch to find the scaling that will match
up the densities within a strip in the overlap zone between each pair
of adjacent volumes. These relative scalings are then resolved into
scalings to apply to each of the volumes to minimize the density dis-
parities in all of the overlap zones. One of the volumes is always set
as a refernce that will not be scaled (piece 1, 1 by default). The
final scalings are printed out before the program starts to stack the
volumes while applying these scalings. If some volumes are multiplied
by a factor much more than 1, then there is a danger that image data of
interest will be truncated at 0 or 255. If a factor is much less than
1, then there is a danger of that piece having its intensities com-
pressed into too little dynamic range, although this might be a more
difficult problem to notice. In some cases, you might want to select a
new reference volume to reduce the amount that volumes are scaled over-
all. For example, if most scale factors are between 0.8 and 1.0,
select one with a factor of 0.9 as the reference to makes the scalings
overall be closer to 1.0. To do this, kill the stacking operation (use
Ctrl C at the command line) and rerun it with the new reference.
Artifacts in the blended volume can be minimized by setting a limit for
the slices from which edge functions will be computed. Edge functions
computed from areas outside the section are prone to errors which dif-
fer radically from slice to slice, making the remaining image features
jump around when paging through the slices. The solution is to use the
edge functions computed on the last good slice for slices outside the
range of good slices. A lower and upper limit on the slices with good
edge functions can be set with the -goodedge option. Using a single
limit for all edges may not be appropriate, so limits can also be set
for individual edges. If -goodedge is entered, its limits apply to all
edges that do not have individual limits. Limits can be specified for
individual edges in two ways. One is with the -onegood option, where
one must specify the number in X and Y of the frame below or to the
left of the edge, and whether the edge is between two pieces adjacent
in X or adjacent in Y. The other way is to make an entry in the info
file in the section for the particular edge, of the form:
goodLimits = # #
where the two numbers are the lower and upper Z limits. Note that in
either of these cases, the slices are numbered from 1 and can be read
directly out of 3dmod. Once you have defined these limits, you can
rerun the blend operation, specifying -oldedge to avoid recomputing
edge functions.
Another kind of artifact can occur in the overlap zones when the trans-
formed volumes contain significant areas filled with a uniform value
due to large shifts. To handle this problem, an option is supplied to
Blendmont to exclude these areas from edge functions and from being
used when blending across edges.
This program outputs a command file for the blending operation that
could be used to run Blendmont with different parameters not acces-
sible through this interface. The file is named blend_sec-
tion_name.com.
Tomostitch provides options so that you can work initially with binned
volumes then apply the results to stitch unbinned volumes. There are
two different ways that you can use this capability. One way is to do
all the alignment through the Findwarp step of Tomostitch with binned
volumes. At that point you would substitute the unbinned volumes for
the binned ones, then carry on in Tomostitch with warping, etc., using
the "-scale" option to specify the change in scale. Any size parame-
ters (such as thickness) would then be given in unbinned pixels. The
other way is to complete the stitching, including the setting of good
edge limits if desired to avoid artifacts beyond the bounds of the sec-
tion. Then either substitute the unbinned volumes for the binned ones,
or copy the info file and all the ".warpxf" to a directory where the
unbinned volumes are. Then run Tomostitch with all the same parameters
as before, using both "-scale" and "-apply" so that the program will
scale all size and position related entries to fit the unbinned data.
OPTIONS
Tomostitch 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 containing all the data about
the frames and sections. If this option is not entered, the
first non-option argument will be taken as the name of the info
file.
-xrun (-xr) OR -XRunStartEnd Two integers
Starting and ending frame number in X to include in operations.
The default is to include all frames in X.
-yrun (-yr) OR -YRunStartEnd Two integers
Starting and ending frame number in Y to include in operations.
The default is to include all frames in Y.
-zrun (-z) OR -ZRun Integer
Z value to perform operations on. This entry is not needed if
there is only one section described in the info file.
-thickness (-th) OR -ThicknessToOutput Integer
Thickness to make output volume. All frames will be transformed
to this thickness. The default is the largest thickness of any
input volume.
-find (-f) OR -FindWarping
Run Findwarp on the warping vector fields from
Stitchalign. The default is to do all operations if no indi-
vidual operations are selected by -find, -warp, -stack, or
-blend, but run only the specified operations if any of these
options are entered.
-warp (-wa) OR -WarpVolumes
Run Warpvol on the pieces
-stack (-st) OR -StackVolumes
Run Densmatch and Newstack on the pieces and produce piece list
-blend (-bl) OR -BlendVolumes
Run Blendmont on warped and stacked pieces
-scale (-sc) OR -SizeScalingFactor Floating point
Scaling factor between the volumes that were analyzed to deter-
mine alignment and analysis, and the volumes that are now being
operated on. For example, if you initially found warping for a
set of volumes that were binned by two, and have now substituted
unbinned volumes in order to stitch them, you would enter a fac-
tor of 2.
-apply (-a) OR -ApplyScaleToEntries
Apply the scale factor to all entries specifying a size or loca-
tion for warping, density matching, stacking, and blending. For
example, if you complete the stitching of binned volumes,
including adjusting the output thickness and setting lower and
upper Z limits for edges in Blendmont, then you can use this
option to rerun Tomostitch on the unbinned volumes with the same
entries of all parameters. Without this option, you would have
to adjust any entries by the scaling factor manually.
-verbose (-v) OR -VerboseOutput Integer
Level of verbose output: 1 for command lines and some output in
density matching, 2 for output of all iterations in density
matching
Options for Running Findwarp or Warpvol
-target (-ta) OR -TargetMeanResidual Multiple floats
One or more mean residual values to try to reach when Find-
warp(1) searches for the best warping. Multiple values should
be entered in increasing order. Findwarp will try to find a
warping with the largest number of included patches that gives a
mean residual below the first value; then it tries again with
the second value, etc.
-measured (-me) OR -MeasuredRatioMinAndMax Two floats
The minimum and maximum ratio of measurements to unknowns to be
allowed in the fits in Findwarp. The defaults are 4 and 12,
divided by the cube of the vector spacing factor used when run-
ning Stitchalign. The actual value used will be reported by
the program.
-discount (-di) OR -DiscountIfZeroVectors Floating point
This option is supplied to Findwarp with a default value of
0.5 to prevent misleading averages when analyzing the warping
fields, which contain mostly zero vectors. Fits with the number
of zero vectors bigger than the given fraction of the total vec-
tors will be excluded from the averages.
-tempdir (-te) OR -TemporaryDirectory Text string
Directory to use for temporary files when runnning Warpvol.
The default is that the temporary files will be placed in the
current directory.
Options for Density Matching when Stacking
-density (-de) OR -DensityReferenceFrame Two integers
Frame number in X and Y (numbered from one) of the volume to
serve as reference for density matching. The default is to use
the first one. (Successive entries accumulate)
-match (-ma) OR -MatchingWidthXandY Two integers
Width of overlap zone in X and Y to use to determine the scaling
for density matching. The program will run Densmatch on the
overlap zones to find a relative scaling between each pair of
overlapping volumes, then resolve these scalings into a single
scaling for each volume. The default is to use the central 30%
of the width of the overlap zone. Enter a width of 0,0 to use
the original kind of density matching, which is a scaling based
on matching the density in the interior of each volume to that
of the reference volume.
-length (-l) OR -MatchingLengthXandY Two integers
Length of overlap zone in X and Y to use to determine the scal-
ing for density matching. The default is to use the central 70%
of the length of an overlap zone; smaller values might be needed
if pieces are severely skewed and have gray area along a large
fraction of the length of the overlap zones. The X and Y
lengths are used for the overlaps between pieces in Y and X,
respectively. Enter 0 for one of the values to use the default.
Options for Running Blendmont
-xminmax (-xm) OR -StartingAndEndingX Two integers
Minimum and maximum X index coordinates to output in Blend-
mont(1) (numbered from 0). The default is to output the entire
image.
-yminmax (-ym) OR -StartingAndEndingY Two integers
Minimum and maximum Y index coordinates to output in Blendmont.
-bin (-bi) OR -BinByFactor Integer
Use binning to reduce blended images in size by the given fac-
tor. Binning is applied to the data just before output, so the
starting and ending X and Y coordinates to output should be
specified in unbinned pixels.
-oldedge (-ol) OR -OldEdgeFunctions
Use existing edge functions, if they exist, rather than comput-
ing new ones in Blendmont.
-goodedge (-g) OR -GoodEdgeLowAndHighZ Two integers
Default lower and upper Z limits for where edge functions in
Blendmont are good. Beyond these limits, the edge functions
will be taken from the last good Z value. If this option is
entered, these limits will applied to all edges except ones that
have Z limit entries in the info file. Unlike in Blendmont,
these Z values are numbered from 1 for convenience.
-onegood (-on) OR -OneGoodEdgeLimits Multiple integers
This options specifies lower and upper Z limits for a specific
edge; beyond these limits the edge functions will be taken from
the last good Z value. Five values are expected: number of
frame below the edge in X and Y, 1 for an edge in X or 2 for an
edge in Y, lower and upper Z limits. Note that the frame num-
bers are the fixed numbers in the supermontage (numbered from
1), not the frame numbers within the blend, which might be lower
if a subset of frames is being blended. Also note that unlike
in Blendmont, the Z values are numbered from 1. (Successive
entries accumulate)
-exclude (-e) OR -ExcludeFillFromEdges
With option, Blendmont will detect image areas near an over-
lap zone that consist of uniform values and exclude these areas
when computing the edge function. In addition, in areas along
an edge where one piece consists of uniform values and the other
has actual image data, it will use the actual data across the
whole edge instead of transitioning to the uniform data. This
option is helpful when stitching a pair of volumes that do not
line up well vertically or horizontally, but it can produce
artifacts with supermontages that are laid out more regularly.
-width (-wi) OR -BlendingWidthXandY Two integers
Width in X and Y across which to blend overlaps in Blendmont.
The default is:
80% of the overlap zone width for overlap width less than 63,
50 pixels for overlap width between 63 and 100, or
50% of the overlap width for overlap width greater than 100.
You will probably need to set a width smaller than the default
if you made extra-large tomograms to avoid losing good regions
from the rotation of the tilt axis to vertical, and you did not
trim the size back in the warped volumes that are being blended.
-boxsize (-bo) OR -BoxSizeShortAndLong Two integers
Size of box for finding edge functions in short and long direc-
tions in Blendmont. The short direction is across an overlap
zone, the long direction is along it. The default size is 10
pixels in the short direction for frame sizes up to 1024 pixels,
increasing proportional to the maximum dimension of the frame
above 1024. The default in the long direction is 1.5 times the
size in the short direction.
-indents (-ind) OR -IndentShortAndLong Two integers
Borders at the edge of the overlap zone in the short and long
directions which will be excluded when finding edge functions in
Blendmont. If your data were taken as a supermontage aligned
to specimen rather than camera axes, it may be helpful to set an
indent in the long direction that will keep the program from
analyzing images in regions where there is good data in only one
of the two overlapping volumes. The default size is 5 pixels in
each direction for frame sizes up to 1024 pixels, increasing
proportional to the maximum dimension of the frame above 1024.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
FILES
When Findwarp is run, several files are produced for each piece:
piecename.warpxf has the warping transforms
piecename_res.patch is a file with the patch vectors and residuals
piecename_res.mod is made from these patches with patch2imod -s 5
To edit the patches, edit "piecename_res.mod". When you run Tomostitch
again, it will detect that it has been edited and replace the original
patch file by running
imod2patch piecename_res.mod piecename.patch
When Warpvol is run, it produces files named "piecename.warped".
When the warped volumes are stacked, the output files are
section_name.st the stacked volumes
section_name.pl the piece list
The output file from blending is "section_name.bl"
AUTHOR
David Mastronarde
SEE ALSO
findwarp, warpvol, newstack, densmatch, blendmont,
stitchalign
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.11.0 tomostitch(1)