- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

# Y:/msp/devkits/temp_geotrans/master/geotrans3.1/CCS/src/dtcc/CoordinateSystems/usng/USNG.h

Go to the documentation of this file.

    00001 // CLASSIFICATION: UNCLASSIFIED
    00002
    00003 #ifndef USNG_H
    00004 #define USNG_H
    00005
    00006 /***************************************************************************/
    00007 /* RSC IDENTIFIER:  USNG
    00008  *
    00009  * ABSTRACT
    00010  *
    00011  *    This component converts between geodetic coordinates (latitude and
    00012  *    longitude) and United States National Grid (USNG) coordinates.
    00013  *
    00014  * ERROR HANDLING
    00015  *
    00016  *    This component checks parameters for valid values.  If an invalid value
    00017  *    is found, the error code is combined with the current error code using
    00018  *    the bitwise or.  This combining allows multiple error codes to be
    00019  *    returned. The possible error codes are:
    00020  *
    00021  *          USNG_NO_ERROR          : No errors occurred in function
    00022  *          USNG_LAT_ERROR         : Latitude outside of valid range
    00023  *                                    (-90 to 90 degrees)
    00024  *          USNG_LON_ERROR         : Longitude outside of valid range
    00025  *                                    (-180 to 360 degrees)
    00026  *          USNG_STR_ERROR         : An USNG string error: string too long,
    00027  *                                    too short, or badly formed
    00028  *          USNG_PRECISION_ERROR   : The precision must be between 0 and 5
    00029  *                                    inclusive.
    00030  *          USNG_A_ERROR           : Semi-major axis less than or equal to zero
    00031  *          USNG_INV_F_ERROR       : Inverse flattening outside of valid range
    00032  *                                    (250 to 350)
    00033  *          USNG_EASTING_ERROR     : Easting outside of valid range
    00034  *                                    (100,000 to 900,000 meters for UTM)
    00035  *                                    (0 to 4,000,000 meters for UPS)
    00036  *          USNG_NORTHING_ERROR    : Northing outside of valid range
    00037  *                                    (0 to 10,000,000 meters for UTM)
    00038  *                                    (0 to 4,000,000 meters for UPS)
    00039  *          USNG_ZONE_ERROR        : Zone outside of valid range (1 to 60)
    00040  *          USNG_HEMISPHERE_ERROR  : Invalid hemisphere ('N' or 'S')
    00041  *
    00042  * REUSE NOTES
    00043  *
    00044  *    USNG is intended for reuse by any application that does conversions
    00045  *    between geodetic coordinates and USNG coordinates.
    00046  *
    00047  * REFERENCES
    00048  *
    00049  *    Further information on USNG can be found in the Reuse Manual.
    00050  *
    00051  *    USNG originated from : Federal Geographic Data Committee
    00052  *                           590 National Center
    00053  *                           12201 Sunrise Valley Drive
    00054  *                           Reston, VA  22092
    00055  *
    00056  * LICENSES
    00057  *
    00058  *    None apply to this component.
    00059  *
    00060  * RESTRICTIONS
    00061  *
    00062  *
    00063  * ENVIRONMENT
    00064  *
    00065  *    USNG was tested and certified in the following environments:
    00066  *
    00067  *    1. Solaris 2.5 with GCC version 2.8.1
    00068  *    2. Windows XP with MS Visual C++ version 6
    00069  *
    00070  * MODIFICATIONS
    00071  *
    00072  *    Date              Description
    00073  *    ----              -----------
    00074  *    3-1-07          Original Code (cloned from MGRS)
    00075  */
    00076
    00077
    00078 #include "CoordinateSystem.h"
    00079
    00080
    00081 namespace MSP
    00082 {
    00083   namespace CCS
    00084   {
    00085     class UPS;
    00086     class UTM;
    00087     class EllipsoidParameters;
    00088     class MGRSorUSNGCoordinates;
    00089     class GeodeticCoordinates;
    00090     class UPSCoordinates;
    00091     class UTMCoordinates;
    00092
    00093     #define USNG_LETTERS 3
    00094
    00095     /**********************************************************************/
    00096     /*
    00097      *                        DEFINES
    00098      */
    00099
    00100     class USNG : public CoordinateSystem
    00101     {
    00102     public:
    00103
    00104       /*
    00105        * The constructor receives the ellipsoid parameters and sets
    00106        * the corresponding state variables. If any errors occur, an exception
    00107        * is thrown with a description of the error.
    00108        *
    00109        *   ellipsoidSemiMajorAxis     : Semi-major axis of ellipsoid in meters  (input)
    00110        *   ellipsoidFlattening        : Flattening of ellipsoid                                         (input)
    00111        *   ellipsoid_Code             : 2-letter code for ellipsoid             (input)
    00112        */
    00113
    00114       USNG( double ellipsoidSemiMajorAxis, double ellipsoidFlattening, char* ellipsoidCode );
    00115
    00116
    00117       USNG( const USNG &u );
    00118
    00119
    00120             ~USNG( void );
    00121
    00122
    00123       USNG& operator=( const USNG &u );
    00124
    00125
    00126       /*
    00127        * The function getParameters returns the current ellipsoid
    00128        * parameters.
    00129        *
    00130        *  ellipsoidSemiMajorAxis     : Semi-major axis of ellipsoid, in meters (output)
    00131        *  ellipsoidFlattening        : Flattening of ellipsoid                                         (output)
    00132        *  ellipsoidCode              : 2-letter code for ellipsoid             (output)
    00133        */
    00134
    00135       EllipsoidParameters* getParameters() const;
    00136
    00137
    00138       /*
    00139        * The function convertFromGeodetic converts Geodetic (latitude and
    00140        * longitude) coordinates to an USNG coordinate string, according to the
    00141        * current ellipsoid parameters.  If any errors occur, an exception is
    00142        * thrown with a description of the error.
    00143        *
    00144        *    latitude      : Latitude in radians              (input)
    00145        *    longitude     : Longitude in radians             (input)
    00146        *    precision     : Precision level of USNG string   (input)
    00147        *    USNGString    : USNG coordinate string           (output)
    00148        *
    00149        */
    00150
    00151       MSP::CCS::MGRSorUSNGCoordinates* convertFromGeodetic( MSP::CCS::GeodeticCoordinates* geodeticCoordinates, long precision );
    00152
    00153
    00154       /*
    00155        * The function convertToGeodetic converts an USNG coordinate string
    00156        * to Geodetic (latitude and longitude) coordinates
    00157        * according to the current ellipsoid parameters.  If any errors occur,
    00158        * an exception is thrown with a description of the error.
    00159        *
    00160        *    USNG       : USNG coordinate string           (input)
    00161        *    latitude   : Latitude in radians              (output)
    00162        *    longitude  : Longitude in radians             (output)
    00163        *
    00164        */
    00165
    00166       MSP::CCS::GeodeticCoordinates* convertToGeodetic( MSP::CCS::MGRSorUSNGCoordinates* mgrsCoordinates );
    00167
    00168
    00169       /*
    00170        * The function convertFromUTM converts UTM (zone, easting, and
    00171        * northing) coordinates to an USNG coordinate string, according to the
    00172        * current ellipsoid parameters.  If any errors occur, an exception is
    00173        * thrown with a description of the error.
    00174        *
    00175        *    zone       : UTM zone                         (input)
    00176        *    hemisphere : North or South hemisphere        (input)
    00177        *    easting    : Easting (X) in meters            (input)
    00178        *    northing   : Northing (Y) in meters           (input)
    00179        *    precision  : Precision level of USNG string   (input)
    00180        *    USNGString : USNG coordinate string           (output)
    00181        */
    00182
    00183       MSP::CCS::MGRSorUSNGCoordinates* convertFromUTM( UTMCoordinates* utmCoordinates, long precision );
    00184
    00185
    00186       /*
    00187        * The function convertToUTM converts an USNG coordinate string
    00188        * to UTM projection (zone, hemisphere, easting and northing) coordinates
    00189        * according to the current ellipsoid parameters.  If any errors occur, an
    00190        * exception is thrown with a description of the error.
    00191        *
    00192        *    USNGString : USNG coordinate string           (input)
    00193        *    zone       : UTM zone                         (output)
    00194        *    hemisphere : North or South hemisphere        (output)
    00195        *    easting    : Easting (X) in meters            (output)
    00196        *    northing   : Northing (Y) in meters           (output)
    00197        */
    00198
    00199       MSP::CCS::UTMCoordinates* convertToUTM( MSP::CCS::MGRSorUSNGCoordinates* mgrsorUSNGCoordinates );
    00200
    00201
    00202       /*
    00203        * The function convertFromUPS converts UPS (hemisphere, easting,
    00204        * and northing) coordinates to an USNG coordinate string according to
    00205        * the current ellipsoid parameters.  If any errors occur, an exception
    00206        * is thrown with a description of the error.
    00207        *
    00208        *    hemisphere    : Hemisphere either 'N' or 'S'     (input)
    00209        *    easting       : Easting/X in meters              (input)
    00210        *    northing      : Northing/Y in meters             (input)
    00211        *    precision     : Precision level of USNG string   (input)
    00212        *    USNGString    : USNG coordinate string           (output)
    00213        */
    00214
    00215       MSP::CCS::MGRSorUSNGCoordinates* convertFromUPS( MSP::CCS::UPSCoordinates* upsCoordinates, long precision );
    00216
    00217
    00218       /*
    00219        * The function convertToUPS converts an USNG coordinate string
    00220        * to UPS (hemisphere, easting, and northing) coordinates, according
    00221        * to the current ellipsoid parameters. If any errors occur, an
    00222        * exception is thrown with a description of the error.
    00223        *
    00224        *    USNGString    : USNG coordinate string           (input)
    00225        *    hemisphere    : Hemisphere either 'N' or 'S'     (output)
    00226        *    easting       : Easting/X in meters              (output)
    00227        *    northing      : Northing/Y in meters             (output)
    00228        */
    00229
    00230       MSP::CCS::UPSCoordinates* convertToUPS( MSP::CCS::MGRSorUSNGCoordinates* mgrsorUSNGCoordinates );
    00231
    00232     private:
    00233
    00234       UPS* ups;
    00235       UTM* utm;
    00236
    00237       char USNGEllipsoidCode[3];
    00238
    00239
    00240       /*
    00241        * The function fromUTM calculates an USNG coordinate string
    00242        * based on the zone, latitude, easting and northing.
    00243        *
    00244        *    zone       : Zone number             (input)
    00245        *    latitude   : Latitude in radians     (input)
    00246        *    easting    : Easting                 (input)
    00247        *    northing   : Northing                (input)
    00248        *    precision  : Precision               (input)
    00249        *    USNGString : USNG coordinate string  (output)
    00250        */
    00251
    00252       MSP::CCS::MGRSorUSNGCoordinates* fromUTM( MSP::CCS::UTMCoordinates* utmCoordinates, double longitude, double latitude, long precision );
    00253
    00254
    00255       /*
    00256        * The function toUTM converts an USNG coordinate string
    00257        * to UTM projection (zone, hemisphere, easting and northing) coordinates
    00258        * according to the current ellipsoid parameters.  If any errors occur,
    00259        * an exception is thrown with a description of the error.
    00260        *
    00261        *    USNGString : USNG coordinate string           (input)
    00262        *    zone       : UTM zone                         (output)
    00263        *    hemisphere : North or South hemisphere        (output)
    00264        *    easting    : Easting (X) in meters            (output)
    00265        *    northing   : Northing (Y) in meters           (output)
    00266        */
    00267
    00268       MSP::CCS::UTMCoordinates* USNG::toUTM( long zone, long letters[USNG_LETTERS], double easting, double northing, long in_precision );
    00269
    00270
    00271       /*
    00272        * The function fromUPS converts UPS (hemisphere, easting,
    00273        * and northing) coordinates to an USNG coordinate string according to
    00274        * the current ellipsoid parameters.
    00275        *
    00276        *    hemisphere    : Hemisphere either 'N' or 'S'     (input)
    00277        *    easting       : Easting/X in meters              (input)
    00278        *    northing      : Northing/Y in meters             (input)
    00279        *    precision     : Precision level of USNG string   (input)
    00280        *    USNGString    : USNG coordinate string           (output)
    00281        */
    00282
    00283       MSP::CCS::MGRSorUSNGCoordinates* fromUPS( MSP::CCS::UPSCoordinates* upsCoordinates, long precision );
    00284
    00285       /*
    00286        * The function toUPS converts an USNG coordinate string
    00287        * to UPS (hemisphere, easting, and northing) coordinates, according
    00288        * to the current ellipsoid parameters. If any errors occur, an
    00289        * exception is thrown with a description of the error.
    00290        *
    00291        *    USNGString    : USNG coordinate string           (input)
    00292        *    hemisphere    : Hemisphere either 'N' or 'S'     (output)
    00293        *    easting       : Easting/X in meters              (output)
    00294        *    northing      : Northing/Y in meters             (output)
    00295        */
    00296
    00297       MSP::CCS::UPSCoordinates* toUPS( long letters[USNG_LETTERS], double easting, double northing );
    00298
    00299
    00300       /*
    00301        * The function getGridValues sets the letter range used for
    00302        * the 2nd letter in the USNG coordinate string, based on the set
    00303        * number of the utm zone. It also sets the pattern offset using a
    00304        * value of A for the second letter of the grid square, based on
    00305        * the grid pattern and set number of the utm zone.
    00306        *
    00307        *    zone            : Zone number             (input)
    00308        *    ltr2_low_value  : 2nd letter low number   (output)
    00309        *    ltr2_high_value : 2nd letter high number  (output)
    00310        *    pattern_offset  : Pattern offset          (output)
    00311        */
    00312
    00313       void getGridValues( long zone, long* ltr2_low_value, long* ltr2_high_value, double* pattern_offset );
    00314
    00315
    00316       /*
    00317        * The function getLatitudeBandMinNorthing receives a latitude band letter
    00318        * and uses the Latitude_Band_Table to determine the minimum northing and northing offset
    00319        * for that latitude band letter.
    00320        *
    00321        *   letter          : Latitude band letter             (input)
    00322        *   min_northing    : Minimum northing for that letter   (output)
    00323        *   northing_offset : Latitude band northing offset      (output)
    00324        */
    00325
    00326       void getLatitudeBandMinNorthing( long letter, double* min_northing, double* northing_offset );
    00327
    00328
    00329       /*
    00330        * The function getLatitudeRange receives a latitude band letter
    00331        * and uses the Latitude_Band_Table to determine the latitude band
    00332        * boundaries for that latitude band letter.
    00333        *
    00334        *   letter   : Latitude band letter                        (input)
    00335        *   north    : Northern latitude boundary for that letter        (output)
    00336        *   north    : Southern latitude boundary for that letter        (output)
    00337        */
    00338
    00339       void getLatitudeRange( long letter, double* north, double* south );
    00340
    00341
    00342       /*
    00343        * The function getLatitudeLetter receives a latitude value
    00344        * and uses the Latitude_Band_Table to determine the latitude band
    00345        * letter for that latitude.
    00346        *
    00347        *   latitude   : Latitude              (input)
    00348        *   letter     : Latitude band letter  (output)
    00349        */
    00350
    00351       void getLatitudeLetter( double latitude, int* letter );
    00352     };
    00353   }
    00354 }
    00355
    00356 #endif
    00357
    00358
    00359 // CLASSIFICATION: UNCLASSIFIED