Prototype and description of the function gettransresiduals()

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

 

gettransresiduals()
Calculation of the residuals from a group of identical points using a Helmert
or Molodenski parameter set.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettransresiduals(
     double aCartQ[][3],
     double aCartZ[][3],
     double aResid[][3],
     unsigned long nCount,
     unsigned short nTyp,
     double aParam[7]);

Prototype of the DLL function in Visual Objects syntax:
_DLL FUNCTION gettransresiduals(;
     aCartQ AS REAL8 PTR,;                 // 4 Byte
     aCartZ AS REAL8 PTR,;                 // 4 Byte
     aResid AS REAL8 PTR,;                 // 4 Byte  nCount * 3 * sizeof(REAL8)
     nCount AS DWORD,;                     // 4 Byte
     nTyp AS WORD,;                        // 2 Byte
     aParam AS REAL8 PTR);                 // 4 Byte
AS LOGIC PASCAL:geodll32.gettransresiduals // 4 Byte


The function creates an array with resulting residuals froms two arrays with
Cartesian XYZ coordinates of identical points and a previously calculated
parameter set of the spatial Helmert Transformation or Molodenski
Transformation. The residuals can be used for subsequent corrections of the
coordinates, that are transformed using the Helmert or Molodenski parameter set.

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. 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. The
            structure of the array is described further below.

aResid[][3] Calculated residuals in a two dimensional array of type double in
(ref out)   meters for each of the X, Y and Z components of the coordinates in
            the arrays aCartQ and aCartZ. The structure of the array is
            described further below.
            For the array the calling function must allocate memory of the
            size nCount*3*sizeof(double) bytes.

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

nTyp        Geographic Transformation Method of the values in aParam.
            1: Helmert Transformation: Coordinate Frame Rotation
            2: Helmert Transformation: Position Vector Transformation
            3: Helmert Transformation: European Standard ISO 19111
            4: Molodenski Transformation

aParam[7]   Seven Helmert parameters in an array of 7 doubles. The variant with
(ref)       seven array elements must be used with Transformation Methods
.           1 to 3.
.           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.
.
or
aParam[3]   Three Molodenski parameters in an array of 3 doubles. The variant
(ref)       with three array elements must be used only with Transformation
.           Method 4.
.           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]
.           ----------------
.           | T1 | T2 | T3 |
.           ----------------
.           For the array the calling function must provide memory of the
.           size 3*sizeof(double) bytes.

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


The two dimensional arrays aCartQ[][3], aCartZ[][3] and aResid[][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 or Residuals 1 to n
X:             X component
Y:             Y component
Z:             Z component


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.