GeographicLib 2.7

Loading...
Searching...
No Matches
GARS.hpp
Go to the documentation of this file.
1/**
2 * \file GARS.hpp
3 * \brief Header for GeographicLib::GARS 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_GARS_HPP)
11#define GEOGRAPHICLIB_GARS_HPP 1
12
13#include <GeographicLib/Constants.hpp>
14
15 namespace GeographicLib {
16
17 /**
18 * \brief Conversions for the Global Area Reference System (GARS)
19 *
20 * The Global Area Reference System is described in
21 * - https://en.wikipedia.org/wiki/Global_Area_Reference_System
22 * - https://earth-info.nga.mil/index.php?dir=coordsys&action=coordsys#tab_gars
23 * .
24 * It provides a compact string representation of a geographic area
25 * (expressed as latitude and longitude). The classes Georef and Geohash
26 * implement similar compact representations.
27 *
28 * Example of use:
29 * \include example-GARS.cpp
30 **********************************************************************/
31
32 class GEOGRAPHICLIB_EXPORT GARS {
33 private:
34 typedef Math::real real;
35 static const char* const digits_;
36 static const char* const letters_;
37 static constexpr int lonorig_ = -Math::hd; // Origin for longitude
38 static constexpr int latorig_ = -Math::qd; // Origin for latitude
39 static constexpr int baselon_ = 10; // Base for longitude tiles
40 static constexpr int baselat_ = 24; // Base for latitude tiles
41 static constexpr int lonlen_ = 3;
42 static constexpr int latlen_ = 2;
43 static constexpr int baselen_ = lonlen_ + latlen_;
44 static constexpr int mult1_ = 2; // base precision = 1/2 degree
45 static constexpr int mult2_ = 2; // 6th char gives 2x more precision
46 static constexpr int mult3_ = 3; // 7th char gives 3x more precision
47 static constexpr int m_ = mult1_ * mult2_ * mult3_;
48 static constexpr int maxprec_ = 2;
49 static constexpr int maxlen_ = baselen_ + maxprec_;
50 GARS() = delete; // Disable constructor
51
52 public:
53
54 /**
55 * Convert from geographic coordinates to GARS.
56 *
57 * @param[in] lat latitude of point (degrees).
58 * @param[in] lon longitude of point (degrees).
59 * @param[in] prec the precision of the resulting GARS.
60 * @param[out] gars the GARS string.
61 * @exception GeographicErr if \e lat is not in [&minus;90&deg;,
62 * 90&deg;].
63 * @exception std::bad_alloc if memory for \e gars can't be allocated.
64 *
65 * \e prec specifies the precision of \e gars as follows:
66 * - \e prec = 0 (min), 30' precision, e.g., 006AG;
67 * - \e prec = 1, 15' precision, e.g., 006AG3;
68 * - \e prec = 2 (max), 5' precision, e.g., 006AG39.
69 *
70 * If \e lat or \e lon is NaN, then \e gars is set to "INVALID".
71 **********************************************************************/
72 static void Forward(real lat, real lon, int prec, std::string& gars);
73
74 /**
75 * Convert from GARS to geographic coordinates.
76 *
77 * @param[in] gars the GARS.
78 * @param[out] lat latitude of point (degrees).
79 * @param[out] lon longitude of point (degrees).
80 * @param[out] prec the precision of \e gars.
81 * @param[in] centerp if true (the default) return the center of the
82 * \e gars, otherwise return the south-west corner.
83 * @exception GeographicErr if \e gars is illegal.
84 *
85 * The case of the letters in \e gars is ignored. \e prec is in the range
86 * [0, 2] and gives the precision of \e gars as follows:
87 * - \e prec = 0 (min), 30' precision, e.g., 006AG;
88 * - \e prec = 1, 15' precision, e.g., 006AG3;
89 * - \e prec = 2 (max), 5' precision, e.g., 006AG39.
90 *
91 * If the first 3 characters of \e gars are "INV", then \e lat and \e lon
92 * are set to NaN and \e prec is unchanged.
93 **********************************************************************/
94 static void Reverse(const std::string& gars, real& lat, real& lon,
95 int& prec, bool centerp = true);
96
97 /**
98 * The angular resolution of a GARS.
99 *
100 * @param[in] prec the precision of the GARS.
101 * @return the latitude-longitude resolution (degrees).
102 *
103 * Internally, \e prec is first put in the range [0, 2].
104 **********************************************************************/
105 static Math::real Resolution(int prec) {
106 return 1/real(prec <= 0 ? mult1_ : (prec == 1 ? mult1_ * mult2_ :
107 mult1_ * mult2_ * mult3_));
108 }
109
110 /**
111 * The GARS precision required to meet a given geographic resolution.
112 *
113 * @param[in] res the minimum of resolution in latitude and longitude
114 * (degrees).
115 * @return GARS precision.
116 *
117 * The returned length is in the range [0, 2].
118 **********************************************************************/
119 static int Precision(real res) {
120 using std::fabs; res = fabs(res);
121 for (int prec = 0; prec < maxprec_; ++prec)
122 if (Resolution(prec) <= res)
123 return prec;
124 return maxprec_;
125 }
126
127 };
128
129} // namespace GeographicLib
130
131#endif // GEOGRAPHICLIB_GARS_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::GARS::Reverse
static void Reverse(const std::string &gars, real &lat, real &lon, int &prec, bool centerp=true)
Definition GARS.cpp:59
GeographicLib::GARS::Resolution
static Math::real Resolution(int prec)
Definition GARS.hpp:105
GeographicLib::GARS::Precision
static int Precision(real res)
Definition GARS.hpp:119
GeographicLib::GARS::Forward
static void Forward(real lat, real lon, int prec, std::string &gars)
Definition GARS.cpp:20
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