Doc/manual/thuban-manual.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 "70">]>
<!-- $Revision$ -->
<book>
  <bookinfo>
    <title>Thuban Manual</title>
    <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>
    <copyright>
      <year>2003</year>
      <holder>Intevation GmbH</holder>
    </copyright>
  </bookinfo>

  <chapter><title>Introduction</title>
    <para>
    Thuban is a Free Software Geographic Information Systems (GIS) viewer.
    It is being developed because there is currently no simple interactive
    viewer for geographic information available as Free Software. Thuban is 
    written in Python and C++ and uses the wxWindows library allowing it to 
    run on many different platforms, including GNU/Linux and Windows.
    </para>
    <para>
    GIS viewers are a necessary tool as they allow one to get a visual 
    impression of the positional relationship of the information that may not
    be apparent from simple inspection of the data values themselves. 
    Thuban allows the user to create a session that displays
    geographic data and then explore that data through navigation and
    manipulation of how it is drawn. The results can then be saved or printed.
    </para>
    <para>
    Thuban arranges a session in a hierarchy. A session contains a map which
    consists of layers. Each layer represents one kind of data set. For 
    instance, there may be a layer for roads and another layer for buildings. 
    These layers can either be vector shapes or images.
    </para>

        <section><title>Installation</title>
        <para>
        Thuban is actively supported under Debian Testing (sarge), RedHat 7.2, 
        and Windows 2000. All the necessary files can be found on the 
        <ulink url="http://thuban.intevation.org/download.html">
        Thuban Download site
        </ulink>.
        </para>
        </section>

        <section><title>The Main Window</title>
        <para>
        <screenshot>
        <screeninfo>The Main Window</screeninfo>
        <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>
        <textobject><phrase>The Main Window</phrase></textobject>
        <caption><para>The Main Window</para></caption>
        </mediaobject>
        </screenshot>
        </para>

        <para>
        The map window shows the current state of the map and is where
        the user can interact with the map using the tools. 
        </para>

        <para>
        The legend on the left displays a list of the current layers and 
        any visible classification groups. In the example, each shape layer 
        has a default classification which specifies how the shapes in each 
        layer are drawn. Layers that are higher in the list appear 
        ``closer'' to the user. The legend can be closed by clicking on the 
        small X in the upper right-hand region of the legend. 
        To open it again, use
        <menuchoice>
        <guimenu>Map</guimenu>
        <guimenuitem>Legend</guimenuitem>
        </menuchoice>.
        The legend is also dockable, which means that it can be detached 
        from the main window by clicking on the small button next to the 
        close button. It can be attached by clicking the same button
        again.
        </para>
        <para>
        The status bar displays different information depending on the
        current context. If the user is selecting an item from the menu
        then the status bar will display a short help message indicating
        what each menu item is for. If the user has a tool selected then
        the position of the cursor on the map is displayed.
        </para>
        <para>
        The tool bar provides quick access to the commonly needed tools.
        By hovering over each button the user can see a short messages
        describing what the tool does. The tools provided are Zoom In, Zoom
        Out, Pan, Full Extent, Full Layer Extent, Full Shape Extent, Indentify,
        and Label. Each of the tools will be explained in further detail later
        in the manual.
        </para>
        </section>

  </chapter>

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

        <section><title>Starting a New Session</title>
        <para>
        A new session can be started from 
        <menuchoice>
        <guimenu>File</guimenu>
        <guimenuitem>New Session</guimenuitem>
        </menuchoice>. 
        If a session is already loaded and has been modified without
        being saved a prompt will ask if the current session should
        be saved. A new session consists of an empty map with no
        layers and no tables.
        </para>
        </section>

        <section><title>Opening a Session</title>
        <para>
        A session can be opened from 
        <menuchoice>
        <guimenu>File</guimenu>
        <guimenuitem>Open Session</guimenuitem>
        </menuchoice>. A dialog box will open allowing the user to browse
        for a Thuban Session file. Thuban session files end with
        <varname>.thuban</varname>. Selecting a file a clicking
        <guibutton>OK</guibutton> will load the session into Thuban.

        If a session is already loaded and has been modified without
        being saved a prompt will ask if the current session should
        be saved.
        </para>
        </section>

        <section><title>Saving a Session</title>
        <para>
        A session can be saved from 
        <menuchoice>
        <guimenu>File</guimenu>
        <guimenuitem>Save Session</guimenuitem>
        </menuchoice>. A dialog box will open allowing the user to browse
        the filesystem and select a place to save the session. Thuban
        sessions should be saved under a name ending in 
        <varname>.thuban</varname>. If the file already exists the user
        will be prompted to save under a different name or overwrite the
        existing file.
        </para>
        </section>

        <section><title>The Session Info-Tree</title>
        <para>
        <screenshot>
        <screeninfo>Session Info Tree</screeninfo>
        <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>
        <textobject><phrase>Session Info Tree</phrase></textobject>
        <caption><para>Session Info Tree</para></caption>
        </mediaobject>
        </screenshot>
        </para>
        <para>
        The session info-tree is primarily intended for developers working
        with Thuban. It displays many of the internal values for the session,
        map, and layers. It can be opened from
        <menuchoice>
        <guimenu>File</guimenu>
        <guimenuitem>Session Tree</guimenuitem>
        </menuchoice>. 
        </para>
        </section>
  </chapter>

  <chapter><title>Map Management</title>
    <para>
    The map consists of a number of layers where each layer represents a
    different type of data set. By interacting with the map the user can
    visually explore the data. 
    </para>
    <para>
    The map can have a name that will appear in the Thuban title bar. 
    The map name can be changed using 
    <menuchoice>
    <guimenu>Map</guimenu>
    <guimenuitem>Rename</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>Rename Map</phrase> </textobject>
    </inlinemediaobject>
    </para>

        <section><title>Adding and Removing Layers</title>
        <para>
        There are two types of layers that can use added to a map: shape layers
        and image layers. Shape layers are stored in Shapefile format, a
        standard file format for storing geographic objects. Normally, these
        files have the extension ``.shp''. Associated with
        the object information is a database file which stores attributes for
        each shape in the Shapefile. This file, stored in dBASE format, usually
        has the extension ``.dbf''. Both files should have the same base name.
        For example, if there is a Shapefile named roads.shp there should
        also be a file roads.dbf.
        </para>
        <para>
        Shape layers can be added to the map with
        <menuchoice>
        <guimenu>Map</guimenu>
        <guimenuitem>Add Layer</guimenuitem>
        </menuchoice>.
        Thuban will load all files with the same base name, so it doesn't
        matter if the Shapefile or database file is selected.
        </para>

        <para>
        Image layers can be added to the map with
        <menuchoice>
        <guimenu>Map</guimenu>
        <guimenuitem>Add Image Layer</guimenuitem>
        </menuchoice>.
        It is important to select a valid image file that has geographic
        data associated with it. This can be embedded in the file itself, 
        or in another file. If geographic information cannot be found, Thuban 
        will report an error.
        </para>
        </section>

        <section><title>Navigation</title>
        <para>
        The map can be explored by using the navigation tools available on 
        the tool bar, or from the 
        <menuchoice><guimenu>Map</guimenu></menuchoice> menu. 
        </para>
        <para>
        The ZoomIn tool 
        <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 Tool</phrase> </textobject>
        </inlinemediaobject>
        can be used to enlarge a region of the map. Clicking once on the map
        will double the magnification and center the map on the point that
        was clicked. Clicking and dragging lets the user select a region
        to be enlarged to fit the window.
        </para>
        <para>
        The ZoomOut tool 
        <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 Tool</phrase> </textobject>
        </inlinemediaobject>
        shrinks the map so that a larger region is visible. A single click
        reduces the magnification by a factor of two. Clicking and dragging
        selects a box such that the current contents of the window will be
        scaled to fit into that box.
        </para>
        <para>
        The Pan tool 
        <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>Pan Tool</phrase> </textobject>
        </inlinemediaobject>
        allows the user to move the map around by clicking and dragging.
        </para>
        <para>
        The Full Extent tool 
        <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>Full Extent Tool</phrase> </textobject>
        </inlinemediaobject>
        rescales the viewable region so that the entire map is visible.
        </para>
        <para>
        The Full Layer Extent tool 
        <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>Full Layer Extent Tool</phrase> </textobject>
        </inlinemediaobject>
        rescales the viewable region so that the currently selected
        layer fits within the window. If no layer is selected this button 
        will be disabled.
        </para>
        <para>
        The Full Shape Extent tool 
        <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>Full Shape Extent Tool</phrase> </textobject>
        </inlinemediaobject>
        rescales the viewable region so that the currently selected
        shape fits within the window. If the shape is a point, it is
        centered and the map is zoomed all the way in. If no shape is 
        selected this button will be disabled.
        </para>
        </section>

        <section><title>Object Identification</title>
        <para>
        Objects on the map can be identified using the Identify tool
        <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>Identify Tool</phrase> </textobject>
        </inlinemediaobject>.
        Clicking on an object selects that object and opens a dialog which 
        shows all the table attributes for that object. Any current selection
        is lost. 
        </para>
        </section>

        <section><title>Object Labelling</title>
        <para>
        Objects can be labelled using the Label tool
        <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 Tool</phrase> </textobject>
        </inlinemediaobject>.
        Clicking on an object selects that object and opens a dialog which
        displays the table attributes for that object. An attribute can
        be selected to be the label on the map. Using this tool for an
        object that already has a label will remove the label.
        </para>
        </section>

        <section><title>The Legend</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>Legend</phrase> </textobject>
        </inlinemediaobject>
        </para>
        <para>
        The Legend provides an overview of the layers in the map. Layers
        that appear higher in the legend will appear ``closer'' to the user.
        If a layer supports classification (currently, only shape layers 
        have this feature) then the classification groups will be shown
        below each layer. The properties for each group are also displayed
        with a small graphic. Polygon layers appear as rectangles, lines
        appear as curved lines, and points appear as circles. 
        </para>
        <para>
        Along the top of the legend is a toolbar which allows quick access
        to some of the layer manipulation options under
        <menuchoice> <guimenu>Map</guimenu> </menuchoice>. 

        Double-clicking on a layer or a group of a layer will open the 
        properties dialog for that layer.
        </para>
        </section>

        <section><title>Exporting</title>
        <para>
        Under Windows, maps can be exported in Enhanced Metafile format
        (<varname>.wmf</varname>)
        from 
        <menuchoice>
        <guimenu>Map</guimenu>
        <guimenuitem>Export</guimenuitem>
        </menuchoice>. Under other platforms this option is not available.
        Clicking this menu item open a file selection dialog that lets the
        user select a location to export the map.
        </para>
        </section>

        <section><title>Printing</title>
        <para>
        The map can be printed using 
        <menuchoice>
        <guimenu>Map</guimenu>
        <guimenuitem>Print</guimenuitem>
        </menuchoice>. A standard printing dialog will open allowing the
        user to configure the printer. This dialog will differ depending
        on which platform Thuban is running.
        </para>
        </section>

  </chapter>

  <chapter><title>Layer Management</title>
    <para>
    </para>

        <section><title>Types of Layers</title>
        <para>
        There are two types of layers supported by Thuban: shape layers and
        image layers. Shape layers consist of vector based shapes with 
        geo-referenced coordinates. There are three types of supported 
        shapes: polygons, lines, and points. Image layers can be any image
        file format supported by GDAL. The images must have geographic
        coordinate data either embedded within the file, or in a seperate
        file that is in the same directory as the image file. GeoTIFF files 
        work very well with Thuban and were designed specifically to be image 
        layers in GIS programs.
        </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 and it can be modified in the text field
        provided. The type of layer is also shows. If the type is 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>
        <screenshot>
        <screeninfo>Properties Window</screeninfo>
        <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>
        <textobject><phrase>Properties Window</phrase></textobject>
        <caption><para>The Properties Window for a Shape Layer</para></caption>
        </mediaobject>
        </screenshot>
        </para>
        <para>
        <screenshot>
        <screeninfo>Properties Window</screeninfo>
        <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>
        <textobject><phrase>Properties Window</phrase></textobject>
        <caption><para>The Properties Window for an Image Layer</para></caption>
        </mediaobject>
        </screenshot>
        </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
        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, with 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. Every shape in the layer, regardless of its
    attributes, will match this group. 
    </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>
        <screenshot>
        <screeninfo>Properties Window</screeninfo>
        <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>
        <textobject><phrase>Properties Window</phrase></textobject>
        <caption><para>The Properties Window with Classifications</para></caption>
        </mediaobject>
        </screenshot>
        </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
        other than 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>
        <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 specifed 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>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>Generating Classes</title>
        <para>
        <screenshot>
        <screeninfo>Generate Class</screeninfo>
        <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>
        <textobject><phrase>Generate Class</phrase></textobject>
        <caption><para>The Generate Classifications Dialog</para></caption>
        </mediaobject>
        </screenshot>
        </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> pulldown there are at most
        three different ways to generate classifications: 
        Unique Values, Unique Distribution, and Quantiles. Some options 
        may not be available if they data type for the field does not
        support them. For instance, <varname>Unique 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 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.
        </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.
        </para>
        <para>
        The Unique 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.
        </para>
        <para>
        The Quantiles option generates ranges based on the number items
        in the input set. For example, by specifying 5 groups Thuban will
        generate groups with appropriate ranges such that 20% of the table
        data is in each group. If it is impossible to generate exact
        grouping, Thuban will issue a warning but allow the user to continue.
        </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 tell Thuban 
    which projection each layer has. 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>.
    <screenshot>
    <screeninfo>Projection Window</screeninfo>
    <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>
    <textobject><phrase>Projection Window</phrase></textobject>
    <caption><para>The Projection Window</para></caption>
    </mediaobject>
    </screenshot>
    </para>
    <para>
    Thuban is distributed with a sample collection of projections. 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 to others.
    </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 be initially 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
        the <guibutton>Update</guibutton>. Only a projection that comes
        from a file can be updated, so if the current layer's projection
        is selectd, <guibutton>Update</guibutton> will be disabled. 
        The <guibutton>Add to List</guibutton> adds the projection to the 
        list of available projections as a new entry, and thus make it 
        available to future Thuban sessions. Clicking <guibutton>New</guibutton>
        will create an entirely new, empty projection. The 
        <guibutton>Remove</guibutton> button will permanantly remove a 
        projection from the list of available projections.
        </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 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 session.
        </para>
    </section>
  </chapter>

  <chapter><title>Table Management</title>
    <para>
    Thuban distinguishes two different types of tables: Attribute tables
    (which belong to a layer) and usual data tables. Both provide in
        general the same functionality with the difference that actions on an
    attribute table might also effect the map display.
    </para>

    <section><title>Table View</title>
        <para>
        <screenshot>
        <screeninfo>Table View</screeninfo>
        <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>
        <textobject><phrase>Table View</phrase></textobject>
        <caption><para>The Table View</para></caption>
        </mediaobject>
        </screenshot>
        </para>
        <para>
        Thuban provides a standard dialog to display table contents, the 
        Table View. The view falls into five sections: The title, selections, 
        the table grid, export functions and the status bar.
        </para>
        <para>
        The title bar identifies the table with it's name.
        </para>
        <para>
        The functions box let the user perform simple analysis on the data
        based on comparisons: First choice must be a field identifier of the 
        table, the second choice determines the type of comparison. The third
        choice can be either a specific value (interpreted as numerical 
        or string depending on the type of the first field) or a second field 
        identifier. Thus you can perform analysis like selecting all
        records where "population > 10000" or 
        "cars_per_habitants <  bike_per_habitants" (note that the field names
        are only explanatory, the currently considered dBASE files allow only 
        11 character field names).
      
        Selections can be combined, either by applying a selection only on 
        a previously selected set of records or by adding the results of a
        selection to a previous set. The default is that a selection replaces
        earlier results.
        </para>
        <para>
        The table grid shows the contents of the table (a record per column), 
        with highlighted selection results. Columns and rows can be resized.
        </para>
        <para>
        The contents of a table can be exported into a file, either dBASE
        format (DBF) or comma seperated values (CSV). The 
        <guibutton>Export</guibutton> button 
        raises a file dialog to specify a path and file name, the export type
        is determined by the file extension (either .dbf or .csv).

        The <guibutton>Export Selection</guibutton> button works similarly
        but exports only the selected records.

        The <guibutton>Close</guibutton> button closes the table view window. 
        This is different from the menu item 
        <menuchoice>
        <guimenu>Table</guimenu>
        <guimenuitem>Close</guimenuitem>
        </menuchoice> which unloads the table from Thuban.
        </para>
        <para>
        The status bar displays some statistics about the table and optional
        selection results.
        </para>
    </section>

    <section><title>General Functionality (Menu Table)</title>
        <para>
        The general functions affect all tables open in Thuban. Attribute
        tables are considered here as usual data tables (with the exception
        that they cannot be closed).
        </para>
        <section><title>Open</title>
            <para>
            The 
            <menuchoice>
            <guimenu>Table</guimenu>
            <guimenuitem>Open</guimenuitem>
            </menuchoice> 
            item raises a file dialog to let you select a 
            dBASE file from the file system to be loaded into Thuban read-only. 
            On OK the selected file is loaded and a table view is opened.
            </para>
        </section>

        <section><title>Close</title>
            <para>
            The
            <menuchoice>
            <guimenu>Table</guimenu>
            <guimenuitem>Close</guimenuitem>
            </menuchoice> 
            item raises a dialog listing the currently open 
            data tables 
            (loaded via 
            <menuchoice>
            <guimenu>Table</guimenu>
            <guimenuitem>Open</guimenuitem>
            </menuchoice>). Selected tables are dereferenced on confirmation. 
            Since tables are opened read-only the contents of the tables are 
            not affected.

            A still open table view is closed as well.

            Tables used in a join cannot be closed.
            </para>
        </section>

        <section><title>Rename</title>
            <para>
            <menuchoice>
            <guimenu>Table</guimenu>
            <guimenuitem>Rename</guimenuitem>
            </menuchoice> changes the table title.
            </para>
        </section>

        <section><title>Show</title>
            <para>
            The
            <menuchoice>
            <guimenu>Table</guimenu>
            <guimenuitem>Show</guimenuitem>
            </menuchoice> 
            item raises a list of available tables (explicitly 
            loaded, attribute tables, results of a join). Selected tables are 
            show in tables views on <guibutton>OK</guibutton>
            </para>
        </section>

        <section><title>Join</title>
            <para>
            <screenshot>
            <screeninfo>Join Tables</screeninfo>
            <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>
            <textobject><phrase>Join Tables</phrase></textobject>
            <caption><para>The Join Tables Dialog</para></caption>
            </mediaobject>
            </screenshot>
            </para>
            <para>
            The 
            <menuchoice>
            <guimenu>Table</guimenu>
            <guimenuitem>Join</guimenuitem>
            </menuchoice> 
            item raises a dialog to specify the two tables to be
            joined. The join results in a new table named 'Join of "left table"
            and "right table"'.

            The dialog let you select the two tables to be joined and the two
            fields the join has to be performed on. By default the new
            table contains only those records which are mathced by the join.

            If you want to preserve the records of the left table you can 
            perform an outer join. The fields from the right table for records 
            not matched by the join are filled with <varname>None</varname> in 
            this case.
            </para>
        </section>

    </section>
    <section><title>Attribute Tables</title>
        <para>
            To clearly separate between both types, Thuban provides 
        functionality regarding the attribute tables under the Layer menu. 
        </para>

        <section><title>Show Table</title>
            <para>
            <menuchoice>
            <guimenu>Layer</guimenu>
            <guimenuitem>Show Table</guimenuitem>
            </menuchoice> 
            opens the attribute table of the currently active layer in a table 
            view. 

            In addition to the functionality described above selections
            affect also the map display: objects related to selected records 
            are highlighted. 
            </para>
        </section>

        <section><title>Join Table</title>
            <para>
            In difference to the join described above the join results not 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 classifications.

            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 explicitely. 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>Trouble Shooting</title>
    <para>
    </para>
    <variablelist>

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

    <varlistentry>
    <term>Thuban crashes on startup with the error 
        <literal>NameError: global name 'False' is not defined</literal>.
    </term>
    <listitem>
    <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>
    </varlistentry>

    <varlistentry>
    <term>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>
    </term>
    <listitem>
    <para>
    Thuban depends on the wxWindows library. If Thuban is compiled with an
    incompatible version of the compiler that wxWindows was compiled with
    this error may occur. Try compiling with a different version of the 
    compilere
    </para>
    </listitem>
    </varlistentry>
    </variablelist>

  </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>

    </variablelist>
  </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 and are available through the Projections dialog.
    </para>
    <variablelist>
    <varlistentry>
    <term>Geographic</term>
    <listitem><para></para></listitem>
    </varlistentry>
    <varlistentry>
    <term>Lambert Conic Conformal</term>
    <listitem><para></para></listitem>
    </varlistentry>
    <varlistentry>
    <term>Transverse Mercator</term>
    <listitem><para></para></listitem>
    </varlistentry>
    <varlistentry>
    <term>Universal Transverse Mercator</term>
    <listitem><para></para></listitem>
    </varlistentry>
    </variablelist>
  </appendix>

</book>
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision