NETGeographicLib::UTMUPS Class Reference

.NET wrapper for GeographicLib::UTMUPS. More...

#include <UTMUPS.h>

Public Types
enum	ZoneSpec {   ZoneSpec::MINPSEUDOZONE = -4, ZoneSpec::INVALID = -4, ZoneSpec::MATCH = -3, ZoneSpec::UTM = -2,   ZoneSpec::STANDARD = -1, ZoneSpec::MAXPSEUDOZONE = -1, ZoneSpec::MINZONE = 0, ZoneSpec::UPS = 0,   ZoneSpec::MINUTMZONE = 1, ZoneSpec::MAXUTMZONE = 60, ZoneSpec::MAXZONE = 60 }

Static Public Member Functions
static void	DecodeEPSG (int epsg, [System::Runtime::InteropServices::Out] int% zone, [System::Runtime::InteropServices::Out] bool% northp)
static void	DecodeZone (System::String^ zonestr, [System::Runtime::InteropServices::Out] int% zone, [System::Runtime::InteropServices::Out] bool% northp)
static int	EncodeEPSG (int zone, bool northp)
static System::String	EncodeZone (int zone, bool northp, bool abbrev)
static void	Forward (double lat, double lon, [System::Runtime::InteropServices::Out] int% zone, [System::Runtime::InteropServices::Out] bool% northp, [System::Runtime::InteropServices::Out] double% x, [System::Runtime::InteropServices::Out] double% y, [System::Runtime::InteropServices::Out] double% gamma, [System::Runtime::InteropServices::Out] double% k, int setzone, bool mgrslimits)
static void	Forward (double lat, double lon, [System::Runtime::InteropServices::Out] int% zone, [System::Runtime::InteropServices::Out] bool% northp, [System::Runtime::InteropServices::Out] double% x, [System::Runtime::InteropServices::Out] double% y, int setzone, bool mgrslimits)
static void	Reverse (int zone, bool northp, double x, double y, [System::Runtime::InteropServices::Out] double% lat, [System::Runtime::InteropServices::Out] double% lon, [System::Runtime::InteropServices::Out] double% gamma, [System::Runtime::InteropServices::Out] double% k, bool mgrslimits)
static void	Reverse (int zone, bool northp, double x, double y, [System::Runtime::InteropServices::Out] double% lat, [System::Runtime::InteropServices::Out] double% lon, bool mgrslimits)
static int	StandardZone (double lat, double lon, int setzone)
static void	Transfer (int zonein, bool northpin, double xin, double yin, int zoneout, bool northpout, [System::Runtime::InteropServices::Out] double% xout, [System::Runtime::InteropServices::Out] double% yout, [System::Runtime::InteropServices::Out] int% zone)
static double	UTMShift ()
Inspector functions
static double	MajorRadius ()
static double	Flattening ()

Private Member Functions
	UTMUPS ()

Detailed Description

.NET wrapper for GeographicLib::UTMUPS.

This class allows .NET applications to access GeographicLib::UTMUPS.

UTM and UPS are defined

• J. W. Hager, J. F. Behensky, and B. W. Drew, The Universal Grids: Universal Transverse Mercator (UTM) and Universal Polar Stereographic (UPS), Defense Mapping Agency, Technical Manual TM8358.2 (1989).

Section 2-3 defines UTM and section 3-2.4 defines UPS. This document also includes approximate algorithms for the computation of the underlying transverse Mercator and polar stereographic projections. Here we substitute much more accurate algorithms given by GeographicLib:TransverseMercator and GeographicLib:PolarStereographic.

In this implementation, the conversions are closed, i.e., output from Forward is legal input for Reverse and vice versa. The error is about 5nm in each direction. However, the conversion from legal UTM/UPS coordinates to geographic coordinates and back might throw an error if the initial point is within 5nm of the edge of the allowed range for the UTM/UPS coordinates.

The simplest way to guarantee the closed property is to define allowed ranges for the eastings and northings for UTM and UPS coordinates. The UTM boundaries are the same for all zones. (The only place the exceptional nature of the zone boundaries is evident is when converting to UTM/UPS coordinates requesting the standard zone.) The MGRS lettering scheme imposes natural limits on UTM/UPS coordinates which may be converted into MGRS coordinates. For the conversion to/from geographic coordinates these ranges have been extended by 100km in order to provide a generous overlap between UTM and UPS and between UTM zones.

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

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

