NETGeographicLib 1.52
Loading...
Searching...
No Matches
GeoCoords.h
Go to the documentation of this file.
1/**
2 * \file NETGeographicLib/GeoCoords.h
3 * \brief Header for NETGeographicLib::GeoCoords class
4 *
5 * NETGeographicLib is copyright (c) Scott Heiman (2013)
6 * GeographicLib is Copyright (c) Charles Karney (2010-2012)
7 * <charles@karney.com> and licensed under the MIT/X11 License.
8 * For more information, see
9 * https://geographiclib.sourceforge.io/
10 **********************************************************************/
11#pragma once
12
13namespace NETGeographicLib
14{
15 /**
16 * \brief .NET wrapper for GeographicLib::GeoCoords.
17 *
18 * This class allows .NET applications to access GeographicLib::GeoCoords.
19 *
20 * This class stores a geographic position which may be set via the
21 * constructors or Reset via
22 * - latitude and longitude
23 * - UTM or UPS coordinates
24 * - a string representation of these or an MGRS coordinate string
25 *
26 * The state consists of the latitude and longitude and the supplied UTM or
27 * UPS coordinates (possibly derived from the MGRS coordinates). If latitude
28 * and longitude were given then the UTM/UPS coordinates follows the standard
29 * conventions.
30 *
31 * The mutable state consists of the UTM or UPS coordinates for a alternate
32 * zone. A method SetAltZone is provided to set the alternate UPS/UTM zone.
33 *
34 * Methods are provided to return the geographic coordinates, the input UTM
35 * or UPS coordinates (and associated meridian convergence and scale), or
36 * alternate UTM or UPS coordinates (and their associated meridian
37 * convergence and scale).
38 *
39 * Once the input string has been parsed, you can print the result out in any
40 * of the formats, decimal degrees, degrees minutes seconds, MGRS, UTM/UPS.
41 *
42 * C# Example:
43 * \include example-GeoCoords.cs
44 * Managed C++ Example:
45 * \include example-GeoCoords.cpp
46 * Visual Basic Example:
47 * \include example-GeoCoords.vb
48 *
49 * <B>INTERFACE DIFFERENCES:</B><BR>
50 * The following functions are implemented as properties: EquatorialRadius,
51 * Flattening, Latitude, Longitude, Easting, Northing, Convergence,
52 * Scale, Northp, Hemisphere, Zone, AltZone, AltEasting, AltNorthing,
53 * AltConvergence, and AltScale.
54 **********************************************************************/
55 public ref class GeoCoords
56 {
57 private:
58 // pointer to the unmanaged GeographicLib::GeoCoords
59 GeographicLib::GeoCoords* m_pGeoCoords;
60
61 // The finalizer frees unmanaged memory when the object is destroyed.
62 !GeoCoords();
63 public:
64 /** \name Initializing the GeoCoords object
65 **********************************************************************/
66 ///@{
67 /**
68 * The default constructor sets the coordinate as undefined.
69 **********************************************************************/
71
72 /**
73 * Construct from a string.
74 *
75 * @param[in] s 1-element, 2-element, or 3-element string representation of
76 * the position.
77 * @param[in] centerp governs the interpretation of MGRS coordinates (see
78 * below).
79 * @param[in] longfirst governs the interpretation of geographic
80 * coordinates (see below).
81 * @exception GeographicErr if the \e s is malformed (see below).
82 *
83 * Parse as a string and interpret it as a geographic position. The input
84 * string is broken into space (or comma) separated pieces and Basic
85 * decision on which format is based on number of components
86 * -# MGRS
87 * -# "Lat Long" or "Long Lat"
88 * -# "Zone Easting Northing" or "Easting Northing Zone"
89 *
90 * The following inputs are approximately the same (Ar Ramadi Bridge, Iraq)
91 * - Latitude and Longitude
92 * - 33.44 43.27
93 * - N33d26.4' E43d16.2'
94 * - 43d16'12&quot;E 33d26'24&quot;N
95 * - 43:16:12E 33:26:24
96 * - MGRS
97 * - 38SLC30
98 * - 38SLC391014
99 * - 38SLC3918701405
100 * - 37SHT9708
101 * - UTM
102 * - 38N 339188 3701405
103 * - 897039 3708229 37N
104 *
105 * <b>Latitude and Longitude parsing</b>: Latitude precedes longitude,
106 * unless a N, S, E, W hemisphere designator is used on one or both
107 * coordinates. If \e longfirst = true (default is false), then
108 * longitude precedes latitude in the absence of a hemisphere designator.
109 * Thus (with \e longfirst = false)
110 * - 40 -75
111 * - N40 W75
112 * - -75 N40
113 * - 75W 40N
114 * - E-75 -40S
115 * .
116 * are all the same position. The coordinates may be given in
117 * decimal degrees, degrees and decimal minutes, degrees, minutes,
118 * seconds, etc. Use d, ', and &quot; to mark off the degrees,
119 * minutes and seconds. Various alternative symbols for degrees, minutes,
120 * and seconds are allowed. Alternatively, use : to separate these
121 * components. (See DMS::Decode for details.) Thus
122 * - 40d30'30&quot;
123 * - 40d30'30
124 * - 40&deg;30'30
125 * - 40d30.5'
126 * - 40d30.5
127 * - 40:30:30
128 * - 40:30.5
129 * - 40.508333333
130 * .
131 * all specify the same angle. The leading sign applies to all
132 * components so -1d30 is -(1+30/60) = -1.5. Latitudes must be in the
133 * range [&minus;90&deg;, 90&deg;]. Internally longitudes are reduced
134 * to the range [&minus;180&deg;, 180&deg;).
135 *
136 * <b>UTM/UPS parsing</b>: For UTM zones (&minus;80&deg; &le; Lat <
137 * 84&deg;), the zone designator is made up of a zone number (for 1 to 60)
138 * and a hemisphere letter (N or S), e.g., 38N. The latitude zone designer
139 * ([C--M] in the southern hemisphere and [N--X] in the northern) should
140 * NOT be used. (This is part of the MGRS coordinate.) The zone
141 * designator for the poles (where UPS is employed) is a hemisphere letter
142 * by itself, i.e., N or S.
143 *
144 * <b>MGRS parsing</b> interprets the grid references as square area at the
145 * specified precision (1m, 10m, 100m, etc.). If \e centerp = true (the
146 * default), the center of this square is then taken to be the precise
147 * position; thus:
148 * - 38SMB = 38N 450000 3650000
149 * - 38SMB4484 = 38N 444500 3684500
150 * - 38SMB44148470 = 38N 444145 3684705
151 * .
152 * Otherwise, the "south-west" corner of the square is used, i.e.,
153 * - 38SMB = 38N 400000 3600000
154 * - 38SMB4484 = 38N 444000 3684000
155 * - 38SMB44148470 = 38N 444140 3684700
156 **********************************************************************/
157 GeoCoords(System::String^ s, bool centerp, bool longfirst );
158
159 /**
160 * Construct from geographic coordinates.
161 *
162 * @param[in] latitude (degrees).
163 * @param[in] longitude (degrees).
164 * @param[in] zone if specified, force the UTM/UPS representation to use a
165 * specified zone using the rules given in UTMUPS::zonespec.
166 * @exception GeographicErr if \e latitude is not in [&minus;90&deg;,
167 * 90&deg;].
168 * @exception GeographicErr if \e zone cannot be used for this location.
169 **********************************************************************/
170 GeoCoords(double latitude, double longitude, int zone );
171
172 /**
173 * Construct from UTM/UPS coordinates.
174 *
175 * @param[in] zone UTM zone (zero means UPS).
176 * @param[in] northp hemisphere (true means north, false means south).
177 * @param[in] easting (meters).
178 * @param[in] northing (meters).
179 * @exception GeographicErr if \e zone, \e easting, or \e northing is
180 * outside its allowed range.
181 **********************************************************************/
182 GeoCoords(int zone, bool northp, double easting, double northing);
183
184 /**
185 * The destructor calls the finalizer.
186 **********************************************************************/
187 ~GeoCoords() { this->!GeoCoords(); }
188
189 /**
190 * Reset the location from a string. See
191 * GeoCoords(const std::string& s, bool centerp, bool longfirst).
192 *
193 * @param[in] s 1-element, 2-element, or 3-element string representation of
194 * the position.
195 * @param[in] centerp governs the interpretation of MGRS coordinates.
196 * @param[in] longfirst governs the interpretation of geographic
197 * coordinates.
198 * @exception GeographicErr if the \e s is malformed.
199 **********************************************************************/
200 void Reset( System::String^ s, bool centerp, bool longfirst);
201
202 /**
203 * Reset the location in terms of geographic coordinates. See
204 * GeoCoords(double latitude, double longitude, int zone).
205 *
206 * @param[in] latitude (degrees).
207 * @param[in] longitude (degrees).
208 * @param[in] zone if specified, force the UTM/UPS representation to use a
209 * specified zone using the rules given in UTMUPS::zonespec.
210 * @exception GeographicErr if \e latitude is not in [&minus;90&deg;,
211 * 90&deg;].
212 * @exception GeographicErr if \e zone cannot be used for this location.
213 **********************************************************************/
214 void Reset(double latitude, double longitude, int zone ) ;
215
216 /**
217 * Reset the location in terms of UPS/UPS coordinates. See
218 * GeoCoords(int zone, bool northp, double easting, double northing).
219 *
220 * @param[in] zone UTM zone (zero means UPS).
221 * @param[in] northp hemisphere (true means north, false means south).
222 * @param[in] easting (meters).
223 * @param[in] northing (meters).
224 * @exception GeographicErr if \e zone, \e easting, or \e northing is
225 * outside its allowed range.
226 **********************************************************************/
227 void Reset(int zone, bool northp, double easting, double northing);
228 ///@}
229
230 /** \name Querying the GeoCoords object
231 **********************************************************************/
232 ///@{
233 /**
234 * @return latitude (degrees)
235 **********************************************************************/
236 property double Latitude { double get(); }
237
238 /**
239 * @return longitude (degrees)
240 **********************************************************************/
241 property double Longitude { double get(); }
242
243 /**
244 * @return easting (meters)
245 **********************************************************************/
246 property double Easting { double get(); }
247
248 /**
249 * @return northing (meters)
250 **********************************************************************/
251 property double Northing { double get(); }
252
253 /**
254 * @return meridian convergence (degrees) for the UTM/UPS projection.
255 **********************************************************************/
256 property double Convergence { double get(); }
257
258 /**
259 * @return scale for the UTM/UPS projection.
260 **********************************************************************/
261 property double Scale { double get(); }
262
263 /**
264 * @return hemisphere (false means south, true means north).
265 **********************************************************************/
266 property bool Northp { bool get(); }
267
268 /**
269 * @return hemisphere letter N or S.
270 **********************************************************************/
271 property char Hemisphere { char get(); }
272
273 /**
274 * @return the zone corresponding to the input (return 0 for UPS).
275 **********************************************************************/
276 property int Zone { int get(); }
277 ///@}
278
279 /** \name Setting and querying the alternate zone
280 **********************************************************************/
281 ///@{
282 /**
283 * Gets/Sets the current alternate zone (0 = UPS).
284 * @exception GeographicErr if \e zone cannot be used for this location.
285 *
286 * See UTMUPS::zonespec for more information on the interpretation of \e
287 * zone. Note that \e zone == UTMUPS::STANDARD (the default) use the
288 * standard UPS or UTM zone, UTMUPS::MATCH does nothing retaining the
289 * existing alternate representation. Before this is called the alternate
290 * zone is the input zone.
291 **********************************************************************/
292 property int AltZone
293 {
294 int get();
295 void set( int zone );
296 }
297
298 /**
299 * @return easting (meters) for alternate zone.
300 **********************************************************************/
301 property double AltEasting { double get(); }
302
303 /**
304 * @return northing (meters) for alternate zone.
305 **********************************************************************/
306 property double AltNorthing { double get(); }
307
308 /**
309 * @return meridian convergence (degrees) for alternate zone.
310 **********************************************************************/
311 property double AltConvergence { double get(); }
312
313 /**
314 * @return scale for alternate zone.
315 **********************************************************************/
316 property double AltScale { double get(); }
317 ///@}
318
319 /** \name String representations of the GeoCoords object
320 **********************************************************************/
321 ///@{
322 /**
323 * String representation with latitude and longitude as signed decimal
324 * degrees.
325 *
326 * @param[in] prec precision (relative to about 1m).
327 * @param[in] longfirst if true give longitude first (default = false)
328 * @exception std::bad_alloc if memory for the string can't be allocated.
329 * @return decimal latitude/longitude string representation.
330 *
331 * Precision specifies accuracy of representation as follows:
332 * - prec = &minus;5 (min), 1&deg;
333 * - prec = 0, 10<sup>&minus;5</sup>&deg; (about 1m)
334 * - prec = 3, 10<sup>&minus;8</sup>&deg;
335 * - prec = 9 (max), 10<sup>&minus;14</sup>&deg;
336 **********************************************************************/
337 System::String^ GeoRepresentation(int prec, bool longfirst );
338
339 /**
340 * String representation with latitude and longitude as degrees, minutes,
341 * seconds, and hemisphere.
342 *
343 * @param[in] prec precision (relative to about 1m)
344 * @param[in] longfirst if true give longitude first (default = false)
345 * @param[in] dmssep if non-null, use as the DMS separator character
346 * (instead of d, ', &quot; delimiters).
347 * @exception std::bad_alloc if memory for the string can't be allocated.
348 * @return DMS latitude/longitude string representation.
349 *
350 * Precision specifies accuracy of representation as follows:
351 * - prec = &minus;5 (min), 1&deg;
352 * - prec = &minus;4, 0.1&deg;
353 * - prec = &minus;3, 1'
354 * - prec = &minus;2, 0.1'
355 * - prec = &minus;1, 1&quot;
356 * - prec = 0, 0.1&quot; (about 3m)
357 * - prec = 1, 0.01&quot;
358 * - prec = 10 (max), 10<sup>&minus;11</sup>&quot;
359 **********************************************************************/
360 System::String^ DMSRepresentation(int prec, bool longfirst,
361 char dmssep );
362
363 /**
364 * MGRS string.
365 *
366 * @param[in] prec precision (relative to about 1m).
367 * @exception std::bad_alloc if memory for the string can't be allocated.
368 * @return MGRS string.
369 *
370 * This gives the coordinates of the enclosing grid square with size given
371 * by the precision. Thus 38N 444180 3684790 converted to a MGRS
372 * coordinate at precision &minus;2 (100m) is 38SMB441847 and not
373 * 38SMB442848. \e prec specifies the precision of the MGRS string as
374 * follows:
375 * - prec = &minus;5 (min), 100km
376 * - prec = &minus;4, 10km
377 * - prec = &minus;3, 1km
378 * - prec = &minus;2, 100m
379 * - prec = &minus;1, 10m
380 * - prec = 0, 1m
381 * - prec = 1, 0.1m
382 * - prec = 6 (max), 1&mu;m
383 **********************************************************************/
384 System::String^ MGRSRepresentation(int prec);
385
386 /**
387 * UTM/UPS string.
388 *
389 * @param[in] prec precision (relative to about 1m)
390 * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
391 * for hemisphere; otherwise spell out the hemisphere (north/south)
392 * @exception std::bad_alloc if memory for the string can't be allocated.
393 * @return UTM/UPS string representation: zone designator, easting, and
394 * northing.
395 *
396 * Precision specifies accuracy of representation as follows:
397 * - prec = &minus;5 (min), 100km
398 * - prec = &minus;3, 1km
399 * - prec = 0, 1m
400 * - prec = 3, 1mm
401 * - prec = 6, 1&mu;m
402 * - prec = 9 (max), 1nm
403 **********************************************************************/
404 System::String^ UTMUPSRepresentation(int prec, bool abbrev);
405
406 /**
407 * UTM/UPS string with hemisphere override.
408 *
409 * @param[in] northp hemisphere override
410 * @param[in] prec precision (relative to about 1m)
411 * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
412 * for hemisphere; otherwise spell out the hemisphere (north/south)
413 * @exception GeographicErr if the hemisphere override attempts to change
414 * UPS N to UPS S or vice versa.
415 * @exception std::bad_alloc if memory for the string can't be allocated.
416 * @return UTM/UPS string representation: zone designator, easting, and
417 * northing.
418 **********************************************************************/
419 System::String^ UTMUPSRepresentation(bool northp, int prec, bool abbrev);
420
421 /**
422 * MGRS string for the alternate zone. See GeoCoords::MGRSRepresentation.
423 *
424 * @param[in] prec precision (relative to about 1m).
425 * @exception std::bad_alloc if memory for the string can't be allocated.
426 * @return MGRS string.
427 **********************************************************************/
428 System::String^ AltMGRSRepresentation(int prec);
429
430 /**
431 * UTM/UPS string for the alternate zone. See
432 * GeoCoords::UTMUPSRepresentation.
433 *
434 * @param[in] prec precision (relative to about 1m)
435 * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
436 * for hemisphere; otherwise spell out the hemisphere (north/south)
437 * @exception std::bad_alloc if memory for the string can't be allocated.
438 * @return UTM/UPS string representation: zone designator, easting, and
439 * northing.
440 **********************************************************************/
441 System::String^ AltUTMUPSRepresentation(int prec, bool abbrev);
442
443 /**
444 * UTM/UPS string for the alternate zone, with hemisphere override.
445 *
446 * @param[in] northp hemisphere override
447 * @param[in] prec precision (relative to about 1m)
448 * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
449 * for hemisphere; otherwise spell out the hemisphere (north/south)
450 * @exception GeographicErr if the hemisphere override attempts to change
451 * UPS n to UPS s or vice verse.
452 * @exception std::bad_alloc if memory for the string can't be allocated.
453 * @return UTM/UPS string representation: zone designator, easting, and
454 * northing.
455 **********************************************************************/
456 System::String^ AltUTMUPSRepresentation(bool northp, int prec, bool abbrev);
457 ///@}
458
459 /** \name Inspector functions
460 **********************************************************************/
461 ///@{
462 /**
463 * @return \e a the equatorial radius of the WGS84 ellipsoid (meters).
464 *
465 * (The WGS84 value is returned because the UTM and UPS projections are
466 * based on this ellipsoid.)
467 **********************************************************************/
468 property double EquatorialRadius { double get(); }
469
470 /**
471 * @return \e f the flattening of the WGS84 ellipsoid.
472 *
473 * (The WGS84 value is returned because the UTM and UPS projections are
474 * based on this ellipsoid.)
475 **********************************************************************/
476 property double Flattening { double get(); }
477 ///@}
478 };
479} //namespace NETGeographicLib
.NET wrapper for GeographicLib::GeoCoords.
Definition: GeoCoords.h:56
GeoCoords(double latitude, double longitude, int zone)
System::String ^ GeoRepresentation(int prec, bool longfirst)
System::String ^ UTMUPSRepresentation(int prec, bool abbrev)
System::String ^ AltMGRSRepresentation(int prec)
GeoCoords(System::String^ s, bool centerp, bool longfirst)
System::String ^ MGRSRepresentation(int prec)
void Reset(System::String^ s, bool centerp, bool longfirst)
System::String ^ AltUTMUPSRepresentation(int prec, bool abbrev)
System::String ^ DMSRepresentation(int prec, bool longfirst, char dmssep)
void Reset(double latitude, double longitude, int zone)
System::String ^ UTMUPSRepresentation(bool northp, int prec, bool abbrev)
GeoCoords(int zone, bool northp, double easting, double northing)
System::String ^ AltUTMUPSRepresentation(bool northp, int prec, bool abbrev)