WCSLIB: sph.h Source File

WCSLIB 5.19.1

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