C# Example:

using System;
using NETGeographicLib;
 
namespace example_UTMUPS
{
    class Program
    {
        static void Main(string[] args)
        {
            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, out zone, out northp, out x, out y, -1, true);
                    string zonestr = UTMUPS.EncodeZone(zone, northp, true);
                    Console.WriteLine(String.Format("{0} {1} {2}", zonestr, x, y));
                }
                {
                    // Sample reverse calculation
                    string zonestr = "38N";
                    int zone;
                    bool northp;
                    UTMUPS.DecodeZone(zonestr, out zone, out northp);
                    double x = 444e3, y = 3688e3;
                    double lat, lon;
                    UTMUPS.Reverse(zone, northp, x, y, out lat, out lon, true);
                    Console.WriteLine(String.Format("{0} {1}", lat,lon));
                }
            }
            catch (GeographicErr e) {
                Console.WriteLine(String.Format("Caught exception: {0}", e.Message));
            }
        }
    }
}

Managed C++ Example:

// Example of using the GeographicLib::UTMUPS class
 
#include <iostream>
#include <iomanip>
#include <exception>
#include <string>
#include <GeographicLib/UTMUPS.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 zonestr = UTMUPS::EncodeZone(zone, northp);
      cout << fixed << setprecision(2)
           << zonestr << " " << x << " " << y << "\n";
    }
    {
      // Sample reverse calculation
      string zonestr = "38n";
      int zone;
      bool northp;
      UTMUPS::DecodeZone(zonestr, zone, northp);
      double x = 444e3, y = 3688e3;
      double lat, lon;
      UTMUPS::Reverse(zone, northp, x, y, lat, lon);
      cout << lat << " " << lon << "\n";
    }
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Visual Basic Example:

Imports NETGeographicLib
 
Module example_UTMUPS
    Sub Main()
        Try
            ' See also example-GeoCoords.cpp
            ' Sample forward calculation
            Dim lat As Double = 33.3, lon = 44.4 ' Baghdad
            Dim zone As Integer
            Dim northp As Boolean
            Dim x, y As Double
            UTMUPS.Forward(lat, lon, zone, northp, x, y, -1, True)
            Dim zonestr As String = UTMUPS.EncodeZone(zone, northp, True)
            Console.WriteLine(String.Format("{0} {1} {2}", zonestr, x, y))
            ' Sample reverse calculation
            zonestr = "38N"
            UTMUPS.DecodeZone(zonestr, zone, northp)
            x = 444000.0 : y = 3688000.0
            UTMUPS.Reverse(zone, northp, x, y, lat, lon, True)
            Console.WriteLine(String.Format("{0} {1}", lat, lon))
        Catch ex As GeographicErr
            Console.WriteLine(String.Format("Caught exception: {0}", ex.Message))
        End Try
    End Sub
End Module

Definition at line 66 of file UTMUPS.h.

Member Enumeration Documentation

ZoneSpec

enum NETGeographicLib::UTMUPS::ZoneSpec

strong

In this class we bring together the UTM and UPS coordinates systems. The UTM divides the earth between latitudes −80° and 84° into 60 zones numbered 1 thru 60. Zone assign zone number 0 to the UPS regions, covering the two poles. Within UTMUPS, non-negative zone numbers refer to one of the "physical" zones, 0 for UPS and [1, 60] for UTM. Negative "pseudo-zone" numbers are used to select one of the physical zones.

