Convert between UTM/UPS and MGRS. More...

#include <MGRS.hpp>

Static Public Member Functions
static void	Check ()

static void	Forward (int zone, bool northp, real x, real y, int prec, std::string &mgrs)

static void	Forward (int zone, bool northp, real x, real y, real lat, int prec, std::string &mgrs)

static void	Reverse (const std::string &mgrs, int &zone, bool &northp, real &x, real &y, int &prec, bool centerp=true)

Inspector functions
static Math::real	MajorRadius ()

static Math::real	Flattening ()

Private Types
enum	{ base_ = 10, tilelevel_ = 5, utmrowperiod_ = 20, utmevenrowshift_ = 5, maxprec_ = 5 + 6, mult_ = 1000000 }

enum	{ tile_ = 100000, minutmcol_ = 1, maxutmcol_ = 9, minutmSrow_ = 10, maxutmSrow_ = 100, minutmNrow_ = 0, maxutmNrow_ = 95, minupsSind_ = 8, maxupsSind_ = 32, minupsNind_ = 13, maxupsNind_ = 27, upseasting_ = 20, utmeasting_ = 5, utmNshift_ = (maxutmSrow_ - minutmNrow_) * tile_ }

typedef Math::real	real

Private Member Functions
	MGRS ()

Static Private Member Functions
static int	ApproxLatitudeBand (real y)

static void	CheckCoords (bool utmp, bool &northp, real &x, real &y)

static int	LatitudeBand (real lat)

static int	UTMRow (int iband, int icol, int irow)

Static Private Attributes
static const char *const	digits_ = "0123456789"

static const char *const	hemispheres_ = "SN"

static const char *const	latband_ = "CDEFGHJKLMNPQRSTUVWX"

static const int	maxeasting_ [4]

static const int	maxnorthing_ [4]

static const int	mineasting_ [4]

static const int	minnorthing_ [4]

static const char *const	upsband_ = "ABYZ"

static const char *const	upscols_ [4]

static const char *const	upsrows_ [2]

static const char *const	utmcols_ [3] = { "ABCDEFGH", "JKLMNPQR", "STUVWXYZ" }

static const char *const	utmrow_ = "ABCDEFGHJKLMNPQRSTUV"

Friends
class	UTMUPS

Detailed Description

Convert between UTM/UPS and MGRS.

MGRS is defined in Chapter 3 of

J. W. Hager, L. L. Fry, S. S. Jacks, D. R. Hill, Datums, Ellipsoids, Grids, and Grid Reference Systems, Defense Mapping Agency, Technical Manual TM8358.1 (1990).

This document has been updated by the two NGA documents

Universal Grids and Grid Reference Systems, NGA.STND.0037_2.0.0_GRIDS (2014).
The Universal Grids and the Transverse Mercator and Polar Stereographic Map Projections, NGA.SIG.0012_2.0.0_UTMUPS (2014).

This implementation has the following properties:

The conversions are closed, i.e., output from Forward is legal input for Reverse and vice versa. Conversion in both directions preserve the UTM/UPS selection and the UTM zone.
Forward followed by Reverse and vice versa is approximately the identity. (This is affected in predictable ways by errors in determining the latitude band and by loss of precision in the MGRS coordinates.)
The trailing digits produced by Forward are consistent as the precision is varied. Specifically, the digits are obtained by operating on the easting with ⌊10⁶ x⌋ and extracting the required digits from the resulting number (and similarly for the northing).
All MGRS coordinates truncate to legal 100 km blocks. All MGRS coordinates with a legal 100 km block prefix are legal (even though the latitude band letter may now belong to a neighboring band).
The range of UTM/UPS coordinates allowed for conversion to MGRS coordinates is the maximum consistent with staying within the letter ranges of the MGRS scheme.
All the transformations are implemented as static methods in the MGRS class.

The NGA software package geotrans also provides conversions to and from MGRS. Version 3.0 (and earlier) suffers from some drawbacks:

Inconsistent rules are used to determine the whether a particular MGRS coordinate is legal. A more systematic approach is taken here.
The underlying projections are not very accurately implemented.

Example of use:

