UNCLASSIFIED
GeographicTranslator
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Friends Macros
egm2008_geoid_grid.h
Go to the documentation of this file.
1 
2 // CLASSIFICATION: UNCLASSIFIED
3 
5 // //
6 // File name: egm2008_geoid_grid.h //
7 // //
8 // Description of this module: //
9 // //
10 // Utility software that interpolates EGM 2008 //
11 // geoid heights from one of NGA's geoid height grids. //
12 // //
13 // This base class supports two geoid height interpolators: //
14 // //
15 // 1) the first one reads the entire worldwide EGM2008 grid //
16 // before interpolating any geoid heights from the worldwide grid; //
17 // 2) the second one does not read geoid height data from //
18 // file until a user requests that a geoid height be computed; //
19 // the 2nd interpolator then reads an Area of Interest //
20 // (AOI) grid from file before interpolating from the AOI grid; //
21 // the Area of Interest grid is refreshed, if needed, //
22 // when users submit subsequent geoid height requests. //
23 // //
24 // Revision History: //
25 // Date Name Description //
26 // ----------- ------------ ----------------------------------------------//
27 // 19 Nov 2010 RD Craig Release //
28 // 11 Feg 2011 RD Craig Upgrades following code review //
29 // 30 May 2013 RD Craig MSP 1.3: ER29758 //
30 // Added second constructor to //
31 // permit multiple geoid-height grids //
32 // when assessing relative interpolation errors. //
33 // //
35 
36 #ifndef EGM2008_GEOID_GRID_H
37 #define EGM2008_GEOID_GRID_H
38 
39 // This file declares a base C++ class
40 // that supports geoid height interpolation
41 // from one of NGA's EGM 2008 geoid height files.
42 
43 // EGM2008_GEOID_GRID IS A PURE VIRTUAL CLASS.
44 
45 // Note: Following common usage, this class uses the term
46 // "geoid height" to mean heights of the geoid above or
47 // below the earth ellipsoid. The GeoidLibrary class confuses
48 // the term "geoid height" with height of a point above or below
49 // the geoid: these heights are properly called "orthometric heights".
50 
51 #include <string>
52 
53 #include "CCSThreadMutex.h"
54 
55 namespace MSP
56 {
57 
58  class Egm2008GeoidGrid {
59 
60  protected:
61 
62  // MAX_WSIZE: The maximum number of rows and
63  // columns in a local interpolation window.
64 
65  int MAX_WSIZE;
66 
67  // gridFname: A string containing
68  // the file name for one of
69  // NGA's reformatted geoid height grids.
70 
71  std::string _gridFname;
72 
73  // nGridPad: The number of grid cells added to
74  // the left, right, top, and bottom sides
75  // of the worldwide EGM2008 geoid height grid;
76  // interpolation window size is related to _nGridPad;
77  // an ExE grid, where E is an even number, requires at
78  // least _nGridPad = int( E - 2 ) / 2 ) rows/cols of pad;
79  // an OxO grid, where O is an odd number, requires at
80  // least _nGridPad = int( O / 2 ) rows/cols of pad on each edge.
81 
82  int _nGridPad;
83 
84  // nGridRows: The number of latitude rows contained in
85  // the padded, memory-resident world-wide grid.
86 
87  int _nGridRows;
88 
89  // nGridCols: The number of longitude entries per
90  // row in the padded, memory-resident grid.
91 
92  int _nGridCols;
93 
94  // nOrigRows: The number of latitude rows
95  // contained in the world-wide grid file.
96 
97  int _nOrigRows;
98 
99  // nOrigCols: The number of longitude entries per
100  // latitude row in the world-wide grid file.
101 
102  int _nOrigCols;
103 
104  // baseLatitude: The padded grid's base latitude
105  // (radians); baseLatitude will be less than
106  // -PI/2 radians for the world-wide EGM 2008 grid.
107 
108  double _baseLatitude;
109 
110  // baseLongitude: The padded grid's base longitude
111  // (radians); baseLongitude will be less than
112  // zero radians for the world-wide EGM 2008 grid.
113 
114  double _baseLongitude;
115 
116  // dLat: Grid's latitude spacing (radians).
117 
118  double _dLat;
119 
120  // dLon: Grid's longitude spacing (radians).
121 
122  double _dLon;
123 
124  // mutex: A CCSThreadMutex object used to ensure thread safety.
125 
126  MSP::CCSThreadMutex _mutex;
127 
128  public:
129 
130  // Basic functions .....
131 
132  Egm2008GeoidGrid( void );
133 
134  Egm2008GeoidGrid( const std::string &gridFname ); // new 5/30/2013
135 
136  Egm2008GeoidGrid( const Egm2008GeoidGrid& oldGrid );
137 
138  virtual
139  ~Egm2008GeoidGrid( void );
140 
141  Egm2008GeoidGrid&
142  operator = ( const Egm2008GeoidGrid& oldGrid );
143 
144  // User functions .....
145 
146  /*
147  * Public function geoidHeight implements
148  * a bicubic spline geoid separation interpolator.
149  *
150  * wSize : Number of rows (= # columns) ( input )
151  * in the local interpolation window;
152  * the function supports 2 <= wSize <= 20,
153  * but EGM 2008 interpolations use wSize = 6.
154  * latitude : Geodetic latitude ( input - radians )
155  * longitude : Geodetic longitude ( input - radians )
156  * gHeight : Geoid height ( output - meters )
157  *
158  * return value : The function's error flag;
159  * errors = 0 ..... no errors encountered,
160  * errors = 1 ..... at least one error encountered.
161  *
162  */
163 
164  virtual int
165  geoidHeight(
166  int wSize, // input
167  double latitude, // input
168  double longitude, // input
169  double& gHeight ) = 0; // output
170 
171  protected:
172 
173  /*
174  * Protected function geoidHeight
175  * implements a bilinear geoid separation interpolator.
176  * Exercise this function when the requested interpolation
177  * window size is too small to support bicubic spline interpolation.
178  *
179  * latitude : Geodetic latitude ( input - radians )
180  * longitude : Geodetic longitude ( input - radians )
181  * gHeight : Geoid height ( output - meters )
182  *
183  * return value : The function's error flag;
184  * errors = 0 ..... no errors encountered,
185  * errors = 1 ..... at least one error encountered.
186  */
187 
188  virtual int
189  geoidHeight(
190  double latitude, // input
191  double longitude, // input
192  double& gHeight ) = 0; // output
193 
194  /*
195  * Protected function loadGridCoords finds
196  * horizontal coordinates corresponding to
197  * grid row and column indices. The indices must
198  * be referenced to the worldwide geoid height grid.
199  *
200  * i : An index to a worldwide grid ( input )
201  * intersection's row of interest.
202  * j : An index to a worldwide grid ( input )
203  * intersection's column of interest.
204  * latitude : Geodetic latitude ( output - radians )
205  * longitude : Geodetic longitude ( output - radians )
206  *
207  * return value : The function's error flag;
208  * errors = 0 ..... no errors encountered,
209  * errors = 1 ..... at least one error encountered.
210  */
211 
212  int
213  loadGridCoords(
214  int i, // input
215  int j, // input
216  double& latitude, // output
217  double& longitude ); // output
218 
219  /*
220  * Protected function initSpline computes the
221  * geoid separation posts' 2nd derivatives. This
222  * function assumes the posts are arranged in a row,
223  * it assumes the posts are equally spaced, and it also
224  * assumes the spline's 2nd derivatives are zero at the endpoints.
225  * The computed 2nd derivatives support the 1D spline interpolator.
226  *
227  * n : Number of geoid height posts for ( input )
228  * which 2nd derivatives are computed.
229  * posts[] : An array containing ( input )
230  * geoid height posts' ordinates.
231  * moments[] : An array containing geoid
232  * height posts' 2nd derivatives. ( output )
233  *
234  * return value : The function's error flag;
235  * errors = 0 ..... no errors encountered,
236  * errors = 1 ..... at least one error encountered.
237  */
238 
239  int
240  initSpline(
241  int n, // input
242  const double posts[], // input
243  double moments[] ); // output
244 
245  /*
246  * Protected function spline implements a
247  * low-level one-dimensional spline interpolator.
248  *
249  * n : Number of geoid height posts for ( input )
250  * which 2nd derivatives are computed.
251  * x : Abscissa at which ( input )
252  * interpolation is to occur;
253  * x is measured in grid intervals,
254  * and it is measured relative to the
255  * first geoid separation post's position.
256  * posts[] : An array containing ( input )
257  * geoid separation posts' ordinates.
258  * moments[] : An array containing geoid
259  * separation posts' 2nd derivatives.( input )
260  *
261  * return value : The interpolated geoid height ( meters ).
262  */
263 
264  double
265  spline(
266  int n, // input
267  double x, // input
268  const double posts[], // input
269  const double moments[] ); // input
270 
271  /*
272  * Protected function swapBytes swaps
273  * bytes when transforming binary numbers
274  * between BIG-ENDIAN and LITTLE-ENDIAN formats.
275  *
276  * buffer : Pointer to binary data item(s) ( input & output )
277  * size : Size of each binary number ( input - bytes )
278  * count : Number of binary numbers ( input )
279  */
280 
281  void
282  swapBytes(
283  void* buffer, // input & output
284  size_t size, // input
285  size_t count ); // input
286 
287  /*
288  * Protected function swGridIndices computes
289  * grid row & column indices for the intersection
290  * immediately to the SOUTHWEST of the input point.
291  * The indices refer to the worldwide geoid height grid.
292  *
293  * latitude : Geodetic latitude ( input - radians )
294  * longitude : Geodetic longitude ( input - radians )
295  * i : Row number for the ( output )
296  * worldwide grid intersection
297  * Southwest of the point of interest.
298  * j : Column number for the ( output )
299  * worldwide grid intersection
300  * Southwest of the point of interest.
301  *
302  * return value : The function's error flag;
303  * errors = 0 ..... no errors encountered,
304  * errors = 1 ..... at least one error encountered.
305  */
306 
307  int
308  swGridIndices(
309  double latitude, // input
310  double longitude, // input
311  int& i, // output
312  int& j ); // output
313 
314  }; // End of Egm2008GeoidGrid class declaration
315 
316 } // End of namespace block
317 
318 #endif
319 
320 // CLASSIFICATION: UNCLASSIFIED
321 
Generated on Tue Feb 16 2016 14:54:02 for GeographicTranslator by doxygen 1.8.2