Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

TILTALIGN(1)							   TILTALIGN(1)

NAME
  tiltalign - Solve for alignment of tilted views using fiducials

SYNOPSIS
  tiltalign

DESCRIPTION
  This program will solve for the displacements, rotations, tilts, and
  magnification differences relating a set of tilted views of an object.  It
  uses a set of fiducial points that have been identified in a series of
  views. These input data are read from a model in which each fiducial point
  is a separate contour.

  This program has five notable features:

  1) Any given fiducial point need not be present in every view. Thus, one
  can track each fiducial point only through the set of views in which it can
  be reliably identified, and one can even skip views in the middle of that
  set.

  2) The program can solve for distortion (stretching) in the plane of the
  section.  It does so with two additional variables: "dmag", an increment to
  the magnification along the X axis; and "skew", the difference in rotation
  between the X and Y axis.  If there is stretch in the plane of the
  sections, then in general the aligned images will backproject correctly
  only at one plane in Z.  This solution thus includes a set of adjustment
  factors that can be passed to the Tilt program to correct for this effect.

  3) It is possible to constrain several views to have the same unknown value
  of rotation, tilt angle, magnification, compression, or distortion.  This
  can reduce the number of unknowns and can give more accurate overall
  solutions.
  
  4) If the fiducial points are supposed to lie in one or two planes, then
  after the minimization procedure is complete, the program can analyze the
  solved point positions and determine the slope of this plane.  It uses this
  slope to estimate how to adjust tilt angles so as to make the planes be
  horizontal in a reconstruction.

  5) The program can solve for a series of local alignments using subsets of
  the fiducial points.  This can be useful when aligning a large area which
  does not behave uniformly during the tilt series.  The local alignments can
  then be used to obtain a single large reconstruction whose resolution is as
  good as would be attained in a smaller volume.

  The constraining of different views to have related values of some unknown
  variable is called "mapping"; it works differently for tilt than for other
  variables.  For variables other than tilt, if two or more views are mapped
  to the same variable, then all of those views will have the same value.
  For tilt angle, if two views are mapped to the same tilt variable, then the
  DIFFERENCE between their tilt angles is constrained to be a constant equal
  to the difference between their initial tilt angles.  So, if they have the
  same initial tilt angle, they will always have the same tilt; and if their
  initial tilt angles differ by 10, their tilt angles will always differ by
  10.
  
  Mapping can be set up relatively easily with "automapping".  When you
  select automapping, the program will map views in a group of adjacent views
  to the same variable, and it will determine a set of groups of a specified
  size.  You control the mapping by specifying the default size of the
  groups.  In addition, if some views need to be grouped differently, you can
  specify one or more ranges of views to have different sized groups.

  With automapping, the program can also set up variables that change
  linearly from one group to the next, rather than being constrained to the
  same value for all views in a group.  In other words, the values for all of
  the views in a group will be a linear combination of the same two actual
  variables (typically the first one in the group and the first one in the
  next group).  This feature usually gives a solution with less error.  The
  distinction between actual variables and combinations can be seen in the
  "Variable mappings" table.  Actual variables would appear as, e.g., "tilt
  15" and "tilt 25", while combinations of the two appear as "t 15+ 20".
  There are also linear combinations between a variable and a fixed value,
  which appear in the table as "t 70+fix".  Currently, the linear mapping is
  available only with automapping, not with manually specified mappings.
  
  With automapping, the size of the groups will be adjusted dynamically for
  two variables, tilt angle and x-axis stretch, so that groups become smaller
  at higher tilt angles.  This is done because it is easier to solve
  accurately for tilt angle at higher tilt, and because the solution for
  x-axis stretch tends to change rapidly at high tilts.  The group size that
  you specify for these variables will be the average size of the whole range
  of tilts.  If this dynamic automapping gives problems with tilt angle, use
  mapping in blocks rather than linear mapping to have stricter control over
  the mapping process.  The dynamic automapping is used for both kinds of
  mapping of x-axis stretch because the mapping in blocks is the preferred
  method for grouping this variable.  (Linear mapping does not always work
  properly.)
  
  The size of groups when automapping will also be adjusted to provide more
  grouping when some views have only one or two points.  Specifically, views
  with fewer than 3 points will not be counted toward the total number of
  views to be included in a group.  This feature is most important with the
  local alignments described next, where there may be relatively few points in
  a local area.

  The program can embark on local alignments after obtaining the standard
  global solution with all of the fiducials.  The program divides the image
  area, or the area occupied by fiducials, into a regular array of overlapping
  subareas.  Fiducials whose X and Y coordinates fall within a subarea are
  included in the computations for that subarea.  A subarea is expanded about
  its center, if necessary, to include a certain minimum number of fiducials.
  The program then seeks a solution for the subset of fiducials that is, for
  all variables, "incremental" to the global solution; that is, it solves for
  variables that are added to the parameters from the global solution.  This
  method allows a dramatic reduction in the number of variables to be solved
  for, mostly because rotation and magnification can be mapped to a much
  smaller number of variables than in the global solution.  The usual need for
  each view to have its own rotation and magnification variable is already
  accommodated in the global solution.
  
  One option in the local alignment is whether to solve for the X-Y-Z
  coordinates of the subset of fiducials, or to fix them at their values from
  the global solution.  Solving for the coordinates may give a more accurate
  solution but it does require more fiducials to get a reliable result.
  Fixing the coordinates reduces the number of variables to be solved for and
  allows a reliable solution with only a relatively few fiducials; it also
  avoids distortions in the resulting reconstruction that could be difficult
  to account for when trying to combine reconstructions from tilts around two
  axes.

  The program implements the following model for the imaging of the specimen
  in each individual view:
  1) The specimen itself changes by 
    a) an isotropic size change (magnification variable); 
    b) additional thinning in the Z dimension (compression variable); and 
    c) linear stretch along one axis in the specimen plane, implemented by
       variables representing stretch along the X axis and skew between the X
       and Y axes;
  2) The specimen is tilted slightly around the X axis (X tilt variable)
  3) The specimen is tilted around the X axis by the negative of the beam tilt,
     if any (one variable for all views)
  4) The specimen is tilted around the Y axis (tilt variable)
  5) The specimen is tilted back around the X axis by the beam tilt, if any 
  6) The projected image rotates in the plane of the camera (rotation
     variable)
  7) The projected image may stretch along an axis midway between the original
     X and Y axes (one variable for all views)
  8) The image shifts on the camera

  Only a subset of this complete model can be solved for in any given case.
  In particular, thinning cannot be solved for together with tilt angle and
  stretch along the X axis; it is very difficult to solve for X axis tilt
  together with rotation angle; and it is almost impossible to solve for beam
  tilt together with rotation and skew.

INPUTS TO THE PROGRAM
  
  In all entries of view numbers, the views are numbered from 1.

  Tiltalign uses the PIP package for input (see the manual page for pip)
  and can still take sequential input interactively, 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 -):


INPUT AND OUTPUT FILE OPTIONS 
  These options give information about input and output files.

 -ModelFile   File name
    Input fiducial model file

 -ImageFile   File name
    Image file that fiducial model was built on, used to obtain information
    for scaling the model.  If this entry is omitted, the program will use
    values entered with ImageSizeXandY, ImageOriginXandY, and
    ImagePixelSizeXandY, or values from the model itself if those options are
    omitted.  In general, the information from the model header should be
    sufficient and none of these entries should be needed.

 -ImageSizeXandY   Two integers
    Dimensions of image file (optional)

 -ImageOriginXandY   Two floats
    X and Y origin values from image file header (optional)

 -ImagePixelSizeXandY   Two floats
    X and Y Pixel spacing from image file header (optional)

 -ImagesAreBinned   Integer
    The current binning of the images relative to the original data.  This
    factor is used to scale the values entered with AxisZShift and AxisXShift
    from unbinned to binned coordinates.  The default is 1.

 -OutputModelFile   File name
    File in which to place 3-D model of the fiducials based on their solved
    positions

 -OutputResidualFile   File name
    Output file for a list of the residuals at all projection points, which
    can be converted to a model with Patch2imod.

 -OutputModelAndResidual   File name
    Root name for output of both a 3-D model and residuals; the files will
    have extensions .3dmod and .resid, respectively.

 -OutputTopBotResiduals   File name
    Root name for output of residuals for fiducials on the top and bottom
    surfaces into separate files, with extensions .topres and .botres.

 -OutputFidXYZFile   File name
    File for text output of the solved X-Y-Z coordinates

 -OutputTiltFile   File name
    Output file for the solved tilt angles after adjustment for beam tilt, if
    any

 -OutputUnadjustedTiltFile   File name
    Output file for the solved tilt angles before adjustment for beam tilt, if
    any

 -OutputXAxisTiltFile   File name
    Output file for tilts around the X axis.

 -OutputTransformFile   File name
    Output file for 2-D transformations needed to align images

 -OutputZFactorFile   File name
    Output file for factors to adjust X and Y as function of Z in
    backprojection.  When there is specimen stretch along an axis, a 2-D
    transformation of the projections cannot fully correct for this effect,
    and these factors are needed to adjust the backprojection position for
    different Z heights in the reconstructed slice.

ANGLE AND VIEW RELATED OPTIONS 
  These options provide information about tilt angles and the views to be
