tomopitch(1)                                                      tomopitch(1)



NAME
       tomopitch - Determines tomogram shift and angles from models of section

SYNOPSIS
       tomopitch  [options]

DESCRIPTION
       Tomopitch analyes simple models of the boundaries of the section in
       slices from a tomogram and recommends how much to change tilt angles to
       make the section flat, how much to shift the tilt axis in Z to produce
       centered slices, and how thick to make the slices.  It can also recom-
       mend how much X-axis tilt is needed to make the section flat in the
       orthogonal direction as well.  It can also be used with a model drawn
       on a whole tomogram, possibly binned down.

       The typical use is with samples of the tomogram in separate files.  For
       each sample of the tomogram, make a model file with two contours in it.
       Each contour should have two points, with the line between them lying
       along the top or bottom surface of the section.  The points do not have
       to be entered in any particular order, and the lines do not need to be
       any particular length (the program will extend them in X, if necessary,
       to within 5% of each edge of the tomogram).

       As an alternative to making a separate model file for each sample, you
       can load all of the samples into 3dmod together and make a single model
       file, creating a pair of contours at each different time index. Make
       this model file be the sole entry to Tomopitch, and it will analyze
       each of the time indexes separately, the same as if they were in sepa-
       rate files.

       A third alternative is to make a model on an entire tomogram.  Such a
       model can take two forms.  It can consist of any number of pairs of
       horizontal lines, where each par is drawn predominantly in the X direc-
       tion along the top and bottom of the section.  This can be done while
       viewing the YZ planes of the tomogram, just as in the samples of YZ
       slices.  The lines can also be drawn while viewing the XY planes of the
       tomogram in the Zap window, or they can be drawn in the Slicer window
       with the angles adjusted to make a surface appear all at once in the
       window.  These lines do not need to be parallel to the X axis, but try
       to draw the two lines of a pair at approximately the same location in
       Y.  The program expects the separation in Y between the two lines of a
       pair to be less than 0.3 times the separation between successive pairs.

       The second form for a model on a whole tomogram consists of a pair of
       horizontal lines near the middle of the tomogram, and a pair of lines
       oriented vertically (predominantly in the Y direction) along the top
       and bottom of the tomogram.  Only one pair of lines of each type is
       allowed.  With this input, the program will construct two more pairs of
       horizontal lines by sliding the pair that were entered to the low Y and
       high Y ends of the vertical lines.  Analysis then proceeds with the
       three pairs of horizontal lines.

       If you make a model on an entire tomogram, you need not enter a value
       for the spacing in Y.  If the tomogram is binned down relative to the
       final tomogram, enter the binning factor as a scale factor to get val-
       ues appropriate for the final tomogram.

       The program analyzes each pair of horizontal lines separately.  It
       determines what rotation is required to make the section be flat.  It
       reports the upward shift needed to center the section in Y, and the
       slice thickness needed to contain the section.  These values are
       derived and reported  before and after the recommended rotation is
       applied.  Thickness values include an additional amount that you spec-
       ify and are rounded up to integers suitable for taking 3D FFTs.  After
       all pairs of lines are analyzed, the program makes the same analysis
       and report based on the data from all of the files.  It then computes
       an X-axis tilt and reports thickness and rotation if that tilt is taken
       into account as well.

OPTIONS
       Tomopitch uses the PIP package for input (see the manual page for
       pip) and can take input interactively for options that existed when
       it was converted, 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 (with-
       out the -).  Options can be abbreviated to unique letters; the cur-
       rently valid abbreviations for short names are shown in parentheses.


       -model (-m) OR -ModelFile      File name
              Model file with lines to analyze.  If there are multiple model
              file entries, they should be in order that they will be consid-
              ered in the program.  (Successive entries accumulate)

       -extra (-e) OR -ExtraThickness      Floating point
              Additional pixels of thickness to add to both the top and the
              bottom of the tomogram, beyond the region described by the model
              lines.  Enter values as unbinned pixels, i.e. pixels after the
              scaling factor has been applied.

       -spacing (-sp) OR -SpacingInY       Floating point
              Spacing between tomogram samples (distance in Y in tilted
              views).  If a non-zero number is entered, the program will com-
              pute the tilt around the X-axis that will make the tomogram be
              flat in its Z dimension.

       -scale (-sc) OR -ScaleFactor   Floating point
              Amount by which to scale the Z shift and thickness recommended
              by the program.  Use this entry if the model was drawn on
              binned-down samples or a whole binned-down tomogram but you
              intend to make an unbinned tomogram.  The scale factor is the
              binning factor.

       -angle (-a) OR -AngleOffsetOld      Floating point
              Angle offset in the alignment used to make the samples.  If this
              entry is present, the program will output the original, added,
              and total offset.

       -zshift (-z) OR -ZShiftOld     Floating point
              Z shift value in the alignment used to make the samples, in
              unbinned pixels.  If this entry is present, the program will
              output the original, added, and total Z shift.

       -xtilt (-x) OR -XAxisTiltOld   Floating point
              X axis tilt applied when the samples were made.  If this entry
              is present, the program will output the original, added, and
              total X axis tilt.

       -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 INPUT
       If the program is started with no command line arguments, it reverts to
       interactive input with the following entries:

       Additional pixels of thickness to add to both the top and the bottom of
       the tomogram, beyond the region described by the model lines.

       Spacing between tomogram samples (the distance in Y in the tilt
       images.)  If a non-zero number is entered, the program will compute the
       tilt around the X-axis that will make the tomogram be flat in its Z
       dimension.

       Number of model files to analyze

       For each file, then enter the name of the file.

HISTORY
       Written by David Mastronarde, January 2000
       5/20/01: Added analysis of single file with multiple time indexes
       11/13/03: Converted to PIP, added ability to draw lines in whole tomogram

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                        tomopitch(1)