/[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

trunk/thuban/Doc/manual/thuban-manual.xml revision 1478 by frank, Thu Jul 24 17:00:25 2003 UTC branches/WIP-pyshapelib-bramz/Doc/manual/thuban-manual.xml revision 2734 by bramz, Thu Mar 1 12:42:59 2007 UTC
# Line 1  Line 1 
1  <?xml version="1.0" encoding="ISO-8859-1"?>  <?xml version="1.0" encoding="ISO-8859-1"?>
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 "60">]>
6  <!-- $Revision$ -->  <!-- $Revision$ -->
7  <book>  <book>
8    <bookinfo>    <bookinfo>
9      <title>Thuban Manual</title>      <title>User's Manual for Thuban 1.2 (Draft)</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, 2005, 2006, 2007</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>SVN version $Id$</revnumber>
30            <date></date>
31            <revremark>Under development.</revremark>
32         </revision>
33    -->
34         <revision>
35            <revnumber>1.2.0</revnumber>
36            <date>20-Feb-2007</date>
37            <revremark>
38                            Removed all installation instructions in favor
39                            of a link to the website. It is not wise to
40                            double the README contents here.
41                    </revremark>
42         </revision>
43         <revision>
44            <revnumber>1.0.0</revnumber>
45            <date>22-Jan-2004</date>
46            <revremark>
47                            Corresponds to Thuban 1.0.0.
48                            New: Installation instructions for Win32.
49                    </revremark>
50         </revision>
51         <revision>
52            <revnumber>1.0pre3</revnumber>
53            <date>04-Dec-2003</date>
54            <revremark>
55                            Corresponds to Thuban 1.0rc1.
56                            New: I18n, right button legend menu, EPSG projectons,
57                PostGIS support.
58                    </revremark>
59         </revision>
60         <revision>
61            <revnumber>1.0pre2</revnumber>
62            <date>29-Aug-2003</date>
63            <revremark>
64                            Corresponds to Thuban development release 0.8.1.
65                            New: chapter on extensions.
66                    </revremark>
67         </revision>
68         <revision>
69            <revnumber>1.0pre1</revnumber>
70            <date>08-Aug-2003</date>
71            <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
72         </revision>
73      </revhistory>
74    
75    </bookinfo>    </bookinfo>
76    
77    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
78      <para>      <para>
79      Thuban is a Free Software Geographic Information Systems (GIS) viewer.      Thuban is an interactive geographic data viewer.
80      It is being developed because there is currently no simple interactive      Its development had been started because there was no simple interactive
81      viewer for geographic information available as Free Software. Thuban is      viewer for geographic information available as Free Software. Thuban is
82      written in Python and C++ and uses the wxWindows library allowing it to      written mainly in Python and uses the wxWidgets (former wxWindows)
83        library allowing it to
84      run on many different platforms, including GNU/Linux and Windows.      run on many different platforms, including GNU/Linux and Windows.
85      </para>      </para>
86      <para>      <para>
87      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
88            get a visual
89      impression of the positional relationship of the information that may not      impression of the positional relationship of the information that may not
90      be apparent from simple inspection of the data values themselves.      be apparent from simple inspection of the data values themselves.
91      Thuban allows the user to create a session that displays      Thuban allows the user to create a session that displays
# Line 39  Line 94 
94      </para>      </para>
95      <para>      <para>
96      Thuban arranges a session in a hierarchy. A session contains a map which      Thuban arranges a session in a hierarchy. A session contains a map which
97      consists of layers. Each layer represents one kind of data set. For      consists of layers. Each layer represents a data set. For
98      instance, there may be a layer for roads and another layer for buildings.      instance, there may be a layer for roads and another layer for buildings.
99      These layers can either be vector shapes or images.      These layers can either be vector shapes or images.
100      </para>      </para>
101    
102          <section><title>Installation</title>          <section><title>Installation</title>
103          <para>          <para>
104          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,          Thuban is actively supported under Debian 4.0 (Etch)
105          and Windows 2000. All the necessary files can be found on the          and Windows (XP). Of course it is possible to run Thuban
106          <ulink url="http://thuban.intevation.org/download.html">          on a variety of other platforms.
107          Thuban Download site  
108          </ulink>.          Please check <ulink url="http://thuban.intevation.org/">
109          </para>          Thuban's Website
110            </ulink> about how to install Thuban and the lastest information
111            about the supported platforms.
112            </para>
113          </section>          </section>
114    
115            <section><title>Internationalization</title>
116            <para>
117            Thuban is implemented with internationalization support. So far Thuban
118            is translated by volunteers to the following languages (apart from its
119            main language: English):
120            <itemizedlist>
121                <listitem><para>French</para></listitem>
122                <listitem><para>German</para></listitem>
123                <listitem><para>Italian</para></listitem>
124                    <listitem><para>Portuguese (Brazilian)</para></listitem>
125                <listitem><para>Russian</para></listitem>
126                <listitem><para>Spanish</para></listitem>
127            </itemizedlist>
128            </para>
129    
130            <para>
131            To use internationalization under POSIX systems (like GNU/Linux)
132            you have to set the environment variable LC_ALL accordingly (e.g.
133            LC_ALL=fr_FR for the french language support). Please check your
134            systems documentation for details and supported settings.
135            Specifiying LC_ALL on the command line while launching thuban
136            allows appication specific language settings:
137            </para>
138            <programlisting>
139            LC_ALL=fr_FR thuban.py
140            </programlisting>
141    
142            <para>
143            MS Windows users have to specify the language to be used via the control
144            bar (which effects all applications).
145            </para>
146            </section>
147    
148          <section><title>The Main Window</title>          <section><title>The Main Window</title>
149          <para>          <para>
150          <screenshot>          <figure>
151          <screeninfo>The Main Window</screeninfo>          <title>The Main Window</title>
152          <mediaobject>          <mediaobject>
153          <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG"/> </imageobject>          <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>
154          <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS"/> </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>  
155          </mediaobject>          </mediaobject>
156          </screenshot>          </figure>
157          </para>          </para>
158    
159          <para>          <para>
# Line 100  Line 189 
189          The tool bar provides quick access to the commonly needed tools.          The tool bar provides quick access to the commonly needed tools.
190          By hovering over each button the user can see a short messages          By hovering over each button the user can see a short messages
191          describing what the tool does. The tools provided are Zoom In, Zoom          describing what the tool does. The tools provided are Zoom In, Zoom
192          Out, Pan, Full Extent, Full Layer Extent, Full Shape Extent, Indentify,          Out, Pan, Full Extent, Full Layer Extent, Full Shape Extent, Identify,
193          and Label. Each of the tools will be explained in further detail later          and Label. Each of the tools will be explained in further detail later
194          in the manual.          in the manual.
195          </para>          </para>
# Line 116  Line 205 
205          <menuchoice>          <menuchoice>
206          <guimenu>File</guimenu>          <guimenu>File</guimenu>
207          <guimenuitem>New Session</guimenuitem>          <guimenuitem>New Session</guimenuitem>
208          </menuchoice>.          </menuchoice>.
   
