NAME
beadtrack - Tracks fiducial gold particles through a tilt series

SYNOPSIS

DESCRIPTION
tilted views.  It takes a "seed" model, where each bead of choice is
marked with at least a single point on a view near zero tilt.  It
tracks each bead as far as possible and puts out a new model.

The program works from one view to the next, using the existing data
the next view to be processed.  After bead positions are available on
enough views, the program will use tilt alignment to estimate the 3D
position of each bead, and use this position to project a position on
the next view.  The program searches for beads from the center outward.
Before looking for a particular bead, it uses the positions of beads
already found on that view to refine the projected position.  It will
adjust by a shift if there are 3 points (or at least one point from the
seed model), by shift and rotation if there are 4 or 5 points, or by
shift, rotation, and a size change if there are more than 5 points.

The program will do one or two passes for each view.  On the first
pass, it uses an average of the current bead over the nearest views for
which positions have already been identified.  It cross-correlates that
average with a box at the expected position of the bead and derives a
bead position from the peak of the correlation.  It then calculates the
centroid and the integral of the density at that position.  To do so,
it takes the average of pixels more than a certain radius away, sub-
tracts this background value from the pixels within that radius, and
uses pixels above the background to calculate a centroid and an inte-
gral.  The position is then refined with Sobel filtering of the image
(see below), if that option is selected.  If the integral is too low,
or if the putative position is too far from the expected position, the
program then attempts a "rescue".  The criterion for a rescue based on
distance is set by the user.  The criterion for a rescue based on den-
sity is set by the mean value of the bead integral on previous views.
Specifically, the criterion is the minimum of a certain fraction of the
mean and a certain number of standard deviations below the mean.  The
latter parameters are also set by the user.  To rescue, the program
starts at the expected bead position and examines every position in a
series of progressively wider circles around that point.  It calculates
an integral for each position, and when it first finds an integral
above a relaxed criterion value, it takes that position as the bead
position.  The criterion can be relaxed by different factors for "den-
sity" and "distance" rescues.

After the first pass, the program does a tilt alignment and uses two
different tests for whether to  eliminate a point on the current view.
One test is whether the residual for the point is greater than a user-
specifed limit ("criterion for rescue after fitting").  The other test
is whether the mean residual for that bead, averaged over all currently
available views, has just increased by an unusual amount.  It finds the
mean and SD of previous increases in this mean residual, and tests
whether the latest increase exceeds the mean by a user-specified crite-
rion number of SD's.

If any points were eliminated by these tests, or if any points failed
to be found, the program does a second pass.  On this pass there is no
correlation, just an attempted rescue at the expected position (possi-
this pass).  The maximum distance for this rescue is set by the user.
After the second pass, the program does another tilt alignment and
tests only the behavior of the increase in mean residual for each
point.  If that increase is too great, a point is eliminated for good.

A Sobel filter, an edge-detecting filter, can be used to get more accu-
rate bead positions in many cases.  This filter produces a ring of
intensity around the edge of the bead.  After filtering, a single bead
image is correlated with a filtered reference based on many images of
option).  For most data sets with relatively low noise, this method
produces significantly better positions and a lower mean residual error
in the alignment solution in Tiltalign.  The improvements are less
for higher-noise data (e.g., cryo data), and such data require a
higher-than-default sigma value for the Gaussian smoothing filter
applied before the Sobel filter, otherwise worse results may be
obtained.

When refining with the Sobel filter,the program stores the unrefined
positions as well.  At the end of each round (and for each local area
when using them) it does a final alignment with each set of positions
and keeps track of the mean residuals and the which set of positions
gives a lower mean residual.  At the end of tracking, the program
prints the mean of those mean residuals and how often the centroid-
based positions gave a lower value.  If that occurs more in more than
half the fits, the program gives a warning and falls back to the cen-
troid-based positions.  This protection is not present when using a
restricted range of tilt angles for alignment.

For data sets that track well, the benefit from using the Sobel filter
can be assessed even before running Tiltalign and/or completing the
model by examining the errors in the alignment solution that Beadtrack
does.  The summary line just described at the end of the log may be
adequate, or if you are doing local tracking, you may want to look at
the values for F (the root-mean-squared error) and for the mean resid-
ual at the end of the tracking for several of the local areas, just
before the output on the number of points missing for that area.  The
values for the centroid-based positions should be very close but not
identical to what you would get without the Sobel filtering.  Also, for
high-noise data, you can run with different sigma values for the kernel
filtering and see which gives the best result.

