GeographicLib: Geoid.hpp Source File

GeographicLib 2.5.2

Loading...
Searching...
No Matches
Geoid.hpp
Go to the documentation of this file.
1/**
2 * \file Geoid.hpp
3 * \brief Header for GeographicLib::Geoid class
4 *
5 * Copyright (c) Charles Karney (2009-2022) <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_GEOID_HPP)
11#define GEOGRAPHICLIB_GEOID_HPP 1
12
13#include <vector>
14#include <fstream>
15#include <GeographicLib/Constants.hpp>
16
17#if defined(_MSC_VER)
18// Squelch warnings about dll vs vector and constant conditional expressions
19# pragma warning (push)
20# pragma warning (disable: 4251 4127)
21#endif
22
23#if !defined(GEOGRAPHICLIB_GEOID_PGM_PIXEL_WIDTH)
24/**
25 * The size of the pixel data in the pgm data files for the geoids. 2 is the
26 * standard size corresponding to a maxval 2<sup>16</sup>&minus;1. Setting it
27 * to 4 uses a maxval of 2<sup>32</sup>&minus;1 and changes the extension for
28 * the data files from .pgm to .pgm4. Note that the format of these pgm4 files
29 * is a non-standard extension of the pgm format.
30 **********************************************************************/
31# define GEOGRAPHICLIB_GEOID_PGM_PIXEL_WIDTH 2
32#endif
33
34namespace GeographicLib {
35
36 /**
37 * \brief Looking up the height of the geoid above the ellipsoid
38 *
39 * This class evaluates the height of one of the standard geoids, EGM84,
40 * EGM96, or EGM2008 by bilinear or cubic interpolation into a rectangular
41 * grid of data. These geoid models are documented in
42 * - EGM84:
43 * https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm84
44 * - EGM96:
45 * https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96
46 * - EGM2008:
47 * https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008
48 *
49 * The geoids are defined in terms of spherical harmonics. However in order
50 * to provide a quick and flexible method of evaluating the geoid heights,
51 * this class evaluates the height by interpolation into a grid of
52 * precomputed values.
53 *
54 * The height of the geoid above the ellipsoid, \e N, is sometimes called the
55 * geoid undulation. It can be used to convert a height above the ellipsoid,
56 * \e h, to the corresponding height above the geoid (the orthometric height,
57 * roughly the height above mean sea level), \e H, using the relations
58 *
59 * &nbsp;&nbsp;&nbsp;\e h = \e N + \e H;
60 * &nbsp;&nbsp;\e H = &minus;\e N + \e h.
61 *
62 * See \ref geoid for details of how to install the data sets, the data
63 * format, estimates of the interpolation errors, and how to use caching.
64 *
65 * This class is typically \e not thread safe in that a single instantiation
66 * cannot be safely used by multiple threads because of the way the object
67 * reads the data set and because it maintains a single-cell cache. If
68 * multiple threads need to calculate geoid heights they should all construct
69 * thread-local instantiations. Alternatively, set the optional \e
70 * threadsafe parameter to true in the constructor. This causes the
71 * constructor to read all the data into memory and to turn off the
72 * single-cell caching which results in a Geoid object which \e is thread
73 * safe.
74 *
75 * Example of use:
76 * \include example-Geoid.cpp
77 *
78 * <a href="GeoidEval.1.html">GeoidEval</a> is a command-line utility
79 * providing access to the functionality of Geoid.
80 **********************************************************************/
81
82 class GEOGRAPHICLIB_EXPORT Geoid {
83 private:
84 typedef Math::real real;
85#if GEOGRAPHICLIB_GEOID_PGM_PIXEL_WIDTH != 4
86 typedef unsigned short pixel_t;
87 static const unsigned pixel_size_ = 2;
88 static const unsigned pixel_max_ = 0xffffu;
89#else
90 typedef unsigned pixel_t;
91 static const unsigned pixel_size_ = 4;
92 static const unsigned pixel_max_ = 0xffffffffu;
93#endif
94 static const unsigned stencilsize_ = 12;
95 static const unsigned nterms_ = ((3 + 1) * (3 + 2))/2; // for a cubic fit
96 static const int c0_;
97 static const int c0n_;
98 static const int c0s_;
99 static const int c3_[stencilsize_ * nterms_];
100 static const int c3n_[stencilsize_ * nterms_];
101 static const int c3s_[stencilsize_ * nterms_];
102
103 std::string _name, _dir, _filename;
104 const bool _cubic;
105 const real _a, _e2, _degree, _eps;
106 mutable std::ifstream _file;
107 real _rlonres, _rlatres;
108 std::string _description, _datetime;
109 real _offset, _scale, _maxerror, _rmserror;
110 int _width, _height;
111 unsigned long long _datastart, _swidth;
112 bool _threadsafe;
113 // Area cache
114 mutable std::vector< std::vector<pixel_t> > _data;
115 mutable bool _cache;
116 // NE corner and extent of cache
117 mutable int _xoffset, _yoffset, _xsize, _ysize;
118 // Cell cache
119 mutable int _ix, _iy;
120 mutable real _v00, _v01, _v10, _v11;
121 mutable real _t[nterms_];
122 void filepos(int ix, int iy) const {
123 _file.seekg(std::streamoff
124 (_datastart +
125 pixel_size_ * (unsigned(iy)*_swidth + unsigned(ix))));
126 }
127 real rawval(int ix, int iy) const {
128 if (ix < 0)
129 ix += _width;
130 else if (ix >= _width)
131 ix -= _width;
132 if (_cache && iy >= _yoffset && iy < _yoffset + _ysize &&
133 ((ix >= _xoffset && ix < _xoffset + _xsize) ||
134 (ix + _width >= _xoffset && ix + _width < _xoffset + _xsize))) {
135 return real(_data[iy - _yoffset]
136 [ix >= _xoffset ? ix - _xoffset : ix + _width - _xoffset]);
137 } else {
138 if (iy < 0 || iy >= _height) {
139 iy = iy < 0 ? -iy : 2 * (_height - 1) - iy;
140 ix += (ix < _width/2 ? 1 : -1) * _width/2;
141 }
142 try {
143 filepos(ix, iy);
144 // initial values to suppress warnings in case get fails
145 char a = 0, b = 0;
146 _file.get(a);
147 _file.get(b);
148 unsigned r = ((unsigned char)(a) << 8) | (unsigned char)(b);
149 // for C++17 use if constexpr
150 if (pixel_size_ == 4) {
151 _file.get(a);
152 _file.get(b);
153 r = (r << 16) | ((unsigned char)(a) << 8) | (unsigned char)(b);
154 }
155 return real(r);
156 }
157 catch (const std::exception& e) {
158 // throw GeographicErr("Error reading " + _filename + ": "
159 // + e.what());
160 // triggers complaints about the "binary '+'" under Visual Studio.
161 // So use '+=' instead.
162 std::string err("Error reading ");
163 err += _filename;
164 err += ": ";
165 err += e.what();
166 throw GeographicErr(err);
167 }
168 }
169 }
170 real height(real lat, real lon) const;
171 Geoid(const Geoid&) = delete; // copy constructor not allowed
172 Geoid& operator=(const Geoid&) = delete; // copy assignment not allowed
173 public:
174
175 /**
176 * Flags indicating conversions between heights above the geoid and heights
177 * above the ellipsoid.
178 **********************************************************************/
179 enum convertflag {
180 /**
181 * The multiplier for converting from heights above the ellipsoid to
182 * heights above the geoid.
183 **********************************************************************/
184 ELLIPSOIDTOGEOID = -1,
185 /**
186 * No conversion.
187 **********************************************************************/
188 NONE = 0,
189 /**
190 * The multiplier for converting from heights above the geoid to heights
191 * above the ellipsoid.
192 **********************************************************************/
193 GEOIDTOELLIPSOID = 1,
194 };
195
196 /** \name Setting up the geoid
197 **********************************************************************/
198 ///@{
199 /**
200 * Construct a geoid.
201 *
202 * @param[in] name the name of the geoid.
203 * @param[in] path (optional) directory for data file.
204 * @param[in] cubic (optional) interpolation method; false means bilinear,
205 * true (the default) means cubic.
206 * @param[in] threadsafe (optional), if true, construct a thread safe
207 * object. The default is false
208 * @exception GeographicErr if the data file cannot be found, is
209 * unreadable, or is corrupt.
210 * @exception GeographicErr if \e threadsafe is true but the memory
211 * necessary for caching the data can't be allocated.
212 *
213 * The data file is formed by appending ".pgm" to the name. If \e path is
214 * specified (and is non-empty), then the file is loaded from directory, \e
215 * path. Otherwise the path is given by DefaultGeoidPath(). If the \e
216 * threadsafe parameter is true, the data set is read into memory, the data
217 * file is closed, and single-cell caching is turned off; this results in a
218 * Geoid object which \e is thread safe.
219 **********************************************************************/
220 explicit Geoid(const std::string& name, const std::string& path = "",
221 bool cubic = true, bool threadsafe = false);
222
223 /**
224 * Set up a cache.
225 *
226 * @param[in] south latitude (degrees) of the south edge of the cached
227 * area.
228 * @param[in] west longitude (degrees) of the west edge of the cached area.
229 * @param[in] north latitude (degrees) of the north edge of the cached
230 * area.
231 * @param[in] east longitude (degrees) of the east edge of the cached area.
232 * @exception GeographicErr if the memory necessary for caching the data
233 * can't be allocated (in this case, you will have no cache and can try
234 * again with a smaller area).
235 * @exception GeographicErr if there's a problem reading the data.
236 * @exception GeographicErr if this is called on a threadsafe Geoid.
237 *
238 * Cache the data for the specified "rectangular" area bounded by the
239 * parallels \e south and \e north and the meridians \e west and \e east.
240 * \e east is always interpreted as being east of \e west, if necessary by
241 * adding 360&deg; to its value. \e south and \e north should be in
242 * the range [&minus;90&deg;, 90&deg;].
243 **********************************************************************/
244 void CacheArea(real south, real west, real north, real east) const;
245
246 /**
247 * Cache all the data.
248 *
249 * @exception GeographicErr if the memory necessary for caching the data
250 * can't be allocated (in this case, you will have no cache and can try
251 * again with a smaller area).
252 * @exception GeographicErr if there's a problem reading the data.
253 * @exception GeographicErr if this is called on a threadsafe Geoid.
254 *
255 * On most computers, this is fast for data sets with grid resolution of 5'
256 * or coarser. For a 1' grid, the required RAM is 450MB; a 2.5' grid needs
257 * 72MB; and a 5' grid needs 18MB.
258 **********************************************************************/
259 void CacheAll() const { CacheArea(real(-Math::qd), real(0),
260 real( Math::qd), real(Math::td)); }
261
262 /**
263 * Clear the cache. This never throws an error. (This does nothing with a
264 * thread safe Geoid.)
265 **********************************************************************/
266 void CacheClear() const;
267
268 ///@}
269
270 /** \name Compute geoid heights
271 **********************************************************************/
272 ///@{
273 /**
274 * Compute the geoid height at a point
275 *
276 * @param[in] lat latitude of the point (degrees).
277 * @param[in] lon longitude of the point (degrees).
278 * @exception GeographicErr if there's a problem reading the data; this
279 * never happens if (\e lat, \e lon) is within a successfully cached
280 * area.
281 * @return the height of the geoid above the ellipsoid (meters).
282 *
283 * The latitude should be in [&minus;90&deg;, 90&deg;].
284 **********************************************************************/
285 Math::real operator()(real lat, real lon) const {
286 return height(lat, lon);
287 }
288
289 /**
290 * Convert a height above the geoid to a height above the ellipsoid and
291 * vice versa.
292 *
293 * @param[in] lat latitude of the point (degrees).
294 * @param[in] lon longitude of the point (degrees).
295 * @param[in] h height of the point (degrees).
296 * @param[in] d a Geoid::convertflag specifying the direction of the
297 * conversion; Geoid::GEOIDTOELLIPSOID means convert a height above the
298 * geoid to a height above the ellipsoid; Geoid::ELLIPSOIDTOGEOID means
299 * convert a height above the ellipsoid to a height above the geoid.
300 * @exception GeographicErr if there's a problem reading the data; this
301 * never happens if (\e lat, \e lon) is within a successfully cached
302 * area.
303 * @return converted height (meters).
304 **********************************************************************/
305 Math::real ConvertHeight(real lat, real lon, real h,
306 convertflag d) const {
307 return h + real(d) * height(lat, lon);
308 }
309
310 ///@}
311
312 /** \name Inspector functions
313 **********************************************************************/
314 ///@{
315 /**
316 * @return geoid description, if available, in the data file; if
317 * absent, return "NONE".
318 **********************************************************************/
319 const std::string& Description() const { return _description; }
320
321 /**
322 * @return date of the data file; if absent, return "UNKNOWN".
323 **********************************************************************/
324 const std::string& DateTime() const { return _datetime; }
325
326 /**
327 * @return full file name used to load the geoid data.
328 **********************************************************************/
329 const std::string& GeoidFile() const { return _filename; }
330
331 /**
332 * @return "name" used to load the geoid data (from the first argument of
333 * the constructor).
334 **********************************************************************/
335 const std::string& GeoidName() const { return _name; }
336
337 /**
338 * @return directory used to load the geoid data.
339 **********************************************************************/
340 const std::string& GeoidDirectory() const { return _dir; }
341
342 /**
343 * @return interpolation method ("cubic" or "bilinear").
344 **********************************************************************/
345 const std::string Interpolation() const
346 { return std::string(_cubic ? "cubic" : "bilinear"); }
347
348 /**
349 * @return estimate of the maximum interpolation and quantization error
350 * (meters).
351 *
352 * This relies on the value being stored in the data file. If the value is
353 * absent, return &minus;1.
354 **********************************************************************/
355 Math::real MaxError() const { return _maxerror; }
356
357 /**
358 * @return estimate of the RMS interpolation and quantization error
359 * (meters).
360 *
361 * This relies on the value being stored in the data file. If the value is
362 * absent, return &minus;1.
363 **********************************************************************/
364 Math::real RMSError() const { return _rmserror; }
365
366 /**
367 * @return offset (meters).
368 *
369 * This in used in converting from the pixel values in the data file to
370 * geoid heights.
371 **********************************************************************/
372 Math::real Offset() const { return _offset; }
373
374 /**
375 * @return scale (meters).
376 *
377 * This in used in converting from the pixel values in the data file to
378 * geoid heights.
379 **********************************************************************/
380 Math::real Scale() const { return _scale; }
381
382 /**
383 * @return true if the object is constructed to be thread safe.
384 **********************************************************************/
385 bool ThreadSafe() const { return _threadsafe; }
386
387 /**
388 * @return true if a data cache is active.
389 **********************************************************************/
390 bool Cache() const { return _cache; }
391
392 /**
393 * @return west edge of the cached area; the cache includes this edge.
394 **********************************************************************/
395 Math::real CacheWest() const {
396 return _cache ? ((_xoffset + (_xsize == _width ? 0 : _cubic)
397 + _width/2) % _width - _width/2) / _rlonres :
398 0;
399 }
400
401 /**
402 * @return east edge of the cached area; the cache excludes this edge.
403 **********************************************************************/
404 Math::real CacheEast() const {
405 return _cache ?
406 CacheWest() +
407 (_xsize - (_xsize == _width ? 0 : 1 + 2 * _cubic)) / _rlonres :
408 0;
409 }
410
411 /**
412 * @return north edge of the cached area; the cache includes this edge.
413 **********************************************************************/
414 Math::real CacheNorth() const {
415 return _cache ? real(Math::qd) - (_yoffset + _cubic) / _rlatres : 0;
416 }
417
418 /**
419 * @return south edge of the cached area; the cache excludes this edge
420 * unless it's the south pole.
421 **********************************************************************/
422 Math::real CacheSouth() const {
423 return _cache ?
424 real(Math::qd) - ( _yoffset + _ysize - 1 - _cubic) / _rlatres :
425 0;
426 }
427
428 /**
429 * @return \e a the equatorial radius of the WGS84 ellipsoid (meters).
430 *
431 * (The WGS84 value is returned because the supported geoid models are all
432 * based on this ellipsoid.)
433 **********************************************************************/
434 Math::real EquatorialRadius() const
435 { return Constants::WGS84_a(); }
436
437 /**
438 * @return \e f the flattening of the WGS84 ellipsoid.
439 *
440 * (The WGS84 value is returned because the supported geoid models are all
441 * based on this ellipsoid.)
442 **********************************************************************/
443 Math::real Flattening() const { return Constants::WGS84_f(); }
444 ///@}
445
446 /**
447 * @return the default path for geoid data files.
448 *
449 * This is the value of the environment variable GEOGRAPHICLIB_GEOID_PATH,
450 * if set; otherwise, it is $GEOGRAPHICLIB_DATA/geoids if the environment
451 * variable GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time
452 * default (/usr/local/share/GeographicLib/geoids on non-Windows systems
453 * and C:/ProgramData/GeographicLib/geoids on Windows systems).
454 **********************************************************************/
455 static std::string DefaultGeoidPath();
456
457 /**
458 * @return the default name for the geoid.
459 *
460 * This is the value of the environment variable GEOGRAPHICLIB_GEOID_NAME,
461 * if set; otherwise, it is "egm96-5". The Geoid class does not use this
462 * function; it is just provided as a convenience for a calling program
463 * when constructing a Geoid object.
464 **********************************************************************/
465 static std::string DefaultGeoidName();
466
467 };
468
469} // namespace GeographicLib
470
471#if defined(_MSC_VER)
472# pragma warning (pop)
473#endif
474
475#endif // GEOGRAPHICLIB_GEOID_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:28
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition Constants.hpp:141
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition Constants.hpp:135
GeographicLib::GeographicErr
Exception handling for GeographicLib.
Definition Constants.hpp:316
GeographicLib::Geoid
Looking up the height of the geoid above the ellipsoid.
Definition Geoid.hpp:82
GeographicLib::Geoid::Scale
Math::real Scale() const
Definition Geoid.hpp:380
GeographicLib::Geoid::MaxError
Math::real MaxError() const
Definition Geoid.hpp:355
GeographicLib::Geoid::Description
const std::string & Description() const
Definition Geoid.hpp:319
GeographicLib::Geoid::CacheEast
Math::real CacheEast() const
Definition Geoid.hpp:404
GeographicLib::Geoid::GeoidDirectory
const std::string & GeoidDirectory() const
Definition Geoid.hpp:340
GeographicLib::Geoid::Cache
bool Cache() const
Definition Geoid.hpp:390
GeographicLib::Geoid::Flattening
Math::real Flattening() const
Definition Geoid.hpp:443
GeographicLib::Geoid::RMSError
Math::real RMSError() const
Definition Geoid.hpp:364
GeographicLib::Geoid::GeoidFile
const std::string & GeoidFile() const
Definition Geoid.hpp:329
GeographicLib::Geoid::convertflag
convertflag
Definition Geoid.hpp:179
GeographicLib::Geoid::ELLIPSOIDTOGEOID
@ ELLIPSOIDTOGEOID
Definition Geoid.hpp:184
GeographicLib::Geoid::NONE
@ NONE
Definition Geoid.hpp:188
GeographicLib::Geoid::GEOIDTOELLIPSOID
@ GEOIDTOELLIPSOID
Definition Geoid.hpp:193
GeographicLib::Geoid::CacheSouth
Math::real CacheSouth() const
Definition Geoid.hpp:422
GeographicLib::Geoid::CacheAll
void CacheAll() const
Definition Geoid.hpp:259
GeographicLib::Geoid::EquatorialRadius
Math::real EquatorialRadius() const
Definition Geoid.hpp:434
GeographicLib::Geoid::Interpolation
const std::string Interpolation() const
Definition Geoid.hpp:345
GeographicLib::Geoid::CacheNorth
Math::real CacheNorth() const
Definition Geoid.hpp:414
GeographicLib::Geoid::ConvertHeight
Math::real ConvertHeight(real lat, real lon, real h, convertflag d) const
Definition Geoid.hpp:305
GeographicLib::Geoid::Offset
Math::real Offset() const
Definition Geoid.hpp:372
GeographicLib::Geoid::CacheArea
void CacheArea(real south, real west, real north, real east) const
Definition Geoid.cpp:408
GeographicLib::Geoid::DateTime
const std::string & DateTime() const
Definition Geoid.hpp:324
GeographicLib::Geoid::operator()
Math::real operator()(real lat, real lon) const
Definition Geoid.hpp:285
GeographicLib::Geoid::ThreadSafe
bool ThreadSafe() const
Definition Geoid.hpp:385
GeographicLib::Geoid::GeoidName
const std::string & GeoidName() const
Definition Geoid.hpp:335
GeographicLib::Geoid::CacheWest
Math::real CacheWest() const
Definition Geoid.hpp:395
GeographicLib::Math::qd
static constexpr int qd
degrees per quarter turn
Definition Math.hpp:150
GeographicLib::Math::td
static constexpr int td
degrees per turn
Definition Math.hpp:154
GeographicLib::Math::real
double real
Definition Math.hpp:115
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12