Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

TILTXCORR(1)							   TILTXCORR(1)

NAME
	tiltxcorr - to align a tilt series by cross-correlation

SYNOPSIS
	tiltxcorr

DESCRIPTION

  TILTXCORR uses cross-correlation to find an initial translational alignment
  between successive images of a tilt series.  For a given pair of images, it
  stretches the image with the larger tilt angle perpendicular to the tilt
  axis, by an amount equal to the ratio of the cosines of the two tilt angles
  (cosine stretch).  The stretched image is correlated with the other image,
  and the position of the peak of the correlation indicates the relative shift
  between the images.  There are options to use only a subset of the image, to
  pad the image with a border before correlating, and to taper the image
  intensities down to the average level over some boundary region.  The latter
  feature is particularly important for getting reliable correlation peaks.
  The program also has an option to correlate each image with the sum of
  already-aligned images at lower tilts, a method developed by Christian
  Renken.  In addition, the program can be used to track the centers of
  multiple subareas through the tilt series and produce an IMOD model that can
  be used for fiducial alignment.  The program will reduce the size of images
  larger than 1180 pixels in one dimension by binning them down, i.e. by
  averaging the values in square sets of adjacent pixels (2x3, or 3x3, etc).
  Images are binned by the smallest factor needed to make them 1180 or smaller
  up to a binning of 4, but there is option to set the binning directly.

  Some notes about some of the options:
  
  Filtering: Some high pass filtering, using a small value of Sigma1 such as
  0.03, may be needed to keep the program from being misled by very large
  scale features in the images.  If the images are noisy, some low pass
  filtering with Sigma2 and Radius2 is appropriate (e.g. 0.05 for Sigma2, 0.25
  for Radius2).  If the images are binned, these values specify frequencies in
  the binned image, so a higher cutoff (less filtering) might be appropriate.
  The filter functions produced by these options can be visualized with the
  program Filterplot; see that man page for a full description of their
  effects.
  
  Central peak exclusion: The exclusion of a central peak may be helpful when
  there is fixed noise in the images due to inadequate gain normalization of
  CCD camera images.  Because one image is stretched, this spurious peak can
  actually occur anywhere in an elongated region perpendicular to the tilt
  axis. If the real alignment happens to fall in that streak, then it will be
  ignored as well, and an incorrect alignment will be found.  For this reason,
  this option should be used only when necessary, as it will misalign images
  that are already nearly aligned.
  
  Subareas: Trimming some area off the edges of the images may be helpful if
  those areas are particularly out of focus or contain material with no useful
  features in it.  The area to be used for correlation can be offset from the
  center of the image by specifying starting and ending coordinates of the
  region to correlate instead of the amount to trim off.  The coordinates
  should be chosen from the zero-tilt image; the program will shift the
  specified box closer to the center of the image at higher tilts so that it
  will contain approximately the same features.  By default, the
  transformations will be adjusted to move the tilt axis back to the center of
  the whole image, but there is an option to leave the axis at the center of
  the correlated area instead.  Note that global rather than image-to-image
  transforms are output in this case; see below for details.
  
  Padding: Padding is customarily done to reduce the contribution to the
  correlation from wrapped around features, which occurs when correlation is
  done with Fourier transforms.  Extensive padding does not help with typical
  biological specimens but may be needed for specimens with periodic
  structures, in which case one should pad each edge by half the image size.
  
  Tapering: In contrast, tapering the images down to a mean intensity at their
  edges is very important.  Tapering over as few as 20 pixels may be adequate,
  but fewer artifacts will appear in the correlation with longer tapers (say,
  50 to 100 pixels).
  
  Cumulative correlation: Tiltxcorr has an option to use a cumulative
  correlation method developed by Christian Renken at the National Center for
  the Visualization of Biological Complexity in Albany, N.Y.  With this
  option, the program will take the image at zero tilt as the first reference,
  and correlate it with the image at the next most negative tilt.  It will
  then add the aligned image to the first reference to make the reference for
  the next tilt.  At each tilt, the reference will be the sum of images that
  have already been aligned.  When the most negative tilt angle is reached,
  the procedure is repeated from the zero-tilt view to more positove tilt
  angles.  (If you specify a range of views to correlate that does not pass
  through zero tilt, then this procedure will start at the lowest tilt in the
  specified range.)  There are two options that can be used with this
  procedure.  By default, aligned images are not cosine-stretched before being
  added into the cumulative reference; but the "absstretch" option will add
  images that have been stretched by the inverse of the cosine of the tilt
  angle into the reference.  The "nostretch" option will disable the cosine
  stretching that is used before correlating an image with the reference.

  180-degree tilt series: If the object being viewed is compact rather than
  slab-like and it is tilted close to 90 degrees, then the cosine stretching
  between views is not appropriate.  Use the "nostretch" option in this case.
  With this option, the program will also not attempt to adjust the shifts
  between images to keep the tilt axis in the center, a procedure which fails
  close to 90 degrees.

  Tracking patches: In a completely different mode of operation, the program
  can track the center positions of multiple subareas (patches) through the
  tilt series and produce an IMOD model.  There is no feature detection
  involved here, so the alignment of patches from two successive views is
  averaged over all the image features in the patch.  Patch tracking is
  invoked by entering the -size option to specify the size of the patches.
  The positions of the patches are specified by entering the number of patches
  in X and Y, or by providing a model with scattered points indicating the
  positions of the patch centers.  In the latter case, the points may be on
  any view, but their positions will be transferred by cosine stretching to
  the view nearest to zero tilt, and the tracking will start at that view.
  Note that patches smaller than 1180 pixels will be correlated without
  binning by default, whereas the whole image will typically be binned for
  correlation.  As a result, the patch correlations may be noisier and may
  require either more high-frequency filtering or explicit binning.  If views
  are skipped, there will be no model points on those views and positions will
  be tracked between the views before and after a skipped view.  If the
  transforms used for preliminary alignment of the input stack are supplied,
  then the program will be able to detect when patches contain blank image
  area.  It will either skip a patch when it has too much blank area (more
  that 30%), or it will taper the image data down to the edge of the blank
  area to minimize correlation artifacts.  When a patch is skipped on a view,
  the tracking will be resumed on the next view where the patch has usable
  image data, unless more than 5 views have been skipped.

  Boundary contours: Boundary contours may be used to constrain the region
  being correlated for alignment or the locations tracked by correlation.
  Contours may be drawn on any view but they will be stretched by 1/cosine of
  the tilt angle to determine their position on the zero-tilt view.  When
  correlating whole images to obtain transforms, the boundary contours are
  used in two ways.  First, the minimum rectangular area containing the
  contours at zero tilt is determined; this area is limited by the -border,
  -xminmax and -yminmax options to define the area that will be used for
  correlation.  Second, on each view, the contours are contracted from their
  positions at zero tilt by the cosine of the tilt angle, and the area outside
  the contours is masked out by setting it to the image mean.  The masked
  image is correlated with an unmasked image at the previous tilt.  Multiple
  contours may be drawn, and they may intersect.  If there is only one
  contour, the image intensity inside the unmasked region is tapered down to
  the mean at the edge over the course of 16 pixels, equivalent to running
  Mrctaper on the image.  This tapering may help prevent artifacts due to
  sharp edges, but it is not done if there is more than one contour.  If
  tapering and the inclusion of separated areas are both important, use a
  single contour with a narrow connector between them, but take care that the
  contour does not cross itself.

  Boundary contours are used differently when correlating to track the centers
  of patches.  The program determines the fraction of each patch that is
  within the contours at zero tilt, and then eliminates patches whose
  fractions are less than 0.75.  There is no masking of the image regions that
  fall outside the boundaries in this case.

  Tiltxcorr 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 OR -InputFile   File name
    Input file with images to correlate.  If this option is not entered, the
    first non-option argument will be used for this input file.

 -piece OR -PieceListFile   File name
    Piece list file for reordering the Z values in the stack

 -output OR -OutputFile   File name
    Output file for transformations or for patch tracking model.  If this
    option is not entered, the second non-option argument will be used for
    this input file.

 -rotation OR -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).

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

 -offset OR -AngleOffset   Floating point
    Amount to add to all entered tilt angles.  If the specimen is
    significantly tilted at zero tilt, then the amount of cosine stretching
    become inaccurate at high tilt.  Sharper correlations can be obtained by
    adding this angle offset, which is the same as the offset needed in
    Tiltalign or Tilt to make the specimen flat in the reconstruction.

 -radius1 OR -FilterRadius1   Floating point
    Low spatial frequencies in the cross-correlation will be attenuated by a
    Gaussian curve that is 1 at this cutoff radius and falls off below this
    radius with a standard deviation specified by FilterSigma2.  Spatial
    frequency units range from 0 to 0.5.  Use FilterSigma1 instead of this
    entry for more predictable attenuation of low frequencies.

 -radius2 OR -FilterRadius2   Floating point
    High spatial frequencies in the cross-correlation will be attenuated by a
    Gaussian curve that is 1 at this cutoff radius and falls off above this
    radius with a standard deviation specified by FilterSigma2.

 -sigma1 OR -FilterSigma1   Floating point
    Sigma value to filter low frequencies in the correlations with a curve
    that is an inverted Gaussian.  This filter is 0 at 0 frequency and decays
    up to 1 with the given sigma value.  However, if a negative value of
    radius1 is entered, this filter will be zero from 0 to |radius1| then
    decay up to 1.

 -sigma2 OR -FilterSigma2   Floating point
    Sigma value for the Gaussian rolloff below and above the cutoff
    frequencies specified by FilterRadius1 and FilterRadius2

 -exclude OR -ExcludeCentralPeak
    Exclude central correlation peak due to fixed pattern noise in the images.
     This option will misalign images that are already nearly aligned.

 -shift OR -ShiftLimitsXandY   Two integers
    Limit on distance in X and Y to search for correlation peak, in pixels. 
    This option can be used to prevent a spurious correlation peak outside
    these limits from giving a bad alignment.  If the program does not find an
    actual peak, i.e. a pixel higher than all its neighbors, within these
    limits, then it will give a zero shift.

 -border OR -BordersInXandY   Two integers
    Number of pixels to trim off each edge in X and in Y (the default is to
    use the whole image).

 -xminmax OR -XMinAndMax   Two integers
    Starting and ending X coordinates of a region to correlate, based on the
    position of the region at zero tilt.  This entry will override an X border
    value entered with BordersInXandY.

 -yminmax OR -YMinAndMax   Two integers
    Starting and ending Y coordinates of a region to correlate.  This entry
    will override a Y border value entered with BordersInXandY.

 -boundary OR -BoundaryModel   File name
    Model file with boundary contours around areas to correlate.  When
    correlating whole images to obtain transforms, the area outside the
    contours is masked out; when tracking patches, only patches inside the
    contours will be tracked (see above for details).

 -objbound OR -BoundaryObject   Integer
    The number of the object to use from the model with boundary contours. 
    The default is to use all the contours in closed-contour objects, but with
    this option only the given object will be used.

 -binning OR -BinningToApply   Integer
    Binning to apply to the trimmed, padded images.  By default, a binning
    will be selected that makes the maximum dimension of the trimmed, padded
    image be no more than 1180 pixels, up to a binning of 4.  Binning will
    increased above 4 only to the extent needed to make the image fit in the
    arrays.  This default behavior might result in more binning than desired,
    and the binning might change when the amount of trimming is changed.  This
    option allows direct control of the binning instead.

 -leaveaxis OR -LeaveTiltAxisShifted
    Leave the tilt axis in the center of the region that was correlated; the
    default is to shift it back to the center of the whole image.  With this
    option, the program will output global transforms ready to use in
    Newstack, rather than the transforms relating one view to the next that
    would need to be converted to global transforms with Xftoxg.  The
    reason for this difference is that the transforms must contain a net shift
    away from the center of the image, which would be lost in Xftoxg.

 -pad OR -PadsInXandY   Two integers
    Number of pixels to pad images in X and in Y.  The default is 5% of the
    image dimensions up to 20 pixels.

 -taper OR -TapersInXandY   Two integers
    Number of pixels to taper images in X and in Y.  The default is 10% of the
    image dimensions up to 100 pixels.

 -views OR -StartingEndingViews   Two integers
    Starting and ending view numbers, numbered from 1, for doing a subset of
    views.

 -skip OR -SkipViews   List of integer ranges
    List of views to skip, while maintaining alignment across skipped views. 
    The program will not find the transform for aligning a listed view to the
    previous one.  When a view is skipped, the following view will be aligned
    to the last unskipped view and a unit transform will be output for the
    skipped view.  With patch tracking, no model points will be placed on the
    skipped views.  Comma-separated ranges of views (numbered from 1) can be
    entered.  The default is to use all of the views.

 -break OR -BreakAtViews   List of integer ranges
    List of views to break alignment at.  This option is like "-skip" in that
    no transform is found for aligning a listed view to the previous one and a
    unit transform is written for the listed view.  However, the following
    view will be aligned to the listed view, and nothing will be aligned to
    the previous view.  This breaks the chain of alignment through the series
    of views.  This option cannot be used with patch tracking.

 -cumulative OR -CumulativeCorrelation
    Use this option to add up previously aligned pictures to get the reference
    for the next alignment.  Alignments will start at low tilt and work up to
    high tilt.

 -absstretch OR -AbsoluteCosineStretch
    Stretch each image added into the cumulative sum by 1 over the cosine of
    its tilt angle.

 -nostretch OR -NoCosineStretch
    Do not do any cosine stretching for correlations or for accumulating into
    the reference (this option overrides AbsoluteCosineStretch).

 -iterate OR -IterateCorrelations   Integer
    Number of iterations of the correlation.  After finding the pixel with the
    peak correlation, the program achieves subpixel accuracy by fitting a
    parabola to the correlation values in X or Y and interpolating from the
    parabola.  If the correlation is iterated, this subpixel shift is applied
    to the cosine-stretched image before the correlation, which tends to shift
    the peak to being exactly on a pixel.  As a result, the shift has slightly
    higher subpixel accuracy than when it is derived by parabolic
    interpolation.  The program will terminate the iterations if the remaining
    fractional shift is less than 0.02 pixel or if a lower correlation value
    is obtained than on the previous iteration.  In the latter case it reverts
    to the shift that gave the highest correlation.  Two or three iterations
    are generally sufficient.  Iteration is not programmed efficiently, so
    computation time will be proportional to the number of iterations.

 -size OR -SizeOfPatchesXandY   Two integers
    Size in X and Y of patches to track by correlation.  This option will
    cause the program to track a set of patches of the given size from the
    starting view to the high tilt view in each direction, and to output the
    positions of the patch centers in an IMOD model.  By default, patches will
    overlap in each direction by the default value for the -overlap option
    (see below).  You can change the overlap with the -overlap option, specify
    the number of patches directly with the -number option, or enter a model
    of points to track with the -seed option, but you can enter only one of
    these options.  Patch tracking cannot be used with cumulative correlation.

 -number OR -NumberOfPatchesXandY   Two integers
    Number of patches in X and Y to track by correlation.  The given number of
    patches will be regularly spaced apart and fill the X and Y ranges of the
    trimmed image area.

 -overlap OR -OverlapOfPatchesXandY   Two integers
    Fractional overlap in X and Y between patches that are tracked by
    correlation.  These overlaps are used to determine the number of patches
    when -number is not entered.  The default, 0.33, 0.33, which will make
    patches that overlap by one-third in each direction.  A value of 0 will
    result in no overlap, and values less than 0 will result in space between
    the patches.

 -seed OR -SeedModel   File name
    Input model file with center points to track by correlation.  Only points
    whose patches fit entirely within the trimmed image area at zero degrees
    will be tracked.  See above for details.

 -objseed OR -SeedObject   Integer
    Number of the object from the seed model with the points for tracking
    patches.  The default is to use all objects containing scattered points;
    with this option only the given object will be used.

 -length OR -LengthAndOverlap   Two integers
    When tracking patches by correlation, the default is to produce one
    contour per patch passing through the whole set of views.  With this
    option, the contour will be broken into pieces of the given length, and
    overlapping by at least the given amount.  If the centers of the tracked
    areas wander enough to give a bad fit when the resulting model is used in
    Tiltalign, then breaking the contours into overlapping pieces might
    improve the fit.  Some overlap is needed to use the model in Tiltalign
    (1).

 -prexf OR -PrealignmentTransformFile   File name
    File with transformations applied to align the images being used for patch
    tracking.  With the shift information in these transforms, each patch is
    evaluated for whether it contains blank image area because of the
    shifting.  Patches that are more than 30% blank will not be tracked
    further, and patches with some blank area less than this amount will be
    tapered down to the edge of the blank area.

 -imagebinned OR -ImagesAreBinned   Integer
    The current binning of the images relative to the unaligned stack.  This
    entry is needed to scale the transforms supplied with the -prexf option if
    the binning is not 1.

 -test OR -TestOutput   File name
    Specify a filename with this option to have two padded, tapered images and
    the cross-correlation saved for every pair of images that are correlated.

 -verbose OR -VerboseOutput
    Output diagnostic information

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


  If there are no command-line arguments, Tiltxcorr takes sequential input
  the old way, with the following entries:
  
  Image input file

  Piece list file for reordering the Z values in the stack, or Return
  if none

  Output file for F transforms
  
  -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
  
  Angle of rotation of the tilt axis in the images; specifically, the
  angle from the vertical to the tilt axis (counterclockwise
  positive).

  Filter parameters to filter the correlation, or / for no filter
  (Enter values of Sigma1, Sigma2, Radius1, Radius2 just as for
  ENHANCE.)

  1 to exclude a central correlation peak due to fixed pattern noise
  in the images, or 0 not to
  
  Nymber of pixels to trim off each side in the X and Y dimensions, or /
  to use the whole image area
  
  Borders (in pixels) with which to pad images in the X and Y dimensions,
  or / for the default, which is 5% of the image dimensions up to 20
  pixels
  
  Distances in pixels over which to taper image intensities down to the
  mean at the edges, in the X and Y dimensions.  Enter / for the default,
  which is 10% of the image dimensions up to 100 pixels

  Starting and ending view #'s (first is 1), or / for all views
  
  
HISTORY
  Written by David Mastronarde 10/6/98