Doc/manual/thuban-manual-de.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book
        PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
    [<!ENTITY imgscale "60">]>
<!-- $Revision$ -->
<book>
  <bookinfo>
    <title>Benutzerhandbuch für Thuban 1.0</title>
        <authorgroup>
      <author>
        <firstname>Jonathan</firstname><surname>Coles</surname>
      </author>
      <author>
        <firstname>Jan-Oliver</firstname><surname>Wagner</surname>
      </author>
      <author>
        <firstname>Frank</firstname><surname>Koormann</surname>
      </author>
        </authorgroup>
    <copyright>
      <year>2004</year>
      <holder>Intevation GmbH</holder>
    </copyright>
   <revhistory>
<!-- comment this first revision out when releasing a real version -->
     <revision>
        <revnumber>CVS version $Id$</revnumber>
        <date></date>
        <revremark>Under development.</revremark>
     </revision>
<!--
     <revision>
        <revnumber>1.0.0</revnumber>
        <date>nn-Mmm-2004</date>
        <revremark>
                        Corresponds to Thuban 1.0.0.
                </revremark>
     </revision>
-->
  </revhistory>

  </bookinfo>

  <chapter><title>Einführung</title>
        <para>
        Thuban ist ein interaktiver Geodaten-Betrachter.
        Die Entwicklung wurde seinerzeit gestartet, da es zu dieser Zeit
        keinen einfachen interkativen Betrachter für Geo-Daten als Freie
        Software gab.
        Thuban ist im wesentlichen in der Programmiersprache Python implementiert und
        nutzt die wxWidgets (ehemals: wxWindows) Bibliothek die es erlaubt
        Thuban auf verschiedenen Plattformen laufen zu lassen, darunter GNU/Linux
        und Windows.
        </para>
        <para>
        Geodatenbetrachter sind wichtige Werkzeuge die es gestatten, einen visuelle
        Eindruck des räumlichen (gegenseiten) Bezuges von Informationen zu bekommen
        die ansonsten anhand der reinen Daten nicht leicht ersichtlich sind.
        Thuban erlaubt dem Benutzer, Sitzungen zu erzeugen, die geografische
        Daten darstellen. Diese können dann erforscht werden indem er durch sie
        sie navigieren und die Art der Darstellung ändern kann.
        Die Ergebnisse können gespeichert oder gedruckt werden.
        </para>
        <para>
        Thuban strukturiert eine Sitzung hierarchisch.
        Eine Sitzung besteht aus Ebenen. Jede Ebene rerpäsentiert
        einen bestimmten Datensatz.
        Beispielsweise eine Ebene für Strassen und eine weitere für Gebäude.
        Die Ebenen können sowohl Vektor-Daten beschreiben als auch Raster-Daten.
        </para>

        <section><title>Installation</title>
        <para>
        Thuban is actively supported under Debian Testing (sarge), RedHat 7.2, 
        and Windows 2000. Thuban depends on the following packages. These
        packages can also be found on the 
        <ulink url="http://thuban.intevation.org/download.html">
        Thuban Download site
        </ulink>.
        </para>
        <para>
        Required:
        <itemizedlist>
            <listitem><para>Python 2.2.1 
                        (<literal>http://www.python.org</literal>)
                        </para></listitem>
            <listitem><para>wxWindows 2.4 
                        (<literal>http://www.wxwindows.org</literal>)
                        </para></listitem>
            <listitem><para>wxPython 2.4 
                        (<literal>http://www.wxpython.org</literal>)
                        </para></listitem>
            <listitem><para>proj 4.4.5 Projection Library 
                        (<literal>http://www.remotesensing.org/proj/</literal>)
                        </para></listitem>
            <listitem><para>SQLite 2.8.3 
                        <literal>http://www.hwaci.com/sw/sqlite/</literal>)
                        </para></listitem>
            <listitem><para>PySQLite 0.4.3 
                        (<literal>http://pysqlite.sourceforge.net</literal>)
                        </para></listitem>
        </itemizedlist>
        </para>
        <para>
        Optional:
        <itemizedlist>
            <listitem><para>GDAL 1.1.8 
                        (<literal>http://www.remotesensing.org/gdal/</literal>)
                        </para></listitem>
            <listitem><para>psycopg 1.0.8 
                        (<literal>http://initd.org/software/psycopg</literal>)
                        </para></listitem>
            </itemizedlist>
        </para>
                <para>
                Along with the source codes, the download page also offers full
                installation packages for Debian, Windows and RPM-based systems
                (Mandrake, RedHat, SuSE, etc).
                </para>
                <section><title>RPM-based GNU/Linux Systems</title>
                        <section><title>Installing Binary Packages</title>
                                <para>
                                The most wide-spread RPM-based GNU/Linux
                                Systems are RedHat, Mandrake and SuSE. 
                                The documentation of these distributions
                                should contain information about how to 
                                install third-party RPM packages.
                                Nonetheless, a short summary is provided here.
                                </para>
                                <para>
                                RPM packages can be installed applying several 
                                tools. The most basic one is the command line 
                                program "rpm".  The hardware architecture is 
                                identified in the name of RPM packages, eg. 
                                'i386' for most Intel/AMD architectures.  
                                If you have a different hardware architecture, 
                                where no binary RPM packages are provided, 
                                you must rebuild binary packages from the 
                                RPM source packages first (see below).
                                Typical rpm commands look like:

                                <programlisting>
                                rpm --install Thuban-0.9.0-1.i386.rpm
                                </programlisting>

                                Depending on what you already have installed 
                                on your system, you are informed that some 
                                packages are required, but not installed. 
                                You need to install them first. Either they 
                                are provided by your GNU/Linux distributor 
                                or available somewhere on the Internet.  
                                The more essential and special ones are 
                                provided together with the Thuban package.
                                </para>

                                <para>
                                For rpm exist some graphical user interfaces, notably
                                kpackage, GnoRPM and xrpm.
                                </para>

                                <para>
                                Make yourself familiar with one of the tools and apply it
                                to install the packages.
                                Note, that you need to be administrator (root) for the system
                                to do that.
                                </para>
                        </section>
                        <section><title>Build Binaries from Source Packages</title>
                                <para>
                                This section describes howto build RPM install-packages
                                from RPM source-packages.
                                This adapts and optimizes an install-package specifically
                                to your system.
                                This is especially helpful to resolve version conflicts of
                                dependent packages. Furthermore, install-packages for other
                                platforms (e.g. PowerPC) can be created.
                                </para>

                                <para>
                                Note: rpm must be at least version 4. Execute
                                <literal>rpm --version</literal> to find out about the version.
                                </para>

                                <para>
                                You need to do the following preparations to be able to
                                build the packages as a regular user. You should now
                                perform the package buling as root since this
                                might cause damage to your system.
                        <itemizedlist>
                        <listitem>
                                                <para>
                                                Create RPM directory structure:
                                                Choose a directory (e.g. $HOME/myrpm) and create the
                                                subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.
                                                A possible command sequence for this is:
                                                <programlisting>
                                                mkdir $HOME/freegisrpm
                                                cd $HOME/freegisrpm
                                                mkdir BUILD RPMS SOURCES SPECS SRPMS
                                                </programlisting>
                                                </para>
                                        </listitem>
                                        <listitem>
                                                <para>
                                                Set environment variable RPM_DIR:
                                                <programlisting>
                                                export RPM_DIR=$HOME/freegisrpm
                                                </programlisting>
                                                </para>
                                        </listitem>
                                        <listitem>
                                                <para>
                                                Create $HOME/.rpmmacros:
                                                This file sets general preferences and some
                                                specific settings for signing packages.
                                                If you don't have a GnuPG-key, you can skip
                                                the signature settings i.e. drop the last 4 lines.
                                                A signature becomes important when you want to
                                                give away packages to third parties.
                                                <programlisting>
<![CDATA[
%packager Name Lastname <[email protected]> 

%_topdir /home/mylogin/myrpm

%_signature gpg
%_gpg_name Name Lastname
%_pgp_path ~/.gnupg
%_pgpbin /usr/bin/gpg
]]>
                                                </programlisting>
                                                </para>
                                        </listitem>
                        </itemizedlist>

                                Now you can install any RPM source-package.
                                It's components are installed into the corresponding
                                subdirectories of your rpm-directory.
                                Essentially these are the sources (into directory SOURCES)
                                and the so-called spec-file which contains all build
                                instructions. The spec-file will go into the SPEC directory.
                                Example:
                                <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>
                                </para>

                                <para>
                                Create install-package:
                                Go to the directory with the spec-files and rebuild the
                                package:
                                <programlisting>
cd $HOME/mypm/SPECS
rpm -bb thuban.spec
                                </programlisting>
                                Next, you will find the newly created package in
                                $HOME/myrpm/RPMS/i386.
                                If you build the package for another architecture than
                                i386, then the name of the directory has a corresponding name.
                                </para>
                                <para>
                                For documentation of RPM, either type
                                <literal>man rpm</literal> or <literal>rpm --help</literal>.
                                This will provide you with information on the various command
                                line options of RPM.
                                For more information see the
                        <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
                                </para>
                        </section>
                </section> <!-- Intro - Installation - RPM-->

                <section><title>Win32 Systems</title>
                <para>
                        A common installation package of Thuban for Win32
                        systems is available from the Thuban website download
                        section. This installation package is configured for
                        displaying file based vector data (Shapefiles). For the
                        display of raster data or the connection to spatial
                        databases additional steps are needed.  
                </para>
                <para>
                        The required Python packages are listed and linked on
                        the download page as well.  If you don't have Python
                        installed already, download the packages for Python,
                        wxPython for Python and the SQLite Python Libraries as
                        well as the Thuban package. Install all four packages
                        in the order: Python, wxPython, SQLite, Thuban. Follow
                        the installation instructions provided by the seperate
                        setups. The Thuban installation package will add an
                        entry in the menu folder you configured.
                </para>
                <section><title>Raster Data: Installation of GDAL</title>
                <para>
                        Enabling the raster data features of Thuban is 
                        straight forward. For the examples we assume that 
                        Thuban has been installed under 
                        <literal>C:\Thuban</literal>:
                        <itemizedlist>
                        <listitem>
                        <para>
                        Download the zip-archive <ulink 
                        url="ftp://intevation.de/thuban/win2k/gdal-win2k.zip"
                        >gdal-win2k</ulink>. 
                        </para></listitem>
                        <listitem><para>Extract the archive (e.g. with 
                        <ulink 
                        url="http://www.info-zip.org/pub/infozip/WiZ.html"
                        >WiZ (InfoZip)</ulink>) into the 
                        <literal>C:\Thuban\Lib</literal>
                        directory of your Thuban installation.
                        </para>
                        </listitem>
                        <listitem>
                        <para>
                        Extent the <varname>PYTHONPATH</varname> 
                        environment variable (in your Windows Control Panel)
                        to make the new libraries available for Thuban.
                        <programlisting>
%PYTHONPATH%;C:\Thuban\Lib\gdal;C:\Thuban\Lib\gdal\pymod
                        </programlisting>
                        </para>
                        </listitem>
                        <listitem>
                        <para>
                        Extent also the <varname>PATH</varname>
                        environment variable accordingly:
                        <programlisting>
%PATH%;C:\Thuban\Lib\gdal
                        </programlisting>
                        </para>
                        </listitem>
                        </itemizedlist>
                        After this installation steps Thuban is ready to
                        display raster data (e.g. the
                        <literal>island.tif</literal> from the Iceland Demo
                        data set.
                </para>
                </section> <!-- Win32: GDAL-->

                <section><title>Working with PostGIS: Installation of PsycoPG</title>
                <para>
                        To access PostgreSQL/PostGIS spatial databases with
                        Thuban you have to install the PsycoPG package for 
                        Windows:
                        <itemizedlist>
                        <listitem>
                        <para> 
                        Download the zip-archive 
                        <ulink 
                                url="http://stickpeople.com/projects/python/win-psycopg/win-psycopg22.zip"
                        >win-psycopg22.zip</ulink>.
                        </para>
                        </listitem>
                        <listitem>
                        <para> 
                        Extract the zip-archive into a directory either already
                        in your <varname>PYTHONPATH</varname> or extent your 
                        <varname>PYTHONPATH</varname> variable to the directory 
                        you have extracted the archive to.
                        </para>
                        </listitem>
                        </itemizedlist>
                        For installation and maintenance of spatial databases
                        we refer to the  <ulink
                        url="http://postgis.refractions.net"
                        >PostGIS Homepage</ulink>.
                </para>
                </section> <!-- Win32: PsycoPG-->

                </section> <!-- Intro - Installation - Win32 -->
        </section>

        <section><title>Internationalisierung</title>
          <para>
          Thuban ist mit Unterstützung für Internaionalisierung realisiert.
          Bisher wurde Thuban in folgende Sprachen (neben der Basis Englisch) übersetzt:
          <itemizedlist>
                <listitem><para>Französisch</para></listitem>
                <listitem><para>Deutsch</para></listitem>
                <listitem><para>Italienisch</para></listitem>
                <listitem><para>Portugiesisch (Brasilien)</para></listitem>
                <listitem><para>Russisch</para></listitem>
                <listitem><para>Spanisch</para></listitem>
          </itemizedlist>
          </para>

        <para>
          Um die Internationalisierung auf POSIX Systemen (wie etwa GNU/Linux)
          zu verwenden, muss die Umgebungsvariable LC_ALL entsprechend
          gesetzt werden (z.B. LC_ALL=de_DE für Deutsch).
          Prüfen Sie die Dokumentation zu Ihrem System für Details
          und die unterstützten Einstellungen.
          Normalweise haben Sie Ihre Sprache bereits mit der Installation
          oder beim einloggen bereits vorausgewählt.
          Trotzdem kann auch dann noch durch Setzen von LC_ALL auf
          der Kommandozeile beim Aufruf von Thuban eine andere Sprache
          gesetzt werden:
        </para>
        <programlisting>
          LC_ALL=fr_FR thuban.py
        </programlisting>

        <para>
        MS Windows Benutzer müssen die Sprache über die Kontroll-Leiste einstellen
        welche grundsätzlich alle Anwendungen beeinflusst.
        </para>
        </section>

        <section><title>Das Hauptfenster</title>
          <para>
                <figure><title>Das Hauptfenster</title>
                  <mediaobject>
                        <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>
                        <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>
                  </mediaobject>
                </figure>
          </para>

          <para>
          Das Hauptfenster stellt die aktuelle Karte dar. Hier kann der
          Benutzer mit der Karte interagieren indem er die verschiednen
          Werkzeuge anwendet.
          </para>

      <para>
          Die Legende auf der linken Seite zeigt eine Liste der aktuellen
          Ebenen und alle dargestellten Klassifikations-Gruppen.
          Bei diesem Beispiel haben alle Geo-Objekte Ebenen eine voreingestellte
          Klassifizierung wie die jeweiligen Geo-Objekte in den einzelnen
          Ebenen gezeichnet werden sollen.
          Die Ebenen die weiter oben in der Liste dargestellt werden über
          die darunter aufgelisteten gezeichnet.
          Die Legende kann durch Anwahl des X in der oberen rechten Ecke
          geschlossen werden.
          Um die Legenden-Ansicht wieder zu öffnen, wählen Sie
          <menuchoice>
          <guimenu>Karte</guimenu>
          <guimenuitem>Legende</guimenuitem>
          </menuchoice>.
          Das Legenden-Fenster ist lösbar. Das bedeutet, dass sie vom Hauptfenster
          abgelöst und dann als eigenständiges Fenster
          positioniert werden kann. Dies wird durch den kleinen Schalter
          neben dem X gemacht. Erneutes Anwählen des Schalters läßt das
          Legenden-Fenster wieder in das Hauptfenster integrieren.
          </para>
          <para>
          Die Status-Leiste zeigt verschiedene Informationen jeweils
          abhängig vom Kontext. Wählt der Benutzer einen Menüpunkt
          dann wird in der Status-Leiste ein Hilfetext zu dem jeweiligen
          Menüpunkt angezeigt.
          Ist eines der Werkzeuge aktiviert, so wird in der Status-Leiste
          die Position angegeben über der der Maus-Cursor auf der Karte
          steht.
          </para>
          <para>
          Die Werkzeugleiste erlaubt direkten Zugriff auf häufig
          benötigte Werkzeuge.
          Schwebt der Maus-Zeiger über einem Knopf wird eine Kurz-Info
          über das jeweilige Werkzeug gegeben.
          Folgende Werzeuge stehen zur Verfügung: Hineinzoomen,
          Herauszoomen, Verschieben, Zur vollen Kartenausdehnung zoomen,
          Zur vollen Ebenenausdehnung zoomen, Zur vollen Auswahlausdehnung zoomen,
          Identifizieren, Labels hinzufügen/entfernen.
          Alle Werkzeuge werden in diesem Handbuch noch detaillierter beschrieben.
          </para>
        </section>

  </chapter>

  <chapter><title>Session Management</title>

        <section><title>Eine neue Session beginnen</title>
                <para>
                Eine neue Session wird gestartet über
                <menuchoice>
                <guimenu>Datei</guimenu>
                <guimenuitem>Neue Session</guimenuitem>
                </menuchoice>. 
                Falls bereits eine Session geladen ist und seit der letzten
                Speicherung verändert wurde, so wird nun nachgefragt, ob
                diese Session zunächst gespeichert werden soll.
                Eine neue Session besteht aus einer leeren Karte
                ohne Ebenen, Tabellen und Projektion.
                </para>
        </section>

        <section><title>Eine Session öffnen</title>
                <para>
                Eine Session kann geöffnet werden über
                <menuchoice>
                <guimenu>Datei</guimenu>
                <guimenuitem>Öffne Session</guimenuitem>
                </menuchoice>.
                Es wird ein Dateiauswahl-Dialog geöffnet um eine
                Thuban Session Datei auszuwählen. Diese Dateien enden
                auf <varname>.thuban</varname>. Wird eine Datei ausgewählt und mit
                <guibutton>OK</guibutton> bestätigt, so wird die entsprechende
                Session in Thuban geladen.

                Ist bereits eine Session geladen und seit dem letzten Speichern modifiziert
                worden, so wird nachgefragt, ob zunächst die alte Session gespeichert werden
                soll.
                </para>
        </section>

        <section><title>Eine Session speichern</title>
                <para>
                Eine Session kann gepsiechert werden über
                <menuchoice>
                <guimenu>Datei</guimenu>
                <guimenuitem>Session Speichern</guimenuitem>
                </menuchoice>.
                Handelt es sich bei der aktuellen Session nicht um eine
                neue und ungespeicherte, so wird die entsprechende Datei
                mit den Daten der aktuellen Session überschrieben.
                Im Falle einer neuen und noch nicht gespeicherten Session
                wird ein Dateiauswahl-Dialog geöffnet um einen Namen
                für die zu speicherende Session auszuwählen.
                Thuban Session Dateien sollten mit der Endung
                <varname>.thuban</varname> versehen werden.
                Existiert bereits eine Datei mit dem gleichen Namen
                wird der Benutzer gefragt ob diese überschrieben
                oder ein neuer Name gewählt werden soll.
                </para>
        </section>

        <section><title>Der Session Info-Baum</title>
                <para>
                <figure>
                <title>Session Info-Baum</title>
                <mediaobject>
                <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>
                <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>
                </mediaobject>
                </figure>
                </para>
                <para>
                Der Session Info-Baum ist hauptsächlich für Software-Entwickler gedacht
                die an Thuban arbeiten.
                Er stellt eine Reihe von internen Daten zur Session, der Karte, den
                Ebenen usw. dar. Er wird geöffnet über
                <menuchoice>
                <guimenu>Datei</guimenu>
                <guimenuitem>Session Baum</guimenuitem>
                </menuchoice>. 
                </para>
        </section>
  </chapter>

  <chapter><title>Karten Management</title>
    <para>
        Die Karte besteht aus eine Anzahl Ebenen wobei jede Ebene einen
        Datensatz mit bestimtem Typ repräsentiert. Mit Interaktion auf der
        Karte kann ein Benutzer die Daten visuell erforschen.
    </para>
    <para>
        Die Karte kann einen Namen haben der dann in der Kopfzeile des
        Thuban Fensters auftaucht. Der Kartenname kann geändert werden
        über
    <menuchoice>
    <guimenu>Karte</guimenu>
    <guimenuitem>Umbennen</guimenuitem>
    </menuchoice>.
    </para>
    <para>
    <inlinemediaobject>
    <imageobject> 
    <imagedata fileref="../images/3_rename_map.png" format="PNG" scale="&imgscale;"/> 
    </imageobject> 
    <imageobject> 
    <imagedata fileref="./images/3_rename_map.eps" format="EPS" scale="&imgscale;"/> 
    </imageobject>
    <textobject> <phrase>Karte umbennen</phrase> </textobject>
    </inlinemediaobject>
    </para>

        <section><title>Hinzufügen und Entfernen von Ebenen</title>
        <para>
        Es gibt drei Typen von Ebenen aus denen eine Karte besteht:
        Shape Ebene, Datenbank Ebene und Bildebene.
        Shape Ebenen sind im Shapefile Format gespeichert welches
        weit verbreitet für die Speicherung von geografischen Objekten
        genutzt wird.
        Die Dateien haben die Endung ``.shp''. Mit der eigentlichen Shape
        Datei ist eine Datenbank Datei welche die Attribut-Daten zu dem
        Shapefile enthält. Diese Datenbank Datei verwendet das dBase Format
        und hat die Endung ``.dbf''. Beide Dateien müssen den selben
        Basisnamen haben. So gehören zum Beispiel die Dateien
        strassen.shp und strassen.dbf zusammen.
        </para>
        <itemizedlist>
        <listitem>
        <para>
                Shape Ebenen können zur Karte hinzugefügt werden mit
        <menuchoice>
        <guimenu>Karte</guimenu>
        <guimenuitem>Ebene hinzufügen</guimenuitem>
        </menuchoice>.
                Zunächst werden im Dateiauswahl Dialog nur die ``.shp'' Dateien
                angezeigt, was für die Auswahl vollkommen ausreicht.
                Falls Sie aber auf Ansicht aller Dateien umschalten, und dann
                einer der assoziierten Dateien (z.B. mit der Endung ``.dbf'')
                auswählen, so verwendet Thuban den Basisnamen um die entsprechende
                Shape Datei zu laden,
                </para>
                <para>
                Der Dateidialog für Shape Dateien erlaubt es auch, viele
                Dateien gleichzeitig auszuwählen. Verwenden Sie dafür
                die Umschalt-Taste gleichzeitig mit der linken Maustaste um
                die Auswahl zu erweitern.
                </para>
        </listitem>

        <listitem>
                <para>Datenbankebenen können zu Karte hinzugefügt werden mit
        <menuchoice>
        <guimenu>Karte</guimenu>
        <guimenuitem>Datenbankebene hinzufügen</guimenuitem>
        </menuchoice>.
        Es wird ein Dialog mit zwei Listen geöffnet.
        Die linke Liste zeigt alle derzeit offenen Datenbankverbindungen dieser
        Session an. Eine Liste der verfügbaren Ebenen aus einer Datenbankverbindung
        wird steht auf der rechten Seite. Aus dieser Liste können Sie eine
        beliebige Ebene zum Öffnen auswählen. Der Dialog wird dabach
        automatisch beendet.
        </para>
        <para>
        Siehe auch Anhang ``Mit PostGIS arbeiten'' für weitere Details.
        </para>
        </listitem>

        <listitem>
        <para>
        Bildebenen können zur Karte hinzugefügt werden mit
        <menuchoice>
        <guimenu>Karte</guimenu>
        <guimenuitem>Bildebene hinzufügen</guimenuitem>
        </menuchoice>.
                Es ist wichtig, dass eine korrekte Bilddatei ausgewählt für
                die auch geographische Daten (Projektions) vorliegen.
                Diese Daten können in die Bilddatei eingebettet sein oder
                als separate Datei vorliegen. Können diese Daten nicht
                gefunden werden, so wird Thuban einen Fehler melden.
        </para>
        </listitem>
        </itemizedlist>
        </section>

        <section><title>Navigation</title>
        <para>
                Die Karte kann erforscht werden indem die Navigationswerkzeuge
                aus der Werkzeugleiste oder über das Menü
        <menuchoice><guimenu>Karte</guimenu></menuchoice> ausgewählt werden.
        </para>
        <itemizedlist>
        <listitem>
        <para>
        Das ZoomIn Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_2_zoomin.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_2_zoomin.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>ZoomIn Werkzeug</phrase> </textobject>
        </inlinemediaobject>
                vergrößert einen Bereich aus der Karte. Ein einmaliges Klicken auf
                die Karte vergrößert die Karte um das Doppelte und zentriert auf den
                angewählten Punkt. Klicken und Ziehen selektiert einen Bereich
                der dann so vergrößert wird, dass er das Fenster ausfüllt.
        </para>
        </listitem>
        <listitem>
        <para>
        Das ZoomOut Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_2_zoomout.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_2_zoomout.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>ZoomOut Werkzeug</phrase> </textobject>
        </inlinemediaobject>
                verkleinert die Karte, so dass ein größerer Bereich zu sehen ist.
                Ein einzelnen Klick verkleinert die Karte um Faktor 2.
                Klicken und Ziehen selektiert einen Bereich in den die gesamte sichtbare
                Karte im Fenster hineinverkleinert wird.
        </para>
        </listitem>
        <listitem>
        <para>
        Das Verschieben Werkzeug 
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_2_pan.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_2_pan.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Verschieben Werkzeug</phrase> </textobject>
        </inlinemediaobject>
        gestattet es dem Benutzer die Karte durch klicken und
        ziehen mit gedrückter Maustaste zu verschieben.
        </para>
        </listitem>
        <listitem>
        <para>
        Das Volle Ausdehnung Werkzeug 
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_2_fullextent.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_2_fullextent.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Volle Ausdehnung Werkzeug</phrase> </textobject>
        </inlinemediaobject>
        skaliert die Zoom-Stufe so, dass die gesamte sichtbare Karte im
        Fenster dargestellt wird.
        </para>
        </listitem>
        <listitem>
        <para>
        Das Voll Ebenen-Ausdehnung Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_2_fulllayerextent.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_2_fulllayerextent.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Volle Ebenen-Ausdehnung Werkzeug</phrase> </textobject>
        </inlinemediaobject>
        skaliert die Zoom-Stufe so, dass die akutelle Ebene vollständig
        im Fenster dargestellt wird. Ist keine Ebene ausgewählt, so
        ist dieser Knopf ausgegraut und damit nicht verfügbar.
        </para>
        </listitem>
        <listitem>
        <para>
        Das Volle Shape-Ausdehnung Werkzeug 
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_2_fullshapeextent.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_2_fullshapeextent.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Volle Shape-Ausdehnung Werkzeug</phrase> </textobject>
        </inlinemediaobject>
        skaliert die Zoom-Stufe so, dass die aktuell ausgewählten Shapes
        vollständig in das Fenster eingepasst sind.
        Handelt es sich bei der Auswahl nur um einen einzelnen Punkt
        so wird dieser zentriert dargestellt und bis zu einem gewissen
        grad gezoomed.
        Ist kein Shape selektiert, so ist dieser Knopf ausgegraut und damit
        nicht verfügbar.
        Dieses Werkzeug ist besonders für den Fall hilfreich wenn man Objekte
        in einer Ebenen-Tabelle auswählt und sie auf der Karte schnell
        anspringen machen möchte.
        </para>
        </listitem>
        </itemizedlist>
        </section>

        <section><title>Objekt Identifikation</title>
        <para>
        Objekte auf der Karte können identifiziert werden über das Identifikations-Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_3_identify.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_3_identify.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Identifikations-Werkzeug</phrase> </textobject>
        </inlinemediaobject>.
        Klickt man auf ein Objekt wird es selektiert und es wird ein
        Dialog geöffnet der dann alle Tabellenattribute für das Objekt
        anzeigt. Jegliche vorherige Selektion wird gelöscht.
        Objekte auf der Karte sind typischerweise Shapes und dieses
        Dokument wird sich häufiger auf Objekte als Shapes beziehen. 
        </para>
        </section>

        <section><title>Objekt mit Label versehen</title>
        <para>
        Objekte können über das Label-Werkzeug mit Labeln versehen
        werden
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_3_label.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_3_label.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Label Werkzeug</phrase> </textobject>
        </inlinemediaobject>.
        Klickt man auf ein Objekt, so wird dies selektiert und es wird ein
        Dialog geöffnet welcher dessen Attribute darstellt.
        Eins der Attribute kann nun als Label für das Objekt auf der Karte
        ausgewählt werden. Der Label wird dann mittif auf dem Shape
        plaziert.
        Klickt man auf ein Objekt welches bereits ein
        Label hat, so wird dieser nun entfernt.
        </para>
        </section>

        <section><title>Die Legende</title>
        <para>
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_5_legend.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_5_legend.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Legende</phrase> </textobject>
        </inlinemediaobject>
        </para>
        <para>
        Die Legende bietet eine Übersicht über die Ebenen der Karte.
        Ebenen die weiter oben in der Legende stehen sind
        ``näher'' zum Benutzer.
        Falls eine Ebene Klassifizierung unterstützt (derzeit haben
        nur Shape-Ebenen haben diese Eigenschaft) so werden die Gruppen
        der Klassifikation für jede Ebene dargestellt. 
        Die Eigenschaften für jede Gruppe werden auch als kleine Grafiken
        dargestellt. Polygon-Ebenen werden als Rechtecke dargestellt,
        Linoen als Kurven und Punkte als Kreise.
        </para>
        <para>
        Am oberen Rand der Legende ist eine Werkzeugleiste welche einen schnellen
        Zugriff auf einige der Komanndos des Menüs
        <menuchoice><guimenu>Map</guimenu></menuchoice>
        gestattet. 
        </para>

        <itemizedlist>
        <listitem>
        <para>
        Das Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_5_totop.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_5_totop.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Auf die oberste Ebene bewegen</phrase> </textobject>
        </inlinemediaobject> bewegt die selektierte Ebene auf der Karte
        nach ganz oben.
        </para>
        </listitem>
        <listitem>

        <para>
        Das Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_5_moveup.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_5_moveup.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Eine Ebene nach oben bewegen</phrase> </textobject>
        </inlinemediaobject> bewegt die selektierte Ebene um einen
        Schritt nach oben.
        </para>
        </listitem>
        <listitem>

        <para>
        Das Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_5_movedown.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_5_movedown.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Eine Ebene nach unten bewegen</phrase> </textobject>
        </inlinemediaobject> bewegt die selektierte Ebene um einen Schritt
        nach unten.
        </para>

        </listitem>
        <listitem>
        <para>
        Das Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_5_tobottom.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_5_tobottom.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Auf die unterste Ebene bewegen</phrase> </textobject>
        </inlinemediaobject> bewegt die selektierte Ebene auf
        der Karte nach ganz unten.
        </para>

        </listitem>
        <listitem>
        <para>
        Das Sichtbarkeits-Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_5_visible.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_5_visible.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Sichtbar</phrase> </textobject>
        </inlinemediaobject> sorgt dafür, dass eine vorher nicht sichtbare
        Ebene nun wieder in der Karte dargestellt wird.
        </para>

        </listitem>
        <listitem>
        <para>
        Das Unsichtbar-Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_5_invisible.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_5_invisible.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Unsichtbar</phrase> </textobject>
        </inlinemediaobject> versteckt die aktuell
        selektierte Ebene auf der Karte.
        </para>

        </listitem>
        <listitem>
        <para>
        Das Eigenschaften-Werkzeug
        <inlinemediaobject>
        <imageobject> 
        <imagedata fileref="../images/3_5_props.png" format="PNG" scale="&imgscale;"/> 
        </imageobject> 
        <imageobject> 
        <imagedata fileref="./images/3_5_props.eps" format="EPS" scale="&imgscale;"/> 
        </imageobject>
        <textobject> <phrase>Eigenschaften</phrase> </textobject>
        </inlinemediaobject> startet den Eigenschaften-Dialog für die
        aktuelle Ebene.
        Ein Doppel-Klick auf eine Ebene startet ebenfalls diesen Dialog.
        </para>
        </listitem>
        </itemizedlist>

        <para>
        Die am häufigsten benötigten Aktionen zu den Ebenen sind
        über ein Popup-Menü erreichbar. Es erscheint wenn Sie
        mit der Maus über einer Ebene stehen und die rechten
        Maustaste betätigen.
        </para>
        
        <para>
        <figure>
        <title>Popup Menü für Ebenen</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>

        <para>
        Am unteren Rand der Legende befindet sich
        die Maßstabsanzeige. Sie ist immer dann zu sehen wenn
        für die Karte eine Projektion gesetzt ist und mindestens
        eine Ebene vorhanden ist.
        </para>
        </section>

        <section><title>Exportieren</title>
        <para>
        Auf dem Betriebssystem MS Windows können Karten im Enhanced Metafile Format
        (<varname>.wmf</varname>)
        über 
        <menuchoice>
        <guimenu>Karte</guimenu>
        <guimenuitem>Export</guimenuitem>
        </menuchoice> erstellt werden um sie in Reports,
        Präsentationen oder weitergehenden Bearbeitungen zu verwenden.
        Die aktuelle Kartenansicht, Legende und, falls verfügbar,
        Maßstabsanzeige werden dafür exportiert.
        Auf anderen Plattformen steht dies nicht zur
        Verfügung.
        Wählt man diesen Menüpunkt an so wird ein
        Dateiauswahldialog für die zu erstellende Exportdatei
        geöffnet.
        </para>
        </section>

        <section><title>Drucken</title>
        <para>
        Eine Karte wird über 
        <menuchoice>
        <guimenu>Karte</guimenu>
        <guimenuitem>Drucken</guimenuitem>
        </menuchoice> ausgedruckt. Die aktuelle Kartenansicht, Legende und,
        falls vorhanden, die Maßstabsanzeige werden gedruckt.
        Es wird ein Standard-Druckdialog geöffnet der die Konfiguration
        des Druckers gestattet. Dieser Druckdialog unterscheidet sich je
        nachdem auf welcher Plattform Thuban ausgeführt wird.
        </para>
        </section>

  </chapter>

  <chapter><title>Ebenen Management</title>
    <para>
    </para>

        <section><title>Typen von Ebenen</title>
        <para>
        Thuban unterstützt 3 Typen von Ebenen:
        Shape-Ebenen, Datenbank-Ebenen und Bild-Ebenen.
        Shape-Ebenen bestehen aus vektor-basierten Objekten mit
        geo-referenzierten Koordinaten.
        Es werden drei Shape-Typen unterstützt:
        Polygone, Linien und Punkte.
        Datenbank-Ebenen sind den Shape-Ebenen ähnlich und unterscheiden
        sich darin, dass die Daten aus einer Datenbank geholt werden
        anstatt direkt vom Dateisystem.
        Bild-Ebenen können im Prinzip alle von GDAL unterstützten Dateiformate
        sein. GDAL ist eine externe Bibliothek und steht für
        Geo-spatial Data Abstraction Library.
        Das Bild muss Informationen zu seiner geographische Lage und
        Ausdenung beinhalten, entweder direkt in die Datei eingebettet
        oder als separate Datei im selben Verzeichnis wie die Bild-Datei.
        GeoTIFF Dateien funktionieren sehr gut mit Thuban und sind
        speziell als Bildebenen für Bild-Ebenen bei Geographischen
        Informationssystemen geeignet.
        </para>
        <para>
        All actions in the
        <menuchoice>
        <guimenu>Layer</guimenu>
        </menuchoice> menu act on the currently selected layer in the legend.
        </para>
        </section>

        <section><title>Properties</title>
        <para>
        To view the properties for a layer it must first be selected in the
        legend. The menu option
        <menuchoice>
        <guimenu>Layer</guimenu>
        <guimenuitem>Properties</guimenuitem>
        </menuchoice> opens a dialog that displays a layer's properties.
        All layers have a title which can be modified in the text field
        provided. The type of layer is also shows. If the type is a type
        of shape (polygon, arc, point) the classification table will be
        shown. Image layers have no other properties other than title 
        and type.
        </para>
        <para>
        <figure>
        <title>Properties Window</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        <para>
        <figure>
        <title>Properties Window</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        </section>

        <section><title>Visibility</title>
        <para>
        Sometimes it is not desirable to view all layers at the same time.
        Some layers may take a long time to draw and so while navigating
        around the map the user may not want to wait for the map to redraw
        all the layers each time the map is changed. Each layer can be 
        independently turned on or off using the 
        <menuchoice>
        <guimenu>Layer</guimenu>
        <guimenuitem>Show</guimenuitem>
        </menuchoice>
        or
        <menuchoice>
        <guimenu>Layer</guimenu>
        <guimenuitem>Hide</guimenuitem>
        </menuchoice> options respectively.
        </para>
        </section>

        <section><title>Duplication</title>
        <para>
        Layers and all their properties, including classifications, can
        be duplicated using 
        <menuchoice>
        <guimenu>Layer</guimenu>
        <guimenuitem>Duplicate</guimenuitem>
        </menuchoice>. Duplicating a layer is useful if the user wishes
        to model a layer in several different ways. Even though the layers
        overlap, by carefully selecting the shape properties it is possible
        to display several pieces of information at once. For example, one
        copy of a roads layer may be classified on a length property and
        another copy may be classified on a type property. If the length
        property was expressed with color and the type property expressed
        with line thickness then it would be possible to view both
        classifications by placing the type property copy over the 
        length property copy.
        </para>
        </section>

  </chapter>

  <chapter><title>Layer Classifications</title>
    <para>
    A layer classification is a way of assigning drawing properties to
    groups of shapes based on attributes stored in the layer's table. 
    Only layer's with shapes can have a classification; image layers
    cannot be classified.
    </para>
    <para>
    A classification consists of a number of groups, each group
    having a value or range of values to match against, and symbol 
    properties which control how a shape is drawn on the map. The user
    selects which field in the table is used by the classification and
    when the map is drawn the value for that field for each shape is
    compared with each group's value. The properties of the first group 
    to match are used to draw the shape. This allows the user to get a 
    visual impression of not only how the data is laid out but also what 
    kind of data lies where.
    </para>
    <para>
    A layer always has a classification. When a new layer is added to the
    map, a default classification is created with the DEFAULT group. This
    group cannot be removed but can be hidden (see below). Every shape in the 
    layer, regardless of its attributes, will match this group if no other 
    group matches. 
    </para>

        <section><title>Editing Classifications</title>
        <para>
        A layer's classification can be modified under the properties dialog 
        (<menuchoice>
        <guimenu>Layer</guimenu>
        <guimenuitem>Properties</guimenuitem>
        </menuchoice>). The layer's classification field can be set to None, 
        which simply assigns a DEFAULT group to the classification. No new 
        groups can be added to the classification if the field is None.
        The user must first select a field to classify on. New groups can
        be added to the classification with the <guibutton>Add</guibutton>
        button. 
        </para>
        <para>
        To apply the changes to the map the user can click
        either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
        <guibutton>Try</guibutton> will not close the dialog box, allowing
        the user to see how the classification changes the map. 
        <guibutton>Revert</guibutton> will undo the last classification applied
        to the map. <guibutton>OK</guibutton> will commit the changes and
        close the dialog. The user will be unable to undo the changes.
        <guibutton>Close</guibutton> simply closes the dialog box. If any
        changes have not been applied with <guibutton>Try</guibutton> the 
        changes will not be applied to the map.
        </para>
        <para>
        <figure>
        <title>Properties Window</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        <para>
        The order of the groups in the classification is significant
        except for the DEFAULT group, which remains at the top. When shapes
        are matched against groups the matching begins at the first group
        after the DEFAULT group so that groups higher in the list will 
        be checked first. Matching for a 
        given shape will stop at the first group that matches. The user can
        use <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton>
        to change the order of the groups. The DEFAULT group will always 
        match a shape that hasn't matched another group.
        </para>
            <section><title>Visible</title>
            <para>
            The Visible column has check-boxes that determine whether a
            classification group will be displayed in the legend. This is
            useful if the user knows that the groups completely cover
            the data set and don't want the DEFAULT group to be displayed
            in the legend and on a printout.
            </para>
        </section>
            <section><title>Symbols</title>
            <para>
            Each type of shape has its own type of symbol. Thuban supports three
            types of shapes: polygons, lines, and points. Polygons and points 
            have outline and fill color, while lines have only line color. Each 
            group has associated symbol properties. To edit the symbol 
            properties for a group the user can double click on the Symbol 
            column or select a group and click the 
            <guibutton>Edit Symbol</guibutton> button.
            </para>
            </section>
        <section><title>Value</title>
            <para>
            The Value column of the classification table is the value that will
            be matched when the map is being drawn. The type of data that can
            entered into this field depends on the type of data of the 
            classification field. 
            </para>
            <para>
            If the field is of type Text, anything entered
            into the field is valid. The text will be compared literally to the
            value of the shape attribute, including case sensitivity. 
            If the type is Integer, then any valid integer may be entered. In 
            addition, with special syntax, a range of values can be entered.
            A range from <varname>start</varname> to <varname>end</varname> 
            inclusive is specified like this: <literal>[start;end]</literal>.
            The exclusive range is specified like this: 
            <literal>]start;end[</literal>. Ranges can include infinity like
            this: <literal>[-oo;oo]</literal>. Field types can also be of type
            Decimal. They represent any rational number and can be used in 
            ranges as well.
            </para>
            </section>
            <section><title>Label</title>
            <para>
            By default, the text that is displayed for a group in the legend
            is the value for that group. The label can substitute a more
            descriptive term in the legend.
            </para>
        </section>
        </section>

        <section><title>Generating Classes</title>
        <para>
        <figure>
        <title>Generate Class</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        <para>
        Creating a classification by hand can be tedious. 
        Thuban, therefore, provides a means of generating an entire
        classification at once while still giving the user control over
        how it appears. Clicking <guibutton>Generate Class</guibutton>
        opens the <varname>Generate Classification</varname> dialog.
        Under the <varname>Generate</varname> pull down there are at most
        three different ways to generate classifications: 
        Unique Values, Uniform Distribution, and Quantiles. Some options 
        may not be available if the data type for the field does not
        support them. For instance, <varname>Uniform Distribution</varname>
        doesn't make sense for a Text field.
        </para>
        <para>
        For every way of generating a classification, a color scheme must
        be selected. Thuban provides several different color schemes that
        affect how the group properties change over the classification.
        It may be desirable that only certain properties change over the
        classification. If the shape type is a polygon or a point then
        the <guibutton>Fix Border Color</guibutton> option will be available.
        This allows the user to select a border color for all classification
        groups.
        It is also possible to create a custom color scheme. Selecting
        this option will display two symbols: the one of the left has the
        properties of the first group and the one on the right has the 
        properties of the last group. Thuban will interpolate between these
        two properties to generate the other groups.
        <figure>
        <title>Custom Color Scheme</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        <para>
        The Unique Values option lets the user select specific values that
        appear in the table. Clicking <guibutton>Retrieve From Table</guibutton>
        searches the table for all unique values and displays them in the
        list on the left. Items can be selected and moved to the list on the
        right. Each list can be sorted or reversed for easier searching.
        The classification that is generated will be in the same order as
        the list on the right.
        <figure>
        <title>Unique Values</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        <para>
        The Uniform Distribution option creates a user specified number of
        groups of ranges such that each range covers equal intervals. The
        minimum and maximum values can automatically be retrieved from the
        table by clicking <guibutton>Retrieve From Table</guibutton>. The
        stepping is how large each interval is. Adjusting this value will
        automatically recalculate how many groups is appropriate.
        <figure>
        <title>Uniform Distribution</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        <para>
        The Quantiles option generates ranges based on the number of items
        in the table. For example, by specifying five groups Thuban will
        generate five groups with appropriate ranges such that 20% of the table
        data is in each group. If it is impossible to generate exact
        groupings, Thuban will issue a warning but allow the user to continue.
        <figure>
        <title>Quantiles</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        </section>
  </chapter>

  <chapter><title>Projection Management</title>
    <para>
    Projections control how the geographic data is displayed on the screen.
    If multiple layers are loaded into Thuban where the geographic data
    is in a different projection system, then the user must specify a
    projection for each layer. The user must also tell Thuban which
    projection the map is in. This can be the same as the layers or a different
    projection in which case the layers are reprojected into that space.
    The map projection can be set using 
    <menuchoice>
    <guimenu>Map</guimenu>
    <guimenuitem>Projection</guimenuitem>
    </menuchoice> and the layer projection can be set using 
    <menuchoice>
    <guimenu>Layer</guimenu>
    <guimenuitem>Projection</guimenuitem>
    </menuchoice>.
    <figure>
    <title>Projection Window</title>
    <mediaobject>
    <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>
    <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>
    </mediaobject>
    </figure>
    </para>
    <para>
    Thuban is distributed with a sample collection of projections and the 
    set of coordinate systems as used by the EPSG
    (European Petroleum Survey Group). This quite large set is only displayed
    if activated by the according checkbox. The set falls into two parts:
    deprecated lists all projections which are no longer part of the 
    EPSG data base.
    </para>
    <para>
         The
    user can create new projections and make them available to all
    future Thuban sessions. They may also be exported and imported so
    that custom projections can be distributed.
    </para>
        <section><title>Selecting a Projection</title>
        <para>
        The available projections are listed on the left. If the layer
        or map already has a projection it will initially be highlighted
        and will end with <varname>(current)</varname>. Selecting 
        <varname>&lt;None&gt;</varname> will cause Thuban to use the data as
        it appears in the source file and will not use a projection.
        </para>
    </section>
        <section><title>Editing a Projection</title>
        <para>
        Whenever a projection is selected from the list its properties
        are displayed on the right. These properties can be changed
        and the changes saved to the selected projection using
        <guibutton>Update</guibutton>. Only a projection that comes
        from a file can be updated, so if the current layer's projection
        is selected, <guibutton>Update</guibutton> will be disabled. 
        <guibutton>Add to List</guibutton> adds the projection to the 
        list of available projections as a new entry, and thus makes it 
        available to future Thuban sessions. Clicking <guibutton>New</guibutton>
        will create an entirely new, empty projection. The 
        <guibutton>Remove</guibutton> button will permanently remove a 
        projection from the list of available projections.
        </para>
        <para>
        To apply the selected projection to the map the user can click
        either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
        <guibutton>Try</guibutton> will not close the dialog box, allowing
        the user to see how the projeciton changes the map. 
        <guibutton>Revert</guibutton> will undo the last projection applied
        to the map. <guibutton>OK</guibutton> will commit the changes and
        close the dialog. The user will be unable to undo the changes.
        <guibutton>Close</guibutton> simply closes the dialog box. If no
        selection has been applied with <guibutton>Try</guibutton> the 
        selection will not be applied to the map.
        </para>
    </section>
        <section><title>Importing/Exporting Projections</title>
        <para>
        The projections that appear in the list of available projections
        can be exported to another file that the user chooses. By selecting
        one or more projections and clicking <guibutton>Export</guibutton>
        the user will be able to select a file in which to store those 
        projections.
        The file can then be distributed to other Thuban users. To import
        a projection file the user can click <guibutton>Import</guibutton>.
        The imported projections are added to the list and are then available
        to the current session and any future Thuban sessions.
        </para>
    </section>
  </chapter>

  <chapter><title>Tabellen-Management</title>
    <para>
    Thuban unterscheidet zwei unterschiedliche Tabellen-Typen:
    Attributtabellen (welche zu einer Ebene gehört) sowie normale
    Datentabellen.
    Beide bieten die gleiche allgemeine Funktionalität mit dem
    einzigen Unterschied, dass Aktionen auf einer Attributtabelle
    die Kartendarstellung ändern können.
    </para>

    <section><title>Tabellen-Ansicht</title>
        <para>
        <figure>
        <title>Tabellen-Ansicht</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        </para>
        <para>
        Thuban stellt einen Standard-Dialog für die Anzeige einer Tabelle
        zur Verfügung. Diese Aansicht hat 5 Elemente:Titel, Selektion,
        das Tabellenraster, Exportfunktionen und die Statuszeile.
        </para>
        <para>
        Die Titelzeile identifiziert die Tabelle mit ihrem Namen.
        </para>
        <para>
        Die Selektionsbox erlaubt es dem Benutzer einfache Analysen auf den Daten
        durch Vergleiche durchzuführen: Die erste Auswahl ist ein Feldbezeichner
        der Tabelle, die zweite Auswahl bestimmt den Typ des Vergleichs.
        Die dritte Auswahl kann entweder ein bestimmter Wert (interpretiert
        als Zahl oder als Zeichenkette abhängig vom Typ des ersten Feldes)
        oder ein zweiter Feldbezeichner sein.
        D.h. man kann Analysen durchführen wie alle Einträge auswählen bei
        denen <literal>bevoelkerung > 10000</literal> oder 
        <literal>pkw_pro_einwohner < fahrraeder_pro_einwohner</literal> 
        (beachten Sie, dass die Namen nur exemplarisch sind, dBase Dateien
        erlauben nur Bezeichner mit einer maximalen Länge von 11 Zeichen).
      
        Selektionen können kombiniert werden. Entweder bezieht sich
        die Selektion auf die zuvor selektierten Einträge oder man kann
        eine bestehende Selektion erweitern. Voreingestellt ist
        einersetzen der bisherigen Selektion.
        </para>
        <para>
        Das Tabellenraster zeigt den Inhalt der Tabelle (pro Zeile ein Eintrag).
        Selektionen sind hervorgehoben. Die Grösse der Zeiken und Spalten kann
        verändert werden.
        </para>
        <para>
        Der Inhalt einer Tabelle kann in eine Datei exportiert werden,
        entweder im dBase format (DBF) oder als kommaseparierte Werte
        (CSV). Der.
        <guibutton>Export</guibutton> Knopf startet einen Dialog
        zur Angabe des Pfades und des Namens der Datei.
        Der Export-Typ wird durch die Namenserwiterung spezifiziert
        (entweder .dbf oder .csv).

        Der Knopf <guibutton>Exportiere Selektion</guibutton> funktioniert
        ähnlich, exportiert aber nur die aktuelle Selektion.

        Der <guibutton>Schliessen</guibutton> Knopf schliesst das
        Fenster mit der Tabellenansicht. Dies ist nicht zu verwechseln mit
        dem Menüpunkt
        <menuchoice>
        <guimenu>Tabelle</guimenu>
        <guimenuitem>Schliessen</guimenuitem>
        </menuchoice> welcher die Tabelle aus Thuban entfernt.
        </para>
        <para>
        Die Statuszeile zeigt einige statistische Informationen zu
        der Tabelle sowie zu Selektionsergebnisse an.
        </para>
    </section>

    <section><title>Allgemeine Funktionalität (Menü Tabelle)</title>
        <para>
        Die allgemeinen Funktionen wirken sich auf alle geöffneten Tabellen
        aus. Attributtabellen werden wie normale Tabellen behandelt (mit der
        Ausnahme dass diese nicht geschlossen werden können).
        </para>
        <section><title>Öffnen</title>
            <para>
            Der Menüpunkt 
            <menuchoice>
            <guimenu>Tabelle</guimenu>
            <guimenuitem>Öffnen</guimenuitem>
            </menuchoice>
            startet einen Dateiselektionsdialog für die Auswahl 
            einer dBase-Datei. Diese wird als nur-lesbar in Thuban
            geladen.
            Mit <guibutton>OK</guibutton> wird die ausgewählte Datei
            geladen und eine entsprechende Tabellenansicht geöffnet.
            </para>
        </section>

        <section><title>Schliessen</title>
            <para>
            Der Menüpunkt 
            <menuchoice>
            <guimenu>Tabelle</guimenu>
            <guimenuitem>Schliessen</guimenuitem>
            </menuchoice>
            startet einen Dialog welcher alle derzeit geöffneten Datentabellen
            (die geladen wurden über 
            <menuchoice>
            <guimenu>Tabelle</guimenu>
            <guimenuitem>Öffnen</guimenuitem>
            </menuchoice>).
            Die gewählten Tabellen werden nach Bestätigung aus Thuban
            entfernt.
            Da die Tabellen als nur-lesend geöffnet wurden, wird
            der Inhalt der Tabellen nicht verändert.

            Sämtliche offenen Tabellenansichten für diese
            Tabellen werden ebenfalls geschlossen.

            Tabellen die bei Verknüpfungen verwendet werden
            können nicht geschlossen werden.
            </para>
        </section>

        <section><title>Umbenennen</title>
            <para>
            <menuchoice>
            <guimenu>Tabelle</guimenu>
            <guimenuitem>Umbenennen</guimenuitem>
            </menuchoice> ändert den Tabellentitel.
            </para>
        </section>

        <section><title>Anzeigen</title>
            <para>
            Der Menüpunkt
            <menuchoice>
            <guimenu>Tabelle</guimenu>
            <guimenuitem>Anzeigen</guimenuitem>
            </menuchoice> 
            öffnet einen Dialog mit der Liste der verfügbaren
            Tabellen (explizit geladene Tabellen, Attributtabellen,
            Ergebnisse aus Verknüpfungen).
            Die ausgewählten Tabellen werden nach der
            Bestätigung mit
            <guibutton>OK</guibutton> in Tabellenansichten dargestellt.
            </para>
        </section>

        <section><title>Verbinden</title>
            <para>
            <figure>
            <title>Verbinde Tabellen</title>
            <mediaobject>
            <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>
            <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>
            </mediaobject>
            </figure>
            </para>
            <para>
            Der Menüpunkt
            <menuchoice>
            <guimenu>Tabelle</guimenu>
            <guimenuitem>Verbinden</guimenuitem>
            </menuchoice> 
            startet einen Dialog für die Angabe der beiden Tabellen die
            verbunden werdn sollen. Das Ergebnis der Verbindung ist eine
            neue Tabelle mit der Bezeichnung 
            'Join of "linke Tabelle" and "rechte Tabelle"'.

            Der Dialog erlaubt es die beiden zu verbindenden Tabellen sowie
            die beiden Felder anzugeben über die die Verbindung hergestellt
            werden soll. Als Voreinstellung beinhaltet die neue Tabelle
            nur die Einträge für die entsprechende Übereinstimmungen
            vorlagen.

            Wollen Sie die Einträge der linken Tabelle erhalten, so können
            Sie eine äussere Verbindung erstellen. Die Felder der rechten
            Tabelle für Einträge ohne Übereinstimmung werden in diesem
            Fall aufgefüllt mit dem Wert <varname>None</varname>.
            </para>
        </section>

    </section>
    <section><title>Attribut-Tabellen</title>
        <para>
        Um klarer zwischen den beiden Tabellen-Typen (Daten und Attribute) zu
        unterscheiden, bietet Thuban die Funktionalität für die Attribut-Tabellen
        unter dem Menü
        <menuchoice><guimenu>Ebene</guimenu></menuchoice> an. 
        </para>

        <section><title>Zeige Tabelle</title>
            <para>
            <menuchoice>
            <guimenu>Ebene</guimenu>
            <guimenuitem>Zeige Tabelle</guimenuitem>
            </menuchoice> 
            öffnet die Attribut-Tabelle für die aktuell aktive Ebene in
            einer Tabellenansicht.

            Eine zusätzliche Funktionalität bei diesen Tabellenansichten
            ist, dass bei Selektionen die korrespondierenden Objekte
            auf der Karte unmittelbar hervorgehoben werden.
            </para>
        </section>

        <section><title>Verbinde Tabelle</title>
            <para>
            Unlike the join described above, the join does not result in a
            new table. The attribute table of the currently active layer is the
            left table and other tables are joined to this table. The results of
            the join are available for classification.

            As a consequence, the join cannot result in fewer
            records than the source attribute table. The user is warned if the 
            right table does not fulfill this constraint. An outer join must be
            used in such cases.
            </para>
        </section>

        <section><title>Unjoin Table</title>
            <para>
            As said above, a normal table cannot be closed while it is still 
            used in a join. While the joined table resulting from a join of 
            normal tables can be simply closed (and thereby dereferencing 
            the source tables), this is not possible for attribute tables.

            Hence joins on attribute tables must be solved explicitly. This is
            what the 
            <menuchoice>
            <guimenu>Layer</guimenu>
            <guimenuitem>Unjoin Table</guimenuitem>
            </menuchoice> 
            item is used for: The last join for the currently
            active layer is solved.
            </para>
        </section>
    </section>
  </chapter>

  <chapter><title>Extensions</title>
        <para>
        Thuban is designed to be extensible. The term Extension is used as a
        general term for anything that extends Thuban.
        This chapter introduces into some oppportunities how to add and
        handle extra functionality developed by your own or third parties.
        </para>

        <section><title>Add personal extensions via thubanstart.py</title>
                <para>
                After Thuban has been started for the first time, a directory
                .thuban is created within your home directory.
                There you can add a file thubanstart.py  which will be imported
                by Thuban at start-up. It is recommended to add only import-statements
                to this file to keep the actual code of extensions separate.
                </para>
                <para>
                The modules to import must either be found through the environment
                variable PYTHONPATH or directly be placed into the .thuban-directory.
                </para>
                <para>
                As an example, copy the file examples/simple_extensions/hello_world.py
                of the Thuban source code into the .thuban-directory of your home
                directory. Now add add the statement import hello_world to the
                file thubanstart.py and run Thuban. You will notice an additional
                menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
                the new item for the Hello-World extension is placed - select it
                to see the Hello-World message.
                </para>
        </section>

        <section><title>Extensions included in Thuban package</title>
                <para>
                The extensions described in this section are part of the
                Thuban package, but not activated by default.
                You will find them in the Thuban installation directory
                under <literal>Extensions/</literal>. Activate them as personal
                extensions via PYTHONPATH as described in the previous section.
                Stable extensions will appear under the menu
                <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
                extensions which are in experimental state and therefore
                not fully functional under
                <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
                </para>

                <section><title>Stable extensions</title>
                        <para>
                        These extensions provide extra-functionality to Thuban
                        that has not (yet) been integrated in the main application.
                        They are considered to be free of bugs, but may be
                        further polished with helpful user interactions.
                        </para>
                    <section><title>gns2shp</title>
                                <para>
                                This tool converts data of the Geospatial Names Server
                                (GNS, see <ulink url="http://www.nima.mil/gns"/>)
                                into Shapefile format.
                                The above web-site offer to download named places
                                information grouped by countries for all of the world
                                except USA for which other data are provided.
                                </para>
                                <para>
                                If you download and unpack a package, you will have
                                a text-file with suffix .txt.
                                Selecting such a file via gns2shp will create the
                                corresponding Shapefile with the same basename and
                                place it in the same direcory. Afterwards it
                                is automatically loaded into Thuban.
                                The Shapefile will not automatically be delete afterwards.
                                </para>
                                <para>
                                The gns2shp.py module can also be executed on the
                                command line for batch processing purposes.
                                </para>
                                <para>
                                A sample (<literal>ls.txt</literal> for Liechtenstein)
                                is included in the directory
                                <literal>Extensions/gns2shp/test</literal>.
                                </para>
                    </section>
                    <section><title>SVG Export</title>
                        <para>
                        Map and legend can be exported separately in the 
                        Thuban-Map-SVG format.
                        You get files that comply with 
                        the Scalable Vector Graphics (SVG) 1.1 Specification
                        and can be read by many vector drawing applications.
                        </para>
                        <para>
                        Goal of svgexport is to provide 
                        the start of a printing pipeline for Thuban.
                        For this purpose the written Thuban-Map-SVG files 
                        contain information that can be used in postprocessing.
                        Typically a general vector drawing application is 
                        more powerful then a geographic information viewer;
                        e.g. having much fancier symbols and fonts.
                        Also users benefit much more when learning to use a 
                        more general application they can also use for other
                        tasks.  So the charming idea is to enable 
                        the drawing application to postprocess a Thuban maps.
                        So thee xtra information in the format will make it 
                        possible to export from Thuban and if a few geoobjects
                        change, and keep the general layout and style 
                        of the full map in the vector drawing appplication.
                        </para>
                        <para>
                        Markus Rechtien has developed a prototype of this
                        printing pipline as his Diplom thetis, showing
                        the feasability of Bernhard Reiter's concept.
                        Scripts exist for the drawing application Skencil
                        (<ulink url="http://www.skencil.org"/>).
                        </para>
                        <para>
                        Technical notes: the names of the layers are used
                        as base for ids within the SVG format. 
                        If you try to export with two layers having 
                        the same name, you will get a name clash error.
                        Just change one of the layer names and try again.
                        </para>
                    </section>
                </section>
                <section><title>Experimental extensions</title>
                        <para>
                        All all of these functions have to be handled with care,
                        since they are neither complete nor well tested.
                        They are to be seen as a proof-of-concept and may
                        additionally in some cases of practical help.
                        </para>
                        <para>
                        Any interest on further improvement of these extensions
                        should be communicated towards the developer and user
                        community.
                        </para>

                        <section><title>importAPR</title>
                                <para>
                                This command offer to load an ESRI® ArcView® project
                                file (suffix .apr) and convert it for use within Thuban.
                                After selecting a apr-file to load, a list
                                will be presented that offers to select one of the views
                                of the apr-file, provided there is more than one.
                                Furthermore, the Session Info-Tree is extended with
                                a complete representation of the parsed apr-file.
                                </para>
                                <para>
                                The legend of Thuban does not yet cover all of the elements as
                                supported by the legend of ArcView®. Therefore, the Thuban
                                map will look different. Furthermore, the apr-format is
                                a proprietary format, not openly documented.
                                Therefore, the interpretation is
                                partly based on reverse engeneering and good guessing.
                                </para>
                                <para>
                                The file-paths within the apr-file may not fit and potentially
                                are subject to fix in the apr-file. You can do this
                                applying any text editor. The paths are either absolute
                                or relative from where Thuban has been started.
                                </para>
                                <para>
                                A sample for the Iceland data is included as
                                <literal>Extensions/importAPR/samples/iceland.apr</literal>.
                                The file-paths are relative from the Thuban main directory.
                                </para>
                        </section>
                </section>
        </section>

        <section><title>Writing simple extensions</title>
                <para>
                Writing an extension for Thuban basically means to
                implement the extra functionality in Python with all of the
                Thuban classes, methods and variables available.
                </para>
                <para>
                All classes and their methods are documented in the source code
                (see their doc-strings). Here is an example from
                Thuban/Model/layer.py that describes some of the methods
                of a Layer object:
                </para>
                <programlisting>
                <![CDATA[
class BaseLayer(TitledObject, Modifiable):

    """Base class for the layers."""

    def __init__(self, title, visible = True, projection = None):
        """Initialize the layer.

        title -- the title
        visible -- boolean. If true the layer is visible.
        """
        TitledObject.__init__(self, title)
        Modifiable.__init__(self)
        self.visible = visible
        self.projection = projection

    def Visible(self):
        """Return true if layer is visible"""
        return self.visible

    def SetVisible(self, visible):
        """Set the layer's visibility."""
        self.visible = visible
        self.issue(LAYER_VISIBILITY_CHANGED, self)

    def HasClassification(self):
        """Determine if this layer support classifications."""
...
                ]]>
                </programlisting>
                <para>
                This example intends to give you an impression of the
                source-code-level documentation.
                You have to make yourself familiar with
                the Python programming language to understand some special
                code elements.
                </para>
                <section><title>hello_world.py</title>
                  <para>
                  Traditionally, the first example should welcome the world.
                  Most of the code handles the frame for integrating a menu
                  item into Thuban while the actual raising of a message
                  is done in a single line.
                  </para>
                        <programlisting>
                        <![CDATA[
# Copyright (C) 2003 by Intevation GmbH
# Authors:
# Jan-Oliver Wagner <[email protected]>
#
# This program is free software under the GPL (>=v2)
# Read the file COPYING coming with Thuban for details.

"""
Extend Thuban with a sample Hello World to demonstrate simple
extensions.
"""

__version__ = '$Revision$'

# use _() already now for all strings that may later be translated
from Thuban import _

# Thuban has named commands which can be registered in the central
# instance registry.
from Thuban.UI.command import registry, Command

# The instance of the main menu of the Thuban application
# See Thuban/UI/menu.py for the API of the Menu class
from Thuban.UI.mainwindow import main_menu

def hello_world_dialog(context):
    """Just raise a simple dialog to greet the world.

    context -- The Thuban context.
    """
    context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))


# create a new command and register it
registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
                     helptext = _('Welcome everyone on this planet')))

# find the extensions menu (create it anew if not found)
extensions_menu = main_menu.FindOrInsertMenu('extensions', _('E&xtensions'))

# finally bind the new command with an entry in the extensions menu
extensions_menu.InsertItem('hello_world')
                        ]]>
                        </programlisting>
                </section>
                <section><title>Registering a Command</title>
                  <para>
                  Mainly, our new function has to be registered to the Thuban
                  framework in order to connect it to the menu. A registered
                  command can also be connected to e.g. a toolbar button.
                  </para>
                  <para>
                  The instances and classes for this are imported at the beginning.
                  Any code not inside a method or class is directly executed when
                  the source-code module is imported. Therefore, the second
                  part of this example consist of the plain statements to create a new
                  Command and to add it to the menu.
                  </para>
                  <para>
                  By convention, it looks for a menu registered as ``extensions'' to
                  insert the new command. If it does not exist yet, it gets created.
                  It is advisable to copy this code for any of your extensions.
                  </para>
                </section>
                <section><title>The Thuban context</title>
                        <para>
                        A registered command that is called, always receives the
                        Thuban context. This instance provides our method with
                        hook references to all important components of the Thuban
                        application.
                        </para>
                        <para>
                In the example hello_world.py, our function uses the
                        mainwindow component which offers a method to raise a
                        message dialog. In total there are three hooks:
                        <itemizedlist>
                        <listitem>
                        <para>application:
                        This object is the instance of the Thuban Application class.
                        Except maybe for loading or savinf sessions, you will not
                        need this object for a simple extension.
                        See Thuban/UI/application.py for the API.
                        </para>
                        </listitem>
                        <listitem>
                        <para>session:
                        The instance of the current session. It manages the sessions'
                        map and tables. You can set and remove the map or tables.
                        In may also get the map object. However, you should know that
                        internally it is already prepared to handle many maps.
                        Therfore, currently you would always receive a list with exactlty
                        one element. In the future, if there are more than one map,
                        you will not know which one is the currently display one and
                        therefore you should use the mainwindow as hook to find
                        the currently displayed map.
                        See Thuban/Model/session.py for the API.
                        </para>
                        </listitem>
                        <listitem>
                        <para>
                        mainwindow: The mainwindow object is central to manage various
                        GUI things such as the Legend sub-window. Most notably,
                        you get access to the canvas which is the window part where
                        the map is drawn. The canvas knows, which map it currently
                        draws and therefore you get the current map via
                        context.mainwindow.canvas.Map().
                        See Thuban/UI/mainwindow.py for the API.
                        </para>
                        </listitem>
                        </itemizedlist>
            </para>
                </section>
        </section>
  </chapter>

  <chapter><title>Trouble Shooting</title>
    <para>
    Here are a few problems that users have encountered when first using Thuban.
    </para>
    <para>

    <itemizedlist>
    <listitem>
    <para>After adding two or more layers nothing is drawn in the map window.
    </para>
    <para>
    This is probably because the layers have different projections. Projections
    must be set on all layers and on the map itself if the layers' projections
    are different.
    </para>
    </listitem>

    <listitem>
    <para>Thuban crashes on startup with the error 
        <literal>NameError: global name 'False' is not defined</literal>.
    </para>
    <para>
    <varname>True</varname> and <varname>False</varname> were only introduced
    in Python 2.2.1. Thuban depends on at least Python 2.2.1.
    </para>
    </listitem>

    <listitem>
    <para>After compiling Thuban, Thuban crashes with an error similar to
        <literal>
        ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0
        </literal>
    </para>
    <para>
    Thuban depends on the wxWindows library. If Thuban is compiled with an
    incompatible version of the compiler than wxWindows was compiled with
    this error may occur. Try compiling with a different version of the 
    compiler.
    </para>
    </listitem>
    </itemizedlist>
    </para>
    <para>
    If an error occurs Thuban will display a dialog indicating the error
    before closing. The text should be copied and reported to the 
    <ulink url="http://thuban.intevation.org/bugtracker.html">
    Intevation bugtracker
    </ulink>.
    More information about the system is available from 
    <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.
    This should also be included in the bug report.
    <figure>
    <title>Error Dialog</title>
    <mediaobject>
    <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>
    <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>
    </mediaobject>
    </figure>
    </para>

  </chapter>

  <appendix><title>Supported Data Sources</title>
    <para>
    </para>
    <variablelist>
    <varlistentry>
    <term>Shapefile</term>
    <listitem>
        <para>
        The Shapefile format has become a standard format for saving
        geographic vector information. It supports polygons, lines, and
        points. 
        
        <ulink url="http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf">
        Technical Specification.
        </ulink>  
        </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term>dBase file</term>
    <listitem>
        <para>
        dBase files are used to store the attributes for each layer. This
        is closely associated with the Shapefile format. For detailed 
        specifications on the correct format of a dBase file used with
        Thuban please see the Technical Specification for the Shapefile
        format above.
        </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term>PostGIS</term>
    <listitem>
        <para>
        PostGIS adds support for geographic objects to the PostgreSQL 
        object-relational database. Different layer types (as for Shapefiles)
        are supported. <ulink url="http://postgis.refractions.net">PostGIS
        Homepage</ulink>
        </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term>Raster files</term>
    <listitem>
        <para>
        Binding the GDAL library Thuban supports numerous raster file formats,
        see <ulink url="http://www.remotesensing.org/gdal/formats_list.html">
        GDAL format list</ulink> for details.</para>

        <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
        format: Raster maps are provided as TIFF images, with an additional 
        "world file" storing the geographic reference (usually with an
        extension ".tfw").
        </para>
    </listitem>
    </varlistentry>

    </variablelist>
  </appendix>

  <appendix><title>Working with PostGIS</title>
  <para>
  This section focusses on the use of PostGIS in the Thuban framework. For
  installation and maintenance of spatial databases we refer to the  
  <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
  The Thuban PostGIS support requires the 
  <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
  </para>

  <para>
        Working with PostGIS Databases is seperated into two steps:
        <itemizedlist>
        <listitem><para>Opening a Database Connection</para></listitem>
        <listitem><para>Loading a Data Layer</para></listitem>
        </itemizedlist>
  </para>
        <section><title>Opening a Database Connection</title>
        <para>
                Before a data layer can be loaded from a PostGIS database a
                connection with the database has to be established. 
                <menuchoice>
                <guimenu>Session</guimenu>
                <guimenuitem>Database Connections ...</guimenuitem>
                </menuchoice> opens a dialog for database connection
                management. In the dialog new connections can be added 
                and existing ones can be removed. Removing a database
                connection is not possible if the map still displays a
                layer provided by this database connection. 
        </para>
    <figure>
    <title>Database Management Dialog</title>
    <mediaobject>
    <imageobject><imagedata fileref="../images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
    <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
    </mediaobject>
    </figure>

        <para>
                To add a new database connection to the session a dialog is
                opened to specify the relevant connection data. Enter all 
                data relevant for your connection. If the connection fails 
                the dialog remains open and provides some hints on the failure.
        </para>
        <figure>
        <title>Add Database Dialog</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        
        <para>
        It is important to note that information on database connections are
        also stored with the session. Passwords are NOT stored. If you load a 
        session with database connections you are asked to enter these
        passwords again where required.
        </para>

        </section>

        <section><title>Loading a Data Layer</title>
        <para>
        Data layers as part of a map are loaded with the 
        <menuchoice>
        <guimenu>Map</guimenu>
        <guimenuitem>Add Database Layer ...</guimenuitem>
        </menuchoice> menu item. A dialog is raised displaying two choice
        lists. In the left list all connected databases are shown.
        Highlighting
        one of these and issuing a retrieval results in a list of available 
        layer tables from that database. After selection of a 
        layer the dialog is closed.
        </para>
        <figure>
        <title>Add Database Dialog</title>
        <mediaobject>
        <imageobject><imagedata fileref="../images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
        <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
        </mediaobject>
        </figure>
        
        </section>

  </appendix>

  <appendix><title>Supported Projections</title>
    <para>
    The following types of projections are directly support by 
    Thuban. The specific values for each are provided by the user
    to create custom projections. Thuban comes with predefined
    projections which are available through the Projections dialog.
    </para>
    <itemizedlist>
    <listitem>
        <para>Geographic</para>
        <itemizedlist>
        <listitem><para><literal>Ellipsoid</literal></para></listitem>
        <listitem><para>
                <literal>Source Data</literal>: either Degrees or Radians
                </para></listitem>
        </itemizedlist>
    </listitem>
    <listitem>
        <para>Lambert Conic Conformal</para>
    <itemizedlist>
        <listitem><para><literal>Ellipsoid</literal></para></listitem>
        <listitem><para><literal>Latitude of 1st standard parallel</literal></para></listitem>
        <listitem><para><literal>Latitude of 2nd standard parallel</literal></para></listitem>
        <listitem><para><literal>Central Meridian</literal></para></listitem>
        <listitem><para><literal>Latitude of Origin</literal></para></listitem>
        <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
        <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
    </itemizedlist>
    </listitem>
    <listitem>
        <para>Transverse Mercator</para>
    <itemizedlist>
        <listitem><para><literal>Ellipsoid</literal></para></listitem>
        <listitem><para><literal>Latitude</literal>of origin</para></listitem>
        <listitem><para><literal>Longitude</literal>at central meridian</para></listitem>
        <listitem><para><literal>Scale Factor</literal>at central meridian</para></listitem>
        <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
        <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
    </itemizedlist>
    </listitem>
    <listitem>
        <para>Universal Transverse Mercator</para>
    <itemizedlist>
        <listitem><para><literal>Ellipsoid</literal></para></listitem>
        <listitem><para><literal>Zone</literal> 
                (can be guessed appling the Propose button)</para></listitem>
        <listitem><para><literal>Southern Hemisphere</literal> flag</para></listitem>
    </itemizedlist>
    </listitem>
    </itemizedlist>
    
    <para>
    Thuban comes with a sample set of map projections for various 
    European countries. Apart from the basic projection they differ 
    especially in their parameterization:
    </para>
    <itemizedlist>
    <listitem><para>Belgium Datum 1972 (Lambert Conic Conformal)</para>
    </listitem>
 
    <listitem><para>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</para>
    </listitem>
 
    <listitem><para>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)
    </para>
    </listitem>
 
    <listitem><para>Reseau Geodesique Francaise 
    (France, Lambert Conic Conformal)</para>
    </listitem>
 
    <listitem><para>UK National Grid (United Kingdom, Transverse Mercartor)
    </para>
    </listitem>
    </itemizedlist>

    <para>
    Thuban uses the comprehensive PROJ library for projections. PROJ provides
    more than the four commonly used projections described above. If needed
    Thuban can be easily extended to a new projection covered by PROJ.
    </para>
  </appendix>

</book>

Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision