geographiclib 0.0.1

data/ext/geographiclib/GeographicLib/TransverseMercator.hpp

@@ -0,0 +1,196 @@
+/**
+ * \file TransverseMercator.hpp
+ * \brief Header for GeographicLib::TransverseMercator class
+ *
+ * Copyright (c) Charles Karney (2008-2015) <charles@karney.com> and licensed
+ * under the MIT/X11 License.  For more information, see
+ * http://geographiclib.sourceforge.net/
+ **********************************************************************/
+
+#if !defined(GEOGRAPHICLIB_TRANSVERSEMERCATOR_HPP)
+#define GEOGRAPHICLIB_TRANSVERSEMERCATOR_HPP 1
+
+#include <GeographicLib/Constants.hpp>
+
+#if !defined(GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER)
+/**
+ * The order of the series approximation used in TransverseMercator.
+ * GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER can be set to any integer in [4, 8].
+ **********************************************************************/
+#  define GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER \
+  (GEOGRAPHICLIB_PRECISION == 2 ? 6 : \
+   (GEOGRAPHICLIB_PRECISION == 1 ? 4 : 8))
+#endif
+
+namespace GeographicLib {
+
+  /**
+   * \brief Transverse Mercator projection
+   *
+   * This uses Kr&uuml;ger's method which evaluates the projection and its
+   * inverse in terms of a series.  See
+   *  - L. Kr&uuml;ger,
+   *    <a href="https://dx.doi.org/10.2312/GFZ.b103-krueger28"> Konforme
+   *    Abbildung des Erdellipsoids in der Ebene</a> (Conformal mapping of the
+   *    ellipsoidal earth to the plane), Royal Prussian Geodetic Institute, New
+   *    Series 52, 172 pp. (1912).
+   *  - C. F. F. Karney,
+   *    <a href="https://dx.doi.org/10.1007/s00190-011-0445-3">
+   *    Transverse Mercator with an accuracy of a few nanometers,</a>
+   *    J. Geodesy 85(8), 475--485 (Aug. 2011);
+   *    preprint
+   *    <a href="http://arxiv.org/abs/1002.1417">arXiv:1002.1417</a>.
+   *
+   * Kr&uuml;ger's method has been extended from 4th to 6th order.  The maximum
+   * error is 5 nm (5 nanometers), ground distance, for all positions within 35
+   * degrees of the central meridian.  The error in the convergence is 2
+   * &times; 10<sup>&minus;15</sup>&quot; and the relative error in the scale
+   * is 6 &times; 10<sup>&minus;12</sup>%%.  See Sec. 4 of
+   * <a href="http://arxiv.org/abs/1002.1417">arXiv:1002.1417</a> for details.
+   * The speed penalty in going to 6th order is only about 1%.
+   *
+   * There's a singularity in the projection at &phi; = 0&deg;, &lambda;
+   * &minus; &lambda;<sub>0</sub> = &plusmn;(1 &minus; \e e)90&deg; (&asymp;
+   * &plusmn;82.6&deg; for the WGS84 ellipsoid), where \e e is the
+   * eccentricity.  Beyond this point, the series ceases to converge and the
+   * results from this method will be garbage.  To be on the safe side, don't
+   * use this method if the angular distance from the central meridian exceeds
+   * (1 &minus; 2e)90&deg; (&asymp; 75&deg; for the WGS84 ellipsoid)
+   *
+   * TransverseMercatorExact is an alternative implementation of the projection
+   * using exact formulas which yield accurate (to 8 nm) results over the
+   * entire ellipsoid.
+   *
+   * The ellipsoid parameters and the central scale are set in the constructor.
+   * The central meridian (which is a trivial shift of the longitude) is
+   * specified as the \e lon0 argument of the TransverseMercator::Forward and
+   * TransverseMercator::Reverse functions.  The latitude of origin is taken to
+   * be the equator.  There is no provision in this class for specifying a
+   * false easting or false northing or a different latitude of origin.
+   * However these are can be simply included by the calling function.  For
+   * example, the UTMUPS class applies the false easting and false northing for
+   * the UTM projections.  A more complicated example is the British National
+   * Grid (<a href="http://www.spatialreference.org/ref/epsg/7405/">
+   * EPSG:7405</a>) which requires the use of a latitude of origin.  This is
+   * implemented by the GeographicLib::OSGB class.
+   *
+   * See TransverseMercator.cpp for more information on the implementation.
+   *
+   * See \ref transversemercator for a discussion of this projection.
+   *
+   * Example of use:
+   * \include example-TransverseMercator.cpp
+   *
+   * <a href="TransverseMercatorProj.1.html">TransverseMercatorProj</a> is a
+   * command-line utility providing access to the functionality of
+   * TransverseMercator and TransverseMercatorExact.
+   **********************************************************************/
+
+  class GEOGRAPHICLIB_EXPORT TransverseMercator {
+  private:
+    typedef Math::real real;
+    static const int maxpow_ = GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER;
+    static const int numit_ = 5;
+    real _a, _f, _k0, _e2, _es, _e2m,  _c, _n;
+    // _alp[0] and _bet[0] unused
+    real _a1, _b1, _alp[maxpow_ + 1], _bet[maxpow_ + 1];
+    friend class Ellipsoid;           // For access to taupf, tauf.
+  public:
+
+    /**
+     * Constructor for a ellipsoid with
+     *
+     * @param[in] a equatorial radius (meters).
+     * @param[in] f flattening of ellipsoid.  Setting \e f = 0 gives a sphere.
+     *   Negative \e f gives a prolate ellipsoid.
+     * @param[in] k0 central scale factor.
+     * @exception GeographicErr if \e a, (1 &minus; \e f) \e a, or \e k0 is
+     *   not positive.
+     **********************************************************************/
+    TransverseMercator(real a, real f, real k0);
+
+    /**
+     * Forward projection, from geographic to transverse Mercator.
+     *
+     * @param[in] lon0 central meridian of the projection (degrees).
+     * @param[in] lat latitude of point (degrees).
+     * @param[in] lon longitude of point (degrees).
+     * @param[out] x easting of point (meters).
+     * @param[out] y northing of point (meters).
+     * @param[out] gamma meridian convergence at point (degrees).
+     * @param[out] k scale of projection at point.
+     *
+     * No false easting or northing is added. \e lat should be in the range
+     * [&minus;90&deg;, 90&deg;].
+     **********************************************************************/
+    void Forward(real lon0, real lat, real lon,
+                 real& x, real& y, real& gamma, real& k) const;
+
+    /**
+     * Reverse projection, from transverse Mercator to geographic.
+     *
+     * @param[in] lon0 central meridian of the projection (degrees).
+     * @param[in] x easting of point (meters).
+     * @param[in] y northing of point (meters).
+     * @param[out] lat latitude of point (degrees).
+     * @param[out] lon longitude of point (degrees).
+     * @param[out] gamma meridian convergence at point (degrees).
+     * @param[out] k scale of projection at point.
+     *
+     * No false easting or northing is added.  The value of \e lon returned is
+     * in the range [&minus;180&deg;, 180&deg;).
+     **********************************************************************/
+    void Reverse(real lon0, real x, real y,
+                 real& lat, real& lon, real& gamma, real& k) const;
+
+    /**
+     * TransverseMercator::Forward without returning the convergence and scale.
+     **********************************************************************/
+    void Forward(real lon0, real lat, real lon,
+                 real& x, real& y) const {
+      real gamma, k;
+      Forward(lon0, lat, lon, x, y, gamma, k);
+    }
+
+    /**
+     * TransverseMercator::Reverse without returning the convergence and scale.
+     **********************************************************************/
+    void Reverse(real lon0, real x, real y,
+                 real& lat, real& lon) const {
+      real gamma, k;
+      Reverse(lon0, x, y, lat, lon, gamma, k);
+    }
+
+    /** \name Inspector functions
+     **********************************************************************/
+    ///@{
+    /**
+     * @return \e a the equatorial radius of the ellipsoid (meters).  This is
+     *   the value used in the constructor.
+     **********************************************************************/
+    Math::real MajorRadius() const { return _a; }
+
+    /**
+     * @return \e f the flattening of the ellipsoid.  This is the value used in
+     *   the constructor.
+     **********************************************************************/
+    Math::real Flattening() const { return _f; }
+
+    /**
+     * @return \e k0 central scale for the projection.  This is the value of \e
+     *   k0 used in the constructor and is the scale on the central meridian.
+     **********************************************************************/
+    Math::real CentralScale() const { return _k0; }
+    ///@}
+
+    /**
+     * A global instantiation of TransverseMercator with the WGS84 ellipsoid
+     * and the UTM scale factor.  However, unlike UTM, no false easting or
+     * northing is added.
+     **********************************************************************/
+    static const TransverseMercator& UTM();
+  };
+
+} // namespace GeographicLib
+
+#endif  // GEOGRAPHICLIB_TRANSVERSEMERCATOR_HPP