included in the analysis.

 -IncludeStartEndInc   Three integers
    Starting and ending view numbers, and increment between views, to include
    in analysis.  This option, IncludeList, and ExcludeList are mutually
    exclusive.  The default is to include all views that have points in the
    model.

 -IncludeList   List of integer ranges
    List of views to include in the analysis (ranges allowed)

 -ExcludeList   List of integer ranges
    List of views to exclude from the analysis (ranges allowed)

 -RotationAngle   Floating point
    Initial angle of rotation in the plane of projection.	 This is the
    rotation (CCW positive) from the Y-axis (the tilt axis after the views are
    aligned) to the suspected tilt axis in the unaligned views.

 -SeparateGroup   List of integer ranges
    List of views that should be grouped separately in automapping.  Multiple
    entries can be used to specify more than one set of separate views.
    (Successive entries accumulate)

 -first OR -FirstTiltAngle   Floating point
    Tilt angle of first view, in degrees.  Use this option together with
    TiltIncrement.

 -increment OR -TiltIncrement   Floating point
    Increment between tilt angles, in degrees.  Use this option together with
    FirstTiltAngle.

 -tiltfile OR -TiltFile   File name
    Use this option if tilt angles are in a file, one per line.

 -angles OR -TiltAngles   Multiple floats
    Use this option to enter the tilt angles for each view individually, in
    degrees.
    (Successive entries accumulate)

 -AngleOffset   Floating point
    Amount to add to all entered tilt angles.

VARIABLE SELECTION OPTIONS 
  These options specify the variables to be included in the analysis and
