xcorrstack(1)                                                    xcorrstack(1)



NAME
       xcorrstack - to cross-correlate a single image with a whole image stack

SYNOPSIS
       xcorrstack  [options]  image_stack  single_image  output_stack

DESCRIPTION
       Xcorrstack cross-correlates each of the sections in one image stack
       with a single image in a second image file.  A subset of sections may
       be done. The correlation may be filtered with the same set of parame-
       ters as in other IMOD programs (see man page for Enhance).  The sin-
       gle image may be smaller than the images in the stack.  In this case,
       by default the single image will be placed in an array of the larger
       size, with the MIDDLE of the smaller image moved to the LOWER-LEFT cor-
       ner of the larger array.  As a consequence of this shift, the coordi-
       nates of the peaks in the correlation will correspond to the coordi-
       nates of the centers of features in the image stack that best match the
       single image.  If the single image and stack have the same dimensions,
       then you have a choice as to whether to keep the single image as it is
       or to move its middle into the lower left corner.  Displacements
       between images would then be reflected by the positions of peaks in the
       correlogram relative to the (0,0) pixel (if the image is not shifted)
       or relative to the middle (NX/2,NY/2) pixel (if the image is shifted.)

       Images will be padded if necessary for taking the FFT, so their size
       may be odd or contain large prime factors.

       Filtering is specified with the standard four parameters used in other
       IMOD programs.  The filter functions produced by these options can be
       visualized with the program Filterplot; see that man page a full
       description of their effects.

OPTIONS
       Xcorrstack uses the PIP package for input exclusively (see the manual
       page for pip).  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.


       -stack (-st) OR -StackInputFile     File name
              Input file with stack of images to correlate with a single
              image. If this option is not entered, the first non-option argu-
              ment will be used for this input file.

       -single (-sin) OR -SingleInputFile       File name
              Input file with single image to correlate with the stack of
              images.  If this option is not entered, the second non-option
              argument will be used for this input file.

       -output (-o) OR -OutputFile    File name
              Output file for correlation images.  If this option is not
              entered, the third non-option argument will be used for this
              output file.

       -sections (-se) OR -StartingEndingSections    Two integers
              Starting and ending sections in the input stack to correlate
              with the single image.  Sections are numbered from 0.  The Z
              origin of the output file will be adjusted so that a model gen-
              erated on the input stack will display correctly on the correla-
              tion stack.

       -rad1 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 FilterSigma2.  Spatial frequency units range from 0 to 0.5.
              Use FilterSigma1 instead of this entry for more predictable
              attenuation of low frequencies.

       -rad2 OR -FilterRadius2   Floating point
              High spatial frequencies in the cross-correlation will be atten-
              uated by a Gaussian curve that is 1 at this cutoff radius and
              falls off above this radius with a standard deviation specified
              by FilterSigma2.

       -sig1 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.  However,
              if a negative value of radius1 is entered, this filter will be
              zero from 0 to |radius1| then decay up to 1.

       -sig2 OR -FilterSigma2    Floating point
              Sigma value for the Gaussian rolloff below and above the cutoff
              frequencies specified by FilterRadius1 and FilterRadius2

       -mode (-m) OR -ModeOfOutput    Integer
              Mode for correlation images: 0 for byte, 1 for short integer, 2
              for floating point, 6 for unsigned short integer.  Except for
              floating point output, each correlation image will be scaled to
              fill the positive dynamic range of the mode.  The default is the
              same mode as the input.

       -split (-sp) OR -SplitIntoCorners
              If the single image is the same size as the input stack, this
              option can be used to the middle shifted to the lower left cor-
              ner, just as occurs for smaller single images.

       -fill (-f) OR -FillValue       Floating point
              Value to fill when embedding image into a larger array.  The
              default is to fill with the mean at the edge of the image.

       -param (-p) 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.


HISTORY
       Written by David Mastronarde 4/26/89
       Converted to PIP, got rid of redundant filters, adjusted origin 10/29/07

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                       xcorrstack(1)