corrsearch3d(1)                                                corrsearch3d(1)



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

SYNOPSIS
       corrsearch3d  options

DESCRIPTION
       Corrsearch3d will determine the 3D displacement between two image vol-
       umes 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 dimen-
       sions.  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 ker-
       nel 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.

OPTIONS
       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 (with-
       out the -).  Options can be abbreviated to unique letters; the cur-
       rently valid abbreviations for short names are shown in parentheses.


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

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

       -output (-o) OR -OutputFile    File name
              Output file for patch displacements

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

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

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

       -xminmax (-x) 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 (-y) OR -YMinAndMax   Two integers
              Starting and ending Y coordinates of region to take patches from

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

       -taper (-t) 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 (-ma) 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 (-v) 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 coordi-
              nate 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 dif-
              ference in size between the two volumes, if any.

       -initial (-i) 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 (-bs) 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 (-bxf) OR -BSourceTransform      File name
              File with 3-D transformation that was used to generate the file
              being aligned from its source file.

       -bxborder (-bxb) 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 (-by) 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 (-br) OR -BRegionModel     File name
              Model file with contours enclosing areas in the original source
              volume for the file being aligned that are suitable for correla-
              tion.

       -kernel (-ke) OR -KernelSigma       Floating point
              Sigma for real-space smoothing with 3D Gaussian kernel (in pix-
              els).  The smoothing is with a 3x3x3 or 5x5x5 kernel whose coef-
              ficients 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 (-ks) 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 fil-
              tering reaches a point of diminishing returns at about this
              sigma with a size of 3.

       -lowpass (-l) 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-correla-
              tions.  The default is no high-frequency filtering.

       -sigma1 (-sig) OR -HighPassSigma    Floating point
              Sigma value to filter low frequencies in the Fourier correla-
              tions 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 (-me) OR -FlipYZMessages
              Exchange Y and Z in error messages if Y is short dimension

       -debug (-d) 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 (-par) 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.


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

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                     corrsearch3d(1)