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 UTMCoordinates* 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