xfalign(1)                                                          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.

       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).

       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 binning the images, and may
       not be needed with the default image reduction.  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 corre-
       spond 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 fea-
       tures, 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.


   Options
       Options may be abbreviated to one to three letters, the minimum needed
       to unambiguously specify the particular option.  The -prexcorr option
       cannot be used with either the -ref or the -initial 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 -):

       -InputImageFile      File name
              Input file with images to align

       -OutputTransformFile      File name
              Output file for transforms

       -size OR -SizeToAnalyze   Two integers
              Size of image area to analyze in X and Y.  The default is to
              analyze the whole image, ignoring the amount around the edges
              specified by the -matt option.

       -offset OR -OffsetToSubarea    Two integers
              When analyzing a subarea, this entry specifies the offfset to
              the center of subarea being analyzed in X and Y.  Positive off-
              sets are used for an area up from and to the right of the cen-
              ter.

       -matt 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 OR -ReduceByBinning    Integer
              Binning factor to reduce by (default 2)

       -filter OR -FilterParameters   Multiple floats
              Filter images before searching with the given sigma1, sigma2,
              radius1, and radius2 values, which have the same meaning as in
              many other programs.  See Xfsimplex for description.

       -sobel OR -SobelFilter
              Apply edge-detecting Sobel filter to each image.  This filter
              will be applied after binning and filtering if any.

       -params OR -ParametersToSearch      Integer
              In Xfsimplex, search for the given number of semi-natural param-
              eters.  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 (rotation, 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 varying 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.

       -limits 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 OR -BilinearInterpolation
              With this option, Xfsimplex will use bilinear rather than near-
              est neighbor interpolation when transforming an image.  This
              slower option should be used when trying to find accurate align-
              ments between small images.

       -ccc 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 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 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 OR -PreCrossCorrelation
              Find preliminary translational alignments with tiltxcorr.
              This option is not available with a reference file.

       -xcfilter 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.  The
              default is 0.01,0.05,0,0.25.

       -initial OR -InitialTransforms      File name
              Search for transformations starting from the transforms in the
              given existing file.

       -skip 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 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 OR -PairedImages
              Break the alignment after every pair of sections, i.e., at all
              even section numbers.

       -tomo 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 OR -DifferenceOutput
              Output the final difference measure or cross-correlation coeffi-
              cient found by Xfsimplex for each pair of images.  The differ-
              ence measure is the mean difference per pixel expressed as a
              multiple of the image standard deviation.

       -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 image of the original is created with the ~ extension.

AUTHOR
       David Mastronarde

SEE ALSO
       xfsimplex, tiltxcorr

BUGS
       Report bugs to mast at colorado dot edu



BL3DEMC                              4.3.7                          xfalign(1)