|
Prototype and description of the function coordtrans() (Function of the unlock requiring group "Coordinate Transformations") |
|
coordtrans()
2D Coordinate Transformation and Reference System Transition for numeric
and alphanumeric coordinates with memory allocation for the return
strings.
Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall coordtrans(
double nCoordXQ,
double nCoordYQ,
const char *pszCoordQ,
unsigned short nCoordSysQ,
unsigned short nRefSysQ,
double *nCoordXZ,
double *nCoordYZ,
char **pszCoordZ,
unsigned short nCoordSysZ,
unsigned short nRefSysZ,
unsigned short nStripZ);
Prototype of the DLL function in Visual Objects syntax:
_DLL function coordtrans(;
nCoordXQ as real8,; // 8 Byte
nCoordYQ as real8,; // 8 Byte
pszCoordQ as psz,; // 4 Byte, char*
nCoordSysQ as word,; // 2 Byte
nRefSysQ as word,; // 2 Byte
nCoordXZ ref real8,; // 4 Byte
nCoordYZ ref real8,; // 4 Byte
pszCoordZ ref psz,; // 4 Byte, char**, 20 alloc.
nCoordSysZ as word,; // 2 Byte
nRefSysZ as word,; // 2 Byte
nStripZ as word); // 2 Byte
as logic pascal:geodll32.coordtrans // 4 Byte
The allocation of memory for "ref psz" / "char**" is necessary only if
setstringallocate(FALSE) is called before.
The function converts the numeric source coordinates nCoordXQ and
nCoordYQ or the alphanumeric source coordinate pszCoordQ from the source
Coordinate System nCoordSysQ to the numeric target coordinates nCoordXZ
and nCoordYZ or the alphanumeric target coordinate pszCoordZ of the target
Coordinate System nCoordSysZ. For a both source and target coordinates
either two numeric or one alphanumeric parameter will be passed. The
transformation is accomplished with high exactness and great speed.
The difference between the function coordtrans() and the function
coordtrans3d() is that this is a 2D transformation. Thereby in the case
of using different source and target Reference Systems the ellipsoidical
height is not included in the calculation because it has only a very
small influence to the position accuracy.
The passed source coordinates and the calculated target coordinates are
examined for the range validity within their Coordinate Systems and for
syntactic correctness. The range validity is specified in the list
"Defaults of the Coordinate Systems". The range and syntax check can be
switched on or off with the function setcoordarea().
If in nCoordSysQ or in nCoordSysZ the values 1000 or 1100 are passed, the
function uses the parameters of the user-defined Coordinate Systems
passed before by the functions setusercoordsys1() and/or
setusercoordsys2() and the earth ellipsoids defined before by the
functions setuserellsource() and setuserelltarget()
With the Coordinate Transformation a Reference System Transition from the
geodetic Reference System nRefSysQ of the source Coordinate System can be
considered to the geodetic Reference System nRefSysZ of the target
Coordinate System.
If in nRefSysQ or in nRefSysZ the value 0 is passed, then the geodetic
Reference Systems, usual for the respective Coordinate Systems, are taken
as a basis for the Reference System Transition. The standard Reference
Systems are specified in the list "Defaults of the Coordinate Systems".
If in nRefSysQ or in nRefSysZ the value 1000 is passed, the function uses
the parameters of the user-defined Reference Systems passed before by the
functions setuserrefsys() and the earth ellipsoids defined before by the
functions setuserellsource() and setuserelltarget()
If in nRefSysQ or in nRefSysZ the value 1100 is passed or if both
parameters have same value (larger than 0), no Reference System Transition
takes place. Then the earth ellipsoids, usual for the respective Coordinate
Systems, are taken as a basis for the Coordinate Transformation. The standard
earth ellipsoids are specified in the list "Defaults of the coordinate
systems".
If in nRefSysQ or in nRefSysZ the value 1150 is passed, no Reference System
Transition takes place. Then the earth ellipsoids defined before by the
functions setuserellsource() and setuserelltarget() are taken as a basis for
the Coordinate Transformation.
If in nRefSysQ or in nRefSysZ the value 1200 is passed, no Reference System
Transition nor Ellipsoid Transition are performed.
If for Reference Systems nRefSysQ or nRefSysZ no Reference System
parameters are defined, only an Ellipsoid Transition is performed, but
no Reference System Transition is performed.
For transformations to the target Coordinate Systems Gauss-Krueger and
UTM the meridian strip nStripZ, to which the target coordinates are to
refer, can be given. The given meridian strip should not deviate more than
3 strips from the native meridian strip of the target Coordinate System.
If in nStripZ the value 0 is passed, an automatic computation of the
native meridians strip from the geographical length takes place.
The following transformations are possible:
Coordinate Transformations with maintaining the Reference System.
Coordinate Transformations with Reference System Transition.
Coordinate Transformation with Ellipsoid Transition when Reference System
parameters not defined.
Reference System Transition with maintaining the Coordinate System.
Change of the notation (way of writing) with geographical coordinates.
Change of the meridian strip with Gauss-Krueger and UTM coordinates.
Conversion in the native meridian strip with Gauss-Krueger and UTM
coordinates.
The parameters are passed and/or returned as follows:
nCoordXQ Longitude, East or X component of the numeric source
coordinate.
During processing of an alphanumeric coordinate this
parameter is without meaning. The input format of the
coordinate (notation) is described in the list "Defaults
of the Coordinate Systems".
nCoordYQ Latitude, North or Y component of the numeric source
coordinate.
During processing of an alphanumeric coordinate this
parameter is without meaning. The input format of the
coordinate (notation) is described in the list "Defaults
of the Coordinate Systems".
pszCoordQ Alphanumeric source coordinate.
During processing of a numeric coordinate this parameter is
without meaning. In this case for pszCoordQ a NULL pointer
can be passed. The input format of the coordinate (notation)
is described in the list "Defaults of the Coordinate Systems".
nCoordSysQ Coordinate System of the source coordinates.
(see list "Coordinate Reference Systems").
nRefSysQ Geodetic Reference System of the source coordinates.
(see list "Coordinate Reference Systems").
nCoordXZ Longitude, East or X component of the numeric target
(ref) coordinate.
During processing of an alphanumeric coordinate this
parameter is without meaning. The return format of the
coordinate (notation) is described in the list "Defaults
of the Coordinate Systems".
nCoordYZ Latitude, North or Y component of the numeric target
(ref) coordinate.
During processing of an alphanumeric coordinate this
parameter is without meaning. The return format of the
coordinate (notation) is described in the list "Defaults
of the Coordinate Systems".
pszCoordZ Alphanumeric target coordinate.
(ref) During processing of a numeric coordinate this parameter is
without meaning. In this case for pszCoordZ a NULL pointer
can be passed. The return format of the coordinate (notation)
is described in the list "Defaults of the Coordinate Systems".
Note: "ref pszCoordZ" corresponds to "char**" in C. 20 bytes of
memory for the zero terminated string must be allocated with
dependence to the call of the function setstringallocate().
Please consider the notes in the description of the function
setstringallocate().
If the used programming language does not support the
construct "pointer to a pointer to the first character of a
string" (char**), then the function coordtrans2() can be used
in place of the function coordtrans(). Further information can
be found in the description of the function coordtrans2().
nCoordSysZ Coordinate System of the target coordinates.
(see list "Coordinate Reference Systems").
nRefSysZ Geodetic Reference System of the target coordinates.
(see list "Coordinate Reference Systems").
nStripZ Meridian strip to use.
This parameter has only an effect, if a "Transversal Mercator
meridian strip system" is registered in nCoordSysZ.
0 Calculation of the native meridian strip from the geographic
longitude.
› 0 Valid number of the required meridian strip.
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 the geographical coordinates
specified under the term "Range (Lon / Lat)" in the list "Defaults of the
Coordinate Systems". The syntax and range examination can be switched off by
the function setCoordArea().
With user-defined Coordinate Systems the range values are calculated
automatically from the origin point of the respective Coordinate System.
Notations
The coordinates of the different Coordinate Systems are written with the
notations specified under the term "Notation (E / N)" in the list
"Defaults of the Coordinate Systems". As many as desired right-of-comma
positions can be added.
A specification of the notations can be found at the end of the list
"Defaults of the Coordinate Systems".
Standard Reference Systems
The Reference Systems specified under the term "Standard RefSys" in the
list "Defaults of the Coordinate Systems" are assigned to the Coordinate
Systems, if in the parameters nRefSysQ or nRefSysZ a zero is passed.
Special features using Reference Systems with Helmert Parameters:
Forward and Backward Transformation:
GeoDLL calculates Reference System Transitions with Helmert transformation
parameters as Forward and Backward Transformations. With a Forward
Transformation, starting from the source system, first the rotations and
then the translations are performed. With a Backward Transformation,
leading to the target system, in reverse order first the translations and
then the rotations are calculated. Forward and Backward Transformations are
executed each across the current dynamic Reference System WGS84.
Calculating bidirectional coordinate transformations with Forward and
Backward Transformations like in GeoDLL does not lead in minor deviations,
that occur in many GIS.
Small and large rotation angles:
Normally, geodesic software only supports very small rotation angles when
transforming with seven Helmert transformation parameters. In GeoDLL, the
fast, simplified rotation matrix is resolved for small rotation angles up
to 5 seconds. At larger angles, the slower, complete rotation matrix is
resolved to maintain accuracy. In this way, both the high accuracy and the
high calculation speed is guaranteed.
Special features using Reference Systems with 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.
Combination prohibiting:
NTv2 Reference Systems are identified by the suffix "NTv2" in the
designation. When setting an NTv2 Reference System for the Source or
Destination Coordinate System, on the other side must be set the equivalent
Reference system of the associated NTv2 file. The combination of NTv2
Reference Systems with Helmert or Molodensky Reference Systems is not
possible.
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".
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".
|