solvematch

solvematch(1) General Commands Manual solvematch(1)
NAME
 solvematch - Solve for transformation matching one tomogram to another
SYNOPSIS
 solvematch [options]
DESCRIPTION
 Solvematch will solve for a 3-dimensional linear transformation relat-
 ing the tomogram volumes resulting from tilt series around two differ-
 ent axes. It can use information from the 3-D coordinates of fiducials
 found by Tiltalign, or from IMOD models of corresponding points in
 the two volumes, or from both of these sources together. Current ver-
 sions of Tiltalign produce fiducial lists with coordinates correspond-
 ing the coordinates in the tomogram, thus providing all of the informa-
 tion that Solvematch needs to find the transformation. Older versions
 of Tiltalign produced coordinates centered around zero; this situa-
 tion is discussed below.
 Using Fiducial Coordinates
 When you use fiducial coordinates, the program needs to know how the
 fiducial points correspond between the two tilt series. There are two
 different ways that this information can be provided.
 If Transferfid was used to produce the seed model for one of the
 axes from the fiducial model for the other, then it can be given an
 option to produce a file with the coordinates of corresponding fiducial
 points from one view in each data set. This file can be provided to
 Solvematch with the "-transfer" option and the program will be able to
 deduce how the points in the fiducial lists from Tiltalign corre-
 spond. This capability allows you to add or delete fiducial points in
 either fiducial model after running Transferfid without having to
 keep track of how this affects the correspondence between points. This
 option requires that both fiducial models be supplied to Solvematch.
 Also, it is essential that Solvematch be informed if the A axis is
 being matched to the B axis, with the -atob option.
 In the absence of a transfer coordinate file, the program needs lists
 of points that correspond between the two data sets. If it is given a
 small list of points which do correspond, it can find the rest of the
 correspondences and ignore any points from either set that do not have
 a mate. There are two restrictions in using this capability. First,
 one must identify at least 4 initial correspondences; in fact, having
 at least 5 is recommended. Second, if there are fiducials on both sur-
 faces of the section, this initial list must include at least one from
 each surface.
 When you enter point numbers, use the numbers listed on the left in the
 fiducial coordinate file. These numbers may not correspond to the con-
 tour numbers in the original fiducial model if some contours were not
 included in the solution. These numbers do not need to be sequential;
 i.e., you can delete points from the coordinate file. The program will
 refer to points by these numbers. When you have both fiducial coordi-
 nates and points from matching models, it will refer to the latter
 points by the negative of their point number.
 When using fiducial coordinates, you also need to indicate to Solve-
 match whether the gold fiducials are on one surface or distributed in
 depth (typically but not necessarily on two surfaces). If there is
 gold on only one surface, you must determine whether the two tomograms
 are inverted in Y (Z in flipped orientation); i.e. whether the gold is
 on the "top" of the section in one tomogram and the "bottom" in the
 other even though they can be superimposed by a rotation. The program
 needs to know this because there is no reliable information about this
 polarity in the fiducial coordinates. However, such an inversion
 should be impossible when data are acquired with a CCD camera.
 Using Matching Models
 When fiducial points from Tiltalign are not available, the best
 option for dual-axis tomograms is to use Dualvolmatch instead of
 Solvematch. Otherwise, you can use models of corresponding points to
 register the two volumes in Solvematch. Pick a set of points that can
 be localized well in both tomograms and enter them in the same order
 into a model for each tomogram. The points can be in the same or in
 different objects or contours, as long as they occur in the same order
 in each model. The points should be well-distributed in all dimen-
 sions, and they must not all be in one plane. At least 8 points are
 recommended. If this is to provide the basis for the final alignment
 of the volumes, they should be relatively near the 8 corners of the
 volume, and more points should be used for greater accuracy; but if the
 alignment is to be refined with correlation, this is not necessary.
 Using Old, Relative Fiducial Coordinates
 With fiducial coordinates from older versions of Tiltalign, the pro-
 gram can solve for the 3 by 3 transformation but not for the shifts in
 X, Y and Z. There are several ways to get these shifts: by rerunning
 Tiltalign to get absolute coordinates; by finding the transformation
 with Dualvolmatch, or by giving Solvematch models of corresponding
 points in the two tomograms. If you create matching models, 3-6 points
 are recommended. If fiducials are essentially on one surface, then the
 modeled points are needed to find the scaling in Y (Z in flipped orien-
 tation) between the two tomograms. In this case, be sure to distribute
 the points in depth (rather than all on one surface) and use 5-6 points
 so as to provide information on this scaling.
 Local Fitting
 Sometimes the fit to the fiducial points gives a high maximum residual
 error because there is a big nonlinear distortion between the two vol-
 umes. In these cases, fitting to local sets of points can be used to
 determine that the fiducials have been properly identified and that the
 global fit is as good as it is ever going to be. If the LocalFitting
 option is selected, the program will try local fits when the maximum
 residual is above the specified limit. It determines the size of the
 area that, on average, would contain the specified minimum number of
 points. It then sets up local areas of this size, overlapping by 50%,
 and expands an area if necessary to contain the minimum number of
 points. It performs fits to the points in each area and reports the
 results of the fits. If the overall maximum residual is less than 1.5
 times the specified limit, and no more than 5% of the areas have maxi-
 mum residuals above this limit, the fit is considered adequate.
 If local fitting is being done, then the program will also compute a
 local fit to points at the center of the volume so as to determine how
 far the global 3D transformation will shift data at the center of the
 volume out of alignment. If this shift is large enough, then
 corrsearch3d may have trouble starting to find the alignment of the
 data. Thus, if the program finds that this shift is bigger than a
 specified limit, it recommends initial shifts to be used when running
 corrsearch3d and may also recommend that the initial matching volume
 be made the same size as the volume being transformed. It will exit
 with an error so that you can adjust these parameters before proceed-
 ing.
 Program Operation
 The program will automatically remove "outliers", pairs of points that
 are likely to be incorrect because their residual errors are so extreme
 relative to the other points. Up to 10% of points may be removed in
 this way. If, even after removing such outliers, the maximum residual
 in the linear fit is still higher than a value that you specify, then
 the program will exit with an error.
 The program determines the transformation and computes the deviation
 between each actual point in the first tomogram and the transformation
 of the corresponding point in the second tomogram. It reports the mean
 and S.D. of these deviations, the number of the point with the highest
 deviation, and the magnitude of its deviation.
