% @(#)find_pair.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:18:47
\se
SECTION./PAIR
\es\co
FIND/PAIR  	                                                20-Oct-1991 RHW
\oc\su
FIND/PAIR intab1 intab2 outtab colums [errors] [coo_sys]
	match (pair) two coordinates tables and produce an output table
\us\pu
Purpose:  
          Match (pair) two point sets with coordinates in table files INA 
          and INB. The common set of points form a new table file OUTA with 
          added columns, excluded points are appended to the common set,
\up\sy
Syntax:   
          FIND/PAIR intab1 intab2 outtab columns [errors] [coo_sys]
\ys\pa
          intab1       = first input table; no default.
\ap\pa
          intab2e      = second input table; no default.
\ap\pa
          outtab       = output table, containing common data point of the two
                         input tables; no default.
\ap\pa
          colunms      = columns number of the first input table containing the 
                         x and y coordinates, followed by the columns in the 
                         second input table; no default.
\ap\pa
          errors       = estimated separations in X and Y between 1st and 2nd 
                         tables. The first two values contain the maximum
                         residual distance after coordinate translation (in X 
                         and Y), the second two vaules the maximum residual
                         distance after coordinate rotation. Default is 
                         0.0,0.0,2.0,2.0
\ap\pa    
          coo_sys      = coordinate transformation option:\\
                         0: coordinates in their own systems (default);\\
                         1: 2nd system transformed to 1st system.
\ap\no
Note:     
          Both object sets should have almost the same scale and orientation.
\\
          It is possible to apply PAIR several times, building up merged 
          tables of increasing complexity, containing three or more original 
          subtables. Note, that at any time only two sets of X,Y coordinates 
          are fully treated; X,Y coordinates associated with other subtables
          may gradually be lost (set to NULL element).
          Therefore, it is advisable to always keep one fixed (+extended)
          set of X,Y coordinates (fixed column nos) as the first system
          (1st table for example) in the next pairing.
\\
          Second set of labels have characters 14-16 replaced with
          column numbers in order to avoid repeated label names;
          embedded blanks are replaced with underscore (_).
\\
          In determining the pair of objects, the common translation vector is
          estimated as the mode of histogram of X,Y separations. In the second
          iteration a small coordinate rotation is made.
\\
          Not matched points are added at the end of the output table,
          left or right coming from the 1st or 2nd table, respectively.
\\
          Maximum number of objects in each table is limited to 50000.
\on\see
See also: 
          Tables commands
\ees\exs
Examples:
\ex
          FIND/PAIR B346 U346 BU 10,11,10,11 0.,0.,40.,30.
          Combines table files B3460120 and U3460005 into table BU using X,Y 
          column nos 10,11 and 10,11 for 1st and 2nd input file, assumed X,Y 
          translation 0.,0. between 1st and 2nd system, tolerances 40. and 30. 
          units (here microns), where the 1st tolerance assumes no rotation 
          nbetween the systems. In a second iteration a small (max 1 degree) 
          corrective rotation and a very minor rescaling is applied and the 
          matching is repeated with a new more restrictive tolerance.\\
          The following message may be displayed (mean translation within 
          brackets):\\
          B346 - U346: (  56.193  12.663)   260 + 211 objects => 180 pairs\\
          residual:   DX=  0.12231E+02 +  0.697E-05 * X + -0.133E-02 * Y\\
          rotation:   DY= -0.27403E+02 +  0.135E-02 * X +  0.132E-03 * Y\\
          B346 - U346: (  53.832   8.699)   260 + 211 objects => 177 pairs
\xe \sxe