The program will leave gaps in the model rather than insert bad points.
It will try to resume tracking after a gap, but only if the gap is not
larger than a user-defined limit.

The user can choose whether or not the program will fill in gaps in the
incoming seed model.  If the image stack has sizable shifts that could
prevent accurate tracking, then one should use one of the beads as a
"pioneer".  It is not necessary to model that bead on every view, just
on the views before and after a large shift.  However, one should be
sure to have the program fill in gaps in this case.  Also, one can
place one point for a bead on the view near zero tilt, then place a few
points on distant views where one can anticipate that the program will
have trouble tracking through (e.g., where another bead crosses, or
where the bead goes too close to the edge).

The program performs poorly when the tilt alignment solution gives a
poor fit, which happens easily with large areas.  The solution to this
is to track on subsets of beads in local areas and/or to restrict the
number of views in the tilt alignment.  There are options to enable
these features when the program is run with PIP input.  An alternative,
available when running with sequential input, is to place seed points
into separate objects in different areas; e.g., 4-9 areas for 2K x 2K
images, depending on how many fiducials are available.  There should be
at least 6-8 points per area.  When there are multiple objects in the
seed model, the program will automatically track them separately unless
local area tracking or the TrackObjectsTogether option is selected.

For each view and pass, the program outputs the results from the linear
fit between actual and projected positions, the tilt alignment root-
After doing all views, the program outputs a summary of which views are

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

-InputSeedModel      File name
Input model file of starting points to track.

-OutputModel    File name
Output file for tracked model.

-ImageFile      File name
Input file with images to track.

-PieceListFile       File name
Name of piece list file if image is montaged or out of sequence.
A montaged file should not be be used unless the overlaps
between pieces are nearly exact.

-prexf (-pr) OR -PrealignTransformFile   File name
File with transformations applied to align the images.  The pro-
gram will assume that the transformations consist only of shifts
and will use this information to avoid searching for a bead on a
filled area that has no image data.

-XYZOutputFile       File name
File name for output of information that can be used by Sort-
This file has an entry for each bead with 5 columns: contour
number, solved X, Y, Z coordinates, and the mean of the mean
residuals from each local area.  The program uses the X/Y/Z
coordinates from beads that overlap between between local areas
to resolve the sets of coordinates from multiple local areas
into a single consistent set.

-ElongationOutputFile     File name
File name for output of mean residuals and bead elongation data,
which can be used by Pickbestseed when selecting optimal
beads for a seed model.  The file has an entry for each bead
with 10 columns: object and contour number, and mean of the con-
tour's mean residuals from each local area that the bead occurs
in, the mean, median, and standard deviation of one measure of
elongation (the standard deviation of pixels around the edge of
the bead when measuring the centroid), the mean, median, and
standard deviation of the elongation of pixels above a thresh-
old, and the mean bead integral.

-ImagesAreBinned     Integer
The current binning of the images relative to the original data.
This factor is used to scale the bead diameter from unbinned to
binned coordinates.  The default is 1.

-pixel (-pi) OR -PixelSize     Floating point
Pixel size of unbinned images in nanometers.  This entry is
required to use overall low pass filtering.

-SkipViews      List of integer ranges
List of views to skip over.  Model contours will pass through
these views; points will need to be added by hand afterwards.
Ranges may be entered, e.g. 1,4-6.  Views are numbered from 1.

-RotationAngle       Floating point
Angle of rotation of the tilt axis in the images; specifically,
the angle from the vertical to the tilt axis (counterclockwise
positive).

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

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

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

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

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

-MinViewsForTiltalign     Integer
Minimum number of views with bead positions available before
trying to do a tilt alignment.  To skip the tilt alignment com-
putations, set this to a number higher than the number of views.
(Default 4)

Either this option or BeadDiameter must be entered, but not
both.  If this option is entered, the diameter will be computed
will be taken as (adjusted diameter + 3) / 2.

Actual diameter of beads in pixels in the original stack, before
diameter will be taken as 2 * radius - 3.

