00001 /*============================================================================ 00002 00003 WCSLIB 4.13 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2012, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see <http://www.gnu.org/licenses/>. 00020 00021 Correspondence concerning WCSLIB may be directed to: 00022 Internet email: mcalabre@atnf.csiro.au 00023 Postal address: Dr. Mark Calabretta 00024 Australia Telescope National Facility, CSIRO 00025 PO Box 76 00026 Epping NSW 1710 00027 AUSTRALIA 00028 00029 Author: Mark Calabretta, Australia Telescope National Facility 00030 http://www.atnf.csiro.au/~mcalabre/index.html 00031 $Id: cel.h,v 4.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $ 00032 *============================================================================= 00033 * 00034 * WCSLIB 4.13 - C routines that implement the FITS World Coordinate System 00035 * (WCS) standard. Refer to 00036 * 00037 * "Representations of world coordinates in FITS", 00038 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I) 00039 * 00040 * "Representations of celestial coordinates in FITS", 00041 * Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II) 00042 * 00043 * Refer to the README file provided with WCSLIB for an overview of the 00044 * library. 00045 * 00046 * 00047 * Summary of the cel routines 00048 * --------------------------- 00049 * These routines implement the part of the FITS World Coordinate System (WCS) 00050 * standard that deals with celestial coordinates. They define methods to be 00051 * used for computing celestial world coordinates from intermediate world 00052 * coordinates (a linear transformation of image pixel coordinates), and vice 00053 * versa. They are based on the celprm struct which contains all information 00054 * needed for the computations. This struct contains some elements that must 00055 * be set by the user, and others that are maintained by these routines, 00056 * somewhat like a C++ class but with no encapsulation. 00057 * 00058 * Routine celini() is provided to initialize the celprm struct with default 00059 * values, celfree() reclaims any memory that may have been allocated to store 00060 * an error message, and celprt() prints its contents. 00061 * 00062 * A setup routine, celset(), computes intermediate values in the celprm struct 00063 * from parameters in it that were supplied by the user. The struct always 00064 * needs to be set up by celset() but it need not be called explicitly - refer 00065 * to the explanation of celprm::flag. 00066 * 00067 * celx2s() and cels2x() implement the WCS celestial coordinate 00068 * transformations. In fact, they are high level driver routines for the lower 00069 * level spherical coordinate rotation and projection routines described in 00070 * sph.h and prj.h. 00071 * 00072 * 00073 * celini() - Default constructor for the celprm struct 00074 * ---------------------------------------------------- 00075 * celini() sets all members of a celprm struct to default values. It should 00076 * be used to initialize every celprm struct. 00077 * 00078 * Returned: 00079 * cel struct celprm* 00080 * Celestial transformation parameters. 00081 * 00082 * Function return value: 00083 * int Status return value: 00084 * 0: Success. 00085 * 1: Null celprm pointer passed. 00086 * 00087 * 00088 * celfree() - Destructor for the celprm struct 00089 * -------------------------------------------- 00090 * celfree() frees any memory that may have been allocated to store an error 00091 * message in the celprm struct. 00092 * 00093 * Given: 00094 * cel struct celprm* 00095 * Celestial transformation parameters. 00096 * 00097 * Function return value: 00098 * int Status return value: 00099 * 0: Success. 00100 * 1: Null celprm pointer passed. 00101 * 00102 * 00103 * celprt() - Print routine for the celprm struct 00104 * ---------------------------------------------- 00105 * celprt() prints the contents of a celprm struct using wcsprintf(). Mainly 00106 * intended for diagnostic purposes. 00107 * 00108 * Given: 00109 * cel const struct celprm* 00110 * Celestial transformation parameters. 00111 * 00112 * Function return value: 00113 * int Status return value: 00114 * 0: Success. 00115 * 1: Null celprm pointer passed. 00116 * 00117 * 00118 * celset() - Setup routine for the celprm struct 00119 * ---------------------------------------------- 00120 * celset() sets up a celprm struct according to information supplied within 00121 * it. 00122 * 00123 * Note that this routine need not be called directly; it will be invoked by 00124 * celx2s() and cels2x() if celprm::flag is anything other than a predefined 00125 * magic value. 00126 * 00127 * Given and returned: 00128 * cel struct celprm* 00129 * Celestial transformation parameters. 00130 * 00131 * Function return value: 00132 * int Status return value: 00133 * 0: Success. 00134 * 1: Null celprm pointer passed. 00135 * 2: Invalid projection parameters. 00136 * 3: Invalid coordinate transformation parameters. 00137 * 4: Ill-conditioned coordinate transformation 00138 * parameters. 00139 * 00140 * For returns > 1, a detailed error message is set in 00141 * celprm::err if enabled, see wcserr_enable(). 00142 * 00143 * 00144 * celx2s() - Pixel-to-world celestial transformation 00145 * -------------------------------------------------- 00146 * celx2s() transforms (x,y) coordinates in the plane of projection to 00147 * celestial coordinates (lng,lat). 00148 * 00149 * Given and returned: 00150 * cel struct celprm* 00151 * Celestial transformation parameters. 00152 * 00153 * Given: 00154 * nx,ny int Vector lengths. 00155 * 00156 * sxy,sll int Vector strides. 00157 * 00158 * x,y const double[] 00159 * Projected coordinates in pseudo "degrees". 00160 * 00161 * Returned: 00162 * phi,theta double[] Longitude and latitude (phi,theta) in the native 00163 * coordinate system of the projection [deg]. 00164 * 00165 * lng,lat double[] Celestial longitude and latitude (lng,lat) of the 00166 * projected point [deg]. 00167 * 00168 * stat int[] Status return value for each vector element: 00169 * 0: Success. 00170 * 1: Invalid value of (x,y). 00171 * 00172 * Function return value: 00173 * int Status return value: 00174 * 0: Success. 00175 * 1: Null celprm pointer passed. 00176 * 2: Invalid projection parameters. 00177 * 3: Invalid coordinate transformation parameters. 00178 * 4: Ill-conditioned coordinate transformation 00179 * parameters. 00180 * 5: One or more of the (x,y) coordinates were 00181 * invalid, as indicated by the stat vector. 00182 * 00183 * For returns > 1, a detailed error message is set in 00184 * celprm::err if enabled, see wcserr_enable(). 00185 * 00186 * 00187 * cels2x() - World-to-pixel celestial transformation 00188 * -------------------------------------------------- 00189 * cels2x() transforms celestial coordinates (lng,lat) to (x,y) coordinates in 00190 * the plane of projection. 00191 * 00192 * Given and returned: 00193 * cel struct celprm* 00194 * Celestial transformation parameters. 00195 * 00196 * Given: 00197 * nlng,nlat int Vector lengths. 00198 * 00199 * sll,sxy int Vector strides. 00200 * 00201 * lng,lat const double[] 00202 * Celestial longitude and latitude (lng,lat) of the 00203 * projected point [deg]. 00204 * 00205 * Returned: 00206 * phi,theta double[] Longitude and latitude (phi,theta) in the native 00207 * coordinate system of the projection [deg]. 00208 * 00209 * x,y double[] Projected coordinates in pseudo "degrees". 00210 * 00211 * stat int[] Status return value for each vector element: 00212 * 0: Success. 00213 * 1: Invalid value of (lng,lat). 00214 * 00215 * Function return value: 00216 * int Status return value: 00217 * 0: Success. 00218 * 1: Null celprm pointer passed. 00219 * 2: Invalid projection parameters. 00220 * 3: Invalid coordinate transformation parameters. 00221 * 4: Ill-conditioned coordinate transformation 00222 * parameters. 00223 * 6: One or more of the (lng,lat) coordinates were 00224 * invalid, as indicated by the stat vector. 00225 * 00226 * For returns > 1, a detailed error message is set in 00227 * celprm::err if enabled, see wcserr_enable(). 00228 * 00229 * 00230 * celprm struct - Celestial transformation parameters 00231 * --------------------------------------------------- 00232 * The celprm struct contains information required to transform celestial 00233 * coordinates. It consists of certain members that must be set by the user 00234 * ("given") and others that are set by the WCSLIB routines ("returned"). Some 00235 * of the latter are supplied for informational purposes and others are for 00236 * internal use only. 00237 * 00238 * Returned celprm struct members must not be modified by the user. 00239 * 00240 * int flag 00241 * (Given and returned) This flag must be set to zero whenever any of the 00242 * following celprm struct members are set or changed: 00243 * 00244 * - celprm::offset, 00245 * - celprm::phi0, 00246 * - celprm::theta0, 00247 * - celprm::ref[4], 00248 * - celprm::prj: 00249 * - prjprm::code, 00250 * - prjprm::r0, 00251 * - prjprm::pv[], 00252 * - prjprm::phi0, 00253 * - prjprm::theta0. 00254 * 00255 * This signals the initialization routine, celset(), to recompute the 00256 * returned members of the celprm struct. celset() will reset flag to 00257 * indicate that this has been done. 00258 * 00259 * int offset 00260 * (Given) If true (non-zero), an offset will be applied to (x,y) to 00261 * force (x,y) = (0,0) at the fiducial point, (phi_0,theta_0). 00262 * Default is 0 (false). 00263 * 00264 * double phi0 00265 * (Given) The native longitude, phi_0 [deg], and ... 00266 * 00267 * double theta0 00268 * (Given) ... the native latitude, theta_0 [deg], of the fiducial point, 00269 * i.e. the point whose celestial coordinates are given in 00270 * celprm::ref[1:2]. If undefined (set to a magic value by prjini()) the 00271 * initialization routine, celset(), will set this to a projection-specific 00272 * default. 00273 * 00274 * double ref[4] 00275 * (Given) The first pair of values should be set to the celestial 00276 * longitude and latitude of the fiducial point [deg] - typically right 00277 * ascension and declination. These are given by the CRVALia keywords in 00278 * FITS. 00279 * 00280 * (Given and returned) The second pair of values are the native longitude, 00281 * phi_p [deg], and latitude, theta_p [deg], of the celestial pole (the 00282 * latter is the same as the celestial latitude of the native pole, 00283 * delta_p) and these are given by the FITS keywords LONPOLEa and LATPOLEa 00284 * (or by PVi_2a and PVi_3a attached to the longitude axis which take 00285 * precedence if defined). 00286 * 00287 * LONPOLEa defaults to phi_0 (see above) if the celestial latitude of the 00288 * fiducial point of the projection is greater than or equal to the native 00289 * latitude, otherwise phi_0 + 180 [deg]. (This is the condition for the 00290 * celestial latitude to increase in the same direction as the native 00291 * latitude at the fiducial point.) ref[2] may be set to UNDEFINED (from 00292 * wcsmath.h) or 999.0 to indicate that the correct default should be 00293 * substituted. 00294 * 00295 * theta_p, the native latitude of the celestial pole (or equally the 00296 * celestial latitude of the native pole, delta_p) is often determined 00297 * uniquely by CRVALia and LONPOLEa in which case LATPOLEa is ignored. 00298 * However, in some circumstances there are two valid solutions for theta_p 00299 * and LATPOLEa is used to choose between them. LATPOLEa is set in ref[3] 00300 * and the solution closest to this value is used to reset ref[3]. It is 00301 * therefore legitimate, for example, to set ref[3] to +90.0 to choose the 00302 * more northerly solution - the default if the LATPOLEa keyword is omitted 00303 * from the FITS header. For the special case where the fiducial point of 00304 * the projection is at native latitude zero, its celestial latitude is 00305 * zero, and LONPOLEa = +/- 90.0 then the celestial latitude of the native 00306 * pole is not determined by the first three reference values and LATPOLEa 00307 * specifies it completely. 00308 * 00309 * The returned value, celprm::latpreq, specifies how LATPOLEa was actually 00310 * used. 00311 * 00312 * struct prjprm prj 00313 * (Given and returned) Projection parameters described in the prologue to 00314 * prj.h. 00315 * 00316 * double euler[5] 00317 * (Returned) Euler angles and associated intermediaries derived from the 00318 * coordinate reference values. The first three values are the Z-, X-, and 00319 * Z'-Euler angles [deg], and the remaining two are the cosine and sine of 00320 * the X-Euler angle. 00321 * 00322 * int latpreq 00323 * (Returned) For informational purposes, this indicates how the LATPOLEa 00324 * keyword was used 00325 * - 0: Not required, theta_p (== delta_p) was determined uniquely by the 00326 * CRVALia and LONPOLEa keywords. 00327 * - 1: Required to select between two valid solutions of theta_p. 00328 * - 2: theta_p was specified solely by LATPOLEa. 00329 * 00330 * int isolat 00331 * (Returned) True if the spherical rotation preserves the magnitude of the 00332 * latitude, which occurs iff the axes of the native and celestial 00333 * coordinates are coincident. It signals an opportunity to cache 00334 * intermediate calculations common to all elements in a vector 00335 * computation. 00336 * 00337 * struct wcserr *err 00338 * (Returned) If enabled, when an error status is returned this struct 00339 * contains detailed information about the error, see wcserr_enable(). 00340 * 00341 * void *padding 00342 * (An unused variable inserted for alignment purposes only.) 00343 * 00344 * Global variable: const char *cel_errmsg[] - Status return messages 00345 * ------------------------------------------------------------------ 00346 * Status messages to match the status value returned from each function. 00347 * 00348 *===========================================================================*/ 00349 00350 #ifndef WCSLIB_CEL 00351 #define WCSLIB_CEL 00352 00353 #include "prj.h" 00354 #include "wcserr.h" 00355 00356 #ifdef __cplusplus 00357 extern "C" { 00358 #endif 00359 00360 00361 extern const char *cel_errmsg[]; 00362 00363 enum cel_errmsg_enum { 00364 CELERR_SUCCESS = 0, /* Success. */ 00365 CELERR_NULL_POINTER = 1, /* Null celprm pointer passed. */ 00366 CELERR_BAD_PARAM = 2, /* Invalid projection parameters. */ 00367 CELERR_BAD_COORD_TRANS = 3, /* Invalid coordinate transformation 00368 parameters. */ 00369 CELERR_ILL_COORD_TRANS = 4, /* Ill-conditioned coordinated transformation 00370 parameters. */ 00371 CELERR_BAD_PIX = 5, /* One or more of the (x,y) coordinates were 00372 invalid. */ 00373 CELERR_BAD_WORLD = 6 /* One or more of the (lng,lat) coordinates 00374 were invalid. */ 00375 }; 00376 00377 struct celprm { 00378 /* Initialization flag (see the prologue above). */ 00379 /*------------------------------------------------------------------------*/ 00380 int flag; /* Set to zero to force initialization. */ 00381 00382 /* Parameters to be provided (see the prologue above). */ 00383 /*------------------------------------------------------------------------*/ 00384 int offset; /* Force (x,y) = (0,0) at (phi_0,theta_0). */ 00385 double phi0, theta0; /* Native coordinates of fiducial point. */ 00386 double ref[4]; /* Celestial coordinates of fiducial */ 00387 /* point and native coordinates of */ 00388 /* celestial pole. */ 00389 00390 struct prjprm prj; /* Projection parameters (see prj.h). */ 00391 00392 /* Information derived from the parameters supplied. */ 00393 /*------------------------------------------------------------------------*/ 00394 double euler[5]; /* Euler angles and functions thereof. */ 00395 int latpreq; /* LATPOLEa requirement. */ 00396 int isolat; /* True if |latitude| is preserved. */ 00397 00398 /* Error handling */ 00399 /*------------------------------------------------------------------------*/ 00400 struct wcserr *err; 00401 00402 /* Private */ 00403 /*------------------------------------------------------------------------*/ 00404 void *padding; /* (Dummy inserted for alignment purposes.) */ 00405 }; 00406 00407 /* Size of the celprm struct in int units, used by the Fortran wrappers. */ 00408 #define CELLEN (sizeof(struct celprm)/sizeof(int)) 00409 00410 00411 int celini(struct celprm *cel); 00412 00413 int celfree(struct celprm *cel); 00414 00415 int celprt(const struct celprm *cel); 00416 00417 int celset(struct celprm *cel); 00418 00419 int celx2s(struct celprm *cel, int nx, int ny, int sxy, int sll, 00420 const double x[], const double y[], 00421 double phi[], double theta[], double lng[], double lat[], 00422 int stat[]); 00423 00424 int cels2x(struct celprm *cel, int nlng, int nlat, int sll, int sxy, 00425 const double lng[], const double lat[], 00426 double phi[], double theta[], double x[], double y[], 00427 int stat[]); 00428 00429 00430 /* Deprecated. */ 00431 #define celini_errmsg cel_errmsg 00432 #define celprt_errmsg cel_errmsg 00433 #define celset_errmsg cel_errmsg 00434 #define celx2s_errmsg cel_errmsg 00435 #define cels2x_errmsg cel_errmsg 00436 00437 #ifdef __cplusplus 00438 } 00439 #endif 00440 00441 #endif /* WCSLIB_CEL */