\section{Geodatenimport}

Der Geodaten Importer ist ein in der Programmiersprache Python
geschriebenes Kommandozeilen Werkzeug zum Import von Shapefiles in
eine Datenbank.
Zum Lesen der Shapefiles und zum Schreiben der Geodaten
in die Datenbank wird die GDAL-Bibliothek verwendet.
Um Daten in eine Oracle Datenbank zu importieren ist es n�tig, dass
GDAL und GDAL-Python-Bindings mit Oracle-Unterst�tzung installiert
sind. Bei der Verwendung von PostgreSQL entf�llt dieser Schritt.
Weitere Details hierzu befinden sich im
Kapitel \ref{Systemanforderungen} und \ref{Installationsanleitung}.

Der Importer kann mit einem Shellscript von der Kommandozeile gestartet werden
(siehe Kapitel \ref{Starten des Geodaten Importers}). Nach dem Start wird anhand der
Konfiguration festgestellt, welche Klassen von Shapefiles aus dem Dateisystem
importiert werden sollen. F�r jede Klasse gibt es einen speziellen
Parser, der die speziellen Attribute eines Shapefiles liest und in die entsprechende
Relation der Datenbank schreibt. Die Parser sind speziell auf das
Dateisystem der BfG ausgerichtet. So wird beispielsweise erwartet, dass die Shapefiles der
Gew�sserachse im Ordner $Geodaesie/Flussachse+km$ liegen. Weitere Informationen zu
den einzelnen Parsern sind Kapitel \ref{Beschreibung der Parser} zu
entnehmen. 

Damit die Geodaten eines Shapes sp�ter eindeutig in der Datenbank identifiziert
werden k�nnen, wird f�r jede Geometrie der Pfad des Shapes im Dateisystem 
im Datenbankfeld 'path' gespeichert. Anwendungen, die auf der Datenbank
aufbauen, k�nnen die Geodaten eines Shapefiles sp�ter anhand dieses Merkmals
gruppieren und anzeigen.

Bitte beachten Sie, dass der Geodaten Importer aufgrund der eingesetzten
Technologien derzeit nicht in der Lage ist, lesend auf die Oracle-Datenbank
zuzugreifen. Entsprechend kann beim Import nicht festgestellt werden, ob sich
die Daten eines Shapefiles bereits in der Datenbank befinden, oder nicht. 
Ein erneuter Import der Geodaten w�rde also dazu f�hren, dass Geometrien doppelt in der
Datenbank abgelegt werden.

\subsection{Koordination-Transformation}
F�r die Transformation der Daten verwendet GDAL wiederum die PROJ4-Bibliothek.
Die Daten werden vor dem Schreiben in die Datenbank alle
in die Gau�-Kr�ger-Projektion Zone 3 (EPSG-Code 31467) transformiert.
Ist f�r die zu importierenden Daten keine Projektion ersichtlich 
(fehlende \textit{*.prj}-Datei), so findet keine Transformation statt.
Dies f�hrt nur zu Problemen mit dem Fachdienst FLYS, falls die Daten nicht
bereits in der genannten Projektion vorlagen.

Im Falle der Digitalen Gel�ndemodelle (DGM) findet keine Transformation statt,
da zu diesen lediglich Metadaten in der Datenbank gespeichert werden 
(siehe Kapitel \ref{dgm_parser}),
w�hrend die Daten selbst von der Anwendung Dive4Elements River
aus dem Dateisystem geholt werden.
F�r Berechnungen mit den DGM werden die Geometrien aus der Datenbank
in Dive4Elements River in die Projektion des jeweiligen DGM transformiert.
Daher ist es besonders wichtig, dass die Angaben des EPSG-Codes
in der Spalte SRID in DGMs.csv korrekt sind (siehe Kapitel \ref{dgm_parser})

\subsection{Logfile}
Der Erfolg oder Misserfolg eines Shape-Imports wird 
im Logfile vermerkt. Folgende Eintr�ge k�nnen dem Logfile
entnommen werden:

