Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

SOLVEMATCH(1)							  SOLVEMATCH(1)

NAME
	solvematch - Solve for transformation matching one tomogram to another

SYNOPSIS
	solvematch

DESCRIPTION
  Solvematch will solve for a 3-dimensional linear transformation
  relating the tomogram volumes resulting from tilt series around two
  different 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 versions of Tiltalign produce fiducial lists with coordinates
  corresponding the coordinates in the tomogram, thus providing all of
  the information that Solvematch needs to find the transformation.  Older
  versions of Tiltalign produced coordinates centered around zero; this
  situation 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 correspond.  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 surfaces
  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 contour 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 coordinates 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 Solvematch
  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, you can use
  models of corresponding points to register the two volumes.  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 dimensions, 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 program
  can solve for the 3 by 3 transformation but not for the shifts in X, Y
  and Z.  There are two ways to get these shifts: by cross-correlation
  of one transformed volume with the other, and by giving Solvematch
  models of corresponding points in the two tomograms.  The shell script
  that does correlations, Matchshifts, is generally successful.  If it
  fails, you have two options: rerun Tiltalign to get absolute
  coordinates; or create matching models.  If you do this, 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
  orientation) 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
  volumes.  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 maximum 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 proceeding.

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.

Inputs and 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 -):

 -output OR -OutputFile   File name
    Output file for 3D transformation.  This entry may be omitted.

 -afiducials 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 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 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 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 correspond between the two series.

 -transfer OR -TransferCoordinateFile   File name
    File of matching fiducial coordinates produced by running transferfid with
    the -c option.

 -amodel 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 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 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 fiducial
    coordinates from Tiltalign correspond to the actual positions of the
    particles in the tomograms.  The default values are 0.

 -angles 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 different from the
    angle offsets used when running Tiltalign, which need not be supplied to
    Solvematch.  The default values are 0.

 -zshifts OR -ZShiftsToTilt   Two floats
    The values of Z shift that were used when running Tilt to generate the
    first and second tomograms.  These are different from the Z shifts used
    when running Tiltalign, which need not be supplied to Solvematch.  The
    default values are 0.

 -surfaces 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 if fiducials are on one surface and the tomograms are NOT inverted
    relative to each other, 
     -1 if the tomograms are inverted and there are fiducials 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.

 -maxresid 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 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 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 OR -AMatchingModel   File name
    Name of model of points from the first tomogram

 -bmatch OR -BMatchingModel   File name
    Name of model of corresponding points from the second tomogram

 -atomogram OR -ATomogramOrSizeXYZ   Text string
    Either the file name or the X, Y and Z dimensions of the first tomogram.

 -btomogram OR -BTomogramOrSizeXYZ   Text string
    Either the file name or the X, Y and Z dimensions of the second tomogram.

 -scales OR -ScaleFactors   Two floats
    Amounts by which the fiducial coordinates need to be scaled to match the
    coordinates of the first and second tomograms, respectively.  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 circumstances.  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 providing
    the image file name in the -atomogram and -btomogram options.

 -aniso 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 OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.


Old Style 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