UNCLASSIFIED
GeographicTranslator
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Friends Macros
USNG.h
Go to the documentation of this file.
1 // CLASSIFICATION: UNCLASSIFIED
2 
3 #ifndef USNG_H
4 #define USNG_H
5 
6 /***************************************************************************/
7 /* RSC IDENTIFIER: USNG
8  *
9  * ABSTRACT
10  *
11  * This component converts between geodetic coordinates (latitude and
12  * longitude) and United States National Grid (USNG) coordinates.
13  *
14  * ERROR HANDLING
15  *
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:
20  *
21  * USNG_NO_ERROR : No errors occurred in function
22  * USNG_LAT_ERROR : Latitude outside of valid range
23  * (-90 to 90 degrees)
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
29  * inclusive.
30  * USNG_A_ERROR : Semi-major axis less than or equal to zero
31  * USNG_INV_F_ERROR : Inverse flattening outside of valid range
32  * (250 to 350)
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')
41  *
42  * REUSE NOTES
43  *
44  * USNG is intended for reuse by any application that does conversions
45  * between geodetic coordinates and USNG coordinates.
46  *
47  * REFERENCES
48  *
49  * Further information on USNG can be found in the Reuse Manual.
50  *
51  * USNG originated from : Federal Geographic Data Committee
52  * 590 National Center
53  * 12201 Sunrise Valley Drive
54  * Reston, VA 22092
55  *
56  * LICENSES
57  *
58  * None apply to this component.
59  *
60  * RESTRICTIONS
61  *
62  *
63  * ENVIRONMENT
64  *
65  * USNG was tested and certified in the following environments:
66  *
67  * 1. Solaris 2.5 with GCC version 2.8.1
68  * 2. Windows XP with MS Visual C++ version 6
69  *
70  * MODIFICATIONS
71  *
72  * Date Description
73  * ---- -----------
74  * 3-1-07 Original Code (cloned from MGRS)
75  */
76 
77 
78 #include "CoordinateSystem.h"
79 
80 
81 namespace MSP
82 {
83  namespace CCS
84  {
85  class UPS;
86  class UTM;
87  class EllipsoidParameters;
88  class MGRSorUSNGCoordinates;
89  class GeodeticCoordinates;
90  class UPSCoordinates;
91  class UTMCoordinates;
92 
93  #define USNG_LETTERS 3
94 
95  /**********************************************************************/
96  /*
97  * DEFINES
98  */
99 
100  class USNG : public CoordinateSystem
101  {
102  public:
103 
104  /*
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.
108  *
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)
112  */
113 
114  USNG( double ellipsoidSemiMajorAxis, double ellipsoidFlattening, char* ellipsoidCode );
115 
116 
117  USNG( const USNG &u );
118 
119 
120  ~USNG( void );
121 
122 
123  USNG& operator=( const USNG &u );
124 
125 
126  /*
127  * The function getParameters returns the current ellipsoid
128  * parameters.
129  *
130  * ellipsoidSemiMajorAxis : Semi-major axis of ellipsoid, in meters (output)
131  * ellipsoidFlattening : Flattening of ellipsoid (output)
132  * ellipsoidCode : 2-letter code for ellipsoid (output)
133  */
134 
135  EllipsoidParameters* getParameters() const;
136 
137 
138  /*
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.
143  *
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)
148  *
149  */
150 
151  MSP::CCS::MGRSorUSNGCoordinates* convertFromGeodetic( MSP::CCS::GeodeticCoordinates* geodeticCoordinates, long precision );
152 
153 
154  /*
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.
159  *
160  * USNG : USNG coordinate string (input)
161  * latitude : Latitude in radians (output)
162  * longitude : Longitude in radians (output)
163  *
164  */
165 
166  MSP::CCS::GeodeticCoordinates* convertToGeodetic( MSP::CCS::MGRSorUSNGCoordinates* mgrsCoordinates );
167 
168 
169  /*
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.
174  *
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)
181  */
182 
183  MSP::CCS::MGRSorUSNGCoordinates* convertFromUTM( UTMCoordinates* utmCoordinates, long precision );
184 
185 
186  /*
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.
191  *
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)
197  */
198 
199  MSP::CCS::UTMCoordinates* convertToUTM( MSP::CCS::MGRSorUSNGCoordinates* mgrsorUSNGCoordinates );
200 
201 
202  /*
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.
207  *
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)
213  */
214 
215  MSP::CCS::MGRSorUSNGCoordinates* convertFromUPS( MSP::CCS::UPSCoordinates* upsCoordinates, long precision );
216 
217 
218  /*
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.
223  *
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)
228  */
229 
230  MSP::CCS::UPSCoordinates* convertToUPS( MSP::CCS::MGRSorUSNGCoordinates* mgrsorUSNGCoordinates );
231 
232  private:
233 
234  UPS* ups;
235  UTM* utm;
236 
237  char USNGEllipsoidCode[3];
238 
239 
240  /*
241  * The function fromUTM calculates an USNG coordinate string
242  * based on the zone, latitude, easting and northing.
243  *
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)
250  */
251 
252  MSP::CCS::MGRSorUSNGCoordinates* fromUTM( MSP::CCS::UTMCoordinates* utmCoordinates, double longitude, double latitude, long precision );
253 
254 
255  /*
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.
260  *
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)
266  */
267 
268  UTMCoordinates* toUTM( long zone, long letters[USNG_LETTERS], double easting, double northing, long in_precision );
269 
270 
271  /*
272  * The function fromUPS converts UPS (hemisphere, easting,
273  * and northing) coordinates to an USNG coordinate string according to
274  * the current ellipsoid parameters.
275  *
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)
281  */
282 
283  MSP::CCS::MGRSorUSNGCoordinates* fromUPS( MSP::CCS::UPSCoordinates* upsCoordinates, long precision );
284 
285  /*
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.
290  *
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)
295  */
296 
297  MSP::CCS::UPSCoordinates* toUPS( long letters[USNG_LETTERS], double easting, double northing );
298 
299 
300  /*
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.
306  *
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)
311  */
312 
313  void getGridValues( long zone, long* ltr2_low_value, long* ltr2_high_value, double* pattern_offset );
314 
315 
316  /*
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.
320  *
321  * letter : Latitude band letter (input)
322  * min_northing : Minimum northing for that letter (output)
323  * northing_offset : Latitude band northing offset (output)
324  */
325 
326  void getLatitudeBandMinNorthing( long letter, double* min_northing, double* northing_offset );
327 
328 
329  /*
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.
333  *
334  * letter : Latitude band letter (input)
335  * north : Northern latitude boundary for that letter (output)
336  * north : Southern latitude boundary for that letter (output)
337  */
338 
339  void getLatitudeRange( long letter, double* north, double* south );
340 
341 
342  /*
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.
346  *
347  * latitude : Latitude (input)
348  * letter : Latitude band letter (output)
349  */
350 
351  void getLatitudeLetter( double latitude, int* letter );
352  };
353  }
354 }
355 
356 #endif
357 
358 
359 // CLASSIFICATION: UNCLASSIFIED
Generated on Tue Feb 16 2016 14:54:02 for GeographicTranslator by doxygen 1.8.2