/[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 1496 by frank, Tue Jul 29 12:07:13 2003 UTC revision 1744 by jan, Tue Sep 23 15:37:25 2003 UTC
# Line 6  Line 6 
6  <!-- $Revision$ -->  <!-- $Revision$ -->
7  <book>  <book>
8    <bookinfo>    <bookinfo>
9      <title>Thuban Manual</title>      <title>User's Manual for Thuban 1.0</title>
10      <author>          <authorgroup>
11        <firstname>Jonathan</firstname><surname>Coles</surname>        <author>
12      </author>          <firstname>Jonathan</firstname><surname>Coles</surname>
13      <author>        </author>
14        <firstname>Jan-Oliver</firstname><surname>Wagner</surname>        <author>
15      </author>          <firstname>Jan-Oliver</firstname><surname>Wagner</surname>
16      <author>        </author>
17        <firstname>Frank</firstname><surname>Koormann</surname>        <author>
18      </author>          <firstname>Frank</firstname><surname>Koormann</surname>
19          </author>
20            </authorgroup>
21      <copyright>      <copyright>
22        <year>2003</year>        <year>2003</year>
23        <holder>Intevation GmbH</holder>        <holder>Intevation GmbH</holder>
24      </copyright>      </copyright>
25       <revhistory>
26    <!-- comment this first revision out when releasing a real version -->
27    <!--
28         <revision>
29            <revnumber>CVS version $Id$</revnumber>
30            <date></date>
31            <revremark>Under development.</revremark>
32         </revision>
33    -->
34         <revision>
35            <revnumber>1.0pre2</revnumber>
36            <date>29-Aug-2003</date>
37            <revremark>
38                            Corresponds to Thuban development release 0.8.1.
39                            New: chapter on extensions.
40                    </revremark>
41         </revision>
42         <revision>
43            <revnumber>1.0pre1</revnumber>
44            <date>08-Aug-2003</date>
45            <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
46         </revision>
47      </revhistory>
48    
49    </bookinfo>    </bookinfo>
50    
51    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
52      <para>      <para>
53      Thuban is a Free Software Geographic Information Systems (GIS) viewer.      Thuban is an interactive geographic data viewer.
54      It is being developed because there is currently no simple interactive      It has been developed because there was no simple interactive
55      viewer for geographic information available as Free Software. Thuban is      viewer for geographic information available as Free Software. Thuban is
56      written in Python and C++ and uses the wxWindows library allowing it to      written in Python and C++ and uses the wxWindows library allowing it to
57      run on many different platforms, including GNU/Linux and Windows.      run on many different platforms, including GNU/Linux and Windows.
58      </para>      </para>
59      <para>      <para>
60      GIS viewers are a necessary tool as they allow one to get a visual      Geographic data viewers are a necessary tool as they allow one to
61            get a visual
62      impression of the positional relationship of the information that may not      impression of the positional relationship of the information that may not
63      be apparent from simple inspection of the data values themselves.      be apparent from simple inspection of the data values themselves.
64      Thuban allows the user to create a session that displays      Thuban allows the user to create a session that displays
# Line 48  Line 75 
75          <section><title>Installation</title>          <section><title>Installation</title>
76          <para>          <para>
77          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,
78          and Windows 2000. All the necessary files can be found on the          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">          <ulink url="http://thuban.intevation.org/download.html">
81          Thuban Download site          Thuban Download site
82          </ulink>.          </ulink>.
83          </para>          <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><title>RPM-based GNU/Linux Systems</title>
99                            <section><title>Installing Binary Packages</title>
100                                    <para>
101                                    The most wide-spread RPM-based GNU/Linux Systems are RedHat,
102                                    Mandrake and SuSE. The documentation of these distributions
103                                    should contain information about how to install third-party
104                                    RPM packages. Nonetheless, a short summary is provided here.
105                                    </para>
106                                    <para>
107                                    RPM packages can be installed applying several tools.
108                                    The most basic one is the command line program "rpm".
109                                    The hardware architecture is identified in the name
110                                    of RPM packages, eg. 'i386' for most Intel/AMD architectures.
111                                    If you have a different hardware architecture, where no
112                                    binary RPM packages are provided, you must rebuild binary
113                                    packages from the RPM source packages first (see below).
114                                    Typical rpm commands look like:
115    
116                                    <programlisting>
117                                    rpm --install Thuban-0.9.0-1.i386.rpm
118                                    </programlisting>
119    
120                                    Depending on what you already have installed on your
121                                    system, you are informed that some packages are
122                                    required, but not installed. You need to install them
123                                    first. Either they are provided by your GNU/Linux distributor
124                                    or available somewhere on the Internet.
125                                    The more essential and special ones are provided together
126                                    with the Thuban package.
127                                    </para>
128    
129                                    <para>
130                                    For rpm exist some graphical user interfaces, notably
131                                    kpackage, GnoRPM and xrpm.
132                                    </para>
133    
134                                    <para>
135                                    Make yourself familiar with one of the tools and apply it
136                                    to install the packages.
137                                    Note, that you need to be administrator (root) for the system
138                                    to do that.
139                                    </para>
140                            </section>
141                            <section><title>Build Binaries from Source Packages</title>
142                                    <para>
143                                    This section describes howto build RPM install-packages
144                                    from RPM source-packages.
145                                    This adapts and optimizes an install-package specifically
146                                    to your system.
147                                    This is especially helpful to resolve version conflicts of
148                                    dependent packages. Furthermore, install-packages for other
149                                    platforms (e.g. PowerPC) can be created.
150                                    </para>
151    
152                                    <para>
153                                    Note: rpm must be at least version 4. Execute
154                                    <literal>rpm --version</literal> to find out about the version.
155                                    </para>
156    
157                                    <para>
158                                    You need to do the following preparations to be able to
159                                    build the packages as a regular user. You should now
160                                    perform the package buling as root since this
161                                    might cause damage to your system.
162                            <itemizedlist>
163                            <listitem>
164                                                    <para>
165                                                    Create RPM directory structure:
166                                                    Choose a directory (e.g. $HOME/myrpm) and create the
167                                                    subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.
168                                                    A possible command sequence for this is:
169                                                    <programlisting>
170                                                    mkdir $HOME/freegisrpm
171                                                    cd $HOME/freegisrpm
172                                                    mkdir BUILD RPMS SOURCES SPECS SRPMS
173                                                    </programlisting>
174                                                    </para>
175                                            </listitem>
176                                            <listitem>
177                                                    <para>
178                                                    Set environment variable RPM_DIR:
179                                                    <programlisting>
180                                                    export RPM_DIR=$HOME/freegisrpm
181                                                    </programlisting>
182                                                    </para>
183                                            </listitem>
184                                            <listitem>
185                                                    <para>
186                                                    Create $HOME/.rpmmacros:
187                                                    This file sets general preferences and some
188                                                    specific settings for signing packages.
189                                                    If you don't have a GnuPG-key, you can skip
190                                                    the signature settings i.e. drop the last 4 lines.
191                                                    A signature becomes important when you want to
192                                                    give away packages to third parties.
193                                                    <programlisting>
194    <![CDATA[
195    %packager Name Lastname <[email protected]>
196    
197    %_topdir /home/mylogin/myrpm
198    
199    %_signature gpg
200    %_gpg_name Name Lastname
201    %_pgp_path ~/.gnupg
202    %_pgpbin /usr/bin/gpg
203    ]]>
204                                                    </programlisting>
205                                                    </para>
206                                            </listitem>
207                            </itemizedlist>
208    
209                                    Now you can install any RPM source-package.
210                                    It's components are installed into the corresponding
211                                    subdirectories of your rpm-directory.
212                                    Essentially these are the sources (into directory SOURCES)
213                                    and the so-called spec-file which contains all build
214                                    instructions. The spec-file will go into the SPEC directory.
215                                    Example:
216                                    <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>
217                                    </para>
218    
219                                    <para>
220                                    Create install-package:
221                                    Go to the directory with the spec-files and rebuild the
222                                    package:
223                                    <programlisting>
224    cd $HOME/mypm/SPECS
225    rpm -bb thuban.spec
226                                    </programlisting>
227                                    Next, you will find the newly created package in
228                                    $HOME/myrpm/RPMS/i386.
229                                    If you build the package for another architecture than
230                                    i386, then the name of the directory has a corresponding name.
231                                    </para>
232                                    <para>
233                                    For documentation of RPM, either type
234                                    <literal>man rpm</literal> or <literal>rpm --help</literal>.
235                                    This will provide you with information on the various command
236                                    line options of RPM.
237                                    For more information see the
238                            <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
239                                    </para>
240                            </section>
241                    </section>
242          </section>          </section>
243    
244          <section><title>The Main Window</title>          <section><title>The Main Window</title>
245          <para>          <para>
246          <screenshot>          <figure>
247          <screeninfo>The Main Window</screeninfo>          <title>The Main Window</title>
248          <mediaobject>          <mediaobject>
249          <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>          <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>
250          <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>          <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>
         <textobject><phrase>The Main Window</phrase></textobject>  
         <caption><para>The Main Window</para></caption>  
251          </mediaobject>          </mediaobject>
252          </screenshot>          </figure>
253          </para>          </para>
254    
255          <para>          <para>
# Line 159  Line 343 
343    
344          <section><title>The Session Info-Tree</title>          <section><title>The Session Info-Tree</title>
345          <para>          <para>
346          <screenshot>          <figure>
347          <screeninfo>Session Info Tree</screeninfo>          <title>Session Info Tree</title>
348          <mediaobject>          <mediaobject>
349          <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>
350          <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Session Info Tree</phrase></textobject>  
         <caption><para>Session Info Tree</para></caption>  
351          </mediaobject>          </mediaobject>
352          </screenshot>          </figure>
353          </para>          </para>
354          <para>          <para>
355          The session info-tree is primarily intended for developers working          The session info-tree is primarily intended for developers working
# Line 209  Line 391 
391    
392          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
393          <para>          <para>
394          There are two types of layers that can use added to a map: shape layers          There are two types of layers that can be added to a map: Shape layers
395          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
396          standard file format for storing geographic objects. These          widely used file format for storing geographic objects. These
397          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
398          the shape file is a database file which stores attributes for          the shape file is a database file which stores attributes for
399          each shape in the shape file. This file, in dBase format,          each shape in the Shape file. This file, in dBase format,
400          has the extension ``.dbf''. Both files must have the same base name.          has the extension ``.dbf''. Both files must have the same base name.
401          For example, if there is a shape file named roads.shp there must          For example, if there is a shape file named roads.shp there must
402          also be a file roads.dbf.          also be a file roads.dbf.
# Line 225  Line 407 
407          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
408          <guimenuitem>Add Layer</guimenuitem>          <guimenuitem>Add Layer</guimenuitem>
409          </menuchoice>.          </menuchoice>.
410          Thuban will load all files with the same base name, so it doesn't          Initially, only the ``.shp'' files are shown which is enough for the
411          matter if the shape file or database file is selected.                  selection. However, if you switch to display all files and select one
412                    of the associated files (e.g. ``.dbf''), Thuban will recognize the base
413                    name and load the corresponding Shape file.
414            </para>
415                    <para>
416                    The file dialog for Shape files allows to select multiple files.
417                    Use the shift-button together with the left mouse button to extend
418                    the selection.
419          </para>          </para>
420    
421          <para>          <para>
# Line 248  Line 437 
437          the tool bar or from the          the tool bar or from the
438          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.
439          </para>          </para>
440            <itemizedlist>
441            <listitem>
442          <para>          <para>
443          The ZoomIn tool          The ZoomIn tool
444          <inlinemediaobject>          <inlinemediaobject>
# Line 261  Line 452 
452          </inlinemediaobject>          </inlinemediaobject>
453          enlarges a region of the map. Clicking once on the map          enlarges a region of the map. Clicking once on the map
454          will double the magnification and center the map on the point that          will double the magnification and center the map on the point that
455          was clicked. Clicking and dragging selects a region that will          was clicked. Clicking and dragging selects a region that will be
456          enlarged to fit the window.          enlarged to fit the window.
457          </para>          </para>
458            </listitem>
459            <listitem>
460          <para>          <para>
461          The ZoomOut tool          The ZoomOut tool
462          <inlinemediaobject>          <inlinemediaobject>
# Line 280  Line 473 
473          selects a box such that the current contents of the window will be          selects a box such that the current contents of the window will be
474          scaled to fit into that box.          scaled to fit into that box.
475          </para>          </para>
476            </listitem>
477            <listitem>
478          <para>          <para>
479          The Pan tool          The Pan tool
480          <inlinemediaobject>          <inlinemediaobject>
# Line 293  Line 488 
488          </inlinemediaobject>          </inlinemediaobject>
489          allows the user to move the map around by clicking and dragging.          allows the user to move the map around by clicking and dragging.
490          </para>          </para>
491            </listitem>
492            <listitem>
493          <para>          <para>
494          The Full Extent tool          The Full Extent tool
495          <inlinemediaobject>          <inlinemediaobject>
# Line 306  Line 503 
503          </inlinemediaobject>          </inlinemediaobject>
504          rescales the viewable region so that the entire map is visible.          rescales the viewable region so that the entire map is visible.
505          </para>          </para>
506            </listitem>
507            <listitem>
508          <para>          <para>
509          The Full Layer Extent tool          The Full Layer Extent tool
510          <inlinemediaobject>          <inlinemediaobject>
# Line 321  Line 520 
520          layer fits within the window. If no layer is selected this button          layer fits within the window. If no layer is selected this button
521          will be disabled.          will be disabled.
522          </para>          </para>
523            </listitem>
524            <listitem>
525          <para>          <para>
526          The Full Shape Extent tool          The Full Shape Extent tool
527          <inlinemediaobject>          <inlinemediaobject>
# Line 335  Line 536 
536          rescales the viewable region so that the currently selected          rescales the viewable region so that the currently selected
537          shape fits within the window. If the shape is a point, it is          shape fits within the window. If the shape is a point, it is
538          centered and the map is zoomed all the way in. If no shape is          centered and the map is zoomed all the way in. If no shape is
539          selected this button will be disabled.          selected this button will be disabled. This feature is especially
540            helpful when identifying an object related to a selected record
541            in a tableview (see below).
542    
543          </para>          </para>
544            </listitem>
545            </itemizedlist>
546          </section>          </section>
547    
548          <section><title>Object Identification</title>          <section><title>Object Identification</title>
# Line 353  Line 559 
559          </inlinemediaobject>.          </inlinemediaobject>.
560          Clicking on an object selects that object and opens a dialog which          Clicking on an object selects that object and opens a dialog which
561          shows all the table attributes for that object. Any current selection          shows all the table attributes for that object. Any current selection
562          is lost.          is lost. Objects on the map are typically shapes and this document
563            will often refer to objects as shapes.
564          </para>          </para>
565          </section>          </section>
566    
# Line 404  Line 611 
611          <menuchoice><guimenu>Map</guimenu></menuchoice>.          <menuchoice><guimenu>Map</guimenu></menuchoice>.
612          </para>          </para>
613    
614            <itemizedlist>
615            <listitem>
616          <para>          <para>
617          The Move Layer to Top tool          The Move Layer to Top tool
618          <inlinemediaobject>          <inlinemediaobject>
# Line 416  Line 625 
625          <textobject> <phrase>Move Layer to Top</phrase> </textobject>          <textobject> <phrase>Move Layer to Top</phrase> </textobject>
626          </inlinemediaobject> raises the selected layer to the top of the map.          </inlinemediaobject> raises the selected layer to the top of the map.
627          </para>          </para>
628            </listitem>
629            <listitem>
630    
631          <para>          <para>
632          The Move Layer Up tool          The Move Layer Up tool
# Line 429  Line 640 
640          <textobject> <phrase>Move Layer Up</phrase> </textobject>          <textobject> <phrase>Move Layer Up</phrase> </textobject>
641          </inlinemediaobject> raises the selected layer one level.          </inlinemediaobject> raises the selected layer one level.
642          </para>          </para>
643            </listitem>
644            <listitem>
645    
646          <para>          <para>
647          The Move Layer Down tool          The Move Layer Down tool
# Line 443  Line 656 
656          </inlinemediaobject> lowers the selected layer one level.          </inlinemediaobject> lowers the selected layer one level.
657          </para>          </para>
658    
659            </listitem>
660            <listitem>
661          <para>          <para>
662          The Move Layer to Bottom tool          The Move Layer to Bottom tool
663          <inlinemediaobject>          <inlinemediaobject>
# Line 456  Line 671 
671          </inlinemediaobject> lowers the selected layer to the bottom of the map.          </inlinemediaobject> lowers the selected layer to the bottom of the map.
672          </para>          </para>
673    
674            </listitem>
675            <listitem>
676          <para>          <para>
677          The Visible tool          The Visible tool
678          <inlinemediaobject>          <inlinemediaobject>
# Line 470  Line 687 
687          hidden.          hidden.
688          </para>          </para>
689    
690            </listitem>
691            <listitem>
692          <para>          <para>
693          The Invisible tool          The Invisible tool
694          <inlinemediaobject>          <inlinemediaobject>
# Line 483  Line 702 
702          </inlinemediaobject> hides the selected layer in the map.          </inlinemediaobject> hides the selected layer in the map.
703          </para>          </para>
704    
705            </listitem>
706            <listitem>
707          <para>          <para>
708          The Properties tool          The Properties tool
709          <inlinemediaobject>          <inlinemediaobject>
# Line 497  Line 718 
718          Double-clicking on a layer or a group of a layer will open the          Double-clicking on a layer or a group of a layer will open the
719          properties dialog for that layer.          properties dialog for that layer.
720          </para>          </para>
721            </listitem>
722            </itemizedlist>
723            <para>
724            Along the bottom of the legend is the scalebar. The scalebar
725            will be available if there are any layers and the  map has a
726            projection set.
727            </para>
728          </section>          </section>
729    
730          <section><title>Exporting</title>          <section><title>Exporting</title>
# Line 507  Line 735 
735          <menuchoice>          <menuchoice>
736          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
737          <guimenuitem>Export</guimenuitem>          <guimenuitem>Export</guimenuitem>
738          </menuchoice>. Under other platforms this option is not available.          </menuchoice> for use in reports, presentations, or further
739          Clicking this menu item open a file selection dialog that lets the          modification. The current map view, legend, and, if available,
740          user select a location to export the map.          scalebar are exported. Under other platforms this option is not
741            available. Clicking this menu item open a file selection dialog
742            that lets the user select a location to export the map.
743          </para>          </para>
744          </section>          </section>
745    
# Line 519  Line 749 
749          <menuchoice>          <menuchoice>
750          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
751          <guimenuitem>Print</guimenuitem>          <guimenuitem>Print</guimenuitem>
752          </menuchoice>. A standard printing dialog will open allowing the          </menuchoice>. The current map view, legend, and, if available,
753          user to configure the printer. This dialog will differ depending          scalebar are printed. A standard printing dialog will open allowing
754            the user to configure the printer. This dialog will differ depending
755          on which platform Thuban is running.          on which platform Thuban is running.
756          </para>          </para>
757          </section>          </section>
# Line 536  Line 767 
767          There are two types of layers supported by Thuban: shape layers and          There are two types of layers supported by Thuban: shape layers and
768          image layers. Shape layers consist of vector based shapes with          image layers. Shape layers consist of vector based shapes with
769          geo-referenced coordinates. There are three types of supported          geo-referenced coordinates. There are three types of supported
770          shapes: polygons, lines, and points. Image layers can be any image          shapes: polygons, lines (arc), and points. Image layers can be any image
771          file format supported by the Geo-spatial Data Abstraction Library          file format supported by the Geo-spatial Data Abstraction Library
772          (GDAL). The images must have geographic          (GDAL). The images must have geographic
773          coordinate data either embedded within the file or in a separate          coordinate data either embedded within the file or in a separate
# Line 544  Line 775 
775          work very well with Thuban and were designed specifically to be image          work very well with Thuban and were designed specifically to be image
776          layers in GIS programs.          layers in GIS programs.
777          </para>          </para>
778            <para>
779            All actions in the
780            <menuchoice>
781            <guimenu>Layer</guimenu>
782            </menuchoice> menu act on the currently selected layer in the legend.
783            </para>
784          </section>          </section>
785    
786          <section><title>Properties</title>          <section><title>Properties</title>
# Line 554  Line 791 
791          <guimenu>Layer</guimenu>          <guimenu>Layer</guimenu>
792          <guimenuitem>Properties</guimenuitem>          <guimenuitem>Properties</guimenuitem>
793          </menuchoice> opens a dialog that displays a layer's properties.          </menuchoice> opens a dialog that displays a layer's properties.
794          All layers have a title and it can be modified in the text field          All layers have a title which can be modified in the text field
795          provided. The type of layer is also shows. If the type is a type          provided. The type of layer is also shows. If the type is a type
796          of shape (polygon, arc, point) the classification table will be          of shape (polygon, arc, point) the classification table will be
797          shown. Image layers have no other properties other than title          shown. Image layers have no other properties other than title
798          and type.          and type.
799          </para>          </para>
800          <para>          <para>
801          <screenshot>          <figure>
802          <screeninfo>Properties Window</screeninfo>          <title>Properties Window</title>
803          <mediaobject>          <mediaobject>
804          <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
805          <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Properties Window</phrase></textobject>  
         <caption><para>The Properties Window for a Shape Layer</para></caption>  
806          </mediaobject>          </mediaobject>
807          </screenshot>          </figure>
808          </para>          </para>
809          <para>          <para>
810          <screenshot>          <figure>
811          <screeninfo>Properties Window</screeninfo>          <title>Properties Window</title>
812          <mediaobject>          <mediaobject>
813          <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
814          <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Properties Window</phrase></textobject>  
         <caption><para>The Properties Window for an Image Layer</para></caption>  
815          </mediaobject>          </mediaobject>
816          </screenshot>          </figure>
817          </para>          </para>
818          </section>          </section>
819    
# Line 646  Line 879 
879      <para>      <para>
880      A layer always has a classification. When a new layer is added to the      A layer always has a classification. When a new layer is added to the
881      map, a default classification is created with the DEFAULT group. This      map, a default classification is created with the DEFAULT group. This
882      group cannot be removed. Every shape in the layer, regardless of its      group cannot be removed but can be hidden (see below). Every shape in the
883      attributes, will match this group if no other group matches.      layer, regardless of its attributes, will match this group if no other
884        group matches.
885      </para>      </para>
886    
887          <section><title>Editing Classifications</title>          <section><title>Editing Classifications</title>
# Line 664  Line 898 
898          button.          button.
899          </para>          </para>
900          <para>          <para>
901          <screenshot>          To apply the changes to the map the user can click
902          <screeninfo>Properties Window</screeninfo>          either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
903            <guibutton>Try</guibutton> will not close the dialog box, allowing
904            the user to see how the classification changes the map.
905            <guibutton>Revert</guibutton> will undo the last classification applied
906            to the map. <guibutton>OK</guibutton> will commit the changes and
907            close the dialog. The user will be unable to undo the changes.
908            <guibutton>Close</guibutton> simply closes the dialog box. If any
909            changes have not been applied with <guibutton>Try</guibutton> the
910            changes will not be applied to the map.
911            </para>
912            <para>
913            <figure>
914            <title>Properties Window</title>
915          <mediaobject>          <mediaobject>
916          <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>
917          <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Properties Window</phrase></textobject>  
         <caption><para>The Properties Window with Classifications</para></caption>  
918          </mediaobject>          </mediaobject>
919          </screenshot>          </figure>
920          </para>          </para>
921          <para>          <para>
922          The order of the groups in the classification is significant          The order of the groups in the classification is significant
# Line 738  Line 982 
982    
983          <section><title>Generating Classes</title>          <section><title>Generating Classes</title>
984          <para>          <para>
985          <screenshot>          <figure>
986          <screeninfo>Generate Class</screeninfo>          <title>Generate Class</title>
987          <mediaobject>          <mediaobject>
988          <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>
989          <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Generate Class</phrase></textobject>  
         <caption><para>The Generate Classifications Dialog</para></caption>  
990          </mediaobject>          </mediaobject>
991          </screenshot>          </figure>
992          </para>          </para>
993          <para>          <para>
994          Creating a classification by hand can be tedious.          Creating a classification by hand can be tedious.
# Line 756  Line 998 
998          opens the <varname>Generate Classification</varname> dialog.          opens the <varname>Generate Classification</varname> dialog.
999          Under the <varname>Generate</varname> pull down there are at most          Under the <varname>Generate</varname> pull down there are at most
1000          three different ways to generate classifications:          three different ways to generate classifications:
1001          Unique Values, Unique Distribution, and Quantiles. Some options          Unique Values, Uniform Distribution, and Quantiles. Some options
1002          may not be available if the data type for the field does not          may not be available if the data type for the field does not
1003          support them. For instance, <varname>Unique Distribution</varname>          support them. For instance, <varname>Uniform Distribution</varname>
1004          doesn't make sense for a Text field.          doesn't make sense for a Text field.
1005          </para>          </para>
1006          <para>          <para>
1007          For every way of generating a classification, a color scheme must          For every way of generating a classification, a color scheme must
1008          be selected. Thuban provides several different color schemes that          be selected. Thuban provides several different color schemes that
1009          affect how the group properties change over the classification.          affect how the group properties change over the classification.
1010            It may be desirable that only certain properties change over the
1011            classification. If the shape type is a polygon or a point then
1012            the <guibutton>Fix Border Color</guibutton> option will be available.
1013            This allows the user to select a border color for all classification
1014            groups.
1015          It is also possible to create a custom color scheme. Selecting          It is also possible to create a custom color scheme. Selecting
1016          this option will display two symbols: the one of the left has the          this option will display two symbols: the one of the left has the
1017          properties of the first group and the one on the right has the          properties of the first group and the one on the right has the
1018          properties of the last group. Thuban will interpolate between these          properties of the last group. Thuban will interpolate between these
1019          two properties to generate the other groups.          two properties to generate the other groups.
1020            <figure>
1021            <title>Custom Color Scheme</title>
1022            <mediaobject>
1023            <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>
1024            <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>
1025            </mediaobject>
1026            </figure>
1027          </para>          </para>
1028          <para>          <para>
1029          The Unique Values option lets the user select specific values that          The Unique Values option lets the user select specific values that
# Line 779  Line 1033 
1033          right. Each list can be sorted or reversed for easier searching.          right. Each list can be sorted or reversed for easier searching.
1034          The classification that is generated will be in the same order as          The classification that is generated will be in the same order as
1035          the list on the right.          the list on the right.
1036            <figure>
1037            <title>Unique Values</title>
1038            <mediaobject>
1039            <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>
1040            <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>
1041            </mediaobject>
1042            </figure>
1043          </para>          </para>
1044          <para>          <para>
1045          The Unique Distribution option creates a user specified number of          The Uniform Distribution option creates a user specified number of
1046          groups of ranges such that each range covers equal intervals. The          groups of ranges such that each range covers equal intervals. The
1047          minimum and maximum values can automatically be retrieved from the          minimum and maximum values can automatically be retrieved from the
1048          table by clicking <guibutton>Retrieve From Table</guibutton>. The          table by clicking <guibutton>Retrieve From Table</guibutton>. The
1049          stepping is how large each interval is. Adjusting this value will          stepping is how large each interval is. Adjusting this value will
1050          automatically recalculate how many groups is appropriate.          automatically recalculate how many groups is appropriate.
1051            <figure>
1052            <title>Uniform Distribution</title>
1053            <mediaobject>
1054            <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>
1055            <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>
1056            </mediaobject>
1057            </figure>
1058          </para>          </para>
1059          <para>          <para>
1060          The Quantiles option generates ranges based on the number of items          The Quantiles option generates ranges based on the number of items
1061          in the input set. For example, by specifying five groups Thuban will          in the table. For example, by specifying five groups Thuban will
1062          generate five groups with appropriate ranges such that 20% of the table          generate five groups with appropriate ranges such that 20% of the table
1063          data is in each group. If it is impossible to generate exact          data is in each group. If it is impossible to generate exact
1064          groupings, Thuban will issue a warning but allow the user to continue.          groupings, Thuban will issue a warning but allow the user to continue.
1065            <figure>
1066            <title>Quantiles</title>
1067            <mediaobject>
1068            <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>
1069            <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>
1070            </mediaobject>
1071            </figure>
1072          </para>          </para>
1073          </section>          </section>
1074    </chapter>    </chapter>
# Line 815  Line 1090 
1090      <guimenu>Layer</guimenu>      <guimenu>Layer</guimenu>
1091      <guimenuitem>Projection</guimenuitem>      <guimenuitem>Projection</guimenuitem>
1092      </menuchoice>.      </menuchoice>.
1093      <screenshot>      <figure>
1094      <screeninfo>Projection Window</screeninfo>      <title>Projection Window</title>
1095      <mediaobject>      <mediaobject>
1096      <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>      <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>
1097      <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>      <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>
     <textobject><phrase>Projection Window</phrase></textobject>  
     <caption><para>The Projection Window</para></caption>  
1098      </mediaobject>      </mediaobject>
1099      </screenshot>      </figure>
1100      </para>      </para>
1101      <para>      <para>
1102      Thuban is distributed with a sample collection of projections. The      Thuban is distributed with a sample collection of projections. The
# Line 855  Line 1128 
1128          <guibutton>Remove</guibutton> button will permanently remove a          <guibutton>Remove</guibutton> button will permanently remove a
1129          projection from the list of available projections.          projection from the list of available projections.
1130          </para>          </para>
1131            <para>
1132            To apply the selected projection to the map the user can click
1133            either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
1134            <guibutton>Try</guibutton> will not close the dialog box, allowing
1135            the user to see how the projeciton changes the map.
1136            <guibutton>Revert</guibutton> will undo the last projection applied
1137            to the map. <guibutton>OK</guibutton> will commit the changes and
1138            close the dialog. The user will be unable to undo the changes.
1139            <guibutton>Close</guibutton> simply closes the dialog box. If no
1140            selection has been applied with <guibutton>Try</guibutton> the
1141            selection will not be applied to the map.
1142            </para>
1143      </section>      </section>
1144          <section><title>Importing/Exporting Projections</title>          <section><title>Importing/Exporting Projections</title>
1145          <para>          <para>
# Line 881  Line 1166 
1166    
1167      <section><title>Table View</title>      <section><title>Table View</title>
1168          <para>          <para>
1169          <screenshot>          <figure>
1170          <screeninfo>Table View</screeninfo>          <title>Table View</title>
1171          <mediaobject>          <mediaobject>
1172          <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>
1173          <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>          <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>
         <textobject><phrase>Table View</phrase></textobject>  
         <caption><para>The Table View</para></caption>  
1174          </mediaobject>          </mediaobject>
1175          </screenshot>          </figure>
1176          </para>          </para>
1177          <para>          <para>
1178          Thuban provides a standard dialog to display table contents, the          Thuban provides a standard dialog to display table contents, the
1179          Table View. The view falls has five sections: The title, selections,          Table View. The view has five sections: The title, selections,
1180          the table grid, export functions, and the status bar.          the table grid, export functions, and the status bar.
1181          </para>          </para>
1182          <para>          <para>
# Line 906  Line 1189 
1189          third choice can be either a specific value (interpreted as numerical          third choice can be either a specific value (interpreted as numerical
1190          or string depending on the type of the first field) or a second field          or string depending on the type of the first field) or a second field
1191          identifier. Thus you can perform analysis like selecting all          identifier. Thus you can perform analysis like selecting all
1192          records where "population > 10000" or          records where <literal>population > 10000</literal> or
1193          "cars_per_inhabitant <  bikes_per_inhabitant" (note that the field names          <literal>cars_per_inhabitant < bikes_per_inhabitant</literal>
1194          are only explanatory, the dBase files allow only          (note that the field names are only explanatory, the dBase files
1195          11 character field names).          allow only 11 character field names).
1196                
1197          Selections can be combined either by applying a selection only on          Selections can be combined either by applying a selection only on
1198          a previously selected set of records or by adding the results of a          a previously selected set of records or by adding the results of a
# Line 917  Line 1200 
1200          earlier results.          earlier results.
1201          </para>          </para>
1202          <para>          <para>
1203          The table grid shows the contents of the table (a record per column),          The table grid shows the contents of the table (one record per row),
1204          with highlighted selection results. Columns and rows can be resized.          with highlighted selection results. Columns and rows can be resized.
1205          </para>          </para>
1206          <para>          <para>
# Line 1010  Line 1293 
1293    
1294          <section><title>Join</title>          <section><title>Join</title>
1295              <para>              <para>
1296              <screenshot>              <figure>
1297              <screeninfo>Join Tables</screeninfo>              <title>Join Tables</title>
1298              <mediaobject>              <mediaobject>
1299              <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>              <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>
1300              <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>              <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>
             <textobject><phrase>Join Tables</phrase></textobject>  
             <caption><para>The Join Tables Dialog</para></caption>  
1301              </mediaobject>              </mediaobject>
1302              </screenshot>              </figure>
1303              </para>              </para>
1304              <para>              <para>
1305              The              The
# Line 1044  Line 1325 
1325      </section>      </section>
1326      <section><title>Attribute Tables</title>      <section><title>Attribute Tables</title>
1327          <para>          <para>
1328              To clearly separate between both types, Thuban provides              To clearly separate between both types of tables (data and
1329          functionality regarding the attribute tables under the Layer menu.          attribute), Thuban provides functionality regarding the attribute
1330            tables under the <menuchoice><guimenu>Layer</guimenu></menuchoice> menu.
1331          </para>          </para>
1332    
1333          <section><title>Show Table</title>          <section><title>Show Table</title>
# Line 1097  Line 1379 
1379      </section>      </section>
1380    </chapter>    </chapter>
1381    
1382      <chapter><title>Extensions</title>
1383            <para>
1384            Thuban is designed to be extensible. The term Extension is used as a
1385            general term for anything that extends Thuban.
1386            This chapter introduces into some oppportunities how to add and
1387            handle extra functionality developed by your own or third parties.
1388            </para>
1389    
1390            <section><title>Add personal extensions via thubanstart.py</title>
1391                    <para>
1392                    After Thuban has been started for the first time, a directory
1393                    .thuban is created within your home directory.
1394                    There you can add a file thubanstart.py  which will be imported
1395                    by Thuban at start-up. It is recommended to add only import-statements
1396                    to this file to keep the actual code of extensions separate.
1397                    </para>
1398                    <para>
1399                    The modules to import must either be found through the environment
1400                    variable PYTHONPATH or directly be placed into the .thuban-directory.
1401                    </para>
1402                    <para>
1403                    As an example, copy the file examples/simple_extensions/hello_world.py
1404                    of the Thuban source code into the .thuban-directory of your home
1405                    directory. Now add add the statement import hello_world to the
1406                    file thubanstart.py and run Thuban. You will notice an additional
1407                    menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
1408                    the new item for the Hello-World extension is placed - select it
1409                    to see the Hello-World message.
1410                    </para>
1411            </section>
1412    
1413            <section><title>Extensions included in Thuban package</title>
1414                    <para>
1415                    The extensions described in this section are part of the
1416                    Thuban package, but not activated by default.
1417                    You will find them in the Thuban installation directory
1418                    under <literal>Extensions/</literal>. Activate them as personal
1419                    extensions via PYTHONPATH as described in the previous section.
1420                    Stable extensions will appear under the menu
1421                    <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
1422                    extensions which are in experimental state and therefore
1423                    not fully functional under
1424                    <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
1425                    </para>
1426    
1427                    <section><title>Stable extensions</title>
1428                            <para>
1429                            These extensions provide extra-functionality to Thuban
1430                            that has not (yet) been integrated in the main application.
1431                            They are considered to be free of bugs, but may be
1432                            further polished with helpful user interactions.
1433                            </para>
1434                            <section><title>gns2shp</title>
1435                                    <para>
1436                                    This tool converts data of the Geospatial Names Server
1437                                    (GNS, see <ulink url="http://www.nima.mil/gns"/>)
1438                                    into Shapefile format.
1439                                    The above web-site offer to download named places
1440                                    information grouped by countries for all of the world
1441                                    except USA for which other data are provided.
1442                                    </para>
1443                                    <para>
1444                                    If you download and unpack a package, you will have
1445                                    a text-file with suffix .txt.
1446                                    Selecting such a file via gns2shp will create the
1447                                    corresponding Shapefile with the same basename and
1448                                    place it in the same direcory. Afterwards it
1449                                    is automatically loaded into Thuban.
1450                                    The Shapefile will not automatically be delete afterwards.
1451                                    </para>
1452                                    <para>
1453                                    The gns2shp.py module can also be executed on the
1454                                    command line for batch processing purposes.
1455                                    </para>
1456                                    <para>
1457                                    A sample (<literal>ls.txt</literal> for Liechtenstein)
1458                                    is included in the directory
1459                                    <literal>Extensions/gns2shp/test</literal>.
1460                                    </para>
1461                            </section>
1462                    </section>
1463                    <section><title>Experimental extensions</title>
1464                            <para>
1465                            All all of these functions have to be handled with care,
1466                            since they are neither complete nor well tested.
1467                            They are to be seen as a proof-of-concept and may
1468                            additionally in some cases of practical help.
1469                            </para>
1470                            <para>
1471                            Any interest on further improvement of these extensions
1472                            should be communicated towards the developer and user
1473                            community.
1474                            </para>
1475    
1476                            <section><title>importAPR</title>
1477                                    <para>
1478                                    This command offer to load an ESRI� ArcView� project
1479                                    file (suffix .apr) and convert it for use within Thuban.
1480                                    After selecting a apr-file to load, a list
1481                                    will be presented that offers to select one of the views
1482                                    of the apr-file, provided there is more than one.
1483                                    Furthermore, the Session Info-Tree is extended with
1484                                    a complete representation of the parsed apr-file.
1485                                    </para>
1486                                    <para>
1487                                    The legend of Thuban does not yet cover all of the elements as
1488                                    supported by the legend of ArcView�. Therefore, the Thuban
1489                                    map will look different. Furthermore, the apr-format is
1490                                    a proprietary format, not openly documented.
1491                                    Therefore, the interpretation is
1492                                    partly based on reverse engeneering and good guessing.
1493                                    </para>
1494                                    <para>
1495                                    The file-paths within the apr-file may not fit and potentially
1496                                    are subject to fix in the apr-file. You can do this
1497                                    applying any text editor. The paths are either absolute
1498                                    or relative from where Thuban has been started.
1499                                    </para>
1500                                    <para>
1501                                    A sample for the Iceland data is included as
1502                                    <literal>Extensions/importAPR/samples/iceland.apr</literal>.
1503                                    The file-paths are relative from the Thuban main directory.
1504                                    </para>
1505                            </section>
1506                    </section>
1507            </section>
1508    
1509            <section><title>Writing simple extensions</title>
1510                    <para>
1511                    Writing an extension for Thuban basically means to
1512                    implement the extra functionality in Python with all of the
1513                    Thuban classes, methods and variables available.
1514                    </para>
1515                    <para>
1516                    All classes and their methods are documented in the source code
1517                    (see their doc-strings). Here is an example from
1518                    Thuban/Model/layer.py that describes some of the methods
1519                    of a Layer object:
1520                    </para>
1521                    <programlisting>
1522                    <![CDATA[
1523    class BaseLayer(TitledObject, Modifiable):
1524    
1525        """Base class for the layers."""
1526    
1527        def __init__(self, title, visible = True, projection = None):
1528            """Initialize the layer.
1529    
1530            title -- the title
1531            visible -- boolean. If true the layer is visible.
1532            """
1533            TitledObject.__init__(self, title)
1534            Modifiable.__init__(self)
1535            self.visible = visible
1536            self.projection = projection
1537    
1538        def Visible(self):
1539            """Return true if layer is visible"""
1540            return self.visible
1541    
1542        def SetVisible(self, visible):
1543            """Set the layer's visibility."""
1544            self.visible = visible
1545            self.issue(LAYER_VISIBILITY_CHANGED, self)
1546    
1547        def HasClassification(self):
1548            """Determine if this layer support classifications."""
1549    ...
1550                    ]]>
1551                    </programlisting>
1552                    <para>
1553                    This example intends to give you an impression of the
1554                    source-code-level documentation.
1555                    You have to make yourself familiar with
1556                    the Python programming language to understand some special
1557                    code elements.
1558                    </para>
1559                    <section><title>hello_world.py</title>
1560                      <para>
1561                      Traditionally, the first example should welcome the world.
1562                      Most of the code handles the frame for integrating a menu
1563                      item into Thuban while the actual raising of a message
1564                      is done in a single line.
1565                      </para>
1566                            <programlisting>
1567                            <![CDATA[
1568    # Copyright (C) 2003 by Intevation GmbH
1569    # Authors:
1570    # Jan-Oliver Wagner <[email protected]>
1571    #
1572    # This program is free software under the GPL (>=v2)
1573    # Read the file COPYING coming with Thuban for details.
1574    
1575    """
1576    Extend Thuban with a sample Hello World to demonstrate simple
1577    extensions.
1578    """
1579    
1580    __version__ = '$Revision$'
1581    
1582    # use _() already now for all strings that may later be translated
1583    from Thuban import _
1584    
1585    # Thuban has named commands which can be registered in the central
1586    # instance registry.
1587    from Thuban.UI.command import registry, Command
1588    
1589    # The instance of the main menu of the Thuban application
1590    # See Thuban/UI/menu.py for the API of the Menu class
1591    from Thuban.UI.mainwindow import main_menu
1592    
1593    def hello_world_dialog(context):
1594        """Just raise a simple dialog to greet the world.
1595    
1596        context -- The Thuban context.
1597        """
1598        context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
1599    
1600    
1601    # create a new command and register it
1602    registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
1603                         helptext = _('Welcome everyone on this planet')))
1604    
1605    # find the extensions menu (create it anew if not found)
1606    extensions_menu = main_menu.find_menu('extensions')
1607    if extensions_menu is None:
1608        extensions_menu = main_menu.InsertMenu('extensions', _('E&xtensions'))
1609    
1610    # finally bind the new command with an entry in the extensions menu
1611    extensions_menu.InsertItem('hello_world')
1612                            ]]>
1613                            </programlisting>
1614                    </section>
1615                    <section><title>Registering a Command</title>
1616                      <para>
1617                      Mainly, our new function has to be registered to the Thuban
1618                      framework in order to connect it to the menu. A registered
1619                      command can also be connected to e.g. a toolbar button.
1620                      </para>
1621                      <para>
1622                      The instances and classes for this are imported at the beginning.
1623                      Any code not inside a method or class is directly executed when
1624                      the source-code module is imported. Therefore, the second
1625                      part of this example consist of the plain statements to create a new
1626                      Command and to add it to the menu.
1627                      </para>
1628                      <para>
1629                      By convention, it looks for a menu registered as ``extensions'' to
1630                      insert the new command. If it does not exist yet, it gets created.
1631                      It is advisable to copy this code for any of your extensions.
1632                      </para>
1633                    </section>
1634                    <section><title>The Thuban context</title>
1635                            <para>
1636                            A registered command that is called, always receives the
1637                            Thuban context. This instance provides our method with
1638                            hook references to all important components of the Thuban
1639                            application.
1640                            </para>
1641                            <para>
1642                    In the example hello_world.py, our function uses the
1643                            mainwindow component which offers a method to raise a
1644                            message dialog. In total there are three hooks:
1645                            <itemizedlist>
1646                            <listitem>
1647                            <para>application:
1648                            This object is the instance of the Thuban Application class.
1649                            Except maybe for loading or savinf sessions, you will not
1650                            need this object for a simple extension.
1651                            See Thuban/UI/application.py for the API.
1652                            </para>
1653                            </listitem>
1654                            <listitem>
1655                            <para>session:
1656                            The instance of the current session. It manages the sessions'
1657                            map and tables. You can set and remove the map or tables.
1658                            In may also get the map object. However, you should know that
1659                            internally it is already prepared to handle many maps.
1660                            Therfore, currently you would always receive a list with exactlty
1661                            one element. In the future, if there are more than one map,
1662                            you will not know which one is the currently display one and
1663                            therefore you should use the mainwindow as hook to find
1664                            the currently displayed map.
1665                            See Thuban/Model/session.py for the API.
1666                            </para>
1667                            </listitem>
1668                            <listitem>
1669                            <para>
1670                            mainwindow: The mainwindow object is central to manage various
1671                            GUI things such as the Legend sub-window. Most notably,
1672                            you get access to the canvas which is the window part where
1673                            the map is drawn. The canvas knows, which map it currently
1674                            draws and therefore you get the current map via
1675                            context.mainwindow.canvas.Map().
1676                            See Thuban/UI/mainwindow.py for the API.
1677                            </para>
1678                            </listitem>
1679                            </itemizedlist>
1680                </para>
1681                    </section>
1682            </section>
1683      </chapter>
1684    
1685    <chapter><title>Trouble Shooting</title>    <chapter><title>Trouble Shooting</title>
1686      <para>      <para>
1687        Here are a few problems that users have encountered when first using Thuban.
1688      </para>      </para>
1689      <variablelist>      <para>
1690    
1691      <varlistentry>      <itemizedlist>
     <term>After adding two or more layers nothing is being drawn in the  
     map window.  
     </term>  
