Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

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
  XCORR 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 parameters as in other IMOD
  programs (see man page for Enhance).  The single 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 corner of the larger array.  As a
  consequence of this shift, the coordinates of the peaks in the correlation
  will correspond to the coordinates 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.

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

 -stack 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 argument will be used for this
    input file.

 -single 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 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 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 generated on the input stack will
    display correctly on the correlation stack.

 -rad1 OR -FilterRadius1   Floating point
    Low spatial frequencies in the cross-correlation will be attenuated 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 attenuated 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 frequency 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 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 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 corner, just as occurs for
    smaller single images.

 -fill 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 OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help 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