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