-MedianForCentroid
Take the median instead of the mean of the pixels in the sur-
rounding annulus when computing the centroid.

Not checked if beads are darker or checked if they are lighter
than background.

-FillGaps
Fill in gaps in the seed model or leave them empty.

-MaxGapSize     Integer
Maximum size of gap to create in the model.  If a bead cannot be
tracked through some views, the tracking may be resumed as long
as the gap thus created is no larger than this amount.  (Default
5)

-ShiftsNearZeroTilt       Multiple floats
One or two entries for the net shift of bead positions when
going from a view near zero tilt to the next higher view.  Each
entry would be a shift in X and Y in unbinned pixels.  These
shifts can help the tracking get started properly when some of
the beads are relatively far in Z from the plane of material on
which the coarse alignment is centered.  They will be used when
a bead position is known on only one view near zero tilt.  If
only one shift is provided, both the position of the bead on the
adjacent view and this position modified by the shift will be
assessed in looking for the bead.  If two shifts are provided,
they will be used to obtain both of the positions that are
assessed.

-MinTiltRangeToFindAxis   Floating point
Minimum range of tilt angles for which data must be available
before trying to find the angle of the tilt axis (default 10).

-MinTiltRangeToFindAngles      Floating point
Minimum range of tilt angles for which data must be available
before trying to solve for tilt angles (default 20).

-BoxSizeXandY   Two integers
X and Y dimensions of the box used to search for a bead, in
unbinned pixels.  Copytomocoms sets this value initially from
max(32, 2 * diameter + 20, 3.3 * diameter + 2)
If images are binned and the box size matches this value, then
the same formula with the binned diameter is used to adjust the
box size.  If the box size has been changed from the initial
value, then an unbinned effective diameter is derived from the
entered box size and a new box size is computed from the formula
with a binned effective diameter.

-RoundsOfTracking    Integer
Number of rounds of tracking through the views.  Tracking pro-
ceeds from low to high tilt on odd rounds and from high to low
tilt on even rounds.

-MaxViewsInAlign     Integer
Maximum number of views to include in the tilt alignment.  Use
this entry to do alignment only on a local subset of views at
nearby tilt angles.  A value at least big enough to include half
the views is recommended.

-RestrictViewsOnRound     Integer
If MaxViewsInAlign is entered, this entry can be used to apply
the restriction on the number of the views in the tilt alignment
on a particular round of tracking.

-UnsplitFirstRound
On the first round, the program will track from the seed view
halfway down to the first view, then halfway up to the last
view, then return to the low views and finish with the high
views.  Use this option to return to the old behavior (prior to
IMOD 4.6.8) of tracking all the way to the first view then
tracking up to the last view.

-InitialBidirectionalViews     Integer
Number of views to track initially around bidirectional starting
point; default is 6.  If tracking starts near the bidirectional
starting point, the program will track half of this number of
views on each side of the starting point before going on to more
negative tilt angles.  Set to 0 to avoid this kind of tracking.
The program assumes a tilt series is bidirection if there is one
separate view group defined at one end of the tilt series.

-LocalAreaTracking
Track subsets of beads in local areas.  The area containing
beads near zero tilt will be divided into subareas, and the sub-
areas will be tracked in order by increasing distance from the
center of the image.  Each subarea will contain a minimum total
first will contain a minimum number that are shared with a more

-LocalAreaTargetSize      Integer
Target size for the local areas.  The program will try to make
typical areas have this size, but some will be bigger to contain

Minimum number of beads in a local area; areas will be expanded
from the target size to contain this minimum (default 8)

Maximum number of beads in a local area; the target size will be
shrunk if possible until no local areas exceed this limit
(default 500)

Each area after the first one tracked will be required to have
at least this many beads shared with areas tracked earlier.

-TrackObjectsTogether
When there is more than one object in the seed model and local
area tracking is not specified, the objects will be tracked sep-
arately unless this option is entered.

Maximum number of views over which to average a bead (default
4).  A running average is kept of the appearance of the bead
over the most recent views examined; this parameter specifies
the maximum number of views averaged.

-LowPassCutoffInverseNm   Floating point
Cutoff radius for a low-pass filter that is applied to all boxes
when read in.  The units are reciprocal nanometers; values
around 0.3-0.4/nm are useful for cryo data sets at a variety of
unbinned pixel sizes.  The falloff (sigma) of the filter is set
to 0.15 times the radius.  The -PixelSize option must be
entered.

