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

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

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

trunk/thuban/Doc/manual/thuban-manual.xml revision 1719 by jan, Fri Sep 19 09:17:10 2003 UTC branches/WIP-pyshapelib-bramz/Doc/manual/thuban-manual.xml revision 2734 by bramz, Thu Mar 1 12:42:59 2007 UTC
# Line 2  Line 2 
2  <!DOCTYPE book  <!DOCTYPE book
3          PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"          PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
5      [<!ENTITY imgscale "70">]>      [<!ENTITY imgscale "60">]>
6  <!-- $Revision$ -->  <!-- $Revision$ -->
7  <book>  <book>
8    <bookinfo>    <bookinfo>
9      <title>User's Manual for Thuban 1.0</title>      <title>User's Manual for Thuban 1.2 (Draft)</title>
10          <authorgroup>          <authorgroup>
11        <author>        <author>
12          <firstname>Jonathan</firstname><surname>Coles</surname>          <firstname>Jonathan</firstname><surname>Coles</surname>
# Line 19  Line 19 
19        </author>        </author>
20          </authorgroup>          </authorgroup>
21      <copyright>      <copyright>
22        <year>2003</year>        <year>2003, 2004, 2005, 2006, 2007</year>
23        <holder>Intevation GmbH</holder>        <holder>Intevation GmbH</holder>
24      </copyright>      </copyright>
25     <revhistory>     <revhistory>
26  <!-- comment this first revision out when releasing a real version -->  <!-- comment this first revision out when releasing a real version -->
27  <!--  <!--
28       <revision>       <revision>
29          <revnumber>CVS version $Id$</revnumber>          <revnumber>SVN version $Id$</revnumber>
30          <date></date>          <date></date>
31          <revremark>Under development.</revremark>          <revremark>Under development.</revremark>
32       </revision>       </revision>
33  -->  -->
34       <revision>       <revision>
35            <revnumber>1.2.0</revnumber>
36            <date>20-Feb-2007</date>
37            <revremark>
38                            Removed all installation instructions in favor
39                            of a link to the website. It is not wise to
40                            double the README contents here.
41                    </revremark>
42         </revision>
43         <revision>
44            <revnumber>1.0.0</revnumber>
45            <date>22-Jan-2004</date>
46            <revremark>
47                            Corresponds to Thuban 1.0.0.
48                            New: Installation instructions for Win32.
49                    </revremark>
50         </revision>
51         <revision>
52            <revnumber>1.0pre3</revnumber>
53            <date>04-Dec-2003</date>
54            <revremark>
55                            Corresponds to Thuban 1.0rc1.
56                            New: I18n, right button legend menu, EPSG projectons,
57                PostGIS support.
58                    </revremark>
59         </revision>
60         <revision>
61          <revnumber>1.0pre2</revnumber>          <revnumber>1.0pre2</revnumber>
62          <date>29-Aug-2003</date>          <date>29-Aug-2003</date>
63          <revremark>          <revremark>
# Line 51  Line 77 
77    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
78      <para>      <para>
79      Thuban is an interactive geographic data viewer.      Thuban is an interactive geographic data viewer.
80      It has been developed because there was no simple interactive      Its development had been started because there was no simple interactive
81      viewer for geographic information available as Free Software. Thuban is      viewer for geographic information available as Free Software. Thuban is
82      written in Python and C++ and uses the wxWindows library allowing it to      written mainly in Python and uses the wxWidgets (former wxWindows)
83        library allowing it to
84      run on many different platforms, including GNU/Linux and Windows.      run on many different platforms, including GNU/Linux and Windows.
85      </para>      </para>
86      <para>      <para>
# Line 67  Line 94 
94      </para>      </para>
95      <para>      <para>
96      Thuban arranges a session in a hierarchy. A session contains a map which      Thuban arranges a session in a hierarchy. A session contains a map which
97      consists of layers. Each layer represents one kind of data set. For      consists of layers. Each layer represents a data set. For
98      instance, there may be a layer for roads and another layer for buildings.      instance, there may be a layer for roads and another layer for buildings.
99      These layers can either be vector shapes or images.      These layers can either be vector shapes or images.
100      </para>      </para>
101    
102          <section><title>Installation</title>          <section><title>Installation</title>
103          <para>          <para>
104          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,          Thuban is actively supported under Debian 4.0 (Etch)
105          and Windows 2000. Thuban depends on the following packages. These          and Windows (XP). Of course it is possible to run Thuban
106          packages can also be found on the          on a variety of other platforms.
107          <ulink url="http://thuban.intevation.org/download.html">  
108          Thuban Download site          Please check <ulink url="http://thuban.intevation.org/">
109          </ulink>.          Thuban's Website
110          <itemizedlist>          </ulink> about how to install Thuban and the lastest information
111              <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>          about the supported platforms.
112              <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>          </para>
113              <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>          </section>
             <listitem><para>proj 4.4.5 Projection Library (<literal>http://www.remotesensing.org/proj/</literal>)</para></listitem>  
             <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>  
             <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>  
             <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>  
             </itemizedlist>  
         </para>  
                 <para>  
                 Along with the source codes, the download page also offers  
                 full installation packages for Debian, Windows and RPM-based systems  
                 (Mandrake, RedHat, SuSE, etc).  
                 </para>  
                 <section><title>RPM-based GNU/Linux Systems</title>  
                         <section><title>Installing Binary Packages</title>  
                                 <para>  
                                 The most wide-spread RPM-based GNU/Linux Systems are RedHat,  
                                 Mandrake and SuSE. The documentation of these distributions  
                                 should contain information about how to install third-party  
                                 RPM packages. Nonetheless, a short summary is provided here.  
                                 </para>  
                                 <para>  
                                 RPM packages can be installed applying several tools.  
                                 The most basic one is the command line program "rpm".  
                                 The hardware architecture is identified in the name  
                                 of RPM packages, eg. 'i386' for most Intel/AMD architectures.  
                                 If you have a different hardware architecture, where no  
                                 binary RPM packages are provided, you must rebuild binary  
                                 packages from the RPM source packages first (see below).  
                                 Typical rpm commands look like:  
   
                                 <programlisting>  
                                 rpm --install Thuban-0.9.0-1.i386.rpm  
                                 </programlisting>  
   
                                 Depending on what you already have installed on your  
                                 system, you are informed that some packages are  
                                 required, but not installed. You need to install them  
                                 first. Either they are provided by your GNU/Linux distributor  
                                 or available somewhere on the Internet.  
                                 The more essential and special ones are provided together  
                                 with the Thuban package.  
                                 </para>  
   
                                 <para>  
                                 For rpm exist some graphical user interfaces, notably  
                                 kpackage, GnoRPM and xrpm.  
                                 </para>  
   
                                 <para>  
                                 Make yourself familiar with one of the tools and apply it  
                                 to install the packages.  
                                 Note, that you need to be administrator (root) for the system  
                                 to do that.  
                                 </para>  
                         </section>  
                         <section><title>Build Binaries from Source Packages</title>  
                                 <para>  
                                 This section describes howto build RPM install-packages  
                                 from RPM source-packages.  
                                 This adapts and optimizes an install-package specifically  
                                 to your system.  
                                 This is especially helpful to resolve version conflicts of  
                                 dependent packages. Furthermore, install-packages for other  
                                 platforms (e.g. PowerPC) can be created.  
                                 </para>  
   
                                 <para>  
                                 Note: rpm must be at least version 4. Execute  
                                 <literal>rpm --version</literal> to find out about the version.  
                                 </para>  
114    
115                                  <para>          <section><title>Internationalization</title>
116                                  You need to do the following preparations to be able to          <para>
117                                  build the packages as a regular user. You should now          Thuban is implemented with internationalization support. So far Thuban
118                                  perform the package buling as root since this          is translated by volunteers to the following languages (apart from its
119                                  might cause damage to your system.          main language: English):
120                          <itemizedlist>          <itemizedlist>
121                          <listitem>              <listitem><para>French</para></listitem>
122                                                  <para>              <listitem><para>German</para></listitem>
123                                                  Create RPM directory structure:              <listitem><para>Italian</para></listitem>
124                                                  Choose a directory (e.g. $HOME/myrpm) and create the                  <listitem><para>Portuguese (Brazilian)</para></listitem>
125                                                  subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.              <listitem><para>Russian</para></listitem>
126                                                  A possible command sequence for this is:              <listitem><para>Spanish</para></listitem>
127                                                  <programlisting>          </itemizedlist>
128                                                  mkdir $HOME/freegisrpm          </para>
                                                 cd $HOME/freegisrpm  
                                                 mkdir BUILD RPMS SOURCES SPECS SRPMS  
                                                 </programlisting>  
                                                 </para>  
                                         </listitem>  
                                         <listitem>  
                                                 <para>  
                                                 Set environment variable RPM_DIR:  
                                                 <programlisting>  
                                                 export RPM_DIR=$HOME/freegisrpm  
                                                 </programlisting>  
                                                 </para>  
                                         </listitem>  
                                         <listitem>  
                                                 <para>  
                                                 Create $HOME/.rpmmacros:  
                                                 This file sets general preferences and some  
                                                 specific settings for signing packages.  
                                                 If you don't have a GnuPG-key, you can skip  
                                                 the signature settings i.e. drop the last 4 lines.  
                                                 A signature becomes important when you want to  
                                                 give away packages to third parties.  
                                                 <programlisting>  
 <![CDATA[  
 %packager Name Lastname <[email protected]>  
   
 %_topdir /home/mylogin/myrpm  
   
 %_signature gpg  
 %_gpg_name Name Lastname  
 %_pgp_path ~/.gnupg  
 %_pgpbin /usr/bin/gpg  
 ]]>  
                                                 </programlisting>  
                                                 </para>  
                                         </listitem>  
                         </itemizedlist>  
   
                                 Now you can install any RPM source-package.  
                                 It's components are installed into the corresponding  
                                 subdirectories of your rpm-directory.  
                                 Essentially these are the sources (into directory SOURCES)  
                                 and the so-called spec-file which contains all build  
                                 instructions. The spec-file will go into the SPEC directory.  
                                 Example:  
                                 <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>  
                                 </para>  
129    
130                                  <para>          <para>
131                                  Create install-package:          To use internationalization under POSIX systems (like GNU/Linux)
132                                  Go to the directory with the spec-files and rebuild the          you have to set the environment variable LC_ALL accordingly (e.g.
133                                  package:          LC_ALL=fr_FR for the french language support). Please check your
134                                  <programlisting>          systems documentation for details and supported settings.
135  cd $HOME/mypm/SPECS          Specifiying LC_ALL on the command line while launching thuban
136  rpm -bb thuban.spec          allows appication specific language settings:
137                                  </programlisting>          </para>
138                                  Next, you will find the newly created package in          <programlisting>
139                                  $HOME/myrpm/RPMS/i386.          LC_ALL=fr_FR thuban.py
140                                  If you build the package for another architecture than          </programlisting>
141                                  i386, then the name of the directory has a corresponding name.  
142                                  </para>          <para>
143                                  <para>          MS Windows users have to specify the language to be used via the control
144                                  For documentation of RPM, either type          bar (which effects all applications).
145                                  <literal>man rpm</literal> or <literal>rpm --help</literal>.          </para>
146                                  This will provide you with information on the various command          </section>
                                 line options of RPM.  
                                 For more information see the  
                         <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.  
                                 </para>  
                         </section>  
                 </section>  
         </section>  
147    
148          <section><title>The Main Window</title>          <section><title>The Main Window</title>
149          <para>          <para>
# Line 305  rpm -bb thuban.spec Line 209  rpm -bb thuban.spec
209          If a session is already loaded and has been modified without          If a session is already loaded and has been modified without
210          being saved a prompt will ask if the current session should          being saved a prompt will ask if the current session should
211          be saved. A new session consists of an empty map with no          be saved. A new session consists of an empty map with no
212          layers and no tables.          layers, no tables and no projection.
213          </para>          </para>
214          </section>          </section>
215    
# Line 319  rpm -bb thuban.spec Line 223  rpm -bb thuban.spec
223          for a Thuban Session file. Thuban session files end with          for a Thuban Session file. Thuban session files end with
224          <varname>.thuban</varname>. Selecting a file a clicking          <varname>.thuban</varname>. Selecting a file a clicking
225          <guibutton>OK</guibutton> will load the session into Thuban.          <guibutton>OK</guibutton> will load the session into Thuban.
226                    </para>
227    
228                    <para>
229          If a session is already loaded and has been modified without          If a session is already loaded and has been modified without
230          being saved a prompt will ask if the current session should          being saved a prompt will ask if the current session should
231          be saved.          be saved.
232          </para>          </para>
233                    
234                    <para>
235                    Thuban provides a path recovery feature: If a (shape) file referenced
236                    in a Thuban session cannot be found at the specified location, the user
237                    is prompted a file dialog. Here a new location can be selected for the
238                    currents layer data source. Cancelling the dialog removes the layer
239                    from the session. If a new location has been selected, Thuban checks
240                    this again, if further layers data sources are missing. The user is
241                    informed about this and can accept or cancel the suggestion.
242            </para>
243          </section>          </section>
244    
245          <section><title>Saving a Session</title>          <section><title>Saving a Session</title>
# Line 332  rpm -bb thuban.spec Line 248  rpm -bb thuban.spec
248          <menuchoice>          <menuchoice>
249          <guimenu>File</guimenu>          <guimenu>File</guimenu>
250          <guimenuitem>Save Session</guimenuitem>          <guimenuitem>Save Session</guimenuitem>
251          </menuchoice>. A dialog box will open allowing the user to browse          </menuchoice>.
252                    In the case the session is not a new and unsaved one,
253                    the corresponding file is updated with the current session
254                    data.
255                    In the case the current session is a new one and yet unsaved
256                    a dialog box will open allowing the user to browse
257          the file system and select a place to save the session. Thuban          the file system and select a place to save the session. Thuban
258          sessions should be saved under a name ending in          sessions should be saved under a name ending in
259          <varname>.thuban</varname>. If the file already exists the user          <varname>.thuban</varname>. If the file already exists the user
# Line 391  rpm -bb thuban.spec Line 312  rpm -bb thuban.spec
312    
313          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
314          <para>          <para>
315          There are two types of layers that can be added to a map: Shape layers          There are three types of layers that can be added to a map:
316            Shape layers, database layers
317          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
318          widely used file format for storing geographic objects. These          widely used file format for storing geographic objects. These
319          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
# Line 401  rpm -bb thuban.spec Line 323  rpm -bb thuban.spec
323          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
324          also be a file roads.dbf.          also be a file roads.dbf.
325          </para>          </para>
326          <para>          <itemizedlist>
327            <listitem>
328            <para>
329          Shape layers can be added to the map with          Shape layers can be added to the map with
330          <menuchoice>          <menuchoice>
331          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
# Line 417  rpm -bb thuban.spec Line 341  rpm -bb thuban.spec
341                  Use the shift-button together with the left mouse button to extend                  Use the shift-button together with the left mouse button to extend
342                  the selection.                  the selection.
343          </para>          </para>
344            </listitem>
345    
346            <listitem>
347            <para>Database layers can be added to the map with
348            <menuchoice>
349            <guimenu>Map</guimenu>
350            <guimenuitem>Add Database Layer</guimenuitem>
351            </menuchoice>.
352            A dialog with two lists is opened. The left list displays all
353            database connections currently open for the session. You can retrieve
354            a list of available layers from the selected database which is
355            displayed on the right hand. From this list one layer can be selected,
356            the dialog is closed afterwards.
357            </para>
358            <para>
359            See appendix ``Working with PostGIS'' for details.
360            </para>
361            </listitem>
362    
363            <listitem>
364          <para>          <para>
365          Image layers can be added to the map with          Image layers can be added to the map with
366          <menuchoice>          <menuchoice>
# Line 429  rpm -bb thuban.spec Line 372  rpm -bb thuban.spec
372          or in another file. If geographic information cannot be found, Thuban          or in another file. If geographic information cannot be found, Thuban
373          will report an error.          will report an error.
374          </para>          </para>
375            </listitem>
376            </itemizedlist>
377          </section>          </section>
378    
379          <section><title>Navigation</title>          <section><title>Navigation</title>
# Line 720  rpm -bb thuban.spec Line 665  rpm -bb thuban.spec
665          </para>          </para>
666          </listitem>          </listitem>
667          </itemizedlist>          </itemizedlist>
668    
669            <para>
670            The most used layer related actions are also available from a
671            popup menu. It is raised when a layer is clicked with the right mouse
672            button.
673            </para>
674            
675            <para>
676            <figure>
677            <title>Layer Popup Menu</title>
678            <mediaobject>
679            <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
680            <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
681            </mediaobject>
682            </figure>
683            </para>
684    
685          <para>          <para>
686          Along the bottom of the legend is the scalebar. The scalebar          Along the bottom of the legend is the scalebar. The scalebar
687          will be available if there are any layers and the  map has a          will be available if there are any layers and the  map has a
# Line 764  rpm -bb thuban.spec Line 726  rpm -bb thuban.spec
726    
727          <section><title>Types of Layers</title>          <section><title>Types of Layers</title>
728          <para>          <para>
729          There are two types of layers supported by Thuban: shape layers and          There are three types of layers supported by Thuban: shape layers,
730            database layers and
731          image layers. Shape layers consist of vector based shapes with          image layers. Shape layers consist of vector based shapes with
732          geo-referenced coordinates. There are three types of supported          geo-referenced coordinates. There are three types of supported
733          shapes: polygons, lines (arc), and points. Image layers can be any image          shapes: polygons, lines (arc), and points. Database layers are similar
734            to shape layers but loaded from a database instead of the file system.
735            Image layers can be any image
736          file format supported by the Geo-spatial Data Abstraction Library          file format supported by the Geo-spatial Data Abstraction Library
737          (GDAL). The images must have geographic          (GDAL). The images must have geographic
738          coordinate data either embedded within the file or in a separate          coordinate data either embedded within the file or in a separate
# Line 952  rpm -bb thuban.spec Line 917  rpm -bb thuban.spec
917          <section><title>Value</title>          <section><title>Value</title>
918              <para>              <para>
919              The Value column of the classification table is the value that will              The Value column of the classification table is the value that will
920              be matched when the map is being drawn. The type of data that can              be matched when the map is being drawn. The type of filter that can
921              entered into this field depends on the type of data of the              entered into this field depends on the type of data of the
922              classification field.              classification field:
923              </para>              </para>
924              <para>              <para>
925              If the field is of type Text, anything entered              If the field is of type Text, anything entered
926              into the field is valid. The text will be compared literally to the              into the field is valid. By default the text will be compared
927              value of the shape attribute, including case sensitivity.              literally to the
928                value of the shape attribute, including case sensitivity.
929                Alternatively the comparison can be based on regular experessions.
930                Right-click on the row label to open a popup menu with the options
931                <guibutton>Singleton</guibutton> (literal comparison) and  
932                <guibutton>Pattern</guibutton> (regular expressions).  
933                </para>
934                <para>
935              If the type is Integer, then any valid integer may be entered. In              If the type is Integer, then any valid integer may be entered. In
936              addition, with special syntax, a range of values can be entered.              addition, with special syntax, a range of values can be entered.
937              A range from <varname>start</varname> to <varname>end</varname>              A range from <varname>start</varname> to <varname>end</varname>
# Line 970  rpm -bb thuban.spec Line 942  rpm -bb thuban.spec
942              Decimal. They represent any rational number and can be used in              Decimal. They represent any rational number and can be used in
943              ranges as well.              ranges as well.
944              </para>              </para>
945              </section>         </section>
946              <section><title>Label</title>              <section><title>Label</title>
947              <para>              <para>
948              By default, the text that is displayed for a group in the legend              By default, the text that is displayed for a group in the legend
# Line 1099  rpm -bb thuban.spec Line 1071  rpm -bb thuban.spec
1071      </figure>      </figure>
1072      </para>      </para>
1073      <para>      <para>
1074      Thuban is distributed with a sample collection of projections. The      Thuban is distributed with a sample collection of projections and the
1075        set of coordinate systems as used by the EPSG
1076        (European Petroleum Survey Group). This quite large set is only displayed
1077        if activated by the according checkbox. The set falls into two parts:
1078        deprecated lists all projections which are no longer part of the
1079        EPSG data base.
1080        </para>
1081        <para>
1082             The
1083      user can create new projections and make them available to all      user can create new projections and make them available to all
1084      future Thuban sessions. They may also be exported and imported so      future Thuban sessions. They may also be exported and imported so
1085      that custom projections can be distributed.      that custom projections can be distributed.
# Line 1410  rpm -bb thuban.spec Line 1390  rpm -bb thuban.spec
1390                  </para>                  </para>
1391          </section>          </section>
1392    
1393            <section><title>Extensions included in Thuban package</title>
1394                    <para>
1395                    The extensions described in this section are part of the
1396                    Thuban package, but not activated by default.
1397                    You will find them in the Thuban installation directory
1398                    under <literal>Extensions/</literal>. Activate them as personal
1399                    extensions via PYTHONPATH as described in the previous section.
1400                    Stable extensions will appear under the menu
1401                    <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
1402                    extensions which are in experimental state and therefore
1403                    not fully functional under
1404                    <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
1405                    </para>
1406    
1407                    <section><title>Stable extensions</title>
1408                        <para>
1409                        These extensions provide extra-functionality to Thuban
1410                        that has not (yet) been integrated in the main application.
1411                        They are considered to be free of bugs, but may be
1412                        further polished with helpful user interactions.
1413                        </para>
1414                        <section><title>gns2shp</title>
1415                                    <para>
1416                                    This tool converts data of the Geospatial Names Server
1417                                    (GNS, see <ulink url="http://www.nima.mil/gns"/>)
1418                                    into Shapefile format.
1419                                    The above web-site offer to download named places
1420                                    information grouped by countries for all of the world
1421                                    except USA for which other data are provided.
1422                                    </para>
1423                                    <para>
1424                                    If you download and unpack a package, you will have
1425                                    a text-file with suffix .txt.
1426                                    Selecting such a file via gns2shp will create the
1427                                    corresponding Shapefile with the same basename and
1428                                    place it in the same direcory. Afterwards it
1429                                    is automatically loaded into Thuban.
1430                                    The Shapefile will not automatically be delete afterwards.
1431                                    </para>
1432                                    <para>
1433                                    The gns2shp.py module can also be executed on the
1434                                    command line for batch processing purposes.
1435                                    </para>
1436                                    <para>
1437                                    A sample (<literal>ls.txt</literal> for Liechtenstein)
1438                                    is included in the directory
1439                                    <literal>Extensions/gns2shp/test</literal>.
1440                                    </para>
1441                        </section>
1442                        <section><title>SVG Export</title>
1443                            <para>
1444                            Map and legend can be exported separately in the
1445                            Thuban-Map-SVG format.
1446                            You get files that comply with
1447                            the Scalable Vector Graphics (SVG) 1.1 Specification
1448                            and can be read by many vector drawing applications.
1449                            </para>
1450                            <para>
1451                            Goal of svgexport is to provide
1452                            the start of a printing pipeline for Thuban.
1453                            For this purpose the written Thuban-Map-SVG files
1454                            contain information that can be used in postprocessing.
1455                            Typically a general vector drawing application is
1456                            more powerful then a geographic information viewer;
1457                            e.g. having much fancier symbols and fonts.
1458                            Also users benefit much more when learning to use a
1459                            more general application they can also use for other
1460                            tasks.  So the charming idea is to enable
1461                            the drawing application to postprocess a Thuban maps.
1462                            So thee xtra information in the format will make it
1463                            possible to export from Thuban and if a few geoobjects
1464                            change, and keep the general layout and style
1465                            of the full map in the vector drawing appplication.
1466                            </para>
1467                            <para>
1468                            Markus Rechtien has developed a prototype of this
1469                            printing pipline as his Diplom thetis, showing
1470                            the feasability of Bernhard Reiter's concept.
1471                            Scripts exist for the drawing application Skencil
1472                            (<ulink url="http://www.skencil.org"/>).
1473                            </para>
1474                            <para>
1475                            Technical notes: the names of the layers are used
1476                            as base for ids within the SVG format.
1477                            If you try to export with two layers having
1478                            the same name, you will get a name clash error.
1479                            Just change one of the layer names and try again.
1480                            </para>
1481                        </section>
1482                    </section>
1483                    <section><title>Experimental extensions</title>
1484                            <para>
1485                            All all of these functions have to be handled with care,
1486                            since they are neither complete nor well tested.
1487                            They are to be seen as a proof-of-concept and may
1488                            additionally in some cases of practical help.
1489                            </para>
1490                            <para>
1491                            Any interest on further improvement of these extensions
1492                            should be communicated towards the developer and user
1493                            community.
1494                            </para>
1495    
1496                            <section><title>importAPR</title>
1497                                    <para>
1498                                    This command offer to load an ESRI� ArcView� project
1499                                    file (suffix .apr) and convert it for use within Thuban.
1500                                    After selecting a apr-file to load, a list
1501                                    will be presented that offers to select one of the views
1502                                    of the apr-file, provided there is more than one.
1503                                    Furthermore, the Session Info-Tree is extended with
1504                                    a complete representation of the parsed apr-file.
1505                                    </para>
1506                                    <para>
1507                                    The legend of Thuban does not yet cover all of the elements as
1508                                    supported by the legend of ArcView�. Therefore, the Thuban
1509                                    map will look different. Furthermore, the apr-format is
1510                                    a proprietary format, not openly documented.
1511                                    Therefore, the interpretation is
1512                                    partly based on reverse engeneering and good guessing.
1513                                    </para>
1514                                    <para>
1515                                    The file-paths within the apr-file may not fit and potentially
1516                                    are subject to fix in the apr-file. You can do this
1517                                    applying any text editor. The paths are either absolute
1518                                    or relative from where Thuban has been started.
1519                                    </para>
1520                                    <para>
1521                                    A sample for the Iceland data is included as
1522                                    <literal>Extensions/importAPR/samples/iceland.apr</literal>.
1523                                    The file-paths are relative from the Thuban main directory.
1524                                    </para>
1525                            </section>
1526                    </section>
1527            </section>
1528    
1529          <section><title>Writing simple extensions</title>          <section><title>Writing simple extensions</title>
1530                  <para>                  <para>
1531                  Writing an extension for Thuban basically means to                  Writing an extension for Thuban basically means to
# Line 1507  registry.Add(Command('hello_world', _('H Line 1623  registry.Add(Command('hello_world', _('H
1623                       helptext = _('Welcome everyone on this planet')))                       helptext = _('Welcome everyone on this planet')))
1624    
1625  # find the extensions menu (create it anew if not found)  # find the extensions menu (create it anew if not found)
1626  extensions_menu = main_menu.find_menu('extensions')  extensions_menu = main_menu.FindOrInsertMenu('extensions', _('E&xtensions'))
 if extensions_menu is None:  
     extensions_menu = main_menu.InsertMenu('extensions', _('E&xtensions'))  
