WCSLIB: cel.h Source File

WCSLIB 8.4

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