|
Prototype and description of the function convntvbin2polyvalid() (Function of the unlock requiring group "NTv2 Tools") |
|
convntvbin2polyvalid()
Supplement of an 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(
const char *pszFileBinary,
const char *pszFilePolyValid,
const 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 quadrangular coordinate grids which are defined in
the NTv2 headers. Instead of a quadrangular 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 then can be excluded from
calculations or be acknowledged by a warning using the KilletSoft products
TRANSDAT and GeoDLL and a lot of GIS software developed by companies which
supports Polygonal Validity Scopes.
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 a country for the Polygonal Validity Scopes in the NTv2
file used in that county. 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 to a new shape file with the
required system using the program TRANSDAT by KilletSoft.
The dBase and index files normally associated with a shapefile are not
needed. The object file with the polygons, which has the file type ".shp" in
the file name, is sufficient. The content of the shape file can consist of a
single polygon or multiple polygons. These may occur with or without
sub-polygons in the shape file. This is the case if, for example, a national
border with the islands belonging to the country is to be displayed. Another
case would be the polygons of subordinate administrative units, such as
states or districts that make up a country. Decisive are only the outer
borders of the entire object. The shape file can contain the outline of the
required area in the following polygon compilations:
Single shape figure with a single polygon
Single shape figure with several sub-polygons
Several shape figures each with one polygon
Several shape figures each with several sub-polygons
Outline files in Shape format can be downloaded in different quality from
some websites. If you want to be sure about the quality, the resolution and
the used reference system, you should ask for a suitable outline file at
the responsible authorities.
Here are some websites from which outline files can be downloaded:
http://www.diva-gis.org/gdata
https://freegisdata.rtwilson.com
https://gisgeography.com/best-free-gis-data-sources-raster-vector
The term "exopolygonal entry" used in the course of the text stands for the
entry of a characteristic value in a grid mesh of an NTv2 file to exclude
this grid mesh from the scope of the NTv2 file. From this follows that all
grid meshes with exopolygonal entries are invalid. The function
convntvbin2polyvalid() marks all grid meshes that lies outside the polygons
of the used shapefile as invalid by introducing exopolygonal entries in the
NTv2 file.
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.
|