GPS4Palm

Source Code Documentation


utm.h

Go to the documentation of this file.
00001 #ifndef UTM_H
00002   #define UTM_H
00003 
00004 /***************************************************************************/
00005 /* RSC IDENTIFIER: UTM
00006  *
00007  * ABSTRACT
00008  *
00009  *    This component provides conversions between geodetic coordinates 
00010  *    (latitude and longitudes) and Universal Transverse Mercator (UTM)
00011  *    projection (zone, hemisphere, easting, and northing) coordinates.
00012  *
00013  * ERROR HANDLING
00014  *
00015  *    This component checks parameters for valid values.  If an invalid value
00016  *    is found, the error code is combined with the current error code using 
00017  *    the bitwise or.  This combining allows multiple error codes to be
00018  *    returned. The possible error codes are:
00019  *
00020  *          UTM_NO_ERROR           : No errors occurred in function
00021  *          UTM_LAT_ERROR          : Latitude outside of valid range
00022  *                                    (-80.5 to 84.5 degrees)
00023  *          UTM_LON_ERROR          : Longitude outside of valid range
00024  *                                    (-180 to 360 degrees)
00025  *          UTM_EASTING_ERROR      : Easting outside of valid range
00026  *                                    (100,000 to 900,000 meters)
00027  *          UTM_NORTHING_ERROR     : Northing outside of valid range
00028  *                                    (0 to 10,000,000 meters)
00029  *          UTM_ZONE_ERROR         : Zone outside of valid range (1 to 60)
00030  *          UTM_HEMISPHERE_ERROR   : Invalid hemisphere ('N' or 'S')
00031  *          UTM_ZONE_OVERRIDE_ERROR: Zone outside of valid range
00032  *                                    (1 to 60) and within 1 of 'natural' zone
00033  *          UTM_A_ERROR            : Semi-major axis less than or equal to zero
00034  *          UTM_INV_F_ERROR        : Inverse flattening outside of valid range
00035  *                                                                                      (250 to 350)
00036  *
00037  * REUSE NOTES
00038  *
00039  *    UTM is intended for reuse by any application that performs a Universal
00040  *    Transverse Mercator (UTM) projection or its inverse.
00041  *    
00042  * REFERENCES
00043  *
00044  *    Further information on UTM can be found in the Reuse Manual.
00045  *
00046  *    UTM originated from :  U.S. Army Topographic Engineering Center
00047  *                           Geospatial Information Division
00048  *                           7701 Telegraph Road
00049  *                           Alexandria, VA  22310-3864
00050  *
00051  * LICENSES
00052  *
00053  *    None apply to this component.
00054  *
00055  * RESTRICTIONS
00056  *
00057  *    UTM has no restrictions.
00058  *
00059  * ENVIRONMENT
00060  *
00061  *    UTM was tested and certified in the following environments:
00062  *
00063  *    1. Solaris 2.5 with GCC, version 2.8.1
00064  *    2. MSDOS with MS Visual C++, version 6
00065  *
00066  * MODIFICATIONS
00067  *
00068  *    Date              Description
00069  *    ----              -----------
00070  *    10-02-97          Original Code
00071  *
00072  */
00073 
00074 
00075 /***************************************************************************/
00076 /*
00077  *                              DEFINES
00078  */
00079 
00080   #define UTM_NO_ERROR            0x0000
00081   #define UTM_LAT_ERROR           0x0001
00082   #define UTM_LON_ERROR           0x0002
00083   #define UTM_EASTING_ERROR       0x0004
00084   #define UTM_NORTHING_ERROR      0x0008
00085   #define UTM_ZONE_ERROR          0x0010
00086   #define UTM_HEMISPHERE_ERROR    0x0020
00087   #define UTM_ZONE_OVERRIDE_ERROR 0x0040
00088   #define UTM_A_ERROR             0x0080
00089   #define UTM_INV_F_ERROR         0x0100
00090 
00091 #define UTM_SECTION   __attribute__ ((section ("geo")))
00092 
00093 /***************************************************************************/
00094 /*
00095  *                              FUNCTION PROTOTYPES
00096  *                                for UTM.C
00097  */
00098 
00099 /* ensure proper linkage to c++ programs */
00100   #ifdef __cplusplus
00101 extern "C" {
00102   #endif
00103 
00104   long Set_UTM_Parameters(double a,      
00105                           double f,
00106                           long   override) UTM_SECTION;
00107 /*
00108  * The function Set_UTM_Parameters receives the ellipsoid parameters and
00109  * UTM zone override parameter as inputs, and sets the corresponding state
00110  * variables.  If any errors occur, the error code(s) are returned by the 
00111  * function, otherwise UTM_NO_ERROR is returned.
00112  *
00113  *    a                 : Semi-major axis of ellipsoid, in meters       (input)
00114  *    f                 : Flattening of ellipsoid                       (input)
00115  *    override          : UTM override zone, zero indicates no override (input)
00116  */
00117 
00118 
00119   void Get_UTM_Parameters(double *a,
00120                           double *f,
00121                           long   *override) UTM_SECTION;
00122 /*
00123  * The function Get_UTM_Parameters returns the current ellipsoid
00124  * parameters and UTM zone override parameter.
00125  *
00126  *    a                 : Semi-major axis of ellipsoid, in meters       (output)
00127  *    f                 : Flattening of ellipsoid                       (output)
00128  *    override          : UTM override zone, zero indicates no override (output)
00129  */
00130 
00131 
00132   long Convert_Geodetic_To_UTM (double Latitude,
00133                                 double Longitude,
00134                                 long   *Zone,
00135                                 char   *Hemisphere,
00136                                 double *Easting,
00137                                 double *Northing) UTM_SECTION; 
00138 /*
00139  * The function Convert_Geodetic_To_UTM converts geodetic (latitude and
00140  * longitude) coordinates to UTM projection (zone, hemisphere, easting and
00141  * northing) coordinates according to the current ellipsoid and UTM zone
00142  * override parameters.  If any errors occur, the error code(s) are returned
00143  * by the function, otherwise UTM_NO_ERROR is returned.
00144  *
00145  *    Latitude          : Latitude in radians                 (input)
00146  *    Longitude         : Longitude in radians                (input)
00147  *    Zone              : UTM zone                            (output)
00148  *    Hemisphere        : North or South hemisphere           (output)
00149  *    Easting           : Easting (X) in meters               (output)
00150  *    Northing          : Northing (Y) in meters              (output)
00151  */
00152 
00153 
00154   long Convert_UTM_To_Geodetic(long   Zone,
00155                                char   Hemisphere,
00156                                double Easting,
00157                                double Northing,
00158                                double *Latitude,
00159                                double *Longitude) UTM_SECTION;
00160 /*
00161  * The function Convert_UTM_To_Geodetic converts UTM projection (zone, 
00162  * hemisphere, easting and northing) coordinates to geodetic(latitude
00163  * and  longitude) coordinates, according to the current ellipsoid
00164  * parameters.  If any errors occur, the error code(s) are returned
00165  * by the function, otherwise UTM_NO_ERROR is returned.
00166  *
00167  *    Zone              : UTM zone                               (input)
00168  *    Hemisphere        : North or South hemisphere              (input)
00169  *    Easting           : Easting (X) in meters                  (input)
00170  *    Northing          : Northing (Y) in meters                 (input)
00171  *    Latitude          : Latitude in radians                    (output)
00172  *    Longitude         : Longitude in radians                   (output)
00173  */
00174 
00175   #ifdef __cplusplus
00176 }
00177   #endif
00178 
00179 #endif /* UTM_H */

Created: Mon, 08 Oct 2007 22:33:16 +0200
Copyright ©2004 M. Prinke