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. |