Prototype and description of the function gettranshelmert()

(Function of the unlock requiring group "Transformation Parameter")

 

gettranshelmert()
Calculation of Seven Helmert Parameters and a rotation matrix from
identical points in different Reference Systems.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettranshelmert(
     double aCartQ[][3],
     double aCartZ[][3],
     unsigned long nCount,
     unsigned short nTyp,
     unsigned short nIterat,
     unsigned short *nItNeed,
     double aHelmert[7],
     double aRotMat[][3]);

Prototype of the DLL function in Visual Objects syntax:
_DLL FUNCTION gettranshelmert(;
     aCartQ as real8 ptr,;                   // 4 Byte
     aCartZ as real8 ptr,;                   // 4 Byte
     nCount as dword,;                       // 4 Byte
     nTyp as word,;                          // 2 Byte
     nIterat as word,;                       // 2 Byte
     nItNeed ref word,;                      // 4 Byte
     aHelmert as real8 ptr,;                 // 4 Byte
     aRotMat as real8 ptr);                  // 4 Byte
AS logic pascal:geodll32.gettranshelmert     // 4 Byte


The function calculates Seven Helmert Transformation Parameters and a
Rotation Matrix from identical points in different source and target
Coordinate Reference Systems. The identical points are stored in arrays as
cartesian coordinates.

The Helmert transformation is a transformation for three-dimensional
Cartesian coordinates. It contains as parameters three translation vectors,
three rotation angles and a scale factor.

The maximum iteration depth for a very accurate calculation of the
transformation parameters is calculated automatically by the function depending
on the number of identical points, if the parameter nIterat is set to null. For
point clouds with plausible identical points, a few iterations are usually
sufficient to achieve the required accuracy and thus to finish the calculation.
But if the automatically predefined maximum iteration depth is exceeded, the
function terminates with an error message.

With a small expansion of a point cloud or with a small number of identical
points, it may happen that the expected accuracy is not achieved when passing
through the automatically predefined maximum iteration depth. In order to
obtain a result anyway, the iteration depth can be specified in the nIterat
parameter. The function then terminates the calculation without an error
message. In extreme cases, however, the parameters calculated in this way may
be inaccurate or even incorrect. In case of doubt, the function
gettransmolertensky() should be used instead of the function gettranshelmert().
The Molodensky Transformation provides a useful result even in extreme cases,
although it does not have the high accuracy of the Helmert transformation.

To check the iteration depth, the function returns in the nItNeed parameter the
count of the effective iterations to the calling routine.

The rotations are also available as a spatial rotation matrix. For this a
rotation matrix with 3 x 3 rotation elements is generated. All KilletSoft
geodetic tools and programs use a complete rotation matrix for Helmert
transformations. The programs of many other manufacturers use a simplified
rotation matrix, which provides accurate results only for small rotation
angles.

Here is the syntax of the full rotation matrix for the "Coordinate Frame
Rotaion" transformation method:
Cos(Ry)*Cos(Rz)
     Cos(Rx)*Sin(Rz) + Sin(Rx)*Sin(Ry)*Cos(Rz)
          Sin(Rx)*Sin(Rz) - Cos(Rx)*Sin(Ry)*Cos(Rz)
-Cos(Ry)*Sin(Rz)" + CRLF
     Cos(Rx)*Cos(Rz) - Sin(Rx)*Sin(Ry)*Sin(Rz)
          Sin(Rx)*Cos(Rz) + Cos(Rx)*Sin(Ry)*Sin(Rz)
Sin(Ry)
     -Sin(Rx)*Cos(Ry)
          Cos(Rx)*Cos(Ry)

The syntax of the simplified rotation matrix has this form:
  1   Rz  -Ry
-Rz    1   Rx
 Ry  -Rx    1

For the other transformation methods (except Molodensky) the same syntax
applies, only some signs are reversed.

Since the function due to the extensive calculations is time-consuming,
the event handling during the calculation by interrupting the processing
loop can be are allowed bei calling the function seteventloop().


