OSSIM - Open Source Software Image Map  Version 1.9.0 (20180803)
datum.h
Go to the documentation of this file.
1 #ifndef DATUM_H
2 #define DATUM_H
3 
4 /***************************************************************************/
5 /* RSC IDENTIFIER: Datum
6  *
7  * ABSTRACT
8  *
9  * This component provides datum shifts for a large collection of local
10  * datums, WGS72, and WGS84. A particular datum can be accessed by using its
11  * standard 5-letter code to find its index in the datum table. The index
12  * can then be used to retrieve the name, type, ellipsoid code, and datum
13  * shift parameters, and to perform shifts to or from that datum.
14  *
15  * By sequentially retrieving all of the datum codes and/or names, a menu
16  * of the available datums can be constructed. The index values resulting
17  * from selections from this menu can then be used to access the parameters
18  * of the selected datum, or to perform datum shifts involving that datum.
19  *
20  * This component supports both 3-parameter local datums, for which only X,
21  * Y, and Z translations relative to WGS 84 have been defined, and
22  * 7-parameter local datums, for which X, Y, and Z rotations, and a scale
23  * factor, are also defined. It also includes entries for WGS 84 (with an
24  * index of 0), and WGS 72 (with an index of 1), but no shift parameter
25  * values are defined for these.
26  *
27  * This component provides datum shift functions for both geocentric and
28  * geodetic coordinates. WGS84 is used as an intermediate state when
29  * shifting from one local datum to another. When geodetic coordinates are
30  * given Molodensky's method is used, except near the poles where the 3-step
31  * step method is used instead. Specific algorithms are used for shifting
32  * between WGS72 and WGS84.
33  *
34  * This component depends on two data files, named 3_param.dat and
35  * 7_param.dat, which contain the datum parameter values. Copies of these
36  * files must be located in the directory specified by the value of the
37  * environment variable "DATUM_DATA", if defined, or else in the current
38  * directory whenever a program containing this component is executed.
39  *
40  * Additional datums can be added to these files, either manually or using
41  * the Create_Datum function. However, if a large number of datums are
42  * added, the datum table array sizes in this component will have to be
43  * increased.
44  *
45  * This component depends on two other components: the Ellipsoid component
46  * for access to ellipsoid parameters; and the Geocentric component for
47  * conversions between geodetic and geocentric coordinates.
48  *
49  * ERROR HANDLING
50  *
51  * This component checks for input file errors and input parameter errors.
52  * If an invalid value is found, the error code is combined with the current
53  * error code using the bitwise or. This combining allows multiple error
54  * codes to be returned. The possible error codes are:
55  *
56  * DATUM_NO_ERROR : No errors occurred in function
57  * DATUM_NOT_INITIALIZED_ERROR : Datum module has not been initialized
58  * DATUM_7PARAM_FILE_OPEN_ERROR : 7 parameter file opening error
59  * DATUM_7PARAM_FILE_PARSING_ERROR : 7 parameter file structure error
60  * DATUM_7PARAM_OVERFLOW_ERROR : 7 parameter table overflow
61  * DATUM_3PARAM_FILE_OPEN_ERROR : 3 parameter file opening error
62  * DATUM_3PARAM_FILE_PARSING_ERROR : 3 parameter file structure error
63  * DATUM_3PARAM_OVERFLOW_ERROR : 3 parameter table overflow
64  * DATUM_INVALID_INDEX_ERROR : Index out of valid range (less than one
65  * or more than Datum_Count)
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  *
77  *
78  * REUSE NOTES
79  *
80  * Datum is intended for reuse by any application that needs access to
81  * datum shift parameters relative to WGS 84.
82  *
83  *
84  * REFERENCES
85  *
86  * Further information on Datum can be found in the Reuse Manual.
87  *
88  * Datum originated from : U.S. Army Topographic Engineering Center (USATEC)
89  * Geospatial Information Division (GID)
90  * 7701 Telegraph Road
91  * Alexandria, VA 22310-3864
92  *
93  * LICENSES
94  *
95  * None apply to this component.
96  *
97  * RESTRICTIONS
98  *
99  * Datum has no restrictions.
100  *
101  * ENVIRONMENT
102  *
103  * Datum was tested and certified in the following environments:
104  *
105  * 1. Solaris 2.5 with GCC 2.8.1
106  * 2. MS Windows 95 with MS Visual C++ 6
107  *
108  * MODIFICATIONS
109  *
110  * Date Description
111  * ---- -----------
112  * 03/30/97 Original Code
113  * 05/28/99 Added user-definable datums (for JMTK)
114  * Added datum domain of validity checking (for JMTK)
115  * Added datum shift accuracy calculation (for JMTK)
116  */
117 
118 
119 /***************************************************************************/
120 /*
121  * DEFINES
122  */
123 
124 #define DATUM_NO_ERROR 0x0000
125 #define DATUM_NOT_INITIALIZED_ERROR 0x0001
126 #define DATUM_7PARAM_FILE_OPEN_ERROR 0x0002
127 #define DATUM_7PARAM_FILE_PARSING_ERROR 0x0004
128 #define DATUM_7PARAM_OVERFLOW_ERROR 0x0008
129 #define DATUM_3PARAM_FILE_OPEN_ERROR 0x0010
130 #define DATUM_3PARAM_FILE_PARSING_ERROR 0x0020
131 #define DATUM_3PARAM_OVERFLOW_ERROR 0x0040
132 #define DATUM_INVALID_INDEX_ERROR 0x0080
133 #define DATUM_INVALID_SRC_INDEX_ERROR 0x0100
134 #define DATUM_INVALID_DEST_INDEX_ERROR 0x0200
135 #define DATUM_INVALID_CODE_ERROR 0x0400
136 #define DATUM_LAT_ERROR 0x0800
137 #define DATUM_LON_ERROR 0x1000
138 #define DATUM_SIGMA_ERROR 0x2000
139 #define DATUM_DOMAIN_ERROR 0x4000
140 #define DATUM_ELLIPSE_ERROR 0x8000
141 
142 
143 /***************************************************************************/
144 /*
145  * GLOBAL DECLARATIONS
146  */
147 typedef enum Datum_Types
148 {
149  Three_Param_Datum,
150  Seven_Param_Datum,
151  WGS84_Datum,
152  WGS72_Datum
153 } Datum_Type; /* different types of datums */
154 
155 
156 /***************************************************************************/
157 /*
158  * FUNCTION PROTOTYPES
159  */
160 
161 /* ensure proper linkage to c++ programs */
162 #ifdef __cplusplus
163 extern "C" {
164 #endif
165 
166  long Initialize_Datums(void);
167 /*
168  * The function Initialize_Datums creates the datum table from two external
169  * files. If an error occurs, the initialization stops and an error code is
170  * returned. This function must be called before any of the other functions
171  * in this component.
172  */
173 
174 
175  long Create_Datum ( const char *Code,
176  const char *Name,
177  const char *Ellipsoid_Code,
178  double Delta_X,
179  double Delta_Y,
180  double Delta_Z,
181  double Sigma_X,
182  double Sigma_Y,
183  double Sigma_Z,
184  double South_latitude,
185  double North_latitude,
186  double West_longitude,
187  double East_longitude);
188 /*
189  * Code : 5-letter new datum code. (input)
190  * Name : Name of the new datum (input)
191  * Ellipsoid_Code : 2-letter code for the associated ellipsoid (input)
192  * Delta_X : X translation to WGS84 in meters (input)
193  * Delta_Y : Y translation to WGS84 in meters (input)
194  * Delta_Z : Z translation to WGS84 in meters (input)
195  * Sigma_X : Standard error in X in meters (input)
196  * Sigma_Y : Standard error in Y in meters (input)
197  * Sigma_Z : Standard error in Z in meters (input)
198  * South_latitude : Southern edge of validity rectangle in radians(input)
199  * North_latitude : Northern edge of validity rectangle in radians(input)
200  * West_longitude : Western edge of validity rectangle in radians (input)
201  * East_longitude : Eastern edge of validity rectangle in radians (input)
202  *
203  * The function Create_Datum creates a new local (3-parameter) datum with the
204  * specified code, name, shift values, and standard error values. If the
205  * datum table has not been initialized, the specified code is already in use,
206  * or a new version of the 3-param.dat file cannot be created, an error code
207  * is returned, otherwise DATUM_NO_ERROR is returned. Note that the indexes
208  * of all datums in the datum table may be changed by this function.
209  */
210 
211 
212  long Datum_Count ( long *Count );
213 /*
214  * The function Datum_Count returns the number of Datums in the table
215  * if the table was initialized without error.
216  *
217  * Count : number of datums in the datum table (output)
218  */
219 
220 
221  long Datum_Index ( const char *Code,
222  long *Index );
223 /*
224  * The function Datum_Index returns the index of the datum with the
225  * specified code.
226  *
227  * Code : The datum code being searched for (input)
228  * Index : The index of the datum in the table with the (output)
229  * specified code
230  */
231 
232 
233  long Datum_Code ( const long Index,
234  char *Code );
235 /*
236  * The function Datum_Code returns the 5-letter code of the datum
237  * referenced by index.
238  *
239  * Index : The index of a given datum in the datum table (input)
240  * Code : The datum code of the datum referenced by index (output)
241  */
242 
243 
244  long Datum_Name ( const long Index,
245  char *Name );
246 /*
247  * The function Datum_Name returns the name of the datum referenced by
248  * index.
249  *
250  * Index : The index of a given datum in the datum table (input)
251  * Name : The datum name of the datum referenced by index (output)
252  */
253 
254 
255  long Datum_Ellipsoid_Code ( const long Index,
256  char *Code );
257 /*
258  * The function Datum_Ellipsoid_Code returns the 2-letter ellipsoid code
259  * for the ellipsoid associated with the datum referenced by index.
260  *
261  * Index : The index of a given datum in the datum table (input)
262  * Code : The ellisoid code for the ellipsoid associated with the (output)
263  * datum referenced by index
264  */
265 
266 
267  long Get_Datum_Type ( const long Index,
268  Datum_Type *Type );
269 /*
270  * The function Get_Datum_Type returns the type of the datum referenced by
271  * index.
272  *
273  * Index : The index of a given datum in the datum table (input)
274  * Type : The type of the datum referenced by index (output)
275  */
276 
277 
278  long Datum_Seven_Parameters ( const long Index,
279  double *Delta_X,
280  double *Delta_Y,
281  double *Delta_Z,
282  double *Rx,
283  double *Ry,
284  double *Rz,
285  double *Scale_Factor );
286 /*
287  * The function Datum_Seven_Parameters returns the seven parameters
288  * for the datum referenced by index.
289  *
290  * Index : The index of a given datum in the datum table (input)
291  * Delta_X : X translation in meters (output)
292  * Delta_Y : Y translation in meters (output)
293  * Delta_Z : Z translation in meters (output)
294  * Rx : X rotation in radians (output)
295  * Rx : Y rotation in radians (output)
296  * Ry : Z rotation in radians (output)
297  * Scale_Factor : Scale factor (output)
298  */
299 
300 
301  long Datum_Three_Parameters ( const long Index,
302  double *Delta_X,
303  double *Delta_Y,
304  double *Delta_Z);
305 /*
306  * The function Datum_Three_Parameters returns the three parameters
307  * for the datum referenced by index.
308  *
309  * Index : The index of a given datum in the datum table (input)
310  * Delta_X : X translation in meters (output)
311  * Delta_Y : Y translation in meters (output)
312  * Delta_Z : Z translation in meters (output)
313  */
314 
315 
316  long Datum_Errors ( const long Index,
317  double *Sigma_X,
318  double *Sigma_Y,
319  double *Sigma_Z);
320 /*
321  * The function Datum_Errors returns the standard errors in X,Y, & Z
322  * for the datum referenced by index.
323  *
324  * Index : The index of a given datum in the datum table (input)
325  * Sigma_X : Standard error in X in meters (output)
326  * Sigma_Y : Standard error in Y in meters (output)
327  * Sigma_Z : Standard error in Z in meters (output)
328  */
329 
330 
331  long Datum_Valid_Rectangle ( const long Index,
332  double *South_latitude,
333  double *North_latitude,
334  double *West_longitude,
335  double *East_longitude);
336 /*
337  * The function Datum_Valid_Rectangle returns the edges of the validity
338  * rectangle for the datum referenced by index.
339  *
340  * Index : The index of a given datum in the datum table (input)
341  * South_latitude : Southern edge of validity rectangle in radians (input)
342  * North_latitude : Northern edge of validity rectangle in radians (input)
343  * West_longitude : Western edge of validity rectangle in radians (input)
344  * East_longitude : Eastern edge of validity rectangle in radians (input)
345  */
346 
347 
348  long Valid_Datum ( const long Index,
349  double latitude,
350  double longitude,
351  long *result);
352 /*
353  * This function checks whether or not the specified location is within the
354  * validity rectangle for the specified datum. It returns zero if the specified
355  * location is NOT within the validity rectangle, and returns 1 otherwise.
356  *
357  * Index : The index of a given datum in the datum table (input)
358  * latitude : Latitude of the location to be checked in radians (input)
359  * longitude : Longitude of the location to be checked in radians (input)
360  * result : Indicates whether location is inside (1) or outside (0)
361  * of the validity rectangle of the specified datum (output)
362  */
363 
364 
365  long Geocentric_Shift_To_WGS84 (const long Index,
366  const double X,
367  const double Y,
368  const double Z,
369  double *X_WGS84,
370  double *Y_WGS84,
371  double *Z_WGS84);
372 /*
373  * This function shifts a geocentric coordinate (X, Y, Z in meters) relative
374  * to the datum referenced by index to a geocentric coordinate (X, Y, Z in
375  * meters) relative to WGS84.
376  *
377  * Index : Index of local datum (input)
378  * X : X coordinate relative to the source datum (input)
379  * Y : Y coordinate relative to the source datum (input)
380  * Z : Z coordinate relative to the source datum (input)
381  * X_WGS84 : X coordinate relative to WGS84 (output)
382  * Y_WGS84 : Y coordinate relative to WGS84 (output)
383  * Z_WGS84 : Z coordinate relative to WGS84 (output)
384  */
385 
386 
387  long Geocentric_Shift_From_WGS84 (const double X_WGS84,
388  const double Y_WGS84,
389  const double Z_WGS84,
390  const long Index,
391  double *X,
392  double *Y,
393  double *Z);
394 /*
395  * This function shifts a geocentric coordinate (X, Y, Z in meters) relative
396  * to WGS84 to a geocentric coordinate (X, Y, Z in meters) relative to the
397  * local datum referenced by index.
398  *
399  * X_WGS84 : X coordinate relative to WGS84 (input)
400  * Y_WGS84 : Y coordinate relative to WGS84 (input)
401  * Z_WGS84 : Z coordinate relative to WGS84 (input)
402  * Index : Index of destination datum (input)
403  * X : X coordinate relative to the destination datum (output)
404  * Y : Y coordinate relative to the destination datum (output)
405  * Z : Z coordinate relative to the destination datum (output)
406  */
407 
408 
409  long Geocentric_Datum_Shift ( const long Index_in,
410  const double X_in,
411  const double Y_in,
412  const double Z_in,
413  const long Index_out,
414  double *X_out,
415  double *Y_out,
416  double *Z_out);
417 /*
418  * This function shifts a geocentric coordinate (X, Y, Z in meters) relative
419  * to the source datum to geocentric coordinate (X, Y, Z in meters) relative
420  * to the destination datum.
421  *
422  * Index_in : Index of source datum (input)
423  * X_in : X coordinate relative to source datum (input)
424  * Y_in : Y coordinate relative to source datum (input)
425  * Z_in : Z coordinate relative to source datum (input)
426  * Index_out : Index of destination datum (input)
427  * X_out : X coordinate relative to destination datum (output)
428  * Y_out : Y coordinate relative to destination datum (output)
429  * Z_out : Z coordinate relative to destination datum (output)
430  */
431 
432 
433  long Geodetic_Shift_To_WGS84 (const long Index,
434  const double Lat_in,
435  const double Lon_in,
436  const double Hgt_in,
437  double *WGS84_Lat,
438  double *WGS84_Lon,
439  double *WGS84_Hgt);
440 /*
441  * This function shifts geodetic coordinates relative to a given source datum
442  * to geodetic coordinates relative to WGS84.
443  *
444  * Index : Index of source datum (input)
445  * Lat_in : Latitude in radians relative to source datum (input)
446  * Lon_in : Longitude in radians relative to source datum (input)
447  * Hgt_in : Height in meters relative to source datum's ellipsoid (input)
448  * WGS84_Lat : Latitude in radians relative to WGS84 (output)
449  * WGS84_Lon : Longitude in radians relative to WGS84 (output)
450  * WGS84_Hgt : Height in meters relative to WGS84 ellipsoid (output)
451  */
452 
453 
454  long Geodetic_Shift_From_WGS84( const double WGS84_Lat,
455  const double WGS84_Lon,
456  const double WGS84_Hgt,
457  const long Index,
458  double *Lat_out,
459  double *Lon_out,
460  double *Hgt_out);
461 /*
462  * This function shifts geodetic coordinates relative to a WGS84
463  * to geodetic coordinates relative to a given local datum.
464  *
465  * WGS84_Lat : Latitude in radians relative to WGS84 (input)
466  * WGS84_Lon : Longitude in radians relative to WGS84 (input)
467  * WGS84_Hgt : Height in meters relative to WGS84 ellipsoid (input)
468  * Index : Index of destination datum (input)
469  * Lat_in : Latitude in radians relative to destination datum (output)
470  * Lon_in : Longitude in radians relative to destination datum (output)
471  * Hgt_in : Height in meters relative to destination datum's ellipsoid (output)
472  */
473 
474 
475  long Geodetic_Datum_Shift ( const long Index_in,
476  const double Lat_in,
477  const double Lon_in,
478  const double Hgt_in,
479  const long Index_out,
480  double *Lat_out,
481  double *Lon_out,
482  double *Hgt_out);
483 /*
484  * This function shifts geodetic coordinates (latitude, longitude in radians
485  * and height in meters) relative to the source datum to geodetic coordinates
486  * (latitude, longitude in radians and height in meters) relative to the
487  * destination datum.
488  *
489  * Index_in : Index of source datum (input)
490  * Lat_in : Latitude in radians relative to source datum (input)
491  * Lon_in : Longitude in radians relative to source datum (input)
492  * Hgt_in : Height in meters relative to source datum's ellipsoid (input)
493  * Index_out : Index of destination datum (input)
494  * Lat_out : Latitude in radians relative to destination datum (output)
495  * Lon_out : Longitude in radians relative to destination datum (output)
496  * Hgt_out : Height in meters relative to destination datum's ellipsoid (output)
497  */
498 
499 
500  long Datum_Shift_Error (const long Index_in,
501  const long Index_out,
502  double latitude,
503  double longitude,
504  double *ce90,
505  double *le90,
506  double *se90);
507 /*
508  * This function returns the 90% horizontal (circular), vertical (linear), and
509  * spherical errors for a shift from the specified source datum to the
510  * specified destination datum at the specified location.
511  *
512  * Index_in : Index of source datum (input)
513  * Index_out : Index of destination datum (input)
514  * latitude : Latitude of point being converted in radians (input)
515  * longitude : Longitude of point being converted in radians (input)
516  * ce90 : Combined 90% circular horizontal error in meters (output)
517  * le90 : Combined 90% linear vertical error in meters (output)
518  * se90 : Combined 90% spherical error in meters (output)
519  */
520 
521 
522 #ifdef __cplusplus
523 }
524 #endif
525 
526 #endif /* DATUM_H */
527 
528 
Geodetic_Shift_From_WGS84
long Geodetic_Shift_From_WGS84(const double WGS84_Lat, const double WGS84_Lon, const double WGS84_Hgt, const long Index, double *Lat_out, double *Lon_out, double *Hgt_out)
Geocentric_Shift_To_WGS84
long Geocentric_Shift_To_WGS84(const long Index, const double X, const double Y, const double Z, double *X_WGS84, double *Y_WGS84, double *Z_WGS84)
Datum_Three_Parameters
long Datum_Three_Parameters(const long Index, double *Delta_X, double *Delta_Y, double *Delta_Z)
Geodetic_Datum_Shift
long Geodetic_Datum_Shift(const long Index_in, const double Lat_in, const double Lon_in, const double Hgt_in, const long Index_out, double *Lat_out, double *Lon_out, double *Hgt_out)
Get_Datum_Type
long Get_Datum_Type(const long Index, Datum_Type *Type)
Datum_Seven_Parameters
long Datum_Seven_Parameters(const long Index, double *Delta_X, double *Delta_Y, double *Delta_Z, double *Rx, double *Ry, double *Rz, double *Scale_Factor)
Create_Datum
long Create_Datum(const char *Code, const char *Name, const char *Ellipsoid_Code, double Delta_X, double Delta_Y, double Delta_Z, double Sigma_X, double Sigma_Y, double Sigma_Z, double South_latitude, double North_latitude, double West_longitude, double East_longitude)
Datum_Errors
long Datum_Errors(const long Index, double *Sigma_X, double *Sigma_Y, double *Sigma_Z)
Initialize_Datums
long Initialize_Datums(void)
Datum_Count
long Datum_Count(long *Count)
Datum_Ellipsoid_Code
long Datum_Ellipsoid_Code(const long Index, char *Code)
Geocentric_Shift_From_WGS84
long Geocentric_Shift_From_WGS84(const double X_WGS84, const double Y_WGS84, const double Z_WGS84, const long Index, double *X, double *Y, double *Z)
Datum_Shift_Error
long Datum_Shift_Error(const long Index_in, const long Index_out, double latitude, double longitude, double *ce90, double *le90, double *se90)
Datum_Types
Datum_Types
Definition: datum.h:147
Datum_Name
long Datum_Name(const long Index, char *Name)
Datum_Index
long Datum_Index(const char *Code, long *Index)
Datum_Code
long Datum_Code(const long Index, char *Code)
Datum_Type
enum Datum_Types Datum_Type
Valid_Datum
long Valid_Datum(const long Index, double latitude, double longitude, long *result)
Geocentric_Datum_Shift
long Geocentric_Datum_Shift(const long Index_in, const double X_in, const double Y_in, const double Z_in, const long Index_out, double *X_out, double *Y_out, double *Z_out)
Geodetic_Shift_To_WGS84
long Geodetic_Shift_To_WGS84(const long Index, const double Lat_in, const double Lon_in, const double Hgt_in, double *WGS84_Lat, double *WGS84_Lon, double *WGS84_Hgt)
Datum_Valid_Rectangle
long Datum_Valid_Rectangle(const long Index, double *South_latitude, double *North_latitude, double *West_longitude, double *East_longitude)
Generated on Fri Aug 3 2018 08:46:44 for OSSIM - Open Source Software Image Map by   doxygen 1.8.14