Geodaten Importer
=================
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. Zum Import in eine
Oracle Datenbank ist es erforderlich, dass GDAL und GDAL Python Bindungs mit
Oracle Unterstützung installiert sind. Weitere Details hierzu befinden sich im
Kapitel `Systemanforderungen` und `Installationsanleitung`.
Der Importer kann mit einem Shellscript von der Kommandozeilen gestartet werden
(siehe Kapitel `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 hierzu einen speziellen
Parser, der die speziellen Attribute eines Shapefiles liest und in die ent-
sprechende 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 `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:

  INFO: Inserted 4 features         Gibt die Anzahl der erfolgreich importierten
                                    Features an.

  INFO: Failed to create 2 features   Gibt die Anzahl der Features an, die nicht
                                      importiert werden konnten.

  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.

  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.

  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.

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.


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:

  Pfad          Der Pfad, in dem die Shapefiles im Dateisystem abgelegt sein
                müssen ausgehend vom Gewässer Verzeichnis.

  Geometrie     Der Geometrie Typ, der für diese Klasse von Shapefiles
                erwartet wird.

  Attribute     Eine Liste der Attribute, die vom Parser aus dem Shape
                gelesen werden.


    Achsen
    ------
    Pfad        Geodaesie/Flussachse+km
    Geometrie   LINESTRING
    Attribute   name, kind


    Hydrologische Grenzen
    ---------------------
    Pfad        Hydrologie/Hydr.Grenzen/Linien
    Geometrie   LINESTRING, POLYGON
    Attribute   name, kind


    Bauwerke
    --------
    Pfad        Geodaesie/Bauwerke
    Geometrie   LINESTRING
    Attribute   name, Name, KWNAAM


    Einzugsgebiete
    --------------
    Pfad        Hydrologie/Einzugsgebiet
    Geometrie   POLYGON, MULTIPOLYGON
    Attribute   name, Name, AREA, area


    Querprofilspuren
    ----------------
    Pfad        Geodaesie/Querprofile
    Geometrie   LINESTRING
    Attribute   KILOMETER, KM, STATION, ELEVATION


    Festpunkte
    ----------
    Pfad        Geodaesie/Festpunkte
    Geometrie   POINT
    Attribute   name, KM, ELBE_KM, X, Y, HPGP


    Talaue
    ------
    Pfad        Hydrologie/Hydr.Grenzen
    Geometrie   POLYGON, MULTIPOLYGON
    Attribute   name


    Pegelstationen
    --------------
    Pfad        Hydrologie/Streckendaten
    Geometrie   POINT
    Attribute   Name, name, MPNAAM


    Hochwasserschutzanlagen
    -----------------------
    Pfad        Hydrologie/HW-Schutzanlagen
    Geometrie   LINESTRING
    Attribute   TYP, Bauart, Name, name


    Kilometrierung
    --------------
    Pfad        Geodaesie/Flussachse+km
    Geometrie   POINT
    Attribute   name, km, KM


    Linien
    ------
    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 als '9999' als Höhe
    angenommen.


    Überschwemmungsfläche
    ----------------------
    Pfad        Hydrologie/UeSG/Berechnung
    Geometrie   POLYGON, MULTIPOLYGON
    Attribut    name, diff, count, area, perimeter


Systemanforderungen
-------------------
 * Oracle Datenbank inkl. Schema für FLYS
 * GDAL Binding für Python mit Oracle Support
 * ogr2ogr
 * Python >= 2.6


Installationsanleitung
----------------------
 * TODO: GDAL Binding installieren
 * TODO: Python installieren
 * TODO: ogr2ogr installieren


Konfiguration
-------------
Der Geodaten Importer kann über die Datei `contrib/shpimporter/run.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:

  RIVER_PATH    Der Pfad zum Gewässer im Dateisystem.
  RIVER_ID      Die Datenbank ID des zu importierenden Gewässers.
  TARGET_SRS    Das EPSG Referenzsystem in das die Geodaten beim Import
                projeziert werden sollen.
  HOST          Der Host der Datenbank.
  USER          Der Nutzer, der zum Verbinden zur Datenbank verwendet wird.
  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.

  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.

  SKIP_AXIS             Bei gesetztem Wert `1` werden keine Flussachsen importiert.
  SKIP_KMS              Bei gesetztem Wert `1` werden keine Kilometrierungen importiert.
  SKIP_CROSSSECTIONS    Bei gesetztem Wert `1` werden keine Querprofilespuren
                        importiert.
  SKIP_LINES            Bei gesetztem Wert `1` werden keine Linien importiert.
  SKIP_FIXPOINTS        Bei gesetztem Wert `1` werden keine Festpunkte importiert.
  SKIP_BUILDINGS        Bei gesetztem Wert `1` werden keine Bauwerke importiert.
  SKIP_FLOODPLAINS      Bei gesetztem Wert `1` werden keine Talauen importiert.
  SKIP_HYDR_BOUNDARIES  Bei gesetztem Wert `1` werden keine hydrologischen
                        Grenzen importiert.
  SKIP_HWS              Bei gesetztem Wert `1` werden keine
                        Hochwasserschutzanlagen importiert.
  SKIP_GAUGE_LOCATION   Bei gesetztem Wert `1` werden keine Pegelorte importiert.
  SKIP_CATCHMENTS       Bei gesetztem Wert `1` werden keine Einzugsgebiete importiert.
  SKIP_UESG             Bei gesetztem Wert `1` werden keine
                        Überschwemmungsflächen importiert.


Starten des Geodaten Importers
------------------------------
Der Geodaten Importer wird mittels eines Shellskripts von einer Konsole
gestartet. Dazu wechseln Sie auf der Konsole in das Verzeichnis 'TODO' und
führen Sie folgenden Befehl aus:

  $> sh contrib/shpimporter/run.sh > import.log

Der Importer wird nun gestartet. Sämtliche Log-Ausgaben werden in die Datei
`import.log` geschrieben.