Enumerator
MINPSEUDOZONE	The smallest pseudo-zone number.
INVALID	A marker for an undefined or invalid zone. Equivalent to NaN.
MATCH	If a coordinate already include zone information (e.g., it is an MGRS coordinate), use that, otherwise apply the UTMUPS::STANDARD rules.
UTM	Apply the standard rules for UTM zone assigment extending the UTM zone to each pole to give a zone number in [1, 60]. For example, use UTM zone 38 for longitude in [42°, 48°). The rules include the Norway and Svalbard exceptions.
STANDARD	Apply the standard rules for zone assignment to give a zone number in [0, 60]. If the latitude is not in [−80°, 84°), then use UTMUPS::UPS = 0, otherwise apply the rules for UTMUPS::UTM. The tests on latitudes and longitudes are all closed on the lower end open on the upper. Thus for UTM zone 38, latitude is in [−80°, 84°) and longitude is in [42°, 48°).
MAXPSEUDOZONE	The largest pseudo-zone number.
MINZONE	The smallest physical zone number.
UPS	The zone number used for UPS
MINUTMZONE	The smallest UTM zone number.
MAXUTMZONE	The largest UTM zone number.
MAXZONE	The largest physical zone number.

Definition at line 81 of file UTMUPS.h.

Constructor & Destructor Documentation

UTMUPS()

NETGeographicLib::UTMUPS::UTMUPS ( )

inlineprivate

Definition at line 70 of file UTMUPS.h.

Member Function Documentation

DecodeEPSG()

void UTMUPS::DecodeEPSG ( int  epsg, [System::Runtime::InteropServices::Out] int%  zone, [System::Runtime::InteropServices::Out] bool%  northp  )

static

Decode EPSG.

Parameters

[in]	epsg	the EPSG code.
[out]	zone	the UTM zone (zero means UPS).
[out]	northp	hemisphere (true means north, false means south).

EPSG (European Petroleum Survery Group) codes are a way to refer to many different projections. DecodeEPSG decodes those refering to UTM or UPS projections for the WGS84 ellipsoid. If the code does not refer to one of these projections, zone is set to UTMUPS::INVALID. See http://spatialreference.org/ref/epsg/

Definition at line 191 of file dotnet/NETGeographicLib/UTMUPS.cpp.

DecodeZone()

void UTMUPS::DecodeZone ( System::String^  zonestr, [System::Runtime::InteropServices::Out] int%  zone, [System::Runtime::InteropServices::Out] bool%  northp  )

static

Decode a UTM/UPS zone string.

Parameters

[in]	zonestr	string representation of zone and hemisphere.
[out]	zone	the UTM zone (zero means UPS).
[out]	northp	hemisphere (true means north, false means south).

Exceptions

GeographicErr

if zonestr is malformed.

For UTM, zonestr has the form of a zone number in the range [UTMUPS::MINUTMZONE, UTMUPS::MAXUTMZONE] = [1, 60] followed by a hemisphere letter, n or s (or "north" or "south" spelled out). For UPS, it consists just of the hemisphere letter (or the spelled out hemisphere). The returned value of zone is UTMUPS::UPS = 0 for UPS. Note well that "38s" indicates the southern hemisphere of zone 38 and not latitude band S, 32° ≤ lat < 40°. n, 01s, 2n, 38s, south, 3north are legal. 0n, 001s, +3n, 61n, 38P are illegal. INV is a special value for which the returned value of is UTMUPS::INVALID.

Definition at line 158 of file dotnet/NETGeographicLib/UTMUPS.cpp.

EncodeEPSG()

int UTMUPS::EncodeEPSG ( int  zone, bool  northp  )

static

Encode zone as EPSG.

Parameters

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

Returns

EPSG code (or -1 if zone is not in the range [UTMUPS::MINZONE, UTMUPS::MAXZONE] = [0, 60])

Convert zone and northp to the corresponding EPSG (European Petroleum Survery Group) codes

Definition at line 203 of file dotnet/NETGeographicLib/UTMUPS.cpp.

EncodeZone()

System::String UTMUPS::EncodeZone ( int  zone, bool  northp, bool  abbrev  )

static

Encode a UTM/UPS zone string.

Parameters

[in]	zone	the UTM zone (zero means UPS).
[in]	northp	hemisphere (true means north, false means south).
[in]	abbrev	if true (the default) use abbreviated (n/s) notation for hemisphere; otherwise spell out the hemisphere (north/south)

Exceptions

GeographicErr	if zone is out of range (see below).
std::bad_alloc	if memoy for the string can't be allocated.

Returns

string representation of zone and hemisphere.

