00001 /*============================================================================ 00002 00003 WCSLIB 4.17 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2013, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see http://www.gnu.org/licenses. 00020 00021 Direct correspondence concerning WCSLIB to mark@calabretta.id.au 00022 00023 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO. 00024 http://www.atnf.csiro.au/people/Mark.Calabretta 00025 $Id: sph.h,v 4.17 2013/01/29 05:29:20 cal103 Exp $ 00026 *============================================================================= 00027 * 00028 * WCSLIB 4.17 - C routines that implement the spherical coordinate 00029 * transformations used by the FITS World Coordinate System (WCS) standard. 00030 * Refer to 00031 * 00032 * "Representations of world coordinates in FITS", 00033 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I) 00034 * 00035 * "Representations of celestial coordinates in FITS", 00036 * Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II) 00037 * 00038 * Refer to the README file provided with WCSLIB for an overview of the 00039 * library. 00040 * 00041 * 00042 * Summary of the sph routines 00043 * --------------------------- 00044 * The WCS spherical coordinate transformations are implemented via separate 00045 * functions, sphx2s() and sphs2x(), for the transformation in each direction. 00046 * 00047 * A utility function, sphdpa(), computes the angular distances and position 00048 * angles from a given point on the sky to a number of other points. sphpad() 00049 * does the complementary operation - computes the coordinates of points offset 00050 * by the given angular distances and position angles from a given point on the 00051 * sky. 00052 * 00053 * 00054 * sphx2s() - Rotation in the pixel-to-world direction 00055 * --------------------------------------------------- 00056 * sphx2s() transforms native coordinates of a projection to celestial 00057 * coordinates. 00058 * 00059 * Given: 00060 * eul const double[5] 00061 * Euler angles for the transformation: 00062 * 0: Celestial longitude of the native pole [deg]. 00063 * 1: Celestial colatitude of the native pole, or 00064 * native colatitude of the celestial pole [deg]. 00065 * 2: Native longitude of the celestial pole [deg]. 00066 * 3: cos(eul[1]) 00067 * 4: sin(eul[1]) 00068 * 00069 * nphi, 00070 * ntheta int Vector lengths. 00071 * 00072 * spt,sxy int Vector strides. 00073 * 00074 * phi,theta const double[] 00075 * Longitude and latitude in the native coordinate 00076 * system of the projection [deg]. 00077 * 00078 * Returned: 00079 * lng,lat double[] Celestial longitude and latitude [deg]. These may 00080 * refer to the same storage as phi and theta 00081 * respectively. 00082 * 00083 * Function return value: 00084 * int Status return value: 00085 * 0: Success. 00086 * 00087 * 00088 * sphs2x() - Rotation in the world-to-pixel direction 00089 * --------------------------------------------------- 00090 * sphs2x() transforms celestial coordinates to the native coordinates of a 00091 * projection. 00092 * 00093 * Given: 00094 * eul const double[5] 00095 * Euler angles for the transformation: 00096 * 0: Celestial longitude of the native pole [deg]. 00097 * 1: Celestial colatitude of the native pole, or 00098 * native colatitude of the celestial pole [deg]. 00099 * 2: Native longitude of the celestial pole [deg]. 00100 * 3: cos(eul[1]) 00101 * 4: sin(eul[1]) 00102 * 00103 * nlng,nlat int Vector lengths. 00104 * 00105 * sll,spt int Vector strides. 00106 * 00107 * lng,lat const double[] 00108 * Celestial longitude and latitude [deg]. 00109 * 00110 * Returned: 00111 * phi,theta double[] Longitude and latitude in the native coordinate system 00112 * of the projection [deg]. These may refer to the same 00113 * storage as lng and lat respectively. 00114 * 00115 * Function return value: 00116 * int Status return value: 00117 * 0: Success. 00118 * 00119 * 00120 * sphdpa() - Compute angular distance and position angle 00121 * ------------------------------------------------------ 00122 * sphdpa() computes the angular distance and generalized position angle (see 00123 * notes) from a "reference" point to a number of "field" points on the sphere. 00124 * The points must be specified consistently in any spherical coordinate 00125 * system. 00126 * 00127 * sphdpa() is complementary to sphpad(). 00128 * 00129 * Given: 00130 * nfield int The number of field points. 00131 * 00132 * lng0,lat0 double Spherical coordinates of the reference point [deg]. 00133 * 00134 * lng,lat const double[] 00135 * Spherical coordinates of the field points [deg]. 00136 * 00137 * Returned: 00138 * dist,pa double[] Angular distances and position angles [deg]. These 00139 * may refer to the same storage as lng and lat 00140 * respectively. 00141 * 00142 * Function return value: 00143 * int Status return value: 00144 * 0: Success. 00145 * 00146 * Notes: 00147 * sphdpa() uses sphs2x() to rotate coordinates so that the reference point 00148 * is at the north pole of the new system with the north pole of the old 00149 * system at zero longitude in the new. The Euler angles required by 00150 * sphs2x() for this rotation are 00151 * 00152 = eul[0] = lng0; 00153 = eul[1] = 90.0 - lat0; 00154 = eul[2] = 0.0; 00155 * 00156 * The angular distance and generalized position angle are readily obtained 00157 * from the longitude and latitude of the field point in the new system. 00158 * This applies even if the reference point is at one of the poles, in which 00159 * case the "position angle" returned is as would be computed for a reference 00160 * point at (lng0,+90-epsilon) or (lng0,-90+epsilon), in the limit as epsilon 00161 * goes to zero. 00162 * 00163 * It is evident that the coordinate system in which the two points are 00164 * expressed is irrelevant to the determination of the angular separation 00165 * between the points. However, this is not true of the generalized position 00166 * angle. 00167 * 00168 * The generalized position angle is here defined as the angle of 00169 * intersection of the great circle containing the reference and field points 00170 * with that containing the reference point and the pole. It has its normal 00171 * meaning when the the reference and field points are specified in 00172 * equatorial coordinates (right ascension and declination). 00173 * 00174 * Interchanging the reference and field points changes the position angle in 00175 * a non-intuitive way (because the sum of the angles of a spherical triangle 00176 * normally exceeds 180 degrees). 00177 * 00178 * The position angle is undefined if the reference and field points are 00179 * coincident or antipodal. This may be detected by checking for a distance 00180 * of 0 or 180 degrees (within rounding tolerance). sphdpa() will return an 00181 * arbitrary position angle in such circumstances. 00182 * 00183 * 00184 * sphpad() - Compute field points offset from a given point 00185 * --------------------------------------------------------- 00186 * sphpad() computes the coordinates of a set of points that are offset by the 00187 * specified angular distances and position angles from a given "reference" 00188 * point on the sky. The distances and position angles must be specified 00189 * consistently in any spherical coordinate system. 00190 * 00191 * sphpad() is complementary to sphdpa(). 00192 * 00193 * Given: 00194 * nfield int The number of field points. 00195 * 00196 * lng0,lat0 double Spherical coordinates of the reference point [deg]. 00197 * 00198 * dist,pa const double[] 00199 * Angular distances and position angles [deg]. 00200 * 00201 * Returned: 00202 * lng,lat double[] Spherical coordinates of the field points [deg]. 00203 * These may refer to the same storage as dist and pa 00204 * respectively. 00205 * 00206 * Function return value: 00207 * int Status return value: 00208 * 0: Success. 00209 * 00210 * Notes: 00211 * sphpad() is implemented analogously to sphdpa() although using sphx2s() 00212 * for the inverse transformation. In particular, when the reference point 00213 * is at one of the poles, "position angle" is interpreted as though the 00214 * reference point was at (lng0,+90-epsilon) or (lng0,-90+epsilon), in the 00215 * limit as epsilon goes to zero. 00216 * 00217 * Applying sphpad() with the distances and position angles computed by 00218 * sphdpa() should return the original field points. 00219 * 00220 *===========================================================================*/ 00221 00222 #ifndef WCSLIB_SPH 00223 #define WCSLIB_SPH 00224 00225 #ifdef __cplusplus 00226 extern "C" { 00227 #endif 00228 00229 00230 int sphx2s(const double eul[5], int nphi, int ntheta, int spt, int sxy, 00231 const double phi[], const double theta[], 00232 double lng[], double lat[]); 00233 00234 int sphs2x(const double eul[5], int nlng, int nlat, int sll , int spt, 00235 const double lng[], const double lat[], 00236 double phi[], double theta[]); 00237 00238 int sphdpa(int nfield, double lng0, double lat0, 00239 const double lng[], const double lat[], 00240 double dist[], double pa[]); 00241 00242 int sphpad(int nfield, double lng0, double lat0, 00243 const double dist[], const double pa[], 00244 double lng[], double lat[]); 00245 00246 00247 #ifdef __cplusplus 00248 } 00249 #endif 00250 00251 #endif /* WCSLIB_SPH */