// Example of using the GeographicLib::MGRS class
#include <iostream>
#include <exception>
#include <string>
#include <GeographicLib/UTMUPS.hpp>
#include <GeographicLib/MGRS.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
  try {
    // See also example-GeoCoords.cpp
    {
      // Sample forward calculation
      double lat = 33.3, lon = 44.4; // Baghdad
      int zone;
      bool northp;
      double x, y;
      UTMUPS::Forward(lat, lon, zone, northp, x, y);
      string mgrs;
      MGRS::Forward(zone, northp, x, y, lat, 5, mgrs);
      cout << mgrs << "\n";
    }
    {
      // Sample reverse calculation
      string mgrs = "38SMB4488";
      int zone, prec;
      bool northp;
      double x, y;
      MGRS::Reverse(mgrs, zone, northp, x, y, prec);
      double lat, lon;
      UTMUPS::Reverse(zone, northp, x, y, lat, lon);
      cout << prec << " " << lat << " " << lon << "\n";
    }
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Definition at line 74 of file MGRS.hpp.

Member Typedef Documentation

◆ real

typedef Math::real GeographicLib::MGRS::real

private

Definition at line 76 of file MGRS.hpp.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

private

Enumerator
base_
tilelevel_
utmrowperiod_
utmevenrowshift_
maxprec_
mult_

Definition at line 90 of file MGRS.hpp.

◆ anonymous enum

anonymous enum

private

Enumerator
tile_
minutmcol_
maxutmcol_
minutmSrow_
maxutmSrow_
minutmNrow_
maxutmNrow_
minupsSind_
maxupsSind_
minupsNind_
maxupsNind_
upseasting_
utmeasting_
utmNshift_

Definition at line 141 of file MGRS.hpp.

Constructor & Destructor Documentation

◆ MGRS()

GeographicLib::MGRS::MGRS ( )

private

Member Function Documentation

◆ ApproxLatitudeBand()

static int GeographicLib::MGRS::ApproxLatitudeBand ( real y )

inlinestaticprivate

Definition at line 118 of file MGRS.hpp.

◆ Check()

void GeographicLib::MGRS::Check ( )

static

Perform some checks on the UTMUPS coordinates on this ellipsoid. Throw an error if any of the assumptions made in the MGRS class is not true. This check needs to be carried out if the ellipsoid parameters (or the UTM/UPS scales) are ever changed.

Definition at line 403 of file src/MGRS.cpp.

◆ CheckCoords()

void GeographicLib::MGRS::CheckCoords	(	bool	utmp,
		bool &	northp,
		real &	x,
		real &	y
	)

staticprivate

Definition at line 276 of file src/MGRS.cpp.

◆ Flattening()

static Math::real GeographicLib::MGRS::Flattening ( )

inlinestatic

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 336 of file MGRS.hpp.

◆ Forward() [1/2]

void GeographicLib::MGRS::Forward	(	int	zone,
		bool	northp,
		real	x,
		real	y,
		int	prec,
		std::string &	mgrs
	)

static

Convert UTM or UPS coordinate to an MGRS coordinate.

Parameters

[in]	zone	UTM zone (zero means UPS).
[in]	northp	hemisphere (true means north, false means south).
[in]	x	easting of point (meters).
[in]	y	northing of point (meters).
[in]	prec	precision relative to 100 km.
[out]	mgrs	MGRS string.

Exceptions

GeographicErr	if zone, x, or y is outside its allowed range.
GeographicErr	if the memory for the MGRS string can't be allocated.

prec specifies the precision of the MGRS string as follows:

prec = −1 (min), only the grid zone is returned
prec = 0, 100 km
prec = 1, 10 km
prec = 2, 1 km
prec = 3, 100 m
prec = 4, 10 m
prec = 5, 1 m
prec = 6, 0.1 m
…
prec = 11 (max), 1 μm

UTM eastings are allowed to be in the range [100 km, 900 km], northings are allowed to be in in [0 km, 9500 km] for the northern hemisphere and in [1000 km, 10000 km] for the southern hemisphere. (However UTM northings can be continued across the equator. So the actual limits on the northings are [−9000 km, 9500 km] for the "northern" hemisphere and [1000 km, 19500 km] for the "southern" hemisphere.)

UPS eastings/northings are allowed to be in the range [1300 km, 2700 km] in the northern hemisphere and in [800 km, 3200 km] in the southern hemisphere.

The ranges are 100 km more restrictive than for the conversion between geographic coordinates and UTM and UPS given by UTMUPS. These restrictions are dictated by the allowed letters in MGRS coordinates. The choice of 9500 km for the maximum northing for northern hemisphere and of 1000 km as the minimum northing for southern hemisphere provide at least 0.5 degree extension into standard UPS zones. The upper ends of the ranges for the UPS coordinates is dictated by requiring symmetry about the meridians 0E and 90E.

All allowed UTM and UPS coordinates may now be converted to legal MGRS coordinates with the proviso that eastings and northings on the upper boundaries are silently reduced by about 4 nm (4 nanometers) to place them within the allowed range. (This includes reducing a southern hemisphere northing of 10000 km by 4 nm so that it is placed in latitude band M.) The UTM or UPS coordinates are truncated to requested precision to determine the MGRS coordinate. Thus in UTM zone 38n, the square area with easting in [444 km, 445 km) and northing in [3688 km, 3689 km) maps to MGRS coordinate 38SMB4488 (at prec = 2, 1 km), Khulani Sq., Baghdad.

The UTM/UPS selection and the UTM zone is preserved in the conversion to MGRS coordinate. Thus for zone > 0, the MGRS coordinate begins with the zone number followed by one of [C–M] for the southern hemisphere and [N–X] for the northern hemisphere. For zone = 0, the MGRS coordinates begins with one of [AB] for the southern hemisphere and [XY] for the northern hemisphere.

The conversion to the MGRS is exact for prec in [0, 5] except that a neighboring latitude band letter may be given if the point is within 5nm of a band boundary. For prec in [6, 11], the conversion is accurate to roundoff.

If prec = −1, then the "grid zone designation", e.g., 18T, is returned. This consists of the UTM zone number (absent for UPS) and the first letter of the MGRS string which labels the latitude band for UTM and the hemisphere for UPS.

If x or y is NaN or if zone is UTMUPS::INVALID, the returned MGRS string is "INVALID".

Return the result via a reference argument to avoid the overhead of allocating a potentially large number of small strings. If an error is thrown, then mgrs is unchanged.

Definition at line 114 of file src/MGRS.cpp.

◆ Forward() [2/2]

void GeographicLib::MGRS::Forward	(	int	zone,
		bool	northp,
		real	x,
		real	y,
		real	lat,
		int	prec,
		std::string &	mgrs
	)

static

Convert UTM or UPS coordinate to an MGRS coordinate when the latitude is known.

Parameters

[in]	zone	UTM zone (zero means UPS).
[in]	northp	hemisphere (true means north, false means south).
[in]	x	easting of point (meters).
[in]	y	northing of point (meters).
[in]	lat	latitude (degrees).
[in]	prec	precision relative to 100 km.
[out]	mgrs	MGRS string.

Exceptions

GeographicErr	if zone, x, or y is outside its allowed range.
GeographicErr	if lat is inconsistent with the given UTM coordinates.
std::bad_alloc	if the memory for mgrs can't be allocated.

The latitude is ignored for zone = 0 (UPS); otherwise the latitude is used to determine the latitude band and this is checked for consistency using the same tests as Reverse.

Definition at line 39 of file src/MGRS.cpp.

◆ LatitudeBand()

static int GeographicLib::MGRS::LatitudeBand ( real lat )

inlinestaticprivate

Definition at line 109 of file MGRS.hpp.

◆ MajorRadius()

static Math::real GeographicLib::MGRS::MajorRadius ( )

inlinestatic

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 328 of file MGRS.hpp.

◆ Reverse()

void GeographicLib::MGRS::Reverse	(	const std::string &	mgrs,
		int &	zone,
		bool &	northp,
		real &	x,
		real &	y,
		int &	prec,
		bool	centerp = `true`
	)

static

Convert a MGRS coordinate to UTM or UPS coordinates.

Parameters

[in]	mgrs	MGRS string.
[out]	zone	UTM zone (zero means UPS).
[out]	northp	hemisphere (true means north, false means south).
[out]	x	easting of point (meters).
[out]	y	northing of point (meters).
[out]	prec	precision relative to 100 km.
[in]	centerp	if true (default), return center of the MGRS square, else return SW (lower left) corner.

Exceptions

GeographicErr if mgrs is illegal.

All conversions from MGRS to UTM/UPS are permitted provided the MGRS coordinate is a possible result of a conversion in the other direction. (The leading 0 may be dropped from an input MGRS coordinate for UTM zones 1–9.) In addition, MGRS coordinates with a neighboring latitude band letter are permitted provided that some portion of the 100 km block is within the given latitude band. Thus

38VLS and 38WLS are allowed (latitude 64N intersects the square 38[VW]LS); but 38VMS is not permitted (all of 38WMS is north of 64N)
38MPE and 38NPF are permitted (they straddle the equator); but 38NPE and 38MPF are not permitted (the equator does not intersect either block).
Similarly ZAB and YZB are permitted (they straddle the prime meridian); but YAB and ZZB are not (the prime meridian does not intersect either block).

The UTM/UPS selection and the UTM zone is preserved in the conversion from MGRS coordinate. The conversion is exact for prec in [0, 5]. With centerp = true, the conversion from MGRS to geographic and back is stable. This is not assured if centerp = false.

If a "grid zone designation" (for example, 18T or A) is given, then some suitable (but essentially arbitrary) point within that grid zone is returned. The main utility of the conversion is to allow zone and northp to be determined. In this case, the centerp parameter is ignored and prec is set to −1.

If the first 3 characters of mgrs are "INV", then x and y are set to NaN, zone is set to UTMUPS::INVALID, and prec is set to −2.

If an exception is thrown, then the arguments are unchanged.

Definition at line 149 of file src/MGRS.cpp.

◆ UTMRow()

int GeographicLib::MGRS::UTMRow	(	int	iband,
		int	icol,
		int	irow
	)

staticprivate

Definition at line 335 of file src/MGRS.cpp.

Friends And Related Function Documentation

◆ UTMUPS

friend class UTMUPS

friend

Definition at line 106 of file MGRS.hpp.

Member Data Documentation

◆ digits_

const char *const GeographicLib::MGRS::digits_ = "0123456789"

staticprivate

Definition at line 84 of file MGRS.hpp.

◆ hemispheres_

const char *const GeographicLib::MGRS::hemispheres_ = "SN"

staticprivate

Definition at line 77 of file MGRS.hpp.

◆ latband_

const char *const GeographicLib::MGRS::latband_ = "CDEFGHJKLMNPQRSTUVWX"

staticprivate

Definition at line 82 of file MGRS.hpp.

◆ maxeasting_

const int GeographicLib::MGRS::maxeasting_

staticprivate

Initial value:

=

{ maxupsSind_, maxupsNind_, maxutmcol_, maxutmcol_ }

Definition at line 87 of file MGRS.hpp.

◆ maxnorthing_

const int GeographicLib::MGRS::maxnorthing_

staticprivate

Initial value:

=
    { maxupsSind_, maxupsNind_,
      maxutmNrow_ + (maxutmSrow_ - minutmNrow_), maxutmNrow_ }

Definition at line 89 of file MGRS.hpp.

◆ mineasting_

const int GeographicLib::MGRS::mineasting_

staticprivate

Initial value:

=

{ minupsSind_, minupsNind_, minutmcol_, minutmcol_ }

Definition at line 86 of file MGRS.hpp.

◆ minnorthing_

const int GeographicLib::MGRS::minnorthing_

staticprivate

Initial value:

=
    { minupsSind_, minupsNind_,
      minutmSrow_, minutmSrow_ - (maxutmSrow_ - minutmNrow_) }

Definition at line 88 of file MGRS.hpp.

◆ upsband_

const char *const GeographicLib::MGRS::upsband_ = "ABYZ"

staticprivate

Definition at line 83 of file MGRS.hpp.

◆ upscols_

const char *const GeographicLib::MGRS::upscols_

staticprivate

Initial value:

=

{ "JKLPQRSTUXYZ", "ABCFGHJKLPQR", "RSTUXYZ", "ABCFGHJ" }

Definition at line 80 of file MGRS.hpp.

◆ upsrows_

const char *const GeographicLib::MGRS::upsrows_

staticprivate

Initial value:

=

{ "ABCDEFGHJKLMNPQRSTUVWXYZ", "ABCDEFGHJKLMNP" }

Definition at line 81 of file MGRS.hpp.

◆ utmcols_

const char *const GeographicLib::MGRS::utmcols_ = { "ABCDEFGH", "JKLMNPQR", "STUVWXYZ" }

staticprivate

Definition at line 78 of file MGRS.hpp.

◆ utmrow_

const char *const GeographicLib::MGRS::utmrow_ = "ABCDEFGHJKLMNPQRSTUV"

staticprivate

Definition at line 79 of file MGRS.hpp.

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

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ real

Member Enumeration Documentation

◆ anonymous enum

◆ anonymous enum

Constructor & Destructor Documentation

◆ MGRS()

Member Function Documentation

◆ ApproxLatitudeBand()

◆ Check()

◆ CheckCoords()

◆ Flattening()

◆ Forward() [1/2]

◆ Forward() [2/2]

◆ LatitudeBand()

◆ MajorRadius()

◆ Reverse()

◆ UTMRow()

Friends And Related Function Documentation

◆ UTMUPS

Member Data Documentation

◆ digits_

◆ hemispheres_

◆ latband_

◆ maxeasting_

◆ maxnorthing_

◆ mineasting_

◆ minnorthing_

◆ upsband_

◆ upscols_

◆ upsrows_

◆ utmcols_

◆ utmrow_