information about them, such as group sizes.

 -ProjectionStretch
    Solve for a parameter representing a skew between the microscope X and Y
    axes that occurs during projection of all images.  This is equivalent to a
    stretch along a 45-degree line between the axes.  A component of stretch
    parallel to the axes cannot be distinguished from a stretch of the 3D
    fiducial coordinates parallel to the axes, so as of IMOD 3.10.7 only this
    skew component is solved for.  The initial rotation angle of the tilt axis
    is used to determine the approximate axis along which this stretch would
    occur after the final image rotation.

 -BeamTiltOption   Integer
    Type of solution for non-perpendicularity between tilt axis and beam axis,
    referred to as beam tilt: 
      0 for beam tilt fixed at the initial value, 
      1 to include beam tilt as a variable in the minimization procedure, 
      2 to perform the minimization at a series of fixed beam tilt values and
    search for the value that gives the smallest error.  
    Because some variables can covary with the beam tilt to give nearly
    equivalent solutions, the second option for finding the beam tilt gives
    more reliable results.  Some combinations of variable simply cannot be
    solved for, in particular the stretch variables and rotation together with
    beam tilt; either omit the stretch variables or solve for a single
    rotation angle.  Note that only the component of the beam tilt around the
    X axis is solved for; the component around the Y axis is indistinguishable
    from a change in tilt angle.  When the beam tilt is non-zero, either as a
    result of a search or because a fixed value was entered, its effect is
    expressed as a varying tilt around the X axis and a modification of the
    tilt angles and in-plane image rotations.  Thus, a file of X-tilt angles
    should be output when beam tilt is included in the solution.

 -FixedOrInitialBeamTilt   Floating point
    The entry provides either an initial value for the beam tilt, when it is
    being solved for, or a fixed value when it is not.

 -RotOption   Integer
    Type of rotation solution: 
      0 for all rotations fixed at the initial angle, 
      1 for each view having an independent rotation, 
      2 to enter general mapping of rotation variables, 
      3 or 4 for automapping of rotation variables (3 for linearly 
        changing values or 4 for values all the same within a group), or 
     -1 to solve for a single rotation variable.

 -RotDefaultGrouping   Integer
    Default group size when automapping rotation variables

 -RotNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    rotation variables should be grouped differently from the default. 
    Multiple entries can be used to specify more than one set of views with
    nondefault grouping.
    (Successive entries accumulate)

 -RotationFixedView   Integer
    Number of view whose rotation should be fixed at the initial rotation
    angle.  This entry is relevant with any of the positive RotOption entries.

 -LocalRotOption   Integer
    Type of local rotation solution: 
      0 for local rotations fixed, 
      1 for each view having an independent rotation, 
      2 to enter general mapping of variables, 
      3 or 4 for automapping of rotation variables (3 for linearly 
        changing values or 4 for values all the same within a group), or 
     -1 to solve for a single rotation variable.

 -LocalRotDefaultGrouping   Integer
    Default group size when automapping local rotation variables.

 -LocalRotNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    local rotation variables should be grouped differently from the default.
    (Successive entries accumulate)

 -TiltOption   Integer
    Type of tilt angle solution: 
      0 to fix all tilt angles at their initial values, 
      1 to solve for all tilt angles except for a specified view, 
      2 to solve for all tilt angles except for the view at minimum tilt, 
      3 to solve for all tilt angles except for a specified view and 
        the view at minimum tilt, 
      4 to specify a mapping of tilt angle variables, 
      5 or 6 to automap groups of tilt angles (5 for linearly changing 
        values or 6 for values all the same within a group), or 
      7 or 8 to automap and fix two tilt angles (7 for linearly changing 
        values or 8 for values all the same within a group)

 -TiltFixedView   Integer
    Number of view at which to fix the tilt angle (required with TiltOption 1,
    3, 7, or 8)

 -TiltSecondFixedView   Integer
    Number of second view at which to fix the tilt angle (required with
    TiltOption 7 or 8)

 -TiltDefaultGrouping   Integer
    Average default group size when automapping tilt variables

 -TiltNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    tilt variables should be grouped differently from the default.
    (Successive entries accumulate)

 -LocalTiltOption   Integer
    Type of local tilt angle solution; values 0-8 have same meaning as for
    global solution.

 -LocalTiltFixedView   Integer
    Number of view at which to fix the tilt angle in the local solution
    (required with LocalTiltOption 1, 3, 7, or 8)

 -LocalTiltSecondFixedView   Integer
    Number of second view at which to fix the tilt angle in the local solution
    (required with LocalTiltOption 7 or 8)

 -LocalTiltDefaultGrouping   Integer
    Average default group size when automapping local tilt variables

 -LocalTiltNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    local tilt variables should be grouped differently from the default.
    (Successive entries accumulate)

 -MagReferenceView   Integer
    Number of reference view whose magnification will be fixed at 1.0.  The
    default is the view at minimum tilt.

 -MagOption   Integer
    Type of magnification solution: 
      0 to fix all magnifications at 1.0, 
      1 to vary all magnifications independently, 
      2 to specify a mapping of magnification variables, or 
      3 or 4 for automapping of variables (3 for linearly changing 
        values or 4 for values all the same within a group).

 -MagDefaultGrouping   Integer
    Default group size when automapping magnification variables

 -MagNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    magnification variables should be grouped differently from the default.
    (Successive entries accumulate)

 -LocalMagReferenceView   Integer
    Number of reference view whose local magnification will be fixed at 1.0. 
    The default is the view at minimum tilt.

 -LocalMagOption   Integer
    Type of local magnification solution; values 0-3 have same meaning as for
    global solution.

 -LocalMagDefaultGrouping   Integer
    Default group size when automapping local magnification variables

 -LocalMagNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    local magnification variables should be grouped differently from the
    default.
    (Successive entries accumulate)

 -CompReferenceView   Integer
    Number of the view to fix at compression 1.0 (something other than a view
    whose tilt angle is fixed at zero.)  Required if CompOption not 0.

 -CompOption   Integer
    Type of compression solution: 
      0 to fix all compressions at 1.0, 
      1 to vary all compressions independently, 
      2 to specify a mapping of compression variables, or 
      3 or 4 for automapping of variables (3 for linearly changing 
        values or 4 for values all the same within a group).

 -CompDefaultGrouping   Integer
    Default group size when automapping compression variables

 -CompNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    compression variables should be grouped differently from the default.
    (Successive entries accumulate)

 -XStretchOption   Integer
    Type of X-stretch solution: 
      0 to fix all X stretches at 0, 
      1 to vary all X stretches independently, 
      2 to specify a mapping of X-stretch variables, or 
      3 or 4 for automapping of variables (3 for values all the 
        same within a group or 4 for linearly changing values).

 -XStretchDefaultGrouping   Integer
    Default average group size when automapping X stretch variables.

 -XStretchNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose X
    stretch variables should be grouped differently from the default.
    (Successive entries accumulate)

 -LocalXStretchOption   Integer
    Type of local X-stretch solution; values 0-3 have same meaning as for
    global solution.

 -LocalXStretchDefaultGrouping   Integer
    Default average group size when automapping local X stretch variables

 -LocalXStretchNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    local X stretch variables should be grouped differently from the default.
    (Successive entries accumulate)

 -SkewOption   Integer
    Type of skew solution: 
      0 to fix all skew angles at 0.0, 
      1 to vary all skew angles independently, 
      2 to specify a mapping of skew variables, or 
      3 or 4 for automapping of variables (3 for linearly changing 
        values or 4 for values all the same within a group).

 -SkewDefaultGrouping   Integer
    Default group size when automapping skew variables

 -SkewNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    skew variables should be grouped differently from the default.
    (Successive entries accumulate)

 -LocalSkewOption   Integer
    Type of local skew solution; values 0-3 have same meaning as for global
    solution.

 -LocalSkewDefaultGrouping   Integer
    Default group size when automapping local skew variables

 -LocalSkewNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    local skew variables should be grouped differently from the default.
    (Successive entries accumulate)

 -XTiltOption   Integer
    Type of X-axis tilt solution: 
      0 to fix all X tilts at 0., 
      1 to vary all X-tilts independently, 
      2 to specify a mapping of X-tilt variables, or 
      3 or 4 for automapping of variables (3 for linearly changing 
        values or 4 for values all the same within a group).

 -XTiltDefaultGrouping   Integer
    Default group size when automapping X-axis tilt variables

 -XTiltNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    X-axis tilt variables should be grouped differently from the default.
    (Successive entries accumulate)

 -LocalXTiltOption   Integer
    Type of local X-axis tilt solution; values 0-3 have same meaning as for
    global solution.

 -LocalXTiltDefaultGrouping   Integer
    Default group size when automapping local X-axis tilt variables

 -LocalXTiltNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    local X-axis tilt variables should be grouped differently from the
    default.
    (Successive entries accumulate)

