GeographicLib  1.35
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-2011) <charles@karney.com> and licensed
6  * under the MIT/X11 License. For more information, see
7  * http://geographiclib.sourceforge.net/
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="http://www.ordnancesurvey.co.uk/docs/support/guide-coordinate-systems-great-britain.pdf">
32  * A guide to coordinate systems in Great Britain</a>
33  * - <a href="http://www.ordnancesurvey.co.uk/docs/support/national-grid.pdf">
34  * Guide to the National Grid</a>
35  *
36  * \b 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 std::string letters_;
48  static const std::string digits_;
49  static const TransverseMercator OSGBTM_;
50  static real northoffset_;
51  static bool init_;
52  enum {
53  base_ = 10,
54  tile_ = 100000,
55  tilelevel_ = 5,
56  tilegrid_ = 5,
57  tileoffx_ = 2 * tilegrid_,
58  tileoffy_ = 1 * tilegrid_,
59  minx_ = - tileoffx_ * tile_,
60  miny_ = - tileoffy_ * tile_,
61  maxx_ = (tilegrid_*tilegrid_ - tileoffx_) * tile_,
62  maxy_ = (tilegrid_*tilegrid_ - tileoffy_) * tile_,
63  // Maximum precision is um
64  maxprec_ = 5 + 6,
65  };
66  static real computenorthoffset() throw();
67  static void CheckCoords(real x, real y);
68  OSGB(); // Disable constructor
69  public:
70 
71  /**
72  * Forward projection, from geographic to OSGB coordinates.
73  *
74  * @param[in] lat latitude of point (degrees).
75  * @param[in] lon longitude of point (degrees).
76  * @param[out] x easting of point (meters).
77  * @param[out] y northing of point (meters).
78  * @param[out] gamma meridian convergence at point (degrees).
79  * @param[out] k scale of projection at point.
80  *
81  * \e lat should be in the range [&minus;90&deg;, 90&deg;]; \e lon
82  * should be in the range [&minus;540&deg;, 540&deg;).
83  **********************************************************************/
84  static void Forward(real lat, real lon,
85  real& x, real& y, real& gamma, real& k) throw() {
86  OSGBTM_.Forward(OriginLongitude(), lat, lon, x, y, gamma, k);
87  x += FalseEasting();
88  y += computenorthoffset();
89  }
90 
91  /**
92  * Reverse projection, from OSGB coordinates to geographic.
93  *
94  * @param[in] x easting of point (meters).
95  * @param[in] y northing of point (meters).
96  * @param[out] lat latitude of point (degrees).
97  * @param[out] lon longitude of point (degrees).
98  * @param[out] gamma meridian convergence at point (degrees).
99  * @param[out] k scale of projection at point.
100  *
101  * The value of \e lon returned is in the range [&minus;180&deg;,
102  * 180&deg;).
103  **********************************************************************/
104 
105  static void Reverse(real x, real y,
106  real& lat, real& lon, real& gamma, real& k) throw() {
107  x -= FalseEasting();
108  y -= computenorthoffset();
109  OSGBTM_.Reverse(OriginLongitude(), x, y, lat, lon, gamma, k);
110  }
111 
112  /**
113  * OSGB::Forward without returning the convergence and scale.
114  **********************************************************************/
115  static void Forward(real lat, real lon, real& x, real& y) throw() {
116  real gamma, k;
117  Forward(lat, lon, x, y, gamma, k);
118  }
119 
120  /**
121  * OSGB::Reverse without returning the convergence and scale.
122  **********************************************************************/
123  static void Reverse(real x, real y, real& lat, real& lon) throw() {
124  real gamma, k;
125  Reverse(x, y, lat, lon, gamma, k);
126  }
127 
128  /**
129  * Convert OSGB coordinates to a grid reference.
130  *
131  * @param[in] x easting of point (meters).
132  * @param[in] y northing of point (meters).
133  * @param[in] prec precision relative to 100 km.
134  * @param[out] gridref National Grid reference.
135  * @exception GeographicErr if \e prec, \e x, or \e y is outside its
136  * allowed range.
137  * @exception std::bad_alloc if the memory for \e gridref can't be
138  * allocatied.
139  *
140  * \e prec specifies the precision of the grid reference string as follows:
141  * - prec = 0 (min), 100km
142  * - prec = 1, 10km
143  * - prec = 2, 1km
144  * - prec = 3, 100m
145  * - prec = 4, 10m
146  * - prec = 5, 1m
147  * - prec = 6, 0.1m
148  * - prec = 11 (max), 1&mu;m
149  *
150  * The easting must be in the range [&minus;1000 km, 1500 km) and the
151  * northing must be in the range [&minus;500 km, 2000 km). These bounds
152  * are consistent with rules for the letter designations for the grid
153  * system.
154  **********************************************************************/
155  static void GridReference(real x, real y, int prec, std::string& gridref);
156 
157  /**
158  * Convert OSGB coordinates to a grid reference.
159  *
160  * @param[in] gridref National Grid reference.
161  * @param[out] x easting of point (meters).
162  * @param[out] y northing of point (meters).
163  * @param[out] prec precision relative to 100 km.
164  * @param[in] centerp if true (default), return center of the grid square,
165  * else return SW (lower left) corner.
166  * @exception GeographicErr if \e gridref is illegal.
167  *
168  * The grid reference must be of the form: two letters (not including I)
169  * followed by an even number of digits (up to 22).
170  **********************************************************************/
171  static void GridReference(const std::string& gridref,
172  real& x, real& y, int& prec,
173  bool centerp = true);
174 
175  /** \name Inspector functions
176  **********************************************************************/
177  ///@{
178  /**
179  * @return \e a the equatorial radius of the Airy 1830 ellipsoid (meters).
180  *
181  * This is 20923713 ft converted to meters using the rule 1 ft =
182  * 10<sup>9.48401603&minus;10</sup> m. (The Airy 1830 value is returned
183  * because the OSGB projection is based on this ellipsoid.)
184  **********************************************************************/
185  static Math::real MajorRadius() throw()
186  // result is about 6377563.3960320664406 m
187  { return real(20923713) * std::pow(real(10), real(0.48401603L) - 1); }
188 
189  /**
190  * @return \e f the inverse flattening of the Airy 1830 ellipsoid.
191  *
192  * For the Airy 1830 ellipsoid, \e a = 20923713 ft and \e b = 20853810 ft;
193  * thus the flattening = (20923713 &minus; 20853810)/20923713 =
194  * 7767/2324857 = 1/299.32496459... (The Airy 1830 value is returned
195  * because the OSGB projection is based on this ellipsoid.)
196  **********************************************************************/
197  static Math::real Flattening() throw()
198  { return real(20923713 - 20853810) / real(20923713); }
199 
200  /// \cond SKIP
201  /**
202  * <b>DEPRECATED</b>
203  * @return \e r the inverse flattening of the Airy 1830 ellipsoid.
204  **********************************************************************/
205  static Math::real InverseFlattening() throw() { return 1/Flattening(); }
206  /// \endcond
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() throw()
215  { return std::pow(real(10), real(9998268 - 10000000) / real(10000000)); }
216 
217  /**
218  * @return latitude of the origin for the OSGB projection (49 degrees).
219  **********************************************************************/
220  static Math::real OriginLatitude() throw() { return real(49); }
221 
222  /**
223  * @return longitude of the origin for the OSGB projection (&minus;2
224  * degrees).
225  **********************************************************************/
226  static Math::real OriginLongitude() throw() { return real(-2); }
227 
228  /**
229  * @return false northing the OSGB projection (&minus;100000 meters).
230  **********************************************************************/
231  static Math::real FalseNorthing() throw() { return real(-100000); }
232 
233  /**
234  * @return false easting the OSGB projection (400000 meters).
235  **********************************************************************/
236  static Math::real FalseEasting() throw() { return real(400000); }
237  ///@}
238 
239  };
240 
241 } // namespace GeographicLib
242 
243 #if defined(_MSC_VER)
244 # pragma warning (pop)
245 #endif
246 
247 #endif // GEOGRAPHICLIB_OSGB_HPP
static void Forward(real lat, real lon, real &x, real &y, real &gamma, real &k)
Definition: OSGB.hpp:84
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:52
GeographicLib::Math::real real
Definition: GeodSolve.cpp:40
static Math::real Flattening()
Definition: OSGB.hpp:197
static Math::real FalseEasting()
Definition: OSGB.hpp:236
static Math::real OriginLatitude()
Definition: OSGB.hpp:220
Transverse Mercator projection.
Header for GeographicLib::TransverseMercator class.
static Math::real CentralScale()
Definition: OSGB.hpp:214
static Math::real FalseNorthing()
Definition: OSGB.hpp:231
static Math::real OriginLongitude()
Definition: OSGB.hpp:226
static Math::real MajorRadius()
Definition: OSGB.hpp:185
static void Reverse(real x, real y, real &lat, real &lon, real &gamma, real &k)
Definition: OSGB.hpp:105
Ordnance Survey grid system for Great Britain.
Definition: OSGB.hpp:44
Header for GeographicLib::Constants class.
static void Forward(real lat, real lon, real &x, real &y)
Definition: OSGB.hpp:115
static void Reverse(real x, real y, real &lat, real &lon)
Definition: OSGB.hpp:123