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