MINIMIZATION AND OUTPUT OPTIONS 
  These options control the minimization procedure and the outputs of the
program.

 -ResidualReportCriterion   Floating point
    Criterion number of standard deviations above mean residual error that
    should be reported. This can be based on either the overall mean and S.d.
    of the residual errors, or on a mean and S.d.  computed from points in
    nearby views.  Enter a positive value for a report based on overall mean,
    or a negative value for a report based on the mean residual in the same
    and nearby views.

 -SurfacesToAnalyze   Integer
    0 to omit surface analysis, or 1 or 2 to fit points to one or two surfaces
    and derive a surface angles and recommended tilt angle offset.  This entry
    has no effect on the global alignment solution.

 -MetroFactor   Floating point
    This entry determines how large a step the variable metric minimization
    procedure (METRO) tries to take.  The default for is 0.5, but smaller
    values of 0.35 or even 0.25 are needed for large data sets.  When METRO
    fails for various reasons, the program will retry with several other,
    mostly smaller values of the factor.

 -MaximumCycles   Integer
    Limit on number of cycles for minimization procedure (default 500).

 -AxisZShift   Floating point
    Amount to shift the tilt axis in Z, relative to the centroid in Z of the
    fiducial points, or 1000 to shift the tilt axis to the midpoint of the
    range of Z values.  Enter this value in unbinned pixels.

 -AxisXShift   Floating point
    Amount to shift the tilt axis in X away from the center of the image. 
    Enter this value in unbinned pixels.

LOCAL ALIGNMENT OPTIONS 
  These options control local alignments.

 -LocalAlignments
    Do alignments with subsets of points in local areas.  When this option is
    selected, the appropriate Local...Option values must be entered to control
    what variables are solved for; the default is 0 for all of the local
    option values.

 -OutputLocalFile   File name
    Output file for transformations for local alignments

 -NumberOfLocalPatchesXandY   Two integers
    Number of local patches in X and in Y in which to obtain a solution from
    the fiducials located in that patch.  If this option is entered,
    overlapping patches will be set up that fill the image area.

 -TargetPatchSizeXandY   Two integers
    Target for the size of local patches in X and Y in which to obtain a
    solution from the fiducials located in that patch.  The number of patches
    will be set so that patches smaller or up to 5% larger than this size and
    overlapping by a fixed amount will fill the range occupied by fiducials
    (not the image area).  The patches on the edges should not have to expand
    as much as when the patch centers are set up to fill the image area.  If
    this option is entered, NumberOfLocalPatchesXandY must not be entered, and
    MinSizeOrOverlapXandY must specify an overlap instead of a size.

 -MinSizeOrOverlapXandY   Two floats
    Either the minimum size of each patch in X and Y (enter values > 1) or the
    minimum fractional overlap between patches (values < 1).  The default is
    an overlap of 0.5.

 -MinFidsTotalAndEachSurface   Two integers
    Minimum total number of fiducials, and minimum number present on each
    surface if two surfaces were assumed in the analysis of surfaces.  A patch
    will be expanded about its center until it contains enough points to meet
    both of these criteria.

 -FixXYZCoordinates
    Fix the X-Y-Z coordinates of the fiducials at their values from the global
    solution; the default is to solve for them independently in each local
    area.  For more on the implications of this option, see the note above in
    the section on local alignments.

 -LocalOutputOptions   Three integers
    These three entries control the output of results for each local
    alignment: 
      1 to output the values of the parameters for each view or 0 not to; 
      1 to output the X-Y-Z coordinates of fiducials or 0 not to; and 
      1 to output points with high residuals, or 0 not to

MAPPING OPTIONS 
  These are obsolete options are for ultimate control of variable mapping.

 -RotMapping   Multiple integers
    If RotOption is 2, this option must be used to enter a rotation variable
    number for each view.  These variable numbers can be completely arbitrary,
    e.g. 1,1,1,3,3,3,5,5,5.  The numbers are used to define block grouping.
    (Successive entries accumulate)

 -LocalRotMapping   Multiple integers
    If LocalRotOption is 2, this option must be used to enter a local rotation
    variable number for each view.
    (Successive entries accumulate)

 -TiltMapping   Multiple integers
    If TiltOption is 2, this option must be used to enter a tilt variable
    number for each view.
    (Successive entries accumulate)

 -LocalTiltMapping   Multiple integers
    If LocalTiltOption is 4, this option must be used to enter a local tilt
    variable number for each view.
    (Successive entries accumulate)

 -MagMapping   Multiple integers
    If MagOption is 2, this option must be used to enter a magnification
    variable number for each view.
    (Successive entries accumulate)

 -LocalMagMapping   Multiple integers
    If LocalMagOption is 2, this option must be used to enter a local
    magnification variable number for each view.
    (Successive entries accumulate)

 -CompMapping   Multiple integers
    If CompOption is 2, this option must be used to enter a compression
    variable number for each view.
    (Successive entries accumulate)

 -XStretchMapping   Multiple integers
    If XStretchOption is 2, this option must be used to enter an X stretch
    variable number for each view.
    (Successive entries accumulate)

 -LocalXStretchMapping   Multiple integers
    If LocalXStretchOption is 2, this option must be used to enter a local X
    stretch variable number for each view.
    (Successive entries accumulate)

 -SkewMapping   Multiple integers
    If SkewOption is 2, this option must be used to enter a skew variable
    number for each view.
    (Successive entries accumulate)

 -LocalSkewMapping   Multiple integers
    If LocalSkewOption is 2, this option must be used to enter a local skew
    variable number for each view.
    (Successive entries accumulate)

 -XTiltMapping   Multiple integers
    If XTiltOption is 2, this option must be used to enter an X-axis tilt
    variable number for each view.
    (Successive entries accumulate)

 -LocalXTiltMapping   Multiple integers
    If LocalXTiltOption is 2, this option must be used to enter a local X-axis
    tilt variable number for each view.
    (Successive entries accumulate)

