1 #if !defined(ATPMATCH_H) 2 #define ATPMATCH_H 3 4 /* 5 * 6 * FILE: atPMatch.h 7 * 8 * DESCRIPTION: 9 * Definitions for structures used in the matching of two sets 10 * of objects to find the transformation that takes one to the other. 11 * 12 * The algorithms used are based on the paper by Valdes et al., 13 * PASP 107, 1119 (1995). 14 * 15 * This version allows 8 coefficients in each dimension, not just 3. 16 * MWR 5/24/2000 17 * 18 * This version allows linear, quadratic, or cubic transformations. 19 * MWR 6/10/2000 20 */ 21 22 /* 23 * any warning messages printed will come out 24 * at this error level 25 */ 26 #define AT_MATCH_ERRLEVEL 2 27 28 /* 29 * this is the default radius for matching triangles in triangle space. 30 * The units are NOT pixels, or arcseconds, but a fraction of the 31 * range of normalized ratios of side lengths in a triangle, 0.0 to 1.0. 32 * 33 * This is the default value. The user can override it with an optional 34 * command-line argument. 35 */ 36 #define AT_TRIANGLE_RADIUS 0.002 37 38 /* 39 * this is the default radius for matching stars to each other, 40 * _after_ both sets have been transformed into a common coordinate 41 * system. The units are those of the second list. This 42 * default value assumes that the second list has units which are 43 * close to the size of a star (i.e. arcseconds, or pixels). 44 */ 45 #define AT_MATCH_RADIUS 5.0 46 47 /* 48 * This is the largest permitted distance between the coords of 49 * a matched pair of stars in the common coord system, after 50 * we've made an attempt at transforming them. This value 51 * is used in the "iter_trans" procedure. 52 * 53 * Like "AT_MATCH_RADIUS", above, it assumes the second list has 54 * units close to the size of a star. 55 */ 56 #define AT_MATCH_MAXDIST 50.0 57 58 /* 59 * as a first step in the matching process, we sort each group of 60 * stars by magnitude and select the AT_MATCH_NBRIGHT brightest items; 61 * these are used to find a rough coordinate transformation. 62 * 63 * This is the default value. The user can override it with an optional 64 * command-line argument. 65 */ 66 #define AT_MATCH_NBRIGHT 20 67 68 /* 69 * ignore all triangles which have (b/a) > AT_MATCH_RATIO when 70 * trying to match up sets of triangles. If AT_MATCH_RATIO 71 * is set to 1.0, then all triangles will be used. 72 */ 73 #define AT_MATCH_RATIO 0.9 74 75 /* 76 * We require AT LEAST this many matched pairs of stars to 77 * calculate a TRANS structure; fail if we are given fewer, 78 * or if we discard so many that we have fewer than this many 79 */ 80 #define AT_MATCH_REQUIRE_LINEAR 3 81 #define AT_MATCH_REQUIRE_QUADRATIC 6 82 #define AT_MATCH_REQUIRE_CUBIC 8 83 84 /* 85 * We start with the top "AT_MATCH_STARTN" candidates of 86 * matched pairs, when we enter the iterative process 87 * of finding a TRANS. Must be >= AT_MATCH_REQUIRE 88 */ 89 #define AT_MATCH_STARTN_LINEAR 6 90 #define AT_MATCH_STARTN_QUADRATIC 12 91 #define AT_MATCH_STARTN_CUBIC 16 92 93 /* 94 * when iterating to throw out mis-matched pairs of stars, 95 * use this percentile in a sorted array of discrepancies 96 * as an effective "sigma". Throw out any pairs with 97 * discrepancy more than AT_MATCH_NSIGMA*"sigma". 98 * 99 * Values of 0.60-0.70 work well for AT_MATCH_PERCENTILE 100 * Values of 2-3 AT_MATCH_NSIGMA 101 */ 102 #define AT_MATCH_PERCENTILE 0.35 103 #define AT_MATCH_NSIGMA 10.0 104 105 /* 106 * We go through a loop of 107 * - calculate TRANS for current matching pairs 108 * - look at the residuals for that TRANS 109 * - discard discrepant pairs, go to top of loop 110 * in the "iter_trans" function. This sets the maximum 111 * number of times we go through that loop. 112 * 113 * The user can modify this limit via the "max_iter" 114 * command-line argument. 115 */ 116 #define AT_MATCH_MAXITER 3 117 118 119 /* 120 * When we are evaluating the current TRANS, we calculate the 121 * residuals for matching pairs of stars. If the "sigma" 122 * (effective median residual) is smaller than this value, 123 * we stop iterating and declare success. 124 * 125 * This value is (typically) in radians-squared. So a residual 126 * of one arcsecond corresponds to sigma = 2.35E-11. 127 * 128 * The user can modify this value via the "halt_sigma" 129 * command-line argument. 130 */ 131 #define AT_MATCH_HALTSIGMA 1.0e-12 132 133 134 /* 135 * we allow a match between two stars only if they appear in this 136 * many matching triangles 137 */ 138 #define AT_MATCH_MINVOTES 2 139 140 /* 141 * If desired, when comparing two triangles, we count them as a match 142 * only if the ratio of their sides (indicated by "a_length") 143 * is within this many percent of an expected value. 144 * The default is to allow any ratio of triangle sizes. 145 * 146 * A value of "10" means "ratio must match expected value to 10 percent" 147 */ 148 #define AT_MATCH_PERCENT 10 149 150 /* 151 * If desired, the user may specify that two triangles count as a match 152 * only if their relative orientation falls within some range 153 * of rotation (in degrees). However, if the user does NOT 154 * specify such a desired range, we can use this value as a marker 155 * to denote that any rotation is permitted. 156 */ 157 #define AT_MATCH_NOANGLE -999.0 158 159 /* 160 * this holds information on a single star (or object) 161 */ 162 typedef struct s_star { 163 int id; /* used for internal debugging purposes only */ 164 int index; /* position of this star in its linked list */ 165 double x; /* star's "X" coordinate */ 166 double y; /* star's "Y" coordinate */ 167 double mag; /* some measure of star's brightness */ 168 int match_id; /* ID of star in other list which matches */ 169 struct s_star *next; /* we use linked lists internally */ 170 } s_star; 171 172 173 /* 174 * this holds information on triangles, used internally for matching. 175 * note that when a triangle is formed, the vertices are identified 176 * so that 177 * side a = dist(bc) is the longest side 178 * b = dist(ac) is the second-longest side 179 * c = dist(ab) is the shortest side 180 * 181 * side_a_angle is the angle in radians defined by 182 * the longest side, relative to x-axis 183 */ 184 typedef struct s_triangle { 185 int id; /* used for internal debugging purposes only */ 186 int index; /* position of this triangle in its linked list */ 187 double a_length; /* length of side a (not normalized) */ 188 double ba; /* ratio of lengths b/a ... must be 0.0-1.0 */ 189 double ca; /* ratio of lengths c/a ... must be 0.0-1.0 */ 190 int a_index; /* index of the star opposite side a */ 191 int b_index; /* index of the star opposite side b */ 192 int c_index; /* index of the star opposite side c */ 193 int match_id; /* ID of triangle in other list which matches */ 194 double side_a_angle; /* angle from one star to other in longest side */ 195 struct s_triangle *next; /* we use linked lists internally */ 196 } s_triangle; 197 198 199 /* 200 * these functions are PUBLIC, and may be called by users 201 */ 202 203 int atFindTrans(int numA, s_star *listA, int numB, s_star *listB, 204 double radius, int nbright, double min_scale, double max_scale, 205 double rotation_deg, double tolerance_deg, 206 int max_iter, double halt_sigma, TRANS *trans); 207 208 int atApplyTrans(int num, s_star *list, TRANS *trans); 209 210 int atMatchLists(int numA, s_star *listA, int numB, s_star *listB, 211 double radius, char *basename, int *num_matches); 212 213 int 214 atBuildSmallFile(double ra, double dec, 215 int numA, struct s_star *listA, int nobj, char *outfile); 216 217 int 218 atSmallTrans(int numA, struct s_star *listA, 219 int numB, struct s_star *star_array_B, 220 int num_triangles_B, struct s_triangle *triangle_array_B, 221 double radius, int nobj, double min_scale, double max_scale, 222 double rotation_deg, double tolerance_deg, 223 int max_iter, double halt_sigma, 224 TRANS *trans, int *ntop, int **top_votes); 225 226 int 227 atRecalcTrans(int numA, struct s_star *listA, 228 int numB, struct s_star *listB, 229 int max_iter, double halt_sigma, TRANS *trans); 230 231 int atFindMedtf(int num_matched_A, s_star *listA, 232 int num_matched_B, s_star *listB, 233 double medsigclip, MEDTF *medtf); 234 235 int 236 atCalcRMS(int num_A, struct s_star *mlistA, 237 int num_B, struct s_star *mlistB, 238 double *Dx_rms, double *Dy_rms); 239 240 #endif /* ATPMATCH_H */ 241