WCSLIB 4.20
sph.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 4.20 - an implementation of the FITS WCS standard.
4  Copyright (C) 1995-2013, 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_8h_source.html,v 1.1 2014/02/12 21:11:37 irby Exp $
26 *=============================================================================
27 *
28 * WCSLIB 4.20 - C routines that implement the spherical coordinate
29 * transformations used by the FITS World Coordinate System (WCS) standard.
30 * Refer to
31 *
32 * "Representations of world coordinates in FITS",
33 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
34 *
35 * "Representations of celestial coordinates in FITS",
36 * Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II)
37 *
38 * Refer to the README file provided with WCSLIB for an overview of the
39 * library.
40 *
41 *
42 * Summary of the sph routines
43 * ---------------------------
44 * The WCS spherical coordinate transformations are implemented via separate
45 * functions, sphx2s() and sphs2x(), for the transformation 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 */
Generated on Wed Dec 18 2013 16:43:14 for WCSLIB 4.20 by   doxygen 1.8.4