Convert between Geographic coordinates and UTM/UPS. More...
#include <GeographicLib/UTMUPS.hpp>
Public Types | |
enum | zonespec { MINPSEUDOZONE = -3, MATCH = -3, UTM = -2, STANDARD = -1, MAXPSEUDOZONE = -1, MINZONE = 0, UPS = 0, MINUTMZONE = 1, MAXUTMZONE = 60, MAXZONE = 60 } |
Static Public Member Functions | |
static int | StandardZone (real lat, real lon, int setzone=STANDARD) |
static void | Forward (real lat, real lon, int &zone, bool &northp, real &x, real &y, real &gamma, real &k, int setzone=STANDARD, bool mgrslimits=false) |
static void | Reverse (int zone, bool northp, real x, real y, real &lat, real &lon, real &gamma, real &k, bool mgrslimits=false) |
static void | Forward (real lat, real lon, int &zone, bool &northp, real &x, real &y, int setzone=STANDARD, bool mgrslimits=false) |
static void | Reverse (int zone, bool northp, real x, real y, real &lat, real &lon, bool mgrslimits=false) |
static void | DecodeZone (const std::string &zonestr, int &zone, bool &northp) |
static std::string | EncodeZone (int zone, bool northp) |
static Math::real | UTMShift () throw () |
static Math::real | MajorRadius () throw () |
static Math::real | InverseFlattening () throw () |
Convert between Geographic coordinates and UTM/UPS.
UTM and UPS are defined
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:
Definition at line 60 of file UTMUPS.hpp.
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.
MINPSEUDOZONE |
The smallest pseudo-zone number. |
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 91 of file UTMUPS.hpp.
int GeographicLib::UTMUPS::StandardZone | ( | real | lat, | |
real | lon, | |||
int | setzone = STANDARD | |||
) | [static] |
Return the standard zone for latitude lat (degrees) and longitude lon (degrees); see UTMUPS::STANDARD. This is exact. If the optional argument setzone is given then use that zone if it is non-negative, otherwise apply the rules given in UTMUPS::zonespec. Throws an error if setzone is outsize the range [UTMUPS::MINPSEUDOZONE, UTMUPS::MAXZONE] = [-3, 60].
Definition at line 46 of file UTMUPS.cpp.
References MAXZONE, MINZONE, UPS, and UTM.
Referenced by Forward(), and GeographicLib::GeoCoords::SetAltZone().
void GeographicLib::UTMUPS::Forward | ( | real | lat, | |
real | lon, | |||
int & | zone, | |||
bool & | northp, | |||
real & | x, | |||
real & | y, | |||
real & | gamma, | |||
real & | k, | |||
int | setzone = STANDARD , |
|||
bool | mgrslimits = false | |||
) | [static] |
Convert geographic coordinates to UTM or UPS coordinate. Given latitude lat (degrees), and longitude lon (degrees), return zone (zero indicates UPS), hemisphere northp (false means south, true means north), easting x (meters), and northing y (meters). The prefered zone for the result can be specified with setzone, see UTMUPS::StandardZone. Throw error if the resulting easting or northing is outside the allowed range (see Reverse), in which case the arguments are unchanged. If mgrslimits == true, then use the stricter MGRS limits (see Reverse). This also returns meridian convergence gamma (degrees) and scale k. The accuracy of the conversion is about 5nm.
Definition at line 68 of file UTMUPS.cpp.
References GeographicLib::PolarStereographic::Forward(), GeographicLib::TransverseMercator::Forward(), StandardZone(), GeographicLib::PolarStereographic::UPS, UPS, and GeographicLib::TransverseMercator::UTM.
Referenced by Forward(), GeographicLib::GeoCoords::Reset(), and GeographicLib::GeoCoords::SetAltZone().
void GeographicLib::UTMUPS::Reverse | ( | int | zone, | |
bool | northp, | |||
real | x, | |||
real | y, | |||
real & | lat, | |||
real & | lon, | |||
real & | gamma, | |||
real & | k, | |||
bool | mgrslimits = false | |||
) | [static] |
Convert UTM or UPS coordinate to geographic coordinates . Given zone zone (zone == UTMUPS::UPS, 0, indicates UPS), hemisphere northp (false means south, true means north), easting x (meters), and northing y (meters), return latitude lat (degrees) and longitude lon (degrees). Throw error if easting or northing is outside the allowed range (see below), in which case the arguments are unchanged. This also returns meridian convergence gamma (degrees) and scale k. 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 111 of file UTMUPS.cpp.
References MAXZONE, MINZONE, GeographicLib::PolarStereographic::Reverse(), GeographicLib::TransverseMercator::Reverse(), GeographicLib::PolarStereographic::UPS, UPS, and GeographicLib::TransverseMercator::UTM.
Referenced by GeographicLib::GeoCoords::Reset(), and Reverse().
static void GeographicLib::UTMUPS::Forward | ( | real | lat, | |
real | lon, | |||
int & | zone, | |||
bool & | northp, | |||
real & | x, | |||
real & | y, | |||
int | setzone = STANDARD , |
|||
bool | mgrslimits = false | |||
) | [inline, static] |
Forward without returning convergence and scale.
Definition at line 204 of file UTMUPS.hpp.
References Forward().
static void GeographicLib::UTMUPS::Reverse | ( | int | zone, | |
bool | northp, | |||
real | x, | |||
real | y, | |||
real & | lat, | |||
real & | lon, | |||
bool | mgrslimits = false | |||
) | [inline, static] |
Reverse without returning convergence and scale.
Definition at line 214 of file UTMUPS.hpp.
References Reverse().
void GeographicLib::UTMUPS::DecodeZone | ( | const std::string & | zonestr, | |
int & | zone, | |||
bool & | northp | |||
) | [static] |
Decode a UTM/UPS zone string, zonestr, returning the resulting zone and hemisphere thru northp (true for northern and false for southern hemispheres). 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. For UPS, it consists just of the hemisphere letter. 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, 40]. N, 01S, 2N, 38S are legal. 0N, 001S, 61N, 38P are illegal.
Definition at line 162 of file UTMUPS.cpp.
References MAXUTMZONE, MINUTMZONE, and UPS.
Referenced by GeographicLib::GeoCoords::Reset().
std::string GeographicLib::UTMUPS::EncodeZone | ( | int | zone, | |
bool | northp | |||
) | [static] |
Encode a UTM/UPS zone string given the zone and hemisphere northp. 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"). This reverses DecodeZone.
Definition at line 197 of file UTMUPS.cpp.
Math::real GeographicLib::UTMUPS::UTMShift | ( | ) | throw () [static] |
The shift necessary to align N and S halves of a UTM zone (107).
Definition at line 207 of file UTMUPS.cpp.
static Math::real GeographicLib::UTMUPS::MajorRadius | ( | ) | throw () [inline, static] |
The major radius of the ellipsoid (meters). This is the value for the WGS84 ellipsoid because the UTM and UPS projections are based on this ellipsoid.
Definition at line 253 of file UTMUPS.hpp.
References GeographicLib::Constants::WGS84_a().
static Math::real GeographicLib::UTMUPS::InverseFlattening | ( | ) | throw () [inline, static] |
The inverse flattening of the ellipsoid. This is the value for the WGS84 ellipsoid because the UTM and UPS projections are based on this ellipsoid.
Definition at line 260 of file UTMUPS.hpp.
References GeographicLib::Constants::WGS84_r().