dualvolmatch(1) General Commands Manual dualvolmatch(1)
NAME
dualvolmatch - Find initial transformation between dual-axis volumes
SYNOPSIS
dualvolmatch [options] rootname
DESCRIPTION
This program will find the initial transformation between the two sin-
gle-axis tomograms of a dual-axis dataset without using the correspond-
ing fiducials or modeled points that are required by Solvematch. It
can do this automatically even when the rotation angle between the two
axes is not close to 90 degrees, and when
The program starts by binning down each of the two volumes, both to
speed up the computations and to improve the signal-to-noise ratio. It
then reprojects each volume at a small set of tilt angles and runs
Matchrotpairs to find which pair of reprojections match the best.
This process is repeated at least once (by default) to yield an esti-
mate of the relative tilts needed to align the volumes, as well of the
2D linear transformation that aligns their reprojections. The result-
ing tilt angles are accurate to within 0.5 degrees. These values pro-
vide a preliminary estimate of the 3D transformation needed to align
the volumes. This transformation is applied to one binned-down volume,
then corresponding patches from this transformed volume and the other
binned-down volume are cross-correlated by Corrsearch3d. These
correlations use a single layer of patches that extend through the
whole depth of the volume and are relatively large in the plane of the
section as well. Refinematch is then used to obtain a better esti-
mate of the initial transformation that includes the shift in the depth
dimension. If the error of the fit in Refinematch is too high, the
program drops back to using the preliminary estimate of the transforma-
tion, and refines the shifts in there with a single large patch corre-
lated between the centers of the two volumes.
OPTIONS
Dualvolmatch uses the PIP package for input (see the manual page for
pip). Options can be specified either as command line arguments
(with the -) or one per line in a command file (without the -).
Options can be abbreviated to unique letters; the currently valid
abbreviations for short names are shown in parentheses.
-name (-n) OR -RootName Text string
Root name of dataset, excluding a and b
-atob (-a) OR -MatchAtoB
Match A to B instead of B to A
-binning (-b) OR -BinningToApply Integer
Amount to bin reconstructions for reprojection and patch corre-
lations. The default is to bin by an amount up to 4 that brings
the smallest dimension (in the plane of the section) to between
512 and 1023.
-tilt (-ti) OR -TiltAngleMaxAndStep Two floats
Maximum tilt angle to reproject and the increment between
angles. The default is 4 and 2. If the best matching pair of
reprojections is at the end of this tilt range, the program will
reproject again with the same range and step size but centered
on the best pair of views, then repeat the tilt matching. This
process will be repeated up to 2 times, allowing a maximum tilt
angle of 10 degrees by default. If is necessary to allow a
larger range, it is more efficient use a larger increment as
well, and increase the number of refinement cycles with the
-refine option.
-refine (-r) OR -RefineTiltAngles Integer
Number of times to refine tilt angle estimates. On each cycle
of refinement, the step size will be cut by two, and new repro-
jections made centered at the previous best (uninterpolated)
tilt angles. The angular range will also be cut by 2, unless
there were fewer than 5 tilts reprojected in the original range.
-center (-c) OR -CenterShiftLimit Floating point
Maximum shift in Z between tomograms at the patch nearest the
center. This shift is obtained from the residual of the of that
patch in the Refinematch fit greater than the -maxresid
entry. If the shift is greater than the limit, the program will
exit with an error so that an appropriate entry for the initial
shift can be made before doing patch correlations. The default
value is 10. A value of 0 disables the test.
-maxresid (-m) OR -MaximumResidual Floating point
The limiting value for the mean residual from running Refine-
match(1). The reported mean residual will be scaled by the bin-
ning and compared with this value, which should be entered in
unbinned pixels. When the mean residual is too high, the pro-
gram will discard the 3D transformation from Refinematch and
use the initial estimate based on the tilt matching. It will
rerun Corrsearch3d with one very large central patch to mod-
ify the shifts in this transformation.
-scan (-sc) OR -ScanRotationMaxAndStep Two floats
Either the maximum angle and angular step size at which to apply
rotation in order to estimate the best rotation; or a single
rotation angle to apply and a 0 step size; or 0,0 for no rota-
tion scan. This entry is passed directly to Matchrotpairs.
The default is 20, 4.
-final (-f) OR -FinalOutputFile File name
Name for output file with final 3D transformation (default
solve.xf)
-style (-st) OR -NamingStyle Integer
0 if image files have descriptive extensions like ".preali", or
1 or 2 if descriptive text is before the extension ".mrc" or
".hdf". This entry is needed only if the style cannot be deter-
mined from files in the dataset.
-test (-te) OR -TestMode Integer
1 to print out all output from Matchrotpairs and Refine-
match(1), 2 to save large temporary files created locally by
this script in addition, or 3 to have Matchrotpairs leave its
temporary files in the temporray directory that is uses.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
FILES
Since temporary files produced by this procedure can be rather large,
they are placed into the current directory instead of a temporary
directory. They are all deleted when the program exits unless the
-test option is used to retain them.
AUTHOR
David Mastronarde
SEE ALSO
binvol, xyzproj, matchrotpairs, corrsearch3d, refine-
match(1), matchvol
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.12.61 dualvolmatch(1)