/Proj4/geocent.h

  1#ifndef GEOCENT_H
  2#define GEOCENT_H
  3
  4/***************************************************************************/
  5/* RSC IDENTIFIER:  GEOCENTRIC
  6 *
  7 * ABSTRACT
  8 *
  9 *    This component provides conversions between Geodetic coordinates (latitude,
 10 *    longitude in radians and height in meters) and Geocentric coordinates
 11 *    (X, Y, Z) in meters.
 12 *
 13 * ERROR HANDLING
 14 *
 15 *    This component checks parameters for valid values.  If an invalid value
 16 *    is found, the error code is combined with the current error code using 
 17 *    the bitwise or.  This combining allows multiple error codes to be
 18 *    returned. The possible error codes are:
 19 *
 20 *      GEOCENT_NO_ERROR        : No errors occurred in function
 21 *      GEOCENT_LAT_ERROR       : Latitude out of valid range
 22 *                                 (-90 to 90 degrees)
 23 *      GEOCENT_LON_ERROR       : Longitude out of valid range
 24 *                                 (-180 to 360 degrees)
 25 *      GEOCENT_A_ERROR         : Semi-major axis less than or equal to zero
 26 *      GEOCENT_B_ERROR         : Semi-minor axis less than or equal to zero
 27 *      GEOCENT_A_LESS_B_ERROR  : Semi-major axis less than semi-minor axis
 28 *
 29 *
 30 * REUSE NOTES
 31 *
 32 *    GEOCENTRIC is intended for reuse by any application that performs
 33 *    coordinate conversions between geodetic coordinates and geocentric
 34 *    coordinates.
 35 *    
 36 *
 37 * REFERENCES
 38 *    
 39 *    An Improved Algorithm for Geocentric to Geodetic Coordinate Conversion,
 40 *    Ralph Toms, February 1996  UCRL-JC-123138.
 41 *    
 42 *    Further information on GEOCENTRIC can be found in the Reuse Manual.
 43 *
 44 *    GEOCENTRIC originated from : U.S. Army Topographic Engineering Center
 45 *                                 Geospatial Information Division
 46 *                                 7701 Telegraph Road
 47 *                                 Alexandria, VA  22310-3864
 48 *
 49 * LICENSES
 50 *
 51 *    None apply to this component.
 52 *
 53 * RESTRICTIONS
 54 *
 55 *    GEOCENTRIC has no restrictions.
 56 *
 57 * ENVIRONMENT
 58 *
 59 *    GEOCENTRIC was tested and certified in the following environments:
 60 *
 61 *    1. Solaris 2.5 with GCC version 2.8.1
 62 *    2. Windows 95 with MS Visual C++ version 6
 63 *
 64 * MODIFICATIONS
 65 *
 66 *    Date              Description
 67 *    ----              -----------
 68 *
 69 *
 70 */
 71
 72
 73/***************************************************************************/
 74/*
 75 *                              DEFINES
 76 */
 77#define GEOCENT_NO_ERROR        0x0000
 78#define GEOCENT_LAT_ERROR       0x0001
 79#define GEOCENT_LON_ERROR       0x0002
 80#define GEOCENT_A_ERROR         0x0004
 81#define GEOCENT_B_ERROR         0x0008
 82#define GEOCENT_A_LESS_B_ERROR  0x0010
 83
 84
 85/***************************************************************************/
 86/*
 87 *                              FUNCTION PROTOTYPES
 88 */
 89
 90/* ensure proper linkage to c++ programs */
 91#ifdef __cplusplus
 92extern "C" {
 93#endif
 94
 95typedef struct 
 96{
 97    double Geocent_a;        /* Semi-major axis of ellipsoid in meters */
 98    double Geocent_b;        /* Semi-minor axis of ellipsoid           */
 99    double Geocent_a2;       /* Square of semi-major axis */
100    double Geocent_b2;       /* Square of semi-minor axis */
101    double Geocent_e2;       /* Eccentricity squared  */
102    double Geocent_ep2;      /* 2nd eccentricity squared */
103} GeocentricInfo;
104
105void pj_Init_Geocentric( GeocentricInfo *gi );
106long pj_Set_Geocentric_Parameters( GeocentricInfo *gi, 
107                                   double a, 
108                                   double b);
109
110/*
111 * The function Set_Geocentric_Parameters receives the ellipsoid parameters
112 * as inputs and sets the corresponding state variables.
113 *
114 *    a  : Semi-major axis, in meters.          (input)
115 *    b  : Semi-minor axis, in meters.          (input)
116 */
117
118
119void pj_Get_Geocentric_Parameters ( GeocentricInfo *gi,
120                                    double *a, 
121                                    double *b);
122
123/*
124 * The function Get_Geocentric_Parameters returns the ellipsoid parameters
125 * to be used in geocentric coordinate conversions.
126 *
127 *    a  : Semi-major axis, in meters.          (output)
128 *    b  : Semi-minor axis, in meters.          (output)
129 */
130
131
132long pj_Convert_Geodetic_To_Geocentric ( GeocentricInfo *gi,
133                                         double Latitude,
134                                         double Longitude,
135                                         double Height,
136                                         double *X,
137                                         double *Y,
138                                         double *Z);
139/*
140 * The function Convert_Geodetic_To_Geocentric converts geodetic coordinates
141 * (latitude, longitude, and height) to geocentric coordinates (X, Y, Z),
142 * according to the current ellipsoid parameters.
143 *
144 *    Latitude  : Geodetic latitude in radians                     (input)
145 *    Longitude : Geodetic longitude in radians                    (input)
146 *    Height    : Geodetic height, in meters                       (input)
147 *    X         : Calculated Geocentric X coordinate, in meters.   (output)
148 *    Y         : Calculated Geocentric Y coordinate, in meters.   (output)
149 *    Z         : Calculated Geocentric Z coordinate, in meters.   (output)
150 *
151 */
152
153
154void pj_Convert_Geocentric_To_Geodetic (GeocentricInfo *gi,
155                                        double X,
156                                        double Y, 
157                                        double Z,
158                                        double *Latitude,
159                                        double *Longitude,
160                                        double *Height);
161/*
162 * The function Convert_Geocentric_To_Geodetic converts geocentric
163 * coordinates (X, Y, Z) to geodetic coordinates (latitude, longitude, 
164 * and height), according to the current ellipsoid parameters.
165 *
166 *    X         : Geocentric X coordinate, in meters.         (input)
167 *    Y         : Geocentric Y coordinate, in meters.         (input)
168 *    Z         : Geocentric Z coordinate, in meters.         (input)
169 *    Latitude  : Calculated latitude value in radians.       (output)
170 *    Longitude : Calculated longitude value in radians.      (output)
171 *    Height    : Calculated height value, in meters.         (output)
172 */
173
174
175#ifdef __cplusplus
176}
177#endif
178
179#endif /* GEOCENT_H */