WCSLIB: prj.h Source File

WCSLIB 7.4

prj.h
Go to the documentation of this file.
1 /*============================================================================
2 WCSLIB 7.4 - 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.4 2021/01/31 02:24:51 mcalabre Exp $
23 *=============================================================================
24 *
25 * WCSLIB 7.4 - C routines that implement the FITS World Coordinate System
26 * (WCS) standard. Refer to the README file provided with WCSLIB for an
27 * overview of the library.
28 *
29 *
30 * Summary of the 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
635 enum prj_errmsg_enum {
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
645 extern const int CONIC, CONVENTIONAL, CYLINDRICAL, POLYCONIC,
646 PSEUDOCYLINDRICAL, QUADCUBE, ZENITHAL, HEALPIX;
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);
721 int prjx2s(PRJX2S_ARGS);
722 int prjs2x(PRJS2X_ARGS);
723
724 int azpset(struct prjprm *prj);
725 int azpx2s(PRJX2S_ARGS);
726 int azps2x(PRJS2X_ARGS);
727
728 int szpset(struct prjprm *prj);
729 int szpx2s(PRJX2S_ARGS);
730 int szps2x(PRJS2X_ARGS);
731
732 int tanset(struct prjprm *prj);
733 int tanx2s(PRJX2S_ARGS);
734 int tans2x(PRJS2X_ARGS);
735
736 int stgset(struct prjprm *prj);
737 int stgx2s(PRJX2S_ARGS);
738 int stgs2x(PRJS2X_ARGS);
739
740 int sinset(struct prjprm *prj);
741 int sinx2s(PRJX2S_ARGS);
742 int sins2x(PRJS2X_ARGS);
743
744 int arcset(struct prjprm *prj);
745 int arcx2s(PRJX2S_ARGS);
746 int arcs2x(PRJS2X_ARGS);
747
748 int zpnset(struct prjprm *prj);
749 int zpnx2s(PRJX2S_ARGS);
750 int zpns2x(PRJS2X_ARGS);
751
752 int zeaset(struct prjprm *prj);
753 int zeax2s(PRJX2S_ARGS);
754 int zeas2x(PRJS2X_ARGS);
755
756 int airset(struct prjprm *prj);
757 int airx2s(PRJX2S_ARGS);
758 int airs2x(PRJS2X_ARGS);
759
760 int cypset(struct prjprm *prj);
761 int cypx2s(PRJX2S_ARGS);
762 int cyps2x(PRJS2X_ARGS);
763
764 int ceaset(struct prjprm *prj);
765 int ceax2s(PRJX2S_ARGS);
766 int ceas2x(PRJS2X_ARGS);
767
768 int carset(struct prjprm *prj);
769 int carx2s(PRJX2S_ARGS);
770 int cars2x(PRJS2X_ARGS);
771
772 int merset(struct prjprm *prj);
773 int merx2s(PRJX2S_ARGS);
774 int mers2x(PRJS2X_ARGS);
775
776 int sflset(struct prjprm *prj);
777 int sflx2s(PRJX2S_ARGS);
778 int sfls2x(PRJS2X_ARGS);
779
780 int parset(struct prjprm *prj);
781 int parx2s(PRJX2S_ARGS);
782 int pars2x(PRJS2X_ARGS);
783
784 int molset(struct prjprm *prj);
785 int molx2s(PRJX2S_ARGS);
786 int mols2x(PRJS2X_ARGS);
787
788 int aitset(struct prjprm *prj);
789 int aitx2s(PRJX2S_ARGS);
790 int aits2x(PRJS2X_ARGS);
791
792 int copset(struct prjprm *prj);
793 int copx2s(PRJX2S_ARGS);
794 int cops2x(PRJS2X_ARGS);
795
796 int coeset(struct prjprm *prj);
797 int coex2s(PRJX2S_ARGS);
798 int coes2x(PRJS2X_ARGS);
799
800 int codset(struct prjprm *prj);
801 int codx2s(PRJX2S_ARGS);
802 int cods2x(PRJS2X_ARGS);
803
804 int cooset(struct prjprm *prj);
805 int coox2s(PRJX2S_ARGS);
806 int coos2x(PRJS2X_ARGS);
807
808 int bonset(struct prjprm *prj);
809 int bonx2s(PRJX2S_ARGS);
810 int bons2x(PRJS2X_ARGS);
811
812 int pcoset(struct prjprm *prj);
813 int pcox2s(PRJX2S_ARGS);
814 int pcos2x(PRJS2X_ARGS);
815
816 int tscset(struct prjprm *prj);
817 int tscx2s(PRJX2S_ARGS);
818 int tscs2x(PRJS2X_ARGS);
819
820 int cscset(struct prjprm *prj);
821 int cscx2s(PRJX2S_ARGS);
822 int cscs2x(PRJS2X_ARGS);
823
824 int qscset(struct prjprm *prj);
825 int qscx2s(PRJX2S_ARGS);
826 int qscs2x(PRJS2X_ARGS);
827
828 int hpxset(struct prjprm *prj);
829 int hpxx2s(PRJX2S_ARGS);
830 int hpxs2x(PRJS2X_ARGS);
831
832 int xphset(struct prjprm *prj);
833 int xphx2s(PRJX2S_ARGS);
834 int xphs2x(PRJS2X_ARGS);
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
airset
int airset(struct prjprm *prj)
Set up a prjprm struct for Airy's (AIR) projection.
codx2s
int codx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the conic equidistant (COD) projection.
cyps2x
int cyps2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the cylindrical perspective (CYP) projection.
molset
int molset(struct prjprm *prj)
Set up a prjprm struct for Mollweide's (MOL) projection.
tscs2x
int tscs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the tangential spherical cube (TSC) projection.
parx2s
int parx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the parabolic (PAR) projection.
pcos2x
int pcos2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the polyconic (PCO) projection.
pcox2s
int pcox2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the polyconic (PCO) projection.
ceas2x
int ceas2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the cylindrical equal area (CEA) projection.
prj_errmsg_enum
prj_errmsg_enum
Definition: prj.h:635
PRJERR_BAD_WORLD
@ PRJERR_BAD_WORLD
Definition: prj.h:641
PRJERR_NULL_POINTER
@ PRJERR_NULL_POINTER
Definition: prj.h:637
PRJERR_BAD_PARAM
@ PRJERR_BAD_PARAM
Definition: prj.h:638
PRJERR_SUCCESS
@ PRJERR_SUCCESS
Definition: prj.h:636
PRJERR_BAD_PIX
@ PRJERR_BAD_PIX
Definition: prj.h:639
airx2s
int airx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for Airy's (AIR) projection.
prj_ncode
const int prj_ncode
The number of recognized three-letter projection codes.
aitx2s
int aitx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the Hammer-Aitoff (AIT) 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.
sflx2s
int sflx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the Sanson-Flamsteed (SFL) projection.
zeaset
int zeaset(struct prjprm *prj)
Set up a prjprm struct for the zenithal/azimuthal equal area (ZEA) projection.
aitset
int aitset(struct prjprm *prj)
Set up a prjprm struct for the Hammer-Aitoff (AIT) projection.
cooset
int cooset(struct prjprm *prj)
Set up a prjprm struct for the conic orthomorphic (COO) projection.
tanset
int tanset(struct prjprm *prj)
Set up a prjprm struct for the gnomonic (TAN) projection.
carset
int carset(struct prjprm *prj)
Set up a prjprm struct for the plate carrée (CAR) projection.
cypset
int cypset(struct prjprm *prj)
Set up a prjprm struct for the cylindrical perspective (CYP) projection.
PRJX2S_ARGS
#define PRJX2S_ARGS
For use in declaring deprojection function prototypes.
Definition: prj.h:661
bons2x
int bons2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for Bonne's (BON) projection.
ZENITHAL
const int ZENITHAL
Identifier for zenithal/azimuthal projections.
Definition: prj.h:646
hpxx2s
int hpxx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the HEALPix (HPX) projection.
prjfree
int prjfree(struct prjprm *prj)
Destructor for the prjprm struct.
bonx2s
int bonx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for Bonne's (BON) projection.
merx2s
int merx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for Mercator's (MER) projection.
sfls2x
int sfls2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the Sanson-Flamsteed (SFL) projection.
zpnx2s
int zpnx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the zenithal/azimuthal polynomial (ZPN) projection.
copx2s
int copx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the conic perspective (COP) projection.
PSEUDOCYLINDRICAL
const int PSEUDOCYLINDRICAL
Identifier for pseudocylindrical projections.
Definition: prj.h:646
prj_codes
const char prj_codes[28][4]
Recognized three-letter projection codes.
prjperr
int prjperr(const struct prjprm *prj, const char *prefix)
Print error messages from a prjprm struct.
arcx2s
int arcx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the zenithal/azimuthal equidistant (ARC) projection.
stgset
int stgset(struct prjprm *prj)
Set up a prjprm struct for the stereographic (STG) projection.
ceaset
int ceaset(struct prjprm *prj)
Set up a prjprm struct for the cylindrical equal area (CEA) projection.
xphx2s
int xphx2s(PRJX2S_ARGS)
xphs2x
int xphs2x(PRJS2X_ARGS)
qscset
int qscset(struct prjprm *prj)
Set up a prjprm struct for the quadrilateralized spherical cube (QSC) projection.
HEALPIX
const int HEALPIX
Identifier for the HEALPix projection.
Definition: prj.h:646
mols2x
int mols2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for Mollweide's (MOL) projection.
szps2x
int szps2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the slant zenithal perspective (SZP) projection.
QUADCUBE
const int QUADCUBE
Identifier for quadcube projections.
Definition: prj.h:646
airs2x
int airs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for Airy's (AIR) projection.
cops2x
int cops2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the conic perspective (COP) projection.
zpns2x
int zpns2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the zenithal/azimuthal polynomial (ZPN) projection.
prjbchk
int prjbchk(double tol, int nphi, int ntheta, int spt, double phi[], double theta[], int stat[])
Bounds checking on native coordinates.
sflset
int sflset(struct prjprm *prj)
Set up a prjprm struct for the Sanson-Flamsteed (SFL) projection.
qscs2x
int qscs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the quadrilateralized spherical cube (QSC) projection.
zeax2s
int zeax2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the zenithal/azimuthal equal area (ZEA) projection.
molx2s
int molx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for Mollweide's (MOL) projection.
CYLINDRICAL
const int CYLINDRICAL
Identifier for cylindrical projections.
Definition: prj.h:645
prjprt
int prjprt(const struct prjprm *prj)
Print routine for the prjprm struct.
stgx2s
int stgx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the stereographic (STG) projection.
cscset
int cscset(struct prjprm *prj)
Set up a prjprm struct for the COBE spherical cube (CSC) projection.
aits2x
int aits2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the Hammer-Aitoff (AIT) projection.
azpx2s
int azpx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the zenithal/azimuthal perspective (AZP) projection.
prjx2s
int prjx2s(PRJX2S_ARGS)
Generic Cartesian-to-spherical deprojection.
prj_categories
const char prj_categories[9][32]
Projection categories.
tans2x
int tans2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the gnomonic (TAN) projection.
hpxset
int hpxset(struct prjprm *prj)
Set up a prjprm struct for the HEALPix (HPX) projection.
arcs2x
int arcs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the zenithal/azimuthal equidistant (ARC) projection.
pcoset
int pcoset(struct prjprm *prj)
Set up a prjprm struct for the polyconic (PCO) projection.
PRJS2X_ARGS
#define PRJS2X_ARGS
For use in declaring projection function prototypes.
Definition: prj.h:665
tscset
int tscset(struct prjprm *prj)
Set up a prjprm struct for the tangential spherical cube (TSC) projection.
bonset
int bonset(struct prjprm *prj)
Set up a prjprm struct for Bonne's (BON) projection.
POLYCONIC
const int POLYCONIC
Identifier for polyconic projections.
Definition: prj.h:645
coeset
int coeset(struct prjprm *prj)
Set up a prjprm struct for the conic equal area (COE) projection.
cars2x
int cars2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the plate carrée (CAR) projection.
stgs2x
int stgs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the stereographic (STG) projection.
sinset
int sinset(struct prjprm *prj)
Set up a prjprm struct for the orthographic/synthesis (SIN) projection.
tscx2s
int tscx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the tangential spherical cube (TSC) projection.
azps2x
int azps2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the zenithal/azimuthal perspective (AZP) projection.
sins2x
int sins2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the orthographic/synthesis (SIN) projection.
prjs2x
int prjs2x(PRJS2X_ARGS)
Generic spherical-to-Cartesian projection.
azpset
int azpset(struct prjprm *prj)
Set up a prjprm struct for the zenithal/azimuthal perspective (AZP) projection.
arcset
int arcset(struct prjprm *prj)
Set up a prjprm struct for the zenithal/azimuthal equidistant (ARC) projection.
copset
int copset(struct prjprm *prj)
Set up a prjprm struct for the conic perspective (COP) projection.
PVN
#define PVN
Total number of projection parameters.
Definition: prj.h:631
CONVENTIONAL
const int CONVENTIONAL
Identifier for conventional projections.
Definition: prj.h:645
zpnset
int zpnset(struct prjprm *prj)
Set up a prjprm struct for the zenithal/azimuthal polynomial (ZPN) projection.
cscs2x
int cscs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the COBE spherical cube (CSC) projection.
prj_errmsg
const char * prj_errmsg[]
Status return messages.
tanx2s
int tanx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the gnomonic (TAN) projection.
merset
int merset(struct prjprm *prj)
Set up a prjprm struct for Mercator's (MER) projection.
parset
int parset(struct prjprm *prj)
Set up a prjprm struct for the parabolic (PAR) projection.
prjset
int prjset(struct prjprm *prj)
Generic setup routine for the prjprm struct.
coex2s
int coex2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the conic equal area (COE) projection.
prjini
int prjini(struct prjprm *prj)
Default constructor for the prjprm struct.
mers2x
int mers2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for Mercator's (MER) projection.
zeas2x
int zeas2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the zenithal/azimuthal equal area (ZEA) projection.
CONIC
const int CONIC
Identifier for conic projections.
pars2x
int pars2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the parabolic (PAR) projection.
sinx2s
int sinx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the orthographic/synthesis (SIN) projection.
coos2x
int coos2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the conic orthomorphic (COO) projection.
carx2s
int carx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the plate carrée (CAR) projection.
hpxs2x
int hpxs2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the HEALPix (HPX) projection.
coes2x
int coes2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the conic equal area (COE) projection.
szpset
int szpset(struct prjprm *prj)
Set up a prjprm struct for the slant zenithal perspective (SZP) projection.
codset
int codset(struct prjprm *prj)
Set up a prjprm struct for the conic equidistant (COD) projection.
qscx2s
int qscx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the quadrilateralized spherical cube (QSC) projection.
cscx2s
int cscx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the COBE spherical cube (CSC) projection.
xphset
int xphset(struct prjprm *prj)
cods2x
int cods2x(PRJS2X_ARGS)
Spherical-to-Cartesian transformation for the conic equidistant (COD) projection.
ceax2s
int ceax2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the cylindrical equal area (CEA) projection.
cypx2s
int cypx2s(PRJX2S_ARGS)
Cartesian-to-spherical transformation for the cylindrical perspective (CYP) projection.
prjprm
Projection parameters.
Definition: prj.h:669
prjprm::y0
double y0
Definition: prj.h:692
prjprm::err
struct wcserr * err
Definition: prj.h:696
prjprm::r0
double r0
Definition: prj.h:677
prjprm::w
double w[10]
Definition: prj.h:701
prjprm::pv
double pv[PVN]
Definition: prj.h:678
prjprm::code
char code[4]
Definition: prj.h:676
prjprm::divergent
int divergent
Definition: prj.h:691
prjprm::phi0
double phi0
Definition: prj.h:679
prjprm::padding
void * padding
Definition: prj.h:700
prjprm::n
int n
Definition: prj.h:702
prjprm::x0
double x0
Definition: prj.h:692
prjprm::name
char name[40]
Definition: prj.h:684
prjprm::equiareal
int equiareal
Definition: prj.h:688
prjprm::bounds
int bounds
Definition: prj.h:680
prjprm::pvrange
int pvrange
Definition: prj.h:686
prjprm::flag
int flag
Definition: prj.h:672
prjprm::conformal
int conformal
Definition: prj.h:689
prjprm::global
int global
Definition: prj.h:690
prjprm::prjs2x
int(* prjs2x)(PRJS2X_ARGS)
Definition: prj.h:705
prjprm::theta0
double theta0
Definition: prj.h:679
prjprm::prjx2s
int(* prjx2s)(PRJX2S_ARGS)
Definition: prj.h:704
prjprm::category
int category
Definition: prj.h:685
prjprm::m
int m
Definition: prj.h:702
prjprm::simplezen
int simplezen
Definition: prj.h:687
wcserr
Error message handling.
Definition: wcserr.h:220