GeographicLib 2.3

OSGB.hpp
Go to the documentation of this file.
1/**
2 * \file OSGB.hpp
3 * \brief Header for GeographicLib::OSGB class
4 *
5 * Copyright (c) Charles Karney (2010-2023) <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_OSGB_HPP)
11#define GEOGRAPHICLIB_OSGB_HPP 1
12
13#include <GeographicLib/Constants.hpp>
14#include <GeographicLib/TransverseMercator.hpp>
15
16#if defined(_MSC_VER)
17// Squelch warnings about dll vs string
18# pragma warning (push)
19# pragma warning (disable: 4251)
20#endif
21
22 namespace GeographicLib {
23
24 /**
25 * \brief Ordnance Survey grid system for Great Britain
26 *
27 * The class implements the coordinate system used by the Ordnance Survey for
28 * maps of Great Britain and conversions to the grid reference system.
29 *
30 * See
31 * - <a href="https://www.ordnancesurvey.co.uk/documents/resources/guide-coordinate-systems-great-britain.pdf">
32 * A guide to coordinate systems in Great Britain</a>
33 * - <a href="https://www.ordnancesurvey.co.uk/documents/resources/guide-to-nationalgrid.pdf">
34 * Using the National Grid</a>
35 *
36 * \warning the latitudes and longitudes for the Ordnance Survey grid
37 * system do not use the WGS84 datum. Do not use the values returned by this
38 * class in the UTMUPS, MGRS, or Geoid classes without first converting the
39 * datum (and vice versa).
40 *
41 * Example of use:
42 * \include example-OSGB.cpp
43 **********************************************************************/
44 class GEOGRAPHICLIB_EXPORT OSGB {
45 private:
46 typedef Math::real real;
47 static const char* const letters_;
48 static const char* const digits_;
49 static const TransverseMercator& OSGBTM();
50 enum {
51 base_ = 10,
52 tile_ = 100000,
53 tilelevel_ = 5,
54 tilegrid_ = 5,
55 tileoffx_ = 2 * tilegrid_,
56 tileoffy_ = 1 * tilegrid_,
57 minx_ = - tileoffx_ * tile_,
58 miny_ = - tileoffy_ * tile_,
59 maxx_ = (tilegrid_*tilegrid_ - tileoffx_) * tile_,
60 maxy_ = (tilegrid_*tilegrid_ - tileoffy_) * tile_,
61 // Maximum precision is um
62 maxprec_ = 5 + 6
63 };
64 static real computenorthoffset();
65 static void CheckCoords(real x, real y);
66 OSGB() = delete; // Disable constructor
67 public:
68
69 /**
70 * Forward projection, from geographic to OSGB coordinates.
71 *
72 * @param[in] lat latitude of point (degrees).
73 * @param[in] lon longitude of point (degrees).
74 * @param[out] x easting of point (meters).
75 * @param[out] y northing of point (meters).
76 * @param[out] gamma meridian convergence at point (degrees).
77 * @param[out] k scale of projection at point.
78 *
79 * \e lat should be in the range [&minus;90&deg;, 90&deg;].
80 **********************************************************************/
81 static void Forward(real lat, real lon,
82 real& x, real& y, real& gamma, real& k) {
83 OSGBTM().Forward(OriginLongitude(), lat, lon, x, y, gamma, k);
84 x += FalseEasting();
85 y += computenorthoffset();
86 }
87
88 /**
89 * Reverse projection, from OSGB coordinates to geographic.
90 *
91 * @param[in] x easting of point (meters).
92 * @param[in] y northing of point (meters).
93 * @param[out] lat latitude of point (degrees).
94 * @param[out] lon longitude of point (degrees).
95 * @param[out] gamma meridian convergence at point (degrees).
96 * @param[out] k scale of projection at point.
97 *
98 * The value of \e lon returned is in the range [&minus;180&deg;,
99 * 180&deg;].
100 **********************************************************************/
101
102 static void Reverse(real x, real y,
103 real& lat, real& lon, real& gamma, real& k) {
104 x -= FalseEasting();
105 y -= computenorthoffset();
106 OSGBTM().Reverse(OriginLongitude(), x, y, lat, lon, gamma, k);
107 }
108
109 /**
110 * OSGB::Forward without returning the convergence and scale.
111 **********************************************************************/
112 static void Forward(real lat, real lon, real& x, real& y) {
113 real gamma, k;
114 Forward(lat, lon, x, y, gamma, k);
115 }
116
117 /**
118 * OSGB::Reverse without returning the convergence and scale.
119 **********************************************************************/
120 static void Reverse(real x, real y, real& lat, real& lon) {
121 real gamma, k;
122 Reverse(x, y, lat, lon, gamma, k);
123 }
124
125 /**
126 * Convert OSGB coordinates to a grid reference.
127 *
128 * @param[in] x easting of point (meters).
129 * @param[in] y northing of point (meters).
130 * @param[in] prec precision relative to 100 km.
131 * @param[out] gridref National Grid reference.
132 * @exception GeographicErr if \e prec, \e x, or \e y is outside its
133 * allowed range.
134 * @exception std::bad_alloc if the memory for \e gridref can't be
135 * allocatied.
136 *
137 * \e prec specifies the precision of the grid reference string as follows:
138 * - prec = 0 (min), 100km
139 * - prec = 1, 10km
140 * - prec = 2, 1km
141 * - prec = 3, 100m
142 * - prec = 4, 10m
143 * - prec = 5, 1m
144 * - prec = 6, 0.1m
145 * - prec = 11 (max), 1&mu;m
146 *
147 * The easting must be in the range [&minus;1000 km, 1500 km) and the
148 * northing must be in the range [&minus;500 km, 2000 km). These bounds
149 * are consistent with rules for the letter designations for the grid
150 * system.
151 *
152 * If \e x or \e y is NaN, the returned grid reference is "INVALID".
153 **********************************************************************/
154 static void GridReference(real x, real y, int prec, std::string& gridref);
155
156 /**
157 * Convert OSGB grid reference to coordinates.
158 *
159 * @param[in] gridref National Grid reference.
160 * @param[out] x easting of point (meters).
161 * @param[out] y northing of point (meters).
162 * @param[out] prec precision relative to 100 km.
163 * @param[in] centerp if true (default), return center of the grid square,
164 * else return SW (lower left) corner.
165 * @exception GeographicErr if \e gridref is illegal.
166 *
167 * The grid reference must be of the form: two letters (not including I)
168 * followed by an even number of digits (up to 22).
169 *
170 * If the first 2 characters of \e gridref are "IN", then \e x and \e y are
171 * set to NaN and \e prec is set to &minus;2.
172 **********************************************************************/
173 static void GridReference(const std::string& gridref,
174 real& x, real& y, int& prec,
175 bool centerp = true);
176
177 /** \name Inspector functions
178 **********************************************************************/
179 ///@{
180 /**
181 * @return \e a the equatorial radius of the Airy 1830 ellipsoid (meters).
182 *
183 * This is 20923713 ft converted to meters using the rule 1 ft =
184 * 10<sup>9.48401603&minus;10</sup> m. The Airy 1830 value is returned
185 * because the OSGB projection is based on this ellipsoid. The conversion
186 * factor from feet to meters is the one used for the 1936 retriangulation
187 * of Britain; see Section A.1 (footnote 10 on p. 44) of <i>A guide to
188 * coordinate systems in Great Britain</i>, v3.6 (2020).
189 **********************************************************************/
190 static Math::real EquatorialRadius() {
191 // result is about 6377563.3960320664406 m
192 using std::pow;
193 return pow(real(10), real(48401603 - 100000000) / 100000000)
194 * real(20923713);
195 }
196
197 /**
198 * @return \e f the inverse flattening of the Airy 1830 ellipsoid.
199 *
200 * For the Airy 1830 ellipsoid, \e a = 20923713 ft and \e b = 20853810 ft;
201 * thus the flattening = (20923713 &minus; 20853810)/20923713 =
202 * 7767/2324857 = 1/299.32496459... (The Airy 1830 value is returned
203 * because the OSGB projection is based on this ellipsoid.)
204 **********************************************************************/
205 static Math::real Flattening()
206 { return real(20923713 - 20853810) / real(20923713); }
207
208 /**
209 * @return \e k0 central scale for the OSGB projection (0.9996012717...).
210 *
211 * C. J. Mugnier, Grids &amp; Datums, PE&amp;RS, Oct. 2003, states that
212 * this is defined as 10<sup>9.9998268&minus;10</sup>.
213 **********************************************************************/
214 static Math::real CentralScale() {
215 using std::pow;
216 return pow(real(10), real(9998268 - 10000000) / 10000000);
217 }
218
219 /**
220 * @return latitude of the origin for the OSGB projection (49 degrees).
221 **********************************************************************/
222 static Math::real OriginLatitude() { return real(49); }
223
224 /**
225 * @return longitude of the origin for the OSGB projection (&minus;2
226 * degrees).
227 **********************************************************************/
228 static Math::real OriginLongitude() { return real(-2); }
229
230 /**
231 * @return false northing the OSGB projection (&minus;100000 meters).
232 **********************************************************************/
233 static Math::real FalseNorthing() { return real(-100000); }
234
235 /**
236 * @return false easting the OSGB projection (400000 meters).
237 **********************************************************************/
238 static Math::real FalseEasting() { return real(400000); }
239 ///@}
240
241 };
242
243} // namespace GeographicLib
244
245#if defined(_MSC_VER)
246# pragma warning (pop)
247#endif
248
249#endif // GEOGRAPHICLIB_OSGB_HPP
Constants.hpp
Header for GeographicLib::Constants class.
GEOGRAPHICLIB_EXPORT
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:67
real
GeographicLib::Math::real real
Definition: GeodSolve.cpp:29
TransverseMercator.hpp
Header for GeographicLib::TransverseMercator class.
GeographicLib::Math::real
double real
Definition: Math.hpp:100
GeographicLib::OSGB
Ordnance Survey grid system for Great Britain.
Definition: OSGB.hpp:44
GeographicLib::OSGB::Forward
static void Forward(real lat, real lon, real &x, real &y)
Definition: OSGB.hpp:112
GeographicLib::OSGB::OriginLongitude
static Math::real OriginLongitude()
Definition: OSGB.hpp:228
GeographicLib::OSGB::CentralScale
static Math::real CentralScale()
Definition: OSGB.hpp:214
GeographicLib::OSGB::EquatorialRadius
static Math::real EquatorialRadius()
Definition: OSGB.hpp:190
GeographicLib::OSGB::FalseNorthing
static Math::real FalseNorthing()
Definition: OSGB.hpp:233
GeographicLib::OSGB::Forward
static void Forward(real lat, real lon, real &x, real &y, real &gamma, real &k)
Definition: OSGB.hpp:81
GeographicLib::OSGB::Flattening
static Math::real Flattening()
Definition: OSGB.hpp:205
GeographicLib::OSGB::FalseEasting
static Math::real FalseEasting()
Definition: OSGB.hpp:238
GeographicLib::OSGB::Reverse
static void Reverse(real x, real y, real &lat, real &lon)
Definition: OSGB.hpp:120
GeographicLib::OSGB::OriginLatitude
static Math::real OriginLatitude()
Definition: OSGB.hpp:222
GeographicLib::OSGB::Reverse
static void Reverse(real x, real y, real &lat, real &lon, real &gamma, real &k)
Definition: OSGB.hpp:102
GeographicLib::TransverseMercator
Transverse Mercator projection.
Definition: TransverseMercator.hpp:94
GeographicLib::TransverseMercator::Reverse
void Reverse(real lon0, real x, real y, real &lat, real &lon, real &gamma, real &k) const
Definition: TransverseMercator.cpp:528
GeographicLib::TransverseMercator::Forward
void Forward(real lon0, real lat, real lon, real &x, real &y, real &gamma, real &k) const
Definition: TransverseMercator.cpp:360
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12