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