GeographicLib::GeoCoords Class Reference

Conversion between geographic coordinates. More...

#include <GeographicLib/GeoCoords.hpp>

List of all members.

Public Member Functions

Initializing the GeoCoords object

 GeoCoords () throw ()
 GeoCoords (const std::string &s, bool centerp=true)
 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)
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 throw ()
Math::real Longitude () const throw ()
Math::real Easting () const throw ()
Math::real Northing () const throw ()
Math::real Convergence () const throw ()
Math::real Scale () const throw ()
bool Northp () const throw ()
char Hemisphere () const throw ()
int Zone () const throw ()
Setting and querying the alternate zone

void SetAltZone (int zone=UTMUPS::STANDARD) const
int AltZone () const throw ()
Math::real AltEasting () const throw ()
Math::real AltNorthing () const throw ()
Math::real AltConvergence () const throw ()
Math::real AltScale () const throw ()
String representations of the GeoCoords object

std::string GeoRepresentation (int prec=0) const
std::string DMSRepresentation (int prec=0) const
std::string MGRSRepresentation (int prec=0) const
std::string UTMUPSRepresentation (int prec=0) const
std::string AltMGRSRepresentation (int prec=0) const
std::string AltUTMUPSRepresentation (int prec=0) const
Inspector functions

Math::real MajorRadius () const throw ()
Math::real InverseFlattening () const throw ()

Detailed Description

Conversion between geographic coordinates.

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

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.

Definition at line 43 of file GeoCoords.hpp.


Constructor & Destructor Documentation

GeographicLib::GeoCoords::GeoCoords (  )  throw () [inline]

The default contructor is equivalent to latitude = 90o, longitude = 0o.

Definition at line 71 of file GeoCoords.hpp.

GeographicLib::GeoCoords::GeoCoords ( const std::string &  s,
bool  centerp = true 
) [inline, explicit]

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).

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
  • MGRS
    • 38SLC301
    • 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. Thus

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

are all the same position. The coodinates may be given in decimal degrees, degrees and decimal minutes, degrees, minutes, seconds, etc. Use d, ', and " to make off the degrees, minutes and seconds. Thus - 40d30'30"

  • 40d30'30
  • 40d30.5'
  • 40d30.5
  • 40.508333333

all specify the same angle. The leading sign applies to all components so -1d30 is -(1+30/60) = -1.5. Latitudes must be in the range [-90, 90] and longitudes in the range [-180, 360]. 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. The latitude zone 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.

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 153 of file GeoCoords.hpp.

References Reset().

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.

Definition at line 164 of file GeoCoords.hpp.

References Reset().

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).

Definition at line 176 of file GeoCoords.hpp.

References Reset().


Member Function Documentation

void GeographicLib::GeoCoords::Reset ( const std::string &  s,
bool  centerp = true 
)
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).

Definition at line 190 of file GeoCoords.hpp.

References GeographicLib::UTMUPS::Forward().

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).

Definition at line 205 of file GeoCoords.hpp.

References GeographicLib::UTMUPS::Reverse().

Math::real GeographicLib::GeoCoords::Latitude (  )  const throw () [inline]
Returns:
latitude (degrees)

Definition at line 223 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Longitude (  )  const throw () [inline]
Returns:
longitude (degrees)

Definition at line 228 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Easting (  )  const throw () [inline]
Returns:
easting (meters)

Definition at line 233 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Northing (  )  const throw () [inline]
Returns:
northing (meters)

Definition at line 238 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Convergence (  )  const throw () [inline]
Returns:
meridian convergence (degrees) for the UTM/UPS projection.

Definition at line 243 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::Scale (  )  const throw () [inline]
Returns:
scale for the UTM/UPS projection.

Definition at line 248 of file GeoCoords.hpp.

bool GeographicLib::GeoCoords::Northp (  )  const throw () [inline]
Returns:
hemisphere (false means south, true means north).

Definition at line 253 of file GeoCoords.hpp.

char GeographicLib::GeoCoords::Hemisphere (  )  const throw () [inline]
Returns:
hemisphere letter N or S.