The parameters are passed and/or returned as follows:
aCartQ[][3] Cartesian coordinates X, Y, Z of the source Coordinate Reference
(ref)       System in a two dimensional array of type double. The first
            dimension counts the available cartesian source coordinates of
            the identical points given in nCount. The second dimension is
            3 for the X, Y and Z component of a cartesian source coordinate.
            The length of the arrays aCartQ and aCartZ must be identical.
            There must be at least three coordinate triples available. The
            structure of the array is described further below.

aCartZ[][3] Cartesian coordinates X, Y, Z of the target Coordinate Reference
(ref)       System in a two dimensional array of type double. The first
            dimension counts the available cartesian target coordinates of
            the identical points given in nCount. The second dimension is
            3 for the X, Y and Z component of a cartesian target coordinate.
            The length of the arrays aCartQ and aCartZ must be identical.
            There must be at least three coordinate triples available. The
            structure of the array is described further below.

nCount      Count of the available identical points stored as cartesian
            coordinates in the arrays aCartQ and aCartZ.

nTyp        Geographic Transformation Method of the Helmert Parameters.
            1: Coordinate Frame Rotation
            2: Position Vector Transformation
            3: European Standard ISO 19111

nIterat     Predefined maximum iteration depth for the calculation of the
            Helmert Transformation Parameters.
            nIterat = 0: Automatic determination of the iteration depth
              depending on the number of Cartesian Coordinates.
              nCount ›= 50000: nIterat = nItMax =  20
              nCount ›= 10000: nIterat = nItMax =  30
              nCount ›= 5000:  nIterat = nItMax =  40
              nCount ›= 1000   nIterat = nItMax =  50
              nCount ›= 500    nIterat = nItMax =  60
              nCount ›= 100    nIterat = nItMax =  70
              nCount ›= 50     nIterat = nItMax =  80
              nCount ›= 25     nIterat = nItMax =  90
              nCount ›= 3      nIterat = nItMax = 100
            nIterat ›= 5 and nIterat ‹ nItMax: Maximum iteration depth
            nIterat ‹ 5 or nIterat ›= nItMax: see nIterat == 0

nItNeed     Iteration depth actually required for the calculation. In case of
(ref out)   an error null is returned.

aHelmert[7] Seven Helmert parameters in an array of 7 doubles.
(ref out)   1. array element: Translation vector for X-axis [meter]
            2. array element: Translation vector for Y-axis [meter]
            3. array element: Translation vector for Z-axis [meter]
            4. array element: Rotation angle around the X-axis [seconds]
            5. array element: Rotation angle around the Y-axis [seconds]
            6. array element: Rotation angle around the Z-axis [seconds]
            7. array element: Scale correction factor [ppm]
            ------------------------------------
            | T1 | T2 | T3 | R1 | R2 | R3 | SF |
            ------------------------------------
            For the array the calling function must provide memory of the
            size 7*sizeof(double) bytes.

aRotMat[3][3]  Rotation Matrix of the spatial Helmert Transformation in an
(ref out)   array of 3 times 3 doubles. The syntax of the matrix is described
            above.
            -------------------
            | w11 | w21 | w31 |
            | w12 | w22 | w32 |
            | w13 | w23 | w33 |
            -------------------
            The signs of w can change in dependence of the Transformation
            Method. For the array the calling function must provide memory
            of the size 3*3*sizeof(double) bytes.
  or
NULL ptr    No Rotation Matrix is calculated.

returnVal   In case of an error the function returns FALSE, otherwise TRUE.


The two dimensional arrays aCartQ[][3] und aCartZ[][3] are filled with values
of type double and are structured as follows:
----------------------------------------------------------------------
| C1-X | C1-Y | C1-Z | C2-X | C2-Y | C2-Z | ... | Cn-X | Cn-Y | Cn-Z |
----------------------------------------------------------------------
with C1 -› Cn: Coordinates 1 to n
X:             Cartesian X component
Y:             Cartesian Y component
Z:             Cartesian Z component
At least three identical points with coordinate triples are needed for the
calculation.


Unlocking:
This function is a component of the unlock requiring function group
"Transformation parameter". It is unlocked for unrestricted use together
with other functions of the group by passing the unlock parameters, acquired
from the software distribution company, trough the function setunlockcode().
Without unlocking at most 25 identical points can be processed.