Prototyp und Beschreibung der Funktion coordtrans3()

(Funktion der freischaltpflichtigen Gruppe "Koordinatentransformationen")

 

coordtrans3()
2D-Koordinatentransformation und Bezugssystemwechsel mit Notation nur
für numerische Koordinaten.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall coordtrans3(
     double nCoordXQ,                      // 8 Byte
     double nCoordYQ,                      // 8 Byte
     unsigned short nCoordSysQ,            // 2 Byte
     unsigned short nRefSysQ,              // 2 Byte
     unsigned short nNotationQ,            // 2 Byte
     double *nCoordXZ,                     // 4 Byte (Pointer)
     double *nCoordYZ,                     // 4 Byte (Pointer)
     unsigned short nCoordSysZ,            // 2 Byte
     unsigned short nRefSysZ,              // 2 Byte
     unsigned short nNotationZ,            // 2 Byte
     unsigned short nStripZ);              // 2 Byte

Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL function coordtrans3(;
     nCoordXQ as real8,;                   // 8 Byte
     nCoordYQ as real8,;                   // 8 Byte
     nCoordSysQ as word,;                  // 2 Byte
     nRefSysQ as word,;                    // 2 Byte
     nNotationQ as word,;                  // 2 Byte
     nCoordXZ ref real8,;                  // 4 Byte (Pointer)
     nCoordYZ ref real8,;                  // 4 Byte (Pointer)
     nCoordSysZ as word,;                  // 2 Byte
     nRefSysZ as word,;                    // 2 Byte
     nNotationZ as word,;                  // 2 Byte
     nStripZ as word);                     // 2 Byte
as logic pascal:geodll32.coordtrans3       // 4 Byte

Prototyp der DLL-Funktion in VisualBasic-Syntax:
Private Declare Function coordtrans3 Lib "GeoDLL32" ( _
ByVal nKoordXQ As Double, _                '8 Byte
ByVal nKoordYQ As Double, _                '8 Byte
ByVal nKoordSysQ As UShort, _              '2 Byte
ByVal nRefSysQ As UShort, _                '2 Byte
ByVal nNotationQ As UShort, _              '2 Byte
ByRef nKoordXZ As Double, _                '4 Byte (Pointer)
ByRef nKoordYZ As Double, _                '4 Byte (Pointer)
ByVal nKoordSysZ As UShort, _              '2 Byte
ByVal nRefSysZ As UShort, _                '2 Byte
ByVal nNotationZ As UShort, _              '2 Byte
ByVal nStreifenZ As UShort) _              '2 Byte
As UInteger                                '4 Byte


Die Funktion coordtrans3() ist der Funktion coordtrans() ähnlich. Der
Unterschied besteht darin, dass nur numerische und keine alphanumerischen
Koordinaten transformiert werden und dass für geographische Koordinaten
eine Notation angegeben werden kann.

Die Funktion rechnet die Quellkoordinaten nCoordXQ und nCoordYQ aus dem
Quellkoordinatensystem nCoordSysQ in die Zielkoordinaten nCoordXZ und
nCoordYZ des Zielkoordinatensystems nCoordSysZ um. Die Transformation
wird mit hoher Genauigkeit und großer Geschwindigkeit durchgeführt.

Der Unterschied der Funktion coordtrans3() zur Funktion coordtrans3d3()
besteht darin, dass es sich hier um eine 2D-Transformation handelt.
Dabei bleibt bei der Verwendung unterschiedlicher Quell- und
Zielbezugssysteme die ellipsoidische Höhe unberücksichtigt, da sie nur
einen sehr geringen Einfluss auf die Lagegenauigkeit hat.

