- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

# Y:/msp/devkits/temp_geotrans/master/geotrans3.1/CCS/src/dtcc/DatumLibrary.h

Go to the documentation of this file.

    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