WCSLIB: prj.h Source File

WCSLIB 7.1

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