Prototype and description of the function setuserrefsys()

(Function of the unlock requiring group "User definitions")

 

setuserrefsys()
Configuration of the transformation parameters for a user-defined Reference
System Transition between two geodetic Reference Systems.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall setuserrefsys(
     unsigned short nRefSysTyp,
     double nTranslatX,
     double nTranslatY,
     double nTranslatZ,
     double nRotatX,
     double nRotatY,
     double nRotatZ,
     double nMeasure);

Prototype of the DLL function in Visual Objects syntax:
_DLL function setuserrefsys(;
     nRefSysTyp as word,;                  // 2 Byte
     nTranslatX as real8,;                 // 8 Byte
     nTranslatY as real8,;                 // 8 Byte
     nTranslatZ as real8,;                 // 8 Byte
     nRotatX as real8,;                    // 8 Byte
     nRotatY as real8,;                    // 8 Byte
     nRotatZ as real8,;                    // 8 Byte
     nMeasure as real8);                   // 8 Byte
as logic pascal:geodll32.setuserrefsys     // 4 Byte


The function passes transformation parameters for a user-defined Reference
System Transition between two geodetic Reference Systems. Three translation
vectors and if necessary three rotation angles and a scale factor will be
passed.

Calculation methods:
There are three different variants of Parameter Sets with seven parameters
each and one with only three parameters. The Seven Parameter Sets are
called Helmert Transformation or also Bursa-Wolf Transformation. They are
defined by three linear shifts (dx, dy, dz), three angular rotations
around the axis (rx, ry, rz), and a scale factor. The Three Parameter Set
is called a Molodensky Transformation. It is defined only with three
linear shifts (dx, dy, dz).

These variants are supported by GeoDLL:
   "Coordinate Frame Rotation"
   "Position Vector Transformation"
   "European Standard ISO 19111"
   "Molodensky Transformation"

Coordinate Frame Rotation
This variant of the Helmert Transformation is used by the United States,
Australia, New Zealand, and a few other countries surveying authorities.
The "Coordinate Frame Rotation" is defined as follows:
Line of sight from the earth center outward
Thereby direction of rotation is positive counterclockwise
Unit of the rotations in Old Seconds

Position Vector Transformation
This variant of the Helmert Transformation is used by most European
surveying authorities. The variant is used in Europe still very
frequently, but it will be replaced by the ISO 19111 standard in the next
years.
The transformation algorithm is based on the same three translation
vectors and the scale correction, as in case of the “Coordinate Frame
Rotation”, but different definitions of the three rotation angles. The
rotation angles have the opposite signs, and it is easy to convert from
one variant to the other simply by changing the signs of the three
rotation values.
The "Position Vector Transformation" described as follows:
Line of sight from outward to the earth center
Thereby direction of rotation is positive clockwise
Unit of the rotations in Old seconds

European Standard ISO 19111
This variant of the Helmert Transformation was explained by ISO guideline
as the European standard. The variant differs from the "Position Vector
Transformation" only by the indication of the three angles of rotation in
another unit.
The "European Standard ISO 19111" described as follows:
Line of sight from outward to the earth center
Thereby direction of rotation clockwise positively
Unit of the rotations in µRad (Rad * 10^-6)

Molodensky Transformation
The calculation of the three translations are made from the average values
of the residuals.

Use of the Reference System parameters:
With the functions coordtrans?() the parameters of the user-defined
Reference System described here are used, if for the source and target
Reference Systems (nRefSysQ, nRefSysZ) the value 1000 is passed as flag.

It must be noted that for a user-defined Reference System Transition apart
from the transformation parameters also the semi axes of the source and
target ellipsoids are needed. Reading the ellipsoid semi axes is done with
the functions setuserellsource() and setuserelltarget().


The parameters are passed and/or returned as follows:
nRefSysTyp (Type of the user-defined Reference System)
   Parameter variable
               Description of the parameter

0              Erase the user-defined Reference System
   nTranslatX  0.0 or arbitrary value without effect
   nTranslatY  0.0 or arbitrary value without effect
   nTranslatZ  0.0 or arbitrary value without effect
   nRotatX     0.0 or arbitrary value without effect
   nRotatY     0.0 or arbitrary value without effect
   nRotatZ     0.0 or arbitrary value without effect
   nMeasure    0.0 or arbitrary value without effect

1              Set user-defined reference system "Coordinate Frame
               Rotation"
2              Set user-defined reference system "Position Vector
               Transformation"
3              Set user-defined reference system "European Standard
               ISO 19111"
4              Set user-defined reference system "Molodensky
               Transformation"
   nTranslatX  Translation vector on the X axis in meter
               Value range: -10000 to 10000 meter
   nTranslatY  Translation vector on the Y axis in meter
               Value range: -10000 to 10000 meter
   nTranslatZ  Translation vector on the Z axis in meter
               Value range: -10000 to 10000 meter
   nRotatX     Rotation angle of the X axis in seconds
               Value range: -900 to 900 seconds
               (-4500 bis 4500 µRad for European Standard ISO 19111)
               (0 for the Molodensky transformation)
   nRotatY     Rotation angle of the Y axis in seconds
               Value range: -900 to 900 seconds
               (-4500 bis 4500 µRad for European Standard ISO 19111)
               (0 for the Molodensky transformation)
   nRotatZ     Rotation angle of the Z axis in seconds
               Value range: -900 to 900 seconds
               (-4500 bis 4500 µRad for European Standard ISO 19111)
               (0 for the Molodensky transformation)
   nMeasure    Scale factor in ppm (parts per million).
               Value range: -1000 to 1000 ppm
               (0 for the Molodensky transformation)

returnVal      If the parameters for the user-defined Reference System
               are successful stored, the function returns TRUE,
               otherwise FALSE.


Unlocking:
This function is a component of the unlock requiring function group
"user definitions". 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.