\textbf{INFO: Inserted \# features}
\\Gibt die Anzahl der erfolgreich importierten Features an.

\textbf{INFO: Failed to create \# features}
\\Gibt die Anzahl der Features an, die nicht importiert werden konnten.

\textbf{INFO: Found 3 unsupported features of type: '...'}
\\Gibt die Anzahl der Features an, die aufgrund ihres Datentyps nicht importiert
werden konnten. Wenn etwa Punkte erwartet wurden aber sich im Shapefile
Polygone befanden.

\textbf{INFO: Did not import values from fields: '...' ...}
\\Der Importer schreibt neben der geographischen Information weitere
Attribut-Daten in die Datenbank. 
Attribut-Spalten die nicht importiert wurden (z.B. auf Grund
von Tippfehlern oder unterschiedlicher Schreibweise),
werden wie angegeben im Logfile aufgef�hrt.

\textbf{ERROR: No source SRS given! No transformation possible!}
\\Das Shapefile enth�lt keine Information, in welcher Projektion die Geometrien
vorliegen. Es findet keine Transformation in die Zielprojektion statt. Bitte
beachten Sie, dass FLYS diese Geometrien sp�ter ggf.\ nicht korrekt darstellen
kann.

\textbf{ERROR: Unable to insert feature: DETAIL}
\\Beim Lesen eines Features ist ein Fehler aufgetreten.
Das Feature konnte nicht in die Datenbank geschrieben werden.

\textbf{ERROR: Exception while committing transaction}
\\Beim Abschluss des Schreib-Vorgangs in die Datenbank ist ein unerwarteter
Fehler aufgetreten. Die Features des Shapes sind nicht importiert worden.

\textbf{ERROR 1: ORA-01017: invalid username/password; logon denied}
\\Es konnte keine Verbindung zur Oracle Datenbank hergestellt werden. Pr�fen Sie
die Verbindungseinstellungen.

Weitere Fehler, die von der Oracle-Datenbank kommen, k�nnen ebenfalls im 
Logfile angezeigt werden.


\subsection{Beschreibung der Parser}
\label{Beschreibung der Parser}

Wie im letzten Kapitel beschrieben, sind die Parser speziell an das Dateisystem
der BfG angepasst. Im Folgenden werden zu jedem Parser folgende Informationen
angegeben:

\textbf{Pfad}
\\Der Pfad, in dem die Shapefiles im Dateisystem abgelegt sein m�ssen (ausgehend
vom Gew�sser Verzeichnis).

\textbf{Geometrie}
\\Der Geometrie Typ, der f�r diese Klasse von Shapefiles erwartet wird.

\textbf{Attribute}
\\Eine Liste der Attribute, die vom Parser aus dem Shape gelesen werden.
In Klammern als alternativ bezeichnete Attribut-Namen werden in
das gleiche Datenbankfeld geschrieben, wie das vorgenannte Feld.
Die alternativen Namen werden vom Importer zus�tzlich unterst�tzt, 
um Dateien aus dem heterogenen Bestand der BfG unver�ndert 
importieren zu k�nnen.

Zudem werden Datenbank-Attribute beschrieben, die nicht direkt aus 
Attribut-Spalten des Shapefiles gelesen werden.

\subsubsection{Achsen}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Geodaesie/Flussachse+km \\
Geometrie   &   LINESTRING, MULTILINESTRING \\
\end{tabular*}

Das Attribut 'name' wird auf den Namen des Shapefiles gesetzt.
Zus�tzlich wird das Attribut 'kind\_id' gesetzt, welches 
f�r die aktuelle Achse (\textit{achse.shp}) 1 ist 
und f�r sonstige Achsen (weitere Linien-Shapes) 2.

\subsubsection{Hydr. Grenzen}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Hydrologie/Hydr.Grenzen \\
Geometrie   &   LINESTRING, MULTILINESTRING, POLYGON, MULTIPOLYGON \\
Attribute   &   SECTIE, STROVOER \\
\end{tabular*}

Das Attribut 'name' wird auf den Namen des Shapefiles gesetzt.
Das Attribut 'kind' wird 1 gesetzt f�r Daten aus dem 
Unterverzeichnis \textit{Linien/BfG}, 
2 f�r Daten aus \textit{Linien/Land},
3 f�r Daten aus \textit{Sonstige}
und f�r alle �brigen 0.
Ausgenommen sind Dateien, in deren Namen 'Talaue' 
(Gro�-Klein-Schreibung irrelevant) vorkommt.

Linien und Polygone werden in der Datenbank in unterschiedlichen
Tabellen gespeichert.

\subsubsection{Bauwerke}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Geodaesie/Bauwerke \\
Geometrie   &   LINESTRING \\
Attribute   &   Name (alternativ: KWNAAM), 
  km (alternativ: station, wsv-km), 
  z (alternativ: H�he, Hoehe, m+NHN)\\
\end{tabular*}

Das Attribut 'name' wird auf den Namen des Shapefiles gesetzt.
Das Attribut 'kind\_id' ist 0 f�r Sonstige,
1 f�r Br�cken, 2 f�r Wehre, 3 f�r Pegel.
Es wird aus dem Dateinamen hergeleitet 
(\textit{bruecken.shp, wehre.shp, pegel.shp}, 
teilweise auch alternative Schreibweisen unterst�tzt)
oder je Feature gesetzt, wenn in einer Attributspalte 
die Werte 'bruecke' und 'wehr' 
(teilweise auch alternative Schreibweisen unterst�tzt) vorkommen.
Ausgenommen sind Dateien, in deren Namen 'Buhnen' 
(Gro�-Klein-Schreibung irrelevant) vorkommt.

\subsubsection{Querprofilspuren}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Geodaesie/Querprofile \\
Geometrie   &   LINESTRING \\
Attribute   &   KILOMETER (alternativ: KM, STATION), ELEVATION \\
\end{tabular*}

Das Attribut 'kind\_id' wird 1 gesetzt f�r die Datei \textit{qps.shp} (aktuelle Querprofilspuren)
und 0 f�r alle weiteren.

\subsubsection{Festpunkte}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Geodaesie/Festpunkte \\
Geometrie   &   POINT \\
Attribute   &   KM (alternativ: ELBE\_KM), X, Y, HPGP (alternativ: ART) \\
\end{tabular*}

Das Attribut 'name' wird auf den Namen des Shapefiles gesetzt.

\subsubsection{Hochwassermarken}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Hydrologie/HW-Marken/hw-marken.shp \\
Geometrie   &   POINT \\
Attribute   &   Ort (alternativ: Pegel),
  km (alternativ: station, wsv-km, FlussKm), 
  z (alternativ: z mit anschlie�ender Zahl, m+NHN)\\
\end{tabular*}

Gro�-Klein-Schreibung im Dateinamen ist irrelevant.
F�r das Attribut 'year' wird im Dateinamen nach einer Jahreszahl
nach folgendem Muster gesucht: \textit{\_YYYY\_} oder \textit{-YYYY-}. 
Gelingt dies nicht, erscheint im Logfile die Warnung
'Could not extract year from filename: ...'.

\subsubsection{Talaue}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Hydrologie/Hydr.Grenzen \\
Geometrie   &   POLYGON, MULTIPOLYGON \\
\end{tabular*}

Es werden nur Dateien betrachtet, in deren Namen das Wort 'Talaue'
(Gro�-Klein-Schreibung irrelevant) vorkommt.
Das Attribut 'name' wird auf den Namen des Shapefiles gesetzt.
Das Attribut 'kind\_id' wird 1 gesetzt f�r die Datei \textit{talaue.shp} (aktuelle Talaue)
und 0 f�r alle weiteren.

\subsubsection{Hochwasserschutzanlagen}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Hydrologie/HW-Schutzanlagen \\
Geometrie   &   LINESTRING, MULTILINESTRING, POINT \\
Attribute   &   Name, Art, Quelle, Anmerkung, Stand, Verband,
                km (alternativ: Deich\_km), Bereich, 
                Hoehe, Hoehe\_soll, WSP\_Bfg100, Bundesland
                (Teilweise auch alternative Schreibweisen unterst�tzt)\\
\end{tabular*}

Das Attribut 'name' wird auf den Namen des Shapefiles gesetzt, 
wenn kein Attribut 'Name' im Shapefile vorhanden ist.
Das Feld 'kind\_id' wird per Default auf 2 (f�r Damm) gesetzt.
Wird ein Attribut 'ART' im Shapefile gefunden, 
so wird 'kind\_id' entsprechend dieses Feldes gesetzt 
(1 f�r die Werte 'Durchlass', 'Rohr1', 'Rohr 1', 'Rohr 2',
2 f�r die Werte 'Damm', 'Deich', 'Hochufer', 'Hauptdeich', 'Sommerdeich',
3 f�r den Wert 'Graben').
Es wird versucht das Bundesland aus dem Dateinamen zu ermitteln,
wenn das Shapefile kein Attribut 'Bundesland' enth�lt.

Linien und Punkte werden in der Datenbank in unterschiedlichen
Tabellen gespeichert.

\subsubsection{Buhnen}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Geodaesie/Bauwerke/Buhnen.shp \\
Geometrie   &   POINT \\
Attribute   &   station (alternativ: km, wsv-km), 
                z (alternativ: Hoehe, H�he, m+NHN) \\
\end{tabular*}

Das Attribut 'kind\_id' wird f�r 
Buhnenkopf (\textit{bkl, bkr, bk}) 0,
f�r Buhnenfu� (\textit{bfl, bfr, bf}) 1 und
f�r Buhnenwurzel (\textit{bwl, bwr, bw}) 2 gesetzt,

\subsubsection{Stationierung}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Geodaesie/Flussachse+km/km.shp \\
Geometrie   &   POINT \\
Attribute   &   km (alternativ: KM), landkm \\
\end{tabular*}

Das Attribut 'name' wird auf den Namen des Shapefiles gesetzt.

\subsubsection{�berschwemmungsfl�che}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   Hydrologie/UeSG \\
Geometrie   &   POLYGON, MULTIPOLYGON \\
Attribut    &   diff, count, area, perimeter, GEWAESSER \\
\end{tabular*}

Das Attribut 'name' wird auf den Namen des Shapefiles gesetzt.
Das Attribut 'kind' wird nach folgendem Schema gesetzt:

\hspace{5mm}
\begin{tabular}[t]{ll}
Unterverzeichnis & Wert \\
\textit{Berechnungen/Aktuell/BfG} & 111 \\
\textit{Berechnungen/Aktuell/Bundesl�nder} & 112 \\
\textit{Berechnungen/Potentiell/BfG} & 121 \\
\textit{Berechnungen/Potentiell/Bundesl�nder} & 122 \\
\textit{Messungen} & 200 \\
\end{tabular}

Das Attribut 'source' wird auf den Namen des Verzeichnisses gesetzt,
indem sich das jeweilige Shapefile befindet.

\subsubsection{Metadaten zu Digitalen Gel�nde-Modellen}
\label{dgm_parser}
\hspace{5mm}
\begin{tabular*}{155mm}[t]{l@{\extracolsep\fill}p{125mm}}
Pfad        &   ../DGMs.csv \\
Attribut    &   Projektion, H�henstatus, Format, Bruchkanten,
                Aufl�sung, SRID, Pfad\_Bestand,
                km\_von, km\_bis, Jahr\_von, Jahr\_bis \\
\end{tabular*}

Aus der Spalte 'Gew�sser' in DGMs.csv wird entnommen, 
f�r welches Gew�sser das angegebene DGM verwendet wird. 
Die Spalte muss daher den exakt gleichen Namen enthalten 
wie in der *.gew-Datei des Gew�ssers angegeben 
(siehe auch Kapitel \ref{start-hydr}).
Die eigentlichen Geo-Daten der DGM werden nicht in die Datenbank importiert.
Diese werden von der Anwendung Dive4Elements River aus dem Dateisystem geholt.

\subsection{Konfiguration}
\label{Konfiguration}
Der Geodaten Importer kann �ber das Skript \textit{./run\_geo.sh}
konfiguriert werden. �ffnen Sie die Datei mit einem Texteditor Ihrer Wahl
und passen Sie ggf.\ folgende Variablen an:

\textbf{HOST}
\\Der Host der Datenbank.

\textbf{BACKEND\_NAME}
\\Der Name der Datenbank Instanz. 
Beispielsweise \textit{XE} bei einer Oracle XE Instanz.

\textbf{USER}
\\Der Nutzer, der zum Verbinden zur Datenbank verwendet wird.

\textbf{PASS}
\\Das Passwort f�r USER zum Verbinden zur Datenbank.

In den weiteren Zeilen werden weitere Optionen definiert, die bei Bedarf angepasst
werden k�nnen. Falls nicht anders angegeben, k�nnen die Optionen mit den Werten
`0` und `1` belegt werden.

\textbf{VERBOSE}
\\Dieser Wert gibt die Granularit�t der Log-Ausgaben w�hrend des
Imports an. Je h�her der Wert, desto mehr Informationen werden
in das Logfile geschrieben. Aktuell sind die Werte `0`, `1` und
`2` definiert. Wird der Wert `0` gesetzt, werden nur Fehler und
Warnungen in das Logfile geschrieben. Bei `1` werden neben
Fehlern und Warnungen auch Infos in das Logfile geschrieben. Bei
`2` werden s�mtliche Ausgaben des Programms geschrieben. Dieser
Modus ist haupts�chlich f�r die Entwicklung gedacht.

\textbf{OGR\_CONNECTION}
\\Hiermit kann direkt ein beliebiger Verbindungs-String angegegeben
werden, welcher dann anstatt HOST, USER und PASS verwendet wird.
Diese Option wird direkt an die OGR-Bibliothek weitergegeben und erm�glicht
verbesserte Tests und Entwicklung mit verschiedenen Backends.

\textbf{SKIP\_AXIS}
\\Bei gesetztem Wert `1` werden keine Flussachsen importiert.

\textbf{SKIP\_KMS}
\\Bei gesetztem Wert `1` werden keine Stationierungen importiert.

\textbf{SKIP\_CROSSSECTIONS}
\\Bei gesetztem Wert `1` werden keine Querprofilespuren importiert.

\textbf{SKIP\_FIXPOINTS}
\\Bei gesetztem Wert `1` werden keine Festpunkte importiert.

\textbf{SKIP\_BUILDINGS}
\\Bei gesetztem Wert `1` werden keine Bauwerke importiert.

\textbf{SKIP\_FLOODPLAINS}
\\Bei gesetztem Wert `1` werden keine Talauen importiert.

\textbf{SKIP\_HYDR\_BOUNDARIES}
\\Bei gesetztem Wert `1` werden keine hydrologischen Grenzen importiert.

\textbf{SKIP\_HWS\_LINES}
\\Bei gesetztem Wert `1` werden kein Hochwasserschutzanlagen  (Liniendaten) importiert.

\textbf{SKIP\_HWS\_POINTS}
\\Bei gesetztem Wert `1` werden kein Hochwasserschutzanlagen (Punktdaten) importiert.

\textbf{SKIP\_UESG}
\\Bei gesetztem Wert `1` werden keine �berschwemmungsfl�chen importiert.

\textbf{SKIP\_DGM}
\\Bei gesetztem Wert `1` werden keine Metadaten zu Digitalen Gel�ndemodellen importiert.

\textbf{SKIP\_JETTIES}
\\Bei gesetztem Wert `1` werden keine Buhnen importiert.

\textbf{SKIP\_FLOODMARKS}
\\Bei gesetztem Wert `1` werden keine HW-Marken importiert.

\subsection{Starten des Geodaten Importers}
\label{Starten des Geodaten Importers}
Der Geodaten Importer wird mittels des Shellskripts,
dass auch f�r die Konfiguration verwendet wird, von einer Konsole
gestartet. Dazu f�hren Sie folgenden Befehl aus:\\

\begin{lstlisting}
    sh ./run_geo.sh pfad/zur/beispiel.gew > geo-import.log
\end{lstlisting}

Bez�glich des �bergebenen Pfades siehe auch Kapitel \ref{start-hydr}.
Der Importer wird nun gestartet. S�mtliche Log-Ausgaben werden in die Datei
$geo-import.log$ geschrieben.