--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/flys-backend/doc/documentation/de/importer-geodaesie.tex	Fri Sep 28 12:14:48 2012 +0200
@@ -0,0 +1,356 @@
+\section{Geodatenimport}
+
+Der Geodaten Importer ist ein in Python geschriebenes Kommandozeilen Tool zum
+Import von Shapefiles in eine Datenbank. Zum Lesen der Shapefiles und zum
+Schreiben der Geodaten in die Datenbank wird GDAL verwendet. Der Import in eine
+Oracle Datenbank erfordert, dass GDAL und GDAL Python Bindungs mit
+Oracle Unterstützung installiert sind. 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 z.B. erwartet, dass die Shapefiles der
+Gewässerachse im Ordner $Geodaesie/Flussachse+km$ liegen. Weitere Informationen zu
+den einzelnen Parsern sind dem nächsten Kapitel \ref{Beschreibung der Parser} zu
+entnehmen. Der Erfolg oder Misserfolg eines Shape-Imports wird je nach
+Konfiguration im Logfile vermerkt. Folgende Einträge können dem Logfile
+entnommen werden:
+
+\textbf{INFO: Inserted 4 features}
+\\Gibt die Anzahl der erfolgreich importierten Features an.\\
+
+\textbf{INFO: Failed to create 2 features}
+\\Gibt die Anzahl der Features an, die nicht importiert werden konnten.\\
+
+\textbf{INFO: Found 3 unsupported features}
+\\Gibt die Anzahl der Features an, die aufgrund ihres Datentyps nicht importiert
+werden konnten. Z.B: es werden Linien erwartet, im Shapefile sind jedoch
+Polygone enthalten.\\
+
+\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 der Attribute 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.
+
+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 in
+einer Spalte der Datenbank gespeichert. Anwendungen, die auf der Datenbank
+aufbauen, können die Geodaten eines Shapefiles später anhand dieses Merkmals
+gruppieren und anzeigen.
+
+
+\subsection{Beschreibung der Parser}
+\label{Beschreibung der Parser}
+
+Wie im letzten Kapitel beschrieben, sind die Parser speziell an das Dateisystem
+der BfG ausgerichtet. 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.
+
+
+\subsubsection{Achsen}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Geodaesie/Flussachse+km \\
+Geometrie   &   LINESTRING \\
+Attribute   &   name, kind \\
+\end{tabular}
+
+
+\subsubsection{Hydrologische Grenzen}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Hydrologie/Hydr.Grenzen/Linien \\
+Geometrie   &   LINESTRING, POLYGON \\
+Attribute   &   name, kind \\
+\end{tabular}
+
+\subsubsection{Bauwerke}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Geodaesie/Bauwerke \\
+Geometrie   &   LINESTRING \\
+Attribute   &   name, Name, KWNAAM \\
+\end{tabular}
+
+
+\subsubsection{Einzugsgebiete}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Hydrologie/Einzugsgebiet \\
+Geometrie   &   POLYGON, MULTIPOLYGON \\
+Attribute   &   name, Name, AREA, area \\
+\end{tabular}
+
+
+\subsubsection{Querprofilspuren}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Geodaesie/Querprofile \\
+Geometrie   &   LINESTRING \\
+Attribute   &   KILOMETER, KM, STATION, ELEVATION \\
+\end{tabular}
+
+
+\subsubsection{Festpunkte}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Geodaesie/Festpunkte \\
+Geometrie   &   POINT \\
+Attribute   &   name, KM, ELBE\_KM, X, Y, HPGP \\
+\end{tabular}
+
+
+\subsubsection{Talaue}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Hydrologie/Hydr.Grenzen \\
+Geometrie   &   POLYGON, MULTIPOLYGON \\
+Attribute   &   name \\
+\end{tabular}
+
+
+\subsubsection{Pegelstationen}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Hydrologie/Streckendaten \\
+Geometrie   &   POINT \\
+Attribute   &   Name, name, MPNAAM \\
+\end{tabular}
+
+
+\subsubsection{Hochwasserschutzanlagen}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Hydrologie/HW-Schutzanlagen \\
+Geometrie   &   LINESTRING \\
+Attribute   &   TYP, Bauart, Name, name \\
+\end{tabular}
+
+
+\subsubsection{Kilometrierung}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Geodaesie/Flussachse+km \\
+Geometrie   &   POINT \\
+Attribute   &   name, km, KM \\
+\end{tabular}
+
+
+\subsubsection{Linien}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Geodaesie/Linien \\
+Geometrie   &   LINESTRING, MULTILINESTRING \\
+Attribute   &   name, TYP, Z \\
+
+Anmerkung   & Wenn kein Attribut 'TYP' definiert ist, wird standardmäßig der Wert \\
+            & 'DAMM' angenommen. Fehlt ein Attribut 'Z' wird '9999' als Höhe \\
+            & angenommen. \\
+\end{tabular}
+
+
+\subsubsection{Überschwemmungsfläche}
+\hspace{1cm}
+\begin{tabular}[t]{ll}
+Pfad        &   Hydrologie/UeSG/Berechnung \\
+Geometrie   &   POLYGON, MULTIPOLYGON \\
+Attribut    &   name, diff, count, area, perimeter \\
+\end{tabular}
+
+
+\subsection{Systemanforderungen}
+\label{Systemanforderungen}
+\begin{itemize}
+  \item Oracle Datenbank inkl. Schema für FLYS
+  \item GDAL Binding für Python mit Oracle Support
+  \item ogr2ogr
+  \item Python $>=$ 2.6
+\end{itemize}
+
+
+\subsection{Installationsanleitung}
+\label{Installationsanleitung}
+\begin{itemize}
+
+ \item Python\\
+ Zum Starten des Importers ist es notwendig Python zu installieren. Dies können
+ Sie mit folgendem Befehl auf der Kommandozeile erledigen:
+
+ \begin{lstlisting}
+    zypper in python
+ \end{lstlisting}
+
+ \item Oracle Instantclient\\
+ Der Oracle Instantclient 11.2 wird benötigt, damit der Importer mittels Python
+ und GDAL in die bestehende Oracle Datenbank schreiben kann. Dazu ist es
+ erforderlich, folgende Archive von Oracle herunterzuladen. Zu finden sind die
+ folgenden Pakete unter\\
+ \href{http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html}{http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html}
+
+ \begin{itemize}
+    \item instantclient-basic-linux-x86-64-11.2.0.2.0.zip
+    \item instantclient-sdk-linux-x86-64-11.2.0.2.0.zip
+    \item instantclient-sqlplus-linux-x86-64-11.2.0.2.0.zip
+ \end{itemize}
+
+ Anschließend führen Sie folgende Befehle auf der Kommandozeile aus:
+
+ \begin{lstlisting}
+
+    mkdir /opt
+
+    unzip ~/instantclient-basic-linux-x86-64-11.2.0.2.0.zip -d /opt
+    unzip ~/instantclient-sdk-linux-x86-64-11.2.0.2.0.zip -d /opt
+    unzip ~/instantclient-sqlplus-linux-x86-64-11.2.0.2.0.zip -d /opt
+
+    mkdir /opt/instantclient_11_2/lib
+    cd /opt/instantclient_11_2/lib
+    ln -s ../libclntsh.so.11.1 .
+    ln -s ../libclntsh.so.11.1 libclntsh.so
+    ln -s ../libnnz11.so .
+    ln -s ../libocci.so.11.1 .
+    ln -s ../libocci.so.11.1 libocci.so
+    ln -s ../libociei.so .
+    ln -s ../libocijdbc11.so .
+    ln -s ../libsqlplusic.so .
+    ln -s ../libsqlplus.so .
+
+    rpm -i --nodeps ~/flys-importer/rpm/RPMS/x86_64/libgdal1180-1.8.0-intevation1.x86_64.rpm 
+    rpm -i --nodeps ~/flys-importer/rpm/RPMS/x86_64/libgdal180-devel-1.8.0-intevation1.x86_64.rpm
+    rpm -i --nodeps ~/flys-importer/rpm/RPMS/x86_64/gdal180-1.8.0-intevation1.x86_64.rpm
+
+ \end{lstlisting}
+
+ Sollten keine Fehler aufgetreten sein, haben Sie den \textit{Oracle
+ Instantclient 11.2} erfolgreich entpackt und im Dateisystem unter
+ \textit{/opt/instantclient\_11\_2} abgelegt. Mit den Befehlen $rpm -i --nodeps$
+ haben Sie anschließend die notwendigen Bindings installiert, damit der Importer
+ die Geodaten in die Oracle Datenbank schreiben kann.
+
+\end{itemize}
+
+
+\subsection{Konfiguration}
+\label{Konfiguration}
+Der Geodaten Importer kann über die Datei \textit{contrib/run\_geo.sh}
+konfiguriert werden. Öffnen Sie die Datei mit einem Texteditor Ihrer Wahl.
+In den Zeilen 4-9 werden Optionen definiert, die zwangsläufig angepasst
+werden müssen:
+
+\textbf{RIVER\_PATH}
+\\Der Pfad zum Gewässer im Dateisystem.
+
+\textbf{RIVER\_ID}
+\\Die Datenbank ID des zu importierenden Gewässers.
+
+\textbf{TARGET\_SRS}
+\\Das EPSG Referenzsystem in das die Geodaten beim Import projeziert werden
+sollen.
+
+\textbf{HOST}
+\\Der Host der Datenbank.
+
+\textbf{USER}
+\\Der Nutzer, der zum Verbinden zur Datenbank verwendet wird.
+
+\textbf{PASS}
+\\Das Passwort für USER zum Verbinden zur Datenbank.
+
+In den Zeilen 12-23 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{SKIP\_AXIS}
+\\Bei gesetztem Wert `1` werden keine Flussachsen importiert.
+
+\textbf{SKIP\_KMS}
+\\Bei gesetztem Wert `1` werden keine Kilometrierungen importiert.
+
+\textbf{SKIP\_CROSSSECTIONS}
+\\Bei gesetztem Wert `1` werden keine Querprofilespuren importiert.
+
+\textbf{SKIP\_LINES}
+\\Bei gesetztem Wert `1` werden keine Linien 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}
+\\Bei gesetztem Wert `1` werden kein Hochwasserschutzanlagen importiert.
+
+\textbf{SKIP\_GAUGE\_LOCATION}
+\\Bei gesetztem Wert `1` werden keine Pegelorte importiert.
+
+\textbf{SKIP\_CATCHMENTS}
+\\Bei gesetztem Wert `1` werden keine Einzugsgebiete importiert.
+
+\textbf{SKIP\_UESG}
+\\Bei gesetztem Wert `1` werden keine Überschwemmungsflächen importiert.
+
+
+\subsection{Starten des Geodaten Importers}
+\label{Starten des Geodaten Importers}
+Der Geodaten Importer wird mittels eines Shellskripts von einer Konsole
+gestartet. Dazu führen Sie folgenden Befehl aus:\\
+
+\begin{lstlisting}
+    sh contrib/run_geo.sh > geo-import.log
+\end{lstlisting}
+
+Der Importer wird nun gestartet. Sämtliche Log-Ausgaben werden in die Datei
+$geo-import.log$ geschrieben.
+
+\textbf{Hinweis}
+\\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
+Shapefiles bereits in der Datenbank befinden, oder nicht. Ein erneuter Import
+Vorgang der Geodaten würde also dazu führen, dass Geometrien doppelt in der
+Datenbank abgelegt werden.
+