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 5.0.2 matchrotpairs(1)