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: prj.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 prj routines
31 * ---------------------------
32 * Routines in this suite implement the spherical map projections defined by
33 * the FITS World Coordinate System (WCS) standard, 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 = "Mapping on the HEALPix grid",
42 = Calabretta, M.R., & Roukema, B.F. 2007, MNRAS, 381, 865 (WCS Paper V)
43 =
44 = "Representing the 'Butterfly' Projection in FITS -- Projection Code XPH",
45 = Calabretta, M.R., & Lowe, S.R. 2013, PASA, 30, e050 (WCS Paper VI)
46 *
47 * These routines are based on the prjprm struct which contains all information
48 * needed for the computations. The struct contains some members that must be
49 * set by the user, and others that are maintained by these routines, somewhat
50 * like a C++ class but with no encapsulation.
51 *
52 * Routine prjini() is provided to initialize the prjprm struct with default
53 * values, prjfree() reclaims any memory that may have been allocated to store
54 * an error message, prjsize() computes its total size including allocated
55 * memory, and prjprt() prints its contents.
56 *
57 * prjperr() prints the error message(s) (if any) stored in a prjprm struct.
58 * prjbchk() performs bounds checking on native spherical coordinates.
59 *
60 * Setup routines for each projection with names of the form ???set(), where
61 * "???" is the down-cased three-letter projection code, compute intermediate
62 * values in the prjprm struct from parameters in it that were supplied by the
63 * user. The struct always needs to be set by the projection's setup routine
64 * but that need not be called explicitly - refer to the explanation of
65 * prjprm::flag.
66 *
67 * Each map projection is implemented via separate functions for the spherical
68 * projection, ???s2x(), and deprojection, ???x2s().
69 *
70 * A set of driver routines, prjset(), prjx2s(), and prjs2x(), provides a
71 * generic interface to the specific projection routines which they invoke
72 * via pointers-to-functions stored in the prjprm struct.
73 *
74 * In summary, the routines are:
75 * - prjini() Initialization routine for the prjprm struct.
76 * - prjfree() Reclaim memory allocated for error messages.
77 * - prjsize() Compute total size of a prjprm struct.
78 * - prjprt() Print a prjprm struct.
79 * - prjperr() Print error message (if any).
80 * - prjbchk() Bounds checking on native coordinates.
81 *
82 * - prjset(), prjx2s(), prjs2x(): Generic driver routines
83 *
84 * - azpset(), azpx2s(), azps2x(): AZP (zenithal/azimuthal perspective)
85 * - szpset(), szpx2s(), szps2x(): SZP (slant zenithal perspective)
86 * - tanset(), tanx2s(), tans2x(): TAN (gnomonic)
87 * - stgset(), stgx2s(), stgs2x(): STG (stereographic)
88 * - sinset(), sinx2s(), sins2x(): SIN (orthographic/synthesis)
89 * - arcset(), arcx2s(), arcs2x(): ARC (zenithal/azimuthal equidistant)
90 * - zpnset(), zpnx2s(), zpns2x(): ZPN (zenithal/azimuthal polynomial)
91 * - zeaset(), zeax2s(), zeas2x(): ZEA (zenithal/azimuthal equal area)
92 * - airset(), airx2s(), airs2x(): AIR (Airy)
93 * - cypset(), cypx2s(), cyps2x(): CYP (cylindrical perspective)
94 * - ceaset(), ceax2s(), ceas2x(): CEA (cylindrical equal area)
95 * - carset(), carx2s(), cars2x(): CAR (Plate carree)
96 * - merset(), merx2s(), mers2x(): MER (Mercator)
97 * - sflset(), sflx2s(), sfls2x(): SFL (Sanson-Flamsteed)
98 * - parset(), parx2s(), pars2x(): PAR (parabolic)
99 * - molset(), molx2s(), mols2x(): MOL (Mollweide)
100 * - aitset(), aitx2s(), aits2x(): AIT (Hammer-Aitoff)
101 * - copset(), copx2s(), cops2x(): COP (conic perspective)
102 * - coeset(), coex2s(), coes2x(): COE (conic equal area)
103 * - codset(), codx2s(), cods2x(): COD (conic equidistant)
104 * - cooset(), coox2s(), coos2x(): COO (conic orthomorphic)
105 * - bonset(), bonx2s(), bons2x(): BON (Bonne)
106 * - pcoset(), pcox2s(), pcos2x(): PCO (polyconic)
107 * - tscset(), tscx2s(), tscs2x(): TSC (tangential spherical cube)
108 * - cscset(), cscx2s(), cscs2x(): CSC (COBE spherical cube)
109 * - qscset(), qscx2s(), qscs2x(): QSC (quadrilateralized spherical cube)
110 * - hpxset(), hpxx2s(), hpxs2x(): HPX (HEALPix)
111 * - xphset(), xphx2s(), xphs2x(): XPH (HEALPix polar, aka "butterfly")
112 *
113 * Argument checking (projection routines):
114 * ----------------------------------------
115 * The values of phi and theta (the native longitude and latitude) normally lie
116 * in the range [-180,180] for phi, and [-90,90] for theta. However, all
117 * projection routines will accept any value of phi and will not normalize it.
118 *
119 * The projection routines do not explicitly check that theta lies within the
120 * range [-90,90]. They do check for any value of theta that produces an
121 * invalid argument to the projection equations (e.g. leading to division by
122 * zero). The projection routines for AZP, SZP, TAN, SIN, ZPN, and COP also
123 * return error 2 if (phi,theta) corresponds to the overlapped (far) side of
124 * the projection but also return the corresponding value of (x,y). This
125 * strict bounds checking may be relaxed at any time by setting
126 * prjprm::bounds%2 to 0 (rather than 1); the projections need not be
127 * reinitialized.
128 *
129 * Argument checking (deprojection routines):
130 * ------------------------------------------
131 * Error checking on the projected coordinates (x,y) is limited to that
132 * required to ascertain whether a solution exists. Where a solution does
133 * exist, an optional check is made that the value of phi and theta obtained
134 * lie within the ranges [-180,180] for phi, and [-90,90] for theta. This
135 * check, performed by prjbchk(), is enabled by default. It may be disabled by
136 * setting prjprm::bounds%4 to 0 (rather than 1); the projections need not be
137 * reinitialized.
138 *
139 * Accuracy:
140 * ---------
141 * No warranty is given for the accuracy of these routines (refer to the
142 * copyright notice); intending users must satisfy for themselves their
143 * adequacy for the intended purpose. However, closure to a precision of at
144 * least 1E-10 degree of longitude and latitude has been verified for typical
145 * projection parameters on the 1 degree graticule of native longitude and
146 * latitude (to within 5 degrees of any latitude where the projection may
147 * diverge). Refer to the tprj1.c and tprj2.c test routines that accompany
148 * this software.
149 *
150 *
151 * prjini() - Default constructor for the prjprm struct
152 * ----------------------------------------------------
153 * prjini() sets all members of a prjprm struct to default values. It should
154 * be used to initialize every prjprm struct.
155 *
156 * PLEASE NOTE: If the prjprm struct has already been initialized, then before
157 * reinitializing, it prjfree() should be used to free any memory that may have
158 * been allocated to store an error message. A memory leak may otherwise
159 * result.
160 *
161 * Returned:
162 * prj struct prjprm*
163 * Projection parameters.
164 *
165 * Function return value:
166 * int Status return value:
167 * 0: Success.
168 * 1: Null prjprm pointer passed.
169 *
170 *
171 * prjfree() - Destructor for the prjprm struct
172 * --------------------------------------------
173 * prjfree() frees any memory that may have been allocated to store an error
174 * message in the prjprm struct.
175 *
176 * Given:
177 * prj struct prjprm*
178 * Projection parameters.
179 *
180 * Function return value:
181 * int Status return value:
182 * 0: Success.
183 * 1: Null prjprm pointer passed.
184 *
185 *
186 * prjsize() - Compute the size of a prjprm struct
187 * -----------------------------------------------
188 * prjsize() computes the full size of a prjprm struct, including allocated
189 * memory.
190 *
191 * Given:
192 * prj const struct prjprm*
193 * Projection parameters.
194 *
195 * If NULL, the base size of the struct and the allocated
196 * size are both set to zero.
197 *
198 * Returned:
199 * sizes int[2] The first element is the base size of the struct as
200 * returned by sizeof(struct prjprm). The second element
201 * is the total allocated size, in bytes. This figure
202 * includes memory allocated for the constituent struct,
203 * prjprm::err.
204 *
205 * It is not an error for the struct not to have been set
206 * up via prjset().
207 *
208 * Function return value:
209 * int Status return value:
210 * 0: Success.
211 *
212 *
213 * prjprt() - Print routine for the prjprm struct
214 * ----------------------------------------------
215 * prjprt() prints the contents of a prjprm struct using wcsprintf(). Mainly
216 * intended for diagnostic purposes.
217 *
218 * Given:
219 * prj const struct prjprm*
220 * Projection parameters.
221 *
222 * Function return value:
223 * int Status return value:
224 * 0: Success.
225 * 1: Null prjprm pointer passed.
226 *
227 *
228 * prjperr() - Print error messages from a prjprm struct
229 * -----------------------------------------------------
230 * prjperr() prints the error message(s) (if any) stored in a prjprm struct.
231 * If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.
232 *
233 * Given:
234 * prj const struct prjprm*
235 * Projection parameters.
236 *
237 * prefix const char *
238 * If non-NULL, each output line will be prefixed with
239 * this string.
240 *
241 * Function return value:
242 * int Status return value:
243 * 0: Success.
244 * 1: Null prjprm pointer passed.
245 *
246 *
247 * prjbchk() - Bounds checking on native coordinates
248 * -------------------------------------------------
249 * prjbchk() performs bounds checking on native spherical coordinates. As
250 * returned by the deprojection (x2s) routines, native longitude is expected
251 * to lie in the closed interval [-180,180], with latitude in [-90,90].
252 *
253 * A tolerance may be specified to provide a small allowance for numerical
254 * imprecision. Values that lie outside the allowed range by not more than
255 * the specified tolerance will be adjusted back into range.
256 *
257 * If prjprm::bounds&4 is set, as it is by prjini(), then prjbchk() will be
258 * invoked automatically by the Cartesian-to-spherical deprojection (x2s)
259 * routines with an appropriate tolerance set for each projection.
260 *
261 * Given:
262 * tol double Tolerance for the bounds check [deg].
263 *
264 * nphi,
265 * ntheta int Vector lengths.
266 *
267 * spt int Vector stride.
268 *
269 * Given and returned:
270 * phi,theta double[] Native longitude and latitude (phi,theta) [deg].
271 *
272 * Returned:
273 * stat int[] Status value for each vector element:
274 * 0: Valid value of (phi,theta).
275 * 1: Invalid value.
276 *
277 * Function return value:
278 * int Status return value:
279 * 0: Success.
280 * 1: One or more of the (phi,theta) coordinates
281 * were, invalid, as indicated by the stat vector.
282 *
283 *
284 * prjset() - Generic setup routine for the prjprm struct
285 * ------------------------------------------------------
286 * prjset() sets up a prjprm struct according to information supplied within
287 * it.
288 *
289 * Note that this routine need not be called directly; it will be invoked by
290 * prjx2s() and prjs2x() if prj.flag is anything other than a predefined magic
291 * value.
292 *
293 * The one important distinction between prjset() and the setup routines for
294 * the specific projections is that the projection code must be defined in the
295 * prjprm struct in order for prjset() to identify the required projection.
296 * Once prjset() has initialized the prjprm struct, prjx2s() and prjs2x() use
297 * the pointers to the specific projection and deprojection routines contained
298 * therein.
299 *
300 * Given and returned:
301 * prj struct prjprm*
302 * Projection parameters.
303 *
304 * Function return value:
305 * int Status return value:
306 * 0: Success.
307 * 1: Null prjprm pointer passed.
308 * 2: Invalid projection parameters.
309 *
310 * For returns > 1, a detailed error message is set in
311 * prjprm::err if enabled, see wcserr_enable().
312 *
313 *
314 * prjx2s() - Generic Cartesian-to-spherical deprojection
315 * ------------------------------------------------------
316 * Deproject Cartesian (x,y) coordinates in the plane of projection to native
317 * spherical coordinates (phi,theta).
318 *
319 * The projection is that specified by prjprm::code.
320 *
321 * Given and returned:
322 * prj struct prjprm*
323 * Projection parameters.
324 *
325 * Given:
326 * nx,ny int Vector lengths.
327 *
328 * sxy,spt int Vector strides.
329 *
330 * x,y const double[]
331 * Projected coordinates.
332 *
333 * Returned:
334 * phi,theta double[] Longitude and latitude (phi,theta) of the projected
335 * point in native spherical coordinates [deg].
336 *
337 * stat int[] Status value for each vector element:
338 * 0: Success.
339 * 1: Invalid value of (x,y).
340 *
341 * Function return value:
342 * int Status return value:
343 * 0: Success.
344 * 1: Null prjprm pointer passed.
345 * 2: Invalid projection parameters.
346 * 3: One or more of the (x,y) coordinates were
347 * invalid, as indicated by the stat vector.
348 *
349 * For returns > 1, a detailed error message is set in
350 * prjprm::err if enabled, see wcserr_enable().
351 *
352 *
353 * prjs2x() - Generic spherical-to-Cartesian projection
354 * ----------------------------------------------------
355 * Project native spherical coordinates (phi,theta) to Cartesian (x,y)
356 * coordinates in the plane of projection.
357 *
358 * The projection is that specified by prjprm::code.
359 *
360 * Given and returned:
361 * prj struct prjprm*
362 * Projection parameters.
363 *
364 * Given:
365 * nphi,
366 * ntheta int Vector lengths.
367 *
368 * spt,sxy int Vector strides.
369 *
370 * phi,theta const double[]
371 * Longitude and latitude (phi,theta) of the projected
372 * point in native spherical coordinates [deg].
373 *
374 * Returned:
375 * x,y double[] Projected coordinates.
376 *
377 * stat int[] Status value for each vector element:
378 * 0: Success.
379 * 1: Invalid value of (phi,theta).
380 *
381 * Function return value:
382 * int Status return value:
383 * 0: Success.
384 * 1: Null prjprm pointer passed.
385 * 2: Invalid projection parameters.
386 * 4: One or more of the (phi,theta) coordinates
387 * were, invalid, as indicated by the stat vector.
388 *
389 * For returns > 1, a detailed error message is set in
390 * prjprm::err if enabled, see wcserr_enable().
391 *
392 *
393 * ???set() - Specific setup routines for the prjprm struct
394 * --------------------------------------------------------
395 * Set up a prjprm struct for a particular projection according to information
396 * supplied within it.
397 *
398 * Given and returned:
399 * prj struct prjprm*
400 * Projection parameters.
401 *
402 * Function return value:
403 * int Status return value:
404 * 0: Success.
405 * 1: Null prjprm pointer passed.
406 * 2: Invalid projection parameters.
407 *
408 * For returns > 1, a detailed error message is set in
409 * prjprm::err if enabled, see wcserr_enable().
410 *
411 *
412 * ???x2s() - Specific Cartesian-to-spherical deprojection routines
413 * ----------------------------------------------------------------
414 * Transform (x,y) coordinates in the plane of projection to native spherical
415 * coordinates (phi,theta).
416 *
417 * Given and returned:
418 * prj struct prjprm*
419 * Projection parameters.
420 *
421 * Given:
422 * nx,ny int Vector lengths.
423 *
424 * sxy,spt int Vector strides.
425 *
426 * x,y const double[]
427 * Projected coordinates.
428 *
429 * Returned:
430 * phi,theta double[] Longitude and latitude of the projected point in
431 * native spherical coordinates [deg].
432 *
433 * stat int[] Status value for each vector element:
434 * 0: Success.
435 * 1: Invalid value of (x,y).
436 *
437 * Function return value:
438 * int Status return value:
439 * 0: Success.
440 * 1: Null prjprm pointer passed.
441 * 2: Invalid projection parameters.
442 * 3: One or more of the (x,y) coordinates were
443 * invalid, as indicated by the stat vector.
444 *
445 * For returns > 1, a detailed error message is set in
446 * prjprm::err if enabled, see wcserr_enable().
447 *
448 *
449 * ???s2x() - Specific spherical-to-Cartesian projection routines
450 *---------------------------------------------------------------
451 * Transform native spherical coordinates (phi,theta) to (x,y) coordinates in
452 * the plane of projection.
453 *
454 * Given and returned:
455 * prj struct prjprm*
456 * Projection parameters.
457 *
458 * Given:
459 * nphi,
460 * ntheta int Vector lengths.
461 *
462 * spt,sxy int Vector strides.
463 *
464 * phi,theta const double[]
465 * Longitude and latitude of the projected point in
466 * native spherical coordinates [deg].
467 *
468 * Returned:
469 * x,y double[] Projected coordinates.
470 *
471 * stat int[] Status value for each vector element:
472 * 0: Success.
473 * 1: Invalid value of (phi,theta).
474 *
475 * Function return value:
476 * int Status return value:
477 * 0: Success.
478 * 1: Null prjprm pointer passed.
479 * 2: Invalid projection parameters.
480 * 4: One or more of the (phi,theta) coordinates
481 * were, invalid, as indicated by the stat vector.
482 *
483 * For returns > 1, a detailed error message is set in
484 * prjprm::err if enabled, see wcserr_enable().
485 *
486 *
487 * prjprm struct - Projection parameters
488 * -------------------------------------
489 * The prjprm struct contains all information needed to project or deproject
490 * native spherical coordinates. It consists of certain members that must be
491 * set by the user ("given") and others that are set by the WCSLIB routines
492 * ("returned"). Some of the latter are supplied for informational purposes
493 * while others are for internal use only.
494 *
495 * int flag
496 * (Given and returned) This flag must be set to zero whenever any of the
497 * following prjprm struct members are set or changed:
498 *
499 * - prjprm::code,
500 * - prjprm::r0,
501 * - prjprm::pv[],
502 * - prjprm::phi0,
503 * - prjprm::theta0.
504 *
505 * This signals the initialization routine (prjset() or ???set()) to
506 * recompute the returned members of the prjprm struct. flag will then be
507 * reset to indicate that this has been done.
508 *
509 * Note that flag need not be reset when prjprm::bounds is changed.
510 *
511 * char code[4]
512 * (Given) Three-letter projection code defined by the FITS standard.
513 *
514 * double r0
515 * (Given) The radius of the generating sphere for the projection, a linear
516 * scaling parameter. If this is zero, it will be reset to its default
517 * value of 180/pi (the value for FITS WCS).
518 *
519 * double pv[30]
520 * (Given) Projection parameters. These correspond to the PVi_ma keywords
521 * in FITS, so pv[0] is PVi_0a, pv[1] is PVi_1a, etc., where i denotes the
522 * latitude-like axis. Many projections use pv[1] (PVi_1a), some also use
523 * pv[2] (PVi_2a) and SZP uses pv[3] (PVi_3a). ZPN is currently the only
524 * projection that uses any of the others.
525 *
526 * Usage of the pv[] array as it applies to each projection is described in
527 * the prologue to each trio of projection routines in prj.c.
528 *
529 * double phi0
530 * (Given) The native longitude, phi_0 [deg], and ...
531 * double theta0
532 * (Given) ... the native latitude, theta_0 [deg], of the reference point,
533 * i.e. the point (x,y) = (0,0). If undefined (set to a magic value by
534 * prjini()) the initialization routine will set this to a
535 * projection-specific default.
536 *
537 * int bounds
538 * (Given) Controls bounds checking. If bounds&1 then enable strict bounds
539 * checking for the spherical-to-Cartesian (s2x) transformation for the
540 * AZP, SZP, TAN, SIN, ZPN, and COP projections. If bounds&2 then enable
541 * strict bounds checking for the Cartesian-to-spherical transformation
542 * (x2s) for the HPX and XPH projections. If bounds&4 then the Cartesian-
543 * to-spherical transformations (x2s) will invoke prjbchk() to perform
544 * bounds checking on the computed native coordinates, with a tolerance set
545 * to suit each projection. bounds is set to 7 by prjini() by default
546 * which enables all checks. Zero it to disable all checking.
547 *
548 * It is not necessary to reset the prjprm struct (via prjset() or
549 * ???set()) when prjprm::bounds is changed.
550 *
551 * The remaining members of the prjprm struct are maintained by the setup
552 * routines and must not be modified elsewhere:
553 *
554 * char name[40]
555 * (Returned) Long name of the projection.
556 *
557 * Provided for information only, not used by the projection routines.
558 *
559 * int category
560 * (Returned) Projection category matching the value of the relevant global
561 * variable:
562 *
563 * - ZENITHAL,
564 * - CYLINDRICAL,
565 * - PSEUDOCYLINDRICAL,
566 * - CONVENTIONAL,
567 * - CONIC,
568 * - POLYCONIC,
569 * - QUADCUBE, and
570 * - HEALPIX.
571 *
572 * The category name may be identified via the prj_categories character
573 * array, e.g.
574 *
575 = struct prjprm prj;
576 = ...
577 = printf("%s\n", prj_categories[prj.category]);
578 *
579 * Provided for information only, not used by the projection routines.
580 *
581 * int pvrange
582 * (Returned) Range of projection parameter indices: 100 times the first
583 * allowed index plus the number of parameters, e.g. TAN is 0 (no
584 * parameters), SZP is 103 (1 to 3), and ZPN is 30 (0 to 29).
585 *
586 * Provided for information only, not used by the projection routines.
587 *
588 * int simplezen
589 * (Returned) True if the projection is a radially-symmetric zenithal
590 * projection.
591 *
592 * Provided for information only, not used by the projection routines.
593 *
594 * int equiareal
595 * (Returned) True if the projection is equal area.
596 *
597 * Provided for information only, not used by the projection routines.
598 *
599 * int conformal
600 * (Returned) True if the projection is conformal.
601 *
602 * Provided for information only, not used by the projection routines.
603 *
604 * int global
605 * (Returned) True if the projection can represent the whole sphere in a
606 * finite, non-overlapped mapping.
607 *
608 * Provided for information only, not used by the projection routines.
609 *
610 * int divergent
611 * (Returned) True if the projection diverges in latitude.
612 *
613 * Provided for information only, not used by the projection routines.
614 *
615 * double x0
616 * (Returned) The offset in x, and ...
617 * double y0
618 * (Returned) ... the offset in y used to force (x,y) = (0,0) at
619 * (phi_0,theta_0).
620 *
621 * struct wcserr *err
622 * (Returned) If enabled, when an error status is returned, this struct
623 * contains detailed information about the error, see wcserr_enable().
624 *
625 * void *padding
626 * (An unused variable inserted for alignment purposes only.)
627 *
628 * double w[10]
629 * (Returned) Intermediate floating-point values derived from the
630 * projection parameters, cached here to save recomputation.
631 *
632 * Usage of the w[] array as it applies to each projection is described in
633 * the prologue to each trio of projection routines in prj.c.
634 *
635 * int n
636 * (Returned) Intermediate integer value (used only for the ZPN and HPX
637 * projections).
638 *
639 * int (*prjx2s)(PRJX2S_ARGS)
640 * (Returned) Pointer to the spherical projection ...
641 * int (*prjs2x)(PRJ_ARGS)
642 * (Returned) ... and deprojection routines.
643 *
644 *
645 * Global variable: const char *prj_errmsg[] - Status return messages
646 * ------------------------------------------------------------------
647 * Error messages to match the status value returned from each function.
648 *
649 *===========================================================================*/
650
651 #ifndef WCSLIB_PROJ
652 #define WCSLIB_PROJ
653
654 #ifdef __cplusplus
655 extern "C" {
656 #endif
657
658
659 // Total number of projection parameters; 0 to PVN-1.
660 #define PVN 30
661
662 extern const char *prj_errmsg[];
663
664 enum prj_errmsg_enum {
665 PRJERR_SUCCESS = 0, // Success.
666 PRJERR_NULL_POINTER = 1, // Null prjprm pointer passed.
667 PRJERR_BAD_PARAM = 2, // Invalid projection parameters.
668 PRJERR_BAD_PIX = 3, // One or more of the (x, y) coordinates were
669 // invalid.
670 PRJERR_BAD_WORLD = 4 // One or more of the (phi, theta) coordinates
671 // were invalid.
672 };
673
674 extern const int CONIC, CONVENTIONAL, CYLINDRICAL, POLYCONIC,
675 PSEUDOCYLINDRICAL, QUADCUBE, ZENITHAL, HEALPIX;
676 extern const char prj_categories[9][32];
677
678 extern const int prj_ncode;
679 extern const char prj_codes[28][4];
680
681 #ifdef PRJX2S_ARGS
682 #undef PRJX2S_ARGS
683 #endif
684
685 #ifdef PRJS2X_ARGS
686 #undef PRJS2X_ARGS
687 #endif
688
689 // For use in declaring deprojection function prototypes.
690 #define PRJX2S_ARGS struct prjprm *prj, int nx, int ny, int sxy, int spt, \
691 const double x[], const double y[], double phi[], double theta[], int stat[]
692
693 // For use in declaring projection function prototypes.
694 #define PRJS2X_ARGS struct prjprm *prj, int nx, int ny, int sxy, int spt, \
695 const double phi[], const double theta[], double x[], double y[], int stat[]
696
697
698 struct prjprm {
699 // Initialization flag (see the prologue above).
700 //--------------------------------------------------------------------------
701 int flag; // Set to zero to force initialization.
702
703 // Parameters to be provided (see the prologue above).
704 //--------------------------------------------------------------------------
705 char code[4]; // Three-letter projection code.
706 double r0; // Radius of the generating sphere.
707 double pv[PVN]; // Projection parameters.
708 double phi0, theta0; // Fiducial native coordinates.
709 int bounds; // Controls bounds checking.
710
711 // Information derived from the parameters supplied.
712 //--------------------------------------------------------------------------
713 char name[40]; // Projection name.
714 int category; // Projection category.
715 int pvrange; // Range of projection parameter indices.
716 int simplezen; // Is it a simple zenithal projection?
717 int equiareal; // Is it an equal area projection?
718 int conformal; // Is it a conformal projection?
719 int global; // Can it map the whole sphere?
720 int divergent; // Does the projection diverge in latitude?
721 double x0, y0; // Fiducial offsets.
722
723 // Error handling
724 //--------------------------------------------------------------------------
725 struct wcserr *err;
726
727 // Private
728 //--------------------------------------------------------------------------
729 void *padding; // (Dummy inserted for alignment purposes.)
730 double w[10]; // Intermediate values.
731 int m, n; // Intermediate values.
732
733 int (*prjx2s)(PRJX2S_ARGS); // Pointers to the spherical projection and
734 int (*prjs2x)(PRJS2X_ARGS); // deprojection functions.
735 };
736
737 // Size of the prjprm struct in int units, used by the Fortran wrappers.
738 #define PRJLEN (sizeof(struct prjprm)/sizeof(int))
739
740
741 int prjini(struct prjprm *prj);
742
743 int prjfree(struct prjprm *prj);
744
745 int prjsize(const struct prjprm *prj, int sizes[2]);
746
747 int prjprt(const struct prjprm *prj);
748
749 int prjperr(const struct prjprm *prj, const char *prefix);
750
751 int prjbchk(double tol, int nphi, int ntheta, int spt, double phi[],
752 double theta[], int stat[]);
753
754 // Use the preprocessor to help declare function prototypes (see above).
755 int prjset(struct prjprm *prj);
756 int prjx2s(PRJX2S_ARGS);
757 int prjs2x(PRJS2X_ARGS);
758
759 int azpset(struct prjprm *prj);
760 int azpx2s(PRJX2S_ARGS);
761 int azps2x(PRJS2X_ARGS);
762
763 int szpset(struct prjprm *prj);
764 int szpx2s(PRJX2S_ARGS);
765 int szps2x(PRJS2X_ARGS);
766
767 int tanset(struct prjprm *prj);
768 int tanx2s(PRJX2S_ARGS);
769 int tans2x(PRJS2X_ARGS);
770
771 int stgset(struct prjprm *prj);
772 int stgx2s(PRJX2S_ARGS);
773 int stgs2x(PRJS2X_ARGS);
774
775 int sinset(struct prjprm *prj);
776 int sinx2s(PRJX2S_ARGS);
777 int sins2x(PRJS2X_ARGS);
778
779 int arcset(struct prjprm *prj);
780 int arcx2s(PRJX2S_ARGS);
781 int arcs2x(PRJS2X_ARGS);
782
783 int zpnset(struct prjprm *prj);
784 int zpnx2s(PRJX2S_ARGS);
785 int zpns2x(PRJS2X_ARGS);
786
787 int zeaset(struct prjprm *prj);
788 int zeax2s(PRJX2S_ARGS);
789 int zeas2x(PRJS2X_ARGS);
790
791 int airset(struct prjprm *prj);
792 int airx2s(PRJX2S_ARGS);
793 int airs2x(PRJS2X_ARGS);
794
795 int cypset(struct prjprm *prj);
796 int cypx2s(PRJX2S_ARGS);
797 int cyps2x(PRJS2X_ARGS);
798
799 int ceaset(struct prjprm *prj);
800 int ceax2s(PRJX2S_ARGS);
801 int ceas2x(PRJS2X_ARGS);
802
803 int carset(struct prjprm *prj);
804 int carx2s(PRJX2S_ARGS);
805 int cars2x(PRJS2X_ARGS);
806
807 int merset(struct prjprm *prj);
808 int merx2s(PRJX2S_ARGS);
809 int mers2x(PRJS2X_ARGS);
810
811 int sflset(struct prjprm *prj);
812 int sflx2s(PRJX2S_ARGS);
813 int sfls2x(PRJS2X_ARGS);
814
815 int parset(struct prjprm *prj);
816 int parx2s(PRJX2S_ARGS);
817 int pars2x(PRJS2X_ARGS);
818
819 int molset(struct prjprm *prj);
820 int molx2s(PRJX2S_ARGS);
821 int mols2x(PRJS2X_ARGS);
822
823 int aitset(struct prjprm *prj);
824 int aitx2s(PRJX2S_ARGS);
825 int aits2x(PRJS2X_ARGS);
826
827 int copset(struct prjprm *prj);
828 int copx2s(PRJX2S_ARGS);
829 int cops2x(PRJS2X_ARGS);
830
831 int coeset(struct prjprm *prj);
832 int coex2s(PRJX2S_ARGS);
833 int coes2x(PRJS2X_ARGS);
834
835 int codset(struct prjprm *prj);
836 int codx2s(PRJX2S_ARGS);
837 int cods2x(PRJS2X_ARGS);
838
839 int cooset(struct prjprm *prj);
840 int coox2s(PRJX2S_ARGS);
841 int coos2x(PRJS2X_ARGS);
842
843 int bonset(struct prjprm *prj);
844 int bonx2s(PRJX2S_ARGS);
845 int bons2x(PRJS2X_ARGS);
846
847 int pcoset(struct prjprm *prj);
848 int pcox2s(PRJX2S_ARGS);
849 int pcos2x(PRJS2X_ARGS);
850
851 int tscset(struct prjprm *prj);
852 int tscx2s(PRJX2S_ARGS);
853 int tscs2x(PRJS2X_ARGS);
854
855 int cscset(struct prjprm *prj);
856 int cscx2s(PRJX2S_ARGS);
857 int cscs2x(PRJS2X_ARGS);
858
859 int qscset(struct prjprm *prj);
860 int qscx2s(PRJX2S_ARGS);
861 int qscs2x(PRJS2X_ARGS);
862
863 int hpxset(struct prjprm *prj);
864 int hpxx2s(PRJX2S_ARGS);
865 int hpxs2x(PRJS2X_ARGS);
866
867 int xphset(struct prjprm *prj);
868 int xphx2s(PRJX2S_ARGS);
869 int xphs2x(PRJS2X_ARGS);
870
871
872 // Deprecated.
873 #define prjini_errmsg prj_errmsg
874 #define prjprt_errmsg prj_errmsg
875 #define prjset_errmsg prj_errmsg
876 #define prjx2s_errmsg prj_errmsg
877 #define prjs2x_errmsg prj_errmsg
878
879 #ifdef __cplusplus
880 }
881 #endif
882
883 #endif // WCSLIB_PROJ
Browse
Usage
Versions