Die übergebenen Quellkoordinaten und die errechneten Zielkoordinaten
werden in Abhängigkeit von den Koordinatensystemen auf ihren
Gültigkeitsbereich 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. Diese 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() eingegebenen
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 von oder in geographische Koordinaten kann in
nNotation? zwischen mehreren möglichen Notationen (Schreibweisen) für die
Parameter nCoordXQ und nCoordYQ bzw. nCoordXZ und nCoordYZ gewählt werden:
[Grad]
[Grad, Minuten, Sekunden]
[Grad, Minuten]
[Sekunden]
[Gon]

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 Bezugsmeridian der
Zielkoordinaten abweichen. Wenn in nStripZ der Wert 0 übergeben wird,
erfolgt die automatische Berechnung des natürlichen Bezugsmeridians
aus der geographischen Länge.

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.
Wechsel der Notation (Schreibweise) bei geographischen Koordinaten.


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
nCoordXQ    Längen-, Ost- oder X-Komponente der Quellkoordinate.
            Das Eingabeformat der Koordinate (Notation) ist in der Liste
            "Standardwerte der Koordinatensysteme" aufgeführt.

nCoordYQ    Breiten-, Nord- oder Y-Komponente der Quellkoordinate.
            Das Eingabeformat der Koordinate (Notation) ist in der Liste
            "Standardwerte der Koordinatensysteme" aufgeführt.

nCoordSysQ  Koordinatensystem der Quellkoordinaten.
            (siehe Liste "Koordinatenbezugssysteme")
            Ausnahmen: Die dort beschriebenen alphanumerischen
            Koordinatensysteme werden hier nicht unterstützt. Die dort
            beschriebenen geographischen Koordinatensysteme werden hier
            durch die Übergabe des Wertes 1 in nCoordSysQ zusammengefasst.

nRefSysQ    Geodätisches Bezugssystem der Quellkoordinaten.
            (siehe Liste "Koordinatenbezugssysteme")

nNotationQ  Notation (Schreibweise) der geographischen Quellkoordinaten.
            Die Notation hat nur Auswirkungen, wenn für nCoordSysQ = 1
            angegeben ist!
0           Geographische Koordinaten [Grad]:        vggg     / vgg
              g  Grad und dezimaler Bruchteil eines Grades
1           Geographische Koord. [Grad, Min, Sek]    vgggmmss / vggmmss
              g  Grad
              m  Minuten
              s  Sekunden und dezimaler Bruchteil einer Sekunde
2           Geographische Koordinaten [Grad, Min]:   vgggmm   / vggmm
              g  Grad
              m  Minuten und dezimaler Bruchteil einer Minute
3           Geographische Koordinaten [Sek]:         vsssssss / vsssssss
              s  Sekunden und dezimaler Bruchteil einer Sekunde
4           Geographische Koordinaten [Gon]:         vggg     / vggg
              g  Gon (400 Gon = 360 Grad) und dezimaler Bruchteil
                 eines Gons
            Weitere Hinweise zur Notation sind in der Beschreibung der
            Funktion coordtrans() unter dem Kapitel "Notation" zu finden.

nCoordXZ    Längen-, Ost- oder X-Komponente der Zielkoordinate.
(ref)       Das Ausgabeformat der Koordinate ist in der Liste "Standardwerte
            der Koordinatensysteme" aufgeführt.

nCoordYZ    Breiten-, Nord- oder Y-Komponente der Zielkoordinate.
(ref)       Das Ausgabeformat der Koordinate ist in der Liste "Standardwerte
            der Koordinatensysteme" aufgeführt.

nCoordSysZ  Koordinatensystem der Zielkoordinaten.
            (siehe Liste "Koordinatenbezugssysteme")
            Ausnahmen: Die dort beschriebenen alphanumerischen
            Koordinatensysteme werden hier nicht unterstützt. Die dort
            beschriebenen geographischen Koordinatensysteme werden hier
            durch die Übergabe des Wertes 1 in nCoordSysZ zusammengefasst.

nRefSysZ    Geodätisches Bezugssystem der Zielkoordinaten.
            (siehe Liste "Koordinatenbezugssysteme")

nNotationZ  Notation (Schreibweise) der geographischen Zielkoordinaten.
            Die Notation hat nur Auswirkungen, wenn für nCoordSysZ = 1
            angegeben ist!
            Die Notationen der geographischen Koordinaten sind weiter oben
            unter dem Parameter nNotationQ beschrieben.

nStripZ     Zu verwendender Meridianstreifen.
            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         Gültige Nummer des benötigten Merdianstreifens.

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


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
rechteckige 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-Gitterdaten".