1 #if !defined( WCSMAP_INCLUDED ) /* Include this file only once */ 2 #define WCSMAP_INCLUDED 3 /* 4 *+ 5 * Name: 6 * wcsmap.h 7 8 * Type: 9 * C include file. 10 11 * Purpose: 12 * Define the interface to the WcsMap class. 13 14 * Invocation: 15 * #include "wcsmap.h" 16 17 * Description: 18 * This include file defines the interface to the WcsMap class and 19 * provides the type definitions, function prototypes and macros, 20 * etc. needed to use this class. 21 * 22 * The WcsMap class implements Mappings that transform a pair of 23 * longitude/latitude values into a pair of projected Cartesian 24 * coordinates. All the projections included in FITS WCS are included. 25 * For more information about these projections, see the appropriate 26 * FITS document. 27 28 * Inheritance: 29 * The WcsMap class inherits from the Mapping class. 30 31 * Attributes Over-Ridden: 32 * None. 33 34 * New Attributes Defined: 35 * NatLat (double) 36 * This attribute gives the latitude of the reference point of 37 * a FITS WCS projection, in the native coordinate system. The value 38 * returned is in radians. A value of AST__BAD is returned if 39 * no value is defined. This attribute is read only, and may change 40 * if new values are assigned to the projection parameters. 41 * NatLon (double) 42 * This attribute gives the longitude of the reference point of 43 * a FITS WCS projection, in the native coordinate system. The value 44 * returned is in radians. A value of AST__BAD is returned if 45 * no value is defined. This attribute is read only, and may change 46 * if new values are assigned to the projection parameters. 47 * ProjP(i) (double) 48 * This attribute provides aliases for the PV attributes, which 49 * specifies the projection parameter values to be used by a WcsMap 50 * when implementing a FITS-WCS sky projection. ProjP is retained for 51 * compatibility with previous versions of FITS-WCS and AST. New 52 * applications should use the PV attibute instead. 53 * PVj_m (double) 54 * This attribute gives the parameter values used by a FITS WCS 55 * projection. The index j is the axis index in the range 1 to 99, and 56 * the index m is the parameter index in the range 0 to 99. They will 57 * have the value AST__BAD if undefined. By default, no projection 58 * parameters are defined. These should be assigned appropriate values 59 * before using a WcsMap to transform points. 60 * WcsAxis(lonlat) (int) 61 * This attribute gives the indices of the longitude and latitude axes 62 * of a FITS WCS projection within the coordinate system used by a 63 * WcsMap. If "lonlat" is 1 then the index of the longitude axis is 64 * returned. If it is 2 the index of the latitude axis is returned. 65 * The first axis in the coordinate system is axis 1. This is a 66 * read-only attribute. 67 * WcsType (int) 68 * This attribute gives the FITS WCS projection type implemented by a 69 * WcsMap. Macros giving the integer value associated with supported 70 * projections are defined. They have the general form "AST__xxx" where 71 * "xxx" is the 3-character code used to represent the projection in the 72 * FITS CTYPE keyword. 73 74 * Methods Over-Ridden: 75 * Public: 76 * None. 77 * 78 * Protected: 79 * astClearAttrib 80 * Clear an attribute value for a WcsMap. 81 * astGetAttrib 82 * Get an attribute value for a WcsMap. 83 * astSetAttrib 84 * Set an attribute value for a WcsMap. 85 * astTestAttrib 86 * Test if an attribute value has been set for a WcsMap. 87 * astTransform 88 * Apply a WcsMap to transform a set of points. 89 90 * New Methods Defined: 91 * Public: 92 * None. 93 * 94 * Protected: 95 * astClearPV 96 * Clear a PVi_j attribute value for a WcsMap. 97 * astGetNatLat 98 * Get the NatLat attribute value for a WcsMap. 99 * astGetNatLon 100 * Get the NatLon attribute value for a WcsMap. 101 * astGetPV 102 * Get a PVi_j attribute value for a WcsMap. 103 * astGetWcsAxis 104 * Get a WcsAxis attribute value for a WcsMap. 105 * astGetWcsType 106 * Get the WcsType attribute value for a WcsMap. 107 * astIsZenithal 108 * Is the projection zenithal? 109 * astSetPV 110 * Set a PVi_j attribute value for a WcsMap. 111 * astTestPV 112 * Test if a PVi_j attribute value has been set for a WcsMap. 113 * astWcsPrjName 114 * Return the FITS CTYPE keyword value for a given projection type. 115 * astWcsPrjDesc 116 * Return a textual description for a given projection type. 117 * astWcsPrjType 118 * Return the projection type given a FITS CTYPE keyword value. 119 120 * Other Class Functions: 121 * Public: 122 * astIsAWcsMap 123 * Test class membership. 124 * astWcsMap 125 * Create a WcsMap. 126 * 127 * Protected: 128 * astCheckWcsMap 129 * Validate class membership. 130 * astInitWcsMap 131 * Initialise a WcsMap. 132 * astInitWcsMapVtab 133 * Initialise the virtual function table for the WcsMap class. 134 * astLoadWcsMap 135 * Load a WcsMap. 136 137 * Macros: 138 * Public: 139 * AST__WCSMX 140 * Maximum number of parameters associated with a projection. 141 * AST__DPI 142 * 180 degrees in radians. 143 * AST__DPIBY2 144 * 90 degrees in radians. 145 * AST__DD2R 146 * Factor for converting degrees to radians. 147 * AST__DR2D 148 * Factor for converting radians to degrees. 149 * AST__AZP 150 * An integer identifier for the FITS AZP projection. 151 * AST__TAN 152 * An integer identifier for the FITS TAN projection. 153 * AST__SIN 154 * An integer identifier for the FITS SIN projection. 155 * AST__STG 156 * An integer identifier for the FITS STG projection. 157 * AST__ARC 158 * An integer identifier for the FITS ARC projection. 159 * AST__ZPN 160 * An integer identifier for the FITS ZPN projection. 161 * AST__ZEA 162 * An integer identifier for the FITS ZEA projection. 163 * AST__AIR 164 * An integer identifier for the FITS AIR projection. 165 * AST__CYP 166 * An integer identifier for the FITS CYP projection. 167 * AST__CAR 168 * An integer identifier for the FITS CAR projection. 169 * AST__MER 170 * An integer identifier for the FITS MER projection. 171 * AST__CEA 172 * An integer identifier for the FITS CEA projection. 173 * AST__COP 174 * An integer identifier for the FITS COP projection. 175 * AST__COD 176 * An integer identifier for the FITS COD projection. 177 * AST__COE 178 * An integer identifier for the FITS COE projection. 179 * AST__COO 180 * An integer identifier for the FITS COO projection. 181 * AST__BON 182 * An integer identifier for the FITS BON projection. 183 * AST__PCO 184 * An integer identifier for the FITS PCO projection. 185 * AST__GLS 186 * A depracated integer identifier for the FITS SFL projection. 187 * AST__SFL 188 * An integer identifier for the FITS SFL projection. 189 * AST__PAR 190 * An integer identifier for the FITS PAR projection. 191 * AST__AIT 192 * An integer identifier for the FITS AIT projection. 193 * AST__MOL 194 * An integer identifier for the FITS MOL projection. 195 * AST__CSC 196 * An integer identifier for the FITS CSC projection. 197 * AST__QSC 198 * An integer identifier for the FITS QSC projection. 199 * AST__TSC 200 * An integer identifier for the FITS TSC projection 201 * AST__HPX 202 * An integer identifier for the FITS HPX projection. 203 * AST__XPH 204 * An integer identifier for the FITS XPH projection. 205 * AST__TPN 206 * An integer identifier for a "TAN with correction terms" projection. 207 * AST__WCSBAD 208 * An integer identifier for a "null" projection. 209 * 210 * Protected: 211 * None. 212 213 * Type Definitions: 214 * Public: 215 * AstWcsMap 216 * WcsMap object type. 217 * 218 * Protected: 219 * AstWcsMapVtab 220 * WcsMap virtual function table type. 221 222 * Feature Test Macros: 223 * astCLASS 224 * If the astCLASS macro is undefined, only public symbols are 225 * made available, otherwise protected symbols (for use in other 226 * class implementations) are defined. This macro also affects 227 * the reporting of error context information, which is only 228 * provided for external calls to the AST library. 229 230 * Copyright: 231 * Copyright (C) 1997-2006 Council for the Central Laboratory of the 232 * Research Councils 233 234 * Licence: 235 * This program is free software: you can redistribute it and/or 236 * modify it under the terms of the GNU Lesser General Public 237 * License as published by the Free Software Foundation, either 238 * version 3 of the License, or (at your option) any later 239 * version. 240 * 241 * This program is distributed in the hope that it will be useful, 242 * but WITHOUT ANY WARRANTY; without even the implied warranty of 243 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 244 * GNU Lesser General Public License for more details. 245 * 246 * You should have received a copy of the GNU Lesser General 247 * License along with this program. If not, see 248 * <http://www.gnu.org/licenses/>. 249 250 * Authors: 251 * DSB: D.S. Berry (Starlink) 252 253 * History: 254 * 15-Feb-1996 (DSB): 255 * Original version. 256 * 23-MAR-1996 (DSB): 257 * Support for PointSets with more than 2 axes added. 258 * 18-NOV-1996 (DSB): 259 * Updated to include attributes, etc. 260 * 26-SEP-1997 (DSB): 261 * Included new protected function, astPrjDesc. 262 * 11-FEB-2000 (DSB): 263 * Replaced wcsmap component projp by pointers p and np. 264 * 20-OCT-2002 (DSB): 265 * Added astIsZenithal 266 * 8-JAN-2003 (DSB): 267 * Added protected astInitWcsMapVtab method. 268 *- 269 */ 270 271 /* Include files. */ 272 /* ============== */ 273 /* Interface definitions. */ 274 /* ---------------------- */ 275 #include "mapping.h" /* Coordinate mappings (parent class) */ 276 #include "proj.h" /* Mark Calabretta's WCSLIB library header 277 file */ 278 279 #if defined(astCLASS) /* Protected */ 280 #include "pointset.h" /* Sets of points/coordinates */ 281 #include "channel.h" /* I/O channels */ 282 #endif 283 284 /* C header files. */ 285 /* --------------- */ 286 #if defined(astCLASS) /* Protected */ 287 #include <stddef.h> 288 #endif 289 290 /* Macros. */ 291 /* ------- */ 292 /* Max. number of parameters for a WCS projection */ 293 294 #if defined(astCLASS) || defined(astFORTRAN77) 295 #define STATUS_PTR status 296 #else 297 #define STATUS_PTR astGetStatusPtr 298 #endif 299 #define AST__WCSMX 10 300 301 /* pi: 180 degrees in radians - from SLALIB file slamac.h. */ 302 #define AST__DPI 3.1415926535897932384626433832795028841971693993751 303 304 /* pi/2: 90 degrees in radians - from SLALIB file slamac.h. */ 305 #define AST__DPIBY2 1.5707963267948966192313216916397514420985846996876 306 307 /* pi/180: degrees to radians - from SLALIB file slamac.h. */ 308 #define AST__DD2R 0.017453292519943295769236907684886127134428718885417 309 310 /* 180/pi: radians to degrees - from SLALIB file slamac.h. */ 311 #define AST__DR2D 57.295779513082320876798154814105170332405472466564 312 313 /* Projection Types: (note, WCSBAD must be the last in this list) */ 314 315 #define AST__AZP 1 316 #define AST__SZP 2 317 #define AST__TAN 3 318 #define AST__STG 4 319 #define AST__SIN 5 320 #define AST__ARC 6 321 #define AST__ZPN 7 322 #define AST__ZEA 8 323 #define AST__AIR 9 324 #define AST__CYP 10 325 #define AST__CEA 11 326 #define AST__CAR 12 327 #define AST__MER 13 328 #define AST__SFL 14 329 #define AST__PAR 15 330 #define AST__MOL 16 331 #define AST__AIT 17 332 #define AST__COP 18 333 #define AST__COE 19 334 #define AST__COD 20 335 #define AST__COO 21 336 #define AST__BON 22 337 #define AST__PCO 23 338 #define AST__TSC 24 339 #define AST__CSC 25 340 #define AST__QSC 26 341 #define AST__NCP 27 342 #define AST__GLS 28 343 #define AST__TPN 29 344 #define AST__HPX 30 345 #define AST__XPH 31 346 #define AST__WCSBAD 32 /* A bad projection type */ 347 348 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ 349 #ifndef __GNUC__ 350 # define __attribute__(x) /*NOTHING*/ 351 #endif 352 353 /* Type Definitions. */ 354 /* ================= */ 355 /* WcsMap structure. */ 356 /* ------------------ */ 357 /* This structure contains all information that is unique to each object in 358 the class (e.g. its instance variables). */ 359 typedef struct AstWcsMap { 360 361 /* Attributes inherited from the parent class. */ 362 AstMapping mapping; /* Parent class structure */ 363 364 /* Attributes specific to objects in this class. */ 365 int type; /* Projection type */ 366 int wcsaxis[2]; /* Indices of lon and lat. axes */ 367 double **p; /* Pointer to array of projection parameter arrays */ 368 int *np; /* Pointer to array of projection parameter counts */ 369 struct AstPrjPrm params; /* WCS structure holding projection 370 parameters, etc. Defined in proj.h */ 371 int fits_proj; /* Use as FITS-WCS projection? */ 372 int tpn_tan; /* Include TAN projection in TPN transformation? */ 373 } AstWcsMap; 374 375 /* Virtual function table. */ 376 /* ----------------------- */ 377 /* This table contains all information that is the same for all 378 objects in the class (e.g. pointers to its virtual functions). */ 379 #if defined(astCLASS) /* Protected */ 380 typedef struct AstWcsMapVtab { 381 382 /* Properties (e.g. methods) inherited from the parent class. */ 383 AstMappingVtab mapping_vtab; /* Parent class virtual function table */ 384 385 /* A Unique identifier to determine class membership. */ 386 AstClassIdentifier id; 387 388 /* Properties (e.g. methods) specific to this class. */ 389 double (* GetNatLat)( AstWcsMap *, int * ); 390 double (* GetNatLon)( AstWcsMap *, int * ); 391 double (* GetPV)( AstWcsMap *, int, int, int * ); 392 int (* GetWcsAxis)( AstWcsMap *, int, int * ); 393 int (* GetWcsType)( AstWcsMap *, int * ); 394 int (* GetPVMax)( AstWcsMap *, int, int * ); 395 int (* TestPV)( AstWcsMap *, int, int, int * ); 396 void (* ClearPV)( AstWcsMap *, int, int, int * ); 397 void (* SetPV)( AstWcsMap *, int, int, double, int * ); 398 int (* IsZenithal)( AstWcsMap *, int * ); 399 400 int (* GetFITSProj)( AstWcsMap *, int * ); 401 int (* TestFITSProj)( AstWcsMap *, int * ); 402 void (* ClearFITSProj)( AstWcsMap *, int * ); 403 void (* SetFITSProj)( AstWcsMap *, int, int * ); 404 405 int (* GetTPNTan)( AstWcsMap *, int * ); 406 int (* TestTPNTan)( AstWcsMap *, int * ); 407 void (* ClearTPNTan)( AstWcsMap *, int * ); 408 void (* SetTPNTan)( AstWcsMap *, int, int * ); 409 410 } AstWcsMapVtab; 411 412 #if defined(THREAD_SAFE) 413 414 /* Define a structure holding all data items that are global within this 415 class. */ 416 typedef struct AstWcsMapGlobals { 417 AstWcsMapVtab Class_Vtab; 418 int Class_Init; 419 char GetAttrib_Buff[ 101 ]; 420 } AstWcsMapGlobals; 421 422 #endif 423 #endif 424 425 /* Function prototypes. */ 426 /* ==================== */ 427 /* Prototypes for standard class functions. */ 428 /* ---------------------------------------- */ 429 astPROTO_CHECK(WcsMap) /* Check class membership */ 430 astPROTO_ISA(WcsMap) /* Test class membership */ 431 432 /* Constructor. */ 433 #if defined(astCLASS) /* Protected. */ 434 AstWcsMap *astWcsMap_( int, int, int, int, const char *, int *, ...); 435 #else 436 AstWcsMap *astWcsMapId_( int, int, int, int, const char *, ... )__attribute__((format(printf,5,6))); 437 #endif 438 439 #if defined(astCLASS) /* Protected */ 440 441 /* Initialiser. */ 442 AstWcsMap *astInitWcsMap_( void *, size_t, int, AstWcsMapVtab *, 443 const char *, int, int, int, int, int * ); 444 445 /* Vtab initialiser. */ 446 void astInitWcsMapVtab_( AstWcsMapVtab *, const char *, int * ); 447 448 /* Loader. */ 449 AstWcsMap *astLoadWcsMap_( void *, size_t, AstWcsMapVtab *, 450 const char *, AstChannel *, int * ); 451 452 /* Thread-safe initialiser for all global data used by this module. */ 453 #if defined(THREAD_SAFE) 454 void astInitWcsMapGlobals_( AstWcsMapGlobals * ); 455 #endif 456 457 #endif 458 459 /* Prototypes for member functions. */ 460 /* -------------------------------- */ 461 # if defined(astCLASS) /* Protected */ 462 const char *astWcsPrjDesc_( int, int * ); 463 const char *astWcsPrjName_( int, int * ); 464 double astGetNatLat_( AstWcsMap *, int * ); 465 double astGetNatLon_( AstWcsMap *, int * ); 466 double astGetPV_( AstWcsMap *, int, int, int * ); 467 int astWcsPrjType_( const char *, int * ); 468 int astGetWcsAxis_( AstWcsMap *, int, int * ); 469 int astGetWcsType_( AstWcsMap *, int * ); 470 int astGetPVMax_( AstWcsMap *, int, int * ); 471 int astTestPV_( AstWcsMap *, int, int, int * ); 472 int astIsZenithal_( AstWcsMap *, int * ); 473 void astClearPV_( AstWcsMap *, int, int, int * ); 474 void astSetPV_( AstWcsMap *, int, int, double, int * ); 475 476 int astGetFITSProj_( AstWcsMap *, int * ); 477 int astTestFITSProj_( AstWcsMap *, int * ); 478 void astClearFITSProj_( AstWcsMap *, int * ); 479 void astSetFITSProj_( AstWcsMap *, int, int * ); 480 481 int astGetTPNTan_( AstWcsMap *, int * ); 482 int astTestTPNTan_( AstWcsMap *, int * ); 483 void astClearTPNTan_( AstWcsMap *, int * ); 484 void astSetTPNTan_( AstWcsMap *, int, int * ); 485 486 #endif 487 488 /* Function interfaces. */ 489 /* ==================== */ 490 /* These macros are wrap-ups for the functions defined by this class 491 to make them easier to invoke (e.g. to avoid type mis-matches when 492 passing pointers to objects from derived classes). */ 493 494 /* Interfaces to standard class functions. */ 495 /* --------------------------------------- */ 496 /* Some of these functions provide validation, so we cannot use them 497 to validate their own arguments. We must use a cast when passing 498 object pointers (so that they can accept objects from derived 499 classes). */ 500 501 /* Check class membership. */ 502 #define astCheckWcsMap(this) astINVOKE_CHECK(WcsMap,this,0) 503 #define astVerifyWcsMap(this) astINVOKE_CHECK(WcsMap,this,1) 504 505 /* Test class membership. */ 506 #define astIsAWcsMap(this) astINVOKE_ISA(WcsMap,this) 507 508 /* Constructor. */ 509 #if defined(astCLASS) /* Protected. */ 510 #define astWcsMap astINVOKE(F,astWcsMap_) 511 #else 512 #define astWcsMap astINVOKE(F,astWcsMapId_) 513 #endif 514 515 #if defined(astCLASS) /* Protected */ 516 517 /* Initialiser. */ 518 #define astInitWcsMap(mem,size,init,vtab,name,ncoord,type,lon,lat) \ 519 astINVOKE(O,astInitWcsMap_(mem,size,init,vtab,name,ncoord,type,lon,lat,STATUS_PTR)) 520 521 /* Vtab Initialiser. */ 522 #define astInitWcsMapVtab(vtab,name) astINVOKE(V,astInitWcsMapVtab_(vtab,name,STATUS_PTR)) 523 /* Loader. */ 524 #define astLoadWcsMap(mem,size,vtab,name,channel) \ 525 astINVOKE(O,astLoadWcsMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) 526 #endif 527 528 /* Interfaces to public member functions. */ 529 /* -------------------------------------- */ 530 /* Here we make use of astCheckWcsMap to validate WcsMap pointers 531 before use. This provides a contextual error report if a pointer 532 to the wrong sort of Object is supplied. */ 533 534 #if defined(astCLASS) /* Protected */ 535 536 #define astWcsPrjType(ctype) astWcsPrjType_(ctype,STATUS_PTR) 537 #define astWcsPrjName(type) astWcsPrjName_(type,STATUS_PTR) 538 #define astWcsPrjDesc(type) astWcsPrjDesc_(type,STATUS_PTR) 539 540 #define astClearPV(this,i,j) \ 541 astINVOKE(V,astClearPV_(astCheckWcsMap(this),i,j,STATUS_PTR)) 542 #define astGetPV(this,i,j) \ 543 astINVOKE(V,astGetPV_(astCheckWcsMap(this),i,j,STATUS_PTR)) 544 #define astSetPV(this,i,j,par) \ 545 astINVOKE(V,astSetPV_(astCheckWcsMap(this),i,j,par,STATUS_PTR)) 546 #define astTestPV(this,i,j) \ 547 astINVOKE(V,astTestPV_(astCheckWcsMap(this),i,j,STATUS_PTR)) 548 549 #define astClearFITSProj(this) \ 550 astINVOKE(V,astClearFITSProj_(astCheckWcsMap(this),STATUS_PTR)) 551 #define astGetFITSProj(this) \ 552 astINVOKE(V,astGetFITSProj_(astCheckWcsMap(this),STATUS_PTR)) 553 #define astSetFITSProj(this,value) \ 554 astINVOKE(V,astSetFITSProj_(astCheckWcsMap(this),value,STATUS_PTR)) 555 #define astTestFITSProj(this) \ 556 astINVOKE(V,astTestFITSProj_(astCheckWcsMap(this),STATUS_PTR)) 557 558 #define astClearTPNTan(this) \ 559 astINVOKE(V,astClearTPNTan_(astCheckWcsMap(this),STATUS_PTR)) 560 #define astGetTPNTan(this) \ 561 astINVOKE(V,astGetTPNTan_(astCheckWcsMap(this),STATUS_PTR)) 562 #define astSetTPNTan(this,value) \ 563 astINVOKE(V,astSetTPNTan_(astCheckWcsMap(this),value,STATUS_PTR)) 564 #define astTestTPNTan(this) \ 565 astINVOKE(V,astTestTPNTan_(astCheckWcsMap(this),STATUS_PTR)) 566 567 #define astGetWcsType(this) \ 568 astINVOKE(V,astGetWcsType_(astCheckWcsMap(this),STATUS_PTR)) 569 570 #define astGetPVMax(this,i) \ 571 astINVOKE(V,astGetPVMax_(astCheckWcsMap(this),i,STATUS_PTR)) 572 573 #define astGetNatLat(this) \ 574 astINVOKE(V,astGetNatLat_(astCheckWcsMap(this),STATUS_PTR)) 575 576 #define astGetNatLon(this) \ 577 astINVOKE(V,astGetNatLon_(astCheckWcsMap(this),STATUS_PTR)) 578 579 #define astGetWcsAxis(this,index) \ 580 astINVOKE(V,astGetWcsAxis_(astCheckWcsMap(this),index,STATUS_PTR)) 581 582 #define astIsZenithal(this) \ 583 astINVOKE(V,astIsZenithal_(astCheckWcsMap(this),STATUS_PTR)) 584 585 #endif 586 #endif 587 588 589 590 591 592