data/ext/geographiclib/GeographicLib/TransverseMercatorExact.hpp

@@ -0,0 +1,254 @@
+/**
+ * \file TransverseMercatorExact.hpp
+ * \brief Header for GeographicLib::TransverseMercatorExact class
+ *
+ * Copyright (c) Charles Karney (2008-2015) <charles@karney.com> and licensed
+ * under the MIT/X11 License.  For more information, see
+ * http://geographiclib.sourceforge.net/
+ **********************************************************************/
+
+#if !defined(GEOGRAPHICLIB_TRANSVERSEMERCATOREXACT_HPP)
+#define GEOGRAPHICLIB_TRANSVERSEMERCATOREXACT_HPP 1
+
+#include <GeographicLib/Constants.hpp>
+#include <GeographicLib/EllipticFunction.hpp>
+
+namespace GeographicLib {
+
+  /**
+   * \brief An exact implementation of the transverse Mercator projection
+   *
+   * Implementation of the Transverse Mercator Projection given in
+   *  - L. P. Lee,
+   *    <a href="https://dx.doi.org/10.3138/X687-1574-4325-WM62"> Conformal
+   *    Projections Based On Jacobian Elliptic Functions</a>, Part V of
+   *    Conformal Projections Based on Elliptic Functions,
+   *    (B. V. Gutsell, Toronto, 1976), 128pp.,
+   *    ISBN: 0919870163
+   *    (also appeared as:
+   *    Monograph 16, Suppl. No. 1 to Canadian Cartographer, Vol 13).
+   *  - C. F. F. Karney,
+   *    <a href="https://dx.doi.org/10.1007/s00190-011-0445-3">
+   *    Transverse Mercator with an accuracy of a few nanometers,</a>
+   *    J. Geodesy 85(8), 475--485 (Aug. 2011);
+   *    preprint
+   *    <a href="http://arxiv.org/abs/1002.1417">arXiv:1002.1417</a>.
+   *
+   * Lee gives the correct results for forward and reverse transformations
+   * subject to the branch cut rules (see the description of the \e extendp
+   * argument to the constructor).  The maximum error is about 8 nm (8
+   * nanometers), ground distance, for the forward and reverse transformations.
+   * The error in the convergence is 2 &times; 10<sup>&minus;15</sup>&quot;,
+   * the relative error in the scale is 7 &times; 10<sup>&minus;12</sup>%%.
+   * See Sec. 3 of
+   * <a href="http://arxiv.org/abs/1002.1417">arXiv:1002.1417</a> for details.
+   * The method is "exact" in the sense that the errors are close to the
+   * round-off limit and that no changes are needed in the algorithms for them
+   * to be used with reals of a higher precision.  Thus the errors using long
+   * double (with a 64-bit fraction) are about 2000 times smaller than using
+   * double (with a 53-bit fraction).
+   *
+   * This algorithm is about 4.5 times slower than the 6th-order Kr&uuml;ger
+   * method, TransverseMercator, taking about 11 us for a combined forward and
+   * reverse projection on a 2.66 GHz Intel machine (g++, version 4.3.0, -O3).
+   *
+   * The ellipsoid parameters and the central scale are set in the constructor.
+   * The central meridian (which is a trivial shift of the longitude) is
+   * specified as the \e lon0 argument of the TransverseMercatorExact::Forward
+   * and TransverseMercatorExact::Reverse functions.  The latitude of origin is
+   * taken to be the equator.  See the documentation on TransverseMercator for
+   * how to include a false easting, false northing, or a latitude of origin.
+   *
+   * See <a href="http://geographiclib.sourceforge.net/tm-grid.kmz"
+   * type="application/vnd.google-earth.kmz"> tm-grid.kmz</a>, for an
+   * illustration of the transverse Mercator grid in Google Earth.
+   *
+   * See TransverseMercatorExact.cpp for more information on the
+   * implementation.
+   *
+   * See \ref transversemercator for a discussion of this projection.
+   *
+   * Example of use:
+   * \include example-TransverseMercatorExact.cpp
+   *
+   * <a href="TransverseMercatorProj.1.html">TransverseMercatorProj</a> is a
+   * command-line utility providing access to the functionality of
+   * TransverseMercator and TransverseMercatorExact.
+   **********************************************************************/
+
+  class GEOGRAPHICLIB_EXPORT TransverseMercatorExact {
+  private:
+    typedef Math::real real;
+    static const int numit_ = 10;
+    real tol_, tol1_, tol2_, taytol_;
+    real _a, _f, _k0, _mu, _mv, _e;
+    bool _extendp;
+    EllipticFunction _Eu, _Ev;
+
+    void zeta(real u, real snu, real cnu, real dnu,
+              real v, real snv, real cnv, real dnv,
+              real& taup, real& lam) const;
+
+    void dwdzeta(real u, real snu, real cnu, real dnu,
+                 real v, real snv, real cnv, real dnv,
+                 real& du, real& dv) const;
+
+    bool zetainv0(real psi, real lam, real& u, real& v) const;
+    void zetainv(real taup, real lam, real& u, real& v) const;
+
+    void sigma(real u, real snu, real cnu, real dnu,
+               real v, real snv, real cnv, real dnv,
+               real& xi, real& eta) const;
+
+    void dwdsigma(real u, real snu, real cnu, real dnu,
+                  real v, real snv, real cnv, real dnv,
+                  real& du, real& dv) const;
+
+    bool sigmainv0(real xi, real eta, real& u, real& v) const;
+    void sigmainv(real xi, real eta, real& u, real& v) const;
+
+    void Scale(real tau, real lam,
+               real snu, real cnu, real dnu,
+               real snv, real cnv, real dnv,
+               real& gamma, real& k) const;
+
+  public:
+
+    /**
+     * Constructor for a ellipsoid with
+     *
+     * @param[in] a equatorial radius (meters).
+     * @param[in] f flattening of ellipsoid.
+     * @param[in] k0 central scale factor.
+     * @param[in] extendp use extended domain.
+     * @exception GeographicErr if \e a, \e f, or \e k0 is not positive.
+     *
+     * The transverse Mercator projection has a branch point singularity at \e
+     * lat = 0 and \e lon &minus; \e lon0 = 90 (1 &minus; \e e) or (for
+     * TransverseMercatorExact::UTM) x = 18381 km, y = 0m.  The \e extendp
+     * argument governs where the branch cut is placed.  With \e extendp =
+     * false, the "standard" convention is followed, namely the cut is placed
+     * along \e x > 18381 km, \e y = 0m.  Forward can be called with any \e lat
+     * and \e lon then produces the transformation shown in Lee, Fig 46.
+     * Reverse analytically continues this in the &plusmn; \e x direction.  As
+     * a consequence, Reverse may map multiple points to the same geographic
+     * location; for example, for TransverseMercatorExact::UTM, \e x =
+     * 22051449.037349 m, \e y = &minus;7131237.022729 m and \e x =
+     * 29735142.378357 m, \e y = 4235043.607933 m both map to \e lat =
+     * &minus;2&deg;, \e lon = 88&deg;.
+     *
+     * With \e extendp = true, the branch cut is moved to the lower left
+     * quadrant.  The various symmetries of the transverse Mercator projection
+     * can be used to explore the projection on any sheet.  In this mode the
+     * domains of \e lat, \e lon, \e x, and \e y are restricted to
+     * - the union of
+     *   - \e lat in [0, 90] and \e lon &minus; \e lon0 in [0, 90]
+     *   - \e lat in (-90, 0] and \e lon &minus; \e lon0 in [90 (1 &minus; \e
+           e), 90]
+     * - the union of
+     *   - <i>x</i>/(\e k0 \e a) in [0, &infin;) and
+     *     <i>y</i>/(\e k0 \e a) in [0, E(<i>e</i><sup>2</sup>)]
+     *   - <i>x</i>/(\e k0 \e a) in [K(1 &minus; <i>e</i><sup>2</sup>) &minus;
+     *     E(1 &minus; <i>e</i><sup>2</sup>), &infin;) and <i>y</i>/(\e k0 \e
+     *     a) in (&minus;&infin;, 0]
+     * .
+     * See Sec. 5 of
+     * <a href="http://arxiv.org/abs/1002.1417">arXiv:1002.1417</a> for a full
+     * discussion of the treatment of the branch cut.
+     *
+     * The method will work for all ellipsoids used in terrestrial geodesy.
+     * The method cannot be applied directly to the case of a sphere (\e f = 0)
+     * because some the constants characterizing this method diverge in that
+     * limit, and in practice, \e f should be larger than about
+     * numeric_limits<real>::epsilon().  However, TransverseMercator treats the
+     * sphere exactly.
+     **********************************************************************/
+    TransverseMercatorExact(real a, real f, real k0, bool extendp = false);
+
+    /**
+     * Forward projection, from geographic to transverse Mercator.
+     *
+     * @param[in] lon0 central meridian of the projection (degrees).
+     * @param[in] lat latitude of point (degrees).
+     * @param[in] lon longitude of point (degrees).
+     * @param[out] x easting of point (meters).
+     * @param[out] y northing of point (meters).
+     * @param[out] gamma meridian convergence at point (degrees).
+     * @param[out] k scale of projection at point.
+     *
+     * No false easting or northing is added. \e lat should be in the range
+     * [&minus;90&deg;, 90&deg;].
+     **********************************************************************/
+    void Forward(real lon0, real lat, real lon,
+                 real& x, real& y, real& gamma, real& k) const;
+
+    /**
+     * Reverse projection, from transverse Mercator to geographic.
+     *
+     * @param[in] lon0 central meridian of the projection (degrees).
+     * @param[in] x easting of point (meters).
+     * @param[in] y northing of point (meters).
+     * @param[out] lat latitude of point (degrees).
+     * @param[out] lon longitude of point (degrees).
+     * @param[out] gamma meridian convergence at point (degrees).
+     * @param[out] k scale of projection at point.
+     *
+     * No false easting or northing is added.  The value of \e lon returned is
+     * in the range [&minus;180&deg;, 180&deg;).
+     **********************************************************************/
+    void Reverse(real lon0, real x, real y,
+                 real& lat, real& lon, real& gamma, real& k) const;
+
+    /**
+     * TransverseMercatorExact::Forward without returning the convergence and
+     * scale.
+     **********************************************************************/
+    void Forward(real lon0, real lat, real lon,
+                 real& x, real& y) const {
+      real gamma, k;
+      Forward(lon0, lat, lon, x, y, gamma, k);
+    }
+
+    /**
+     * TransverseMercatorExact::Reverse without returning the convergence and
+     * scale.
+     **********************************************************************/
+    void Reverse(real lon0, real x, real y,
+                 real& lat, real& lon) const {
+      real gamma, k;
+      Reverse(lon0, x, y, lat, lon, gamma, k);
+    }
+
+    /** \name Inspector functions
+     **********************************************************************/
+    ///@{
+    /**
+     * @return \e a the equatorial radius of the ellipsoid (meters).  This is
+     *   the value used in the constructor.
+     **********************************************************************/
+    Math::real MajorRadius() const { return _a; }
+
+    /**
+     * @return \e f the flattening of the ellipsoid.  This is the value used in
+     *   the constructor.
+     **********************************************************************/
+    Math::real Flattening() const { return _f; }
+
+    /**
+     * @return \e k0 central scale for the projection.  This is the value of \e
+     *   k0 used in the constructor and is the scale on the central meridian.
+     **********************************************************************/
+    Math::real CentralScale() const { return _k0; }
+    ///@}
+
+    /**
+     * A global instantiation of TransverseMercatorExact with the WGS84
+     * ellipsoid and the UTM scale factor.  However, unlike UTM, no false
+     * easting or northing is added.
+     **********************************************************************/
+    static const TransverseMercatorExact& UTM();
+  };
+
+} // namespace GeographicLib
+
+#endif  // GEOGRAPHICLIB_TRANSVERSEMERCATOREXACT_HPP

