/[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 1744 by jan, Tue Sep 23 15:37:25 2003 UTC revision 2052 by frank, Thu Jan 22 14:40:32 2004 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</year>
23        <holder>Intevation GmbH</holder>        <holder>Intevation GmbH</holder>
24      </copyright>      </copyright>
25     <revhistory>     <revhistory>
# Line 32  Line 32 
32       </revision>       </revision>
33  -->  -->
34       <revision>       <revision>
35            <revnumber>1.0.0</revnumber>
36            <date>22-Jan-2004</date>
37            <revremark>
38                            Corresponds to Thuban 1.0.0.
39                            New: Installation instructions for Win32.
40                    </revremark>
41         </revision>
42         <revision>
43            <revnumber>1.0pre3</revnumber>
44            <date>04-Dec-2003</date>
45            <revremark>
46                            Corresponds to Thuban 1.0rc1.
47                            New: I18n, right button legend menu, EPSG projectons,
48                PostGIS support.
49                    </revremark>
50         </revision>
51         <revision>
52          <revnumber>1.0pre2</revnumber>          <revnumber>1.0pre2</revnumber>
53          <date>29-Aug-2003</date>          <date>29-Aug-2003</date>
54          <revremark>          <revremark>
# Line 80  Line 97 
97          <ulink url="http://thuban.intevation.org/download.html">          <ulink url="http://thuban.intevation.org/download.html">
98          Thuban Download site          Thuban Download site
99          </ulink>.          </ulink>.
100            </para>
101            <para>
102            Required:
103          <itemizedlist>          <itemizedlist>
104              <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>              <listitem><para>Python 2.2.1
105              <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>                          (<literal>http://www.python.org</literal>)
106              <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>                          </para></listitem>
107              <listitem><para>proj 4.4.5 Projection Library (<literal>http://www.remotesensing.org/proj/</literal>)</para></listitem>              <listitem><para>wxWindows 2.4
108              <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>                          (<literal>http://www.wxwindows.org</literal>)
109              <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>                          </para></listitem>
110              <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>              <listitem><para>wxPython 2.4
111                            (<literal>http://www.wxpython.org</literal>)
112                            </para></listitem>
113                <listitem><para>proj 4.4.5 Projection Library
114                            (<literal>http://www.remotesensing.org/proj/</literal>)
115                            </para></listitem>
116                <listitem><para>SQLite 2.8.3
117                            <literal>http://www.hwaci.com/sw/sqlite/</literal>)
118                            </para></listitem>
119                <listitem><para>PySQLite 0.4.3
120                            (<literal>http://pysqlite.sourceforge.net</literal>)
121                            </para></listitem>
122            </itemizedlist>
123            </para>
124            <para>
125            Optional:
126            <itemizedlist>
127                <listitem><para>GDAL 1.1.8
128                            (<literal>http://www.remotesensing.org/gdal/</literal>)
129                            </para></listitem>
130                <listitem><para>psycopg 1.0.8
131                            (<literal>http://initd.org/software/psycopg</literal>)
132                            </para></listitem>
133              </itemizedlist>              </itemizedlist>
134          </para>          </para>
135                  <para>                  <para>
136                  Along with the source codes, the download page also offers                  Along with the source codes, the download page also offers full
137                  full installation packages for Debian, Windows and RPM-based systems                  installation packages for Debian, Windows and RPM-based systems
138                  (Mandrake, RedHat, SuSE, etc).                  (Mandrake, RedHat, SuSE, etc).
139                  </para>                  </para>
140                  <section><title>RPM-based GNU/Linux Systems</title>                  <section><title>RPM-based GNU/Linux Systems</title>
141                          <section><title>Installing Binary Packages</title>                          <section><title>Installing Binary Packages</title>
142                                  <para>                                  <para>
143                                  The most wide-spread RPM-based GNU/Linux Systems are RedHat,                                  The most wide-spread RPM-based GNU/Linux
144                                  Mandrake and SuSE. The documentation of these distributions                                  Systems are RedHat, Mandrake and SuSE.
145                                  should contain information about how to install third-party                                  The documentation of these distributions
146                                  RPM packages. Nonetheless, a short summary is provided here.                                  should contain information about how to
147                                    install third-party RPM packages.
148                                    Nonetheless, a short summary is provided here.
149                                  </para>                                  </para>
150                                  <para>                                  <para>
151                                  RPM packages can be installed applying several tools.                                  RPM packages can be installed applying several
152                                  The most basic one is the command line program "rpm".                                  tools. The most basic one is the command line
153                                  The hardware architecture is identified in the name                                  program "rpm".  The hardware architecture is
154                                  of RPM packages, eg. 'i386' for most Intel/AMD architectures.                                  identified in the name of RPM packages, eg.
155                                  If you have a different hardware architecture, where no                                  'i386' for most Intel/AMD architectures.  
156                                  binary RPM packages are provided, you must rebuild binary                                  If you have a different hardware architecture,
157                                  packages from the RPM source packages first (see below).                                  where no binary RPM packages are provided,
158                                    you must rebuild binary packages from the
159                                    RPM source packages first (see below).
160                                  Typical rpm commands look like:                                  Typical rpm commands look like:
161    
162                                  <programlisting>                                  <programlisting>
163                                  rpm --install Thuban-0.9.0-1.i386.rpm                                  rpm --install Thuban-0.9.0-1.i386.rpm
164                                  </programlisting>                                  </programlisting>
165    
166                                  Depending on what you already have installed on your                                  Depending on what you already have installed
167                                  system, you are informed that some packages are                                  on your system, you are informed that some
168                                  required, but not installed. You need to install them                                  packages are required, but not installed.
169                                  first. Either they are provided by your GNU/Linux distributor                                  You need to install them first. Either they
170                                  or available somewhere on the Internet.                                  are provided by your GNU/Linux distributor
171                                  The more essential and special ones are provided together                                  or available somewhere on the Internet.  
172                                  with the Thuban package.                                  The more essential and special ones are
173                                    provided together with the Thuban package.
174                                  </para>                                  </para>
175    
176                                  <para>                                  <para>
# Line 238  rpm -bb thuban.spec Line 285  rpm -bb thuban.spec
285                          <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.                          <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
286                                  </para>                                  </para>
287                          </section>                          </section>
288                  </section>                  </section> <!-- Intro - Installation - RPM-->
289    
290                    <section><title>Win32 Systems</title>
291                    <para>
292                            A common installation package of Thuban for Win32
293                            systems is available from the Thuban website download
294                            section. This installation package is configured for
295                            displaying file based vector data (Shapefiles). For the
296                            display of raster data or the connection to spatial
297                            databases additional steps are needed.  
298                    </para>
299                    <para>
300                            The required Python packages are listed and linked on
301                            the download page as well.  If you don't have Python
302                            installed already, download the packages for Python,
303                            wxPython for Python and the SQLite Python Libraries as
304                            well as the Thuban package. Install all four packages
305                            in the order: Python, wxPython, SQLite, Thuban. Follow
306                            the installation instructions provided by the seperate
307                            setups. The Thuban installation package will add an
308                            entry in the menu folder you configured.
309                    </para>
310                    <section><title>Raster Data: Installation of GDAL</title>
311                    <para>
312                            Enabling the raster data features of Thuban is
313                            straight forward. For the examples we assume that
314                            Thuban has been installed under
315                            <literal>C:\Thuban</literal>:
316                            <itemizedlist>
317                            <listitem>
318                            <para>
319                            Download the zip-archive <ulink
320                            url="ftp://intevation.de/thuban/win2k/gdal-win2k.zip"
321                            >gdal-win2k</ulink>.
322                            </para></listitem>
323                            <listitem><para>Extract the archive (e.g. with
324                            <ulink
325                            url="http://www.info-zip.org/pub/infozip/WiZ.html"
326                            >WiZ (InfoZip)</ulink>) into the
327                            <literal>C:\Thuban\Lib</literal>
328                            directory of your Thuban installation.
329                            </para>
330                            </listitem>
331                            <listitem>
332                            <para>
333                            Extent the <varname>PYTHONPATH</varname>
334                            environment variable (in your Windows Control Panel)
335                            to make the new libraries available for Thuban.
336                            <programlisting>
337    %PYTHONPATH%;C:\Thuban\Lib\gdal;C:\Thuban\Lib\gdal\pymod
338                            </programlisting>
339                            </para>
340                            </listitem>
341                            <listitem>
342                            <para>
343                            Extent also the <varname>PATH</varname>
344                            environment variable accordingly:
345                            <programlisting>
346    %PATH%;C:\Thuban\Lib\gdal
347                            </programlisting>
348                            </para>
349                            </listitem>
350                            </itemizedlist>
351                            After this installation steps Thuban is ready to
352                            display raster data (e.g. the
353                            <literal>island.tif</literal> from the Iceland Demo
354                            data set.
355                    </para>
356                    </section> <!-- Win32: GDAL-->
357    
358                    <section><title>Working with PostGIS: Installation of PsycoPG</title>
359                    <para>
360                            To access PostgreSQL/PostGIS spatial databases with
361                            Thuban you have to install the PsycoPG package for
362                            Windows:
363                            <itemizedlist>
364                            <listitem>
365                            <para>
366                            Download the zip-archive
367                            <ulink
368                                    url="http://stickpeople.com/projects/python/win-psycopg/win-psycopg22.zip"
369                            >win-psycopg22.zip</ulink>.
370                            </para>
371                            </listitem>
372                            <listitem>
373                            <para>
374                            Extract the zip-archive into a directory either already
375                            in your <varname>PYTHONPATH</varname> or extent your
376                            <varname>PYTHONPATH</varname> variable to the directory
377                            you have extracted the archive to.
378                            </para>
379                            </listitem>
380                            </itemizedlist>
381                            For installation and maintenance of spatial databases
382                            we refer to the  <ulink
383                            url="http://postgis.refractions.net"
384                            >PostGIS Homepage</ulink>.
385                    </para>
386                    </section> <!-- Win32: PsycoPG-->
387    
388                    </section> <!-- Intro - Installation - Win32 -->
389          </section>          </section>
390    
391            <section><title>Internationalization</title>
392            <para>
393            Thuban is implemented with internationalization support. So far Thuban
394            is translated by volunteers to the following languages (apart from its
395            main language: English):
396            <itemizedlist>
397                <listitem><para>French</para></listitem>
398                <listitem><para>German</para></listitem>
399                <listitem><para>Italian</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    
414            <para>
415            MS Windows users have to specify the language to be used via the control
416            bar (which effects all applications).
417            </para>
418            </section>
419    
420          <section><title>The Main Window</title>          <section><title>The Main Window</title>
421          <para>          <para>
422          <figure>          <figure>
# Line 391  rpm -bb thuban.spec Line 567  rpm -bb thuban.spec
567    
568          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
569          <para>          <para>
570          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:
571            Shape layers, database layers
572          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
573          widely used file format for storing geographic objects. These          widely used file format for storing geographic objects. These
574          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
# Line 401  rpm -bb thuban.spec Line 578  rpm -bb thuban.spec
578          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
579          also be a file roads.dbf.          also be a file roads.dbf.
580          </para>          </para>
581          <para>          <itemizedlist>
582            <listitem>
583            <para>
584          Shape layers can be added to the map with          Shape layers can be added to the map with
585          <menuchoice>          <menuchoice>
586          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
# Line 417  rpm -bb thuban.spec Line 596  rpm -bb thuban.spec
596                  Use the shift-button together with the left mouse button to extend                  Use the shift-button together with the left mouse button to extend
597                  the selection.                  the selection.
598          </para>          </para>
599            </listitem>
600    
601            <listitem>
602            <para>Database layers can be added to the map with
603            <menuchoice>
604            <guimenu>Map</guimenu>
605            <guimenuitem>Add Database Layer</guimenuitem>
606            </menuchoice>.
607            A dialog with two is list is opened. The left list displays all
608            database connections currently open for the session. You can retrieve
609            a list of available layers from the selected database which is
610            displayed on the right hand. From this list one layer can be selected,
611            the dialog is closed afterwards.
612            </para>
613            <para>
614            See appendix ``Working with PostGIS'' for details.
615            </para>
616            </listitem>
617    
618            <listitem>
619          <para>          <para>
620          Image layers can be added to the map with          Image layers can be added to the map with
621          <menuchoice>          <menuchoice>
# Line 429  rpm -bb thuban.spec Line 627  rpm -bb thuban.spec
627          or in another file. If geographic information cannot be found, Thuban          or in another file. If geographic information cannot be found, Thuban
628          will report an error.          will report an error.
629          </para>          </para>
630            </listitem>
631            </itemizedlist>
632          </section>          </section>
633    
634          <section><title>Navigation</title>          <section><title>Navigation</title>
# Line 720  rpm -bb thuban.spec Line 920  rpm -bb thuban.spec
920          </para>          </para>
921          </listitem>          </listitem>
922          </itemizedlist>          </itemizedlist>
923    
924            <para>
925            The most used layer related actions are also available from a
926            popup menu. It is raised when a layer is clicked with the right mouse
927            button.
928            </para>
929            
930            <para>
931            <figure>
932            <title>Layer Popup Menu</title>
933            <mediaobject>
934            <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
935            <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
936            </mediaobject>
937            </figure>
938            </para>
939    
940          <para>          <para>
941          Along the bottom of the legend is the scalebar. The scalebar          Along the bottom of the legend is the scalebar. The scalebar
942          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 981  rpm -bb thuban.spec
981    
982          <section><title>Types of Layers</title>          <section><title>Types of Layers</title>
983          <para>          <para>
984          There are two types of layers supported by Thuban: shape layers and          There are three types of layers supported by Thuban: shape layers,
985            database layers and
986          image layers. Shape layers consist of vector based shapes with          image layers. Shape layers consist of vector based shapes with
987          geo-referenced coordinates. There are three types of supported          geo-referenced coordinates. There are three types of supported
988          shapes: polygons, lines (arc), and points. Image layers can be any image          shapes: polygons, lines (arc), and points. Database layers are similar
989            to shape layers but loaded from a database instead of the file system.
990            Image layers can be any image
991          file format supported by the Geo-spatial Data Abstraction Library          file format supported by the Geo-spatial Data Abstraction Library
992          (GDAL). The images must have geographic          (GDAL). The images must have geographic
993          coordinate data either embedded within the file or in a separate          coordinate data either embedded within the file or in a separate
# Line 1099  rpm -bb thuban.spec Line 1319  rpm -bb thuban.spec
1319      </figure>      </figure>
1320      </para>      </para>
1321      <para>      <para>
1322      Thuban is distributed with a sample collection of projections. The      Thuban is distributed with a sample collection of projections and the
1323        set of coordinate systems as used by the EPSG
1324        (European Petroleum Survey Group). This quite large set is only displayed
1325        if activated by the according checkbox. The set falls into two parts:
1326        deprecated lists all projections which are no longer part of the
1327        EPSG data base.
1328        </para>
1329        <para>
1330             The
1331      user can create new projections and make them available to all      user can create new projections and make them available to all
1332      future Thuban sessions. They may also be exported and imported so      future Thuban sessions. They may also be exported and imported so
1333      that custom projections can be distributed.      that custom projections can be distributed.
# Line 1777  extensions_menu.InsertItem('hello_world' Line 2005  extensions_menu.InsertItem('hello_world'
2005      </varlistentry>      </varlistentry>
2006    
2007      <varlistentry>      <varlistentry>
2008        <term>PostGIS</term>
2009        <listitem>
2010            <para>
2011            PostGIS adds support for geographic objects to the PostgreSQL
2012            object-relational database. Different layer types (as for Shapefiles)
2013            are supported. <ulink url="http://postgis.refractions.net">PostGIS
2014            Homepage</ulink>
2015            </para>
2016        </listitem>
2017        </varlistentry>
2018    
2019        <varlistentry>
2020      <term>Raster files</term>      <term>Raster files</term>
2021      <listitem>      <listitem>
2022          <para>          <para>
# Line 1795  extensions_menu.InsertItem('hello_world' Line 2035  extensions_menu.InsertItem('hello_world'
2035      </variablelist>      </variablelist>
2036    </appendix>    </appendix>
2037    
2038      <appendix><title>Working with PostGIS</title>
2039      <para>
2040      This section focusses on the use of PostGIS in the Thuban framework. For
2041      installation and maintenance of spatial databases we refer to the  
2042      <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
2043      The Thuban PostGIS support requires the
2044      <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
2045      </para>
2046    
2047      <para>
2048            Working with PostGIS Databases is seperated into two steps:
2049            <itemizedlist>
2050            <listitem><para>Opening a Database Connection</para></listitem>
2051            <listitem><para>Loading a Data Layer</para></listitem>
2052            </itemizedlist>
2053      </para>
2054            <section><title>Opening a Database Connection</title>
2055            <para>
2056                    Before a data layer can be loaded from a PostGIS database a
2057                    connection with the database has to be established.
2058                    <menuchoice>
2059                    <guimenu>Session</guimenu>
2060                    <guimenuitem>Database Connections ...</guimenuitem>
2061                    </menuchoice> opens a dialog for database connection
2062                    management. In the dialog new connections can be added
2063                    and existing ones can be removed. Removing a database
2064                    connection is not possible if the map still displays a
2065                    layer provided by this database connection.
2066            </para>
2067        <figure>
2068        <title>Database Management Dialog</title>
2069        <mediaobject>
2070        <imageobject><imagedata fileref="../images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
2071        <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
2072        </mediaobject>
2073        </figure>
2074    
2075            <para>
2076                    To add a new database connection to the session a dialog is
2077                    opened to specify the relevant connection data. Enter all
2078                    data relevant for your connection. If the connection fails
2079                    the dialog remains open and provides some hints on the failure.
2080            </para>
2081            <figure>
2082            <title>Add Database Dialog</title>
2083            <mediaobject>
2084            <imageobject><imagedata fileref="../images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
2085            <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
2086            </mediaobject>
2087            </figure>
2088            
2089            <para>
2090            It is important to note that information on database connections are
2091            also stored with the session. Passwords are NOT stored. If you load a
2092            session with database connections you are asked to enter these
2093            passwords again where required.
2094            </para>
2095    
2096            </section>
2097    
2098            <section><title>Loading a Data Layer</title>
2099            <para>
2100            Data layers as part of a map are loaded with the
2101            <menuchoice>
2102            <guimenu>Map</guimenu>
2103            <guimenuitem>Add Database Layer ...</guimenuitem>
2104            </menuchoice> menu item. A dialog is raised displaying two choice
2105            lists. In the left list all connected databases are shown.
2106            Highlighting
2107            one of these and issuing a retrieval results in a list of available
2108            layer tables from that database. After selection of a
2109            layer the dialog is closed.
2110            </para>
2111            <figure>
2112            <title>Add Database Dialog</title>
2113            <mediaobject>
2114            <imageobject><imagedata fileref="../images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
2115            <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
2116            </mediaobject>
2117            </figure>
2118            
2119            </section>
2120    
2121      </appendix>
2122    
2123    <appendix><title>Supported Projections</title>    <appendix><title>Supported Projections</title>
2124      <para>      <para>
2125      The following types of projections are directly support by      The following types of projections are directly support by
Legend:
Removed from v.1744  
changed lines
  Added in v.2052
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26