--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/flys-backend/doc/shapeimporter/documentation.txt	Thu Aug 23 15:46:01 2012 +0000
@@ -0,0 +1,227 @@
+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.