filltomo(1)                                                        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
       maintain 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.



BL3DEMC                              4.7.3                         filltomo(1)