00001 // CLASSIFICATION: UNCLASSIFIED 00002 00003 #ifndef DatumLibrary_H 00004 #define DatumLibrary_H 00005 00006 /***************************************************************************/ 00007 /* RSC IDENTIFIER: Datum Library 00008 * 00009 * ABSTRACT 00010 * 00011 * This component provides datum shifts for a large collection of local 00012 * datums, WGS72, and WGS84. A particular datum can be accessed by using its 00013 * standard 5-letter code to find its index in the datum table. The index 00014 * can then be used to retrieve the name, type, ellipsoid code, and datum 00015 * shift parameters, and to perform shifts to or from that datum. 00016 * 00017 * By sequentially retrieving all of the datum codes and/or names, a menu 00018 * of the available datums can be constructed. The index values resulting 00019 * from selections from this menu can then be used to access the parameters 00020 * of the selected datum, or to perform datum shifts involving that datum. 00021 * 00022 * This component supports both 3-parameter local datums, for which only X, 00023 * Y, and Z translations relative to WGS 84 have been defined, and 00024 * 7-parameter local datums, for which X, Y, and Z rotations, and a scale 00025 * factor, are also defined. It also includes entries for WGS 84 (with an 00026 * index of 0), and WGS 72 (with an index of 1), but no shift parameter 00027 * values are defined for these. 00028 * 00029 * This component provides datum shift functions for both geocentric and 00030 * geodetic coordinates. WGS84 is used as an intermediate state when 00031 * shifting from one local datum to another. When geodetic coordinates are 00032 * given Molodensky's method is used, except near the poles where the 3-step 00033 * step method is used instead. Specific algorithms are used for shifting 00034 * between WGS72 and WGS84. 00035 * 00036 * This component depends on two data files, named 3_param.dat and 00037 * 7_param.dat, which contain the datum parameter values. Copies of these 00038 * files must be located in the directory specified by the value of the 00039 * environment variable "MSPCCS_DATA", if defined, or else in the current 00040 * directory whenever a program containing this component is executed. 00041 * 00042 * Additional datums can be added to these files, either manually or using 00043 * the Create_Datum function. However, if a large number of datums are 00044 * added, the datum table array sizes in this component will have to be 00045 * increased. 00046 * 00047 * This component depends on two other components: the Ellipsoid component 00048 * for access to ellipsoid parameters; and the Geocentric component for 00049 * conversions between geodetic and geocentric coordinates. 00050 * 00051 * ERROR HANDLING 00052 * 00053 * This component checks for input file errors and input parameter errors. 00054 * If an invalid value is found, the error code is combined with the current 00055 * error code using the bitwise or. This combining allows multiple error 00056 * codes to be returned. The possible error codes are: 00057 * 00058 * DATUM_NO_ERROR : No errors occurred in function 00059 * DATUM_NOT_INITIALIZED_ERROR : Datum module has not been initialized 00060 * DATUM_7PARAM_FILE_OPEN_ERROR : 7 parameter file opening error 00061 * DATUM_7PARAM_FILE_PARSING_ERROR : 7 parameter file structure error 00062 * DATUM_7PARAM_OVERFLOW_ERROR : 7 parameter table overflow 00063 * DATUM_3PARAM_FILE_OPEN_ERROR : 3 parameter file opening error 00064 * DATUM_3PARAM_FILE_PARSING_ERROR : 3 parameter file structure error 00065 * DATUM_3PARAM_OVERFLOW_ERROR : 3 parameter table overflow 00066 * DATUM_INVALID_INDEX_ERROR : Index out of valid range (less than one 00067 * or more than Number_of_Datums) 00068 * DATUM_INVALID_SRC_INDEX_ERROR : Source datum index invalid 00069 * DATUM_INVALID_DEST_INDEX_ERROR : Destination datum index invalid 00070 * DATUM_INVALID_CODE_ERROR : Datum code not found in table 00071 * DATUM_LAT_ERROR : Latitude out of valid range (-90 to 90) 00072 * DATUM_LON_ERROR : Longitude out of valid range (-180 to 00073 * 360) 00074 * DATUM_SIGMA_ERROR : Standard error values must be positive 00075 * (or -1 if unknown) 00076 * DATUM_DOMAIN_ERROR : Domain of validity not well defined 00077 * DATUM_ELLIPSE_ERROR : Error in ellipsoid module 00078 * DATUM_NOT_USERDEF_ERROR : Datum code is not user defined - cannot 00079 * be deleted 00080 * 00081 * 00082 * REUSE NOTES 00083 * 00084 * Datum is intended for reuse by any application that needs access to 00085 * datum shift parameters relative to WGS 84. 00086 * 00087 * 00088 * REFERENCES 00089 * 00090 * Further information on Datum can be found in the Reuse Manual. 00091 * 00092 * Datum originated from : U.S. Army Topographic Engineering Center (USATEC) 00093 * Geospatial Information Division (GID) 00094 * 7701 Telegraph Road 00095 * Alexandria, VA 22310-3864 00096 * 00097 * LICENSES 00098 * 00099 * None apply to this component. 00100 * 00101 * RESTRICTIONS 00102 * 00103 * Datum has no restrictions. 00104 * 00105 * ENVIRONMENT 00106 * 00107 * Datum was tested and certified in the following environments: 00108 * 00109 * 1. Solaris 2.5 with GCC 2.8.1 00110 * 2. MS Windows 95 with MS Visual C++ 6 00111 * 00112 * MODIFICATIONS 00113 * 00114 * Date Description 00115 * ---- ----------- 00116 * 11/20/08 Original Code 00117 * 05/26/10 S. Gillis, BAEts26674, Added Validate Datum to the API 00118 * in MSP Geotrans 3.0 00119 * 07/01/10 S. Gillis, BAEts26676, Fixed the error always returned 00120 * when calling CCS API getDatumParamters 00121 */ 00122 00123 00124 #include "DatumType.h" 00125 #include "DtccApi.h" 00126 00127 00128 00129 namespace MSP 00130 { 00131 namespace CCS 00132 { 00133 class DatumLibraryImplementation; 00134 00135 class MSP_DTCC_API DatumLibrary 00136 { 00137 public: 00138 00139 /* 00140 * The constructor creates an empty list to store the datum information 00141 * contained in two external files, 3_param.dat and 7_param.dat. 00142 */ 00143 00144 DatumLibrary( DatumLibraryImplementation* __datumLibraryImplementation ); 00145 00146 00147 DatumLibrary( const DatumLibrary &d ); 00148 00149 00150 DatumLibrary& operator=( const DatumLibrary &d ); 00151 00152 00153 ~DatumLibrary( void ); 00154 00155 00156 /* The function defineDatum creates a new local (3 or 7-parameter) datum with the 00157 * specified code, name, shift values, and standard error values or rotation and scale factor values. 00158 * If the datum table has not been initialized, the specified code is already in use, 00159 * or a new version of the 3-param.dat or 7-param.dat file cannot be created, an 00160 * exception is thrown. Note that the indexes 00161 * of all datums in the datum table may be changed by this function. 00162 * 00163 * datumType : Specifies 3 parameter or 7 parameter datum (input) 00164 * datumCode : 5-letter new datum code. (input) 00165 * datumName : Name of the new datum (input) 00166 * ellipsoidCode : 2-letter code for the associated ellipsoid (input) 00167 * deltaX : X translation to WGS84 in meters (input) 00168 * deltaY : Y translation to WGS84 in meters (input) 00169 * deltaZ : Z translation to WGS84 in meters (input) 00170 * sigmaX : Standard error in X in meters (input) 00171 * sigmaY : Standard error in Y in meters (input) 00172 * sigmaZ : Standard error in Z in meters (input) 00173 * westLongitude : Western edge of validity rectangle in radians (input) 00174 * eastLongitude : Eastern edge of validity rectangle in radians (input) 00175 * southLatitude : Southern edge of validity rectangle in radians(input) 00176 * northLatitude : Northern edge of validity rectangle in radians(input) 00177 * rotationX : X rotation to WGS84 in arc seconds (input) 00178 * rotationY : Y rotation to WGS84 in arc seconds (input) 00179 * rotationZ : Z rotation to WGS84 in arc seconds (input) 00180 * scalefactor : Scale factor (input) 00181 * 00182 */ 00183 00184 void defineDatum( const int datumType, const char *datumCode, const char *datumName, const char *ellipsoidCode, 00185 double deltaX, double deltaY, double deltaZ, 00186 double sigmaX, double sigmaY, double sigmaZ, 00187 double westLongitude, double eastLongitude, double southLatitude, double northLatitude, 00188 double rotationX, double rotationY, double rotationZ, double scaleFactor); 00189 00190 00191 /* 00192 * The function removeDatum deletes a local (3-parameter) datum with the 00193 * specified code. If the datum table has not been initialized or a new 00194 * version of the 3-param.dat file cannot be created, an exception is thrown. 00195 * Note that the indexes of all datums 00196 * in the datum table may be changed by this function. 00197 * 00198 * code : 5-letter datum code. (input) 00199 * 00200 */ 00201 00202 void removeDatum( const char* code ); 00203 00204 00205 /* 00206 * The function datumCode returns the 5-letter code of the datum 00207 * referenced by index. 00208 * 00209 * index : The index of a given datum in the datum table. (input) 00210 * code : The datum Code of the datum referenced by Index. (output) 00211 */ 00212 00213 void datumCode( const long index, char *code ); 00214 00215 00216 /* 00217 * The function getDatumCount returns the number of Datums in the table 00218 * if the table was initialized without error. 00219 * 00220 * count : number of datums in the datum table (output) 00221 */ 00222 00223 void getDatumCount( long *count ); 00224 00225 00226 /* 00227 * The function getDatumIndex returns the index of the datum with the 00228 * specified code. 00229 * 00230 * code : The datum code being searched for. (input) 00231 * index : The index of the datum in the table with the (output) 00232 * specified code. 00233 */ 00234 00235 void getDatumIndex( const char *code, long *index ); 00236 00237 00238 /* 00239 * The function getDatumInfo returns the 5-letter code, name and 00240 * 2-letter ellipsoid code of the datum referenced by index. 00241 * 00242 * index : The index of a given datum in the datum table. (input) 00243 * code : The datum Code of the datum referenced by Index. (output) 00244 * name : The datum Name of the datum referenced by Index. (output) 00245 * ellipsoidCode : The ellipsoid code for the ellipsoid associated with (output) 00246 * the datum referenced by index. 00247 */ 00248 00249 void getDatumInfo( const long index, char *code, char *name, char *ellipsoidCode ); 00250 00251 00252 /* 00253 * The function getDatumParameters returns the following datum parameters 00254 * (specified as output parameters below): datumType, deltaX, deltaY, 00255 * deltaZ, sigmaX, sigmaY, sigmaZ, westLongitude, eastLongitude, 00256 * southLatitude, northLatitude, rotationX, rotationY, rotationZ, and 00257 * scaleFactor. 00258 * 00259 * sigmaX, sigmaY, and sigmaZ only apply to 3 parameter datum and will be 00260 * set to 0 if the datum type is a 7 parameter datum. 00261 * 00262 * rotationX, rotationY, rotationZ, and scaleFactor only apply to 7 00263 * parameter datum and will be set to 0 if the datum type is a 3 00264 * parameter datum. 00265 * 00266 * If the datum type is neither a 3 parameter datum nor a 7 parameter 00267 * datum, a CoordinateConversionException will be thrown. 00268 * 00269 * index : The index of a given datum in the datum table (input) 00270 * datumType : Specifies datum type (output) 00271 * deltaX : X translation to WGS84 in meters (output) 00272 * deltaY : Y translation to WGS84 in meters (output) 00273 * deltaZ : Z translation to WGS84 in meters (output) 00274 * sigmaX : Standard error in X in meters (output) 00275 * sigmaY : Standard error in Y in meters (output) 00276 * sigmaZ : Standard error in Z in meters (output) 00277 * westLongitude : Western edge of validity rectangle in radians (output) 00278 * eastLongitude : Eastern edge of validity rectangle in radians (output) 00279 * southLatitude : Southern edge of validity rectangle in radians (output) 00280 * northLatitude : Northern edge of validity rectangle in radians (output) 00281 * rotationX : X rotation to WGS84 in arc seconds (output) 00282 * rotationY : Y rotation to WGS84 in arc seconds (output) 00283 * rotationZ : Z rotation to WGS84 in arc seconds (output) 00284 * scaleFactor : Scale factor (output) 00285 */ 00286 00287 void getDatumParameters( const long index, DatumType::Enum *datumType, double *deltaX, double *deltaY, double *deltaZ, 00288 double *sigmaX, double *sigmaY, double *sigmaZ, 00289 double *westLongitude, double *eastLongitude, double *southLatitude, double *northLatitude, 00290 double *rotationX, double *rotationY, double *rotationZ, double *scaleFactor ); 00291 00292 00293 /* 00294 * The function datumValidRectangle returns the edges of the validity 00295 * rectangle for the datum referenced by index. 00296 * 00297 * index : The index of a given datum in the datum table (input) 00298 * westLongitude : Western edge of validity rectangle in radians (output) 00299 * eastLongitude : Eastern edge of validity rectangle in radians (output) 00300 * southLatitude : Southern edge of validity rectangle in radians (output) 00301 * northLatitude : Northern edge of validity rectangle in radians (output) 00302 * 00303 */ 00304 00305 void getDatumValidRectangle( const long index, double *westLongitude, double *eastLongitude, double *southLatitude, double *northLatitude ); 00306 00307 /* 00308 * The function validDatum checks whether or not the specified location 00309 * is within the validity rectangle for the specified datum. It returns 00310 * zero if the specified location is NOT within the validity rectangle, 00311 * and returns 1 otherwise. 00312 * 00313 * index : The index of a given datum in the datum table (input) 00314 * latitude : Latitude of the location to be checked in radians (input) 00315 * longitude : Longitude of the location to be checked in radians (input) 00316 * result : Indicates whether location is inside (1) or outside (0) 00317 * of the validity rectangle of the specified datum (output) 00318 */ 00319 00320 void validDatum( const long index, double longitude, double latitude, 00321 long *result ); 00322 00323 private: 00324 00325 DatumLibraryImplementation* _datumLibraryImplementation; 00326 00327 }; 00328 } 00329 } 00330 00331 #endif 00332 00333 00334 // CLASSIFICATION: UNCLASSIFIED