/[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 1719 by jan, Fri Sep 19 09:17:10 2003 UTC revision 2023 by frank, Fri Dec 5 13:54:46 2003 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 32  Line 32 
32       </revision>       </revision>
33  -->  -->
34       <revision>       <revision>
35            <revnumber>1.0pre3</revnumber>
36            <date>04-Dec-2003</date>
37            <revremark>
38                            Corresponds to Thuban 1.0rc1
39                            New: I18n, right button legend menu, EPSG projectons,
40                PostGIS support.
41                    </revremark>
42         </revision>
43         <revision>
44          <revnumber>1.0pre2</revnumber>          <revnumber>1.0pre2</revnumber>
45          <date>29-Aug-2003</date>          <date>29-Aug-2003</date>
46          <revremark>          <revremark>
# Line 80  Line 89 
89          <ulink url="http://thuban.intevation.org/download.html">          <ulink url="http://thuban.intevation.org/download.html">
90          Thuban Download site          Thuban Download site
91          </ulink>.          </ulink>.
92            </para>
93            <para>
94            Required:
95          <itemizedlist>          <itemizedlist>
96              <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>              <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>
97              <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>              <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>
98              <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>              <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>
99              <listitem><para>proj 4.4.5 Projection Library (<literal>http://www.remotesensing.org/proj/</literal>)</para></listitem>              <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>  
100              <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>              <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>
101              <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>              <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>
102            </itemizedlist>
103            </para>
104            <para>
105            Optional:
106            <itemizedlist>
107                <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>
108                <listitem><para>psycopg 1.0.8 (<literal>http://initd.org/software/psycopg</literal>)</para></listitem>
109              </itemizedlist>              </itemizedlist>
110          </para>          </para>
111                  <para>                  <para>
# Line 241  rpm -bb thuban.spec Line 259  rpm -bb thuban.spec
259                  </section>                  </section>
260          </section>          </section>
261    
262            <section><title>Internationalization</title>
263            <para>
264            Thuban is implemented with internationalization support. So far Thuban
265            is translated by volunteers to the following languages (apart from its
266            main language: English):
267            <itemizedlist>
268                <listitem><para>French</para></listitem>
269                <listitem><para>German</para></listitem>
270                <listitem><para>Italian</para></listitem>
271                <listitem><para>Russian</para></listitem>
272                <listitem><para>Spanish</para></listitem>
273            </itemizedlist>
274            </para>
275    
276            <para>
277            To use internationalization under POSIX systems (like GNU/Linux)
278            you have to set the environment variable LC_ALL accordingly (e.g.
279            LC_ALL=fr_FR for the french language support). Please check your
280            systems documentation for details and supported settings.
281            Specifiying LC_ALL on the command line while launching thuban
282            allows appication specific language settings.
283            </para>
284    
285            <para>
286            MS Windows users have to specify the language to be used via the control
287            bar (which effects all applications).
288            </para>
289            </section>
290    
291          <section><title>The Main Window</title>          <section><title>The Main Window</title>
292          <para>          <para>
293          <figure>          <figure>
# Line 391  rpm -bb thuban.spec Line 438  rpm -bb thuban.spec
438    
439          <section><title>Adding and Removing Layers</title>          <section><title>Adding and Removing Layers</title>
440          <para>          <para>
441          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:
442            Shape layers, database layers
443          and image layers. Shape layers are stored in Shapefile format, a          and image layers. Shape layers are stored in Shapefile format, a
444          widely used file format for storing geographic objects. These          widely used file format for storing geographic objects. These
445          files have the extension ``.shp''. Associated with          files have the extension ``.shp''. Associated with
# Line 401  rpm -bb thuban.spec Line 449  rpm -bb thuban.spec
449          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
450          also be a file roads.dbf.          also be a file roads.dbf.
451          </para>          </para>
452          <para>          <itemizedlist>
453            <listitem>
454            <para>
455          Shape layers can be added to the map with          Shape layers can be added to the map with
456          <menuchoice>          <menuchoice>
457          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
# Line 417  rpm -bb thuban.spec Line 467  rpm -bb thuban.spec
467                  Use the shift-button together with the left mouse button to extend                  Use the shift-button together with the left mouse button to extend
468                  the selection.                  the selection.
469          </para>          </para>
470            </listitem>
471    
472            <listitem>
473            <para>Database layers can be added to the map with
474            <menuchoice>
475            <guimenu>Map</guimenu>
476            <guimenuitem>Add Database Layer</guimenuitem>
477            </menuchoice>.
478            A dialog with two is list is opened. The left list displays all
479            database connections currently open for the session. You can retrieve
480            a list of available layers from the selected database which is
481            displayed on the right hand. From this list one layer can be selected,
482            the dialog is closed afterwards.
483            </para>
484            <para>
485            See appendix ``Working with PostGIS'' for details.
486            </para>
487            </listitem>
488    
489            <listitem>
490          <para>          <para>
491          Image layers can be added to the map with          Image layers can be added to the map with
492          <menuchoice>          <menuchoice>
# Line 429  rpm -bb thuban.spec Line 498  rpm -bb thuban.spec
498          or in another file. If geographic information cannot be found, Thuban          or in another file. If geographic information cannot be found, Thuban
499          will report an error.          will report an error.
500          </para>          </para>
501            </listitem>
502            </itemizedlist>
503          </section>          </section>
504    
505          <section><title>Navigation</title>          <section><title>Navigation</title>
# Line 720  rpm -bb thuban.spec Line 791  rpm -bb thuban.spec
791          </para>          </para>
792          </listitem>          </listitem>
793          </itemizedlist>          </itemizedlist>
794    
795            <para>
796            The most used layer related actions are also available from a
797            popup menu. It is raised when a layer is clicked with the right mouse
798            button.
799            </para>
800            
801            <para>
802            <figure>
803            <title>Layer Popup Menu</title>
804            <mediaobject>
805            <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
806            <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
807            </mediaobject>
808            </figure>
809            </para>
810    
811          <para>          <para>
812          Along the bottom of the legend is the scalebar. The scalebar          Along the bottom of the legend is the scalebar. The scalebar
813          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 852  rpm -bb thuban.spec
852    
853          <section><title>Types of Layers</title>          <section><title>Types of Layers</title>
854          <para>          <para>
855          There are two types of layers supported by Thuban: shape layers and          There are three types of layers supported by Thuban: shape layers,
856            database layers and
857          image layers. Shape layers consist of vector based shapes with          image layers. Shape layers consist of vector based shapes with
858          geo-referenced coordinates. There are three types of supported          geo-referenced coordinates. There are three types of supported
859          shapes: polygons, lines (arc), and points. Image layers can be any image          shapes: polygons, lines (arc), and points. Database layers are similar
860            to shape layers but loaded from a database instead of the file system.
861            Image layers can be any image
862          file format supported by the Geo-spatial Data Abstraction Library          file format supported by the Geo-spatial Data Abstraction Library
863          (GDAL). The images must have geographic          (GDAL). The images must have geographic
864          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 1190  rpm -bb thuban.spec
1190      </figure>      </figure>
1191      </para>      </para>
1192      <para>      <para>
1193      Thuban is distributed with a sample collection of projections. The      Thuban is distributed with a sample collection of projections and the
1194        set of coordinate systems as used by the EPSG
1195        (European Petroleum Survey Group). This quite large set is only displayed
1196        if activated by the according checkbox. The set falls into two parts:
1197        deprecated lists all projections which are no longer part of the
1198        EPSG data base.
1199        </para>
1200        <para>
1201             The
1202      user can create new projections and make them available to all      user can create new projections and make them available to all
1203      future Thuban sessions. They may also be exported and imported so      future Thuban sessions. They may also be exported and imported so
1204      that custom projections can be distributed.      that custom projections can be distributed.
# Line 1410  rpm -bb thuban.spec Line 1509  rpm -bb thuban.spec
1509                  </para>                  </para>
1510          </section>          </section>
1511    
1512            <section><title>Extensions included in Thuban package</title>
1513                    <para>
1514                    The extensions described in this section are part of the
1515                    Thuban package, but not activated by default.
1516                    You will find them in the Thuban installation directory
1517                    under <literal>Extensions/</literal>. Activate them as personal
1518                    extensions via PYTHONPATH as described in the previous section.
1519                    Stable extensions will appear under the menu
1520                    <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
1521                    extensions which are in experimental state and therefore
1522                    not fully functional under
1523                    <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
1524                    </para>
1525    
1526                    <section><title>Stable extensions</title>
1527                            <para>
1528                            These extensions provide extra-functionality to Thuban
1529                            that has not (yet) been integrated in the main application.
1530                            They are considered to be free of bugs, but may be
1531                            further polished with helpful user interactions.
1532                            </para>
1533                            <section><title>gns2shp</title>
1534                                    <para>
1535                                    This tool converts data of the Geospatial Names Server
1536                                    (GNS, see <ulink url="http://www.nima.mil/gns"/>)
1537                                    into Shapefile format.
1538                                    The above web-site offer to download named places
1539                                    information grouped by countries for all of the world
1540                                    except USA for which other data are provided.
1541                                    </para>
1542                                    <para>
1543                                    If you download and unpack a package, you will have
1544                                    a text-file with suffix .txt.
1545                                    Selecting such a file via gns2shp will create the
1546                                    corresponding Shapefile with the same basename and
1547                                    place it in the same direcory. Afterwards it
1548                                    is automatically loaded into Thuban.
1549                                    The Shapefile will not automatically be delete afterwards.
1550                                    </para>
1551                                    <para>
1552                                    The gns2shp.py module can also be executed on the
1553                                    command line for batch processing purposes.
1554                                    </para>
1555                                    <para>
1556                                    A sample (<literal>ls.txt</literal> for Liechtenstein)
1557                                    is included in the directory
1558                                    <literal>Extensions/gns2shp/test</literal>.
1559                                    </para>
1560                            </section>
1561                    </section>
1562                    <section><title>Experimental extensions</title>
1563                            <para>
1564                            All all of these functions have to be handled with care,
1565                            since they are neither complete nor well tested.
1566                            They are to be seen as a proof-of-concept and may
1567                            additionally in some cases of practical help.
1568                            </para>
1569                            <para>
1570                            Any interest on further improvement of these extensions
1571                            should be communicated towards the developer and user
1572                            community.
1573                            </para>
1574    
1575                            <section><title>importAPR</title>
1576                                    <para>
1577                                    This command offer to load an ESRI� ArcView� project
1578                                    file (suffix .apr) and convert it for use within Thuban.
1579                                    After selecting a apr-file to load, a list
1580                                    will be presented that offers to select one of the views
1581                                    of the apr-file, provided there is more than one.
1582                                    Furthermore, the Session Info-Tree is extended with
1583                                    a complete representation of the parsed apr-file.
1584                                    </para>
1585                                    <para>
1586                                    The legend of Thuban does not yet cover all of the elements as
1587                                    supported by the legend of ArcView�. Therefore, the Thuban
1588                                    map will look different. Furthermore, the apr-format is
1589                                    a proprietary format, not openly documented.
1590                                    Therefore, the interpretation is
1591                                    partly based on reverse engeneering and good guessing.
1592                                    </para>
1593                                    <para>
1594                                    The file-paths within the apr-file may not fit and potentially
1595                                    are subject to fix in the apr-file. You can do this
1596                                    applying any text editor. The paths are either absolute
1597                                    or relative from where Thuban has been started.
1598                                    </para>
1599                                    <para>
1600                                    A sample for the Iceland data is included as
1601                                    <literal>Extensions/importAPR/samples/iceland.apr</literal>.
1602                                    The file-paths are relative from the Thuban main directory.
1603                                    </para>
1604                            </section>
1605                    </section>
1606            </section>
1607    
1608          <section><title>Writing simple extensions</title>          <section><title>Writing simple extensions</title>
1609                  <para>                  <para>
1610                  Writing an extension for Thuban basically means to                  Writing an extension for Thuban basically means to
# Line 1681  extensions_menu.InsertItem('hello_world' Line 1876  extensions_menu.InsertItem('hello_world'
1876      </varlistentry>      </varlistentry>
1877    
1878      <varlistentry>      <varlistentry>
1879        <term>PostGIS</term>
1880        <listitem>
1881            <para>
1882            PostGIS adds support for geographic objects to the PostgreSQL
1883            object-relational database. Different layer types (as for Shapefiles)
1884            are supported. <ulink url="http://postgis.refractions.net">PostGIS
1885            Homepage</ulink>
1886            </para>
1887        </listitem>
1888        </varlistentry>
1889    
1890        <varlistentry>
1891      <term>Raster files</term>      <term>Raster files</term>
1892      <listitem>      <listitem>
1893          <para>          <para>
# Line 1699  extensions_menu.InsertItem('hello_world' Line 1906  extensions_menu.InsertItem('hello_world'
1906      </variablelist>      </variablelist>
1907    </appendix>    </appendix>
1908    
1909      <appendix><title>Working with PostGIS</title>
1910      <para>
1911      This section focusses on the use of PostGIS in the Thuban framework. For
1912      installation and maintenance of spatial databases we refer to the  
1913      <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
1914      The Thuban PostGIS support requires the
1915      <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
1916      </para>
1917    
1918      <para>
1919            Working with PostGIS Databases is seperated into two steps:
1920            <itemizedlist>
1921            <listitem><para>Opening a Database Connection</para></listitem>
1922            <listitem><para>Loading a Data Layer</para></listitem>
1923            </itemizedlist>
1924      </para>
1925            <section><title>Opening a Database Connection</title>
1926            <para>
1927                    Before a data layer can be loaded from a PostGIS database a
1928                    connection with the database has to be established.
1929                    <menuchoice>
1930                    <guimenu>Session</guimenu>
1931                    <guimenuitem>Database Connections ...</guimenuitem>
1932                    </menuchoice> opens a dialog for database connection
1933                    management. In the dialog new connections can be added
1934                    and existing ones can be removed. Removing a database
1935                    connection is not possible if the map still displays a
1936                    layer provided by this database connection.
1937            </para>
1938        <figure>
1939        <title>Database Management Dialog</title>
1940        <mediaobject>
1941        <imageobject><imagedata fileref="./images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
1942        <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
1943        </mediaobject>
1944        </figure>
1945    
1946            <para>
1947                    To add a new database connection to the session a dialog is
1948                    opened to specify the relevant connection data. Enter all
1949                    data relevant for your connection. If the connection fails
1950                    the dialog remains open and provides some hints on the failure.
1951            </para>
1952            <figure>
1953            <title>Add Database Dialog</title>
1954            <mediaobject>
1955            <imageobject><imagedata fileref="./images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
1956            <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
1957            </mediaobject>
1958            </figure>
1959            
1960            <para>
1961            It is important to note that information on database connections are
1962            also stored with the session. Passwords are NOT stored. If you load a
1963            session with database connections you are asked to enter these
1964            passwords again where required.
1965            </para>
1966    
1967            </section>
1968    
1969            <section><title>Loading a Data Layer</title>
1970            <para>
1971            Data layers as part of a map are loaded with the
1972            <menuchoice>
1973            <guimenu>Map</guimenu>
1974            <guimenuitem>Add Database Layer ...</guimenuitem>
1975            </menuchoice> menu item. A dialog is raised displaying two choice
1976            lists. In the left list all connected databases are shown.
1977            Highlighting
1978            one of these and issuing a retrieval results in a list of available
1979            layer tables from that database. After selection of a
1980            layer the dialog is closed.
1981            </para>
1982            <figure>
1983            <title>Add Database Dialog</title>
1984            <mediaobject>
1985            <imageobject><imagedata fileref="./images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
1986            <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
1987            </mediaobject>
1988            </figure>
1989            
1990            </section>
1991    
1992      </appendix>
1993    
1994    <appendix><title>Supported Projections</title>    <appendix><title>Supported Projections</title>
1995      <para>      <para>
1996      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.2023
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26