Prototyp und Beschreibung der Funktion coordtrans3dex()

(Funktion der freischaltpflichtigen Gruppe "Koordinatentransformationen")

 

coordtrans3dex()
3D-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 coordtrans3dex(
     double nCoordXQ,
     double nCoordYQ,
     const char *pszCoordQ,
     double nEllHgtQ,
     unsigned short nCoordSysQ,
     unsigned short nRefSysQ,
     unsigned short nUnitQ,
     unsigned short nStripQ,
     unsigned long lNoStripQ,
     double *nCoordXZ,
     double *nCoordYZ,
     char **pszCoordZ,
     double *nEllHgtZ,
     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 coordtrans3dex(;
     nCoordXQ as real8,;                   // 8 Byte
     nCoordYQ as real8,;                   // 8 Byte
     pszCoordQ as psz,;                    // 4 Byte, char*
     nEllHgtQ as real8,;                   // 8 Byte
     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.
     nEllHgtZ ref real8,;                  // 4 Byte
     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.coordtrans3dex    // 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 coordtrans3dex() zur Funktion coordtransex()
besteht darin, dass es sich hier um eine 3D-Transformation handelt.
Dabei wird bei der Verwendung unterschiedlicher Quell- und
Zielbezugssysteme die ellipsoidische Höhe berücksichtigt. Für die
Berechnung wird die ellipsoidische Höhe nEllHgtQ des für das Quellsystem
verwendeten Ellipsoiden verwendet. Als Ergebnis wird die ellipsoidische
Höhe nEllHgtZ des Zielsystems zurückgegeben. Die Berechnungen sind auch
mit kartesischen Koordinaten möglich.

3D-Berechnungen sind bei der Verwendung des "Bezugssystems in beliebiger
NTv2-Datei" nicht möglich, da für die ellipsoidische Höhenberechnung kein
zur NTv2-Datei passendes äquivalentes Helmert / Molodensky-Bezugssystem
verfügbar ist.

Die ellipsoidische Höhe ist geometrisch als Abstand eines Punktes von
einem Referenzellipsoiden entlang der Ellipsoidnormalen definiert.
Ellipsoidische Höhen können direkt mittels GPS bestimmt werden. Sie
dürfen aber nicht mit nivellierten (orthometrischen) Höhen verwechselt
werden!

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.

nEllHgtQ    Ellipsoidische Höhe der Quellkoordinate
              oder
            Z-Komponente bei kartesischen Koordinaten.
            Bei 3D-Transformationen wird bei unterschiedlichen Quell- und
            Zielbezugssystemen (nRefSysQ, nRefSysZ) die ellipsoidische
            Höhe der Quellkoordinate berücksichtigt.

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().

nEllHgtQ    Ellipsoidische Höhe der Zielkoordinate.
(ref)         oder
            Z-Komponente bei kartesischen Koordinaten.
            Bei 3D-Transformationen wird bei unterschiedlichen Quell- und
            Zielbezugssystemen (nRefSysQ, nRefSysZ) die ellipsoidische
            Höhe der Zielkoordinate berechnet.

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 Funktionen
coordtransf() und coordtrans3d().


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