Prototyp und Beschreibung der Funktion coordtransex() (Funktion der freischaltpflichtigen Gruppe "Koordinatentransformationen") |
coordtransex() 2D-Koordinatentransformation und Bezugssystemwechsel für numerische und alphanumerische Koordinaten mit memory allocation für die return strings und mit Unterdrückung der Meridianstreifennummer. Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!): extern "C" __declspec(dllimport) unsigned long __stdcall coordtransex( double nCoordXQ, double nCoordYQ, const char *pszCoordQ, unsigned short nCoordSysQ, unsigned short nRefSysQ, unsigned short nUnitQ, unsigned short nStripQ, unsigned long lNoStripQ, double *nCoordXZ, double *nCoordYZ, char **pszCoordZ, unsigned short nCoordSysZ, unsigned short nRefSysZ, unsigned short nUnitZ, unsigned short nStripZ, unsigned long lNoStripZ); Prototyp der DLL-Funktion in Visual Objects Syntax: _DLL function coordtransex(; nCoordXQ as real8,; // 8 Byte nCoordYQ as real8,; // 8 Byte pszCoordQ as psz,; // 4 Byte, char* nCoordSysQ as word,; // 2 Byte nRefSysQ as word,; // 2 Byte nUnitQ as word,; // 2 Byte nStripQ as word,; // 2 Byte lNoStripQ as logic,; // 4 Byte nCoordXZ ref real8,; // 4 Byte nCoordYZ ref real8,; // 4 Byte pszCoordZ ref psz,; // 4 Byte, char**, 20 alloc. nCoordSysZ as word,; // 2 Byte nRefSysZ as word,; // 2 Byte nUnitZ as word,; // 2 Byte nStripZ as word,; // 2 Byte lNoStripZ as logic); // 4 Byte as logic pascal:geodll32.coordtransex // 4 Byte Die Allokation von Speicher für "ref psz" / "char**" ist nur notwendig, wenn zuvor setstringallocate(FALSE) aufgerufen worden ist. Achtung: Ab Version 14.60 zwei zusätzliche Parameter nUnitQ und nUnitZ! Die Funktion rechnet die numerischen Quellkoordinaten nCoordXQ und nCoordYQ oder die alphanumerische Quellkoordinate pszCoordQ aus dem Quellkoordinatensystem nCoordSysQ in die numerischen Zielkoordinaten nCoordXZ und nCoordYZ oder die alphanumerische Zielkoordinate pszCoordZ des Zielkoordinatensystems nCoordSysZ um. Für Quell- und Zielkoordinaten werden jeweils entweder zwei numerische oder ein alphanumerischer Parameter übergeben. Die Transformation wird mit hoher Genauigkeit und großer Geschwindigkeit durchgeführt. Der Unterschied der Funktion coordtransex() zur Funktion coordtrans() besteht darin, dass bei der Bearbeitung eines Streifensystems (UTM oder Gauß-Krüger) Einfluss auf die Verwendung der Meridianstreifennummer in den Ostwerten genommen werden kann (siehe unten). Die übergebenen Quellkoordinaten und die errechneten Zielkoordinaten werden auf den Gültigkeitsbereich innerhalb ihrer Koordinatensysteme und auf syntaktische Richtigkeit überprüft. Die Bereichsgrenzen sind in der Liste "Standardwerte der Koordinatensysteme" aufgeführt. Die Bereichs- und Syntaxprüfung kann mithilfe der Funktion setcoordarea() ein- oder ausgeschaltet werden. Wenn in nCoordSysQ oder in nCoordSysZ der Wert 1000 oder der Wert 1100 übergeben wird, benutzt die Funktion die zuvor mit den Funktionen setusercoordsys1() bzw. setusercoordsys2() eingegeben Parameter benutzerdefinierter Koordinatensysteme und die zuvor mit den Funktionen setuserellsource() bzw. setuserelltarget() definierten Erdellipsoide. Bei der Koordinatentransformation kann ein Bezugssystemwechsel vom geodätischen Bezugssystem nRefSysQ des Quellkoordinatensystems in das geodätische Bezugssystem nRefSysZ des Zielkoordinatensystems berücksichtigt werden. Wenn in nRefSysQ oder in nRefSysZ der Wert 0 übergeben wird, werden die für die jeweiligen Koordinatensysteme üblichen geodätischen Bezugssysteme für den Bezugssystemwechsel zugrunde gelegt. Die Standard-Bezugssysteme sind in der Liste "Standardwerte der Koordinatensysteme" aufgeführt. Wenn in nRefSysQ oder in nRefSysZ der Wert 1000 übergeben wird, benutzt die Funktion die zuvor mit der Funktion setuserrefsys() eingegeben Transformationsparameter des benutzerdefinierten Bezugssystems und die zuvor mit den Funktionen setuserellsource() und setuserelltarget() definierten Erdellipsoide. Wenn in nRefSysQ oder in nRefSysZ der Wert 1100 übergeben wird oder wenn beide Parameter denselben Wert (größer als 0) haben, erfolgt kein Bezugssystemwechsel. Für die Koordinatentransformation werden dabei die für die jeweiligen Koordinatensysteme üblichen Erdellipsoide verwendet. Die Erdellipsoide sind in der Liste "Standardwerte der Koordinatensysteme" aufgeführt. Wenn in nRefSysQ oder in nRefSysZ der Wert 1150 übergeben wird, erfolgt kein Bezugssystemwechsel. Für die Koordinatentransformation werden dabei die zuvor mit den Funktionen setuserellsource() und setuserelltarget() definierten Erdellipsoide verwendet. Wenn in nRefSysQ oder in nRefSysZ der Wert 1200 übergeben wird erfolgt kein Bezugssystemwechsel und kein Ellipsoidübergang. Wenn in den Bezugssystemen nRefSysQ oder in nRefSysZ keine Bezugs- systemparameter definiert sind, erfolgt nur ein Ellipsoidübergang, aber kein Bezugssystemwechsel. Bei Transformationen aus den Quellkoordinatensystemen Gauß-Krüger und UTM kann der Meridianstreifen nStripQ, auf dem sich die Quellkoordinaten beziehen, vorgegeben werden. Der vorgegebene Meridianstreifen darf nicht mehr als 3 Streifen vom natürlichen Meridianstreifen der Quellkoordinate abweichen. Wenn in nStripQ der Wert 0 übergeben wird, werden die führenden Ziffern der Ostwerte zur automatischen Berechnung der geographischen Länge des natürlichen Meridianstreifens herangezogen. Wenn im Paramter nStripQ ein Meridianstreifen vorgegeben ist, kann durch die Übergabe des Wertes TRUE im Parameter lNoStripQ die Verwendung von reduzierten Ostwerten eingestellt werden. Die Ostwerte dürfen dann keine führenden Meridianstreifennummern enthalten. Beispiel: nStripQ = 32, lNoStripQ = TRUE, UTM Ostwert 32564410 kann als 564410 eingegeben werden. Bei Transformationen in die Zielkoordinatensysteme Gauß-Krüger und UTM kann der Meridianstreifen nStripZ, auf den sich die Zielkoordinaten beziehen sollen, vorgegeben werden. Der vorgegebene Meridianstreifen darf nicht mehr als 3 Streifen vom natürlichen Meridianstreifen der Zielkoordinate abweichen. Wenn in nStripZ der Wert 0 übergeben wird, erfolgt die automatische Berechnung des natürlichen Meridianstreifens aus der geographischen Länge. Wenn im Parameter nStripZ ein Meridianstreifen vorgegeben ist, kann durch die Übergabe des Wertes TRUE im Parameter lNoStripZ die Ausgabe von reduzierten Ostwerten eingestellt werden. Die Ostwerte enthalten dann keine führende Meridianstreifennummer. Beispiel: nStripZ = 32, lNoStripZ = TRUE, UTM Ostwert 32564410 wird als 564410 ausgegeben. Folgende Transformationen sind möglich: Koordinatentransformationen unter Beibehaltung des Bezugssystems. Koordinatentransformationen mit Bezugssystemwechsel. Koordinatentransformationen mit Ellipsoidwechsel bei undefinierten Bezugssystemen. Bezugssystemwechsel unter Beibehaltung des Koordinatensystems. Wechsel des Bezugmeridians bei Gauß-Krüger- und UTM-Koordinaten. Umrechnung in den natürlichen Meridianstreifen bei Gauß-Krüger- und UTM-Koordinaten. Ein- und Ausgabe reduzierter Gauß-Krüger- und UTM-Koordinaten. Wechsel der Notation (Schreibweise) bei geographischen Koordinaten. Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben: nCoordXQ Längen-, Ost- oder X-Komponente der numerischen Quellkoordinate. Bei der Bearbeitung einer alphanumerischen Koordinate ist dieser Parameter ohne Bedeutung. Das Eingabeformat der Koordinate (Notation) ist in der Liste "Standardwerte der Koordinatensysteme" beschrieben. nCoordYQ Breiten-, Nord- oder Y-Komponente der numerischen Quellkoordinate. Bei der Bearbeitung einer alphanumerischen Koordinate ist dieser Parameter ohne Bedeutung. Das Eingabeformat der Koordinate (Notation) ist in der Liste "Standardwerte der Koordinatensysteme" beschrieben. pszCoordQ Alphanumerische Quellkoordinate. Bei der Bearbeitung numerischer Koordinaten ist dieser Parameter ohne Bedeutung. In diesem Fall kann ein NULL-Zeiger für pszCoordQ eingetragen werden. Das Eingabeformat der Koordinate (Notation) ist in der Liste "Standardwerte der Koordinatensysteme" beschrieben. nCoordSysQ Koordinatensystem der Quellkoordinaten. (siehe Liste "Koordinatenbezugssysteme"). nRefSysQ Geodätisches Bezugssystem der Quellkoordinaten. (siehe Liste "Koordinatenbezugssysteme"). nUnitQ Maßeinheit der Quellkoordinaten. 0 Die Quellkoordinaten sind in der in GeoDLL voreingestellten Standard-Maßeinheit des Koordinatensystems angegeben. Falls erforderlich werden sie für die interne Verwendung in Meter umgerechnet. (siehe Liste "Standardwerte" [Quelltext: settings_d.txt]). › 0 Die Quellkoordinaten sind in einer bestimmten Maßeinheit angegeben und werden für die interne Verwendung in Meter umgerechnet. (siehe Liste "Koordinatenbezugssysteme alphabetisch" [Quelltext: sysalpha_d.txt]). 1000 Keine Auswirkung. Die Quellkoordinaten werden nicht in eine andere Maßeinheit umgerechnet. nStripQ Zu verwendender Meridianstreifen im Quellkoordinatensystem. Dieser Parameter hat nur eine Wirkung, wenn in nCoordSysQ ein "Transversales Mercator Streifensystem" eingetragen ist. 0 Verwendung der führenden Ziffern des Ostwerts zur Berechnung des natürlichen Meridianstreifens. › 0 Verwendung des Wertes in nStripQ zur Berechnung des natürlichen Meridianstreifens. lNoStripQ Einstellung für die Unterdrückung der Meridianstreifennummer im Ostwert. Dieser Parameter hat nur eine Wirkung, wenn in nCoordSysQ ein "Transversales Mercator Streifensystem" eingetragen ist. TRUE Ostwerte müssen ohne führenden Meridianstreifennummern übergeben werden. FALSE Ostwerte müssen mit führenden Meridianstreifennummern übergeben werden. nCoordXZ Längen-, Ost- oder X-Komponente der numerischen (ref) Zielkoordinate. Bei der Bearbeitung einer alphanumerischen Koordinate ist dieser Parameter ohne Bedeutung. Das Rückgabeformat der Koordinate (Notation) ist unter dem Begriff "Notation" in der Liste "Standardwerte der Koordinatensysteme" aufgeführt. nCoordYZ Breiten-, Nord- oder Y-Komponente der numerischen (ref) Zielkoordinate. Bei der Bearbeitung einer alphanumerischen Koordinate ist dieser Parameter ohne Bedeutung. Das Rückgabeformat der Koordinate (Notation) ist unter dem Begriff "Notation" in der Liste "Standardwerte der Koordinatensysteme" aufgeführt. pszCoordZ Alphanumerische Zielkoordinate. (ref) Bei der Bearbeitung numerischer Koordinaten ist dieser Parameter ohne Bedeutung. In diesem Fall kann ein NULL-Zeiger für pszCoordZ eingetragen werden. Das Rückgabeformat der Koordinate (Notation) ist unter dem Begriff "Notation" in der Liste "Standardwerte der Koordinatensysteme" aufgeführt. Achtung: "ref pszCoordZ" entspricht "char**" in C. Es müssen 20 Byte Speicher für den Null terminated string in Abhängigkeit vom Aufruf der Funktion setstringallocate() allokiert werden. Beachten Sie dazu die Hinweise in der Beschreibung der Funktion setstringallocate(). nCoordSysZ Koordinatensystem der Zielkoordinaten. (siehe Liste "Koordinatenbezugssysteme"). nRefSysZ Geodätisches Bezugssystem der Zielkoordinaten. (siehe Liste "Koordinatenbezugssysteme"). nUnitZ Maßeinheit der Zielkoordinaten. 0 Die Zielkoordinaten werden in die in GeoDLL voreingestellten Standard-Maßeinheit des Koordinatensystems ausgegeben. Falls erforderlich werden sie von den intern verwendeten Meter in die voreingestellte Maßeinheit umgerechnet. (siehe Liste "Standardwerte" [Quelltext: settings_d.txt]). › 0 Die Zielkoordinaten werden in einer bestimmten Maßeinheit ausgegeben. Sie werden von den intern verwendeten Metern in die gewünschte Maßeinheit umgerechnet. (siehe Liste "Koordinatenbezugssysteme alphabetisch" [Quelltext: sysalpha_d.txt]). 1000 Keine Auswirkung. Die Zielkoordinaten werden nicht in eine andere Maßeinheit umgerechnet. nStripZ Zu verwendender Meridianstreifen im Zielkoordinatensystem. Dieser Parameter hat nur eine Wirkung, wenn in nCoordSysZ ein "Transversales Mercator Streifensystem" eingetragen ist. 0 Berechnung des natürlichen Meridianstreifens aus der Geographischen Länge. › 0 Berechnung des Ostwerts mit der Streifennummer nStripZ als natürlicher Meridianstreifen. lNoStripZ Einstellung für die Unterdrückung der Meridianstreifennummer im Ostwert. Dieser Parameter hat nur eine Wirkung, wenn in nCoordSysZ ein "Transversales Mercator Streifensystem" eingetragen ist. TRUE Ostwerte werden ohne führenden Meridianstreifennummern zurückgegeben. FALSE Ostwerte werden mit führenden Meridianstreifennummern zurückgegeben. returnWert Im Fehlerfall gibt die Funktion FALSE zurück, sonst TRUE. Gültigkeitsbereiche Die Bereichsgrenzen der Quellkoordinaten und der errechneten Zielkoordinaten werden anhand der unter dem Begriff "Bereich (L / B)" in der Liste "Standardwerte der Koordinatensysteme" aufgeführten geographischen Koordinaten überprüft. Die Syntax- und Bereichüberprüfung kann mithilfe der Funktion setCoordArea() ausgeschaltet werden. Bei benutzerdefinierten Koordinatensysteme wird der Bereich automatisch in Abhängigkeit vom Nullpunkt des jeweiligen Koordinatensystems eingestellt. Notationen Die Koordinaten der verschiedenen Koordinatensysteme werden mit den unter dem Begriff "Notation (E / N)" in der Liste "Standardwerte der Koordinatensysteme" aufgeführten Notationen ein- und ausgegeben. Es können beliebig viele Nachkommastellen angefügt sein. Eine genaue Beschreibung der Notationen ist am Ende der Liste "Standardwerte der Koordinatensysteme" zu finden. Standard-Bezugssysteme Den Koordinatensystemen werden die unter dem Begriff "Standard-BezSys" in der Liste "Standardwerte der Koordinatensysteme" aufgeführten Bezugssysteme zugeordnet, wenn in den Parametern nRefSysQ oder nRefSysZ eine Null übergeben wird. Besonderheiten bei der Verwendung von NTv2-Gitterdateien Download von NTv2-Dateien: Die gebräuchlichen NTv2-Dateien können von der KilletSoft- Internetseite herunter geladen oder bei Anbietern von Geodiensten bezogen werden. Verschlüsselte NTv2-Dateien: Zum Schutz von Rechten einiger Autoren, die NTv2-Dateien speziell für die Nutzung mit KilletSoft-Produkten zur Verfügung stellen, unterstützt GeoDLL verschlüsselte NTv2-Dateien, die von der KilletSoft-Internetseite herunter geladen werden können. Polygonale Gültigkeitsbereiche: Der Gültigkeitsbereich einer NTv2-Datei ist standardmäßig durch viereckige Koordinatenfenster festgelegt. Um trotzdem polygonale Strukturen, wie z.B. Landesgrenzen zu realisieren, kann der Hersteller in seiner NTv2-Datei einen polygonalen Gültigkeitsbereich festlegen. Dazu werden die außerhalb der polygonalen Gültigkeit liegenden Gittermaschen durch die exopolygonalen Einträge -99/-99 in ihren Shift- oder Genauigkeitswerten gekennzeichnet. GeoDLL kann die Gittermaschen auf exopolygonale Einträge prüfen und bei Treffern von der Berechnung ausschließen und mit einer Fehlermeldung kommentieren. Die Überprüfung wird mit der Funktion setntvpolyvalid() ein- oder ausgeschaltet. Detaillierte Informationen finden Sie im Hilfe-Kapitel "Polygonale Gültigkeitsbereiche". Weitere Hinweise entnehmen Sie bitte der Beschreibung der Funktion coordtrans(). Freischaltung Die Funktion ist Bestandteil der freischaltpflichtigen Funktionsgruppe "Koordinatentransformationen". 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 nur wenige Funktionsaufrufe zu Testzwecken (Sharewareprinzip) möglich. Bezugssystemwechsel mit NTv2-Gitterdateien erfordern zusätzlich die Freischaltung der Funktionsgruppe "NTv2-Transformationen". |