- Main Page
- Related Pages
- Data Structures
- Files

# cel.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.13 - 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: cel.h,v 4.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $
    00032 *=============================================================================
    00033 *
    00034 * WCSLIB 4.13 - C routines that implement the FITS World Coordinate System
    00035 * (WCS) standard.  Refer to
    00036 *
    00037 *   "Representations of world coordinates in FITS",
    00038 *   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
    00039 *
    00040 *   "Representations of celestial coordinates in FITS",
    00041 *   Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (Paper II)
    00042 *
    00043 * Refer to the README file provided with WCSLIB for an overview of the
    00044 * library.
    00045 *
    00046 *
    00047 * Summary of the cel routines
    00048 * ---------------------------
    00049 * These routines implement the part of the FITS World Coordinate System (WCS)
    00050 * standard that deals with celestial coordinates.  They define methods to be
    00051 * used for computing celestial world coordinates from intermediate world
    00052 * coordinates (a linear transformation of image pixel coordinates), and vice
    00053 * versa.  They are based on the celprm struct which contains all information
    00054 * needed for the computations.  This struct contains some elements that must
    00055 * be set by the user, and others that are maintained by these routines,
    00056 * somewhat like a C++ class but with no encapsulation.
    00057 *
    00058 * Routine celini() is provided to initialize the celprm struct with default
    00059 * values, celfree() reclaims any memory that may have been allocated to store
    00060 * an error message, and celprt() prints its contents.
    00061 *
    00062 * A setup routine, celset(), computes intermediate values in the celprm struct
    00063 * from parameters in it that were supplied by the user.  The struct always
    00064 * needs to be set up by celset() but it need not be called explicitly - refer
    00065 * to the explanation of celprm::flag.
    00066 *
    00067 * celx2s() and cels2x() implement the WCS celestial coordinate
    00068 * transformations.  In fact, they are high level driver routines for the lower
    00069 * level spherical coordinate rotation and projection routines described in
    00070 * sph.h and prj.h.
    00071 *
    00072 *
    00073 * celini() - Default constructor for the celprm struct
    00074 * ----------------------------------------------------
    00075 * celini() sets all members of a celprm struct to default values.  It should
    00076 * be used to initialize every celprm struct.
    00077 *
    00078 * Returned:
    00079 *   cel       struct celprm*
    00080 *                       Celestial transformation parameters.
    00081 *
    00082 * Function return value:
    00083 *             int       Status return value:
    00084 *                         0: Success.
    00085 *                         1: Null celprm pointer passed.
    00086 *
    00087 *
    00088 * celfree() - Destructor for the celprm struct
    00089 * --------------------------------------------
    00090 * celfree() frees any memory that may have been allocated to store an error
    00091 * message in the celprm struct.
    00092 *
    00093 * Given:
    00094 *   cel       struct celprm*
    00095 *                       Celestial transformation parameters.
    00096 *
    00097 * Function return value:
    00098 *             int       Status return value:
    00099 *                         0: Success.
    00100 *                         1: Null celprm pointer passed.
    00101 *
    00102 *
    00103 * celprt() - Print routine for the celprm struct
    00104 * ----------------------------------------------
    00105 * celprt() prints the contents of a celprm struct using wcsprintf().  Mainly
    00106 * intended for diagnostic purposes.
    00107 *
    00108 * Given:
    00109 *   cel       const struct celprm*
    00110 *                       Celestial transformation parameters.
    00111 *
    00112 * Function return value:
    00113 *             int       Status return value:
    00114 *                         0: Success.
    00115 *                         1: Null celprm pointer passed.
    00116 *
    00117 *
    00118 * celset() - Setup routine for the celprm struct
    00119 * ----------------------------------------------
    00120 * celset() sets up a celprm struct according to information supplied within
    00121 * it.
    00122 *
    00123 * Note that this routine need not be called directly; it will be invoked by
    00124 * celx2s() and cels2x() if celprm::flag is anything other than a predefined
    00125 * magic value.
    00126 *
    00127 * Given and returned:
    00128 *   cel       struct celprm*
    00129 *                       Celestial transformation parameters.
    00130 *
    00131 * Function return value:
    00132 *             int       Status return value:
    00133 *                         0: Success.
    00134 *                         1: Null celprm pointer passed.
    00135 *                         2: Invalid projection parameters.
    00136 *                         3: Invalid coordinate transformation parameters.
    00137 *                         4: Ill-conditioned coordinate transformation
    00138 *                            parameters.
    00139 *
    00140 *                       For returns > 1, a detailed error message is set in
    00141 *                       celprm::err if enabled, see wcserr_enable().
    00142 *
    00143 *
    00144 * celx2s() - Pixel-to-world celestial transformation
    00145 * --------------------------------------------------
    00146 * celx2s() transforms (x,y) coordinates in the plane of projection to
    00147 * celestial coordinates (lng,lat).
    00148 *
    00149 * Given and returned:
    00150 *   cel       struct celprm*
    00151 *                       Celestial transformation parameters.
    00152 *
    00153 * Given:
    00154 *   nx,ny     int       Vector lengths.
    00155 *
    00156 *   sxy,sll   int       Vector strides.
    00157 *
    00158 *   x,y       const double[]
    00159 *                       Projected coordinates in pseudo "degrees".
    00160 *
    00161 * Returned:
    00162 *   phi,theta double[]  Longitude and latitude (phi,theta) in the native
    00163 *                       coordinate system of the projection [deg].
    00164 *
    00165 *   lng,lat   double[]  Celestial longitude and latitude (lng,lat) of the
    00166 *                       projected point [deg].
    00167 *
    00168 *   stat      int[]     Status return value for each vector element:
    00169 *                         0: Success.
    00170 *                         1: Invalid value of (x,y).
    00171 *
    00172 * Function return value:
    00173 *             int       Status return value:
    00174 *                         0: Success.
    00175 *                         1: Null celprm pointer passed.
    00176 *                         2: Invalid projection parameters.
    00177 *                         3: Invalid coordinate transformation parameters.
    00178 *                         4: Ill-conditioned coordinate transformation
    00179 *                            parameters.
    00180 *                         5: One or more of the (x,y) coordinates were
    00181 *                            invalid, as indicated by the stat vector.
    00182 *
    00183 *                       For returns > 1, a detailed error message is set in
    00184 *                       celprm::err if enabled, see wcserr_enable().
    00185 *
    00186 *
    00187 * cels2x() - World-to-pixel celestial transformation
    00188 * --------------------------------------------------
    00189 * cels2x() transforms celestial coordinates (lng,lat) to (x,y) coordinates in
    00190 * the plane of projection.
    00191 *
    00192 * Given and returned:
    00193 *   cel       struct celprm*
    00194 *                       Celestial transformation parameters.
    00195 *
    00196 * Given:
    00197 *   nlng,nlat int       Vector lengths.
    00198 *
    00199 *   sll,sxy   int       Vector strides.
    00200 *
    00201 *   lng,lat   const double[]
    00202 *                       Celestial longitude and latitude (lng,lat) of the
    00203 *                       projected point [deg].
    00204 *
    00205 * Returned:
    00206 *   phi,theta double[]  Longitude and latitude (phi,theta) in the native
    00207 *                       coordinate system of the projection [deg].
    00208 *
    00209 *   x,y       double[]  Projected coordinates in pseudo "degrees".
    00210 *
    00211 *   stat      int[]     Status return value for each vector element:
    00212 *                         0: Success.
    00213 *                         1: Invalid value of (lng,lat).
    00214 *
    00215 * Function return value:
    00216 *             int       Status return value:
    00217 *                         0: Success.
    00218 *                         1: Null celprm pointer passed.
    00219 *                         2: Invalid projection parameters.
    00220 *                         3: Invalid coordinate transformation parameters.
    00221 *                         4: Ill-conditioned coordinate transformation
    00222 *                            parameters.
    00223 *                         6: One or more of the (lng,lat) coordinates were
    00224 *                            invalid, as indicated by the stat vector.
    00225 *
    00226 *                       For returns > 1, a detailed error message is set in
    00227 *                       celprm::err if enabled, see wcserr_enable().
    00228 *
    00229 *
    00230 * celprm struct - Celestial transformation parameters
    00231 * ---------------------------------------------------
    00232 * The celprm struct contains information required to transform celestial
    00233 * coordinates.  It consists of certain members that must be set by the user
    00234 * ("given") and others that are set by the WCSLIB routines ("returned").  Some
    00235 * of the latter are supplied for informational purposes and others are for
    00236 * internal use only.
    00237 *
    00238 * Returned celprm struct members must not be modified by the user.
    00239 *
    00240 *   int flag
    00241 *     (Given and returned) This flag must be set to zero whenever any of the
    00242 *     following celprm struct members are set or changed:
    00243 *
    00244 *       - celprm::offset,
    00245 *       - celprm::phi0,
    00246 *       - celprm::theta0,
    00247 *       - celprm::ref[4],
    00248 *       - celprm::prj:
    00249 *         - prjprm::code,
    00250 *         - prjprm::r0,
    00251 *         - prjprm::pv[],
    00252 *         - prjprm::phi0,
    00253 *         - prjprm::theta0.
    00254 *
    00255 *     This signals the initialization routine, celset(), to recompute the
    00256 *     returned members of the celprm struct.  celset() will reset flag to
    00257 *     indicate that this has been done.
    00258 *
    00259 *   int offset
    00260 *     (Given) If true (non-zero), an offset will be applied to (x,y) to
    00261 *     force (x,y) = (0,0) at the fiducial point, (phi_0,theta_0).
    00262 *     Default is 0 (false).
    00263 *
    00264 *   double phi0
    00265 *     (Given) The native longitude, phi_0 [deg], and ...
    00266 *
    00267 *   double theta0
    00268 *     (Given) ... the native latitude, theta_0 [deg], of the fiducial point,
    00269 *     i.e. the point whose celestial coordinates are given in
    00270 *     celprm::ref[1:2].  If undefined (set to a magic value by prjini()) the
    00271 *     initialization routine, celset(), will set this to a projection-specific
    00272 *     default.
    00273 *
    00274 *   double ref[4]
    00275 *     (Given) The first pair of values should be set to the celestial
    00276 *     longitude and latitude of the fiducial point [deg] - typically right
    00277 *     ascension and declination.  These are given by the CRVALia keywords in
    00278 *     FITS.
    00279 *
    00280 *     (Given and returned) The second pair of values are the native longitude,
    00281 *     phi_p [deg], and latitude, theta_p [deg], of the celestial pole (the
    00282 *     latter is the same as the celestial latitude of the native pole,
    00283 *     delta_p) and these are given by the FITS keywords LONPOLEa and LATPOLEa
    00284 *     (or by PVi_2a and PVi_3a attached to the longitude axis which take
    00285 *     precedence if defined).
    00286 *
    00287 *     LONPOLEa defaults to phi_0 (see above) if the celestial latitude of the
    00288 *     fiducial point of the projection is greater than or equal to the native
    00289 *     latitude, otherwise phi_0 + 180 [deg].  (This is the condition for the
    00290 *     celestial latitude to increase in the same direction as the native
    00291 *     latitude at the fiducial point.)  ref[2] may be set to UNDEFINED (from
    00292 *     wcsmath.h) or 999.0 to indicate that the correct default should be
    00293 *     substituted.
    00294 *
    00295 *     theta_p, the native latitude of the celestial pole (or equally the
    00296 *     celestial latitude of the native pole, delta_p) is often determined
    00297 *     uniquely by CRVALia and LONPOLEa in which case LATPOLEa is ignored.
    00298 *     However, in some circumstances there are two valid solutions for theta_p
    00299 *     and LATPOLEa is used to choose between them.  LATPOLEa is set in ref[3]
    00300 *     and the solution closest to this value is used to reset ref[3].  It is
    00301 *     therefore legitimate, for example, to set ref[3] to +90.0 to choose the
    00302 *     more northerly solution - the default if the LATPOLEa keyword is omitted
    00303 *     from the FITS header.  For the special case where the fiducial point of
    00304 *     the projection is at native latitude zero, its celestial latitude is
    00305 *     zero, and LONPOLEa = +/- 90.0 then the celestial latitude of the native
    00306 *     pole is not determined by the first three reference values and LATPOLEa
    00307 *     specifies it completely.
    00308 *
    00309 *     The returned value, celprm::latpreq, specifies how LATPOLEa was actually
    00310 *     used.
    00311 *
    00312 *   struct prjprm prj
    00313 *     (Given and returned) Projection parameters described in the prologue to
    00314 *     prj.h.
    00315 *
    00316 *   double euler[5]
    00317 *     (Returned) Euler angles and associated intermediaries derived from the
    00318 *     coordinate reference values.  The first three values are the Z-, X-, and
    00319 *     Z'-Euler angles [deg], and the remaining two are the cosine and sine of
    00320 *     the X-Euler angle.
    00321 *
    00322 *   int latpreq
    00323 *     (Returned) For informational purposes, this indicates how the LATPOLEa
    00324 *     keyword was used
    00325 *       - 0: Not required, theta_p (== delta_p) was determined uniquely by the
    00326 *            CRVALia and LONPOLEa keywords.
    00327 *       - 1: Required to select between two valid solutions of theta_p.
    00328 *       - 2: theta_p was specified solely by LATPOLEa.
    00329 *
    00330 *   int isolat
    00331 *     (Returned) True if the spherical rotation preserves the magnitude of the
    00332 *     latitude, which occurs iff the axes of the native and celestial
    00333 *     coordinates are coincident.  It signals an opportunity to cache
    00334 *     intermediate calculations common to all elements in a vector
    00335 *     computation.
    00336 *
    00337 *   struct wcserr *err
    00338 *     (Returned) If enabled, when an error status is returned this struct
    00339 *     contains detailed information about the error, see wcserr_enable().
    00340 *
    00341 *   void *padding
    00342 *     (An unused variable inserted for alignment purposes only.)
    00343 *
    00344 * Global variable: const char *cel_errmsg[] - Status return messages
    00345 * ------------------------------------------------------------------
    00346 * Status messages to match the status value returned from each function.
    00347 *
    00348 *===========================================================================*/
    00349
    00350 #ifndef WCSLIB_CEL
    00351 #define WCSLIB_CEL
    00352
    00353 #include "prj.h"
    00354 #include "wcserr.h"
    00355
    00356 #ifdef __cplusplus
    00357 extern "C" {
    00358 #endif
    00359
    00360
    00361 extern const char *cel_errmsg[];
    00362
    00363 enum cel_errmsg_enum {
    00364   CELERR_SUCCESS         = 0,   /* Success. */
    00365   CELERR_NULL_POINTER    = 1,   /* Null celprm pointer passed. */
    00366   CELERR_BAD_PARAM       = 2,   /* Invalid projection parameters. */
    00367   CELERR_BAD_COORD_TRANS = 3,   /* Invalid coordinate transformation
    00368                                    parameters. */
    00369   CELERR_ILL_COORD_TRANS = 4,   /* Ill-conditioned coordinated transformation
    00370                                    parameters. */
    00371   CELERR_BAD_PIX         = 5,   /* One or more of the (x,y) coordinates were
    00372                                    invalid. */
    00373   CELERR_BAD_WORLD       = 6    /* One or more of the (lng,lat) coordinates
    00374                                    were invalid. */
    00375 };
    00376
    00377 struct celprm {
    00378   /* Initialization flag (see the prologue above).                          */
    00379   /*------------------------------------------------------------------------*/
    00380   int    flag;                  /* Set to zero to force initialization.     */
    00381
    00382   /* Parameters to be provided (see the prologue above).                    */
    00383   /*------------------------------------------------------------------------*/
    00384   int    offset;                /* Force (x,y) = (0,0) at (phi_0,theta_0).  */
    00385   double phi0, theta0;          /* Native coordinates of fiducial point.    */
    00386   double ref[4];                /* Celestial coordinates of fiducial        */
    00387                                 /* point and native coordinates of          */
    00388                                 /* celestial pole.                          */
    00389
    00390   struct prjprm prj;            /* Projection parameters (see prj.h).       */
    00391
    00392   /* Information derived from the parameters supplied.                      */
    00393   /*------------------------------------------------------------------------*/
    00394   double euler[5];              /* Euler angles and functions thereof.      */
    00395   int    latpreq;               /* LATPOLEa requirement.                    */
    00396   int    isolat;                /* True if |latitude| is preserved.         */
    00397
    00398   /* Error handling                                                         */
    00399   /*------------------------------------------------------------------------*/
    00400   struct wcserr *err;
    00401
    00402   /* Private                                                                */
    00403   /*------------------------------------------------------------------------*/
    00404   void   *padding;              /* (Dummy inserted for alignment purposes.) */
    00405 };
    00406
    00407 /* Size of the celprm struct in int units, used by the Fortran wrappers. */
    00408 #define CELLEN (sizeof(struct celprm)/sizeof(int))
    00409
    00410
    00411 int celini(struct celprm *cel);
    00412
    00413 int celfree(struct celprm *cel);
    00414
    00415 int celprt(const struct celprm *cel);
    00416
    00417 int celset(struct celprm *cel);
    00418
    00419 int celx2s(struct celprm *cel, int nx, int ny, int sxy, int sll,
    00420            const double x[], const double y[],
    00421            double phi[], double theta[], double lng[], double lat[],
    00422            int stat[]);
    00423
    00424 int cels2x(struct celprm *cel, int nlng, int nlat, int sll, int sxy,
    00425            const double lng[], const double lat[],
    00426            double phi[], double theta[], double x[], double y[],
    00427            int stat[]);
    00428
    00429
    00430 /* Deprecated. */
    00431 #define celini_errmsg cel_errmsg
    00432 #define celprt_errmsg cel_errmsg
    00433 #define celset_errmsg cel_errmsg
    00434 #define celx2s_errmsg cel_errmsg
    00435 #define cels2x_errmsg cel_errmsg
    00436
    00437 #ifdef __cplusplus
    00438 }
    00439 #endif
    00440
    00441 #endif /* WCSLIB_CEL */