wcslib (8.2.2)
1 /*============================================================================
2 WCSLIB 8.2 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2023, 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.2.1.1 2023/11/16 10:05:57 mcalabre Exp mcalabre $
23 *=============================================================================
24 *
25 * WCSLIB 8.2 - 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
Browse
Usage
Versions