1 #if !defined( SKYAXIS_INCLUDED ) /* Include this file only once */ 2 #define SKYAXIS_INCLUDED 3 /* 4 *+ 5 * Name: 6 * skyaxis.h 7 8 * Type: 9 * C include file. 10 11 * Purpose: 12 * Define the interface to the SkyAxis class. 13 14 * Invocation: 15 * #include "skyaxis.h" 16 17 * Description: 18 * This include file defines the interface to the SkyAxis class and 19 * provides the type definitions, function prototypes and macros, 20 * etc. needed to use this class. 21 * 22 * The SkyAxis class extends the Axis class to represent angles on 23 * the sky measured in radians. It provides alternative formatting 24 * facilities for representing these coordinate values either as 25 * angles (in degrees) or as time (in hours) using sexagesimal 26 * notation. It also provides alternative defaults for certain 27 * attributes and adds new attributes and methods of its own which 28 * are needed to manipulate angular coordinates on the sky. 29 30 * Inheritance: 31 * The SkyAxis class inherits from the Axis class. 32 33 * Attributes Over-Ridden: 34 * Format (string) 35 * The SkyAxis class defines a new syntax for this string. 36 * Label (string) 37 * The SkyAxis class defines new default values. These may 38 * depend on other attribute settings. 39 * Symbol (string) 40 * The SkyAxis class defines new default values. These may 41 * depend on other attribute settings. 42 * Unit (string) 43 * The SkyAxis class defines new default values. These may 44 * depend on other attribute settings. 45 46 * New Attributes Defined: 47 * AsTime (integer) 48 * A boolean value which indicates whether SkyAxis coordinate 49 * values should be formatted for display as times (instead of 50 * angles). It is used to determine the default format to use if 51 * no explicit value has been set for the Format attribute. 52 * CentreZero (integer) 53 * A boolean value which indicates whether a SkyAxis value should 54 * be normalised into the range [-PI,+PI] or [0,2.PI] when astNorm 55 * is used. 56 * IsLatitude (integer) 57 * A boolean value which indicates whether a SkyAxis is a 58 * latitude axis (as opposed to a longitude axis). It is used to 59 * determine default axis labels and symbols. It also determines the 60 * default value for the "AsTime" attribute (since longitudes on 61 * the sky are usually expressed as times). 62 63 * Methods Over-Ridden: 64 * Public: 65 * astAxisFormat 66 * Format a coordinate value for a SkyAxis. 67 * astAxisNorm 68 * Normalise a SkyAxis coordinate value. 69 * astAxisUnformat 70 * Read a formatted coordinate value for a SkyAxis. 71 72 * Protected: 73 * astAxisAbbrev 74 * Abbreviate a formatted SkyAxis value by skipping leading fields. 75 * astAxisDistance 76 * Find the distance between two SkyAxis values. 77 * astAxisGap 78 * Find a "nice" gap for tabulating SkyAxis values. 79 * astClearAxisFormat 80 * Clear the Format attribute for a SkyAxis. 81 * astGetAxisDirection 82 * Obtain the value of the Direction attribute for a SkyAxis. 83 * astGetAxisFormat 84 * Obtain a pointer to the Format attribute for a SkyAxis. 85 * astGetAxisLabel 86 * Obtain a pointer to the Label attribute for a SkyAxis. 87 * astGetAxisSymbol 88 * Obtain a pointer to the Symbol attribute for a SkyAxis. 89 * astGetAxisUnit 90 * Obtain a pointer to the Unit attribute for a SkyAxis. 91 * astSetAxisFormat 92 * Set a value for the Format attribute of a SkyAxis. 93 * astTestAxisFormat 94 * Test if a value has been set for the Format attribute of a SkyAxis. 95 * astAxisOffset 96 * Add an increment onto a supplied SkyAxis value. 97 * astAxisOverlay 98 * Overlay the attributes of a template SkyAxis on to another Axis. 99 * astSetAttrib 100 * Set an attribute value for a SkyAxis. 101 102 * New Methods Defined: 103 * Public: 104 * None. 105 106 * Protected: 107 * astClearAxisAsTime 108 * Clear the AsTime attribute for a SkyAxis. 109 * astClearAxisCentreZero 110 * Clear the CentreZero attribute for a SkyAxis. 111 * astClearAxisIsLatitude 112 * Clear the IsLatitude attribute for a SkyAxis. 113 * astGetAxisAsTime 114 * Obtain the value of the AsTime attribute for a SkyAxis. 115 * astGetAxisIsLatitude 116 * Obtain the value of the IsLatitude attribute for a SkyAxis. 117 * astGetAxisCentreZero 118 * Obtain the value of the CentreZero attribute for a SkyAxis. 119 * astSetAxisAsTime 120 * Set a value for the AsTime attribute of a SkyAxis. 121 * astSetAxisIsLatitude 122 * Set a value for the IsLatitude attribute of a SkyAxis. 123 * astSetAxisCentreZero 124 * Set a value for the CentreZero attribute of a SkyAxis. 125 * astTestAxisAsTime 126 * Test if a value has been set for the AsTime attribute of a SkyAxis. 127 * astTestAxisIsLatitude 128 * Test if a value has been set for the IsLatitude attribute of a 129 * SkyAxis. 130 * astTestAxisCentreZero 131 * Test if a value has been set for the CentreZero attribute of a 132 * SkyAxis. 133 134 * Other Class Functions: 135 * Public: 136 * astIsASkyAxis 137 * Test class membership. 138 * astSkyAxis 139 * Create an SkyAxis. 140 141 * Protected: 142 * astCheckSkyAxis 143 * Validate class membership. 144 * astInitSkyAxis 145 * Initialise an SkyAxis. 146 147 * Macros: 148 * None. 149 150 * Type Definitions: 151 * Public: 152 * AstSkyAxis 153 * SkyAxis object type. 154 155 * Protected: 156 * AstSkyAxisVtab 157 * SkyAxis virtual function table type. 158 159 * Feature Test Macros: 160 * astCLASS 161 * If the astCLASS macro is undefined, only public symbols are 162 * made available, otherwise protected symbols (for use in other 163 * class implementations) are defined. This macro also affects 164 * the reporting of error context information, which is only 165 * provided for external calls to the AST library. 166 167 * Copyright: 168 * Copyright (C) 1997-2006 Council for the Central Laboratory of the 169 * Research Councils 170 171 * Licence: 172 * This program is free software: you can redistribute it and/or 173 * modify it under the terms of the GNU Lesser General Public 174 * License as published by the Free Software Foundation, either 175 * version 3 of the License, or (at your option) any later 176 * version. 177 * 178 * This program is distributed in the hope that it will be useful, 179 * but WITHOUT ANY WARRANTY; without even the implied warranty of 180 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 181 * GNU Lesser General Public License for more details. 182 * 183 * You should have received a copy of the GNU Lesser General 184 * License along with this program. If not, see 185 * <http://www.gnu.org/licenses/>. 186 187 * Authors: 188 * RFWS: R.F. Warren-Smith (Starlink) 189 190 * History: 191 * 29-MAR-1996 (RFWS): 192 * Original version. 193 * 25-APR-1996 (RFWS): 194 * Made all attribute access functions protected. 195 * 13-MAY-1996 (RFWS): 196 * Documented over-riding of the astGetAxisDirection method. 197 * 26-FEB-1998 (RFWS): 198 * Over-ride the astAxisUnformat method. 199 * 8-JAN-2003 (DSB): 200 * Added protected astInitSkyAxisVtab method. 201 *- 202 */ 203 204 /* Include files. */ 205 /* ============== */ 206 /* Interface definitions. */ 207 /* ---------------------- */ 208 #include "axis.h" /* Coordinate axes (parent class) */ 209 210 /* Macros */ 211 /* ====== */ 212 213 /* Define constants used to size global arrays in this module. */ 214 /* Define numerical constants for use in thie module. */ 215 #define AST__SKYAXIS_GETAXISFORMAT_BUFF_LEN 50 216 #define AST__SKYAXIS_DHMSFORMAT_BUFF_LEN 70 217 #define AST__SKYAXIS_DHMSUNIT_BUFF_LEN 17 218 #define AST__SKYAXIS_GETATTRIB_BUFF_LEN 50 219 220 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ 221 #ifndef __GNUC__ 222 # define __attribute__(x) /*NOTHING*/ 223 #endif 224 225 226 /* Type Definitions. */ 227 /* ================= */ 228 /* SkyAxis structure. */ 229 /* ------------------ */ 230 /* This structure contains all information that is unique to each 231 object in the class (e.g. its instance variables). */ 232 typedef struct AstSkyAxis { 233 234 /* Attributes inherited from the parent class. */ 235 AstAxis axis; /* Parent class structure */ 236 237 /* Attributes specific to objects in this class. */ 238 char *skyformat; /* Pointer to sky format string */ 239 int as_time; /* Format angles as time (hours)? */ 240 int is_latitude; /* SkyAxis is a latitude axis? */ 241 int centrezero; /* Normalised range is zero-centred? */ 242 } AstSkyAxis; 243 244 /* Virtual function table. */ 245 /* ----------------------- */ 246 /* This table contains all information that is the same for all 247 objects in the class (e.g. pointers to its virtual functions). */ 248 #if defined(astCLASS) /* Protected */ 249 typedef struct AstSkyAxisVtab { 250 251 /* Properties (e.g. methods) inherited from the parent class. */ 252 AstAxisVtab axis_vtab; /* Parent class virtual function table */ 253 254 /* A Unique identifier to determine class membership. */ 255 AstClassIdentifier id; 256 257 /* Properties (e.g. methods) specific to this class. */ 258 int (* GetAxisAsTime)( AstSkyAxis *, int * ); 259 int (* GetAxisIsLatitude)( AstSkyAxis *, int * ); 260 int (* GetAxisCentreZero)( AstSkyAxis *, int * ); 261 int (* TestAxisAsTime)( AstSkyAxis *, int * ); 262 int (* TestAxisIsLatitude)( AstSkyAxis *, int * ); 263 int (* TestAxisCentreZero)( AstSkyAxis *, int * ); 264 void (* ClearAxisAsTime)( AstSkyAxis *, int * ); 265 void (* ClearAxisIsLatitude)( AstSkyAxis *, int * ); 266 void (* ClearAxisCentreZero)( AstSkyAxis *, int * ); 267 void (* SetAxisAsTime)( AstSkyAxis *, int, int * ); 268 void (* SetAxisIsLatitude)( AstSkyAxis *, int, int * ); 269 void (* SetAxisCentreZero)( AstSkyAxis *, int, int * ); 270 } AstSkyAxisVtab; 271 272 #if defined(THREAD_SAFE) 273 274 /* Define a structure holding all data items that are global within this 275 class. */ 276 typedef struct AstSkyAxisGlobals { 277 AstSkyAxisVtab Class_Vtab; 278 int Class_Init; 279 char DHmsFormat_Buff[ AST__SKYAXIS_DHMSFORMAT_BUFF_LEN + 1 ]; 280 char DHmsUnit_Buff[ AST__SKYAXIS_DHMSUNIT_BUFF_LEN + 1 ]; 281 char GetAttrib_Buff[ AST__SKYAXIS_GETATTRIB_BUFF_LEN + 1 ]; 282 char GetAxisFormat_Buff[ AST__SKYAXIS_GETAXISFORMAT_BUFF_LEN + 1 ]; 283 char *GhDelim; 284 char *GmDelim; 285 char *GsDelim; 286 char *GdDelim; 287 char *GamDelim; 288 char *GasDelim; 289 } AstSkyAxisGlobals; 290 291 #endif 292 293 294 #endif 295 296 /* Function prototypes. */ 297 /* ==================== */ 298 /* Prototypes for standard class functions. */ 299 /* ---------------------------------------- */ 300 astPROTO_CHECK(SkyAxis) /* Check class membership */ 301 astPROTO_ISA(SkyAxis) /* Test class membership */ 302 303 /* Constructor. */ 304 #if defined(astCLASS) /* Protected. */ 305 AstSkyAxis *astSkyAxis_( const char *, int *, ...); 306 #else 307 AstSkyAxis *astSkyAxisId_( const char *, ... )__attribute__((format(printf,1,2))); 308 #endif 309 310 #if defined(astCLASS) /* Protected */ 311 312 /* Initialiser. */ 313 AstSkyAxis *astInitSkyAxis_( void *, size_t, int, AstSkyAxisVtab *, 314 const char *, int * ); 315 316 /* Vtab initialiser. */ 317 void astInitSkyAxisVtab_( AstSkyAxisVtab *, const char *, int * ); 318 319 /* Loader. */ 320 AstSkyAxis *astLoadSkyAxis_( void *, size_t, AstSkyAxisVtab *, 321 const char *, AstChannel *, int * ); 322 323 /* Thread-safe initialiser for all global data used by this module. */ 324 #if defined(THREAD_SAFE) 325 void astInitSkyAxisGlobals_( AstSkyAxisGlobals * ); 326 #endif 327 328 #endif 329 330 /* Prototypes for member functions. */ 331 /* -------------------------------- */ 332 #if defined(astCLASS) /* Protected */ 333 int astGetAxisAsTime_( AstSkyAxis *, int * ); 334 int astGetAxisIsLatitude_( AstSkyAxis *, int * ); 335 int astGetAxisCentreZero_( AstSkyAxis *, int * ); 336 int astTestAxisAsTime_( AstSkyAxis *, int * ); 337 int astTestAxisIsLatitude_( AstSkyAxis *, int * ); 338 int astTestAxisCentreZero_( AstSkyAxis *, int * ); 339 void astClearAxisAsTime_( AstSkyAxis *, int * ); 340 void astClearAxisIsLatitude_( AstSkyAxis *, int * ); 341 void astClearAxisCentreZero_( AstSkyAxis *, int * ); 342 void astSetAxisAsTime_( AstSkyAxis *, int, int * ); 343 void astSetAxisIsLatitude_( AstSkyAxis *, int, int * ); 344 void astSetAxisCentreZero_( AstSkyAxis *, int, int * ); 345 346 #endif 347 348 /* Function interfaces. */ 349 /* ==================== */ 350 /* These macros are wrap-ups for the functions defined by this class 351 to make them easier to invoke (e.g. to avoid type mis-matches when 352 passing pointers to objects from derived classes). */ 353 354 /* Interfaces to standard class functions. */ 355 /* --------------------------------------- */ 356 /* Some of these functions provide validation, so we cannot use them 357 to validate their own arguments. We must use a cast when passing 358 object pointers (so that they can accept objects from derived 359 classes). */ 360 361 /* Check class membership. */ 362 #define astCheckSkyAxis(this) astINVOKE_CHECK(SkyAxis,this,0) 363 #define astVerifySkyAxis(this) astINVOKE_CHECK(SkyAxis,this,1) 364 365 /* Test class membership. */ 366 #define astIsASkyAxis(this) astINVOKE_ISA(SkyAxis,this) 367 368 /* Constructor. */ 369 #if defined(astCLASS) /* Protected. */ 370 #define astSkyAxis astINVOKE(F,astSkyAxis_) 371 #else 372 #define astSkyAxis astINVOKE(F,astSkyAxisId_) 373 #endif 374 375 #if defined(astCLASS) /* Protected */ 376 377 /* Initialiser. */ 378 #define astInitSkyAxis(mem,size,init,vtab,name) \ 379 astINVOKE(O,astInitSkyAxis_(mem,size,init,vtab,name,STATUS_PTR)) 380 381 /* Vtab Initialiser. */ 382 #define astInitSkyAxisVtab(vtab,name) astINVOKE(V,astInitSkyAxisVtab_(vtab,name,STATUS_PTR)) 383 /* Loader. */ 384 #define astLoadSkyAxis(mem,size,vtab,name,channel) \ 385 astINVOKE(O,astLoadSkyAxis_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) 386 #endif 387 388 /* Interfaces to public member functions. */ 389 /* -------------------------------------- */ 390 391 /* Here we make use of astCheckSkyAxis to validate SkyAxis pointers 392 before use. This provides a contextual error report if a pointer to 393 the wrong sort of object is supplied. */ 394 #if defined(astCLASS) /* Protected */ 395 396 #define astClearAxisAsTime(this) \ 397 astINVOKE(V,astClearAxisAsTime_(astCheckSkyAxis(this),STATUS_PTR)) 398 #define astClearAxisIsLatitude(this) \ 399 astINVOKE(V,astClearAxisIsLatitude_(astCheckSkyAxis(this),STATUS_PTR)) 400 #define astGetAxisAsTime(this) \ 401 astINVOKE(V,astGetAxisAsTime_(astCheckSkyAxis(this),STATUS_PTR)) 402 #define astGetAxisIsLatitude(this) \ 403 astINVOKE(V,astGetAxisIsLatitude_(astCheckSkyAxis(this),STATUS_PTR)) 404 #define astSetAxisAsTime(this,value) \ 405 astINVOKE(V,astSetAxisAsTime_(astCheckSkyAxis(this),value,STATUS_PTR)) 406 #define astSetAxisIsLatitude(this,value) \ 407 astINVOKE(V,astSetAxisIsLatitude_(astCheckSkyAxis(this),value,STATUS_PTR)) 408 #define astTestAxisAsTime(this) \ 409 astINVOKE(V,astTestAxisAsTime_(astCheckSkyAxis(this),STATUS_PTR)) 410 #define astTestAxisIsLatitude(this) \ 411 astINVOKE(V,astTestAxisIsLatitude_(astCheckSkyAxis(this),STATUS_PTR)) 412 413 #define astClearAxisCentreZero(this) \ 414 astINVOKE(V,astClearAxisCentreZero_(astCheckSkyAxis(this),STATUS_PTR)) 415 #define astGetAxisCentreZero(this) \ 416 astINVOKE(V,astGetAxisCentreZero_(astCheckSkyAxis(this),STATUS_PTR)) 417 #define astSetAxisCentreZero(this,value) \ 418 astINVOKE(V,astSetAxisCentreZero_(astCheckSkyAxis(this),value,STATUS_PTR)) 419 #define astTestAxisCentreZero(this) \ 420 astINVOKE(V,astTestAxisCentreZero_(astCheckSkyAxis(this),STATUS_PTR)) 421 422 #endif 423 #endif 424 425 426 427 428 429