Prototype and description of the function coordcalcextra() (Function of the unlock requiring group "Coordinate Transformations") |
coordcalcextra() Calculation of Extra Parameters during coordinate transformations with the coordtrans*() functions. Meridian Convergence, Origin Center and Geographical Point coordinate. Prototype of the DLL function in C++ syntax (attend lower case!): extern "C" __declspec(dllimport) unsigned long __stdcall coordcalcextra( double *nGeoLonQ, double *nGeoLatQ, double *nOriginQ, double *nConvergenceQ, double *nGeoLonZ, double *nGeoLatZ, double *nOriginZ, double *nConvergenceZ); Prototype of the DLL function in Visual Objects syntax: _DLL function coordcalcextra(; nGeoLonQ ref real8,; // 4 Byte nGeoLatQ ref real8,; // 4 Byte nOriginQ ref real8,; // 4 Byte nConvergenceQ ref real8,; // 4 Byte nGeoLonZ ref real8,; // 4 Byte nGeoLatZ ref real8,; // 4 Byte nOriginZ ref real8,; // 4 Byte nConvergenceZ ref real8); // 4 Byte as logic pascal:geodll32.coordcalcextra // 4 Byte The function calculates additional (extra) parameters for each coordinate transformation performed with functions of the type coordtrans*(). The prerequisite for this is the previous activation of the calculations by the function setcalcextra(). The Extra Parameters can be prompted after each coordinate transformation. The Extra Parameters calculated by a coordinate transformation are retained until the function setcalcextra() with set parameter on TRUE is called next time. The following Extra Parameters are available: Longitude of the Geographical Point coordinate in the source system. Latitude of the Geographical Point coordinate in the source system. Longitude of Origin Center in the source System. Meridian Convergence at the Geographical Point in the source system. Longitude of the Geographical Point coordinate in the target system. Latitude of the Geographical Point coordinate in the target system. Longitude of Origin Center in the target System. Meridian Convergence at the Geographical Point in the target system. Coordinates in arbitrary coordinate Reference Systems (CRS) can always be converted into Geographical Point Coordinates. They are available for the source system and for the target system. The Longitude of Origin Center is the north-aligned central meridian of the Coordinate System. The Meridian Convergence is often also referred as map convergence or grid convergence. The Meridian Convergence is the angle between the north direction of the coordinate grid and the geographic north direction at the Origin Center. It can be calculated e.g. for all Mercator and Lambert projections. The convergence is available for the source system and for the target system. Note that the calculation of some Extra Parameters is not possible with every coordinate transformation. In these cases, the values -9999 are returned for the corresponding Extra Parameters. The Meridian Convergence and the Central Meridian are currently supported by the following systems: All Transversal Mercator systems All normal Mercator systems All Lambert Conformal Conic systems If no Extra Parameters could be calculated, the function is terminated with the return value FALSE and all Extra Parameters have the value -9999. This function may be extended in later GeoDLL versions. Please ensure the correct parameter passing after you have installed an update! The parameters are returned as follows: nGeoLonQ Geographical longitude in decimal notation calculated from (ref) the source coordinate (Geographical Point). Or -9999, if the value could not be calculated. nGeoLatQ Geographical latitude in decimal notation calculated from (ref) the source coordinate (Geographical Point). Or -9999, if the value could not be calculated. nOriginQ Longitude of Origin Center in the source system. Or -9999, if the value could not be calculated. nConvergenceQ Meridian Convergence at the Geographical Point in the source (ref) system. Or -9999, if the value could not be calculated. nGeoLonZ Geographical longitude in decimal notation calculated from (ref) the target coordinate (Geographical Point). Or -9999, if the value could not be calculated. nGeoLatZ Geographical latitude in decimal notation calculated from (ref) the target coordinate (Geographical Point). Or -9999, if the value could not be calculated. nOriginZ Longitude of Origin Center in the target system. Or -9999, if the value could not be calculated. nConvergenceZ Meridian Convergence at the Geographical Point in the target (ref) system. Or -9999, if the value could not be calculated. returnVal In case of error the function returns FALSE, otherwise TRUE. 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. |