matchrotpairs(1)            General Commands Manual           matchrotpairs(1)



NAME
       matchrotpairs - find transform between best matching pair of rotated
       views

SYNOPSIS
       matchrotpairs [options] file_a file_b output_transform

DESCRIPTION
       Matchrotpairs will find the best-matching pair of images between two
       sets of tilted images rotated by about 90 degrees from each other and
       output the transformation between that pair of images.  The program was
       first developed for the analysis of image distortion fields.  The
       transformation is supplied to Finddistort, which will use it to com-
       pute the absolute stretch component of an image distortion field.  How-
       ever, the stretch cannot be computed accurately if one of the images is
       of a tilted specimen, because a tilt will shrink the image slightly
       perpendicular to the tilt axis.  Also, the specimen cannot be assumed
       to be horizontal at zero tilt.  The solution to these problems is to
       use a specimen with some features distributed at different heights,
       take a small tilt series of the specimen (e.g., at -4, -2, 0, 2, and 4
       degrees), rotate it by 90 degrees, and take another such tilt series.
       Matchrotpairs can then be used to search for the pair of views from the
       two series that match the best, using essentially the same procedure as
       in Transferfid.  The difference between these images can then be
       assumed to be the result of the rotation alone, even if the specimen is
       tilted in each of these two views.

       The recommended procedure would be to run Finddistort first to find
       a zero-stretch distortion field, and to supply this field to Matchrot-
       pairs.  The two best matching images will be undistorted and these
       undistorted images should then differ only by a stretch, allowing the
       stretch to be determined with the greatest accuracy.

       Matchrotpairs is a Python script that uses a module shared with Trans-
       ferfid(1) for most of its operations


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

       -ia OR -AImageFile   File name
              Name of image file A. If this option is not entered, the first
              non-option argument will be taken as this name.

       -ib OR -BImageFile   File name
              Name of image file B. If this option is not entered, the second
              non-option argument will be taken as this name.

       -output (-o) OR -OutputFile    File name
              Name of output transform file. If this option is not entered,
              the third non-option argument will be taken as this name.

       -za OR -AStartingEndingViews   Two integers
              The starting and ending sections from the first input file to
              include in the search, numbered from 1.  The default is to use
              all sections from the first file.

       -zb OR -BStartingEndingViews   Two integers
              The starting and ending sections from the second input file to
              include in the search, numbered from 1.  The default is to use
              all sections from the second file.  Note that the two tilt
              series can be placed in the same file, that file name can be
              given for both input files, and the -za and -zb options can be
              used to indicate where the two tilt series are in the file.

       -swap (-sw) OR -SwapAandB
              Swap A and B in the processing to get a transformation from B to
              A; otherwise the output transform aligns an image in A to one in
              B.

       -a OR -AngleOfRotation    Integer
              Use this option to specify the direction of rotation from the
              first to the second axis.  Only the sign of this number matters,
              so you can enter -1 or -90 for clockwise rotations, or 1 or 90
              for counterclockwise rotations.  In the absence of this option,
              the program will consider both directions of rotation.

       -mirror (-mi) OR -MirrorXaxis       Integer
              This option controls whether the image from one stack is mir-
              rored around the X axis before rotating by 90 degrees.  Enter 1
              to mirror always, -1 to never mirror, or 0 to have the program
              assess both with and without mirroring.  The default is 0.

       -d OR -DistortionFile     File name
              Name of file with zero-stretch image distortion field from Find-
              distort(1).

       -b OR -ImagesAreBinned    Integer
              The binning at which images were acquired, which usually needs
              to be specified when undistorting.

       -m OR -RunMidas
              Run Midas on the first pair of views, and use the alignment that
              you set in Midas as the initial alignment for all pairs of views
              that are considered.  A correction for stretch will be applied
              in the initial alignment of the other pairs and may be needed in
              some cases.

       -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 (legacy behavior).  In the latter case, or when the
              rotation scan finds the best rotation at the end the range, an
              initial run of Xfsimplex will be done to search for rota-
              tion/translation only.  The default is 20 and 4, which will
              accommodate inaccuracies in 90-degree rotation of up to ~22
              degrees, and give fairly accurate interpolated rotation values
              that allow the first Xfsimplex step to be skipped.

       -nearest (-n) OR -NearestNeighbor
              Use nearest neighbor instead of linear interpolation in Xfsim-
              plex(1).  This option will trigger other changes in program
              behavior that are appropriate when it is not being used for ana-
              lyzing stretch.

       -x OR -WriteAllTransforms
              Write out the transformations between all pairs of sections; a
              separate file will be written for each view in B containing the
              transformations that align each view in A to that view in B as a
              reference.

       -t OR -LeaveTempFiles
              For diagnosing problems, leave temporary files in the standard
              temporary directory (/usr/tmp, /tmp, or defined by IMOD_TMPDIR)
              or in the current directory if there is no temporary directory.

       -PID   Print process ID

       -help (-h) OR -usage
              Print help output

       -StandardInput
              Read parameter entries from standard input

FILES
       The best matching pair will be undistorted if the -d option is given
       and stacked into a file with the root name of the output file and the
       extension ".stack".  If the output file already exists, a backup image
       of the original is created with the ~ extension.

AUTHOR
       David Mastronarde  <mast at colorado dot edu>

SEE ALSO
       finddistort, transferfid, midas



IMOD                                4.11.0                    matchrotpairs(1)