/[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 1496 by frank, Tue Jul 29 12:07:13 2003 UTC revision 2023 by frank, Fri Dec 5 13:54:46 2003 UTC
# Line 2  Line 2 
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 "70">]>      [<!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>Jonathan</firstname><surname>Coles</surname>        <author>
12      </author>          <firstname>Jonathan</firstname><surname>Coles</surname>
13      <author>        </author>
14        <firstname>Jan-Oliver</firstname><surname>Wagner</surname>        <author>
15      </author>          <firstname>Jan-Oliver</firstname><surname>Wagner</surname>
16      <author>        </author>
17        <firstname>Frank</firstname><surname>Koormann</surname>        <author>
18      </author>          <firstname>Frank</firstname><surname>Koormann</surname>
19          </author>
20            </authorgroup>
21      <copyright>      <copyright>
22        <year>2003</year>        <year>2003</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    <!--
28         <revision>
29            <revnumber>CVS version $Id$</revnumber>
30            <date></date>
31            <revremark>Under development.</revremark>
32         </revision>
33    -->
34         <revision>
35            <revnumber>1.0pre3</revnumber>
36            <date>04-Dec-2003</date>
37            <revremark>
38                            Corresponds to Thuban 1.0rc1
39                            New: I18n, right button legend menu, EPSG projectons,
40                PostGIS support.
41                    </revremark>
42         </revision>
43         <revision>
44            <revnumber>1.0pre2</revnumber>
45            <date>29-Aug-2003</date>
46            <revremark>
47                            Corresponds to Thuban development release 0.8.1.
48                            New: chapter on extensions.
49                    </revremark>
50         </revision>
51         <revision>
52            <revnumber>1.0pre1</revnumber>
53            <date>08-Aug-2003</date>
54            <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
55         </revision>
56      </revhistory>
57    
58    </bookinfo>    </bookinfo>
59    
60    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
61      <para>      <para>
62      Thuban is a Free Software Geographic Information Systems (GIS) viewer.      Thuban is an interactive geographic data viewer.
63      It is being developed because there is currently no simple interactive      It has been developed because there was no simple interactive
64      viewer for geographic information available as Free Software. Thuban is      viewer for geographic information available as Free Software. Thuban is
65      written in Python and C++ and uses the wxWindows library allowing it to      written in Python and C++ and uses the wxWindows library allowing it to
66      run on many different platforms, including GNU/Linux and Windows.      run on many different platforms, including GNU/Linux and Windows.
67      </para>      </para>
68      <para>      <para>
69      GIS viewers are a necessary tool as they allow one to get a visual      Geographic data viewers are a necessary tool as they allow one to
70            get a visual
71      impression of the positional relationship of the information that may not      impression of the positional relationship of the information that may not
72      be apparent from simple inspection of the data values themselves.      be apparent from simple inspection of the data values themselves.
73      Thuban allows the user to create a session that displays      Thuban allows the user to create a session that displays
# Line 48  Line 84 
84          <section><title>Installation</title>          <section><title>Installation</title>
85          <para>          <para>
86          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,
87          and Windows 2000. All the necessary files can be found on the          and Windows 2000. Thuban depends on the following packages. These
88            packages can also be found on the
89          <ulink url="http://thuban.intevation.org/download.html">          <ulink url="http://thuban.intevation.org/download.html">
90          Thuban Download site          Thuban Download site
91          </ulink>.          </ulink>.
92          </para>          </para>
93            <para>
94            Required:
95            <itemizedlist>
96                <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>
97                <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>
98                <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>
99                <listitem><para>proj 4.4.5 Projection Library (<literal>http://www.remotesensing.org/proj/</literal>)</para></listitem>
100                <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>
101                <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>
102            </itemizedlist>
103            </para>
104            <para>
105            Optional:
106            <itemizedlist>
107                <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>
108                <listitem><para>psycopg 1.0.8 (<literal>http://initd.org/software/psycopg</literal>)</para></listitem>
109                </itemizedlist>
110            </para>
111                    <para>
112                    Along with the source codes, the download page also offers
113                    full installation packages for Debian, Windows and RPM-based systems
114                    (Mandrake, RedHat, SuSE, etc).
115                    </para>
116                    <section><title>RPM-based GNU/Linux Systems</title>
117                            <section><title>Installing Binary Packages</title>
118                                    <para>
119                                    The most wide-spread RPM-based GNU/Linux Systems are RedHat,
120                                    Mandrake and SuSE. The documentation of these distributions
121                                    should contain information about how to install third-party
122                                    RPM packages. Nonetheless, a short summary is provided here.
123                                    </para>
124                                    <para>
125                                    RPM packages can be installed applying several tools.
126                                    The most basic one is the command line program "rpm".
127                                    The hardware architecture is identified in the name
128                                    of RPM packages, eg. 'i386' for most Intel/AMD architectures.
129                                    If you have a different hardware architecture, where no
130                                    binary RPM packages are provided, you must rebuild binary
131                                    packages from the RPM source packages first (see below).
132                                    Typical rpm commands look like:
133    
134                                    <programlisting>
135                                    rpm --install Thuban-0.9.0-1.i386.rpm
136                                    </programlisting>
137    
138                                    Depending on what you already have installed on your
139                                    system, you are informed that some packages are
140                                    required, but not installed. You need to install them
141                                    first. Either they are provided by your GNU/Linux distributor
142                                    or available somewhere on the Internet.
143                                    The more essential and special ones are provided together
144                                    with the Thuban package.
145                                    </para>
146    
147                                    <para>
148                                    For rpm exist some graphical user interfaces, notably
149                                    kpackage, GnoRPM and xrpm.
150                                    </para>
151    
152                                    <para>
153                                    Make yourself familiar with one of the tools and apply it
154                                    to install the packages.
155                                    Note, that you need to be administrator (root) for the system
156                                    to do that.
157                                    </para>
158                            </section>
159                            <section><title>Build Binaries from Source Packages</title>
160                                    <para>
161                                    This section describes howto build RPM install-packages
162                                    from RPM source-packages.
163                                    This adapts and optimizes an install-package specifically
164                                    to your system.
165                                    This is especially helpful to resolve version conflicts of
166                                    dependent packages. Furthermore, install-packages for other
167                                    platforms (e.g. PowerPC) can be created.
168                                    </para>
169    
170                                    <para>
171                                    Note: rpm must be at least version 4. Execute
172                                    <literal>rpm --version</literal> to find out about the version.
173                                    </para>
174    
175                                    <para>
176                                    You need to do the following preparations to be able to
177                                    build the packages as a regular user. You should now
178                                    perform the package buling as root since this
179                                    might cause damage to your system.
180                            <itemizedlist>
181                            <listitem>
182                                                    <para>
183                                                    Create RPM directory structure:
184                                                    Choose a directory (e.g. $HOME/myrpm) and create the
185                                                    subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.
186                                                    A possible command sequence for this is:
187                                                    <programlisting>
188                                                    mkdir $HOME/freegisrpm
189                                                    cd $HOME/freegisrpm
190                                                    mkdir BUILD RPMS SOURCES SPECS SRPMS
191                                                    </programlisting>
192                                                    </para>
193                                            </listitem>
194                                            <listitem>
195                                                    <para>
196                                                    Set environment variable RPM_DIR:
197                                                    <programlisting>
198                                                    export RPM_DIR=$HOME/freegisrpm
199                                                    </programlisting>
200                                                    </para>
201                                            </listitem>
202                                            <listitem>
203                                                    <para>
204                                                    Create $HOME/.rpmmacros:
205                                                    This file sets general preferences and some
206                                                    specific settings for signing packages.
207                                                    If you don't have a GnuPG-key, you can skip
208                                                    the signature settings i.e. drop the last 4 lines.
209                                                    A signature becomes important when you want to
210                                                    give away packages to third parties.
211                                                    <programlisting>
212    <![CDATA[
213    %packager Name Lastname <[email protected]>
214    
215    %_topdir /home/mylogin/myrpm
216    
217    %_signature gpg
218    %_gpg_name Name Lastname
219    %_pgp_path ~/.gnupg
220    %_pgpbin /usr/bin/gpg
221    ]]>
222                                                    </programlisting>
223                                                    </para>
224                                            </listitem>
225                            </itemizedlist>
226    
227                                    Now you can install any RPM source-package.
228                                    It's components are installed into the corresponding
229                                    subdirectories of your rpm-directory.
230                                    Essentially these are the sources (into directory SOURCES)
231                                    and the so-called spec-file which contains all build
232                                    instructions. The spec-file will go into the SPEC directory.
233                                    Example:
234                                    <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>
235                                    </para>
236    
237                                    <para>
238                                    Create install-package:
239                                    Go to the directory with the spec-files and rebuild the
240                                    package:
241                                    <programlisting>
242    cd $HOME/mypm/SPECS
243    rpm -bb thuban.spec
244                                    </programlisting>
245                                    Next, you will find the newly created package in
246                                    $HOME/myrpm/RPMS/i386.
247                                    If you build the package for another architecture than
248                                    i386, then the name of the directory has a corresponding name.
249                                    </para>
250                                    <para>
251                                    For documentation of RPM, either type
252                                    <literal>man rpm</literal> or <literal>rpm --help</literal>.
253                                    This will provide you with information on the various command
254                                    line options of RPM.
255                                    For more information see the
256                            <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
257                                    </para>
258                            </section>
259                    </section>
260          </section>          </section>
261    
262            <section><title>Internationalization</title>
263            <para>
264            Thuban is implemented with internationalization support. So far Thuban
265            is translated by volunteers to the following languages (apart from its
266            main language: English):
267            <itemizedlist>
268                <listitem><para>French</para></listitem>
269                <listitem><para>German</para></listitem>
270                <listitem><para>Italian</para></listitem>
271                <listitem><para>Russian</para></listitem>
272                <listitem><para>Spanish</para></listitem>
273            </itemizedlist>
274            </para>
275    
276            <para>
277            To use internationalization under POSIX systems (like GNU/Linux)
278            you have to set the environment variable LC_ALL accordingly (e.g.
279            LC_ALL=fr_FR for the french language support). Please check your
280            systems documentation for details and supported settings.
281            Specifiying LC_ALL on the command line while launching thuban
282            allows appication specific language settings.
283            </para>
284    
285            <para>
286            MS Windows users have to specify the language to be used via the control
287            bar (which effects all applications).
288            </para>
289            </section>
290    
291          <section><title>The Main Window</title>          <section><title>The Main Window</title>
292          <para>          <para>
293          <screenshot>          <figure>
294          <screeninfo>The Main Window</screeninfo>          <title>The Main Window</title>
295          <mediaobject>          <mediaobject>
296          <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>          <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>
297          <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>          <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>
         <textobject><phrase>The Main Window</phrase></textobject>  
         <caption><para>The Main Window</para></caption>  
298          </mediaobject>          </mediaobject>
299          </screenshot>          </figure>
300          </para>          </para>
301    
302          <para>          <para>
# Line 159  Line 390 
390    
391          <section><title>The Session Info-Tree</title>          <section><title>The Session Info-Tree</title>
392          <para>          <para>
393          <screenshot>          <figure>
394          <screeninfo>Session Info Tree</screeninfo>          <title>Session Info Tree</title>
395          <mediaobject>          <mediaobject>
396          <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>
397          <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Session Info Tree</phrase></textobject>  
         <caption><para>Session Info Tree</para></caption>  
398          </mediaobject>          </mediaobject>
399          </screenshot>          </figure>
400          </para>          </para>
401          <para>          <para>
402          The session info-tree is primarily intended for developers working          The session info-tree is primarily intended for developers working
# Line 209  Line 438 
438    
439          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
440          <para>          <para>
441          There are two types of layers that can use added to a map: shape layers          There are three types of layers that can be added to a map:
442            Shape layers, database layers
443          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
444          standard file format for storing geographic objects. These          widely used file format for storing geographic objects. These
445          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
446          the shape file is a database file which stores attributes for          the shape file is a database file which stores attributes for
447          each shape in the shape file. This file, in dBase format,          each shape in the Shape file. This file, in dBase format,
448          has the extension ``.dbf''. Both files must have the same base name.          has the extension ``.dbf''. Both files must have the same base name.
449          For example, if there is a shape file named roads.shp there must          For example, if there is a shape file named roads.shp there must
450          also be a file roads.dbf.          also be a file roads.dbf.
451          </para>          </para>
452          <para>          <itemizedlist>
453            <listitem>
454            <para>
455          Shape layers can be added to the map with          Shape layers can be added to the map with
456          <menuchoice>          <menuchoice>
457          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
458          <guimenuitem>Add Layer</guimenuitem>          <guimenuitem>Add Layer</guimenuitem>
459          </menuchoice>.          </menuchoice>.
460          Thuban will load all files with the same base name, so it doesn't          Initially, only the ``.shp'' files are shown which is enough for the
461          matter if the shape file or database file is selected.                  selection. However, if you switch to display all files and select one
462          </para>                  of the associated files (e.g. ``.dbf''), Thuban will recognize the base
463                    name and load the corresponding Shape file.
464            </para>
465                    <para>
466                    The file dialog for Shape files allows to select multiple files.
467                    Use the shift-button together with the left mouse button to extend
468                    the selection.
469            </para>
470            </listitem>
471    
472            <listitem>
473            <para>Database layers can be added to the map with
474            <menuchoice>
475            <guimenu>Map</guimenu>
476            <guimenuitem>Add Database Layer</guimenuitem>
477            </menuchoice>.
478            A dialog with two is list is opened. The left list displays all
479            database connections currently open for the session. You can retrieve
480            a list of available layers from the selected database which is
481            displayed on the right hand. From this list one layer can be selected,
482            the dialog is closed afterwards.
483            </para>
484            <para>
485            See appendix ``Working with PostGIS'' for details.
486            </para>
487            </listitem>
488    
489            <listitem>
490          <para>          <para>
491          Image layers can be added to the map with          Image layers can be added to the map with
492          <menuchoice>          <menuchoice>
# Line 240  Line 498 
498          or in another file. If geographic information cannot be found, Thuban          or in another file. If geographic information cannot be found, Thuban
499          will report an error.          will report an error.
500          </para>          </para>
501            </listitem>
502            </itemizedlist>
503          </section>          </section>
504    
505          <section><title>Navigation</title>          <section><title>Navigation</title>
# Line 248  Line 508 
508          the tool bar or from the          the tool bar or from the
509          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.
510          </para>          </para>
511            <itemizedlist>
512            <listitem>
513          <para>          <para>
514          The ZoomIn tool          The ZoomIn tool
515          <inlinemediaobject>          <inlinemediaobject>
# Line 261  Line 523 
523          </inlinemediaobject>          </inlinemediaobject>
524          enlarges a region of the map. Clicking once on the map          enlarges a region of the map. Clicking once on the map
525          will double the magnification and center the map on the point that          will double the magnification and center the map on the point that
526          was clicked. Clicking and dragging selects a region that will          was clicked. Clicking and dragging selects a region that will be
527          enlarged to fit the window.          enlarged to fit the window.
528          </para>          </para>
529            </listitem>
530            <listitem>
531          <para>          <para>
532          The ZoomOut tool          The ZoomOut tool
533          <inlinemediaobject>          <inlinemediaobject>
# Line 280  Line 544 
544          selects a box such that the current contents of the window will be          selects a box such that the current contents of the window will be
545          scaled to fit into that box.          scaled to fit into that box.
546          </para>          </para>
547            </listitem>
548            <listitem>
549          <para>          <para>
550          The Pan tool          The Pan tool
551          <inlinemediaobject>          <inlinemediaobject>
# Line 293  Line 559 
559          </inlinemediaobject>          </inlinemediaobject>
560          allows the user to move the map around by clicking and dragging.          allows the user to move the map around by clicking and dragging.
561          </para>          </para>
562            </listitem>
563            <listitem>
564          <para>          <para>
565          The Full Extent tool          The Full Extent tool
566          <inlinemediaobject>          <inlinemediaobject>
# Line 306  Line 574 
574          </inlinemediaobject>          </inlinemediaobject>
575          rescales the viewable region so that the entire map is visible.          rescales the viewable region so that the entire map is visible.
576          </para>          </para>
577            </listitem>
578            <listitem>
579          <para>          <para>
580          The Full Layer Extent tool          The Full Layer Extent tool
581          <inlinemediaobject>          <inlinemediaobject>
# Line 321  Line 591 
591          layer fits within the window. If no layer is selected this button          layer fits within the window. If no layer is selected this button
592          will be disabled.          will be disabled.
593          </para>          </para>
594            </listitem>
595            <listitem>
596          <para>          <para>
597          The Full Shape Extent tool          The Full Shape Extent tool
598          <inlinemediaobject>          <inlinemediaobject>
# Line 335  Line 607 
607          rescales the viewable region so that the currently selected          rescales the viewable region so that the currently selected
608          shape fits within the window. If the shape is a point, it is          shape fits within the window. If the shape is a point, it is
609          centered and the map is zoomed all the way in. If no shape is          centered and the map is zoomed all the way in. If no shape is
610          selected this button will be disabled.          selected this button will be disabled. This feature is especially
611            helpful when identifying an object related to a selected record
612            in a tableview (see below).
613    
614          </para>          </para>
615            </listitem>
616            </itemizedlist>
617          </section>          </section>
618    
619          <section><title>Object Identification</title>          <section><title>Object Identification</title>
# Line 353  Line 630 
630          </inlinemediaobject>.          </inlinemediaobject>.
631          Clicking on an object selects that object and opens a dialog which          Clicking on an object selects that object and opens a dialog which
632          shows all the table attributes for that object. Any current selection          shows all the table attributes for that object. Any current selection
633          is lost.          is lost. Objects on the map are typically shapes and this document
634            will often refer to objects as shapes.
635          </para>          </para>
636          </section>          </section>
637    
# Line 404  Line 682 
682          <menuchoice><guimenu>Map</guimenu></menuchoice>.          <menuchoice><guimenu>Map</guimenu></menuchoice>.
683          </para>          </para>
684    
685            <itemizedlist>
686            <listitem>
687          <para>          <para>
688          The Move Layer to Top tool          The Move Layer to Top tool
689          <inlinemediaobject>          <inlinemediaobject>
# Line 416  Line 696 
696          <textobject> <phrase>Move Layer to Top</phrase> </textobject>          <textobject> <phrase>Move Layer to Top</phrase> </textobject>
697          </inlinemediaobject> raises the selected layer to the top of the map.          </inlinemediaobject> raises the selected layer to the top of the map.
698          </para>          </para>
699            </listitem>
700            <listitem>
701    
702          <para>          <para>
703          The Move Layer Up tool          The Move Layer Up tool
# Line 429  Line 711 
711          <textobject> <phrase>Move Layer Up</phrase> </textobject>          <textobject> <phrase>Move Layer Up</phrase> </textobject>
712          </inlinemediaobject> raises the selected layer one level.          </inlinemediaobject> raises the selected layer one level.
713          </para>          </para>
714            </listitem>
715            <listitem>
716    
717          <para>          <para>
718          The Move Layer Down tool          The Move Layer Down tool
# Line 443  Line 727 
727          </inlinemediaobject> lowers the selected layer one level.          </inlinemediaobject> lowers the selected layer one level.
728          </para>          </para>
729    
730            </listitem>
731            <listitem>
732          <para>          <para>
733          The Move Layer to Bottom tool          The Move Layer to Bottom tool
734          <inlinemediaobject>          <inlinemediaobject>
# Line 456  Line 742 
742          </inlinemediaobject> lowers the selected layer to the bottom of the map.          </inlinemediaobject> lowers the selected layer to the bottom of the map.
743          </para>          </para>
744    
745            </listitem>
746            <listitem>
747          <para>          <para>
748          The Visible tool          The Visible tool
749          <inlinemediaobject>          <inlinemediaobject>
# Line 470  Line 758 
758          hidden.          hidden.
759          </para>          </para>
760    
761            </listitem>
762            <listitem>
763          <para>          <para>
764          The Invisible tool          The Invisible tool
765          <inlinemediaobject>          <inlinemediaobject>
# Line 483  Line 773 
773          </inlinemediaobject> hides the selected layer in the map.          </inlinemediaobject> hides the selected layer in the map.
774          </para>          </para>
775    
776            </listitem>
777            <listitem>
778          <para>          <para>
779          The Properties tool          The Properties tool
780          <inlinemediaobject>          <inlinemediaobject>
# Line 497  Line 789 
789          Double-clicking on a layer or a group of a layer will open the          Double-clicking on a layer or a group of a layer will open the
790          properties dialog for that layer.          properties dialog for that layer.
791          </para>          </para>
792            </listitem>
793            </itemizedlist>
794    
795            <para>
796            The most used layer related actions are also available from a
797            popup menu. It is raised when a layer is clicked with the right mouse
798            button.
799            </para>
800            
801            <para>
802            <figure>
803            <title>Layer Popup Menu</title>
804            <mediaobject>
805            <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
806            <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
807            </mediaobject>
808            </figure>
809            </para>
810    
811            <para>
812            Along the bottom of the legend is the scalebar. The scalebar
813            will be available if there are any layers and the  map has a
814            projection set.
815            </para>
816          </section>          </section>
817    
818          <section><title>Exporting</title>          <section><title>Exporting</title>
# Line 507  Line 823 
823          <menuchoice>          <menuchoice>
824          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
825          <guimenuitem>Export</guimenuitem>          <guimenuitem>Export</guimenuitem>
826          </menuchoice>. Under other platforms this option is not available.          </menuchoice> for use in reports, presentations, or further
827          Clicking this menu item open a file selection dialog that lets the          modification. The current map view, legend, and, if available,
828          user select a location to export the map.          scalebar are exported. Under other platforms this option is not
829            available. Clicking this menu item open a file selection dialog
830            that lets the user select a location to export the map.
831          </para>          </para>
832          </section>          </section>
833    
# Line 519  Line 837 
837          <menuchoice>          <menuchoice>
838          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
839          <guimenuitem>Print</guimenuitem>          <guimenuitem>Print</guimenuitem>
840          </menuchoice>. A standard printing dialog will open allowing the          </menuchoice>. The current map view, legend, and, if available,
841          user to configure the printer. This dialog will differ depending          scalebar are printed. A standard printing dialog will open allowing
842            the user to configure the printer. This dialog will differ depending
843          on which platform Thuban is running.          on which platform Thuban is running.
844          </para>          </para>
845          </section>          </section>
# Line 533  Line 852 
852    
853          <section><title>Types of Layers</title>          <section><title>Types of Layers</title>
854          <para>          <para>
855          There are two types of layers supported by Thuban: shape layers and          There are three types of layers supported by Thuban: shape layers,
856            database layers and
857          image layers. Shape layers consist of vector based shapes with          image layers. Shape layers consist of vector based shapes with
858          geo-referenced coordinates. There are three types of supported          geo-referenced coordinates. There are three types of supported
859          shapes: polygons, lines, and points. Image layers can be any image          shapes: polygons, lines (arc), and points. Database layers are similar
860            to shape layers but loaded from a database instead of the file system.
861            Image layers can be any image
862          file format supported by the Geo-spatial Data Abstraction Library          file format supported by the Geo-spatial Data Abstraction Library
863          (GDAL). The images must have geographic          (GDAL). The images must have geographic
864          coordinate data either embedded within the file or in a separate          coordinate data either embedded within the file or in a separate
# Line 544  Line 866 
866          work very well with Thuban and were designed specifically to be image          work very well with Thuban and were designed specifically to be image
867          layers in GIS programs.          layers in GIS programs.
868          </para>          </para>
869            <para>
870            All actions in the
871            <menuchoice>
872            <guimenu>Layer</guimenu>
873            </menuchoice> menu act on the currently selected layer in the legend.
874            </para>
875          </section>          </section>
876    
877          <section><title>Properties</title>          <section><title>Properties</title>
# Line 554  Line 882 
882          <guimenu>Layer</guimenu>          <guimenu>Layer</guimenu>
883          <guimenuitem>Properties</guimenuitem>          <guimenuitem>Properties</guimenuitem>
884          </menuchoice> opens a dialog that displays a layer's properties.          </menuchoice> opens a dialog that displays a layer's properties.
885          All layers have a title and it can be modified in the text field          All layers have a title which can be modified in the text field
886          provided. The type of layer is also shows. If the type is a type          provided. The type of layer is also shows. If the type is a type
887          of shape (polygon, arc, point) the classification table will be          of shape (polygon, arc, point) the classification table will be
888          shown. Image layers have no other properties other than title          shown. Image layers have no other properties other than title
889          and type.          and type.
890          </para>          </para>
891          <para>          <para>
892          <screenshot>          <figure>
893          <screeninfo>Properties Window</screeninfo>          <title>Properties Window</title>
894          <mediaobject>          <mediaobject>
895          <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
896          <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Properties Window</phrase></textobject>  
         <caption><para>The Properties Window for a Shape Layer</para></caption>  
897          </mediaobject>          </mediaobject>
898          </screenshot>          </figure>
899          </para>          </para>
900          <para>          <para>
901          <screenshot>          <figure>
902          <screeninfo>Properties Window</screeninfo>          <title>Properties Window</title>
903          <mediaobject>          <mediaobject>
904          <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
905          <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Properties Window</phrase></textobject>  
         <caption><para>The Properties Window for an Image Layer</para></caption>  
906          </mediaobject>          </mediaobject>
907          </screenshot>          </figure>
908          </para>          </para>
909          </section>          </section>
910    
# Line 646  Line 970 
970      <para>      <para>
971      A layer always has a classification. When a new layer is added to the      A layer always has a classification. When a new layer is added to the
972      map, a default classification is created with the DEFAULT group. This      map, a default classification is created with the DEFAULT group. This
973      group cannot be removed. Every shape in the layer, regardless of its      group cannot be removed but can be hidden (see below). Every shape in the
974      attributes, will match this group if no other group matches.      layer, regardless of its attributes, will match this group if no other
975        group matches.
976      </para>      </para>
977    
978          <section><title>Editing Classifications</title>          <section><title>Editing Classifications</title>
# Line 664  Line 989 
989          button.          button.
990          </para>          </para>
991          <para>          <para>
992          <screenshot>          To apply the changes to the map the user can click
993          <screeninfo>Properties Window</screeninfo>          either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
994            <guibutton>Try</guibutton> will not close the dialog box, allowing
995            the user to see how the classification changes the map.
996            <guibutton>Revert</guibutton> will undo the last classification applied
997            to the map. <guibutton>OK</guibutton> will commit the changes and
998            close the dialog. The user will be unable to undo the changes.
999            <guibutton>Close</guibutton> simply closes the dialog box. If any
1000            changes have not been applied with <guibutton>Try</guibutton> the
1001            changes will not be applied to the map.
1002            </para>
1003            <para>
1004            <figure>
1005            <title>Properties Window</title>
1006          <mediaobject>          <mediaobject>
1007          <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>
1008          <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Properties Window</phrase></textobject>  
         <caption><para>The Properties Window with Classifications</para></caption>  
1009          </mediaobject>          </mediaobject>
1010          </screenshot>          </figure>
1011          </para>          </para>
1012          <para>          <para>
1013          The order of the groups in the classification is significant          The order of the groups in the classification is significant
# Line 738  Line 1073 
1073    
1074          <section><title>Generating Classes</title>          <section><title>Generating Classes</title>
1075          <para>          <para>
1076          <screenshot>          <figure>
1077          <screeninfo>Generate Class</screeninfo>          <title>Generate Class</title>
1078          <mediaobject>          <mediaobject>
1079          <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>
1080          <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Generate Class</phrase></textobject>  
         <caption><para>The Generate Classifications Dialog</para></caption>  
1081          </mediaobject>          </mediaobject>
1082          </screenshot>          </figure>
1083          </para>          </para>
1084          <para>          <para>
1085          Creating a classification by hand can be tedious.          Creating a classification by hand can be tedious.
# Line 756  Line 1089 
1089          opens the <varname>Generate Classification</varname> dialog.          opens the <varname>Generate Classification</varname> dialog.
1090          Under the <varname>Generate</varname> pull down there are at most          Under the <varname>Generate</varname> pull down there are at most
1091          three different ways to generate classifications:          three different ways to generate classifications:
1092          Unique Values, Unique Distribution, and Quantiles. Some options          Unique Values, Uniform Distribution, and Quantiles. Some options
1093          may not be available if the data type for the field does not          may not be available if the data type for the field does not
1094          support them. For instance, <varname>Unique Distribution</varname>          support them. For instance, <varname>Uniform Distribution</varname>
1095          doesn't make sense for a Text field.          doesn't make sense for a Text field.
1096          </para>          </para>
1097          <para>          <para>
1098          For every way of generating a classification, a color scheme must          For every way of generating a classification, a color scheme must
1099          be selected. Thuban provides several different color schemes that          be selected. Thuban provides several different color schemes that
1100          affect how the group properties change over the classification.          affect how the group properties change over the classification.
1101            It may be desirable that only certain properties change over the
1102            classification. If the shape type is a polygon or a point then
1103            the <guibutton>Fix Border Color</guibutton> option will be available.
1104            This allows the user to select a border color for all classification
1105            groups.
1106          It is also possible to create a custom color scheme. Selecting          It is also possible to create a custom color scheme. Selecting
1107          this option will display two symbols: the one of the left has the          this option will display two symbols: the one of the left has the
1108          properties of the first group and the one on the right has the          properties of the first group and the one on the right has the
1109          properties of the last group. Thuban will interpolate between these          properties of the last group. Thuban will interpolate between these
1110          two properties to generate the other groups.          two properties to generate the other groups.
1111            <figure>
1112            <title>Custom Color Scheme</title>
1113            <mediaobject>
1114            <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>
1115            <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>
1116            </mediaobject>
1117            </figure>
1118          </para>          </para>
1119          <para>          <para>
1120          The Unique Values option lets the user select specific values that          The Unique Values option lets the user select specific values that
# Line 779  Line 1124 
1124          right. Each list can be sorted or reversed for easier searching.          right. Each list can be sorted or reversed for easier searching.
1125          The classification that is generated will be in the same order as          The classification that is generated will be in the same order as
1126          the list on the right.          the list on the right.
1127            <figure>
1128            <title>Unique Values</title>
1129            <mediaobject>
1130            <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>
1131            <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>
1132            </mediaobject>
1133            </figure>
1134          </para>          </para>
1135          <para>          <para>
1136          The Unique Distribution option creates a user specified number of          The Uniform Distribution option creates a user specified number of
1137          groups of ranges such that each range covers equal intervals. The          groups of ranges such that each range covers equal intervals. The
1138          minimum and maximum values can automatically be retrieved from the          minimum and maximum values can automatically be retrieved from the
1139          table by clicking <guibutton>Retrieve From Table</guibutton>. The          table by clicking <guibutton>Retrieve From Table</guibutton>. The
1140          stepping is how large each interval is. Adjusting this value will          stepping is how large each interval is. Adjusting this value will
1141          automatically recalculate how many groups is appropriate.          automatically recalculate how many groups is appropriate.
1142            <figure>
1143            <title>Uniform Distribution</title>
1144            <mediaobject>
1145            <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>
1146            <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>
1147            </mediaobject>
1148            </figure>
1149          </para>          </para>
1150          <para>          <para>
1151          The Quantiles option generates ranges based on the number of items          The Quantiles option generates ranges based on the number of items
1152          in the input set. For example, by specifying five groups Thuban will          in the table. For example, by specifying five groups Thuban will
1153          generate five groups with appropriate ranges such that 20% of the table          generate five groups with appropriate ranges such that 20% of the table
1154          data is in each group. If it is impossible to generate exact          data is in each group. If it is impossible to generate exact
1155          groupings, Thuban will issue a warning but allow the user to continue.          groupings, Thuban will issue a warning but allow the user to continue.
1156            <figure>
1157            <title>Quantiles</title>
1158            <mediaobject>
1159            <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>
1160            <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>
1161            </mediaobject>
1162            </figure>
1163          </para>          </para>
1164          </section>          </section>
1165    </chapter>    </chapter>
# Line 815  Line 1181 
1181      <guimenu>Layer</guimenu>      <guimenu>Layer</guimenu>
1182      <guimenuitem>Projection</guimenuitem>      <guimenuitem>Projection</guimenuitem>
1183      </menuchoice>.      </menuchoice>.
1184      <screenshot>      <figure>
1185      <screeninfo>Projection Window</screeninfo>      <title>Projection Window</title>
1186      <mediaobject>      <mediaobject>
1187      <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>      <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>
1188      <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>      <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>
     <textobject><phrase>Projection Window</phrase></textobject>  
     <caption><para>The Projection Window</para></caption>  
1189      </mediaobject>      </mediaobject>
1190      </screenshot>      </figure>
1191        </para>
1192        <para>
1193        Thuban is distributed with a sample collection of projections and the
1194        set of coordinate systems as used by the EPSG
1195        (European Petroleum Survey Group). This quite large set is only displayed
1196        if activated by the according checkbox. The set falls into two parts:
1197        deprecated lists all projections which are no longer part of the
1198        EPSG data base.
1199      </para>      </para>
1200      <para>      <para>
1201      Thuban is distributed with a sample collection of projections. The           The
1202      user can create new projections and make them available to all      user can create new projections and make them available to all
1203      future Thuban sessions. They may also be exported and imported so      future Thuban sessions. They may also be exported and imported so
1204      that custom projections can be distributed.      that custom projections can be distributed.
# Line 855  Line 1227 
1227          <guibutton>Remove</guibutton> button will permanently remove a          <guibutton>Remove</guibutton> button will permanently remove a
1228          projection from the list of available projections.          projection from the list of available projections.
1229          </para>          </para>
1230            <para>
1231            To apply the selected projection to the map the user can click
1232            either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
1233            <guibutton>Try</guibutton> will not close the dialog box, allowing
1234            the user to see how the projeciton changes the map.
1235            <guibutton>Revert</guibutton> will undo the last projection applied
1236            to the map. <guibutton>OK</guibutton> will commit the changes and
1237            close the dialog. The user will be unable to undo the changes.
1238            <guibutton>Close</guibutton> simply closes the dialog box. If no
1239            selection has been applied with <guibutton>Try</guibutton> the
1240            selection will not be applied to the map.
1241            </para>
1242      </section>      </section>
1243          <section><title>Importing/Exporting Projections</title>          <section><title>Importing/Exporting Projections</title>
1244          <para>          <para>
# Line 881  Line 1265 
1265    
1266      <section><title>Table View</title>      <section><title>Table View</title>
1267          <para>          <para>
1268          <screenshot>          <figure>
1269          <screeninfo>Table View</screeninfo>          <title>Table View</title>
1270          <mediaobject>          <mediaobject>
1271          <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>
1272          <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Table View</phrase></textobject>  
         <caption><para>The Table View</para></caption>  
1273          </mediaobject>          </mediaobject>
1274          </screenshot>          </figure>
1275          </para>          </para>
1276          <para>          <para>
1277          Thuban provides a standard dialog to display table contents, the          Thuban provides a standard dialog to display table contents, the
1278          Table View. The view falls has five sections: The title, selections,          Table View. The view has five sections: The title, selections,
1279          the table grid, export functions, and the status bar.          the table grid, export functions, and the status bar.
1280          </para>          </para>
1281          <para>          <para>
# Line 906  Line 1288 
1288          third choice can be either a specific value (interpreted as numerical          third choice can be either a specific value (interpreted as numerical
1289          or string depending on the type of the first field) or a second field          or string depending on the type of the first field) or a second field
1290          identifier. Thus you can perform analysis like selecting all          identifier. Thus you can perform analysis like selecting all
1291          records where "population > 10000" or          records where <literal>population > 10000</literal> or
1292          "cars_per_inhabitant <  bikes_per_inhabitant" (note that the field names          <literal>cars_per_inhabitant < bikes_per_inhabitant</literal>
1293          are only explanatory, the dBase files allow only          (note that the field names are only explanatory, the dBase files
1294          11 character field names).          allow only 11 character field names).
1295                
1296          Selections can be combined either by applying a selection only on          Selections can be combined either by applying a selection only on
1297          a previously selected set of records or by adding the results of a          a previously selected set of records or by adding the results of a
# Line 917  Line 1299 
1299          earlier results.          earlier results.
1300          </para>          </para>
1301          <para>          <para>
1302          The table grid shows the contents of the table (a record per column),          The table grid shows the contents of the table (one record per row),
1303          with highlighted selection results. Columns and rows can be resized.          with highlighted selection results. Columns and rows can be resized.
1304          </para>          </para>
1305          <para>          <para>
# Line 1010  Line 1392 
1392    
1393          <section><title>Join</title>          <section><title>Join</title>
1394              <para>              <para>
1395              <screenshot>              <figure>
1396              <screeninfo>Join Tables</screeninfo>              <title>Join Tables</title>
1397              <mediaobject>              <mediaobject>
1398              <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>              <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>
1399              <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>              <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>
             <textobject><phrase>Join Tables</phrase></textobject>  
             <caption><para>The Join Tables Dialog</para></caption>  
1400              </mediaobject>              </mediaobject>
1401              </screenshot>              </figure>
1402              </para>              </para>
1403              <para>              <para>
1404              The              The
# Line 1044  Line 1424 
1424      </section>      </section>
1425      <section><title>Attribute Tables</title>      <section><title>Attribute Tables</title>
1426          <para>          <para>
1427              To clearly separate between both types, Thuban provides              To clearly separate between both types of tables (data and
1428          functionality regarding the attribute tables under the Layer menu.          attribute), Thuban provides functionality regarding the attribute
1429            tables under the <menuchoice><guimenu>Layer</guimenu></menuchoice> menu.
1430          </para>          </para>
1431    
1432          <section><title>Show Table</title>          <section><title>Show Table</title>
# Line 1097  Line 1478 
1478      </section>      </section>
1479    </chapter>    </chapter>
1480    
1481      <chapter><title>Extensions</title>
1482            <para>
1483            Thuban is designed to be extensible. The term Extension is used as a
1484            general term for anything that extends Thuban.
1485            This chapter introduces into some oppportunities how to add and
1486            handle extra functionality developed by your own or third parties.
1487            </para>
1488    
1489            <section><title>Add personal extensions via thubanstart.py</title>
1490                    <para>
1491                    After Thuban has been started for the first time, a directory
1492                    .thuban is created within your home directory.
1493                    There you can add a file thubanstart.py  which will be imported
1494                    by Thuban at start-up. It is recommended to add only import-statements
1495                    to this file to keep the actual code of extensions separate.
1496                    </para>
1497                    <para>
1498                    The modules to import must either be found through the environment
1499                    variable PYTHONPATH or directly be placed into the .thuban-directory.
1500                    </para>
1501                    <para>
1502                    As an example, copy the file examples/simple_extensions/hello_world.py
1503                    of the Thuban source code into the .thuban-directory of your home
1504                    directory. Now add add the statement import hello_world to the
1505                    file thubanstart.py and run Thuban. You will notice an additional
1506                    menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
1507                    the new item for the Hello-World extension is placed - select it
1508                    to see the Hello-World message.
1509                    </para>
1510            </section>
1511    
1512            <section><title>Extensions included in Thuban package</title>
1513                    <para>
1514                    The extensions described in this section are part of the
1515                    Thuban package, but not activated by default.
1516                    You will find them in the Thuban installation directory
1517                    under <literal>Extensions/</literal>. Activate them as personal
1518                    extensions via PYTHONPATH as described in the previous section.
1519                    Stable extensions will appear under the menu
1520                    <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
1521                    extensions which are in experimental state and therefore
1522                    not fully functional under
1523                    <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
1524                    </para>
1525    
1526                    <section><title>Stable extensions</title>
1527                            <para>
1528                            These extensions provide extra-functionality to Thuban
1529                            that has not (yet) been integrated in the main application.
1530                            They are considered to be free of bugs, but may be
1531                            further polished with helpful user interactions.
1532                            </para>
1533                            <section><title>gns2shp</title>
1534                                    <para>
1535                                    This tool converts data of the Geospatial Names Server
1536                                    (GNS, see <ulink url="http://www.nima.mil/gns"/>)
1537                                    into Shapefile format.
1538                                    The above web-site offer to download named places
1539                                    information grouped by countries for all of the world
1540                                    except USA for which other data are provided.
1541                                    </para>
1542                                    <para>
1543                                    If you download and unpack a package, you will have
1544                                    a text-file with suffix .txt.
1545                                    Selecting such a file via gns2shp will create the
1546                                    corresponding Shapefile with the same basename and
1547                                    place it in the same direcory. Afterwards it
1548                                    is automatically loaded into Thuban.
1549                                    The Shapefile will not automatically be delete afterwards.
1550                                    </para>
1551                                    <para>
1552                                    The gns2shp.py module can also be executed on the
1553                                    command line for batch processing purposes.
1554                                    </para>
1555                                    <para>
1556                                    A sample (<literal>ls.txt</literal> for Liechtenstein)
1557                                    is included in the directory
1558                                    <literal>Extensions/gns2shp/test</literal>.
1559                                    </para>
1560                            </section>
1561                    </section>
1562                    <section><title>Experimental extensions</title>
1563                            <para>
1564                            All all of these functions have to be handled with care,
1565                            since they are neither complete nor well tested.
1566                            They are to be seen as a proof-of-concept and may
1567                            additionally in some cases of practical help.
1568                            </para>
1569                            <para>
1570                            Any interest on further improvement of these extensions
1571                            should be communicated towards the developer and user
1572                            community.
1573                            </para>
1574    
1575                            <section><title>importAPR</title>
1576                                    <para>
1577                                    This command offer to load an ESRI� ArcView� project
1578                                    file (suffix .apr) and convert it for use within Thuban.
1579                                    After selecting a apr-file to load, a list
1580                                    will be presented that offers to select one of the views
1581                                    of the apr-file, provided there is more than one.
1582                                    Furthermore, the Session Info-Tree is extended with
1583                                    a complete representation of the parsed apr-file.
1584                                    </para>
1585                                    <para>
1586                                    The legend of Thuban does not yet cover all of the elements as
1587                                    supported by the legend of ArcView�. Therefore, the Thuban
1588                                    map will look different. Furthermore, the apr-format is
1589                                    a proprietary format, not openly documented.
1590                                    Therefore, the interpretation is
1591                                    partly based on reverse engeneering and good guessing.
1592                                    </para>
1593                                    <para>
1594                                    The file-paths within the apr-file may not fit and potentially
1595                                    are subject to fix in the apr-file. You can do this
1596                                    applying any text editor. The paths are either absolute
1597                                    or relative from where Thuban has been started.
1598                                    </para>
1599                                    <para>
1600                                    A sample for the Iceland data is included as
1601                                    <literal>Extensions/importAPR/samples/iceland.apr</literal>.
1602                                    The file-paths are relative from the Thuban main directory.
1603                                    </para>
1604                            </section>
1605                    </section>
1606            </section>
1607    
1608            <section><title>Writing simple extensions</title>
1609                    <para>
1610                    Writing an extension for Thuban basically means to
1611                    implement the extra functionality in Python with all of the
1612                    Thuban classes, methods and variables available.
1613                    </para>
1614                    <para>
1615                    All classes and their methods are documented in the source code
1616                    (see their doc-strings). Here is an example from
1617                    Thuban/Model/layer.py that describes some of the methods
1618                    of a Layer object:
1619                    </para>
1620                    <programlisting>
1621                    <![CDATA[
1622    class BaseLayer(TitledObject, Modifiable):
1623    
1624        """Base class for the layers."""
1625    
1626        def __init__(self, title, visible = True, projection = None):
1627            """Initialize the layer.
1628    
1629            title -- the title
1630            visible -- boolean. If true the layer is visible.
1631            """
1632            TitledObject.__init__(self, title)
1633            Modifiable.__init__(self)
1634            self.visible = visible
1635            self.projection = projection
1636    
1637        def Visible(self):
1638            """Return true if layer is visible"""
1639            return self.visible
1640    
1641        def SetVisible(self, visible):
1642            """Set the layer's visibility."""
1643            self.visible = visible
1644            self.issue(LAYER_VISIBILITY_CHANGED, self)
1645    
1646        def HasClassification(self):
1647            """Determine if this layer support classifications."""
1648    ...
1649                    ]]>
1650                    </programlisting>
1651                    <para>
1652                    This example intends to give you an impression of the
1653                    source-code-level documentation.
1654                    You have to make yourself familiar with
1655                    the Python programming language to understand some special
1656                    code elements.
1657                    </para>
1658                    <section><title>hello_world.py</title>
1659                      <para>
1660                      Traditionally, the first example should welcome the world.
1661                      Most of the code handles the frame for integrating a menu
1662                      item into Thuban while the actual raising of a message
1663                      is done in a single line.
1664                      </para>
1665                            <programlisting>
1666                            <![CDATA[
1667    # Copyright (C) 2003 by Intevation GmbH
1668    # Authors:
1669    # Jan-Oliver Wagner <[email protected]>
1670    #
1671    # This program is free software under the GPL (>=v2)
1672    # Read the file COPYING coming with Thuban for details.
1673    
1674    """
1675    Extend Thuban with a sample Hello World to demonstrate simple
1676    extensions.
1677    """
1678    
1679    __version__ = '$Revision$'
1680    
1681    # use _() already now for all strings that may later be translated
1682    from Thuban import _
1683    
1684    # Thuban has named commands which can be registered in the central
1685    # instance registry.
1686    from Thuban.UI.command import registry, Command
1687    
1688    # The instance of the main menu of the Thuban application
1689    # See Thuban/UI/menu.py for the API of the Menu class
1690    from Thuban.UI.mainwindow import main_menu
1691    
1692    def hello_world_dialog(context):
1693        """Just raise a simple dialog to greet the world.
1694    
1695        context -- The Thuban context.
1696        """
1697        context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
1698    
1699    
1700    # create a new command and register it
1701    registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
1702                         helptext = _('Welcome everyone on this planet')))
1703    
1704    # find the extensions menu (create it anew if not found)
1705    extensions_menu = main_menu.find_menu('extensions')
1706    if extensions_menu is None:
1707        extensions_menu = main_menu.InsertMenu('extensions', _('E&xtensions'))
1708    
1709    # finally bind the new command with an entry in the extensions menu
1710    extensions_menu.InsertItem('hello_world')
1711                            ]]>
1712                            </programlisting>
1713                    </section>
1714                    <section><title>Registering a Command</title>
1715                      <para>
1716                      Mainly, our new function has to be registered to the Thuban
1717                      framework in order to connect it to the menu. A registered
1718                      command can also be connected to e.g. a toolbar button.
1719                      </para>
1720                      <para>
1721                      The instances and classes for this are imported at the beginning.
1722                      Any code not inside a method or class is directly executed when
1723                      the source-code module is imported. Therefore, the second
1724                      part of this example consist of the plain statements to create a new
1725                      Command and to add it to the menu.
1726                      </para>
1727                      <para>
1728                      By convention, it looks for a menu registered as ``extensions'' to
1729                      insert the new command. If it does not exist yet, it gets created.
1730                      It is advisable to copy this code for any of your extensions.
1731                      </para>
1732                    </section>
1733                    <section><title>The Thuban context</title>
1734                            <para>
1735                            A registered command that is called, always receives the
1736                            Thuban context. This instance provides our method with
1737                            hook references to all important components of the Thuban
1738                            application.
1739                            </para>
1740                            <para>
1741                    In the example hello_world.py, our function uses the
1742                            mainwindow component which offers a method to raise a
1743                            message dialog. In total there are three hooks:
1744                            <itemizedlist>
1745                            <listitem>
1746                            <para>application:
1747                            This object is the instance of the Thuban Application class.
1748                            Except maybe for loading or savinf sessions, you will not
1749                            need this object for a simple extension.
1750                            See Thuban/UI/application.py for the API.
1751                            </para>
1752                            </listitem>
1753                            <listitem>
1754                            <para>session:
1755                            The instance of the current session. It manages the sessions'
1756                            map and tables. You can set and remove the map or tables.
1757                            In may also get the map object. However, you should know that
1758                            internally it is already prepared to handle many maps.
1759                            Therfore, currently you would always receive a list with exactlty
1760                            one element. In the future, if there are more than one map,
1761                            you will not know which one is the currently display one and
1762                            therefore you should use the mainwindow as hook to find
1763                            the currently displayed map.
1764                            See Thuban/Model/session.py for the API.
1765                            </para>
1766                            </listitem>
1767                            <listitem>
1768                            <para>
1769                            mainwindow: The mainwindow object is central to manage various
1770                            GUI things such as the Legend sub-window. Most notably,
1771                            you get access to the canvas which is the window part where
1772                            the map is drawn. The canvas knows, which map it currently
1773                            draws and therefore you get the current map via
1774                            context.mainwindow.canvas.Map().
1775                            See Thuban/UI/mainwindow.py for the API.
1776                            </para>
1777                            </listitem>
1778                            </itemizedlist>
1779                </para>
1780                    </section>
1781            </section>
1782      </chapter>
1783    
1784    <chapter><title>Trouble Shooting</title>    <chapter><title>Trouble Shooting</title>
1785      <para>      <para>
1786        Here are a few problems that users have encountered when first using Thuban.
1787      </para>      </para>
1788      <variablelist>      <para>
1789    
1790      <varlistentry>      <itemizedlist>
     <term>After adding two or more layers nothing is being drawn in the  
     map window.  
     </term>  
1791      <listitem>      <listitem>
1792        <para>After adding two or more layers nothing is drawn in the map window.
1793        </para>
1794      <para>      <para>
1795      This is probably because the layers have different projections. Projections      This is probably because the layers have different projections. Projections
1796      must be set on all layers and on the map itself if the layer's projections      must be set on all layers and on the map itself if the layers' projections
1797      are different.      are different.
1798      </para>      </para>
1799      </listitem>      </listitem>
     </varlistentry>  
1800    
     <varlistentry>  
     <term>Thuban crashes on startup with the error  
         <literal>NameError: global name 'False' is not defined</literal>.  
     </term>  
1801      <listitem>      <listitem>
1802        <para>Thuban crashes on startup with the error
1803            <literal>NameError: global name 'False' is not defined</literal>.
1804        </para>
1805      <para>      <para>
1806      <varname>True</varname> and <varname>False</varname> were only introduced      <varname>True</varname> and <varname>False</varname> were only introduced
1807      in Python 2.2.1. Thuban depends on at least Python 2.2.1.      in Python 2.2.1. Thuban depends on at least Python 2.2.1.
1808      </para>      </para>
1809      </listitem>      </listitem>
     </varlistentry>  
1810    
1811      <varlistentry>      <listitem>
1812      <term>After compiling Thuban, Thuban crashes with an error similar to      <para>After compiling Thuban, Thuban crashes with an error similar to
1813          <literal>          <literal>
1814          ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0          ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0
1815          </literal>          </literal>
1816      </term>      </para>
     <listitem>  
1817      <para>      <para>
1818      Thuban depends on the wxWindows library. If Thuban is compiled with an      Thuban depends on the wxWindows library. If Thuban is compiled with an
1819      incompatible version of the compiler than wxWindows was compiled with      incompatible version of the compiler than wxWindows was compiled with
# Line 1141  Line 1821 
1821      compiler.      compiler.
1822      </para>      </para>
1823      </listitem>      </listitem>
1824      </varlistentry>      </itemizedlist>
1825      </variablelist>      </para>
1826        <para>
1827        If an error occurs Thuban will display a dialog indicating the error
1828        before closing. The text should be copied and reported to the
1829        <ulink url="http://thuban.intevation.org/bugtracker.html">
1830        Intevation bugtracker
1831        </ulink>.
1832        More information about the system is available from
1833        <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.
1834        This should also be included in the bug report.
1835        <figure>
1836        <title>Error Dialog</title>
1837        <mediaobject>
1838        <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>
1839        <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>
1840        </mediaobject>
1841        </figure>
1842        </para>
1843    
1844    </chapter>    </chapter>
1845    
# Line 1178  Line 1875 
1875      </listitem>      </listitem>
1876      </varlistentry>      </varlistentry>
1877    
1878        <varlistentry>
1879        <term>PostGIS</term>
1880        <listitem>
1881            <para>
1882            PostGIS adds support for geographic objects to the PostgreSQL
1883            object-relational database. Different layer types (as for Shapefiles)
1884            are supported. <ulink url="http://postgis.refractions.net">PostGIS
1885            Homepage</ulink>
1886            </para>
1887        </listitem>
1888        </varlistentry>
1889    
1890        <varlistentry>
1891        <term>Raster files</term>
1892        <listitem>
1893            <para>
1894            Binding the GDAL library Thuban supports numerous raster file formats,
1895            see <ulink url="http://www.remotesensing.org/gdal/formats_list.html">
1896            GDAL format list</ulink> for details.</para>
1897    
1898            <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
1899            format: Raster maps are provided as TIFF images, with an additional
1900            "world file" storing the geographic reference (usually with an
1901            extension ".tfw").
1902            </para>
1903        </listitem>
1904        </varlistentry>
1905    
1906      </variablelist>      </variablelist>
1907    </appendix>    </appendix>
1908    
1909      <appendix><title>Working with PostGIS</title>
1910      <para>
1911      This section focusses on the use of PostGIS in the Thuban framework. For
1912      installation and maintenance of spatial databases we refer to the  
1913      <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
1914      The Thuban PostGIS support requires the
1915      <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
1916      </para>
1917    
1918      <para>
1919            Working with PostGIS Databases is seperated into two steps:
1920            <itemizedlist>
1921            <listitem><para>Opening a Database Connection</para></listitem>
1922            <listitem><para>Loading a Data Layer</para></listitem>
1923            </itemizedlist>
1924      </para>
1925            <section><title>Opening a Database Connection</title>
1926            <para>
1927                    Before a data layer can be loaded from a PostGIS database a
1928                    connection with the database has to be established.
1929                    <menuchoice>
1930                    <guimenu>Session</guimenu>
1931                    <guimenuitem>Database Connections ...</guimenuitem>
1932                    </menuchoice> opens a dialog for database connection
1933                    management. In the dialog new connections can be added
1934                    and existing ones can be removed. Removing a database
1935                    connection is not possible if the map still displays a
1936                    layer provided by this database connection.
1937            </para>
1938        <figure>
1939        <title>Database Management Dialog</title>
1940        <mediaobject>
1941        <imageobject><imagedata fileref="./images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
1942        <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
1943        </mediaobject>
1944        </figure>
1945    
1946            <para>
1947                    To add a new database connection to the session a dialog is
1948                    opened to specify the relevant connection data. Enter all
1949                    data relevant for your connection. If the connection fails
1950                    the dialog remains open and provides some hints on the failure.
1951            </para>
1952            <figure>
1953            <title>Add Database Dialog</title>
1954            <mediaobject>
1955            <imageobject><imagedata fileref="./images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
1956            <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
1957            </mediaobject>
1958            </figure>
1959            
1960            <para>
1961            It is important to note that information on database connections are
1962            also stored with the session. Passwords are NOT stored. If you load a
1963            session with database connections you are asked to enter these
1964            passwords again where required.
1965            </para>
1966    
1967            </section>
1968    
1969            <section><title>Loading a Data Layer</title>
1970            <para>
1971            Data layers as part of a map are loaded with the
1972            <menuchoice>
1973            <guimenu>Map</guimenu>
1974            <guimenuitem>Add Database Layer ...</guimenuitem>
1975            </menuchoice> menu item. A dialog is raised displaying two choice
1976            lists. In the left list all connected databases are shown.
1977            Highlighting
1978            one of these and issuing a retrieval results in a list of available
1979            layer tables from that database. After selection of a
1980            layer the dialog is closed.
1981            </para>
1982            <figure>
1983            <title>Add Database Dialog</title>
1984            <mediaobject>
1985            <imageobject><imagedata fileref="./images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
1986            <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
1987            </mediaobject>
1988            </figure>
1989            
1990            </section>
1991    
1992      </appendix>
1993    
1994    <appendix><title>Supported Projections</title>    <appendix><title>Supported Projections</title>
1995      <para>      <para>
1996      The following types of projections are directly support by      The following types of projections are directly support by
1997      Thuban. The specific values for each are provided by the user      Thuban. The specific values for each are provided by the user
1998      to create custom projections. Thuban comes with predefined      to create custom projections. Thuban comes with predefined
1999      projections and are available through the Projections dialog.      projections which are available through the Projections dialog.
2000        </para>
2001        <itemizedlist>
2002        <listitem>
2003            <para>Geographic</para>
2004            <itemizedlist>
2005            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2006            <listitem><para>
2007                    <literal>Source Data</literal>: either Degrees or Radians
2008                    </para></listitem>
2009            </itemizedlist>
2010        </listitem>
2011        <listitem>
2012            <para>Lambert Conic Conformal</para>
2013        <itemizedlist>
2014            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2015            <listitem><para><literal>Latitude of 1st standard parallel</literal></para></listitem>
2016            <listitem><para><literal>Latitude of 2nd standard parallel</literal></para></listitem>
2017            <listitem><para><literal>Central Meridian</literal></para></listitem>
2018            <listitem><para><literal>Latitude of Origin</literal></para></listitem>
2019            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
2020            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
2021        </itemizedlist>
2022        </listitem>
2023        <listitem>
2024            <para>Transverse Mercator</para>
2025        <itemizedlist>
2026            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2027            <listitem><para><literal>Latitude</literal>of origin</para></listitem>
2028            <listitem><para><literal>Longitude</literal>at central meridian</para></listitem>
2029            <listitem><para><literal>Scale Factor</literal>at central meridian</para></listitem>
2030            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
2031            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
2032        </itemizedlist>
2033        </listitem>
2034        <listitem>
2035            <para>Universal Transverse Mercator</para>
2036        <itemizedlist>
2037            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2038            <listitem><para><literal>Zone</literal>
2039                    (can be guessed appling the Propose button)</para></listitem>
2040            <listitem><para><literal>Southern Hemisphere</literal> flag</para></listitem>
2041        </itemizedlist>
2042        </listitem>
2043        </itemizedlist>
2044        
2045        <para>
2046        Thuban comes with a sample set of map projections for various
2047        European countries. Apart from the basic projection they differ
2048        especially in their parameterization:
2049        </para>
2050        <itemizedlist>
2051        <listitem><para>Belgium Datum 1972 (Lambert Conic Conformal)</para>
2052        </listitem>
2053    
2054        <listitem><para>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</para>
2055        </listitem>
2056    
2057        <listitem><para>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)
2058        </para>
2059        </listitem>
2060    
2061        <listitem><para>Reseau Geodesique Francaise
2062        (France, Lambert Conic Conformal)</para>
2063        </listitem>
2064    
2065        <listitem><para>UK National Grid (United Kingdom, Transverse Mercartor)
2066        </para>
2067        </listitem>
2068        </itemizedlist>
2069    
2070        <para>
2071        Thuban uses the comprehensive PROJ library for projections. PROJ provides
2072        more than the four commonly used projections described above. If needed
2073        Thuban can be easily extended to a new projection covered by PROJ.
2074      </para>      </para>
     <variablelist>  
     <varlistentry>  
     <term>Geographic</term>  
     <listitem><para></para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Lambert Conic Conformal</term>  
     <listitem><para></para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Transverse Mercator</term>  
     <listitem><para></para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Universal Transverse Mercator</term>  
     <listitem><para></para></listitem>  
     </varlistentry>  
     </variablelist>  
2075    </appendix>    </appendix>
2076    
2077  </book>  </book>
Legend:
Removed from v.1496  
changed lines
  Added in v.2023
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26