1692      <listitem>      <listitem>
1693        <para>After adding two or more layers nothing is drawn in the map window.
1694        </para>
1695      <para>      <para>
1696      This is probably because the layers have different projections. Projections      This is probably because the layers have different projections. Projections
1697      must be set on all layers and on the map itself if the layer's projections      must be set on all layers and on the map itself if the layers' projections
1698      are different.      are different.
1699      </para>      </para>
1700      </listitem>      </listitem>
     </varlistentry>  
1701    
     <varlistentry>  
     <term>Thuban crashes on startup with the error  
         <literal>NameError: global name 'False' is not defined</literal>.  
     </term>  
1702      <listitem>      <listitem>
1703        <para>Thuban crashes on startup with the error
1704            <literal>NameError: global name 'False' is not defined</literal>.
1705        </para>
1706      <para>      <para>
1707      <varname>True</varname> and <varname>False</varname> were only introduced      <varname>True</varname> and <varname>False</varname> were only introduced
1708      in Python 2.2.1. Thuban depends on at least Python 2.2.1.      in Python 2.2.1. Thuban depends on at least Python 2.2.1.
1709      </para>      </para>
1710      </listitem>      </listitem>
     </varlistentry>  
1711    
1712      <varlistentry>      <listitem>
1713      <term>After compiling Thuban, Thuban crashes with an error similar to      <para>After compiling Thuban, Thuban crashes with an error similar to
1714          <literal>          <literal>
1715          ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0          ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0
1716          </literal>          </literal>
1717      </term>      </para>
     <listitem>  