-SobelFilterCentering
Use an edge-detecting Sobel filter to refine the centroid-based

-KernelSigmaForSobel      Floating point
Sigma in pixels for gaussian kernel filtering of single bead
before Sobel filtering, which reduces the contribution of noise
to the edge-filtered image.  The default is 0.5 pixels, which is
optimal for relatively low-noise data.  Higher-noise data
requires a higher sigma of around 1.5 when the binned pixel size
is in the 0.6 - 1 nm range, and correspondingly higher values
for smaller pixel sizes.  This option cannot be entered with
-ScalableSigmaForSobel.

-ScalableSigmaForSobel    Floating point
Sigma for gaussian kernel filtering of single beads before Sobel
filtering, as a fraction of the bead diameter.  This filtering
reduces the contribution of noise to the edge-filtered image.
If neither this option nor -KernelSigmaForSobel is entered, the
default sigma is 0.5 pixels, which is optimal for relatively
low-noise data.  Higher-noise data requires a value around 0.12
bead diameters, which can be used with different binnings of
data with a very small unbinned pixel size.  This option cannot
be entered with -KernelSigmaForSobel.

Number of beads to average for the reference for Sobel filter
correlation.  Images will be averaged from already-tracked
nearby views separately for each bead.  If there are not enough
already-tracked views, averages will be combined from multiple
beads to reach the desired number.  If the number of averaged
beads is less than half of this value, a model bead is used
instead.  The average or model is Sobel-filtered and correlated
with the Sobel-filtered image of the single bead.  The default
is 50.

-InterpolationType   Integer
Type of interpolation to use in the scaled Sobel filter: 1 for
linear interpolation, 0 for cubic interpolation, and -1 for
image reduction with an antialias filter instead of with inter-
polation combined with binning.  The default is 0 if the sigma
for kernel filtering is less than 1.5, otherwise 1.

-PositionTrialDiamFrac    Floating point
When the projection of the 3D position from tilt alignment and
the extrapolated position from nearby views differ by more than
this fraction of the bead diameter, the program will try both
positions.  If a bead is found from both starting positions, the
two results will be evaluated by distance from the expected
position and integrated density.  The default is 1.

-MinDiamForParamScaling   Floating point
parameters that depend on bead size to account for binning: the
distance rescue criterion (DistanceRescueCriterion), the post-
fitting rescue criterion (PostFitRescueResidual), the maximum
distance for rescues (MaxRescueDistance), and the minimum resid-
ual criterion for deleting a point (first entry to DeletionCri-
terionMinAndSD).  This option should be entered only if these
parameters are already scaled up from their usual defaults to
account for an unbinned bead size larger than this minimum size.
Copytomocoms does such scaling when this option is present in
the master track command file or added or modified by a batch or
template directive.  Specifically, when the unbinned bead diame-
ter is greater than the minimum, the parameters in the master
command file are scaled up by the ratio of this diameter to the
minimum.  When the ImageBinned entry is greater than 1, Bead-
track scales the parameters back down by a ratio equal to the
maximum of the minimum diameter (this option) and the binned
bead diameter, divided by the unbinned diameter.  Regardless of
binning, if the binned bead size is bigger than this entry, an
absolute minimum residual value required for deleting points
(not modifiable by option) is scaled up by the ratio of the bead
size to this entry.

-PointsToFitMaxAndMin     Two integers
Number of positions to use for extrapolating the bead position
to the next view when no tilt alignment is available, and mini-
mum required to do extrapolation rather than simply taking the
mean of positions on the last few views.  (Defaults 7 and 3).

-DensityRescueFractionAndSD    Two floats
Fraction of mean bead integral, and number of standard devia-
tions below mean, to use as the criterion for when to attempt a

-DistanceRescueCriterion       Floating point
Criterion distance between found position and expected position
for attempting a rescue based on excessive distance.  The dis-
tance should be in unbinned pixels if -MinDiamForParamScaling is
entered, namely if a tilt series was set up in IMOD 4.10.33 or
later, otherwise in binned pixels.

