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