WCSLIB: cel.h Source File

WCSLIB 4.25.1

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

cel.h
Go to the documentation of this file.
1 /*============================================================================
2
3 WCSLIB 4.25 - an implementation of the FITS WCS standard.
4 Copyright (C) 1995-2015, Mark Calabretta
5
6 This file is part of WCSLIB.
7
8 WCSLIB is free software: you can redistribute it and/or modify it under the
9 terms of the GNU Lesser General Public License as published by the Free
10 Software Foundation, either version 3 of the License, or (at your option)
11 any later version.
12
13 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
14 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16 more details.
17
18 You should have received a copy of the GNU Lesser General Public License
19 along with WCSLIB. If not, see http://www.gnu.org/licenses.
20
21 Direct correspondence concerning WCSLIB to mark@calabretta.id.au
22
23 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
24 http://www.atnf.csiro.au/people/Mark.Calabretta
25 $Id: cel.h,v 4.25.1.2 2015/01/06 01:01:06 mcalabre Exp mcalabre $
26 *=============================================================================
27 *
28 * WCSLIB 4.25 - C routines that implement the FITS World Coordinate System
29 * (WCS) standard. Refer to
30 *
31 * "Representations of world coordinates in FITS",
32 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
33 *
34 * "Representations of celestial coordinates in FITS",
35 * Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II)
36 *
37 * Refer to the README file provided with WCSLIB for an overview of the
38 * library.
39 *
40 *
41 * Summary of the cel routines
42 * ---------------------------
43 * These routines implement the part of the FITS World Coordinate System (WCS)
44 * standard that deals with celestial coordinates. They define methods to be
45 * used for computing celestial world coordinates from intermediate world
46 * coordinates (a linear transformation of image pixel coordinates), and vice
47 * versa. They are based on the celprm struct which contains all information
48 * needed for the computations. This struct contains some elements that must
49 * be set by the user, and others that are maintained by these routines,
50 * somewhat like a C++ class but with no encapsulation.
51 *
52 * Routine celini() is provided to initialize the celprm struct with default
53 * values, celfree() reclaims any memory that may have been allocated to store
54 * an error message, and celprt() prints its contents.
55 *
56 * A setup routine, celset(), computes intermediate values in the celprm struct
57 * from parameters in it that were supplied by the user. The struct always
58 * needs to be set up by celset() but it need not be called explicitly - refer
59 * to the explanation of celprm::flag.
60 *
61 * celx2s() and cels2x() implement the WCS celestial coordinate
62 * transformations. In fact, they are high level driver routines for the lower
63 * level spherical coordinate rotation and projection routines described in
64 * sph.h and prj.h.
65 *
66 *
67 * celini() - Default constructor for the celprm struct
68 * ----------------------------------------------------
69 * celini() sets all members of a celprm struct to default values. It should
70 * be used to initialize every celprm struct.
71 *
72 * Returned:
73 * cel struct celprm*
74 * Celestial transformation parameters.
75 *
76 * Function return value:
77 * int Status return value:
78 * 0: Success.
79 * 1: Null celprm pointer passed.
80 *
81 *
82 * celfree() - Destructor for the celprm struct
83 * --------------------------------------------
84 * celfree() frees any memory that may have been allocated to store an error
85 * message in the celprm struct.
86 *
87 * Given:
88 * cel struct celprm*
89 * Celestial transformation parameters.
90 *
91 * Function return value:
92 * int Status return value:
93 * 0: Success.
94 * 1: Null celprm pointer passed.
95 *
96 *
97 * celprt() - Print routine for the celprm struct
98 * ----------------------------------------------
99 * celprt() prints the contents of a celprm struct using wcsprintf(). Mainly
100 * intended for diagnostic purposes.
101 *
102 * Given:
103 * cel const struct celprm*
104 * Celestial transformation parameters.
105 *
106 * Function return value:
107 * int Status return value:
108 * 0: Success.
109 * 1: Null celprm pointer passed.
110 *
111 *
112 * celset() - Setup routine for the celprm struct
113 * ----------------------------------------------
114 * celset() sets up a celprm struct according to information supplied within
115 * it.
116 *
117 * Note that this routine need not be called directly; it will be invoked by
118 * celx2s() and cels2x() if celprm::flag is anything other than a predefined
119 * magic value.
120 *
121 * Given and returned:
122 * cel struct celprm*
123 * Celestial transformation parameters.
124 *
125 * Function return value:
126 * int Status return value:
127 * 0: Success.
128 * 1: Null celprm pointer passed.
129 * 2: Invalid projection parameters.
130 * 3: Invalid coordinate transformation parameters.
131 * 4: Ill-conditioned coordinate transformation
132 * parameters.
133 *
134 * For returns > 1, a detailed error message is set in
135 * celprm::err if enabled, see wcserr_enable().
136 *
137 *
138 * celx2s() - Pixel-to-world celestial transformation
139 * --------------------------------------------------
140 * celx2s() transforms (x,y) coordinates in the plane of projection to
141 * celestial coordinates (lng,lat).
142 *
143 * Given and returned:
144 * cel struct celprm*
145 * Celestial transformation parameters.
146 *
147 * Given:
148 * nx,ny int Vector lengths.
149 *
150 * sxy,sll int Vector strides.
151 *
152 * x,y const double[]
153 * Projected coordinates in pseudo "degrees".
154 *
155 * Returned:
156 * phi,theta double[] Longitude and latitude (phi,theta) in the native
157 * coordinate system of the projection [deg].
158 *
159 * lng,lat double[] Celestial longitude and latitude (lng,lat) of the
160 * projected point [deg].
161 *
162 * stat int[] Status return value for each vector element:
163 * 0: Success.
164 * 1: Invalid value of (x,y).
165 *
166 * Function return value:
167 * int Status return value:
168 * 0: Success.
169 * 1: Null celprm pointer passed.
170 * 2: Invalid projection parameters.
171 * 3: Invalid coordinate transformation parameters.
172 * 4: Ill-conditioned coordinate transformation
173 * parameters.
174 * 5: One or more of the (x,y) coordinates were
175 * invalid, as indicated by the stat vector.
176 *
177 * For returns > 1, a detailed error message is set in
178 * celprm::err if enabled, see wcserr_enable().
179 *
180 *
181 * cels2x() - World-to-pixel celestial transformation
182 * --------------------------------------------------
183 * cels2x() transforms celestial coordinates (lng,lat) to (x,y) coordinates in
184 * the plane of projection.
185 *
186 * Given and returned:
187 * cel struct celprm*
188 * Celestial transformation parameters.
189 *
190 * Given:
191 * nlng,nlat int Vector lengths.
192 *
193 * sll,sxy int Vector strides.
194 *
195 * lng,lat const double[]
196 * Celestial longitude and latitude (lng,lat) of the
197 * projected point [deg].
198 *
199 * Returned:
200 * phi,theta double[] Longitude and latitude (phi,theta) in the native
201 * coordinate system of the projection [deg].
202 *
203 * x,y double[] Projected coordinates in pseudo "degrees".
204 *
205 * stat int[] Status return value for each vector element:
206 * 0: Success.
207 * 1: Invalid value of (lng,lat).
208 *
209 * Function return value:
210 * int Status return value:
211 * 0: Success.
212 * 1: Null celprm pointer passed.
213 * 2: Invalid projection parameters.
214 * 3: Invalid coordinate transformation parameters.
215 * 4: Ill-conditioned coordinate transformation
216 * parameters.
217 * 6: One or more of the (lng,lat) coordinates were
218 * invalid, as indicated by the stat vector.
219 *
220 * For returns > 1, a detailed error message is set in
221 * celprm::err if enabled, see wcserr_enable().
222 *
223 *
224 * celprm struct - Celestial transformation parameters
225 * ---------------------------------------------------
226 * The celprm struct contains information required to transform celestial
227 * coordinates. It consists of certain members that must be set by the user
228 * ("given") and others that are set by the WCSLIB routines ("returned"). Some
229 * of the latter are supplied for informational purposes and others are for
230 * internal use only.
231 *
232 * Returned celprm struct members must not be modified by the user.
233 *
234 * int flag
235 * (Given and returned) This flag must be set to zero whenever any of the
236 * following celprm struct members are set or changed:
237 *
238 * - celprm::offset,
239 * - celprm::phi0,
240 * - celprm::theta0,
241 * - celprm::ref[4],
242 * - celprm::prj:
243 * - prjprm::code,
244 * - prjprm::r0,
245 * - prjprm::pv[],
246 * - prjprm::phi0,
247 * - prjprm::theta0.
248 *
249 * This signals the initialization routine, celset(), to recompute the
250 * returned members of the celprm struct. celset() will reset flag to
251 * indicate that this has been done.
252 *
253 * int offset
254 * (Given) If true (non-zero), an offset will be applied to (x,y) to
255 * force (x,y) = (0,0) at the fiducial point, (phi_0,theta_0).
256 * Default is 0 (false).
257 *
258 * double phi0
259 * (Given) The native longitude, phi_0 [deg], and ...
260 *
261 * double theta0
262 * (Given) ... the native latitude, theta_0 [deg], of the fiducial point,
263 * i.e. the point whose celestial coordinates are given in
264 * celprm::ref[1:2]. If undefined (set to a magic value by prjini()) the
265 * initialization routine, celset(), will set this to a projection-specific
266 * default.
267 *
268 * double ref[4]
269 * (Given) The first pair of values should be set to the celestial
270 * longitude and latitude of the fiducial point [deg] - typically right
271 * ascension and declination. These are given by the CRVALia keywords in
272 * FITS.
273 *
274 * (Given and returned) The second pair of values are the native longitude,
275 * phi_p [deg], and latitude, theta_p [deg], of the celestial pole (the
276 * latter is the same as the celestial latitude of the native pole,
277 * delta_p) and these are given by the FITS keywords LONPOLEa and LATPOLEa
278 * (or by PVi_2a and PVi_3a attached to the longitude axis which take
279 * precedence if defined).
280 *
281 * LONPOLEa defaults to phi_0 (see above) if the celestial latitude of the
282 * fiducial point of the projection is greater than or equal to the native
283 * latitude, otherwise phi_0 + 180 [deg]. (This is the condition for the
284 * celestial latitude to increase in the same direction as the native
285 * latitude at the fiducial point.) ref[2] may be set to UNDEFINED (from
286 * wcsmath.h) or 999.0 to indicate that the correct default should be
287 * substituted.
288 *
289 * theta_p, the native latitude of the celestial pole (or equally the
290 * celestial latitude of the native pole, delta_p) is often determined
291 * uniquely by CRVALia and LONPOLEa in which case LATPOLEa is ignored.
292 * However, in some circumstances there are two valid solutions for theta_p
293 * and LATPOLEa is used to choose between them. LATPOLEa is set in ref[3]
294 * and the solution closest to this value is used to reset ref[3]. It is
295 * therefore legitimate, for example, to set ref[3] to +90.0 to choose the
296 * more northerly solution - the default if the LATPOLEa keyword is omitted
297 * from the FITS header. For the special case where the fiducial point of
298 * the projection is at native latitude zero, its celestial latitude is
299 * zero, and LONPOLEa = +/- 90.0 then the celestial latitude of the native
300 * pole is not determined by the first three reference values and LATPOLEa
301 * specifies it completely.
302 *
303 * The returned value, celprm::latpreq, specifies how LATPOLEa was actually
304 * used.
305 *
306 * struct prjprm prj
307 * (Given and returned) Projection parameters described in the prologue to
308 * prj.h.
309 *
310 * double euler[5]
311 * (Returned) Euler angles and associated intermediaries derived from the
312 * coordinate reference values. The first three values are the Z-, X-, and
313 * Z'-Euler angles [deg], and the remaining two are the cosine and sine of
314 * the X-Euler angle.
315 *
316 * int latpreq
317 * (Returned) For informational purposes, this indicates how the LATPOLEa
318 * keyword was used
319 * - 0: Not required, theta_p (== delta_p) was determined uniquely by the
320 * CRVALia and LONPOLEa keywords.
321 * - 1: Required to select between two valid solutions of theta_p.
322 * - 2: theta_p was specified solely by LATPOLEa.
323 *
324 * int isolat
325 * (Returned) True if the spherical rotation preserves the magnitude of the
326 * latitude, which occurs iff the axes of the native and celestial
327 * coordinates are coincident. It signals an opportunity to cache
328 * intermediate calculations common to all elements in a vector
329 * computation.
330 *
331 * struct wcserr *err
332 * (Returned) If enabled, when an error status is returned this struct
333 * contains detailed information about the error, see wcserr_enable().
334 *
335 * void *padding
336 * (An unused variable inserted for alignment purposes only.)
337 *
338 * Global variable: const char *cel_errmsg[] - Status return messages
339 * ------------------------------------------------------------------
340 * Status messages to match the status value returned from each function.
341 *
342 *===========================================================================*/
343
344 #ifndef WCSLIB_CEL
345 #define WCSLIB_CEL
346
347 #include "prj.h"
348 #include "wcserr.h"
349
350 #ifdef __cplusplus
351 extern "C" {
352 #endif
353
354
355 extern const char *cel_errmsg[];
356
357 enum cel_errmsg_enum {
358 CELERR_SUCCESS = 0, /* Success. */
359 CELERR_NULL_POINTER = 1, /* Null celprm pointer passed. */
360 CELERR_BAD_PARAM = 2, /* Invalid projection parameters. */
361 CELERR_BAD_COORD_TRANS = 3, /* Invalid coordinate transformation
362 parameters. */
363 CELERR_ILL_COORD_TRANS = 4, /* Ill-conditioned coordinated transformation
364 parameters. */
365 CELERR_BAD_PIX = 5, /* One or more of the (x,y) coordinates were
366 invalid. */
367 CELERR_BAD_WORLD = 6 /* One or more of the (lng,lat) coordinates
368 were invalid. */
369 };
370
371 struct celprm {
372 /* Initialization flag (see the prologue above). */
373 /*------------------------------------------------------------------------*/
374 int flag; /* Set to zero to force initialization. */
375
376 /* Parameters to be provided (see the prologue above). */
377 /*------------------------------------------------------------------------*/
378 int offset; /* Force (x,y) = (0,0) at (phi_0,theta_0). */
379 double phi0, theta0; /* Native coordinates of fiducial point. */
380 double ref[4]; /* Celestial coordinates of fiducial */
381 /* point and native coordinates of */
382 /* celestial pole. */
383
384 struct prjprm prj; /* Projection parameters (see prj.h). */
385
386 /* Information derived from the parameters supplied. */
387 /*------------------------------------------------------------------------*/
388 double euler[5]; /* Euler angles and functions thereof. */
389 int latpreq; /* LATPOLEa requirement. */
390 int isolat; /* True if |latitude| is preserved. */
391
392 /* Error handling */
393 /*------------------------------------------------------------------------*/
394 struct wcserr *err;
395
396 /* Private */
397 /*------------------------------------------------------------------------*/
398 void *padding; /* (Dummy inserted for alignment purposes.) */
399 };
400
401 /* Size of the celprm struct in int units, used by the Fortran wrappers. */
402 #define CELLEN (sizeof(struct celprm)/sizeof(int))
403
404
405 int celini(struct celprm *cel);
406
407 int celfree(struct celprm *cel);
408
409 int celprt(const struct celprm *cel);
410
411 int celset(struct celprm *cel);
412
413 int celx2s(struct celprm *cel, int nx, int ny, int sxy, int sll,
414 const double x[], const double y[],
415 double phi[], double theta[], double lng[], double lat[],
416 int stat[]);
417
418 int cels2x(struct celprm *cel, int nlng, int nlat, int sll, int sxy,
419 const double lng[], const double lat[],
420 double phi[], double theta[], double x[], double y[],
421 int stat[]);
422
423
424 /* Deprecated. */
425 #define celini_errmsg cel_errmsg
426 #define celprt_errmsg cel_errmsg
427 #define celset_errmsg cel_errmsg
428 #define celx2s_errmsg cel_errmsg
429 #define cels2x_errmsg cel_errmsg
430
431 #ifdef __cplusplus
432 }
433 #endif
434
435 #endif /* WCSLIB_CEL */
cel_errmsg
const char * cel_errmsg[]
celprt
int celprt(const struct celprm *cel)
Print routine for the celprm struct.
celprm::ref
double ref[4]
Definition: cel.h:380
CELERR_NULL_POINTER
Definition: cel.h:359
cels2x
int cels2x(struct celprm *cel, int nlng, int nlat, int sll, int sxy, const double lng[], const double lat[], double phi[], double theta[], double x[], double y[], int stat[])
World-to-pixel celestial transformation.
prj.h
wcserr
Error message handling.
Definition: wcserr.h:221
celprm
Celestial transformation parameters.
Definition: cel.h:371
cel_errmsg_enum
cel_errmsg_enum
Definition: cel.h:357
celprm::offset
int offset
Definition: cel.h:378
CELERR_ILL_COORD_TRANS
Definition: cel.h:363
CELERR_BAD_PIX
Definition: cel.h:365
prjprm
Projection parameters.
Definition: prj.h:638
celfree
int celfree(struct celprm *cel)
Destructor for the celprm struct.
celprm::latpreq
int latpreq
Definition: cel.h:389
CELERR_BAD_COORD_TRANS
Definition: cel.h:361
celprm::flag
int flag
Definition: cel.h:374
celprm::theta0
double theta0
Definition: cel.h:379
celini
int celini(struct celprm *cel)
Default constructor for the celprm struct.
celprm::padding
void * padding
Definition: cel.h:398
wcserr.h
CELERR_BAD_WORLD
Definition: cel.h:367
CELERR_SUCCESS
Definition: cel.h:358
celprm::isolat
int isolat
Definition: cel.h:390
celprm::phi0
double phi0
Definition: cel.h:379
celprm::err
struct wcserr * err
Definition: cel.h:394
celx2s
int celx2s(struct celprm *cel, int nx, int ny, int sxy, int sll, const double x[], const double y[], double phi[], double theta[], double lng[], double lat[], int stat[])
Pixel-to-world celestial transformation.
celprm::euler
double euler[5]
Definition: cel.h:388
celprm::prj
struct prjprm prj
Definition: cel.h:384
celset
int celset(struct celprm *cel)
Setup routine for the celprm struct.
CELERR_BAD_PARAM
Definition: cel.h:360