00001 /*============================================================================ 00002 00003 WCSLIB 4.7 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2011, 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.7 2011/02/07 07:03:42 cal103 Exp $ 00032 *============================================================================= 00033 * 00034 * WCSLIB 4.7 - 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 * nphi, 00075 * ntheta int Vector lengths. 00076 * spt,sxy int Vector strides. 00077 * phi,theta const double[] 00078 * Longitude and latitude in the native coordinate 00079 * system of the projection [deg]. 00080 * 00081 * Returned: 00082 * lng,lat double[] Celestial longitude and latitude [deg]. These may 00083 * refer to the same storage as phi and theta 00084 * respectively. 00085 * 00086 * Function return value: 00087 * int Status return value: 00088 * 0: Success. 00089 * 00090 * 00091 * sphs2x() - Rotation in the world-to-pixel direction 00092 * --------------------------------------------------- 00093 * sphs2x() transforms celestial coordinates to the native coordinates of a 00094 * projection. 00095 * 00096 * Given: 00097 * eul const double[5] 00098 * Euler angles for the transformation: 00099 * 0: Celestial longitude of the native pole [deg]. 00100 * 1: Celestial colatitude of the native pole, or 00101 * native colatitude of the celestial pole [deg]. 00102 * 2: Native longitude of the celestial pole [deg]. 00103 * 3: cos(eul[1]) 00104 * 4: sin(eul[1]) 00105 * nlng,nlat int Vector lengths. 00106 * sll,spt int Vector strides. 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 * lng0,lat0 double Spherical coordinates of the reference point [deg]. 00132 * lng,lat const double[] 00133 * Spherical coordinates of the field points [deg]. 00134 * 00135 * Returned: 00136 * dist,pa double[] Angular distances and position angles [deg]. These 00137 * may refer to the same storage as lng and lat 00138 * respectively. 00139 * 00140 * Function return value: 00141 * int Status return value: 00142 * 0: Success. 00143 * 00144 * Notes: 00145 * sphdpa() uses sphs2x() to rotate coordinates so that the reference point 00146 * is at the north pole of the new system with the north pole of the old 00147 * system at zero longitude in the new. The Euler angles required by 00148 * sphs2x() for this rotation are 00149 * 00150 = eul[0] = lng0; 00151 = eul[1] = 90.0 - lat0; 00152 = eul[2] = 0.0; 00153 * 00154 * The angular distance and generalized position angle are readily obtained 00155 * from the longitude and latitude of the field point in the new system. 00156 * This applies even if the reference point is at one of the poles, in which 00157 * case the "position angle" returned is as would be computed for a reference 00158 * point at (lng0,+90-epsilon) or (lng0,-90+epsilon), in the limit as epsilon 00159 * goes to zero. 00160 * 00161 * It is evident that the coordinate system in which the two points are 00162 * expressed is irrelevant to the determination of the angular separation 00163 * between the points. However, this is not true of the generalized position 00164 * angle. 00165 * 00166 * The generalized position angle is here defined as the angle of 00167 * intersection of the great circle containing the reference and field points 00168 * with that containing the reference point and the pole. It has its normal 00169 * meaning when the the reference and field points are specified in 00170 * equatorial coordinates (right ascension and declination). 00171 * 00172 * Interchanging the reference and field points changes the position angle in 00173 * a non-intuitive way (because the sum of the angles of a spherical triangle 00174 * normally exceeds 180 degrees). 00175 * 00176 * The position angle is undefined if the reference and field points are 00177 * coincident or antipodal. This may be detected by checking for a distance 00178 * of 0 or 180 degrees (within rounding tolerance). sphdpa() will return an 00179 * arbitrary position angle in such circumstances. 00180 * 00181 * 00182 * sphpad() - Compute field points offset from a given point 00183 * --------------------------------------------------------- 00184 * sphpad() computes the coordinates of a set of points that are offset by the 00185 * specified angular distances and position angles from a given "reference" 00186 * point on the sky. The distances and position angles must be specified 00187 * consistently in any spherical coordinate system. 00188 * 00189 * sphpad() is complementary to sphdpa(). 00190 * 00191 * Given: 00192 * nfield int The number of field points. 00193 * lng0,lat0 double Spherical coordinates of the reference point [deg]. 00194 * dist,pa const double[] 00195 * Angular distances and position angles [deg]. 00196 * 00197 * Returned: 00198 * lng,lat double[] Spherical coordinates of the field points [deg]. 00199 * These may refer to the same storage as dist and pa 00200 * respectively. 00201 * 00202 * Function return value: 00203 * int Status return value: 00204 * 0: Success. 00205 * 00206 * Notes: 00207 * sphpad() is implemented analogously to sphdpa() although using sphx2s() 00208 * for the inverse transformation. In particular, when the reference point 00209 * is at one of the poles, "position angle" is interpreted as though the 00210 * reference point was at (lng0,+90-epsilon) or (lng0,-90+epsilon), in the 00211 * limit as epsilon goes to zero. 00212 * 00213 * Applying sphpad() with the distances and position angles computed by 00214 * sphdpa() should return the original field points. 00215 * 00216 *===========================================================================*/ 00217 00218 #ifndef WCSLIB_SPH 00219 #define WCSLIB_SPH 00220 00221 #ifdef __cplusplus 00222 extern "C" { 00223 #endif 00224 00225 00226 int sphx2s(const double eul[5], int nphi, int ntheta, int spt, int sxy, 00227 const double phi[], const double theta[], 00228 double lng[], double lat[]); 00229 00230 int sphs2x(const double eul[5], int nlng, int nlat, int sll , int spt, 00231 const double lng[], const double lat[], 00232 double phi[], double theta[]); 00233 00234 int sphdpa(int nfield, double lng0, double lat0, 00235 const double lng[], const double lat[], 00236 double dist[], double pa[]); 00237 00238 int sphpad(int nfield, double lng0, double lat0, 00239 const double dist[], const double pa[], 00240 double lng[], double lat[]); 00241 00242 00243 #ifdef __cplusplus 00244 } 00245 #endif 00246 00247 #endif /* WCSLIB_SPH */