Function coordtransepsg()

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.

For most EPSG codes, in addition to the preset Coordinate System different
Reference Systems can be used. In GeoDLL, however, only a single reference
system is preset. To determine which coordinate and Reference Systems and
other parameters are preset in GeoDLL for a particular EPSG code, you can use
the getepsg2geodll() function (see below). If you want to deviate from the
default parameters, please do not use coordtransepsg(), but one of the other
coordtrans() functions. Preferably, the function coordtrans3dex() is to be
used since it can process all parameters that match an EPSG code. The
coordinates and Reference Systems and other parameters preset in GeoDLL for
EPSG codes are marked with their GeoDLL numbers in the "List with supported
EPSG codes" in the user manual and in the online manual
(http://www.killetsoft.de/h_geodll_e/handbuch_e.htm).

Some EPSG codes use reference systems with datum transitions vian NTv2 or
HARN files. This is not always obvious at first glance when using the
function coordtransepsg(). Therefore, the following should be noted:
1. NTv2 or HARN datum transitions only work within the scope of the NTv2
   or HARN file. Usually this is for example only one country / state, one
   US state or one German federal state.
2. Both reference systems must be of the same type:
   Helmert / Molodenski --› Helmert / Molodenski.
   NTv2 / HARN --› NTv2 / HARN (with the same NTv2 or HARN file).

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 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.

It does not always make sense to use the coordtransepsg() function to select
a CRS. An EPSG code usually refers to a Coordinate System and to one of many
possible Reference Systems. In GeoDLL, only one widely used Reference System
for the respective Coordinate System is preset when using an EPSG code.
Depending on the specific case, a Reference System other than the default
one must be selected. This is necessary, for example, if several variants of
different epochs and resolutions are available for the Reference System. If a
Reference System other than the default one is more suitable, this should be
realized, for example, with the functions getepsg2geodll() and coordtrans3dex().

Functions using EPSG coding:
coordtransepsg()   This function
getepsg2geodll()   Determination of predefined GeoDLL numbers belonging to
                   an 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 an NTv2 file is by default defined by quadrangular coordinate
boxes. In order to be able to implement polygonal structures, e.g. such as
national borders, the producer of an 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".

Please take further references from the description of the functions
coordtrans() and coordtrans3d().


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 Transformations".