|
Prototype and description of the function getrefsys() (Function of the unlock requiring group "Parameter determination") |
|
getrefsys()
Determination of the transformation parameters for the Reference System
Transition between the geodetic source and target Reference Systems.
Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getrefsys(
unsigned short wRefSysQ,
unsigned short wRefSysZ,
unsigned short wCoordSysQ,
unsigned short wCoordSysZ,
char **pszRefSys,
unsigned long lForBack);
Prototype of the DLL function in Visual Objects syntax:
_DLL function getrefsys(;
wRefSysQ as word,; // 2 Byte
wRefSysZ as word,; // 2 Byte
wCoordSysQ as word,; // 2 Byte
wCoordSysZ as word,; // 2 Byte
pszRefSys ref psz,; // 4 Byte, char**, 1200 alloc.
lForBack as logic); // 4 Byte
as logic pascal:geodll32.getrefsys // 4 Byte
The allocation of memory for "ref psz" / "char**" is necessary only if
setstringallocate(FALSE) is called before.
The function returns the transformation parameters for the Reference
System Transition fitting to the geodetic source and target reference
systems wRefSysQ and wRefSysZ as formatted text in the parameter pszRefSys.
The text is returned in the language set by the function setLanguage()
before.
The parameters are passed and/or returned as follows:
wRefSysQ Geodetic source Reference System. The available reference
systems are specified in the list "Coordinate and Reference
systems".
wRefSysZ Geodetic target Reference System to which coordinates of
the source Reference System has to be transformed. The
available Reference Systems are specified in the list
"Coordinate Reference Systems".
wCoordSysQ Source Coordinate System. It is needed only if for the source
or target Reference Systems the identification 1100, 1150 or
1200 (no Reference System Transition) is passed, in order to
indicate the used standard ellipsoid. In addition it is needed,
if for the source Reference System the identification 0
(standard Reference System) is passed, in order to indicate the
standard Reference System that is fitting the coordinate
system. The available Coordinate Systems are specified in the
list "Coordinate Reference Systems".
wCoordSysZ Target Coordinate System. It is needed only if for the source
or target Reference Systems the identification 1100, 1150 or
1200 (no Reference System Transition) is passed, in order to
indicate the used standard ellipsoid. In addition it is needed,
if for the target Reference System the identification 0
(standard Reference System) is passed, in order to indicate the
standard Reference System that is fitting the coordinate
system. The available Coordinate Systems are specified in the
list "Coordinate Reference Systems".
pszRefSys The transformation parameters will be provided together with
(ref) their descriptions in a formatted text and returned by
reference. The lines of the text are separated with "Return
and Linefeed".
Note: "ref pszRefSys" corresponds to "char**" in C. 1200 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().
lForBack Flag for the representation of Seven Helmert parameters.
An explanation of the Forward and Backward Transformation can
be found below.
TRUE: The seven parameters of the Helmert transformation are each
presented separately for the Forward Transformation from the
source system to WGS84 and for the Backward Transformation from
WGS84 to the target system.
FALSE: The seven parameters of the Helmert transformation are added
from the parts Forward Transformation and Backward
Transformation. They are valid directly from the source to the
target system and are presented together. User defined
Reference System Transitions are always shown in this format.
returnVal In case of an error the function returns FALSE, otherwise TRUE.
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. Only user
defined Reference System Transitions are an exception. They are always
calculated directly from the source to the target system.
Calculating bidirectional coordinate transformations with Forward and
Backward Transformations like in GeoDLL does not lead in minor deviations,
that occur in many GIS.
With "on" switched flag lForBack the returned text looks dependently of
the geodetic source and target Reference Systems e.g. like this:
Geodetic Reference Systems:
DHDN/PD (DE Old States South ‹±1m), Rauenberg, Bessel
to
ETRS89 (EU), geocentric, GRS80
Transformation parameters:
7 Parameter Helmert Transformation (Bursa-Wolf)
Coordinate Frame Rotation
Forward and Backward Transformation separate
Forward Transformation source system to WGS84
00597.046300 Translation vector for X-axis [meter]
00071.349100 Translation vector for Y-axis [meter]
00412.187300 Translation vector for Z-axis [meter]
-00.89181300 Rotation around the X-axis [seconds]
-00.05477000 Rotation around the Y-axis [seconds]
001.54161600 Rotation around the Z-axis [seconds]
0007.5733800 Scale correction factor [ppm]
Backward Transformation WGS84 to target system
00000.053700 Translation vector for X-axis [meter]
00000.050900 Translation vector for Y-axis [meter]
-0000.087300 Translation vector for Z-axis [meter]
-00.00218700 Rotation around the X-axis [seconds]
-00.01323000 Rotation around the Y-axis [seconds]
000.02138400 Rotation around the Z-axis [seconds]
0000.0026200 Scale correction factor [ppm]
With "off" switched flag lForBack the returned text looks dependently of
the geodetic source and target Reference Systems e.g. like this:
Geodetic Reference Systems:
DHDN/PD (DE Old States South ‹±1m), Rauenberg, Bessel
to
ETRS89 (EU), geocentric, GRS80
Transformation parameters:
7 Parameter Helmert Transformation (Bursa-Wolf)
Coordinate Frame Rotation
Forward and Backward Transformation united
Transformation source system to target system
00597.100000 Translation vector for X-axis [meter]
00071.400000 Translation vector for Y-axis [meter]
00412.100000 Translation vector for Z-axis [meter]
-00.89400000 Rotation around the X-axis [seconds]
-00.06800000 Rotation around the Y-axis [seconds]
001.56300000 Rotation around the Z-axis [seconds]
0007.5760000 Scale correction factor [ppm]
For NTv2 reference systems the returned text looks dependently of the
geodetic source and target Reference Systems e.g. like this:
Geodetic Reference Systems:
ETRS89 (DE-BY 2019 NTv2 BY_KanU_OFr ‹±2cm), geoc., GRS80
to
DHDN90 (DE-BY 2019 NTv2 BY_KanU_OFr ‹±2cm), Rauenb., Bessel
Transformation:
Grid based Reference System with NTv2 grid file
is just initialized with the NTv2 grid file
c:\programm_ntv2\deutschland\Bayern\kanu_ntv2_oberfranken.gsb
The NTv2 grid file should have the following file name:
kanu_ntv2_oberfranken.gsb (.gsa)
or
by-kanu_oberfranken.gsb (.gsa)
or
kanu_ntv2_oberfranken_ks.gsb (.gsa)
Unlocking:
This function is a component of the unlock requiring function group
"parameter determination". 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 no function calls are possible.
|