1 #if !defined( SKYFRAME_INCLUDED ) /* Include this file only once */ 2 #define SKYFRAME_INCLUDED 3 /* 4 *+ 5 * Name: 6 * skyframe.h 7 8 * Type: 9 * C include file. 10 11 * Purpose: 12 * Define the interface to the SkyFrame class. 13 14 * Invocation: 15 * #include "skyframe.h" 16 17 * Description: 18 * This include file defines the interface to the SkyFrame class 19 * and provides the type definitions, function prototypes and 20 * macros, etc. needed to use this class. 21 22 * Inheritance: 23 * The SkyFrame class inherits from the Frame class. 24 25 * Macros: 26 * None. 27 28 * Type Definitions: 29 * Public: 30 * AstSkyFrame 31 * SkyFrame object type. 32 33 * Protected: 34 * AstSkyFrameVtab 35 * SkyFrame virtual function table type. 36 37 * Feature Test Macros: 38 * astCLASS 39 * If the astCLASS macro is undefined, only public symbols are 40 * made available, otherwise protected symbols (for use in other 41 * class implementations) are defined. This macro also affects 42 * the reporting of error context information, which is only 43 * provided for external calls to the AST library. 44 45 * Copyright: 46 * Copyright (C) 1997-2006 Council for the Central Laboratory of the 47 * Research Councils 48 49 * Licence: 50 * This program is free software: you can redistribute it and/or 51 * modify it under the terms of the GNU Lesser General Public 52 * License as published by the Free Software Foundation, either 53 * version 3 of the License, or (at your option) any later 54 * version. 55 * 56 * This program is distributed in the hope that it will be useful, 57 * but WITHOUT ANY WARRANTY; without even the implied warranty of 58 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 59 * GNU Lesser General Public License for more details. 60 * 61 * You should have received a copy of the GNU Lesser General 62 * License along with this program. If not, see 63 * <http://www.gnu.org/licenses/>. 64 65 * Authors: 66 * RFWS: R.F. Warren-Smith (Starlink) 67 * DSB: David S. Berry (Starlink) 68 69 * History: 70 * 4-MAR-1996 (RFWS): 71 * Original version. 72 * 24-MAY-1996 (RFWS): 73 * Tidied up, etc. 74 * 24-SEP-1996 (RFWS): 75 * Added I/O facilities. 76 * 16-JUL-1997 (RFWS): 77 * Added Projection attribute. 78 * 26-FEB-1998 (RFWS): 79 * Over-ride the astUnformat method. 80 * 3-APR-2001 (DSB): 81 * Added "Unknown" option for the System attribute. Added read-only 82 * attributes LatAxis and LonAxis. 83 * 10-OCT-2002 (DSB): 84 * Moved definitions of macros for SkyFrame system values into 85 * this file from skyframe.c. 86 * 15-NOV-2002 (DSB): 87 * Move the System attribute from this class to the parent (Frame) 88 * class. 89 * 8-JAN-2003 (DSB): 90 * Added protected astInitSkyFrameVtab method. 91 * 19-APR-2004 (DSB): 92 * Added SkyRef, SkyRefIs, SkyRefP and AlignOffset attributes. 93 * Simplified prologue. 94 * 2-DEC-2004 (DSB): 95 * Added System "J2000" 96 * 22-FEB-2006 (DSB): 97 * Added Local Apparent Sidereal Time to the SkyFrame structure. 98 * 3-OCT-2006 (DSB): 99 * Added Equation of Equinoxes to the SkyFrame structure. 100 * 6-OCT-2006 (DSB): 101 * Removed Equation of Equinoxes from the SkyFrame structure. 102 * Added dut1 to the SkyFrame structure. 103 * Added Dut1 accessor methods. 104 * 14-OCT-2006 (DSB): 105 * Moved dut1 to the Frame class. 106 *- 107 */ 108 109 /* Include files. */ 110 /* ============== */ 111 /* Interface definitions. */ 112 /* ---------------------- */ 113 #include "object.h" /* Base Object class */ 114 #include "frame.h" /* Parent Frame class */ 115 116 /* Macros. */ 117 /* ======= */ 118 #if defined(astCLASS) || defined(astFORTRAN77) 119 #define STATUS_PTR status 120 #else 121 #define STATUS_PTR astGetStatusPtr 122 #endif 123 124 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ 125 #ifndef __GNUC__ 126 # define __attribute__(x) /*NOTHING*/ 127 #endif 128 129 #if defined(astCLASS) /* Protected */ 130 131 /* Define values for the different values of the SkyRefIs attribute. */ 132 #define AST__BAD_REF 0 133 #define AST__POLE_REF 1 134 #define AST__ORIGIN_REF 2 135 #define AST__IGNORED_REF 3 136 137 /* Values used to represent different System attribute values. */ 138 #define AST__FK4 1 139 #define AST__FK4_NO_E 2 140 #define AST__FK5 3 141 #define AST__GAPPT 4 142 #define AST__ECLIPTIC 5 143 #define AST__GALACTIC 6 144 #define AST__SUPERGALACTIC 7 145 #define AST__ICRS 8 146 #define AST__HELIOECLIPTIC 9 147 #define AST__J2000 10 148 #define AST__UNKNOWN 11 149 #define AST__AZEL 12 150 151 /* Define constants used to size global arrays in this module. */ 152 /* Define other numerical constants for use in this module. */ 153 #define AST__SKYFRAME_GETATTRIB_BUFF_LEN 200 154 #define AST__SKYFRAME_GETFORMAT_BUFF_LEN 50 155 #define AST__SKYFRAME_GETLABEL_BUFF_LEN 40 156 #define AST__SKYFRAME_GETSYMBOL_BUFF_LEN 20 157 #define AST__SKYFRAME_GETTITLE_BUFF_LEN 200 158 159 #endif 160 161 /* Type Definitions. */ 162 /* ================= */ 163 164 /* Cached LAST look-up table. */ 165 /* -------------------------- */ 166 /* Holds a list of epoch values and the corresponding Local Apparent 167 Sidereal Time values. Also holds the observatory position and DUT1 168 value used when calculating the LAST values. */ 169 typedef struct AstSkyLastTable { 170 double obslat; /* ObsLat at which LAST values were calculated */ 171 double obslon; /* ObsLon at which LAST values were calculated */ 172 double obsalt; /* ObsAlt at which LAST values were calculated */ 173 double dut1; /* Dut1 values at which LAST values were calculated */ 174 int nentry; /* Number of entries in the epoch and last arrays */ 175 double *epoch; /* Array of epoch values */ 176 double *last; /* Array of LAST values */ 177 } AstSkyLastTable; 178 179 /* SkyFrame structure. */ 180 /* ------------------- */ 181 /* This structure contains all information that is unique to each object in 182 the class (e.g. its instance variables). */ 183 typedef struct AstSkyFrame { 184 185 /* Attributes inherited from the parent class. */ 186 AstFrame frame; /* Parent class structure */ 187 188 /* Attributes specific to objects in this class. */ 189 char *projection; /* Description of sky projection */ 190 double equinox; /* Modified Julian Date of mean equinox */ 191 int neglon; /* Display negative longitude values? */ 192 int alignoffset; /* Align SkyFrame in offset coords? */ 193 int skyrefis; /* Nature of offset coord system */ 194 double skyref[ 2 ]; /* Origin or pole of offset coord system */ 195 double skyrefp[ 2 ]; /* Point on primary meridian of offset coord system */ 196 double last; /* Local Apparent Sidereal Time */ 197 double eplast; /* Epoch used to calculate "last" */ 198 double klast; /* Ratio of solar to sidereal time */ 199 double diurab; /* Magnitude of diurnal aberration vector */ 200 } AstSkyFrame; 201 202 /* Virtual function table. */ 203 /* ----------------------- */ 204 /* This table contains all information that is the same for all objects in the 205 class (e.g. pointers to its virtual functions). */ 206 #if defined(astCLASS) /* Protected */ 207 typedef struct AstSkyFrameVtab { 208 209 /* Properties (e.g. methods) inherited from the parent class. */ 210 AstFrameVtab frame_vtab; /* Parent class virtual function table */ 211 212 /* A Unique identifier to determine class membership. */ 213 AstClassIdentifier id; 214 215 /* Properties (e.g. methods) specific to this class. */ 216 AstMapping *(* SkyOffsetMap)( AstSkyFrame *, int * ); 217 const char *(* GetProjection)( AstSkyFrame *, int * ); 218 double (* GetEquinox)( AstSkyFrame *, int * ); 219 int (* GetNegLon)( AstSkyFrame *, int * ); 220 int (* GetAsTime)( AstSkyFrame *, int, int * ); 221 int (* GetIsLatAxis)( AstSkyFrame *, int, int * ); 222 int (* GetIsLonAxis)( AstSkyFrame *, int, int * ); 223 int (* GetLatAxis)( AstSkyFrame *, int * ); 224 int (* GetLonAxis)( AstSkyFrame *, int * ); 225 int (* TestAsTime)( AstSkyFrame *, int, int * ); 226 int (* TestEquinox)( AstSkyFrame *, int * ); 227 int (* TestNegLon)( AstSkyFrame *, int * ); 228 int (* TestProjection)( AstSkyFrame *, int * ); 229 void (* ClearAsTime)( AstSkyFrame *, int, int * ); 230 void (* ClearEquinox)( AstSkyFrame *, int * ); 231 void (* ClearNegLon)( AstSkyFrame *, int * ); 232 void (* ClearProjection)( AstSkyFrame *, int * ); 233 void (* SetAsTime)( AstSkyFrame *, int, int, int * ); 234 void (* SetEquinox)( AstSkyFrame *, double, int * ); 235 void (* SetNegLon)( AstSkyFrame *, int, int * ); 236 void (* SetProjection)( AstSkyFrame *, const char *, int * ); 237 238 int (* GetSkyRefIs)( AstSkyFrame *, int * ); 239 int (* TestSkyRefIs)( AstSkyFrame *, int * ); 240 void (* ClearSkyRefIs)( AstSkyFrame *, int * ); 241 void (* SetSkyRefIs)( AstSkyFrame *, int, int * ); 242 243 double (* GetSkyRef)( AstSkyFrame *, int, int * ); 244 int (* TestSkyRef)( AstSkyFrame *, int, int * ); 245 void (* ClearSkyRef)( AstSkyFrame *, int, int * ); 246 void (* SetSkyRef)( AstSkyFrame *, int, double, int * ); 247 248 double (* GetSkyRefP)( AstSkyFrame *, int, int * ); 249 int (* TestSkyRefP)( AstSkyFrame *, int, int * ); 250 void (* ClearSkyRefP)( AstSkyFrame *, int, int * ); 251 void (* SetSkyRefP)( AstSkyFrame *, int, double, int * ); 252 253 int (* GetAlignOffset)( AstSkyFrame *, int * ); 254 int (* TestAlignOffset)( AstSkyFrame *, int * ); 255 void (* ClearAlignOffset)( AstSkyFrame *, int * ); 256 void (* SetAlignOffset)( AstSkyFrame *, int, int * ); 257 258 } AstSkyFrameVtab; 259 260 #if defined(THREAD_SAFE) 261 262 /* The AstSkyFrameGlobals structure makes a forward reference to the 263 AstTimeFrame structure which is not defined here (since the 264 timeframe.h file includes skyframe.h). Hence make a preliminary 265 definition available now. */ 266 struct AstTimeFrame; 267 268 /* Define a structure holding all data items that are global within this 269 class. */ 270 typedef struct AstSkyFrameGlobals { 271 AstSkyFrameVtab Class_Vtab; 272 int Class_Init; 273 char GetAttrib_Buff[ AST__SKYFRAME_GETATTRIB_BUFF_LEN + 1 ]; 274 char GetFormat_Buff[ AST__SKYFRAME_GETFORMAT_BUFF_LEN + 1 ]; 275 char GetLabel_Buff[ AST__SKYFRAME_GETLABEL_BUFF_LEN + 1 ]; 276 char GetSymbol_Buff[ AST__SKYFRAME_GETSYMBOL_BUFF_LEN + 1 ]; 277 char GetTitle_Buff[ AST__SKYFRAME_GETTITLE_BUFF_LEN + 1 ]; 278 char GetTitle_Buff2[ AST__SKYFRAME_GETTITLE_BUFF_LEN + 1 ]; 279 struct AstTimeFrame *TDBFrame; 280 struct AstTimeFrame *LASTFrame; 281 } AstSkyFrameGlobals; 282 283 #endif 284 285 #endif 286 287 /* Function prototypes. */ 288 /* ==================== */ 289 /* Prototypes for standard class functions. */ 290 /* ---------------------------------------- */ 291 astPROTO_CHECK(SkyFrame) /* Check class membership */ 292 astPROTO_ISA(SkyFrame) /* Test class membership */ 293 294 /* Constructor. */ 295 #if defined(astCLASS) /* Protected */ 296 AstSkyFrame *astSkyFrame_( const char *, int *, ...); 297 #else 298 AstSkyFrame *astSkyFrameId_( const char *, ... )__attribute__((format(printf,1,2))); 299 #endif 300 301 #if defined(astCLASS) /* Protected */ 302 303 /* Initialiser. */ 304 AstSkyFrame *astInitSkyFrame_( void *, size_t, int, AstSkyFrameVtab *, 305 const char *, int * ); 306 307 /* Vtab initialiser. */ 308 void astInitSkyFrameVtab_( AstSkyFrameVtab *, const char *, int * ); 309 310 /* Loader. */ 311 AstSkyFrame *astLoadSkyFrame_( void *, size_t, AstSkyFrameVtab *, 312 const char *, AstChannel *channel, int * ); 313 314 /* Thread-safe initialiser for all global data used by this module. */ 315 #if defined(THREAD_SAFE) 316 void astInitSkyFrameGlobals_( AstSkyFrameGlobals * ); 317 #endif 318 #endif 319 320 /* Prototypes for member functions. */ 321 /* -------------------------------- */ 322 AstMapping *astSkyOffsetMap_( AstSkyFrame *, int * ); 323 324 #if defined(astCLASS) /* Protected */ 325 const char *astGetProjection_( AstSkyFrame *, int * ); 326 double astGetEquinox_( AstSkyFrame *, int * ); 327 int astGetNegLon_( AstSkyFrame *, int * ); 328 int astGetAsTime_( AstSkyFrame *, int, int * ); 329 int astGetIsLatAxis_( AstSkyFrame *, int, int * ); 330 int astGetIsLonAxis_( AstSkyFrame *, int, int * ); 331 int astGetLatAxis_( AstSkyFrame *, int * ); 332 int astGetLonAxis_( AstSkyFrame *, int * ); 333 int astTestAsTime_( AstSkyFrame *, int, int * ); 334 int astTestEquinox_( AstSkyFrame *, int * ); 335 int astTestNegLon_( AstSkyFrame *, int * ); 336 int astTestProjection_( AstSkyFrame *, int * ); 337 void astClearAsTime_( AstSkyFrame *, int, int * ); 338 void astClearEquinox_( AstSkyFrame *, int * ); 339 void astClearNegLon_( AstSkyFrame *, int * ); 340 void astClearProjection_( AstSkyFrame *, int * ); 341 void astSetAsTime_( AstSkyFrame *, int, int, int * ); 342 void astSetEquinox_( AstSkyFrame *, double, int * ); 343 void astSetNegLon_( AstSkyFrame *, int, int * ); 344 void astSetProjection_( AstSkyFrame *, const char *, int * ); 345 346 int astGetAlignOffset_( AstSkyFrame *, int * ); 347 int astTestAlignOffset_( AstSkyFrame *, int * ); 348 void astClearAlignOffset_( AstSkyFrame *, int * ); 349 void astSetAlignOffset_( AstSkyFrame *, int, int * ); 350 351 int astGetSkyRefIs_( AstSkyFrame *, int * ); 352 int astTestSkyRefIs_( AstSkyFrame *, int * ); 353 void astClearSkyRefIs_( AstSkyFrame *, int * ); 354 void astSetSkyRefIs_( AstSkyFrame *, int, int * ); 355 356 double astGetSkyRef_( AstSkyFrame *, int, int * ); 357 int astTestSkyRef_( AstSkyFrame *, int, int * ); 358 void astClearSkyRef_( AstSkyFrame *, int, int * ); 359 void astSetSkyRef_( AstSkyFrame *, int, double, int * ); 360 361 double astGetSkyRefP_( AstSkyFrame *, int, int * ); 362 int astTestSkyRefP_( AstSkyFrame *, int, int * ); 363 void astClearSkyRefP_( AstSkyFrame *, int, int * ); 364 void astSetSkyRefP_( AstSkyFrame *, int, double, int * ); 365 366 367 #endif 368 369 /* Function interfaces. */ 370 /* ==================== */ 371 /* These macros are wrap-ups for the functions defined by this class 372 to make them easier to invoke (e.g. to avoid type mis-matches when 373 passing pointers to objects from derived classes). */ 374 375 /* Interfaces to standard class functions. */ 376 /* --------------------------------------- */ 377 /* Some of these functions provide validation, so we cannot use them 378 to validate their own arguments. We must use a cast when passing 379 object pointers (so that they can accept objects from derived 380 classes). */ 381 382 /* Check class membership. */ 383 #define astCheckSkyFrame(this) astINVOKE_CHECK(SkyFrame,this,0) 384 #define astVerifySkyFrame(this) astINVOKE_CHECK(SkyFrame,this,1) 385 386 /* Test class membership. */ 387 #define astIsASkyFrame(this) astINVOKE_ISA(SkyFrame,this) 388 389 /* Constructor. */ 390 #if defined(astCLASS) /* Protected */ 391 #define astSkyFrame astINVOKE(F,astSkyFrame_) 392 #else 393 #define astSkyFrame astINVOKE(F,astSkyFrameId_) 394 #endif 395 396 #if defined(astCLASS) /* Protected */ 397 398 /* Initialiser. */ 399 #define astInitSkyFrame(mem,size,init,vtab,name) \ 400 astINVOKE(O,astInitSkyFrame_(mem,size,init,vtab,name,STATUS_PTR)) 401 402 /* Vtab Initialiser. */ 403 #define astInitSkyFrameVtab(vtab,name) astINVOKE(V,astInitSkyFrameVtab_(vtab,name,STATUS_PTR)) 404 /* Loader. */ 405 #define astLoadSkyFrame(mem,size,vtab,name,channel) \ 406 astINVOKE(O,astLoadSkyFrame_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) 407 408 #endif 409 410 /* Interfaces to public member functions. */ 411 /* -------------------------------------- */ 412 413 #define astSkyOffsetMap(this) \ 414 astINVOKE(O,astSkyOffsetMap_(astCheckSkyFrame(this),STATUS_PTR)) 415 416 /* Interfaces to protected member functions. */ 417 /* ----------------------------------------- */ 418 /* Here we make use of astCheckSkyFrame to validate SkyFrame pointers 419 before use. This provides a contextual error report if a pointer to 420 the wrong sort of object is supplied. */ 421 422 #if defined(astCLASS) /* Protected */ 423 #define astClearAsTime(this,axis) \ 424 astINVOKE(V,astClearAsTime_(astCheckSkyFrame(this),axis,STATUS_PTR)) 425 #define astClearEquinox(this) \ 426 astINVOKE(V,astClearEquinox_(astCheckSkyFrame(this),STATUS_PTR)) 427 #define astClearNegLon(this) \ 428 astINVOKE(V,astClearNegLon_(astCheckSkyFrame(this),STATUS_PTR)) 429 #define astClearProjection(this) \ 430 astINVOKE(V,astClearProjection_(astCheckSkyFrame(this),STATUS_PTR)) 431 #define astGetAsTime(this,axis) \ 432 astINVOKE(V,astGetAsTime_(astCheckSkyFrame(this),axis,STATUS_PTR)) 433 #define astGetEquinox(this) \ 434 astINVOKE(V,astGetEquinox_(astCheckSkyFrame(this),STATUS_PTR)) 435 #define astGetNegLon(this) \ 436 astINVOKE(V,astGetNegLon_(astCheckSkyFrame(this),STATUS_PTR)) 437 #define astGetIsLatAxis(this,axis) \ 438 astINVOKE(V,astGetIsLatAxis_(astCheckSkyFrame(this),axis,STATUS_PTR)) 439 #define astGetIsLonAxis(this,axis) \ 440 astINVOKE(V,astGetIsLonAxis_(astCheckSkyFrame(this),axis,STATUS_PTR)) 441 #define astGetLatAxis(this) \ 442 astINVOKE(V,astGetLatAxis_(astCheckSkyFrame(this),STATUS_PTR)) 443 #define astGetLonAxis(this) \ 444 astINVOKE(V,astGetLonAxis_(astCheckSkyFrame(this),STATUS_PTR)) 445 #define astGetProjection(this) \ 446 astINVOKE(V,astGetProjection_(astCheckSkyFrame(this),STATUS_PTR)) 447 #define astSetAsTime(this,axis,value) \ 448 astINVOKE(V,astSetAsTime_(astCheckSkyFrame(this),axis,value,STATUS_PTR)) 449 #define astSetEquinox(this,value) \ 450 astINVOKE(V,astSetEquinox_(astCheckSkyFrame(this),value,STATUS_PTR)) 451 #define astSetNegLon(this,value) \ 452 astINVOKE(V,astSetNegLon_(astCheckSkyFrame(this),value,STATUS_PTR)) 453 #define astSetProjection(this,value) \ 454 astINVOKE(V,astSetProjection_(astCheckSkyFrame(this),value,STATUS_PTR)) 455 #define astTestAsTime(this,axis) \ 456 astINVOKE(V,astTestAsTime_(astCheckSkyFrame(this),axis,STATUS_PTR)) 457 #define astTestEquinox(this) \ 458 astINVOKE(V,astTestEquinox_(astCheckSkyFrame(this),STATUS_PTR)) 459 #define astTestNegLon(this) \ 460 astINVOKE(V,astTestNegLon_(astCheckSkyFrame(this),STATUS_PTR)) 461 #define astTestProjection(this) \ 462 astINVOKE(V,astTestProjection_(astCheckSkyFrame(this),STATUS_PTR)) 463 464 #define astClearAlignOffset(this) astINVOKE(V,astClearAlignOffset_(astCheckSkyFrame(this),STATUS_PTR)) 465 #define astGetAlignOffset(this) astINVOKE(V,astGetAlignOffset_(astCheckSkyFrame(this),STATUS_PTR)) 466 #define astSetAlignOffset(this,value) astINVOKE(V,astSetAlignOffset_(astCheckSkyFrame(this),value,STATUS_PTR)) 467 #define astTestAlignOffset(this) astINVOKE(V,astTestAlignOffset_(astCheckSkyFrame(this),STATUS_PTR)) 468 469 #define astClearSkyRefIs(this) astINVOKE(V,astClearSkyRefIs_(astCheckSkyFrame(this),STATUS_PTR)) 470 #define astGetSkyRefIs(this) astINVOKE(V,astGetSkyRefIs_(astCheckSkyFrame(this),STATUS_PTR)) 471 #define astSetSkyRefIs(this,value) astINVOKE(V,astSetSkyRefIs_(astCheckSkyFrame(this),value,STATUS_PTR)) 472 #define astTestSkyRefIs(this) astINVOKE(V,astTestSkyRefIs_(astCheckSkyFrame(this),STATUS_PTR)) 473 474 #define astClearSkyRef(this,axis) astINVOKE(V,astClearSkyRef_(astCheckSkyFrame(this),axis,STATUS_PTR)) 475 #define astGetSkyRef(this,axis) astINVOKE(V,astGetSkyRef_(astCheckSkyFrame(this),axis,STATUS_PTR)) 476 #define astSetSkyRef(this,axis,value) astINVOKE(V,astSetSkyRef_(astCheckSkyFrame(this),axis,value,STATUS_PTR)) 477 #define astTestSkyRef(this,axis) astINVOKE(V,astTestSkyRef_(astCheckSkyFrame(this),axis,STATUS_PTR)) 478 479 #define astClearSkyRefP(this,axis) astINVOKE(V,astClearSkyRefP_(astCheckSkyFrame(this),axis,STATUS_PTR)) 480 #define astGetSkyRefP(this,axis) astINVOKE(V,astGetSkyRefP_(astCheckSkyFrame(this),axis,STATUS_PTR)) 481 #define astSetSkyRefP(this,axis,value) astINVOKE(V,astSetSkyRefP_(astCheckSkyFrame(this),axis,value,STATUS_PTR)) 482 #define astTestSkyRefP(this,axis) astINVOKE(V,astTestSkyRefP_(astCheckSkyFrame(this),axis,STATUS_PTR)) 483 484 #endif 485 #endif 486 487 488 489 490 491