/[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 1689 by jan, Fri Aug 29 10:03:49 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>          </section>
99    
100          <section><title>The Main Window</title>          <section><title>The Main Window</title>
# Line 250  Line 247 
247    
248          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
249          <para>          <para>
250          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
251          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
252          standard file format for storing geographic objects. These          widely used file format for storing geographic objects. These
253          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
254          the shape file is a database file which stores attributes for          the shape file is a database file which stores attributes for
255          each shape in the shape file. This file, in dBase format,          each shape in the Shape file. This file, in dBase format,
256          has the extension ``.dbf''. Both files must have the same base name.          has the extension ``.dbf''. Both files must have the same base name.
257          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
258          also be a file roads.dbf.          also be a file roads.dbf.
# Line 266  Line 263 
263          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
264          <guimenuitem>Add Layer</guimenuitem>          <guimenuitem>Add Layer</guimenuitem>
265          </menuchoice>.          </menuchoice>.
266          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
267          matter if the shape file or database file is selected.                  selection. However, if you switch to display all files and select one
268                    of the associated files (e.g. ``.dbf''), Thuban will recognize the base
269                    name and load the corresponding Shape file.
270            </para>
271                    <para>
272                    The file dialog for Shape files allows to select multiple files.
273                    Use the shift-button together with the left mouse button to extend
274                    the selection.
275          </para>          </para>
276    
277          <para>          <para>
# Line 1231  Line 1235 
1235      </section>      </section>
1236    </chapter>    </chapter>
1237    
1238      <chapter><title>Extensions</title>
1239            <para>
1240            Thuban is designed to be extensible. The term Extension is used as a
1241            general term for anything that extends Thuban.
1242            This chapter introduces into some oppportunities how to add and
1243            handle extra functionality developed by your own or third parties.
1244            </para>
1245    
1246            <section><title>Add personal extensions via thubanstart.py</title>
1247                    <para>
1248                    After Thuban has been started for the first time, a directory
1249                    .thuban is created within your home directory.
1250                    There you can add a file thubanstart.py  which will be imported
1251                    by Thuban at start-up. It is recommended to add only import-statements
1252                    to this file to keep the actual code of extensions separate.
1253                    </para>
1254                    <para>
1255                    The modules to import must either be found though the environment
1256                    variable PYTHONPATH or directly be placed into the .thuban-directory.
1257                    </para>
1258                    <para>
1259                    As an example, copy the file examples/simple_extensions/hello_world.py
1260                    of the Thuban source code into the .thuban-directory of your home
1261                    directory. Now add add the statement import hello_world to the
1262                    file thubanstart.py and run Thuban. You will notice an additional
1263                    menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
1264                    the new item for the Hello-World extension is placed - select it
1265                    to see the Hello-World message.
1266                    </para>
1267            </section>
1268    
1269            <section><title>Writing simple extensions</title>
1270                    <para>
1271                    Writing an extension for Thuban basically means to
1272                    implement the extra functionality in Python with all of the
1273                    Thuban classes, methods and variables available.
1274                    </para>
1275                    <para>
1276                    All classes and their methods are documented in the source code
1277                    (see their doc-strings). Here is an example from
1278                    Thuban/Model/layer.py that describes some of the methods
1279                    of a Layer object:
1280                    </para>
1281                    <programlisting>
1282                    <![CDATA[
1283    class BaseLayer(TitledObject, Modifiable):
1284    
1285        """Base class for the layers."""
1286    
1287        def __init__(self, title, visible = True, projection = None):
1288            """Initialize the layer.
1289    
1290            title -- the title
1291            visible -- boolean. If true the layer is visible.
1292            """
1293            TitledObject.__init__(self, title)
1294            Modifiable.__init__(self)
1295            self.visible = visible
1296            self.projection = projection
1297    
1298        def Visible(self):
1299            """Return true if layer is visible"""
1300            return self.visible
1301    
1302        def SetVisible(self, visible):
1303            """Set the layer's visibility."""
1304            self.visible = visible
1305            self.issue(LAYER_VISIBILITY_CHANGED, self)
1306    
1307        def HasClassification(self):
1308            """Determine if this layer support classifications."""
1309    ...
1310                    ]]>
1311                    </programlisting>
1312                    <para>
1313                    This example intends to give you an impression of the
1314                    source-code-level documentation.
1315                    You have to make yourself familiar with
1316                    the Python programming language to understand some special
1317                    code elements.
1318                    </para>
1319                    <section><title>hello_world.py</title>
1320                      <para>
1321                      Traditionally, the first example should welcome the world.
1322                      Most of the code handles the frame for integrating a menu
1323                      item into Thuban while the actual raising of a message
1324                      is done in a single line.
1325                      </para>
1326                            <programlisting>
1327                            <![CDATA[
1328    # Copyright (C) 2003 by Intevation GmbH
1329    # Authors:
1330    # Jan-Oliver Wagner <[email protected]>
1331    #
1332    # This program is free software under the GPL (>=v2)
1333    # Read the file COPYING coming with Thuban for details.
1334    
1335    """
1336    Extend Thuban with a sample Hello World to demonstrate simple
1337    extensions.
1338    """
1339    
1340    __version__ = '$Revision$'
1341    
1342    # use _() already now for all strings that may later be translated
1343    from Thuban import _
1344    
1345    # Thuban has named commands which can be registered in the central
1346    # instance registry.
1347    from Thuban.UI.command import registry, Command
1348    
1349    # The instance of the main menu of the Thuban application
1350    # See Thuban/UI/menu.py for the API of the Menu class
1351    from Thuban.UI.mainwindow import main_menu
1352    
1353    def hello_world_dialog(context):
1354        """Just raise a simple dialog to greet the world.
1355    
1356        context -- The Thuban context.
1357        """
1358        context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
1359    
1360    
1361    # create a new command and register it
1362    registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
1363                         helptext = _('Welcome everyone on this planet')))
1364    
1365    # find the extensions menu (create it anew if not found)
1366    extensions_menu = main_menu.find_menu('extensions')
1367    if extensions_menu is None:
1368        extensions_menu = main_menu.InsertMenu('extensions', _('E&xtensions'))
1369    
1370    # finally bind the new command with an entry in the extensions menu
1371    extensions_menu.InsertItem('hello_world')
1372                            ]]>
1373                            </programlisting>
1374                    </section>
1375                    <section><title>Registering a Command</title>
1376                      <para>
1377                      Mainly, our new function has to be registered to the Thuban
1378                      framework in order to connect it to the menu. A registered
1379                      command can also be connected to e.g. a toolbar button.
1380                      </para>
1381                      <para>
1382                      The instances and classes for this are imported at the beginning.
1383                      Any code not inside a method or class is directly executed when
1384                      the source-code module is imported. Therefore, the second
1385                      part of this example consist of the plain statements to create a new
1386                      Command and to add it to the menu.
1387                      </para>
1388                      <para>
1389                      By convention, it looks for a menu registered as ``extensions'' to
1390                      insert the new command. If it does not exist yet, it gets created.
1391                      It is advisable to copy this code for any of your extensions.
1392                      </para>
1393                    </section>
1394                    <section><title>The Thuban context</title>
1395                            <para>
1396                            A registered command that is called, always receives the
1397                            Thuban context. This instance provides our method with
1398                            hook references to all important components of the Thuban
1399                            application.
1400                            </para>
1401                            <para>
1402                    In the example hello_world.py, our function uses the
1403                            mainwindow component which offers a method to raise a
1404                            message dialog. In total there are three hooks:
1405                            <itemizedlist>
1406                            <listitem>
1407                            <para>application:
1408                            This object is the instance of the Thuban Application class.
1409                            Except maybe for loading or savinf sessions, you will not
1410                            need this object for a simple extension.
1411                            See Thuban/UI/application.py for the API.
1412                            </para>
1413                            </listitem>
1414                            <listitem>
1415                            <para>session:
1416                            The instance of the current session. It manages the sessions'
1417                            map and tables. You can set and remove the map or tables.
1418                            In may also get the map object. However, you should know that
1419                            internally it is already prepared to handle many maps.
1420                            Therfore, currently you would always receive a list with exactlty
1421                            one element. In the future, if there are more than one map,
1422                            you will not know which one is the currently display one and
1423                            therefore you should use the mainwindow as hook to find
1424                            the currently displayed map.
1425                            See Thuban/Model/session.py for the API.
1426                            </para>
1427                            </listitem>
1428                            <listitem>
1429                            <para>
1430                            mainwindow: The mainwindow object is central to manage various
1431                            GUI things such as the Legend sub-window. Most notably,
1432                            you get access to the canvas which is the window part where
1433                            the map is drawn. The canvas knows, which map it currently
1434                            draws and therefore you get the current map via
1435                            context.mainwindow.canvas.Map().
1436                            See Thuban/UI/mainwindow.py for the API.
1437                            </para>
1438                            </listitem>
1439                            </itemizedlist>
1440                </para>
1441                    </section>
1442            </section>
1443      </chapter>
1444    
1445    <chapter><title>Trouble Shooting</title>    <chapter><title>Trouble Shooting</title>
1446      <para>      <para>
1447      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 1547 
1547          <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>          <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
1548          format: Raster maps are provided as TIFF images, with an additional          format: Raster maps are provided as TIFF images, with an additional
1549          "world file" storing the geographic reference (usually with an          "world file" storing the geographic reference (usually with an
1550          extension ".tfw".          extension ".tfw").
1551          </para>          </para>
1552      </listitem>      </listitem>
1553      </varlistentry>      </varlistentry>
Legend:
Removed from v.1532  
changed lines
  Added in v.1689
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26