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