UNCLASSIFIED
GeographicTranslator
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Friends Macros
DatumLibrary.h
Go to the documentation of this file.
1 // CLASSIFICATION: UNCLASSIFIED
2 
3 #ifndef DatumLibrary_H
4 #define DatumLibrary_H
5 
6 /***************************************************************************/
7 /* RSC IDENTIFIER: Datum Library
8  *
9  * ABSTRACT
10  *
11  * This component provides datum shifts for a large collection of local
12  * datums, WGS72, and WGS84. A particular datum can be accessed by using its
13  * standard 5-letter code to find its index in the datum table. The index
14  * can then be used to retrieve the name, type, ellipsoid code, and datum
15  * shift parameters, and to perform shifts to or from that datum.
16  *
17  * By sequentially retrieving all of the datum codes and/or names, a menu
18  * of the available datums can be constructed. The index values resulting
19  * from selections from this menu can then be used to access the parameters
20  * of the selected datum, or to perform datum shifts involving that datum.
21  *
22  * This component supports both 3-parameter local datums, for which only X,
23  * Y, and Z translations relative to WGS 84 have been defined, and
24  * 7-parameter local datums, for which X, Y, and Z rotations, and a scale
25  * factor, are also defined. It also includes entries for WGS 84 (with an
26  * index of 0), and WGS 72 (with an index of 1), but no shift parameter
27  * values are defined for these.
28  *
29  * This component provides datum shift functions for both geocentric and
30  * geodetic coordinates. WGS84 is used as an intermediate state when
31  * shifting from one local datum to another. When geodetic coordinates are
32  * given Molodensky's method is used, except near the poles where the 3-step
33  * step method is used instead. Specific algorithms are used for shifting
34  * between WGS72 and WGS84.
35  *
36  * This component depends on two data files, named 3_param.dat and
37  * 7_param.dat, which contain the datum parameter values. Copies of these
38  * files must be located in the directory specified by the value of the
39  * environment variable "MSPCCS_DATA", if defined, or else in the current
40  * directory whenever a program containing this component is executed.
41  *
42  * Additional datums can be added to these files, either manually or using
43  * the Create_Datum function. However, if a large number of datums are
44  * added, the datum table array sizes in this component will have to be
45  * increased.
46  *
47  * This component depends on two other components: the Ellipsoid component
48  * for access to ellipsoid parameters; and the Geocentric component for
49  * conversions between geodetic and geocentric coordinates.
50  *
51  * ERROR HANDLING
52  *
53  * This component checks for input file errors and input parameter errors.
54  * If an invalid value is found, the error code is combined with the current
55  * error code using the bitwise or. This combining allows multiple error
56  * codes to be returned. The possible error codes are:
57  *
58  * DATUM_NO_ERROR : No errors occurred in function
59  * DATUM_NOT_INITIALIZED_ERROR : Datum module has not been initialized
60  * DATUM_7PARAM_FILE_OPEN_ERROR : 7 parameter file opening error
61  * DATUM_7PARAM_FILE_PARSING_ERROR : 7 parameter file structure error
62  * DATUM_3PARAM_FILE_OPEN_ERROR : 3 parameter file opening error
63  * DATUM_3PARAM_FILE_PARSING_ERROR : 3 parameter file structure error
64  * DATUM_INVALID_INDEX_ERROR : Index out of valid range (less than one
65  * or more than Number_of_Datums)
66  * DATUM_INVALID_SRC_INDEX_ERROR : Source datum index invalid
67  * DATUM_INVALID_DEST_INDEX_ERROR : Destination datum index invalid
68  * DATUM_INVALID_CODE_ERROR : Datum code not found in table
69  * DATUM_LAT_ERROR : Latitude out of valid range (-90 to 90)
70  * DATUM_LON_ERROR : Longitude out of valid range (-180 to
71  * 360)
72  * DATUM_SIGMA_ERROR : Standard error values must be positive
73  * (or -1 if unknown)
74  * DATUM_DOMAIN_ERROR : Domain of validity not well defined
75  * DATUM_ELLIPSE_ERROR : Error in ellipsoid module
76  * DATUM_NOT_USERDEF_ERROR : Datum code is not user defined - cannot
77  * be deleted
78  *
79  *
80  * REUSE NOTES
81  *
82  * Datum is intended for reuse by any application that needs access to
83  * datum shift parameters relative to WGS 84.
84  *
85  *
86  * REFERENCES
87  *
88  * Further information on Datum can be found in the Reuse Manual.
89  *
90  * Datum originated from : U.S. Army Topographic Engineering Center (USATEC)
91  * Geospatial Information Division (GID)
92  * 7701 Telegraph Road
93  * Alexandria, VA 22310-3864
94  *
95  * LICENSES
96  *
97  * None apply to this component.
98  *
99  * RESTRICTIONS
100  *
101  * Datum has no restrictions.
102  *
103  * ENVIRONMENT
104  *
105  * Datum was tested and certified in the following environments:
106  *
107  * 1. Solaris 2.5 with GCC 2.8.1
108  * 2. MS Windows 95 with MS Visual C++ 6
109  *
110  * MODIFICATIONS
111  *
112  * Date Description
113  * ---- -----------
114  * 11/20/08 Original Code
115  * 05/26/10 S. Gillis, BAEts26674, Added Validate Datum to the API
116  * in MSP Geotrans 3.0
117  * 07/01/10 S. Gillis, BAEts26676, Fixed the error always returned
118  * when calling CCS API getDatumParamters
119  */
120 
121 
122 #include "DatumType.h"
123 #include "DtccApi.h"
124 
125 
126 
127 namespace MSP
128 {
129  namespace CCS
130  {
131  class DatumLibraryImplementation;
132 
133  class MSP_DTCC_API DatumLibrary
134  {
135  public:
136 
137  /*
138  * The constructor creates an empty list to store the datum information
139  * contained in two external files, 3_param.dat and 7_param.dat.
140  */
141 
142  DatumLibrary( DatumLibraryImplementation* __datumLibraryImplementation );
143 
144 
145  DatumLibrary( const DatumLibrary &d );
146 
147 
148  DatumLibrary& operator=( const DatumLibrary &d );
149 
150 
151  ~DatumLibrary( void );
152 
153 
154  /* The function defineDatum creates a new local (3 or 7-parameter) datum with the
155  * specified code, name, shift values, and standard error values or rotation and scale factor values.
156  * If the datum table has not been initialized, the specified code is already in use,
157  * or a new version of the 3-param.dat or 7-param.dat file cannot be created, an
158  * exception is thrown. Note that the indexes
159  * of all datums in the datum table may be changed by this function.
160  *
161  * datumType : Specifies 3 parameter or 7 parameter datum (input)
162  * datumCode : 5-letter new datum code. (input)
163  * datumName : Name of the new datum (input)
164  * ellipsoidCode : 2-letter code for the associated ellipsoid (input)
165  * deltaX : X translation to WGS84 in meters (input)
166  * deltaY : Y translation to WGS84 in meters (input)
167  * deltaZ : Z translation to WGS84 in meters (input)
168  * sigmaX : Standard error in X in meters (input)
169  * sigmaY : Standard error in Y in meters (input)
170  * sigmaZ : Standard error in Z in meters (input)
171  * westLongitude : Western edge of validity rectangle in radians (input)
172  * eastLongitude : Eastern edge of validity rectangle in radians (input)
173  * southLatitude : Southern edge of validity rectangle in radians(input)
174  * northLatitude : Northern edge of validity rectangle in radians(input)
175  * rotationX : X rotation to WGS84 in arc seconds (input)
176  * rotationY : Y rotation to WGS84 in arc seconds (input)
177  * rotationZ : Z rotation to WGS84 in arc seconds (input)
178  * scalefactor : Scale factor (input)
179  *
180  */
181 
182  void defineDatum( const int datumType, const char *datumCode, const char *datumName, const char *ellipsoidCode,
183  double deltaX, double deltaY, double deltaZ,
184  double sigmaX, double sigmaY, double sigmaZ,
185  double westLongitude, double eastLongitude, double southLatitude, double northLatitude,
186  double rotationX, double rotationY, double rotationZ, double scaleFactor);
187 
188 
189  /*
190  * The function removeDatum deletes a local (3-parameter) datum with the
191  * specified code. If the datum table has not been initialized or a new
192  * version of the 3-param.dat file cannot be created, an exception is thrown.
193  * Note that the indexes of all datums
194  * in the datum table may be changed by this function.
195  *
196  * code : 5-letter datum code. (input)
197  *
198  */
199 
200  void removeDatum( const char* code );
201 
202 
203  /*
204  * The function datumCode returns the 5-letter code of the datum
205  * referenced by index.
206  *
207  * index : The index of a given datum in the datum table. (input)
208  * code : The datum Code of the datum referenced by Index. (output)
209  */
210 
211  void datumCode( const long index, char *code );
212 
213 
214  /*
215  * The function getDatumCount returns the number of Datums in the table
216  * if the table was initialized without error.
217  *
218  * count : number of datums in the datum table (output)
219  */
220 
221  void getDatumCount( long *count );
222 
223 
224  /*
225  * The function getDatumIndex returns the index of the datum with the
226  * specified code.
227  *
228  * code : The datum code being searched for. (input)
229  * index : The index of the datum in the table with the (output)
230  * specified code.
231  */
232 
233  void getDatumIndex( const char *code, long *index );
234 
235 
236  /*
237  * The function getDatumInfo returns the 5-letter code, name and
238  * 2-letter ellipsoid code of the datum referenced by index.
239  *
240  * index : The index of a given datum in the datum table. (input)
241  * code : The datum Code of the datum referenced by Index. (output)
242  * name : The datum Name of the datum referenced by Index. (output)
243  * ellipsoidCode : The ellipsoid code for the ellipsoid associated with (output)
244  * the datum referenced by index.
245  */
246 
247  void getDatumInfo( const long index, char *code, char *name, char *ellipsoidCode );
248 
249 
250  /*
251  * The function getDatumParameters returns the following datum parameters
252  * (specified as output parameters below): datumType, deltaX, deltaY,
253  * deltaZ, sigmaX, sigmaY, sigmaZ, westLongitude, eastLongitude,
254  * southLatitude, northLatitude, rotationX, rotationY, rotationZ, and
255  * scaleFactor.
256  *
257  * sigmaX, sigmaY, and sigmaZ only apply to 3 parameter datum and will be
258  * set to 0 if the datum type is a 7 parameter datum.
259  *
260  * rotationX, rotationY, rotationZ, and scaleFactor only apply to 7
261  * parameter datum and will be set to 0 if the datum type is a 3
262  * parameter datum.
263  *
264  * If the datum type is neither a 3 parameter datum nor a 7 parameter
265  * datum, a CoordinateConversionException will be thrown.
266  *
267  * index : The index of a given datum in the datum table (input)
268  * datumType : Specifies datum type (output)
269  * deltaX : X translation to WGS84 in meters (output)
270  * deltaY : Y translation to WGS84 in meters (output)
271  * deltaZ : Z translation to WGS84 in meters (output)
272  * sigmaX : Standard error in X in meters (output)
273  * sigmaY : Standard error in Y in meters (output)
274  * sigmaZ : Standard error in Z in meters (output)
275  * westLongitude : Western edge of validity rectangle in radians (output)
276  * eastLongitude : Eastern edge of validity rectangle in radians (output)
277  * southLatitude : Southern edge of validity rectangle in radians (output)
278  * northLatitude : Northern edge of validity rectangle in radians (output)
279  * rotationX : X rotation to WGS84 in arc seconds (output)
280  * rotationY : Y rotation to WGS84 in arc seconds (output)
281  * rotationZ : Z rotation to WGS84 in arc seconds (output)
282  * scaleFactor : Scale factor (output)
283  */
284 
285  void getDatumParameters( const long index, DatumType::Enum *datumType, double *deltaX, double *deltaY, double *deltaZ,
286  double *sigmaX, double *sigmaY, double *sigmaZ,
287  double *westLongitude, double *eastLongitude, double *southLatitude, double *northLatitude,
288  double *rotationX, double *rotationY, double *rotationZ, double *scaleFactor );
289 
290 
291  /*
292  * The function datumValidRectangle returns the edges of the validity
293  * rectangle for the datum referenced by index.
294  *
295  * index : The index of a given datum in the datum table (input)
296  * westLongitude : Western edge of validity rectangle in radians (output)
297  * eastLongitude : Eastern edge of validity rectangle in radians (output)
298  * southLatitude : Southern edge of validity rectangle in radians (output)
299  * northLatitude : Northern edge of validity rectangle in radians (output)
300  *
301  */
302 
303  void getDatumValidRectangle( const long index, double *westLongitude, double *eastLongitude, double *southLatitude, double *northLatitude );
304 
305  /*
306  * The function validDatum checks whether or not the specified location
307  * is within the validity rectangle for the specified datum. It returns
308  * zero if the specified location is NOT within the validity rectangle,
309  * and returns 1 otherwise.
310  *
311  * index : The index of a given datum in the datum table (input)
312  * latitude : Latitude of the location to be checked in radians (input)
313  * longitude : Longitude of the location to be checked in radians (input)
314  * result : Indicates whether location is inside (1) or outside (0)
315  * of the validity rectangle of the specified datum (output)
316  */
317 
318  void validDatum( const long index, double longitude, double latitude,
319  long *result );
320 
321  private:
322 
323  DatumLibraryImplementation* _datumLibraryImplementation;
324 
325  };
326  }
327 }
328 
329 #endif
330 
331 
332 // CLASSIFICATION: UNCLASSIFIED
Generated on Tue Feb 16 2016 14:54:02 for GeographicTranslator by doxygen 1.8.2