-RescueRelaxationDensityAndDistance      Two floats
Factors by which to adjust (relax) the density criterion when
trying to rescue.  Enter one factor for density rescue and one
for distance rescue.  A value of 1 does not relax the criterion.

-PostFitRescueResidual    Floating point
Criterion distance for deletion of a point after tilt alignment.
Points with residuals greater than this amount will be deleted
on the first pass, and a rescue search performed on the second
pass.  The distance should be in unbinned pixels if -MinDiamFor-
ParamScaling is entered, namely if a tilt series was set up in
IMOD 4.10.33 or later, otherwise in binned pixels.

-DensityRelaxationPostFit      Floating point
Factor by which to relax the density criterion on the second
pass.

-MaxRescueDistance   Floating point
Maximum distance to search from the expected position on the
second pass.  The distance should be in unbinned pixels if -Min-
DiamForParamScaling is entered, namely if a tilt series was set
up in IMOD 4.10.33 or later, otherwise in binned pixels.

-ResidualsToAnalyzeMaxAndMin   Two integers
Maximum and minimum number of changes in mean residual to use in
finding the mean and SD of changes in the mean residual for a
bead as more points have been added.  Default values 9 and 5.

-DeletionCriterionMinAndSD     Two floats
Minimum change in residual, and criterion number of SD's from
the mean residual change, to require for deletion of a point on
pass 1 or 2.  The minimum change should be in unbinned pixels if
-MinDiamForParamScaling is entered, namely if a tilt series was
set up in IMOD 4.10.33 or later, otherwise in binned pixels.

-SetIndexedParameter      Multiple floats
One or more pairs consisting of a parameter number and a value
to set.  "bmr" refers to the analysis of background integrated
densities and of elongation when a point would be eliminated due
to a big mean residual.  "drb" refers to analysis of background
densities when evaluating a density rescue result. Parameters
are:
-1  maxBmrDeltaZ: Maximum delta Z from view for measuring
elongations; default 4.
-2  maxDrbDeltaZ: Maximum delta Z for analyzing background
densities
-3  numBidirRelaxCrit: Number of views around bidirectional
reversal over which to relax the BMR criteria; default is 0.
-4  minzDelzNearZero: Maximum number of views away from the
minimum-tilt view at which to use the shifts near zero tilt;
default is 2.
-5  maxDelzNearZero: Maximum number views from view with seed
point at which to use the shifts near zero tilt; default is 2.
1  bmrLowerElongLim: Elongation below which the BMR criteria
will be raised without measuring on adjacent views; default 1.2.
2  bmrUpperElongLim: Elongation below which the BMR criteria
can be raised after measuring on adjacent views; default 1.35
3  bmrLowElongRaiseFac: Factor by which to raise BMR criteria
when below the lower limit; default 1.5
4  bmrHighElongRaiseFac: Factor by which to raise BMR crite-
ria when between the two limits; default 1.3
5  bmrMaxElongSD: Maximum allowed SD of elongation values
over range of views; default 0.2
median background density required to raise the BMR criteria;
default 8.
7  bmrMaxNumSDaboveMean:  Maximum number of SDs above the
mean elongation allowed for raising the BMR criteria; default 1.
8  drbJustAcceptCrit: After a successful density rescue, just
accept when density is above median background density by this
number of MADNs.  Set to 0 to accept all successful rescues;
default 8.
9  drbJustRejectCrit: After a failed density rescue, just
drop the point when density is below median background density
by this number of MADNs.  Set to 0 to reject all failed rescues;
default 3.
maximum background density required to accept a bead despite a
failed rescue; default 5.
background density below which a successful rescue will be
dropped for density just below drbJustAcceptCrit; default 0.
12  dbrAnyTypeMinMADNs: After any successful rescue, drop the
point when its density is below median background density by
this number of MADNs; default 1.5
mum background density below which a successful rescue will be
dropped for density just above dbrAnyTypeMinMADNs; default 2.
14  tiltIncMinForScaling - Winimum tilt increment for raising
BMR criteria by the ratio of tilt increment to this value;
default 1.5.  Set to 0 to prevent raising the critera.
15  cgEdgeDiamFrac - Width of annulus around bead in which
background value for centroid is measured; default 0.1
16  cgGapDiamFrac - Width of annulus between pixels from which
centroid and background are measured; default 0.
17  relaxBidirFac - Maximum amount by which to raise BMR cri-
teria near a bidirectional reversal.

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

