WCSLIB 8.5

Loading...
Searching...
No Matches
sph.h
Go to the documentation of this file.
1/*============================================================================
2 WCSLIB 8.5 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2025, Mark Calabretta
4
5 This file is part of WCSLIB.
6
7 WCSLIB is free software: you can redistribute it and/or modify it under the
8 terms of the GNU Lesser General Public License as published by the Free
9 Software Foundation, either version 3 of the License, or (at your option)
10 any later version.
11
12 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
15 more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with WCSLIB. If not, see http://www.gnu.org/licenses.
19
20 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
21 http://www.atnf.csiro.au/people/Mark.Calabretta
22 $Id: sph.h,v 8.5 2025/12/06 13:47:41 mcalabre Exp $
23*=============================================================================
24*
25* WCSLIB 8.5 - 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 sph routines
31* ---------------------------
32* Routines in this suite implement the spherical coordinate transformations
33* defined by the FITS World Coordinate System (WCS) standard
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* The transformations are implemented via separate functions, sphx2s() and
42* sphs2x(), for the spherical rotation in each direction.
43*
44* A utility function, sphdpa(), computes the angular distances and position
45* angles from a given point on the sky to a number of other points. sphpad()
46* does the complementary operation - computes the coordinates of points offset
47* by the given angular distances and position angles from a given point on the
48* sky.
49*
50*
51* sphx2s() - Rotation in the pixel-to-world direction
52* ---------------------------------------------------
53* sphx2s() transforms native coordinates of a projection to celestial
54* coordinates.
55*
56* Given:
57* eul const double[5]
58* Euler angles for the transformation:
59* 0: Celestial longitude of the native pole [deg].
60* 1: Celestial colatitude of the native pole, or
61* native colatitude of the celestial pole [deg].
62* 2: Native longitude of the celestial pole [deg].
63* 3: cos(eul[1])
64* 4: sin(eul[1])
65*
66* nphi,
67* ntheta int Vector lengths.
68*
69* spt,sxy int Vector strides.
70*
71* phi,theta const double[]
72* Longitude and latitude in the native coordinate
73* system of the projection [deg].
74*
75* Returned:
76* lng,lat double[] Celestial longitude and latitude [deg]. These may
77* refer to the same storage as phi and theta
78* respectively.
79*
80* Function return value:
81* int Status return value:
82* 0: Success.
83*
84*
85* sphs2x() - Rotation in the world-to-pixel direction
86* ---------------------------------------------------
87* sphs2x() transforms celestial coordinates to the native coordinates of a
88* projection.
89*
90* Given:
91* eul const double[5]
92* Euler angles for the transformation:
93* 0: Celestial longitude of the native pole [deg].
94* 1: Celestial colatitude of the native pole, or
95* native colatitude of the celestial pole [deg].
96* 2: Native longitude of the celestial pole [deg].
97* 3: cos(eul[1])
98* 4: sin(eul[1])
99*
100* nlng,nlat int Vector lengths.
101*
102* sll,spt int Vector strides.
103*
104* lng,lat const double[]
105* Celestial longitude and latitude [deg].
106*
107* Returned:
108* phi,theta double[] Longitude and latitude in the native coordinate system
109* of the projection [deg]. These may refer to the same
110* storage as lng and lat respectively.
111*
112* Function return value:
113* int Status return value:
114* 0: Success.
115*
116*
117* sphdpa() - Compute angular distance and position angle
118* ------------------------------------------------------
119* sphdpa() computes the angular distance and generalized position angle (see
120* notes) from a "reference" point to a number of "field" points on the sphere.
121* The points must be specified consistently in any spherical coordinate
122* system.
123*
124* sphdpa() is complementary to sphpad().
125*
126* Given:
127* nfield int The number of field points.
128*
129* lng0,lat0 double Spherical coordinates of the reference point [deg].
130*
131* lng,lat const double[]
132* Spherical coordinates of the field points [deg].
133*
134* Returned:
135* dist,pa double[] Angular distances and position angles [deg]. These
136* may refer to the same storage as lng and lat
137* respectively.
138*
139* Function return value:
140* int Status return value:
141* 0: Success.
142*
143* Notes:
144* 1. sphdpa() uses sphs2x() to rotate coordinates so that the reference
145* point is at the north pole of the new system with the north pole of the
146* old system at zero longitude in the new. The Euler angles required by
147* sphs2x() for this rotation are
148*
149= eul[0] = lng0;
150= eul[1] = 90.0 - lat0;
151= eul[2] = 0.0;
152*
153* The angular distance and generalized position angle are readily
154* obtained from the longitude and latitude of the field point in the new
155* system. This applies even if the reference point is at one of the
156* poles, in which case the "position angle" returned is as would be
157* computed for a reference point at (lng0,+90-epsilon) or
158* (lng0,-90+epsilon), in the limit as epsilon goes to zero.
159*
160* It is evident that the coordinate system in which the two points are
161* expressed is irrelevant to the determination of the angular separation
162* between the points. However, this is not true of the generalized
163* position angle.
164*
165* The generalized position angle is here defined as the angle of
166* intersection of the great circle containing the reference and field
167* points with that containing the reference point and the pole. It has
168* its normal meaning when the the reference and field points are
169* specified in equatorial coordinates (right ascension and declination).
170*
171* Interchanging the reference and field points changes the position angle
172* in a non-intuitive way (because the sum of the angles of a spherical
173* triangle normally exceeds 180 degrees).
174*
175* The position angle is undefined if the reference and field points are
176* coincident or antipodal. This may be detected by checking for a
177* distance of 0 or 180 degrees (within rounding tolerance). sphdpa()
178* will return an arbitrary position angle in such circumstances.
179*
180*
181* sphpad() - Compute field points offset from a given point
182* ---------------------------------------------------------
183* sphpad() computes the coordinates of a set of points that are offset by the
184* specified angular distances and position angles from a given "reference"
185* point on the sky. The distances and position angles must be specified
186* consistently in any spherical coordinate system.
187*
188* sphpad() is complementary to sphdpa().
189*
190* Given:
191* nfield int The number of field points.
192*
193* lng0,lat0 double Spherical coordinates of the reference point [deg].
194*
195* dist,pa const double[]
196* Angular distances and position angles [deg].
197*
198* Returned:
199* lng,lat double[] Spherical coordinates of the field points [deg].
200* These may refer to the same storage as dist and pa
201* respectively.
202*
203* Function return value:
204* int Status return value:
205* 0: Success.
206*
207* Notes:
208* 1: sphpad() is implemented analogously to sphdpa() although using sphx2s()
209* for the inverse transformation. In particular, when the reference
210* point is at one of the poles, "position angle" is interpreted as though
211* the reference point was at (lng0,+90-epsilon) or (lng0,-90+epsilon), in
212* the limit as epsilon goes to zero.
213*
214* Applying sphpad() with the distances and position angles computed by
215* sphdpa() should return the original field points.
216*
217*===========================================================================*/
218
219#ifndef WCSLIB_SPH
220#define WCSLIB_SPH
221
222#ifdef __cplusplus
223 extern "C" {
224#endif
225
226
227 int sphx2s(const double eul[5], int nphi, int ntheta, int spt, int sxy,
228 const double phi[], const double theta[],
229 double lng[], double lat[]);
230
231 int sphs2x(const double eul[5], int nlng, int nlat, int sll , int spt,
232 const double lng[], const double lat[],
233 double phi[], double theta[]);
234
235 int sphdpa(int nfield, double lng0, double lat0,
236 const double lng[], const double lat[],
237 double dist[], double pa[]);
238
239 int sphpad(int nfield, double lng0, double lat0,
240 const double dist[], const double pa[],
241 double lng[], double lat[]);
242
243
244#ifdef __cplusplus
245}
246#endif
247
248#endif // WCSLIB_SPH
sphs2x
int sphs2x(const double eul[5], int nlng, int nlat, int sll, int spt, const double lng[], const double lat[], double phi[], double theta[])
Rotation in the world-to-pixel direction.
sphpad
int sphpad(int nfield, double lng0, double lat0, const double dist[], const double pa[], double lng[], double lat[])
Compute field points offset from a given point.
sphx2s
int sphx2s(const double eul[5], int nphi, int ntheta, int spt, int sxy, const double phi[], const double theta[], double lng[], double lat[])
Rotation in the pixel-to-world direction.
sphdpa
int sphdpa(int nfield, double lng0, double lat0, const double lng[], const double lat[], double dist[], double pa[])
Compute angular distance and position angle.