1
// CLASSIFICATION: UNCLASSIFIED
6
/***************************************************************************/
7
/* RSC IDENTIFIER: USNG
11
* This component converts between geodetic coordinates (latitude and
12
* longitude) and United States National Grid (USNG) coordinates.
16
* This component checks parameters for valid values. If an invalid value
17
* is found, the error code is combined with the current error code using
18
* the bitwise or. This combining allows multiple error codes to be
19
* returned. The possible error codes are:
21
* USNG_NO_ERROR : No errors occurred in function
22
* USNG_LAT_ERROR : Latitude outside of valid range
24
* USNG_LON_ERROR : Longitude outside of valid range
25
* (-180 to 360 degrees)
26
* USNG_STR_ERROR : An USNG string error: string too long,
27
* too short, or badly formed
28
* USNG_PRECISION_ERROR : The precision must be between 0 and 5
30
* USNG_A_ERROR : Semi-major axis less than or equal to zero
31
* USNG_INV_F_ERROR : Inverse flattening outside of valid range
33
* USNG_EASTING_ERROR : Easting outside of valid range
34
* (100,000 to 900,000 meters for UTM)
35
* (0 to 4,000,000 meters for UPS)
36
* USNG_NORTHING_ERROR : Northing outside of valid range
37
* (0 to 10,000,000 meters for UTM)
38
* (0 to 4,000,000 meters for UPS)
39
* USNG_ZONE_ERROR : Zone outside of valid range (1 to 60)
40
* USNG_HEMISPHERE_ERROR : Invalid hemisphere ('N' or 'S')
44
* USNG is intended for reuse by any application that does conversions
45
* between geodetic coordinates and USNG coordinates.
49
* Further information on USNG can be found in the Reuse Manual.
51
* USNG originated from : Federal Geographic Data Committee
53
* 12201 Sunrise Valley Drive
58
* None apply to this component.
65
* USNG was tested and certified in the following environments:
67
* 1. Solaris 2.5 with GCC version 2.8.1
68
* 2. Windows XP with MS Visual C++ version 6
74
* 3-1-07 Original Code (cloned from MGRS)
78
#include "CoordinateSystem.h"
87
class EllipsoidParameters;
88
class MGRSorUSNGCoordinates;
89
class GeodeticCoordinates;
93
#define USNG_LETTERS 3
95
/**********************************************************************/
100
class USNG : public CoordinateSystem
105
* The constructor receives the ellipsoid parameters and sets
106
* the corresponding state variables. If any errors occur, an exception
107
* is thrown with a description of the error.
109
* ellipsoidSemiMajorAxis : Semi-major axis of ellipsoid in meters (input)
110
* ellipsoidFlattening : Flattening of ellipsoid (input)
111
* ellipsoid_Code : 2-letter code for ellipsoid (input)
114
USNG( double ellipsoidSemiMajorAxis, double ellipsoidFlattening, char* ellipsoidCode );
117
USNG( const USNG &u );
123
USNG& operator=( const USNG &u );
127
* The function getParameters returns the current ellipsoid
130
* ellipsoidSemiMajorAxis : Semi-major axis of ellipsoid, in meters (output)
131
* ellipsoidFlattening : Flattening of ellipsoid (output)
132
* ellipsoidCode : 2-letter code for ellipsoid (output)
135
EllipsoidParameters* getParameters() const;
139
* The function convertFromGeodetic converts Geodetic (latitude and
140
* longitude) coordinates to an USNG coordinate string, according to the
141
* current ellipsoid parameters. If any errors occur, an exception is
142
* thrown with a description of the error.
144
* latitude : Latitude in radians (input)
145
* longitude : Longitude in radians (input)
146
* precision : Precision level of USNG string (input)
147
* USNGString : USNG coordinate string (output)
151
MSP::CCS::MGRSorUSNGCoordinates* convertFromGeodetic( MSP::CCS::GeodeticCoordinates* geodeticCoordinates, long precision );
155
* The function convertToGeodetic converts an USNG coordinate string
156
* to Geodetic (latitude and longitude) coordinates
157
* according to the current ellipsoid parameters. If any errors occur,
158
* an exception is thrown with a description of the error.
160
* USNG : USNG coordinate string (input)
161
* latitude : Latitude in radians (output)
162
* longitude : Longitude in radians (output)
166
MSP::CCS::GeodeticCoordinates* convertToGeodetic( MSP::CCS::MGRSorUSNGCoordinates* mgrsCoordinates );
170
* The function convertFromUTM converts UTM (zone, easting, and
171
* northing) coordinates to an USNG coordinate string, according to the
172
* current ellipsoid parameters. If any errors occur, an exception is
173
* thrown with a description of the error.
175
* zone : UTM zone (input)
176
* hemisphere : North or South hemisphere (input)
177
* easting : Easting (X) in meters (input)
178
* northing : Northing (Y) in meters (input)
179
* precision : Precision level of USNG string (input)
180
* USNGString : USNG coordinate string (output)
183
MSP::CCS::MGRSorUSNGCoordinates* convertFromUTM( UTMCoordinates* utmCoordinates, long precision );
187
* The function convertToUTM converts an USNG coordinate string
188
* to UTM projection (zone, hemisphere, easting and northing) coordinates
189
* according to the current ellipsoid parameters. If any errors occur, an
190
* exception is thrown with a description of the error.
192
* USNGString : USNG coordinate string (input)
193
* zone : UTM zone (output)
194
* hemisphere : North or South hemisphere (output)
195
* easting : Easting (X) in meters (output)
196
* northing : Northing (Y) in meters (output)
199
MSP::CCS::UTMCoordinates* convertToUTM( MSP::CCS::MGRSorUSNGCoordinates* mgrsorUSNGCoordinates );
203
* The function convertFromUPS converts UPS (hemisphere, easting,
204
* and northing) coordinates to an USNG coordinate string according to
205
* the current ellipsoid parameters. If any errors occur, an exception
206
* is thrown with a description of the error.
208
* hemisphere : Hemisphere either 'N' or 'S' (input)
209
* easting : Easting/X in meters (input)
210
* northing : Northing/Y in meters (input)
211
* precision : Precision level of USNG string (input)
212
* USNGString : USNG coordinate string (output)
215
MSP::CCS::MGRSorUSNGCoordinates* convertFromUPS( MSP::CCS::UPSCoordinates* upsCoordinates, long precision );
219
* The function convertToUPS converts an USNG coordinate string
220
* to UPS (hemisphere, easting, and northing) coordinates, according
221
* to the current ellipsoid parameters. If any errors occur, an
222
* exception is thrown with a description of the error.
224
* USNGString : USNG coordinate string (input)
225
* hemisphere : Hemisphere either 'N' or 'S' (output)
226
* easting : Easting/X in meters (output)
227
* northing : Northing/Y in meters (output)
230
MSP::CCS::UPSCoordinates* convertToUPS( MSP::CCS::MGRSorUSNGCoordinates* mgrsorUSNGCoordinates );
237
char USNGEllipsoidCode[3];
241
* The function fromUTM calculates an USNG coordinate string
242
* based on the zone, latitude, easting and northing.
244
* zone : Zone number (input)
245
* latitude : Latitude in radians (input)
246
* easting : Easting (input)
247
* northing : Northing (input)
248
* precision : Precision (input)
249
* USNGString : USNG coordinate string (output)
252
MSP::CCS::MGRSorUSNGCoordinates* fromUTM( MSP::CCS::UTMCoordinates* utmCoordinates, double longitude, double latitude, long precision );
256
* The function toUTM converts an USNG coordinate string
257
* to UTM projection (zone, hemisphere, easting and northing) coordinates
258
* according to the current ellipsoid parameters. If any errors occur,
259
* an exception is thrown with a description of the error.
261
* USNGString : USNG coordinate string (input)
262
* zone : UTM zone (output)
263
* hemisphere : North or South hemisphere (output)
264
* easting : Easting (X) in meters (output)
265
* northing : Northing (Y) in meters (output)
268
MSP::CCS::UTMCoordinates* USNG::toUTM( long zone, long letters[USNG_LETTERS], double easting, double northing, long in_precision );
272
* The function fromUPS converts UPS (hemisphere, easting,
273
* and northing) coordinates to an USNG coordinate string according to
274
* the current ellipsoid parameters.
276
* hemisphere : Hemisphere either 'N' or 'S' (input)
277
* easting : Easting/X in meters (input)
278
* northing : Northing/Y in meters (input)
279
* precision : Precision level of USNG string (input)
280
* USNGString : USNG coordinate string (output)
283
MSP::CCS::MGRSorUSNGCoordinates* fromUPS( MSP::CCS::UPSCoordinates* upsCoordinates, long precision );
286
* The function toUPS converts an USNG coordinate string
287
* to UPS (hemisphere, easting, and northing) coordinates, according
288
* to the current ellipsoid parameters. If any errors occur, an
289
* exception is thrown with a description of the error.
291
* USNGString : USNG coordinate string (input)
292
* hemisphere : Hemisphere either 'N' or 'S' (output)
293
* easting : Easting/X in meters (output)
294
* northing : Northing/Y in meters (output)
297
MSP::CCS::UPSCoordinates* toUPS( long letters[USNG_LETTERS], double easting, double northing );
301
* The function getGridValues sets the letter range used for
302
* the 2nd letter in the USNG coordinate string, based on the set
303
* number of the utm zone. It also sets the pattern offset using a
304
* value of A for the second letter of the grid square, based on
305
* the grid pattern and set number of the utm zone.
307
* zone : Zone number (input)
308
* ltr2_low_value : 2nd letter low number (output)
309
* ltr2_high_value : 2nd letter high number (output)
310
* pattern_offset : Pattern offset (output)
313
void getGridValues( long zone, long* ltr2_low_value, long* ltr2_high_value, double* pattern_offset );
317
* The function getLatitudeBandMinNorthing receives a latitude band letter
318
* and uses the Latitude_Band_Table to determine the minimum northing and northing offset
319
* for that latitude band letter.
321
* letter : Latitude band letter (input)
322
* min_northing : Minimum northing for that letter (output)
323
* northing_offset : Latitude band northing offset (output)
326
void getLatitudeBandMinNorthing( long letter, double* min_northing, double* northing_offset );
330
* The function getLatitudeRange receives a latitude band letter
331
* and uses the Latitude_Band_Table to determine the latitude band
332
* boundaries for that latitude band letter.
334
* letter : Latitude band letter (input)
335
* north : Northern latitude boundary for that letter (output)
336
* north : Southern latitude boundary for that letter (output)
339
void getLatitudeRange( long letter, double* north, double* south );
343
* The function getLatitudeLetter receives a latitude value
344
* and uses the Latitude_Band_Table to determine the latitude band
345
* letter for that latitude.
347
* latitude : Latitude (input)
348
* letter : Latitude band letter (output)
351
void getLatitudeLetter( double latitude, int* letter );
359
// CLASSIFICATION: UNCLASSIFIED