GeographicLib: Georef.hpp Source File

GeographicLib 2.7

Loading...
Searching...
No Matches
Georef.hpp
Go to the documentation of this file.
1/**
2 * \file Georef.hpp
3 * \brief Header for GeographicLib::Georef class
4 *
5 * Copyright (c) Charles Karney (2015-2024) <karney@alum.mit.edu> and licensed
6 * under the MIT/X11 License. For more information, see
7 * https://geographiclib.sourceforge.io/
8 **********************************************************************/
9
10#if !defined(GEOGRAPHICLIB_GEOREF_HPP)
11#define GEOGRAPHICLIB_GEOREF_HPP 1
12
13#include <GeographicLib/Constants.hpp>
14
15namespace GeographicLib {
16
17 /**
18 * \brief Conversions for the World Geographic Reference System (georef)
19 *
20 * The World Geographic Reference System is described in
21 * - https://en.wikipedia.org/wiki/Georef
22 * - https://web.archive.org/web/20161214054445/http://earth-info.nga.mil/GandG/coordsys/grids/georef.pdf
23 * .
24 * It provides a compact string representation of a geographic area
25 * (expressed as latitude and longitude). The classes GARS and Geohash
26 * implement similar compact representations.
27 *
28 * Example of use:
29 * \include example-Georef.cpp
30 **********************************************************************/
31
32 class GEOGRAPHICLIB_EXPORT Georef {
33 private:
34 typedef Math::real real;
35 static const char* const digits_;
36 static const char* const lontile_;
37 static const char* const lattile_;
38 static const char* const degrees_;
39 static constexpr int tile_ = 15; // The size of tile in degrees
40 static constexpr int lonorig_ = -Math::hd; // Origin for longitude
41 static constexpr int latorig_ = -Math::qd; // Origin for latitude
42 static constexpr int base_ = 10; // Base for minutes
43 static constexpr int baselen_ = 4;
44 static constexpr int maxprec_ = 11; // approximately equivalent to MGRS class
45 static constexpr int maxlen_ = baselen_ + 2 * maxprec_;
46 Georef() = delete; // Disable constructor
47
48 public:
49
50 /**
51 * Convert from geographic coordinates to georef.
52 *
53 * @param[in] lat latitude of point (degrees).
54 * @param[in] lon longitude of point (degrees).
55 * @param[in] prec the precision of the resulting georef.
56 * @param[out] georef the georef string.
57 * @exception GeographicErr if \e lat is not in [&minus;90&deg;,
58 * 90&deg;].
59 * @exception std::bad_alloc if memory for \e georef can't be allocated.
60 *
61 * \e prec specifies the precision of \e georef as follows:
62 * - \e prec = &minus;1 (min), 15&deg;
63 * - \e prec = 0, 1&deg;
64 * - \e prec = 1, converted to \e prec = 2
65 * - \e prec = 2, 1'
66 * - \e prec = 3, 0.1'
67 * - \e prec = 4, 0.01'
68 * - \e prec = 5, 0.001'
69 * - &hellip;
70 * - \e prec = 11 (max), 10<sup>&minus;9</sup>'
71 *
72 * If \e lat or \e lon is NaN, then \e georef is set to "INVALID".
73 **********************************************************************/
74 static void Forward(real lat, real lon, int prec, std::string& georef);
75
76 /**
77 * Convert from Georef to geographic coordinates.
78 *
79 * @param[in] georef the Georef.
80 * @param[out] lat latitude of point (degrees).
81 * @param[out] lon longitude of point (degrees).
82 * @param[out] prec the precision of \e georef.
83 * @param[in] centerp if true (the default) return the center
84 * \e georef, otherwise return the south-west corner.
85 * @exception GeographicErr if \e georef is illegal.
86 *
87 * The case of the letters in \e georef is ignored. \e prec is in the
88 * range [&minus;1, 11] and gives the precision of \e georef as follows:
89 * - \e prec = &minus;1 (min), 15&deg;
90 * - \e prec = 0, 1&deg;
91 * - \e prec = 1, not returned
92 * - \e prec = 2, 1'
93 * - \e prec = 3, 0.1'
94 * - \e prec = 4, 0.01'
95 * - \e prec = 5, 0.001'
96 * - &hellip;
97 * - \e prec = 11 (max), 10<sup>&minus;9</sup>'
98 *
99 * If the first 3 characters of \e georef are "INV", then \e lat and \e lon
100 * are set to NaN and \e prec is unchanged.
101 **********************************************************************/
102 static void Reverse(const std::string& georef, real& lat, real& lon,
103 int& prec, bool centerp = true);
104
105 /**
106 * The angular resolution of a Georef.
107 *
108 * @param[in] prec the precision of the Georef.
109 * @return the latitude-longitude resolution (degrees).
110 *
111 * Internally, \e prec is first put in the range [&minus;1, 11].
112 **********************************************************************/
113 static Math::real Resolution(int prec) {
114 if (prec < 1)
115 return real(prec < 0 ? 15 : 1);
116 else {
117 using std::pow;
118 // Treat prec = 1 as 2.
119 prec = (std::max)(2, (std::min)(int(maxprec_), prec));
120 // Need extra real because, since C++11, pow(float, int) returns double
121 return 1/(60 * real(pow(real(base_), prec - 2)));
122 }
123 }
124
125 /**
126 * The Georef precision required to meet a given geographic resolution.
127 *
128 * @param[in] res the minimum of resolution in latitude and longitude
129 * (degrees).
130 * @return Georef precision.
131 *
132 * The returned length is in the range [0, 11].
133 **********************************************************************/
134 static int Precision(real res) {
135 using std::fabs; res = fabs(res);
136 for (int prec = 0; prec < maxprec_; ++prec) {
137 if (prec == 1)
138 continue;
139 if (Resolution(prec) <= res)
140 return prec;
141 }
142 return maxprec_;
143 }
144
145 };
146
147} // namespace GeographicLib
148
149#endif // GEOGRAPHICLIB_GEOREF_HPP
Constants.hpp
Header for GeographicLib::Constants class.
GEOGRAPHICLIB_EXPORT
#define GEOGRAPHICLIB_EXPORT
Definition Constants.hpp:59
real
GeographicLib::Math::real real
Definition Geod3Solve.cpp:25
GeographicLib::Georef::Precision
static int Precision(real res)
Definition Georef.hpp:134
GeographicLib::Georef::Forward
static void Forward(real lat, real lon, int prec, std::string &georef)
Definition Georef.cpp:22
GeographicLib::Georef::Resolution
static Math::real Resolution(int prec)
Definition Georef.hpp:113
GeographicLib::Georef::Reverse
static void Reverse(const std::string &georef, real &lat, real &lon, int &prec, bool centerp=true)
Definition Georef.cpp:64
GeographicLib::Math::qd
static constexpr int qd
degrees per quarter turn
Definition Math.hpp:142
GeographicLib::Math::hd
static constexpr int hd
degrees per half turn
Definition Math.hpp:145
GeographicLib::Math::real
double real
Definition Math.hpp:115
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12