1627    
1628  # finally bind the new command with an entry in the extensions menu  # finally bind the new command with an entry in the extensions menu
1629  extensions_menu.InsertItem('hello_world')  extensions_menu.InsertItem('hello_world')
# Line 1681  extensions_menu.InsertItem('hello_world' Line 1795  extensions_menu.InsertItem('hello_world'
1795      </varlistentry>      </varlistentry>
1796    
1797      <varlistentry>      <varlistentry>
1798        <term>PostGIS</term>
1799        <listitem>
1800            <para>
1801            PostGIS adds support for geographic objects to the PostgreSQL
1802            object-relational database. Different layer types (as for Shapefiles)
1803            are supported. <ulink url="http://postgis.refractions.net">PostGIS
1804            Homepage</ulink>
1805            </para>
1806        </listitem>
1807        </varlistentry>
1808    
1809        <varlistentry>
1810      <term>Raster files</term>      <term>Raster files</term>
1811      <listitem>      <listitem>
1812          <para>          <para>
# Line 1699  extensions_menu.InsertItem('hello_world' Line 1825  extensions_menu.InsertItem('hello_world'
1825      </variablelist>      </variablelist>
1826    </appendix>    </appendix>
1827    
1828      <appendix><title>Working with PostGIS</title>
1829      <para>
1830      This section focusses on the use of PostGIS in the Thuban framework. For
1831      installation and maintenance of spatial databases we refer to the  
1832      <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
1833      The Thuban PostGIS support requires the
1834      <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
1835      </para>
1836    
1837      <para>
1838            Working with PostGIS Databases is seperated into two steps:
1839            <itemizedlist>
1840            <listitem><para>Opening a Database Connection</para></listitem>
1841            <listitem><para>Loading a Data Layer</para></listitem>
1842            </itemizedlist>
1843      </para>
1844            <section><title>Opening a Database Connection</title>
1845            <para>
1846                    Before a data layer can be loaded from a PostGIS database a
1847                    connection with the database has to be established.
1848                    <menuchoice>
1849                    <guimenu>Session</guimenu>
1850                    <guimenuitem>Database Connections ...</guimenuitem>
1851                    </menuchoice> opens a dialog for database connection
1852                    management. In the dialog new connections can be added
1853                    and existing ones can be removed. Removing a database
1854                    connection is not possible if the map still displays a
1855                    layer provided by this database connection.
1856            </para>
1857        <figure>
1858        <title>Database Management Dialog</title>
1859        <mediaobject>
1860        <imageobject><imagedata fileref="../images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
1861        <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
1862        </mediaobject>
1863        </figure>
1864    
1865            <para>
1866                    To add a new database connection to the session a dialog is
1867                    opened to specify the relevant connection data. Enter all
1868                    data relevant for your connection. If the connection fails
1869                    the dialog remains open and provides some hints on the failure.
1870            </para>
1871            <figure>
1872            <title>Add Database Dialog</title>
1873            <mediaobject>
1874            <imageobject><imagedata fileref="../images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
1875            <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
1876            </mediaobject>
1877            </figure>
1878            
1879            <para>
1880            It is important to note that information on database connections are
1881            also stored with the session. Passwords are NOT stored. If you load a
1882            session with database connections you are asked to enter these
1883            passwords again where required.
1884            </para>
1885    
1886            </section>
1887    
1888            <section><title>Loading a Data Layer</title>
1889            <para>
1890            Data layers as part of a map are loaded with the
1891            <menuchoice>
1892            <guimenu>Map</guimenu>
1893            <guimenuitem>Add Database Layer ...</guimenuitem>
1894            </menuchoice> menu item. A dialog is raised displaying two choice
1895            lists. In the left list all connected databases are shown.
1896            Highlighting
1897            one of these and issuing a retrieval results in a list of available
1898            layer tables from that database. After selection of a
1899            layer the dialog is closed.
1900            </para>
1901            <figure>
1902            <title>Add Database Dialog</title>
1903            <mediaobject>
1904            <imageobject><imagedata fileref="../images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
1905            <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
1906            </mediaobject>
1907            </figure>
1908            
1909            </section>
1910    
1911      </appendix>
1912    
1913    <appendix><title>Supported Projections</title>    <appendix><title>Supported Projections</title>
1914      <para>      <para>
1915      The following types of projections are directly support by      The following types of projections are directly support by
Legend:
Removed from v.1719  
changed lines
  Added in v.2734
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26