|
Prototype and description of the function coordtrans3d3() (Function of the unlock requiring group "Coordinate Transformations") |
|
coordtrans3d3()
3D Coordinate Transformation and Reference System Transition only for
numeric coordinates.
Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall coordtrans3d3(
double nCoordXQ,
double nCoordYQ,
double nEllHgtQ,
unsigned short nCoordSysQ,
unsigned short nRefSysQ,
unsigned short nNotationQ,
double *nCoordXZ,
double *nCoordYZ,
double *nEllHgtZ,
unsigned short nCoordSysZ,
unsigned short nRefSysZ,
unsigned short nNotationZ,
unsigned short nStripZ);
Prototype of the DLL function in Visual Objects syntax:
_DLL function coordtrans3d3(;
nCoordXQ as real8,; // 8 Byte
nCoordYQ as real8,; // 8 Byte
nEllHgtQ as real8,; // 8 Byte
nCoordSysQ as word,; // 2 Byte
nRefSysQ as word,; // 2 Byte
nNotationQ as word,; // 2 Byte
nCoordXZ ref real8,; // 4 Byte
nCoordYZ ref real8,; // 4 Byte
nEllHgtZ ref real8,; // 4 Byte
nCoordSysZ as word,; // 2 Byte
nRefSysZ as word,; // 2 Byte
nNotationZ as word,; // 2 Byte
nStripZ as word); // 2 Byte
as logic pascal:geodll32.coordtrans3d3 // 4 Byte
The function coordtrans3d3() is similar to the function coordtrans3d(). The
difference is that only numeric coordinates and no alphanumeric coordinates
are transformed and that for geographical coordinates a notation can be
given as a parameter.
The function converts the numeric source coordinates nCoordXQ and nCoordYQ
from the source Coordinate System nCoordSysQ to the numeric target
coordinates nCoordXZ and nCoordYZ of the target Coordinate System
nCoordSysZ. The transformation is accomplished with high exactness and
great speed.
The difference between the function coordtrans3d3() and the function
coordtrans3() is that this is a 3D transformation. Thereby in the case
of using different source and target Reference Systems the ellipsoidical
height is included in the calculation. For the calculation the
ellipsoidical height nEllHgtQ of the source system ellipsoid is used. As
the result, the ellipsoidical height nEllHgtZ of the target system
ellipsoid is returned. The calculations are also possible with cartesian
coordinates.
3D calculation are not possible when using a 'Reference System in an
arbitrary NTv2 file' because no equivalent Helmert / Molodensky Reference
System matching the NTv2 file is available for the ellipsoidal height
calculation.
The ellipsoidical height is geometrically defined as the distance of a
point of a reference ellipsoid along the ellipsoid normal. The
ellipsoidical height can be determined directly using GPS. But it may
not be confused with leveled (orthometric) heights!
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 of "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
is performed.
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.
During transformations from or to geographical coordinates with the
parameters nNotation? can be selected between several possible notations
(ways of writing) for the parameters nCoordXQ and nCoordYQ and/or nCoordXZ
and nCoordYZ:
[degrees]
[degrees, minutes, seconds]
[degrees, minutes]
[seconds]
[gon]
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.
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.
The input format of the coordinate (notation) is described
in the list "Defaults of the Coordinate Systems".
nEllHgtQ Ellipsoidical height of the source coordinate
or
Z component of a cartesian coordinate.
With 3D transformations in the case of using different source
and target Reference Systems (nRefSysQ, nRefSysZ), the
ellipsoidical height of the source coordinate is considered.
nCoordSysQ Coordinate System of the source coordinates.
(see list "Coordinate Reference Systems").
Exceptions: The alphanumeric Coordinate Systems described
there are not supported here. The geographical coordinate
systems described there are summarized here by passing of the
value 1 in nCoordSysQ.
nRefSysQ Geodetic Reference System of the source coordinates.
(see list "Coordinate Reference Systems").
nNotationQ Notation (way of writing) of the geographical source
coordinates. The notation affects only if nCoordSysQ = 1!
0 Geographic coordinates [degrees]: vddd / vdd
d degrees and decimal fraction of a degree
1 Geographic coordinates [deg, min, sec] vdddmmss / vddmmss
d degrees
m minutes
s seconds and decimal fraction of a second
2 Geographic coordinates [deg, min]: vdddmm / vddmm
d degrees
m Minutes and decimal fraction of a minute
3 Geographic coordinates [sec]: vsssssss / vsssssss
s Seconds and decimal fraction of a second
4 Geographic coordinates [gon]: vggg / vggg
g Gon (400 gon = 360 degrees) and decimal fraction of a gon
v = Optional sign for longitudes west of Greenwich and latitudes
south of the equator.
More information about the notations can be found at the end of
the list "coordinates and Reference Systems".
nCoordXZ Longitude, East or X component of the numeric target
(ref) coordinate.
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.
The return format of the coordinate (notation) is described in
the list "Defaults of the Coordinate Systems".
nEllHgtZ Ellipsoidical height of the target coordinate
(ref) or
Z component of a cartesian coordinate.
With 3D transformations in the case of using different source
and target Reference Systems (nRefSysQ, nRefSysZ), the
ellipsoidical height of the target coordinate is calculated.
nCoordSysZ Coordinate System of the target coordinates.
(see list "Coordinate Reference Systems").
Exceptions: The alphanumeric Coordinate Systems described
there are not supported here. The geographical coordinate
systems described there are summarized here by passing of the
value 1 in nCoordSysZ.
nRefSysZ Geodetic Reference System of the target coordinates.
(see list "Coordinate Reference Systems").
nNotationZ Notation (way of writing) of the geographical target
coordinates. The notation affects only if nCoordSysZ = 1!
The notations of the geographical coordinates are described
under the parameter nNotationQ further above.
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.
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".
|