tiltalign(1)                General Commands Manual               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 several 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 dif-
       ference 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 distor-
       tion.  This can reduce the number of unknowns and can give more accu-
       rate 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 ana-
       lyze 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.

       6) The program can use a robust fitting method to give different
       weights to different modeled points based on their individual fitting
       errors.  Points with the most extreme errors are eliminated from the
       fit, and ones with high but less extreme errors are down-weighted.
       This fitting provides a substitute for fixing many modeled point posi-
       tions based on their errors.

   Mapping of Variables
       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 differ-
       ently, 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 combina-
       tions 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 automap-
       ping, 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 solu-
       tion 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 map-
       ping 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 vari-
       able.  (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.  Specifi-
       cally, 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.

   Local Alignments
       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 mini-
       mum 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 accommo-
       dated 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 recon-
       structions from tilts around two axes.

   Robust Fitting
       The goal in robust fitting is to reduce the effect of incorrectly
       placed model points on the fitted solution by giving less weight to
       points which appear to be outliers.  Because it is not possible to be
       certain about which points are indeed incorrect, each point is given a
       weight that depends on how large its error is relative to that of other
       points.  When the option to use robust fitting is selected, the program
       first obtains a global alignment solution, or one for a local area,
       which gives a residual error value for each projection point.  The
       residual values are analyzed to derive a weight between 0 and 1 for
       each one, and the fitting routine is call again to refine the solution
       with these weights.  This solution provides new residuals, and this
       process is repeated until the weights do not change significantly or
       until the fitting routine only runs for one iteration several times in
       a row.  At the end, the program prints out the final F value from the
       fit, which is the square root of the mean squared weighted errors, and
       it also prints a weighted mean residual value immediately after the
       ordinary mean.  It also prints a line showing the number of weights
       that were set to 0, less than 0.1, less than 0.2, and less than 0.5.
       The latter number is usually about 5% of the total points.  The numbers
       of down-weighted points can be increased or decreased by entering the
       KFactorScaling with a value less than or greater than 1, respectively.

       The weights are derived by the following method.  The median residual
       is first obtained for each view from the errors of the unweighted fit,
       and these values are smoothed to obtain a curve for the dependence of
       median residual on view number.  The projection points are divided into
       groups of about 100 by forming groups of adjacent views, and, for the
       global solution, by sorting the points into concentric rings based on
       distance from the center.  These two measures are used to reduce the
       influence of systematic variations in residual error with tilt angle
       and with distance from the center on the detection of incorrectly posi-
       tioned points.  For a group of points, each point's residual is divided
       by the smoothed median residual for that point's views.  The median of
       the values is found, as well as the normalized median absolute devia-
       tion from the median (the MADN).  For each point with residual greater
       than the median, the value
         x = (residual - median) / (K * MADN)
       is computed, where K is the K factor (4.685 by default), and the weight
       is
         (1 - x**2)**2
       for x < 1, or 0 for x > 1.

   The Alignment Model
       The program implements the following model for the imaging of the spec-
       imen 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.

       The complete model is summarized in:
       Mastronarde, D. N. 2008.  Correction for non-perpendicularity of beam
       and tilt axis in tomographic reconstructions with the IMOD package. J.
       Microsc.  230: 212-217.
       The version of the model prior to the addition of beam tilt is
       described in more detail in:
       Mastronarde, D. N.  2007.  Fiducial marker and hybrid alignment methods
       for single- and double-axis tomography.  In: Electron Tomography, Ed.
       J. Frank, 2nd edition, pp 163-185. Springer, New York.

OPTIONS
       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 -).  Options can be
       abbreviated to unique letters; the currently valid abbreviations for
       short names are shown in parentheses.

       In all entries of view numbers, the views are numbered from 1.

   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, ImageO-
              riginXandY, and ImagePixelSizeXandY, or values from the model
              itself if those options are omitted.  In general, the informa-
              tion 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, in Angstroms
              (optional)

       -UnbinnedPixelSize   Floating point
              Pixel size of unbinned data in nanometers

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

       -OutputFilledInModel      File name
              Output file for fiducial model with missing points filled in on
              the views included in the solution.  This model can be used for
              erasing fiducial markers.  A missing point is first computed
              from the projection position of the solved 3-D position of the
              fiducial. Then, a line is fit to the residuals of points on the
              6 nearest views and an estimated residual is subtracted from the
              projection position, in order to incorporate a consistent dis-
              parity between the fiducial positions and the solution.  Projec-
              tion positions from a global solution are replaced by ones from
              local solutions, if any, and ones from multiple local areas are
              averaged.  This option is ignored for a model from patch track-
              ing.

       -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

       -FixedXYZInputFile   File name
              File with fixed X-Y-Z coordinates to use in local alignments.
              The values will be used when initializing the coordinates for
              the search in each local area, but they will have little effect
              unless -FixXYZCoordinates is entered.  Each line of this file
              should start with the three coordinates; numbers after that are
              ignored.  There must be the same number of lines in the file as
              the number of fiducials.

       -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 backpro-
              jection 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)

       -NoSeparateTiltGroups     Integer
              Allow tilt angles to be grouped across separate view groups in
              order to prevent large jumps in the solved tilt angles.  Enter 1
              to allow this grouping with a patch tracking model, or 2 to
              allow it for any fiducial model.

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

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

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

       -angles (-a) OR -TiltAngles    Multiple floats
              Use this option to enter the tilt angles for each view individu-
              ally, 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 par-
              allel 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 differ-
              ently 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 solu-
              tion (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 differ-
              ently 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 mean-
              ing as for global solution.

       -LocalMagDefaultGrouping       Integer
              Default group size when automapping local magnification vari-
              ables

       -LocalMagNondefaultGroup       Three integers
              Starting and ending view numbers and group size for a set of
              views whose local magnification variables should be grouped dif-
              ferently 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 differ-
              ently 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 dif-
              ferently 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 mini-
              mization procedure (METRO) tries to take.  The default is 0.25,
              which typically works even for large data sets.  When METRO
              fails for various reasons, the program will retry with several
              other nearby values of the factor.

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

       -RobustFitting
              Use a robust fitting method that gives less weight to points
              with residuals higher than the median residual, and no weight to
              the most extreme points.

       -WeightWholeTracks
              When doing robust fitting with a model from patch tracking,
              assign the same weight to all the points in each contour.  Con-
              tours with mean residuals higher than the median will thus be
              given less weight, and ones with the most extreme residuals will
              be given weights of 0.02.

       -KFactorScaling      Floating point
              Amount to scale the K factor that controls how many points are
              down-weighted in the robust fitting.  The default scaling of 1
              gives a K factor of 4.685, the factor commonly used for the
              Tukey bisquare weighting.  A smaller factor will down-weight and
              eliminate more points.

       -WarnOnRobustFailure
              Give just a warning instead of exiting with an error if the
              robust fitting fails and only a global alignment is being done.
              If local alignments are being done, a failure in either the
              global alignment or a local area will always result in just a
              warning.  In all cases, the non-robust alignment is restored
              after a failure.

       -MinWeightGroupSizes      Two integers
              Minimum sizes of the groups of points used for computing
              weights, in global and local alignment runs.  In order to apply
              the robust method to points that are relatively similar to each
              other, deviations from a median residual are computed within
              subsets of points that are located on adjacent views; and if
              there are enough points, the points in a global alignment run
              are also sorted into rings based on distance from the center.
              These entries set the minimum sizes of these groups.  If the
              total number of points available for fitting falls below the
              minimum, the robust fitting is not done and a warning or error
              is issued.  The defaults are 100 and 65 when adjusting weights
              for individual points.  When assigning weights to whole contours
              with data from patch tracking, a similar approach is used to
              divide the contours into groups that are analyzed together.
              Here, the defaults are 30 and 20.

       -AxisZShift     Floating point
              Amount to shift the tilt axis in Z, relative to the centroid in
              Z of the fiducial points or relative to the original Z axis
              location if ShiftZFromOriginal is entered. It is also possible
              to enter 1000 to shift the tilt axis to the midpoint of the
              range of Z values.  Enter this value in unbinned pixels.

       -ShiftZFromOriginal
              Apply Z shift relative to original tilt axis location.  If
              images were initially aligned by cross-correlation, this option
              will keep specimen material near the center of the reconstruc-
              tion even if fiducials are on one surface.

       -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 solu-
              tion 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 indepen-
              dently 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 map-
       ping.

       -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 magnifi-
              cation variable number for each view.  (Successive entries accu-
              mulate)

       -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 compres-
              sion variable number for each view.  (Successive entries accumu-
              late)

       -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 accumu-
              late)

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

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.25, which typically
           works even for large data sets.  The
           default # of cycles is 1000.  When METRO fails for various reasons,
           the program will retry with several other, nearby 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 abso-
       lute and the incremental compression for each view.  When no compres-
       sion 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 follow-
       ing formats:

       The file with alignment transforms (option OutputTransformFile) con-
       tains 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 OutputXAxisTiltFile) 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 data are all expressed as incre-
       ments to the global alignment information.  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.

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                4.11.0                        tiltalign(1)