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