Funktion convntvbin2polyvalid()

Prototyp und Beschreibung der Funktion convntvbin2polyvalid()

(Funktion der freischaltpflichtigen Gruppe "NTv2-Werkzeuge")

 

convntvbin2polyvalid()
NTv2-Binärdatei mit polygonalen Gültigkeitsbereichen ergänzen.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall convntvbin2polyvalid(
     char *pszFileBinary,
     char *pszFilePolyValid,
     char *pszFileShape,
     unsigned short nTyp);

Prototyp der DLL-Funktion 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


Die Funktion kopiert eine NTv2-Binärdatei unter Berücksichtigung des
Polygonalen Gültigkeitsbereichs in eine neue NTv2-Binärdatei.

Mit Hilfe von NTv2-Gitterdateien ist es möglich, Punkte von einem Koordinaten-
bezugssystem in ein anderes mit sehr hoher Genauigkeit zu transformieren.
Eine NTv2-Datei enthält ein oder mehrere quasi rechteckige Koordinatengitter,
die in den NTv2-Headern definiert sind. Anstelle eines rechteckigen Bereichs
soll und darf aber nur ein darin enthaltener polygonaler Bereich abgedeckt
sein, z.B. ein Staatsgebiet innerhalb der Landesgrenzen.

Die Funktion convntvbin2polyvalid() realisiert den Polygonalen Gültigkeits-
bereich in NTv2-Dateien. Koordinaten außerhalb des Gültigkeitsbereich können
dann mit den KilletSoft-Produkten TRANSDAT und GeoDLL und vieler GIS-Software
von Herstellern, die Polygonale Gültigkeitsbereiche unterstützen, von den
Berechnungen ausgeschlossen oder durch einen Warnhinweis quittiert werden.

Der Polygonale Gültigkeitsbereich wird dabei mit einer Shape-Datei
realisiert, die die Umrisse des Gültigkeitsbereichs als Polygone enthält.
Das kann zum Beispiel der Grenzumriss eines Landes für die Polygonalen
Gültigkeitsbereiche der in dem Land verwendeten NTv2-Datei sein. Die in der
Shape-Datei enthaltenen Polygone müssen als Geographische Koordinaten in
dezimaler Notation vorliegen. Das Bezugssystem der Umriss-Koordinaten sollte
möglichst genau dem Quellbezugssystem der NTv2-Datei entsprechen. Eine in
einem anderen Koordinatenbezugssystem vorliegende Shape-Datei kann mit dem
Programm TRANSDAT von KilletSoft in eine neue Shape-Datei mit dem benötigten
System umgerechnet werden.

Die normalerweise zu einer Shape-Datei gehörenden dBase- und Index-Dateien
werden nicht benötigt. Es genügt die Objekt-Datei mit den Polygonen, die den
Dateityp ".shp" im Dateinamen hat. Der Inhalt der Shape-Datei kann aus einem
einzelnen Polygon oder aus mehreren Polygonen bestehen. Diese dürfen jeweils
mit oder ohne Sub-Polygone in der Shape-Datei vorkommen. Das ist der Fall,
wenn zum Beispiel eine Landesgrenze mit den zum Land gehörenden Inseln
dargestellt werden soll. Ein weiterer Fall wären die Polygone von
untergeordneten administrativen Einheiten, wie zum Beispiel Bundesländer, aus
denen ein Land zusammen gesetzt ist. Maßgeblich sind nur die Außengrenzen des
gesamten Objekts. Die Shape-Datei kann den Umriss des benötigten Gebiets in
folgenden Polygon-Zusammenstellungen enthalten:
  Einzelne Shape-Figur mit einem einzelnen Polygon
  Einzelne Shape-Figur mit mehreren Sub-Polygonen
  Mehrere Shape-Figuren mit jeweils einem Polygon
  Mehrere Shape-Figuren mit jeweils mehreren Sub-Polygonen

Umrissdateien im Shape-Format können in unterschiedlicher Qualität von
einigen Internetseiten herunter geladen werden. Wenn man bezüglich der
Qualität, der Auflösung und des verwendeten Bezugssystems sicher gehen will,
sollte man nach einer geeigneten Umrissdatei bei den zuständigen Behörden
nachfragen.

Hier sind einige Internetseiten, von denen Umrissdateien herunter geladen
werden können:
http://www.diva-gis.org/gdata
https://freegisdata.rtwilson.com
https://gisgeography.com/best-free-gis-data-sources-raster-vector

Der im Textverlauf verwendete Begriff "exopolygonaler Eintrag" steht für den
Eintrag eines Kennwertes in eine Gittermasche einer NTv2-Datei zum Ausschluss
dieser Gittermasche aus dem Wirkungsbereich der NTv2-Datei. Daraus folgt,
dass alle Gittermaschen mit exopolygonalen Einträgen ungültig sind. Die
Funktion convntvbin2polyvalid() kennzeichnet alle außerhalb der Polygone der
verwendeten Shapedatei liegenden Gittermaschen in der NTv2-Datei durch das
Einbringen exopolygonaler Einträge als ungültig.

Durch die Verwendung exopolygonaler Einträge in den Verschiebungswerten oder
in den Genauigkeitswerten der NTv2-Datei ergeben sich zwei Methoden zur
Realisierung polygonaler Gültigkeitsbereiche. Die beiden Methoden unter-
scheiden sich in den Auswirkungen erheblich.

