GeographicLib::GeoCoords Class Reference

Conversion between geographic coordinates. More...

#include <GeoCoords.hpp>

Public Member Functions
Initializing the GeoCoords object
	GeoCoords ()
	GeoCoords (const std::string &s, bool centerp=true, bool longfirst=false)
	GeoCoords (real latitude, real longitude, int zone=UTMUPS::STANDARD)
	GeoCoords (int zone, bool northp, real easting, real northing)
void	Reset (const std::string &s, bool centerp=true, bool longfirst=false)
void	Reset (real latitude, real longitude, int zone=UTMUPS::STANDARD)
void	Reset (int zone, bool northp, real easting, real northing)
Querying the GeoCoords object
Math::real	Latitude () const
Math::real	Longitude () const
Math::real	Easting () const
Math::real	Northing () const
Math::real	Convergence () const
Math::real	Scale () const
bool	Northp () const
char	Hemisphere () const
int	Zone () const
Setting and querying the alternate zone
void	SetAltZone (int zone=UTMUPS::STANDARD) const
int	AltZone () const
Math::real	AltEasting () const
Math::real	AltNorthing () const
Math::real	AltConvergence () const
Math::real	AltScale () const
String representations of the GeoCoords object
std::string	GeoRepresentation (int prec=0, bool longfirst=false) const
std::string	DMSRepresentation (int prec=0, bool longfirst=false, char dmssep=char(0)) const
std::string	MGRSRepresentation (int prec=0) const
std::string	UTMUPSRepresentation (int prec=0, bool abbrev=true) const
std::string	UTMUPSRepresentation (bool northp, int prec=0, bool abbrev=true) const
std::string	AltMGRSRepresentation (int prec=0) const
std::string	AltUTMUPSRepresentation (int prec=0, bool abbrev=true) const
std::string	AltUTMUPSRepresentation (bool northp, int prec=0, bool abbrev=true) const
Inspector functions
Math::real	MajorRadius () const
Math::real	Flattening () const

Private Types
typedef Math::real	real

Private Member Functions
void	CopyToAlt () const
void	FixHemisphere ()

Static Private Member Functions
static void	UTMUPSString (int zone, bool northp, real easting, real northing, int prec, bool abbrev, std::string &utm)

Private Attributes
real	_alt_easting
real	_alt_gamma
real	_alt_k
real	_alt_northing
int	_alt_zone
real	_easting
real	_gamma
real	_k
real	_lat
real	_long
real	_northing
bool	_northp
int	_zone

Detailed Description

Conversion between geographic coordinates.

This class stores a geographic position which may be set via the constructors or Reset via

• latitude and longitude
• UTM or UPS coordinates
• a string representation of these or an MGRS coordinate string

The state consists of the latitude and longitude and the supplied UTM or UPS coordinates (possibly derived from the MGRS coordinates). If latitude and longitude were given then the UTM/UPS coordinates follows the standard conventions.

The mutable state consists of the UTM or UPS coordinates for a alternate zone. A method SetAltZone is provided to set the alternate UPS/UTM zone.

Methods are provided to return the geographic coordinates, the input UTM or UPS coordinates (and associated meridian convergence and scale), or alternate UTM or UPS coordinates (and their associated meridian convergence and scale).

Once the input string has been parsed, you can print the result out in any of the formats, decimal degrees, degrees minutes seconds, MGRS, UTM/UPS.

Example of use:

// Example of using the GeographicLib::GeoCoords class

#include <iostream>
#include <exception>
#include <GeographicLib/GeoCoords.hpp>

using namespace std;
using namespace GeographicLib;

