WCSLIB: prj.h Source File

WCSLIB 4.25.1

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

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