filltomo(1) General Commands Manual filltomo(1)
NAME
filltomo - Replace pixels in dual-axis tomogram with values from one
SYNOPSIS
filltomo [options] matched_to_tomogram tomogram_to_fill
DESCRIPTION
Filltomo improves a combined tomogram from a two-axis tilt series by
replacing pixels in locations where the "matching" tomogram had no data
with the values from the tomogram that was matched to. It determines a
linear scaling between the latter tomogram and the combined tomogram so
that the intensities will match as well as possible. It can also be
applied to fill the tomogram from the axis that is transformed to
match, prior to combining.
Three files need to be considered to understand how the program works:
1) The tomogram from the axis being matched to, which is the source for
replacement pixels; 2) the tomogram from the other axis, which needed
to be transformed into alignment with the first one; 3) the tomogram in
which pixels are being replaced, which is either the transformation of
the second tomogram, or the combination of that transformed tomogram
with the first axis.
The decision of whether to replace a pixel is made in up to four
stages. First, the program determines if the pixel back-transforms to
a location outside the boundaries of the tomogram from the other axis,
in which case it was filled with a mean value during the transforma-
tion. Second, if options are entered to define the region containing
valid data in the tomogram from the other axis, then the program can
also determine if a pixel back-transforms to a location outside that
defined region. Third, if options are entered to define the region
containing valid data in the tomogram being matched to, the program
will refrain from replacing pixels outside those regions. Fourth, if
regions near the edges are specified where the pixels should be
replaced regardless of these other criteria, then pixels in such
regions will be replaced unconditionally.
There are two different ways to define the region containing valid data
in a tomogram. "Valid data" refers to regions where there is a rela-
tively complete set of views providing back-projected data, not just to
regions that have material suitable for correlations. One way is to
create an IMOD model with a contour surrounding the area with valid
data, when viewing the raw tomogram in flipped orientation (perpendicu-
lar to the plane of section). The other way is to provide the size of
the original unaligned image data and the transformations used to align
them. The latter way works only if the tomogram is centered on the
original image data (i.e., the aligned stack was centered on the origi-
nal stack and neither an X nor a Y shift was used in building the tomo-
gram). If a tomogram is not centered, then a boundary model needs to
be used instead.
Specifying the valid data area in the tomogram from the other axis
becomes increasingly important the greater the rotation of the tilt
axis from vertical or horizontal, the bigger the shift between the two
volumes, and the greater the difference between reconstruction and raw
data size. In the context of combining data from two axes, however,
there appears to be no merit in specifying the valid data region in the
tomogram being matched to.
OPTIONS
Filltomo uses the PIP package for input (see the manual page for
pip) but can take input interactively for basic operations, to main-
tain compatibility with old command files. 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.
-matched (-ma) OR -MatchedToTomogram File name
Tomogram that was matched to, typically "...a.rec" when matching
the B to the A axis. This tomogram is the source of pixels used
for replacement. This input file is required. If this option
is not entered, the first non-option argument will be used for
the filename.
-fill (-f) OR -FillTomogram File name
Transformed or combined tomogram to fill with pixels from the
tomogram that was matched to, typically named "...b.mat" (when
matching B to A) or "sum.rec", respectively. This output file
is required. If this option is not entered, the second non-
option argument will be used for the filename. This file must
have the same dimensions as the tomogram that was matched to.
-source (-so) OR -SourceTomogram Text string
Name of tomogram that was transformed to produce a matching
tomogram, typically named "...b.rec" when matching B to A. This
entry is required.
-inverse (-i) OR -InverseTransformFile File name
File with inverse of 3D transform applied to produce matching
tomogram. This file is typically named "inverse.xf" and is pro-
duced when Refinematch is run by Matchorwarp. This entry
is required.
-xfill (-x) OR -LeftRightFill Two integers
Number of pixels to fill regardless on left and right sides of
tomogram
-yfill (-y) OR -BottomTopFill Two integers
Number of pixels to fill regardless on bottom and top sides of
tomogram
-binning (-b) OR -ImagesAreBinned Integer
The binning of the aligned images used to beuild the tomomgrams,
relative to the original data. The default is 1. This entry is
needed if options specifying stack transforms are entered with
unbinned sizes and binning was not 1.
-sraw (-sr) OR -SourceRawStackSize Three integers
Size in X, Y, and Z of the unaligned tilt series used to build
the tomogram that was transformed to match. If images were
binned to make the aligned stack, either enter a binned size
here, or enter an unbinned size and the -binning option. This
entry is required if -sxform is entered.
-sxform (-sx) OR -SourceStackTransforms File name
File of 2D transforms applied to align the tilt series images
used to build the tomogram that was transformed to match. With
this option, the program will replace pixels that come from
regions where there was not complete projection data available
for backprojection.
-sboundary (-sb) OR -SourceBoundaryModel File name
File with model drawn on the tomogram that was transformed to
match, where the boundary contour indicates the region where
data are good, and outside which data should be replaced. This
option cannot be used together with -sxform. If there is more
than one contour, the one closest to the midplane of the tomo-
gram is used.
-mraw (-mr) OR -MatchedToRawStackSize Three integers
Size in X, Y, and Z of the unaligned tilt series used to build
the tomogram that was matched. Enter either a size adjusted for
binning, or the unbinned size along with the -binning option.
This entry is required if -mxform is entered.
-mxform (-mx) OR -MatchedToStackTransforms File name
File of 2D transforms applied to align the tilt series images
used to build the tomogram that was matched to. With this
option, the program will refrain from using replacement pixels
from regions where there was not complete projection data avail-
able for backprojection, unless they are inside edge regions to
be filled regardless (set by -xfill and -yfill options).
-mboundary (-mb) OR -MatchedToBoundaryModel File name
File with model drawn on the tomogram that was matched to, where
the boundary contour indicates the region where data are good,
and outside of which data should be not be used for replacement.
Pixels inside of edge regions set by -xfill and -yfill options
will still be replaced. This option cannot be used together
with -mxform. If there is more than one contour, the one clos-
est to the midplane of the tomogram is used.
-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.
INTERACTIVE INPUTS
If no command line arguments are entered, inputs are prompted interac-
tively. Inputs to the program:
Name of combined tomogram file
Name of the tomogram that was matched TO, which will be the source of
replacement values
Either the name of the tomogram that was transformed to match, or the
X, Y and Z dimensions of that file
Name of file containing inverse transformation used by MATCHVOL
Number of pixels to replace unconditionally along the four sides of the
tomogram when in flipped orientation. Enter four numbers, for the
number of pixels on the left (lower X), right (upper X), bottom
(lower Y in flipped tomogram), and top (upper Y) edges.
HISTORY
Written by David Mastronarde, November 1995
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 filltomo(1)