Prototype and description of the function gettransoutliers()

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

 

gettransoutliers()
Calculation of outliers in a group of identical points.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettransoutliers(
     double aCartQ[][3],
     double aCartZ[][3],
     unsigned long nCount,
     double aOutlVal[],
     unsigned long aOutlNo[],
     unsigned long nOutlMax,
     unsigned long *nOutlCount,
     unsigned long lIndexC);

Prototype of the DLL function in Visual Objects syntax:
_DLL FUNCTION gettransoutliers(;
     aCartQ AS REAL8 PTR,;                 // 4 Byte
     aCartZ AS REAL8 PTR,;                 // 4 Byte
     nCount AS DWORD,;                     // 4 Byte
     aOutlVal AS REAL8 PTR,;               // 4 Byte  nOutlMax * sizeof(REAL8)
     aOutlNo AS DWORD PTR,;                // 4 Byte  nOutlMax * sizeof(DWORD)
     nOutlMax AS DWORD,;                   // 4 Byte
     nOutlCount REF DWORD,;                // 4 Byte
     lIndexC AS LOGIC);                    // 4 Byte
AS LOGIC PASCAL:geodll32.gettransoutliers  // 4 Byte


The function scans through two arrays with Cartesian XYZ coordinates of
identical points and finds outliers, that have been included, for example, by
faulty measurements or erroneous data transfer. The outliers with a deviation
of more than 50% from the average value, will be returned in the array aOutlVal
as percentual values. In the array aOutlNo the indexes of coordinates in the
arrays aCartQ and aCartZ, that have been identified as outliers, are entered.
The detected outliers can be corrected in the coordinate arrays or can be
removed therefrom to obtain a plausible result.

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.

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

aOutlVal[]  Calculated ourliers in a one dimensional array of type double in
(ref out)   percent of the deviation from the average value.
            ---------------------------
            | V1 | V2 | V3 | ... | Vn |
            ---------------------------
            For the array the calling function must allocate memory of the
            size nOutlMax*sizeof(double) bytes.

aOutlNo[]   Indexes of coordinates in the arrays aCartQ and aCartZ, that have
(ref out)   been identified as outliers, in a one dimensional array of type
            "unsigned long". Depending on the value in lIndexC the indexes are
            registered with Null for the first array element (C, C++, Pearl,
            etc.) or with One for the first array element (Visual Objects,
            FORTRAN, etc.).
            ---------------------------
            | N1 | N2 | N3 | ... | Nn |
            ---------------------------
            For the array the calling function must allocate memory of the
            size nOutlMax*sizeof(long) bytes.

nOutlMax    Maximum number of outliers to be determined. The search for outliers
            is terminated when the number has been reached nOutlMax. If all
            outliers are to be determined, it is sensible, that you enter the
            same value as for the argument nCount.

nOutlCount  In this argument the function returns the actual number of
            identified outliers to the calling routine.

lIndexC     Switch for the index number of first array elements useable in
            different programming languages. In the array aOutlNo the indexes
            are entered in different ways depending on the switch position.
            TRUE: First array index is Null (C, C++, Pearl, ec.).
            (default)
            FALSE: First array index is One (Visual Objects, FORTRAN, ec.).

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:             Kartesian X component
Y:             Kartesian Y component
Z:             Kartesian 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.