KMSTRLIB SDK version 2.0 B18 Lars Hansen October 2009 KMSTRLIB SDK
KMS Transformation Library Software Development Kit User's Guide KMSTRLIB SDK User's Guide 1 / 30
1. Revision history...... 3
2. Introduction...... 3
3. SDK Overview...... 4
3.1 Installing the SDK...... 4
3.2 Included files...... 4
3.3 Redistributable files...... 4
3.4 SDK architecture...... 5
4. Transformation methods...... 5
5. Defining projections in KMSTRLIB using "Minilabels".....5
5.1 Supported projections...... 8
5.2 Projections with implicit datum...... 8
5.3 Projections that require additional parameters...... 10
5.4 (Vertical) datums...... 11
5.5 (Horizontal) Datums...... 12
5.6 Examples of projections and coordinate systems defined by Minilabels...... 14
5.7 Examples of minilabels defining projections that require ad- ditional parameters...... 14
6. Calling the DLL interface from C or C++...... 16
7. DLL Interface Reference...... 18
8. Calling the DLL interface from Visual Basic...... 25
9. Using the ActiveX/COM interface...... 26 KMSTRLIB SDK User's Guide 2 / 30
10. Reference: Methods and properties exposed by the Act- iveX/COM interface...... 26
11. Calling KMSTRLIB from .NET...... 28
12. References...... 29 KMSTRLIB SDK User's Guide 3 / 30
1. Revision history Build Modifications B17/18 . Based on September 2009 of the KMS transformation & geoid library.
. Additional files required for minimal install B16 . Based on July 2008 version of the KMS transformation & geoid library.
. Added new C# sample demonstration how to invoke the transformation library.
. Recompiled for use with MS VC 2005
. Revised documentation B14 . Based on December 2005 version of KMS transformation & geoid library.
. Added check for exact size of KMSSYSMS.DLL 12/13 . Modified KMSTRLIB.H for C compatibility 11 . Improved exception handling. 10 . Based on April 2004 version of KMS transformation & geoid library.
. Improved DLL loading.
. New sample program in C# .NET.
. Updated test program.
. Revised documentation. 9 . Recompiled with MSVC 7.1 8 . Message log removed 7 . Recompiled using MSVC 7.0
. Added functions for extending the horizon of S45/34 transformations 6 . Extended error message -3 is no longer reported as a transformation error KMSTRLIB SDK User's Guide 4 / 30
5 . Added new version of GDTRANSMS.DLL and new geoids
2. Introduction KMSTRLIB is a transformation library based on the GDTRANS library cre- ated by the Danish National Survey and Cadastre (KMS). The KMSTRLIB Software Development Kit (SDK) is designed for easy access to the trans- formation library from user applications running on the Win32 platform (Windows 95/98/Me/NT/2000/XP).
GDTRANS implements methods for conversion between a wide range of different projections and coordinate systems in both 2- and 3D. This func- tionality may be accessed by calling a C-style API exposed by the KM- STRLIB.DLL, alternatively by inserting the KMSTRLIBOCX.OCX ActiveX/COM Control in any host environment that supports the use of ActiveX/COM controls. A new sample demonstrates how to access the transformation library from .NET using P/Invoke.
3. SDK Overview
3.1 Installing the SDK To install the SDK, simply unzip the KMSTRLIB SDK package to an arbit- rary folder. For additional installation steps, please refer to the separate sections on how to access the various APIs exposed by KMSTRLIB.
Included files
The SDK contains the following files and folders
.
. KMSTRLIB Documentation.doc – this document.
. KMSFNCS.dll – Transformation library supplied by KMS.
. KMSTRLIB.dll – KMSTRLIB Transformation library wrapper.
. KMSTRLIBOCX.ocx – OCX Wrapper for KMSTRLIB.DLL
. Kmstrlib.h – KMSTRLIB header file KMSTRLIB SDK User's Guide 5 / 30
. KMSTRLIB.lib – Import library for MSVC 2005
.
.
. DEF_DTM.TXT, DEF_GRS.TXT, DEF_SHP.TXT - must be placed in the same folder as KMSTRLIB.DLL
3.2 Redistributable files To distribute KMSTRLIB as part of an application, include the following files in the distribution:
. KMSTRLIB.DLL . KMSFNCS.DLL . KMSTRLIBOCX.OCX (if the application uses the ActiveX/COM inter- face) .
3.3 SDK architecture . KMSFNCS.DLL contains the actual transformation routines provided by KMS, but should not be called directly.
. KMSTRLIB.DLL acts as a wrapper around KMSSYSMS.DLL and ex- poses the functionality of the transformation library. KMSTRLIB.LIB was built using MSVC 2005 and links to the multithreading DLL ver- sion of the C runtime library. All functions exposed by this DLL are fully thread-safe.
. KMSTRLIBOCX.OCX is an ActiveX/COM control wrapper around KM- STRLIB.DLL build using the MFC ActiveX Wizard in MSVC 2005. The OCX implements the apartment threading model, links to the shared DLL version of MFC and uses the DLL version of the C runtime library.
4. Transformation methods For further documentation on the transformation methods implemented by KMSTRLIB, please refer to [1]. KMSTRLIB SDK User's Guide 6 / 30
5. Defining projections in KMSTRLIB using "Minilabels" KMSTRLIB defines projections and coordinate systems by means of so-c- alled "MINILABELS" that describe projections and datums (including ver- tical datums). A MINILABEL has the following syntax:
Defines a regional label.
Defines a region.
(
(
Defines a coordinate label.
Defines a general projection.
For additional information, please refer to section 5.1, Supported projections.
Defines a general projection that requires additional parameters.
For additional information, please refer to section 5.3, Projections that require additional parameters.
s45b/dks/sb/sbf/gsgeo/gsbgeo/gs/gsb/kk/os/ fke/fk89/fg50/fu50/fg54/fk54/gk*w/gk*e/etrs-tm**/ETRS- TM**/etrs-lcc/ETRS-LCC/etrs-laea/ETRS-LAEA/ rt90g/rt90v/rt38v/eetm**/eetm*/eebm/eel2p/eelmne/eelms e/eegeo/eecrt) KMSTRLIB SDK User's Guide 7 / 30
Defines a projection with an implicit datum.
For additional information, please refer to section 5.2, Projections with implicit datum.
Labels with the separator N are automatically changed to H.._h_msl outside DK and to H...h_dvr90 within DK. I.e. FE_utm29Neuref89 -> FE_ut- m29Heuref89_h_msl and DK_utm32Neuref89 -> DK_utm32Heuref89_h_dvr90
Defines a (horizontal) datum.
For additional information, please refer to section 5.5, (Horizontal) Datums.
Defines a (vertical datum).
For additional information, please refer to section 5.4, (Vertical) datums
(
(
(
For additional information, please refer to section 5.3, Projections that require additional parameters. KMSTRLIB SDK User's Guide 8 / 30
*:== (0/1/2/3/4/5/6/7/8/9)
Notes:
1) Capital letters are only allowed in
2) Some strings that respect the syntax above may not make sense.
5.1 Supported projections crt Cartesian 3-d coordinates geo Geographical coordinates utm** UTM zone ** (** = 2 digits) utm**n UTM zone **, North latitude utm**s UTM zone **, South latitude safle Sansom-Flamsteed equiv. projection, ellips- oidial. safl Sansom-Flamsteed equiv. projection lmbac Lambert equiv. cylindrical projection. lmbap Lambert equiv. polar projection. npstg North polar stereographic projection. spstg South polar stereographic projection. upsn Universal polar stereographic N upss Universal polar stereographic S
5.2 Projections with implicit datum gsbgeo Geographic coordinates, gsb fg50 Faeroe Islands Geographic coordinates, ed50 fu50 Utm zone 29, top_ed50 fg54 Faeroe Islands Geographic coordinates, fd54 fk54 Conf. con. Faeroe Islands, fd 54 fke Conf. con. Faeroe Islands, euref89 KMSTRLIB SDK User's Guide 9 / 30
fk89 Conf. con. Faeroe Islands, fd 54a eegeo geogr. crd, Pulkovo 1942 dm Danish Mercator asb Oeresund bridge project. eetm** Estonian Gauss-Kr **, 6dg.z eetm* Estonian Gauss-Kr *, 3dg.z gk*w GI conf. con, W-Greenland gk*e GI conf. con, E-Greenland eel2p Estonian Lambert, 2 std par. geo Faeroe Islands, ed50 gsgeo Geographic coordinates, gs u32 Utm zone 32, ed50 tc32 TR Utm zone 32, ed50 u33 Utm zone 33, ed50 s34j System 1934 Jylland s34s System 1934 Sjælland s45b System 1945 Bornholm s34b System 1945 Bornholm gs GS conf. con. DK gsb GS conf. con. Bornholm kk Kbh. komm. system os Ostenfeldt system dks Oeresund bridge proj, sp sb SB bridge proj. sbf SB bridge proj., inverted rt38g RT38g, 2.5 gon vest rt90g RT90g, 2.5 gon vest rt90v RT90v, spec. for dks rt38v RT38v, spec. for dks lmbhjo KMSTRLIB SDK User's Guide 10 / 30
islmb kp2000s KP2000 Sjælland kp2000b KP2000 Bornholm kp2000j KP2000 Jylland-Fyn dktm1 Dansk transversal Mercator zone 1, Jyl- land vest for 10 E dktm2 Dansk transversal Mercator zone 2, Jylland øst for 9 E og Fyn dktm3 Dansk transversal Mercator zone 3, Sjælland og Lolland dktm4 Dansk transversal Mercator zone 4, Bornholm ETRS- European Terrestrial Reference System TM
5.3 Projections that require additional parameters estg Bc Nc Lc Ec Eql. Stereogr. projection stg Bc Nc Lc Ec Stereogr. projection mrc B0 N0 Lc Ec Mercator projection lmb B0 N0 Lc Ec Bc Lambert conf. con. dlmb B0 N0 Lc Ec B1 B2 Lambert 2 par. c. con. elmb B0 N0 Lc Ec B1 B2 Lambert eql. c. con. itm B0 N0 Lc Ec Scale ITM, general GAUSS-KR itmi B0 N0 Lc Ec Scale ITMI, inv. gen GAUSS-KR KMSTRLIB SDK User's Guide 11 / 30
Where
- BC,B0 are the latitude of origin
- Lc is the longitude of origin (or central meridian)
- Nc, N0 are northing constants
- Ec is an Easting constant
- Scale is the scale at the central meridian
5.4 (Vertical) datums dvr90 msl Mean sea level. gm91 ii50 evrt2000 European Veritical Reference System, European Verit- ical Reference Frame 2000. See [2], p 98. dnn Used as a common designator for gi50 and gm91
5.5 (Horizontal) Datums Datum Description Parent datum Ellipsoid wgs84 World Geodetic System ed50 WGS84 1984 ed50 European Datum 1950 ed50 Hayford nwl9d Naval Weapons Laboratory wgs84 NWL9D euref89 EUREF 89 wgs84 GRS80 ed87 European Datum 1987 ed50 Hayford wgs72 World Geodetic system 1972 nwl9d WGS72 fd54 Færø Datum 1954 ed50 Hayford qornoq Qornok Datum 1927 (til WG- nwl9d Hayford S84) nad83 North American Datum 1983 wgs84 GRS80 nad27 North American D.1927, Co- wgs84 Clarke66 KMSTRLIB SDK User's Guide 12 / 30
nus nad27c North American D.1927, wgs84 Clarke66 Canada pul42 Pulkowo 1942, temporary wgs84 Krassovsky island Hjørsey datum 1955 wgs84 Hayford scosd Scoresbysund datum nwl9d Hayford ammlk Ammassalik datum nwl9d Hayford srt90g SRT90, Sverige wgs84 Bessel rt90g RT90, Sverige wgs84 Bessel ed79 European Datum 1979 (fra wgs84 Hayford WGS84) dhdn Deutsches Hauptdreiecks- ed50 Bessel netz dhdnd Deutsches Hauptdreiecks- ed50 Bessel netz dhdn1 Deutsches Hauptdrnetz, euref89 Bessel DOEDOC dhdn2 Deutsches Hauptdrnetz, ed50 Bessel DOEDOC5p dhdn3 Deutsches Hauptdrnetz, ed50 Bessel DOEDOC7p nad83g North American D.1983 nwl9d GRS80 Greenland s34j @System 1934 Jylland ed50 Hayford s34s @System 1934 Sjælland ed50 Hayford s45b @System 1945 Bornholm ed50 Hayford gs @Generalst. Sys., Jyl. + Sjl ed50 GS gsb @Generalst. System, ed50 GS Bornholm os @Ostenfeldt System ed50 Bessel kk @Københavns Komm. Sys- ed50 Dansk tem sb @Storebælts System ed50 Hayford KMSTRLIB SDK User's Guide 13 / 30
sbf @Storebælts S., inv ed50 Hayford dks @ DKS ed50 Hayford asb @ ASB ed50 Hayford fg54 @ Geogr. FD 1954 euref89 Hayford fg50 @ Færø, Geogr ED 1950 Hayford euref89 fk54 @ Konf. con. FD 1954 euref89 Hayford fu50 @ UTM 29, Topogr. grid ED euref89 Hayford 50 fk89 @ Konf. con. FD 1989 euref89 Hayford rt90v @ RT90v ed50 Bessel rt38v @ RT38v ed50 Bessel rt38g @ RT38g ed50 Bessel eesti42 @ EESTI 1942 euref89 Krassovsky lok @ Lokalt kotesystem lok Hayford
5.6 Examples of projections and coordinate systems defined by Minilabels utm32_ed50 UTM Zone 32, European 1950, No vertical datum. geo_ed50 Geographical coordinates (radians), European 1950, No vertical datum. geoEed50 Geographical coordinates (radians), European 1950, Heights above ellipsoid. utm32_euref89 UTM Zone 32, EUREF89, No vertical datum. s34b System 34 Bornholm, No vertical datum s34jE System 34 Jylland/Fyn, Heights above ellipsoid crt_euref89 Cartesian coordinates, EUREF89, implicit heights DK_utm32Heure- UTM Zone 32, EUREF89, vertical datum dvr90 f89_h_dvr90 kp2000jH_h_dnn KP2000J, vertical datum dnn kp2000sE KP2000S, heights above the ellipsoid. dktm1H_h_dvr90 DKTM1, vertical datum dvr90 KMSTRLIB SDK User's Guide 14 / 30
5.7 Examples of minilabels defining projections that require addi- tional parameters Some of the supported projections, like general transverse mercator (itm), require additional parameters. In this case, the additional parameters must follow the minilabel. I.e. to define a general transverse mercator projec- tion, defined by latitude of origin, a false northing, longitude of origin, a false easting and a central scale factor, use the following minilabel:
"itm_wgs84 0sx 0m 150000sx 500000m 0.9996"
Please observe the use of unit designators: rad Radians nt Nautic Units: 360 degrees decimal minutes (60 minutes pr degree) cc Centigesimal Units: 400-degrees minutes (100 pr de- gree) decimal seconds (100.0 pr minute) sx Sexagesimal Units: 360-degrees minutes (60 min pr de- gree) and decimal arcseconds (60 secs pr min) km Kilometers m Meters mm Millimeters
For metric coordinates, the default units are meters.
A single space character inside a coordinate string is ignored. Such single space characters are used for making the coordinates more readable for humans. Normally a coordinate and its unit termination are separated by a "blind" space character (it looks nicer that way). A double space on this place would terminate the coordinate string, leaving the coordinate without unit termination. In this case the default unit type is used.
Examples:
60 00 34.33 sx (ok) 60..0 34.33 sx (error: minutes should be written using two digits) 0 00 34.33 sx (ok: leading zeros can be omitted) KMSTRLIB SDK User's Guide 15 / 30
0 34.33 sx (ok: leading zeros can be omitted) 1203344.555sx (ok) 44 55.6 nt (ok) 1 23 56.777 (no unit termination: default unit used) 6 555 666.777 m (ok) 5678.456 km (ok) 55 33.44 m (double space char inside coordinate string)
6. Calling the DLL interface from C or C++ To call the transformation library from C or C++, you'll have to
. Copy KMSTRLIB.DLL and KMSFNCS.DLL to a folder on the system search path. . If you are going to perform 3D transformations using the geoid library, copy the geoid library files to an arbitrary folder. . Include the file KMSTRLIB.H in your source. . Link with the import library (KMSTRLIB.LIB). Import libraries are provided for MSVC 2005 only. If you are using a different development environment, please refer to the documentation on the specific product for more information on creating import libraries.
In general, the sequences of calls to KMSTRLIB are:
. Call KMSTR_InitLibrary to initialise the library. . Call KMSTR_InitialiseGeoidLibrary if you are going to perform 3D transformations. . Call KMSTR_Transform to perform transformations. . Call KMSTR_TerminateLibrary when the library is no longer needed.
In a slightly more efficient approach, replace the call(s) to KMSTR_Trans- form with the following sequence of calls:
. Call KMSTR_CreateProjectionHandle to create projection handles for input and output projections. . Call KMSTR_TransformViaHandle to perform single or multiple trans- formations between projections using the same set of projections. . Call KMSTR_ReleaseProjectionHandle to release the projection handles. KMSTRLIB SDK User's Guide 16 / 30
The sample code below illustrates the basic use of the library: void SimpleTest() { if (KMSTR_InitLibrary()!=KMSTR_OK) { printf("Failed to initialise transformation library\n"); return; }
double X,Y,Z; KMSTR_Error R;
// Transform from UTM Zone 32 ED50 to lat/long WGS 84 (output in radians!) // without using projection handles R = KMSTR_Transform("s34s","utm32_ed50",97000,130000,0,&X,&Y,&Z); if (R!=KMSTR_OK) { printf("Transformation failed\n"); } else { printf("Output is %lf, %lf, %lf\n",X,Y,Z); }
// Terminate the use of the transformation library KMSTR_TerminateLibrary(); }
The following example demonstrates how to enable 3D transformations and perform the transformations using a slightly more efficient approach: void TestHandlesAnd3D() { if (KMSTR_InitLibrary()!=KMSTR_OK) { printf("Failed to initialise transformation library\n"); return; }
// Enable use of geoid library for subsequent 3D transformations // Make the path point to a folder in which the geoids are located! if (KMSTR_InitialiseGeoidLibrary("C:\\TEMP\\GEOIDS\\")!=KMSTR_OK) { printf("Failed to initialize geoid library\n"); return; }
// Test transformations using projection handles (this is slightly more efficient) // Set up projection handles for UTM Zone 32 ED50 DNN and // UTM Zone 32 EUREF 89 DVR90 KMSTRLIB SDK User's Guide 17 / 30
// Also demonstrates how to get an extended error message HKMSTR hIn = KMSTR_CreateProjectionHandle("utm32Hed50_h_dnn"); HKMSTR hOut = KMSTR_CreateProjectionHandle("utm32Heuref89_h_dvr90");
if ((hIn == NULL) || (hOut==NULL)) { printf("Failed to create projection handle\n"); } else { // Do some transformations using the projection handles for (double X = 500000; X<550000; X+=10000) { double Y = 6200000; double Z = 0; double Xout,Yout,Zout; int ExtendedErrorMessage;
KMSTR_Error E = KMSTR_TransformViaHandle( hIn,hOut, X,Y,Z, &Xout,&Yout,&Zout, &ExtendedErrorMessage);
if (E!=KMSTR_OK) { printf("Transformation failed with extended error message %d\n",Ex- tendedErrorMessage); } else { printf("Transformed %lf %lf %lf to %lf %lf %lf\n",X,Y,Z,Xout,Yout,Zout); } } }
// Release the projection handles (may be called safely with NULL handles!) KMSTR_ReleaseProjectionHandle(hIn); KMSTR_ReleaseProjectionHandle(hOut);
// Terminate the use of the transformation library KMSTR_TerminateLibrary(); }
7. DLL Interface Reference KMSTRLIB.H defines the following types and functions exposed by KM- STRLIB: KMSTRLIB SDK User's Guide 18 / 30
. enum KMSTR_Error - Error messages in integer format. Applications may cast these values into integers. The following values have been defined:
Value Name Meaning 0 KMSTR_OK No Error 1 KMSTR_LABELERROR Invalid input or output label 2 KMSTR_TRANSFORMATIONERROR Transformation failed for some reason. An extended error message may provide more additional information, See KMSTR_TransformViaHandle for more information. 3 KMSTR_EXCEPTION Caught exception (internal error) 4 KMSTR_GEOIDINITFAILED Failed to initialise geoid library 5 KMSTR_GDTRANSMSLOADFAILED Failed to load GDTRANSMS.DLL/KMSSYSMS.DLL 6 KMSTR_GEOIDSALREADYINITIALISED Geoid library has already been initial- ised. 7 KMSTR_ALLOCATIONFAILED Allocation failed (out of memmory).
. typedef void* HKMSTR - A projection handle. Although a projection handle in reality is a 32-bit pointer to a memory location, applications should not attempt to access any internal structures using the handle. Projection handles are a purely internal structure and should not be used for any purposes other than described in this document. I.e. do not attempt to compare two projections handles to determine if they represent the same projection.
Function: KMSTR_Error _stdcall KMSTR_InitLibrary() Purpose: Initialise the transformation library. This call must take place before any other library function is called. Parameters: None Return value: KMSTR_OK if successful.
Function: KMSTR_Error _stdcall KMSTR_InitLibrary2() Purpose: Present for backward compatibility only. Calls KMSTR_InitLibrary KMSTRLIB SDK User's Guide 19 / 30
Parameters: None Return value: KMSTR_OK if successful.
Function: void _stdcall KMSTR_TerminateLibrary() Purpose: Call this function when the transformation library is no longer needed. After this, calls to any other library functions are not allowed. Failing to call this function before exiting the main program may cause memory and resource leaks. Parameters: None Return value: None
Function: void _stdcall KMSTR_GetVersionID(char* pBuffer, int BufSize) Purpose: Call this function to return a string that describes the library version (i.e. "KMSTRLIB 1.0"). Parameters: char* pBuffer - pointer to array of chars allocated by caller
int BufSize - size of buffer (characters). If the version identification string is longer than the size of the allocated buffer, only BufSize char- acters are copied to the buffer. Return value: None
Function: KMSTR_Error _stdcall
KMSTR_InitialiseGeoidLibrary(const char* pFolder) Purpose: Initialise the use of the geoid library in transformations. This function must be called in order to enable 3D transformations and it must be called any calls to KMSTR_Transform or KMSTR_TransformVi- aHandle take place. In addition, it should be called once only. Parameters: . const char* pFolder - pointer to array of characters defining the name of the folder in which the geoid library files are store. The path name should end with a backslash, i.e. "C:\DATA\GEOIDS\" Return value: KMSTR_OK - if geoid library is succesfully initialised. KMSTRLIB SDK User's Guide 20 / 30
KMSTR_GEOIDINITFAILED - if initialisation failed.
KMSTR_GEOIDSALREADYINITIALISED - if geoid library has been previously initialised.
Function: HKMSTR _stdcall
KMSTR_CreateProjectionHandle(const char* pMinilabel) Purpose: Call this function to create a projection handle given a "Minilabel". Please refer to the section "Defining projections in KMSTRLIB using Minilabels" for more information. The returned projection handle may subsequently be used for transformations using KMSTR_TransformVi- aHandle. When a projection handle is no longer needed, it must be re- leased by calling KMSTR_ReleaseProjectionHandle. Parameters: . const char* pMinilabel - pointer to zero-terminated string identifying the input projection (using a "Minilabel"). Return value: NULL if the creation fails, otherwise a projection handle is returned.
Function: void _stdcall
KMSTR_ReleaseProjectionHandle(HKMSTR hProjection) Purpose: Call this function to release a projection handle previously created by KMSTR_CreateProjectionHandle. When a projection handle has been released, it should no longer be used in any calls. This function may safely be called with NULL handles. Parameters: . HKMSTR hProjection - a projection handle. Return value: none
Function: KMSTR_Error _stdcall KMSTR_TransformViaHandle(
HKMSTR hInProjection,
HKMSTR hOutProjection,
double XIn,
double YIn, KMSTRLIB SDK User's Guide 21 / 30
double ZIn,
double* pXOut,
double* pYOut,
double* pZOut,
int* ExtendedErrorMessage) Purpose: Call this function to perform a transformation of 2- or 3D coordinates using projection handles. To enable 3D transformations, KMSTR_Ini- tialiseGeoidLibrary must be called prior to calling this function. Parameters: . HKMSTR hInProjection - a projection handle identifying the input projection . HKMSTR hOutProjection - a projection handle identifying the out- put projection . double Xin,Yin,Zin - input coordinates (for 2D transformations, Zin can be set to 0.0). . double *pXOut, *pYOut, *pZOut - pointer to double's in which the output coordinate is stored. . int* ExtendedErrorMessage - pointer to an integer in which an ex- tended error message is returned. Possible values are:
(-1) BOUNDARY EXCEEDED (inaccurate)
(-2) TOLERANCE EXCEEDED
(-3) BOUNDARY EXCEEDED (serious)
(-4) NO GEOID ILLEGAL TRANSFORMATION
(-5) ILLEGAL TRANSFORMATION
(-6) SYSTEM/PROG FAULT
(-100) TABLE AREA OUT
(-200) TABLE WRONG LABEL
(-300) TABLE NONE FOUND
(-400) GEOID TOO MANY
(-500) table_name not found in manager.tab
(-600) manager.tab region not found
(-700) manager.tab not found KMSTRLIB SDK User's Guide 22 / 30
(-800) manager.tab not found Return value: KMSTR_OK if transformation is successful. Extended error messages in the range -1 to -3 may be available.
KMSTR_EXCEPTION if an exception occurred (unknown cause). No extended error message is available.
KMSTR_TRANSFORMATIONERROR if the transformation fails. In this case, an extended error message is available.
Function: KMSTR_Error _stdcall KMSTR_Transform(
const char* InLabel,
const char* OutLabel,
double XIn,
double YIn,
double ZIn,
double* pXOut,
double* pYOut,
double* pZOut) Purpose: Call this function to perform a transformation of 2- or 3D coordinates using minilabels. To enable 3D transformations, KMSTR_Initial- iseGeoidLibrary must be called prior to calling this function. Parameters: . const char* InLabel - a pointer to an array of characters describing the input projection using a minilabel. . const char* OutLabel - a pointer to an array of characters describ- ing the output projection using a minilabel. . double Xin,Yin,Zin - input coordinates (for 2D transformations, Zin should be set to 0.0). . double *pXOut, *pYOut, *pZOut - pointer to double's in which the output coordinate is stored. Return value: KMSTR_OK if transformation is successful
KMSTR_EXCEPTION if an exception occurred (unknown cause).
KMSTR_TRANSFORMATIONERROR if the transformation fails. KMSTRLIB SDK User's Guide 23 / 30
Function: void _stdcall KMSTR_EnableHorizonWorkaround(bool bEnable) Purpose: Enable or disable the workaround for S34/45 limited horizons. If the workaround is enabled, transformations outside the standard horizons of the S34/45 projections are performed using a low-precision affine transformation and an extended error message -2 (transformation tol- erance exceeded) is returned.
When the workaround is enabled, no 3D transformations are possible.
By default, the workaround is disabled. Parameters: . bool bEnable – If true, the horizon workaround is enabled. If false, the horizon workaround is disabled. This applies to all subsequent transformations. Return value: none
8. Calling the DLL interface from Visual Basic To call the transformation library DLL interface from Visual Basic or VBA, make sure that the KMSTRLIB.DLL and KMSFNCS.DLL are stored in a folder on the system search path.
Within VB or VBA, declare the following three functions:
Private Declare Function KMSTR_Transform Lib "KMSTRLIB.DLL" _ (ByVal InLabel As String, ByVal OutLabel As String, _ ByVal XIn As Double, ByVal YIn As Double, _ ByVal ZIn As Double, ByRef pXout As Double, _ ByRef pYout As Double, ByRef pZout As Double) As Integer
Private Declare Function KMSTR_InitLibrary Lib "KMSTRLIB.DLL" () As In- teger
Private Declare Sub KMSTR_TerminateLibrary Lib "KMSTRLIB.DLL" ()
Before using the transformation routine, call KMSTR_InitLibrary and check the return value (KMSTR_OK = 0 is returned if the library is successfully initialised):
If KMSTR_InitLibrary() <> 0 Then MsgBox ("Failed to load transformation library") End If KMSTRLIB SDK User's Guide 24 / 30
To perform a transformation between two projections defined by "minila- bels", use the KMSTR_Transform routine:
Dim X, Y, Z As Double If KMSTR_Transform("u32_ed50", "geo_wgs84", 400000, 6200000, 0, X, Y, Z) <> 0 Then MsgBox ("Transformation error") Else MsgBox ("Output is " & X & " " & Y & " " & Z) End If
When the transformation library is no longer needed, call KMSTR_Termin- ateLibrary. After this call, no further calls to KMSTR_Transform should be made.
9. Using the ActiveX/COM interface The ActiveX/COM interface to the transformation library makes it possible to access the transformation library from any host environment that sup- ports the use of ActiveX/COM controls.
To use the ActiveX interface, the following installation steps are required:
. KMSTRLIB.DLL and KMSFNCS.DLL must be copied to a folder on the system search path. . KMSTRLIBOCX.OCX must be copied to the host system and re- gistered with the system registry using REGSVR32 or a similar utility. I.e. to register the control using REGSVR32, open a command line prompt and use the command REGSVR32 KMSTROCX.OCX.
The control itself supports window-free activation, i.e. it has no visual ap- pearance. To insert the control in a host application, insert the ActiveX ob- ject named "KMTRLIB Control" or refer to the control by the ProgID "KM- STROCX.KMSTRLIBCtrl.1".
The sample below illustrates how to use the ActiveX/Com interface from VBScript:
Dim T, R Set T = CreateObject("KMSTROCX.KMSTRLIBCtrl.1") T.XI = 500000 T.YI = 6200000 T.ZI = 0 KMSTRLIB SDK User's Guide 25 / 30
T.InputProjection = "utm32_ed50" T.OutputProjection = "utm33_ed50" R = T.Transform() If R = 0 Then MsgBox ("Output is " & T.XO & " " & T.YO & " " & T.ZO) Else MsgBox ("Transformation error " & R) End If
10. Reference: Methods and properties exposed by the ActiveX/COM interface
Property InputProjection Data Type String Purpose Use this property to define the input projection using a minilabel. Please refer to the section "Defining projec- tions in KMSTRLIB using Minilabels" for more informa- tion.
Property OutputProjection Data Type String Purpose Use this property to define the output projection using a minilabel. Please refer to the section "Defining projec- tions in KMSTRLIB using Minilabels" for more informa- tion.
Property XI, YI, ZI Data Type Double Purpose Use these properties to define the input coordinates
Property XO, YO, ZO Data Type Double Purpose Use these properties to the retrieve the output coordin- ates after the Transform method has been invoked. KMSTRLIB SDK User's Guide 26 / 30
Method Transform Parameters None Purpose Invoke this method when the XI, YI, ZI, InputProjection and OutputProjection properties have been defined. If the transformation is successful (see below), the prop- erties XO, YO and ZO contains the output coordinate. Return value long
The following values may be returned:
KMSTR_OK (0) if transformation is successful.
KMSTR_EXCEPTION (3) if an exception occurred (un- known cause).
KMSTR_TRANSFORMATIONERROR (2) if the trans- formation fails.
Method InitGeoidLibrary Parameters . BSTR Folder - a string defining the name of the folder in which the geoid library files are stored. The path name should end with a backslash, i.e. "C:\DATA\GEOIDS\" Purpose Initialise the use of the geoid library in transformations. This function must be called in order to enable 3D transformations and it must be called any calls to Trans- form() are being made. In addition, it should be called once only. Return value Long
0, if successful. Any other value indicates a failure. KMSTRLIB SDK User's Guide 27 / 30
11. Calling KMSTRLIB from .NET To call KMSTRLIB from .NET, use the following approach (the sample KMSTRLIB.NET demonstrates this).
1. Add the file Interface.cs from the sample to your project. This file imple- ments a C# wrapper for KMSTRLIB.
2. Make sure that KMSTRLIB.DLL and KMSFNCS.DLL are placed in the same folder as the .NET assembly.
Usage is then straightforward: class TestProgram { static void Main(string[] args) { Interface.KMSTR_Error error; error = Interface.KMSTR_InitLibrary(); if (error!=Interface.KMSTR_Error.KMSTR_OK) throw new Exception(Interface.GetKMSErrorMessage(error));
error = Interface.KMSTR_InitialiseGeoidLib- rary("c:\\temp\\geoids\\"); if (error!=Interface.KMSTR_Error.KMSTR_OK) throw new Exception(Interface.GetKMSErrorMessage(error));
double X = 400000; double Y = 6500000; double Z = 0; error = Interface.KMSTR_Transform("utm32Eed50", "ut- m32Ewgs84", X, Y, Z, out X, out Y, out Z); if (error != Interface.KMSTR_Error.KMSTR_OK) throw new Exception(Interface.GetKMSErrorMessage(error)); } }
12. References [1] "Some Conformal Mappings and Transformations for Geodesy and To- pographic Cartography", Publications 4. series, volume 6, by Knud Poder and Karsten Engsager, Geodetic Division, KMS, 1998.
[2] Map Projections for Europe, Institute for Environment and Sustainabil- ity, (EUROPEAN COMMISION, EuroGeographics), EUR 20120 EN, 2001 KMSTRLIB SDK User's Guide 28 / 30