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