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