Prototype and description of the function coordtransepsg()

(Function of the unlock requiring group "Coordinate Transformations")

 

coordtransepsg()
Coordinate Transformation and Reference System Transition with EPSG
codes of the Coordinate Reference Systems.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall coordtransepsg(
     double nCoordXQ,
     double nCoordYQ,
     double nEllHgtQ,
     unsigned short nEpsgQ,
     double *nCoordXZ,
     double *nCoordYZ,
     double *nEllHgtZ,
     unsigned short nEpsgZ);

Prototype of the DLL function in Visual Objects syntax:
_DLL function coordtransepsg(;
     nCoordXQ as real8,;                   // 8 Byte
     nCoordYQ as real8,;                   // 8 Byte
     nEllHgtQ as real8,;                   // 8 Byte
     nEpsgQ as word,;                      // 2 Byte
     nCoordXZ ref real8,;                  // 4 Byte
     nCoordYZ ref real8,;                  // 4 Byte
     nEllHgtZ ref real8,;                  // 4 Byte
     nEpsgZ as word);                      // 2 Byte
as logic pascal:geodll32.coordtransepsg    // 4 Byte


The function converts the numeric source coordinates nCoordXQ and nCoordYQ
from the EPSG source Coordinate Reference System nEpsgQ to the numeric
target coordinates nCoordXZ and nCoordYZ of the EPSG target Coordinate
Reference System nEpsgZ. For both source and target coordinates either two
numeric parameter will be passed. The transformation is accomplished with
high exactness and great speed.

If one of the EPSG Coordinate Reference Systems is a 3D system, the
ellipsoidical height nEllHgtQ of the source system ellipsoid is included in
the calculation. As the result, the ellipsoidical height nEllHgtZ of the
target system ellipsoid is returned. Also calculations with cartesian
coordinates are possible.

Using the EPSG codes all the settings for the Coordinate Systems and
Reference Systems of the equivalent EPSG Coordinate Reference Systems ar
made. If necessary, also Meridian Strip Numbers and the projection type 2D
or 3D are set.

EPSG is the acronym for "European Petroleum Survey Group Geodesy". This is
a working group of the European oil and gas exploration companies. The EPSG
and their successors OGP "International Association of Oil and Gas
Producers" have made it to their task to build a system with globally
unique identitfiers (EPSG codes) for geodetic data, such as Coordinate
Reference Systems, Reference Ellipsoids or Map Projections.

It is expressly noted, that not always exactly the same parameters for
Coordinate Transformations and Reference System Transitions are used by
GeoDLL, as they are present in the EPSG database. The reason for this is
that some EPSG parameter sets do not meet the quality standards of
KilletSoft products. GeoDLL mostly uses parameter sets which have been
published by the respective survey administrations or have made firsthand
available to KilletSoft by them or even have been purchased from them.
KilletSoft has created its own high-quality data collection of exact
geodetic parameter sets over the past years. Since the EPSG coding is used
in many GIS systems and thus has obtained a high level of awareness, we
provide some functions, that simplifies the selection of the required
Coordinate Systems and Reference Systems while programming with GeoDLL.

Functions using EPSG coding:
coordtransepsg()   This function
getepsg2geodll()   Determination of GeoDLL codes equivalent to EPSG code
getepsgcrsname()   Determination of the designation of a EPSG CRS


The parameters are passed and/or returned as follows:
nCoordXQ    Longitude, East or X component of the numeric source
            coordinate.
            The input format of the coordinate (notation) is described in
            the data form of the EPSG Coordinate Reference System (see
            EPSG database).

nCoordYQ    Latitude, North or Y component of the numeric source
            coordinate.
            The input format of the coordinate (notation) is described in
            the data form of the EPSG Coordinate Reference System (see
            EPSG database).

nEllHgtQ    Ellipsoidical height of the source coordinate
              or
            Z component of a cartesian coordinate.
            If the EPSG Coordinate Reference System is a 3D system, the
            ellipsoidal height of the source coordinate is considered.

nEpsgsQ     EPSG code for the source Coordinate Reference System.
            All parameters are described in the data form of the EPSG
            Coordinate Reference System (see EPSG database).

nCoordXZ    Longitude, East or X component of the numeric target
(ref)       coordinate.
            The output format of the coordinate (notation) is described in
            the data form of the EPSG Coordinate Reference System (see
            EPSG database).

nCoordYZ    Latitude, North or Y component of the numeric target
(ref)       coordinate.
            The output format of the coordinate (notation) is described in
            the data form of the EPSG Coordinate Reference System (see
            EPSG database).

nEllHgtZ    Ellipsoidical height of the target coordinate
(ref)         or
            Z component of a cartesian coordinate.
            If the EPSG Coordinate Reference System is a 3D system, the
            ellipsoidal height of the target coordinate will be calculated.

nEpsgZ      EPSG code for the target Coordinate Reference System.
            All parameters are described in the data form of the EPSG
            Coordinate Reference System (see EPSG database).

returnVal   In case of an error the function returns FALSE, otherwise TRUE.


Range validity
The range limitations of the source coordinates and the calculated target
coordinates are examined on the basis of standard settings. The syntax and
range examination can be switched off by the function setCoordArea().


Special features using NTv2 grid files
Download of NTv2 files:
The commonly used NTv2 files can be download from the KilletSoft-Website
or can be purchased from suppliers of geoservices.

Encrypted NTv2 files:
To protect the rights of some authors that provide NTv2 files specifically
for use with KilletSoft products, GeoDLL supports encrypted NTv2 files
that can be download from the KilletSoft website.

Polygonal Validity Scopes:
The scope of a NTv2 file is by default defined by rectangular coordinate
boxes. In order to be able to implement polygonal structures, e.g. such as
national borders, the producer of a NTv2 file therein can specify a
Polygonal Validity Scope. For this, outside of the poligonal validity
located grid meshes are indicated by the exopolygonal entries -99/-99 in
their shift or accuracy values. GeoDLL can check the grid meshes on
exopolygonal entries and exclude hits from the calculation and comment
them with an error message. The Polygonal Validity Check will be switched
on or off using the function setntvpolyvalid(). Detailed information can
be found in the help section "Polygonal Validity Scopes".


Unlocking
This function is a component of the unlock requiring function group
"Coordinate Transformations". It is unlocked for unrestricted use
together with the other functions of the group by passing the unlock
parameters, acquired from the software distribution company, trough the
function setunlockcode(). Without unlocking only a few function calls for
test purposes (shareware principle) are possible.

Reference System Transitions with NTv2 grid files require an additional
unlocking of the function group "NTv2 Grid Data".