zone must be in the range [UTMUPS::MINZONE, UTMUPS::MAXZONE] = [0, 60] with zone = UTMUPS::UPS, 0, indicating UPS (but the resulting string does not contain "0"). zone may also be UTMUPS::INVALID, in which case the returned string is "inv". This reverses UTMUPS::DecodeZone.

Definition at line 178 of file dotnet/NETGeographicLib/UTMUPS.cpp.

Flattening()

double UTMUPS::Flattening ( )

static

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 215 of file dotnet/NETGeographicLib/UTMUPS.cpp.

Forward() [1/2]

void UTMUPS::Forward ( double  lat, double  lon, [System::Runtime::InteropServices::Out] int%  zone, [System::Runtime::InteropServices::Out] bool%  northp, [System::Runtime::InteropServices::Out] double%  x, [System::Runtime::InteropServices::Out] double%  y, [System::Runtime::InteropServices::Out] double%  gamma, [System::Runtime::InteropServices::Out] double%  k, int  setzone, bool  mgrslimits  )

static

Forward projection, from geographic to UTM/UPS.

Parameters

[in]	lat	latitude of point (degrees).
[in]	lon	longitude of point (degrees).
[out]	zone	the 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]	gamma	meridian convergence at point (degrees).
[out]	k	scale of projection at point.
[in]	setzone	zone override (use ZoneSpec.STANDARD as default).
[in]	mgrslimits	if true enforce the stricter MGRS limits on the coordinates (default = false).

Exceptions

GeographicErr	if lat is not in [−90°, 90°].
GeographicErr	if the resulting x or y is out of allowed range (see Reverse); in this case, these arguments are unchanged.

If setzone is omitted, use the standard rules for picking the zone. If setzone is given then use that zone if it is non-negative, otherwise apply the rules given in UTMUPS::zonespec. The accuracy of the conversion is about 5nm.

The northing y jumps by UTMUPS::UTMShift() when crossing the equator in the southerly direction. Sometimes it is useful to remove this discontinuity in y by extending the "northern" hemisphere using UTMUPS::Transfer:

double lat = -1, lon = 123;
int zone;
bool northp;
double x, y, gamma, k;
GeographicLib::UTMUPS::Forward(lat, lon, zone, northp, x, y, gamma, k);
GeographicLib::UTMUPS::Transfer(zone, northp, x, y,
                                zone, true,   x, y, zone);
northp = true;

Definition at line 32 of file dotnet/NETGeographicLib/UTMUPS.cpp.

Forward() [2/2]

void UTMUPS::Forward ( double  lat, double  lon, [System::Runtime::InteropServices::Out] int%  zone, [System::Runtime::InteropServices::Out] bool%  northp, [System::Runtime::InteropServices::Out] double%  x, [System::Runtime::InteropServices::Out] double%  y, int  setzone, bool  mgrslimits  )

static

UTMUPS::Forward without returning convergence and scale.

Definition at line 88 of file dotnet/NETGeographicLib/UTMUPS.cpp.

MajorRadius()

double UTMUPS::MajorRadius ( )

static

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 212 of file dotnet/NETGeographicLib/UTMUPS.cpp.

Reverse() [1/2]

void UTMUPS::Reverse ( int  zone, bool  northp, double  x, double  y, [System::Runtime::InteropServices::Out] double%  lat, [System::Runtime::InteropServices::Out] double%  lon, [System::Runtime::InteropServices::Out] double%  gamma, [System::Runtime::InteropServices::Out] double%  k, bool  mgrslimits  )

static

Reverse projection, from UTM/UPS to geographic.

Parameters

[in]	zone	the 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).
[out]	lat	latitude of point (degrees).
[out]	lon	longitude of point (degrees).
[out]	gamma	meridian convergence at point (degrees).
[out]	k	scale of projection at point.
[in]	mgrslimits	if true enforce the stricter MGRS limits on the coordinates (default = false).

Exceptions

GeographicErr

if zone, x, or y is out of allowed range; this this case the arguments are unchanged.

The accuracy of the conversion is about 5nm.

UTM eastings are allowed to be in the range [0km, 1000km], northings are allowed to be in in [0km, 9600km] for the northern hemisphere and in [900km, 10000km] for the southern hemisphere. However UTM northings can be continued across the equator. So the actual limits on the northings are [-9100km, 9600km] for the "northern" hemisphere and [900km, 19600km] for the "southern" hemisphere.

