WCSLIB: prj.h Source File

WCSLIB 8.8

Loading...
Searching...
No Matches
prj.h
Go to the documentation of this file.
1/*============================================================================
2 WCSLIB 8.8 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2026, 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/computing/software/wcs
22 $Id: prj.h,v 8.8 2026/05/22 11:19:30 mcalabre Exp $
23*=============================================================================
24*
25* WCSLIB 8.8 - 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, prjsize() computes its total size including allocated
55* memory, prjenq() returns information about the state of the struct, and
56* prjprt() prints its contents.
57*
58* prjperr() prints the error message(s) (if any) stored in a prjprm struct.
59* prjbchk() performs bounds checking on native spherical coordinates.
60*
61* Setup routines for each projection with names of the form ???set(), where
62* "???" is the down-cased three-letter projection code, compute intermediate
63* values in the prjprm struct from parameters in it that were supplied by the
64* user. The struct always needs to be set by the projection's setup routine
65* but that need not be called explicitly - refer to the explanation of
66* prjprm::flag.
67*
68* Each map projection is implemented via separate functions for the spherical
69* projection, ???s2x(), and deprojection, ???x2s().
70*
71* A set of driver routines, prjset(), prjx2s(), and prjs2x(), provides a
72* generic interface to the specific projection routines which they invoke
73* via pointers-to-functions stored in the prjprm struct.
74*
75* In summary, the routines are:
76* - prjini() Initialization routine for the prjprm struct.
77* - prjfree() Reclaim memory allocated for error messages.
78* - prjsize() Compute total size of a prjprm struct.
79* - prjprt() Print a 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 and returned:
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* prjsize() - Compute the size of a prjprm struct
188* -----------------------------------------------
189* prjsize() computes the full size of a prjprm struct, including allocated
190* memory.
191*
192* Given:
193* prj const struct prjprm*
194* Projection parameters.
195*
196* If NULL, the base size of the struct and the allocated
197* size are both set to zero.
198*
199* Returned:
200* sizes int[2] The first element is the base size of the struct as
201* returned by sizeof(struct prjprm). The second element
202* is the total allocated size, in bytes. This figure
203* includes memory allocated for the constituent struct,
204* prjprm::err.
205*
206* It is not an error for the struct not to have been set
207* up via prjset().
208*
209* Function return value:
210* int Status return value:
211* 0: Success.
212*
213*
214* prjenq() - enquire about the state of a prjprm struct
215* -----------------------------------------------------
216* prjenq() may be used to obtain information about the state of a prjprm
217* struct. The function returns a true/false answer for the enquiry asked.
218*
219* Given:
220* prj const struct prjprm*
221* Projection parameters.
222*
223* enquiry int Enquiry according to the following parameters:
224* PRJENQ_SET: the struct has been set up by prjset().
225* PRJENQ_BYP: the struct is in bypass mode (see
226* prjset()).
227*
228* Function return value:
229* int Enquiry result:
230* 0: No.
231* 1: Yes.
232*
233*
234* prjprt() - Print routine for the prjprm struct
235* ----------------------------------------------
236* prjprt() prints the contents of a prjprm struct using wcsprintf(). Mainly
237* intended for diagnostic purposes.
238*
239* Given:
240* prj const struct prjprm*
241* Projection parameters.
242*
243* Function return value:
244* int Status return value:
245* 0: Success.
246* 1: Null prjprm pointer passed.
247*
248*
249* prjperr() - Print error messages from a prjprm struct
250* -----------------------------------------------------
251* prjperr() prints the error message(s) (if any) stored in a prjprm struct.
252* If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.
253*
254* Given:
255* prj const struct prjprm*
256* Projection parameters.
257*
258* prefix const char *
259* If non-NULL, each output line will be prefixed with
260* this string.
261*
262* Function return value:
263* int Status return value:
264* 0: Success.
265* 1: Null prjprm pointer passed.
266*
267*
268* prjbchk() - Bounds checking on native coordinates
269* -------------------------------------------------
270* prjbchk() performs bounds checking on native spherical coordinates. As
271* returned by the deprojection (x2s) routines, native longitude is expected
272* to lie in the closed interval [-180,180], with latitude in [-90,90].
273*
274* A tolerance may be specified to provide a small allowance for numerical
275* imprecision. Values that lie outside the allowed range by not more than
276* the specified tolerance will be adjusted back into range.
277*
278* If prjprm::bounds&4 is set, as it is by prjini(), then prjbchk() will be
279* invoked automatically by the Cartesian-to-spherical deprojection (x2s)
280* routines with an appropriate tolerance set for each projection.
281*
282* Given:
283* tol double Tolerance for the bounds check [deg].
284*
285* nphi,
286* ntheta int Vector lengths.
287*
288* spt int Vector stride.
289*
290* Given and returned:
291* phi,theta double[] Native longitude and latitude (phi,theta) [deg].
292*
293* Returned:
294* stat int[] Status value for each vector element:
295* 0: Valid value of (phi,theta).
296* 1: Invalid value.
297*
298* Function return value:
299* int Status return value:
300* 0: Success.
301* 1: One or more of the (phi,theta) coordinates
302* were, invalid, as indicated by the stat vector.
303*
304*
305* prjset() - Generic setup routine for the prjprm struct
306* ------------------------------------------------------
307* prjset() sets up a prjprm struct according to information supplied within
308* it.
309*
310* The one important distinction between prjset() and the setup routines for
311* the specific projections is that the projection code must be defined in the
312* prjprm struct in order for prjset() to identify the required projection.
313* Once prjset() has initialized the prjprm struct, prjx2s() and prjs2x() use
314* the pointers to the specific projection and deprojection routines contained
315* therein.
316*
317* Note that this routine need not be called directly; it will be invoked by
318* prjx2s() and prjs2x() if prj.flag is anything other than a predefined magic
319* value.
320*
321* prjset() normally operates regardless of the value of prjprm::flag; i.e.
322* even if a struct was previously set up it will be reset unconditionally.
323* However, a prjprm struct may be put into "bypass" mode by invoking prjset()
324* initially with prjprm::flag == 1 (rather than 0). prjset() will return
325* immediately if invoked on a struct in that state. To take a struct out of
326* bypass mode, simply reset prjprm::flag to zero. See also prjenq().
327*
328* Given and returned:
329* prj struct prjprm*
330* Projection parameters.
331*
332* Function return value:
333* int Status return value:
334* 0: Success.
335* 1: Null prjprm pointer passed.
336* 2: Invalid projection parameters.
337*
338* For returns > 1, a detailed error message is set in
339* prjprm::err if enabled, see wcserr_enable().
340*
341*
342* prjx2s() - Generic Cartesian-to-spherical deprojection
343* ------------------------------------------------------
344* Deproject Cartesian (x,y) coordinates in the plane of projection to native
345* spherical coordinates (phi,theta).
346*
347* The projection is that specified by prjprm::code.
348*
349* Given and returned:
350* prj struct prjprm*
351* Projection parameters.
352*
353* Given:
354* nx,ny int Vector lengths.
355*
356* sxy,spt int Vector strides.
357*
358* x,y const double[]
359* Projected coordinates.
360*
361* Returned:
362* phi,theta double[] Longitude and latitude (phi,theta) of the projected
363* point in native spherical coordinates [deg].
364*
365* stat int[] Status value for each vector element:
366* 0: Success.
367* 1: Invalid value of (x,y).
368*
369* Function return value:
370* int Status return value:
371* 0: Success.
372* 1: Null prjprm pointer passed.
373* 2: Invalid projection parameters.
374* 3: One or more of the (x,y) coordinates were
375* invalid, as indicated by the stat vector.
376*
377* For returns > 1, a detailed error message is set in
378* prjprm::err if enabled, see wcserr_enable().
379*
380*
381* prjs2x() - Generic spherical-to-Cartesian projection
382* ----------------------------------------------------
383* Project native spherical coordinates (phi,theta) to Cartesian (x,y)
384* coordinates in the plane of projection.
385*
386* The projection is that specified by prjprm::code.
387*
388* Given and returned:
389* prj struct prjprm*
390* Projection parameters.
391*
392* Given:
393* nphi,
394* ntheta int Vector lengths.
395*
396* spt,sxy int Vector strides.
397*
398* phi,theta const double[]
399* Longitude and latitude (phi,theta) of the projected
400* point in native spherical coordinates [deg].
401*
402* Returned:
403* x,y double[] Projected coordinates.
404*
405* stat int[] Status value for each vector element:
406* 0: Success.
407* 1: Invalid value of (phi,theta).
408*
409* Function return value:
410* int Status return value:
411* 0: Success.
412* 1: Null prjprm pointer passed.
413* 2: Invalid projection parameters.
414* 4: One or more of the (phi,theta) coordinates
415* were, invalid, as indicated by the stat vector.
416*
417* For returns > 1, a detailed error message is set in
418* prjprm::err if enabled, see wcserr_enable().
419*
420*
421* ???set() - Specific setup routines for the prjprm struct
422* --------------------------------------------------------
423* Set up a prjprm struct for a particular projection according to information
424* supplied within it.
425*
426* Given and returned:
427* prj struct prjprm*
428* Projection parameters.
429*
430* Function return value:
431* int Status return value:
432* 0: Success.
433* 1: Null prjprm pointer passed.
434* 2: Invalid projection parameters.
435*
436* For returns > 1, a detailed error message is set in
437* prjprm::err if enabled, see wcserr_enable().
438*
439*
440* ???x2s() - Specific Cartesian-to-spherical deprojection routines
441* ----------------------------------------------------------------
442* Transform (x,y) coordinates in the plane of projection to native spherical
443* coordinates (phi,theta).
444*
445* Given and returned:
446* prj struct prjprm*
447* Projection parameters.
448*
449* Given:
450* nx,ny int Vector lengths.
451*
452* sxy,spt int Vector strides.
453*
454* x,y const double[]
455* Projected coordinates.
456*
457* Returned:
458* phi,theta double[] Longitude and latitude of the projected point in
459* native spherical coordinates [deg].
460*
461* stat int[] Status value for each vector element:
462* 0: Success.
463* 1: Invalid value of (x,y).
464*
465* Function return value:
466* int Status return value:
467* 0: Success.
468* 1: Null prjprm pointer passed.
469* 2: Invalid projection parameters.
470* 3: One or more of the (x,y) coordinates were
471* invalid, as indicated by the stat vector.
472*
473* For returns > 1, a detailed error message is set in
474* prjprm::err if enabled, see wcserr_enable().
475*
476*
477* ???s2x() - Specific spherical-to-Cartesian projection routines
478*---------------------------------------------------------------
479* Transform native spherical coordinates (phi,theta) to (x,y) coordinates in
480* the plane of projection.
481*
482* Given and returned:
483* prj struct prjprm*
484* Projection parameters.
485*
486* Given:
487* nphi,
488* ntheta int Vector lengths.
489*
490* spt,sxy int Vector strides.
491*
492* phi,theta const double[]
493* Longitude and latitude of the projected point in
494* native spherical coordinates [deg].
495*
496* Returned:
497* x,y double[] Projected coordinates.
498*
499* stat int[] Status value for each vector element:
500* 0: Success.
501* 1: Invalid value of (phi,theta).
502*
503* Function return value:
504* int Status return value:
505* 0: Success.
506* 1: Null prjprm pointer passed.
507* 2: Invalid projection parameters.
508* 4: One or more of the (phi,theta) coordinates
509* were, invalid, as indicated by the stat vector.
510*
511* For returns > 1, a detailed error message is set in
512* prjprm::err if enabled, see wcserr_enable().
513*
514*
515* prjprm struct - Projection parameters
516* -------------------------------------
517* The prjprm struct contains all information needed to project or deproject
518* native spherical coordinates. It consists of certain members that must be
519* set by the user ("given") and others that are set by the WCSLIB routines
520* ("returned"). Some of the latter are supplied for informational purposes
521* while others are for internal use only.
522*
523* int flag
524* (Given and returned) This flag must be set to zero (or 1, see prjset())
525* whenever any of the following prjprm members are set or changed:
526*
527* - prjprm::code,
528* - prjprm::r0,
529* - prjprm::pv[],
530* - prjprm::phi0,
531* - prjprm::theta0.
532*
533* This signals the initialization routine (prjset() or ???set()) to
534* recompute the returned members of the prjprm struct. flag will then be
535* reset to indicate that this has been done.
536*
537* Note that flag need not be reset when prjprm::bounds is changed.
538*
539* char code[4]
540* (Given) Three-letter projection code defined by the FITS standard.
541*
542* double r0
543* (Given) The radius of the generating sphere for the projection, a linear
544* scaling parameter. If this is zero, it will be reset to its default
545* value of 180/pi (the value for FITS WCS).
546*
547* double pv[30]
548* (Given) Projection parameters. These correspond to the PVi_ma keywords
549* in FITS, so pv[0] is PVi_0a, pv[1] is PVi_1a, etc., where i denotes the
550* latitude-like axis. Many projections use pv[1] (PVi_1a), some also use
551* pv[2] (PVi_2a) and SZP uses pv[3] (PVi_3a). ZPN is currently the only
552* projection that uses any of the others.
553*
554* Usage of the pv[] array as it applies to each projection is described in
555* the prologue to each trio of projection routines in prj.c.
556*
557* double phi0
558* (Given) The native longitude, phi_0 [deg], and ...
559* double theta0
560* (Given) ... the native latitude, theta_0 [deg], of the reference point,
561* i.e. the point (x,y) = (0,0). If undefined (set to a magic value by
562* prjini()) the initialization routine will set this to a
563* projection-specific default.
564*
565* int bounds
566* (Given) Controls bounds checking. If bounds&1 then enable strict bounds
567* checking for the spherical-to-Cartesian (s2x) transformation for the
568* AZP, SZP, TAN, SIN, ZPN, and COP projections. If bounds&2 then enable
569* strict bounds checking for the Cartesian-to-spherical transformation
570* (x2s) for the HPX and XPH projections. If bounds&4 then the Cartesian-
571* to-spherical transformations (x2s) will invoke prjbchk() to perform
572* bounds checking on the computed native coordinates, with a tolerance set
573* to suit each projection. bounds is set to 7 by prjini() by default
574* which enables all checks. Zero it to disable all checking.
575*
576* It is not necessary to reset the prjprm struct (via prjset() or
577* ???set()) when prjprm::bounds is changed.
578*
579* The remaining members of the prjprm struct are maintained by the setup
580* routines and must not be modified elsewhere:
581*
582* char name[40]
583* (Returned) Long name of the projection.
584*
585* Provided for information only, not used by the projection routines.
586*
587* int category
588* (Returned) Projection category matching the value of the relevant global
589* variable:
590*
591* - ZENITHAL,
592* - CYLINDRICAL,
593* - PSEUDOCYLINDRICAL,
594* - CONVENTIONAL,
595* - CONIC,
596* - POLYCONIC,
597* - QUADCUBE, and
598* - HEALPIX.
599*
600* The category name may be identified via the prj_categories character
601* array, e.g.
602*
603= struct prjprm prj;
604= ...
605= printf("%s\n", prj_categories[prj.category]);
606*
607* Provided for information only, not used by the projection routines.
608*
609* int pvrange
610* (Returned) Range of projection parameter indices: 100 times the first
611* allowed index plus the number of parameters, e.g. TAN is 0 (no
612* parameters), SZP is 103 (1 to 3), and ZPN is 30 (0 to 29).
613*
614* Provided for information only, not used by the projection routines.
615*
616* int simplezen
617* (Returned) True if the projection is a radially-symmetric zenithal
618* projection.
619*
620* Provided for information only, not used by the projection routines.
621*
622* int equiareal
623* (Returned) True if the projection is equal area.
624*
625* Provided for information only, not used by the projection routines.
626*
627* int conformal
628* (Returned) True if the projection is conformal.
629*
630* Provided for information only, not used by the projection routines.
631*
632* int global
633* (Returned) True if the projection can represent the whole sphere in a
634* finite, non-overlapped mapping.
635*
636* Provided for information only, not used by the projection routines.
637*
638* int divergent
639* (Returned) True if the projection diverges in latitude.
640*
641* Provided for information only, not used by the projection routines.
642*
643* double x0
644* (Returned) The offset in x, and ...
645* double y0
646* (Returned) ... the offset in y used to force (x,y) = (0,0) at
647* (phi_0,theta_0).
648*
649* struct wcserr *err
650* (Returned) If enabled, when an error status is returned, this struct
651* contains detailed information about the error, see wcserr_enable().
652*
653* void *padding
654* (An unused variable inserted for alignment purposes only.)
655*
656* double w[10]
657* (For internal use only.) Intermediate floating-point values derived from
658* the projection parameters by prjset(), cached here to save recomputation.
659*
660* Usage of the w[] array as it applies to each projection is described in
661* the prologue to each trio of projection routines in prj.c.
662*
663* int m, n
664* (For internal use only.) Intermediate integer values set by prjset()
665* (used only for the ZPN and HPX projections).
666*
667* int (*prjx2s)(PRJX2S_ARGS)
668* (For internal use only.) Pointer to the spherical projection ...
669* int (*prjs2x)(PRJ_ARGS)
670* (For internal use only.) ... and deprojection routines.
671*
672*
673* Global variable: const char *prj_errmsg[] - Status return messages
674* ------------------------------------------------------------------
675* Error messages to match the status value returned from each function.
676*
677*===========================================================================*/
678
679#ifndef WCSLIB_PROJ
680#define WCSLIB_PROJ
681
682#ifdef __cplusplus
683extern "C" {
684#endif
685
686 enum prjenq_enum {
687 PRJENQ_SET = 2, // prjprm struct has been set up.
688 PRJENQ_BYP = 4, // prjprm struct is in bypass mode.
689};
690
691// Total number of projection parameters; 0 to PVN-1.
692#define PVN 30
693
694extern const char *prj_errmsg[];
695
696 enum prj_errmsg_enum {
697 PRJERR_SUCCESS = 0, // Success.
698 PRJERR_NULL_POINTER = 1, // Null prjprm pointer passed.
699 PRJERR_BAD_PARAM = 2, // Invalid projection parameters.
700 PRJERR_BAD_PIX = 3, // One or more of the (x, y) coordinates were
701 // invalid.
702 PRJERR_BAD_WORLD = 4 // One or more of the (phi, theta) coordinates
703 // were invalid.
704};
705
706 extern const int CONIC, CONVENTIONAL, CYLINDRICAL, POLYCONIC,
707 PSEUDOCYLINDRICAL, QUADCUBE, ZENITHAL, HEALPIX;
708extern const char prj_categories[9][32];
709
710extern const int prj_ncode;
711extern const char prj_codes[28][4];
712
713#ifdef PRJX2S_ARGS
714#undef PRJX2S_ARGS
715#endif
716
717#ifdef PRJS2X_ARGS
718#undef PRJS2X_ARGS
719#endif
720
721// For use in declaring deprojection function prototypes.
722#define PRJX2S_ARGS struct prjprm *prj, int nx, int ny, int sxy, int spt, \
723const double x[], const double y[], double phi[], double theta[], int stat[]
724
725// For use in declaring projection function prototypes.
726#define PRJS2X_ARGS struct prjprm *prj, int nx, int ny, int sxy, int spt, \
727const double phi[], const double theta[], double x[], double y[], int stat[]
728
729
730 struct prjprm {
731 // Initialization flag (see the prologue above).
732 //--------------------------------------------------------------------------
733 int flag; // Set to zero to force initialization.
734
735 // Parameters to be provided (see the prologue above).
736 //--------------------------------------------------------------------------
737 char code[4]; // Three-letter projection code.
738 double r0; // Radius of the generating sphere.
739 double pv[PVN]; // Projection parameters.
740 double phi0, theta0; // Fiducial native coordinates.
741 int bounds; // Controls bounds checking.
742
743 // Information derived from the parameters supplied.
744 //--------------------------------------------------------------------------
745 char name[40]; // Projection name.
746 int category; // Projection category.
747 int pvrange; // Range of projection parameter indices.
748 int simplezen; // Is it a simple zenithal projection?
749 int equiareal; // Is it an equal area projection?
750 int conformal; // Is it a conformal projection?
751 int global; // Can it map the whole sphere?
752 int divergent; // Does the projection diverge in latitude?
753 double x0, y0; // Fiducial offsets.
754
755 // Error messaging, if enabled.
756 //--------------------------------------------------------------------------
757 struct wcserr *err;
758
759 //--------------------------------------------------------------------------
760 // Private - the remainder are for internal use.
761 //--------------------------------------------------------------------------
762 void *padding; // (Dummy inserted for alignment purposes.)
763
764 double w[10]; // Intermediate values set by prjset().
765 int m, n; // Intermediate values set by prjset().
766
767 int (*prjx2s)(PRJX2S_ARGS); // Pointers to the spherical projection and
768 int (*prjs2x)(PRJS2X_ARGS); // deprojection functions.
769};
770
771// Size of the prjprm struct in int units, used by the Fortran wrappers.
772#define PRJLEN (sizeof(struct prjprm)/sizeof(int))
773
774
775 int prjini(struct prjprm *prj);
776
777 int prjfree(struct prjprm *prj);
778
779 int prjsize(const struct prjprm *prj, int sizes[2]);
780
781 int prjenq(const struct prjprm *prj, int enquiry);
782
783 int prjprt(const struct prjprm *prj);
784
785 int prjperr(const struct prjprm *prj, const char *prefix);
786
787 int prjbchk(double tol, int nphi, int ntheta, int spt, double phi[],
788 double theta[], int stat[]);
789
790// Use the preprocessor to help declare function prototypes (see above).
791 int prjset(struct prjprm *prj);
792 int prjx2s(PRJX2S_ARGS);
793 int prjs2x(PRJS2X_ARGS);
794
795 int azpset(struct prjprm *prj);
796 int azpx2s(PRJX2S_ARGS);
797 int azps2x(PRJS2X_ARGS);
798
799 int szpset(struct prjprm *prj);
800 int szpx2s(PRJX2S_ARGS);
801 int szps2x(PRJS2X_ARGS);
802
803 int tanset(struct prjprm *prj);
804 int tanx2s(PRJX2S_ARGS);
805 int tans2x(PRJS2X_ARGS);
806
807 int stgset(struct prjprm *prj);
808 int stgx2s(PRJX2S_ARGS);
809 int stgs2x(PRJS2X_ARGS);
810
811 int sinset(struct prjprm *prj);
812 int sinx2s(PRJX2S_ARGS);
813 int sins2x(PRJS2X_ARGS);
814
815 int arcset(struct prjprm *prj);
816 int arcx2s(PRJX2S_ARGS);
817 int arcs2x(PRJS2X_ARGS);
818
819 int zpnset(struct prjprm *prj);
820 int zpnx2s(PRJX2S_ARGS);
821 int zpns2x(PRJS2X_ARGS);
822
823 int zeaset(struct prjprm *prj);
824 int zeax2s(PRJX2S_ARGS);
825 int zeas2x(PRJS2X_ARGS);
826
827 int airset(struct prjprm *prj);
828 int airx2s(PRJX2S_ARGS);
829 int airs2x(PRJS2X_ARGS);
830
831 int cypset(struct prjprm *prj);
832 int cypx2s(PRJX2S_ARGS);
833 int cyps2x(PRJS2X_ARGS);
834
835 int ceaset(struct prjprm *prj);
836 int ceax2s(PRJX2S_ARGS);
837 int ceas2x(PRJS2X_ARGS);
838
839 int carset(struct prjprm *prj);
840 int carx2s(PRJX2S_ARGS);
841 int cars2x(PRJS2X_ARGS);
842
843 int merset(struct prjprm *prj);
844 int merx2s(PRJX2S_ARGS);
845 int mers2x(PRJS2X_ARGS);
846
847 int sflset(struct prjprm *prj);
848 int sflx2s(PRJX2S_ARGS);
849 int sfls2x(PRJS2X_ARGS);
850
851 int parset(struct prjprm *prj);
852 int parx2s(PRJX2S_ARGS);
853 int pars2x(PRJS2X_ARGS);
854
855 int molset(struct prjprm *prj);
856 int molx2s(PRJX2S_ARGS);
857 int mols2x(PRJS2X_ARGS);
858
859 int aitset(struct prjprm *prj);
860 int aitx2s(PRJX2S_ARGS);
861 int aits2x(PRJS2X_ARGS);
862
863 int copset(struct prjprm *prj);
864 int copx2s(PRJX2S_ARGS);
865 int cops2x(PRJS2X_ARGS);
866
867 int coeset(struct prjprm *prj);
868 int coex2s(PRJX2S_ARGS);
869 int coes2x(PRJS2X_ARGS);
870
871 int codset(struct prjprm *prj);
872 int codx2s(PRJX2S_ARGS);
873 int cods2x(PRJS2X_ARGS);
874
875 int cooset(struct prjprm *prj);
876 int coox2s(PRJX2S_ARGS);
877 int coos2x(PRJS2X_ARGS);
878
879 int bonset(struct prjprm *prj);
880 int bonx2s(PRJX2S_ARGS);
881 int bons2x(PRJS2X_ARGS);
882
883 int pcoset(struct prjprm *prj);
884 int pcox2s(PRJX2S_ARGS);
885 int pcos2x(PRJS2X_ARGS);
886
887 int tscset(struct prjprm *prj);
888 int tscx2s(PRJX2S_ARGS);
889 int tscs2x(PRJS2X_ARGS);
890
891 int cscset(struct prjprm *prj);
892 int cscx2s(PRJX2S_ARGS);
893 int cscs2x(PRJS2X_ARGS);
894
895 int qscset(struct prjprm *prj);
896 int qscx2s(PRJX2S_ARGS);
897 int qscs2x(PRJS2X_ARGS);
898
899 int hpxset(struct prjprm *prj);
900 int hpxx2s(PRJX2S_ARGS);
901 int hpxs2x(PRJS2X_ARGS);
902
903 int xphset(struct prjprm *prj);
904 int xphx2s(PRJX2S_ARGS);
905 int xphs2x(PRJS2X_ARGS);
906
907
908// Deprecated.
909#define prjini_errmsg prj_errmsg
910#define prjprt_errmsg prj_errmsg
911#define prjset_errmsg prj_errmsg
912#define prjx2s_errmsg prj_errmsg
913#define prjs2x_errmsg prj_errmsg
914
915#ifdef __cplusplus
916}
917#endif
918
919#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:696
PRJERR_BAD_WORLD
@ PRJERR_BAD_WORLD
Definition prj.h:702
PRJERR_NULL_POINTER
@ PRJERR_NULL_POINTER
Definition prj.h:698
PRJERR_BAD_PARAM
@ PRJERR_BAD_PARAM
Definition prj.h:699
PRJERR_SUCCESS
@ PRJERR_SUCCESS
Definition prj.h:697
PRJERR_BAD_PIX
@ PRJERR_BAD_PIX
Definition prj.h:700
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:722
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:707
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:707
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:707
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:707
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.
prj_codes
const char prj_codes[28][4]
Recognized three-letter projection codes.
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:706
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.
prjenq
int prjenq(const struct prjprm *prj, int enquiry)
enquire about the state of a prjprm struct.
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:726
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:706
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.
prj_errmsg
const char * prj_errmsg[]
Status return messages.
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:692
CONVENTIONAL
const int CONVENTIONAL
Identifier for conventional projections.
Definition prj.h:706
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.
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.
prjenq_enum
prjenq_enum
Definition prj.h:686
PRJENQ_BYP
@ PRJENQ_BYP
Definition prj.h:688
PRJENQ_SET
@ PRJENQ_SET
Definition prj.h:687
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.
prjsize
int prjsize(const struct prjprm *prj, int sizes[2])
Compute the size of a prjprm struct.
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:730
prjprm::name
char name[40]
Definition prj.h:745
prjprm::y0
double y0
Definition prj.h:753
prjprm::pv
double pv[PVN]
Definition prj.h:739
prjprm::code
char code[4]
Definition prj.h:737
prjprm::padding
void * padding
Definition prj.h:762
prjprm::r0
double r0
Definition prj.h:738
prjprm::w
double w[10]
Definition prj.h:764
prjprm::divergent
int divergent
Definition prj.h:752
prjprm::phi0
double phi0
Definition prj.h:740
prjprm::prjs2x
int(* prjs2x)(PRJS2X_ARGS)
Definition prj.h:768
prjprm::err
struct wcserr * err
Definition prj.h:757
prjprm::n
int n
Definition prj.h:765
prjprm::x0
double x0
Definition prj.h:753
prjprm::equiareal
int equiareal
Definition prj.h:749
prjprm::bounds
int bounds
Definition prj.h:741
prjprm::pvrange
int pvrange
Definition prj.h:747
prjprm::flag
int flag
Definition prj.h:733
prjprm::conformal
int conformal
Definition prj.h:750
prjprm::prjx2s
int(* prjx2s)(PRJX2S_ARGS)
Definition prj.h:767
prjprm::global
int global
Definition prj.h:751
prjprm::theta0
double theta0
Definition prj.h:740
prjprm::category
int category
Definition prj.h:746
prjprm::m
int m
Definition prj.h:765
prjprm::simplezen
int simplezen
Definition prj.h:748
wcserr
Error message handling.
Definition wcserr.h:243