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