Methode 1:
Exopolygonale Einträge ersetzen die Genauigkeitswerte der Gittermaschen.
Es wird genau eine Gittermasche angesprochen, die sich einen Gitterabstand
in nördlicher und einen Gitterabstand in westlicher Richtung vom Gitterpunkt
erstreckt. Das ist genau die Gittermasche, die durch den Gitterpunkt
definiert ist und die bei der Interpolation einer darin befindlichen
Koordinate angesprochen wird. Diese Gittermasche wird aus dem polygonalen
Gültigkeitsbereich des NTv2-Gitters ausgeschlossen.

Methode 2:
Exopolygonale Einträge ersetzen die Verschiebungswerte der Gittermaschen.
Bei der bilinearen Interpolation werden die vier benachbarten Gitterpunkte
einer Koordinate verwendet, in denen jeweils exopolygonale Einträge enthalten
sein können. Daher werden insgesamt vier Gittermaschen angesprochen, die
sich je einen Gitterabstand in nördlicher und südlicher und je einen Gitter-
abstand in westlicher und östlicher Richtung vom Gitterpunkt erstrecken. Das
sind die vier Gittermaschen, die um den Gitterpunkt herum angeordnet sind.
Genau diese vier Gittermaschen werden aus dem polygonalen Gültigkeitsbereich
des NTv2-Gitters ausgeschlossen.

Zur Unterscheidung von der Original-Gitterdatei werden in der neu erstellten
NTv2-Gitterdatei die Einträge UPDATED in allen Gitterheadern mit dem Datum
des Erstellungstages überschrieben. NTv2-Binärdateien mit Syntaxfehlern
werden von GeoDLL mit einer Fehlermeldung abgelehnt.

Eine möglicherweise vorhandene KilletSoft-Verschlüsselung der NTv2-Datei und
darin bereits eingetragene Polygonale Gültigkeitsbereiche bleiben bei der
Übertragung in die neue NTv2-Datei erhalten.

Sie können die von GeoDLL unterstützten NTv2-Dateien direkt von der
KilletSoft Internetseite "http://www.killetsoft.de/p_gdln_d.htm#download"
herunterladen oder dort die Verweise zu den Originalquellen verwenden. Auf
der Internetseite finden Sie auch eine ausführliche Beschreibung des
NTv2-Standards.

Die Verwendung von polygonalen Gültigkeitsbereichen ist auf der KilletSoft
Internetseite "http://www.killetsoft.de/t_1512_d.htm" in unserem White Paper
"Vorschlag zur Verwendung polygonaler Gültigkeitsbereiche in NTv2-
Gitterdateien" detailliert beschrieben.

Da die Funktion wegen der umfangreichen Berechnungen zeitintensiv ist, kann
mit der Funktion seteventloop() die Event-Bearbeitung während der Berechnung
durch Unterbrechung der Bearbeitungsschleife zugelassen werden.

Die Dateinamen der NTv2-Binärdatei,der neu zu erzeugenden NTv2-Binär-
Datei und der Shape-Datei dürfen jeweils einen Laufwerksbuchstaben und eine
Verzeichniskette enthalten.
Beispiel:
Binärdatei  "c:\programm_ntv2\BeTA2007.gsb"
Neue Datei  "c:\programm_ntv2\BeTA2007_scope.gsb"
Shape-Datei "c:\programm_ntv2\Germany_border.shp"
Achtung, in C-Syntax müssen doppelte Backslashes verwendet werden!


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
pszFileBinary  Dateiname der als Quelle verwendeten NTv2-Binärdatei. Der
            Dateiname darf einen Laufwerksbuchstaben und eine Verzeichnis-
            kette enthalten. Der Dateiname sollte die Dateinamens-
            erweiterung ".gsb" haben.

pszFilePolyValid  Dateiname der zu erzeugenden NTv2-Binärdatei mit den
            Exopolygonalen Einträgen. Der Dateiname darf einen Laufwerks-
            buchstaben und eine Verzeichniskette enthalten. Der Dateiname
            sollte die Dateinamenserweiterung ".gsb" haben.

pszFileShape  Dateiname der Shapedatei mit den polygonalen Gültigkeits-
            bereichen. Die Gültigkeitsbereiche müssen darin als Polygon-
            Objekte vorliegen. Der Dateiname darf einen Laufwerksbuchstaben
            und eine Verzeichniskette enthalten. Der Dateiname sollte die
            Dateinamenserweiterung ".shp" haben.

nTyp        Eine von zwei zwei Methoden zur Realisierung Polygonaler
            Gültigkeitsbereiche (siehe oben)
1           Exopolygonale Einträge ersetzen die Genauigkeitswerte der
            Gittermaschen.
2           Exopolygonale Einträge ersetzen die Verschiebungswerte der
            Gittermaschen.

returnWert  Im Fehlerfall gibt die Funktion FALSE zurück, sonst TRUE.


Freischaltung:
Die Funktion ist Bestandteil der freischaltpflichtigen Funktionsgruppe
"NTv2-Werkzeuge". Sie wird zusammen mit den anderen Funktionen der Gruppe
durch die Eingabe der bei der Vertriebsfirma erworbenen Freischaltparameter
per Aufruf der Funktion setunlockcode() zur uneingeschränkten Nutzung frei
geschaltet. Ohne die Freischaltung sind mit dieser Funktion keine Funktions-
aufrufe zu Testzwecken (Sharewareprinzip) möglich.