UPS eastings and northings are allowed to be in the range [1200km, 2800km] in the northern hemisphere and in [700km, 3100km] in the southern hemisphere.

These ranges are 100km larger than allowed for the conversions to MGRS. (100km is the maximum extra padding consistent with eastings remaining non-negative.) This allows generous overlaps between zones and UTM and UPS. If mgrslimits = true, then all the ranges are shrunk by 100km so that they agree with the stricter MGRS ranges. No checks are performed besides these (e.g., to limit the distance outside the standard zone boundaries).

Definition at line 64 of file dotnet/NETGeographicLib/UTMUPS.cpp.

Reverse() [2/2]

void UTMUPS::Reverse ( int  zone, bool  northp, double  x, double  y, [System::Runtime::InteropServices::Out] double%  lat, [System::Runtime::InteropServices::Out] double%  lon, bool  mgrslimits  )

static

UTMUPS::Reverse without returning convergence and scale.

Definition at line 114 of file dotnet/NETGeographicLib/UTMUPS.cpp.

StandardZone()

int UTMUPS::StandardZone ( double  lat, double  lon, int  setzone  )

static

The standard zone.

Parameters

[in]	lat	latitude (degrees).
[in]	lon	longitude (degrees).
[in]	setzone	zone override (use ZoneSpec.STANDARD as default). If omitted, use the standard rules for picking the zone. If setzone is given then use that zone if it is non-negative, otherwise apply the rules given in UTMUPS::zonespec.

Exceptions

GeographicErr

if setzone is outside the range [UTMUPS::MINPSEUDOZONE, UTMUPS::MAXZONE] = [−4, 60].

This is exact.

Definition at line 19 of file dotnet/NETGeographicLib/UTMUPS.cpp.

Transfer()

void UTMUPS::Transfer ( int  zonein, bool  northpin, double  xin, double  yin, int  zoneout, bool  northpout, [System::Runtime::InteropServices::Out] double%  xout, [System::Runtime::InteropServices::Out] double%  yout, [System::Runtime::InteropServices::Out] int%  zone  )

static

Transfer UTM/UPS coordinated from one zone to another.

Parameters

[in]	zonein	the UTM zone for xin and yin (or zero for UPS).
[in]	northpin	hemisphere for xin and yin (true means north, false means south).
[in]	xin	easting of point (meters) in zonein.
[in]	yin	northing of point (meters) in zonein.
[in]	zoneout	the requested UTM zone for xout and yout (or zero for UPS).
[in]	northpout	hemisphere for xout output and yout.
[out]	xout	easting of point (meters) in zoneout.
[out]	yout	northing of point (meters) in zoneout.
[out]	zone	the actual UTM zone for xout and yout (or zero for UPS); this equals zoneout if zoneout ≥ 0.

Exceptions

GeographicErr	if zonein is out of range (see below).
GeographicErr	if zoneout is out of range (see below).
GeographicErr	if xin or yin fall outside their allowed ranges (see UTMUPS::Reverse).
GeographicErr	if xout or yout fall outside their allowed ranges (see UTMUPS::Reverse).

zonein must be in the range [UTMUPS::MINZONE, UTMUPS::MAXZONE] = [0, 60] with zonein = UTMUPS::UPS, 0, indicating UPS. zonein may also be UTMUPS::INVALID.

zoneout must be in the range [UTMUPS::MINPSEUDOZONE, UTMUPS::MAXZONE] = [-4, 60]. If zoneout < UTMUPS::MINZONE then the rules give in the documentation of UTMUPS::zonespec are applied, and zone is set to the actual zone used for output.

(xout, yout) can overlap with (xin, yin).

Definition at line 134 of file dotnet/NETGeographicLib/UTMUPS.cpp.

UTMShift()

double UTMUPS::UTMShift ( )

static

Returns

shift (meters) necessary to align N and S halves of a UTM zone (10⁷).

Definition at line 209 of file dotnet/NETGeographicLib/UTMUPS.cpp.

---

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

• UTMUPS.h
• dotnet/NETGeographicLib/UTMUPS.cpp