00001 // CLASSIFICATION: UNCLASSIFIED 00002 00003 #ifndef MGRS_H 00004 #define MGRS_H 00005 00006 /***************************************************************************/ 00007 /* RSC IDENTIFIER: MGRS 00008 * 00009 * ABSTRACT 00010 * 00011 * This component converts between geodetic coordinates (latitude and 00012 * longitude) and Military Grid Reference System (MGRS) 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 * MGRS_NO_ERROR : No errors occurred in function 00022 * MGRS_LAT_ERROR : Latitude outside of valid range 00023 * (-90 to 90 degrees) 00024 * MGRS_LON_ERROR : Longitude outside of valid range 00025 * (-180 to 360 degrees) 00026 * MGRS_STR_ERROR : An MGRS string error: string too long, 00027 * too short, or badly formed 00028 * MGRS_PRECISION_ERROR : The precision must be between 0 and 5 00029 * inclusive. 00030 * MGRS_A_ERROR : Semi-major axis less than or equal to zero 00031 * MGRS_INV_F_ERROR : Inverse flattening outside of valid range 00032 * (250 to 350) 00033 * MGRS_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 * MGRS_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 * MGRS_ZONE_ERROR : Zone outside of valid range (1 to 60) 00040 * MGRS_HEMISPHERE_ERROR : Invalid hemisphere ('N' or 'S') 00041 * 00042 * REUSE NOTES 00043 * 00044 * MGRS is intended for reuse by any application that does conversions 00045 * between geodetic coordinates and MGRS coordinates. 00046 * 00047 * REFERENCES 00048 * 00049 * Further information on MGRS can be found in the Reuse Manual. 00050 * 00051 * MGRS originated from : U.S. Army Topographic Engineering Center 00052 * Geospatial Information Division 00053 * 7701 Telegraph Road 00054 * Alexandria, VA 22310-3864 00055 * 00056 * LICENSES 00057 * 00058 * None apply to this component. 00059 * 00060 * RESTRICTIONS 00061 * 00062 * 00063 * ENVIRONMENT 00064 * 00065 * MGRS was tested and certified in the following environments: 00066 * 00067 * 1. Solaris 2.5 with GCC version 2.8.1 00068 * 2. Windows 95 with MS Visual C++ version 6 00069 * 00070 * MODIFICATIONS 00071 * 00072 * Date Description 00073 * ---- ----------- 00074 * 2-27-07 Original Code 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 MGRS_LETTERS 3 00094 00095 /**********************************************************************/ 00096 /* 00097 * DEFINES 00098 */ 00099 00100 class MSP_DTCC_API MGRS : 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, 00107 * an exception is thrown with a description of the error. 00108 * 00109 * ellipsoidSemiMajorAxis : Semi-major axis of ellipsoid (m) (input) 00110 * ellipsoidFlattening : Flattening of ellipsoid (input) 00111 * ellipsoid_Code : 2-letter code for ellipsoid (input) 00112 */ 00113 00114 MGRS( 00115 double ellipsoidSemiMajorAxis, 00116 double ellipsoidFlattening, 00117 char* ellipsoidCode ); 00118 00119 00120 MGRS( const MGRS &m ); 00121 00122 00123 ~MGRS( void ); 00124 00125 00126 MGRS& operator=( const MGRS &m ); 00127 00128 00129 /* 00130 * The function getParameters returns the current ellipsoid 00131 * parameters. 00132 * 00133 * ellipsoidSemiMajorAxis : Semi-major axis of ellipsoid, (m) (output) 00134 * ellipsoidFlattening : Flattening of ellipsoid (output) 00135 * ellipsoidCode : 2-letter code for ellipsoid (output) 00136 */ 00137 00138 EllipsoidParameters* getParameters() const; 00139 00140 00141 /* 00142 * The function convertFromGeodetic converts Geodetic (latitude and 00143 * longitude) coordinates to an MGRS coordinate string, according to the 00144 * current ellipsoid parameters. If any errors occur, 00145 * an exception is thrown with a description of the error. 00146 * 00147 * latitude : Latitude in radians (input) 00148 * longitude : Longitude in radians (input) 00149 * precision : Precision level of MGRS string (input) 00150 * MGRSString : MGRS coordinate string (output) 00151 * 00152 */ 00153 00154 MSP::CCS::MGRSorUSNGCoordinates* convertFromGeodetic( 00155 MSP::CCS::GeodeticCoordinates* geodeticCoordinates, 00156 long precision ); 00157 00158 /* 00159 * The function convertToGeodetic converts an MGRS coordinate string 00160 * to Geodetic (latitude and longitude) coordinates 00161 * according to the current ellipsoid parameters. If any errors occur, 00162 * an exception is thrown with a description of the error. 00163 * 00164 * MGRS : MGRS coordinate string (input) 00165 * latitude : Latitude in radians (output) 00166 * longitude : Longitude in radians (output) 00167 * 00168 */ 00169 00170 MSP::CCS::GeodeticCoordinates* convertToGeodetic( 00171 MSP::CCS::MGRSorUSNGCoordinates* mgrsCoordinates ); 00172 00173 00174 /* 00175 * The function convertFromUTM converts UTM (zone, easting, and 00176 * northing) coordinates to an MGRS coordinate string, according to the 00177 * current ellipsoid parameters. If any errors occur, 00178 * an exception is thrown with a description of the error. 00179 * 00180 * zone : UTM zone (input) 00181 * hemisphere : North or South hemisphere (input) 00182 * easting : Easting (X) in meters (input) 00183 * northing : Northing (Y) in meters (input) 00184 * precision : Precision level of MGRS string (input) 00185 * MGRSString : MGRS coordinate string (output) 00186 */ 00187 00188 MSP::CCS::MGRSorUSNGCoordinates* convertFromUTM( 00189 UTMCoordinates* utmCoordinates, long precision ); 00190 00191 00192 /* 00193 * The function convertToUTM converts an MGRS coordinate string 00194 * to UTM projection (zone, hemisphere, easting and northing) coordinates 00195 * according to the current ellipsoid parameters. If any errors occur, 00196 * an exception is thrown with a description of the error. 00197 * 00198 * MGRSString : MGRS coordinate string (input) 00199 * zone : UTM zone (output) 00200 * hemisphere : North or South hemisphere (output) 00201 * easting : Easting (X) in meters (output) 00202 * northing : Northing (Y) in meters (output) 00203 */ 00204 00205 MSP::CCS::UTMCoordinates* convertToUTM( 00206 MSP::CCS::MGRSorUSNGCoordinates* mgrsorUSNGCoordinates ); 00207 00208 /* 00209 * The function convertFromUPS converts UPS (hemisphere, easting, 00210 * and northing) coordinates to an MGRS coordinate string according to 00211 * the current ellipsoid parameters. If any errors occur, 00212 * an exception is thrown with a description of the error. 00213 * 00214 * hemisphere : Hemisphere either 'N' or 'S' (input) 00215 * easting : Easting/X in meters (input) 00216 * northing : Northing/Y in meters (input) 00217 * precision : Precision level of MGRS string (input) 00218 * MGRSString : MGRS coordinate string (output) 00219 */ 00220 00221 MSP::CCS::MGRSorUSNGCoordinates* convertFromUPS( 00222 MSP::CCS::UPSCoordinates* upsCoordinates, long precision ); 00223 00224 00225 /* 00226 * The function convertToUPS converts an MGRS coordinate string 00227 * to UPS (hemisphere, easting, and northing) coordinates, according 00228 * to the current ellipsoid parameters. If any errors occur, 00229 * an exception is thrown with a description of the error. 00230 * 00231 * MGRSString : MGRS coordinate string (input) 00232 * hemisphere : Hemisphere either 'N' or 'S' (output) 00233 * easting : Easting/X in meters (output) 00234 * northing : Northing/Y in meters (output) 00235 */ 00236 00237 MSP::CCS::UPSCoordinates* convertToUPS( 00238 MSP::CCS::MGRSorUSNGCoordinates* mgrsorUSNGCoordinates ); 00239 00240 private: 00241 00242 UPS* ups; 00243 UTM* utm; 00244 00245 char MGRSEllipsoidCode[3]; 00246 00247 00248 /* 00249 * The function fromUTM calculates an MGRS coordinate string 00250 * based on the zone, latitude, easting and northing. 00251 * 00252 * zone : Zone number (input) 00253 * hemisphere : Hemisphere (input) 00254 * longitude : Longitude in radians (input) 00255 * latitude : Latitude in radians (input) 00256 * easting : Easting (input) 00257 * northing : Northing (input) 00258 * precision : Precision (input) 00259 * MGRSString : MGRS coordinate string (output) 00260 */ 00261 00262 MSP::CCS::MGRSorUSNGCoordinates* fromUTM( 00263 MSP::CCS::UTMCoordinates* utmCoordinates, 00264 double longitude, 00265 double latitude, 00266 long precision ); 00267 00268 /* 00269 * The function toUTM converts an MGRS coordinate string 00270 * to UTM projection (zone, hemisphere, easting and northing) coordinates 00271 * according to the current ellipsoid parameters. If any errors occur, 00272 * an exception is thrown with a description of the error. 00273 * 00274 * MGRSString : MGRS coordinate string (input) 00275 * zone : UTM zone (output) 00276 * hemisphere : North or South hemisphere (output) 00277 * easting : Easting (X) in meters (output) 00278 * northing : Northing (Y) in meters (output) 00279 */ 00280 00281 MSP::CCS::UTMCoordinates* toUTM( 00282 long zone, 00283 long letters[MGRS_LETTERS], 00284 double easting, 00285 double northing, 00286 long in_precision ); 00287 00288 00289 /* 00290 * The function fromUPS converts UPS (hemisphere, easting, 00291 * and northing) coordinates to an MGRS coordinate string according to 00292 * the current ellipsoid parameters. 00293 * 00294 * hemisphere : Hemisphere either 'N' or 'S' (input) 00295 * easting : Easting/X in meters (input) 00296 * northing : Northing/Y in meters (input) 00297 * precision : Precision level of MGRS string (input) 00298 * MGRSString : MGRS coordinate string (output) 00299 */ 00300 00301 MSP::CCS::MGRSorUSNGCoordinates* fromUPS( 00302 MSP::CCS::UPSCoordinates* upsCoordinates, 00303 long precision ); 00304 00305 /* 00306 * The function toUPS converts an MGRS coordinate string 00307 * to UPS (hemisphere, easting, and northing) coordinates, according 00308 * to the current ellipsoid parameters. If any errors occur, an 00309 * exception is thrown with a description of the error. 00310 * 00311 * MGRSString : MGRS coordinate string (input) 00312 * hemisphere : Hemisphere either 'N' or 'S' (output) 00313 * easting : Easting/X in meters (output) 00314 * northing : Northing/Y in meters (output) 00315 */ 00316 00317 MSP::CCS::UPSCoordinates* toUPS( 00318 long letters[MGRS_LETTERS], 00319 double easting, double northing ); 00320 00321 /* 00322 * The function getGridValues sets the letter range used for 00323 * the 2nd letter in the MGRS coordinate string, based on the set 00324 * number of the utm zone. It also sets the pattern offset using a 00325 * value of A for the second letter of the grid square, based on 00326 * the grid pattern and set number of the utm zone. 00327 * 00328 * zone : Zone number (input) 00329 * ltr2_low_value : 2nd letter low number (output) 00330 * ltr2_high_value : 2nd letter high number (output) 00331 * pattern_offset : Pattern offset (output) 00332 */ 00333 00334 void getGridValues( 00335 long zone, 00336 long* ltr2_low_value, 00337 long* ltr2_high_value, 00338 double* pattern_offset ); 00339 00340 00341 /* 00342 * The function getLatitudeBandMinNorthing receives a latitude band 00343 * letter and uses the Latitude_Band_Table to determine the 00344 * minimum northing and northing offset for that latitude band letter. 00345 * 00346 * letter : Latitude band letter (input) 00347 * min_northing : Minimum northing for that letter (output) 00348 * northing_offset : Latitude band northing offset (output) 00349 */ 00350 00351 void getLatitudeBandMinNorthing( 00352 long letter, double* min_northing, double* northing_offset ); 00353 00354 00355 /* 00356 * The function inLatitudeRange receives a latitude band letter 00357 * and uses the Latitude_Band_Table to determine if the latitude 00358 * falls within the band boundaries for that latitude band letter. 00359 * 00360 * letter : Latitude band letter (input) 00361 * latitude : Latitude to test (input) 00362 * border : Border added to band in radians (input) 00363 */ 00364 00365 bool inLatitudeRange( long letter, double latitude, double border ); 00366 00367 00368 /* 00369 * The function getLatitudeLetter receives a latitude value 00370 * and uses the Latitude_Band_Table to determine the latitude band 00371 * letter for that latitude. 00372 * 00373 * latitude : Latitude (input) 00374 * letter : Latitude band letter (output) 00375 */ 00376 00377 void getLatitudeLetter( double latitude, int* letter ); 00378 }; 00379 } 00380 } 00381 00382 #endif 00383 00384 00385 // CLASSIFICATION: UNCLASSIFIED