corrsearch3d(1) General Commands Manual 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. Sometimes the borders of the usable area are defined just by the
area that contains image data in aligned stack; unusable area can be
significant if the tilt axis was not very close to vertical or horizon-
tal and an extra-large aligned stack was built to contain more of the
rotated images. In this case, the need for a boundary model can be
avoided by entering options that specify the size of the original tilt
series and the tilt axis rotation.
An initial analysis of a measure of structure in the volume can also be
used to avoid the need for delineating the region to where patches
should be analyzed. The measure of structure is the local standard
deviation, computed in an array of boxes that overlap by about 50%.
This SD is computed after a series of binnings to minimize the degree
to which the SD reflects noisiness in the data rather than the presence
of structure. For each binning, the program measures the median SD of
the top and bottom surfaces. It also analyzes a histogram of SD values
through the entire volume and seeks two peaks in the histogram, one for
structure and one for background. If this succeeds, it picks the bin-
ning where the top of the peak for structure is most distinguishable
from the median of surface SD values. It uses the dip between the
peaks as the best estimate of a threshold between structure and back-
ground. Using the SD values from this binning, it then computes two
numbers for each patch: the fraction of boxes in the patch with SD
above this threshold, and the mean SD in the patch relative to the SD
at the top of the peak. Patches can then be eliminated if one of the
measures falls below a criterion. The first measure seems to be better
for this purpose.
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
and a set of ID values for the extra columns of data. Then there is
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 (ID value 1). If local SD is analyzed, there
are two more columns: the fraction of boxes with a high SD, and the
relative mean SD value in the patch (ID values 5 and 6, respectively).
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 (-al) 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
-tilt (-ti) OR -TiltSeriesSizeXY Two integers
Size in X and Y of raw tilt series for volume being aligned to,
divided by the binning applied to make its aligned stack. With
this entry plus the -axis option with the rotation angle of the
tilt axis, the program will eliminate patches outside the area
that can be well-reconstructed from the original images. This
will avoid the need for a boundary model just to delineate well-
reconstructed areas. However, the method works only if the
aligned stack and reconstruction were centered on the original
tilt series.
-btilt (-bt) OR -BTiltSeriesSizeXY Two integers
Size in X and Y of raw tilt series for volume being aligned,
divided by the binning applied to make its aligned stack. This
entry allows the program to eliminate patches outside the region
that can be well-reconstructed in the second volume.
-axis (-ax) OR -AxisRotationAngle Floating point
Rotation angle from Y axis to tilt axis in the raw tilt series,
counterclockwise positive. This entry is required with the
-tilt or -btilt options.
-taper (-ta) 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 (-ini) 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.
-binnings (-bi) OR -LocalSDNumBinnings Integer
Number of binnings at which to analyze the local standard devia-
tion of pixel values. See above for details. An entry of 4 is
appropriate unless the data are already binned.
-box (-bo) OR -BoxSizeForLocalSD Three integers
Box size in X, Y, and Z for analyzing local standard deviation,
in unbinned pixels. For the binnings higher than 1, the number
of binned pixels analyzed will be the entered number divided by
the binning, so the box needs to be big enough to still have
enough pixels for a reliable SD estimate at hte highest binning.
It should be thinner in the thickness dimension since that is
the dimension where there are the most transitions between
structure and non-structure. It needs to be wide enough to span
small variations in structure so that the SD estimate itself
does not vary so much from one box to the next. A size of 32
laterally and 8 in thickness is effective.
-elim (-e) OR -EliminateByLocalSD Two floats
This option enables patches to be eliminated after the analysis
of local SD. Enter 2 numbers: 1 to use the fraction of boxes
with high SD values or 2 to use the relative mean SD value of
the patch; and the threshold value required to retain the patch.
-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
-invert (-inv) OR -InvertYLimits
Invert the starting and ending Y coordinates to take patches
from by subtracting them from NY - 1 and exchanging the two val-
ues, where NY is the Y dimension of the file being matched to.
This entry is needed if the Y limits are set from Z slice values
picked in 3dmod after loading the volume with rotation round the
X axis.
-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. Add 20 for histogram out-
put from findHistogramDip.
-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.
IMOD 4.11.0 corrsearch3d(1)