1 #if !defined( SPHMAP_INCLUDED ) /* Include this file only once */ 2 #define SPHMAP_INCLUDED 3 /* 4 *+ 5 * Name: 6 * sphmap.h 7 8 * Type: 9 * C include file. 10 11 * Purpose: 12 * Define the interface to the SphMap class. 13 14 * Invocation: 15 * #include "sphmap.h" 16 17 * Description: 18 * This include file defines the interface to the SphMap class and 19 * provides the type definitions, function prototypes and macros, 20 * etc. needed to use this class. 21 * 22 * The SphMap class implements Mappings which maps positions from 23 * 3-dimensional Cartesian coordinates into 2-dimensional spherical 24 * coordinates (i.e. longitude and latitude on a unit sphere). The 25 * inverse Mapping always produces vectors of unit length. 26 * 27 * The spherical coordinates are longitude (positive anti-clockwise 28 * looking from the positive latitude pole) and latitude. The 29 * Cartesian coordinates are right-handed, with the x-axis (axis 1) 30 * at zero longitude and latitude, and the z-axis (axis 3) at the 31 * positive latitude pole. 32 * 33 * At either pole, the longitude is set to the value of the PolarLong 34 * attribute. If the Cartesian coordinates are all zero, then the 35 * longitude and latitude values are set to AST__BAD. 36 37 * Inheritance: 38 * The SphMap class inherits from the Mapping class. 39 40 * Attributes Over-Ridden: 41 * None. 42 43 * New Attributes Defined: 44 * PolarLong (double) 45 * This attribute holds the longitude value, in radians, to be 46 * returned when a Cartesian position corresponding to either the north 47 * or south pole is transformed into spherical coordinates. The 48 * default value is zero. 49 * UnitRadius (integer) 50 * This is a boolean attribute which indicates whether the 51 * 3-dimensional vectors which are supplied as input to a SphMap 52 * are known to always have unit length, so that they lie on a 53 * unit sphere centred on the origin. 54 * 55 * If this condition is true (indicated by setting UnitRadius 56 * non-zero), it implies that a CmpMap which is composed of a 57 * SphMap applied in the forward direction followed by a similar 58 * SphMap applied in the inverse direction may be simplified 59 * (e.g. by astSimplify) to become a UnitMap. This is because 60 * the input and output vectors will both have unit length and 61 * will therefore have the same coordinate values. 62 * 63 * If UnitRadius is zero (the default), then although the output 64 * vector produced by the CmpMap (above) will still have unit 65 * length, the input vector may not have. This will, in general, 66 * change the coordinate values, so it prevents the pair of 67 * SphMaps being simplified. 68 69 * Methods Over-Ridden: 70 * Public: 71 * None. 72 * 73 * Protected: 74 * astClearAttrib 75 * Clear an attribute value for a SphMap. 76 * astGetAttrib 77 * Get an attribute value for a SphMap. 78 * astMapMerge 79 * Simplify a sequence of Mappings containing a SphMap. 80 * astSetAttrib 81 * Set an attribute value for a SphMap. 82 * astTestAttrib 83 * Test if an attribute value has been set for a SphMap. 84 * astTransform 85 * Apply a SphMap to transform a set of points. 86 87 * New Methods Defined: 88 * Public: 89 * None. 90 * 91 * Protected: 92 * astClearUnitRadius 93 * Clear the UnitRadius attribute value for a SphMap. 94 * astGetUnitRadius 95 * Get the UnitRadius attribute value for a SphMap. 96 * astSetUnitRadius 97 * Set the UnitRadius attribute value for a SphMap. 98 * astTestUnitRadius 99 * Test if a UnitRadius attribute value has been set for a SphMap. 100 * astClearPolarLong 101 * Clear the PolarLong attribute value for a SphMap. 102 * astGetPolarLong 103 * Get the PolarLong attribute value for a SphMap. 104 * astSetPolarLong 105 * Set the PolarLong attribute value for a SphMap. 106 * astTestPolarLong 107 * Test if a PolarLong attribute value has been set for a SphMap. 108 109 * Other Class Functions: 110 * Public: 111 * astIsASphMap 112 * Test class membership. 113 * astSphMap 114 * Create a SphMap. 115 * 116 * Protected: 117 * astCheckSphMap 118 * Validate class membership. 119 * astInitSphMap 120 * Initialise a SphMap. 121 * astInitSphMapVtab 122 * Initialise the virtual function table for the SphMap class. 123 * astLoadSphMap 124 * Load a SphMap. 125 126 * Macros: 127 * None. 128 129 * Type Definitions: 130 * Public: 131 * AstSphMap 132 * SphMap object type. 133 * 134 * Protected: 135 * AstSphMapVtab 136 * SphMap virtual function table type. 137 138 * Feature Test Macros: 139 * astCLASS 140 * If the astCLASS macro is undefined, only public symbols are 141 * made available, otherwise protected symbols (for use in other 142 * class implementations) are defined. This macro also affects 143 * the reporting of error context information, which is only 144 * provided for external calls to the AST library. 145 146 * Copyright: 147 * Copyright (C) 1997-2006 Council for the Central Laboratory of the 148 * Research Councils 149 150 * Licence: 151 * This program is free software: you can redistribute it and/or 152 * modify it under the terms of the GNU Lesser General Public 153 * License as published by the Free Software Foundation, either 154 * version 3 of the License, or (at your option) any later 155 * version. 156 * 157 * This program is distributed in the hope that it will be useful, 158 * but WITHOUT ANY WARRANTY; without even the implied warranty of 159 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 160 * GNU Lesser General Public License for more details. 161 * 162 * You should have received a copy of the GNU Lesser General 163 * License along with this program. If not, see 164 * <http://www.gnu.org/licenses/>. 165 166 * Authors: 167 * DSB: D.S. Berry (Starlink) 168 169 * History: 170 * 25-OCT-1996 (DSB): 171 * Original version. 172 * 24-MAR-1998 (RFWS): 173 * Override the astMapMerge method. 174 * 4-SEP-1998 (DSB): 175 * Added UnitRadius attribute. 176 * 8-JAN-2003 (DSB): 177 * Added protected astInitSphMapVtab method. 178 * 11-JUN-2003 (DSB): 179 * Added PolarLong attribute. 180 *- 181 */ 182 183 /* Include files. */ 184 /* ============== */ 185 /* Interface definitions. */ 186 /* ---------------------- */ 187 #include "mapping.h" /* Coordinate mappings (parent class) */ 188 189 #if defined(astCLASS) /* Protected */ 190 #include "pointset.h" /* Sets of points/coordinates */ 191 #include "channel.h" /* I/O channels */ 192 #endif 193 194 /* C header files. */ 195 /* --------------- */ 196 #if defined(astCLASS) /* Protected */ 197 #include <stddef.h> 198 #endif 199 200 /* Macros */ 201 /* ====== */ 202 203 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ 204 #ifndef __GNUC__ 205 # define __attribute__(x) /*NOTHING*/ 206 #endif 207 208 /* Type Definitions. */ 209 /* ================= */ 210 /* SphMap structure. */ 211 /* ------------------ */ 212 /* This structure contains all information that is unique to each object in 213 the class (e.g. its instance variables). */ 214 typedef struct AstSphMap { 215 216 /* Attributes inherited from the parent class. */ 217 AstMapping mapping; /* Parent class structure */ 218 219 /* Attributes specific to objects in this class. */ 220 double polarlong; /* Longitude to assign to either pole */ 221 int unitradius; /* Are input vectors always of unit length? */ 222 } AstSphMap; 223 224 /* Virtual function table. */ 225 /* ----------------------- */ 226 /* This table contains all information that is the same for all 227 objects in the class (e.g. pointers to its virtual functions). */ 228 #if defined(astCLASS) /* Protected */ 229 typedef struct AstSphMapVtab { 230 231 /* Properties (e.g. methods) inherited from the parent class. */ 232 AstMappingVtab mapping_vtab; /* Parent class virtual function table */ 233 234 /* A Unique identifier to determine class membership. */ 235 AstClassIdentifier id; 236 237 /* Properties (e.g. methods) specific to this class. */ 238 int (* GetUnitRadius)( AstSphMap *, int * ); 239 int (* TestUnitRadius)( AstSphMap *, int * ); 240 void (* ClearUnitRadius)( AstSphMap *, int * ); 241 void (* SetUnitRadius)( AstSphMap *, int, int * ); 242 243 double (* GetPolarLong)( AstSphMap *, int * ); 244 int (* TestPolarLong)( AstSphMap *, int * ); 245 void (* ClearPolarLong)( AstSphMap *, int * ); 246 void (* SetPolarLong)( AstSphMap *, double, int * ); 247 } AstSphMapVtab; 248 249 #if defined(THREAD_SAFE) 250 251 /* Define a structure holding all data items that are global within this 252 class. */ 253 typedef struct AstSphMapGlobals { 254 AstSphMapVtab Class_Vtab; 255 int Class_Init; 256 char GetAttrib_Buff[ 51 ]; 257 } AstSphMapGlobals; 258 #endif 259 260 #endif 261 262 /* Function prototypes. */ 263 /* ==================== */ 264 /* Prototypes for standard class functions. */ 265 /* ---------------------------------------- */ 266 astPROTO_CHECK(SphMap) /* Check class membership */ 267 astPROTO_ISA(SphMap) /* Test class membership */ 268 269 /* Constructor. */ 270 #if defined(astCLASS) /* Protected. */ 271 AstSphMap *astSphMap_( const char *, int *, ...); 272 #else 273 AstSphMap *astSphMapId_( const char *, ...)__attribute__((format(printf,1,2))); 274 #endif 275 276 #if defined(astCLASS) /* Protected */ 277 278 /* Initialiser. */ 279 AstSphMap *astInitSphMap_( void *, size_t, int, AstSphMapVtab *, 280 const char *, int * ); 281 282 /* Vtab initialiser. */ 283 void astInitSphMapVtab_( AstSphMapVtab *, const char *, int * ); 284 285 /* Loader. */ 286 AstSphMap *astLoadSphMap_( void *, size_t, AstSphMapVtab *, 287 const char *, AstChannel *, int * ); 288 289 /* Thread-safe initialiser for all global data used by this module. */ 290 #if defined(THREAD_SAFE) 291 void astInitSphMapGlobals_( AstSphMapGlobals * ); 292 #endif 293 294 #endif 295 296 /* Prototypes for member functions. */ 297 /* -------------------------------- */ 298 # if defined(astCLASS) /* Protected */ 299 int astGetUnitRadius_( AstSphMap *, int * ); 300 int astTestUnitRadius_( AstSphMap *, int * ); 301 void astClearUnitRadius_( AstSphMap *, int * ); 302 void astSetUnitRadius_( AstSphMap *, int, int * ); 303 304 double astGetPolarLong_( AstSphMap *, int * ); 305 int astTestPolarLong_( AstSphMap *, int * ); 306 void astClearPolarLong_( AstSphMap *, int * ); 307 void astSetPolarLong_( AstSphMap *, double, int * ); 308 #endif 309 310 /* Function interfaces. */ 311 /* ==================== */ 312 /* These macros are wrap-ups for the functions defined by this class 313 to make them easier to invoke (e.g. to avoid type mis-matches when 314 passing pointers to objects from derived classes). */ 315 316 /* Interfaces to standard class functions. */ 317 /* --------------------------------------- */ 318 /* Some of these functions provide validation, so we cannot use them 319 to validate their own arguments. We must use a cast when passing 320 object pointers (so that they can accept objects from derived 321 classes). */ 322 323 /* Check class membership. */ 324 #define astCheckSphMap(this) astINVOKE_CHECK(SphMap,this,0) 325 #define astVerifySphMap(this) astINVOKE_CHECK(SphMap,this,1) 326 327 /* Test class membership. */ 328 #define astIsASphMap(this) astINVOKE_ISA(SphMap,this) 329 330 /* Constructor. */ 331 #if defined(astCLASS) /* Protected. */ 332 #define astSphMap astINVOKE(F,astSphMap_) 333 #else 334 #define astSphMap astINVOKE(F,astSphMapId_) 335 #endif 336 337 #if defined(astCLASS) /* Protected */ 338 339 /* Initialiser. */ 340 #define \ 341 astInitSphMap(mem,size,init,vtab,name) \ 342 astINVOKE(O,astInitSphMap_(mem,size,init,vtab,name,STATUS_PTR)) 343 344 /* Vtab Initialiser. */ 345 #define astInitSphMapVtab(vtab,name) astINVOKE(V,astInitSphMapVtab_(vtab,name,STATUS_PTR)) 346 /* Loader. */ 347 #define astLoadSphMap(mem,size,vtab,name,channel) \ 348 astINVOKE(O,astLoadSphMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) 349 #endif 350 351 /* Interfaces to public member functions. */ 352 /* -------------------------------------- */ 353 /* Here we make use of astCheckSphMap to validate SphMap pointers 354 before use. This provides a contextual error report if a pointer 355 to the wrong sort of Object is supplied. */ 356 357 #if defined(astCLASS) /* Protected */ 358 #define astClearUnitRadius(this) astINVOKE(V,astClearUnitRadius_(astCheckSphMap(this),STATUS_PTR)) 359 #define astGetUnitRadius(this) astINVOKE(V,astGetUnitRadius_(astCheckSphMap(this),STATUS_PTR)) 360 #define astSetUnitRadius(this,value) astINVOKE(V,astSetUnitRadius_(astCheckSphMap(this),value,STATUS_PTR)) 361 #define astTestUnitRadius(this) astINVOKE(V,astTestUnitRadius_(astCheckSphMap(this),STATUS_PTR)) 362 363 #define astClearPolarLong(this) astINVOKE(V,astClearPolarLong_(astCheckSphMap(this),STATUS_PTR)) 364 #define astGetPolarLong(this) astINVOKE(V,astGetPolarLong_(astCheckSphMap(this),STATUS_PTR)) 365 #define astSetPolarLong(this,value) astINVOKE(V,astSetPolarLong_(astCheckSphMap(this),value,STATUS_PTR)) 366 #define astTestPolarLong(this) astINVOKE(V,astTestPolarLong_(astCheckSphMap(this),STATUS_PTR)) 367 #endif 368 369 #endif 370 371 372 373 374 375