dualvolmatch(1)             General Commands Manual            dualvolmatch(1)

       dualvolmatch - Find initial transformation between dual-axis volumes

       dualvolmatch  [options]  rootname

       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.

       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

       -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

              Read parameter entries from standard input

       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.

       David Mastronarde

       binvol, xyzproj, matchrotpairs, corrsearch3d, refine-
       match(1), matchvol

       Email bug reports to mast at colorado dot edu.

IMOD                                4.12.60                    dualvolmatch(1)