WCSLIB: cel.h Source File

WCSLIB 8.1

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