NETGeographicLib  1.50.1
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 
13 namespace 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  * Gets/Sets the current alternate zone (0 = UPS).
280  * @exception GeographicErr if \e zone cannot be used for this location.
281  *
282  * See UTMUPS::zonespec for more information on the interpretation of \e
283  * zone. Note that \e zone == UTMUPS::STANDARD (the default) use the
284  * standard UPS or UTM zone, UTMUPS::MATCH does nothing retaining the
285  * existing alternate representation. Before this is called the alternate
286  * zone is the input zone.
287  **********************************************************************/
288  property int AltZone
289  {
290  int get();
291  void set( int zone );
292  }
293  ///@}
294 
295  /**
296  * @return easting (meters) for alternate zone.
297  **********************************************************************/
298  property double AltEasting { double get(); }
299 
300  /**
301  * @return northing (meters) for alternate zone.
302  **********************************************************************/
303  property double AltNorthing { double get(); }
304 
305  /**
306  * @return meridian convergence (degrees) for alternate zone.
307  **********************************************************************/
308  property double AltConvergence { double get(); }
309 
310  /**
311  * @return scale for alternate zone.
312  **********************************************************************/
313  property double AltScale { double get(); }
314  ///@}
315 
316  /** \name String representations of the GeoCoords object
317  **********************************************************************/
318  ///@{
319  /**
320  * String representation with latitude and longitude as signed decimal
321  * degrees.
322  *
323  * @param[in] prec precision (relative to about 1m).
324  * @param[in] longfirst if true give longitude first (default = false)
325  * @exception std::bad_alloc if memory for the string can't be allocated.
326  * @return decimal latitude/longitude string representation.
327  *
328  * Precision specifies accuracy of representation as follows:
329  * - prec = &minus;5 (min), 1&deg;
330  * - prec = 0, 10<sup>&minus;5</sup>&deg; (about 1m)
331  * - prec = 3, 10<sup>&minus;8</sup>&deg;
332  * - prec = 9 (max), 10<sup>&minus;14</sup>&deg;
333  **********************************************************************/
334  System::String^ GeoRepresentation(int prec, bool longfirst );
335 
336  /**
337  * String representation with latitude and longitude as degrees, minutes,
338  * seconds, and hemisphere.
339  *
340  * @param[in] prec precision (relative to about 1m)
341  * @param[in] longfirst if true give longitude first (default = false)
342  * @param[in] dmssep if non-null, use as the DMS separator character
343  * (instead of d, ', &quot; delimiters).
344  * @exception std::bad_alloc if memory for the string can't be allocated.
345  * @return DMS latitude/longitude string representation.
346  *
347  * Precision specifies accuracy of representation as follows:
348  * - prec = &minus;5 (min), 1&deg;
349  * - prec = &minus;4, 0.1&deg;
350  * - prec = &minus;3, 1'
351  * - prec = &minus;2, 0.1'
352  * - prec = &minus;1, 1&quot;
353  * - prec = 0, 0.1&quot; (about 3m)
354  * - prec = 1, 0.01&quot;
355  * - prec = 10 (max), 10<sup>&minus;11</sup>&quot;
356  **********************************************************************/
357  System::String^ DMSRepresentation(int prec, bool longfirst,
358  char dmssep );
359 
360  /**
361  * MGRS string.
362  *
363  * @param[in] prec precision (relative to about 1m).
364  * @exception std::bad_alloc if memory for the string can't be allocated.
365  * @return MGRS string.
366  *
367  * This gives the coordinates of the enclosing grid square with size given
368  * by the precision. Thus 38N 444180 3684790 converted to a MGRS
369  * coordinate at precision &minus;2 (100m) is 38SMB441847 and not
370  * 38SMB442848. \e prec specifies the precision of the MGRS string as
371  * follows:
372  * - prec = &minus;5 (min), 100km
373  * - prec = &minus;4, 10km
374  * - prec = &minus;3, 1km
375  * - prec = &minus;2, 100m
376  * - prec = &minus;1, 10m
377  * - prec = 0, 1m
378  * - prec = 1, 0.1m
379  * - prec = 6 (max), 1&mu;m
380  **********************************************************************/
381  System::String^ MGRSRepresentation(int prec);
382 
383  /**
384  * UTM/UPS string.
385  *
386  * @param[in] prec precision (relative to about 1m)
387  * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
388  * for hemisphere; otherwise spell out the hemisphere (north/south)
389  * @exception std::bad_alloc if memory for the string can't be allocated.
390  * @return UTM/UPS string representation: zone designator, easting, and
391  * northing.
392  *
393  * Precision specifies accuracy of representation as follows:
394  * - prec = &minus;5 (min), 100km
395  * - prec = &minus;3, 1km
396  * - prec = 0, 1m
397  * - prec = 3, 1mm
398  * - prec = 6, 1&mu;m
399  * - prec = 9 (max), 1nm
400  **********************************************************************/
401  System::String^ UTMUPSRepresentation(int prec, bool abbrev);
402 
403  /**
404  * UTM/UPS string with hemisphere override.
405  *
406  * @param[in] northp hemisphere override
407  * @param[in] prec precision (relative to about 1m)
408  * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
409  * for hemisphere; otherwise spell out the hemisphere (north/south)
410  * @exception GeographicErr if the hemisphere override attempts to change
411  * UPS N to UPS S or vice versa.
412  * @exception std::bad_alloc if memory for the string can't be allocated.
413  * @return UTM/UPS string representation: zone designator, easting, and
414  * northing.
415  **********************************************************************/
416  System::String^ UTMUPSRepresentation(bool northp, int prec, bool abbrev);
417 
418  /**
419  * MGRS string for the alternate zone. See GeoCoords::MGRSRepresentation.
420  *
421  * @param[in] prec precision (relative to about 1m).
422  * @exception std::bad_alloc if memory for the string can't be allocated.
423  * @return MGRS string.
424  **********************************************************************/
425  System::String^ AltMGRSRepresentation(int prec);
426 
427  /**
428  * UTM/UPS string for the alternate zone. See
429  * GeoCoords::UTMUPSRepresentation.
430  *
431  * @param[in] prec precision (relative to about 1m)
432  * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
433  * for hemisphere; otherwise spell out the hemisphere (north/south)
434  * @exception std::bad_alloc if memory for the string can't be allocated.
435  * @return UTM/UPS string representation: zone designator, easting, and
436  * northing.
437  **********************************************************************/
438  System::String^ AltUTMUPSRepresentation(int prec, bool abbrev);
439 
440  /**
441  * UTM/UPS string for the alternate zone, with hemisphere override.
442  *
443  * @param[in] northp hemisphere override
444  * @param[in] prec precision (relative to about 1m)
445  * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
446  * for hemisphere; otherwise spell out the hemisphere (north/south)
447  * @exception GeographicErr if the hemisphere override attempts to change
448  * UPS n to UPS s or vice verse.
449  * @exception std::bad_alloc if memory for the string can't be allocated.
450  * @return UTM/UPS string representation: zone designator, easting, and
451  * northing.
452  **********************************************************************/
453  System::String^ AltUTMUPSRepresentation(bool northp, int prec, bool abbrev);
454  ///@}
455 
456  /** \name Inspector functions
457  **********************************************************************/
458  ///@{
459  /**
460  * @return \e a the equatorial radius of the WGS84 ellipsoid (meters).
461  *
462  * (The WGS84 value is returned because the UTM and UPS projections are
463  * based on this ellipsoid.)
464  **********************************************************************/
465  property double EquatorialRadius { double get(); }
466 
467  /**
468  * @return \e f the flattening of the WGS84 ellipsoid.
469  *
470  * (The WGS84 value is returned because the UTM and UPS projections are
471  * based on this ellipsoid.)
472  **********************************************************************/
473  property double Flattening { double get(); }
474  ///@}
475  };
476 } //namespace NETGeographicLib
NETGeographicLib::GeoCoords::Northing
double Northing
Definition: GeoCoords.h:251
NETGeographicLib::GeoCoords::Easting
double Easting
Definition: GeoCoords.h:246
NETGeographicLib::GeoCoords::GeoCoords
GeoCoords()
NETGeographicLib::GeoCoords::Zone
int Zone
Definition: GeoCoords.h:276
NETGeographicLib::GeoCoords::Reset
void Reset(double latitude, double longitude, int zone)
NETGeographicLib::GeoCoords::Scale
double Scale
Definition: GeoCoords.h:261
NETGeographicLib::GeoCoords::GeoCoords
GeoCoords(double latitude, double longitude, int zone)
NETGeographicLib::GeoCoords::Longitude
double Longitude
Definition: GeoCoords.h:241
NETGeographicLib::GeoCoords::Northp
bool Northp
Definition: GeoCoords.h:266
NETGeographicLib::GeoCoords::Convergence
double Convergence
Definition: GeoCoords.h:256
NETGeographicLib::GeoCoords::GeoRepresentation
System::String ^ GeoRepresentation(int prec, bool longfirst)
NETGeographicLib::GeoCoords::AltNorthing
double AltNorthing
Definition: GeoCoords.h:303
NETGeographicLib::GeoCoords::Flattening
double Flattening
Definition: GeoCoords.h:473
NETGeographicLib::GeoCoords::AltConvergence
double AltConvergence
Definition: GeoCoords.h:308
NETGeographicLib::GeoCoords::EquatorialRadius
double EquatorialRadius
Definition: GeoCoords.h:465
NETGeographicLib::GeoCoords::~GeoCoords
~GeoCoords()
Definition: GeoCoords.h:187
NETGeographicLib::GeoCoords::Hemisphere
char Hemisphere
Definition: GeoCoords.h:271
NETGeographicLib::GeoCoords::AltEasting
double AltEasting
Definition: GeoCoords.h:298
GeographicLib::GeoCoords
NETGeographicLib::GeoCoords::AltScale
double AltScale
Definition: GeoCoords.h:313
NETGeographicLib::GeoCoords::Latitude
double Latitude
Definition: GeoCoords.h:236
NETGeographicLib::GeoCoords::UTMUPSRepresentation
System::String ^ UTMUPSRepresentation(bool northp, int prec, bool abbrev)
NETGeographicLib::GeoCoords::AltZone
int AltZone
Definition: GeoCoords.h:288
NETGeographicLib::GeoCoords::DMSRepresentation
System::String ^ DMSRepresentation(int prec, bool longfirst, char dmssep)
NETGeographicLib::GeoCoords::MGRSRepresentation
System::String ^ MGRSRepresentation(int prec)
NETGeographicLib::GeoCoords::Reset
void Reset(System::String^ s, bool centerp, bool longfirst)
NETGeographicLib::GeoCoords
.NET wrapper for GeographicLib::GeoCoords.
Definition: GeoCoords.h:56
NETGeographicLib::GeoCoords::GeoCoords
GeoCoords(System::String^ s, bool centerp, bool longfirst)
NETGeographicLib::GeoCoords::GeoCoords
GeoCoords(int zone, bool northp, double easting, double northing)
NETGeographicLib::GeoCoords::AltMGRSRepresentation
System::String ^ AltMGRSRepresentation(int prec)
NETGeographicLib::GeoCoords::AltUTMUPSRepresentation
System::String ^ AltUTMUPSRepresentation(int prec, bool abbrev)
NETGeographicLib
Definition: Accumulator.h:14
NETGeographicLib::GeoCoords::UTMUPSRepresentation
System::String ^ UTMUPSRepresentation(int prec, bool abbrev)