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