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)