UNIVERSAL OPTIONS

 -param OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.

SEQUENTIAL INPUTS
  
  If there are no command-line arguments, Tiltalign takes sequential input
  the old way, with the following entries:
  
  Parameters are entered in the following order.  Lines starting with
  IF are entered only for particular choices on the preceding line.

  Model file name

  Name of image file on which model was built, or a blank line

  IF a blank line was entered, next enter the image dimensions NX & NY,
      the X and Y origin (default is 0,0), and the X and Y delta
      values (default is 1,1).

  Either a filename with an extension containing "mod" to output a
        3-D model of the fiducials based on their solved positions,
      or a filename with extension containing "res" for a list of all 
        residuals, which can be converted to a model with Patch2imod,
      or a filename with neither text in the extension to get both outputs, 
        one with extension .3dmod and one with extension .resid,
      or a blank line for neither output

  Name of file to which to write (in ASCII text) the solved X-Y-Z
      coordinates, or a blank line for no text output

  Name of file to which to write a list of the solved tilt angles,
      or a blank line for no tilt angle output

  Name of output file for solutions and/or transformations

  -1 to put only the solved values of the parameters in the output file
      or 1 to put only transformations for aligning the images
        into the output file,
      or 0 to put both in the file.

  0 to include all views that have points in the model file
      or 1 to specify the starting, ending, and increment views to
        include
      or 2 to enter a list of the individual views to include
      or 3 to enter a list of views to exclude

  IF 1 was selected, next enter the starting and ending view number
       and the increment to use between those values

  OR IF 2 was selected, enter a list of views to be included.  Ranges 
      may be entered; e.g. 0-3,6-8
  
  OR IF 3 was selected, enter a list of views to be excluded

  Initial angle of rotation in the plane of projection.  This is the
      rotation (CCW positive) from the Y-axis (the tilt axis after the
      views are aligned) to the suspected tilt axis in the unaligned
      views.

  0 to solve for all rotation angles (and thus to solve for tilt axis),
      or the number of the view to fix at the initial rotation angle
        (and thus fix the tilt axis at that angle for that view)
      or -1 to solve for a single global rotation of the tilt axis
      or -2 to fix all rotation angles at the initial angle

  Number of sets of views to treat separately from the main set of
      views in any automapping of variables.  Enter 0 if you will not
      be using automapping or if all views can be treated together
      when automapping.  These sets would typically be lists of views
      that were reshot so they will be referred to as reshoot sets.
  
  IF a number other than 0 was entered, next enter one line for each
      separate set, giving a list of the views included in that set.
      Ranges are allowed here.

  -1 to enter initial tilt angles individually, 1 to enter starting
      and increment tilt angles, or 0 to read tilt angles from a file

  Either the individual tilt angles (ranges NOT allowed), the
      starting and increment tilt angles, or the name of a file with
      tilt angles, depending on whether you just entered -1, 1, or 0.

  Tilt angle offset, i.e. amount to ADD to all entered tilt angles

  0 to fix all tilt angles at their initial values
      or 1 to solve for all tilt angles except for a specified view
      or 2 to solve for all tilt angles except for the view at minimum
        tilt 
      or 3 to solve for all tilt angles except for a specified view
        and the view at minimum tilt
      or 4 to specify some other combination of fixed, variable, and
        mapped tilt angles
      or 5 or 6 to automap groups of tilt angles; 5 for linearly 
         changing values or 6 for values all the same within a group 
      or 7 or 8 to automap and fix two tilt angles; 7 for linearly 
         changing values or 8 for values all the same within a group 
  
  IF 1, 3, 7 or 8 was selected, next enter the number of the view 
        whose tilt angle will be fixed.

  IF 7 or 8 was selected, next enter the number of the second view
        whose tilt angle will be fixed.

  IF 4 was selected, next enter a variable number for each view, or 0
      to fix the view at its initial tilt.  For convenience, these
      variable numbers can be completely arbitrary; e.g. 0,1,1,1,2,2
      and 0,9,9,9,5,5 both do the same thing: fix the tilt for view 1,
      map the tilts for views 2, 3 and 4 to the first tilt variable,
      and map the tilts for views 5 and 6 to the second tilt variable.

  IF 5 to 8 was selected, next enter the default number of views to
      group together, and the number of ranges of views that should
      have some grouping other than the default.  If a negative number
      of views is entered, then reshoot sets will NOT be segregated
      from the rest of the views in this default mapping.
  
      IF you entered a non-zero number of ranges to be treated
         separately, then for each such range, enter the starting and
         ending view number and the number of views that should be
         grouped in that range.  If a negative number of views is
         entered, then reshoot sets will NOT be segregated from the
         rest of the views in this range.

  Number of "reference" view whose magnification will be fixed at 1.0.
      Enter "/" to accept the default, which is the view at minimum
      tilt.

  0 to fix all magnifications at 1.0,
      or 1 to vary all magnifications independently,
      or 2 to specify a mapping of magnification variables
      or 3 or 4 for automapping of variables; 3 for linearly changing 
      values or 4 for values all the same within a group 

  IF 2 was selected, enter a magnification variable number for each
      view.  As for tilts, these variable numbers can be completely
      arbitrary.  The reference view (typically the one at minimum
      tilt angle) will be constrained to a mag of 1.0; to constrain
      any other views to a mag of 1.0, simply map them to the same
      variable number as for the reference view.

  IF 3 or 4 was selected, enter default group size, number of special
      ranges, and group size for each such range just as for tilt
      variable automapping.

  0 to omit section compression,
      or the number of the view to fix at compression 1.0 (something
        other than a view whose tilt angle is fixed at zero.)

  IF compression is being solved for, next enter 1 to have all
      compressions be independent, or 2 to specify mappings of
      compression variables, or 3 or 4 for automapping; 3 for linearly 
      changing values or 4 for values all the same within a group
  
      IF 2 was selected, enter a compression variable number for each
         view.  As for tilts, these variable numbers can be completely
         arbitrary.  The reference view will be constrained to a comp
         of 1.0; to constrain any other views to a comp of 1.0, simply
         map them to the same variable number as for the reference
         view.  A View with tilt fixed at zero will automatically have
         its comp fixed at 1.0 UNLESS you map it to another view whose
         tilt is not fixed at zero.

      IF 3 or 4 was selected, enter default group size, number of 
         special ranges, and group size for each such range just as
         for tilt variable automapping.

  0 to omit section distortion, 1 to include distortion and use the
      same set of mappings for X-axis stretch and skew variables, or
      2 to specify separate mappings for these two variables.
  
  IF 1 or 2 was selected, answer the next two queries either once
      (for distortion variables in general) or twice (first for the
      X-axis stretch, then for the skew):
  
      1 for independent variables, 2 to specify a mapping, or 3 or 4
         for automapping.  For X-axis stretch, 3 will make values be 
         all the same within a group and 4 will make values change
         linearly (not recommended).  For skew, use 3 for linearly
         changing values or 4 for values all the same within a group.
  
      IF 2 was selected, enter a variable number for each view.  The
         reference view for magnification will be constrained to
         distortion values of 0; to constrain any other views to 0
         distortion, map them to the same variable number as for the
         reference view.

      IF 3 or 4 was selected, enter default group size, number of 
         special ranges, and group size for each such range just as
         for tilt variable automapping.

  Criterion number of standard deviations above mean residual error
      that should be reported.  This can be based on either the overall
      mean and S.d. of the residual errors, or on a mean and S.d.
      computed from points in nearby views.  Enter a positive value 
      for a report based on overall mean, or a negative value for a
      report based on the mean residual in the same and nearby views.

  0 to omit analysis of surfaces,
      or 1 or 2 to derive a tilt angle offset by assuming that
      points lie on 1 or 2 surfaces.

  "Factor", and limit on number of cycles, for the variable metric
      minimization (METRO).  "Factor" determines how large a step METRO
      tries to take.  The default for "factor" is 0.5, but smaller
      values of 0.35 or even 0.25 are needed for large data sets.  The
      default # of cycles is 500.  When METRO fails for various reasons,
      the program will retry with several other, mostly smaller values
      of the factor.

  IF transformations are being computed, next enter two more lines:

      Amount to shift the tilt axis in Z, relative to the centroid in 
      Z of the fiducial points, or 1000 to shift the tilt axis to the
      midpoint of the range of Z values 

      Amount to shift the tilt axis in X away from the center of the 
      image
  
  0 to exit, or 1 to do a series of local alignments.  If you enter 1
      to do local alignments, a series of entries is required to
      specify the special parameters for local alignment, then a
      series of entries to specify the mapping of variables.  Entries
      continue with:
  
  Name of output file in which to place transformations for local
      alignment.
  
  Number of local patches in X and in Y in which to obtain a solution
      from the fiducials located in that patch.  These patches will be 
      aranged so as to cover the whole image area.
  
  Either the minimum size of each patch in X and Y (enter values > 1)
      or the minimum fractional overlap between patches (values < 1)
  
  Minimum total number of fiducials, and minimum number present on each
      surface if two surfaces were assumed in the analysis of
      surfaces.  A patch will be expanded about its center until it
      contains enough points to meet both of these criteria.
  
  0 to solve for the X-Y-Z coordinates of the fiducials independently
      in each local area, or 1 to fix them at their values from the
      global solution
  
  Three entries to control the output of results for each local
      alignment: 1 to output the values of the parameters for each
      view or 0 not to; 1 to output the X-Y-Z coordinates of fiducials
      or 0 not to; 1 to output points with high residuals, or 0 not to
  
  Finally, there are a series of entries just as above, to control the
  mapping of rotation, tilt, magnification and distortion variables:
  
  0 to fix all rotations, 1 to have them all be independent, 2 to
      specify a mapping of rotation variables, 3 for automapping with
      linearly changing values, or 4 for automapping in blocks of
      values.  After this, enter mapping information as appropriate.
  
  0-8 to specify treatment of tilt variables, as described above.
      After this, enter mapping information for tilt variables as
      appropriate.

  Number of "reference" view whose magnification will be fixed at 1.0.
      Enter "/" to use the view at minimum tilt.

  0-3 to specify treatment of magnification variables, as described
      above.  Then enter mapping information as appropriate.
  
  0 to omit section distortion, 1 to include distortion and use the
      same set of mappings for X-axis stretch and skew variables, or
      2 to specify separate mappings for these two variables.  After
      this, enter specifications for treatment of each or both sets of
      parameters, just as above.


  Note: when compression is solved for, the program prints both the
  absolute and the incremental compression for each view.  When no
  compression is solved for, the program prints instead two additional
  columns: "deltilt" is the difference between the solved and original
  tilt angles, and "mean resid" is the mean residual error for each
  view.

