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