OPTIONS
 Solvematch uses the PIP package for input (see the manual page for
 pip) and can also take input interactively to maintain compatibility
 with old command files. The following options can be specified either
 as command line arguments (with the -) or one per line in a command
 file or parameter file (without the -). Options can be abbreviated to
 unique letters; the currently valid abbreviations for short names are
 shown in parentheses.
 -output (-o) OR -OutputFile File name
 Output file for 3D transformation. This entry may be omitted.
 -afiducials (-af) OR -AFiducialFile File name
 Name of file with coordinates of fiducials from the first tilt
 series. To solve for the transformation using matching models
 only, omit this entry.
 -bfiducials (-bf) OR -BFiducialFile File name
 Name of file with coordinates of fiducials from the second tilt
 series. This entry is not needed when using matching models
 only.
 -alist (-al) OR -ACorrespondenceList List of integer ranges
 A list of the points in series 1 for which a corresponding point
 in series 2 is known with confidence. Ranges may be entered
 (e.g. 1-5,7,6,12). This entry and the following one are not
 needed when a coordinate file from transferfid is available.
 The default is that all points correspond between the two
 series.
 -blist (-bl) OR -BCorrespondenceList List of integer ranges
 A list of the corresponding points in the second series. The
 same number of values must be entered in this list as in the
 preceding list. Again, the default is that all points corre-
 spond between the two series.
 -transfer (-t) OR -TransferCoordinateFile File name
 File of matching fiducial coordinates produced by running trans-
 ferfid with the -c option.
 -amodel (-amo) OR -AFiducialModel File name
 Name of fiducial model file for first tilt series. This entry
 is needed only when a transfer coordinate file is being used.
 -bmodel (-bmo) OR -BFiducialModel File name
 Name of fiducial model file for second tilt series. This entry
 is needed only when a transfer coordinate file is being used.
 -use OR -UsePoints List of integer ranges
 List of starting points to use from the A axis (the first series
 taken). The program will start with these correspondences and
 add other pairs of points that appear to correspond.
 -atob OR -MatchingAtoB
 The first series here (referred to as A in these options) is the
 B axis, i.e. the second tilt series taken, and the second series
 is the A axis.
 -xtilts (-x) OR -XAxisTilts Two floats
 The values of X axis tilt that were used in generating the first
 and second tomograms. These angles are needed to make the fidu-
 cial coordinates from Tiltalign correspond to the actual posi-
 tions of the particles in the tomograms. The default values are
 0.
 -angles (-ang) OR -AngleOffsetsToTilt Two floats
 The values of tilt angle offsets that were used when running
 Tilt to generate the first and second tomograms. These are dif-
 ferent from the angle offsets used when running Tiltalign, which
 need not be supplied to Solvematch. The default values are 0.
 -zshifts (-z) OR -ZShiftsToTilt Two floats
 The values of Z shift that were used when running Tilt to gener-
 ate the first and second tomograms. These are different from
 the Z shifts used when running Tiltalign, which need not be sup-
 plied to Solvematch. The default values are 0.
 -surfaces (-su) OR -SurfacesOrUseModels Integer
 This entry governs the mode of operation of the program. To
 obtain the transformation from fiducial points only, enter:
 2 if there are fiducials on two surfaces,
 1 or -1 if fiducials are on only one surface,
 0 to use model files of corresponding points; with this entry
 both the matching model points and fiducial points will be used
 if the fiducials are available.
 -2 to use only the matching model points and ignore any entries
 of fiducial point files.
 The default is 2. When 1 or -1 is entered, the program will
 determine whether the tomograms are upside-down from each other
 (i.e., inverted in depth) by assuming that the tomograms have
 the same handedness.
 -inverted (-i) OR -InvertedInDepth Integer
 This option can be used with a -surfaces entry of 1 to prevent
 the program from analyzing whether tomograms are inverted by
 assuming that they have the same handedness. Enter 1 if tomo-
 grams are inverted in the depth dimension, or 0 if they are not.
 Tomograms are inverted if features at high Z in one tomogram are
 at low Z in the other; this property is independent of whether
 they are mirror images of each other. This entry should be
 needed only if tomograms are in fact mirror images.
 -maxresid (-m) OR -MaximumResidual Floating point
 The limiting value for the maximum residual, so that the program
 will exit with an error if this value is exceeded.
 -local (-l) OR -LocalFitting Integer
 Minimum number of points required in each local area if local
 fitting is desired. The default is 0, which disables local
 fits. Non-zero values must be at least 6.
 -center (-c) OR -CenterShiftLimit Floating point
 Maximum shift between central local fit and global fit. This
 shift is computed and tested against this limit only when local
 fitting occurs, namely when the -local option is selected and
 the global maximum residual is greater than the -maxresid entry.
 If the shift is greater than the limit, the program will exit
 with an error, but if the solution is adequate there is no need
 to rerun the program. The default value is 10. A value of 0
 disables the test.
 -amatch (-ama) OR -AMatchingModel File name
 Name of model of points from the first tomogram
 -bmatch (-bma) OR -BMatchingModel File name
 Name of model of corresponding points from the second tomogram
 -atomogram (-atom) OR -ATomogramOrSizeXYZ Text string
 Either the file name or the X, Y and Z dimensions of the first
 tomogram.
 -btomogram (-bt) OR -BTomogramOrSizeXYZ Text string
 Either the file name or the X, Y and Z dimensions of the second
 tomogram.
 -scales (-sc) OR -ScaleFactors Two floats
 Amounts by which the fiducial coordinates need to be scaled to
 match the coordinates of the first and second tomograms, respec-
 tively. Each factor should be the binning of the images on
 which the fiducials were modeled divided by the binning of the
 aligned stack. The entry should not be needed in ordinary cir-
 cumstances. It overrides the scaling that is computed from a
 pixel size in the fiducial file and the pixel spacing from the
 tomogram header. The entry can be used as a substitute for pro-
 viding the image file name in the -atomogram and -btomogram
 options.
 -aniso (-ani) OR -AnisotropicLimit Floating point
 The maximum percentage difference between the scaling along the
 three axes; a percentage difference greater than this limit will
 cause a warning to be issued. If the difference is in the Y
 direction and points were specified as being on two surfaces,
 the program will also advise that it be run with "-surfaces 1"
 instead. Enter 0 to disable these warnings. The default is
 10%.
 -param (-p) 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 and is restricted to older modes of operation. The
 input takes different forms depending on what data are available. The
 inputs to the program when fiducials from Tiltalign are available are:
 Name of file with coordinates of fiducials from the first tilt series
 Name of file with coordinates of fiducials from the second series
 A list of the points in series 1 for which a corresponding point in
 series 2 is known with confidence, or / if all points correspond
 between the two series.
 A list of the corresponding points in the second series, or / if all
 points correspond between the two series.
 The values of X axis tilt that were used in generating the first and
 second tomograms.
 The limiting value for the maximum residual, so that the program will
 exit with an error if this value is exceeded.
 Enter either 0 to determine shifts from model files of corresponding
 points, or -1, 1, or 2 to determine just the 3 by 3 transformation
 and not the shifts. Enter 2 if there are fiducials on two
 surfaces, 1 if fiducials are on one surface and the tomograms are
 NOT inverted relative to each other, or -1 if the tomograms are
 inverted and there are fiducials on only one surface.
 IF you entered 0, make the following four entries:
 Either the file name or the X, Y and Z dimensions of the first
 tomogram
 Name of model of points from the first tomogram
 Either the file name or the X, Y and Z dimensions of the second
 tomogram
 Name of model of points from the second tomogram
 Finally, enter name of file for output of the transformation, or
 Return for none
 Inputs to the program when matching models alone are being used:
 A blank line (Return) in place of the name of the first fiducial file
 The limiting value for the maximum residual
 Either the file name or the X, Y and Z size of the first tomogram
 Name of model of points from the first tomogram
 Either the file name or the X, Y and Z size of the second tomogram
 Name of model of points from the second tomogram
 Name of file for output of the transformation, or Return for none
HISTORY
 Written by David Mastronarde, 1995; modified for zero shifts, 7/4/97
 Added outlier elimination and error exit, 6/5/99
 Added ability to start with small initial set of matches, 3/20/00
 Added ability to use matching models only, 7/21/02
 Fixed treatment of single-surface case and converted to PIP, 12/24/03
 Added ability to deal with absolute fiducial coordinates, 6/9/04
BUGS
 Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 solvematch(1)