/[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 1530 by jonathan, Thu Jul 31 09:57:25 2003 UTC revision 2314 by jan, Sun Aug 1 21:31:30 2004 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, 2004</year>
23        <holder>Intevation GmbH</holder>        <holder>Intevation GmbH</holder>
24      </copyright>      </copyright>
25       <revhistory>
26    <!-- comment this first revision out when releasing a real version -->
27         <revision>
28            <revnumber>CVS version $Id$</revnumber>
29            <date></date>
30            <revremark>Under development.</revremark>
31         </revision>
32         <revision>
33            <revnumber>1.0.0</revnumber>
34            <date>22-Jan-2004</date>
35            <revremark>
36                            Corresponds to Thuban 1.0.0.
37                            New: Installation instructions for Win32.
38                    </revremark>
39         </revision>
40         <revision>
41            <revnumber>1.0pre3</revnumber>
42            <date>04-Dec-2003</date>
43            <revremark>
44                            Corresponds to Thuban 1.0rc1.
45                            New: I18n, right button legend menu, EPSG projectons,
46                PostGIS support.
47                    </revremark>
48         </revision>
49         <revision>
50            <revnumber>1.0pre2</revnumber>
51            <date>29-Aug-2003</date>
52            <revremark>
53                            Corresponds to Thuban development release 0.8.1.
54                            New: chapter on extensions.
55                    </revremark>
56         </revision>
57         <revision>
58            <revnumber>1.0pre1</revnumber>
59            <date>08-Aug-2003</date>
60            <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
61         </revision>
62      </revhistory>
63    
64    </bookinfo>    </bookinfo>
65    
66    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
67      <para>      <para>
68      Thuban is a Free Software Geographic Information Systems (GIS) viewer.      Thuban is an interactive geographic data viewer.
69      It is being developed because there is currently no simple interactive      Its development had been started because there was no simple interactive
70      viewer for geographic information available as Free Software. Thuban is      viewer for geographic information available as Free Software. Thuban is
71      written in Python and C++ and uses the wxWindows library allowing it to      written mainly in Python and uses the wxWidgets (former wxWindows)
72        library allowing it to
73      run on many different platforms, including GNU/Linux and Windows.      run on many different platforms, including GNU/Linux and Windows.
74      </para>      </para>
75      <para>      <para>
76      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
77            get a visual
78      impression of the positional relationship of the information that may not      impression of the positional relationship of the information that may not
79      be apparent from simple inspection of the data values themselves.      be apparent from simple inspection of the data values themselves.
80      Thuban allows the user to create a session that displays      Thuban allows the user to create a session that displays
# Line 40  Line 83 
83      </para>      </para>
84      <para>      <para>
85      Thuban arranges a session in a hierarchy. A session contains a map which      Thuban arranges a session in a hierarchy. A session contains a map which
86      consists of layers. Each layer represents one kind of data set. For      consists of layers. Each layer represents a data set. For
87      instance, there may be a layer for roads and another layer for buildings.      instance, there may be a layer for roads and another layer for buildings.
88      These layers can either be vector shapes or images.      These layers can either be vector shapes or images.
89      </para>      </para>
# Line 48  Line 91 
91          <section><title>Installation</title>          <section><title>Installation</title>
92          <para>          <para>
93          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,
94          and Windows 2000. The following list of files that Thuban requires          and Windows 2000. Thuban depends on the following packages. These
95          can be found on the          packages can also be found on the
96          <ulink url="http://thuban.intevation.org/download.html">          <ulink url="http://thuban.intevation.org/download.html">
97          Thuban Download site          Thuban Download site
98          </ulink>.          </ulink>.
99          <variablelist>          </para>
100          <varlistentry>          <para>
101          <term>Debian Testing (sarge)</term>          Required:
102          <listitem>          <itemizedlist>
103              <para>Thuban-0.8.1-1-debian.i386.rpm</para>              <listitem><para>Python 2.2.1
104              <para>GTK 1.2.3</para>                          (<literal>http://www.python.org</literal>)
105              <para>Python 2.2.1</para>                          </para></listitem>
106              <para>Python 2.2 XML Base Tools</para>              <listitem><para>wxWindows 2.4
107              <para>wxWindows 2.4</para>                          (<literal>http://www.wxwindows.org</literal>)
108              <para>wxWindows 2.4 Python Bindings</para>                          </para></listitem>
109              <para>proj 4.4.5 Projection Library</para>              <listitem><para>wxPython 2.4
110              <para>SQLite Python Bindings 0.4.3</para>                          (<literal>http://www.wxpython.org</literal>)
111              <para>GDAL 1.1.8</para>                          </para></listitem>
112          </listitem>              <listitem><para>proj 4.4.5 Projection Library
113          </varlistentry>                          (<literal>http://www.remotesensing.org/proj/</literal>)
114          <varlistentry>                          </para></listitem>
115          <term>RedHat 7.2</term>              <listitem><para>SQLite 2.8.3
116          <listitem>                          <literal>http://www.hwaci.com/sw/sqlite/</literal>)
117              <para>Thuban-0.8.1-1.i386.rpm</para>                          </para></listitem>
118              <para>Python 2.2.1</para>              <listitem><para>PySQLite 0.4.3
119              <para>wxPython 2.4 for Python 2.2 with wxGTK</para>                          (<literal>http://pysqlite.sourceforge.net</literal>)
120              <para>proj 4.4.5 Projection Library</para>                          </para></listitem>
121              <para>SQLite 2.8.3</para>          </itemizedlist>
122              <para>PySQLite 0.4.3</para>          </para>
123              <para>GDAL 1.1.8</para>          <para>
124          </listitem>          Optional:
125          </varlistentry>          <itemizedlist>
126          <varlistentry>              <listitem><para>GDAL 1.1.8
127          <term>Windows 2000</term>                          (<literal>http://www.remotesensing.org/gdal/</literal>)
128          <listitem>                          </para></listitem>
129              <para>Thuban-0.8.1-0.exe</para>              <listitem><para>psycopg 1.0.8
130              <para>Python 2.2.1</para>                          (<literal>http://initd.org/software/psycopg</literal>)
131              <para>wxWindows 2.4 for Python 2.2</para>                          </para></listitem>
132              <para>SQLite Python Libraries</para>              </itemizedlist>
133              <para>GDAL for Thuban</para>          </para>
134          </listitem>                  <para>
135          </varlistentry>                  Along with the source codes, the download page also offers full
136          </variablelist>                  installation packages for Debian, Windows and RPM-based systems
137          </para>                  (Mandrake, RedHat, SuSE, etc).
138                    </para>
139                    <section><title>RPM-based GNU/Linux Systems</title>
140                            <section><title>Installing Binary Packages</title>
141                                    <para>
142                                    The most wide-spread RPM-based GNU/Linux
143                                    Systems are RedHat, Mandrake and SuSE.
144                                    The documentation of these distributions
145                                    should contain information about how to
146                                    install third-party RPM packages.
147                                    Nonetheless, a short summary is provided here.
148                                    </para>
149                                    <para>
150                                    RPM packages can be installed applying several
151                                    tools. The most basic one is the command line
152                                    program "rpm".  The hardware architecture is
153                                    identified in the name of RPM packages, eg.
154                                    'i386' for most Intel/AMD architectures.  
155                                    If you have a different hardware architecture,
156                                    where no binary RPM packages are provided,
157                                    you must rebuild binary packages from the
158                                    RPM source packages first (see below).
159                                    Typical rpm commands look like:
160    
161                                    <programlisting>
162                                    rpm --install Thuban-0.9.0-1.i386.rpm
163                                    </programlisting>
164    
165                                    Depending on what you already have installed
166                                    on your system, you are informed that some
167                                    packages are required, but not installed.
168                                    You need to install them first. Either they
169                                    are provided by your GNU/Linux distributor
170                                    or available somewhere on the Internet.  
171                                    The more essential and special ones are
172                                    provided together with the Thuban package.
173                                    </para>
174    
175                                    <para>
176                                    For rpm exist some graphical user interfaces, notably
177                                    kpackage, GnoRPM and xrpm.
178                                    </para>
179    
180                                    <para>
181                                    Make yourself familiar with one of the tools and apply it
182                                    to install the packages.
183                                    Note, that you need to be administrator (root) for the system
184                                    to do that.
185                                    </para>
186                            </section>
187                            <section><title>Build Binaries from Source Packages</title>
188                                    <para>
189                                    This section describes howto build RPM install-packages
190                                    from RPM source-packages.
191                                    This adapts and optimizes an install-package specifically
192                                    to your system.
193                                    This is especially helpful to resolve version conflicts of
194                                    dependent packages. Furthermore, install-packages for other
195                                    platforms (e.g. PowerPC) can be created.
196                                    </para>
197    
198                                    <para>
199                                    Note: rpm must be at least version 4. Execute
200                                    <literal>rpm --version</literal> to find out about the version.
201                                    </para>
202    
203                                    <para>
204                                    You need to do the following preparations to be able to
205                                    build the packages as a regular user. You should now
206                                    perform the package buling as root since this
207                                    might cause damage to your system.
208                            <itemizedlist>
209                            <listitem>
210                                                    <para>
211                                                    Create RPM directory structure:
212                                                    Choose a directory (e.g. $HOME/myrpm) and create the
213                                                    subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.
214                                                    A possible command sequence for this is:
215                                                    <programlisting>
216                                                    mkdir $HOME/freegisrpm
217                                                    cd $HOME/freegisrpm
218                                                    mkdir BUILD RPMS SOURCES SPECS SRPMS
219                                                    </programlisting>
220                                                    </para>
221                                            </listitem>
222                                            <listitem>
223                                                    <para>
224                                                    Set environment variable RPM_DIR:
225                                                    <programlisting>
226                                                    export RPM_DIR=$HOME/freegisrpm
227                                                    </programlisting>
228                                                    </para>
229                                            </listitem>
230                                            <listitem>
231                                                    <para>
232                                                    Create $HOME/.rpmmacros:
233                                                    This file sets general preferences and some
234                                                    specific settings for signing packages.
235                                                    If you don't have a GnuPG-key, you can skip
236                                                    the signature settings i.e. drop the last 4 lines.
237                                                    A signature becomes important when you want to
238                                                    give away packages to third parties.
239                                                    <programlisting>
240    <![CDATA[
241    %packager Name Lastname <[email protected]>
242    
243    %_topdir /home/mylogin/myrpm
244    
245    %_signature gpg
246    %_gpg_name Name Lastname
247    %_pgp_path ~/.gnupg
248    %_pgpbin /usr/bin/gpg
249    ]]>
250                                                    </programlisting>
251                                                    </para>
252                                            </listitem>
253                            </itemizedlist>
254    
255                                    Now you can install any RPM source-package.
256                                    It's components are installed into the corresponding
257                                    subdirectories of your rpm-directory.
258                                    Essentially these are the sources (into directory SOURCES)
259                                    and the so-called spec-file which contains all build
260                                    instructions. The spec-file will go into the SPEC directory.
261                                    Example:
262                                    <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>
263                                    </para>
264    
265                                    <para>
266                                    Create install-package:
267                                    Go to the directory with the spec-files and rebuild the
268                                    package:
269                                    <programlisting>
270    cd $HOME/mypm/SPECS
271    rpm -bb thuban.spec
272                                    </programlisting>
273                                    Next, you will find the newly created package in
274                                    $HOME/myrpm/RPMS/i386.
275                                    If you build the package for another architecture than
276                                    i386, then the name of the directory has a corresponding name.
277                                    </para>
278                                    <para>
279                                    For documentation of RPM, either type
280                                    <literal>man rpm</literal> or <literal>rpm --help</literal>.
281                                    This will provide you with information on the various command
282                                    line options of RPM.
283                                    For more information see the
284                            <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
285                                    </para>
286                            </section>
287                    </section> <!-- Intro - Installation - RPM-->
288    
289                    <section><title>Win32 Systems</title>
290                    <para>
291                            A common installation package of Thuban for Win32
292                            systems is available from the Thuban website download
293                            section. This installation package is configured for
294                            displaying file based vector data (Shapefiles). For the
295                            display of raster data or the connection to spatial
296                            databases additional steps are needed.  
297                    </para>
298                    <para>
299                            The required Python packages are listed and linked on
300                            the download page as well.  If you don't have Python
301                            installed already, download the packages for Python,
302                            wxPython for Python and the SQLite Python Libraries as
303                            well as the Thuban package. Install all four packages
304                            in the order: Python, wxPython, SQLite, Thuban. Follow
305                            the installation instructions provided by the seperate
306                            setups. The Thuban installation package will add an
307                            entry in the menu folder you configured.
308                    </para>
309                    <section><title>Raster Data: Installation of GDAL</title>
310                    <para>
311                            Enabling the raster data features of Thuban is
312                            straight forward. For the examples we assume that
313                            Thuban has been installed under
314                            <literal>C:\Thuban</literal>:
315                            <itemizedlist>
316                            <listitem>
317                            <para>
318                            Download the zip-archive <ulink
319                            url="ftp://intevation.de/thuban/win2k/gdal-win2k.zip"
320                            >gdal-win2k</ulink>.
321                            </para></listitem>
322                            <listitem><para>Extract the archive (e.g. with
323                            <ulink
324                            url="http://www.info-zip.org/pub/infozip/WiZ.html"
325                            >WiZ (InfoZip)</ulink>) into the
326                            <literal>C:\Thuban\Lib</literal>
327                            directory of your Thuban installation.
328                            </para>
329                            </listitem>
330                            <listitem>
331                            <para>
332                            Extent the <varname>PYTHONPATH</varname>
333                            environment variable (in your Windows Control Panel)
334                            to make the new libraries available for Thuban.
335                            <programlisting>
336    %PYTHONPATH%;C:\Thuban\Lib\gdal;C:\Thuban\Lib\gdal\pymod
337                            </programlisting>
338                            </para>
339                            </listitem>
340                            <listitem>
341                            <para>
342                            Extent also the <varname>PATH</varname>
343                            environment variable accordingly:
344                            <programlisting>
345    %PATH%;C:\Thuban\Lib\gdal
346                            </programlisting>
347                            </para>
348                            </listitem>
349                            </itemizedlist>
350                            After this installation steps Thuban is ready to
351                            display raster data (e.g. the
352                            <literal>island.tif</literal> from the Iceland Demo
353                            data set.
354                    </para>
355                    </section> <!-- Win32: GDAL-->
356    
357                    <section><title>Working with PostGIS: Installation of PsycoPG</title>
358                    <para>
359                            To access PostgreSQL/PostGIS spatial databases with
360                            Thuban you have to install the PsycoPG package for
361                            Windows:
362                            <itemizedlist>
363                            <listitem>
364                            <para>
365                            Download the zip-archive
366                            <ulink
367                                    url="http://stickpeople.com/projects/python/win-psycopg/win-psycopg22.zip"
368                            >win-psycopg22.zip</ulink>.
369                            </para>
370                            </listitem>
371                            <listitem>
372                            <para>
373                            Extract the zip-archive into a directory either already
374                            in your <varname>PYTHONPATH</varname> or extent your
375                            <varname>PYTHONPATH</varname> variable to the directory
376                            you have extracted the archive to.
377                            </para>
378                            </listitem>
379                            </itemizedlist>
380                            For installation and maintenance of spatial databases
381                            we refer to the  <ulink
382                            url="http://postgis.refractions.net"
383                            >PostGIS Homepage</ulink>.
384                    </para>
385                    </section> <!-- Win32: PsycoPG-->
386    
387                    </section> <!-- Intro - Installation - Win32 -->
388          </section>          </section>
389    
390            <section><title>Internationalization</title>
391            <para>
392            Thuban is implemented with internationalization support. So far Thuban
393            is translated by volunteers to the following languages (apart from its
394            main language: English):
395            <itemizedlist>
396                <listitem><para>French</para></listitem>
397                <listitem><para>German</para></listitem>
398                <listitem><para>Italian</para></listitem>
399                    <listitem><para>Portuguese (Brazilian)</para></listitem>
400                <listitem><para>Russian</para></listitem>
401                <listitem><para>Spanish</para></listitem>
402            </itemizedlist>
403            </para>
404    
405            <para>
406            To use internationalization under POSIX systems (like GNU/Linux)
407            you have to set the environment variable LC_ALL accordingly (e.g.
408            LC_ALL=fr_FR for the french language support). Please check your
409            systems documentation for details and supported settings.
410            Specifiying LC_ALL on the command line while launching thuban
411            allows appication specific language settings:
412            </para>
413            <programlisting>
414            LC_ALL=fr_FR thuban.py
415            </programlisting>
416    
417            <para>
418            MS Windows users have to specify the language to be used via the control
419            bar (which effects all applications).
420            </para>
421            </section>
422    
423          <section><title>The Main Window</title>          <section><title>The Main Window</title>
424          <para>          <para>
425          <screenshot>          <figure>
426          <screeninfo>The Main Window</screeninfo>          <title>The Main Window</title>
427          <mediaobject>          <mediaobject>
428          <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>
429          <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>  
430          </mediaobject>          </mediaobject>
431          </screenshot>          </figure>
432          </para>          </para>
433    
434          <para>          <para>
# Line 160  Line 484 
484          If a session is already loaded and has been modified without          If a session is already loaded and has been modified without
485          being saved a prompt will ask if the current session should          being saved a prompt will ask if the current session should
486          be saved. A new session consists of an empty map with no          be saved. A new session consists of an empty map with no
487          layers and no tables.          layers, no tables and no projection.
488          </para>          </para>
489          </section>          </section>
490    
# Line 187  Line 511 
511          <menuchoice>          <menuchoice>
512          <guimenu>File</guimenu>          <guimenu>File</guimenu>
513          <guimenuitem>Save Session</guimenuitem>          <guimenuitem>Save Session</guimenuitem>
514          </menuchoice>. A dialog box will open allowing the user to browse          </menuchoice>.
515                    In the case the session is not a new and unsaved one,
516                    the corresponding file is updated with the current session
517                    data.
518                    In the case the current session is a new one and yet unsaved
519                    a dialog box will open allowing the user to browse
520          the file system and select a place to save the session. Thuban          the file system and select a place to save the session. Thuban
521          sessions should be saved under a name ending in          sessions should be saved under a name ending in
522          <varname>.thuban</varname>. If the file already exists the user          <varname>.thuban</varname>. If the file already exists the user
# Line 198  Line 527 
527    
528          <section><title>The Session Info-Tree</title>          <section><title>The Session Info-Tree</title>
529          <para>          <para>
530          <screenshot>          <figure>
531          <screeninfo>Session Info Tree</screeninfo>          <title>Session Info Tree</title>
532          <mediaobject>          <mediaobject>
533          <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>
534          <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>  
535          </mediaobject>          </mediaobject>
536          </screenshot>          </figure>
537          </para>          </para>
538          <para>          <para>
539          The session info-tree is primarily intended for developers working          The session info-tree is primarily intended for developers working
# Line 248  Line 575 
575    
576          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
577          <para>          <para>
578          There are two types of layers that can be added to a map: shape layers          There are three types of layers that can be added to a map:
579            Shape layers, database layers
580          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
581          standard file format for storing geographic objects. These          widely used file format for storing geographic objects. These
582          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
583          the shape file is a database file which stores attributes for          the shape file is a database file which stores attributes for
584          each shape in the shape file. This file, in dBase format,          each shape in the Shape file. This file, in dBase format,
585          has the extension ``.dbf''. Both files must have the same base name.          has the extension ``.dbf''. Both files must have the same base name.
586          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
587          also be a file roads.dbf.          also be a file roads.dbf.
588          </para>          </para>
589          <para>          <itemizedlist>
590            <listitem>
591            <para>
592          Shape layers can be added to the map with          Shape layers can be added to the map with
593          <menuchoice>          <menuchoice>
594          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
595          <guimenuitem>Add Layer</guimenuitem>          <guimenuitem>Add Layer</guimenuitem>
596          </menuchoice>.          </menuchoice>.
597          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
598          matter if the shape file or database file is selected.                  selection. However, if you switch to display all files and select one
599          </para>                  of the associated files (e.g. ``.dbf''), Thuban will recognize the base
600                    name and load the corresponding Shape file.
601            </para>
602                    <para>
603                    The file dialog for Shape files allows to select multiple files.
604                    Use the shift-button together with the left mouse button to extend
605                    the selection.
606            </para>
607            </listitem>
608    
609            <listitem>
610            <para>Database layers can be added to the map with
611            <menuchoice>
612            <guimenu>Map</guimenu>
613            <guimenuitem>Add Database Layer</guimenuitem>
614            </menuchoice>.
615            A dialog with two is list is opened. The left list displays all
616            database connections currently open for the session. You can retrieve
617            a list of available layers from the selected database which is
618            displayed on the right hand. From this list one layer can be selected,
619            the dialog is closed afterwards.
620            </para>
621            <para>
622            See appendix ``Working with PostGIS'' for details.
623            </para>
624            </listitem>
625    
626            <listitem>
627          <para>          <para>
628          Image layers can be added to the map with          Image layers can be added to the map with
629          <menuchoice>          <menuchoice>
# Line 279  Line 635 
635          or in another file. If geographic information cannot be found, Thuban          or in another file. If geographic information cannot be found, Thuban
636          will report an error.          will report an error.
637          </para>          </para>
638            </listitem>
639            </itemizedlist>
640          </section>          </section>
641    
642          <section><title>Navigation</title>          <section><title>Navigation</title>
# Line 287  Line 645 
645          the tool bar or from the          the tool bar or from the
646          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.
647          </para>          </para>
648            <itemizedlist>
649            <listitem>
650          <para>          <para>
651          The ZoomIn tool          The ZoomIn tool
652          <inlinemediaobject>          <inlinemediaobject>
# Line 303  Line 663 
663          was clicked. Clicking and dragging selects a region that will be          was clicked. Clicking and dragging selects a region that will be
664          enlarged to fit the window.          enlarged to fit the window.
665          </para>          </para>
666            </listitem>
667            <listitem>
668          <para>          <para>
669          The ZoomOut tool          The ZoomOut tool
670          <inlinemediaobject>          <inlinemediaobject>
# Line 319  Line 681 
681          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
682          scaled to fit into that box.          scaled to fit into that box.
683          </para>          </para>
684            </listitem>
685            <listitem>
686          <para>          <para>
687          The Pan tool          The Pan tool
688          <inlinemediaobject>          <inlinemediaobject>
# Line 332  Line 696 
696          </inlinemediaobject>          </inlinemediaobject>
697          allows the user to move the map around by clicking and dragging.          allows the user to move the map around by clicking and dragging.
698          </para>          </para>
699            </listitem>
700            <listitem>
701          <para>          <para>
702          The Full Extent tool          The Full Extent tool
703          <inlinemediaobject>          <inlinemediaobject>
# Line 345  Line 711 
711          </inlinemediaobject>          </inlinemediaobject>
712          rescales the viewable region so that the entire map is visible.          rescales the viewable region so that the entire map is visible.
713          </para>          </para>
714            </listitem>
715            <listitem>
716          <para>          <para>
717          The Full Layer Extent tool          The Full Layer Extent tool
718          <inlinemediaobject>          <inlinemediaobject>
# Line 360  Line 728 
728          layer fits within the window. If no layer is selected this button          layer fits within the window. If no layer is selected this button
729          will be disabled.          will be disabled.
730          </para>          </para>
731            </listitem>
732            <listitem>
733          <para>          <para>
734          The Full Shape Extent tool          The Full Shape Extent tool
735          <inlinemediaobject>          <inlinemediaobject>
# Line 379  Line 749 
749          in a tableview (see below).          in a tableview (see below).
750    
751          </para>          </para>
752            </listitem>
753            </itemizedlist>
754          </section>          </section>
755    
756          <section><title>Object Identification</title>          <section><title>Object Identification</title>
# Line 447  Line 819 
819          <menuchoice><guimenu>Map</guimenu></menuchoice>.          <menuchoice><guimenu>Map</guimenu></menuchoice>.
820          </para>          </para>
821    
822            <itemizedlist>
823            <listitem>
824          <para>          <para>
825          The Move Layer to Top tool          The Move Layer to Top tool
826          <inlinemediaobject>          <inlinemediaobject>
# Line 459  Line 833 
833          <textobject> <phrase>Move Layer to Top</phrase> </textobject>          <textobject> <phrase>Move Layer to Top</phrase> </textobject>
834          </inlinemediaobject> raises the selected layer to the top of the map.          </inlinemediaobject> raises the selected layer to the top of the map.
835          </para>          </para>
836            </listitem>
837            <listitem>
838    
839          <para>          <para>
840          The Move Layer Up tool          The Move Layer Up tool
# Line 472  Line 848 
848          <textobject> <phrase>Move Layer Up</phrase> </textobject>          <textobject> <phrase>Move Layer Up</phrase> </textobject>
849          </inlinemediaobject> raises the selected layer one level.          </inlinemediaobject> raises the selected layer one level.
850          </para>          </para>
851            </listitem>
852            <listitem>
853    
854          <para>          <para>
855          The Move Layer Down tool          The Move Layer Down tool
# Line 486  Line 864 
864          </inlinemediaobject> lowers the selected layer one level.          </inlinemediaobject> lowers the selected layer one level.
865          </para>          </para>
866    
867            </listitem>
868            <listitem>
869          <para>          <para>
870          The Move Layer to Bottom tool          The Move Layer to Bottom tool
871          <inlinemediaobject>          <inlinemediaobject>
# Line 499  Line 879 
879          </inlinemediaobject> lowers the selected layer to the bottom of the map.          </inlinemediaobject> lowers the selected layer to the bottom of the map.
880          </para>          </para>
881    
882            </listitem>
883            <listitem>
884          <para>          <para>
885          The Visible tool          The Visible tool
886          <inlinemediaobject>          <inlinemediaobject>
# Line 513  Line 895 
895          hidden.          hidden.
896          </para>          </para>
897    
898            </listitem>
899            <listitem>
900          <para>          <para>
901          The Invisible tool          The Invisible tool
902          <inlinemediaobject>          <inlinemediaobject>
# Line 526  Line 910 
910          </inlinemediaobject> hides the selected layer in the map.          </inlinemediaobject> hides the selected layer in the map.
911          </para>          </para>
912    
913            </listitem>
914            <listitem>
915          <para>          <para>
916          The Properties tool          The Properties tool
917          <inlinemediaobject>          <inlinemediaobject>
# Line 540  Line 926 
926          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
927          properties dialog for that layer.          properties dialog for that layer.
928          </para>          </para>
929            </listitem>
930            </itemizedlist>
931    
932            <para>
933            The most used layer related actions are also available from a
934            popup menu. It is raised when a layer is clicked with the right mouse
935            button.
936            </para>
937            
938            <para>
939            <figure>
940            <title>Layer Popup Menu</title>
941            <mediaobject>
942            <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
943            <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
944            </mediaobject>
945            </figure>
946            </para>
947    
948          <para>          <para>
949          Along the bottom of the legend is the scalebar. The scalebar          Along the bottom of the legend is the scalebar. The scalebar
# Line 585  Line 989 
989    
990          <section><title>Types of Layers</title>          <section><title>Types of Layers</title>
991          <para>          <para>
992          There are two types of layers supported by Thuban: shape layers and          There are three types of layers supported by Thuban: shape layers,
993            database layers and
994          image layers. Shape layers consist of vector based shapes with          image layers. Shape layers consist of vector based shapes with
995          geo-referenced coordinates. There are three types of supported          geo-referenced coordinates. There are three types of supported
996          shapes: polygons, lines (arc), and points. Image layers can be any image          shapes: polygons, lines (arc), and points. Database layers are similar
997            to shape layers but loaded from a database instead of the file system.
998            Image layers can be any image
999          file format supported by the Geo-spatial Data Abstraction Library          file format supported by the Geo-spatial Data Abstraction Library
1000          (GDAL). The images must have geographic          (GDAL). The images must have geographic
1001          coordinate data either embedded within the file or in a separate          coordinate data either embedded within the file or in a separate
# Line 619  Line 1026 
1026          and type.          and type.
1027          </para>          </para>
1028          <para>          <para>
1029          <screenshot>          <figure>
1030          <screeninfo>Properties Window</screeninfo>          <title>Properties Window</title>
1031          <mediaobject>          <mediaobject>
1032          <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>
1033          <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>  
1034          </mediaobject>          </mediaobject>
1035          </screenshot>          </figure>
1036          </para>          </para>
1037          <para>          <para>
1038          <screenshot>          <figure>
1039          <screeninfo>Properties Window</screeninfo>          <title>Properties Window</title>
1040          <mediaobject>          <mediaobject>
1041          <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>
1042          <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>  
1043          </mediaobject>          </mediaobject>
1044          </screenshot>          </figure>
1045          </para>          </para>
1046          </section>          </section>
1047    
# Line 735  Line 1138 
1138          changes will not be applied to the map.          changes will not be applied to the map.
1139          </para>          </para>
1140          <para>          <para>
1141          <screenshot>          <figure>
1142          <screeninfo>Properties Window</screeninfo>          <title>Properties Window</title>
1143          <mediaobject>          <mediaobject>
1144          <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>
1145          <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>  
1146          </mediaobject>          </mediaobject>
1147          </screenshot>          </figure>
1148          </para>          </para>
1149          <para>          <para>
1150          The order of the groups in the classification is significant          The order of the groups in the classification is significant
# Line 809  Line 1210 
1210    
1211          <section><title>Generating Classes</title>          <section><title>Generating Classes</title>
1212          <para>          <para>
1213          <screenshot>          <figure>
1214          <screeninfo>Generate Class</screeninfo>          <title>Generate Class</title>
1215          <mediaobject>          <mediaobject>
1216          <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>
1217          <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>  
1218          </mediaobject>          </mediaobject>
1219          </screenshot>          </figure>
1220          </para>          </para>
1221          <para>          <para>
1222          Creating a classification by hand can be tedious.          Creating a classification by hand can be tedious.
# Line 846  Line 1245 
1245          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
1246          properties of the last group. Thuban will interpolate between these          properties of the last group. Thuban will interpolate between these
1247          two properties to generate the other groups.          two properties to generate the other groups.
1248          <screenshot>          <figure>
1249          <screeninfo>Custom Color Scheme</screeninfo>          <title>Custom Color Scheme</title>
1250          <mediaobject>          <mediaobject>
1251          <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>
1252          <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Custom Color Scheme</phrase></textobject>  
         <caption><para>Custom Color Scheme</para></caption>  
1253          </mediaobject>          </mediaobject>
1254          </screenshot>          </figure>
1255          </para>          </para>
1256          <para>          <para>
1257          The Unique Values option lets the user select specific values that          The Unique Values option lets the user select specific values that
# Line 864  Line 1261 
1261          right. Each list can be sorted or reversed for easier searching.          right. Each list can be sorted or reversed for easier searching.
1262          The classification that is generated will be in the same order as          The classification that is generated will be in the same order as
1263          the list on the right.          the list on the right.
1264          <screenshot>          <figure>
1265          <screeninfo>Unique Values</screeninfo>          <title>Unique Values</title>
1266          <mediaobject>          <mediaobject>
1267          <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>
1268          <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Unique Values</phrase></textobject>  
         <caption><para>Unique Values Classification</para></caption>  
1269          </mediaobject>          </mediaobject>
1270          </screenshot>          </figure>
1271          </para>          </para>
1272          <para>          <para>
1273          The Uniform Distribution option creates a user specified number of          The Uniform Distribution option creates a user specified number of
# Line 881  Line 1276 
1276          table by clicking <guibutton>Retrieve From Table</guibutton>. The          table by clicking <guibutton>Retrieve From Table</guibutton>. The
1277          stepping is how large each interval is. Adjusting this value will          stepping is how large each interval is. Adjusting this value will
1278          automatically recalculate how many groups is appropriate.          automatically recalculate how many groups is appropriate.
1279          <screenshot>          <figure>
1280          <screeninfo>Uniform Distribution</screeninfo>          <title>Uniform Distribution</title>
1281          <mediaobject>          <mediaobject>
1282          <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>
1283          <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Uniform Distribution</phrase></textobject>  
         <caption><para>Uniform Distribution Classification</para></caption>  
1284          </mediaobject>          </mediaobject>
1285          </screenshot>          </figure>
1286          </para>          </para>
1287          <para>          <para>
1288          The Quantiles option generates ranges based on the number of items          The Quantiles option generates ranges based on the number of items
# Line 897  Line 1290 
1290          generate five groups with appropriate ranges such that 20% of the table          generate five groups with appropriate ranges such that 20% of the table
1291          data is in each group. If it is impossible to generate exact          data is in each group. If it is impossible to generate exact
1292          groupings, Thuban will issue a warning but allow the user to continue.          groupings, Thuban will issue a warning but allow the user to continue.
1293          <screenshot>          <figure>
1294          <screeninfo>Quantiles</screeninfo>          <title>Quantiles</title>
1295          <mediaobject>          <mediaobject>
1296          <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>
1297          <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Quantiles</phrase></textobject>  
         <caption><para>Quantiles Classification</para></caption>  
1298          </mediaobject>          </mediaobject>
1299          </screenshot>          </figure>
1300          </para>          </para>
1301          </section>          </section>
1302    </chapter>    </chapter>
# Line 927  Line 1318 
1318      <guimenu>Layer</guimenu>      <guimenu>Layer</guimenu>
1319      <guimenuitem>Projection</guimenuitem>      <guimenuitem>Projection</guimenuitem>
1320      </menuchoice>.      </menuchoice>.
1321      <screenshot>      <figure>
1322      <screeninfo>Projection Window</screeninfo>      <title>Projection Window</title>
1323      <mediaobject>      <mediaobject>
1324      <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>      <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>
1325      <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>  
1326      </mediaobject>      </mediaobject>
1327      </screenshot>      </figure>
1328        </para>
1329        <para>
1330        Thuban is distributed with a sample collection of projections and the
1331        set of coordinate systems as used by the EPSG
1332        (European Petroleum Survey Group). This quite large set is only displayed
1333        if activated by the according checkbox. The set falls into two parts:
1334        deprecated lists all projections which are no longer part of the
1335        EPSG data base.
1336      </para>      </para>
1337      <para>      <para>
1338      Thuban is distributed with a sample collection of projections. The           The
1339      user can create new projections and make them available to all      user can create new projections and make them available to all
1340      future Thuban sessions. They may also be exported and imported so      future Thuban sessions. They may also be exported and imported so
1341      that custom projections can be distributed.      that custom projections can be distributed.
# Line 1005  Line 1402 
1402    
1403      <section><title>Table View</title>      <section><title>Table View</title>
1404          <para>          <para>
1405          <screenshot>          <figure>
1406          <screeninfo>Table View</screeninfo>          <title>Table View</title>
1407          <mediaobject>          <mediaobject>
1408          <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>
1409          <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>  
1410          </mediaobject>          </mediaobject>
1411          </screenshot>          </figure>
1412          </para>          </para>
1413          <para>          <para>
1414          Thuban provides a standard dialog to display table contents, the          Thuban provides a standard dialog to display table contents, the
# Line 1134  Line 1529 
1529    
1530          <section><title>Join</title>          <section><title>Join</title>
1531              <para>              <para>
1532              <screenshot>              <figure>
1533              <screeninfo>Join Tables</screeninfo>              <title>Join Tables</title>
1534              <mediaobject>              <mediaobject>
1535              <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>
1536              <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>  
1537              </mediaobject>              </mediaobject>
1538              </screenshot>              </figure>
1539              </para>              </para>
1540              <para>              <para>
1541              The              The
# Line 1222  Line 1615 
1615      </section>      </section>
1616    </chapter>    </chapter>
1617    
1618      <chapter><title>Extensions</title>
1619            <para>
1620            Thuban is designed to be extensible. The term Extension is used as a
1621            general term for anything that extends Thuban.
1622            This chapter introduces into some oppportunities how to add and
1623            handle extra functionality developed by your own or third parties.
1624            </para>
1625    
1626            <section><title>Add personal extensions via thubanstart.py</title>
1627                    <para>
1628                    After Thuban has been started for the first time, a directory
1629                    .thuban is created within your home directory.
1630                    There you can add a file thubanstart.py  which will be imported
1631                    by Thuban at start-up. It is recommended to add only import-statements
1632                    to this file to keep the actual code of extensions separate.
1633                    </para>
1634                    <para>
1635                    The modules to import must either be found through the environment
1636                    variable PYTHONPATH or directly be placed into the .thuban-directory.
1637                    </para>
1638                    <para>
1639                    As an example, copy the file examples/simple_extensions/hello_world.py
1640                    of the Thuban source code into the .thuban-directory of your home
1641                    directory. Now add add the statement import hello_world to the
1642                    file thubanstart.py and run Thuban. You will notice an additional
1643                    menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
1644                    the new item for the Hello-World extension is placed - select it
1645                    to see the Hello-World message.
1646                    </para>
1647            </section>
1648    
1649            <section><title>Extensions included in Thuban package</title>
1650                    <para>
1651                    The extensions described in this section are part of the
1652                    Thuban package, but not activated by default.
1653                    You will find them in the Thuban installation directory
1654                    under <literal>Extensions/</literal>. Activate them as personal
1655                    extensions via PYTHONPATH as described in the previous section.
1656                    Stable extensions will appear under the menu
1657                    <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
1658                    extensions which are in experimental state and therefore
1659                    not fully functional under
1660                    <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
1661                    </para>
1662    
1663                    <section><title>Stable extensions</title>
1664                            <para>
1665                            These extensions provide extra-functionality to Thuban
1666                            that has not (yet) been integrated in the main application.
1667                            They are considered to be free of bugs, but may be
1668                            further polished with helpful user interactions.
1669                            </para>
1670                            <section><title>gns2shp</title>
1671                                    <para>
1672                                    This tool converts data of the Geospatial Names Server
1673                                    (GNS, see <ulink url="http://www.nima.mil/gns"/>)
1674                                    into Shapefile format.
1675                                    The above web-site offer to download named places
1676                                    information grouped by countries for all of the world
1677                                    except USA for which other data are provided.
1678                                    </para>
1679                                    <para>
1680                                    If you download and unpack a package, you will have
1681                                    a text-file with suffix .txt.
1682                                    Selecting such a file via gns2shp will create the
1683                                    corresponding Shapefile with the same basename and
1684                                    place it in the same direcory. Afterwards it
1685                                    is automatically loaded into Thuban.
1686                                    The Shapefile will not automatically be delete afterwards.
1687                                    </para>
1688                                    <para>
1689                                    The gns2shp.py module can also be executed on the
1690                                    command line for batch processing purposes.
1691                                    </para>
1692                                    <para>
1693                                    A sample (<literal>ls.txt</literal> for Liechtenstein)
1694                                    is included in the directory
1695                                    <literal>Extensions/gns2shp/test</literal>.
1696                                    </para>
1697                            </section>
1698                    </section>
1699                    <section><title>Experimental extensions</title>
1700                            <para>
1701                            All all of these functions have to be handled with care,
1702                            since they are neither complete nor well tested.
1703                            They are to be seen as a proof-of-concept and may
1704                            additionally in some cases of practical help.
1705                            </para>
1706                            <para>
1707                            Any interest on further improvement of these extensions
1708                            should be communicated towards the developer and user
1709                            community.
1710                            </para>
1711    
1712                            <section><title>importAPR</title>
1713                                    <para>
1714                                    This command offer to load an ESRI� ArcView� project
1715                                    file (suffix .apr) and convert it for use within Thuban.
1716                                    After selecting a apr-file to load, a list
1717                                    will be presented that offers to select one of the views
1718                                    of the apr-file, provided there is more than one.
1719                                    Furthermore, the Session Info-Tree is extended with
1720                                    a complete representation of the parsed apr-file.
1721                                    </para>
1722                                    <para>
1723                                    The legend of Thuban does not yet cover all of the elements as
1724                                    supported by the legend of ArcView�. Therefore, the Thuban
1725                                    map will look different. Furthermore, the apr-format is
1726                                    a proprietary format, not openly documented.
1727                                    Therefore, the interpretation is
1728                                    partly based on reverse engeneering and good guessing.
1729                                    </para>
1730                                    <para>
1731                                    The file-paths within the apr-file may not fit and potentially
1732                                    are subject to fix in the apr-file. You can do this
1733                                    applying any text editor. The paths are either absolute
1734                                    or relative from where Thuban has been started.
1735                                    </para>
1736                                    <para>
1737                                    A sample for the Iceland data is included as
1738                                    <literal>Extensions/importAPR/samples/iceland.apr</literal>.
1739                                    The file-paths are relative from the Thuban main directory.
1740                                    </para>
1741                            </section>
1742                    </section>
1743            </section>
1744    
1745            <section><title>Writing simple extensions</title>
1746                    <para>
1747                    Writing an extension for Thuban basically means to
1748                    implement the extra functionality in Python with all of the
1749                    Thuban classes, methods and variables available.
1750                    </para>
1751                    <para>
1752                    All classes and their methods are documented in the source code
1753                    (see their doc-strings). Here is an example from
1754                    Thuban/Model/layer.py that describes some of the methods
1755                    of a Layer object:
1756                    </para>
1757                    <programlisting>
1758                    <![CDATA[
1759    class BaseLayer(TitledObject, Modifiable):
1760    
1761        """Base class for the layers."""
1762    
1763        def __init__(self, title, visible = True, projection = None):
1764            """Initialize the layer.
1765    
1766            title -- the title
1767            visible -- boolean. If true the layer is visible.
1768            """
1769            TitledObject.__init__(self, title)
1770            Modifiable.__init__(self)
1771            self.visible = visible
1772            self.projection = projection
1773    
1774        def Visible(self):
1775            """Return true if layer is visible"""
1776            return self.visible
1777    
1778        def SetVisible(self, visible):
1779            """Set the layer's visibility."""
1780            self.visible = visible
1781            self.issue(LAYER_VISIBILITY_CHANGED, self)
1782    
1783        def HasClassification(self):
1784            """Determine if this layer support classifications."""
1785    ...
1786                    ]]>
1787                    </programlisting>
1788                    <para>
1789                    This example intends to give you an impression of the
1790                    source-code-level documentation.
1791                    You have to make yourself familiar with
1792                    the Python programming language to understand some special
1793                    code elements.
1794                    </para>
1795                    <section><title>hello_world.py</title>
1796                      <para>
1797                      Traditionally, the first example should welcome the world.
1798                      Most of the code handles the frame for integrating a menu
1799                      item into Thuban while the actual raising of a message
1800                      is done in a single line.
1801                      </para>
1802                            <programlisting>
1803                            <![CDATA[
1804    # Copyright (C) 2003 by Intevation GmbH
1805    # Authors:
1806    # Jan-Oliver Wagner <[email protected]>
1807    #
1808    # This program is free software under the GPL (>=v2)
1809    # Read the file COPYING coming with Thuban for details.
1810    
1811    """
1812    Extend Thuban with a sample Hello World to demonstrate simple
1813    extensions.
1814    """
1815    
1816    __version__ = '$Revision$'
1817    
1818    # use _() already now for all strings that may later be translated
1819    from Thuban import _
1820    
1821    # Thuban has named commands which can be registered in the central
1822    # instance registry.
1823    from Thuban.UI.command import registry, Command
1824    
1825    # The instance of the main menu of the Thuban application
1826    # See Thuban/UI/menu.py for the API of the Menu class
1827    from Thuban.UI.mainwindow import main_menu
1828    
1829    def hello_world_dialog(context):
1830        """Just raise a simple dialog to greet the world.
1831    
1832        context -- The Thuban context.
1833        """
1834        context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
1835    
1836    
1837    # create a new command and register it
1838    registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
1839                         helptext = _('Welcome everyone on this planet')))
1840    
1841    # find the extensions menu (create it anew if not found)
1842    extensions_menu = main_menu.FindOrInsertMenu('extensions', _('E&xtensions'))
1843    
1844    # finally bind the new command with an entry in the extensions menu
1845    extensions_menu.InsertItem('hello_world')
1846                            ]]>
1847                            </programlisting>
1848                    </section>
1849                    <section><title>Registering a Command</title>
1850                      <para>
1851                      Mainly, our new function has to be registered to the Thuban
1852                      framework in order to connect it to the menu. A registered
1853                      command can also be connected to e.g. a toolbar button.
1854                      </para>
1855                      <para>
1856                      The instances and classes for this are imported at the beginning.
1857                      Any code not inside a method or class is directly executed when
1858                      the source-code module is imported. Therefore, the second
1859                      part of this example consist of the plain statements to create a new
1860                      Command and to add it to the menu.
1861                      </para>
1862                      <para>
1863                      By convention, it looks for a menu registered as ``extensions'' to
1864                      insert the new command. If it does not exist yet, it gets created.
1865                      It is advisable to copy this code for any of your extensions.
1866                      </para>
1867                    </section>
1868                    <section><title>The Thuban context</title>
1869                            <para>
1870                            A registered command that is called, always receives the
1871                            Thuban context. This instance provides our method with
1872                            hook references to all important components of the Thuban
1873                            application.
1874                            </para>
1875                            <para>
1876                    In the example hello_world.py, our function uses the
1877                            mainwindow component which offers a method to raise a
1878                            message dialog. In total there are three hooks:
1879                            <itemizedlist>
1880                            <listitem>
1881                            <para>application:
1882                            This object is the instance of the Thuban Application class.
1883                            Except maybe for loading or savinf sessions, you will not
1884                            need this object for a simple extension.
1885                            See Thuban/UI/application.py for the API.
1886                            </para>
1887                            </listitem>
1888                            <listitem>
1889                            <para>session:
1890                            The instance of the current session. It manages the sessions'
1891                            map and tables. You can set and remove the map or tables.
1892                            In may also get the map object. However, you should know that
1893                            internally it is already prepared to handle many maps.
1894                            Therfore, currently you would always receive a list with exactlty
1895                            one element. In the future, if there are more than one map,
1896                            you will not know which one is the currently display one and
1897                            therefore you should use the mainwindow as hook to find
1898                            the currently displayed map.
1899                            See Thuban/Model/session.py for the API.
1900                            </para>
1901                            </listitem>
1902                            <listitem>
1903                            <para>
1904                            mainwindow: The mainwindow object is central to manage various
1905                            GUI things such as the Legend sub-window. Most notably,
1906                            you get access to the canvas which is the window part where
1907                            the map is drawn. The canvas knows, which map it currently
1908                            draws and therefore you get the current map via
1909                            context.mainwindow.canvas.Map().
1910                            See Thuban/UI/mainwindow.py for the API.
1911                            </para>
1912                            </listitem>
1913                            </itemizedlist>
1914                </para>
1915                    </section>
1916            </section>
1917      </chapter>
1918    
1919    <chapter><title>Trouble Shooting</title>    <chapter><title>Trouble Shooting</title>
1920      <para>      <para>
1921      Here are a few problems that users have encountered when first using Thuban.      Here are a few problems that users have encountered when first using Thuban.
1922      </para>      </para>
1923      <para>      <para>
     <variablelist>  
1924    
1925      <varlistentry>      <itemizedlist>
     <term>After adding two or more layers nothing is drawn in the map window.  
     </term>  
1926      <listitem>      <listitem>
1927        <para>After adding two or more layers nothing is drawn in the map window.
1928        </para>
1929      <para>      <para>
1930      This is probably because the layers have different projections. Projections      This is probably because the layers have different projections. Projections
1931      must be set on all layers and on the map itself if the layers' projections      must be set on all layers and on the map itself if the layers' projections
1932      are different.      are different.
1933      </para>      </para>
1934      </listitem>      </listitem>
     </varlistentry>  
1935    
     <varlistentry>  
     <term>Thuban crashes on startup with the error  
         <literal>NameError: global name 'False' is not defined</literal>.  
     </term>  
1936      <listitem>      <listitem>
1937        <para>Thuban crashes on startup with the error
1938            <literal>NameError: global name 'False' is not defined</literal>.
1939        </para>
1940      <para>      <para>
1941      <varname>True</varname> and <varname>False</varname> were only introduced      <varname>True</varname> and <varname>False</varname> were only introduced
1942      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.
1943      </para>      </para>
1944      </listitem>      </listitem>
     </varlistentry>  
1945    
1946      <varlistentry>      <listitem>
1947      <term>After compiling Thuban, Thuban crashes with an error similar to      <para>After compiling Thuban, Thuban crashes with an error similar to
1948          <literal>          <literal>
1949          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
1950          </literal>          </literal>
1951      </term>      </para>
     <listitem>  
1952      <para>      <para>
1953      Thuban depends on the wxWindows library. If Thuban is compiled with an      Thuban depends on the wxWindows library. If Thuban is compiled with an
1954      incompatible version of the compiler than wxWindows was compiled with      incompatible version of the compiler than wxWindows was compiled with
# Line 1267  Line 1956 
1956      compiler.      compiler.
1957      </para>      </para>
1958      </listitem>      </listitem>
1959      </varlistentry>      </itemizedlist>
     </variablelist>  
1960      </para>      </para>
1961      <para>      <para>
1962      If an error occurs Thuban will display a dialog indicating the error      If an error occurs Thuban will display a dialog indicating the error
# Line 1279  Line 1967 
1967      More information about the system is available from      More information about the system is available from
1968      <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.      <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.
1969      This should also be included in the bug report.      This should also be included in the bug report.
1970      <screenshot>      <figure>
1971      <screeninfo>Error Dialog</screeninfo>      <title>Error Dialog</title>
1972      <mediaobject>      <mediaobject>
1973      <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>      <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>
1974      <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>      <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>
     <textobject><phrase>Error Dialog</phrase></textobject>  
     <caption><para>Error Dialog</para></caption>  
1975      </mediaobject>      </mediaobject>
1976      </screenshot>      </figure>
1977      </para>      </para>
1978    
1979    </chapter>    </chapter>
# Line 1324  Line 2010 
2010      </listitem>      </listitem>
2011      </varlistentry>      </varlistentry>
2012    
2013        <varlistentry>
2014        <term>PostGIS</term>
2015        <listitem>
2016            <para>
2017            PostGIS adds support for geographic objects to the PostgreSQL
2018            object-relational database. Different layer types (as for Shapefiles)
2019            are supported. <ulink url="http://postgis.refractions.net">PostGIS
2020            Homepage</ulink>
2021            </para>
2022        </listitem>
2023        </varlistentry>
2024    
2025        <varlistentry>
2026        <term>Raster files</term>
2027        <listitem>
2028            <para>
2029            Binding the GDAL library Thuban supports numerous raster file formats,
2030            see <ulink url="http://www.remotesensing.org/gdal/formats_list.html">
2031            GDAL format list</ulink> for details.</para>
2032    
2033            <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
2034            format: Raster maps are provided as TIFF images, with an additional
2035            "world file" storing the geographic reference (usually with an
2036            extension ".tfw").
2037            </para>
2038        </listitem>
2039        </varlistentry>
2040    
2041      </variablelist>      </variablelist>
2042    </appendix>    </appendix>
2043    
2044      <appendix><title>Working with PostGIS</title>
2045      <para>
2046      This section focusses on the use of PostGIS in the Thuban framework. For
2047      installation and maintenance of spatial databases we refer to the  
2048      <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
2049      The Thuban PostGIS support requires the
2050      <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
2051      </para>
2052    
2053      <para>
2054            Working with PostGIS Databases is seperated into two steps:
2055            <itemizedlist>
2056            <listitem><para>Opening a Database Connection</para></listitem>
2057            <listitem><para>Loading a Data Layer</para></listitem>
2058            </itemizedlist>
2059      </para>
2060            <section><title>Opening a Database Connection</title>
2061            <para>
2062                    Before a data layer can be loaded from a PostGIS database a
2063                    connection with the database has to be established.
2064                    <menuchoice>
2065                    <guimenu>Session</guimenu>
2066                    <guimenuitem>Database Connections ...</guimenuitem>
2067                    </menuchoice> opens a dialog for database connection
2068                    management. In the dialog new connections can be added
2069                    and existing ones can be removed. Removing a database
2070                    connection is not possible if the map still displays a
2071                    layer provided by this database connection.
2072            </para>
2073        <figure>
2074        <title>Database Management Dialog</title>
2075        <mediaobject>
2076        <imageobject><imagedata fileref="../images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
2077        <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
2078        </mediaobject>
2079        </figure>
2080    
2081            <para>
2082                    To add a new database connection to the session a dialog is
2083                    opened to specify the relevant connection data. Enter all
2084                    data relevant for your connection. If the connection fails
2085                    the dialog remains open and provides some hints on the failure.
2086            </para>
2087            <figure>
2088            <title>Add Database Dialog</title>
2089            <mediaobject>
2090            <imageobject><imagedata fileref="../images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
2091            <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
2092            </mediaobject>
2093            </figure>
2094            
2095            <para>
2096            It is important to note that information on database connections are
2097            also stored with the session. Passwords are NOT stored. If you load a
2098            session with database connections you are asked to enter these
2099            passwords again where required.
2100            </para>
2101    
2102            </section>
2103    
2104            <section><title>Loading a Data Layer</title>
2105            <para>
2106            Data layers as part of a map are loaded with the
2107            <menuchoice>
2108            <guimenu>Map</guimenu>
2109            <guimenuitem>Add Database Layer ...</guimenuitem>
2110            </menuchoice> menu item. A dialog is raised displaying two choice
2111            lists. In the left list all connected databases are shown.
2112            Highlighting
2113            one of these and issuing a retrieval results in a list of available
2114            layer tables from that database. After selection of a
2115            layer the dialog is closed.
2116            </para>
2117            <figure>
2118            <title>Add Database Dialog</title>
2119            <mediaobject>
2120            <imageobject><imagedata fileref="../images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
2121            <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
2122            </mediaobject>
2123            </figure>
2124            
2125            </section>
2126    
2127      </appendix>
2128    
2129    <appendix><title>Supported Projections</title>    <appendix><title>Supported Projections</title>
2130      <para>      <para>
2131      The following types of projections are directly support by      The following types of projections are directly support by
# Line 1334  Line 2133 
2133      to create custom projections. Thuban comes with predefined      to create custom projections. Thuban comes with predefined
2134      projections which are available through the Projections dialog.      projections which are available through the Projections dialog.
2135      </para>      </para>
2136      <variablelist>      <itemizedlist>
2137      <varlistentry>      <listitem>
2138          <term>Geographic</term>          <para>Geographic</para>
2139          <listitem><para><literal>Ellipsoid</literal></para>          <itemizedlist>
2140          <para><literal>Source Data</literal>: either Degrees or Radians          <listitem><para><literal>Ellipsoid</literal></para></listitem>
2141            <listitem><para>
2142                    <literal>Source Data</literal>: either Degrees or Radians
2143                  </para></listitem>                  </para></listitem>
2144      </varlistentry>          </itemizedlist>
2145      <varlistentry>      </listitem>
2146          <term>Lambert Conic Conformal</term>      <listitem>
2147          <listitem><para><literal>Ellipsoid</literal></para>          <para>Lambert Conic Conformal</para>
2148          <para><literal>Latitude of 1st standard parallel</literal></para>      <itemizedlist>
2149          <para><literal>Latitude of 2nd standard parallel</literal></para>          <listitem><para><literal>Ellipsoid</literal></para></listitem>
2150          <para><literal>Central Meridian</literal></para>          <listitem><para><literal>Latitude of 1st standard parallel</literal></para></listitem>
2151          <para><literal>Latitude of Origin</literal></para>          <listitem><para><literal>Latitude of 2nd standard parallel</literal></para></listitem>
2152          <para><literal>False Easting</literal> (meters)</para>          <listitem><para><literal>Central Meridian</literal></para></listitem>
2153          <para><literal>False Northing</literal> (meters)</para></listitem>          <listitem><para><literal>Latitude of Origin</literal></para></listitem>
2154      </varlistentry>          <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
2155      <varlistentry>          <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
2156          <term>Transverse Mercator</term>      </itemizedlist>
2157          <listitem><para><literal>Ellipsoid</literal></para>      </listitem>
2158          <para><literal>Latitude</literal>of origin</para>      <listitem>
2159          <para><literal>Longitude</literal>at central meridian</para>          <para>Transverse Mercator</para>
2160          <para><literal>Scale Factor</literal>at central meridian</para>      <itemizedlist>
2161          <para><literal>False Easting</literal> (meters)</para>          <listitem><para><literal>Ellipsoid</literal></para></listitem>
2162          <para><literal>False Northing</literal> (meters)</para></listitem>          <listitem><para><literal>Latitude</literal>of origin</para></listitem>
2163      </varlistentry>          <listitem><para><literal>Longitude</literal>at central meridian</para></listitem>
2164      <varlistentry>          <listitem><para><literal>Scale Factor</literal>at central meridian</para></listitem>
2165          <term>Universal Transverse Mercator</term>          <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
2166          <listitem><para><literal>Ellipsoid</literal></para>          <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
2167          <para><literal>Zone</literal>      </itemizedlist>
2168                  (can be guessed appling the Propose button)</para>      </listitem>
2169          <para><literal>Southern Hemisphere</literal> flag</para></listitem>      <listitem>
2170      </varlistentry>          <para>Universal Transverse Mercator</para>
2171      </variablelist>      <itemizedlist>
2172            <listitem><para><literal>Ellipsoid</literal></para></listitem>
2173            <listitem><para><literal>Zone</literal>
2174                    (can be guessed appling the Propose button)</para></listitem>
2175            <listitem><para><literal>Southern Hemisphere</literal> flag</para></listitem>
2176        </itemizedlist>
2177        </listitem>
2178        </itemizedlist>
2179            
2180      <para>      <para>
2181      Thuban comes with a sample set of map projections for various      Thuban comes with a sample set of map projections for various
2182      European countries. Apart from the basic projection they differ      European countries. Apart from the basic projection they differ
2183      especially in their parameterization:      especially in their parameterization:
2184      </para>      </para>
2185      <variablelist>      <itemizedlist>
2186      <varlistentry><term>Belgium Datum 1972 (Lambert Conic Conformal)</term>      <listitem><para>Belgium Datum 1972 (Lambert Conic Conformal)</para>
2187          <listitem><para></para></listitem>      </listitem>
     </varlistentry>  
2188    
2189      <varlistentry><term>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</term>      <listitem><para>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</para>
2190          <listitem><para></para></listitem>      </listitem>
     </varlistentry>  
2191    
2192      <varlistentry><term>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)      <listitem><para>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)
2193      </term>      </para>
2194          <listitem><para></para></listitem>      </listitem>
     </varlistentry>  
2195    
2196      <varlistentry><term>Reseau Geodesique Francaise      <listitem><para>Reseau Geodesique Francaise
2197      (France, Lambert Conic Conformal)</term>      (France, Lambert Conic Conformal)</para>
2198          <listitem><para></para></listitem>      </listitem>
     </varlistentry>  
2199    
2200      <varlistentry><term>UK National Grid (United Kingdom, Transverse Mercartor)      <listitem><para>UK National Grid (United Kingdom, Transverse Mercartor)
2201      </term>      </para>
2202          <listitem><para></para></listitem>      </listitem>
2203      </varlistentry>      </itemizedlist>
     </variablelist>  
2204    
2205      <para>      <para>
2206      Thuban uses the comprehensive PROJ library for projections. PROJ provides      Thuban uses the comprehensive PROJ library for projections. PROJ provides
Legend:
Removed from v.1530  
changed lines
  Added in v.2314
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26