int main() {
  try {
    // Miscellaneous conversions
    double lat = 33.3, lon = 44.4;
    GeoCoords c(lat, lon);
    cout << c.MGRSRepresentation(-3) << "\n";
    c.Reset("18TWN0050");
    cout << c.DMSRepresentation() << "\n";
    cout << c.Latitude() << " " << c.Longitude() << "\n";
    c.Reset("1d38'W 55d30'N");
    cout << c.GeoRepresentation() << "\n";
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

GeoConvert is a command-line utility providing access to the functionality of GeoCoords.

Definition at line 49 of file GeoCoords.hpp.

Member Typedef Documentation

typedef Math::real GeographicLib::GeoCoords::real

private

Definition at line 51 of file GeoCoords.hpp.

Constructor & Destructor Documentation

GeographicLib::GeoCoords::GeoCoords ( )

inline

The default constructor sets the coordinate as undefined.

Definition at line 77 of file GeoCoords.hpp.

GeographicLib::GeoCoords::GeoCoords ( const std::string &  s, bool  centerp = true, bool  longfirst = false  )

inlineexplicit

Construct from a string.

Parameters

[in]	s	1-element, 2-element, or 3-element string representation of the position.
[in]	centerp	governs the interpretation of MGRS coordinates (see below).
[in]	longfirst	governs the interpretation of geographic coordinates (see below).

Exceptions

GeographicErr

if the s is malformed (see below).

Parse as a string and interpret it as a geographic position. The input string is broken into space (or comma) separated pieces and Basic decision on which format is based on number of components

1. MGRS
2. "Lat Long" or "Long Lat"
3. "Zone Easting Northing" or "Easting Northing Zone"

The following inputs are approximately the same (Ar Ramadi Bridge, Iraq)

• Latitude and Longitude
  • 33.44 43.27
  • N33d26.4' E43d16.2'
  • 43d16'12"E 33d26'24"N
  • 43:16:12E 33:26:24
• MGRS
  • 38SLC30
  • 38SLC391014
  • 38SLC3918701405
  • 37SHT9708
• UTM
  • 38n 339188 3701405
  • 897039 3708229 37n

Latitude and Longitude parsing: Latitude precedes longitude, unless a N, S, E, W hemisphere designator is used on one or both coordinates. If longfirst = true (default is false), then longitude precedes latitude in the absence of a hemisphere designator. Thus (with longfirst = false)

• 40 -75
• N40 W75
• -75 N40
• 75W 40N
• E-75 -40S

are all the same position. The coordinates may be given in decimal degrees, degrees and decimal minutes, degrees, minutes, seconds, etc. Use d, ', and " to mark off the degrees, minutes and seconds. Various alternative symbols for degrees, minutes, and seconds are allowed. Alternatively, use : to separate these components. A single addition or subtraction is allowed. (See DMS::Decode for details.) Thus

• 40d30'30"
• 40d30'30
• 40°30'30
• 40d30.5'
• 40d30.5
• 40:30:30
• 40:30.5
• 40.508333333
• 40:30+0:0:30
• 40:31-0:0.5

all specify the same angle. The leading sign applies to the following components so -1d30 is -(1+30/60) = −1.5. However, note that -1:30-0:0:15 is parsed as (-1:30) + (-0:0:15) = −(1+30/60) − (15/3600). Latitudes must be in the range [−90°, 90°]. Internally longitudes are reduced to the range [−180°, 180°].

UTM/UPS parsing: For UTM zones (−80° ≤ Lat < 84°), the zone designator is made up of a zone number (for 1 to 60) and a hemisphere letter (n or s), e.g., 38n (38north can also be used). The latitude band designer ([C–M] in the southern hemisphere and [N–X] in the northern) should NOT be used. (This is part of the MGRS coordinate.) The zone designator for the poles (where UPS is employed) is a hemisphere letter by itself, i.e., n or s (north or south can also be used).

MGRS parsing interprets the grid references as square area at the specified precision (1m, 10m, 100m, etc.). If centerp = true (the default), the center of this square is then taken to be the precise position; thus:

• 38SMB = 38n 450000 3650000
• 38SMB4484 = 38n 444500 3684500
• 38SMB44148470 = 38n 444145 3684705

Otherwise, the "south-west" corner of the square is used, i.e.,

• 38SMB = 38n 400000 3600000
• 38SMB4484 = 38n 444000 3684000
• 38SMB44148470 = 38n 444140 3684700

Definition at line 179 of file GeoCoords.hpp.

GeographicLib::GeoCoords::GeoCoords ( real  latitude, real  longitude, int  zone = UTMUPS::STANDARD  )

inline

Construct from geographic coordinates.

Parameters

[in]	latitude	(degrees).
[in]	longitude	(degrees).
[in]	zone	if specified, force the UTM/UPS representation to use a specified zone using the rules given in UTMUPS::zonespec.

Exceptions

GeographicErr	if latitude is not in [−90°, 90°].
GeographicErr	if zone cannot be used for this location.

Definition at line 194 of file GeoCoords.hpp.

GeographicLib::GeoCoords::GeoCoords ( int  zone, bool  northp, real  easting, real  northing  )

inline

Construct from UTM/UPS coordinates.

Parameters

[in]	zone	UTM zone (zero means UPS).
[in]	northp	hemisphere (true means north, false means south).
[in]	easting	(meters).
[in]	northing	(meters).

Exceptions

GeographicErr

if zone, easting, or northing is outside its allowed range.

Definition at line 208 of file GeoCoords.hpp.

Member Function Documentation

Math::real GeographicLib::GeoCoords::AltConvergence ( ) const

inline

Returns

meridian convergence (degrees) for alternate zone.

Definition at line 370 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::AltEasting ( ) const

inline

Returns

easting (meters) for alternate zone.

Definition at line 360 of file GeoCoords.hpp.

string GeographicLib::GeoCoords::AltMGRSRepresentation

(

int

prec = 0

)

const

MGRS string for the alternate zone. See GeoCoords::MGRSRepresentation.

Parameters

[in]

prec

precision (relative to about 1m).

Exceptions

std::bad_alloc

if memory for the string can't be allocated.

Returns

MGRS string.

Definition at line 97 of file src/GeoCoords.cpp.

Math::real GeographicLib::GeoCoords::AltNorthing ( ) const

inline

Returns

northing (meters) for alternate zone.

Definition at line 365 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::AltScale ( ) const

inline

Returns

scale for alternate zone.

Definition at line 375 of file GeoCoords.hpp.

string GeographicLib::GeoCoords::AltUTMUPSRepresentation	(	int	prec = 0,
		bool	abbrev = true
	)		const

UTM/UPS string for the alternate zone. See GeoCoords::UTMUPSRepresentation.

Parameters

[in]	prec	precision (relative to about 1m)
[in]	abbrev	if true (the default) use abbreviated (n/s) notation for hemisphere; otherwise spell out the hemisphere (north/south)

Exceptions

std::bad_alloc

if memory for the string can't be allocated.

Returns

UTM/UPS string representation: zone designator, easting, and northing.

Definition at line 146 of file src/GeoCoords.cpp.

string GeographicLib::GeoCoords::AltUTMUPSRepresentation	(	bool	northp,
		int	prec = 0,
		bool	abbrev = true
	)		const

UTM/UPS string for the alternate zone, with hemisphere override.

Parameters

[in]	northp	hemisphere override
[in]	prec	precision (relative to about 1m)
[in]	abbrev	if true (the default) use abbreviated (n/s) notation for hemisphere; otherwise spell out the hemisphere (north/south)

Exceptions

GeographicErr	if the hemisphere override attempts to change UPS n to UPS s or vice verse.
std::bad_alloc	if memory for the string can't be allocated.

Returns

UTM/UPS string representation: zone designator, easting, and northing.

Definition at line 153 of file src/GeoCoords.cpp.

int GeographicLib::GeoCoords::AltZone ( ) const

inline

Returns

current alternate zone (return 0 for UPS).

Definition at line 355 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Convergence ( ) const

inline

Returns

meridian convergence (degrees) for the UTM/UPS projection.

Definition at line 298 of file GeoCoords.hpp.

void GeographicLib::GeoCoords::CopyToAlt ( ) const

inlineprivate

Definition at line 58 of file GeoCoords.hpp.

string GeographicLib::GeoCoords::DMSRepresentation	(	int	prec = 0,
		bool	longfirst = false,
		char	dmssep = char(0)
	)		const

String representation with latitude and longitude as degrees, minutes, seconds, and hemisphere.

Parameters

[in]	prec	precision (relative to about 1m)
[in]	longfirst	if true give longitude first (default = false)
[in]	dmssep	if non-null, use as the DMS separator character (instead of d, ', " delimiters).

Exceptions

std::bad_alloc

if memory for the string can't be allocated.

Returns

DMS latitude/longitude string representation.

Precision specifies accuracy of representation as follows:

• prec = −5 (min), 1°
• prec = −4, 0.1°
• prec = −3, 1'
• prec = −2, 0.1'
• prec = −1, 1"
• prec = 0, 0.1" (about 3m)
• prec = 1, 0.01"
• prec = 10 (max), 10⁻¹¹"

Definition at line 80 of file src/GeoCoords.cpp.

Math::real GeographicLib::GeoCoords::Easting ( ) const

inline

Returns

easting (meters)

Definition at line 288 of file GeoCoords.hpp.

void GeographicLib::GeoCoords::FixHemisphere ( )

private

Definition at line 164 of file src/GeoCoords.cpp.

Math::real GeographicLib::GeoCoords::Flattening ( ) const

inline

Returns

f the flattening of the WGS84 ellipsoid.

(The WGS84 value is returned because the UTM and UPS projections are based on this ellipsoid.)

Definition at line 540 of file GeoCoords.hpp.

string GeographicLib::GeoCoords::GeoRepresentation	(	int	prec = 0,
		bool	longfirst = false
	)		const

String representation with latitude and longitude as signed decimal degrees.

Parameters

[in]	prec	precision (relative to about 1m).
[in]	longfirst	if true give longitude first (default = false)

Exceptions

std::bad_alloc

if memory for the string can't be allocated.

Returns

decimal latitude/longitude string representation.

Precision specifies accuracy of representation as follows:

• prec = −5 (min), 1°
• prec = 0, 10⁻⁵° (about 1m)
• prec = 3, 10⁻⁸°
• prec = 9 (max), 10⁻¹⁴°

Definition at line 62 of file src/GeoCoords.cpp.

char GeographicLib::GeoCoords::Hemisphere ( ) const

inline

Returns

hemisphere letter n or s.

Definition at line 313 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Latitude ( ) const

inline

Returns

latitude (degrees)

Definition at line 278 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Longitude ( ) const

inline

Returns

longitude (degrees)

Definition at line 283 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::MajorRadius ( ) const

inline

Returns

a the equatorial radius of the WGS84 ellipsoid (meters).

(The WGS84 value is returned because the UTM and UPS projections are based on this ellipsoid.)

Definition at line 532 of file GeoCoords.hpp.

string GeographicLib::GeoCoords::MGRSRepresentation

(

int

prec = 0

)

const

MGRS string.

Parameters

[in]

prec

precision (relative to about 1m).

Exceptions

std::bad_alloc

if memory for the string can't be allocated.

Returns

MGRS string.

This gives the coordinates of the enclosing grid square with size given by the precision. Thus 38n 444180 3684790 converted to a MGRS coordinate at precision −2 (100m) is 38SMB441847 and not 38SMB442848. prec specifies the precision of the MGRS string as follows:

• prec = −6 (min), only the grid zone is returned, e.g., 38S
• prec = −5, 100km, e.g., 38SMB
• prec = −4, 10km
• prec = −3, 1km
• prec = −2, 100m
• prec = −1, 10m
• prec = 0, 1m
• prec = 1, 0.1m
• prec = 6 (max), 1μm

Definition at line 89 of file src/GeoCoords.cpp.

Math::real GeographicLib::GeoCoords::Northing ( ) const

inline

Returns

northing (meters)

Definition at line 293 of file GeoCoords.hpp.

bool GeographicLib::GeoCoords::Northp ( ) const

inline

Returns

hemisphere (false means south, true means north).

Definition at line 308 of file GeoCoords.hpp.

void GeographicLib::GeoCoords::Reset	(	const std::string &	s,
		bool	centerp = true,
		bool	longfirst = false
	)

Reset the location from a string. See GeoCoords(const std::string& s, bool centerp, bool longfirst).

Parameters

[in]	s	1-element, 2-element, or 3-element string representation of the position.
[in]	centerp	governs the interpretation of MGRS coordinates.
[in]	longfirst	governs the interpretation of geographic coordinates.

Exceptions

GeographicErr

if the s is malformed.

Definition at line 19 of file src/GeoCoords.cpp.

void GeographicLib::GeoCoords::Reset ( real  latitude, real  longitude, int  zone = UTMUPS::STANDARD  )

inline

Reset the location in terms of geographic coordinates. See GeoCoords(real latitude, real longitude, int zone).

Parameters

[in]	latitude	(degrees).
[in]	longitude	(degrees).
[in]	zone	if specified, force the UTM/UPS representation to use a specified zone using the rules given in UTMUPS::zonespec.

Exceptions

GeographicErr	if latitude is not in [−90°, 90°].
GeographicErr	if zone cannot be used for this location.

Definition at line 238 of file GeoCoords.hpp.

void GeographicLib::GeoCoords::Reset ( int  zone, bool  northp, real  easting, real  northing  )

inline

Reset the location in terms of UPS/UPS coordinates. See GeoCoords(int zone, bool northp, real easting, real northing).

Parameters

[in]	zone	UTM zone (zero means UPS).
[in]	northp	hemisphere (true means north, false means south).
[in]	easting	(meters).
[in]	northing	(meters).

Exceptions

GeographicErr

if zone, easting, or northing is outside its allowed range.

Definition at line 260 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Scale ( ) const

inline

Returns

scale for the UTM/UPS projection.

Definition at line 303 of file GeoCoords.hpp.

void GeographicLib::GeoCoords::SetAltZone ( int  zone = UTMUPS::STANDARD ) const

inline

Specify alternate zone number.

Parameters

[in]

zone

zone number for the alternate representation.

Exceptions

GeographicErr

if zone cannot be used for this location.

See UTMUPS::zonespec for more information on the interpretation of zone. Note that zone == UTMUPS::STANDARD (the default) use the standard UPS or UTM zone, UTMUPS::MATCH does nothing retaining the existing alternate representation. Before this is called the alternate zone is the input zone.

Definition at line 337 of file GeoCoords.hpp.

string GeographicLib::GeoCoords::UTMUPSRepresentation	(	int	prec = 0,
		bool	abbrev = true
	)		const

UTM/UPS string.

Parameters

[in]	prec	precision (relative to about 1m)
[in]	abbrev	if true (the default) use abbreviated (n/s) notation for hemisphere; otherwise spell out the hemisphere (north/south)

Exceptions

std::bad_alloc

if memory for the string can't be allocated.

Returns

UTM/UPS string representation: zone designator, easting, and northing.

Precision specifies accuracy of representation as follows:

• prec = −5 (min), 100km
• prec = −3, 1km
• prec = 0, 1m
• prec = 3, 1mm
• prec = 6, 1μm
• prec = 9 (max), 1nm

Definition at line 129 of file src/GeoCoords.cpp.

string GeographicLib::GeoCoords::UTMUPSRepresentation	(	bool	northp,
		int	prec = 0,
		bool	abbrev = true
	)		const

UTM/UPS string with hemisphere override.

Parameters

[in]	northp	hemisphere override
[in]	prec	precision (relative to about 1m)
[in]	abbrev	if true (the default) use abbreviated (n/s) notation for hemisphere; otherwise spell out the hemisphere (north/south)

Exceptions

GeographicErr	if the hemisphere override attempts to change UPS N to UPS S or vice versa.
std::bad_alloc	if memory for the string can't be allocated.

Returns

UTM/UPS string representation: zone designator, easting, and northing.

Definition at line 135 of file src/GeoCoords.cpp.

void GeographicLib::GeoCoords::UTMUPSString ( int  zone, bool  northp, real  easting, real  northing, int  prec, bool  abbrev, std::string &  utm  )

staticprivate

Definition at line 106 of file src/GeoCoords.cpp.

int GeographicLib::GeoCoords::Zone ( ) const

inline

Returns

the zone corresponding to the input (return 0 for UPS).

Definition at line 318 of file GeoCoords.hpp.

Member Data Documentation

real GeographicLib::GeoCoords::_alt_easting

mutableprivate

Definition at line 55 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_alt_gamma

mutableprivate

Definition at line 55 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_alt_k

mutableprivate

Definition at line 55 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_alt_northing

mutableprivate

Definition at line 55 of file GeoCoords.hpp.

int GeographicLib::GeoCoords::_alt_zone

mutableprivate

Definition at line 56 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_easting

private

Definition at line 52 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_gamma

private

Definition at line 52 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_k

private

Definition at line 52 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_lat

private

Definition at line 52 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_long

private

Definition at line 52 of file GeoCoords.hpp.

real GeographicLib::GeoCoords::_northing

private

Definition at line 52 of file GeoCoords.hpp.

bool GeographicLib::GeoCoords::_northp

private

Definition at line 53 of file GeoCoords.hpp.

int GeographicLib::GeoCoords::_zone

private

Definition at line 54 of file GeoCoords.hpp.

---

The documentation for this class was generated from the following files:

• GeoCoords.hpp
• src/GeoCoords.cpp