1718      <para>      <para>
1719      Thuban depends on the wxWindows library. If Thuban is compiled with an      Thuban depends on the wxWindows library. If Thuban is compiled with an
1720      incompatible version of the compiler than wxWindows was compiled with      incompatible version of the compiler than wxWindows was compiled with
# Line 1141  Line 1722 
1722      compiler.      compiler.
1723      </para>      </para>
1724      </listitem>      </listitem>
1725      </varlistentry>      </itemizedlist>
1726      </variablelist>      </para>
1727        <para>
1728        If an error occurs Thuban will display a dialog indicating the error
1729        before closing. The text should be copied and reported to the
1730        <ulink url="http://thuban.intevation.org/bugtracker.html">
1731        Intevation bugtracker
1732        </ulink>.
1733        More information about the system is available from
1734        <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.
1735        This should also be included in the bug report.
1736        <figure>
1737        <title>Error Dialog</title>
1738        <mediaobject>
1739        <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>
1740        <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>
1741        </mediaobject>
1742        </figure>
1743        </para>
1744    
1745    </chapter>    </chapter>
1746    
# Line 1178  Line 1776 
1776      </listitem>      </listitem>
1777      </varlistentry>      </varlistentry>
1778    
1779        <varlistentry>
1780        <term>Raster files</term>
1781        <listitem>
1782            <para>
1783            Binding the GDAL library Thuban supports numerous raster file formats,
1784            see <ulink url="http://www.remotesensing.org/gdal/formats_list.html">
1785            GDAL format list</ulink> for details.</para>
1786    
1787            <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
1788            format: Raster maps are provided as TIFF images, with an additional
1789            "world file" storing the geographic reference (usually with an
1790            extension ".tfw").
1791            </para>
1792        </listitem>
1793        </varlistentry>
1794    
1795      </variablelist>      </variablelist>
1796    </appendix>    </appendix>
1797    
# Line 1186  Line 1800 
1800      The following types of projections are directly support by      The following types of projections are directly support by
1801      Thuban. The specific values for each are provided by the user      Thuban. The specific values for each are provided by the user
1802      to create custom projections. Thuban comes with predefined      to create custom projections. Thuban comes with predefined
1803      projections and are available through the Projections dialog.      projections which are available through the Projections dialog.
1804        </para>
1805        <itemizedlist>
1806        <listitem>
1807            <para>Geographic</para>
1808            <itemizedlist>
1809            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1810            <listitem><para>
1811                    <literal>Source Data</literal>: either Degrees or Radians
1812                    </para></listitem>
1813            </itemizedlist>
1814        </listitem>
1815        <listitem>
1816            <para>Lambert Conic Conformal</para>
1817        <itemizedlist>
1818            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1819            <listitem><para><literal>Latitude of 1st standard parallel</literal></para></listitem>
1820            <listitem><para><literal>Latitude of 2nd standard parallel</literal></para></listitem>
1821            <listitem><para><literal>Central Meridian</literal></para></listitem>
1822            <listitem><para><literal>Latitude of Origin</literal></para></listitem>
1823            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
1824            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
1825        </itemizedlist>
1826        </listitem>
1827        <listitem>
1828            <para>Transverse Mercator</para>
1829        <itemizedlist>
1830            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1831            <listitem><para><literal>Latitude</literal>of origin</para></listitem>
1832            <listitem><para><literal>Longitude</literal>at central meridian</para></listitem>
1833            <listitem><para><literal>Scale Factor</literal>at central meridian</para></listitem>
1834            <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
1835            <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
1836        </itemizedlist>
1837        </listitem>
1838        <listitem>
1839            <para>Universal Transverse Mercator</para>
1840        <itemizedlist>
1841            <listitem><para><literal>Ellipsoid</literal></para></listitem>
1842            <listitem><para><literal>Zone</literal>
1843                    (can be guessed appling the Propose button)</para></listitem>
1844            <listitem><para><literal>Southern Hemisphere</literal> flag</para></listitem>
1845        </itemizedlist>
1846        </listitem>
1847        </itemizedlist>
1848        
1849        <para>
1850        Thuban comes with a sample set of map projections for various
1851        European countries. Apart from the basic projection they differ
1852        especially in their parameterization:
1853        </para>
1854        <itemizedlist>
1855        <listitem><para>Belgium Datum 1972 (Lambert Conic Conformal)</para>
1856        </listitem>
1857    
1858        <listitem><para>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</para>
1859        </listitem>
1860    
1861        <listitem><para>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)
1862        </para>
1863        </listitem>
1864    
1865        <listitem><para>Reseau Geodesique Francaise
1866        (France, Lambert Conic Conformal)</para>
1867        </listitem>
1868    
1869        <listitem><para>UK National Grid (United Kingdom, Transverse Mercartor)
1870        </para>
1871        </listitem>
1872        </itemizedlist>
1873    
1874        <para>
1875        Thuban uses the comprehensive PROJ library for projections. PROJ provides
1876        more than the four commonly used projections described above. If needed
1877        Thuban can be easily extended to a new projection covered by PROJ.
1878      </para>      </para>
     <variablelist>  
     <varlistentry>  
     <term>Geographic</term>  
     <listitem><para></para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Lambert Conic Conformal</term>  
     <listitem><para></para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Transverse Mercator</term>  
     <listitem><para></para></listitem>  
     </varlistentry>  
     <varlistentry>  
     <term>Universal Transverse Mercator</term>  
     <listitem><para></para></listitem>  
     </varlistentry>  
     </variablelist>  
1879    </appendix>    </appendix>
1880    
1881  </book>  </book>
Legend:
Removed from v.1496  
changed lines
  Added in v.1744
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26