Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

CORRSEARCH3D(1)						        CORRSEARCH3D(1)

NAME
	corrsearch3d - search for array of 3D displacements between two volumes

SYNOPSIS
	corrsearch3d

DESCRIPTION
  Corrsearch3d will determine the 3D displacement between two image
  volumes at a regular array of positions.  At each position, it extracts
  a patch of a specified size from each volume, then searches for a local
  maximum in the cross-correlation between the two patches, computing
  correlations in real space at each displacement between the patches.  
  The starting point of the search is based upon the displacements of
  adjacent patches that have already been determined.  If there are no
  such adjacent patches, or if no maximum is found for displacements
  within a specified range, the program uses FFT-based cross-correlation
  instead of real-space correlation.  The program works from the center
  of the volume outward, analyzing patches in the X direction, then in
  the shorter of Y and Z dimensions, then in the longer of those
  dimensions.  An optional model file can be entered with contours
  enclosing the area where patches should be analyzed; patches outside
  this area are excluded.  Information about the source volume for the
  file being transformed can be entered so that the program can analyze
  patches only from regions that are good in the second image file.  In
  addition, a model can be provided enclosing good areas in the source
  for the second file.

  The data being correlated can be filtered by convolving with a 3x3x3 or
  5x5x5 Gaussian kernel in real space.  This smoothing is applied to one
  of the two patches before correlating them.  The degree of filtering is
  controlled by the sigma (standard deviation) of the Gaussian, which
  should be a small number on the order of 1.  Computation time will
  increase by ~30% when smoothing with a 3x3x3 kernel and it will double
  with a 5x5x5 kernel.  By default, the program will select a 3x3x3
  kernel for sigma less than 1.5 and a 5x5x5 kernel for larger sigmas,
  unless the size is explicitly selected.  The useful range of sigma is
  probably 0.5 to 3.

  Low and high frequency filtering can also be applied in Fourier space,
  but this is useful only for testing because it is used only with the
  rare FFT-based correlations.

  The program works with files whose thin dimension is in either Y or Z.
  If the volumes are offset from each other (such as adjacent tomograms),
  this offset can be specified with the -InitialShiftXYZ option.  The
  displacements computed by the program are in addition to this global
  shift.

  The program outputs an initial line with the total number of
  patches, then one line for each patch, containing the X, Y, and Z
  coordinates of the patch, the displacement between the two files
  in X, Y, and Z, and the correlation coefficient.

  Corrsearch3d uses the PIP package for input (see the manual page for pip)
  and can take input interactively for options that existed when it was
  converted, to maintain compatibility with patchcrawl3d.  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 -):

 -ref OR -ReferenceFile   File name
    Reference image file that is being aligned to

 -align OR -FileToAlign   File name
    Image file that will be transformed into alignment

 -output OR -OutputFile   File name
    Output file for patch displacements

 -region OR -RegionModel   File name
    Model file with contours enclosing regions to take patches from

 -size OR -PatchSizeXYZ   Three integers
    Size of patches in X, Y, and Z

 -number OR -NumberOfPatchesXYZ   Three integers
    Number of patches in the X, Y and Z directions

 -xminmax OR -XMinAndMax   Two integers
    Starting and ending X coordinates of region to take patches from.  X, Y,
    and Z coordinates are numbered from 1.

 -yminmax OR -YMinAndMax   Two integers
    Starting and ending Y coordinates of region to take patches from

 -zminmax OR -ZMinAndMax   Two integers
    Starting and ending Z coordinates of region to take patches from

 -taper OR -TapersInXYZ   Three integers
    Number of pixels over which to taper the patches in X, Y and Z.  The
    default is 10% of the patch dimensions.

 -pad OR -PadsInXYZ   Three integers
    Number of pixels to pad each side of the patch in X, Y, and Z for Fourier
    correlations .  The default is 20% of the patch dimensions.

 -maxshift OR -MaximumShift   Integer
    Maximum displacement to determine by searching.  This is in addition to
    the local offset determined from adjacent patches.  The default is 10.

 -volume OR -VolumeShiftXYZ   Three floats
    Overall displacement of the volume being aligned relative to the reference
    volume in X, Y, and Z; namely, the amount to add to a pixel coordinate in
    the reference volume to obtain the coordinate of the corresponding pixel
    in the file being aligned.  This shift is excluded from the shifts
    reported in the output file.  If no volume shift is entered, it is set
    equal to half the difference in size between the two volumes, if any.

 -initial OR -InitialShiftXYZ   Three floats
    Initial displacement between the center of the volume being aligned and
    the center of the reference volume in X, Y, and Z.  This is the amount to
    add to the coordinate of a feature near the center of the reference volume
    to obtain the coordinate of the same feature in the file being aligned,
    after accounting for any overall volume displacement entered with -volume.
     This shift will be used to start the search and will be included in the
    shifts reported in the output file.

 -bsource OR -BSourceOrSizeXYZ   Text string
    File name or X, Y and Z size of source of file being aligned.  This size
    must be entered if a 3-D transformation is supplied; otherwise the size of
    the file being aligned is used.

 -bxform OR -BSourceTransform   File name
    File with 3-D transformation that was used to generate the file being
    aligned from its source file.

 -bxborder OR -BSourceBorderXLoHi   Two integers
    Size of borders to be excluded on the lower and upper sides in X in the
    original source volume for the file being aligned

 -byzborder OR -BSourceBorderYZLoHi   Two integers
    Size of borders to be excluded on the lower and upper sides in Y or Z
    (whichever is the longer dimension) in the original source volume for the
    file being aligned.

 -bregion OR -BRegionModel   File name
    Model file with contours enclosing areas in the original source volume for
    the file being aligned that are suitable for correlation.

 -kernel OR -KernelSigma   Floating point
    Sigma for real-space smoothing with 3D Gaussian kernel (in pixels).  The
    smoothing is with a 3x3x3 or 5x5x5 kernel whose coefficients are
    proportional to a Gaussian with the given sigma centered on the central
    pixel.  Each patch from the first volume is smoothed before being used for
    either the correlation search or a Fourier correlation.

 -ksize OR -KernelSize   Floating point
    Size in pixels of the 3D Gaussian kernel used for real-space smoothing. 
    The size can be either 3 or 5.  The default is 3 for a kernel sigma below
    1.5 and 5 for larger sigmas since the filtering reaches a point of
    diminishing returns at about this sigma with a size of 3.

 -lowpass OR -LowPassRadiusSigma   Two floats
    Cutoff radius and sigma for a low pass filter that imposes a
    high-frequency Gaussian roll-off in the Fourier cross-correlations.  The
    default is no high-frequency filtering.

 -sigma1 OR -HighPassSigma   Floating point
    Sigma value to filter low frequencies in the Fourier 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.

 -messages OR -FlipYZMessages
    Exchange Y and Z in error messages if Y is short dimension

 -debug OR -DebugMode   Integer
    Set to 1 for debugging output, 2 to obtain a dummy patch output file to
    assess the positions of the patches, and 3 to do Fourier correlations at
    all positions, plus direct correlation searches wherever possible.  In the
    latter case each line of the patch output file will have the results from
    the Fourier correlation, followed by the results from direct correlation,
    ending with a 3D distance between the two results.

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


  If the program is started with no command line arguments, it reverts to
  interactive input with the following entries:
  
  Name of reference image file being aligned to
  
  Name of image file that will be transformed to match
  
  Name of output file for patch positions and displacements
  
  Name of a temporary file for output from onepatchcorr
  
  Name of a model file with contours that enclose the areas where
  patches should be analyzed, or Return to analyze patches at all
  locations
  
  Size of patches in X, Y and Z
  
  Number of patches in the X, Y and Z directions
  
  Size of borders to be excluded on the lower and upper sides in X,
  the lower and upper sides in Y, and the lower and upper sides in Z
  
  Number of pixels over which to taper the patches in X, Y and Z
  
  Maximum displacement to determine by searching
  
  Either the X, Y, and Z size or the name of the original source
  volume for the second image file.  Return to omit analysis of
  positions in this file.
  
  Name of the 3-D transformation file used to generate the second
  image file from its source volume, or Return to omit analysis of
  positions in the second file.
  
  Size of borders to be excluded on the lower and upper sides in X
  and the lower and upper sides in Z in the original source volume
  for the second image file.
  
HISTORY
  Written by David Mastronarde  7/16/01
  7/20/02: Added analysis of areas to exclude based on positions in the
	source for the second volume
  8/16/06: Converted to PIP, incorporated FFT correlations internally,
        added filtering, made it extract the B patches based on the local
        shift instead of using the same coordinates in both volumes,
        added model file for B and initial displacement, handled volumes
        in both orientations.