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 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, an exception is thrown with a description 00107 * 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 MGRS( double ellipsoidSemiMajorAxis, double ellipsoidFlattening, char* ellipsoidCode ); 00115 00116 00117 MGRS( const MGRS &m ); 00118 00119 00120 ~MGRS( void ); 00121 00122 00123 MGRS& operator=( const MGRS &m ); 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 MGRS coordinate string, according to the 00141 * current ellipsoid parameters. If any errors occur, an exception is thrown with a description 00142 * of the error. 00143 * 00144 * latitude : Latitude in radians (input) 00145 * longitude : Longitude in radians (input) 00146 * precision : Precision level of MGRS string (input) 00147 * MGRSString : MGRS 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 MGRS coordinate string 00156 * to Geodetic (latitude and longitude) coordinates 00157 * according to the current ellipsoid parameters. If any errors occur, an exception is 00158 * thrown with a description of the error. 00159 * 00160 * MGRS : MGRS 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 MGRS coordinate string, according to the 00172 * current ellipsoid parameters. If any errors occur, an exception is thrown 00173 * 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 MGRS string (input) 00180 * MGRSString : MGRS coordinate string (output) 00181 */ 00182 00183 MSP::CCS::MGRSorUSNGCoordinates* convertFromUTM( UTMCoordinates* utmCoordinates, long precision ); 00184 00185 00186 /* 00187 * The function convertToUTM converts an MGRS coordinate string 00188 * to UTM projection (zone, hemisphere, easting and northing) coordinates 00189 * according to the current ellipsoid parameters. If any errors occur, an exception is thrown 00190 * with a description of the error. 00191 * 00192 * MGRSString : MGRS 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 MGRS coordinate string according to 00205 * the current ellipsoid parameters. If any errors occur, an exception is thrown with a description 00206 * 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 MGRS string (input) 00212 * MGRSString : MGRS 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 MGRS coordinate string 00220 * to UPS (hemisphere, easting, and northing) coordinates, according 00221 * to the current ellipsoid parameters. If any errors occur, an exception is thrown with a description 00222 * of the error. 00223 * 00224 * MGRSString : MGRS 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 MGRSEllipsoidCode[3]; 00238 00239 00240 /* 00241 * The function fromUTM calculates an MGRS coordinate string 00242 * based on the zone, latitude, easting and northing. 00243 * 00244 * zone : Zone number (input) 00245 * hemisphere : Hemisphere (input) 00246 * longitude : Longitude in radians (input) 00247 * latitude : Latitude in radians (input) 00248 * easting : Easting (input) 00249 * northing : Northing (input) 00250 * precision : Precision (input) 00251 * MGRSString : MGRS coordinate string (output) 00252 */ 00253 00254 MSP::CCS::MGRSorUSNGCoordinates* fromUTM( MSP::CCS::UTMCoordinates* utmCoordinates, double longitude, double latitude, long precision ); 00255 00256 00257 /* 00258 * The function toUTM converts an MGRS coordinate string 00259 * to UTM projection (zone, hemisphere, easting and northing) coordinates 00260 * according to the current ellipsoid parameters. If any errors occur, 00261 * an exception is thrown with a description of the error. 00262 * 00263 * MGRSString : MGRS coordinate string (input) 00264 * zone : UTM zone (output) 00265 * hemisphere : North or South hemisphere (output) 00266 * easting : Easting (X) in meters (output) 00267 * northing : Northing (Y) in meters (output) 00268 */ 00269 00270 MSP::CCS::UTMCoordinates* toUTM( long zone, long letters[MGRS_LETTERS], double easting, double northing, long in_precision ); 00271 00272 00273 /* 00274 * The function fromUPS converts UPS (hemisphere, easting, 00275 * and northing) coordinates to an MGRS coordinate string according to 00276 * the current ellipsoid parameters. 00277 * 00278 * hemisphere : Hemisphere either 'N' or 'S' (input) 00279 * easting : Easting/X in meters (input) 00280 * northing : Northing/Y in meters (input) 00281 * precision : Precision level of MGRS string (input) 00282 * MGRSString : MGRS coordinate string (output) 00283 */ 00284 00285 MSP::CCS::MGRSorUSNGCoordinates* fromUPS( MSP::CCS::UPSCoordinates* upsCoordinates, long precision ); 00286 00287 /* 00288 * The function toUPS converts an MGRS coordinate string 00289 * to UPS (hemisphere, easting, and northing) coordinates, according 00290 * to the current ellipsoid parameters. If any errors occur, an 00291 * exception is thrown with a description of the error. 00292 * 00293 * MGRSString : MGRS coordinate string (input) 00294 * hemisphere : Hemisphere either 'N' or 'S' (output) 00295 * easting : Easting/X in meters (output) 00296 * northing : Northing/Y in meters (output) 00297 */ 00298 00299 MSP::CCS::UPSCoordinates* toUPS( long letters[MGRS_LETTERS], double easting, double northing ); 00300 00301 00302 /* 00303 * The function getGridValues sets the letter range used for 00304 * the 2nd letter in the MGRS coordinate string, based on the set 00305 * number of the utm zone. It also sets the pattern offset using a 00306 * value of A for the second letter of the grid square, based on 00307 * the grid pattern and set number of the utm zone. 00308 * 00309 * zone : Zone number (input) 00310 * ltr2_low_value : 2nd letter low number (output) 00311 * ltr2_high_value : 2nd letter high number (output) 00312 * pattern_offset : Pattern offset (output) 00313 */ 00314 00315 void getGridValues( long zone, long* ltr2_low_value, long* ltr2_high_value, double* pattern_offset ); 00316 00317 00318 /* 00319 * The function getLatitudeBandMinNorthing receives a latitude band letter 00320 * and uses the Latitude_Band_Table to determine the minimum northing and northing offset 00321 * for that latitude band letter. 00322 * 00323 * letter : Latitude band letter (input) 00324 * min_northing : Minimum northing for that letter (output) 00325 * northing_offset : Latitude band northing offset (output) 00326 */ 00327 00328 void getLatitudeBandMinNorthing( long letter, double* min_northing, double* northing_offset ); 00329 00330 00331 /* 00332 * The function getLatitudeRange receives a latitude band letter 00333 * and uses the Latitude_Band_Table to determine the latitude band 00334 * boundaries for that latitude band letter. 00335 * 00336 * letter : Latitude band letter (input) 00337 * north : Northern latitude boundary for that letter (output) 00338 * north : Southern latitude boundary for that letter (output) 00339 */ 00340 00341 void getLatitudeRange( long letter, double* north, double* south ); 00342 00343 00344 /* 00345 * The function getLatitudeLetter receives a latitude value 00346 * and uses the Latitude_Band_Table to determine the latitude band 00347 * letter for that latitude. 00348 * 00349 * latitude : Latitude (input) 00350 * letter : Latitude band letter (output) 00351 */ 00352 00353 void getLatitudeLetter( double latitude, int* letter ); 00354 }; 00355 } 00356 } 00357 00358 #endif 00359 00360 00361 // CLASSIFICATION: UNCLASSIFIED