Prototype and description of the function convntvbin2polyvalid()

(Function of the unlock requiring group "NTv2 Tools")

 

convntvbin2polyvalid()
Supplement of a NTv2 binary file with Polygonal Validity Scopes.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall convntvbin2polyvalid(
     char *pszFileBinary,
     char *pszFilePolyValid,
     char *pszFileShape,
     unsigned short nTyp);

Prototype of the DLL function in Visual Objects syntax:
_DLL function convntvbin2polyvalid(;
     pszFileBinary AS PSZ,;                   // 4 Byte, char*
     pszFilePolyValid AS PSZ,;                // 4 Byte, char*
     pszFileShape AS PSZ,;                    // 4 Byte, char*
     nTyp AS WORD)                            // 2 Byte
as logic pascal:geodll32.convntvbin2polyvalid // 4 Byte


The function copies an NTv2 binary file in consideration of the
Polygonal Validity Scopes into a new NTv2 binary file.

By means of NTv2 grid files it is possible to transform points from one
coordinate reference system to another with very high accuracy. An NTv2 file
contains one or more quasi-rectangular coordinate grids which are defined in
the NTv2 headers. Instead of a rectangular area only an embedded polygonal
area should and must be covered, for example, a state territory within the
country borders.

The function convntvbin2polyvalid() realizes the Polygonal Validity Scope in
NTv2 files. Coordinates outside the scope can then be excluded from
calculations using the KilletSoft products TRANSDAT and GeoDLL and other GIS
software, or be acknowledged by a warning.

For that purpose the polygonal scope is realized with a shape file that
contains the outlines of the scope as polygons. This can be, for example, the
border outline of the Federal Republic of Germany for the validity scopes in
the NTv2 file BETA2007. The polygons contained in the shape file must be
available as geographic coordinates in decimal notation. The reference
system of the outline coordinates should correspond as closely as possible
to the source reference system of the NTv2 file. A shape file in another
coordinate reference system can be converted into the required system with
GeoDLL functions or with the program TRANSDAT by KilletSoft.

By using exopolygonal entries in the shift values or in the accuracy values
of the NTv2 file, there are two methods for realizing Polygonal Validity
Scopes. The two methods differ considerably in their effects.

Method 1:
Exopolygonal entries replace the accuracy values of the grid meshes.
Exactly one grid mesh is addressed that has a grid spacing LAT_INC in
northern direction and a grid spacing in western direction from the grid
point. Exactly this grid mesh is defined by the grid point and addressed
regarding the interpolation of a coordinate that lies within. This grid mesh
is excluded from the polygonal validity scope of the NTv2 grid.

Method 2:
Exopolygonal entries replace the shift values of the grid meshes.
With a bilinear interpolation the four adjacent grid points of a coordinate
are used. Each may contain exopolygonal entries. So, all in all four grid
meshes are addressed and each has one grid spacing in northern and southern
direction and one grid spacing in western and eastern direction from the
grid point. These are the four grid meshes that are arranged around the grid
point. Exactly these four grid meshes are excluded from the polygonal
validity scope of the NTv2 grid.

To distinguish it from the original grid file, in the new created NTv2 grid
file the UPDATED entries in all grid headers are overwritten with the date
of the creation day. NTv2 binary files with syntax errors are rejected by
GeoDLL with an error message.

An existing KilletSoft encryption of the NTv2 file and Polygonal Validity
Scopes already contained therein will be retained when transferred to the
new NTv2 file.

You can download the NTv2 files supported by GeoDLL directly from the
KilletSoft website http://www.killetsoft.de/p_gdln_e.htm#download or use the
download links to the original sources there. On that Internet site you also
find a detailed description of the NTv2 standard.

The use of Polygonal Validity Scopes is described in detail on the KilletSoft
website "http://www.killetsoft.de/t_1512_e.htm" in our white paper "Proposal
for using Polygonal Validity Scopes in NTv2 grid files".

Since the function due to the extensive calculations is time-consuming,
the event handling during the calculation by interrupting the processing loop
can be are allowed bei calling the function seteventloop().

The file names of the NTv2 binary file, the generated binary file and the
shape file may contain a drive letter and a directory path.
Example:
Binary file  "c:\programm_ntv2\BeTA2007.gsb"
New binary   "c:\programm_ntv2\BeTA2007_scope.gsb"
Shape file   "c:\programm_ntv2\Germany_border.shp"
Attention, in C syntax double backslashes must be used!


The parameters are passed and/or returned as follows:
pszFileBinary  File name of the NTV2 binary file which is used as source.
              The file name may contain a drive letter, a directory path
              and a file name extension. The file name should have the file
              name extension ".gsb".

pszFilePolyValid  File name of the NTv2 binary file which is to be generated
              for the grid data with exopolygonal entries. The file name may
              contain  a drive letter, a directory path and a file name
              extension. The file name should have the file name extension
              ".gsb".

pszFileShape  File name of the shapefile with the Polygonal Validity Scopes.
              The scopes must be present as polygon objects. The file name
              may contain  a drive letter, a directory path and a file name
              extension. The file name should have the file name extension
              ".shp".

nTyp          One of two methods for realizing Polygonal Validity Scopes
              (see above)
1             Exopolygonal entries replace the accuracy values of the grid
              meshes.
2             Exopolygonal entries replace the shift values of the grid
              meshes.

returnVal     In case of an error the function returns FALSE, otherwise TRUE.


Unlocking:
This function is a component of the unlock requiring function group "NTv2
tools". 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 no
calls for test purposes (shareware principle) are possible with this function.