wcslib (8.2.2)
1 /*============================================================================
2 WCSLIB 8.2 - 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.2.1.1 2023/11/16 10:05:57 mcalabre Exp mcalabre $
23 *=============================================================================
24 *
25 * WCSLIB 8.2 - 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
403 extern "C" {
404 #endif
405
406
407 extern 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
Browse
Usage
Versions