/[thuban]/branches/WIP-pyshapelib-bramz/Doc/manual/thuban-manual.xml
ViewVC logotype

Diff of /branches/WIP-pyshapelib-bramz/Doc/manual/thuban-manual.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1369 by bh, Thu Jul 3 16:27:22 2003 UTC revision 2688 by frank, Fri Jun 30 12:27:20 2006 UTC
# Line 1  Line 1 
1  <?xml version="1.0" encoding="ISO-8859-1"?>  <?xml version="1.0" encoding="ISO-8859-1"?>
2  <!DOCTYPE book  <!DOCTYPE book
3          PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"          PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
5        [<!ENTITY imgscale "60">]>
6  <!-- $Revision$ -->  <!-- $Revision$ -->
7  <book>  <book>
8    <bookinfo>    <bookinfo>
9      <title>Thuban Manual</title>      <title>User's Manual for Thuban 1.0</title>
10      <author>          <authorgroup>
11        <firstname></firstname><surname></surname>        <author>
12      </author>          <firstname>Jonathan</firstname><surname>Coles</surname>
13          </author>
14          <author>
15            <firstname>Jan-Oliver</firstname><surname>Wagner</surname>
16          </author>
17          <author>
18            <firstname>Frank</firstname><surname>Koormann</surname>
19          </author>
20            </authorgroup>
21      <copyright>      <copyright>
22        <year>2003</year>        <year>2003, 2004, 2005, 2006</year>
23        <holder>Intevation GmbH</holder>        <holder>Intevation GmbH</holder>
24      </copyright>      </copyright>
25       <revhistory>
26    <!-- comment this first revision out when releasing a real version -->
27         <revision>
28            <revnumber>SVN version $Id$</revnumber>
29            <date></date>
30            <revremark>Under development.</revremark>
31         </revision>
32         <revision>
33            <revnumber>1.0.0</revnumber>
34            <date>22-Jan-2004</date>
35            <revremark>
36                            Corresponds to Thuban 1.0.0.
37                            New: Installation instructions for Win32.
38                    </revremark>
39         </revision>
40         <revision>
41            <revnumber>1.0pre3</revnumber>
42            <date>04-Dec-2003</date>
43            <revremark>
44                            Corresponds to Thuban 1.0rc1.
45                            New: I18n, right button legend menu, EPSG projectons,
46                PostGIS support.
47                    </revremark>
48         </revision>
49         <revision>
50            <revnumber>1.0pre2</revnumber>
51            <date>29-Aug-2003</date>
52            <revremark>
53                            Corresponds to Thuban development release 0.8.1.
54                            New: chapter on extensions.
55                    </revremark>
56         </revision>
57         <revision>
58            <revnumber>1.0pre1</revnumber>
59            <date>08-Aug-2003</date>
60            <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
61         </revision>
62      </revhistory>
63    
64    </bookinfo>    </bookinfo>
65    
66    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
67      <para>      <para>
68        Thuban is an interactive geographic data viewer.
69        Its development had been started because there was no simple interactive
70        viewer for geographic information available as Free Software. Thuban is
71        written mainly in Python and uses the wxWidgets (former wxWindows)
72        library allowing it to
73        run on many different platforms, including GNU/Linux and Windows.
74        </para>
75        <para>
76        Geographic data viewers are a necessary tool as they allow one to
77            get a visual
78        impression of the positional relationship of the information that may not
79        be apparent from simple inspection of the data values themselves.
80        Thuban allows the user to create a session that displays
81        geographic data and then explore that data through navigation and
82        manipulation of how it is drawn. The results can then be saved or printed.
83        </para>
84        <para>
85        Thuban arranges a session in a hierarchy. A session contains a map which
86        consists of layers. Each layer represents a data set. For
87        instance, there may be a layer for roads and another layer for buildings.
88        These layers can either be vector shapes or images.
89        </para>
90    
91            <section><title>Installation</title>
92            <para>
93            Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,
94            and Windows 2000. Thuban depends on the following packages. These
95            packages can also be found on the
96            <ulink url="http://thuban.intevation.org/download.html">
97            Thuban Download site
98            </ulink>.
99            </para>
100            <para>
101            Required:
102            <itemizedlist>
103                <listitem><para>Python 2.2.1
104                            (<literal>http://www.python.org</literal>)
105                            </para></listitem>
106                <listitem><para>wxWindows 2.4
107                            (<literal>http://www.wxwindows.org</literal>)
108                            </para></listitem>
109                <listitem><para>wxPython 2.4
110                            (<literal>http://www.wxpython.org</literal>)
111                            </para></listitem>
112                <listitem><para>proj 4.4.5 Projection Library
113                            (<literal>http://www.remotesensing.org/proj/</literal>)
114                            </para></listitem>
115                <listitem><para>SQLite 2.8.3
116                            <literal>http://www.hwaci.com/sw/sqlite/</literal>)
117                            </para></listitem>
118                <listitem><para>PySQLite 0.4.3
119                            (<literal>http://pysqlite.sourceforge.net</literal>)
120                            </para></listitem>
121            </itemizedlist>
122            </para>
123            <para>
124            Optional:
125            <itemizedlist>
126                <listitem><para>GDAL 1.1.8
127                            (<literal>http://www.remotesensing.org/gdal/</literal>)
128                            </para></listitem>
129                <listitem><para>psycopg 1.0.8
130                            (<literal>http://initd.org/software/psycopg</literal>)
131                            </para></listitem>
132                </itemizedlist>
133            </para>
134                    <para>
135                    Along with the source codes, the download page also offers full
136                    installation packages for Debian, Windows and RPM-based systems
137                    (Mandrake, RedHat, SuSE, etc).
138                    </para>
139                    <section><title>RPM-based GNU/Linux Systems</title>
140                            <section><title>Installing Binary Packages</title>
141                                    <para>
142                                    The most wide-spread RPM-based GNU/Linux
143                                    Systems are RedHat, Mandrake and SuSE.
144                                    The documentation of these distributions
145                                    should contain information about how to
146                                    install third-party RPM packages.
147                                    Nonetheless, a short summary is provided here.
148                                    </para>
149                                    <para>
150                                    RPM packages can be installed applying several
151                                    tools. The most basic one is the command line
152                                    program "rpm".  The hardware architecture is
153                                    identified in the name of RPM packages, eg.
154                                    'i386' for most Intel/AMD architectures.  
155                                    If you have a different hardware architecture,
156                                    where no binary RPM packages are provided,
157                                    you must rebuild binary packages from the
158                                    RPM source packages first (see below).
159                                    Typical rpm commands look like:
160    
161                                    <programlisting>
162                                    rpm --install Thuban-0.9.0-1.i386.rpm
163                                    </programlisting>
164    
165                                    Depending on what you already have installed
166                                    on your system, you are informed that some
167                                    packages are required, but not installed.
168                                    You need to install them first. Either they
169                                    are provided by your GNU/Linux distributor
170                                    or available somewhere on the Internet.  
171                                    The more essential and special ones are
172                                    provided together with the Thuban package.
173                                    </para>
174    
175                                    <para>
176                                    For rpm exist some graphical user interfaces, notably
177                                    kpackage, GnoRPM and xrpm.
178                                    </para>
179    
180                                    <para>
181                                    Make yourself familiar with one of the tools and apply it
182                                    to install the packages.
183                                    Note, that you need to be administrator (root) for the system
184                                    to do that.
185                                    </para>
186                            </section>
187                            <section><title>Build Binaries from Source Packages</title>
188                                    <para>
189                                    This section describes howto build RPM install-packages
190                                    from RPM source-packages.
191                                    This adapts and optimizes an install-package specifically
192                                    to your system.
193                                    This is especially helpful to resolve version conflicts of
194                                    dependent packages. Furthermore, install-packages for other
195                                    platforms (e.g. PowerPC) can be created.
196                                    </para>
197    
198                                    <para>
199                                    Note: rpm must be at least version 4. Execute
200                                    <literal>rpm --version</literal> to find out about the version.
201                                    </para>
202    
203                                    <para>
204                                    You need to do the following preparations to be able to
205                                    build the packages as a regular user. You should now
206                                    perform the package buling as root since this
207                                    might cause damage to your system.
208                            <itemizedlist>
209                            <listitem>
210                                                    <para>
211                                                    Create RPM directory structure:
212                                                    Choose a directory (e.g. $HOME/myrpm) and create the
213                                                    subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.
214                                                    A possible command sequence for this is:
215                                                    <programlisting>
216                                                    mkdir $HOME/freegisrpm
217                                                    cd $HOME/freegisrpm
218                                                    mkdir BUILD RPMS SOURCES SPECS SRPMS
219                                                    </programlisting>
220                                                    </para>
221                                            </listitem>
222                                            <listitem>
223                                                    <para>
224                                                    Set environment variable RPM_DIR:
225                                                    <programlisting>
226                                                    export RPM_DIR=$HOME/freegisrpm
227                                                    </programlisting>
228                                                    </para>
229                                            </listitem>
230                                            <listitem>
231                                                    <para>
232                                                    Create $HOME/.rpmmacros:
233                                                    This file sets general preferences and some
234                                                    specific settings for signing packages.
235                                                    If you don't have a GnuPG-key, you can skip
236                                                    the signature settings i.e. drop the last 4 lines.
237                                                    A signature becomes important when you want to
238                                                    give away packages to third parties.
239                                                    <programlisting>
240    <![CDATA[
241    %packager Name Lastname <[email protected]>
242    
243    %_topdir /home/mylogin/myrpm
244    
245    %_signature gpg
246    %_gpg_name Name Lastname
247    %_pgp_path ~/.gnupg
248    %_pgpbin /usr/bin/gpg
249    ]]>
250                                                    </programlisting>
251                                                    </para>
252                                            </listitem>
253                            </itemizedlist>
254    
255                                    Now you can install any RPM source-package.
256                                    It's components are installed into the corresponding
257                                    subdirectories of your rpm-directory.
258                                    Essentially these are the sources (into directory SOURCES)
259                                    and the so-called spec-file which contains all build
260                                    instructions. The spec-file will go into the SPEC directory.
261                                    Example:
262                                    <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>
263                                    </para>
264    
265                                    <para>
266                                    Create install-package:
267                                    Go to the directory with the spec-files and rebuild the
268                                    package:
269                                    <programlisting>
270    cd $HOME/mypm/SPECS
271    rpm -bb thuban.spec
272                                    </programlisting>
273                                    Next, you will find the newly created package in
274                                    $HOME/myrpm/RPMS/i386.
275                                    If you build the package for another architecture than
276                                    i386, then the name of the directory has a corresponding name.
277                                    </para>
278                                    <para>
279                                    For documentation of RPM, either type
280                                    <literal>man rpm</literal> or <literal>rpm --help</literal>.
281                                    This will provide you with information on the various command
282                                    line options of RPM.
283                                    For more information see the
284                            <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
285                                    </para>
286                            </section>
287                    </section> <!-- Intro - Installation - RPM-->
288    
289                    <section><title>Win32 Systems</title>
290                    <para>
291                            A common installation package of Thuban for Win32
292                            systems is available from the Thuban website download
293                            section. This installation package is configured for
294                            displaying file based vector data (Shapefiles). For the
295                            display of raster data or the connection to spatial
296                            databases additional steps are needed.  
297                    </para>
298                    <para>
299                            The required Python packages are listed and linked on
300                            the download page as well.  If you don't have Python
301                            installed already, download the packages for Python,
302                            wxPython for Python and the SQLite Python Libraries as
303                            well as the Thuban package. Install all four packages
304                            in the order: Python, wxPython, SQLite, Thuban. Follow
305                            the installation instructions provided by the seperate
306                            setups. The Thuban installation package will add an
307                            entry in the menu folder you configured.
308                    </para>
309                    <section><title>Raster Data: Installation of GDAL</title>
310                    <para>
311                            Enabling the raster data features of Thuban is
312                            straight forward. For the examples we assume that
313                            Thuban has been installed under
314                            <literal>C:\Thuban</literal>:
315                            <itemizedlist>
316                            <listitem>
317                            <para>
318                            Download the zip-archive <ulink
319                            url="ftp://intevation.de/thuban/win2k/gdal-win2k.zip"
320                            >gdal-win2k</ulink>.
321                            </para></listitem>
322                            <listitem><para>Extract the archive (e.g. with
323                            <ulink
324                            url="http://www.info-zip.org/pub/infozip/WiZ.html"
325                            >WiZ (InfoZip)</ulink>) into the
326                            <literal>C:\Thuban\Lib</literal>
327                            directory of your Thuban installation.
328                            </para>
329                            </listitem>
330                            <listitem>
331                            <para>
332                            Extent the <varname>PYTHONPATH</varname>
333                            environment variable (in your Windows Control Panel)
334                            to make the new libraries available for Thuban.
335                            <programlisting>
336    %PYTHONPATH%;C:\Thuban\Lib\gdal;C:\Thuban\Lib\gdal\pymod
337                            </programlisting>
338                            </para>
339                            </listitem>
340                            <listitem>
341                            <para>
342                            Extent also the <varname>PATH</varname>
343                            environment variable accordingly:
344                            <programlisting>
345    %PATH%;C:\Thuban\Lib\gdal
346                            </programlisting>
347                            </para>
348                            </listitem>
349                            </itemizedlist>
350                            After this installation steps Thuban is ready to
351                            display raster data (e.g. the
352                            <literal>island.tif</literal> from the Iceland Demo
353                            data set.
354                    </para>
355                    </section> <!-- Win32: GDAL-->
356    
357                    <section><title>Working with PostGIS: Installation of PsycoPG</title>
358                    <para>
359                            To access PostgreSQL/PostGIS spatial databases with
360                            Thuban you have to install the PsycoPG package for
361                            Windows:
362                            <itemizedlist>
363                            <listitem>
364                            <para>
365                            Download the zip-archive
366                            <ulink
367                                    url="http://stickpeople.com/projects/python/win-psycopg/win-psycopg22.zip"
368                            >win-psycopg22.zip</ulink>.
369                            </para>
370                            </listitem>
371                            <listitem>
372                            <para>
373                            Extract the zip-archive into a directory either already
374                            in your <varname>PYTHONPATH</varname> or extent your
375                            <varname>PYTHONPATH</varname> variable to the directory
376                            you have extracted the archive to.
377                            </para>
378                            </listitem>
379                            </itemizedlist>
380                            For installation and maintenance of spatial databases
381                            we refer to the  <ulink
382                            url="http://postgis.refractions.net"
383                            >PostGIS Homepage</ulink>.
384                    </para>
385                    </section> <!-- Win32: PsycoPG-->
386    
387                    </section> <!-- Intro - Installation - Win32 -->
388            </section>
389    
390            <section><title>Internationalization</title>
391            <para>
392            Thuban is implemented with internationalization support. So far Thuban
393            is translated by volunteers to the following languages (apart from its
394            main language: English):
395            <itemizedlist>
396                <listitem><para>French</para></listitem>
397                <listitem><para>German</para></listitem>
398                <listitem><para>Italian</para></listitem>
399                    <listitem><para>Portuguese (Brazilian)</para></listitem>
400                <listitem><para>Russian</para></listitem>
401                <listitem><para>Spanish</para></listitem>
402            </itemizedlist>
403            </para>
404    
405            <para>
406            To use internationalization under POSIX systems (like GNU/Linux)
407            you have to set the environment variable LC_ALL accordingly (e.g.
408            LC_ALL=fr_FR for the french language support). Please check your
409            systems documentation for details and supported settings.
410            Specifiying LC_ALL on the command line while launching thuban
411            allows appication specific language settings:
412            </para>
413            <programlisting>
414            LC_ALL=fr_FR thuban.py
415            </programlisting>
416    
417            <para>
418            MS Windows users have to specify the language to be used via the control
419            bar (which effects all applications).
420            </para>
421            </section>
422    
423            <section><title>The Main Window</title>
424            <para>
425            <figure>
426            <title>The Main Window</title>
427            <mediaobject>
428            <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>
429            <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>
430            </mediaobject>
431            </figure>
432            </para>
433    
434            <para>
435            The map window shows the current state of the map and is where
436            the user can interact with the map using the tools.
437            </para>
438    
439            <para>
440            The legend on the left displays a list of the current layers and
441            any visible classification groups. In the example, each shape layer
442            has a default classification which specifies how the shapes in each
443            layer are drawn. Layers that are higher in the list appear
444            ``closer'' to the user. The legend can be closed by clicking on the
445            small X in the upper right-hand region of the legend.
446            To open it again, use
447            <menuchoice>
448            <guimenu>Map</guimenu>
449            <guimenuitem>Legend</guimenuitem>
450            </menuchoice>.
451            The legend is also dockable, which means that it can be detached
452            from the main window by clicking on the small button next to the
453            close button. It can be attached by clicking the same button
454            again.
455            </para>
456            <para>
457            The status bar displays different information depending on the
458            current context. If the user is selecting an item from the menu
459            then the status bar will display a short help message indicating
460            what each menu item is for. If the user has a tool selected then
461            the position of the cursor on the map is displayed.
462            </para>
463            <para>
464            The tool bar provides quick access to the commonly needed tools.
465            By hovering over each button the user can see a short messages
466            describing what the tool does. The tools provided are Zoom In, Zoom
467            Out, Pan, Full Extent, Full Layer Extent, Full Shape Extent, Identify,
468            and Label. Each of the tools will be explained in further detail later
469            in the manual.
470            </para>
471            </section>
472    
473      </chapter>
474    
475      <chapter><title>Session Management</title>
476    
477            <section><title>Starting a New Session</title>
478            <para>
479            A new session can be started from
480            <menuchoice>
481            <guimenu>File</guimenu>
482            <guimenuitem>New Session</guimenuitem>
483            </menuchoice>.
484            If a session is already loaded and has been modified without
485            being saved a prompt will ask if the current session should
486            be saved. A new session consists of an empty map with no
487            layers, no tables and no projection.
488            </para>
489            </section>
490    
491            <section><title>Opening a Session</title>
492            <para>
493            A session can be opened from
494            <menuchoice>
495            <guimenu>File</guimenu>
496            <guimenuitem>Open Session</guimenuitem>
497            </menuchoice>. A dialog box will open allowing the user to browse
498            for a Thuban Session file. Thuban session files end with
499            <varname>.thuban</varname>. Selecting a file a clicking
500            <guibutton>OK</guibutton> will load the session into Thuban.
501                    </para>
502    
503                    <para>
504            If a session is already loaded and has been modified without
505            being saved a prompt will ask if the current session should
506            be saved.
507            </para>
508                    
509                    <para>
510                    Thuban provides a path recovery feature: If a (shape) file referenced
511                    in a Thuban session cannot be found at the specified location, the user
512                    is prompted a file dialog. Here a new location can be selected for the
513                    currents layer data source. Cancelling the dialog removes the layer
514                    from the session. If a new location has been selected, Thuban checks
515                    this again, if further layers data sources are missing. The user is
516                    informed about this and can accept or cancel the suggestion.
517            </para>
518            </section>
519    
520            <section><title>Saving a Session</title>
521            <para>
522            A session can be saved from
523            <menuchoice>
524            <guimenu>File</guimenu>
525            <guimenuitem>Save Session</guimenuitem>
526            </menuchoice>.
527                    In the case the session is not a new and unsaved one,
528                    the corresponding file is updated with the current session
529                    data.
530                    In the case the current session is a new one and yet unsaved
531                    a dialog box will open allowing the user to browse
532            the file system and select a place to save the session. Thuban
533            sessions should be saved under a name ending in
534            <varname>.thuban</varname>. If the file already exists the user
535            will be prompted to save under a different name or overwrite the
536            existing file.
537            </para>
538            </section>
539    
540            <section><title>The Session Info-Tree</title>
541            <para>
542            <figure>
543            <title>Session Info Tree</title>
544            <mediaobject>
545            <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>
546            <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>
547            </mediaobject>
548            </figure>
549            </para>
550            <para>
551            The session info-tree is primarily intended for developers working
552            with Thuban. It displays many of the internal values for the session,
553            map, and layers. It can be opened from
554            <menuchoice>
555            <guimenu>File</guimenu>
556            <guimenuitem>Session Tree</guimenuitem>
557            </menuchoice>.
558            </para>
559            </section>
560      </chapter>
561    
562      <chapter><title>Map Management</title>
563        <para>
564        The map consists of a number of layers where each layer represents a
565        different type of data set. By interacting with the map the user can
566        visually explore the data.
567        </para>
568        <para>
569        The map can have a name that will appear in the Thuban title bar.
570        The map name can be changed using
571        <menuchoice>
572        <guimenu>Map</guimenu>
573        <guimenuitem>Rename</guimenuitem>
574        </menuchoice>.
575        </para>
576        <para>
577        <inlinemediaobject>
578        <imageobject>
579        <imagedata fileref="../images/3_rename_map.png" format="PNG" scale="&imgscale;"/>
580        </imageobject>
581        <imageobject>
582        <imagedata fileref="./images/3_rename_map.eps" format="EPS" scale="&imgscale;"/>
583        </imageobject>
584        <textobject> <phrase>Rename Map</phrase> </textobject>
585        </inlinemediaobject>
586        </para>
587    
588            <section><title>Adding and Removing Layers</title>
589            <para>
590            There are three types of layers that can be added to a map:
591            Shape layers, database layers
592            and image layers. Shape layers are stored in Shapefile format, a
593            widely used file format for storing geographic objects. These
594            files have the extension ``.shp''. Associated with
595            the shape file is a database file which stores attributes for
596            each shape in the Shape file. This file, in dBase format,
597            has the extension ``.dbf''. Both files must have the same base name.
598            For example, if there is a shape file named roads.shp there must
599            also be a file roads.dbf.
600            </para>
601            <itemizedlist>
602            <listitem>
603            <para>
604            Shape layers can be added to the map with
605            <menuchoice>
606            <guimenu>Map</guimenu>
607            <guimenuitem>Add Layer</guimenuitem>
608            </menuchoice>.
609            Initially, only the ``.shp'' files are shown which is enough for the
610                    selection. However, if you switch to display all files and select one
611                    of the associated files (e.g. ``.dbf''), Thuban will recognize the base
612                    name and load the corresponding Shape file.
613            </para>
614                    <para>
615                    The file dialog for Shape files allows to select multiple files.
616                    Use the shift-button together with the left mouse button to extend
617                    the selection.
618            </para>
619            </listitem>
620    
621            <listitem>
622            <para>Database layers can be added to the map with
623            <menuchoice>
624            <guimenu>Map</guimenu>
625            <guimenuitem>Add Database Layer</guimenuitem>
626            </menuchoice>.
627            A dialog with two lists is opened. The left list displays all
628            database connections currently open for the session. You can retrieve
629            a list of available layers from the selected database which is
630            displayed on the right hand. From this list one layer can be selected,
631            the dialog is closed afterwards.
632            </para>
633            <para>
634            See appendix ``Working with PostGIS'' for details.
635            </para>
636            </listitem>
637    
638            <listitem>
639            <para>
640            Image layers can be added to the map with
641            <menuchoice>
642            <guimenu>Map</guimenu>
643            <guimenuitem>Add Image Layer</guimenuitem>
644            </menuchoice>.
645            It is important to select a valid image file that has geographic
646            data associated with it. The data can be embedded in the file itself,
647            or in another file. If geographic information cannot be found, Thuban
648            will report an error.
649            </para>
650            </listitem>
651            </itemizedlist>
652            </section>
653    
654            <section><title>Navigation</title>
655            <para>
656            The map can be explored by using the navigation tools available on
657            the tool bar or from the
658            <menuchoice><guimenu>Map</guimenu></menuchoice> menu.
659            </para>
660            <itemizedlist>
661            <listitem>
662            <para>
663            The ZoomIn tool
664            <inlinemediaobject>
665            <imageobject>
666            <imagedata fileref="../images/3_2_zoomin.png" format="PNG" scale="&imgscale;"/>
667            </imageobject>
668            <imageobject>
669            <imagedata fileref="./images/3_2_zoomin.eps" format="EPS" scale="&imgscale;"/>
670            </imageobject>
671            <textobject> <phrase>ZoomIn Tool</phrase> </textobject>
672            </inlinemediaobject>
673            enlarges a region of the map. Clicking once on the map
674            will double the magnification and center the map on the point that
675            was clicked. Clicking and dragging selects a region that will be
676            enlarged to fit the window.
677            </para>
678            </listitem>
679            <listitem>
680            <para>
681            The ZoomOut tool
682            <inlinemediaobject>
683            <imageobject>
684            <imagedata fileref="../images/3_2_zoomout.png" format="PNG" scale="&imgscale;"/>
685            </imageobject>
686            <imageobject>
687            <imagedata fileref="./images/3_2_zoomout.eps" format="EPS" scale="&imgscale;"/>
688            </imageobject>
689            <textobject> <phrase>ZoomOut Tool</phrase> </textobject>
690            </inlinemediaobject>
691            shrinks the map so that a larger region is visible. A single click
692            reduces the magnification by a factor of two. Clicking and dragging
693            selects a box such that the current contents of the window will be
694            scaled to fit into that box.
695            </para>
696            </listitem>
697            <listitem>
698            <para>
699            The Pan tool
700            <inlinemediaobject>
701            <imageobject>
702            <imagedata fileref="../images/3_2_pan.png" format="PNG" scale="&imgscale;"/>
703            </imageobject>
704            <imageobject>
705            <imagedata fileref="./images/3_2_pan.eps" format="EPS" scale="&imgscale;"/>
706            </imageobject>
707            <textobject> <phrase>Pan Tool</phrase> </textobject>
708            </inlinemediaobject>
709            allows the user to move the map around by clicking and dragging.
710            </para>
711            </listitem>
712            <listitem>
713            <para>
714            The Full Extent tool
715            <inlinemediaobject>
716            <imageobject>
717            <imagedata fileref="../images/3_2_fullextent.png" format="PNG" scale="&imgscale;"/>
718            </imageobject>
719            <imageobject>
720            <imagedata fileref="./images/3_2_fullextent.eps" format="EPS" scale="&imgscale;"/>
721            </imageobject>
722            <textobject> <phrase>Full Extent Tool</phrase> </textobject>
723            </inlinemediaobject>
724            rescales the viewable region so that the entire map is visible.
725            </para>
726            </listitem>
727            <listitem>
728            <para>
729            The Full Layer Extent tool
730            <inlinemediaobject>
731            <imageobject>
732            <imagedata fileref="../images/3_2_fulllayerextent.png" format="PNG" scale="&imgscale;"/>
733            </imageobject>
734            <imageobject>
735            <imagedata fileref="./images/3_2_fulllayerextent.eps" format="EPS" scale="&imgscale;"/>
736            </imageobject>
737            <textobject> <phrase>Full Layer Extent Tool</phrase> </textobject>
738            </inlinemediaobject>
739            rescales the viewable region so that the currently selected
740            layer fits within the window. If no layer is selected this button
741            will be disabled.
742            </para>
743            </listitem>
744            <listitem>
745            <para>
746            The Full Shape Extent tool
747            <inlinemediaobject>
748            <imageobject>
749            <imagedata fileref="../images/3_2_fullshapeextent.png" format="PNG" scale="&imgscale;"/>
750            </imageobject>
751            <imageobject>
752            <imagedata fileref="./images/3_2_fullshapeextent.eps" format="EPS" scale="&imgscale;"/>
753            </imageobject>
754            <textobject> <phrase>Full Shape Extent Tool</phrase> </textobject>
755            </inlinemediaobject>
756            rescales the viewable region so that the currently selected
757            shape fits within the window. If the shape is a point, it is
758            centered and the map is zoomed all the way in. If no shape is
759            selected this button will be disabled. This feature is especially
760            helpful when identifying an object related to a selected record
761            in a tableview (see below).
762    
763            </para>
764            </listitem>
765            </itemizedlist>
766            </section>
767    
768            <section><title>Object Identification</title>
769            <para>
770            Objects on the map can be identified using the Identify tool
771            <inlinemediaobject>
772            <imageobject>
773            <imagedata fileref="../images/3_3_identify.png" format="PNG" scale="&imgscale;"/>
774            </imageobject>
775            <imageobject>
776            <imagedata fileref="./images/3_3_identify.eps" format="EPS" scale="&imgscale;"/>
777            </imageobject>
778            <textobject> <phrase>Identify Tool</phrase> </textobject>
779            </inlinemediaobject>.
780            Clicking on an object selects that object and opens a dialog which
781            shows all the table attributes for that object. Any current selection
782            is lost. Objects on the map are typically shapes and this document
783            will often refer to objects as shapes.
784            </para>
785            </section>
786    
787            <section><title>Object Labeling</title>
788            <para>
789            Objects can be labeled using the Label tool
790            <inlinemediaobject>
791            <imageobject>
792            <imagedata fileref="../images/3_3_label.png" format="PNG" scale="&imgscale;"/>
793            </imageobject>
794            <imageobject>
795            <imagedata fileref="./images/3_3_label.eps" format="EPS" scale="&imgscale;"/>
796            </imageobject>
797            <textobject> <phrase>Label Tool</phrase> </textobject>
798            </inlinemediaobject>.
799            Clicking on an object selects that object and opens a dialog which
800            displays the table attributes for that object. An attribute can
801            be selected to be the label on the map. The label will be placed
802            at the center of the shape. Clicking on an object that already has
803            a label will remove the label.
804            </para>
805            </section>
806    
807            <section><title>The Legend</title>
808            <para>
809            <inlinemediaobject>
810            <imageobject>
811            <imagedata fileref="../images/3_5_legend.png" format="PNG" scale="&imgscale;"/>
812            </imageobject>
813            <imageobject>
814            <imagedata fileref="./images/3_5_legend.eps" format="EPS" scale="&imgscale;"/>
815            </imageobject>
816            <textobject> <phrase>Legend</phrase> </textobject>
817            </inlinemediaobject>
818            </para>
819            <para>
820            The Legend provides an overview of the layers in the map. Layers
821            that appear higher in the legend will appear ``closer'' to the user.
822            If a layer supports classification (currently, only shape layers
823            have this feature) then the classification groups will be shown
824            below each layer. The properties for each group are also displayed
825            with a small graphic. Polygon layers appear as rectangles, lines
826            appear as curved lines, and points appear as circles.
827            </para>
828            <para>
829            Along the top of the legend is a toolbar which allows quick access
830            to some of the layer manipulation options under
831            <menuchoice><guimenu>Map</guimenu></menuchoice>.
832            </para>
833    
834            <itemizedlist>
835            <listitem>
836            <para>
837            The Move Layer to Top tool
838            <inlinemediaobject>
839            <imageobject>
840            <imagedata fileref="../images/3_5_totop.png" format="PNG" scale="&imgscale;"/>
841            </imageobject>
842            <imageobject>
843            <imagedata fileref="./images/3_5_totop.eps" format="EPS" scale="&imgscale;"/>
844            </imageobject>
845            <textobject> <phrase>Move Layer to Top</phrase> </textobject>
846            </inlinemediaobject> raises the selected layer to the top of the map.
847            </para>
848            </listitem>
849            <listitem>
850    
851            <para>
852            The Move Layer Up tool
853            <inlinemediaobject>
854            <imageobject>
855            <imagedata fileref="../images/3_5_moveup.png" format="PNG" scale="&imgscale;"/>
856            </imageobject>
857            <imageobject>
858            <imagedata fileref="./images/3_5_moveup.eps" format="EPS" scale="&imgscale;"/>
859            </imageobject>
860            <textobject> <phrase>Move Layer Up</phrase> </textobject>
861            </inlinemediaobject> raises the selected layer one level.
862            </para>
863            </listitem>
864            <listitem>
865    
866            <para>
867            The Move Layer Down tool
868            <inlinemediaobject>
869            <imageobject>
870            <imagedata fileref="../images/3_5_movedown.png" format="PNG" scale="&imgscale;"/>
871            </imageobject>
872            <imageobject>
873            <imagedata fileref="./images/3_5_movedown.eps" format="EPS" scale="&imgscale;"/>
874            </imageobject>
875            <textobject> <phrase>Move Layer Down</phrase> </textobject>
876            </inlinemediaobject> lowers the selected layer one level.
877            </para>
878    
879            </listitem>
880            <listitem>
881            <para>
882            The Move Layer to Bottom tool
883            <inlinemediaobject>
884            <imageobject>
885            <imagedata fileref="../images/3_5_tobottom.png" format="PNG" scale="&imgscale;"/>
886            </imageobject>
887            <imageobject>
888            <imagedata fileref="./images/3_5_tobottom.eps" format="EPS" scale="&imgscale;"/>
889            </imageobject>
890            <textobject> <phrase>Move Layer to Bottom</phrase> </textobject>
891            </inlinemediaobject> lowers the selected layer to the bottom of the map.
892            </para>
893    
894            </listitem>
895            <listitem>
896            <para>
897            The Visible tool
898            <inlinemediaobject>
899            <imageobject>
900            <imagedata fileref="../images/3_5_visible.png" format="PNG" scale="&imgscale;"/>
901            </imageobject>
902            <imageobject>
903            <imagedata fileref="./images/3_5_visible.eps" format="EPS" scale="&imgscale;"/>
904            </imageobject>
905            <textobject> <phrase>Visible</phrase> </textobject>
906            </inlinemediaobject> shows the selected layer in the map if it was
907            hidden.
908            </para>
909    
910            </listitem>
911            <listitem>
912            <para>
913            The Invisible tool
914            <inlinemediaobject>
915            <imageobject>
916            <imagedata fileref="../images/3_5_invisible.png" format="PNG" scale="&imgscale;"/>
917            </imageobject>
918            <imageobject>
919            <imagedata fileref="./images/3_5_invisible.eps" format="EPS" scale="&imgscale;"/>
920            </imageobject>
921            <textobject> <phrase>Invisible</phrase> </textobject>
922            </inlinemediaobject> hides the selected layer in the map.
923            </para>
924    
925            </listitem>
926            <listitem>
927            <para>
928            The Properties tool
929            <inlinemediaobject>
930            <imageobject>
931            <imagedata fileref="../images/3_5_props.png" format="PNG" scale="&imgscale;"/>
932            </imageobject>
933            <imageobject>
934            <imagedata fileref="./images/3_5_props.eps" format="EPS" scale="&imgscale;"/>
935            </imageobject>
936            <textobject> <phrase>Properties</phrase> </textobject>
937            </inlinemediaobject> opens the layer's properties dialog box.
938            Double-clicking on a layer or a group of a layer will open the
939            properties dialog for that layer.
940            </para>
941            </listitem>
942            </itemizedlist>
943    
944            <para>
945            The most used layer related actions are also available from a
946            popup menu. It is raised when a layer is clicked with the right mouse
947            button.
948            </para>
949            
950            <para>
951            <figure>
952            <title>Layer Popup Menu</title>
953            <mediaobject>
954            <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
955            <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
956            </mediaobject>
957            </figure>
958            </para>
959    
960            <para>
961            Along the bottom of the legend is the scalebar. The scalebar
962            will be available if there are any layers and the  map has a
963            projection set.
964            </para>
965            </section>
966    
967            <section><title>Exporting</title>
968            <para>
969            Under Windows, maps can be exported in Enhanced Metafile format
970            (<varname>.wmf</varname>)
971            from
972            <menuchoice>
973            <guimenu>Map</guimenu>
974            <guimenuitem>Export</guimenuitem>
975            </menuchoice> for use in reports, presentations, or further
976            modification. The current map view, legend, and, if available,
977            scalebar are exported. Under other platforms this option is not
978            available. Clicking this menu item open a file selection dialog
979            that lets the user select a location to export the map.
980            </para>
981            </section>
982    
983            <section><title>Printing</title>
984            <para>
985            The map can be printed using
986            <menuchoice>
987            <guimenu>Map</guimenu>
988            <guimenuitem>Print</guimenuitem>
989            </menuchoice>. The current map view, legend, and, if available,
990            scalebar are printed. A standard printing dialog will open allowing
991            the user to configure the printer. This dialog will differ depending
992            on which platform Thuban is running.
993            </para>
994            </section>
995    
996      </chapter>
997    
998      <chapter><title>Layer Management</title>
999        <para>
1000        </para>
1001    
1002            <section><title>Types of Layers</title>
1003            <para>
1004            There are three types of layers supported by Thuban: shape layers,
1005            database layers and
1006            image layers. Shape layers consist of vector based shapes with
1007            geo-referenced coordinates. There are three types of supported
1008            shapes: polygons, lines (arc), and points. Database layers are similar
1009            to shape layers but loaded from a database instead of the file system.
1010            Image layers can be any image
1011            file format supported by the Geo-spatial Data Abstraction Library
1012            (GDAL). The images must have geographic
1013            coordinate data either embedded within the file or in a separate
1014            file that is in the same directory as the image file. GeoTIFF files
1015            work very well with Thuban and were designed specifically to be image
1016            layers in GIS programs.
1017            </para>
1018            <para>
1019            All actions in the
1020            <menuchoice>
1021            <guimenu>Layer</guimenu>
1022            </menuchoice> menu act on the currently selected layer in the legend.
1023            </para>
1024            </section>
1025    
1026            <section><title>Properties</title>
1027            <para>
1028            To view the properties for a layer it must first be selected in the
1029            legend. The menu option
1030            <menuchoice>
1031            <guimenu>Layer</guimenu>
1032            <guimenuitem>Properties</guimenuitem>
1033            </menuchoice> opens a dialog that displays a layer's properties.
1034            All layers have a title which can be modified in the text field
1035            provided. The type of layer is also shows. If the type is a type
1036            of shape (polygon, arc, point) the classification table will be
1037            shown. Image layers have no other properties other than title
1038            and type.
1039            </para>
1040            <para>
1041            <figure>
1042            <title>Properties Window</title>
1043            <mediaobject>
1044            <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
1045            <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
1046            </mediaobject>
1047            </figure>
1048            </para>
1049            <para>
1050            <figure>
1051            <title>Properties Window</title>
1052            <mediaobject>
1053            <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
1054            <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
1055            </mediaobject>
1056            </figure>
1057            </para>
1058            </section>
1059    
1060            <section><title>Visibility</title>
1061            <para>
1062            Sometimes it is not desirable to view all layers at the same time.
1063            Some layers may take a long time to draw and so while navigating
1064            around the map the user may not want to wait for the map to redraw
1065            all the layers each time the map is changed. Each layer can be
1066            independently turned on or off using the
1067            <menuchoice>
1068            <guimenu>Layer</guimenu>
1069            <guimenuitem>Show</guimenuitem>
1070            </menuchoice>
1071            or
1072            <menuchoice>
1073            <guimenu>Layer</guimenu>
1074            <guimenuitem>Hide</guimenuitem>
1075            </menuchoice> options respectively.
1076            </para>
1077            </section>
1078    
1079            <section><title>Duplication</title>
1080            <para>
1081            Layers and all their properties, including classifications, can
1082            be duplicated using
1083            <menuchoice>
1084            <guimenu>Layer</guimenu>
1085            <guimenuitem>Duplicate</guimenuitem>
1086            </menuchoice>. Duplicating a layer is useful if the user wishes
1087            to model a layer in several different ways. Even though the layers
1088            overlap, by carefully selecting the shape properties it is possible
1089            to display several pieces of information at once. For example, one
1090            copy of a roads layer may be classified on a length property and
1091            another copy may be classified on a type property. If the length
1092            property was expressed with color and the type property expressed
1093            with line thickness then it would be possible to view both
1094            classifications by placing the type property copy over the
1095            length property copy.
1096            </para>
1097            </section>
1098    
1099      </chapter>
1100    
1101      <chapter><title>Layer Classifications</title>
1102        <para>
1103        A layer classification is a way of assigning drawing properties to
1104        groups of shapes based on attributes stored in the layer's table.
1105        Only layer's with shapes can have a classification; image layers
1106        cannot be classified.
1107        </para>
1108        <para>
1109        A classification consists of a number of groups, each group
1110        having a value or range of values to match against, and symbol
1111        properties which control how a shape is drawn on the map. The user
1112        selects which field in the table is used by the classification and
1113        when the map is drawn the value for that field for each shape is
1114        compared with each group's value. The properties of the first group
1115        to match are used to draw the shape. This allows the user to get a
1116        visual impression of not only how the data is laid out but also what
1117        kind of data lies where.
1118        </para>
1119        <para>
1120        A layer always has a classification. When a new layer is added to the
1121        map, a default classification is created with the DEFAULT group. This
1122        group cannot be removed but can be hidden (see below). Every shape in the
1123        layer, regardless of its attributes, will match this group if no other
1124        group matches.
1125        </para>
1126    
1127            <section><title>Editing Classifications</title>
1128            <para>
1129            A layer's classification can be modified under the properties dialog
1130            (<menuchoice>
1131            <guimenu>Layer</guimenu>
1132            <guimenuitem>Properties</guimenuitem>
1133            </menuchoice>). The layer's classification field can be set to None,
1134            which simply assigns a DEFAULT group to the classification. No new
1135            groups can be added to the classification if the field is None.
1136            The user must first select a field to classify on. New groups can
1137            be added to the classification with the <guibutton>Add</guibutton>
1138            button.
1139            </para>
1140            <para>
1141            To apply the changes to the map the user can click
1142            either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
1143            <guibutton>Try</guibutton> will not close the dialog box, allowing
1144            the user to see how the classification changes the map.
1145            <guibutton>Revert</guibutton> will undo the last classification applied
1146            to the map. <guibutton>OK</guibutton> will commit the changes and
1147            close the dialog. The user will be unable to undo the changes.
1148            <guibutton>Close</guibutton> simply closes the dialog box. If any
1149            changes have not been applied with <guibutton>Try</guibutton> the
1150            changes will not be applied to the map.
1151            </para>
1152            <para>
1153            <figure>
1154            <title>Properties Window</title>
1155            <mediaobject>
1156            <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>
1157            <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>
1158            </mediaobject>
1159            </figure>
1160            </para>
1161            <para>
1162            The order of the groups in the classification is significant
1163            except for the DEFAULT group, which remains at the top. When shapes
1164            are matched against groups the matching begins at the first group
1165            after the DEFAULT group so that groups higher in the list will
1166            be checked first. Matching for a
1167            given shape will stop at the first group that matches. The user can
1168            use <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton>
1169            to change the order of the groups. The DEFAULT group will always
1170            match a shape that hasn't matched another group.
1171            </para>
1172                <section><title>Visible</title>
1173                <para>
1174                The Visible column has check-boxes that determine whether a
1175                classification group will be displayed in the legend. This is
1176                useful if the user knows that the groups completely cover
1177                the data set and don't want the DEFAULT group to be displayed
1178                in the legend and on a printout.
1179                </para>
1180            </section>
1181                <section><title>Symbols</title>
1182                <para>
1183                Each type of shape has its own type of symbol. Thuban supports three
1184                types of shapes: polygons, lines, and points. Polygons and points
1185                have outline and fill color, while lines have only line color. Each
1186                group has associated symbol properties. To edit the symbol
1187                properties for a group the user can double click on the Symbol
1188                column or select a group and click the
1189                <guibutton>Edit Symbol</guibutton> button.
1190                </para>
1191                </section>
1192            <section><title>Value</title>
1193                <para>
1194                The Value column of the classification table is the value that will
1195                be matched when the map is being drawn. The type of filter that can
1196                entered into this field depends on the type of data of the
1197                classification field:
1198                </para>
1199                <para>
1200                If the field is of type Text, anything entered
1201                into the field is valid. By default the text will be compared
1202                literally to the
1203                value of the shape attribute, including case sensitivity.
1204                Alternatively the comparison can be based on regular experessions.
1205                Right-click on the row label to open a popup menu with the options
1206                <guibutton>Singleton</guibutton> (literal comparison) and  
1207                <guibutton>Pattern</guibutton> (regular expressions).  
1208                </para>
1209                <para>
1210                If the type is Integer, then any valid integer may be entered. In
1211                addition, with special syntax, a range of values can be entered.
1212                A range from <varname>start</varname> to <varname>end</varname>
1213                inclusive is specified like this: <literal>[start;end]</literal>.
1214                The exclusive range is specified like this:
1215                <literal>]start;end[</literal>. Ranges can include infinity like
1216                this: <literal>[-oo;oo]</literal>. Field types can also be of type
1217                Decimal. They represent any rational number and can be used in
1218                ranges as well.
1219                </para>
1220           </section>
1221                <section><title>Label</title>
1222                <para>
1223                By default, the text that is displayed for a group in the legend
1224                is the value for that group. The label can substitute a more
1225                descriptive term in the legend.
1226                </para>
1227            </section>
1228            </section>
1229    
1230            <section><title>Generating Classes</title>
1231            <para>
1232            <figure>
1233            <title>Generate Class</title>
1234            <mediaobject>
1235            <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>
1236            <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>
1237            </mediaobject>
1238            </figure>
1239            </para>
1240            <para>
1241            Creating a classification by hand can be tedious.
1242            Thuban, therefore, provides a means of generating an entire
1243            classification at once while still giving the user control over
1244            how it appears. Clicking <guibutton>Generate Class</guibutton>
1245            opens the <varname>Generate Classification</varname> dialog.
1246            Under the <varname>Generate</varname> pull down there are at most
1247            three different ways to generate classifications:
1248            Unique Values, Uniform Distribution, and Quantiles. Some options
1249            may not be available if the data type for the field does not
1250            support them. For instance, <varname>Uniform Distribution</varname>
1251            doesn't make sense for a Text field.
1252            </para>
1253            <para>
1254            For every way of generating a classification, a color scheme must
1255            be selected. Thuban provides several different color schemes that
1256            affect how the group properties change over the classification.
1257            It may be desirable that only certain properties change over the
1258            classification. If the shape type is a polygon or a point then
1259            the <guibutton>Fix Border Color</guibutton> option will be available.
1260            This allows the user to select a border color for all classification
1261            groups.
1262            It is also possible to create a custom color scheme. Selecting
1263            this option will display two symbols: the one of the left has the
1264            properties of the first group and the one on the right has the
1265            properties of the last group. Thuban will interpolate between these
1266            two properties to generate the other groups.
1267            <figure>
1268            <title>Custom Color Scheme</title>
1269            <mediaobject>
1270            <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>
1271            <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>
1272            </mediaobject>
1273            </figure>
1274            </para>
1275            <para>
1276            The Unique Values option lets the user select specific values that
1277            appear in the table. Clicking <guibutton>Retrieve From Table</guibutton>
1278            searches the table for all unique values and displays them in the
1279            list on the left. Items can be selected and moved to the list on the
1280            right. Each list can be sorted or reversed for easier searching.
1281            The classification that is generated will be in the same order as
1282            the list on the right.
1283            <figure>
1284            <title>Unique Values</title>
1285            <mediaobject>
1286            <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>
1287            <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>
1288            </mediaobject>
1289            </figure>
1290            </para>
1291            <para>
1292            The Uniform Distribution option creates a user specified number of
1293            groups of ranges such that each range covers equal intervals. The
1294            minimum and maximum values can automatically be retrieved from the
1295            table by clicking <guibutton>Retrieve From Table</guibutton>. The
1296            stepping is how large each interval is. Adjusting this value will
1297            automatically recalculate how many groups is appropriate.
1298            <figure>
1299            <title>Uniform Distribution</title>
1300            <mediaobject>
1301            <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>
1302            <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>
1303            </mediaobject>
1304            </figure>
1305            </para>
1306            <para>
1307            The Quantiles option generates ranges based on the number of items
1308            in the table. For example, by specifying five groups Thuban will
1309            generate five groups with appropriate ranges such that 20% of the table
1310            data is in each group. If it is impossible to generate exact
1311            groupings, Thuban will issue a warning but allow the user to continue.
1312            <figure>
1313            <title>Quantiles</title>
1314            <mediaobject>
1315            <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>
1316            <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>
1317            </mediaobject>
1318            </figure>
1319            </para>
1320            </section>
1321      </chapter>
1322    
1323      <chapter><title>Projection Management</title>
1324        <para>
1325        Projections control how the geographic data is displayed on the screen.
1326        If multiple layers are loaded into Thuban where the geographic data
1327        is in a different projection system, then the user must specify a
1328        projection for each layer. The user must also tell Thuban which
1329        projection the map is in. This can be the same as the layers or a different
1330        projection in which case the layers are reprojected into that space.
1331        The map projection can be set using
1332        <menuchoice>
1333        <guimenu>Map</guimenu>
1334        <guimenuitem>Projection</guimenuitem>
1335        </menuchoice> and the layer projection can be set using
1336        <menuchoice>
1337        <guimenu>Layer</guimenu>
1338        <guimenuitem>Projection</guimenuitem>
1339        </menuchoice>.
1340        <figure>
1341        <title>Projection Window</title>
1342        <mediaobject>
1343        <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>
1344        <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>
1345        </mediaobject>
1346        </figure>
1347        </para>
1348        <para>
1349        Thuban is distributed with a sample collection of projections and the
1350        set of coordinate systems as used by the EPSG
1351        (European Petroleum Survey Group). This quite large set is only displayed
1352        if activated by the according checkbox. The set falls into two parts:
1353        deprecated lists all projections which are no longer part of the
1354        EPSG data base.
1355        </para>
1356        <para>
1357             The
1358        user can create new projections and make them available to all
1359        future Thuban sessions. They may also be exported and imported so
1360        that custom projections can be distributed.
1361        </para>
1362            <section><title>Selecting a Projection</title>
1363            <para>
1364            The available projections are listed on the left. If the layer
1365            or map already has a projection it will initially be highlighted
1366            and will end with <varname>(current)</varname>. Selecting
1367            <varname>&lt;None&gt;</varname> will cause Thuban to use the data as
1368            it appears in the source file and will not use a projection.
1369            </para>
1370        </section>
1371            <section><title>Editing a Projection</title>
1372            <para>
1373            Whenever a projection is selected from the list its properties
1374            are displayed on the right. These properties can be changed
1375            and the changes saved to the selected projection using
1376            <guibutton>Update</guibutton>. Only a projection that comes
1377            from a file can be updated, so if the current layer's projection
1378            is selected, <guibutton>Update</guibutton> will be disabled.
1379            <guibutton>Add to List</guibutton> adds the projection to the
1380            list of available projections as a new entry, and thus makes it
1381            available to future Thuban sessions. Clicking <guibutton>New</guibutton>
1382            will create an entirely new, empty projection. The
1383            <guibutton>Remove</guibutton> button will permanently remove a
1384            projection from the list of available projections.
1385            </para>
1386            <para>
1387            To apply the selected projection to the map the user can click
1388            either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
1389            <guibutton>Try</guibutton> will not close the dialog box, allowing
1390            the user to see how the projeciton changes the map.
1391            <guibutton>Revert</guibutton> will undo the last projection applied
1392            to the map. <guibutton>OK</guibutton> will commit the changes and
1393            close the dialog. The user will be unable to undo the changes.
1394            <guibutton>Close</guibutton> simply closes the dialog box. If no
1395            selection has been applied with <guibutton>Try</guibutton> the
1396            selection will not be applied to the map.
1397            </para>
1398        </section>
1399            <section><title>Importing/Exporting Projections</title>
1400            <para>
1401            The projections that appear in the list of available projections
1402            can be exported to another file that the user chooses. By selecting
1403            one or more projections and clicking <guibutton>Export</guibutton>
1404            the user will be able to select a file in which to store those
1405            projections.
1406            The file can then be distributed to other Thuban users. To import
1407            a projection file the user can click <guibutton>Import</guibutton>.
1408            The imported projections are added to the list and are then available
1409            to the current session and any future Thuban sessions.
1410            </para>
1411        </section>
1412      </chapter>
1413    
1414      <chapter><title>Table Management</title>
1415        <para>
1416        Thuban distinguishes two different types of tables: Attribute tables
1417        (which belong to a layer) and normal data tables. Both provide
1418            the same general functionality with the difference that actions on an
1419        attribute table might also effect the map display.
1420      </para>      </para>
1421    
1422        <section><title>Table View</title>
1423            <para>
1424            <figure>
1425            <title>Table View</title>
1426            <mediaobject>
1427            <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>
1428            <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>
1429            </mediaobject>
1430            </figure>
1431            </para>
1432            <para>
1433            Thuban provides a standard dialog to display table contents, the
1434            Table View. The view has five sections: The title, selections,
1435            the table grid, export functions, and the status bar.
1436            </para>
1437            <para>
1438            The title bar identifies the table with its name.
1439            </para>
1440            <para>
1441            The selections box let the user perform simple analysis on the data
1442            based on comparisons: The first choice must be a field identifier of
1443            the table, the second choice determines the type of comparison. The
1444            third choice can be either a specific value (interpreted as numerical
1445            or string depending on the type of the first field) or a second field
1446            identifier. Thus you can perform analysis like selecting all
1447            records where <literal>population > 10000</literal> or
1448            <literal>cars_per_inhabitant < bikes_per_inhabitant</literal>
1449            (note that the field names are only explanatory, the dBase files
1450            allow only 11 character field names).
1451          
1452            Selections can be combined either by applying a selection only on
1453            a previously selected set of records or by adding the results of a
1454            selection to a previous set. The default is that a selection replaces
1455            earlier results.
1456            </para>
1457            <para>
1458            The table grid shows the contents of the table (one record per row),
1459            with highlighted selection results. Columns and rows can be resized.
1460            </para>
1461            <para>
1462            The contents of a table can be exported into a file, either dBase
1463            format (DBF) or comma separated values (CSV). The
1464            <guibutton>Export</guibutton> button
1465            raises a file dialog to specify a path and file name, the export type
1466            is determined by the file extension (either .dbf or .csv).
1467    
1468            The <guibutton>Export Selection</guibutton> button works similarly
1469            but exports only the selected records.
1470    
1471            The <guibutton>Close</guibutton> button closes the table view window.
1472            This is different from the menu item
1473            <menuchoice>
1474            <guimenu>Table</guimenu>
1475            <guimenuitem>Close</guimenuitem>
1476            </menuchoice> which unloads the table from Thuban.
1477            </para>
1478            <para>
1479            The status bar displays some statistics about the table and optional
1480            selection results.
1481            </para>
1482        </section>
1483    
1484        <section><title>General Functionality (Menu Table)</title>
1485            <para>
1486            The general functions affect all tables open in Thuban. Attribute
1487            tables are considered here as normal data tables (with the exception
1488            that they cannot be closed).
1489            </para>
1490            <section><title>Open</title>
1491                <para>
1492                The
1493                <menuchoice>
1494                <guimenu>Table</guimenu>
1495                <guimenuitem>Open</guimenuitem>
1496                </menuchoice>
1497                item raises a file dialog to let you select a
1498                dBase file from the file system to be loaded into Thuban read-only.
1499                On <guibutton>OK</guibutton> the selected file is loaded and a
1500                table view is opened.
1501                </para>
1502            </section>
1503    
1504            <section><title>Close</title>
1505                <para>
1506                The
1507                <menuchoice>
1508                <guimenu>Table</guimenu>
1509                <guimenuitem>Close</guimenuitem>
1510                </menuchoice>
1511                item raises a dialog listing the currently open
1512                data tables
1513                (loaded via
1514                <menuchoice>
1515                <guimenu>Table</guimenu>
1516                <guimenuitem>Open</guimenuitem>
1517                </menuchoice>). Selected tables are dereferenced on confirmation.
1518                Since tables are opened read-only the contents of the tables are
1519                not affected.
1520    
1521                Any open views of the tables are closed as well.
1522    
1523                Tables used in a join cannot be closed.
1524                </para>
1525            </section>
1526    
1527            <section><title>Rename</title>
1528                <para>
1529                <menuchoice>
1530                <guimenu>Table</guimenu>
1531                <guimenuitem>Rename</guimenuitem>
1532                </menuchoice> changes the table title.
1533                </para>
1534            </section>
1535    
1536            <section><title>Show</title>
1537                <para>
1538                The
1539                <menuchoice>
1540                <guimenu>Table</guimenu>
1541                <guimenuitem>Show</guimenuitem>
1542                </menuchoice>
1543                item raises a list of available tables (explicitly
1544                loaded, attribute tables, results of a join). Selected tables are
1545                show in tables views on <guibutton>OK</guibutton>.
1546                </para>
1547            </section>
1548    
1549            <section><title>Join</title>
1550                <para>
1551                <figure>
1552                <title>Join Tables</title>
1553                <mediaobject>
1554                <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>
1555                <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>
1556                </mediaobject>
1557                </figure>
1558                </para>
1559                <para>
1560                The
1561                <menuchoice>
1562                <guimenu>Table</guimenu>
1563                <guimenuitem>Join</guimenuitem>
1564                </menuchoice>
1565                item raises a dialog to specify the two tables to be
1566                joined. The join results in a new table named 'Join of "left table"
1567                and "right table"'.
1568    
1569                The dialog lets you select the two tables to be joined and the two
1570                fields the join has to be performed on. By default, the new
1571                table contains only those records which are matched by the join.
1572    
1573                If you want to preserve the records of the left table you can
1574                perform an outer join. The fields from the right table for records
1575                not matched by the join are filled with <varname>None</varname> in
1576                this case.
1577                </para>
1578            </section>
1579    
1580        </section>
1581        <section><title>Attribute Tables</title>
1582            <para>
1583                To clearly separate between both types of tables (data and
1584            attribute), Thuban provides functionality regarding the attribute
1585            tables under the <menuchoice><guimenu>Layer</guimenu></menuchoice> menu.
1586            </para>
1587    
1588            <section><title>Show Table</title>
1589                <para>
1590                <menuchoice>
1591                <guimenu>Layer</guimenu>
1592                <guimenuitem>Show Table</guimenuitem>
1593                </menuchoice>
1594                opens the attribute table of the currently active layer in a table
1595                view.
1596    
1597                In addition to the functionality described above selections
1598                affect also the map display: objects related to selected records
1599                are highlighted.
1600                </para>
1601            </section>
1602    
1603            <section><title>Join Table</title>
1604                <para>
1605                Unlike the join described above, the join does not result in a
1606                new table. The attribute table of the currently active layer is the
1607                left table and other tables are joined to this table. The results of
1608                the join are available for classification.
1609    
1610                As a consequence, the join cannot result in fewer
1611                records than the source attribute table. The user is warned if the
1612                right table does not fulfill this constraint. An outer join must be
1613                used in such cases.
1614                </para>
1615            </section>
1616    
1617            <section><title>Unjoin Table</title>
1618                <para>
1619                As said above, a normal table cannot be closed while it is still
1620                used in a join. While the joined table resulting from a join of
1621                normal tables can be simply closed (and thereby dereferencing
1622                the source tables), this is not possible for attribute tables.
1623    
1624                Hence joins on attribute tables must be solved explicitly. This is
1625                what the
1626                <menuchoice>
1627                <guimenu>Layer</guimenu>
1628                <guimenuitem>Unjoin Table</guimenuitem>
1629                </menuchoice>
1630                item is used for: The last join for the currently
1631                active layer is solved.
1632                </para>
1633            </section>
1634        </section>
1635      </chapter>
1636    
1637      <chapter><title>Extensions</title>
1638            <para>
1639            Thuban is designed to be extensible. The term Extension is used as a
1640            general term for anything that extends Thuban.
1641            This chapter introduces into some oppportunities how to add and
1642            handle extra functionality developed by your own or third parties.
1643            </para>
1644    
1645            <section><title>Add personal extensions via thubanstart.py</title>
1646                    <para>
1647                    After Thuban has been started for the first time, a directory
1648                    .thuban is created within your home directory.
1649                    There you can add a file thubanstart.py  which will be imported
1650                    by Thuban at start-up. It is recommended to add only import-statements
1651                    to this file to keep the actual code of extensions separate.
1652                    </para>
1653                    <para>
1654                    The modules to import must either be found through the environment
1655                    variable PYTHONPATH or directly be placed into the .thuban-directory.
1656                    </para>
1657                    <para>
1658                    As an example, copy the file examples/simple_extensions/hello_world.py
1659                    of the Thuban source code into the .thuban-directory of your home
1660                    directory. Now add add the statement import hello_world to the
1661                    file thubanstart.py and run Thuban. You will notice an additional
1662                    menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
1663                    the new item for the Hello-World extension is placed - select it
1664                    to see the Hello-World message.
1665                    </para>
1666            </section>
1667    
1668            <section><title>Extensions included in Thuban package</title>
1669                    <para>
1670                    The extensions described in this section are part of the
1671                    Thuban package, but not activated by default.
1672                    You will find them in the Thuban installation directory
1673                    under <literal>Extensions/</literal>. Activate them as personal
1674                    extensions via PYTHONPATH as described in the previous section.
1675                    Stable extensions will appear under the menu
1676                    <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
1677                    extensions which are in experimental state and therefore
1678                    not fully functional under
1679                    <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
1680                    </para>
1681    
1682                    <section><title>Stable extensions</title>
1683                        <para>
1684                        These extensions provide extra-functionality to Thuban
1685                        that has not (yet) been integrated in the main application.
1686                        They are considered to be free of bugs, but may be
1687                        further polished with helpful user interactions.
1688                        </para>
1689                        <section><title>gns2shp</title>
1690                                    <para>
1691                                    This tool converts data of the Geospatial Names Server
1692                                    (GNS, see <ulink url="http://www.nima.mil/gns"/>)
1693                                    into Shapefile format.
1694                                    The above web-site offer to download named places
1695                                    information grouped by countries for all of the world
1696                                    except USA for which other data are provided.
1697                                    </para>
1698                                    <para>
1699                                    If you download and unpack a package, you will have
1700                                    a text-file with suffix .txt.
1701                                    Selecting such a file via gns2shp will create the
1702                                    corresponding Shapefile with the same basename and
1703                                    place it in the same direcory. Afterwards it
1704                                    is automatically loaded into Thuban.
1705                                    The Shapefile will not automatically be delete afterwards.
1706                                    </para>
1707                                    <para>
1708                                    The gns2shp.py module can also be executed on the
1709                                    command line for batch processing purposes.
1710                                    </para>
1711                                    <para>
1712                                    A sample (<literal>ls.txt</literal> for Liechtenstein)
1713                                    is included in the directory
1714                                    <literal>Extensions/gns2shp/test</literal>.
1715                                    </para>
1716                        </section>
1717                        <section><title>SVG Export</title>
1718                            <para>
1719                            Map and legend can be exported separately in the
1720                            Thuban-Map-SVG format.
1721                            You get files that comply with
1722                            the Scalable Vector Graphics (SVG) 1.1 Specification
1723                            and can be read by many vector drawing applications.
1724                            </para>
1725                            <para>
1726                            Goal of svgexport is to provide
1727                            the start of a printing pipeline for Thuban.
1728                            For this purpose the written Thuban-Map-SVG files
1729                            contain information that can be used in postprocessing.
1730                            Typically a general vector drawing application is
1731                            more powerful then a geographic information viewer;
1732                            e.g. having much fancier symbols and fonts.
1733                            Also users benefit much more when learning to use a
1734                            more general application they can also use for other
1735                            tasks.  So the charming idea is to enable
1736                            the drawing application to postprocess a Thuban maps.
1737                            So thee xtra information in the format will make it
1738                            possible to export from Thuban and if a few geoobjects
1739                            change, and keep the general layout and style
1740                            of the full map in the vector drawing appplication.
1741                            </para>
1742                            <para>
1743                            Markus Rechtien has developed a prototype of this
1744                            printing pipline as his Diplom thetis, showing
1745                            the feasability of Bernhard Reiter's concept.
1746                            Scripts exist for the drawing application Skencil
1747                            (<ulink url="http://www.skencil.org"/>).
1748                            </para>
1749                            <para>
1750                            Technical notes: the names of the layers are used
1751                            as base for ids within the SVG format.
1752                            If you try to export with two layers having
1753                            the same name, you will get a name clash error.
1754                            Just change one of the layer names and try again.
1755                            </para>
1756                        </section>
1757                    </section>
1758                    <section><title>Experimental extensions</title>
1759                            <para>
1760                            All all of these functions have to be handled with care,
1761                            since they are neither complete nor well tested.
1762                            They are to be seen as a proof-of-concept and may
1763                            additionally in some cases of practical help.
1764                            </para>
1765                            <para>
1766                            Any interest on further improvement of these extensions
1767                            should be communicated towards the developer and user
1768                            community.
1769                            </para>
1770    
1771                            <section><title>importAPR</title>
1772                                    <para>
1773                                    This command offer to load an ESRI� ArcView� project
1774                                    file (suffix .apr) and convert it for use within Thuban.
1775                                    After selecting a apr-file to load, a list
1776                                    will be presented that offers to select one of the views
1777                                    of the apr-file, provided there is more than one.
1778                                    Furthermore, the Session Info-Tree is extended with
1779                                    a complete representation of the parsed apr-file.
1780                                    </para>
1781                                    <para>
1782                                    The legend of Thuban does not yet cover all of the elements as
1783                                    supported by the legend of ArcView�. Therefore, the Thuban
1784                                    map will look different. Furthermore, the apr-format is
1785                                    a proprietary format, not openly documented.
1786                                    Therefore, the interpretation is
1787                                    partly based on reverse engeneering and good guessing.
1788                                    </para>
1789                                    <para>
1790                                    The file-paths within the apr-file may not fit and potentially
1791                                    are subject to fix in the apr-file. You can do this
1792                                    applying any text editor. The paths are either absolute
1793                                    or relative from where Thuban has been started.
1794                                    </para>
1795                                    <para>
1796                                    A sample for the Iceland data is included as
1797                                    <literal>Extensions/importAPR/samples/iceland.apr</literal>.
1798                                    The file-paths are relative from the Thuban main directory.
1799                                    </para>
1800                            </section>
1801                    </section>
1802            </section>
1803    
1804            <section><title>Writing simple extensions</title>
1805                    <para>
1806                    Writing an extension for Thuban basically means to
1807                    implement the extra functionality in Python with all of the
1808                    Thuban classes, methods and variables available.
1809                    </para>
1810                    <para>
1811                    All classes and their methods are documented in the source code
1812                    (see their doc-strings). Here is an example from
1813                    Thuban/Model/layer.py that describes some of the methods
1814                    of a Layer object:
1815                    </para>
1816                    <programlisting>
1817                    <![CDATA[
1818    class BaseLayer(TitledObject, Modifiable):
1819    
1820        """Base class for the layers."""
1821    
1822        def __init__(self, title, visible = True, projection = None):
1823            """Initialize the layer.
1824    
1825            title -- the title
1826            visible -- boolean. If true the layer is visible.
1827            """
1828            TitledObject.__init__(self, title)
1829            Modifiable.__init__(self)
1830            self.visible = visible
1831            self.projection = projection
1832    
1833        def Visible(self):
1834            """Return true if layer is visible"""
1835            return self.visible
1836    
1837        def SetVisible(self, visible):
1838            """Set the layer's visibility."""
1839            self.visible = visible
1840            self.issue(LAYER_VISIBILITY_CHANGED, self)
1841    
1842        def HasClassification(self):
1843            """Determine if this layer support classifications."""
1844    ...
1845                    ]]>
1846                    </programlisting>
1847                    <para>
1848                    This example intends to give you an impression of the
1849                    source-code-level documentation.
1850                    You have to make yourself familiar with
1851                    the Python programming language to understand some special
1852                    code elements.
1853                    </para>
1854                    <section><title>hello_world.py</title>
1855                      <para>
1856                      Traditionally, the first example should welcome the world.
1857                      Most of the code handles the frame for integrating a menu
1858                      item into Thuban while the actual raising of a message
1859                      is done in a single line.
1860                      </para>
1861                            <programlisting>
1862                            <![CDATA[
1863    # Copyright (C) 2003 by Intevation GmbH
1864    # Authors:
1865    # Jan-Oliver Wagner <[email protected]>
1866    #
1867    # This program is free software under the GPL (>=v2)
1868    # Read the file COPYING coming with Thuban for details.
1869    
1870    """
1871    Extend Thuban with a sample Hello World to demonstrate simple
1872    extensions.
1873    """
1874    
1875    __version__ = '$Revision$'
1876    
1877    # use _() already now for all strings that may later be translated
1878    from Thuban import _
1879    
1880    # Thuban has named commands which can be registered in the central
1881    # instance registry.
1882    from Thuban.UI.command import registry, Command
1883    
1884    # The instance of the main menu of the Thuban application
1885    # See Thuban/UI/menu.py for the API of the Menu class
1886    from Thuban.UI.mainwindow import main_menu
1887    
1888    def hello_world_dialog(context):
1889        """Just raise a simple dialog to greet the world.
1890    
1891        context -- The Thuban context.
1892        """
1893        context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
1894    
1895    
1896    # create a new command and register it
1897    registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
1898                         helptext = _('Welcome everyone on this planet')))
1899    
1900    # find the extensions menu (create it anew if not found)
1901    extensions_menu = main_menu.FindOrInsertMenu('extensions', _('E&xtensions'))
1902    
1903    # finally bind the new command with an entry in the extensions menu
1904    extensions_menu.InsertItem('hello_world')
1905                            ]]>
1906                            </programlisting>
1907                    </section>
1908                    <section><title>Registering a Command</title>
1909                      <para>
1910                      Mainly, our new function has to be registered to the Thuban
1911                      framework in order to connect it to the menu. A registered
1912                      command can also be connected to e.g. a toolbar button.
1913                      </para>
1914                      <para>
1915                      The instances and classes for this are imported at the beginning.
1916                      Any code not inside a method or class is directly executed when
1917                      the source-code module is imported. Therefore, the second
1918                      part of this example consist of the plain statements to create a new
1919                      Command and to add it to the menu.
1920                      </para>
1921                      <para>
1922                      By convention, it looks for a menu registered as ``extensions'' to
1923                      insert the new command. If it does not exist yet, it gets created.
1924                      It is advisable to copy this code for any of your extensions.
1925                      </para>
1926                    </section>
1927                    <section><title>The Thuban context</title>
1928                            <para>
1929                            A registered command that is called, always receives the
1930                            Thuban context. This instance provides our method with
1931                            hook references to all important components of the Thuban
1932                            application.
1933                            </para>
1934                            <para>
1935                    In the example hello_world.py, our function uses the
1936                            mainwindow component which offers a method to raise a
1937                            message dialog. In total there are three hooks:
1938                            <itemizedlist>
1939                            <listitem>
1940                            <para>application:
1941                            This object is the instance of the Thuban Application class.
1942                            Except maybe for loading or savinf sessions, you will not
1943                            need this object for a simple extension.
1944                            See Thuban/UI/application.py for the API.
1945                            </para>
1946                            </listitem>
1947                            <listitem>
1948                            <para>session:
1949                            The instance of the current session. It manages the sessions'
1950                            map and tables. You can set and remove the map or tables.
1951                            In may also get the map object. However, you should know that
1952                            internally it is already prepared to handle many maps.
1953                            Therfore, currently you would always receive a list with exactlty
1954                            one element. In the future, if there are more than one map,
1955                            you will not know which one is the currently display one and
1956                            therefore you should use the mainwindow as hook to find
1957                            the currently displayed map.
1958                            See Thuban/Model/session.py for the API.
1959                            </para>
1960                            </listitem>
1961                            <listitem>
1962                            <para>
1963                            mainwindow: The mainwindow object is central to manage various
1964                            GUI things such as the Legend sub-window. Most notably,
1965                            you get access to the canvas which is the window part where
1966                            the map is drawn. The canvas knows, which map it currently
1967                            draws and therefore you get the current map via
1968                            context.mainwindow.canvas.Map().
1969                            See Thuban/UI/mainwindow.py for the API.
1970                            </para>
1971                            </listitem>
1972                            </itemizedlist>
1973                </para>
1974                    </section>
1975            </section>
1976    </chapter>    </chapter>
1977    
1978      <chapter><title>Trouble Shooting</title>
1979        <para>
1980        Here are a few problems that users have encountered when first using Thuban.
1981        </para>
1982        <para>
1983    
1984        <itemizedlist>
1985        <listitem>
1986        <para>After adding two or more layers nothing is drawn in the map window.
1987        </para>
1988        <para>
1989        This is probably because the layers have different projections. Projections
1990        must be set on all layers and on the map itself if the layers' projections
1991        are different.
1992        </para>
1993        </listitem>
1994    
1995        <listitem>
1996        <para>Thuban crashes on startup with the error
1997            <literal>NameError: global name 'False' is not defined</literal>.
1998        </para>
1999        <para>
2000        <varname>True</varname> and <varname>False</varname> were only introduced
2001        in Python 2.2.1. Thuban depends on at least Python 2.2.1.
2002        </para>
2003        </listitem>
2004    
2005        <listitem>
2006        <para>After compiling Thuban, Thuban crashes with an error similar to
2007            <literal>
2008            ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0
2009            </literal>
2010        </para>
2011        <para>
2012        Thuban depends on the wxWindows library. If Thuban is compiled with an
2013        incompatible version of the compiler than wxWindows was compiled with
2014        this error may occur. Try compiling with a different version of the
2015        compiler.
2016        </para>
2017        </listitem>
2018        </itemizedlist>
2019        </para>
2020        <para>
2021        If an error occurs Thuban will display a dialog indicating the error
2022        before closing. The text should be copied and reported to the
2023        <ulink url="http://thuban.intevation.org/bugtracker.html">
2024        Intevation bugtracker
2025        </ulink>.
2026        More information about the system is available from
2027        <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.
2028        This should also be included in the bug report.
2029        <figure>
2030        <title>Error Dialog</title>
2031        <mediaobject>
2032        <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>
2033        <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>
2034        </mediaobject>
2035        </figure>
2036        </para>
2037    
2038      </chapter>
2039    
2040      <appendix><title>Supported Data Sources</title>
2041        <para>
2042        </para>
2043        <variablelist>
2044        <varlistentry>
2045        <term>Shapefile</term>
2046        <listitem>
2047            <para>
2048            The Shapefile format has become a standard format for saving
2049            geographic vector information. It supports polygons, lines, and
2050            points.
2051            
2052            <ulink url="http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf">
2053            Technical Specification.
2054            </ulink>  
2055            </para>
2056        </listitem>
2057        </varlistentry>
2058    
2059        <varlistentry>
2060        <term>dBase file</term>
2061        <listitem>
2062            <para>
2063            dBase files are used to store the attributes for each layer. This
2064            is closely associated with the Shapefile format. For detailed
2065            specifications on the correct format of a dBase file used with
2066            Thuban please see the Technical Specification for the Shapefile
2067            format above.
2068            </para>
2069        </listitem>
2070        </varlistentry>
2071    
2072        <varlistentry>
2073        <term>PostGIS</term>
2074        <listitem>
2075            <para>
2076            PostGIS adds support for geographic objects to the PostgreSQL
2077            object-relational database. Different layer types (as for Shapefiles)
2078            are supported. <ulink url="http://postgis.refractions.net">PostGIS
2079            Homepage</ulink>
2080            </para>
2081        </listitem>
2082        </varlistentry>
2083    
2084        <varlistentry>
2085        <term>Raster files</term>
2086        <listitem>
2087            <para>
2088            Binding the GDAL library Thuban supports numerous raster file formats,
2089            see <ulink url="http://www.remotesensing.org/gdal/formats_list.html">
2090            GDAL format list</ulink> for details.</para>
2091    
2092            <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
2093            format: Raster maps are provided as TIFF images, with an additional
2094            "world file" storing the geographic reference (usually with an
2095            extension ".tfw").
2096            </para>
2097        </listitem>
2098        </varlistentry>
2099    
2100        </variablelist>
2101      </appendix>
2102    
2103      <appendix><title>Working with PostGIS</title>
2104      <para>
2105      This section focusses on the use of PostGIS in the Thuban framework. For
2106      installation and maintenance of spatial databases we refer to the  
2107      <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
2108      The Thuban PostGIS support requires the
2109      <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
2110      </para>
2111    
2112      <para>
2113            Working with PostGIS Databases is seperated into two steps:
2114            <itemizedlist>
2115            <listitem><para>Opening a Database Connection</para></listitem>
2116            <listitem><para>Loading a Data Layer</para></listitem>
2117            </itemizedlist>
2118      </para>
2119            <section><title>Opening a Database Connection</title>
2120            <para>
2121                    Before a data layer can be loaded from a PostGIS database a
2122                    connection with the database has to be established.
2123                    <menuchoice>
2124                    <guimenu>Session</guimenu>
2125                    <guimenuitem>Database Connections ...</guimenuitem>
2126                    </menuchoice> opens a dialog for database connection
2127                    management. In the dialog new connections can be added
2128                    and existing ones can be removed. Removing a database
2129                    connection is not possible if the map still displays a
2130                    layer provided by this database connection.
2131            </para>
2132        <figure>
2133        <title>Database Management Dialog</title>
2134        <mediaobject>
2135        <imageobject><imagedata fileref="../images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
2136        <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
2137        </mediaobject>
2138        </figure>
2139    
2140            <para>
2141                    To add a new database connection to the session a dialog is
2142                    opened to specify the relevant connection data. Enter all
2143                    data relevant for your connection. If the connection fails
2144                    the dialog remains open and provides some hints on the failure.
2145            </para>
2146            <figure>
2147            <title>Add Database Dialog</title>
2148            <mediaobject>
2149            <imageobject><imagedata fileref="../images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
2150            <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
2151            </mediaobject>
2152            </figure>
2153            
2154            <para>
2155            It is important to note that information on database connections are
2156            also stored with the session. Passwords are NOT stored. If you load a
2157            session with database connections you are asked to enter these
2158            passwords again where required.
2159            </para>
2160    
2161            </section>
2162    
2163            <section><title>Loading a Data Layer</title>
2164            <para>
2165            Data layers as part of a map are loaded with the
2166            <menuchoice>
2167            <guimenu>Map</guimenu>
2168            <guimenuitem>Add Database Layer ...</guimenuitem>
2169            </menuchoice> menu item. A dialog is raised displaying two choice
2170            lists. In the left list all connected databases are shown.
2171            Highlighting
2172            one of these and issuing a retrieval results in a list of available
2173            layer tables from that database. After selection of a
2174            layer the dialog is closed.
2175            </para>
2176            <figure>
2177            <title>Add Database Dialog</title>
2178            <mediaobject>
2179            <imageobject><imagedata fileref="../images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
2180            <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
2181            </mediaobject>
2182            </figure>
2183            
2184            </section>
2185    
2186      </appendix>
2187    
2188      <appendix><title>Supported Projections</title>
2189        <para>
2190        The following types of projections are directly support by
2191        Thuban. The specific values for each are provided by the user
2192        to create custom projections. Thuban comes with predefined
2193        projections which are available through the Projections dialog.
2194        </para>
2195        <itemizedlist>
2196        <listitem>
2197            <para>Geographic</para>
2198            <itemizedlist>
2199            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2200            <listitem><para>
2201                    <literal>Source Data</literal>: either Degrees or Radians
2202                    </para></listitem>
2203            </itemizedlist>
2204        </listitem>
2205        <listitem>
2206            <para>Lambert Conic Conformal</para>
2207        <itemizedlist>
2208            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2209            <listitem><para><literal>Latitude of 1st standard parallel</literal></para></listitem>
2210            <listitem><para><literal>Latitude of 2nd standard parallel</literal></para></listitem>
2211            <listitem><para><literal>Central Meridian</literal></para></listitem>
2212            <listitem><para><literal>Latitude of Origin</literal></para></listitem>
2213            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
2214            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
2215        </itemizedlist>
2216        </listitem>
2217        <listitem>
2218            <para>Transverse Mercator</para>
2219        <itemizedlist>
2220            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2221            <listitem><para><literal>Latitude</literal>of origin</para></listitem>
2222            <listitem><para><literal>Longitude</literal>at central meridian</para></listitem>
2223            <listitem><para><literal>Scale Factor</literal>at central meridian</para></listitem>
2224            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
2225            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
2226        </itemizedlist>
2227        </listitem>
2228        <listitem>
2229            <para>Universal Transverse Mercator</para>
2230        <itemizedlist>
2231            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2232            <listitem><para><literal>Zone</literal>
2233                    (can be guessed appling the Propose button)</para></listitem>
2234            <listitem><para><literal>Southern Hemisphere</literal> flag</para></listitem>
2235        </itemizedlist>
2236        </listitem>
2237        </itemizedlist>
2238        
2239        <para>
2240        Thuban comes with a sample set of map projections for various
2241        European countries. Apart from the basic projection they differ
2242        especially in their parameterization:
2243        </para>
2244        <itemizedlist>
2245        <listitem><para>Belgium Datum 1972 (Lambert Conic Conformal)</para>
2246        </listitem>
2247    
2248        <listitem><para>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</para>
2249        </listitem>
2250    
2251        <listitem><para>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)
2252        </para>
2253        </listitem>
2254    
2255        <listitem><para>Reseau Geodesique Francaise
2256        (France, Lambert Conic Conformal)</para>
2257        </listitem>
2258    
2259        <listitem><para>UK National Grid (United Kingdom, Transverse Mercartor)
2260        </para>
2261        </listitem>
2262        </itemizedlist>
2263    
2264        <para>
2265        Thuban uses the comprehensive PROJ library for projections. PROJ provides
2266        more than the four commonly used projections described above. If needed
2267        Thuban can be easily extended to a new projection covered by PROJ.
2268        </para>
2269      </appendix>
2270    
2271  </book>  </book>
2272    
Legend:
Removed from v.1369  
changed lines
  Added in v.2688
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26