/[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 1624 by jan, Thu Aug 21 16:02:17 2003 UTC revision 2670 by frank, Thu Sep 8 16:44:26 2005 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>
# Line 19  Line 19 
19        </author>        </author>
20          </authorgroup>          </authorgroup>
21      <copyright>      <copyright>
22        <year>2003</year>        <year>2003, 2004, 2005</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       <revision>       <revision>
28          <revnumber>1.0pre1 CVS $Id$</revnumber>          <revnumber>CVS version $Id$</revnumber>
29          <date>$Date$</date>          <date></date>
30          <revremark>Under development.</revremark>          <revremark>Under development.</revremark>
31       </revision>       </revision>
32       <revision>       <revision>
33            <revnumber>1.0.0</revnumber>
34            <date>22-Jan-2004</date>
35            <revremark>
36                            Corresponds to Thuban 1.0.0.
37                            New: Installation instructions for Win32.
38                    </revremark>
39         </revision>
40         <revision>
41            <revnumber>1.0pre3</revnumber>
42            <date>04-Dec-2003</date>
43            <revremark>
44                            Corresponds to Thuban 1.0rc1.
45                            New: I18n, right button legend menu, EPSG projectons,
46                PostGIS support.
47                    </revremark>
48         </revision>
49         <revision>
50            <revnumber>1.0pre2</revnumber>
51            <date>29-Aug-2003</date>
52            <revremark>
53                            Corresponds to Thuban development release 0.8.1.
54                            New: chapter on extensions.
55                    </revremark>
56         </revision>
57         <revision>
58          <revnumber>1.0pre1</revnumber>          <revnumber>1.0pre1</revnumber>
59          <date>08-Aug-2003</date>          <date>08-Aug-2003</date>
60          <revremark>Corresponds to Thuban development release 0.8.1</revremark>          <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
61       </revision>       </revision>
62    </revhistory>    </revhistory>
63    
# Line 41  Line 66 
66    <chapter><title>Introduction</title>    <chapter><title>Introduction</title>
67      <para>      <para>
68      Thuban is an interactive geographic data viewer.      Thuban is an interactive geographic data viewer.
69      It has been developed because there was no simple interactive      Its development had been started because there was no simple interactive
70      viewer for geographic information available as Free Software. Thuban is      viewer for geographic information available as Free Software. Thuban is
71      written in Python and C++ and uses the wxWindows library allowing it to      written mainly in Python and uses the wxWidgets (former wxWindows)
72        library allowing it to
73      run on many different platforms, including GNU/Linux and Windows.      run on many different platforms, including GNU/Linux and Windows.
74      </para>      </para>
75      <para>      <para>
# Line 57  Line 83 
83      </para>      </para>
84      <para>      <para>
85      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
86      consists of layers. Each layer represents one kind of data set. For      consists of layers. Each layer represents a data set. For
87      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.
88      These layers can either be vector shapes or images.      These layers can either be vector shapes or images.
89      </para>      </para>
# Line 70  Line 96 
96          <ulink url="http://thuban.intevation.org/download.html">          <ulink url="http://thuban.intevation.org/download.html">
97          Thuban Download site          Thuban Download site
98          </ulink>.          </ulink>.
99            </para>
100            <para>
101            Required:
102          <itemizedlist>          <itemizedlist>
103              <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>              <listitem><para>Python 2.2.1
104              <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>                          (<literal>http://www.python.org</literal>)
105              <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>                          </para></listitem>
106              <listitem><para>proj 4.4.5 Projection Library (<literal>http://www.remotesensing.org/proj/</literal>)</para></listitem>              <listitem><para>wxWindows 2.4
107              <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>                          (<literal>http://www.wxwindows.org</literal>)
108              <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>                          </para></listitem>
109              <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>              <listitem><para>wxPython 2.4
110                            (<literal>http://www.wxpython.org</literal>)
111                            </para></listitem>
112                <listitem><para>proj 4.4.5 Projection Library
113                            (<literal>http://www.remotesensing.org/proj/</literal>)
114                            </para></listitem>
115                <listitem><para>SQLite 2.8.3
116                            <literal>http://www.hwaci.com/sw/sqlite/</literal>)
117                            </para></listitem>
118                <listitem><para>PySQLite 0.4.3
119                            (<literal>http://pysqlite.sourceforge.net</literal>)
120                            </para></listitem>
121            </itemizedlist>
122            </para>
123            <para>
124            Optional:
125            <itemizedlist>
126                <listitem><para>GDAL 1.1.8
127                            (<literal>http://www.remotesensing.org/gdal/</literal>)
128                            </para></listitem>
129                <listitem><para>psycopg 1.0.8
130                            (<literal>http://initd.org/software/psycopg</literal>)
131                            </para></listitem>
132              </itemizedlist>              </itemizedlist>
133          </para>          </para>
134                  <para>                  <para>
135                  Along with the source codes, the download page also offers                  Along with the source codes, the download page also offers full
136                  full installation packages for Debian, Windows and RPM-based systems                  installation packages for Debian, Windows and RPM-based systems
137                  (Mandrake, RedHat, SuSE, etc).                  (Mandrake, RedHat, SuSE, etc).
138                  </para>                  </para>
139                    <section><title>RPM-based GNU/Linux Systems</title>
140                            <section><title>Installing Binary Packages</title>
141                                    <para>
142                                    The most wide-spread RPM-based GNU/Linux
143                                    Systems are RedHat, Mandrake and SuSE.
144                                    The documentation of these distributions
145                                    should contain information about how to
146                                    install third-party RPM packages.
147                                    Nonetheless, a short summary is provided here.
148                                    </para>
149                                    <para>
150                                    RPM packages can be installed applying several
151                                    tools. The most basic one is the command line
152                                    program "rpm".  The hardware architecture is
153                                    identified in the name of RPM packages, eg.
154                                    'i386' for most Intel/AMD architectures.  
155                                    If you have a different hardware architecture,
156                                    where no binary RPM packages are provided,
157                                    you must rebuild binary packages from the
158                                    RPM source packages first (see below).
159                                    Typical rpm commands look like:
160    
161                                    <programlisting>
162                                    rpm --install Thuban-0.9.0-1.i386.rpm
163                                    </programlisting>
164    
165                                    Depending on what you already have installed
166                                    on your system, you are informed that some
167                                    packages are required, but not installed.
168                                    You need to install them first. Either they
169                                    are provided by your GNU/Linux distributor
170                                    or available somewhere on the Internet.  
171                                    The more essential and special ones are
172                                    provided together with the Thuban package.
173                                    </para>
174    
175                                    <para>
176                                    For rpm exist some graphical user interfaces, notably
177                                    kpackage, GnoRPM and xrpm.
178                                    </para>
179    
180                                    <para>
181                                    Make yourself familiar with one of the tools and apply it
182                                    to install the packages.
183                                    Note, that you need to be administrator (root) for the system
184                                    to do that.
185                                    </para>
186                            </section>
187                            <section><title>Build Binaries from Source Packages</title>
188                                    <para>
189                                    This section describes howto build RPM install-packages
190                                    from RPM source-packages.
191                                    This adapts and optimizes an install-package specifically
192                                    to your system.
193                                    This is especially helpful to resolve version conflicts of
194                                    dependent packages. Furthermore, install-packages for other
195                                    platforms (e.g. PowerPC) can be created.
196                                    </para>
197    
198                                    <para>
199                                    Note: rpm must be at least version 4. Execute
200                                    <literal>rpm --version</literal> to find out about the version.
201                                    </para>
202    
203                                    <para>
204                                    You need to do the following preparations to be able to
205                                    build the packages as a regular user. You should now
206                                    perform the package buling as root since this
207                                    might cause damage to your system.
208                            <itemizedlist>
209                            <listitem>
210                                                    <para>
211                                                    Create RPM directory structure:
212                                                    Choose a directory (e.g. $HOME/myrpm) and create the
213                                                    subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.
214                                                    A possible command sequence for this is:
215                                                    <programlisting>
216                                                    mkdir $HOME/freegisrpm
217                                                    cd $HOME/freegisrpm
218                                                    mkdir BUILD RPMS SOURCES SPECS SRPMS
219                                                    </programlisting>
220                                                    </para>
221                                            </listitem>
222                                            <listitem>
223                                                    <para>
224                                                    Set environment variable RPM_DIR:
225                                                    <programlisting>
226                                                    export RPM_DIR=$HOME/freegisrpm
227                                                    </programlisting>
228                                                    </para>
229                                            </listitem>
230                                            <listitem>
231                                                    <para>
232                                                    Create $HOME/.rpmmacros:
233                                                    This file sets general preferences and some
234                                                    specific settings for signing packages.
235                                                    If you don't have a GnuPG-key, you can skip
236                                                    the signature settings i.e. drop the last 4 lines.
237                                                    A signature becomes important when you want to
238                                                    give away packages to third parties.
239                                                    <programlisting>
240    <![CDATA[
241    %packager Name Lastname <[email protected]>
242    
243    %_topdir /home/mylogin/myrpm
244    
245    %_signature gpg
246    %_gpg_name Name Lastname
247    %_pgp_path ~/.gnupg
248    %_pgpbin /usr/bin/gpg
249    ]]>
250                                                    </programlisting>
251                                                    </para>
252                                            </listitem>
253                            </itemizedlist>
254    
255                                    Now you can install any RPM source-package.
256                                    It's components are installed into the corresponding
257                                    subdirectories of your rpm-directory.
258                                    Essentially these are the sources (into directory SOURCES)
259                                    and the so-called spec-file which contains all build
260                                    instructions. The spec-file will go into the SPEC directory.
261                                    Example:
262                                    <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>
263                                    </para>
264    
265                                    <para>
266                                    Create install-package:
267                                    Go to the directory with the spec-files and rebuild the
268                                    package:
269                                    <programlisting>
270    cd $HOME/mypm/SPECS
271    rpm -bb thuban.spec
272                                    </programlisting>
273                                    Next, you will find the newly created package in
274                                    $HOME/myrpm/RPMS/i386.
275                                    If you build the package for another architecture than
276                                    i386, then the name of the directory has a corresponding name.
277                                    </para>
278                                    <para>
279                                    For documentation of RPM, either type
280                                    <literal>man rpm</literal> or <literal>rpm --help</literal>.
281                                    This will provide you with information on the various command
282                                    line options of RPM.
283                                    For more information see the
284                            <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
285                                    </para>
286                            </section>
287                    </section> <!-- Intro - Installation - RPM-->
288    
289                    <section><title>Win32 Systems</title>
290                    <para>
291                            A common installation package of Thuban for Win32
292                            systems is available from the Thuban website download
293                            section. This installation package is configured for
294                            displaying file based vector data (Shapefiles). For the
295                            display of raster data or the connection to spatial
296                            databases additional steps are needed.  
297                    </para>
298                    <para>
299                            The required Python packages are listed and linked on
300                            the download page as well.  If you don't have Python
301                            installed already, download the packages for Python,
302                            wxPython for Python and the SQLite Python Libraries as
303                            well as the Thuban package. Install all four packages
304                            in the order: Python, wxPython, SQLite, Thuban. Follow
305                            the installation instructions provided by the seperate
306                            setups. The Thuban installation package will add an
307                            entry in the menu folder you configured.
308                    </para>
309                    <section><title>Raster Data: Installation of GDAL</title>
310                    <para>
311                            Enabling the raster data features of Thuban is
312                            straight forward. For the examples we assume that
313                            Thuban has been installed under
314                            <literal>C:\Thuban</literal>:
315                            <itemizedlist>
316                            <listitem>
317                            <para>
318                            Download the zip-archive <ulink
319                            url="ftp://intevation.de/thuban/win2k/gdal-win2k.zip"
320                            >gdal-win2k</ulink>.
321                            </para></listitem>
322                            <listitem><para>Extract the archive (e.g. with
323                            <ulink
324                            url="http://www.info-zip.org/pub/infozip/WiZ.html"
325                            >WiZ (InfoZip)</ulink>) into the
326                            <literal>C:\Thuban\Lib</literal>
327                            directory of your Thuban installation.
328                            </para>
329                            </listitem>
330                            <listitem>
331                            <para>
332                            Extent the <varname>PYTHONPATH</varname>
333                            environment variable (in your Windows Control Panel)
334                            to make the new libraries available for Thuban.
335                            <programlisting>
336    %PYTHONPATH%;C:\Thuban\Lib\gdal;C:\Thuban\Lib\gdal\pymod
337                            </programlisting>
338                            </para>
339                            </listitem>
340                            <listitem>
341                            <para>
342                            Extent also the <varname>PATH</varname>
343                            environment variable accordingly:
344                            <programlisting>
345    %PATH%;C:\Thuban\Lib\gdal
346                            </programlisting>
347                            </para>
348                            </listitem>
349                            </itemizedlist>
350                            After this installation steps Thuban is ready to
351                            display raster data (e.g. the
352                            <literal>island.tif</literal> from the Iceland Demo
353                            data set.
354                    </para>
355                    </section> <!-- Win32: GDAL-->
356    
357                    <section><title>Working with PostGIS: Installation of PsycoPG</title>
358                    <para>
359                            To access PostgreSQL/PostGIS spatial databases with
360                            Thuban you have to install the PsycoPG package for
361                            Windows:
362                            <itemizedlist>
363                            <listitem>
364                            <para>
365                            Download the zip-archive
366                            <ulink
367                                    url="http://stickpeople.com/projects/python/win-psycopg/win-psycopg22.zip"
368                            >win-psycopg22.zip</ulink>.
369                            </para>
370                            </listitem>
371                            <listitem>
372                            <para>
373                            Extract the zip-archive into a directory either already
374                            in your <varname>PYTHONPATH</varname> or extent your
375                            <varname>PYTHONPATH</varname> variable to the directory
376                            you have extracted the archive to.
377                            </para>
378                            </listitem>
379                            </itemizedlist>
380                            For installation and maintenance of spatial databases
381                            we refer to the  <ulink
382                            url="http://postgis.refractions.net"
383                            >PostGIS Homepage</ulink>.
384                    </para>
385                    </section> <!-- Win32: PsycoPG-->
386    
387                    </section> <!-- Intro - Installation - Win32 -->
388          </section>          </section>
389    
390            <section><title>Internationalization</title>
391            <para>
392            Thuban is implemented with internationalization support. So far Thuban
393            is translated by volunteers to the following languages (apart from its
394            main language: English):
395            <itemizedlist>
396                <listitem><para>French</para></listitem>
397                <listitem><para>German</para></listitem>
398                <listitem><para>Italian</para></listitem>
399                    <listitem><para>Portuguese (Brazilian)</para></listitem>
400                <listitem><para>Russian</para></listitem>
401                <listitem><para>Spanish</para></listitem>
402            </itemizedlist>
403            </para>
404    
405            <para>
406            To use internationalization under POSIX systems (like GNU/Linux)
407            you have to set the environment variable LC_ALL accordingly (e.g.
408            LC_ALL=fr_FR for the french language support). Please check your
409            systems documentation for details and supported settings.
410            Specifiying LC_ALL on the command line while launching thuban
411            allows appication specific language settings:
412            </para>
413            <programlisting>
414            LC_ALL=fr_FR thuban.py
415            </programlisting>
416    
417            <para>
418            MS Windows users have to specify the language to be used via the control
419            bar (which effects all applications).
420            </para>
421            </section>
422    
423          <section><title>The Main Window</title>          <section><title>The Main Window</title>
424          <para>          <para>
425          <figure>          <figure>
# Line 151  Line 484 
484          If a session is already loaded and has been modified without          If a session is already loaded and has been modified without
485          being saved a prompt will ask if the current session should          being saved a prompt will ask if the current session should
486          be saved. A new session consists of an empty map with no          be saved. A new session consists of an empty map with no
487          layers and no tables.          layers, no tables and no projection.
488          </para>          </para>
489          </section>          </section>
490    
# Line 165  Line 498 
498          for a Thuban Session file. Thuban session files end with          for a Thuban Session file. Thuban session files end with
499          <varname>.thuban</varname>. Selecting a file a clicking          <varname>.thuban</varname>. Selecting a file a clicking
500          <guibutton>OK</guibutton> will load the session into Thuban.          <guibutton>OK</guibutton> will load the session into Thuban.
501                    </para>
502    
503                    <para>
504          If a session is already loaded and has been modified without          If a session is already loaded and has been modified without
505          being saved a prompt will ask if the current session should          being saved a prompt will ask if the current session should
506          be saved.          be saved.
507          </para>          </para>
508                    
509                    <para>
510                    Thuban provides a path recovery feature: If a (shape) file referenced
511                    in a Thuban session cannot be found at the specified location, the user
512                    is prompted a file dialog. Here a new location can be selected for the
513                    currents layer data source. Cancelling the dialog removes the layer
514                    from the session. If a new location has been selected, Thuban checks
515                    this again, if further layers data sources are missing. The user is
516                    informed about this and can accept or cancel the suggestion.
517            </para>
518          </section>          </section>
519    
520          <section><title>Saving a Session</title>          <section><title>Saving a Session</title>
# Line 178  Line 523 
523          <menuchoice>          <menuchoice>
524          <guimenu>File</guimenu>          <guimenu>File</guimenu>
525          <guimenuitem>Save Session</guimenuitem>          <guimenuitem>Save Session</guimenuitem>
526          </menuchoice>. A dialog box will open allowing the user to browse          </menuchoice>.
527                    In the case the session is not a new and unsaved one,
528                    the corresponding file is updated with the current session
529                    data.
530                    In the case the current session is a new one and yet unsaved
531                    a dialog box will open allowing the user to browse
532          the file system and select a place to save the session. Thuban          the file system and select a place to save the session. Thuban
533          sessions should be saved under a name ending in          sessions should be saved under a name ending in
534          <varname>.thuban</varname>. If the file already exists the user          <varname>.thuban</varname>. If the file already exists the user
# Line 237  Line 587 
587    
588          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
589          <para>          <para>
590          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:
591            Shape layers, database layers
592          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
593          widely used file format for storing geographic objects. These          widely used file format for storing geographic objects. These
594          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
# Line 247  Line 598 
598          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
599          also be a file roads.dbf.          also be a file roads.dbf.
600          </para>          </para>
601          <para>          <itemizedlist>
602            <listitem>
603            <para>
604          Shape layers can be added to the map with          Shape layers can be added to the map with
605          <menuchoice>          <menuchoice>
606          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
# Line 263  Line 616 
616                  Use the shift-button together with the left mouse button to extend                  Use the shift-button together with the left mouse button to extend
617                  the selection.                  the selection.
618          </para>          </para>
619            </listitem>
620    
621            <listitem>
622            <para>Database layers can be added to the map with
623            <menuchoice>
624            <guimenu>Map</guimenu>
625            <guimenuitem>Add Database Layer</guimenuitem>
626            </menuchoice>.
627            A dialog with two lists is opened. The left list displays all
628            database connections currently open for the session. You can retrieve
629            a list of available layers from the selected database which is
630            displayed on the right hand. From this list one layer can be selected,
631            the dialog is closed afterwards.
632            </para>
633            <para>
634            See appendix ``Working with PostGIS'' for details.
635            </para>
636            </listitem>
637    
638            <listitem>
639          <para>          <para>
640          Image layers can be added to the map with          Image layers can be added to the map with
641          <menuchoice>          <menuchoice>
# Line 275  Line 647 
647          or in another file. If geographic information cannot be found, Thuban          or in another file. If geographic information cannot be found, Thuban
648          will report an error.          will report an error.
649          </para>          </para>
650            </listitem>
651            </itemizedlist>
652          </section>          </section>
653    
654          <section><title>Navigation</title>          <section><title>Navigation</title>
# Line 566  Line 940 
940          </para>          </para>
941          </listitem>          </listitem>
942          </itemizedlist>          </itemizedlist>
943    
944            <para>
945            The most used layer related actions are also available from a
946            popup menu. It is raised when a layer is clicked with the right mouse
947            button.
948            </para>
949            
950            <para>
951            <figure>
952            <title>Layer Popup Menu</title>
953            <mediaobject>
954            <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
955            <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
956            </mediaobject>
957            </figure>
958            </para>
959    
960          <para>          <para>
961          Along the bottom of the legend is the scalebar. The scalebar          Along the bottom of the legend is the scalebar. The scalebar
962          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 610  Line 1001 
1001    
1002          <section><title>Types of Layers</title>          <section><title>Types of Layers</title>
1003          <para>          <para>
1004          There are two types of layers supported by Thuban: shape layers and          There are three types of layers supported by Thuban: shape layers,
1005            database layers and
1006          image layers. Shape layers consist of vector based shapes with          image layers. Shape layers consist of vector based shapes with
1007          geo-referenced coordinates. There are three types of supported          geo-referenced coordinates. There are three types of supported
1008          shapes: polygons, lines (arc), and points. Image layers can be any image          shapes: polygons, lines (arc), and points. Database layers are similar
1009            to shape layers but loaded from a database instead of the file system.
1010            Image layers can be any image
1011          file format supported by the Geo-spatial Data Abstraction Library          file format supported by the Geo-spatial Data Abstraction Library
1012          (GDAL). The images must have geographic          (GDAL). The images must have geographic
1013          coordinate data either embedded within the file or in a separate          coordinate data either embedded within the file or in a separate
# Line 945  Line 1339 
1339      </figure>      </figure>
1340      </para>      </para>
1341      <para>      <para>
1342      Thuban is distributed with a sample collection of projections. The      Thuban is distributed with a sample collection of projections and the
1343        set of coordinate systems as used by the EPSG
1344        (European Petroleum Survey Group). This quite large set is only displayed
1345        if activated by the according checkbox. The set falls into two parts:
1346        deprecated lists all projections which are no longer part of the
1347        EPSG data base.
1348        </para>
1349        <para>
1350             The
1351      user can create new projections and make them available to all      user can create new projections and make them available to all
1352      future Thuban sessions. They may also be exported and imported so      future Thuban sessions. They may also be exported and imported so
1353      that custom projections can be distributed.      that custom projections can be distributed.
# Line 1242  Line 1644 
1644                  to this file to keep the actual code of extensions separate.                  to this file to keep the actual code of extensions separate.
1645                  </para>                  </para>
1646                  <para>                  <para>
1647                  The modules to import must either be found though the environment                  The modules to import must either be found through the environment
1648                  variable PYTHONPATH or directly be placed into the .thuban-directory.                  variable PYTHONPATH or directly be placed into the .thuban-directory.
1649                  </para>                  </para>
1650                  <para>                  <para>
# Line 1256  Line 1658 
1658                  </para>                  </para>
1659          </section>          </section>
1660    
1661            <section><title>Extensions included in Thuban package</title>
1662                    <para>
1663                    The extensions described in this section are part of the
1664                    Thuban package, but not activated by default.
1665                    You will find them in the Thuban installation directory
1666                    under <literal>Extensions/</literal>. Activate them as personal
1667                    extensions via PYTHONPATH as described in the previous section.
1668                    Stable extensions will appear under the menu
1669                    <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
1670                    extensions which are in experimental state and therefore
1671                    not fully functional under
1672                    <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
1673                    </para>
1674    
1675                    <section><title>Stable extensions</title>
1676                        <para>
1677                        These extensions provide extra-functionality to Thuban
1678                        that has not (yet) been integrated in the main application.
1679                        They are considered to be free of bugs, but may be
1680                        further polished with helpful user interactions.
1681                        </para>
1682                        <section><title>gns2shp</title>
1683                                    <para>
1684                                    This tool converts data of the Geospatial Names Server
1685                                    (GNS, see <ulink url="http://www.nima.mil/gns"/>)
1686                                    into Shapefile format.
1687                                    The above web-site offer to download named places
1688                                    information grouped by countries for all of the world
1689                                    except USA for which other data are provided.
1690                                    </para>
1691                                    <para>
1692                                    If you download and unpack a package, you will have
1693                                    a text-file with suffix .txt.
1694                                    Selecting such a file via gns2shp will create the
1695                                    corresponding Shapefile with the same basename and
1696                                    place it in the same direcory. Afterwards it
1697                                    is automatically loaded into Thuban.
1698                                    The Shapefile will not automatically be delete afterwards.
1699                                    </para>
1700                                    <para>
1701                                    The gns2shp.py module can also be executed on the
1702                                    command line for batch processing purposes.
1703                                    </para>
1704                                    <para>
1705                                    A sample (<literal>ls.txt</literal> for Liechtenstein)
1706                                    is included in the directory
1707                                    <literal>Extensions/gns2shp/test</literal>.
1708                                    </para>
1709                        </section>
1710                        <section><title>SVG Export</title>
1711                            <para>
1712                            Map and legend can be exported separately in the
1713                            Thuban-Map-SVG format.
1714                            You get files that comply with
1715                            the Scalable Vector Graphics (SVG) 1.1 Specification
1716                            and can be read by many vector drawing applications.
1717                            </para>
1718                            <para>
1719                            Goal of svgexport is to provide
1720                            the start of a printing pipeline for Thuban.
1721                            For this purpose the written Thuban-Map-SVG files
1722                            contain information that can be used in postprocessing.
1723                            Typically a general vector drawing application is
1724                            more powerful then a geographic information viewer;
1725                            e.g. having much fancier symbols and fonts.
1726                            Also users benefit much more when learning to use a
1727                            more general application they can also use for other
1728                            tasks.  So the charming idea is to enable
1729                            the drawing application to postprocess a Thuban maps.
1730                            So thee xtra information in the format will make it
1731                            possible to export from Thuban and if a few geoobjects
1732                            change, and keep the general layout and style
1733                            of the full map in the vector drawing appplication.
1734                            </para>
1735                            <para>
1736                            Markus Rechtien has developed a prototype of this
1737                            printing pipline as his Diplom thetis, showing
1738                            the feasability of Bernhard Reiter's concept.
1739                            Scripts exist for the drawing application Skencil
1740                            (<ulink url="http://www.skencil.org"/>).
1741                            </para>
1742                            <para>
1743                            Technical notes: the names of the layers are used
1744                            as base for ids within the SVG format.
1745                            If you try to export with two layers having
1746                            the same name, you will get a name clash error.
1747                            Just change one of the layer names and try again.
1748                            </para>
1749                        </section>
1750                    </section>
1751                    <section><title>Experimental extensions</title>
1752                            <para>
1753                            All all of these functions have to be handled with care,
1754                            since they are neither complete nor well tested.
1755                            They are to be seen as a proof-of-concept and may
1756                            additionally in some cases of practical help.
1757                            </para>
1758                            <para>
1759                            Any interest on further improvement of these extensions
1760                            should be communicated towards the developer and user
1761                            community.
1762                            </para>
1763    
1764                            <section><title>importAPR</title>
1765                                    <para>
1766                                    This command offer to load an ESRI� ArcView� project
1767                                    file (suffix .apr) and convert it for use within Thuban.
1768                                    After selecting a apr-file to load, a list
1769                                    will be presented that offers to select one of the views
1770                                    of the apr-file, provided there is more than one.
1771                                    Furthermore, the Session Info-Tree is extended with
1772                                    a complete representation of the parsed apr-file.
1773                                    </para>
1774                                    <para>
1775                                    The legend of Thuban does not yet cover all of the elements as
1776                                    supported by the legend of ArcView�. Therefore, the Thuban
1777                                    map will look different. Furthermore, the apr-format is
1778                                    a proprietary format, not openly documented.
1779                                    Therefore, the interpretation is
1780                                    partly based on reverse engeneering and good guessing.
1781                                    </para>
1782                                    <para>
1783                                    The file-paths within the apr-file may not fit and potentially
1784                                    are subject to fix in the apr-file. You can do this
1785                                    applying any text editor. The paths are either absolute
1786                                    or relative from where Thuban has been started.
1787                                    </para>
1788                                    <para>
1789                                    A sample for the Iceland data is included as
1790                                    <literal>Extensions/importAPR/samples/iceland.apr</literal>.
1791                                    The file-paths are relative from the Thuban main directory.
1792                                    </para>
1793                            </section>
1794                    </section>
1795            </section>
1796    
1797          <section><title>Writing simple extensions</title>          <section><title>Writing simple extensions</title>
1798                  <para>                  <para>
1799                  Writing an extension for Thuban basically means to                  Writing an extension for Thuban basically means to
# Line 1353  registry.Add(Command('hello_world', _('H Line 1891  registry.Add(Command('hello_world', _('H
1891                       helptext = _('Welcome everyone on this planet')))                       helptext = _('Welcome everyone on this planet')))
1892    
1893  # find the extensions menu (create it anew if not found)  # find the extensions menu (create it anew if not found)
1894  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'))  
1895    
1896  # finally bind the new command with an entry in the extensions menu  # finally bind the new command with an entry in the extensions menu
1897  extensions_menu.InsertItem('hello_world')  extensions_menu.InsertItem('hello_world')
# Line 1527  extensions_menu.InsertItem('hello_world' Line 2063  extensions_menu.InsertItem('hello_world'
2063      </varlistentry>      </varlistentry>
2064    
2065      <varlistentry>      <varlistentry>
2066        <term>PostGIS</term>
2067        <listitem>
2068            <para>
2069            PostGIS adds support for geographic objects to the PostgreSQL
2070            object-relational database. Different layer types (as for Shapefiles)
2071            are supported. <ulink url="http://postgis.refractions.net">PostGIS
2072            Homepage</ulink>
2073            </para>
2074        </listitem>
2075        </varlistentry>
2076    
2077        <varlistentry>
2078      <term>Raster files</term>      <term>Raster files</term>
2079      <listitem>      <listitem>
2080          <para>          <para>
# Line 1545  extensions_menu.InsertItem('hello_world' Line 2093  extensions_menu.InsertItem('hello_world'
2093      </variablelist>      </variablelist>
2094    </appendix>    </appendix>
2095    
2096      <appendix><title>Working with PostGIS</title>
2097      <para>
2098      This section focusses on the use of PostGIS in the Thuban framework. For
2099      installation and maintenance of spatial databases we refer to the  
2100      <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
2101      The Thuban PostGIS support requires the
2102      <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
2103      </para>
2104    
2105      <para>
2106            Working with PostGIS Databases is seperated into two steps:
2107            <itemizedlist>
2108            <listitem><para>Opening a Database Connection</para></listitem>
2109            <listitem><para>Loading a Data Layer</para></listitem>
2110            </itemizedlist>
2111      </para>
2112            <section><title>Opening a Database Connection</title>
2113            <para>
2114                    Before a data layer can be loaded from a PostGIS database a
2115                    connection with the database has to be established.
2116                    <menuchoice>
2117                    <guimenu>Session</guimenu>
2118                    <guimenuitem>Database Connections ...</guimenuitem>
2119                    </menuchoice> opens a dialog for database connection
2120                    management. In the dialog new connections can be added
2121                    and existing ones can be removed. Removing a database
2122                    connection is not possible if the map still displays a
2123                    layer provided by this database connection.
2124            </para>
2125        <figure>
2126        <title>Database Management Dialog</title>
2127        <mediaobject>
2128        <imageobject><imagedata fileref="../images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
2129        <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
2130        </mediaobject>
2131        </figure>
2132    
2133            <para>
2134                    To add a new database connection to the session a dialog is
2135                    opened to specify the relevant connection data. Enter all
2136                    data relevant for your connection. If the connection fails
2137                    the dialog remains open and provides some hints on the failure.
2138            </para>
2139            <figure>
2140            <title>Add Database Dialog</title>
2141            <mediaobject>
2142            <imageobject><imagedata fileref="../images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
2143            <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
2144            </mediaobject>
2145            </figure>
2146            
2147            <para>
2148            It is important to note that information on database connections are
2149            also stored with the session. Passwords are NOT stored. If you load a
2150            session with database connections you are asked to enter these
2151            passwords again where required.
2152            </para>
2153    
2154            </section>
2155    
2156            <section><title>Loading a Data Layer</title>
2157            <para>
2158            Data layers as part of a map are loaded with the
2159            <menuchoice>
2160            <guimenu>Map</guimenu>
2161            <guimenuitem>Add Database Layer ...</guimenuitem>
2162            </menuchoice> menu item. A dialog is raised displaying two choice
2163            lists. In the left list all connected databases are shown.
2164            Highlighting
2165            one of these and issuing a retrieval results in a list of available
2166            layer tables from that database. After selection of a
2167            layer the dialog is closed.
2168            </para>
2169            <figure>
2170            <title>Add Database Dialog</title>
2171            <mediaobject>
2172            <imageobject><imagedata fileref="../images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
2173            <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
2174            </mediaobject>
2175            </figure>
2176            
2177            </section>
2178    
2179      </appendix>
2180    
2181    <appendix><title>Supported Projections</title>    <appendix><title>Supported Projections</title>
2182      <para>      <para>
2183      The following types of projections are directly support by      The following types of projections are directly support by
Legend:
Removed from v.1624  
changed lines
  Added in v.2670
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26