Definition at line 258 of file GeoCoords.hpp.

int GeographicLib::GeoCoords::Zone (  )  const throw () [inline]
Returns:
the zone corresponding to the input (return 0 for UPS).

Definition at line 263 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.

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 281 of file GeoCoords.hpp.

References GeographicLib::UTMUPS::Forward(), GeographicLib::UTMUPS::MATCH, and GeographicLib::UTMUPS::StandardZone().

int GeographicLib::GeoCoords::AltZone (  )  const throw () [inline]
Returns:
current alternate zone (return 0 for UPS).

Definition at line 299 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::AltEasting (  )  const throw () [inline]
Returns:
easting (meters) for alternate zone.

Definition at line 304 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::AltNorthing (  )  const throw () [inline]
Returns:
northing (meters) for alternate zone.

Definition at line 309 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::AltConvergence (  )  const throw () [inline]
Returns:
meridian convergence (degrees) for altermate zone.

Definition at line 314 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::AltScale (  )  const throw () [inline]
Returns:
scale for altermate zone.

Definition at line 319 of file GeoCoords.hpp.

string GeographicLib::GeoCoords::GeoRepresentation ( int  prec = 0  )  const

String representation with latitude and longitude as signed decimal degrees.

Parameters:
[in] prec precision (relative to about 1m).
Returns:
decimal latitude/longitude string representation.

Precision specifies accuracy of representation as follows:

  • prec = -5 (min), 1d
  • prec = 0, 10-5d (about 1m)
  • prec = 3, 10-8d
  • prec = 9 (max), 10-14d

Definition at line 72 of file GeoCoords.cpp.

string GeographicLib::GeoCoords::DMSRepresentation ( int  prec = 0  )  const

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

Parameters:
[in] prec precision (relative to about 1m)
Returns:
DMS latitude/longitude string representation.

Precision specifies accuracy of representation as follows:

  • prec = -5 (min), 1d
  • prec = -4, 0.1d
  • prec = -3, 1'
  • prec = -2, 0.1'
  • prec = -1, 1" - prec = 0, 0.1" (about 3m)
  • prec = 1, 0.01" - prec = 10 (max), 10<sup>-11</sup>"

Definition at line 88 of file GeoCoords.cpp.

References GeographicLib::DMS::Encode(), GeographicLib::DMS::LATITUDE, and GeographicLib::DMS::LONGITUDE.

string GeographicLib::GeoCoords::MGRSRepresentation ( int  prec = 0  )  const

MGRS string.

Parameters:
[in] prec precision (relative to about 1m).
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 MSGRS string as follows:

  • prec = -5 (min), 100km
  • prec = -4, 10km
  • prec = -3, 1km
  • prec = -2, 100m
  • prec = -1, 10m
  • prec = 0, 1m
  • prec = 1, 0.1m
  • prec = 6 (max), 1um

Definition at line 94 of file GeoCoords.cpp.

References GeographicLib::MGRS::Forward().

string GeographicLib::GeoCoords::UTMUPSRepresentation ( int  prec = 0  )  const

UTM/UPS string.

Parameters:
[in] prec precision (relative to about 1m)
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, 1um
  • prec = 9 (max), 1nm

Definition at line 132 of file GeoCoords.cpp.

string GeographicLib::GeoCoords::AltMGRSRepresentation ( int  prec = 0  )  const

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

Definition at line 102 of file GeoCoords.cpp.

References GeographicLib::MGRS::Forward().

string GeographicLib::GeoCoords::AltUTMUPSRepresentation ( int  prec = 0  )  const

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

Definition at line 138 of file GeoCoords.cpp.

Math::real GeographicLib::GeoCoords::MajorRadius (  )  const throw () [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 418 of file GeoCoords.hpp.

Math::real GeographicLib::GeoCoords::InverseFlattening (  )  const throw () [inline]
Returns:
r the inverse flattening of the WGS84 ellipsoid.

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

Definition at line 426 of file GeoCoords.hpp.


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