WCSLIB  7.3.1
prj.h
Go to the documentation of this file.
1 /*============================================================================
2  WCSLIB 7.3 - an implementation of the FITS WCS standard.
3  Copyright (C) 1995-2020, 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  Direct correspondence concerning WCSLIB to mark@calabretta.id.au
21 
22  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
23  http://www.atnf.csiro.au/people/Mark.Calabretta
24  $Id: prj.h,v 7.3.1.2 2020/08/17 11:19:09 mcalabre Exp mcalabre $
25 *=============================================================================
26 *
27 * WCSLIB 7.3 - C routines that implement the FITS World Coordinate System
28 * (WCS) standard. Refer to the README file provided with WCSLIB for an
29 * overview of the library.
30 *
31 *
32 * Summary of the prj routines
33 * ---------------------------
34 * Routines in this suite implement the spherical map projections defined by
35 * the FITS World Coordinate System (WCS) standard, as described in
36 *
37 = "Representations of world coordinates in FITS",
38 = Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
39 =
40 = "Representations of celestial coordinates in FITS",
41 = Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (WCS Paper II)
42 =
43 = "Mapping on the HEALPix grid",
44 = Calabretta, M.R., & Roukema, B.F. 2007, MNRAS, 381, 865 (WCS Paper V)
45 =
46 = "Representing the 'Butterfly' Projection in FITS -- Projection Code XPH",
47 = Calabretta, M.R., & Lowe, S.R. 2013, PASA, 30, e050 (WCS Paper VI)
48 *
49 * These routines are based on the prjprm struct which contains all information
50 * needed for the computations. The struct contains some members that must be
51 * set by the user, and others that are maintained by these routines, somewhat
52 * like a C++ class but with no encapsulation.
53 *
54 * Routine prjini() is provided to initialize the prjprm struct with default
55 * values, prjfree() reclaims any memory that may have been allocated to store
56 * an error message, and prjprt() prints its contents.
57 *
58 * prjperr() prints the error message(s) (if any) stored in a prjprm struct.
59 * prjbchk() performs bounds checking on native spherical coordinates.
60 *
61 * Setup routines for each projection with names of the form ???set(), where
62 * "???" is the down-cased three-letter projection code, compute intermediate
63 * values in the prjprm struct from parameters in it that were supplied by the
64 * user. The struct always needs to be set by the projection's setup routine
65 * but that need not be called explicitly - refer to the explanation of
66 * prjprm::flag.
67 *
68 * Each map projection is implemented via separate functions for the spherical
69 * projection, ???s2x(), and deprojection, ???x2s().
70 *
71 * A set of driver routines, prjset(), prjx2s(), and prjs2x(), provides a
72 * generic interface to the specific projection routines which they invoke
73 * via pointers-to-functions stored in the prjprm struct.
74 *
75 * In summary, the routines are:
76 * - prjini() Initialization routine for the prjprm struct.
77 * - prjfree() Reclaim memory allocated for error messages.
78 * - prjprt() Print the 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 * prjprt() - Print routine for the prjprm struct
187 * ----------------------------------------------
188 * prjprt() prints the contents of a prjprm struct using wcsprintf(). Mainly
189 * intended for diagnostic purposes.
190 *
191 * Given:
192 * prj const struct prjprm*
193 * Projection parameters.
194 *
195 * Function return value:
196 * int Status return value:
197 * 0: Success.
198 * 1: Null prjprm pointer passed.
199 *
200 *
201 * prjperr() - Print error messages from a prjprm struct
202 * -----------------------------------------------------
203 * prjperr() prints the error message(s) (if any) stored in a prjprm struct.
204 * If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.
205 *
206 * Given:
207 * prj const struct prjprm*
208 * Projection parameters.
209 *
210 * prefix const char *
211 * If non-NULL, each output line will be prefixed with
212 * this string.
213 *
214 * Function return value:
215 * int Status return value:
216 * 0: Success.
217 * 1: Null prjprm pointer passed.
218 *
219 *
220 * prjbchk() - Bounds checking on native coordinates
221 * -------------------------------------------------
222 * prjbchk() performs bounds checking on native spherical coordinates. As
223 * returned by the deprojection (x2s) routines, native longitude is expected
224 * to lie in the closed interval [-180,180], with latitude in [-90,90].
225 *
226 * A tolerance may be specified to provide a small allowance for numerical
227 * imprecision. Values that lie outside the allowed range by not more than
228 * the specified tolerance will be adjusted back into range.
229 *
230 * If prjprm::bounds&4 is set, as it is by prjini(), then prjbchk() will be
231 * invoked automatically by the Cartesian-to-spherical deprojection (x2s)
232 * routines with an appropriate tolerance set for each projection.
233 *
234 * Given:
235 * tol double Tolerance for the bounds check [deg].
236 *
237 * nphi,
238 * ntheta int Vector lengths.
239 *
240 * spt int Vector stride.
241 *
242 * Given and returned:
243 * phi,theta double[] Native longitude and latitude (phi,theta) [deg].
244 *
245 * Returned:
246 * stat int[] Status value for each vector element:
247 * 0: Valid value of (phi,theta).
248 * 1: Invalid value.
249 *
250 * Function return value:
251 * int Status return value:
252 * 0: Success.
253 * 1: One or more of the (phi,theta) coordinates
254 * were, invalid, as indicated by the stat vector.
255 *
256 *
257 * prjset() - Generic setup routine for the prjprm struct
258 * ------------------------------------------------------
259 * prjset() sets up a prjprm struct according to information supplied within
260 * it.
261 *
262 * Note that this routine need not be called directly; it will be invoked by
263 * prjx2s() and prjs2x() if prj.flag is anything other than a predefined magic
264 * value.
265 *
266 * The one important distinction between prjset() and the setup routines for
267 * the specific projections is that the projection code must be defined in the
268 * prjprm struct in order for prjset() to identify the required projection.
269 * Once prjset() has initialized the prjprm struct, prjx2s() and prjs2x() use
270 * the pointers to the specific projection and deprojection routines contained
271 * therein.
272 *
273 * Given and returned:
274 * prj struct prjprm*
275 * Projection parameters.
276 *
277 * Function return value:
278 * int Status return value:
279 * 0: Success.
280 * 1: Null prjprm pointer passed.
281 * 2: Invalid projection parameters.
282 *
283 * For returns > 1, a detailed error message is set in
284 * prjprm::err if enabled, see wcserr_enable().
285 *
286 *
287 * prjx2s() - Generic Cartesian-to-spherical deprojection
288 * ------------------------------------------------------
289 * Deproject Cartesian (x,y) coordinates in the plane of projection to native
290 * spherical coordinates (phi,theta).
291 *
292 * The projection is that specified by prjprm::code.
293 *
294 * Given and returned:
295 * prj struct prjprm*
296 * Projection parameters.
297 *
298 * Given:
299 * nx,ny int Vector lengths.
300 *
301 * sxy,spt int Vector strides.
302 *
303 * x,y const double[]
304 * Projected coordinates.
305 *
306 * Returned:
307 * phi,theta double[] Longitude and latitude (phi,theta) of the projected
308 * point in native spherical coordinates [deg].
309 *
310 * stat int[] Status value for each vector element:
311 * 0: Success.
312 * 1: Invalid value of (x,y).
313 *
314 * Function return value:
315 * int Status return value:
316 * 0: Success.
317 * 1: Null prjprm pointer passed.
318 * 2: Invalid projection parameters.
319 * 3: One or more of the (x,y) coordinates were
320 * invalid, as indicated by the stat vector.
321 *
322 * For returns > 1, a detailed error message is set in
323 * prjprm::err if enabled, see wcserr_enable().
324 *
325 *
326 * prjs2x() - Generic spherical-to-Cartesian projection
327 * ----------------------------------------------------
328 * Project native spherical coordinates (phi,theta) to Cartesian (x,y)
329 * coordinates in the plane of projection.
330 *
331 * The projection is that specified by prjprm::code.
332 *
333 * Given and returned:
334 * prj struct prjprm*
335 * Projection parameters.
336 *
337 * Given:
338 * nphi,
339 * ntheta int Vector lengths.
340 *
341 * spt,sxy int Vector strides.
342 *
343 * phi,theta const double[]
344 * Longitude and latitude (phi,theta) of the projected
345 * point in native spherical coordinates [deg].
346 *
347 * Returned:
348 * x,y double[] Projected coordinates.
349 *
350 * stat int[] Status value for each vector element:
351 * 0: Success.
352 * 1: Invalid value of (phi,theta).
353 *
354 * Function return value:
355 * int Status return value:
356 * 0: Success.
357 * 1: Null prjprm pointer passed.
358 * 2: Invalid projection parameters.
359 * 4: One or more of the (phi,theta) coordinates
360 * were, invalid, as indicated by the stat vector.
361 *
362 * For returns > 1, a detailed error message is set in
363 * prjprm::err if enabled, see wcserr_enable().
364 *
365 *
366 * ???set() - Specific setup routines for the prjprm struct
367 * --------------------------------------------------------
368 * Set up a prjprm struct for a particular projection according to information
369 * supplied within it.
370 *
371 * Given and returned:
372 * prj struct prjprm*
373 * Projection parameters.
374 *
375 * Function return value:
376 * int Status return value:
377 * 0: Success.
378 * 1: Null prjprm pointer passed.
379 * 2: Invalid projection parameters.
380 *
381 * For returns > 1, a detailed error message is set in
382 * prjprm::err if enabled, see wcserr_enable().
383 *
384 *
385 * ???x2s() - Specific Cartesian-to-spherical deprojection routines
386 * ----------------------------------------------------------------
387 * Transform (x,y) coordinates in the plane of projection to native spherical
388 * coordinates (phi,theta).
389 *
390 * Given and returned:
391 * prj struct prjprm*
392 * Projection parameters.
393 *
394 * Given:
395 * nx,ny int Vector lengths.
396 *
397 * sxy,spt int Vector strides.
398 *
399 * x,y const double[]
400 * Projected coordinates.
401 *
402 * Returned:
403 * phi,theta double[] Longitude and latitude of the projected point in
404 * native spherical coordinates [deg].
405 *
406 * stat int[] Status value for each vector element:
407 * 0: Success.
408 * 1: Invalid value of (x,y).
409 *
410 * Function return value:
411 * int Status return value:
412 * 0: Success.
413 * 1: Null prjprm pointer passed.
414 * 2: Invalid projection parameters.
415 * 3: One or more of the (x,y) coordinates were
416 * invalid, as indicated by the stat vector.
417 *
418 * For returns > 1, a detailed error message is set in
419 * prjprm::err if enabled, see wcserr_enable().
420 *
421 *
422 * ???s2x() - Specific spherical-to-Cartesian projection routines
423 *---------------------------------------------------------------
424 * Transform native spherical coordinates (phi,theta) to (x,y) coordinates in
425 * the plane of projection.
426 *
427 * Given and returned:
428 * prj struct prjprm*
429 * Projection parameters.
430 *
431 * Given:
432 * nphi,
433 * ntheta int Vector lengths.
434 *
435 * spt,sxy int Vector strides.
436 *
437 * phi,theta const double[]
438 * Longitude and latitude of the projected point in
439 * native spherical coordinates [deg].
440 *
441 * Returned:
442 * x,y double[] Projected coordinates.
443 *
444 * stat int[] Status value for each vector element:
445 * 0: Success.
446 * 1: Invalid value of (phi,theta).
447 *
448 * Function return value:
449 * int Status return value:
450 * 0: Success.
451 * 1: Null prjprm pointer passed.
452 * 2: Invalid projection parameters.
453 * 4: One or more of the (phi,theta) coordinates
454 * were, invalid, as indicated by the stat vector.
455 *
456 * For returns > 1, a detailed error message is set in
457 * prjprm::err if enabled, see wcserr_enable().
458 *
459 *
460 * prjprm struct - Projection parameters
461 * -------------------------------------
462 * The prjprm struct contains all information needed to project or deproject
463 * native spherical coordinates. It consists of certain members that must be
464 * set by the user ("given") and others that are set by the WCSLIB routines
465 * ("returned"). Some of the latter are supplied for informational purposes
466 * while others are for internal use only.
467 *
468 * int flag
469 * (Given and returned) This flag must be set to zero whenever any of the
470 * following prjprm struct members are set or changed:
471 *
472 * - prjprm::code,
473 * - prjprm::r0,
474 * - prjprm::pv[],
475 * - prjprm::phi0,
476 * - prjprm::theta0.
477 *
478 * This signals the initialization routine (prjset() or ???set()) to
479 * recompute the returned members of the prjprm struct. flag will then be
480 * reset to indicate that this has been done.
481 *
482 * Note that flag need not be reset when prjprm::bounds is changed.
483 *
484 * char code[4]
485 * (Given) Three-letter projection code defined by the FITS standard.
486 *
487 * double r0
488 * (Given) The radius of the generating sphere for the projection, a linear
489 * scaling parameter. If this is zero, it will be reset to its default
490 * value of 180/pi (the value for FITS WCS).
491 *
492 * double pv[30]
493 * (Given) Projection parameters. These correspond to the PVi_ma keywords
494 * in FITS, so pv[0] is PVi_0a, pv[1] is PVi_1a, etc., where i denotes the
495 * latitude-like axis. Many projections use pv[1] (PVi_1a), some also use
496 * pv[2] (PVi_2a) and SZP uses pv[3] (PVi_3a). ZPN is currently the only
497 * projection that uses any of the others.
498 *
499 * Usage of the pv[] array as it applies to each projection is described in
500 * the prologue to each trio of projection routines in prj.c.
501 *
502 * double phi0
503 * (Given) The native longitude, phi_0 [deg], and ...
504 * double theta0
505 * (Given) ... the native latitude, theta_0 [deg], of the reference point,
506 * i.e. the point (x,y) = (0,0). If undefined (set to a magic value by
507 * prjini()) the initialization routine will set this to a
508 * projection-specific default.
509 *
510 * int bounds
511 * (Given) Controls bounds checking. If bounds&1 then enable strict bounds
512 * checking for the spherical-to-Cartesian (s2x) transformation for the
513 * AZP, SZP, TAN, SIN, ZPN, and COP projections. If bounds&2 then enable
514 * strict bounds checking for the Cartesian-to-spherical transformation
515 * (x2s) for the HPX and XPH projections. If bounds&4 then the Cartesian-
516 * to-spherical transformations (x2s) will invoke prjbchk() to perform
517 * bounds checking on the computed native coordinates, with a tolerance set
518 * to suit each projection. bounds is set to 7 by prjini() by default
519 * which enables all checks. Zero it to disable all checking.
520 *
521 * It is not necessary to reset the prjprm struct (via prjset() or
522 * ???set()) when prjprm::bounds is changed.
523 *
524 * The remaining members of the prjprm struct are maintained by the setup
525 * routines and must not be modified elsewhere:
526 *
527 * char name[40]
528 * (Returned) Long name of the projection.
529 *
530 * Provided for information only, not used by the projection routines.
531 *
532 * int category
533 * (Returned) Projection category matching the value of the relevant global
534 * variable:
535 *
536 * - ZENITHAL,
537 * - CYLINDRICAL,
538 * - PSEUDOCYLINDRICAL,
539 * - CONVENTIONAL,
540 * - CONIC,
541 * - POLYCONIC,
542 * - QUADCUBE, and
543 * - HEALPIX.
544 *
545 * The category name may be identified via the prj_categories character
546 * array, e.g.
547 *
548 = struct prjprm prj;
549 = ...
550 = printf("%s\n", prj_categories[prj.category]);
551 *
552 * Provided for information only, not used by the projection routines.
553 *
554 * int pvrange
555 * (Returned) Range of projection parameter indices: 100 times the first
556 * allowed index plus the number of parameters, e.g. TAN is 0 (no
557 * parameters), SZP is 103 (1 to 3), and ZPN is 30 (0 to 29).
558 *
559 * Provided for information only, not used by the projection routines.
560 *
561 * int simplezen
562 * (Returned) True if the projection is a radially-symmetric zenithal
563 * projection.
564 *
565 * Provided for information only, not used by the projection routines.
566 *
567 * int equiareal
568 * (Returned) True if the projection is equal area.
569 *
570 * Provided for information only, not used by the projection routines.
571 *
572 * int conformal
573 * (Returned) True if the projection is conformal.
574 *
575 * Provided for information only, not used by the projection routines.
576 *
577 * int global
578 * (Returned) True if the projection can represent the whole sphere in a
579 * finite, non-overlapped mapping.
580 *
581 * Provided for information only, not used by the projection routines.
582 *
583 * int divergent
584 * (Returned) True if the projection diverges in latitude.
585 *
586 * Provided for information only, not used by the projection routines.
587 *
588 * double x0
589 * (Returned) The offset in x, and ...
590 * double y0
591 * (Returned) ... the offset in y used to force (x,y) = (0,0) at
592 * (phi_0,theta_0).
593 *
594 * struct wcserr *err
595 * (Returned) If enabled, when an error status is returned, this struct
596 * contains detailed information about the error, see wcserr_enable().
597 *
598 * void *padding
599 * (An unused variable inserted for alignment purposes only.)
600 *
601 * double w[10]
602 * (Returned) Intermediate floating-point values derived from the
603 * projection parameters, cached here to save recomputation.
604 *
605 * Usage of the w[] array as it applies to each projection is described in
606 * the prologue to each trio of projection routines in prj.c.
607 *
608 * int n
609 * (Returned) Intermediate integer value (used only for the ZPN and HPX
610 * projections).
611 *
612 * int (*prjx2s)(PRJX2S_ARGS)
613 * (Returned) Pointer to the spherical projection ...
614 * int (*prjs2x)(PRJ_ARGS)
615 * (Returned) ... and deprojection routines.
616 *
617 *
618 * Global variable: const char *prj_errmsg[] - Status return messages
619 * ------------------------------------------------------------------
620 * Error messages to match the status value returned from each function.
621 *
622 *===========================================================================*/
623 
624 #ifndef WCSLIB_PROJ
625 #define WCSLIB_PROJ
626 
627 #ifdef __cplusplus
628 extern "C" {
629 #endif
630 
631 
632 // Total number of projection parameters; 0 to PVN-1.
633 #define PVN 30
634 
635 extern const char *prj_errmsg[];
636 
638  PRJERR_SUCCESS = 0, // Success.
639  PRJERR_NULL_POINTER = 1, // Null prjprm pointer passed.
640  PRJERR_BAD_PARAM = 2, // Invalid projection parameters.
641  PRJERR_BAD_PIX = 3, // One or more of the (x, y) coordinates were
642  // invalid.
643  PRJERR_BAD_WORLD = 4 // One or more of the (phi, theta) coordinates
644  // were invalid.
645 };
646 
649 extern const char prj_categories[9][32];
650 
651 extern const int prj_ncode;
652 extern const char prj_codes[28][4];
653 
654 #ifdef PRJX2S_ARGS
655 #undef PRJX2S_ARGS
656 #endif
657 
658 #ifdef PRJS2X_ARGS
659 #undef PRJS2X_ARGS
660 #endif
661 
662 // For use in declaring deprojection function prototypes.
663 #define PRJX2S_ARGS struct prjprm *prj, int nx, int ny, int sxy, int spt, \
664 const double x[], const double y[], double phi[], double theta[], int stat[]
665 
666 // For use in declaring projection function prototypes.
667 #define PRJS2X_ARGS struct prjprm *prj, int nx, int ny, int sxy, int spt, \
668 const double phi[], const double theta[], double x[], double y[], int stat[]
669 
670 
671 struct prjprm {
672  // Initialization flag (see the prologue above).
673  //--------------------------------------------------------------------------
674  int flag; // Set to zero to force initialization.
675 
676  // Parameters to be provided (see the prologue above).
677  //--------------------------------------------------------------------------
678  char code[4]; // Three-letter projection code.
679  double r0; // Radius of the generating sphere.
680  double pv[PVN]; // Projection parameters.
681  double phi0, theta0; // Fiducial native coordinates.
682  int bounds; // Controls bounds checking.
683 
684  // Information derived from the parameters supplied.
685  //--------------------------------------------------------------------------
686  char name[40]; // Projection name.
687  int category; // Projection category.
688  int pvrange; // Range of projection parameter indices.
689  int simplezen; // Is it a simple zenithal projection?
690  int equiareal; // Is it an equal area projection?
691  int conformal; // Is it a conformal projection?
692  int global; // Can it map the whole sphere?
693  int divergent; // Does the projection diverge in latitude?
694  double x0, y0; // Fiducial offsets.
695 
696  // Error handling
697  //--------------------------------------------------------------------------
698  struct wcserr *err;
699 
700  // Private
701  //--------------------------------------------------------------------------
702  void *padding; // (Dummy inserted for alignment purposes.)
703  double w[10]; // Intermediate values.
704  int m, n; // Intermediate values.
705 
706  int (*prjx2s)(PRJX2S_ARGS); // Pointers to the spherical projection and
707  int (*prjs2x)(PRJS2X_ARGS); // deprojection functions.
708 };
709 
710 // Size of the prjprm struct in int units, used by the Fortran wrappers.
711 #define PRJLEN (sizeof(struct prjprm)/sizeof(int))
712 
713 
714 // Use the preprocessor to help declare function prototypes (see above).
715 int prjini(struct prjprm *prj);
716 int prjfree(struct prjprm *prj);
717 int prjprt(const struct prjprm *prj);
718 int prjperr(const struct prjprm *prj, const char *prefix);
719 int prjbchk(double tol, int nphi, int ntheta, int spt, double phi[],
720  double theta[], int stat[]);
721 
722 int prjset(struct prjprm *prj);
725 
726 int azpset(struct prjprm *prj);
729 
730 int szpset(struct prjprm *prj);
733 
734 int tanset(struct prjprm *prj);
737 
738 int stgset(struct prjprm *prj);
741 
742 int sinset(struct prjprm *prj);
745 
746 int arcset(struct prjprm *prj);
749 
750 int zpnset(struct prjprm *prj);
753 
754 int zeaset(struct prjprm *prj);
757 
758 int airset(struct prjprm *prj);
761 
762 int cypset(struct prjprm *prj);
765 
766 int ceaset(struct prjprm *prj);
769 
770 int carset(struct prjprm *prj);
773 
774 int merset(struct prjprm *prj);
777 
778 int sflset(struct prjprm *prj);
781 
782 int parset(struct prjprm *prj);
785 
786 int molset(struct prjprm *prj);
789 
790 int aitset(struct prjprm *prj);
793 
794 int copset(struct prjprm *prj);
797 
798 int coeset(struct prjprm *prj);
801 
802 int codset(struct prjprm *prj);
805 
806 int cooset(struct prjprm *prj);
809 
810 int bonset(struct prjprm *prj);
813 
814 int pcoset(struct prjprm *prj);
817 
818 int tscset(struct prjprm *prj);
821 
822 int cscset(struct prjprm *prj);
825 
826 int qscset(struct prjprm *prj);
829 
830 int hpxset(struct prjprm *prj);
833 
834 int xphset(struct prjprm *prj);
837 
838 
839 // Deprecated.
840 #define prjini_errmsg prj_errmsg
841 #define prjprt_errmsg prj_errmsg
842 #define prjset_errmsg prj_errmsg
843 #define prjx2s_errmsg prj_errmsg
844 #define prjs2x_errmsg prj_errmsg
845 
846 #ifdef __cplusplus
847 }
848 #endif
849 
850 #endif // WCSLIB_PROJ
cops2x
int cops2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the conic perspective (COP) projection.
coox2s
int coox2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the conic orthomorphic (COO) projection.
szpx2s
int szpx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the slant zenithal perspective (SZP) projection.
hpxx2s
int hpxx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the HEALPix (HPX) projection.
hpxset
int hpxset(struct prjprm *prj)
Set up a prjprm struct for the HEALPix (HPX) projection.
cods2x
int cods2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the conic equidistant (COD) projection.
prjprm::category
int category
Definition: prj.h:687
zeaset
int zeaset(struct prjprm *prj)
Set up a prjprm struct for the zenithal/azimuthal equal area (ZEA) projection.
merset
int merset(struct prjprm *prj)
Set up a prjprm struct for Mercator's (MER) projection.
prjprm::padding
void * padding
Definition: prj.h:702
prjini
int prjini(struct prjprm *prj)
Default constructor for the prjprm struct.
stgset
int stgset(struct prjprm *prj)
Set up a prjprm struct for the stereographic (STG) projection.
prjprm::phi0
double phi0
Definition: prj.h:681
aitx2s
int aitx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the Hammer-Aitoff (AIT) projection.
prj_codes
const char prj_codes[28][4]
Recognized three-letter projection codes.
molx2s
int molx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for Mollweide's (MOL) projection.
sinset
int sinset(struct prjprm *prj)
Set up a prjprm struct for the orthographic/synthesis (SIN) projection.
cscs2x
int cscs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the COBE spherical cube (CSC) projection.
prjprm::global
int global
Definition: prj.h:692
cooset
int cooset(struct prjprm *prj)
Set up a prjprm struct for the conic orthomorphic (COO) projection.
parset
int parset(struct prjprm *prj)
Set up a prjprm struct for the parabolic (PAR) projection.
carset
int carset(struct prjprm *prj)
Set up a prjprm struct for the plate carrée (CAR) projection.
prjprt
int prjprt(const struct prjprm *prj)
Print routine for the prjprm struct.
prjprm::m
int m
Definition: prj.h:704
prjperr
int prjperr(const struct prjprm *prj, const char *prefix)
Print error messages from a prjprm struct.
zpnx2s
int zpnx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the zenithal/azimuthal polynomial (ZPN) projection.
bons2x
int bons2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for Bonne's (BON) projection.
CONIC
const int CONIC
Identifier for conic projections.
copset
int copset(struct prjprm *prj)
Set up a prjprm struct for the conic perspective (COP) projection.
airx2s
int airx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for Airy's (AIR) projection.
POLYCONIC
const int POLYCONIC
Identifier for polyconic projections.
Definition: prj.h:647
tanx2s
int tanx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the gnomonic (TAN) projection.
prjprm::conformal
int conformal
Definition: prj.h:691
QUADCUBE
const int QUADCUBE
Identifier for quadcube projections.
Definition: prj.h:648
xphset
int xphset(struct prjprm *prj)
hpxs2x
int hpxs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the HEALPix (HPX) projection.
cscset
int cscset(struct prjprm *prj)
Set up a prjprm struct for the COBE spherical cube (CSC) projection.
sins2x
int sins2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the orthographic/synthesis (SIN) projection.
PRJERR_BAD_PARAM
@ PRJERR_BAD_PARAM
Definition: prj.h:640
prjprm::bounds
int bounds
Definition: prj.h:682
coos2x
int coos2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the conic orthomorphic (COO) projection.
tscs2x
int tscs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the tangential spherical cube (TSC) projection.
prjprm
Projection parameters.
Definition: prj.h:671
coeset
int coeset(struct prjprm *prj)
Set up a prjprm struct for the conic equal area (COE) projection.
azpset
int azpset(struct prjprm *prj)
Set up a prjprm struct for the zenithal/azimuthal perspective (AZP) projection.
sfls2x
int sfls2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the Sanson-Flamsteed (SFL) projection.
PRJERR_BAD_WORLD
@ PRJERR_BAD_WORLD
Definition: prj.h:643
tscx2s
int tscx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the tangential spherical cube (TSC) projection.
ceas2x
int ceas2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the cylindrical equal area (CEA) projection.
zpns2x
int zpns2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the zenithal/azimuthal polynomial (ZPN) projection.
prj_ncode
const int prj_ncode
The number of recognized three-letter projection codes.
cscx2s
int cscx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the COBE spherical cube (CSC) projection.
pcox2s
int pcox2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the polyconic (PCO) projection.
szps2x
int szps2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the slant zenithal perspective (SZP) projection.
arcx2s
int arcx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the zenithal/azimuthal equidistant (ARC) projection.
copx2s
int copx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the conic perspective (COP) projection.
codset
int codset(struct prjprm *prj)
Set up a prjprm struct for the conic equidistant (COD) projection.
zpnset
int zpnset(struct prjprm *prj)
Set up a prjprm struct for the zenithal/azimuthal polynomial (ZPN) projection.
carx2s
int carx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the plate carrée (CAR) projection.
prjprm::name
char name[40]
Definition: prj.h:686
azpx2s
int azpx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the zenithal/azimuthal perspective (AZP) projection.
prj_errmsg
const char * prj_errmsg[]
Status return messages.
mols2x
int mols2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for Mollweide's (MOL) projection.
stgx2s
int stgx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the stereographic (STG) projection.
zeas2x
int zeas2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the zenithal/azimuthal equal area (ZEA) projection.
prj_errmsg_enum
prj_errmsg_enum
Definition: prj.h:637
cyps2x
int cyps2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the cylindrical perspective (CYP) projection.
ZENITHAL
const int ZENITHAL
Identifier for zenithal/azimuthal projections.
Definition: prj.h:648
arcset
int arcset(struct prjprm *prj)
Set up a prjprm struct for the zenithal/azimuthal equidistant (ARC) projection.
PRJERR_NULL_POINTER
@ PRJERR_NULL_POINTER
Definition: prj.h:639
CONVENTIONAL
const int CONVENTIONAL
Identifier for conventional projections.
Definition: prj.h:647
merx2s
int merx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for Mercator's (MER) projection.
prjprm::r0
double r0
Definition: prj.h:679
stgs2x
int stgs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the stereographic (STG) projection.
PSEUDOCYLINDRICAL
const int PSEUDOCYLINDRICAL
Identifier for pseudocylindrical projections.
Definition: prj.h:648
prjprm::pv
double pv[PVN]
Definition: prj.h:680
tscset
int tscset(struct prjprm *prj)
Set up a prjprm struct for the tangential spherical cube (TSC) projection.
prjprm::prjx2s
int(* prjx2s)(PRJX2S_ARGS)
Definition: prj.h:706
prjprm::theta0
double theta0
Definition: prj.h:681
xphs2x
int xphs2x(PRJS2X_ARGS)
prjprm::divergent
int divergent
Definition: prj.h:693
coes2x
int coes2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the conic equal area (COE) projection.
pcoset
int pcoset(struct prjprm *prj)
Set up a prjprm struct for the polyconic (PCO) projection.
prjprm::code
char code[4]
Definition: prj.h:678
cypx2s
int cypx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the cylindrical perspective (CYP) projection.
sflset
int sflset(struct prjprm *prj)
Set up a prjprm struct for the Sanson-Flamsteed (SFL) projection.
xphx2s
int xphx2s(PRJX2S_ARGS)
sflx2s
int sflx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the Sanson-Flamsteed (SFL) projection.
prj_categories
const char prj_categories[9][32]
Projection categories.
PVN
#define PVN
Total number of projection parameters.
Definition: prj.h:633
prjprm::y0
double y0
Definition: prj.h:694
prjs2x
int prjs2x(PRJS2X_ARGS)
Generic spherical-to-Cartesian projection.
pcos2x
int pcos2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the polyconic (PCO) projection.
prjfree
int prjfree(struct prjprm *prj)
Destructor for the prjprm struct.
molset
int molset(struct prjprm *prj)
Set up a prjprm struct for Mollweide's (MOL) projection.
ceaset
int ceaset(struct prjprm *prj)
Set up a prjprm struct for the cylindrical equal area (CEA) projection.
prjset
int prjset(struct prjprm *prj)
Generic setup routine for the prjprm struct.
azps2x
int azps2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the zenithal/azimuthal perspective (AZP) projection.
HEALPIX
const int HEALPIX
Identifier for the HEALPix projection.
Definition: prj.h:648
airs2x
int airs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for Airy's (AIR) projection.
prjx2s
int prjx2s(PRJX2S_ARGS)
Generic Cartesian-to-spherical deprojection.
qscx2s
int qscx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the quadrilateralized spherical cube (QSC) projection.
coex2s
int coex2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the conic equal area (COE) projection.
aits2x
int aits2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the Hammer-Aitoff (AIT) projection.
mers2x
int mers2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for Mercator's (MER) projection.
zeax2s
int zeax2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the zenithal/azimuthal equal area (ZEA) projection.
codx2s
int codx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the conic equidistant (COD) projection.
prjprm::err
struct wcserr * err
Definition: prj.h:698
qscset
int qscset(struct prjprm *prj)
Set up a prjprm struct for the quadrilateralized spherical cube (QSC) projection.
PRJERR_BAD_PIX
@ PRJERR_BAD_PIX
Definition: prj.h:641
szpset
int szpset(struct prjprm *prj)
Set up a prjprm struct for the slant zenithal perspective (SZP) projection.
wcserr
Error message handling.
Definition: wcserr.h:222
prjprm::w
double w[10]
Definition: prj.h:703
prjprm::prjs2x
int(* prjs2x)(PRJS2X_ARGS)
Definition: prj.h:707
prjprm::n
int n
Definition: prj.h:704
PRJS2X_ARGS
#define PRJS2X_ARGS
For use in declaring projection function prototypes.
Definition: prj.h:667
CYLINDRICAL
const int CYLINDRICAL
Identifier for cylindrical projections.
Definition: prj.h:647
cars2x
int cars2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the plate carrée (CAR) projection.
bonx2s
int bonx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for Bonne's (BON) projection.
prjbchk
int prjbchk(double tol, int nphi, int ntheta, int spt, double phi[], double theta[], int stat[])
Bounds checking on native coordinates.
prjprm::equiareal
int equiareal
Definition: prj.h:690
tanset
int tanset(struct prjprm *prj)
Set up a prjprm struct for the gnomonic (TAN) projection.
prjprm::flag
int flag
Definition: prj.h:674
prjprm::x0
double x0
Definition: prj.h:694
prjprm::pvrange
int pvrange
Definition: prj.h:688
bonset
int bonset(struct prjprm *prj)
Set up a prjprm struct for Bonne's (BON) projection.
arcs2x
int arcs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the zenithal/azimuthal equidistant (ARC) projection.
aitset
int aitset(struct prjprm *prj)
Set up a prjprm struct for the Hammer-Aitoff (AIT) projection.
PRJX2S_ARGS
#define PRJX2S_ARGS
For use in declaring deprojection function prototypes.
Definition: prj.h:663
cypset
int cypset(struct prjprm *prj)
Set up a prjprm struct for the cylindrical perspective (CYP) projection.
tans2x
int tans2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the gnomonic (TAN) projection.
pars2x
int pars2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the parabolic (PAR) projection.
parx2s
int parx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the parabolic (PAR) projection.
PRJERR_SUCCESS
@ PRJERR_SUCCESS
Definition: prj.h:638
ceax2s
int ceax2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the cylindrical equal area (CEA) projection.
airset
int airset(struct prjprm *prj)
Set up a prjprm struct for Airy's (AIR) projection.
prjprm::simplezen
int simplezen
Definition: prj.h:689
sinx2s
int sinx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the orthographic/synthesis (SIN) projection.
qscs2x
int qscs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the quadrilateralized spherical cube (QSC) projection.