xfalign(1) General Commands Manual xfalign(1)
NAME
xfalign - Automatic image alignment using xfsimplex
SYNOPSIS
xfalign [options] input_image_file output_transform_file
DESCRIPTION
xfalign will search for the linear transformations that align each sec-
tion to the previous one in an image stack, or that align each section
to a single reference image. It runs Xfsimplex repeatedly to find
these transformations. Because Xfsimplex performs an incremental
search for a local optimum in alignment, it cannot find the right
alignment if there is a large displacement between the images. Xfalign
has options for initially finding such displacements by cross-correla-
tion using Tiltxcorr, and for working from a set of initial dis-
placements computed previously or set up manually. In addition,
Xfalign can find a warping transformation between successive images by
running Tiltxcorr to correlate overlapping image patches.
These methods will work only on images where there are enough similar
features between one section and the next to guide the alignment. It
may take some experimentation to find settings that will give good
results with a particular kind of data. The major factors to vary
would be the choice of filter to be applied before the search, and the
amount of binning to apply to the images in the search. If images are
not already roughly in alignment, the other variable is whether cross-
correlation will work adequately or whether another method of prealign-
ment is needed.
The images can be reduced in size by binning. More reduction will make
the search run faster and remove or average out more high-frequency
noise. The default reduction is by a factor of 2; no reduction should
be needed for very small images and more reduction might be helpful for
large images (say, 1K x 1K or bigger). As of IMOD 4.6.30, reduction is
done with an antialiasing filter, as is used for high-quality display
in 3dmod, and prefiltering of the images is done on these reduced
images.
Prefiltering uses the four parameters sigma1, sigma2, radius1, radius2
that are used to specify filtering for several other programs (see Fil-
terplot(1). Low-pass filtering to reduce noise (e.g., sigma2 = 0.05,
radius2 = 0.25) is somewhat redundant to reducing the images by a
higher binning factor, and may not be needed with an image reduction
that brings the size below 1K x 1K. If the images contain large areas
of light and dark that correspond between sections and so are good cues
for alignment, then prefiltering, if any, should not include a high-
pass filter (i.e., leave sigma1 at 0 or do not filter). However, if
there are large areas of light and dark that do not correspond and
would be misleading, a high-pass filter should be applied (e.g., sigma1
= 0.05 to flatten the contrast of areas larger than 20-40 pixels). If
the cues for alignment are mostly relatively fine features, it may help
to enhance them with a band-pass filter. This can be done by setting a
sigma2 such as 0.05 and both radius1 and radius2, such as 0.15 and 0.2,
to provide a Gaussian fall-off with sigma of 0.05 around the band from
0.15 to 0.2 reciprocal pixels. Alternatively, a band-pass filter can
be specified with a single parameter, a negative entry for sigma1, such
as -0.1 to get a band-pass filter centered at 0.14 reciprocal pixels.
Another filtering option is to use a Sobel filter, which will highlight
edges in the image.
If initial cross-correlations are chosen, a filter is included whose
default values will remove some high frequency noise (sigma2 = 0.05,
radius2 = 0.25) and prevent the correlation from being thrown off by
very low frequency trends in the images (sigma1 = 0.01). If there are
large light and dark patches that do not correspond well between
images, the low frequency filter set by Sigma1 should be increased. If
images are particularly noisy, radius2 could be decreased.
When initial cross-correlation is used, the program will produce two
transform files, the one specified as your output file, and another
file with the initial transformations. The name of the latter file
will be the root name of your output file, with the extension ".xcxf"
(e.g., "setname.xcxf" if your output file is "setname.xf"). If some of
the initial displacements are bad, there are two possible approaches to
repairing the deficiencies. You can use Midas to correct the final
transformations, in which case you will have to introduce any rota-
tions, size changes or stretches manually as well. Alternatively, you
can edit the initial transformations, then rerun xfalign with the -ini-
tial option specifying that existing .xcxf file, instead of the -prex-
corr option. This would give Xfalign a chance to find the more complex
linear transformations properly for the sections that had bad initial
alignments the first time.
If you are finding warping transformations, by default the program will
first find linear transforms with Xfsimplex. However, you can also
choose to have it find initial shifts as well as linear transforms with
the -prexcorr option, you can have it find initial shifts only by
entering "-prexcorr" and "-param -1", or you can provide initial trans-
forms with the -initial option. In all of these cases, Xfalign runs
Tiltxcorr separately on each pair of sections after using New-
stack(1) to transform the second image of the pair with its initial
linear transform. If images are already well enough aligned, you can
try finding warping transforms directly in Tiltxcorr by using
"-param -1" without entering the -prexcorr or -initial options. This
will be significantly faster, if it works.
When you enter options that make Xfalign find linear transforms then
warping transforms, the initial linear transforms are left in a file
with extension ".linxf" (e.g., the file is named "setname.linxf" if
your output file is "setname.xf"). If there is problem with the final
transforms, you can use Midas with this ".linxf" file to see if the
initial linear transforms are bad. After correcting these transforms,
you can rerun Xfalign to find the warping transforms again using -ini-
tial option with the ".xcxf" file, with "-param -1", and without the
-prexcorr option.
When finding warping alignments, it is possible to enter a model with
contours enclosing areas where there are data suitable for patch corre-
lation (see the -boundary option). One can also enter separate limits
for the shifts to be found in the patch correlations with the -shift
option.
Xfalign works on RGB color images (MRC mode 16). It simply uses
Clip to create a new gray-scale stack in bytes, and a gray-scale
reference file if a color reference file is used. If a color file is
named "rootname.ext", the gray-scale file will be named "root-
name_gray.ext". Transforms can be applied to a color file by running
Colornewst.
OPTIONS
The -prexcorr option cannot be used with either the -ref or the -ini-
tial options.
Xfalign uses the PIP package for input (see the manual page for
pip). Options can be specified either as command line arguments
(with the -) or one per line in a command file (without the -).
Options can be abbreviated to unique letters; the currently valid
abbreviations for short names are shown in parentheses.
-InputImageFile File name
Input file with images to align
-OutputTransformFile File name
Output file for transforms
-size (-si) OR -SizeToAnalyze Two integers
Size of image area to analyze in X and Y in both Xfsimplex
and Tiltxcorr. The default is to analyze the whole image,
with Xfsimplex ignoring the amount around the edges specified
by the -matt option.
-offset (-of) OR -OffsetToSubarea Two integers
When analyzing a subarea, this entry specifies the offset to the
center of subarea being analyzed in X and Y. Positive offsets
are used for an area up from and to the right of the center.
-matt (-m) OR -EdgeToIgnore Floating point
In Xfsimplex, omit areas of images near their edges. Enter a
value < 1 to indicate the fraction of the image extent to omit,
or > 1 to indicate the number of pixels to omit. If a subarea
is being analyzed, this amount is ignored inside the subarea and
the fraction is relative to the subarea size. The default is
0.05.
-reduce (-red) OR -ReduceByBinning Integer
Factor to reduce images by in Xfsimplex. Image reduction is
done with antialias filtering. The default is 2.
-filter (-f) OR -FilterParameters Multiple floats
Filter images before searching in Xfsimplex with the given
sigma1, sigma2, radius1, and radius2 values, which have the same
meaning as in many other programs. See Xfsimplex for
description.
-sobel (-so) OR -SobelFilter
Apply edge-detecting Sobel filter to each image in Xfsimplex.
This filter will be applied after binning and filtering if any.
-params (-pa) OR -ParametersToSearch Integer
In Xfsimplex, search for the given number of semi-natural
parameters or skip the search entirely. Enter 2 to search only
for translations, 3 to search for rotations in addition, 4 to
search for magnifications as well, or 6 to search for the full
transformation as represented by semi-natural parameters (rota-
tion, magnification, difference between X and Y axis stretch,
difference between X and Y axis rotation.) The default is 0, in
which case Xfsimplex searches for the transformation by vary-
ing the formal parameters of the 2 by 2 transformation matrix.
The one advantage of using 6 instead of 0 is that the search can
be limited, and the amount of stretch is limited by default.
Enter -1 to skip the search and perform only initial cross-cor-
relation alignment (the -prexcorr option must also be entered in
this case).
-limits (-li) OR -LimitsOnSearch Multiple floats
Limits for each of the variables being searched. Each number
entered specifies the maximum amount that the respective vari-
able can change from its initial value. Enter a 0 to avoid lim-
iting a parameter. If the search is being done on formal param-
eters, then only the first two (shift in X and Y) can be lim-
ited, so only 1 or 2 values will be meaningful. If the search
is on semi-natural parameters, then you can enter more or fewer
values than the number of variables being searched. Extra val-
ues are ignored, missing values retain their default values.
The default is 0,0,0,0,0.1,4; i.e., difference between X and Y
axis stretch is limited to 10% and difference between X and Y
axis rotation is limited to 4 degrees.
-bilinear (-bi) OR -BilinearInterpolation
With this option, Xfsimplex will use bilinear rather than
nearest neighbor interpolation when transforming an image. This
slower option should be used when trying to find accurate align-
ments between small images.
-ccc (-c) OR -CorrelationCoefficient
Compute the standard cross-correlation coefficient instead of
difference between images. The difference measure that is mini-
mized will be 1 minus the CCC, but the CCC itself is printed in
the trace and final output. It takes < 5% more time to compute
the CCC.
-local (-lo) OR -LocalPatchSize Integer
Size of square subareas (patches) within which to compute a mea-
sure of image difference, in pixels before binning, if any.
This option should prevent the need for low frequency filtering,
which would increase execution time by roughly 10%. Patch sizes
on the order of 1/20 to 1/10 of the image size should be effec-
tive. see Xfsimplex for more details.
-reference (-ref) OR -ReferenceFile File name
Align each image in the input image stack to the single image in
the given image file. Images can be skipped.
-prexcorr (-pr) OR -PreCrossCorrelation
Find preliminary translational alignments with tiltxcorr.
This option is not available with a reference file.
-xcfilter (-xcf) OR -XcorrFilter Multiple floats
Change the filter that is used in cross-correlation by tiltx-
corr(1) to have the given sigma1, sigma2, radius1, radius2.
This filter is applied both in initial cross-correlations and
when finding warp transformations. The values are in the fre-
quency units of the images being correlated after image reduc-
tion, if any. The default is 0.01,0.05,0,0.25.
-xcreduce (-xcr) OR -XcorrReduction Integer
Image reduction to apply in the initial cross-correlations and
when finding warp transformations. For the initial cross-corre-
lations, the default in Tiltxcorr is to make the reduced size
be no bigger than 1250 pixels up to a reduction of 4, then to
increase reduction up to 16 to keep the reduced size under 4100.
There is no reduction by default when finding warping. The pro-
gram will specify antialias filtering when the anticipated or
specified reduction is 4 or higher.
-initial (-i) OR -InitialTransforms File name
Search for transformations starting from the transforms in the
given existing file.
-warp (-wa) OR -WarpPatchSizeXandY Two integers
Find warping transformations with the given patch size in X and
Y. Before Tiltxcorr is run to find warping, shifts will be
determined with cross-correlation if the -prexcorr option is
given, and linear transformations will be sought unless "-param
-1" is entered. Alignment to a reference is not allowed when
finding warping transforms.
-boundary (-bo) OR -BoundaryModel File name
Model with contours around areas to analyze for warping.
Patches for warping will be included if their centers fall
within one of the contours. Contours can be drawn on multiple
sections if the area changes through the stack. When there is
no contour on a section, the contour(s) from the nearest section
with contours will be used to constrain patches.
-seed (-se) OR -WarpSeedModel File name
Model with points specifying location of patches to correlate
for warping, instead of using patches on a regular array. All
points in scattered point objects will be used. Points can be
defined on multiple sections; for any given section, the points
from the nearest section with points will be used.
-shift (-sh) OR -ShiftLimitsForWarp Two integers
Limits in X and Y for shifts when using patch correlation to
find warping. The highest cross-correlation peak will be used
that falls within the limits, or a zero shift will be assigned
if none does.
-wreduce (-wr) OR -WarpReduction Integer
Image reduction to apply when using patch correlation to find
warping. The default in Tiltxcorr is to reduce patches to be
no bigger than 1250 pixels up to a reduction of 4, then to
increase reduction up to 16 to keep the reduced size under 4100.
The program will specify antialias filtering when the antici-
pated or specified reduction is 4 or higher.
-skip (-sk) OR -SkipSections List of integer ranges
List of sections to skip, while maintaining alignment across
skipped sections. The program will not find the transform for
aligning a listed section to the previous one. Section numbers
are separated by the ',' character for single sections or the
'-' character for ranges. Section numbers start with zero and
go up to nz-1. When a section is skipped, the following section
will be aligned to the last unskipped section and a unit trans-
form will be output for the skipped section. The default is to
use all of the sections.
-break (-br) OR -BreakAtSections List of integer ranges
List of sections to break alignment at. This option is like
"-skip" in that no transform is found for aligning a listed sec-
tion to the previous one and a unit transform is written for the
listed section. However, the following section will be aligned
to the listed section, and nothing will be aligned to the previ-
ous section. This breaks the chain of alignment through the
series of sections.
-bpair (-bp) OR -PairedImages
Break the alignment after every pair of sections, i.e., at all
even section numbers.
-tomo (-t) OR -TomogramAverages
Align averaged slices from the top and bottom of tomograms of
serial sections. The image file is assumed to contain pairs of
top and bottom averages, i.e., from the top of the first tomo-
gram, the bottom of the second, the top of the second, etc.,
ending in the bottom of the last tomogram. The program will
align only a bottom average to the previous top average, and the
number of transforms output will equal the number of tomograms,
not the number of averages in the image file. The same number
of transforms are assumed to be present in a file of initial
alignments entered with the -initial option.
-diff (-d) OR -DifferenceOutput
Output the final difference measure or cross-correlation coeffi-
cient found by Xfsimplex for each pair of images. The dif-
ference measure is the mean difference per pixel expressed as a
multiple of the image standard deviation.
-one (-on) OR -SectionsNumberedFromOne
Section numbers in the -skip and -break section list entries are
numbered from 1 instead of from 0.
-PID Print process ID
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
FILES
When using prealignment by cross-correlation, the initial transforms
will be placed into a file with the same root name as the transform
output file but with the extension .xcxf. If an output file already
exists a backup of the original is created with the ~ extension.
AUTHOR
David Mastronarde
SEE ALSO
xfsimplex, tiltxcorr, midas, colornewst, clip
BUGS
Report bugs to mast at colorado dot edu
IMOD 4.11.0 xfalign(1)