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