====== Datenimport ======

Der Datenaustausch zwischen dem Instrument und der Ausgleichungssoftware JAG3D kann auf verschiedenen Wegen erfolgen. Ziel des Datenimports ist es, die für die Ausgleichungsrechnung notwendigen Eingangsdaten in der projektspezifischen SQL-Datenbank zu hinterlegen. Technisch gesehen kann daher ein Import von Daten direkt über [[#import_via_sql|SQL-Standardbefehle]] erfolgen. Diese Variante empfiehlt sich, wenn JAG3D als Modul in einer automatisierten Monitoring-Software betrieben wird und keine Administration über die graphische Benutzeroberfläche erfolgt.

Neben dem direkten Import von Daten via SQL-Statements bietet JAG3D zahlreiche Möglichkeiten zum Importieren von Daten über die graphische Benutzeroberfläche an, die sich hinter dem [[user-interface:menu|Hauptmenüpunkt]] ''Import'' befinden. Neben proprietären Formaten von verschiedenen Herstellern unterstützt JAG3D ein flaches, intuitives [[#ascii-daten|ASCII-Format]] zum schnellen und direkten Datenaustausch. Für strukturierte Datenformate steht darüber hinaus auch ein Import für frei-definierbare, [[#spaltenbasierte_daten|spaltenbasierte Daten]] zur Verfügung.

===== ASCII-Daten =====

Seit der Version 2 unterstützt JAG3D ein rudimentär aufgebautes, spaltenbasiertes Textformat, welches als Trennzeichen mindestens ein Leerzeichen und/oder Tabulator (Whitspaces) voraussetzt. Die Anzahl der Whitespaces kann zwischen den Spalten //und// Zeilen variieren. Das Format setzt sich aus zwingend notwendigen Spalten und optionalen Spalten mit Zusatzinformationen zusammen. Kommentare in der Datei sollten mit einem Doppelkreuz (''#'') am Zeilenanfang eingeleitet werden. Für die nachfolgende Formatbeschreibung werden spitze Klammern (''<'' und ''>'') für eine Spaltendefinition verwendet. Eckige Klammern (''['' und '']'') werden eingesetzt, wenn es sich um optionale Werte handelt. Die Defaultwerte bei optionalen Spalten werden jeweils numerisch am Ende angegeben. Die numerischen Größen müssen ferner in der Einheit vorliegen, die auch im Ausgleichungsprojekt eingestellt ist ggf. ist vor dem Import die Einheit umzuschalten. 

==== Terrestrische Beobachtungen ====

Eine terrestrische Beobachtung ist definiert zwischen einem Standpunkt und einem Endpunkt und benötigt einen Messwert. Optionale Zusatzwerte sind die Instrumenten- und Reflektorhöhe sowie die a-priori Standardunsicherheit und die Entfernung, die zur Bildung der kombinierten Messunsicherheit heranzuziehen ist. Die Unterscheidung zwischen a-priori Standardunsicherheit und Entfernung erfolgt über die numerische Größe des Wertes. Ist der eingelesene Wert $\lt 1$, so wird dieser als Unsicherheit betrachtet ansonsten als Entfernung.

<code><start point name> <end point name> [<instrument height|0> <reflector height|0>] <observation value> [<uncertainty|length approximation>]</code>

//Beispiel 1:// Minimale Konfiguration einer Beobachtungsdatei

<code>MS	 P51	 8.20
MS	 P37	 3.85
MS	 P31	 4.35</code>

Instrumenten- und Reflektorhöhen sind 0 (Null) und die a-priori Unsicherheit ist nicht definiert.


//Beispiel 2:// Konfiguration einer Beobachtungsdatei mit Instrumenten- und Reflektorhöhen

<code>MS	 51	1.6	1.3	 8.20
MS	 P37	1.6	1.8	 3.85
MS	 P31	1.6	1.5	 4.35</code>

Die a-priori Unsicherheit ist nicht definiert.


//Beispiel 3:// Konfiguration einer Beobachtungsdatei mit individuellen Unsicherheiten

<code>MS	 P51	 8.20	0.05
MS	 P37	 3.85	0.05
MS	 P31	 4.35	0.05</code>

Instrumenten- und Reflektorhöhen sind 0 (Null) und die a-priori Unsicherheit ist ''0.05''.

//Beispiel 4:// Konfiguration einer Beobachtungsdatei mit individuellen Unsicherheiten und Instrumenten- und Reflektorhöhen

<code>MS	 P51	1.6	1.3	 8.20	0.05
MS	 P37	1.6	1.8	 3.85	0.05
MS	 P31	1.6	1.5	 4.35	0.05</code>

//Hinweis:// Die letzte Spalte ist optional und kann wahlweise die a-priori Messunsicherheit der Beobachtung enthalten oder den Abstand $d$ zwischen Stand- und Zielpunkt. Beim Datenimport wird die Größe des eingelesenen Wertes geprüft. Ist diese kleiner als 1 m, so wird der gelesene Wert als a-priori Messunsicherheit der Beobachtung interpretiert, ansonsten als Abstand $d$, welcher bei der Bildung des gruppenbasierten [[least-squares-adjustment:observation#terrestrische_beobachtungen|stochastischen Modells]] herangezogen wird. Werte, die kleiner oder gleich Null sind, werden ignoriert.
==== Punkte und Koordinaten ====

Ein Punkt benötigt zwingend eine //eindeutige// Bezeichnung, den Punktnamen bzw. die Punktnummer, und entsprechend der Dimension des Punktes bis zu drei numerische Werte für die einzelnen Koordinatenkomponenten. Zusätzlich bzw. optional können für die Dimensionen a-priori Standardunsicherheiten angegeben werden. Im Folgenden wird das Format für den räumlichen 3D-Punkt explizit angeben. Die Formate für Höhen- und Lagepunkte ergeben sich durch entsprechende Vereinfachungen, sodass diese hier nicht angegeben werden. Die optionalen a-priori Unsicherheiten können komponentenweise aber auch für mehrere Koordinatenkomponenten spezifiziert werden.

<code><point name> <east> <north> <height> [[[<uncertainty east/north/height|uncertainty east/north|uncertainty east>] <uncertainty north|uncertainty height>] <uncertainty height>]</code>

//Beispiel 1:// Minimale Konfiguration einer Datei mit Raumpunkten
<code>51	-8.62	27.42	10.29
37	-4.95	27.30	10.04
31	-4.85	20.69	10.51</code>

Es sind nur die Koordinatenkomponenten spezifiziert. Eine Angabe bzgl. der a-priori Unsicherheiten existiert hingegen nicht.

//Beispiel 2:// Konfiguration einer Datei mit Raumpunkten und expliziter Angabe von a-priori Unsicherheiten für alle Koordinatenkomponenten
<code>51	-8.62	27.42	10.29	0.01	0.03	0.02
37	-4.95	27.30	10.04	0.03	0.03	0.02
31	-4.85	20.69	10.51	0.02	0.05	0.04</code>

Es sind die Koordinatenkomponenten und die zugehörigen a-priori Unsicherheiten explizit spezifiziert.

//Beispiel 3:// Konfiguration einer Datei mit Raumpunkten und einheitlichen a-priori Unsicherheiten für alle Koordinatenkomponenten 
<code>51	-8.62	27.42	10.29	0.02
37	-4.95	27.30	10.04	0.03
31	-4.85	20.69	10.51	0.04</code>

Es sind die Koordinatenkomponenten angegeben, die identische a-priori Unsicherheiten aufweisen.

//Beispiel 4:// Konfiguration einer Datei mit Raumpunkten und variierenden a-priori Unsicherheiten für die Lage- und Höhenkomponente
<code>51	-8.62	27.42	10.29	0.02	0.02
37	-4.95	27.30	10.04	0.03	0.02
31	-4.85	20.69	10.51	0.04	0.04</code>

Es sind die Koordinatenkomponenten angegeben, die in der Lage identische a-priori Unsicherheiten aufweisen, sich in der Höhenkomponente aber unterscheiden.

//Hinweis:// Das Standardformat von JAG3D unterstützt keine Spalte für den Punktcode, da dieser für die Ausgleichung nicht relevant ist. Um den Punktcode zu importieren, ist daher der nutzerspezifische Formatimport zu verwenden.

==== GNSS-Basislinien ====

Das Format für GNSS-Basislinien ergibt sich aus einer Kombination der Formate für Punkte und terrestrische Beobachtungen. Wie auch bei den terrestrischen Beobachtungen benötigt die Basislinie zwingend einen Standpunkt und einen Endpunkt. Analog zum Punktformat sind in Abhängigkeit der Dimension die Vektorkomponenten anzugeben. Optional können die a-priori Unsicherheiten der Vektorkomponenten als Zusatzspalten hinterlegt werden.

<code><start point name> <end point name> <delta east> <delta north> <delta height> [[[<uncertainty east/north/height|uncertainty east/north|uncertainty east>] <uncertainty north|uncertainty height>] <uncertainty height>]</code>

//Beispiel 1:// Konfiguration einer Datei mit räumlicher GNSS-Basislinie und expliziter Angabe von a-priori Unsicherheiten für alle Vektorkomponenten
<code>41	N	199.98	500.02	109.94	0.016	0.016	0.062</code>



===== Spaltenbasierte Daten =====

Für spaltenbasierte Daten bietet JAG3D einen nutzerspezifischen Import an, mit dem Formate mit fester Breite oder einem definierten Trennzeichen importiert werden können. Der Importdialog ist im Hauptmenü über ''Import → Spaltenbasierte Daten'' erreichbar und wird nach der Auswahl der zu lesenden Datei geöffnet. Im Dialog ist die Datenart (Punkt, terrestrische Beobachtung oder GNSS-Basislinie) auszuwählen und das Format zu spezifizieren. Handelt es sich um eine CSV-Datei, sind die Trenn- und Maskierungsoptionen entsprechend der Dateiinhalte vorzugeben. Die einzelnen Spalten sind abschließend dem Datentyp zuzuordnen, vgl. Abbildung {{ref>jag3d_ui_import_csv}}. Hierzu kann die Picking-Funktion des Vorschaufensters verwendet werden.

<figure|jag3d_ui_import_csv|left>
{{:user-interface:jag3d_ui_import_csv.png?nolink&690|Import einer Datei mit Character-separated values}}
<caption>Import einer CSV-Datei</caption>
</figure>

Werden die Spalten nicht durch ein eindeutiges Trennzeichen voneinander abgegrenzt, kann die Spaltendefinition auch über einen Zeichenbereich erfolgen. Hierzu ist in der Vorschau einfach der gewünschte Bereich zu selektieren und dem Datentyp zuzuordnen, vgl. Abbildung {{ref>jag3d_ui_import_column_defined}}.

<figure|jag3d_ui_import_column_defined|left>
{{:user-interface:jag3d_ui_import_column_defined.png?nolink&690|Import einer Datei mit fester Spaltendefinition}}
<caption>Import einer Datei mit fester Spaltendefinition</caption>
</figure>


===== Import via SQL =====

Neben der Nutzung des UI kann der Import auch direkt über SQL-Statements abgewickelt werden. Dies bietet sich an, wenn JAG3D als Modul in eine Applikation eingebunden ist und nicht als Stand-Alone Applikation betrieben wird. Ein klassisches Beispiel ist eine Software zum automatisierten Monitoring, in der JAG3D als Modul das Prozessieren der erhobenen Daten (automatisch) vornimmt. In diesem Fall wird man auch bestrebt sein, den Import direkt durchzuführen. Die Datenbank von JAG3D ist nicht verschlüsselt und benötigt keine Authentifizierung. Es wird der HSQLDB Standardnutzer ''sa'' (Akronym für SuperAdmin) ohne Passwort verwendet. Der direkte Import von Daten über die Datenbank erfordert SQL-Kenntnisse. Die zum Projekt gehörenden Tabellennamen können über das Schema abgefragt werden.

<code sql>SELECT 
   TABLE_NAME 
FROM 
   INFORMATION_SCHEMA.TABLES 
WHERE 
   TABLE_SCHEMA = 'OpenAdjustment'</code>