FILES
  Files generated by Tiltalign for use by other programs have the following
  formats:

  The file with alignment transforms (option OutputTransformFile) contains one
  line per view, each with a linear transformation specified by six numbers:
    A11 A12 A21 A22 DX DY
  where the coordinate (X, Y) is transformed to (X', Y') by:
    X' = A11 * X + A12 * Y + DX
    Y' = A21 * X + A22 * Y + DY

  The file with solved tilt angles (option OutputTiltFile) has the angle in 
  degrees for each view, one per line.

  The file with X-axis tilt angles (option OutputXAxisTiltFileq) has the angle
  in degrees for each view, one per line.

  The file with Z factors (option OutputZFactorFile) has two numbers on one
  line for each view, the displacement in X and the displacement in Y per
  pixels of deviation in Z from the midplane.

  The file with all residuals (option OutputResidualFile) starts with a line
  with the number of residuals to follow, then has five values per line for
  each residual:
    X  Y  Z  X_residual Y_residual
  It can be converted to a model by running Patch2imod with no special
  options. 

  The file with solved X-Y-Z coordinates (option OutputFidXYZFile) has one
  line per 3D point:
    fiducial_# X Y Z object_# contour_#
  The first line has, after these values, the pixel size and the size of the
  image file that the alignment was run with:
    Pix:    pixel_in_Angstroms   Dim:   X_size Y_Size

  The file of local alignments (option OutputLocalFile) has a header line
  with: 
    #_X #_Y X_start Y_start dX dY if_Xtilts  pixel_Angstroms if_Zfactors
  where #_X and #_Y are number of patches in X and Y, X/Y_start are the
  centers of the first patches in X and Y, dX and Y are the spacing between
  patches in X and Y, if_Xtilts is 1 if there are X-axis tilts,
  pixel_Angstroms is the pixel size of the image file, and if_Zfactors is 1 if
  there are Z factors.
  Following the header is a block of data for each local area, where areas
  progress in X then in Y.  The elements in each block are:
    Tilt angles, one per view, many per line
    X-axis tilt angles if they are included, one per view, many per line
    Z factors if they are included, a pair of X and Y factors for each view,
      several pairs per line
    Refinement transformations for each view in the same format as above,
       one per line

HISTORY
  Written by David Mastronarde, March 1989, based on programs ALIGN and 
  ALIGNXYZ (Mike Lawrence, 1982) obtained from R.A. Crowther at the MRC
  5/19/89 added model output, changed format of output table
  6/21/89 added mean residual output to find_surfaces, changed to
  get recommendation on maximum FIXED tilt angle
  4/9/93 allow full mapping of compression variables
  10/30/95 added distortion, automapping, point & angle output.
  10/17/98 added linear combinations to automapping
  2/12/98 added local alignments; changed find_surfaces to find and
  recommend an X-axis tilt.