/[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 1532 by frank, Thu Jul 31 10:58:24 2003 UTC revision 1719 by jan, Fri Sep 19 09:17:10 2003 UTC
# Line 6  Line 6 
6  <!-- $Revision$ -->  <!-- $Revision$ -->
7  <book>  <book>
8    <bookinfo>    <bookinfo>
9      <title>Thuban Manual</title>      <title>User's Manual for Thuban 1.0</title>
10      <author>          <authorgroup>
11        <firstname>Jonathan</firstname><surname>Coles</surname>        <author>
12      </author>          <firstname>Jonathan</firstname><surname>Coles</surname>
13      <author>        </author>
14        <firstname>Jan-Oliver</firstname><surname>Wagner</surname>        <author>
15      </author>          <firstname>Jan-Oliver</firstname><surname>Wagner</surname>
16      <author>        </author>
17        <firstname>Frank</firstname><surname>Koormann</surname>        <author>
18      </author>          <firstname>Frank</firstname><surname>Koormann</surname>
19          </author>
20            </authorgroup>
21      <copyright>      <copyright>
22        <year>2003</year>        <year>2003</year>
23        <holder>Intevation GmbH</holder>        <holder>Intevation GmbH</holder>
24      </copyright>      </copyright>
25       <revhistory>
26    <!-- comment this first revision out when releasing a real version -->
27    <!--
28         <revision>
29            <revnumber>CVS version $Id$</revnumber>
30            <date></date>
31            <revremark>Under development.</revremark>
32         </revision>
33    -->
34         <revision>
35            <revnumber>1.0pre2</revnumber>
36            <date>29-Aug-2003</date>
37            <revremark>
38                            Corresponds to Thuban development release 0.8.1.
39                            New: chapter on extensions.
40                    </revremark>
41         </revision>
42         <revision>
43            <revnumber>1.0pre1</revnumber>
44            <date>08-Aug-2003</date>
45            <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
46         </revision>
47      </revhistory>
48    
49    </bookinfo>    </bookinfo>
50    
51    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
52      <para>      <para>
53      Thuban is a Free Software Geographic Information Systems (GIS) viewer.      Thuban is an interactive geographic data viewer.
54      It is being developed because there is currently no simple interactive      It has been developed because there was no simple interactive
55      viewer for geographic information available as Free Software. Thuban is      viewer for geographic information available as Free Software. Thuban is
56      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
57      run on many different platforms, including GNU/Linux and Windows.      run on many different platforms, including GNU/Linux and Windows.
58      </para>      </para>
59      <para>      <para>
60      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
61            get a visual
62      impression of the positional relationship of the information that may not      impression of the positional relationship of the information that may not
63      be apparent from simple inspection of the data values themselves.      be apparent from simple inspection of the data values themselves.
64      Thuban allows the user to create a session that displays      Thuban allows the user to create a session that displays
# Line 48  Line 75 
75          <section><title>Installation</title>          <section><title>Installation</title>
76          <para>          <para>
77          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,
78          and Windows 2000. The following list of files that Thuban requires          and Windows 2000. Thuban depends on the following packages. These
79          can be found on the          packages can also be found on the
80          <ulink url="http://thuban.intevation.org/download.html">          <ulink url="http://thuban.intevation.org/download.html">
81          Thuban Download site          Thuban Download site
82          </ulink>.          </ulink>.
         <variablelist>  
         <varlistentry>  
         <term>Debian Testing (sarge)</term>  
         <listitem>  
         <itemizedlist>  
             <listitem><para>Thuban-0.8.1-1-debian.i386.rpm</para></listitem>  
             <listitem><para>GTK 1.2.3</para></listitem>  
             <listitem><para>Python 2.2.1</para></listitem>  
             <listitem><para>Python 2.2 XML Base Tools</para></listitem>  
             <listitem><para>wxWindows 2.4</para></listitem>  
             <listitem><para>wxWindows 2.4 Python Bindings</para></listitem>  
             <listitem><para>proj 4.4.5 Projection Library</para></listitem>  
             <listitem><para>SQLite Python Bindings 0.4.3</para></listitem>  
             <listitem><para>GDAL 1.1.8</para></listitem>  
         </itemizedlist>  
         </listitem>  
         </varlistentry>  
         <varlistentry>  
         <term>RedHat 7.2</term>  
         <listitem>  
         <itemizedlist>  
             <listitem><para>Thuban-0.8.1-1.i386.rpm</para></listitem>  
             <listitem><para>Python 2.2.1</para></listitem>  
             <listitem><para>wxPython 2.4 for Python 2.2 with wxGTK</para></listitem>  
             <listitem><para>proj 4.4.5 Projection Library</para></listitem>  
             <listitem><para>SQLite 2.8.3</para></listitem>  
             <listitem><para>PySQLite 0.4.3</para></listitem>  
             <listitem><para>GDAL 1.1.8</para></listitem>  
         </itemizedlist>  
         </listitem>  
         </varlistentry>  
         <varlistentry>  
         <term>Windows 2000</term>  
         <listitem>  
83          <itemizedlist>          <itemizedlist>
84              <listitem><para>Thuban-0.8.1-0.exe</para></listitem>              <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>
85              <listitem><para>Python 2.2.1</para></listitem>              <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>
86              <listitem><para>wxWindows 2.4 for Python 2.2</para></listitem>              <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>
87              <listitem><para>SQLite Python Libraries</para></listitem>              <listitem><para>proj 4.4.5 Projection Library (<literal>http://www.remotesensing.org/proj/</literal>)</para></listitem>
88              <listitem><para>GDAL for Thuban</para></listitem>              <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>
89          </itemizedlist>              <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>
90          </listitem>              <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>
91          </varlistentry>              </itemizedlist>
92          </variablelist>          </para>
93          </para>                  <para>
94                    Along with the source codes, the download page also offers
95                    full installation packages for Debian, Windows and RPM-based systems
96                    (Mandrake, RedHat, SuSE, etc).
97                    </para>
98                    <section><title>RPM-based GNU/Linux Systems</title>
99                            <section><title>Installing Binary Packages</title>
100                                    <para>
101                                    The most wide-spread RPM-based GNU/Linux Systems are RedHat,
102                                    Mandrake and SuSE. The documentation of these distributions
103                                    should contain information about how to install third-party
104                                    RPM packages. Nonetheless, a short summary is provided here.
105                                    </para>
106                                    <para>
107                                    RPM packages can be installed applying several tools.
108                                    The most basic one is the command line program "rpm".
109                                    The hardware architecture is identified in the name
110                                    of RPM packages, eg. 'i386' for most Intel/AMD architectures.
111                                    If you have a different hardware architecture, where no
112                                    binary RPM packages are provided, you must rebuild binary
113                                    packages from the RPM source packages first (see below).
114                                    Typical rpm commands look like:
115    
116                                    <programlisting>
117                                    rpm --install Thuban-0.9.0-1.i386.rpm
118                                    </programlisting>
119    
120                                    Depending on what you already have installed on your
121                                    system, you are informed that some packages are
122                                    required, but not installed. You need to install them
123                                    first. Either they are provided by your GNU/Linux distributor
124                                    or available somewhere on the Internet.
125                                    The more essential and special ones are provided together
126                                    with the Thuban package.
127                                    </para>
128    
129                                    <para>
130                                    For rpm exist some graphical user interfaces, notably
131                                    kpackage, GnoRPM and xrpm.
132                                    </para>
133    
134                                    <para>
135                                    Make yourself familiar with one of the tools and apply it
136                                    to install the packages.
137                                    Note, that you need to be administrator (root) for the system
138                                    to do that.
139                                    </para>
140                            </section>
141                            <section><title>Build Binaries from Source Packages</title>
142                                    <para>
143                                    This section describes howto build RPM install-packages
144                                    from RPM source-packages.
145                                    This adapts and optimizes an install-package specifically
146                                    to your system.
147                                    This is especially helpful to resolve version conflicts of
148                                    dependent packages. Furthermore, install-packages for other
149                                    platforms (e.g. PowerPC) can be created.
150                                    </para>
151    
152                                    <para>
153                                    Note: rpm must be at least version 4. Execute
154                                    <literal>rpm --version</literal> to find out about the version.
155                                    </para>
156    
157                                    <para>
158                                    You need to do the following preparations to be able to
159                                    build the packages as a regular user. You should now
160                                    perform the package buling as root since this
161                                    might cause damage to your system.
162                            <itemizedlist>
163                            <listitem>
164                                                    <para>
165                                                    Create RPM directory structure:
166                                                    Choose a directory (e.g. $HOME/myrpm) and create the
167                                                    subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.
168                                                    A possible command sequence for this is:
169                                                    <programlisting>
170                                                    mkdir $HOME/freegisrpm
171                                                    cd $HOME/freegisrpm
172                                                    mkdir BUILD RPMS SOURCES SPECS SRPMS
173                                                    </programlisting>
174                                                    </para>
175                                            </listitem>
176                                            <listitem>
177                                                    <para>
178                                                    Set environment variable RPM_DIR:
179                                                    <programlisting>
180                                                    export RPM_DIR=$HOME/freegisrpm
181                                                    </programlisting>
182                                                    </para>
183                                            </listitem>
184                                            <listitem>
185                                                    <para>
186                                                    Create $HOME/.rpmmacros:
187                                                    This file sets general preferences and some
188                                                    specific settings for signing packages.
189                                                    If you don't have a GnuPG-key, you can skip
190                                                    the signature settings i.e. drop the last 4 lines.
191                                                    A signature becomes important when you want to
192                                                    give away packages to third parties.
193                                                    <programlisting>
194    <![CDATA[
195    %packager Name Lastname <[email protected]>
196    
197    %_topdir /home/mylogin/myrpm
198    
199    %_signature gpg
200    %_gpg_name Name Lastname
201    %_pgp_path ~/.gnupg
202    %_pgpbin /usr/bin/gpg
203    ]]>
204                                                    </programlisting>
205                                                    </para>
206                                            </listitem>
207                            </itemizedlist>
208    
209                                    Now you can install any RPM source-package.
210                                    It's components are installed into the corresponding
211                                    subdirectories of your rpm-directory.
212                                    Essentially these are the sources (into directory SOURCES)
213                                    and the so-called spec-file which contains all build
214                                    instructions. The spec-file will go into the SPEC directory.
215                                    Example:
216                                    <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>
217                                    </para>
218    
219                                    <para>
220                                    Create install-package:
221                                    Go to the directory with the spec-files and rebuild the
222                                    package:
223                                    <programlisting>
224    cd $HOME/mypm/SPECS
225    rpm -bb thuban.spec
226                                    </programlisting>
227                                    Next, you will find the newly created package in
228                                    $HOME/myrpm/RPMS/i386.
229                                    If you build the package for another architecture than
230                                    i386, then the name of the directory has a corresponding name.
231                                    </para>
232                                    <para>
233                                    For documentation of RPM, either type
234                                    <literal>man rpm</literal> or <literal>rpm --help</literal>.
235                                    This will provide you with information on the various command
236                                    line options of RPM.
237                                    For more information see the
238                            <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
239                                    </para>
240                            </section>
241                    </section>
242          </section>          </section>
243    
244          <section><title>The Main Window</title>          <section><title>The Main Window</title>
# Line 250  Line 391 
391    
392          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
393          <para>          <para>
394          There are two types of layers that can be added to a map: shape layers          There are two types of layers that can be added to a map: Shape layers
395          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
396          standard file format for storing geographic objects. These          widely used file format for storing geographic objects. These
397          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
398          the shape file is a database file which stores attributes for          the shape file is a database file which stores attributes for
399          each shape in the shape file. This file, in dBase format,          each shape in the Shape file. This file, in dBase format,
400          has the extension ``.dbf''. Both files must have the same base name.          has the extension ``.dbf''. Both files must have the same base name.
401          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
402          also be a file roads.dbf.          also be a file roads.dbf.
# Line 266  Line 407 
407          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
408          <guimenuitem>Add Layer</guimenuitem>          <guimenuitem>Add Layer</guimenuitem>
409          </menuchoice>.          </menuchoice>.
410          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
411          matter if the shape file or database file is selected.                  selection. However, if you switch to display all files and select one
412                    of the associated files (e.g. ``.dbf''), Thuban will recognize the base
413                    name and load the corresponding Shape file.
414            </para>
415                    <para>
416                    The file dialog for Shape files allows to select multiple files.
417                    Use the shift-button together with the left mouse button to extend
418                    the selection.
419          </para>          </para>
420    
421          <para>          <para>
# Line 1231  Line 1379 
1379      </section>      </section>
1380    </chapter>    </chapter>
1381    
1382      <chapter><title>Extensions</title>
1383            <para>
1384            Thuban is designed to be extensible. The term Extension is used as a
1385            general term for anything that extends Thuban.
1386            This chapter introduces into some oppportunities how to add and
1387            handle extra functionality developed by your own or third parties.
1388            </para>
1389    
1390            <section><title>Add personal extensions via thubanstart.py</title>
1391                    <para>
1392                    After Thuban has been started for the first time, a directory
1393                    .thuban is created within your home directory.
1394                    There you can add a file thubanstart.py  which will be imported
1395                    by Thuban at start-up. It is recommended to add only import-statements
1396                    to this file to keep the actual code of extensions separate.
1397                    </para>
1398                    <para>
1399                    The modules to import must either be found through the environment
1400                    variable PYTHONPATH or directly be placed into the .thuban-directory.
1401                    </para>
1402                    <para>
1403                    As an example, copy the file examples/simple_extensions/hello_world.py
1404                    of the Thuban source code into the .thuban-directory of your home
1405                    directory. Now add add the statement import hello_world to the
1406                    file thubanstart.py and run Thuban. You will notice an additional
1407                    menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
1408                    the new item for the Hello-World extension is placed - select it
1409                    to see the Hello-World message.
1410                    </para>
1411            </section>
1412    
1413            <section><title>Writing simple extensions</title>
1414                    <para>
1415                    Writing an extension for Thuban basically means to
1416                    implement the extra functionality in Python with all of the
1417                    Thuban classes, methods and variables available.
1418                    </para>
1419                    <para>
1420                    All classes and their methods are documented in the source code
1421                    (see their doc-strings). Here is an example from
1422                    Thuban/Model/layer.py that describes some of the methods
1423                    of a Layer object:
1424                    </para>
1425                    <programlisting>
1426                    <![CDATA[
1427    class BaseLayer(TitledObject, Modifiable):
1428    
1429        """Base class for the layers."""
1430    
1431        def __init__(self, title, visible = True, projection = None):
1432            """Initialize the layer.
1433    
1434            title -- the title
1435            visible -- boolean. If true the layer is visible.
1436            """
1437            TitledObject.__init__(self, title)
1438            Modifiable.__init__(self)
1439            self.visible = visible
1440            self.projection = projection
1441    
1442        def Visible(self):
1443            """Return true if layer is visible"""
1444            return self.visible
1445    
1446        def SetVisible(self, visible):
1447            """Set the layer's visibility."""
1448            self.visible = visible
1449            self.issue(LAYER_VISIBILITY_CHANGED, self)
1450    
1451        def HasClassification(self):
1452            """Determine if this layer support classifications."""
1453    ...
1454                    ]]>
1455                    </programlisting>
1456                    <para>
1457                    This example intends to give you an impression of the
1458                    source-code-level documentation.
1459                    You have to make yourself familiar with
1460                    the Python programming language to understand some special
1461                    code elements.
1462                    </para>
1463                    <section><title>hello_world.py</title>
1464                      <para>
1465                      Traditionally, the first example should welcome the world.
1466                      Most of the code handles the frame for integrating a menu
1467                      item into Thuban while the actual raising of a message
1468                      is done in a single line.
1469                      </para>
1470                            <programlisting>
1471                            <![CDATA[
1472    # Copyright (C) 2003 by Intevation GmbH
1473    # Authors:
1474    # Jan-Oliver Wagner <[email protected]>
1475    #
1476    # This program is free software under the GPL (>=v2)
1477    # Read the file COPYING coming with Thuban for details.
1478    
1479    """
1480    Extend Thuban with a sample Hello World to demonstrate simple
1481    extensions.
1482    """
1483    
1484    __version__ = '$Revision$'
1485    
1486    # use _() already now for all strings that may later be translated
1487    from Thuban import _
1488    
1489    # Thuban has named commands which can be registered in the central
1490    # instance registry.
1491    from Thuban.UI.command import registry, Command
1492    
1493    # The instance of the main menu of the Thuban application
1494    # See Thuban/UI/menu.py for the API of the Menu class
1495    from Thuban.UI.mainwindow import main_menu
1496    
1497    def hello_world_dialog(context):
1498        """Just raise a simple dialog to greet the world.
1499    
1500        context -- The Thuban context.
1501        """
1502        context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
1503    
1504    
1505    # create a new command and register it
1506    registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
1507                         helptext = _('Welcome everyone on this planet')))
1508    
1509    # find the extensions menu (create it anew if not found)
1510    extensions_menu = main_menu.find_menu('extensions')
1511    if extensions_menu is None:
1512        extensions_menu = main_menu.InsertMenu('extensions', _('E&xtensions'))
1513    
1514    # finally bind the new command with an entry in the extensions menu
1515    extensions_menu.InsertItem('hello_world')
1516                            ]]>
1517                            </programlisting>
1518                    </section>
1519                    <section><title>Registering a Command</title>
1520                      <para>
1521                      Mainly, our new function has to be registered to the Thuban
1522                      framework in order to connect it to the menu. A registered
1523                      command can also be connected to e.g. a toolbar button.
1524                      </para>
1525                      <para>
1526                      The instances and classes for this are imported at the beginning.
1527                      Any code not inside a method or class is directly executed when
1528                      the source-code module is imported. Therefore, the second
1529                      part of this example consist of the plain statements to create a new
1530                      Command and to add it to the menu.
1531                      </para>
1532                      <para>
1533                      By convention, it looks for a menu registered as ``extensions'' to
1534                      insert the new command. If it does not exist yet, it gets created.
1535                      It is advisable to copy this code for any of your extensions.
1536                      </para>
1537                    </section>
1538                    <section><title>The Thuban context</title>
1539                            <para>
1540                            A registered command that is called, always receives the
1541                            Thuban context. This instance provides our method with
1542                            hook references to all important components of the Thuban
1543                            application.
1544                            </para>
1545                            <para>
1546                    In the example hello_world.py, our function uses the
1547                            mainwindow component which offers a method to raise a
1548                            message dialog. In total there are three hooks:
1549                            <itemizedlist>
1550                            <listitem>
1551                            <para>application:
1552                            This object is the instance of the Thuban Application class.
1553                            Except maybe for loading or savinf sessions, you will not
1554                            need this object for a simple extension.
1555                            See Thuban/UI/application.py for the API.
1556                            </para>
1557                            </listitem>
1558                            <listitem>
1559                            <para>session:
1560                            The instance of the current session. It manages the sessions'
1561                            map and tables. You can set and remove the map or tables.
1562                            In may also get the map object. However, you should know that
1563                            internally it is already prepared to handle many maps.
1564                            Therfore, currently you would always receive a list with exactlty
1565                            one element. In the future, if there are more than one map,
1566                            you will not know which one is the currently display one and
1567                            therefore you should use the mainwindow as hook to find
1568                            the currently displayed map.
1569                            See Thuban/Model/session.py for the API.
1570                            </para>
1571                            </listitem>
1572                            <listitem>
1573                            <para>
1574                            mainwindow: The mainwindow object is central to manage various
1575                            GUI things such as the Legend sub-window. Most notably,
1576                            you get access to the canvas which is the window part where
1577                            the map is drawn. The canvas knows, which map it currently
1578                            draws and therefore you get the current map via
1579                            context.mainwindow.canvas.Map().
1580                            See Thuban/UI/mainwindow.py for the API.
1581                            </para>
1582                            </listitem>
1583                            </itemizedlist>
1584                </para>
1585                    </section>
1586            </section>
1587      </chapter>
1588    
1589    <chapter><title>Trouble Shooting</title>    <chapter><title>Trouble Shooting</title>
1590      <para>      <para>
1591      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.
# Line 1336  Line 1691 
1691          <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>          <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
1692          format: Raster maps are provided as TIFF images, with an additional          format: Raster maps are provided as TIFF images, with an additional
1693          "world file" storing the geographic reference (usually with an          "world file" storing the geographic reference (usually with an
1694          extension ".tfw".          extension ".tfw").
1695          </para>          </para>
1696      </listitem>      </listitem>
1697      </varlistentry>      </varlistentry>
Legend:
Removed from v.1532  
changed lines
  Added in v.1719
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26