GeographicLib  1.50
Geoid.cpp
Go to the documentation of this file.
1 /**
2  * \file Geoid.cpp
3  * \brief Implementation for GeographicLib::Geoid class
4  *
5  * Copyright (c) Charles Karney (2009-2018) <charles@karney.com> and licensed
6  * under the MIT/X11 License. For more information, see
7  * https://geographiclib.sourceforge.io/
8  **********************************************************************/
9 
10 #include <GeographicLib/Geoid.hpp>
11 // For getenv
12 #include <cstdlib>
14 
15 #if !defined(GEOGRAPHICLIB_DATA)
16 # if defined(_WIN32)
17 # define GEOGRAPHICLIB_DATA "C:/ProgramData/GeographicLib"
18 # else
19 # define GEOGRAPHICLIB_DATA "/usr/local/share/GeographicLib"
20 # endif
21 #endif
22 
23 #if !defined(GEOGRAPHICLIB_GEOID_DEFAULT_NAME)
24 # define GEOGRAPHICLIB_GEOID_DEFAULT_NAME "egm96-5"
25 #endif
26 
27 #if defined(_MSC_VER)
28 // Squelch warnings about unsafe use of getenv
29 # pragma warning (disable: 4996)
30 #endif
31 
32 namespace GeographicLib {
33 
34  using namespace std;
35 
36  // This is the transfer matrix for a 3rd order fit with a 12-point stencil
37  // with weights
38  //
39  // \x -1 0 1 2
40  // y
41  // -1 . 1 1 .
42  // 0 1 2 2 1
43  // 1 1 2 2 1
44  // 2 . 1 1 .
45  //
46  // A algorithm for n-dimensional polynomial fits is described in
47  // F. H. Lesh,
48  // Multi-dimensional least-squares polynomial curve fitting,
49  // CACM 2, 29-30 (1959).
50  // https://doi.org/10.1145/368424.368443
51  //
52  // Here's the Maxima code to generate this matrix:
53  //
54  // /* The stencil and the weights */
55  // xarr:[
56  // 0, 1,
57  // -1, 0, 1, 2,
58  // -1, 0, 1, 2,
59  // 0, 1]$
60  // yarr:[
61  // -1,-1,
62  // 0, 0, 0, 0,
63  // 1, 1, 1, 1,
64  // 2, 2]$
65  // warr:[
66  // 1, 1,
67  // 1, 2, 2, 1,
68  // 1, 2, 2, 1,
69  // 1, 1]$
70  //
71  // /* [x exponent, y exponent] for cubic fit */
72  // pows:[
73  // [0,0],
74  // [1,0],[0,1],
75  // [2,0],[1,1],[0,2],
76  // [3,0],[2,1],[1,2],[0,3]]$
77  //
78  // basisvec(x,y,pows):=map(lambda([ex],(if ex[1]=0 then 1 else x^ex[1])*
79  // (if ex[2]=0 then 1 else y^ex[2])),pows)$
80  // addterm(x,y,f,w,pows):=block([a,b,bb:basisvec(x,y,pows)],
81  // a:w*(transpose(bb).bb),
82  // b:(w*f) * bb,
83  // [a,b])$
84  //
85  // c3row(k):=block([a,b,c,pows:pows,n],
86  // n:length(pows),
87  // a:zeromatrix(n,n),
88  // b:copylist(part(a,1)),
89  // c:[a,b],
90  // for i:1 thru length(xarr) do
91  // c:c+addterm(xarr[i],yarr[i],if i=k then 1 else 0,warr[i],pows),
92  // a:c[1],b:c[2],
93  // part(transpose( a^^-1 . transpose(b)),1))$
94  // c3:[]$
95  // for k:1 thru length(warr) do c3:endcons(c3row(k),c3)$
96  // c3:apply(matrix,c3)$
97  // c0:part(ratsimp(
98  // genmatrix(yc,1,length(warr)).abs(c3).genmatrix(yd,length(pows),1)),2)$
99  // c3:c0*c3$
100 
101  const int Geoid::c0_ = 240; // Common denominator
102  const int Geoid::c3_[stencilsize_ * nterms_] = {
103  9, -18, -88, 0, 96, 90, 0, 0, -60, -20,
104  -9, 18, 8, 0, -96, 30, 0, 0, 60, -20,
105  9, -88, -18, 90, 96, 0, -20, -60, 0, 0,
106  186, -42, -42, -150, -96, -150, 60, 60, 60, 60,
107  54, 162, -78, 30, -24, -90, -60, 60, -60, 60,
108  -9, -32, 18, 30, 24, 0, 20, -60, 0, 0,
109  -9, 8, 18, 30, -96, 0, -20, 60, 0, 0,
110  54, -78, 162, -90, -24, 30, 60, -60, 60, -60,
111  -54, 78, 78, 90, 144, 90, -60, -60, -60, -60,
112  9, -8, -18, -30, -24, 0, 20, 60, 0, 0,
113  -9, 18, -32, 0, 24, 30, 0, 0, -60, 20,
114  9, -18, -8, 0, -24, -30, 0, 0, 60, 20,
115  };
116 
117  // Like c3, but with the coeffs of x, x^2, and x^3 constrained to be zero.
118  // Use this at the N pole so that the height in independent of the longitude
119  // there.
120  //
121  // Here's the Maxima code to generate this matrix (continued from above).
122  //
123  // /* figure which terms to exclude so that fit is indep of x at y=0 */
124  // mask:part(zeromatrix(1,length(pows)),1)+1$
125  // for i:1 thru length(pows) do
126  // if pows[i][1]>0 and pows[i][2]=0 then mask[i]:0$
127  //
128  // /* Same as c3row but with masked pows. */
129  // c3nrow(k):=block([a,b,c,powsa:[],n,d,e],
130  // for i:1 thru length(mask) do if mask[i]>0 then
131  // powsa:endcons(pows[i],powsa),
132  // n:length(powsa),
133  // a:zeromatrix(n,n),
134  // b:copylist(part(a,1)),
135  // c:[a,b],
136  // for i:1 thru length(xarr) do
137  // c:c+addterm(xarr[i],yarr[i],if i=k then 1 else 0,warr[i],powsa),
138  // a:c[1],b:c[2],
139  // d:part(transpose( a^^-1 . transpose(b)),1),
140  // e:[],
141  // for i:1 thru length(mask) do
142  // if mask[i]>0 then (e:endcons(first(d),e),d:rest(d)) else e:endcons(0,e),
143  // e)$
144  // c3n:[]$
145  // for k:1 thru length(warr) do c3n:endcons(c3nrow(k),c3n)$
146  // c3n:apply(matrix,c3n)$
147  // c0n:part(ratsimp(
148  // genmatrix(yc,1,length(warr)).abs(c3n).genmatrix(yd,length(pows),1)),2)$
149  // c3n:c0n*c3n$
150 
151  const int Geoid::c0n_ = 372; // Common denominator
152  const int Geoid::c3n_[stencilsize_ * nterms_] = {
153  0, 0, -131, 0, 138, 144, 0, 0, -102, -31,
154  0, 0, 7, 0, -138, 42, 0, 0, 102, -31,
155  62, 0, -31, 0, 0, -62, 0, 0, 0, 31,
156  124, 0, -62, 0, 0, -124, 0, 0, 0, 62,
157  124, 0, -62, 0, 0, -124, 0, 0, 0, 62,
158  62, 0, -31, 0, 0, -62, 0, 0, 0, 31,
159  0, 0, 45, 0, -183, -9, 0, 93, 18, 0,
160  0, 0, 216, 0, 33, 87, 0, -93, 12, -93,
161  0, 0, 156, 0, 153, 99, 0, -93, -12, -93,
162  0, 0, -45, 0, -3, 9, 0, 93, -18, 0,
163  0, 0, -55, 0, 48, 42, 0, 0, -84, 31,
164  0, 0, -7, 0, -48, -42, 0, 0, 84, 31,
165  };
166 
167  // Like c3n, but y -> 1-y so that h is independent of x at y = 1. Use this
168  // at the S pole so that the height in independent of the longitude there.
169  //
170  // Here's the Maxima code to generate this matrix (continued from above).
171  //
172  // /* Transform c3n to c3s by transforming y -> 1-y */
173  // vv:[
174  // v[11],v[12],
175  // v[7],v[8],v[9],v[10],
176  // v[3],v[4],v[5],v[6],
177  // v[1],v[2]]$
178  // poly:expand(vv.(c3n/c0n).transpose(basisvec(x,1-y,pows)))$
179  // c3sf[i,j]:=coeff(coeff(coeff(poly,v[i]),x,pows[j][1]),y,pows[j][2])$
180  // c3s:genmatrix(c3sf,length(vv),length(pows))$
181  // c0s:part(ratsimp(
182  // genmatrix(yc,1,length(warr)).abs(c3s).genmatrix(yd,length(pows),1)),2)$
183  // c3s:c0s*c3s$
184 
185  const int Geoid::c0s_ = 372; // Common denominator
186  const int Geoid::c3s_[stencilsize_ * nterms_] = {
187  18, -36, -122, 0, 120, 135, 0, 0, -84, -31,
188  -18, 36, -2, 0, -120, 51, 0, 0, 84, -31,
189  36, -165, -27, 93, 147, -9, 0, -93, 18, 0,
190  210, 45, -111, -93, -57, -192, 0, 93, 12, 93,
191  162, 141, -75, -93, -129, -180, 0, 93, -12, 93,
192  -36, -21, 27, 93, 39, 9, 0, -93, -18, 0,
193  0, 0, 62, 0, 0, 31, 0, 0, 0, -31,
194  0, 0, 124, 0, 0, 62, 0, 0, 0, -62,
195  0, 0, 124, 0, 0, 62, 0, 0, 0, -62,
196  0, 0, 62, 0, 0, 31, 0, 0, 0, -31,
197  -18, 36, -64, 0, 66, 51, 0, 0, -102, 31,
198  18, -36, 2, 0, -66, -51, 0, 0, 102, 31,
199  };
200 
201  Geoid::Geoid(const std::string& name, const std::string& path, bool cubic,
202  bool threadsafe)
203  : _name(name)
204  , _dir(path)
205  , _cubic(cubic)
206  , _a( Constants::WGS84_a() )
207  , _e2( (2 - Constants::WGS84_f()) * Constants::WGS84_f() )
208  , _degree( Math::degree() )
209  , _eps( sqrt(numeric_limits<real>::epsilon()) )
210  , _threadsafe(false) // Set after cache is read
211  {
212  GEOGRAPHICLIB_STATIC_ASSERT(sizeof(pixel_t) == pixel_size_,
213  "pixel_t has the wrong size");
214  if (_dir.empty())
215  _dir = DefaultGeoidPath();
216  _filename = _dir + "/" + _name + (pixel_size_ != 4 ? ".pgm" : ".pgm4");
217  _file.open(_filename.c_str(), ios::binary);
218  if (!(_file.good()))
219  throw GeographicErr("File not readable " + _filename);
220  string s;
221  if (!(getline(_file, s) && s == "P5"))
222  throw GeographicErr("File not in PGM format " + _filename);
223  _offset = numeric_limits<real>::max();
224  _scale = 0;
225  _maxerror = _rmserror = -1;
226  _description = "NONE";
227  _datetime = "UNKNOWN";
228  while (getline(_file, s)) {
229  if (s.empty())
230  continue;
231  if (s[0] == '#') {
232  istringstream is(s);
233  string commentid, key;
234  if (!(is >> commentid >> key) || commentid != "#")
235  continue;
236  if (key == "Description" || key =="DateTime") {
237  string::size_type p =
238  s.find_first_not_of(" \t", unsigned(is.tellg()));
239  if (p != string::npos)
240  (key == "Description" ? _description : _datetime) = s.substr(p);
241  } else if (key == "Offset") {
242  if (!(is >> _offset))
243  throw GeographicErr("Error reading offset " + _filename);
244  } else if (key == "Scale") {
245  if (!(is >> _scale))
246  throw GeographicErr("Error reading scale " + _filename);
247  } else if (key == (_cubic ? "MaxCubicError" : "MaxBilinearError")) {
248  // It's not an error if the error can't be read
249  is >> _maxerror;
250  } else if (key == (_cubic ? "RMSCubicError" : "RMSBilinearError")) {
251  // It's not an error if the error can't be read
252  is >> _rmserror;
253  }
254  } else {
255  istringstream is(s);
256  if (!(is >> _width >> _height))
257  throw GeographicErr("Error reading raster size " + _filename);
258  break;
259  }
260  }
261  {
262  unsigned maxval;
263  if (!(_file >> maxval))
264  throw GeographicErr("Error reading maxval " + _filename);
265  if (maxval != pixel_max_)
266  throw GeographicErr("Incorrect value of maxval " + _filename);
267  // Add 1 for whitespace after maxval
268  _datastart = (unsigned long long)(_file.tellg()) + 1ULL;
269  _swidth = (unsigned long long)(_width);
270  }
271  if (_offset == numeric_limits<real>::max())
272  throw GeographicErr("Offset not set " + _filename);
273  if (_scale == 0)
274  throw GeographicErr("Scale not set " + _filename);
275  if (_scale < 0)
276  throw GeographicErr("Scale must be positive " + _filename);
277  if (_height < 2 || _width < 2)
278  // Coarsest grid spacing is 180deg.
279  throw GeographicErr("Raster size too small " + _filename);
280  if (_width & 1)
281  // This is so that longitude grids can be extended thru the poles.
282  throw GeographicErr("Raster width is odd " + _filename);
283  if (!(_height & 1))
284  // This is so that latitude grid includes the equator.
285  throw GeographicErr("Raster height is even " + _filename);
286  _file.seekg(0, ios::end);
287  if (!_file.good() ||
288  _datastart + pixel_size_ * _swidth * (unsigned long long)(_height) !=
289  (unsigned long long)(_file.tellg()))
290  // Possibly this test should be "<" because the file contains, e.g., a
291  // second image. However, for now we are more strict.
292  throw GeographicErr("File has the wrong length " + _filename);
293  _rlonres = _width / real(360);
294  _rlatres = (_height - 1) / real(180);
295  _cache = false;
296  _ix = _width;
297  _iy = _height;
298  // Ensure that file errors throw exceptions
299  _file.exceptions(ifstream::eofbit | ifstream::failbit | ifstream::badbit);
300  if (threadsafe) {
301  CacheAll();
302  _file.close();
303  _threadsafe = true;
304  }
305  }
306 
307  Math::real Geoid::height(real lat, real lon) const {
308  lat = Math::LatFix(lat);
309  if (Math::isnan(lat) || Math::isnan(lon)) {
310  return Math::NaN();
311  }
312  lon = Math::AngNormalize(lon);
313  real
314  fx = lon * _rlonres,
315  fy = -lat * _rlatres;
316  int
317  ix = int(floor(fx)),
318  iy = min((_height - 1)/2 - 1, int(floor(fy)));
319  fx -= ix;
320  fy -= iy;
321  iy += (_height - 1)/2;
322  ix += ix < 0 ? _width : (ix >= _width ? -_width : 0);
323  real v00 = 0, v01 = 0, v10 = 0, v11 = 0;
324  real t[nterms_];
325 
326  if (_threadsafe || !(ix == _ix && iy == _iy)) {
327  if (!_cubic) {
328  v00 = rawval(ix , iy );
329  v01 = rawval(ix + 1, iy );
330  v10 = rawval(ix , iy + 1);
331  v11 = rawval(ix + 1, iy + 1);
332  } else {
333  real v[stencilsize_];
334  int k = 0;
335  v[k++] = rawval(ix , iy - 1);
336  v[k++] = rawval(ix + 1, iy - 1);
337  v[k++] = rawval(ix - 1, iy );
338  v[k++] = rawval(ix , iy );
339  v[k++] = rawval(ix + 1, iy );
340  v[k++] = rawval(ix + 2, iy );
341  v[k++] = rawval(ix - 1, iy + 1);
342  v[k++] = rawval(ix , iy + 1);
343  v[k++] = rawval(ix + 1, iy + 1);
344  v[k++] = rawval(ix + 2, iy + 1);
345  v[k++] = rawval(ix , iy + 2);
346  v[k++] = rawval(ix + 1, iy + 2);
347 
348  const int* c3x = iy == 0 ? c3n_ : (iy == _height - 2 ? c3s_ : c3_);
349  int c0x = iy == 0 ? c0n_ : (iy == _height - 2 ? c0s_ : c0_);
350  for (unsigned i = 0; i < nterms_; ++i) {
351  t[i] = 0;
352  for (unsigned j = 0; j < stencilsize_; ++j)
353  t[i] += v[j] * c3x[nterms_ * j + i];
354  t[i] /= c0x;
355  }
356  }
357  } else { // same cell; used cached coefficients
358  if (!_cubic) {
359  v00 = _v00;
360  v01 = _v01;
361  v10 = _v10;
362  v11 = _v11;
363  } else
364  copy(_t, _t + nterms_, t);
365  }
366  if (!_cubic) {
367  real
368  a = (1 - fx) * v00 + fx * v01,
369  b = (1 - fx) * v10 + fx * v11,
370  c = (1 - fy) * a + fy * b,
371  h = _offset + _scale * c;
372  if (!_threadsafe) {
373  _ix = ix;
374  _iy = iy;
375  _v00 = v00;
376  _v01 = v01;
377  _v10 = v10;
378  _v11 = v11;
379  }
380  return h;
381  } else {
382  real h = t[0] + fx * (t[1] + fx * (t[3] + fx * t[6])) +
383  fy * (t[2] + fx * (t[4] + fx * t[7]) +
384  fy * (t[5] + fx * t[8] + fy * t[9]));
385  h = _offset + _scale * h;
386  if (!_threadsafe) {
387  _ix = ix;
388  _iy = iy;
389  copy(t, t + nterms_, _t);
390  }
391  return h;
392  }
393  }
394 
395  void Geoid::CacheClear() const {
396  if (!_threadsafe) {
397  _cache = false;
398  try {
399  _data.clear();
400  // Use swap to release memory back to system
401  vector< vector<pixel_t> >().swap(_data);
402  }
403  catch (const exception&) {
404  }
405  }
406  }
407 
408  void Geoid::CacheArea(real south, real west, real north, real east) const {
409  if (_threadsafe)
410  throw GeographicErr("Attempt to change cache of threadsafe Geoid");
411  if (south > north) {
412  CacheClear();
413  return;
414  }
415  south = Math::LatFix(south);
416  north = Math::LatFix(north);
417  west = Math::AngNormalize(west); // west in [-180, 180)
418  east = Math::AngNormalize(east);
419  if (east <= west)
420  east += 360; // east - west in (0, 360]
421  int
422  iw = int(floor(west * _rlonres)),
423  ie = int(floor(east * _rlonres)),
424  in = int(floor(-north * _rlatres)) + (_height - 1)/2,
425  is = int(floor(-south * _rlatres)) + (_height - 1)/2;
426  in = max(0, min(_height - 2, in));
427  is = max(0, min(_height - 2, is));
428  is += 1;
429  ie += 1;
430  if (_cubic) {
431  in -= 1;
432  is += 1;
433  iw -= 1;
434  ie += 1;
435  }
436  if (ie - iw >= _width - 1) {
437  // Include entire longitude range
438  iw = 0;
439  ie = _width - 1;
440  } else {
441  ie += iw < 0 ? _width : (iw >= _width ? -_width : 0);
442  iw += iw < 0 ? _width : (iw >= _width ? -_width : 0);
443  }
444  int oysize = int(_data.size());
445  _xsize = ie - iw + 1;
446  _ysize = is - in + 1;
447  _xoffset = iw;
448  _yoffset = in;
449 
450  try {
451  _data.resize(_ysize, vector<pixel_t>(_xsize));
452  for (int iy = min(oysize, _ysize); iy--;)
453  _data[iy].resize(_xsize);
454  }
455  catch (const bad_alloc&) {
456  CacheClear();
457  throw GeographicErr("Insufficient memory for caching " + _filename);
458  }
459 
460  try {
461  for (int iy = in; iy <= is; ++iy) {
462  int iy1 = iy, iw1 = iw;
463  if (iy < 0 || iy >= _height) {
464  // Allow points "beyond" the poles to support interpolation
465  iy1 = iy1 < 0 ? -iy1 : 2 * (_height - 1) - iy1;
466  iw1 += _width/2;
467  if (iw1 >= _width)
468  iw1 -= _width;
469  }
470  int xs1 = min(_width - iw1, _xsize);
471  filepos(iw1, iy1);
472  Utility::readarray<pixel_t, pixel_t, true>
473  (_file, &(_data[iy - in][0]), xs1);
474  if (xs1 < _xsize) {
475  // Wrap around longitude = 0
476  filepos(0, iy1);
477  Utility::readarray<pixel_t, pixel_t, true>
478  (_file, &(_data[iy - in][xs1]), _xsize - xs1);
479  }
480  }
481  _cache = true;
482  }
483  catch (const exception& e) {
484  CacheClear();
485  throw GeographicErr(string("Error filling cache ") + e.what());
486  }
487  }
488 
489  std::string Geoid::DefaultGeoidPath() {
490  string path;
491  char* geoidpath = getenv("GEOGRAPHICLIB_GEOID_PATH");
492  if (geoidpath)
493  path = string(geoidpath);
494  if (!path.empty())
495  return path;
496  char* datapath = getenv("GEOGRAPHICLIB_DATA");
497  if (datapath)
498  path = string(datapath);
499  return (!path.empty() ? path : string(GEOGRAPHICLIB_DATA)) + "/geoids";
500  }
501 
502  std::string Geoid::DefaultGeoidName() {
503  string name;
504  char* geoidname = getenv("GEOGRAPHICLIB_GEOID_NAME");
505  if (geoidname)
506  name = string(geoidname);
507  return !name.empty() ? name : string(GEOGRAPHICLIB_GEOID_DEFAULT_NAME);
508  }
509 
510 } // namespace GeographicLib
static T AngNormalize(T x)
Definition: Math.hpp:383
Header for GeographicLib::Utility class.
static T LatFix(T x)
Definition: Math.hpp:395
void CacheArea(real south, real west, real north, real east) const
Definition: Geoid.cpp:408
Mathematical functions needed by GeographicLib.
Definition: Math.hpp:98
static std::string DefaultGeoidPath()
Definition: Geoid.cpp:489
#define GEOGRAPHICLIB_GEOID_DEFAULT_NAME
Definition: Geoid.cpp:24
#define GEOGRAPHICLIB_DATA
Definition: Geoid.cpp:19
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
static T NaN()
Definition: Math.cpp:389
static bool isnan(T x)
Definition: Math.cpp:401
void swap(GeographicLib::NearestNeighbor< dist_t, pos_t, distfun_t > &a, GeographicLib::NearestNeighbor< dist_t, pos_t, distfun_t > &b)
Constants needed by GeographicLib
Definition: Constants.hpp:132
Exception handling for GeographicLib.
Definition: Constants.hpp:390
static std::string DefaultGeoidName()
Definition: Geoid.cpp:502
void CacheClear() const
Definition: Geoid.cpp:395
Header for GeographicLib::Geoid class.
void CacheAll() const
Definition: Geoid.hpp:258