-help (-h) OR -usage
Print help output

OPTIONS FOR TEST OUTPUT
These options are used for program testing and development.

-BoxOutputFile       File name
Root filename for diagnostic output of correlation boxes

-SnapshotViews       List of integer ranges
List of views at which to snapshot model before deletion on
first and second passes.  The models will be named <Output-
Model>.<view #>.<pass #>.

-SaveAllPointsAreaRound   Two integers
Area or object and round at which to save all positions in new
objects.  Enter negative of the area number to exit after fin-
ishing the area.  This option will also enable some debugging
output for that area and round.

-StandardInput
Read parameter entries from standard input.

SEQUENTIAL INPUTS
Image file name

Piece list file name if the file is montaged (or if it is digitized
out of order), otherwise enter a blank line

Name of model file with starting bead coordinates

Name of output model file

List of views to skip over.  Model contours will pass through
these views; points will need to be added by hand afterwards.
Ranges may be entered, e.g. 1,4-6.  Views are numbered from 1.

Angle of rotation of the tilt axis in the images; specifically, the
angle from the vertical to the tilt axis (counterclockwise
positive).

Number of sets of views to treat separately from the main set of
views when automapping the tilt angle and magnification
variables.  Enter 0 if all views can be treated together when
automapping.  These sets would typically be lists of views
that were reshot.

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 individual tilt angle for each view, 1 to specify a
starting and increment tilt, or 0 to read tilt angles from a file

IF you entered 1, next enter the starting and incremental tilt angles
IF you entered -1, enter the tilt angle of each view.  IF you entered
0, enter name of file with tilt angles

The default number of views to group together in solving for tilt
angles, 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.

The default number of views to group together in solving for
magnifications, and the number of ranges of views to group in
some other way.  If you enter a non-zero number of ranges, then
for each one, enter starting and emding view numbers and group
size.  Note that extensive grouping of tilt angle and
magnification variables is desirable, but the grouping should be
adjusted if there are known places where magnification or the
deviation from the ideal tilt angle changes abruptly.

Minimum number of views with bead positions available before trying
to do a tilt alignment.  To skip the tilt alignment computations,
set this to a number higher than the number of views.

Radius for centroid calculation, and 0 if beads are darker or 1 if
they are lighter than background.  The radius need not be a whole
number; e.g., 4.5 is acceptable.

1 to fill in gaps in the seed model, or 0 not to fill in gaps

Maximum size of gap to create in the model.  If a bead cannot be
tracked through some views, the tracking may be resumed as long as
the gap thus created is no larger than this amount.

Minimum range of tilt angles for which data must be available before
trying to find the angle of the tilt axis, and minimum range of
angles required before trying to solve for tilt angles.  Suggested
values are 10 and 20.

X and Y dimensions of the box used to search for a bead
(32,32 suggested)

Maximum number of views over which to average a bead (4 suggested)
A running average is kept of the appearance of the bead over
the most recent views examined; this parameter specifies the
maximum number of views averaged.

Number of positions to use for extrapolating the bead position to
the next view, and minimum required to do extrapolation rather
than simply taking the mean of positions on the last few views.

Fraction of mean bead integral, and number of standard deviations
below mean, to use as the criterion for when to attempt a rescue

Distance in pixels away from expected position at which to attempt
a rescue based on excessive distance

Factors by which to adjust (relax) the density criterion when
trying to rescue.  Enter one factor for density rescue and one for
distance rescue.  A value of 1 does not relax the criterion.

Criterion distance for deletion of a point after tilt alignment.
Points with residuals greater than this amount will be deleted on
the first pass, and a rescue search performed on the second pass.

Factor by which to relax the density criterion on the second pass,
and maximum distance to search from the expected position on this
pass.

Maximum and minimum number of changes in mean residual to use in
finding the mean and SD of changes in the mean residual for a
bead as more points have been added.  Suggested values 9 and 5.

Minimum change in residual, and criterion number of SD's from the
mean residual change, to require for deletion of a point on pass 1
or 2.

HISTORY
Written by David Mastronarde, 1995.  Tilt alignment added 10/6/97.

BUGS
Email bug reports to mast at colorado dot edu.