FreeBSD Manual Pages
match(1) USER COMMANDS match(1) name match - match two lists of stars synopsis match fileA xcolA ycolA magcolA fileB xcolB ycolB magcolB [id1=] [id2=] [max_iter=] [halt_sigma=] [outfile=] [trirad=] [nobj=] [matchrad=] [scale=] [min_scale=] [max_scale=] [transonly] [recalc] [linear|quadratic|cubic] [medtf] [medsigclip=] [intrans=] [identity [xsh=] [ysh=]] [--version] [--help] [help] DESCRIPTION This program is designed to match up items in two different lists, which may have two different systems of coordinates. The program al- lows the two sets of coordinates to be related by a linear, quadratic, or cubic transformation. It is an implementation of the algorithm de- scribed in Valdes et al., Publications of the Astronomical Society of the Pacific, vol 107, page 1119 (1995); see also Droege et al., Publi- cations of the Astronomical Society of the Pacific, vol 118, page 1666 (2006). The basic idea is to select the brightest nobj objects from each list, then to create a (very large) set of triangles using the stars in each list. By finding similar triangles in the two sets, one can identify matching stars from the two lists. This method is insensitive to translation, rotation, scaling, and inversion, but it can take a long time. After finding candidate matching pairs, the program enters a loop in which it computes a geometric transformation, determines the residuals between the actual and transformed coordinates, and discards the the most discrepant items; the user can set parameters controlling the iteration of this loop using command-line arguments max_iter and halt_sigma. OPTIONS id1=N column in fileA containing "ID" value of items id2=N column in fileB containing "ID" value of items (the values must be unique within each list; the program will not check, and strange behavior will result if duplicate IDs occur) outfile=abc place output in files with base name "abc" abc.mtA items from list A which had matches in list B abc.mtB items from list B which had matches in list A abc.unA items from list A which had no matches in list B abc.unB items from list B which had no matches in list A trirad=0.001 critical value for counting triangles as a match (default value 0.002; see below) nobj=30 use the brightest 'nobj' values in each list during the matching process (default value 20) matchrad=4 after applying transformation to listA, so that both lists are in coordinate system of listB, items from the two lists must be within this distance to count as 'matched' (default value 5) scale=2.0 if present, only triangles with the given scale factor are counted as matches (in this example, only triangles in coord system A which are about 2.0 times larger than triangles in co- ord system B are counted as matches) min_scale=1.5 if present, only triangles with ratios greater than the given scale factor are counted as matches max_scale=2.5 if present, only triangles with ratios less than the given scale factor are counted as matches max_iter=3 during the solution process, there is a loop in which the code matches stars in the two lists, finds the residuals for each pair, and discards pairs with big residuals. This argument sets a limit on the number of times this loop can be entered. De- fault value is given by AT_MATCH_MAXITER parameter in atp- match.h, currently 3. halt_sigma=1.0e-12 during the solution process, if the typical residual between pairs of stars in the two lists drops to this level, stop iter- ating and declare success. The units are the square of the units in the second list of stars; often, radians squared. De- fault value is given by AT_MATCH_HALTSIGMA parameter in atp- match.h, currently 1.0e-12. transonly if present, stop after having derived a transformation which best takes the 'nobj' objects from list A into objects in list B. Don't go on to find the matching objects explicitly. recalc if present, after having derived a transformation with the brightest 'nobj' objects, and having applied that transformation to ALL the objects in list A, derive a transformation again, this time using ALL the objects in list A and list B linear use a linear transformation (the default) quadratic use a quadratic transformation cubic use a cubic transformation medtf calculate the MEDTF statistics (see below); assumes that a sim- ple translation connects the two lists medsigclip=N discard matched pairs more than N stdev from the median offset before calculating MEDTF statistics identity as an initial guess, use a linear TRANS in which there is no ro- tation, change in scale, or translation (unless xsh= and ysh= are specified) xsh= in initial guess, use linear TRANS with the given translation in the 'x' direction ysh= in initial guess, use linear TRANS with the given translation in the 'x' direction intrans=file as an initial guess, use the TRANS which is given in the ASCII text file 'file' (see below for the format) --version print the current version number and exit --help print list of command-line options help print list of command-line options The argument "trirad" may need some extra explanation. For a full de- sciption, see the paper by Valdes et al. In short, stars are grouped into triangles, the sides of which are labelled "a", "b" and "c" in or- der of decreasing size. The normalized ratios b/a and c/a are formed for each triangle. In order for a triangle, t1, from one list to be considered identical to a triangle, t2, in the other list, it must satisfy the equation sqrt[ (t1.ba - t2.ba)^2 + (t1.ca - t2.ca)^2 ] <= trirad So the value of "trirad" has units of neither list; it exists in a two- dimensional "triangle-space" formed by the coordinates b/a and c/a (each of which ranges from 0.0 to 1.0). One way the user can control the matching of triangles is to specify a "scale factor". Only triangles with a ratio of size falling with a particular window will be counted as matches. The user can control the "scale factor window" in two ways: using the scale= option alone; for example, scale=1.5 The window is centered on the given factor, and extends a percentage (AT_MATCH_PERCENT) above it and below it. using both min_scale and max_scale together; for example, min_scale=1.3 max_scale=1.7 The window extends from the min_scale to max_scale, including both boundaries. If the two lists are known to have the same scale and rotation, the user may use the identity keyword to force an initial guess at the TRANS: a linear model with a=0.0 b=1.0 c=0.0 d=0.0 e=0.0 f=1.0 The program will use this initial TRANS structure to match up the items in the two lists, rather than trying to figure out the transformation itself. After looking for matched items with this fixed model, the program will use the matched pairs it finds to define an improved TRANS. In a similar vein, if the user knows that the scale and rotation of the two sets of objects are identical, but there is a fixed and known translation of XX units in the x-direction and YY units in the y-direc- tion, he can use the identity keyword with additional arguments xsh=XX ysh=YY which will create an initial TRANS with a=XX b=1.0 c=0.0 d=YY e=0.0 f=1.0 Finally, for ultimate control, the user may specify the exact values of the coefficients for the initial TRANS via the intrans=filename option. The program will look for an ASCII text file with the given filename, which must have the following format: a) blank lines are skipped b) lines starting with the '#' character are skipped c) the first non-skipped line must describe the order of the model, either by one of the following keywords linear quadratic cubic or by a line like norder=NN, in which NN has value 1 for linear, 2 for quadratic, or 3 for cubic. d) all following non-blank lines must give values for the coefficients of the specified TRANS model, in the general form a=33.34 b=1.3e-4 c 99.01 d -5.323e1 Note that the equals sign between the coefficient and the value is optional In any case, if the user specifies the initial TRANS, either via the identity or intrans method, that initial model is used to convert the coordinates of objects in list A into the system of list B. The pro- gram then looks for matches within the matchrad units. It then uses only the matched pairs to generate an improved TRANS model. On the other hand, if the user does NOT provide an initial TRANS model, the program searches for one itself. After its first guess, the code matches up candidate pairs of stars from the two lists. It then enters a loop in which it calculates a plate solution, applies the solution to the stars in list A, then compares the predicted positions from list A to the actual positions of stars in list B. Based on those residuals, the code marks some of the pairs as "bad", discards them, and goes back to the top of the loop. The max_iter and halt_sigma arguments can be used to control the number of times the code enters this loop and dis- cards possible matches. Note that, if one uses the project_coords rou- tine to turn (RA, Dec) positions from a catalog into an input list, the units will of this list will be radians; hence, the residuals from a solution against this list will be in radians squared. A typical residual of 1 arcsec corresponds to halt_sigma of 2.4e-11 radians squared. SEE ALSO The web pages for the match program contain additional documentation and a description of the associated project_coords and apply_match pro- grams. Read them at http://spiff.rit.edu/match/ AUTHOR Michael Richmond < mwrsps at rit dot edu > version 0.13 November 30, 2010 match(1)
name | synopsis | DESCRIPTION | OPTIONS | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=match&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>