UNCLASSIFIED

GeographicTranslator
 All Classes Namespaces Functions Enumerations
GeoidLibrary.h
1 // CLASSIFICATION: UNCLASSIFIED
2 
3 #ifndef GeoidLibrary_H
4 #define GeoidLibrary_H
5 
6 /***************************************************************************/
7 /* RSC IDENTIFIER: Geoid Library
8  *
9  * ABSTRACT
10  *
11  * The purpose of GEOID is to support conversions between WGS84 ellipsoid
12  * heights and WGS84 geoid heights.
13  *
14  *
15  * ERROR HANDLING
16  *
17  * This component checks parameters for valid values. If an invalid value
18  * is found, the error code is combined with the current error code using
19  * the bitwise or. This combining allows multiple error codes to be
20  * returned. The possible error codes are:
21  *
22  * GEOID_NO_ERROR : No errors occurred in function
23  * GEOID_FILE_OPEN_ERROR : Geoid file opening error
24  * GEOID_INITIALIZE_ERROR : Geoid separation database can not initialize
25  * GEOID_LAT_ERROR : Latitude out of valid range
26  * (-90 to 90 degrees)
27  * GEOID_LON_ERROR : Longitude out of valid range
28  * (-180 to 360 degrees)
29  *
30  * REUSE NOTES
31  *
32  * Geoid is intended for reuse by any application that requires conversion
33  * between WGS84 ellipsoid heights and WGS84 geoid heights.
34  *
35  * REFERENCES
36  *
37  * Further information on Geoid can be found in the Reuse Manual.
38  *
39  * Geoid originated from : U.S. Army Topographic Engineering Center
40  * Geospatial Information Division
41  * 7701 Telegraph Road
42  * Alexandria, VA 22310-3864
43  *
44  * LICENSES
45  *
46  * None apply to this component.
47  *
48  * RESTRICTIONS
49  *
50  * Geoid has no restrictions.
51  *
52  * ENVIRONMENT
53  *
54  * Geoid was tested and certified in the following environments
55  *
56  * 1. Solaris 2.5 with GCC 2.8.1
57  * 2. MS Windows XP with MS Visual C++ 6.0
58  *
59  *
60  * MODIFICATIONS
61  *
62  * Date Description
63  * ---- -----------
64  * 24-May-99 Original Code
65  * 09-Jan-06 Added new geoid height interpolation methods
66  * 03-14-07 Original C++ Code
67  * 05-12-10 S. Gillis, BAEts26542, MSL-HAE for 30 minute grid added
68  * 07-21-10 Read in full file at once instead of one post at a time
69  * 12-17-10 RD Craig added pointer to EGM2008 interpolator (BAEts26267).
70  *
71  */
72 
73 #include "egm2008_geoid_grid.h"
74 
75 #include "DtccApi.h"
76 
77 namespace MSP
78 {
79  class CCSThreadMutex;
80  namespace CCS
81  {
82  class MSP_DTCC_API GeoidLibrary
83  {
84  friend class GeoidLibraryCleaner;
85 
86  public:
87 
88  /* The function getInstance returns an instance of the GeoidLibrary
89  */
90 
91  static GeoidLibrary* getInstance();
92 
93 
94  /*
95  * The function removeInstance removes this GeoidLibrary
96  * instance from the total number of instances.
97  */
98 
99  static void removeInstance();
100 
101 
102  ~GeoidLibrary( void );
103 
104 
105  /*
106  * The function convertEllipsoidToEGM96FifteenMinBilinearGeoidHeight
107  * converts the specified WGS84 ellipsoid height at the specified
108  * geodetic coordinates to the equivalent
109  * geoid height, using the EGM96 gravity model and
110  * the bilinear interpolation method.
111  *
112  * longitude : Geodetic longitude in radians (input)
113  * latitude : Geodetic latitude in radians (input)
114  * ellipsoidHeight : Ellipsoid height, in meters (input)
115  * geoidHeight : Geoid height, in meters. (output)
116  *
117  */
118 
119  void convertEllipsoidToEGM96FifteenMinBilinearGeoidHeight(
120  double longitude,
121  double latitude,
122  double ellipsoidHeight,
123  double *geoidHeight );
124 
125 
126  /*
127  * The function convertEllipsoidToEGM96VariableNaturalSplineHeight
128  * converts the specified WGS84 ellipsoid height at the specified
129  * geodetic coordinates to the equivalent geoid height,
130  * using the EGM96 gravity model and
131  * the natural spline interpolation method.
132  *
133  * longitude : Geodetic longitude in radians (input)
134  * latitude : Geodetic latitude in radians (input)
135  * ellipsoidHeight : Ellipsoid height, in meters (input)
136  * geoidHeight : Geoid height, in meters. (output)
137  *
138  */
139 
140  void convertEllipsoidToEGM96VariableNaturalSplineHeight(
141  double longitude,
142  double latitude,
143  double ellipsoidHeight,
144  double *geoidHeight );
145 
146  /*
147  * The function convertEllipsoidToEGM84TenDegBilinearHeight
148  * converts the specified WGS84 ellipsoid height at the specified
149  * geodetic coordinates to the equivalent geoid height,
150  * using the EGM84 gravity model and
151  * the bilinear interpolation method.
152  *
153  * longitude : Geodetic longitude in radians (input)
154  * latitude : Geodetic latitude in radians (input)
155  * ellipsoidHeight : Ellipsoid height, in meters (input)
156  * geoidHeight : Geoid height, in meters. (output)
157  *
158  */
159 
160  void convertEllipsoidToEGM84TenDegBilinearHeight(
161  double longitude,
162  double latitude,
163  double ellipsoidHeight,
164  double *geoidHeight );
165 
166  /*
167  * The function convertEllipsoidToEGM84TenDegNaturalSplineHeight
168  * converts the specified WGS84 ellipsoid height at the specified
169  * geodetic coordinates to the equivalent geoid height,
170  * using the EGM84 gravity model and
171  * the natural splineinterpolation method.
172  *
173  * longitude : Geodetic longitude in radians (input)
174  * latitude : Geodetic latitude in radians (input)
175  * ellipsoidHeight : Ellipsoid height, in meters (input)
176  * geoidHeight : Geoid height, in meters. (output)
177  *
178  */
179 
180  void convertEllipsoidToEGM84TenDegNaturalSplineHeight(
181  double longitude,
182  double latitude,
183  double ellipsoidHeight,
184  double *geoidHeight );
185 
186  /*
187  * The function convertEllipsoidToEGM84ThirtyMinBiLinearHeight
188  * converts the specified WGS84 ellipsoid height at the specified
189  * geodetic coordinates to the equivalent geoid height,
190  * using the EGM84 gravity model and
191  * the bilinear interpolation method.
192  *
193  * longitude : Geodetic longitude in radians (input)
194  * latitude : Geodetic latitude in radians (input)
195  * ellipsoidHeight : Ellipsoid height, in meters (input)
196  * geoidHeight : Geoid height, in meters. (output)
197  */
198 
199  void convertEllipsoidToEGM84ThirtyMinBiLinearHeight(
200  double longitude,
201  double latitude,
202  double ellipsoidHeight,
203  double *geoidHeight );
204 
205  /*
206  * The function convertEllipsoidHeightToEGM2008GeoidHeight
207  * converts the specified WGS84 ellipsoid height at the specified
208  * geodetic coordinates to the equivalent height above the geoid. This function
209  * uses the EGM2008 gravity model, plus the bicubic spline interpolation method.
210  *
211  * longitude : Geodetic longitude in radians (input)
212  * latitude : Geodetic latitude in radians (input)
213  * ellipsoidHeight : Ellipsoid height, in meters (input)
214  * geoidHeight : Height above the geoid, meters (output)
215  */
216 
217  void
218  convertEllipsoidHeightToEGM2008GeoidHeight(
219  double longitude,
220  double latitude,
221  double ellipsoidHeight,
222  double *geoidHeight );
223 
224  /*
225  * The function convertEGM96FifteenMinBilinearGeoidToEllipsoidHeight
226  * converts the specified WGS84 geoid height at the specified
227  * geodetic coordinates to the equivalent ellipsoid height,
228  * using the EGM96 gravity model and
229  * the bilinear interpolation method.
230  *
231  * longitude : Geodetic longitude in radians (input)
232  * latitude : Geodetic latitude in radians (input)
233  * geoidHeight : Geoid height, in meters. (input)
234  * ellipsoidHeight : Ellipsoid height, in meters (output)
235  *
236  */
237 
238  void convertEGM96FifteenMinBilinearGeoidToEllipsoidHeight(
239  double longitude,
240  double latitude,
241  double geoidHeight,
242  double *ellipsoidHeight );
243 
244  /*
245  * The function convertEGM96VariableNaturalSplineToEllipsoidHeight
246  * converts the specified WGS84 geoid height at the specified
247  * geodetic coordinates to the equivalent ellipsoid height,
248  * using the EGM96 gravity model and
249  * the natural spline interpolation method.
250  *
251  * longitude : Geodetic longitude in radians (input)
252  * latitude : Geodetic latitude in radians (input)
253  * geoidHeight : Geoid height, in meters. (input)
254  * ellipsoidHeight : Ellipsoid height, in meters (output)
255  *
256  */
257 
258  void convertEGM96VariableNaturalSplineToEllipsoidHeight(
259  double longitude,
260  double latitude,
261  double geoidHeight,
262  double *ellipsoidHeight );
263 
264 
265  /*
266  * The function convertEGM84TenDegBilinearToEllipsoidHeight
267  * converts the specified WGS84 geoid height at the specified
268  * geodetic coordinates to the equivalent ellipsoid height, using
269  * the EGM84 gravity model and
270  * the bilinear interpolation method.
271  *
272  * longitude : Geodetic longitude in radians (input)
273  * latitude : Geodetic latitude in radians (input)
274  * geoidHeight : Geoid height, in meters. (input)
275  * ellipsoidHeight : Ellipsoid height, in meters (output)
276  *
277  */
278 
279  void convertEGM84TenDegBilinearToEllipsoidHeight(
280  double longitude,
281  double latitude,
282  double geoidHeight,
283  double *ellipsoidHeight );
284 
285  /*
286  * The function convertEGM84TenDegNaturalSplineToEllipsoidHeight
287  * converts the specified WGS84 geoid height at the specified
288  * geodetic coordinates to the equivalent ellipsoid height,
289  * using the EGM84 gravity model and
290  * the natural spline interpolation method.
291  *
292  * longitude : Geodetic longitude in radians (input)
293  * latitude : Geodetic latitude in radians (input)
294  * geoidHeight : Geoid height, in meters. (input)
295  * ellipsoidHeight : Ellipsoid height, in meters (output)
296  *
297  */
298 
299  void convertEGM84TenDegNaturalSplineToEllipsoidHeight(
300  double longitude,
301  double latitude,
302  double geoidHeight,
303  double *ellipsoidHeight );
304 
305  /*
306  * The function convertEGM84ThirtyMinBiLinearToEllipsoidHeight
307  * converts the specified WGS84 geoid height at the specified
308  * geodetic coordinates to the equivalent ellipsoid height, using
309  * the EGM84 gravity model and the bilinear interpolation method.
310  *
311  * longitude : Geodetic longitude in radians (input)
312  * latitude : Geodetic latitude in radians (input)
313  * geoidHeight : Geoid height, in meters. (input)
314  * ellipsoidHeight : Ellipsoid height, in meters (output)
315  *
316  */
317 
318  void convertEGM84ThirtyMinBiLinearToEllipsoidHeight(
319  double longitude,
320  double latitude,
321  double geoidHeight,
322  double *ellipsoidHeight );
323 
324  /*
325  * The function convertEGM2008GeoidHeightToEllipsoidHeight(
326  * converts the specified EGM2008 geoid height at the specified
327  * geodetic coordinates to the equivalent ellipsoid height. It uses
328  * the EGM2008 gravity model, plus the bicubic spline interpolation method.
329  *
330  * longitude : Geodetic longitude in radians (input)
331  * latitude : Geodetic latitude in radians (input)
332  * geoidHeight : Height above the geoid, meters (input)
333  * ellipsoidHeight : Ellipsoid height, in meters (output)
334  */
335 
336  void convertEGM2008GeoidHeightToEllipsoidHeight(
337  double longitude,
338  double latitude,
339  double geoidHeight,
340  double *ellipsoidHeight );
341 
342  protected:
343 
344  /*
345  * The constructor creates empty lists which are used
346  * to store the geoid separation data
347  * contained in the data files egm84.grd and egm96.grd.
348  *
349  * The constructor now also instantiates the
350  * appropriate EGM2008 geoid separation interpolator.
351  */
352 
353  GeoidLibrary();
354 
355 
356  GeoidLibrary( const GeoidLibrary &gl );
357 
358 
359  GeoidLibrary& operator=( const GeoidLibrary &gl );
360 
361 
362  private:
363 
364  static CCSThreadMutex mutex;
365  static GeoidLibrary* instance;
366  static int instanceCount;
367 
368  /* List of EGM96 elevations */
369  float *egm96GeoidList;
370 
371  /* List of EGM84 elevations */
372  float *egm84GeoidList;
373 
374  /* List of EGM84 thirty minute elevations */
375  double *egm84ThirtyMinGeoidList;
376 
377  /* Pointer to EGM2008 interpolator object */
378 
379  Egm2008GeoidGrid* egm2008Geoid;
380 
381  /*
382  * The function loadGeoids reads geoid separation data from a file
383  * in the current directory and builds the geoid separation table
384  * from it.
385  * If the separation file can not be found or accessed, an
386  * error code of GEOID_FILE_OPEN_ERROR is returned,
387  * If the separation file is incomplete or improperly formatted,
388  * an error code of GEOID_INITIALIZE_ERROR is returned,
389  * otherwise GEOID_NO_ERROR is returned.
390  * This function must be called before
391  * any of the other functions in this component.
392  */
393 
394  void loadGeoids();
395 
396  /*
397  * The function initializeEGM96Geoid reads geoid separation data
398  * from the egm96.grd file in the current directory
399  * and builds a geoid separation table from it.
400  * If the separation file can not be found or accessed,
401  * an error code of GEOID_FILE_OPEN_ERROR is returned,
402  * If the separation file is incomplete or improperly formatted,
403  * an error code of GEOID_INITIALIZE_ERROR is returned,
404  * otherwise GEOID_NO_ERROR is returned.
405  */
406 
407  void initializeEGM96Geoid();
408 
409  /*
410  * The function initializeEGM84Geoid reads geoid separation data
411  * from a file in the current directory and builds
412  * the geoid separation table from it.
413  * If the separation file can not be found or accessed,
414  * an error code of GEOID_FILE_OPEN_ERROR is returned,
415  * If the separation file is incomplete or improperly formatted,
416  * an error code of GEOID_INITIALIZE_ERROR is returned,
417  * otherwise GEOID_NO_ERROR is returned.
418  */
419 
420  void initializeEGM84Geoid();
421 
422  /*
423  * The function initializeEGM84ThirtyMinGeoid reads geoid
424  * separation data from a file in the current directory and builds
425  * the geoid separation table from it.
426  * If the separation file can not be found or accessed,
427  * an error code of GEOID_FILE_OPEN_ERROR is returned,
428  * If the separation file is incomplete or improperly formatted,
429  * an error code of GEOID_INITIALIZE_ERROR is returned,
430  * otherwise GEOID_NO_ERROR is returned.
431  */
432 
433  void initializeEGM84ThirtyMinGeoid();
434 
435  /*
436  * The function initializeEGM2008Geoid
437  * instantiates one of two geoid-separation objects.
438  * The FULL_GRID interpolator reads the entire
439  * geoid-separation file into memory upon instantiation,
440  * while the AOI_GRID interpolator only reads the
441  * grid file's header into memory upon instantiation.
442  *
443  * The FULL_GRID interpolator builds its local interpolation
444  * windows from data contained in the worldwide, memory-resident,
445  * geoid separation grid. The AOI_GRID interpolator reads intermediate
446  * Area of Interest grids into memory before populating local interpolation
447  * windows. These AOI grids are much smaller than the EGM2008 worldwide grid,
448  * so they load quickly, and they permit high-resolution geoid separations to be
449  * computed even on small computer systems. AOI grids do not need to be reloaded
450  * into computer memory if all requested geoid separations are spatially localized.
451  * AOI grid reloads are automatic, and they require no action by GeoidLibrary users.
452  */
453 
454  void initializeEGM2008Geoid();
455 
456  /*
457  * The private function bilinearInterpolateDoubleHeights returns the
458  * height of the WGS84 geoid above or below the WGS84 ellipsoid,
459  * at the specified geodetic coordinates,
460  * using a grid of height adjustments
461  * and the bilinear interpolation method.
462  *
463  * longitude : Geodetic longitude in radians (input)
464  * latitude : Geodetic latitude in radians (input)
465  * scale_factor : Grid scale factor (input)
466  * num_cols : Number of columns in grid (input)
467  * num_rows : Number of rows in grid (input)
468  * height_buffer : Grid of height adjustments, doubles (input)
469  * delta_height : Height Adjustment, in meters. (output)
470  *
471  */
472 
473  void bilinearInterpolateDoubleHeights(
474  double longitude,
475  double latitude,
476  double scale_factor,
477  int num_cols,
478  int num_rows,
479  double *height_buffer,
480  double *delta_height );
481 
482  /*
483  * The private function bilinearInterpolate returns the height of
484  * the WGS84 geoid above or below the WGS84 ellipsoid, at the
485  * specified geodetic coordinates, using a grid of height
486  * adjustments and the bilinear interpolation method.
487  *
488  * longitude : Geodetic longitude in radians (input)
489  * latitude : Geodetic latitude in radians (input)
490  * scale_factor : Grid scale factor (input)
491  * num_cols : Number of columns in grid (input)
492  * num_rows : Number of rows in grid (input)
493  * height_buffer : Grid of height adjustments, floats (input)
494  * delta_height : Height Adjustment, in meters. (output)
495  *
496  */
497 
498  void bilinearInterpolate(
499  double longitude,
500  double latitude,
501  double scale_factor,
502  int num_cols,
503  int num_rows,
504  float *height_buffer,
505  double *delta_height );
506 
507  /*
508  * The private function naturalSplineInterpolate returns the
509  * height of the WGS84 geoid above or below the WGS84 ellipsoid,
510  * at the specified geodetic coordinates,
511  * using a grid of height adjustments
512  * and the natural spline interpolation method.
513  *
514  * longitude : Geodetic longitude in radians (input)
515  * latitude : Geodetic latitude in radians (input)
516  * scale_factor : Grid scale factor (input)
517  * num_cols : Number of columns in grid (input)
518  * num_rows : Number of rows in grid (input)
519  * height_buffer : Grid of height adjustments (input)
520  * DeltaHeight : Height Adjustment, in meters. (output)
521  *
522  */
523 
524  void naturalSplineInterpolate(
525  double longitude,
526  double latitude,
527  double scale_factor,
528  int num_cols,
529  int num_rows,
530  int max_index,
531  float *height_buffer,
532  double *delta_height );
533 
534  /*
535  * Delete the singleton.
536  */
537 
538  static void deleteInstance();
539  };
540  }
541 }
542 
543 #endif
544 
545 
546 // CLASSIFICATION: UNCLASSIFIED