Prototype and description of the function coordtrans3dex() (Function of the unlock requiring group "Coordinate Transformations") |

coordtrans3dex() 3D Coordinate Transformation and Reference System Transition for numeric and alphanumeric coordinates with memory allocation for the return strings and with disabling of meridian strip numbers. Prototype of the DLL function in C++ syntax (attend lower case!): extern "C" __declspec(dllimport) unsigned long __stdcall coordtrans3dex( double nCoordXQ, double nCoordYQ, const char *pszCoordQ, double nEllHgtQ, unsigned short nCoordSysQ, unsigned short nRefSysQ, unsigned short nUnitQ, unsigned short nStripQ, unsigned long lNoStripQ, double *nCoordXZ, double *nCoordYZ, char **pszCoordZ, double *nEllHgtZ, unsigned short nCoordSysZ, unsigned short nRefSysZ, unsigned short nUnitZ, unsigned short nStripZ, unsigned long lNoStripZ); Prototype of the DLL function in Visual Objects syntax: _DLL function coordtrans3dex(; nCoordXQ as real8,; // 8 Byte nCoordYQ as real8,; // 8 Byte pszCoordQ as psz,; // 4 Byte, char* nEllHgtQ as real8,; // 8 Byte nCoordSysQ as word,; // 2 Byte nRefSysQ as word,; // 2 Byte nUnitQ as word,; // 2 Byte nStripQ as word,; // 2 Byte lNoStripQ as logic,; // 4 Byte nCoordXZ ref real8,; // 4 Byte nCoordYZ ref real8,; // 4 Byte pszCoordZ ref psz,; // 4 Byte, char**, 20 alloc. nEllHgtZ ref real8,; // 4 Byte nCoordSysZ as word,; // 2 Byte nRefSysZ as word,; // 2 Byte nUnitZ as word,; // 2 Byte nStripZ as word,; // 2 Byte lNoStripZ as logic); // 4 Byte as logic pascal:geodll32.coordtrans3dex // 4 Byte The allocation of memory for "ref psz" / "char**" is necessary only if setstringallocate(FALSE) is called before. Note: Since version 14.60 two additional parameters nUnitQ and nUnitZ! The function converts the numeric source coordinates nCoordXQ and nCoordYQ or the alphanumeric source coordinate pszCoordQ from the source Coordinate System nCoordSysQ to the numeric target coordinates nCoordXZ and nCoordYZ or the alphanumeric target coordinate pszCoordZ of the target Coordinate System nCoordSysZ. For a both source and target coordinates either two numeric or one alphanumeric parameter will be passed. The transformation is accomplished with high exactness and great speed. The difference between the function coordtrans3dex() and the function coordtransex() is that this is a 3D transformation. Thereby in the case of using different source and target Reference Systems the ellipsoidical height is included in the calculation. For the calculation the ellipsoidical height nEllHgtQ of the source system ellipsoid is used. As the result, the ellipsoidical height nEllHgtZ of the target system ellipsoid is returned. The calculations are also possible with cartesian coordinates. 3D calculation are not possible when using a 'Reference System in an arbitrary NTv2 file' because no equivalent Helmert / Molodensky Reference System matching the NTv2 file is available for the ellipsoidal height calculation. The ellipsoidical height is geometrically defined as the distance of a point of a reference ellipsoid along the ellipsoid normal. The ellipsoidical height can be determined directly using GPS. But it may not be confused with leveled (orthometric) heights! The passed source coordinates and the calculated target coordinates are examined for the range validity within their Coordinate Systems and for syntactic correctness. The range validity is specified in the list "Defaults of the Coordinate Systems". The range and syntax check can be switched on or off with the function setcoordarea(). If in nCoordSysQ or in nCoordSysZ the values 1000 or 1100 are passed, the function uses the parameters of the user-defined Coordinate Systems passed before by the functions setusercoordsys1() and/or setusercoordsys2() and the earth ellipsoids defined before by the functions setuserellsource() and setuserelltarget() With the Coordinate Transformation a Reference System Transition from the geodetic Reference System nRefSysQ of the source Coordinate System can be considered to the geodetic Reference System nRefSysZ of the target Coordinate System. If in nRefSysQ or in nRefSysZ the value 0 is passed, then the geodetic Reference Systems, usual for the respective Coordinate Systems, are taken as a basis for the Reference System Transition. The standard reference systems are specified in the list of "Defaults of the Coordinate Systems". If in nRefSysQ or in nRefSysZ the value 1000 is passed, the function uses the parameters of the user-defined Reference Systems passed before by the functions setuserrefsys() and the earth ellipsoids defined before by the functions setuserellsource() and setuserelltarget() If in nRefSysQ or in nRefSysZ the value 1100 is passed or if both parameters have same value (larger than 0), no Reference System Transition is performed. Then the earth ellipsoids, usual for the respective coordinate systems, are taken as a basis for the Coordinate Transformation. The standard earth ellipsoids are specified in the list "Defaults of the Coordinate Systems". If in nRefSysQ or in nRefSysZ the value 1150 is passed, no Reference System Transition is performed. Then the earth ellipsoids defined before by the functions setuserellsource() and setuserelltarget() are taken as a basis for the Coordinate Transformation. If in nRefSysQ or in nRefSysZ the value 1200 is passed, no Reference System Transition nor Ellipsoid Transition are performed. If for Reference Systems nRefSysQ or nRefSysZ no Reference System parameters are defined, only an Ellipsoid Transition is performed, but no Reference System Transition is performed. For transformations from the source Coordinate Systems Gauss-Krueger and UTM the meridian strip nStripQ, to which the source coordinates refer, can be given. The given meridian strip should not deviate more than 3 strips from the native meridian strip of the source coordinate. If in nStripZ the value 0 is passed, the leading digits of the eastings are used for automatic calculations of the geographical lengths of the native meridian strip. If the parameter nStripQ contains a meridian strip number, with the value TRUE in the parameter lNoStripQ the input of reduced eastings is made possible. The eastings then may not contain leading meridian strip numbers. Example: nStripQ = 32, lNoStripQ = TRUE, UTM Easting 32564410 can be passed as 564410. For transformations to the target Coordinate Systems Gauss-Krueger and UTM the meridian strip nStripZ, to which the target coordinates refer, can be given. The given meridian strip should not deviate more than 3 strips from the native meridian strip of the target coordinate. If in nStripZ the value 0 is passed, an automatic calculation of the native meridians strip from the geographical length results. If the parameter nStripZ contains a meridian strip number, with the value TRUE in the parameter lNoStripZ the output of reduced Eastings can be determined. The eastings then do not contain leading meridian strip numbers. Example: nStripZ = 32, lNoStripZ = TRUE, UTM Easting 32564410 will be passed back as 564410. The following transformations are possible: Coordinate Transformations with maintaining the Reference System. Coordinate Transformations with Reference System Transition. Coordinate Transformation with Ellipsoid Transition when Reference System parameters not defined. Reference System Transition with maintaining the Coordinate System. Change of the notation (way of writing) with geographical coordinates. Change of the meridian strip with Gauss-Krueger and UTM coordinates. Input and output of reduced Gauss-Krueger and UTM coordinates. Conversion in the native meridian strip with Gauss-Krueger and UTM coordinates. The parameters are passed and/or returned as follows: nCoordXQ Longitude, East or X component of the numeric source coordinate. During processing of an alphanumeric coordinate this parameter is without meaning. The input format of the coordinate (notation) is described in the list "Defaults of the Coordinate Systems". nCoordYQ Latitude, North or Y component of the numeric source coordinate. During processing of an alphanumeric coordinate this parameter is without meaning. The input format of the coordinate (notation) is described in the list "Defaults of the Coordinate Systems". pszCoordQ Alphanumeric source coordinate. During processing of a numeric coordinate this parameter is without meaning. In this case for pszCoordQ a NULL pointer can be passed. The input format of the coordinate (notation) is described in the list "Defaults of the Coordinate Systems". nEllHgtQ Ellipsoidical height of the source coordinate or Z component of a cartesian coordinate. With 3D transformations in the case of using different source and target Reference Systems (nRefSysQ, nRefSysZ), the ellipsoidical height of the source coordinate is considered. nCoordSysQ Coordinate System of the source coordinates. (see list "Coordinate Reference Systems"). nRefSysQ Geodetic Reference System of the source coordinates. (see list "Coordinate Reference Systems"). nUnitQ Measurement Unit of the source coordinates. 0 The source coordinates are specified in a standard Measurement Unit, as for the Coordinate System preset in GeoDLL. If necessary, they are translated in meters for internal use. (see list "Default settings" [source code: settings_e.txt]). › 0 The source coordinates are specified in a particular Measurement Unit and are translated in meters for internal use. (see list "Coordinate Reference Systems alphabetical" [source: sysalpha_e.txt]). 1000 No effect. The source coordinates are not converted to another Measurement Unit. nStripQ Meridian strip to use with the source Coordinate System. This parameter has only an effect, if a "Transversal Mercator meridian strip system" is registered in nCoordSysQ. 0 Using of the leading digits of the easting for the calculation of the natural meridian strip. › 0 Using of the value in nStripQ for the calculation of the natural meridian strip. lNoStripQ Setting for the suppressing of the meridian strip number in the eastings. This parameter has only an effect, if a "Transversal Mercator meridian strip system" is registered in nCoordSysQ. TRUE Eastings must be passed without leading meridian strip numbers. FALSE Eastings must be passed with leading meridian strip numbers. nCoordXZ Longitude, East or X component of the numeric target (ref) coordinate. During processing of an alphanumeric coordinate this parameter is without meaning. The return format of the coordinate (notation) is described in the list "Defaults of the Coordinate Systems". nCoordYZ Latitude, North or Y component of the numeric target (ref) coordinate. During processing of an alphanumeric coordinate this parameter is without meaning. The return format of the coordinate (notation) is described in the list "Defaults of the Coordinate Systems". pszCoordZ Alphanumeric target coordinate. (ref) During processing of a numeric coordinate this parameter is without meaning. In this case for pszCoordZ a NULL pointer can be passed. The return format of the coordinate (notation) is described in the list "Defaults of the Coordinate Systems". Note: "ref pszCoordZ" corresponds to "char**" in C. 20 bytes of memory for the zero terminated string must be allocated with dependence to the call of the function setstringallocate(). Please consider the notes in the description of the function setstringallocate(). nEllHgtZ Ellipsoidical height of the target coordinate (ref) or Z component of a cartesian coordinate. With 3D transformations in the case of using different source and target Reference Systems (nRefSysQ, nRefSysZ), the ellipsoidical height of the target coordinate is calculated. nCoordSysZ Coordinate System of the target coordinates. (see list "Coordinate Reference Systems"). nRefSysZ Geodetic Reference System of the target coordinates. (see list "Coordinate Reference Systems"). nUnitZ Measurement Unit of the target coordinates. 0 The target coordinates will be calculated in a standard Measurement Unit, as for the Coordinate System preset in GeoDLL. If necessary, they will be translated from internal useed meters to the preset Measurement Unit. (see list "Default settings" [source code: settings_e.txt]). › 0 The target coordinates will be calculated in a particular Measurement Unit. They will be translated from internal useed meters to the given Measurement Unit. (see list "Coordinate Reference Systems alphabetical" [source: sysalpha_e.txt]). 1000 No effect. The target coordinates are not converted to another Measurement Unit. nStripZ Meridian strip to use with the target Coordinate System. This parameter has only an effect, if a "Transversal Mercator meridian strip system" is registered in nCoordSysZ. 0 Calculation of the native meridian strip from the geographic longitude. › 0 Calculation of the easting with the strip number nStripZ as native meridian strip. lNoStripZ Setting for the suppressing of the meridian strip number in the eastings. This parameter has only an effect, if a "Transversal Mercator meridian strip system" is registered in nCoordSysZ. TRUE Eastings are returned without leading meridian strip numbers. FALSE Eastings are returned with leading meridian strip numbers. returnVal In case of an error the function returns FALSE, otherwise TRUE. Range validity The range limitations of the source coordinates and the calculated target coordinates are examined on the basis the geographical coordinates specified under the term "Range (Lon / Lat)" in the list "Defaults of the Coordinate Systems". The syntax and range examination can be switched off by the function setCoordArea(). With user-defined Coordinate Systems the range values are calculated automatically from the origin point of the respective Coordinate System. Notations The coordinates of the different Coordinate Systems are written with the notations specified under the term "Notation (E / N)" in the list "Defaults of the Coordinate Systems". As many as desired right-of-comma positions can be added. A specification of the notations can be found at the end of the list "Defaults of the Coordinate Systems". Standard Reference Systems The Reference Systems specified under the term "Standard RefSys" in the list "Defaults of the Coordinate Systems" are assigned to the coordinates systems, if in the parameters nRefSysQ or nRefSysZ a zero is passed. Special features using NTv2 grid files Download of NTv2 files: The commonly used NTv2 files can be download from the KilletSoft-Website or can be purchased from suppliers of geoservices. Encrypted NTv2 files: To protect the rights of some authors that provide NTv2 files specifically for use with KilletSoft products, GeoDLL supports encrypted NTv2 files that can be download from the KilletSoft website. Polygonal Validity Scopes: The scope of an NTv2 file is by default defined by quadrangular coordinate boxes. In order to be able to implement polygonal structures, e.g. such as national borders, the producer of an NTv2 file therein can specify a Polygonal Validity Scope. For this, outside of the poligonal validity located grid meshes are indicated by the exopolygonal entries -99/-99 in their shift or accuracy values. GeoDLL can check the grid meshes on exopolygonal entries and exclude hits from the calculation and comment them with an error message. The Polygonal Validity Check will be switched on or off using the function setntvpolyvalid(). Detailed information can be found in the help section "Polygonal Validity Scopes". functions Please take further references from the description of the functions coordtrans() and coordtrans3d(). Unlocking: This function is a component of the unlock requiring function group "Coordinate Transformations". 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. Reference System Transitions with NTv2 grid files require an additional unlocking of the function group "NTv2 Transformations". |