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. The program will reduce
the size of images larger than 1024 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 1024 or smaller.
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 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.
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 correlated area instead.
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.
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).
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.
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.
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
Image file to correlate.
-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.
-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)
-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.
-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.
-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.
-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 to correlate; the default is all views.
-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).
-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.
-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