data/ext/geographiclib/GeographicLib/UTMUPS.hpp

@@ -0,0 +1,421 @@
+/**
+ * \file UTMUPS.hpp
+ * \brief Header for GeographicLib::UTMUPS class
+ *
+ * Copyright (c) Charles Karney (2008-2015) <charles@karney.com> and licensed
+ * under the MIT/X11 License.  For more information, see
+ * http://geographiclib.sourceforge.net/
+ **********************************************************************/
+
+#if !defined(GEOGRAPHICLIB_UTMUPS_HPP)
+#define GEOGRAPHICLIB_UTMUPS_HPP 1
+
+#include <GeographicLib/Constants.hpp>
+
+namespace GeographicLib {
+
+  /**
+   * \brief Convert between geographic coordinates and UTM/UPS
+   *
+   * UTM and UPS are defined
+   * - J. W. Hager, J. F. Behensky, and B. W. Drew,
+   *   <a href="http://earth-info.nga.mil/GandG/publications/tm8358.2/TM8358_2.pdf">
+   *   The Universal Grids: Universal Transverse Mercator (UTM) and Universal
+   *   Polar Stereographic (UPS)</a>, 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.
+   * These are the algorithms recommended by the NGA document
+   * - <a href="http://earth-info.nga.mil/GandG/publications/NGA_SIG_0012_2_0_0_UTMUPS/NGA.SIG.0012_2.0.0_UTMUPS.pdf">
+   *   The Universal Grids and the Transverse Mercator and Polar Stereographic
+   *   Map Projections</a>, NGA.SIG.0012_2.0.0_UTMUPS (2014).
+   *
+   * 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 <a href="http://www.nga.mil">NGA</a> software package
+   * <a href="http://earth-info.nga.mil/GandG/geotrans/index.html">geotrans</a>
+   * 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.
+   *
+   * The GeographicLib::UTMUPS::EncodeZone encodes the UTM zone and hemisphere
+   * to allow UTM/UPS coordinated to be displayed as, for example, "38N 444500
+   * 3688500".  According to NGA.SIG.0012_2.0.0_UTMUPS the use of "N" to denote
+   * "north" in the context is not allowed (since a upper case letter in this
+   * context denotes the MGRS latitude band).  Consequently, as of version
+   * 1.36, EncodeZone uses the lower case letters "n" and "s" to denote the
+   * hemisphere.  In addition EncodeZone accepts an optional final argument \e
+   * abbrev, which, if false, results in the hemisphere being spelled out as in
+   * "38north".
+   *
+   * Example of use:
+   * \include example-UTMUPS.cpp
+   **********************************************************************/
+  class GEOGRAPHICLIB_EXPORT UTMUPS {
+  private:
+    typedef Math::real real;
+    static const int falseeasting_[4];
+    static const int falsenorthing_[4];
+    static const int mineasting_[4];
+    static const int maxeasting_[4];
+    static const int minnorthing_[4];
+    static const int maxnorthing_[4];
+    static const int epsg01N = 32601; // EPSG code for UTM 01N
+    static const int epsg60N = 32660; // EPSG code for UTM 60N
+    static const int epsgN   = 32661; // EPSG code for UPS   N
+    static const int epsg01S = 32701; // EPSG code for UTM 01S
+    static const int epsg60S = 32760; // EPSG code for UTM 60S
+    static const int epsgS   = 32761; // EPSG code for UPS   S
+    static real CentralMeridian(int zone)
+    { return real(6 * zone - 183); }
+    // Throw an error if easting or northing are outside standard ranges.  If
+    // throwp = false, return bool instead.
+    static bool CheckCoords(bool utmp, bool northp, real x, real y,
+                            bool msgrlimits = false, bool throwp = true);
+    UTMUPS();                   // Disable constructor
+
+  public:
+
+    /**
+     * In this class we bring together the UTM and UPS coordinates systems.
+     * The UTM divides the earth between latitudes &minus;80&deg; and 84&deg;
+     * 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.
+     **********************************************************************/
+    enum zonespec {
+      /**
+       * The smallest pseudo-zone number.
+       **********************************************************************/
+      MINPSEUDOZONE = -4,
+      /**
+       * A marker for an undefined or invalid zone.  Equivalent to NaN.
+       **********************************************************************/
+      INVALID = -4,
+      /**
+       * If a coordinate already include zone information (e.g., it is an MGRS
+       * coordinate), use that, otherwise apply the UTMUPS::STANDARD rules.
+       **********************************************************************/
+      MATCH = -3,
+      /**
+       * 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&deg;, 48&deg;).  The rules include the
+       * Norway and Svalbard exceptions.
+       **********************************************************************/
+      UTM = -2,
+      /**
+       * Apply the standard rules for zone assignment to give a zone number in
+       * [0, 60].  If the latitude is not in [&minus;80&deg;, 84&deg;), 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 [&minus;80&deg;,
+       * 84&deg;) and longitude is in [42&deg;, 48&deg;).
+       **********************************************************************/
+      STANDARD = -1,
+      /**
+       * The largest pseudo-zone number.
+       **********************************************************************/
+      MAXPSEUDOZONE = -1,
+      /**
+       * The smallest physical zone number.
+       **********************************************************************/
+      MINZONE = 0,
+      /**
+       * The zone number used for UPS
+       **********************************************************************/
+      UPS = 0,
+      /**
+       * The smallest UTM zone number.
+       **********************************************************************/
+      MINUTMZONE = 1,
+      /**
+       * The largest UTM zone number.
+       **********************************************************************/
+      MAXUTMZONE = 60,
+      /**
+       * The largest physical zone number.
+       **********************************************************************/
+      MAXZONE = 60,
+    };
+
+    /**
+     * The standard zone.
+     *
+     * @param[in] lat latitude (degrees).
+     * @param[in] lon longitude (degrees).
+     * @param[in] setzone zone override (optional).  If omitted, use the
+     *   standard rules for picking the zone.  If \e setzone is given then use
+     *   that zone if it is non-negative, otherwise apply the rules given in
+     *   UTMUPS::zonespec.
+     * @exception GeographicErr if \e setzone is outside the range
+     *   [UTMUPS::MINPSEUDOZONE, UTMUPS::MAXZONE] = [&minus;4, 60].
+     *
+     * This is exact.
+     **********************************************************************/
+    static int StandardZone(real lat, real lon, int setzone = STANDARD);
+
+    /**
+     * Forward projection, from geographic to UTM/UPS.
+     *
+     * @param[in] lat latitude of point (degrees).
+     * @param[in] lon longitude of point (degrees).
+     * @param[out] zone the UTM zone (zero means UPS).
+     * @param[out] northp hemisphere (true means north, false means south).
+     * @param[out] x easting of point (meters).
+     * @param[out] y northing of point (meters).
+     * @param[out] gamma meridian convergence at point (degrees).
+     * @param[out] k scale of projection at point.
+     * @param[in] setzone zone override (optional).
+     * @param[in] mgrslimits if true enforce the stricter MGRS limits on the
+     *   coordinates (default = false).
+     * @exception GeographicErr if \e lat is not in [&minus;90&deg;,
+     *   90&deg;].
+     * @exception GeographicErr if the resulting \e x or \e y is out of allowed
+     *   range (see Reverse); in this case, these arguments are unchanged.
+     *
+     * If \e setzone is omitted, use the standard rules for picking the zone.
+     * If \e 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 \e y jumps by UTMUPS::UTMShift() when crossing the equator
+     * in the southerly direction.  Sometimes it is useful to remove this
+     * discontinuity in \e y by extending the "northern" hemisphere using
+     * UTMUPS::Transfer:
+     * \code
+     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;
+     \endcode
+     **********************************************************************/
+    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);
+
+    /**
+     * Reverse projection, from  UTM/UPS to geographic.
+     *
+     * @param[in] zone the UTM zone (zero means UPS).
+     * @param[in] northp hemisphere (true means north, false means south).
+     * @param[in] x easting of point (meters).
+     * @param[in] y northing of point (meters).
+     * @param[out] lat latitude of point (degrees).
+     * @param[out] lon longitude of point (degrees).
+     * @param[out] gamma meridian convergence at point (degrees).
+     * @param[out] k scale of projection at point.
+     * @param[in] mgrslimits if true enforce the stricter MGRS limits on the
+     *   coordinates (default = false).
+     * @exception GeographicErr if \e zone, \e x, or \e 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, 3300km] 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 \e 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).
+     **********************************************************************/
+    static void Reverse(int zone, bool northp, real x, real y,
+                        real& lat, real& lon, real& gamma, real& k,
+                        bool mgrslimits = false);
+
+    /**
+     * UTMUPS::Forward without returning convergence and scale.
+     **********************************************************************/
+    static void Forward(real lat, real lon,
+                        int& zone, bool& northp, real& x, real& y,
+                        int setzone = STANDARD, bool mgrslimits = false) {
+      real gamma, k;
+      Forward(lat, lon, zone, northp, x, y, gamma, k, setzone, mgrslimits);
+    }
+
+    /**
+     * UTMUPS::Reverse without returning convergence and scale.
+     **********************************************************************/
+    static void Reverse(int zone, bool northp, real x, real y,
+                        real& lat, real& lon, bool mgrslimits = false) {
+      real gamma, k;
+      Reverse(zone, northp, x, y, lat, lon, gamma, k, mgrslimits);
+    }
+
+    /**
+     * Transfer UTM/UPS coordinated from one zone to another.
+     *
+     * @param[in] zonein the UTM zone for \e xin and \e yin (or zero for UPS).
+     * @param[in] northpin hemisphere for \e xin and \e yin (true means north,
+     *   false means south).
+     * @param[in] xin easting of point (meters) in \e zonein.
+     * @param[in] yin northing of point (meters) in \e zonein.
+     * @param[in] zoneout the requested UTM zone for \e xout and \e yout (or
+     *   zero for UPS).
+     * @param[in] northpout hemisphere for \e xout output and \e yout.
+     * @param[out] xout easting of point (meters) in \e zoneout.
+     * @param[out] yout northing of point (meters) in \e zoneout.
+     * @param[out] zone the actual UTM zone for \e xout and \e yout (or zero
+     *   for UPS); this equals \e zoneout if \e zoneout &ge; 0.
+     * @exception GeographicErr if \e zonein is out of range (see below).
+     * @exception GeographicErr if \e zoneout is out of range (see below).
+     * @exception GeographicErr if \e xin or \e yin fall outside their allowed
+     *   ranges (see UTMUPS::Reverse).
+     * @exception GeographicErr if \e xout or \e yout fall outside their
+     *   allowed ranges (see UTMUPS::Reverse).
+     *
+     * \e zonein must be in the range [UTMUPS::MINZONE, UTMUPS::MAXZONE] = [0,
+     * 60] with \e zonein = UTMUPS::UPS, 0, indicating UPS.  \e zonein may
+     * also be UTMUPS::INVALID.
+     *
+     * \e zoneout must be in the range [UTMUPS::MINPSEUDOZONE, UTMUPS::MAXZONE]
+     * = [-4, 60].  If \e zoneout &lt; UTMUPS::MINZONE then the rules give in
+     * the documentation of UTMUPS::zonespec are applied, and \e zone is set to
+     * the actual zone used for output.
+     *
+     * (\e xout, \e yout) can overlap with (\e xin, \e yin).
+     **********************************************************************/
+    static void Transfer(int zonein, bool northpin, real xin, real yin,
+                         int zoneout, bool northpout, real& xout, real& yout,
+                         int& zone);
+
+    /**
+     * Decode a UTM/UPS zone string.
+     *
+     * @param[in] zonestr string representation of zone and hemisphere.
+     * @param[out] zone the UTM zone (zero means UPS).
+     * @param[out] northp hemisphere (true means north, false means south).
+     * @exception GeographicErr if \e zonestr is malformed.
+     *
+     * For UTM, \e 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 \e zone is UTMUPS::UPS = 0 for UPS.
+     * Note well that "38s" indicates the southern hemisphere of zone 38 and
+     * not latitude band S, 32&deg; &le; \e lat &lt; 40&deg;.  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 \e is UTMUPS::INVALID.
+     **********************************************************************/
+    static void DecodeZone(const std::string& zonestr, int& zone, bool& northp);
+
+    /**
+     * Encode a UTM/UPS zone string.
+     *
+     * @param[in] zone the UTM zone (zero means UPS).
+     * @param[in] northp hemisphere (true means north, false means south).
+     * @param[in] abbrev if true (the default) use abbreviated (n/s) notation
+     *   for hemisphere; otherwise spell out the hemisphere (north/south)
+     * @exception GeographicErr if \e zone is out of range (see below).
+     * @exception std::bad_alloc if memoy for the string can't be allocated.
+     * @return string representation of zone and hemisphere.
+     *
+     * \e zone must be in the range [UTMUPS::MINZONE, UTMUPS::MAXZONE] = [0,
+     * 60] with \e zone = UTMUPS::UPS, 0, indicating UPS (but the resulting
+     * string does not contain "0").  \e zone may also be UTMUPS::INVALID, in
+     * which case the returned string is "inv".  This reverses
+     * UTMUPS::DecodeZone.
+     **********************************************************************/
+    static std::string EncodeZone(int zone, bool northp, bool abbrev = true);
+
+    /**
+     * Decode EPSG.
+     *
+     * @param[in] epsg the EPSG code.
+     * @param[out] zone the UTM zone (zero means UPS).
+     * @param[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, \e zone is set to UTMUPS::INVALID.  See
+     * http://spatialreference.org/ref/epsg/
+     **********************************************************************/
+    static void DecodeEPSG(int epsg, int& zone, bool& northp);
+
+    /**
+     * Encode zone as EPSG.
+     *
+     * @param[in] zone the UTM zone (zero means UPS).
+     * @param[in] northp hemisphere (true means north, false means south).
+     * @return EPSG code (or -1 if \e zone is not in the range
+     *   [UTMUPS::MINZONE, UTMUPS::MAXZONE] = [0, 60])
+     *
+     * Convert \e zone and \e northp to the corresponding EPSG (European
+     * Petroleum Survery Group) codes
+     **********************************************************************/
+    static int EncodeEPSG(int zone, bool northp);
+
+    /**
+     * @return shift (meters) necessary to align north and south halves of a
+     * UTM zone (10<sup>7</sup>).
+     **********************************************************************/
+    static Math::real UTMShift();
+
+    /** \name Inspector functions
+     **********************************************************************/
+    ///@{
+    /**
+     * @return \e 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.)
+     **********************************************************************/
+    static Math::real MajorRadius()
+    { return Constants::WGS84_a(); }
+
+    /**
+     * @return \e f the flattening of the WGS84 ellipsoid.
+     *
+     * (The WGS84 value is returned because the UTM and UPS projections are
+     * based on this ellipsoid.)
+     **********************************************************************/
+    static Math::real Flattening()
+    { return Constants::WGS84_f(); }
+    ///@}
+
+  };
+
+} // namespace GeographicLib
+
+#endif  // GEOGRAPHICLIB_UTMUPS_HPP