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

       -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.



BL3DEMC                              4.7.3                       tomostitch(1)