tiltxcorr(1) General Commands Manual tiltxcorr(1)
NAME
tiltxcorr - to align a tilt series by cross-correlation
SYNOPSIS
tiltxcorr [options] input_file output_file
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 perpendic-
ular 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 corre-
lated with the other image, and the position of the peak of the corre-
lation indicates the relative shift between the images. There are
options to use only a subset of the image, to pad the image with a bor-
der before correlating, and to taper the image intensities down to the
average level over some boundary region. The latter feature is partic-
ularly 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. When correlating whole images, the pro-
gram will reduce the size of images larger than 1250 pixels in one
dimension by binning them down, i.e. by averaging the values in square
sets of adjacent pixels (2x3, or 3x3, etc), although reduction with
antialias filtering can be specified instead. Images are binned by the
smallest factor needed to make them 1250 or smaller up to a binning of
4, but there is an option to set the binning directly.
The program is also useful for cross-correlation alignment of untilted
images such as serial sections and subframes recorded when acquiring an
image from a direct electron detection camera.
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 fil-
tering) 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.
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 fea-
tures. 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 peri-
odic 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).
CENTRAL PEAK EXCLUSION: The exclusion of a central peak may be helpful
when there is fixed noise in the images due to inadequate gain normal-
ization of CCD camera images. Because one image is stretched, this
spurious peak can actually occur anywhere in an elongated region per-
pendicular to the tilt axis. As of IMOD 4.6.31, this option has become
much more reliable and effective, since a peak will be excluded only if
certain conditions are met. First, the program tests whether the peak
center is within 0.3 pixels of the center line of the elongated region,
whether this peak is narrower than the highest peak outside the exclu-
sion region in at least one direction, and whether that highest eligi-
ble peak is sufficiently stronger than the next-highest one. If these
tests are passed, the program computes a correlation between unbinned,
unstretched images with no high-frequency filtering and measures the
width of first and second peaks. If the first peak is narrow enough,
and sufficiently narrower than the second peak, then the highest eligi-
ble peak position (in the original correlation) is used.
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 stretch-
ing 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 pro-
gram 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 succes-
sive 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 scat-
tered 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
1250 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-fre-
quency 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 min-
imize 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.
FITTING TO PREDICTED POSITIONS: When patch tracking, this fitting aims
to identify and eliminate aberrant points. It is done after finding
all patches on a view by computing a predicted position for each patch
from the locations found on several preceding views. Rather than doing
a single linear fit to all the patches, which could include substantial
errors from distortion over large areas, the program divides the
patches into domains and does a fit within each domain. Outliers are
identified by dropping out the worst-fitting points and finding a point
where all the ones left out have a small probability of belonging in
the fit to rest. The domains overlap by at least two positions and, in
the overlap with another domain, only the interior outliers are consid-
ered for elimination. (Each point is considered only once.) For each
of those points, alternative cross-correlation peaks are evaluated for
whether they would give sufficiently less error and substituted, and if
not, the point is dropped. The domain size can be specified or set to
0,0 to disable this fitting.
STRUCTURE MEASURE FOR ELIMINATING AND EXPANDING PATCHES: There are two
features that use a measure of structure: one eliminates patches from
tracking that have too little structure, and the other expands patches
so that they all have a certain minium amount of structure. The struc-
ture measure is based on the local standard deviation (SD) in reduced
images. To find a reduction that makes this SD be dominated by fea-
tures rather than noise, the program tries a series of reductions
(referred to as binning, but antialiased reduction is used). At each,
it measure the SD in a box around each pixel. The higher SD values may
then be accentuated by applying a sigmoidal function (this is done by
default when using the measure for eliminating patches). At each
reduction tested, this structure measure is averaged over the reduced
pixels in each patch. The mean and SD is computed from these averages
and the SD is divided by the mean minus the 1 percentile value of the
structure measure. The reduction is chosen that achieves a high frac-
tion of the maximum value of this modified coefficient of variation.
(The output for each reduction shows the minimum and maximum, mean, and
SD of the average patch measures, the minimum and 1 percentile value of
the measure, ratio of SD to mean of the average patch measures, ratio
with the 1 percentile value subtracted from the mean (all of the pre-
ceding values multiplied by 100), and the ratio of maximum to minimum
average patch measures, without and with the 1 percentile value sub-
tracted.)
PATCH ELIMINATION: Patches can be eliminated using the structure mea-
sure computed at the starting tilt angle. A kernel histogram is com-
puted from the summed structure measures for each patch, and the mode
is taken to be the highest peak in that histogram, or the second high-
est one if it at a higher measure value and not much lower than the
highest peak. The criterion for eliminating a patch is expressed as a
fraction of the mode. Fractions around 0.7 have been found to be use-
ful. If patch expansion is being used, the criterion is applied to
patches that cannot be expanded enough to meet the criterion for expan-
sion, using the summed structure measure at the maximum feasible size.
PATCH EXPANSION: To enable patch expansion, the structure measure at
the chosen reduction is summed for all patches and a particular per-
centile point in the distribution is taken as the summed structure
value to match. At the starting tilt, patches are expanded by up to
the maximum amount and moved away from the edge to allow this, if nec-
essary. The patches are retained even if they do not match that struc-
ture value, unless the -struct option is entered and the expanded patch
does not meet the separate criterion just discussed. Patches dropped
at the starting tilt are simply eliminated. If expansion is also spec-
ified to occur at higher tilts, the summed measure is computed for each
patch and the patch is expanded up to the maximum amount, if possible,
to meet the summed structure value to match. In this case, patches
near the edge can no longer be moved, which may prevent further growth
before the maximum is reached. By default, patches which fall short of
the match value by too much (a fraction specified by the the -drop
option) will be skipped on the particular tilt.
Patch expansion has been found to give better results on some data sets
and not others. Eliminating patches with too little structure may be
more effective than expanding.
FINDING WARPING TRANSFORMATIONS: In a variation on patch tracking, the
program can output the local patch displacements as a set of warping
transformations that align each section to the previous one. This fea-
ture is not for tilt series but for other serial images that need to be
aligned with warping. With tilt series patch tracking, the tracking
area moves through the views to follow a piece of image, whereas when
finding warp transformations, the tracking area is in the same position
on every section, either on a regular grid or as defined by a seed
model. The format of warping transformations is described in the docu-
mentation for library libiwarp.
BOUNDARY CONTOURS: Boundary contours may be used to constrain the
region being correlated for alignment or the locations tracked by cor-
relation. When used with tilt series, contours may be drawn on any
view but they will be stretched by 1/cosine of the tilt angle to deter-
mine 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 correla-
tion. 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 sepa-
rated areas are both important, use a single contour with a narrow con-
nector 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. For a tilt series, the program determines the
fraction of each patch that is within any of the contours (where all
contours are projected onto the zero tilt view), 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. When
finding warping transformations, the boundary contour used at a partic-
ular section is taken from the nearest section with a boundary contour.
Thus, it is useful to draw boundary contours at multiple sections in
the stack, whenever the region suitable for tracking changes. The
patches are evaluated for inclusion separately on every section, using
the contours appropriate for that section.
OPTIONS
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 -). Options can be
abbreviated to unique letters; the currently valid abbreviations for
short names are shown in parentheses.
Input and Output Specification
These options specify input and output files and properties of the
input
-input (-inp) 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 (-pie) OR -PieceListFile File name
Piece list file for reordering the Z values in the stack
-reference (-ref) OR -ReferenceFile File name
Input file containing an image to use as a reference. Each view
from the main input image file will be aligned with this refer-
ence image, which will be assumed to be at zero tilt. The out-
put file will contain a linear transform for every view in the
input file; if a subset of views is specified with -views or
some views are skipped, unaligned views will be given a unit
transform. This option cannot be used with cumulative correla-
tions, patch tracking, or when finding warping.
-rview (-rv) OR -ReferenceView Integer
View number of image to use in reference file, numbered from 1.
-output (-ou) 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 (-ro) 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 (-f) OR -FirstTiltAngle Floating point
Tilt angle of first view, in degrees. Use this option together
with TiltIncrement.
-increment (-inc) OR -TiltIncrement Floating point
Increment between tilt angles, in degrees. Use this option
together with FirstTiltAngle.
-tiltfile (-ti) OR -TiltFile File name
Use this option if tilt angles are in a file, one per line.
-angles (-ang) OR -TiltAngles Multiple floats
Use this option to enter the tilt angles for each view individu-
ally, in degrees. (Successive entries accumulate)
-offset (-of) 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.
-reverse (-rev) OR -ReverseOrder
Reverse order of processing when all views have same tilt angle.
Specifically, this will cause the program to start with the last
view at minimum tilt instead of the first one.
-prexf (-pre) OR -PrealignmentTransformFile File name
File with transformations applied to align the images being used
for patch tracking. With the shift information in these trans-
forms, 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 (-im) 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.
-pixel (-pix) OR -PixelSize Floating point
Pixel size of unbinned images in nanometers.
-unali (-un) OR -UnalignedSizeXandY Two integers
The full size of the unaligned stack that was transformed to
create the images being aligned with patch tracking. This entry
is needed if an output size was specified when creating the
stack being aligned and if transforms are supplied with the
-prexf option.
General Options Preparing for Correlations
These options specify
-binning (-bi) OR -BinningToApply Integer
Binning or other reduction to apply to the trimmed, padded
images. Ordinary binning is used unless the -antialias option
is given. By default, a reduction will be selected that makes
the maximum dimension of the trimmed, padded image be no more
than 1250 pixels, up to a reduction of 4. Reduction will be
increased above 4 only to keep the reduced image within a size
of about 4K, up to a reduction of 16. This default behavior
might result in more reduction than desired, and the reduction
might change when the amount of trimming is changed. This
option allows direct control of the reduction instead and also
allows a reduction up to 32.
-antialias (-ant) OR -AntialiasFilter Integer
Type of antialiasing filter to use for image reduction instead
of binning. Antialiasing becomes important when the images con-
tain a strong noise component at the high frequencies being
eliminated by the image reduction. Ordinary binning reduces
aliasing, but not as much as these filters do. As in New-
stack(1), the available types here are:
2: Blackman - fast but not as good at antialiasing as slower
filters
3: Triangle - fast but smooths more than Blackman
4: Mitchell - good at antialiasing, smooths a bit
5: Lanczos 2 lobes - good at antialiasing, less smoothing
than Mitchell
6: Lanczos 3 lobes - slower, even less smoothing but more
risk of ringing
-radius1 OR -FilterRadius1 Floating point
Low spatial frequencies in the cross-correlation will be attenu-
ated by a Gaussian curve that is 1 at this cutoff radius and
falls off below this radius with a standard deviation specified
by -sigma2 or -nmsig2. Spatial frequency units range from 0 to
0.5. Use -sigma1 or -nmsig1 instead of this entry for more pre-
dictable attenuation of low frequencies.
-radius2 OR -FilterRadius2 Floating point
High spatial frequencies in the cross-correlation (after bin-
ning, if any) will be attenuated by a Gaussian curve that is 1
at this cutoff radius in reciprocal pixels and falls off above
this radius with a standard deviation specified by -sigma2 or
-nmsig2.
-nmrad2 (-nmr) OR -Radius2InvNanometers Floating point
This entry entry specifies the high-frequency cutoff of the
Gaussian filter as a periodicity in nanometers. This option and
-radius2 cannot be entered together. The pixel size must be
entered.
-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 fre-
quency and decays up to 1 with the given sigma value, specified
as reciprocal pixels after binning, if any. However, if a nega-
tive value of -radius1 is entered, this filter will be zero from
0 to |radius1| then decay up to 1.
-nmsig1 OR -Sigma1InvNanometers Floating point
This entry specifies the sigma value for the inverted Gaussian
low-frequency filter as a periodicity in reciprocal nanometers.
This option and -sigma1 cannot be entered together. The pixel
size must be entered.
-sigma2 OR -FilterSigma2 Floating point
Sigma value for the Gaussian rolloff below and above the cutoff
frequencies specified by -radius1 and -radius2 or -nmrad2, spec-
ified as reciprocal pixels after binning, if any.
-nmsig2 OR -Sigma2InvNanometers Floating point
This entry specifies the sigma value for the Gaussian rolloff
below and above the cutoff frequencies as a periodicity in
reciprocal nanometers. This option and -sigma2 cannot be
entered together. The pixel size must be entered.
-border (-bor) OR -BordersInXandY Two integers
Number of pixels to trim off each edge in X and in Y, in pixels
of the input stack. The default is 0,0 to use the whole image,
but some trimming should be used with patch tracking.
-ubborder (-ubb) OR -UnbinnedBordersXY Two integers
Number of pixels to trim off each edge in X and in Y, in
unbinned pixels of the raw stack (i.e., the entry will be
divided by the -imagebinned entry). The default is 0,0 to use
the whole image, but some trimming should be used with patch
tracking. This option cannot be entered with -border.
-xminmax (-x) OR -XMinAndMax Two integers
Starting and ending X coordinates of a region to correlate,
based on the position of the region at zero tilt, in pixels of
the input stack. This entry will override an X border value
entered with -border or -ubborder.
-yminmax (-y) OR -YMinAndMax Two integers
Starting and ending Y coordinates of a region to correlate.
This entry will override a Y border value entered with Border-
sInXandY.
-ubxmm (-ubx) OR -UnbinnedXMinAndMax Two integers
Starting and ending X coordinates of a region to correlate,
based on the position of the region at zero tilt, in unbinned
pixels of the raw stack (i.e., the entry will be divided by the
-imagebinned entry). This entry will override an X border value
entered with -border or -ubborder. It cannot be entered with
-xminmax.
-ubymm (-uby) OR -UnbinnedYMinAndMax Two integers
Starting and ending Y coordinates of a region to correlate, in
unbinned pixels of the raw stack (i.e., the entry will be
divided by the -imagebinned entry). This entry will override a
Y border value entered with -border or -ubborder. It cannot be
entered with -yminmax.
-pad OR -PadsInXandY Two integers
Number of pixels to pad images on each side in X and in Y,
before binning. With no padding, shifts greater than 50% of the
image size will not be treated correctly. Each 1% of padding
allows proper treatment of shifts more than 50% by an additional
2% of image size. The default is 5% of image dimensions for
patch tracking or finding warping, or 10% for regular correla-
tions, allowing shifts up to 70% of the image size to be deter-
mined.
-taper (-tap) OR -TapersInXandY Two integers
Number of pixels to taper images in X and in Y. The default is
10% of the image dimensions.
General Cross-correlation Options
These options govern cross-correlations in all situations
-ccc (-cc) OR -CorrelationCoefficient
Compute a normalized cross-correlation coefficient at the 10
highest correlation peaks and pick the peak with the highest
coefficient. This computation requires 5 Fourier transforms
instead of 3, because filtered images must be used for computing
the correlation coefficient.
-iterate (-it) 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.
-shift (-sh) OR -ShiftLimitsXandY Two integers
Limits on distance in X and Y to search for correlation peak, in
pixels before binning is applied internally. This option can be
used to prevent a spurious correlation peak outside these limits
from giving a bad alignment. As of IMOD 4.6.31, the peak must
be located within an ellipse whose axes are defined by the lim-
its in X and Y. 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. If cumulative correlations are
being used, the program will seek a peak within this distance of
the peak for the previous view and assign that view's shift
instead of zero if no peak is found. This option cannot be
entered together with -axial.
-axial (-ax) OR -AxialShiftLimits Two integers
Limits on distance perpendicular and parallel to tilt to search
for correlation peaks, in unbinned pixels of the raw stack if
-imagebinned is entered. This option can be used to prevent a
spurious correlation peak outside these limits from giving a bad
alignment. This entry would not need to be changed if the bin-
ning of the input stack is changed. It can be used to enter
invariant shifts even when there is no tilting, provided -rota-
tion is not entered or is 0; in that case the two values specify
shifts in X and Y. This option cannot be entered together with
-shift.
-rect (-rec) OR -RectangularLimits
With this option, the -shift option works as it did before IMOD
4.6.31, requiring a peak to be within the rectangle defined by
the limits in X and Y. With the -axial option, the peaks would
be constrained to a rectangle after rotating the tilt axis to
the Y axis, instead of to an ellipse.
Options for Specifying Subsets of Views or Area
These options allow processing in restricted areas and over a subset
of views.
-boundary (-bou) 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 (-objb) 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-con-
tour objects, but with this option only the given object will be
used.
-skip (-sk) 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 (-br) 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 tilt series patch tracking, but
can be used when finding warping.
-views (-vi) OR -StartingEndingViews Two integers
Starting and ending view numbers, numbered from 1, for doing a
subset of views.
Whole-image Correlation Options
These options apply when using whole images for coarse tilt series
alignment
-exclude (-exc) OR -ExcludeCentralPeak
Exclude a central correlation peak caused by fixed pattern noise
in the images. In tilted images, these peaks can occur anywhere
within an extended, narrow strip perpendicular to the tilt axis.
A peak in this region will now be excluded only if conditions
are met both by this peak and by the highest peak outside this
region, as described above.
-central (-ce) OR -CentralPeakExclusionCriteria Three floats
This option specifies three of the criteria applied when decid-
ing whether to exclude a peak at (0, 0): the minimum ratio of
the second to the third peak strength (default 3); the absolute
width of the central peak in the unbinned, unstretched correla-
tion (default 1.5); and the minimum ratio of the second to the
first peak width (default 1.6).
-leaveaxis (-lea) OR -LeaveTiltAxisShifted
Leave the tilt axis in the center of the region that was corre-
lated; 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 trans-
forms relating one view to the next that would need to be con-
verted 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.
-cumulative (-cu) 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 (-ab) OR -AbsoluteCosineStretch
Stretch each image added into the cumulative sum by 1 over the
cosine of its tilt angle.
-nostretch (-no) OR -NoCosineStretch
Do not do any cosine stretching for correlations or for accumu-
lating into the reference (this option overrides Absolute-
CosineStretch).
-search (-sea) OR -SearchMagChanges
Search for the magnification factor that gives the highest cor-
relation coefficient at one or more views. This factor will be
incorporated into the transformation for the respective view.
If a maximum value of the correlation coefficient is not found
within the allowed range (specified with the -mag option), a
magnification of 1 is used. This option cannot be used together
with rotation scan, cumulative correlation, patch tracking, or
when finding warping.
-changes (-ch) OR -ViewsWithMagChanges List of integer ranges
List of views at which to search for magnification changes.
Ranges are allowed. The default is to do all views.
-mag (-m) OR -MagnificationLimits Two floats
Lower and upper limits for size change when searching for magni-
fication factors. The default is 0.9,1.1.
-scan (-sca) OR -ScanRotationMaxAndStep Two floats
Either the maximum angle and angular step size at which to apply
rotation in order to estimate the best rotation; or a single
rotation angle to apply and a 0 step size. With a positive step
size to estimate rotation, the program does a coarse scan just
at the given interval from the negative to positive maximum
angle, then estimates the best rotation by interpolation. This
is unlike the magnification search, which reduces its step size
to refine the estimate. The final correlation is done at the
interpolated angle. With a step size of 0, the angle given as
the maximum (which can be negative) is applied before correlat-
ing. The resulting transformation incorporates the rotation in
either case. This option cannot be used together with magnifi-
cation search, cumulative correlation, patch tracking, or when
finding warping.
-second (-sec) OR -SecondPeakBoxSize Two integers
Report on the second peak position if it is within a box of the
given length and width before binning, centered on the first
peak and with its width along the tilt axis and its length per-
pendicular to the tilt axis.
Options for Patch-based Correlations
These options apply when using whole images for coarse tilt series
alignment
-size (-siz) 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 direc-
tion, 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.
-ubsize (-ubs) OR -UnbinnedPatchSizeXY Two integers
Size in X and Y of patches to track by correlation, in unbinned
pixels of the raw stack (i.e, entered values will be divided by
the -imagebinned entry). This option cannot be entered with
-ubsize.
-varying (-vary) OR -VaryingToPatchSizeXY Two integers
Set up patch positions as if the patch size was the given value,
in unbinned pixels. This option is useful for comparing align-
ment results between different patch sizes, because it prevents
the area covered from become smaller with larger patches, which
would give a better alignment fit simply due to the smaller
area.
-number (-nu) 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 (-ov) 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 (-see) 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 (-objs) 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.
Options for Tilt Series Patch Tracking
These options are specific to patch tracking for tilt series align-
ment
-length (-len) 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).
-struct (-st) OR -MinStructureModeFrac Floating point
Skip patches with a summed structure measure less than the given
fraction of the mode of this measure. See description above.
-expand (-exp) OR -MaxPatchExpansions Two floats
Maximum linear extents by which to expand patches at the start-
ing tilt and at higher tilts. The first value must be greater
than 1 to enable this analysis; they must both be greater than 1
to apply the analysis at higher tilts. See description above.
-percentile (-pe) OR -PercentileToMatch Floating point
Percentile point in distribution of summed structure measures
for patches to match when expanding patches. The default is 50,
which means that 50% of patches fall below this point and might
be expanded.
-drop (-dr) OR -TiltedExpandDropFrac Floating point
Fraction of summed structure criterion below which a patch that
cannot be expanded to match the criterion on higher tilts will
be dropped, The default is 0.7.
-target (-tar) OR -TargetPixelMinAndMax Two floats
Minimum and maximum pixel sizes in nanometers to which to reduce
images for structure analysis. If structure analysis is being
done because either the -expand or -struct option is entered,
and the -sdbin option is not entered with a list of reductions,
a set of reductions will be set up to span the range of reduced
pixel sizes between these target values. This option cannot be
entered with -sdbin. An unbinned pixel size must be entered.
The default is 0.2 and 5 nm, although the lower limit has no
effect if it is less than the pixel size of the input file.
-variation (-vari) OR -FractionOfMaxVariation Floating point
This fraction determines what reduction is used for measuring
structure in patches. The variation among patches is measured
for all reductions tested, and the reduction is chosen that
given the given fraction of the maximum variation seen.
-scurve (-scu) OR -SigmoidPowerAndHalfRise Two floats
Exponent to apply and half-rise point for a sigmoidal scaling of
SD values computed at each pixel to produce the structure mea-
sure. The exponent should be bigger than 1 and determines the
slope of the sigmoid at its half-rise point. The second value
can be between 0.1 and 0.9 to specify the fraction of the range
at which the sigmoid has risen half-way. With a negative value,
a kernel histogram is computed from a sample of SD values and
the mode is taken to be the position of the highest peak, or of
the second highest peak if it is at a higher SD value and still
relatively strong. The median absolute deviation (MAD) from
this mode is computed, and the half-rise point is set at the
mode plus the entered value times the MAD (e.g., if -1 is
entered, the half-rise point is at mode minus MAD.) The default
is no sigmoid scaling (1,0.5) unless the -struct option is
entered, in which case the default values are 4 and -1. The
sigmoid equation for a range of 0 to 1 in X and Y (from Timofey
Prodanov) is ^ 1 / (1 + ((h / x) * (1 - x) / (1 - h))**p) ^
where h is the half-rise and p is the power.
-box OR -SdReducedBoxSize Integer
Box size for measuring local SD in reduced images when analyzing
structure. This is the size in the reduced image; the default
is 6 pixels.
-sdbin (-sd) OR -SdBinList List of integer ranges
List of reductions at which to compute local SDs. The list need
not be in order.
-domains (-do) OR -LocalDomainSizesXandY Two integers
Number of local patches in X and Y for fitting to predicted
positions (see above). The default is 6,6; enter 0,0 to skip
the prediction fitting.
-prob (-pro) OR -CriterionProbabilities Two floats
Two probabilities controlling outlier elimination in the local
fitting to predicted positions: a criterion probability for a
patch to be evaluated as an outlier (default 0.01), and a crite-
rion probability for a patch to be eliminated regardless of the
distribution of extreme values (default 0.002).
Warping and Miscellaneous options
These are options for warping alignment, using the GPU, and test out-
put.
-warp (-w) OR -FindWarpTransforms Integer
Use patch correlations to find and save warping transformations
between successive images. The output file will be a file with
warp transforms, not a model. Enter 1 for transforms with the
linear component separated out, and -1 to not separate the lin-
ear component. Tilt angles cannot be entered with this option,
nor can the -reverse option. Unlike with tilt series patch
tracking, you can break the alignment at views as well as skip
views. Limits in X and Y and a boundary model can be used to
constrain patch locations, but there must be at least 3 patches
in the area defined by all the boundary contours.
-pair (-pai) OR -RawAndAlignedPair Two integers
After transforms relating each section to the previous have been
obtained, this option can be used to find a warping alignment
between a pair of sections, where the first is an unaligned
image and the second is a section transformed into linear align-
ment with it. The option specifies the view number (numbered
from 1, as usual) of the second view of the pair and the total
number of sections. If this option is entered, the file of sec-
tion-to-section transforms must be entered with the -prexf
option. The input images must not be binned or resized from the
ones on which those transforms are based. This option is used
by Xfalign.
-append (-ap) OR -AppendToWarpFile
When doing a raw and aligned pair, this option can be used to
add the warp transform from the pair to an existing file. The
output file must be a valid warp transform file.
-gpu (-g) OR -UseGPU Integer
Use the GPU (graphical processing unit) for computations if pos-
sible; enter 0 to use the best GPU on the system, or the number
of a specific GPU (numbered from 1). If the GPU is not avail-
able, the program will use the CPU or take the action specified
by the -action option if that is entered. The program will
respond in the same way if a failure occurs in the initial GPU
access for each slice, where memory allocation is done, but for
any GPU errors after that, it will exit with an error message.
-action (-ac) OR -ActionIfGPUFails Two integers
The action to take when the GPU cannot be used after being
requested: 0 to take no action, 1 to issue a warning prefixed
with MESSAGE:, and 2 to exit with an error. Enter 2 numbers:
the first for the action when the GPU is requested by the UseGPU
option; the second for the action when the GPU is requested only
by the environment variable IMOD_USE_GPU, or by the variable
IMOD_USE_GPU2. The default is 0,0.
-test (-te) 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 (-ve) OR -VerboseOutput Integer
Output diagnostic information at the given level, 1 or 2. With
level 2, patch coordinates are output for each patch, and maps
of SD for each tested reduction are saved to files "sdmap-
bn.mrc" where n is the reduction value.
-param (-par) OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter
file.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
INTERACTIVE 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 start-
ing 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
Number 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 pix-
els
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
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.4 tiltxcorr(1)