|
Prototyp und Beschreibung der Funktion coordtrans3d2() (Funktion der freischaltpflichtigen Gruppe "Koordinatentransformationen") |
|
coordtrans3d2()
3D-Koordinatentransformation und Bezugssystemwechsel für numerische und
alphanumerische Koordinaten ohne memory allocation für die return
strings.
Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall coordtrans3d2(
double nCoordXQ,
double nCoordYQ,
const char *pszCoordQ,
double nEllHgtQ,
unsigned short nCoordSysQ,
unsigned short nRefSysQ,
double *nCoordXZ,
double *nCoordYZ,
char *pszCoordZ,
double *nEllHgtZ,
unsigned short nCoordSysZ,
unsigned short nRefSysZ,
unsigned short nStripZ);
Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL function coordtrans3d2(;
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
nCoordXZ ref real8,; // 4 Byte
nCoordYZ ref real8,; // 4 Byte
pszCoordZ as psz,; // 4 Byte, char*, 20 alloc.
nEllHgtZ ref real8,; // 4 Byte
nCoordSysZ as word,; // 2 Byte
nRefSysZ as word,; // 2 Byte
nStripZ as word); // 2 Byte
as logic pascal:geodll32.coordtrans3d2 // 4 Byte
Die Allokation von Speicher für "as psz" / "char*" ist zwingend notwendig.
Die Funktion coordtrans3d2() ist der Funktion coordtrans3d() ähnlich. Der
Unterschied besteht darin, dass für die Variable pszCoordZ anstelle der
Übergabe per Referenz eine Übergabe per Value erfolgt. Das ist nur für
Programmiersprachen notwendig, die nicht in der Lage sind ein Konstrukt
"Zeiger auf einen Zeiger auf das erste Zeichen eines Strings", in C mit
"char**" bezeichnet, als Parameter zu übergeben. Der Nachteil besteht
darin, dass die automatische Speicherverwaltung der GeoDLL nicht
verwendet werden kann. Vielmehr muss das rufende Programm den
Speicherplatz für die Variable pszCoordZ allokieren und später auch
wieder freigeben. Aufrufe der Funktion setstringallocate() bleiben in der
Funktion coordtrans3d2() unwirksam.
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 Ziel- und Quellkoordinaten
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 coordtrans3d2() zur Funktion coordtrans2()
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 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 zugrundegelegt. 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 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 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" aufgeführt.
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" aufgeführt.
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" aufgeführt.
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")
nCoordXZ Längen-, Ost- oder X-Komponente der numerischen
(ref) Zielkoordinate.
Bei der Bearbeitung einer alphanumerischen Koordinate ist
dieser Parameter ohne Bedeutung. Das Ausgabeformat der
Koordinate (Notation) ist 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 Ausgabeformat der
Koordinate (Notation) ist in der Liste "Standardwerte der
Koordinatensysteme" aufgeführt.
pszCoordZ Alphanumerische Zielkoordinate.
Bei der Bearbeitung numerischer Koordinaten ist dieser
Parameter ohne Bedeutung. In diesem Fall kann ein NULL-Zeiger
für pszCoordZ eingetragen werden. Das Ausgabeformat der
Koordinate (Notation) ist in der Liste "Standardwerte der
Koordinatensysteme" aufgeführt.
Achtung: "as pszCoordZ" entspricht "char*" in C. Es müssen
20 Byte Speicher für den Null terminated string allokiert
werden.
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")
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 Merdidianstreifens.
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
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".
|