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

coordtransepsg() Coordinate Transformation and Reference System Transition with EPSG codes of the Coordinate Reference Systems. Prototype of the DLL function in C++ syntax (attend lower case!): extern "C" __declspec(dllimport) unsigned long __stdcall coordtransepsg( double nCoordXQ, double nCoordYQ, double nEllHgtQ, unsigned short nEpsgQ, double *nCoordXZ, double *nCoordYZ, double *nEllHgtZ, unsigned short nEpsgZ); Prototype of the DLL function in Visual Objects syntax: _DLL function coordtransepsg(; nCoordXQ as real8,; // 8 Byte nCoordYQ as real8,; // 8 Byte nEllHgtQ as real8,; // 8 Byte nEpsgQ as word,; // 2 Byte nCoordXZ ref real8,; // 4 Byte nCoordYZ ref real8,; // 4 Byte nEllHgtZ ref real8,; // 4 Byte nEpsgZ as word); // 2 Byte as logic pascal:geodll32.coordtransepsg // 4 Byte The function converts the numeric source coordinates nCoordXQ and nCoordYQ from the EPSG source Coordinate Reference System nEpsgQ to the numeric target coordinates nCoordXZ and nCoordYZ of the EPSG target Coordinate Reference System nEpsgZ. For both source and target coordinates either two numeric parameter will be passed. The transformation is accomplished with high exactness and great speed. If one of the EPSG Coordinate Reference Systems is a 3D system, the ellipsoidical height nEllHgtQ of the source system ellipsoid is included in the calculation. As the result, the ellipsoidical height nEllHgtZ of the target system ellipsoid is returned. Also calculations with cartesian coordinates are possible. Using the EPSG codes all the settings for the Coordinate Systems and Reference Systems of the equivalent EPSG Coordinate Reference Systems ar made. If necessary, also Meridian Strip Numbers and the projection type 2D or 3D are set. EPSG is the acronym for "European Petroleum Survey Group Geodesy". This is a working group of the European oil and gas exploration companies. The EPSG and their successors OGP "International Association of Oil and Gas Producers" have made it to their task to build a system with globally unique identitfiers (EPSG codes) for geodetic data, such as Coordinate Reference Systems, Reference Ellipsoids or Map Projections. For most EPSG codes, in addition to the preset Coordinate System different Reference Systems can be used. In GeoDLL, however, only a single reference system is preset. To determine which coordinate and Reference Systems and other parameters are preset in GeoDLL for a particular EPSG code, you can use the getepsg2geodll() function (see below). If you want to deviate from the default parameters, please do not use coordtransepsg(), but one of the other coordtrans() functions. Preferably, the function coordtrans3dex() is to be used since it can process all parameters that match an EPSG code. The coordinates and Reference Systems and other parameters preset in GeoDLL for EPSG codes are marked with their GeoDLL numbers in the "List with supported EPSG codes" in the user manual and in the online manual (http://www.killetsoft.de/h_geodll_e/handbuch_e.htm). Some EPSG codes use reference systems with datum transitions vian NTv2 or HARN files. This is not always obvious at first glance when using the function coordtransepsg(). Therefore, the following should be noted: 1. NTv2 or HARN datum transitions only work within the scope of the NTv2 or HARN file. Usually this is for example only one country / state, one US state or one German federal state. 2. Both reference systems must be of the same type: Helmert / Molodenski --› Helmert / Molodenski. NTv2 / HARN --› NTv2 / HARN (with the same NTv2 or HARN file). It is expressly noted, that not always exactly the same parameters for Coordinate Transformations and Reference System Transitions are used by GeoDLL, as they are present in the EPSG database. The reason for this is that some EPSG parameter sets do not meet the quality standards of KilletSoft products. GeoDLL mostly uses parameter sets which have been published by the respective survey administrations or have made firsthand available to KilletSoft by them or even have been purchased from them. KilletSoft has created its own high-quality data collection of exact geodetic parameter sets over the past years. Since the EPSG coding is used in many GIS and thus has obtained a high level of awareness, we provide some functions, that simplifies the selection of the required Coordinate Systems and Reference Systems while programming with GeoDLL. It does not always make sense to use the coordtransepsg() function to select a CRS. An EPSG code usually refers to a Coordinate System and to one of many possible Reference Systems. In GeoDLL, only one widely used Reference System for the respective Coordinate System is preset when using an EPSG code. Depending on the specific case, a Reference System other than the default one must be selected. This is necessary, for example, if several variants of different epochs and resolutions are available for the Reference System. If a Reference System other than the default one is more suitable, this should be realized, for example, with the functions getepsg2geodll() and coordtrans3dex(). Functions using EPSG coding: coordtransepsg() This function getepsg2geodll() Determination of predefined GeoDLL numbers belonging to an EPSG code getepsgcrsname() Determination of the designation of a EPSG CRS The parameters are passed and/or returned as follows: nCoordXQ Longitude, East or X component of the numeric source coordinate. The input format of the coordinate (notation) is described in the data form of the EPSG Coordinate Reference System (see EPSG database). nCoordYQ Latitude, North or Y component of the numeric source coordinate. The input format of the coordinate (notation) is described in the data form of the EPSG Coordinate Reference System (see EPSG database). nEllHgtQ Ellipsoidical height of the source coordinate or Z component of a cartesian coordinate. If the EPSG Coordinate Reference System is a 3D system, the ellipsoidal height of the source coordinate is considered. nEpsgsQ EPSG code for the source Coordinate Reference System. All parameters are described in the data form of the EPSG Coordinate Reference System (see EPSG database). nCoordXZ Longitude, East or X component of the numeric target (ref) coordinate. The output format of the coordinate (notation) is described in the data form of the EPSG Coordinate Reference System (see EPSG database). nCoordYZ Latitude, North or Y component of the numeric target (ref) coordinate. The output format of the coordinate (notation) is described in the data form of the EPSG Coordinate Reference System (see EPSG database). nEllHgtZ Ellipsoidical height of the target coordinate (ref) or Z component of a cartesian coordinate. If the EPSG Coordinate Reference System is a 3D system, the ellipsoidal height of the target coordinate will be calculated. nEpsgZ EPSG code for the target Coordinate Reference System. All parameters are described in the data form of the EPSG Coordinate Reference System (see EPSG database). 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 of standard settings. The syntax and range examination can be switched off by the function setCoordArea(). 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". 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". |