209          If a session is already loaded and has been modified without          If a session is already loaded and has been modified without
210          being saved a prompt will ask if the current session should          being saved a prompt will ask if the current session should
211          be saved.          be saved. A new session consists of an empty map with no
212            layers, no tables and no projection.
213          </para>          </para>
214          </section>          </section>
215    
# Line 131  Line 219 
219          <menuchoice>          <menuchoice>
220          <guimenu>File</guimenu>          <guimenu>File</guimenu>
221          <guimenuitem>Open Session</guimenuitem>          <guimenuitem>Open Session</guimenuitem>
222          </menuchoice>.          </menuchoice>. A dialog box will open allowing the user to browse
223            for a Thuban Session file. Thuban session files end with
224            <varname>.thuban</varname>. Selecting a file a clicking
225            <guibutton>OK</guibutton> will load the session into Thuban.
226                    </para>
227    
228                    <para>
229          If a session is already loaded and has been modified without          If a session is already loaded and has been modified without
230          being saved a prompt will ask if the current session should          being saved a prompt will ask if the current session should
231          be saved.          be saved.
232          </para>          </para>
233                    
234                    <para>
235                    Thuban provides a path recovery feature: If a (shape) file referenced
236                    in a Thuban session cannot be found at the specified location, the user
237                    is prompted a file dialog. Here a new location can be selected for the
238                    currents layer data source. Cancelling the dialog removes the layer
239                    from the session. If a new location has been selected, Thuban checks
240                    this again, if further layers data sources are missing. The user is
241                    informed about this and can accept or cancel the suggestion.
242            </para>
243          </section>          </section>
244    
245          <section><title>Saving a Session</title>          <section><title>Saving a Session</title>
# Line 146  Line 249 
249          <guimenu>File</guimenu>          <guimenu>File</guimenu>
250          <guimenuitem>Save Session</guimenuitem>          <guimenuitem>Save Session</guimenuitem>
251          </menuchoice>.          </menuchoice>.
252                    In the case the session is not a new and unsaved one,
253                    the corresponding file is updated with the current session
254                    data.
255                    In the case the current session is a new one and yet unsaved
256                    a dialog box will open allowing the user to browse
257            the file system and select a place to save the session. Thuban
258            sessions should be saved under a name ending in
259            <varname>.thuban</varname>. If the file already exists the user
260            will be prompted to save under a different name or overwrite the
261            existing file.
262          </para>          </para>
263          </section>          </section>
264    
265          <section><title>The Session Info-Tree</title>          <section><title>The Session Info-Tree</title>
266            <para>
267            <figure>
268            <title>Session Info Tree</title>
269            <mediaobject>
270            <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>
271            <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>
272            </mediaobject>
273            </figure>
274            </para>
275          <para>          <para>
276                  (primarily for developers)          The session info-tree is primarily intended for developers working
277            with Thuban. It displays many of the internal values for the session,
278            map, and layers. It can be opened from
279            <menuchoice>
280            <guimenu>File</guimenu>
281            <guimenuitem>Session Tree</guimenuitem>
282            </menuchoice>.
283          </para>          </para>
284          </section>          </section>
285    </chapter>    </chapter>
# Line 163  Line 290 
290      different type of data set. By interacting with the map the user can      different type of data set. By interacting with the map the user can
291      visually explore the data.      visually explore the data.
292      </para>      </para>
293        <para>
294        The map can have a name that will appear in the Thuban title bar.
295        The map name can be changed using
296        <menuchoice>
297        <guimenu>Map</guimenu>
298        <guimenuitem>Rename</guimenuitem>
299        </menuchoice>.
300        </para>
301        <para>
302        <inlinemediaobject>
303        <imageobject>
304        <imagedata fileref="../images/3_rename_map.png" format="PNG" scale="&imgscale;"/>
305        </imageobject>
306        <imageobject>
307        <imagedata fileref="./images/3_rename_map.eps" format="EPS" scale="&imgscale;"/>
308        </imageobject>
309        <textobject> <phrase>Rename Map</phrase> </textobject>
310        </inlinemediaobject>
311        </para>
312    
313          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
314          <para>          <para>
315          There are two types of layers that can use added to a map: shape layers          There are three types of layers that can be added to a map:
316            Shape layers, database layers
317          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
318          standard file format for storing geographic objects. Normally, these          widely used file format for storing geographic objects. These
319          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
320          the object information is a database file which stores attributes for          the shape file is a database file which stores attributes for
321          each shape in the Shapefile. This file, stored in DB2 format, usually          each shape in the Shape file. This file, in dBase format,
322          has the extension ``.dbf''. Both files should have the same base name.          has the extension ``.dbf''. Both files must have the same base name.
323          For example, if there is a Shapefile named roads.shp there should          For example, if there is a shape file named roads.shp there must
324          also be a file roads.dbf.          also be a file roads.dbf.
325          </para>          </para>
326          <para>          <itemizedlist>
327            <listitem>
328            <para>
329          Shape layers can be added to the map with          Shape layers can be added to the map with
330          <menuchoice>          <menuchoice>
331          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
332          <guimenuitem>Add Layer</guimenuitem>          <guimenuitem>Add Layer</guimenuitem>
333          </menuchoice>.          </menuchoice>.
334          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
335          matter if the Shapefile or database file is selected.                  selection. However, if you switch to display all files and select one
336          </para>                  of the associated files (e.g. ``.dbf''), Thuban will recognize the base
337                    name and load the corresponding Shape file.
338            </para>
339                    <para>
340                    The file dialog for Shape files allows to select multiple files.
341                    Use the shift-button together with the left mouse button to extend
342                    the selection.
343            </para>
344            </listitem>
345    
346            <listitem>
347            <para>Database layers can be added to the map with
348            <menuchoice>
349            <guimenu>Map</guimenu>
350            <guimenuitem>Add Database Layer</guimenuitem>
351            </menuchoice>.
352            A dialog with two lists is opened. The left list displays all
353            database connections currently open for the session. You can retrieve
354            a list of available layers from the selected database which is
355            displayed on the right hand. From this list one layer can be selected,
356            the dialog is closed afterwards.
357            </para>
358            <para>
359            See appendix ``Working with PostGIS'' for details.
360            </para>
361            </listitem>
362    
363            <listitem>
364          <para>          <para>
365          Image layers can be added to the map with          Image layers can be added to the map with
366          <menuchoice>          <menuchoice>
# Line 193  Line 368 
368          <guimenuitem>Add Image Layer</guimenuitem>          <guimenuitem>Add Image Layer</guimenuitem>
369          </menuchoice>.          </menuchoice>.
370          It is important to select a valid image file that has geographic          It is important to select a valid image file that has geographic
371          data associated with it. This can be embedded in the file itself,          data associated with it. The data can be embedded in the file itself,
372          or in another file. If geographic information cannot be found, Thuban          or in another file. If geographic information cannot be found, Thuban
373          will report an error.          will report an error.
374          </para>          </para>
375            </listitem>
376            </itemizedlist>
377          </section>          </section>
378    
379          <section><title>Navigation</title>          <section><title>Navigation</title>
380          <para>          <para>
381          The map can be explored by using the navigation tools available on          The map can be explored by using the navigation tools available on
382          the tool bar, or from the          the tool bar or from the
383          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.
384          </para>          </para>
385            <itemizedlist>
386            <listitem>
387          <para>          <para>
388          The ZoomIn tool          The ZoomIn tool
389          <inlinemediaobject>          <inlinemediaobject>
390          <imageobject>          <imageobject>
391          <imagedata fileref="../images/3_2_zoomin.png" format="PNG"/>          <imagedata fileref="../images/3_2_zoomin.png" format="PNG" scale="&imgscale;"/>
392          </imageobject>          </imageobject>
393          <imageobject>          <imageobject>
394          <imagedata fileref="./images/3_2_zoomin.eps" format="EPS"/>          <imagedata fileref="./images/3_2_zoomin.eps" format="EPS" scale="&imgscale;"/>
395          </imageobject>          </imageobject>
396          <textobject> <phrase>ZoomIn Tool</phrase> </textobject>          <textobject> <phrase>ZoomIn Tool</phrase> </textobject>
397          </inlinemediaobject>          </inlinemediaobject>
398          can be used to enlarge a region of the map. Clicking once on the map          enlarges a region of the map. Clicking once on the map
399          will double the magnification and center the map on the point that          will double the magnification and center the map on the point that
400          was clicked. Clicking and dragging lets the user select a region          was clicked. Clicking and dragging selects a region that will be
401          to be enlarged to fit the window.          enlarged to fit the window.
402          </para>          </para>
403            </listitem>
404            <listitem>
405          <para>          <para>
406          The ZoomOut tool          The ZoomOut tool
407          <inlinemediaobject>          <inlinemediaobject>
408          <imageobject>          <imageobject>
409          <imagedata fileref="../images/3_2_zoomout.png" format="PNG"/>          <imagedata fileref="../images/3_2_zoomout.png" format="PNG" scale="&imgscale;"/>
410          </imageobject>          </imageobject>
411          <imageobject>          <imageobject>
412          <imagedata fileref="./images/3_2_zoomout.eps" format="EPS"/>          <imagedata fileref="./images/3_2_zoomout.eps" format="EPS" scale="&imgscale;"/>
413          </imageobject>          </imageobject>
414          <textobject> <phrase>ZoomOut Tool</phrase> </textobject>          <textobject> <phrase>ZoomOut Tool</phrase> </textobject>
415          </inlinemediaobject>          </inlinemediaobject>
# Line 237  Line 418 
418          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
419          scaled to fit into that box.          scaled to fit into that box.
420          </para>          </para>
421            </listitem>
422            <listitem>
423          <para>          <para>
424          The Pan tool          The Pan tool
425          <inlinemediaobject>          <inlinemediaobject>
426          <imageobject>          <imageobject>
427          <imagedata fileref="../images/3_2_pan.png" format="PNG"/>          <imagedata fileref="../images/3_2_pan.png" format="PNG" scale="&imgscale;"/>
428          </imageobject>          </imageobject>
429          <imageobject>          <imageobject>
430          <imagedata fileref="./images/3_2_pan.eps" format="EPS"/>          <imagedata fileref="./images/3_2_pan.eps" format="EPS" scale="&imgscale;"/>
431          </imageobject>          </imageobject>
432          <textobject> <phrase>Pan Tool</phrase> </textobject>          <textobject> <phrase>Pan Tool</phrase> </textobject>
433          </inlinemediaobject>          </inlinemediaobject>
434          allows the user to move the map around by clicking and dragging.          allows the user to move the map around by clicking and dragging.
435          </para>          </para>
436            </listitem>
437            <listitem>
438          <para>          <para>
439          The Full Extent tool          The Full Extent tool
440          <inlinemediaobject>          <inlinemediaobject>
441          <imageobject>          <imageobject>
442          <imagedata fileref="../images/3_2_fullextent.png" format="PNG"/>          <imagedata fileref="../images/3_2_fullextent.png" format="PNG" scale="&imgscale;"/>
443          </imageobject>          </imageobject>
444          <imageobject>          <imageobject>
445          <imagedata fileref="./images/3_2_fullextent.eps" format="EPS"/>          <imagedata fileref="./images/3_2_fullextent.eps" format="EPS" scale="&imgscale;"/>
446          </imageobject>          </imageobject>
447          <textobject> <phrase>Full Extent Tool</phrase> </textobject>          <textobject> <phrase>Full Extent Tool</phrase> </textobject>
448          </inlinemediaobject>          </inlinemediaobject>
449          rescales the viewable region so that the entire map is visible.          rescales the viewable region so that the entire map is visible.
450          </para>          </para>
451            </listitem>
452            <listitem>
453          <para>          <para>
454          The Full Layer Extent tool          The Full Layer Extent tool
455          <inlinemediaobject>          <inlinemediaobject>
456          <imageobject>          <imageobject>
457          <imagedata fileref="../images/3_2_fulllayerextent.png" format="PNG"/>          <imagedata fileref="../images/3_2_fulllayerextent.png" format="PNG" scale="&imgscale;"/>
458          </imageobject>          </imageobject>
459          <imageobject>          <imageobject>
460          <imagedata fileref="./images/3_2_fulllayerextent.eps" format="EPS"/>          <imagedata fileref="./images/3_2_fulllayerextent.eps" format="EPS" scale="&imgscale;"/>
461          </imageobject>          </imageobject>
462          <textobject> <phrase>Full Layer Extent Tool</phrase> </textobject>          <textobject> <phrase>Full Layer Extent Tool</phrase> </textobject>
463          </inlinemediaobject>          </inlinemediaobject>
# Line 278  Line 465 
465          layer fits within the window. If no layer is selected this button          layer fits within the window. If no layer is selected this button
466          will be disabled.          will be disabled.
467          </para>          </para>
468            </listitem>
469            <listitem>
470          <para>          <para>
471          The Full Shape Extent tool          The Full Shape Extent tool
472          <inlinemediaobject>          <inlinemediaobject>
473          <imageobject>          <imageobject>
474          <imagedata fileref="../images/3_2_fullshapeextent.png" format="PNG"/>          <imagedata fileref="../images/3_2_fullshapeextent.png" format="PNG" scale="&imgscale;"/>
475          </imageobject>          </imageobject>
476          <imageobject>          <imageobject>
477          <imagedata fileref="./images/3_2_fullshapeextent.eps" format="EPS"/>          <imagedata fileref="./images/3_2_fullshapeextent.eps" format="EPS" scale="&imgscale;"/>
478          </imageobject>          </imageobject>
479          <textobject> <phrase>Full Shape Extent Tool</phrase> </textobject>          <textobject> <phrase>Full Shape Extent Tool</phrase> </textobject>
480          </inlinemediaobject>          </inlinemediaobject>
481          rescales the viewable region so that the currently selected          rescales the viewable region so that the currently selected
482          shape fits within the window. If the shape is a point, it is          shape fits within the window. If the shape is a point, it is
483          centered and the map is zoomed all the way in. If no shape is          centered and the map is zoomed all the way in. If no shape is
484          selected this button will be disabled.          selected this button will be disabled. This feature is especially
485            helpful when identifying an object related to a selected record
486            in a tableview (see below).
487    
488          </para>          </para>
489            </listitem>
490            </itemizedlist>
491          </section>          </section>
492    
493          <section><title>Object Identification</title>          <section><title>Object Identification</title>
# Line 301  Line 495 
495          Objects on the map can be identified using the Identify tool          Objects on the map can be identified using the Identify tool
496          <inlinemediaobject>          <inlinemediaobject>
497          <imageobject>          <imageobject>
498          <imagedata fileref="../images/3_3_identify.png" format="PNG"/>          <imagedata fileref="../images/3_3_identify.png" format="PNG" scale="&imgscale;"/>
499          </imageobject>          </imageobject>
500          <imageobject>          <imageobject>
501          <imagedata fileref="./images/3_3_identify.eps" format="EPS"/>          <imagedata fileref="./images/3_3_identify.eps" format="EPS" scale="&imgscale;"/>
502          </imageobject>          </imageobject>
503          <textobject> <phrase>Identify Tool</phrase> </textobject>          <textobject> <phrase>Identify Tool</phrase> </textobject>
504          </inlinemediaobject>.          </inlinemediaobject>.
505          Clicking on an object selects that object and opens a dialog which          Clicking on an object selects that object and opens a dialog which
506          shows all the table attributes for that object. Any current selection          shows all the table attributes for that object. Any current selection
507          is lost.          is lost. Objects on the map are typically shapes and this document
508            will often refer to objects as shapes.
509          </para>          </para>
510          </section>          </section>
511    
512          <section><title>Object Labelling</title>          <section><title>Object Labeling</title>
513          <para>          <para>
514          Objects can be labelled using the Label tool          Objects can be labeled using the Label tool
515          <inlinemediaobject>          <inlinemediaobject>
516          <imageobject>          <imageobject>
517          <imagedata fileref="../images/3_3_label.png" format="PNG"/>          <imagedata fileref="../images/3_3_label.png" format="PNG" scale="&imgscale;"/>
518          </imageobject>          </imageobject>
519          <imageobject>          <imageobject>
520          <imagedata fileref="./images/3_3_label.eps" format="EPS"/>          <imagedata fileref="./images/3_3_label.eps" format="EPS" scale="&imgscale;"/>
521          </imageobject>          </imageobject>
522          <textobject> <phrase>Label Tool</phrase> </textobject>          <textobject> <phrase>Label Tool</phrase> </textobject>
523          </inlinemediaobject>.          </inlinemediaobject>.
524          Clicking on an object selects that object and opens a dialog which          Clicking on an object selects that object and opens a dialog which
525          displays the table attributes for that object. An attribute can          displays the table attributes for that object. An attribute can
526          be selected to be the label on the map. Using this tool for an          be selected to be the label on the map. The label will be placed
527          object that already has a label will remove the label.          at the center of the shape. Clicking on an object that already has
528            a label will remove the label.
529          </para>          </para>
530          </section>          </section>
531    
532          <section><title>The Legend</title>          <section><title>The Legend</title>
533            <para>
534            <inlinemediaobject>
535            <imageobject>
536            <imagedata fileref="../images/3_5_legend.png" format="PNG" scale="&imgscale;"/>
537            </imageobject>
538            <imageobject>
539            <imagedata fileref="./images/3_5_legend.eps" format="EPS" scale="&imgscale;"/>
540            </imageobject>
541            <textobject> <phrase>Legend</phrase> </textobject>
542            </inlinemediaobject>
543            </para>
544          <para>          <para>
545          The Legend provides an overview of the layers in the map. Layers          The Legend provides an overview of the layers in the map. Layers
546          that appear higher in the legend will appear ``closer'' to the user.          that appear higher in the legend will appear ``closer'' to the user.
# Line 346  Line 553 
553          <para>          <para>
554          Along the top of the legend is a toolbar which allows quick access          Along the top of the legend is a toolbar which allows quick access
555          to some of the layer manipulation options under          to some of the layer manipulation options under
556          <menuchoice> <guimenu>Map</guimenu> </menuchoice>.          <menuchoice><guimenu>Map</guimenu></menuchoice>.
557            </para>
558    
559            <itemizedlist>
560            <listitem>
561            <para>
562            The Move Layer to Top tool
563            <inlinemediaobject>
564            <imageobject>
565            <imagedata fileref="../images/3_5_totop.png" format="PNG" scale="&imgscale;"/>
566            </imageobject>
567            <imageobject>
568            <imagedata fileref="./images/3_5_totop.eps" format="EPS" scale="&imgscale;"/>
569            </imageobject>
570            <textobject> <phrase>Move Layer to Top</phrase> </textobject>
571            </inlinemediaobject> raises the selected layer to the top of the map.
572            </para>
573            </listitem>
574            <listitem>
575    
576            <para>
577            The Move Layer Up tool
578            <inlinemediaobject>
579            <imageobject>
580            <imagedata fileref="../images/3_5_moveup.png" format="PNG" scale="&imgscale;"/>
581            </imageobject>
582            <imageobject>
583            <imagedata fileref="./images/3_5_moveup.eps" format="EPS" scale="&imgscale;"/>
584            </imageobject>
585            <textobject> <phrase>Move Layer Up</phrase> </textobject>
586            </inlinemediaobject> raises the selected layer one level.
587            </para>
588            </listitem>
589            <listitem>
590    
591            <para>
592            The Move Layer Down tool
593            <inlinemediaobject>
594            <imageobject>
595            <imagedata fileref="../images/3_5_movedown.png" format="PNG" scale="&imgscale;"/>
596            </imageobject>
597            <imageobject>
598            <imagedata fileref="./images/3_5_movedown.eps" format="EPS" scale="&imgscale;"/>
599            </imageobject>
600            <textobject> <phrase>Move Layer Down</phrase> </textobject>
601            </inlinemediaobject> lowers the selected layer one level.
602            </para>
603    
604            </listitem>
605            <listitem>
606            <para>
607            The Move Layer to Bottom tool
608            <inlinemediaobject>
609            <imageobject>
610            <imagedata fileref="../images/3_5_tobottom.png" format="PNG" scale="&imgscale;"/>
611            </imageobject>
612            <imageobject>
613            <imagedata fileref="./images/3_5_tobottom.eps" format="EPS" scale="&imgscale;"/>
614            </imageobject>
615            <textobject> <phrase>Move Layer to Bottom</phrase> </textobject>
616            </inlinemediaobject> lowers the selected layer to the bottom of the map.
617            </para>
618    
619            </listitem>
620            <listitem>
621            <para>
622            The Visible tool
623            <inlinemediaobject>
624            <imageobject>
625            <imagedata fileref="../images/3_5_visible.png" format="PNG" scale="&imgscale;"/>
626            </imageobject>
627            <imageobject>
628            <imagedata fileref="./images/3_5_visible.eps" format="EPS" scale="&imgscale;"/>
629            </imageobject>
630            <textobject> <phrase>Visible</phrase> </textobject>
631            </inlinemediaobject> shows the selected layer in the map if it was
632            hidden.
633            </para>
634    
635            </listitem>
636            <listitem>
637            <para>
638            The Invisible tool
639            <inlinemediaobject>
640            <imageobject>
641            <imagedata fileref="../images/3_5_invisible.png" format="PNG" scale="&imgscale;"/>
642            </imageobject>
643            <imageobject>
644            <imagedata fileref="./images/3_5_invisible.eps" format="EPS" scale="&imgscale;"/>
645            </imageobject>
646            <textobject> <phrase>Invisible</phrase> </textobject>
647            </inlinemediaobject> hides the selected layer in the map.
648            </para>
649    
650            </listitem>
651            <listitem>
652            <para>
653            The Properties tool
654            <inlinemediaobject>
655            <imageobject>
656            <imagedata fileref="../images/3_5_props.png" format="PNG" scale="&imgscale;"/>
657            </imageobject>
658            <imageobject>
659            <imagedata fileref="./images/3_5_props.eps" format="EPS" scale="&imgscale;"/>
660            </imageobject>
661            <textobject> <phrase>Properties</phrase> </textobject>
662            </inlinemediaobject> opens the layer's properties dialog box.
663          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
664          properties dialog for that layer.          properties dialog for that layer.
665          </para>          </para>
666            </listitem>
667            </itemizedlist>
668    
669            <para>
670            The most used layer related actions are also available from a
671            popup menu. It is raised when a layer is clicked with the right mouse
672            button.
673            </para>
674            
675            <para>
676            <figure>
677            <title>Layer Popup Menu</title>
678            <mediaobject>
679            <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
680            <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
681            </mediaobject>
682            </figure>
683            </para>
684    
685            <para>
686            Along the bottom of the legend is the scalebar. The scalebar
687            will be available if there are any layers and the  map has a
688            projection set.
689            </para>
690            </section>
691    
692            <section><title>Exporting</title>
693            <para>
694            Under Windows, maps can be exported in Enhanced Metafile format
695            (<varname>.wmf</varname>)
696            from
697            <menuchoice>
698            <guimenu>Map</guimenu>
699            <guimenuitem>Export</guimenuitem>
700            </menuchoice> for use in reports, presentations, or further
701            modification. The current map view, legend, and, if available,
702            scalebar are exported. Under other platforms this option is not
703            available. Clicking this menu item open a file selection dialog
704            that lets the user select a location to export the map.
705            </para>
706          </section>          </section>
707    
708          <section><title>Printing</title>          <section><title>Printing</title>
# Line 359  Line 711 
711          <menuchoice>          <menuchoice>
712          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
713          <guimenuitem>Print</guimenuitem>          <guimenuitem>Print</guimenuitem>
714          </menuchoice>. A standard printing dialog will open allowing the          </menuchoice>. The current map view, legend, and, if available,
715          user to configure the printer.          scalebar are printed. A standard printing dialog will open allowing
716            the user to configure the printer. This dialog will differ depending
717            on which platform Thuban is running.
718          </para>          </para>
719          </section>          </section>
720    
721    </chapter>    </chapter>
722    
723    <chapter><title>Layer Management</title>    <chapter><title>Layer Management</title>
# Line 371  Line 726 
726    
727          <section><title>Types of Layers</title>          <section><title>Types of Layers</title>
728          <para>          <para>
729          There are two types of layers supported by Thuban: shape layers and          There are three types of layers supported by Thuban: shape layers,
730            database layers and
731          image layers. Shape layers consist of vector based shapes with          image layers. Shape layers consist of vector based shapes with
732          geo-referenced coordinates. There are three types of supported          geo-referenced coordinates. There are three types of supported
733          shapes: polygons, lines, and points. Image layers can be any image          shapes: polygons, lines (arc), and points. Database layers are similar
734          file format supported by GDAL. The images must have geographic          to shape layers but loaded from a database instead of the file system.
735          coordinate data either embedded within the file, or in a seperate          Image layers can be any image
736            file format supported by the Geo-spatial Data Abstraction Library
737            (GDAL). The images must have geographic
738            coordinate data either embedded within the file or in a separate
739          file that is in the same directory as the image file. GeoTIFF files          file that is in the same directory as the image file. GeoTIFF files
740          work very well with Thuban and were designed specifically to be image          work very well with Thuban and were designed specifically to be image
741          layers in GIS programs.          layers in GIS programs.
742          </para>          </para>
743            <para>
744            All actions in the
745            <menuchoice>
746            <guimenu>Layer</guimenu>
747            </menuchoice> menu act on the currently selected layer in the legend.
748            </para>
749          </section>          </section>
750    
751          <section><title>Properties</title>          <section><title>Properties</title>
752          <para>          <para>
753          Each shape in a shape layer can have various properties which control          To view the properties for a layer it must first be selected in the
754          how it is drawn on the map. Polygons and points can be drawn with an          legend. The menu option
755          outline color and a fill color, while lines have only a line color.          <menuchoice>
756            <guimenu>Layer</guimenu>
757            <guimenuitem>Properties</guimenuitem>
758            </menuchoice> opens a dialog that displays a layer's properties.
759            All layers have a title which can be modified in the text field
760            provided. The type of layer is also shows. If the type is a type
761            of shape (polygon, arc, point) the classification table will be
762            shown. Image layers have no other properties other than title
763            and type.
764            </para>
765            <para>
766            <figure>
767            <title>Properties Window</title>
768            <mediaobject>
769            <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
770            <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
771            </mediaobject>
772            </figure>
773            </para>
774            <para>
775            <figure>
776            <title>Properties Window</title>
777            <mediaobject>
778            <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
779            <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
780            </mediaobject>
781            </figure>
782          </para>          </para>
783          </section>          </section>
784    
# Line 396  Line 787 
787          Sometimes it is not desirable to view all layers at the same time.          Sometimes it is not desirable to view all layers at the same time.
788          Some layers may take a long time to draw and so while navigating          Some layers may take a long time to draw and so while navigating
789          around the map the user may not want to wait for the map to redraw          around the map the user may not want to wait for the map to redraw
790          each time the map is changed. Each layer can be independently          all the layers each time the map is changed. Each layer can be
791          turned on or off using the          independently turned on or off using the
792          <menuchoice>          <menuchoice>
793          <guimenu>Layer</guimenu>          <guimenu>Layer</guimenu>
794          <guimenuitem>Show</guimenuitem>          <guimenuitem>Show</guimenuitem>
# Line 410  Line 801 
801          </para>          </para>
802          </section>          </section>
803    
         <section><title>Sequence</title>  
         <para>  
         </para>  
         </section>  
   
