UNCLASSIFIED

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