/[thuban]/branches/WIP-pyshapelib-bramz/Doc/manual/thuban-manual.xml
ViewVC logotype

Diff of /branches/WIP-pyshapelib-bramz/Doc/manual/thuban-manual.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1367 by bh, Thu Jul 3 16:25:35 2003 UTC revision 1689 by jan, Fri Aug 29 10:03:49 2003 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  <!-- $ Revision: $ -->      [<!ENTITY imgscale "70">]>
6    <!-- $Revision$ -->
7  <book>  <book>
8    <bookinfo>    <bookinfo>
9      <title>Thuban Manual</title>      <title>User's Manual for Thuban 1.0</title>
10      <author>          <authorgroup>
11        <firstname></firstname><surname></surname>        <author>
12      </author>          <firstname>Jonathan</firstname><surname>Coles</surname>
13          </author>
14          <author>
15            <firstname>Jan-Oliver</firstname><surname>Wagner</surname>
16          </author>
17          <author>
18            <firstname>Frank</firstname><surname>Koormann</surname>
19          </author>
20            </authorgroup>
21      <copyright>      <copyright>
22        <year>2003</year>        <year>2003</year>
23        <holder>Intevation GmbH</holder>        <holder>Intevation GmbH</holder>
24      </copyright>      </copyright>
25       <revhistory>
26    <!-- comment this first revision out when releasing a real version -->
27    <!--
28         <revision>
29            <revnumber>CVS version $Id$</revnumber>
30            <date></date>
31            <revremark>Under development.</revremark>
32         </revision>
33    -->
34         <revision>
35            <revnumber>1.0pre2</revnumber>
36            <date>29-Aug-2003</date>
37            <revremark>
38                            Corresponds to Thuban development release 0.8.1.
39                            New: chapter on extensions.
40                    </revremark>
41         </revision>
42         <revision>
43            <revnumber>1.0pre1</revnumber>
44            <date>08-Aug-2003</date>
45            <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
46         </revision>
47      </revhistory>
48    
49    </bookinfo>    </bookinfo>
50    
51    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
52      <para>      <para>
53        Thuban is an interactive geographic data viewer.
54        It has been developed because there was no simple interactive
55        viewer for geographic information available as Free Software. Thuban is
56        written in Python and C++ and uses the wxWindows library allowing it to
57        run on many different platforms, including GNU/Linux and Windows.
58        </para>
59        <para>
60        Geographic data viewers are a necessary tool as they allow one to
61            get a visual
62        impression of the positional relationship of the information that may not
63        be apparent from simple inspection of the data values themselves.
64        Thuban allows the user to create a session that displays
65        geographic data and then explore that data through navigation and
66        manipulation of how it is drawn. The results can then be saved or printed.
67        </para>
68        <para>
69        Thuban arranges a session in a hierarchy. A session contains a map which
70        consists of layers. Each layer represents one kind of data set. For
71        instance, there may be a layer for roads and another layer for buildings.
72        These layers can either be vector shapes or images.
73        </para>
74    
75            <section><title>Installation</title>
76            <para>
77            Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,
78            and Windows 2000. Thuban depends on the following packages. These
79            packages can also be found on the
80            <ulink url="http://thuban.intevation.org/download.html">
81            Thuban Download site
82            </ulink>.
83            <itemizedlist>
84                <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>
85                <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>
86                <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>
87                <listitem><para>proj 4.4.5 Projection Library (<literal>http://www.remotesensing.org/proj/</literal>)</para></listitem>
88                <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>
89                <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>
90                <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>
91                </itemizedlist>
92            </para>
93                    <para>
94                    Along with the source codes, the download page also offers
95                    full installation packages for Debian, Windows and RPM-based systems
96                    (Mandrake, RedHat, SuSE, etc).
97                    </para>
98            </section>
99    
100            <section><title>The Main Window</title>
101            <para>
102            <figure>
103            <title>The Main Window</title>
104            <mediaobject>
105            <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>
106            <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>
107            </mediaobject>
108            </figure>
109            </para>
110    
111            <para>
112            The map window shows the current state of the map and is where
113            the user can interact with the map using the tools.
114            </para>
115    
116            <para>
117            The legend on the left displays a list of the current layers and
118            any visible classification groups. In the example, each shape layer
119            has a default classification which specifies how the shapes in each
120            layer are drawn. Layers that are higher in the list appear
121            ``closer'' to the user. The legend can be closed by clicking on the
122            small X in the upper right-hand region of the legend.
123            To open it again, use
124            <menuchoice>
125            <guimenu>Map</guimenu>
126            <guimenuitem>Legend</guimenuitem>
127            </menuchoice>.
128            The legend is also dockable, which means that it can be detached
129            from the main window by clicking on the small button next to the
130            close button. It can be attached by clicking the same button
131            again.
132            </para>
133            <para>
134            The status bar displays different information depending on the
135            current context. If the user is selecting an item from the menu
136            then the status bar will display a short help message indicating
137            what each menu item is for. If the user has a tool selected then
138            the position of the cursor on the map is displayed.
139            </para>
140            <para>
141            The tool bar provides quick access to the commonly needed tools.
142            By hovering over each button the user can see a short messages
143            describing what the tool does. The tools provided are Zoom In, Zoom
144            Out, Pan, Full Extent, Full Layer Extent, Full Shape Extent, Identify,
145            and Label. Each of the tools will be explained in further detail later
146            in the manual.
147            </para>
148            </section>
149    
150      </chapter>
151    
152      <chapter><title>Session Management</title>
153    
154            <section><title>Starting a New Session</title>
155            <para>
156            A new session can be started from
157            <menuchoice>
158            <guimenu>File</guimenu>
159            <guimenuitem>New Session</guimenuitem>
160            </menuchoice>.
161            If a session is already loaded and has been modified without
162            being saved a prompt will ask if the current session should
163            be saved. A new session consists of an empty map with no
164            layers and no tables.
165            </para>
166            </section>
167    
168            <section><title>Opening a Session</title>
169            <para>
170            A session can be opened from
171            <menuchoice>
172            <guimenu>File</guimenu>
173            <guimenuitem>Open Session</guimenuitem>
174            </menuchoice>. A dialog box will open allowing the user to browse
175            for a Thuban Session file. Thuban session files end with
176            <varname>.thuban</varname>. Selecting a file a clicking
177            <guibutton>OK</guibutton> will load the session into Thuban.
178    
179            If a session is already loaded and has been modified without
180            being saved a prompt will ask if the current session should
181            be saved.
182            </para>
183            </section>
184    
185            <section><title>Saving a Session</title>
186            <para>
187            A session can be saved from
188            <menuchoice>
189            <guimenu>File</guimenu>
190            <guimenuitem>Save Session</guimenuitem>
191            </menuchoice>. A dialog box will open allowing the user to browse
192            the file system and select a place to save the session. Thuban
193            sessions should be saved under a name ending in
194            <varname>.thuban</varname>. If the file already exists the user
195            will be prompted to save under a different name or overwrite the
196            existing file.
197            </para>
198            </section>
199    
200            <section><title>The Session Info-Tree</title>
201            <para>
202            <figure>
203            <title>Session Info Tree</title>
204            <mediaobject>
205            <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>
206            <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>
207            </mediaobject>
208            </figure>
209            </para>
210            <para>
211            The session info-tree is primarily intended for developers working
212            with Thuban. It displays many of the internal values for the session,
213            map, and layers. It can be opened from
214            <menuchoice>
215            <guimenu>File</guimenu>
216            <guimenuitem>Session Tree</guimenuitem>
217            </menuchoice>.
218            </para>
219            </section>
220      </chapter>
221    
222      <chapter><title>Map Management</title>
223        <para>
224        The map consists of a number of layers where each layer represents a
225        different type of data set. By interacting with the map the user can
226        visually explore the data.
227        </para>
228        <para>
229        The map can have a name that will appear in the Thuban title bar.
230        The map name can be changed using
231        <menuchoice>
232        <guimenu>Map</guimenu>
233        <guimenuitem>Rename</guimenuitem>
234        </menuchoice>.
235        </para>
236        <para>
237        <inlinemediaobject>
238        <imageobject>
239        <imagedata fileref="../images/3_rename_map.png" format="PNG" scale="&imgscale;"/>
240        </imageobject>
241        <imageobject>
242        <imagedata fileref="./images/3_rename_map.eps" format="EPS" scale="&imgscale;"/>
243        </imageobject>
244        <textobject> <phrase>Rename Map</phrase> </textobject>
245        </inlinemediaobject>
246        </para>
247    
248            <section><title>Adding and Removing Layers</title>
249            <para>
250            There are two types of layers that can be added to a map: Shape layers
251            and image layers. Shape layers are stored in Shapefile format, a
252            widely used file format for storing geographic objects. These
253            files have the extension ``.shp''. Associated with
254            the shape file is a database file which stores attributes for
255            each shape in the Shape file. This file, in dBase format,
256            has the extension ``.dbf''. Both files must have the same base name.
257            For example, if there is a shape file named roads.shp there must
258            also be a file roads.dbf.
259            </para>
260            <para>
261            Shape layers can be added to the map with
262            <menuchoice>
263            <guimenu>Map</guimenu>
264            <guimenuitem>Add Layer</guimenuitem>
265            </menuchoice>.
266            Initially, only the ``.shp'' files are shown which is enough for the
267                    selection. However, if you switch to display all files and select one
268                    of the associated files (e.g. ``.dbf''), Thuban will recognize the base
269                    name and load the corresponding Shape file.
270            </para>
271                    <para>
272                    The file dialog for Shape files allows to select multiple files.
273                    Use the shift-button together with the left mouse button to extend
274                    the selection.
275            </para>
276    
277            <para>
278            Image layers can be added to the map with
279            <menuchoice>
280            <guimenu>Map</guimenu>
281            <guimenuitem>Add Image Layer</guimenuitem>
282            </menuchoice>.
283            It is important to select a valid image file that has geographic
284            data associated with it. The data can be embedded in the file itself,
285            or in another file. If geographic information cannot be found, Thuban
286            will report an error.
287            </para>
288            </section>
289    
290            <section><title>Navigation</title>
291            <para>
292            The map can be explored by using the navigation tools available on
293            the tool bar or from the
294            <menuchoice><guimenu>Map</guimenu></menuchoice> menu.
295            </para>
296            <itemizedlist>
297            <listitem>
298            <para>
299            The ZoomIn tool
300            <inlinemediaobject>
301            <imageobject>
302            <imagedata fileref="../images/3_2_zoomin.png" format="PNG" scale="&imgscale;"/>
303            </imageobject>
304            <imageobject>
305            <imagedata fileref="./images/3_2_zoomin.eps" format="EPS" scale="&imgscale;"/>
306            </imageobject>
307            <textobject> <phrase>ZoomIn Tool</phrase> </textobject>
308            </inlinemediaobject>
309            enlarges a region of the map. Clicking once on the map
310            will double the magnification and center the map on the point that
311            was clicked. Clicking and dragging selects a region that will be
312            enlarged to fit the window.
313            </para>
314            </listitem>
315            <listitem>
316            <para>
317            The ZoomOut tool
318            <inlinemediaobject>
319            <imageobject>
320            <imagedata fileref="../images/3_2_zoomout.png" format="PNG" scale="&imgscale;"/>
321            </imageobject>
322            <imageobject>
323            <imagedata fileref="./images/3_2_zoomout.eps" format="EPS" scale="&imgscale;"/>
324            </imageobject>
325            <textobject> <phrase>ZoomOut Tool</phrase> </textobject>
326            </inlinemediaobject>
327            shrinks the map so that a larger region is visible. A single click
328            reduces the magnification by a factor of two. Clicking and dragging
329            selects a box such that the current contents of the window will be
330            scaled to fit into that box.
331            </para>
332            </listitem>
333            <listitem>
334            <para>
335            The Pan tool
336            <inlinemediaobject>
337            <imageobject>
338            <imagedata fileref="../images/3_2_pan.png" format="PNG" scale="&imgscale;"/>
339            </imageobject>
340            <imageobject>
341            <imagedata fileref="./images/3_2_pan.eps" format="EPS" scale="&imgscale;"/>
342            </imageobject>
343            <textobject> <phrase>Pan Tool</phrase> </textobject>
344            </inlinemediaobject>
345            allows the user to move the map around by clicking and dragging.
346            </para>
347            </listitem>
348            <listitem>
349            <para>
350            The Full Extent tool
351            <inlinemediaobject>
352            <imageobject>
353            <imagedata fileref="../images/3_2_fullextent.png" format="PNG" scale="&imgscale;"/>
354            </imageobject>
355            <imageobject>
356            <imagedata fileref="./images/3_2_fullextent.eps" format="EPS" scale="&imgscale;"/>
357            </imageobject>
358            <textobject> <phrase>Full Extent Tool</phrase> </textobject>
359            </inlinemediaobject>
360            rescales the viewable region so that the entire map is visible.
361            </para>
362            </listitem>
363            <listitem>
364            <para>
365            The Full Layer Extent tool
366            <inlinemediaobject>
367            <imageobject>
368            <imagedata fileref="../images/3_2_fulllayerextent.png" format="PNG" scale="&imgscale;"/>
369            </imageobject>
370            <imageobject>
371            <imagedata fileref="./images/3_2_fulllayerextent.eps" format="EPS" scale="&imgscale;"/>
372            </imageobject>
373            <textobject> <phrase>Full Layer Extent Tool</phrase> </textobject>
374            </inlinemediaobject>
375            rescales the viewable region so that the currently selected
376            layer fits within the window. If no layer is selected this button
377            will be disabled.
378            </para>
379            </listitem>
380            <listitem>
381            <para>
382            The Full Shape Extent tool
383            <inlinemediaobject>
384            <imageobject>
385            <imagedata fileref="../images/3_2_fullshapeextent.png" format="PNG" scale="&imgscale;"/>
386            </imageobject>
387            <imageobject>
388            <imagedata fileref="./images/3_2_fullshapeextent.eps" format="EPS" scale="&imgscale;"/>
389            </imageobject>
390            <textobject> <phrase>Full Shape Extent Tool</phrase> </textobject>
391            </inlinemediaobject>
392            rescales the viewable region so that the currently selected
393            shape fits within the window. If the shape is a point, it is
394            centered and the map is zoomed all the way in. If no shape is
395            selected this button will be disabled. This feature is especially
396            helpful when identifying an object related to a selected record
397            in a tableview (see below).
398    
399            </para>
400            </listitem>
401            </itemizedlist>
402            </section>
403    
404            <section><title>Object Identification</title>
405            <para>
406            Objects on the map can be identified using the Identify tool
407            <inlinemediaobject>
408            <imageobject>
409            <imagedata fileref="../images/3_3_identify.png" format="PNG" scale="&imgscale;"/>
410            </imageobject>
411            <imageobject>
412            <imagedata fileref="./images/3_3_identify.eps" format="EPS" scale="&imgscale;"/>
413            </imageobject>
414            <textobject> <phrase>Identify Tool</phrase> </textobject>
415            </inlinemediaobject>.
416            Clicking on an object selects that object and opens a dialog which
417            shows all the table attributes for that object. Any current selection
418            is lost. Objects on the map are typically shapes and this document
419            will often refer to objects as shapes.
420            </para>
421            </section>
422    
423            <section><title>Object Labeling</title>
424            <para>
425            Objects can be labeled using the Label tool
426            <inlinemediaobject>
427            <imageobject>
428            <imagedata fileref="../images/3_3_label.png" format="PNG" scale="&imgscale;"/>
429            </imageobject>
430            <imageobject>
431            <imagedata fileref="./images/3_3_label.eps" format="EPS" scale="&imgscale;"/>
432            </imageobject>
433            <textobject> <phrase>Label Tool</phrase> </textobject>
434            </inlinemediaobject>.
435            Clicking on an object selects that object and opens a dialog which
436            displays the table attributes for that object. An attribute can
437            be selected to be the label on the map. The label will be placed
438            at the center of the shape. Clicking on an object that already has
439            a label will remove the label.
440            </para>
441            </section>
442    
443            <section><title>The Legend</title>
444            <para>
445            <inlinemediaobject>
446            <imageobject>
447            <imagedata fileref="../images/3_5_legend.png" format="PNG" scale="&imgscale;"/>
448            </imageobject>
449            <imageobject>
450            <imagedata fileref="./images/3_5_legend.eps" format="EPS" scale="&imgscale;"/>
451            </imageobject>
452            <textobject> <phrase>Legend</phrase> </textobject>
453            </inlinemediaobject>
454            </para>
455            <para>
456            The Legend provides an overview of the layers in the map. Layers
457            that appear higher in the legend will appear ``closer'' to the user.
458            If a layer supports classification (currently, only shape layers
459            have this feature) then the classification groups will be shown
460            below each layer. The properties for each group are also displayed
461            with a small graphic. Polygon layers appear as rectangles, lines
462            appear as curved lines, and points appear as circles.
463            </para>
464            <para>
465            Along the top of the legend is a toolbar which allows quick access
466            to some of the layer manipulation options under
467            <menuchoice><guimenu>Map</guimenu></menuchoice>.
468            </para>
469    
470            <itemizedlist>
471            <listitem>
472            <para>
473            The Move Layer to Top tool
474            <inlinemediaobject>
475            <imageobject>
476            <imagedata fileref="../images/3_5_totop.png" format="PNG" scale="&imgscale;"/>
477            </imageobject>
478            <imageobject>
479            <imagedata fileref="./images/3_5_totop.eps" format="EPS" scale="&imgscale;"/>
480            </imageobject>
481            <textobject> <phrase>Move Layer to Top</phrase> </textobject>
482            </inlinemediaobject> raises the selected layer to the top of the map.
483            </para>
484            </listitem>
485            <listitem>
486    
487            <para>
488            The Move Layer Up tool
489            <inlinemediaobject>
490            <imageobject>
491            <imagedata fileref="../images/3_5_moveup.png" format="PNG" scale="&imgscale;"/>
492            </imageobject>
493            <imageobject>
494            <imagedata fileref="./images/3_5_moveup.eps" format="EPS" scale="&imgscale;"/>
495            </imageobject>
496            <textobject> <phrase>Move Layer Up</phrase> </textobject>
497            </inlinemediaobject> raises the selected layer one level.
498            </para>
499            </listitem>
500            <listitem>
501    
502            <para>
503            The Move Layer Down tool
504            <inlinemediaobject>
505            <imageobject>
506            <imagedata fileref="../images/3_5_movedown.png" format="PNG" scale="&imgscale;"/>
507            </imageobject>
508            <imageobject>
509            <imagedata fileref="./images/3_5_movedown.eps" format="EPS" scale="&imgscale;"/>
510            </imageobject>
511            <textobject> <phrase>Move Layer Down</phrase> </textobject>
512            </inlinemediaobject> lowers the selected layer one level.
513            </para>
514    
515            </listitem>
516            <listitem>
517            <para>
518            The Move Layer to Bottom tool
519            <inlinemediaobject>
520            <imageobject>
521            <imagedata fileref="../images/3_5_tobottom.png" format="PNG" scale="&imgscale;"/>
522            </imageobject>
523            <imageobject>
524            <imagedata fileref="./images/3_5_tobottom.eps" format="EPS" scale="&imgscale;"/>
525            </imageobject>
526            <textobject> <phrase>Move Layer to Bottom</phrase> </textobject>
527            </inlinemediaobject> lowers the selected layer to the bottom of the map.
528            </para>
529    
530            </listitem>
531            <listitem>
532            <para>
533            The Visible tool
534            <inlinemediaobject>
535            <imageobject>
536            <imagedata fileref="../images/3_5_visible.png" format="PNG" scale="&imgscale;"/>
537            </imageobject>
538            <imageobject>
539            <imagedata fileref="./images/3_5_visible.eps" format="EPS" scale="&imgscale;"/>
540            </imageobject>
541            <textobject> <phrase>Visible</phrase> </textobject>
542            </inlinemediaobject> shows the selected layer in the map if it was
543            hidden.
544            </para>
545    
546            </listitem>
547            <listitem>
548            <para>
549            The Invisible tool
550            <inlinemediaobject>
551            <imageobject>
552            <imagedata fileref="../images/3_5_invisible.png" format="PNG" scale="&imgscale;"/>
553            </imageobject>
554            <imageobject>
555            <imagedata fileref="./images/3_5_invisible.eps" format="EPS" scale="&imgscale;"/>
556            </imageobject>
557            <textobject> <phrase>Invisible</phrase> </textobject>
558            </inlinemediaobject> hides the selected layer in the map.
559            </para>
560    
561            </listitem>
562            <listitem>
563            <para>
564            The Properties tool
565            <inlinemediaobject>
566            <imageobject>
567            <imagedata fileref="../images/3_5_props.png" format="PNG" scale="&imgscale;"/>
568            </imageobject>
569            <imageobject>
570            <imagedata fileref="./images/3_5_props.eps" format="EPS" scale="&imgscale;"/>
571            </imageobject>
572            <textobject> <phrase>Properties</phrase> </textobject>
573            </inlinemediaobject> opens the layer's properties dialog box.
574            Double-clicking on a layer or a group of a layer will open the
575            properties dialog for that layer.
576            </para>
577            </listitem>
578            </itemizedlist>
579            <para>
580            Along the bottom of the legend is the scalebar. The scalebar
581            will be available if there are any layers and the  map has a
582            projection set.
583            </para>
584            </section>
585    
586            <section><title>Exporting</title>
587            <para>
588            Under Windows, maps can be exported in Enhanced Metafile format
589            (<varname>.wmf</varname>)
590            from
591            <menuchoice>
592            <guimenu>Map</guimenu>
593            <guimenuitem>Export</guimenuitem>
594            </menuchoice> for use in reports, presentations, or further
595            modification. The current map view, legend, and, if available,
596            scalebar are exported. Under other platforms this option is not
597            available. Clicking this menu item open a file selection dialog
598            that lets the user select a location to export the map.
599            </para>
600            </section>
601    
602            <section><title>Printing</title>
603            <para>
604            The map can be printed using
605            <menuchoice>
606            <guimenu>Map</guimenu>
607            <guimenuitem>Print</guimenuitem>
608            </menuchoice>. The current map view, legend, and, if available,
609            scalebar are printed. A standard printing dialog will open allowing
610            the user to configure the printer. This dialog will differ depending
611            on which platform Thuban is running.
612            </para>
613            </section>
614    
615      </chapter>
616    
617      <chapter><title>Layer Management</title>
618        <para>
619        </para>
620    
621            <section><title>Types of Layers</title>
622            <para>
623            There are two types of layers supported by Thuban: shape layers and
624            image layers. Shape layers consist of vector based shapes with
625            geo-referenced coordinates. There are three types of supported
626            shapes: polygons, lines (arc), and points. Image layers can be any image
627            file format supported by the Geo-spatial Data Abstraction Library
628            (GDAL). The images must have geographic
629            coordinate data either embedded within the file or in a separate
630            file that is in the same directory as the image file. GeoTIFF files
631            work very well with Thuban and were designed specifically to be image
632            layers in GIS programs.
633            </para>
634            <para>
635            All actions in the
636            <menuchoice>
637            <guimenu>Layer</guimenu>
638            </menuchoice> menu act on the currently selected layer in the legend.
639            </para>
640            </section>
641    
642            <section><title>Properties</title>
643            <para>
644            To view the properties for a layer it must first be selected in the
645            legend. The menu option
646            <menuchoice>
647            <guimenu>Layer</guimenu>
648            <guimenuitem>Properties</guimenuitem>
649            </menuchoice> opens a dialog that displays a layer's properties.
650            All layers have a title which can be modified in the text field
651            provided. The type of layer is also shows. If the type is a type
652            of shape (polygon, arc, point) the classification table will be
653            shown. Image layers have no other properties other than title
654            and type.
655            </para>
656            <para>
657            <figure>
658            <title>Properties Window</title>
659            <mediaobject>
660            <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
661            <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
662            </mediaobject>
663            </figure>
664            </para>
665            <para>
666            <figure>
667            <title>Properties Window</title>
668            <mediaobject>
669            <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
670            <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
671            </mediaobject>
672            </figure>
673            </para>
674            </section>
675    
676            <section><title>Visibility</title>
677            <para>
678            Sometimes it is not desirable to view all layers at the same time.
679            Some layers may take a long time to draw and so while navigating
680            around the map the user may not want to wait for the map to redraw
681            all the layers each time the map is changed. Each layer can be
682            independently turned on or off using the
683            <menuchoice>
684            <guimenu>Layer</guimenu>
685            <guimenuitem>Show</guimenuitem>
686            </menuchoice>
687            or
688            <menuchoice>
689            <guimenu>Layer</guimenu>
690            <guimenuitem>Hide</guimenuitem>
691            </menuchoice> options respectively.
692            </para>
693            </section>
694    
695            <section><title>Duplication</title>
696            <para>
697            Layers and all their properties, including classifications, can
698            be duplicated using
699            <menuchoice>
700            <guimenu>Layer</guimenu>
701            <guimenuitem>Duplicate</guimenuitem>
702            </menuchoice>. Duplicating a layer is useful if the user wishes
703            to model a layer in several different ways. Even though the layers
704            overlap, by carefully selecting the shape properties it is possible
705            to display several pieces of information at once. For example, one
706            copy of a roads layer may be classified on a length property and
707            another copy may be classified on a type property. If the length
708            property was expressed with color and the type property expressed
709            with line thickness then it would be possible to view both
710            classifications by placing the type property copy over the
711            length property copy.
712            </para>
713            </section>
714    
715      </chapter>
716    
717      <chapter><title>Layer Classifications</title>
718        <para>
719        A layer classification is a way of assigning drawing properties to
720        groups of shapes based on attributes stored in the layer's table.
721        Only layer's with shapes can have a classification; image layers
722        cannot be classified.
723        </para>
724        <para>
725        A classification consists of a number of groups, each group
726        having a value or range of values to match against, and symbol
727        properties which control how a shape is drawn on the map. The user
728        selects which field in the table is used by the classification and
729        when the map is drawn the value for that field for each shape is
730        compared with each group's value. The properties of the first group
731        to match are used to draw the shape. This allows the user to get a
732        visual impression of not only how the data is laid out but also what
733        kind of data lies where.
734      </para>      </para>
735        <para>
736        A layer always has a classification. When a new layer is added to the
737        map, a default classification is created with the DEFAULT group. This
738        group cannot be removed but can be hidden (see below). Every shape in the
739        layer, regardless of its attributes, will match this group if no other
740        group matches.
741        </para>
742    
743            <section><title>Editing Classifications</title>
744            <para>
745            A layer's classification can be modified under the properties dialog
746            (<menuchoice>
747            <guimenu>Layer</guimenu>
748            <guimenuitem>Properties</guimenuitem>
749            </menuchoice>). The layer's classification field can be set to None,
750            which simply assigns a DEFAULT group to the classification. No new
751            groups can be added to the classification if the field is None.
752            The user must first select a field to classify on. New groups can
753            be added to the classification with the <guibutton>Add</guibutton>
754            button.
755            </para>
756            <para>
757            To apply the changes to the map the user can click
758            either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
759            <guibutton>Try</guibutton> will not close the dialog box, allowing
760            the user to see how the classification changes the map.
761            <guibutton>Revert</guibutton> will undo the last classification applied
762            to the map. <guibutton>OK</guibutton> will commit the changes and
763            close the dialog. The user will be unable to undo the changes.
764            <guibutton>Close</guibutton> simply closes the dialog box. If any
765            changes have not been applied with <guibutton>Try</guibutton> the
766            changes will not be applied to the map.
767            </para>
768            <para>
769            <figure>
770            <title>Properties Window</title>
771            <mediaobject>
772            <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>
773            <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>
774            </mediaobject>
775            </figure>
776            </para>
777            <para>
778            The order of the groups in the classification is significant
779            except for the DEFAULT group, which remains at the top. When shapes
780            are matched against groups the matching begins at the first group
781            after the DEFAULT group so that groups higher in the list will
782            be checked first. Matching for a
783            given shape will stop at the first group that matches. The user can
784            use <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton>
785            to change the order of the groups. The DEFAULT group will always
786            match a shape that hasn't matched another group.
787            </para>
788                <section><title>Visible</title>
789                <para>
790                The Visible column has check-boxes that determine whether a
791                classification group will be displayed in the legend. This is
792                useful if the user knows that the groups completely cover
793                the data set and don't want the DEFAULT group to be displayed
794                in the legend and on a printout.
795                </para>
796            </section>
797                <section><title>Symbols</title>
798                <para>
799                Each type of shape has its own type of symbol. Thuban supports three
800                types of shapes: polygons, lines, and points. Polygons and points
801                have outline and fill color, while lines have only line color. Each
802                group has associated symbol properties. To edit the symbol
803                properties for a group the user can double click on the Symbol
804                column or select a group and click the
805                <guibutton>Edit Symbol</guibutton> button.
806                </para>
807                </section>
808            <section><title>Value</title>
809                <para>
810                The Value column of the classification table is the value that will
811                be matched when the map is being drawn. The type of data that can
812                entered into this field depends on the type of data of the
813                classification field.
814                </para>
815                <para>
816                If the field is of type Text, anything entered
817                into the field is valid. The text will be compared literally to the
818                value of the shape attribute, including case sensitivity.
819                If the type is Integer, then any valid integer may be entered. In
820                addition, with special syntax, a range of values can be entered.
821                A range from <varname>start</varname> to <varname>end</varname>
822                inclusive is specified like this: <literal>[start;end]</literal>.
823                The exclusive range is specified like this:
824                <literal>]start;end[</literal>. Ranges can include infinity like
825                this: <literal>[-oo;oo]</literal>. Field types can also be of type
826                Decimal. They represent any rational number and can be used in
827                ranges as well.
828                </para>
829                </section>
830                <section><title>Label</title>
831                <para>
832                By default, the text that is displayed for a group in the legend
833                is the value for that group. The label can substitute a more
834                descriptive term in the legend.
835                </para>
836            </section>
837            </section>
838    
839            <section><title>Generating Classes</title>
840            <para>
841            <figure>
842            <title>Generate Class</title>
843            <mediaobject>
844            <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>
845            <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>
846            </mediaobject>
847            </figure>
848            </para>
849            <para>
850            Creating a classification by hand can be tedious.
851            Thuban, therefore, provides a means of generating an entire
852            classification at once while still giving the user control over
853            how it appears. Clicking <guibutton>Generate Class</guibutton>
854            opens the <varname>Generate Classification</varname> dialog.
855            Under the <varname>Generate</varname> pull down there are at most
856            three different ways to generate classifications:
857            Unique Values, Uniform Distribution, and Quantiles. Some options
858            may not be available if the data type for the field does not
859            support them. For instance, <varname>Uniform Distribution</varname>
860            doesn't make sense for a Text field.
861            </para>
862            <para>
863            For every way of generating a classification, a color scheme must
864            be selected. Thuban provides several different color schemes that
865            affect how the group properties change over the classification.
866            It may be desirable that only certain properties change over the
867            classification. If the shape type is a polygon or a point then
868            the <guibutton>Fix Border Color</guibutton> option will be available.
869            This allows the user to select a border color for all classification
870            groups.
871            It is also possible to create a custom color scheme. Selecting
872            this option will display two symbols: the one of the left has the
873            properties of the first group and the one on the right has the
874            properties of the last group. Thuban will interpolate between these
875            two properties to generate the other groups.
876            <figure>
877            <title>Custom Color Scheme</title>
878            <mediaobject>
879            <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>
880            <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>
881            </mediaobject>
882            </figure>
883            </para>
884            <para>
885            The Unique Values option lets the user select specific values that
886            appear in the table. Clicking <guibutton>Retrieve From Table</guibutton>
887            searches the table for all unique values and displays them in the
888            list on the left. Items can be selected and moved to the list on the
889            right. Each list can be sorted or reversed for easier searching.
890            The classification that is generated will be in the same order as
891            the list on the right.
892            <figure>
893            <title>Unique Values</title>
894            <mediaobject>
895            <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>
896            <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>
897            </mediaobject>
898            </figure>
899            </para>
900            <para>
901            The Uniform Distribution option creates a user specified number of
902            groups of ranges such that each range covers equal intervals. The
903            minimum and maximum values can automatically be retrieved from the
904            table by clicking <guibutton>Retrieve From Table</guibutton>. The
905            stepping is how large each interval is. Adjusting this value will
906            automatically recalculate how many groups is appropriate.
907            <figure>
908            <title>Uniform Distribution</title>
909            <mediaobject>
910            <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>
911            <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>
912            </mediaobject>
913            </figure>
914            </para>
915            <para>
916            The Quantiles option generates ranges based on the number of items
917            in the table. For example, by specifying five groups Thuban will
918            generate five groups with appropriate ranges such that 20% of the table
919            data is in each group. If it is impossible to generate exact
920            groupings, Thuban will issue a warning but allow the user to continue.
921            <figure>
922            <title>Quantiles</title>
923            <mediaobject>
924            <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>
925            <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>
926            </mediaobject>
927            </figure>
928            </para>
929            </section>
930      </chapter>
931    
932      <chapter><title>Projection Management</title>
933        <para>
934        Projections control how the geographic data is displayed on the screen.
935        If multiple layers are loaded into Thuban where the geographic data
936        is in a different projection system, then the user must specify a
937        projection for each layer. The user must also tell Thuban which
938        projection the map is in. This can be the same as the layers or a different
939        projection in which case the layers are reprojected into that space.
940        The map projection can be set using
941        <menuchoice>
942        <guimenu>Map</guimenu>
943        <guimenuitem>Projection</guimenuitem>
944        </menuchoice> and the layer projection can be set using
945        <menuchoice>
946        <guimenu>Layer</guimenu>
947        <guimenuitem>Projection</guimenuitem>
948        </menuchoice>.
949        <figure>
950        <title>Projection Window</title>
951        <mediaobject>
952        <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>
953        <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>
954        </mediaobject>
955        </figure>
956        </para>
957        <para>
958        Thuban is distributed with a sample collection of projections. The
959        user can create new projections and make them available to all
960        future Thuban sessions. They may also be exported and imported so
961        that custom projections can be distributed.
962        </para>
963            <section><title>Selecting a Projection</title>
964            <para>
965            The available projections are listed on the left. If the layer
966            or map already has a projection it will initially be highlighted
967            and will end with <varname>(current)</varname>. Selecting
968            <varname>&lt;None&gt;</varname> will cause Thuban to use the data as
969            it appears in the source file and will not use a projection.
970            </para>
971        </section>
972            <section><title>Editing a Projection</title>
973            <para>
974            Whenever a projection is selected from the list its properties
975            are displayed on the right. These properties can be changed
976            and the changes saved to the selected projection using
977            <guibutton>Update</guibutton>. Only a projection that comes
978            from a file can be updated, so if the current layer's projection
979            is selected, <guibutton>Update</guibutton> will be disabled.
980            <guibutton>Add to List</guibutton> adds the projection to the
981            list of available projections as a new entry, and thus makes it
982            available to future Thuban sessions. Clicking <guibutton>New</guibutton>
983            will create an entirely new, empty projection. The
984            <guibutton>Remove</guibutton> button will permanently remove a
985            projection from the list of available projections.
986            </para>
987            <para>
988            To apply the selected projection to the map the user can click
989            either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
990            <guibutton>Try</guibutton> will not close the dialog box, allowing
991            the user to see how the projeciton changes the map.
992            <guibutton>Revert</guibutton> will undo the last projection applied
993            to the map. <guibutton>OK</guibutton> will commit the changes and
994            close the dialog. The user will be unable to undo the changes.
995            <guibutton>Close</guibutton> simply closes the dialog box. If no
996            selection has been applied with <guibutton>Try</guibutton> the
997            selection will not be applied to the map.
998            </para>
999        </section>
1000            <section><title>Importing/Exporting Projections</title>
1001            <para>
1002            The projections that appear in the list of available projections
1003            can be exported to another file that the user chooses. By selecting
1004            one or more projections and clicking <guibutton>Export</guibutton>
1005            the user will be able to select a file in which to store those
1006            projections.
1007            The file can then be distributed to other Thuban users. To import
1008            a projection file the user can click <guibutton>Import</guibutton>.
1009            The imported projections are added to the list and are then available
1010            to the current session and any future Thuban sessions.
1011            </para>
1012        </section>
1013    </chapter>    </chapter>
1014    
1015      <chapter><title>Table Management</title>
1016        <para>
1017        Thuban distinguishes two different types of tables: Attribute tables
1018        (which belong to a layer) and normal data tables. Both provide
1019            the same general functionality with the difference that actions on an
1020        attribute table might also effect the map display.
1021        </para>
1022    
1023        <section><title>Table View</title>
1024            <para>
1025            <figure>
1026            <title>Table View</title>
1027            <mediaobject>
1028            <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>
1029            <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>
1030            </mediaobject>
1031            </figure>
1032            </para>
1033            <para>
1034            Thuban provides a standard dialog to display table contents, the
1035            Table View. The view has five sections: The title, selections,
1036            the table grid, export functions, and the status bar.
1037            </para>
1038            <para>
1039            The title bar identifies the table with its name.
1040            </para>
1041            <para>
1042            The selections box let the user perform simple analysis on the data
1043            based on comparisons: The first choice must be a field identifier of
1044            the table, the second choice determines the type of comparison. The
1045            third choice can be either a specific value (interpreted as numerical
1046            or string depending on the type of the first field) or a second field
1047            identifier. Thus you can perform analysis like selecting all
1048            records where <literal>population > 10000</literal> or
1049            <literal>cars_per_inhabitant < bikes_per_inhabitant</literal>
1050            (note that the field names are only explanatory, the dBase files
1051            allow only 11 character field names).
1052          
1053            Selections can be combined either by applying a selection only on
1054            a previously selected set of records or by adding the results of a
1055            selection to a previous set. The default is that a selection replaces
1056            earlier results.
1057            </para>
1058            <para>
1059            The table grid shows the contents of the table (one record per row),
1060            with highlighted selection results. Columns and rows can be resized.
1061            </para>
1062            <para>
1063            The contents of a table can be exported into a file, either dBase
1064            format (DBF) or comma separated values (CSV). The
1065            <guibutton>Export</guibutton> button
1066            raises a file dialog to specify a path and file name, the export type
1067            is determined by the file extension (either .dbf or .csv).
1068    
1069            The <guibutton>Export Selection</guibutton> button works similarly
1070            but exports only the selected records.
1071    
1072            The <guibutton>Close</guibutton> button closes the table view window.
1073            This is different from the menu item
1074            <menuchoice>
1075            <guimenu>Table</guimenu>
1076            <guimenuitem>Close</guimenuitem>
1077            </menuchoice> which unloads the table from Thuban.
1078            </para>
1079            <para>
1080            The status bar displays some statistics about the table and optional
1081            selection results.
1082            </para>
1083        </section>
1084    
1085        <section><title>General Functionality (Menu Table)</title>
1086            <para>
1087            The general functions affect all tables open in Thuban. Attribute
1088            tables are considered here as normal data tables (with the exception
1089            that they cannot be closed).
1090            </para>
1091            <section><title>Open</title>
1092                <para>
1093                The
1094                <menuchoice>
1095                <guimenu>Table</guimenu>
1096                <guimenuitem>Open</guimenuitem>
1097                </menuchoice>
1098                item raises a file dialog to let you select a
1099                dBase file from the file system to be loaded into Thuban read-only.
1100                On <guibutton>OK</guibutton> the selected file is loaded and a
1101                table view is opened.
1102                </para>
1103            </section>
1104    
1105            <section><title>Close</title>
1106                <para>
1107                The
1108                <menuchoice>
1109                <guimenu>Table</guimenu>
1110                <guimenuitem>Close</guimenuitem>
1111                </menuchoice>
1112                item raises a dialog listing the currently open
1113                data tables
1114                (loaded via
1115                <menuchoice>
1116                <guimenu>Table</guimenu>
1117                <guimenuitem>Open</guimenuitem>
1118                </menuchoice>). Selected tables are dereferenced on confirmation.
1119                Since tables are opened read-only the contents of the tables are
1120                not affected.
1121    
1122                Any open views of the tables are closed as well.
1123    
1124                Tables used in a join cannot be closed.
1125                </para>
1126            </section>
1127    
1128            <section><title>Rename</title>
1129                <para>
1130                <menuchoice>
1131                <guimenu>Table</guimenu>
1132                <guimenuitem>Rename</guimenuitem>
1133                </menuchoice> changes the table title.
1134                </para>
1135            </section>
1136    
1137            <section><title>Show</title>
1138                <para>
1139                The
1140                <menuchoice>
1141                <guimenu>Table</guimenu>
1142                <guimenuitem>Show</guimenuitem>
1143                </menuchoice>
1144                item raises a list of available tables (explicitly
1145                loaded, attribute tables, results of a join). Selected tables are
1146                show in tables views on <guibutton>OK</guibutton>.
1147                </para>
1148            </section>
1149    
1150            <section><title>Join</title>
1151                <para>
1152                <figure>
1153                <title>Join Tables</title>
1154                <mediaobject>
1155                <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>
1156                <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>
1157                </mediaobject>
1158                </figure>
1159                </para>
1160                <para>
1161                The
1162                <menuchoice>
1163                <guimenu>Table</guimenu>
1164                <guimenuitem>Join</guimenuitem>
1165                </menuchoice>
1166                item raises a dialog to specify the two tables to be
1167                joined. The join results in a new table named 'Join of "left table"
1168                and "right table"'.
1169    
1170                The dialog lets you select the two tables to be joined and the two
1171                fields the join has to be performed on. By default, the new
1172                table contains only those records which are matched by the join.
1173    
1174                If you want to preserve the records of the left table you can
1175                perform an outer join. The fields from the right table for records
1176                not matched by the join are filled with <varname>None</varname> in
1177                this case.
1178                </para>
1179            </section>
1180    
1181        </section>
1182        <section><title>Attribute Tables</title>
1183            <para>
1184                To clearly separate between both types of tables (data and
1185            attribute), Thuban provides functionality regarding the attribute
1186            tables under the <menuchoice><guimenu>Layer</guimenu></menuchoice> menu.
1187            </para>
1188    
1189            <section><title>Show Table</title>
1190                <para>
1191                <menuchoice>
1192                <guimenu>Layer</guimenu>
1193                <guimenuitem>Show Table</guimenuitem>
1194                </menuchoice>
1195                opens the attribute table of the currently active layer in a table
1196                view.
1197    
1198                In addition to the functionality described above selections
1199                affect also the map display: objects related to selected records
1200                are highlighted.
1201                </para>
1202            </section>
1203    
1204            <section><title>Join Table</title>
1205                <para>
1206                Unlike the join described above, the join does not result in a
1207                new table. The attribute table of the currently active layer is the
1208                left table and other tables are joined to this table. The results of
1209                the join are available for classification.
1210    
1211                As a consequence, the join cannot result in fewer
1212                records than the source attribute table. The user is warned if the
1213                right table does not fulfill this constraint. An outer join must be
1214                used in such cases.
1215                </para>
1216            </section>
1217    
1218            <section><title>Unjoin Table</title>
1219                <para>
1220                As said above, a normal table cannot be closed while it is still
1221                used in a join. While the joined table resulting from a join of
1222                normal tables can be simply closed (and thereby dereferencing
1223                the source tables), this is not possible for attribute tables.
1224    
1225                Hence joins on attribute tables must be solved explicitly. This is
1226                what the
1227                <menuchoice>
1228                <guimenu>Layer</guimenu>
1229                <guimenuitem>Unjoin Table</guimenuitem>
1230                </menuchoice>
1231                item is used for: The last join for the currently
1232                active layer is solved.
1233                </para>
1234            </section>
1235        </section>
1236      </chapter>
1237    
1238      <chapter><title>Extensions</title>
1239            <para>
1240            Thuban is designed to be extensible. The term Extension is used as a
1241            general term for anything that extends Thuban.
1242            This chapter introduces into some oppportunities how to add and
1243            handle extra functionality developed by your own or third parties.
1244            </para>
1245    
1246            <section><title>Add personal extensions via thubanstart.py</title>
1247                    <para>
1248                    After Thuban has been started for the first time, a directory
1249                    .thuban is created within your home directory.
1250                    There you can add a file thubanstart.py  which will be imported
1251                    by Thuban at start-up. It is recommended to add only import-statements
1252                    to this file to keep the actual code of extensions separate.
1253                    </para>
1254                    <para>
1255                    The modules to import must either be found though the environment
1256                    variable PYTHONPATH or directly be placed into the .thuban-directory.
1257                    </para>
1258                    <para>
1259                    As an example, copy the file examples/simple_extensions/hello_world.py
1260                    of the Thuban source code into the .thuban-directory of your home
1261                    directory. Now add add the statement import hello_world to the
1262                    file thubanstart.py and run Thuban. You will notice an additional
1263                    menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
1264                    the new item for the Hello-World extension is placed - select it
1265                    to see the Hello-World message.
1266                    </para>
1267            </section>
1268    
1269            <section><title>Writing simple extensions</title>
1270                    <para>
1271                    Writing an extension for Thuban basically means to
1272                    implement the extra functionality in Python with all of the
1273                    Thuban classes, methods and variables available.
1274                    </para>
1275                    <para>
1276                    All classes and their methods are documented in the source code
1277                    (see their doc-strings). Here is an example from
1278                    Thuban/Model/layer.py that describes some of the methods
1279                    of a Layer object:
1280                    </para>
1281                    <programlisting>
1282                    <![CDATA[
1283    class BaseLayer(TitledObject, Modifiable):
1284    
1285        """Base class for the layers."""
1286    
1287        def __init__(self, title, visible = True, projection = None):
1288            """Initialize the layer.
1289    
1290            title -- the title
1291            visible -- boolean. If true the layer is visible.
1292            """
1293            TitledObject.__init__(self, title)
1294            Modifiable.__init__(self)
1295            self.visible = visible
1296            self.projection = projection
1297    
1298        def Visible(self):
1299            """Return true if layer is visible"""
1300            return self.visible
1301    
1302        def SetVisible(self, visible):
1303            """Set the layer's visibility."""
1304            self.visible = visible
1305            self.issue(LAYER_VISIBILITY_CHANGED, self)
1306    
1307        def HasClassification(self):
1308            """Determine if this layer support classifications."""
1309    ...
1310                    ]]>
1311                    </programlisting>
1312                    <para>
1313                    This example intends to give you an impression of the
1314                    source-code-level documentation.
1315                    You have to make yourself familiar with
1316                    the Python programming language to understand some special
1317                    code elements.
1318                    </para>
1319                    <section><title>hello_world.py</title>
1320                      <para>
1321                      Traditionally, the first example should welcome the world.
1322                      Most of the code handles the frame for integrating a menu
1323                      item into Thuban while the actual raising of a message
1324                      is done in a single line.
1325                      </para>
1326                            <programlisting>
1327                            <![CDATA[
1328    # Copyright (C) 2003 by Intevation GmbH
1329    # Authors:
1330    # Jan-Oliver Wagner <[email protected]>
1331    #
1332    # This program is free software under the GPL (>=v2)
1333    # Read the file COPYING coming with Thuban for details.
1334    
1335    """
1336    Extend Thuban with a sample Hello World to demonstrate simple
1337    extensions.
1338    """
1339    
1340    __version__ = '$Revision$'
1341    
1342    # use _() already now for all strings that may later be translated
1343    from Thuban import _
1344    
1345    # Thuban has named commands which can be registered in the central
1346    # instance registry.
1347    from Thuban.UI.command import registry, Command
1348    
1349    # The instance of the main menu of the Thuban application
1350    # See Thuban/UI/menu.py for the API of the Menu class
1351    from Thuban.UI.mainwindow import main_menu
1352    
1353    def hello_world_dialog(context):
1354        """Just raise a simple dialog to greet the world.
1355    
1356        context -- The Thuban context.
1357        """
1358        context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
1359    
1360    
1361    # create a new command and register it
1362    registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
1363                         helptext = _('Welcome everyone on this planet')))
1364    
1365    # find the extensions menu (create it anew if not found)
1366    extensions_menu = main_menu.find_menu('extensions')
1367    if extensions_menu is None:
1368        extensions_menu = main_menu.InsertMenu('extensions', _('E&xtensions'))
1369    
1370    # finally bind the new command with an entry in the extensions menu
1371    extensions_menu.InsertItem('hello_world')
1372                            ]]>
1373                            </programlisting>
1374                    </section>
1375                    <section><title>Registering a Command</title>
1376                      <para>
1377                      Mainly, our new function has to be registered to the Thuban
1378                      framework in order to connect it to the menu. A registered
1379                      command can also be connected to e.g. a toolbar button.
1380                      </para>
1381                      <para>
1382                      The instances and classes for this are imported at the beginning.
1383                      Any code not inside a method or class is directly executed when
1384                      the source-code module is imported. Therefore, the second
1385                      part of this example consist of the plain statements to create a new
1386                      Command and to add it to the menu.
1387                      </para>
1388                      <para>
1389                      By convention, it looks for a menu registered as ``extensions'' to
1390                      insert the new command. If it does not exist yet, it gets created.
1391                      It is advisable to copy this code for any of your extensions.
1392                      </para>
1393                    </section>
1394                    <section><title>The Thuban context</title>
1395                            <para>
1396                            A registered command that is called, always receives the
1397                            Thuban context. This instance provides our method with
1398                            hook references to all important components of the Thuban
1399                            application.
1400                            </para>
1401                            <para>
1402                    In the example hello_world.py, our function uses the
1403                            mainwindow component which offers a method to raise a
1404                            message dialog. In total there are three hooks:
1405                            <itemizedlist>
1406                            <listitem>
1407                            <para>application:
1408                            This object is the instance of the Thuban Application class.
1409                            Except maybe for loading or savinf sessions, you will not
1410                            need this object for a simple extension.
1411                            See Thuban/UI/application.py for the API.
1412                            </para>
1413                            </listitem>
1414                            <listitem>
1415                            <para>session:
1416                            The instance of the current session. It manages the sessions'
1417                            map and tables. You can set and remove the map or tables.
1418                            In may also get the map object. However, you should know that
1419                            internally it is already prepared to handle many maps.
1420                            Therfore, currently you would always receive a list with exactlty
1421                            one element. In the future, if there are more than one map,
1422                            you will not know which one is the currently display one and
1423                            therefore you should use the mainwindow as hook to find
1424                            the currently displayed map.
1425                            See Thuban/Model/session.py for the API.
1426                            </para>
1427                            </listitem>
1428                            <listitem>
1429                            <para>
1430                            mainwindow: The mainwindow object is central to manage various
1431                            GUI things such as the Legend sub-window. Most notably,
1432                            you get access to the canvas which is the window part where
1433                            the map is drawn. The canvas knows, which map it currently
1434                            draws and therefore you get the current map via
1435                            context.mainwindow.canvas.Map().
1436                            See Thuban/UI/mainwindow.py for the API.
1437                            </para>
1438                            </listitem>
1439                            </itemizedlist>
1440                </para>
1441                    </section>
1442            </section>
1443      </chapter>
1444    
1445      <chapter><title>Trouble Shooting</title>
1446        <para>
1447        Here are a few problems that users have encountered when first using Thuban.
1448        </para>
1449        <para>
1450    
1451        <itemizedlist>
1452        <listitem>
1453        <para>After adding two or more layers nothing is drawn in the map window.
1454        </para>
1455        <para>
1456        This is probably because the layers have different projections. Projections
1457        must be set on all layers and on the map itself if the layers' projections
1458        are different.
1459        </para>
1460        </listitem>
1461    
1462        <listitem>
1463        <para>Thuban crashes on startup with the error
1464            <literal>NameError: global name 'False' is not defined</literal>.
1465        </para>
1466        <para>
1467        <varname>True</varname> and <varname>False</varname> were only introduced
1468        in Python 2.2.1. Thuban depends on at least Python 2.2.1.
1469        </para>
1470        </listitem>
1471    
1472        <listitem>
1473        <para>After compiling Thuban, Thuban crashes with an error similar to
1474            <literal>
1475            ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0
1476            </literal>
1477        </para>
1478        <para>
1479        Thuban depends on the wxWindows library. If Thuban is compiled with an
1480        incompatible version of the compiler than wxWindows was compiled with
1481        this error may occur. Try compiling with a different version of the
1482        compiler.
1483        </para>
1484        </listitem>
1485        </itemizedlist>
1486        </para>
1487        <para>
1488        If an error occurs Thuban will display a dialog indicating the error
1489        before closing. The text should be copied and reported to the
1490        <ulink url="http://thuban.intevation.org/bugtracker.html">
1491        Intevation bugtracker
1492        </ulink>.
1493        More information about the system is available from
1494        <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.
1495        This should also be included in the bug report.
1496        <figure>
1497        <title>Error Dialog</title>
1498        <mediaobject>
1499        <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>
1500        <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>
1501        </mediaobject>
1502        </figure>
1503        </para>
1504    
1505      </chapter>
1506    
1507      <appendix><title>Supported Data Sources</title>
1508        <para>
1509        </para>
1510        <variablelist>
1511        <varlistentry>
1512        <term>Shapefile</term>
1513        <listitem>
1514            <para>
1515            The Shapefile format has become a standard format for saving
1516            geographic vector information. It supports polygons, lines, and
1517            points.
1518            
1519            <ulink url="http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf">
1520            Technical Specification.
1521            </ulink>  
1522            </para>
1523        </listitem>
1524        </varlistentry>
1525    
1526        <varlistentry>
1527        <term>dBase file</term>
1528        <listitem>
1529            <para>
1530            dBase files are used to store the attributes for each layer. This
1531            is closely associated with the Shapefile format. For detailed
1532            specifications on the correct format of a dBase file used with
1533            Thuban please see the Technical Specification for the Shapefile
1534            format above.
1535            </para>
1536        </listitem>
1537        </varlistentry>
1538    
1539        <varlistentry>
1540        <term>Raster files</term>
1541        <listitem>
1542            <para>
1543            Binding the GDAL library Thuban supports numerous raster file formats,
1544            see <ulink url="http://www.remotesensing.org/gdal/formats_list.html">
1545            GDAL format list</ulink> for details.</para>
1546    
1547            <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
1548            format: Raster maps are provided as TIFF images, with an additional
1549            "world file" storing the geographic reference (usually with an
1550            extension ".tfw").
1551            </para>
1552        </listitem>
1553        </varlistentry>
1554    
1555        </variablelist>
1556      </appendix>
1557    
1558      <appendix><title>Supported Projections</title>
1559        <para>
1560        The following types of projections are directly support by
1561        Thuban. The specific values for each are provided by the user
1562        to create custom projections. Thuban comes with predefined
1563        projections which are available through the Projections dialog.
1564        </para>
1565        <itemizedlist>
1566        <listitem>
1567            <para>Geographic</para>
1568            <itemizedlist>
1569            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1570            <listitem><para>
1571                    <literal>Source Data</literal>: either Degrees or Radians
1572                    </para></listitem>
1573            </itemizedlist>
1574        </listitem>
1575        <listitem>
1576            <para>Lambert Conic Conformal</para>
1577        <itemizedlist>
1578            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1579            <listitem><para><literal>Latitude of 1st standard parallel</literal></para></listitem>
1580            <listitem><para><literal>Latitude of 2nd standard parallel</literal></para></listitem>
1581            <listitem><para><literal>Central Meridian</literal></para></listitem>
1582            <listitem><para><literal>Latitude of Origin</literal></para></listitem>
1583            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
1584            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
1585        </itemizedlist>
1586        </listitem>
1587        <listitem>
1588            <para>Transverse Mercator</para>
1589        <itemizedlist>
1590            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1591            <listitem><para><literal>Latitude</literal>of origin</para></listitem>
1592            <listitem><para><literal>Longitude</literal>at central meridian</para></listitem>
1593            <listitem><para><literal>Scale Factor</literal>at central meridian</para></listitem>
1594            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
1595            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
1596        </itemizedlist>
1597        </listitem>
1598        <listitem>
1599            <para>Universal Transverse Mercator</para>
1600        <itemizedlist>
1601            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1602            <listitem><para><literal>Zone</literal>
1603                    (can be guessed appling the Propose button)</para></listitem>
1604            <listitem><para><literal>Southern Hemisphere</literal> flag</para></listitem>
1605        </itemizedlist>
1606        </listitem>
1607        </itemizedlist>
1608        
1609        <para>
1610        Thuban comes with a sample set of map projections for various
1611        European countries. Apart from the basic projection they differ
1612        especially in their parameterization:
1613        </para>
1614        <itemizedlist>
1615        <listitem><para>Belgium Datum 1972 (Lambert Conic Conformal)</para>
1616        </listitem>
1617    
1618        <listitem><para>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</para>
1619        </listitem>
1620    
1621        <listitem><para>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)
1622        </para>
1623        </listitem>
1624    
1625        <listitem><para>Reseau Geodesique Francaise
1626        (France, Lambert Conic Conformal)</para>
1627        </listitem>
1628    
1629        <listitem><para>UK National Grid (United Kingdom, Transverse Mercartor)
1630        </para>
1631        </listitem>
1632        </itemizedlist>
1633    
1634        <para>
1635        Thuban uses the comprehensive PROJ library for projections. PROJ provides
1636        more than the four commonly used projections described above. If needed
1637        Thuban can be easily extended to a new projection covered by PROJ.
1638        </para>
1639      </appendix>
1640    
1641  </book>  </book>
1642    
Legend:
Removed from v.1367  
changed lines
  Added in v.1689
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26