NETGeographicLib 1.52
Loading...
Searching...
No Matches
Geoid.h
Go to the documentation of this file.
1#pragma once
2/**
3 * \file NETGeographicLib/Geoid.h
4 * \brief Header for NETGeographicLib::Geoid class
5 *
6 * NETGeographicLib is copyright (c) Scott Heiman (2013)
7 * GeographicLib is Copyright (c) Charles Karney (2010-2012)
8 * <charles@karney.com> and licensed under the MIT/X11 License.
9 * For more information, see
10 * https://geographiclib.sourceforge.io/
11 **********************************************************************/
12
13namespace NETGeographicLib
14{
15 /**
16 * \brief .NET wrapper for GeographicLib::Geoid.
17 *
18 * This class allows .NET applications to access GeographicLib::Geoid.
19 *
20 * This class evaluated the height of one of the standard geoids, EGM84,
21 * EGM96, or EGM2008 by bilinear or cubic interpolation into a rectangular
22 * grid of data. These geoid models are documented in
23 * - EGM84:
24 * https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm84
25 * - EGM96:
26 * https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96
27 * - EGM2008:
28 * https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008
29 *
30 * The geoids are defined in terms of spherical harmonics. However in order
31 * to provide a quick and flexible method of evaluating the geoid heights,
32 * this class evaluates the height by interpolation into a grid of
33 * precomputed values.
34 *
35 * The geoid height, \e N, can be used to convert a height above the
36 * ellipsoid, \e h, to the corresponding height above the geoid (roughly the
37 * height above mean sea level), \e H, using the relations
38 *
39 * &nbsp;&nbsp;&nbsp;\e h = \e N + \e H;
40 * &nbsp;&nbsp;\e H = &minus;\e N + \e h.
41 *
42 * See \ref geoid for details of how to install the data sets, the data
43 * format, estimates of the interpolation errors, and how to use caching.
44 *
45 * This class is typically \e not thread safe in that a single instantiation
46 * cannot be safely used by multiple threads because of the way the object
47 * reads the data set and because it maintains a single-cell cache. If
48 * multiple threads need to calculate geoid heights they should all construct
49 * thread-local instantiations. Alternatively, set the optional \e
50 * threadsafe parameter to true in the constructor. This causes the
51 * constructor to read all the data into memory and to turn off the
52 * single-cell caching which results in a Geoid object which \e is thread
53 * safe.
54 *
55 * C# Example:
56 * \include example-Geoid.cs
57 * Managed C++ Example:
58 * \include example-Geoid.cpp
59 * Visual Basic Example:
60 * \include example-Geoid.vb
61 *
62 * <B>INTERFACE DIFFERENCES:</B><BR>
63 * The () operator has been replaced with Height method.
64 *
65 * The following functions are implemented as properties:
66 * Description, DateTime, GeoidFile, GeoidName, GeoidDirectory,
67 * Interpolation, MaxError, RMSError, Offset, Scale, ThreadSafe,
68 * Cache, CacheWest, CacheEast, CacheNorth, CacheSouth, EquatorialRadius,
69 * and Flattening.
70 **********************************************************************/
71 public ref class Geoid
72 {
73 private:
74 // a pointer to the unmanaged GeographicLib::Geoid.
75 const GeographicLib::Geoid* m_pGeoid;
76
77 // the finalizer frees hthe unmanaged memory when the object is destroyed.
78 !Geoid(void);
79 public:
80 /**
81 * Flags indicating conversions between heights above the geoid and heights
82 * above the ellipsoid.
83 **********************************************************************/
84 enum class ConvertFlag {
85 /**
86 * The multiplier for converting from heights above the geoid to heights
87 * above the ellipsoid.
88 **********************************************************************/
90 /**
91 * No conversion.
92 **********************************************************************/
93 NONE = 0,
94 /**
95 * The multiplier for converting from heights above the ellipsoid to
96 * heights above the geoid.
97 **********************************************************************/
99 };
100
101 /** \name Setting up the geoid
102 **********************************************************************/
103 ///@{
104 /**
105 * Construct a geoid.
106 *
107 * @param[in] name the name of the geoid.
108 * @param[in] path (optional) directory for data file.
109 * @param[in] cubic (optional) interpolation method; false means bilinear,
110 * true (the default) means cubic.
111 * @param[in] threadsafe (optional), if true, construct a thread safe
112 * object. The default is false
113 * @exception GeographicErr if the data file cannot be found, is
114 * unreadable, or is corrupt.
115 * @exception GeographicErr if \e threadsafe is true but the memory
116 * necessary for caching the data can't be allocated.
117 *
118 * The data file is formed by appending ".pgm" to the name. If \e path is
119 * specified (and is non-empty), then the file is loaded from directory, \e
120 * path. Otherwise the path is given by DefaultGeoidPath(). If the \e
121 * threadsafe parameter is true, the data set is read into memory, the data
122 * file is closed, and single-cell caching is turned off; this results in a
123 * Geoid object which \e is thread safe.
124 **********************************************************************/
125 Geoid(System::String^ name, System::String^ path,
126 bool cubic, bool threadsafe);
127 /**
128 * The destructor calls the finalizer.
129 **********************************************************************/
131 { this->!Geoid(); }
132
133 /**
134 * Set up a cache.
135 *
136 * @param[in] south latitude (degrees) of the south edge of the cached area.
137 * @param[in] west longitude (degrees) of the west edge of the cached area.
138 * @param[in] north latitude (degrees) of the north edge of the cached area.
139 * @param[in] east longitude (degrees) of the east edge of the cached area.
140 * @exception GeographicErr if the memory necessary for caching the data
141 * can't be allocated (in this case, you will have no cache and can try
142 * again with a smaller area).
143 * @exception GeographicErr if there's a problem reading the data.
144 * @exception GeographicErr if this is called on a threadsafe Geoid.
145 *
146 * Cache the data for the specified "rectangular" area bounded by the
147 * parallels \e south and \e north and the meridians \e west and \e east.
148 * \e east is always interpreted as being east of \e west, if necessary by
149 * adding 360&deg; to its value. \e south and \e north should be in
150 * the range [&minus;90&deg;, 90&deg;].
151 **********************************************************************/
152 void CacheArea(double south, double west, double north, double east);
153
154 /**
155 * Cache all the data.
156 *
157 * @exception GeographicErr if the memory necessary for caching the data
158 * can't be allocated (in this case, you will have no cache and can try
159 * again with a smaller area).
160 * @exception GeographicErr if there's a problem reading the data.
161 * @exception GeographicErr if this is called on a threadsafe Geoid.
162 *
163 * On most computers, this is fast for data sets with grid resolution of 5'
164 * or coarser. For a 1' grid, the required RAM is 450MB; a 2.5' grid needs
165 * 72MB; and a 5' grid needs 18MB.
166 **********************************************************************/
167 void CacheAll();
168
169 /**
170 * Clear the cache. This never throws an error. (This does nothing with a
171 * thread safe Geoid.)
172 **********************************************************************/
174
175 ///@}
176
177 /** \name Compute geoid heights
178 **********************************************************************/
179 ///@{
180 /**
181 * Compute the geoid height at a point
182 *
183 * @param[in] lat latitude of the point (degrees).
184 * @param[in] lon longitude of the point (degrees).
185 * @exception GeographicErr if there's a problem reading the data; this
186 * never happens if (\e lat, \e lon) is within a successfully cached area.
187 * @return geoid height (meters).
188 *
189 * The latitude should be in [&minus;90&deg;, 90&deg;].
190 **********************************************************************/
191 double Height(double lat, double lon);
192
193 /**
194 * Convert a height above the geoid to a height above the ellipsoid and
195 * vice versa.
196 *
197 * @param[in] lat latitude of the point (degrees).
198 * @param[in] lon longitude of the point (degrees).
199 * @param[in] h height of the point (degrees).
200 * @param[in] d a Geoid::convertflag specifying the direction of the
201 * conversion; Geoid::GEOIDTOELLIPSOID means convert a height above the
202 * geoid to a height above the ellipsoid; Geoid::ELLIPSOIDTOGEOID means
203 * convert a height above the ellipsoid to a height above the geoid.
204 * @exception GeographicErr if there's a problem reading the data; this
205 * never happens if (\e lat, \e lon) is within a successfully cached area.
206 * @return converted height (meters).
207 **********************************************************************/
208 double ConvertHeight(double lat, double lon, double h,
209 ConvertFlag d);
210
211 ///@}
212
213 /** \name Inspector functions
214 **********************************************************************/
215 ///@{
216 /**
217 * @return geoid description, if available, in the data file; if
218 * absent, return "NONE".
219 **********************************************************************/
220 property System::String^ Description { System::String^ get(); }
221
222 /**
223 * @return date of the data file; if absent, return "UNKNOWN".
224 **********************************************************************/
225 property System::String^ DateTime { System::String^ get(); }
226
227 /**
228 * @return full file name used to load the geoid data.
229 **********************************************************************/
230 property System::String^ GeoidFile { System::String^ get(); }
231
232 /**
233 * @return "name" used to load the geoid data (from the first argument of
234 * the constructor).
235 **********************************************************************/
236 property System::String^ GeoidName { System::String^ get(); }
237
238 /**
239 * @return directory used to load the geoid data.
240 **********************************************************************/
241 property System::String^ GeoidDirectory { System::String^ get(); }
242
243 /**
244 * @return interpolation method ("cubic" or "bilinear").
245 **********************************************************************/
246 property System::String^ Interpolation { System::String^ get(); }
247
248 /**
249 * @return estimate of the maximum interpolation and quantization error
250 * (meters).
251 *
252 * This relies on the value being stored in the data file. If the value is
253 * absent, return &minus;1.
254 **********************************************************************/
255 property double MaxError { double get(); }
256
257 /**
258 * @return estimate of the RMS interpolation and quantization error
259 * (meters).
260 *
261 * This relies on the value being stored in the data file. If the value is
262 * absent, return &minus;1.
263 **********************************************************************/
264 property double RMSError { double get(); }
265
266 /**
267 * @return offset (meters).
268 *
269 * This in used in converting from the pixel values in the data file to
270 * geoid heights.
271 **********************************************************************/
272 property double Offset { double get(); }
273
274 /**
275 * @return scale (meters).
276 *
277 * This in used in converting from the pixel values in the data file to
278 * geoid heights.
279 **********************************************************************/
280 property double Scale { double get(); }
281
282 /**
283 * @return true if the object is constructed to be thread safe.
284 **********************************************************************/
285 property bool ThreadSafe { bool get(); }
286
287 /**
288 * @return true if a data cache is active.
289 **********************************************************************/
290 property bool Cache { bool get(); }
291
292 /**
293 * @return west edge of the cached area; the cache includes this edge.
294 **********************************************************************/
295 property double CacheWest { double get(); }
296
297 /**
298 * @return east edge of the cached area; the cache excludes this edge.
299 **********************************************************************/
300 property double CacheEast { double get(); }
301
302 /**
303 * @return north edge of the cached area; the cache includes this edge.
304 **********************************************************************/
305 property double CacheNorth { double get(); }
306
307 /**
308 * @return south edge of the cached area; the cache excludes this edge
309 * unless it's the south pole.
310 **********************************************************************/
311 property double CacheSouth { double get(); }
312
313 /**
314 * @return \e a the equatorial radius of the WGS84 ellipsoid (meters).
315 *
316 * (The WGS84 value is returned because the supported geoid models are all
317 * based on this ellipsoid.)
318 **********************************************************************/
319 property double EquatorialRadius { double get(); }
320
321 /**
322 * @return \e f the flattening of the WGS84 ellipsoid.
323 *
324 * (The WGS84 value is returned because the supported geoid models are all
325 * based on this ellipsoid.)
326 **********************************************************************/
327 property double Flattening { double get(); }
328 ///@}
329
330 /**
331 * @return the default path for geoid data files.
332 *
333 * This is the value of the environment variable
334 * GEOGRAPHICLIB_GEOID_PATH, if set; otherwise, it is
335 * $GEOGRAPHICLIB_DATA/geoids if the environment variable
336 * GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default
337 * (/usr/local/share/GeographicLib/geoids on non-Windows systems and
338 * C:/ProgramData/GeographicLib/geoids on Windows systems).
339 **********************************************************************/
340 static System::String^ DefaultGeoidPath();
341
342 /**
343 * @return the default name for the geoid.
344 *
345 * This is the value of the environment variable
346 * GEOGRAPHICLIB_GEOID_NAME, if set, otherwise, it is "egm96-5". The
347 * Geoid class does not use this function; it is just provided as a
348 * convenience for a calling program when constructing a Geoid object.
349 **********************************************************************/
350 static System::String^ DefaultGeoidName();
351 };
352} // namespace NETGeographicLib
.NET wrapper for GeographicLib::Geoid.
Definition: Geoid.h:72
System::String^ Interpolation
Definition: Geoid.h:246
double EquatorialRadius
Definition: Geoid.h:319
static System::String ^ DefaultGeoidName()
void CacheArea(double south, double west, double north, double east)
System::String^ GeoidDirectory
Definition: Geoid.h:241
System::String^ Description
Definition: Geoid.h:220
double ConvertHeight(double lat, double lon, double h, ConvertFlag d)
static System::String ^ DefaultGeoidPath()
System::String^ DateTime
Definition: Geoid.h:225
System::String^ GeoidName
Definition: Geoid.h:236
System::String^ GeoidFile
Definition: Geoid.h:230
Geoid(System::String^ name, System::String^ path, bool cubic, bool threadsafe)
double Height(double lat, double lon)