beadtrack(1)                General Commands Manual               beadtrack(1)



NAME
       beadtrack - Tracks fiducial gold particles through a tilt series

SYNOPSIS
       beadtrack  options

DESCRIPTION
       Beadtrack will track selected fiducial gold beads through a series of
       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
       about bead positions to deduce a projected position for each bead on
       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-
       bly refined because of the additional information about other beads on
       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
       that bead, and of others if necessary (see the AverageBeadsForSobel
       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-
       mean-squared error, and which beads have been deleted or added back.
       After doing all views, the program outputs a summary of which views are
       missing for each bead.

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-
              beadsurfs(1) to determine which of two surfaces each bead is on.
              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)

       -CentroidRadius      Floating point
              Radius for centroid calculation.  The radius need not be a whole
              number and should be somewhat larger than the bead radius.
              Either this option or BeadDiameter must be entered, but not
              both.  If this option is entered, the diameter will be computed
              as 2 * radius - 3, then adjusted for binning, and the radius
              will be taken as (adjusted diameter + 3) / 2.

       -BeadDiameter   Floating point
              Actual diameter of beads in pixels in the original stack, before
              any binning.  If CentroidRadius is entered instead, the unbinned
              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.

       -LightBeads
              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
              the unbinned bead diameter to
                 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
              number of beads (given by MinBeadsInArea), and areas after the
              first will contain a minimum number that are shared with a more
              central area (given by MinOverlapBeads)

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

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

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

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

       -MaxBeadsToAverage   Integer
              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
              bead positions.

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

       -AverageBeadsForSobel     Integer
              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
              Minimum bead diameter, in binned pixels, for adjusting four
              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
              rescue based on bead density.

       -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
                 6  bmrMinWsumMADNratio: Minimum number of MADNS above the
              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.
                10  drbAcceptMinMADNS: Minimum number of MADNs above median
              maximum background density required to accept a bead despite a
              failed rescue; default 5.
                11  drbRejectMaxLowMADNS: Number of MADNs above median maximum
              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
                13  drbRejectMaxHighMADNS: Number of MADNs above median maxi-
              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
          based on bead density.

       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.



IMOD                                4.11.0                        beadtrack(1)