804          <section><title>Duplication</title>          <section><title>Duplication</title>
805          <para>          <para>
806          Layers and all their properties, including classifications, can          Layers and all their properties, including classifications, can
# Line 424  Line 810 
810          <guimenuitem>Duplicate</guimenuitem>          <guimenuitem>Duplicate</guimenuitem>
811          </menuchoice>. Duplicating a layer is useful if the user wishes          </menuchoice>. Duplicating a layer is useful if the user wishes
812          to model a layer in several different ways. Even though the layers          to model a layer in several different ways. Even though the layers
813          overlap by carefully selecting the shape properties it is possible          overlap, by carefully selecting the shape properties it is possible
814          to display several pieces of information at once. For example, one          to display several pieces of information at once. For example, one
815          copy of a roads layer may be classified on a length property and          copy of a roads layer may be classified on a length property and
816          another copy may be classified on a type property. if the length          another copy may be classified on a type property. If the length
817          property was expressed with color and the type property expressed          property was expressed with color and the type property expressed
818          with line thickness then it would be possible to view both          with line thickness then it would be possible to view both
819          classifications by placing the type property copy over the          classifications by placing the type property copy over the
# Line 445  Line 831 
831      cannot be classified.      cannot be classified.
832      </para>      </para>
833      <para>      <para>
834      A classification consists of a number of groups, with each group      A classification consists of a number of groups, each group
835      having a value or range of values to match against, and symbol      having a value or range of values to match against, and symbol
836      properties which control how a shape is drawn on the map. The user      properties which control how a shape is drawn on the map. The user
837      selects which field in the table is used by the classification and      selects which field in the table is used by the classification and
# Line 458  Line 844 
844      <para>      <para>
845      A layer always has a classification. When a new layer is added to the      A layer always has a classification. When a new layer is added to the
846      map, a default classification is created with the DEFAULT group. This      map, a default classification is created with the DEFAULT group. This
847      group cannot be removed. Every shape in the layer, regardless of its      group cannot be removed but can be hidden (see below). Every shape in the
848      attributes, will match this group.      layer, regardless of its attributes, will match this group if no other
849        group matches.
850      </para>      </para>
851    
852          <section><title>Editing Classifications</title>          <section><title>Editing Classifications</title>
# Line 476  Line 863 
863          button.          button.
864          </para>          </para>
865          <para>          <para>
866            To apply the changes to the map the user can click
867            either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
868            <guibutton>Try</guibutton> will not close the dialog box, allowing
869            the user to see how the classification changes the map.
870            <guibutton>Revert</guibutton> will undo the last classification applied
871            to the map. <guibutton>OK</guibutton> will commit the changes and
872            close the dialog. The user will be unable to undo the changes.
873            <guibutton>Close</guibutton> simply closes the dialog box. If any
874            changes have not been applied with <guibutton>Try</guibutton> the
875            changes will not be applied to the map.
876            </para>
877            <para>
878            <figure>
879            <title>Properties Window</title>
880            <mediaobject>
881            <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>
882            <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>
883            </mediaobject>
884            </figure>
885            </para>
886            <para>
887          The order of the groups in the classification is significant          The order of the groups in the classification is significant
888          except for the DEFAULT group, which remains at the top. When shapes          except for the DEFAULT group, which remains at the top. When shapes
889          are matched against groups the matching begins at the first group          are matched against groups the matching begins at the first group
890          other than the DEFAULT group so that groups higher in the list will          after the DEFAULT group so that groups higher in the list will
891          be checked first. Matching for a          be checked first. Matching for a
892          given shape will stop at the first group that matches. The user can          given shape will stop at the first group that matches. The user can
893          use <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton>          use <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton>
894          to change the order of the groups. The DEFAULT group will always          to change the order of the groups. The DEFAULT group will always
895          match a shape that hasn't matched another group.          match a shape that hasn't matched another group.
896          </para>          </para>
897          <para>              <section><title>Visible</title>
898          The Value column of the classification table is the value that will              <para>
899          be matched when the map is being drawn. The type of data that can              The Visible column has check-boxes that determine whether a
900          entered into this field depends on the type of data of the              classification group will be displayed in the legend. This is
901          classification field.              useful if the user knows that the groups completely cover
902          </para>              the data set and don't want the DEFAULT group to be displayed
903          <para>              in the legend and on a printout.
904          If the field is of type Text, anything entered              </para>
905          into the field is valid. The text will be compared literally to the          </section>
906          value of the shape attribute, including case sensitivity.              <section><title>Symbols</title>
907          If the type is Integer, then any valid integer may be entered. In              <para>
908          addition, with special syntax, a range of values can be entered.              Each type of shape has its own type of symbol. Thuban supports three
909          A range from <varname>start</varname> to <varname>end</varname>              types of shapes: polygons, lines, and points. Polygons and points
910          inclusive is specifed like this: <literal>[start;end]</literal>.              have outline and fill color, while lines have only line color. Each
911          The exclusive range is specified like this:              group has associated symbol properties. To edit the symbol
912          <literal>]start;end[</literal>. Ranges can include infinity like              properties for a group the user can double click on the Symbol
913          this: <literal>[-oo;oo]</literal>. Field types can also be of type              column or select a group and click the
914          Decimal. They represent any rational number and can be used in ranges              <guibutton>Edit Symbol</guibutton> button.
915          as well.              </para>
916          </para>              </section>
917          </section>          <section><title>Value</title>
918                <para>
919          <section><title>Symbols</title>              The Value column of the classification table is the value that will
920          <para>              be matched when the map is being drawn. The type of filter that can
921          Each type of shape has its own type of symbol. Thuban supports three              entered into this field depends on the type of data of the
922          types of shapes: polygons, lines, and points. Polygons and points have              classification field:
923          outline and fill color, while lines have only line color. Each group              </para>
924          has associated symbol properties. To edit the symbol properties for a              <para>
925          group the user can double click on the Symbol column or select a              If the field is of type Text, anything entered
926          group and click the <guibutton>Edit Symbol</guibutton> button.              into the field is valid. By default the text will be compared
927          </para>              literally to the
928                value of the shape attribute, including case sensitivity.
929                Alternatively the comparison can be based on regular experessions.
930                Right-click on the row label to open a popup menu with the options
931                <guibutton>Singleton</guibutton> (literal comparison) and  
932                <guibutton>Pattern</guibutton> (regular expressions).  
933                </para>
934                <para>
935                If the type is Integer, then any valid integer may be entered. In
936                addition, with special syntax, a range of values can be entered.
937                A range from <varname>start</varname> to <varname>end</varname>
938                inclusive is specified like this: <literal>[start;end]</literal>.
939                The exclusive range is specified like this:
940                <literal>]start;end[</literal>. Ranges can include infinity like
941                this: <literal>[-oo;oo]</literal>. Field types can also be of type
942                Decimal. They represent any rational number and can be used in
943                ranges as well.
944                </para>
945           </section>
946                <section><title>Label</title>
947                <para>
948                By default, the text that is displayed for a group in the legend
949                is the value for that group. The label can substitute a more
950                descriptive term in the legend.
951                </para>
952            </section>
953          </section>          </section>
954    
955          <section><title>Generating Classes</title>          <section><title>Generating Classes</title>
956          <para>          <para>
957            <figure>
958            <title>Generate Class</title>
959            <mediaobject>
960            <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>
961            <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>
962            </mediaobject>
963            </figure>
964            </para>
965            <para>
966          Creating a classification by hand can be tedious.          Creating a classification by hand can be tedious.
967          Thuban, therefore, provides a means of generating an entire          Thuban, therefore, provides a means of generating an entire
968          classification at once while still giving the user control over          classification at once while still giving the user control over
969          how it appears. Clicking <guibutton>Generate Class</guibutton>          how it appears. Clicking <guibutton>Generate Class</guibutton>
970          opens the <varname>Generate Classification</varname> dialog.          opens the <varname>Generate Classification</varname> dialog.
971          Under the <varname>Generate</varname> pulldown there are at most          Under the <varname>Generate</varname> pull down there are at most
972          three different ways to generate classifications:          three different ways to generate classifications:
973          Unique Values, Unique Distribution, and Quantiles. Some options          Unique Values, Uniform Distribution, and Quantiles. Some options
974          may not be available if they data type for the field does not          may not be available if the data type for the field does not
975          support them. For instance, <varname>Unique Distribution</varname>          support them. For instance, <varname>Uniform Distribution</varname>
976          doesn't make sense for a Text field.          doesn't make sense for a Text field.
977          </para>          </para>
978          <para>          <para>
979          For every way of generating a classification, a color scheme must          For every way of generating a classification, a color scheme must
980          be selected. Thuban provides several different color schemes that          be selected. Thuban provides several different color schemes that
981          affect how the group properties change over the classification.          affect how the group properties change over the classification.
982            It may be desirable that only certain properties change over the
983            classification. If the shape type is a polygon or a point then
984            the <guibutton>Fix Border Color</guibutton> option will be available.
985            This allows the user to select a border color for all classification
986            groups.
987          It is also possible to create a custom color scheme. Selecting          It is also possible to create a custom color scheme. Selecting
988          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
989          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
990          properties of the last group. Thuban will interpolate between these          properties of the last group. Thuban will interpolate between these
991          two properties to generate the other groups.          two properties to generate the other groups.
992            <figure>
993            <title>Custom Color Scheme</title>
994            <mediaobject>
995            <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>
996            <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>
997            </mediaobject>
998            </figure>
999          </para>          </para>
1000          <para>          <para>
1001          The Unique Values option lets the user select specific values that          The Unique Values option lets the user select specific values that
# Line 551  Line 1005 
1005          right. Each list can be sorted or reversed for easier searching.          right. Each list can be sorted or reversed for easier searching.
1006          The classification that is generated will be in the same order as          The classification that is generated will be in the same order as
1007          the list on the right.          the list on the right.
1008            <figure>
1009            <title>Unique Values</title>
1010            <mediaobject>
1011            <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>
1012            <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>
1013            </mediaobject>
1014            </figure>
1015          </para>          </para>
1016          <para>          <para>
1017          The Unique Distribution option creates a user specified number of          The Uniform Distribution option creates a user specified number of
1018          groups of ranges such that each range covers equal intervals. The          groups of ranges such that each range covers equal intervals. The
1019          minimum and maximum values can automatically be retrieved from the          minimum and maximum values can automatically be retrieved from the
1020          table by clicking <guibutton>Retrieve From Table</guibutton>. The          table by clicking <guibutton>Retrieve From Table</guibutton>. The
1021          stepping is how large each interval is. Adjusting this value will          stepping is how large each interval is. Adjusting this value will
1022          automatically recalculate how many groups is appropriate.          automatically recalculate how many groups is appropriate.
1023            <figure>
1024            <title>Uniform Distribution</title>
1025            <mediaobject>
1026            <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>
1027            <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>
1028            </mediaobject>
1029            </figure>
1030          </para>          </para>
1031          <para>          <para>
1032          The Quantiles option generates ranges based on the number items          The Quantiles option generates ranges based on the number of items
1033          in the input set. For example, by specifying 5 groups Thuban will          in the table. For example, by specifying five groups Thuban will
1034          generate groups with appropriate ranges such that 20% of the table          generate five groups with appropriate ranges such that 20% of the table
1035          data is in each group. If it is impossible to generate exact          data is in each group. If it is impossible to generate exact
1036          grouping, Thuban will issue a warning but allow the user to continue.          groupings, Thuban will issue a warning but allow the user to continue.
1037            <figure>
1038            <title>Quantiles</title>
1039            <mediaobject>
1040            <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>
1041            <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>
1042            </mediaobject>
1043            </figure>
1044          </para>          </para>
1045          </section>          </section>
1046    </chapter>    </chapter>
# Line 574  Line 1049 
1049      <para>      <para>
1050      Projections control how the geographic data is displayed on the screen.      Projections control how the geographic data is displayed on the screen.
1051      If multiple layers are loaded into Thuban where the geographic data      If multiple layers are loaded into Thuban where the geographic data
1052      is in a different projection system, then the user must tell Thuban      is in a different projection system, then the user must specify a
1053      which projection each layer has. The user must also tell Thuban which      projection for each layer. The user must also tell Thuban which
1054      projection the map is in. This can be the same as the layers or a different      projection the map is in. This can be the same as the layers or a different
1055      projection in which case the layers are reprojected into that space.      projection in which case the layers are reprojected into that space.
1056      The map projection can be set using      The map projection can be set using
# Line 587  Line 1062 
1062      <guimenu>Layer</guimenu>      <guimenu>Layer</guimenu>
1063      <guimenuitem>Projection</guimenuitem>      <guimenuitem>Projection</guimenuitem>
1064      </menuchoice>.      </menuchoice>.
1065        <figure>
1066        <title>Projection Window</title>
1067        <mediaobject>
1068        <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>
1069        <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>
1070        </mediaobject>
1071        </figure>
1072        </para>
1073        <para>
1074        Thuban is distributed with a sample collection of projections and the
1075        set of coordinate systems as used by the EPSG
1076        (European Petroleum Survey Group). This quite large set is only displayed
1077        if activated by the according checkbox. The set falls into two parts:
1078        deprecated lists all projections which are no longer part of the
1079        EPSG data base.
1080      </para>      </para>
1081      <para>      <para>
1082      Thuban is distributed with a sample collection of projections. The           The
1083      user can create new projections and make them available to all      user can create new projections and make them available to all
1084      future Thuban sessions. They may also be exported and imported so      future Thuban sessions. They may also be exported and imported so
1085      that custom projections can be distributed to others.      that custom projections can be distributed.
1086      </para>      </para>
1087          <section><title>Selecting a Projection</title>          <section><title>Selecting a Projection</title>
1088          <para>          <para>
1089          The available projections are listed on the left. If the layer          The available projections are listed on the left. If the layer
1090          or map already has a projection it will be initially highlighted          or map already has a projection it will initially be highlighted
1091          and will end with <varname>(current)</varname>. Selecting          and will end with <varname>(current)</varname>. Selecting
1092          <varname>None</varname> will cause Thuban to use the data as          <varname>&lt;None&gt;</varname> will cause Thuban to use the data as
1093          it appears in the source file and will not use a projection.          it appears in the source file and will not use a projection.
1094          </para>          </para>
1095      </section>      </section>
# Line 608  Line 1098 
1098          Whenever a projection is selected from the list its properties          Whenever a projection is selected from the list its properties
1099          are displayed on the right. These properties can be changed          are displayed on the right. These properties can be changed
1100          and the changes saved to the selected projection using          and the changes saved to the selected projection using
1101          the <guibutton>Update</guibutton>. Only a projection that comes          <guibutton>Update</guibutton>. Only a projection that comes
1102          from a file can be updated, so if the current layer's projection          from a file can be updated, so if the current layer's projection
1103          is selectd, <guibutton>Update</guibutton> will be disabled.          is selected, <guibutton>Update</guibutton> will be disabled.
1104          The <guibutton>Add to List</guibutton> adds the projection to the          <guibutton>Add to List</guibutton> adds the projection to the
1105          list of available projections as a new entry, and thus make it          list of available projections as a new entry, and thus makes it
1106          available to future Thuban sessions. Clicking <guibutton>New</guibutton>          available to future Thuban sessions. Clicking <guibutton>New</guibutton>
1107          will create an entirely new, empty projection. The          will create an entirely new, empty projection. The
1108          <guibutton>Remove</guibutton> button will permanantly remove a          <guibutton>Remove</guibutton> button will permanently remove a
1109          projection from the list of available projections.          projection from the list of available projections.
1110          </para>          </para>
1111            <para>
1112            To apply the selected projection to the map the user can click
1113            either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
1114            <guibutton>Try</guibutton> will not close the dialog box, allowing
1115            the user to see how the projeciton changes the map.
1116            <guibutton>Revert</guibutton> will undo the last projection applied
1117            to the map. <guibutton>OK</guibutton> will commit the changes and
1118            close the dialog. The user will be unable to undo the changes.
1119            <guibutton>Close</guibutton> simply closes the dialog box. If no
1120            selection has been applied with <guibutton>Try</guibutton> the
1121            selection will not be applied to the map.
1122            </para>
1123      </section>      </section>
1124          <section><title>Importing/Exporting Projections</title>          <section><title>Importing/Exporting Projections</title>
1125          <para>          <para>
1126          The projections that appear in the list of available projections          The projections that appear in the list of available projections
1127          can be exported to another file that the user chooses. By selecting          can be exported to another file that the user chooses. By selecting
1128          one or more projections and clicking <guibutton>Export</guibutton>          one or more projections and clicking <guibutton>Export</guibutton>
1129          the user will be able to select a file to store those projections.          the user will be able to select a file in which to store those
1130            projections.
1131          The file can then be distributed to other Thuban users. To import          The file can then be distributed to other Thuban users. To import
1132          a projection file the user can click <guibutton>Import</guibutton>.          a projection file the user can click <guibutton>Import</guibutton>.
1133          The imported projections are added to the list and are then available          The imported projections are added to the list and are then available
1134          to the current session and any future Thuban session.          to the current session and any future Thuban sessions.
1135          </para>          </para>
1136      </section>      </section>
1137    </chapter>    </chapter>
1138    
1139    <chapter><title>Table Management</title>    <chapter><title>Table Management</title>
1140      <para>      <para>
1141              Thuban distinguishes two different types of tables: Attribute tables      Thuban distinguishes two different types of tables: Attribute tables
1142              (which belong to a layer) and usual data tables. Both provide in      (which belong to a layer) and normal data tables. Both provide
1143          general the same functionality with the difference that actions on an          the same general functionality with the difference that actions on an
1144              attribute table might also effect the map display.      attribute table might also effect the map display.
1145      </para>      </para>
1146    
1147      <section><title>Table View</title>      <section><title>Table View</title>
1148        <para>          <para>
1149            <figure>
1150            <title>Table View</title>
1151            <mediaobject>
1152            <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>
1153            <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>
1154            </mediaobject>
1155            </figure>
1156            </para>
1157            <para>
1158          Thuban provides a standard dialog to display table contents, the          Thuban provides a standard dialog to display table contents, the
1159          Table View. The view falls into five sections: The title, selections,          Table View. The view has five sections: The title, selections,
1160          the table grid, export functions and the status bar.          the table grid, export functions, and the status bar.
1161        </para>          </para>
1162        <para>          <para>
1163          The title bar identifies the table with it's name.          The title bar identifies the table with its name.
1164        </para>          </para>
1165        <para>          <para>
1166          The functions box let the user perform simple analysis on the data          The selections box let the user perform simple analysis on the data
1167          based on comparisons: First choice must be a field identifier of the          based on comparisons: The first choice must be a field identifier of
1168          table, the second choice determines the type of comparison. The third          the table, the second choice determines the type of comparison. The
1169          choice can be either a specific value (interpreted as numerical          third choice can be either a specific value (interpreted as numerical
1170          or string depending on the type of the first field) or a second field          or string depending on the type of the first field) or a second field
1171          identifier. Thus you can perform analysis like selecting all          identifier. Thus you can perform analysis like selecting all
1172          records where "population > 10000" or          records where <literal>population > 10000</literal> or
1173          "cars_per_habitants <  bike_per_habitants" (note that the field names          <literal>cars_per_inhabitant < bikes_per_inhabitant</literal>
1174          are only explanatory, the currently considered dbase files allow only          (note that the field names are only explanatory, the dBase files
1175          11 character field names).          allow only 11 character field names).
1176                  
1177          Selections can be combined, either by applying a selection only on          Selections can be combined either by applying a selection only on
1178          a previously selected set of records or by adding the results of a          a previously selected set of records or by adding the results of a
1179          selection to a previous set. The default is that a selection replaces          selection to a previous set. The default is that a selection replaces
1180          earlier results.          earlier results.
1181        </para>          </para>
1182        <para>          <para>
1183          The table grid shows the contents of the table (a record per column),          The table grid shows the contents of the table (one record per row),
1184          with highlighted selection results. Columns and rows can be resized.          with highlighted selection results. Columns and rows can be resized.
1185        </para>          </para>
1186        <para>          <para>
1187          The contents of a table can be exported into a file, either dbase          The contents of a table can be exported into a file, either dBase
1188          format (DBF) or comma seperated values (CSV). The 'Export' button          format (DBF) or comma separated values (CSV). The
1189            <guibutton>Export</guibutton> button
1190          raises a file dialog to specify a path and file name, the export type          raises a file dialog to specify a path and file name, the export type
1191          is determined by the file extension (either .dbf or .csv).          is determined by the file extension (either .dbf or .csv).
1192    
1193          The 'Export Selection' button works similar but exports only the          The <guibutton>Export Selection</guibutton> button works similarly
1194          selected records.          but exports only the selected records.
1195    
1196          The 'Close' button closes the table view. In difference to the          The <guibutton>Close</guibutton> button closes the table view window.
1197          menu item 'Close' just the dialog is closed, the table is still loaded          This is different from the menu item
1198          in Thuban.          <menuchoice>
1199        </para>          <guimenu>Table</guimenu>
1200        <para>          <guimenuitem>Close</guimenuitem>
1201            </menuchoice> which unloads the table from Thuban.
1202            </para>
1203            <para>
1204          The status bar displays some statistics about the table and optional          The status bar displays some statistics about the table and optional
1205          selection results.          selection results.
1206        </para>          </para>
1207      </section>      </section>
1208    
1209      <section><title>General Functionality (Menu Table)</title>      <section><title>General Functionality (Menu Table)</title>
1210        <para>          <para>
1211          The general functions affect all tables open in Thuban. Attribute          The general functions affect all tables open in Thuban. Attribute
1212          tables are considered as here as usual data tables (with the exception          tables are considered here as normal data tables (with the exception
1213          that they cannot be closed).          that they cannot be closed).
       </para>  
       <section><title>Open</title>  
         <para>  
           The 'Open' item raises a file dialog to let you select a  
           dbase file from the file system to be loaded into Thuban read-only.  
           On OK the selected file is loaded and a table view is opened.  
         </para>  
       </section>  
   
       <section><title>Close</title>  
         <para>  
           The 'Close' item raises a dialog listing the currently open  
           data tables (loaded via the 'Open' functionality'). You can select  
           tables which are dereferenced on confirmation. Since tables are  
           opened read-only the contents of the tables are not affected.  
   
           A still open table view is closed as well.  
   
           Tables used in a join can not be closed.  
1214          </para>          </para>
1215        </section>          <section><title>Open</title>
1216                <para>
1217        <section><title>Rename</title>              The
1218          <para>              <menuchoice>
1219            Changes the table title.              <guimenu>Table</guimenu>
1220          </para>              <guimenuitem>Open</guimenuitem>
1221        </section>              </menuchoice>
1222                item raises a file dialog to let you select a
1223        <section><title>Show</title>              dBase file from the file system to be loaded into Thuban read-only.
1224          <para>              On <guibutton>OK</guibutton> the selected file is loaded and a
1225            The 'Show' item raises a list of available tables (explicitly loaded,           attribute tables, results of a join). Selected tables are show in              table view is opened.
1226            tables views on 'OK'.                        </para>
1227          </para>          </section>
1228        </section>  
1229            <section><title>Close</title>
1230        <section><title>Join</title>              <para>
1231          <para>              The
1232            The 'Join' item raises a dialog to specify the two tables to be              <menuchoice>
1233            joined. The join results in a new table named 'Join of "left table"              <guimenu>Table</guimenu>
1234            and "right table"'.              <guimenuitem>Close</guimenuitem>
1235                </menuchoice>
1236            The dialog let you select the two tables to be joined and the two              item raises a dialog listing the currently open
1237            fields the join has to be performed on. By default the new              data tables
1238            table contains only those records which are mathced by the join.              (loaded via
1239                <menuchoice>
1240            If you want to preserve the records of the left table you can perform              <guimenu>Table</guimenu>
1241            an outer join. The fields from the right table for records not              <guimenuitem>Open</guimenuitem>
1242            matched by the join are filled with <varname>None</varname> in this              </menuchoice>). Selected tables are dereferenced on confirmation.
1243            case.              Since tables are opened read-only the contents of the tables are
1244          </para>              not affected.
1245        </section>  
1246                Any open views of the tables are closed as well.
1247    
1248                Tables used in a join cannot be closed.
1249                </para>
1250            </section>
1251    
1252            <section><title>Rename</title>
1253                <para>
1254                <menuchoice>
1255                <guimenu>Table</guimenu>
1256                <guimenuitem>Rename</guimenuitem>
1257                </menuchoice> changes the table title.
1258                </para>
1259            </section>
1260    
1261            <section><title>Show</title>
1262                <para>
1263                The
1264                <menuchoice>
1265                <guimenu>Table</guimenu>
1266                <guimenuitem>Show</guimenuitem>
1267                </menuchoice>
1268                item raises a list of available tables (explicitly
1269                loaded, attribute tables, results of a join). Selected tables are
1270                show in tables views on <guibutton>OK</guibutton>.
1271                </para>
1272            </section>
1273    
1274            <section><title>Join</title>
1275                <para>
1276                <figure>
1277                <title>Join Tables</title>
1278                <mediaobject>
1279                <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>
1280                <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>
1281                </mediaobject>
1282                </figure>
1283                </para>
1284                <para>
1285                The
1286                <menuchoice>
1287                <guimenu>Table</guimenu>
1288                <guimenuitem>Join</guimenuitem>
1289                </menuchoice>
1290                item raises a dialog to specify the two tables to be
1291                joined. The join results in a new table named 'Join of "left table"
1292                and "right table"'.
1293    
1294                The dialog lets you select the two tables to be joined and the two
1295                fields the join has to be performed on. By default, the new
1296                table contains only those records which are matched by the join.
1297    
1298                If you want to preserve the records of the left table you can
1299                perform an outer join. The fields from the right table for records
1300                not matched by the join are filled with <varname>None</varname> in
1301                this case.
1302                </para>
1303            </section>
1304    
1305      </section>      </section>
1306      <section><title>Attribute Tables</title>      <section><title>Attribute Tables</title>
     <para>  
             To clearly separate between both types, Thuban provides functionality  
             regarding the attribute tables under the Layer menu.  
     </para>  
   
       <section><title>Show Table</title>  
         <para>  
           Opens the attribute table of the currently active layer in a table  
           view.  
   
           In addition to the functionality described above selections  
           affect also the map display: objects related to selected records  
           are highlighted.  
         </para>  
       </section>  
   
       <section><title>Join Table</title>  
1307          <para>          <para>
1308             In difference to the join described above the join results not in a              To clearly separate between both types of tables (data and
1309            attribute), Thuban provides functionality regarding the attribute
1310            tables under the <menuchoice><guimenu>Layer</guimenu></menuchoice> menu.
1311            </para>
1312    
1313            <section><title>Show Table</title>
1314                <para>
1315                <menuchoice>
1316                <guimenu>Layer</guimenu>
1317                <guimenuitem>Show Table</guimenuitem>
1318                </menuchoice>
1319                opens the attribute table of the currently active layer in a table
1320                view.
1321    
1322                In addition to the functionality described above selections
1323                affect also the map display: objects related to selected records
1324                are highlighted.
1325                </para>
1326            </section>
1327    
1328            <section><title>Join Table</title>
1329                <para>
1330                Unlike the join described above, the join does not result in a
1331              new table. The attribute table of the currently active layer is the              new table. The attribute table of the currently active layer is the
1332              left table and other tables are join to this table. Results of the              left table and other tables are joined to this table. The results of
1333              join in turn are available for classifications.              the join are available for classification.
   
             As a consequence of the above the join cannot result in less  
             records than the source attribute table. You are warned if the  
             right table does not fulfill this constraint. Use an outer join  
             in such cases.  
         </para>  
       </section>  
1334    
1335        <section><title>Unjoin Table</title>              As a consequence, the join cannot result in fewer
1336          <para>              records than the source attribute table. The user is warned if the
1337              As said above, a usual table can not be closed while still used in              right table does not fulfill this constraint. An outer join must be
1338              a join. While the join table resulting from a join of usual tables              used in such cases.
1339              can be simply closed (and therewith dereferences the source tables)              </para>
1340              this is not possible for attribute tables.          </section>
1341    
1342              Hence joins on attribute tables must be solved explicitely. This is          <section><title>Unjoin Table</title>
1343              what the 'Unjoin' item is used for: The last join for the currently              <para>
1344                As said above, a normal table cannot be closed while it is still
1345                used in a join. While the joined table resulting from a join of
1346                normal tables can be simply closed (and thereby dereferencing
1347                the source tables), this is not possible for attribute tables.
1348    
1349                Hence joins on attribute tables must be solved explicitly. This is
1350                what the
1351                <menuchoice>
1352                <guimenu>Layer</guimenu>
1353                <guimenuitem>Unjoin Table</guimenuitem>
1354                </menuchoice>
1355                item is used for: The last join for the currently
1356              active layer is solved.              active layer is solved.
1357          </para>              </para>
1358        </section>          </section>
   
1359      </section>      </section>
1360    </chapter>    </chapter>
1361    
1362      <chapter><title>Extensions</title>
1363            <para>
1364            Thuban is designed to be extensible. The term Extension is used as a
1365            general term for anything that extends Thuban.
1366            This chapter introduces into some oppportunities how to add and
1367            handle extra functionality developed by your own or third parties.
1368            </para>
1369    
1370            <section><title>Add personal extensions via thubanstart.py</title>
1371                    <para>
1372                    After Thuban has been started for the first time, a directory
1373                    .thuban is created within your home directory.
1374                    There you can add a file thubanstart.py  which will be imported
1375                    by Thuban at start-up. It is recommended to add only import-statements
1376                    to this file to keep the actual code of extensions separate.
1377                    </para>
1378                    <para>
1379                    The modules to import must either be found through the environment
1380                    variable PYTHONPATH or directly be placed into the .thuban-directory.
1381                    </para>
1382                    <para>
1383                    As an example, copy the file examples/simple_extensions/hello_world.py
1384                    of the Thuban source code into the .thuban-directory of your home
1385                    directory. Now add add the statement import hello_world to the
1386                    file thubanstart.py and run Thuban. You will notice an additional
1387                    menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
1388                    the new item for the Hello-World extension is placed - select it
1389                    to see the Hello-World message.
1390                    </para>
1391            </section>
1392    
1393            <section><title>Extensions included in Thuban package</title>
1394                    <para>
1395                    The extensions described in this section are part of the
1396                    Thuban package, but not activated by default.
1397                    You will find them in the Thuban installation directory
1398                    under <literal>Extensions/</literal>. Activate them as personal
1399                    extensions via PYTHONPATH as described in the previous section.
1400                    Stable extensions will appear under the menu
1401                    <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
1402                    extensions which are in experimental state and therefore
1403                    not fully functional under
1404                    <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
1405                    </para>
1406    
1407                    <section><title>Stable extensions</title>
1408                        <para>
1409                        These extensions provide extra-functionality to Thuban
1410                        that has not (yet) been integrated in the main application.
1411                        They are considered to be free of bugs, but may be
1412                        further polished with helpful user interactions.
1413                        </para>
1414                        <section><title>gns2shp</title>
1415                                    <para>
1416                                    This tool converts data of the Geospatial Names Server
1417                                    (GNS, see <ulink url="http://www.nima.mil/gns"/>)
1418                                    into Shapefile format.
1419                                    The above web-site offer to download named places
1420                                    information grouped by countries for all of the world
1421                                    except USA for which other data are provided.
1422                                    </para>
1423                                    <para>
1424                                    If you download and unpack a package, you will have
1425                                    a text-file with suffix .txt.
1426                                    Selecting such a file via gns2shp will create the
1427                                    corresponding Shapefile with the same basename and
1428                                    place it in the same direcory. Afterwards it
1429                                    is automatically loaded into Thuban.
1430                                    The Shapefile will not automatically be delete afterwards.
1431                                    </para>
1432                                    <para>
1433                                    The gns2shp.py module can also be executed on the
1434                                    command line for batch processing purposes.
1435                                    </para>
1436                                    <para>
1437                                    A sample (<literal>ls.txt</literal> for Liechtenstein)
1438                                    is included in the directory
1439                                    <literal>Extensions/gns2shp/test</literal>.
1440                                    </para>
1441                        </section>
1442                        <section><title>SVG Export</title>
1443                            <para>
1444                            Map and legend can be exported separately in the
1445                            Thuban-Map-SVG format.
1446                            You get files that comply with
1447                            the Scalable Vector Graphics (SVG) 1.1 Specification
1448                            and can be read by many vector drawing applications.
1449                            </para>
1450                            <para>
1451                            Goal of svgexport is to provide
1452                            the start of a printing pipeline for Thuban.
1453                            For this purpose the written Thuban-Map-SVG files
1454                            contain information that can be used in postprocessing.
1455                            Typically a general vector drawing application is
1456                            more powerful then a geographic information viewer;
1457                            e.g. having much fancier symbols and fonts.
1458                            Also users benefit much more when learning to use a
1459                            more general application they can also use for other
1460                            tasks.  So the charming idea is to enable
1461                            the drawing application to postprocess a Thuban maps.
1462                            So thee xtra information in the format will make it
1463                            possible to export from Thuban and if a few geoobjects
1464                            change, and keep the general layout and style
1465                            of the full map in the vector drawing appplication.
1466                            </para>
1467                            <para>
1468                            Markus Rechtien has developed a prototype of this
1469                            printing pipline as his Diplom thetis, showing
1470                            the feasability of Bernhard Reiter's concept.
1471                            Scripts exist for the drawing application Skencil
1472                            (<ulink url="http://www.skencil.org"/>).
1473                            </para>
1474                            <para>
1475                            Technical notes: the names of the layers are used
1476                            as base for ids within the SVG format.
1477                            If you try to export with two layers having
1478                            the same name, you will get a name clash error.
1479                            Just change one of the layer names and try again.
1480                            </para>
1481                        </section>
1482                    </section>
1483                    <section><title>Experimental extensions</title>
1484                            <para>
1485                            All all of these functions have to be handled with care,
1486                            since they are neither complete nor well tested.
1487                            They are to be seen as a proof-of-concept and may
1488                            additionally in some cases of practical help.
1489                            </para>
1490                            <para>
1491                            Any interest on further improvement of these extensions
1492                            should be communicated towards the developer and user
1493                            community.
1494                            </para>
1495    
1496                            <section><title>importAPR</title>
1497                                    <para>
1498                                    This command offer to load an ESRI� ArcView� project
1499                                    file (suffix .apr) and convert it for use within Thuban.
1500                                    After selecting a apr-file to load, a list
1501                                    will be presented that offers to select one of the views
1502                                    of the apr-file, provided there is more than one.
1503                                    Furthermore, the Session Info-Tree is extended with
1504                                    a complete representation of the parsed apr-file.
1505                                    </para>
1506                                    <para>
1507                                    The legend of Thuban does not yet cover all of the elements as
1508                                    supported by the legend of ArcView�. Therefore, the Thuban
1509                                    map will look different. Furthermore, the apr-format is
1510                                    a proprietary format, not openly documented.
1511                                    Therefore, the interpretation is
1512                                    partly based on reverse engeneering and good guessing.
1513                                    </para>
1514                                    <para>
1515                                    The file-paths within the apr-file may not fit and potentially
1516                                    are subject to fix in the apr-file. You can do this
1517                                    applying any text editor. The paths are either absolute
1518                                    or relative from where Thuban has been started.
1519                                    </para>
1520                                    <para>
1521                                    A sample for the Iceland data is included as
1522                                    <literal>Extensions/importAPR/samples/iceland.apr</literal>.
1523                                    The file-paths are relative from the Thuban main directory.
1524                                    </para>
1525                            </section>
1526                    </section>
1527            </section>
1528    
1529            <section><title>Writing simple extensions</title>
1530                    <para>
1531                    Writing an extension for Thuban basically means to
1532                    implement the extra functionality in Python with all of the
1533                    Thuban classes, methods and variables available.
1534                    </para>
1535                    <para>
1536                    All classes and their methods are documented in the source code
1537                    (see their doc-strings). Here is an example from
1538                    Thuban/Model/layer.py that describes some of the methods
1539                    of a Layer object:
1540                    </para>
1541                    <programlisting>
1542                    <![CDATA[
1543    class BaseLayer(TitledObject, Modifiable):
1544    
1545        """Base class for the layers."""
1546    
1547        def __init__(self, title, visible = True, projection = None):
1548            """Initialize the layer.
1549    
1550            title -- the title
1551            visible -- boolean. If true the layer is visible.
1552            """
1553            TitledObject.__init__(self, title)
1554            Modifiable.__init__(self)
1555            self.visible = visible
1556            self.projection = projection
1557    
1558        def Visible(self):
1559            """Return true if layer is visible"""
1560            return self.visible
1561    
1562        def SetVisible(self, visible):
1563            """Set the layer's visibility."""
1564            self.visible = visible
1565            self.issue(LAYER_VISIBILITY_CHANGED, self)
1566    
1567        def HasClassification(self):
1568            """Determine if this layer support classifications."""
1569    ...
1570                    ]]>
1571                    </programlisting>
1572                    <para>
1573                    This example intends to give you an impression of the
1574                    source-code-level documentation.
1575                    You have to make yourself familiar with
1576                    the Python programming language to understand some special
1577                    code elements.
1578                    </para>
1579                    <section><title>hello_world.py</title>
1580                      <para>
1581                      Traditionally, the first example should welcome the world.
1582                      Most of the code handles the frame for integrating a menu
1583                      item into Thuban while the actual raising of a message
1584                      is done in a single line.
1585                      </para>
1586                            <programlisting>
1587                            <![CDATA[
1588    # Copyright (C) 2003 by Intevation GmbH
1589    # Authors:
1590    # Jan-Oliver Wagner <[email protected]>
1591    #
1592    # This program is free software under the GPL (>=v2)
1593    # Read the file COPYING coming with Thuban for details.
1594    
1595    """
1596    Extend Thuban with a sample Hello World to demonstrate simple
1597    extensions.
1598    """
1599    
1600    __version__ = '$Revision$'
1601    
1602    # use _() already now for all strings that may later be translated
1603    from Thuban import _
1604    
1605    # Thuban has named commands which can be registered in the central
1606    # instance registry.
1607    from Thuban.UI.command import registry, Command
1608    
1609    # The instance of the main menu of the Thuban application
1610    # See Thuban/UI/menu.py for the API of the Menu class
1611    from Thuban.UI.mainwindow import main_menu
1612    
1613    def hello_world_dialog(context):
1614        """Just raise a simple dialog to greet the world.
1615    
1616        context -- The Thuban context.
1617        """
1618        context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
1619    
1620    
1621    # create a new command and register it
1622    registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
1623                         helptext = _('Welcome everyone on this planet')))
1624    
1625    # find the extensions menu (create it anew if not found)
1626    extensions_menu = main_menu.FindOrInsertMenu('extensions', _('E&xtensions'))
1627    
1628    # finally bind the new command with an entry in the extensions menu
1629    extensions_menu.InsertItem('hello_world')
1630                            ]]>
1631                            </programlisting>
1632                    </section>
1633                    <section><title>Registering a Command</title>
1634                      <para>
1635                      Mainly, our new function has to be registered to the Thuban
1636                      framework in order to connect it to the menu. A registered
1637                      command can also be connected to e.g. a toolbar button.
1638                      </para>
1639                      <para>
1640                      The instances and classes for this are imported at the beginning.
1641                      Any code not inside a method or class is directly executed when
1642                      the source-code module is imported. Therefore, the second
1643                      part of this example consist of the plain statements to create a new
1644                      Command and to add it to the menu.
1645                      </para>
1646                      <para>
1647                      By convention, it looks for a menu registered as ``extensions'' to
1648                      insert the new command. If it does not exist yet, it gets created.
1649                      It is advisable to copy this code for any of your extensions.
1650                      </para>
1651                    </section>
1652                    <section><title>The Thuban context</title>
1653                            <para>
1654                            A registered command that is called, always receives the
1655                            Thuban context. This instance provides our method with
1656                            hook references to all important components of the Thuban
1657                            application.
1658                            </para>
1659                            <para>
1660                    In the example hello_world.py, our function uses the
1661                            mainwindow component which offers a method to raise a
1662                            message dialog. In total there are three hooks:
1663                            <itemizedlist>
1664                            <listitem>
1665                            <para>application:
1666                            This object is the instance of the Thuban Application class.
1667                            Except maybe for loading or savinf sessions, you will not
1668                            need this object for a simple extension.
1669                            See Thuban/UI/application.py for the API.
1670                            </para>
1671                            </listitem>
1672                            <listitem>
1673                            <para>session:
1674                            The instance of the current session. It manages the sessions'
1675                            map and tables. You can set and remove the map or tables.
1676                            In may also get the map object. However, you should know that
1677                            internally it is already prepared to handle many maps.
1678                            Therfore, currently you would always receive a list with exactlty
1679                            one element. In the future, if there are more than one map,
1680                            you will not know which one is the currently display one and
1681                            therefore you should use the mainwindow as hook to find
1682                            the currently displayed map.
1683                            See Thuban/Model/session.py for the API.
1684                            </para>
1685                            </listitem>
1686                            <listitem>
1687                            <para>
1688                            mainwindow: The mainwindow object is central to manage various
1689                            GUI things such as the Legend sub-window. Most notably,
1690                            you get access to the canvas which is the window part where
1691                            the map is drawn. The canvas knows, which map it currently
1692                            draws and therefore you get the current map via
1693                            context.mainwindow.canvas.Map().
1694                            See Thuban/UI/mainwindow.py for the API.
1695                            </para>
1696                            </listitem>
1697                            </itemizedlist>
1698                </para>
1699                    </section>
1700            </section>
1701      </chapter>
1702    
1703    <chapter><title>Trouble Shooting</title>    <chapter><title>Trouble Shooting</title>
1704      <para>      <para>
1705        Here are a few problems that users have encountered when first using Thuban.
1706        </para>
1707        <para>
1708    
1709        <itemizedlist>
1710        <listitem>
1711        <para>After adding two or more layers nothing is drawn in the map window.
1712        </para>
1713        <para>
1714        This is probably because the layers have different projections. Projections
1715        must be set on all layers and on the map itself if the layers' projections
1716        are different.
1717        </para>
1718        </listitem>
1719    
1720        <listitem>
1721        <para>Thuban crashes on startup with the error
1722            <literal>NameError: global name 'False' is not defined</literal>.
1723        </para>
1724        <para>
1725        <varname>True</varname> and <varname>False</varname> were only introduced
1726        in Python 2.2.1. Thuban depends on at least Python 2.2.1.
1727        </para>
1728        </listitem>
1729    
1730        <listitem>
1731        <para>After compiling Thuban, Thuban crashes with an error similar to
1732            <literal>
1733            ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0
1734            </literal>
1735        </para>
1736        <para>
1737        Thuban depends on the wxWindows library. If Thuban is compiled with an
1738        incompatible version of the compiler than wxWindows was compiled with
1739        this error may occur. Try compiling with a different version of the
1740        compiler.
1741        </para>
1742        </listitem>
1743        </itemizedlist>
1744        </para>
1745        <para>
1746        If an error occurs Thuban will display a dialog indicating the error
1747        before closing. The text should be copied and reported to the
1748        <ulink url="http://thuban.intevation.org/bugtracker.html">
1749        Intevation bugtracker
1750        </ulink>.
1751        More information about the system is available from
1752        <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.
1753        This should also be included in the bug report.
1754        <figure>
1755        <title>Error Dialog</title>
1756        <mediaobject>
1757        <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>
1758        <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>
1759        </mediaobject>
1760        </figure>
1761      </para>      </para>
1762    
1763    </chapter>    </chapter>
1764    
1765    <appendix><title>Supported Data Sources</title>    <appendix><title>Supported Data Sources</title>
# Line 806  Line 1768 
1768      <variablelist>      <variablelist>
1769      <varlistentry>      <varlistentry>
1770      <term>Shapefile</term>      <term>Shapefile</term>
1771      <listitem><para></para></listitem>      <listitem>
1772            <para>
1773            The Shapefile format has become a standard format for saving
1774            geographic vector information. It supports polygons, lines, and
1775            points.
1776            
1777            <ulink url="http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf">
1778            Technical Specification.
1779            </ulink>  
1780            </para>
1781        </listitem>
1782        </varlistentry>
1783    
1784        <varlistentry>
1785        <term>dBase file</term>
1786        <listitem>
1787            <para>
1788            dBase files are used to store the attributes for each layer. This
1789            is closely associated with the Shapefile format. For detailed
1790            specifications on the correct format of a dBase file used with
1791            Thuban please see the Technical Specification for the Shapefile
1792            format above.
1793            </para>
1794        </listitem>
1795        </varlistentry>
1796    
1797        <varlistentry>
1798        <term>PostGIS</term>
1799        <listitem>
1800            <para>
1801            PostGIS adds support for geographic objects to the PostgreSQL
1802            object-relational database. Different layer types (as for Shapefiles)
1803            are supported. <ulink url="http://postgis.refractions.net">PostGIS
1804            Homepage</ulink>
1805            </para>
1806        </listitem>
1807      </varlistentry>      </varlistentry>
1808    
1809      <varlistentry>      <varlistentry>
1810      <term>DB2 file</term>      <term>Raster files</term>
1811      <listitem><para></para></listitem>      <listitem>
1812            <para>
1813            Binding the GDAL library Thuban supports numerous raster file formats,
1814            see <ulink url="http://www.remotesensing.org/gdal/formats_list.html">
1815            GDAL format list</ulink> for details.</para>
1816    
1817            <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
1818            format: Raster maps are provided as TIFF images, with an additional
1819            "world file" storing the geographic reference (usually with an
1820            extension ".tfw").
1821            </para>
1822        </listitem>
1823      </varlistentry>      </varlistentry>
1824    
1825      </variablelist>      </variablelist>
1826    </appendix>    </appendix>
1827    
1828      <appendix><title>Working with PostGIS</title>
1829      <para>
1830      This section focusses on the use of PostGIS in the Thuban framework. For
1831      installation and maintenance of spatial databases we refer to the  
1832      <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
1833      The Thuban PostGIS support requires the
1834      <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
1835      </para>
1836    
1837      <para>
1838            Working with PostGIS Databases is seperated into two steps:
1839            <itemizedlist>
1840            <listitem><para>Opening a Database Connection</para></listitem>
1841            <listitem><para>Loading a Data Layer</para></listitem>
1842            </itemizedlist>
1843      </para>
1844            <section><title>Opening a Database Connection</title>
1845            <para>
1846                    Before a data layer can be loaded from a PostGIS database a
1847                    connection with the database has to be established.
1848                    <menuchoice>
1849                    <guimenu>Session</guimenu>
1850                    <guimenuitem>Database Connections ...</guimenuitem>
1851                    </menuchoice> opens a dialog for database connection
1852                    management. In the dialog new connections can be added
1853                    and existing ones can be removed. Removing a database
1854                    connection is not possible if the map still displays a
1855                    layer provided by this database connection.
1856            </para>
1857        <figure>
1858        <title>Database Management Dialog</title>
1859        <mediaobject>
1860        <imageobject><imagedata fileref="../images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
1861        <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
1862        </mediaobject>
1863        </figure>
1864    
1865            <para>
1866                    To add a new database connection to the session a dialog is
1867                    opened to specify the relevant connection data. Enter all
1868                    data relevant for your connection. If the connection fails
1869                    the dialog remains open and provides some hints on the failure.
1870            </para>
1871            <figure>
1872            <title>Add Database Dialog</title>
1873            <mediaobject>
1874            <imageobject><imagedata fileref="../images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
1875            <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
1876            </mediaobject>
1877            </figure>
1878            
1879            <para>
1880            It is important to note that information on database connections are
1881            also stored with the session. Passwords are NOT stored. If you load a
1882            session with database connections you are asked to enter these
1883            passwords again where required.
1884            </para>
1885    
1886            </section>
1887    
1888            <section><title>Loading a Data Layer</title>
1889            <para>
1890            Data layers as part of a map are loaded with the
1891            <menuchoice>
1892            <guimenu>Map</guimenu>
1893            <guimenuitem>Add Database Layer ...</guimenuitem>
1894            </menuchoice> menu item. A dialog is raised displaying two choice
1895            lists. In the left list all connected databases are shown.
1896            Highlighting
1897            one of these and issuing a retrieval results in a list of available
1898            layer tables from that database. After selection of a
1899            layer the dialog is closed.
1900            </para>
1901            <figure>
1902            <title>Add Database Dialog</title>
1903            <mediaobject>
1904            <imageobject><imagedata fileref="../images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
1905            <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
1906            </mediaobject>
1907            </figure>
1908            
1909            </section>
1910    
1911      </appendix>
1912    
1913    <appendix><title>Supported Projections</title>    <appendix><title>Supported Projections</title>
1914      <para>      <para>
1915        The following types of projections are directly support by
1916        Thuban. The specific values for each are provided by the user
1917        to create custom projections. Thuban comes with predefined
1918        projections which are available through the Projections dialog.
1919        </para>
1920        <itemizedlist>
1921        <listitem>
1922            <para>Geographic</para>
1923            <itemizedlist>
1924            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1925            <listitem><para>
1926                    <literal>Source Data</literal>: either Degrees or Radians
1927                    </para></listitem>
1928            </itemizedlist>
1929        </listitem>
1930        <listitem>
1931            <para>Lambert Conic Conformal</para>
1932        <itemizedlist>
1933            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1934            <listitem><para><literal>Latitude of 1st standard parallel</literal></para></listitem>
1935            <listitem><para><literal>Latitude of 2nd standard parallel</literal></para></listitem>
1936            <listitem><para><literal>Central Meridian</literal></para></listitem>
1937            <listitem><para><literal>Latitude of Origin</literal></para></listitem>
1938            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
1939            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
1940        </itemizedlist>
1941        </listitem>
1942        <listitem>
1943            <para>Transverse Mercator</para>
1944        <itemizedlist>
1945            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1946            <listitem><para><literal>Latitude</literal>of origin</para></listitem>
1947            <listitem><para><literal>Longitude</literal>at central meridian</para></listitem>
1948            <listitem><para><literal>Scale Factor</literal>at central meridian</para></listitem>
1949            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
1950            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
1951        </itemizedlist>
1952        </listitem>
1953        <listitem>
1954            <para>Universal Transverse Mercator</para>
1955        <itemizedlist>
1956            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1957            <listitem><para><literal>Zone</literal>
1958                    (can be guessed appling the Propose button)</para></listitem>
1959            <listitem><para><literal>Southern Hemisphere</literal> flag</para></listitem>
1960        </itemizedlist>
1961        </listitem>
1962        </itemizedlist>
1963        
1964        <para>
1965        Thuban comes with a sample set of map projections for various
1966        European countries. Apart from the basic projection they differ
1967        especially in their parameterization:
1968        </para>
1969        <itemizedlist>
1970        <listitem><para>Belgium Datum 1972 (Lambert Conic Conformal)</para>
1971        </listitem>
1972    
1973        <listitem><para>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</para>
1974        </listitem>
1975    
1976        <listitem><para>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)
1977        </para>
1978        </listitem>
1979    
1980        <listitem><para>Reseau Geodesique Francaise
1981        (France, Lambert Conic Conformal)</para>
1982        </listitem>
1983    
1984        <listitem><para>UK National Grid (United Kingdom, Transverse Mercartor)
1985        </para>
1986        </listitem>
1987        </itemizedlist>
1988    
1989        <para>
1990        Thuban uses the comprehensive PROJ library for projections. PROJ provides
1991        more than the four commonly used projections described above. If needed
1992        Thuban can be easily extended to a new projection covered by PROJ.
1993      </para>      </para>
     <variablelist>  
     <varlistentry>  
     <term>Geographic</term>  
     <listitem><para>Geographic</para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Lambert Conic Conformal</term>  
     <listitem><para>Lambert Conic Conformal</para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Transverse Mercator</term>  
     <listitem><para>Transverse Mercator</para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Universal Transverse Mercator</term>  
     <listitem><para>Universal Transverse Mercator</para></listitem>  
     </varlistentry>  
     </variablelist>  
1994    </appendix>    </appendix>
1995    
1996  </book>  </book>
1997    
Legend:
Removed from v.1478  
changed lines
  Added in v.2734
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26