WCSLIB 4.8.2: sph.h Source File

- Main Page
- Related Pages
- Data Structures
- Files

# sph.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.8 - 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.8.1.1 2011/08/15 08:07:06 cal103 Exp cal103 $
    00032 *=============================================================================
    00033 *
    00034 * WCSLIB 4.8 - 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 */