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