/[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 2447 by frank, Mon Dec 13 11:53:15 2004 UTC revision 2727 by bernhard, Tue Feb 20 10:44:51 2007 UTC
# Line 6  Line 6 
6  <!-- $Revision$ -->  <!-- $Revision$ -->
7  <book>  <book>
8    <bookinfo>    <bookinfo>
9      <title>User's Manual for Thuban 1.0</title>      <title>User's Manual for Thuban 1.2 (Draft)</title>
10          <authorgroup>          <authorgroup>
11        <author>        <author>
12          <firstname>Jonathan</firstname><surname>Coles</surname>          <firstname>Jonathan</firstname><surname>Coles</surname>
# Line 19  Line 19 
19        </author>        </author>
20          </authorgroup>          </authorgroup>
21      <copyright>      <copyright>
22        <year>2003, 2004</year>        <year>2003, 2004, 2005, 2006, 2007</year>
23        <holder>Intevation GmbH</holder>        <holder>Intevation GmbH</holder>
24      </copyright>      </copyright>
25     <revhistory>     <revhistory>
26  <!-- comment this first revision out when releasing a real version -->  <!-- comment this first revision out when releasing a real version -->
27    <!--
28       <revision>       <revision>
29          <revnumber>CVS version $Id$</revnumber>          <revnumber>SVN version $Id$</revnumber>
30          <date></date>          <date></date>
31          <revremark>Under development.</revremark>          <revremark>Under development.</revremark>
32       </revision>       </revision>
33    -->
34         <revision>
35            <revnumber>1.2.0</revnumber>
36            <date>20-Feb-2007</date>
37            <revremark>
38                            Removed all installation instructions in favor
39                            of a link to the website. It is not wise to
40                            double the README contents here.
41                    </revremark>
42         </revision>
43       <revision>       <revision>
44          <revnumber>1.0.0</revnumber>          <revnumber>1.0.0</revnumber>
45          <date>22-Jan-2004</date>          <date>22-Jan-2004</date>
# Line 90  Line 101 
101    
102          <section><title>Installation</title>          <section><title>Installation</title>
103          <para>          <para>
104          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,          Thuban is actively supported under Debian 4.0 (Etch)
105          and Windows 2000. Thuban depends on the following packages. These          and Windows (XP). Of course it is possible to run Thuban
106          packages can also be found on the          on a variety of other platforms.
107          <ulink url="http://thuban.intevation.org/download.html">  
108          Thuban Download site          Please check <ulink url="http://thuban.intevation.org/">
109          </ulink>.          Thuban's Website
110            </ulink> about how to install Thuban and the lastest information
111            about the supported platforms.
112          </para>          </para>
         <para>  
         Required:  
         <itemizedlist>  
             <listitem><para>Python 2.2.1  
                         (<literal>http://www.python.org</literal>)  
                         </para></listitem>  
             <listitem><para>wxWindows 2.4  
                         (<literal>http://www.wxwindows.org</literal>)  
                         </para></listitem>  
             <listitem><para>wxPython 2.4  
                         (<literal>http://www.wxpython.org</literal>)  
                         </para></listitem>  
             <listitem><para>proj 4.4.5 Projection Library  
                         (<literal>http://www.remotesensing.org/proj/</literal>)  
                         </para></listitem>  
             <listitem><para>SQLite 2.8.3  
                         <literal>http://www.hwaci.com/sw/sqlite/</literal>)  
                         </para></listitem>  
             <listitem><para>PySQLite 0.4.3  
                         (<literal>http://pysqlite.sourceforge.net</literal>)  
                         </para></listitem>  
         </itemizedlist>  
         </para>  
         <para>  
         Optional:  
         <itemizedlist>  
             <listitem><para>GDAL 1.1.8  
                         (<literal>http://www.remotesensing.org/gdal/</literal>)  
                         </para></listitem>  
             <listitem><para>psycopg 1.0.8  
                         (<literal>http://initd.org/software/psycopg</literal>)  
                         </para></listitem>  
             </itemizedlist>  
         </para>  
                 <para>  
                 Along with the source codes, the download page also offers full  
                 installation packages for Debian, Windows and RPM-based systems  
                 (Mandrake, RedHat, SuSE, etc).  
                 </para>  
                 <section><title>RPM-based GNU/Linux Systems</title>  
                         <section><title>Installing Binary Packages</title>  
                                 <para>  
                                 The most wide-spread RPM-based GNU/Linux  
                                 Systems are RedHat, Mandrake and SuSE.  
                                 The documentation of these distributions  
                                 should contain information about how to  
                                 install third-party RPM packages.  
                                 Nonetheless, a short summary is provided here.  
                                 </para>  
                                 <para>  
                                 RPM packages can be installed applying several  
                                 tools. The most basic one is the command line  
                                 program "rpm".  The hardware architecture is  
                                 identified in the name of RPM packages, eg.  
                                 'i386' for most Intel/AMD architectures.    
                                 If you have a different hardware architecture,  
                                 where no binary RPM packages are provided,  
                                 you must rebuild binary packages from the  
                                 RPM source packages first (see below).  
                                 Typical rpm commands look like:  
   
                                 <programlisting>  
                                 rpm --install Thuban-0.9.0-1.i386.rpm  
                                 </programlisting>  
   
                                 Depending on what you already have installed  
                                 on your system, you are informed that some  
                                 packages are required, but not installed.  
                                 You need to install them first. Either they  
                                 are provided by your GNU/Linux distributor  
                                 or available somewhere on the Internet.    
                                 The more essential and special ones are  
                                 provided together with the Thuban package.  
                                 </para>  
   
                                 <para>  
                                 For rpm exist some graphical user interfaces, notably  
                                 kpackage, GnoRPM and xrpm.  
                                 </para>  
   
                                 <para>  
                                 Make yourself familiar with one of the tools and apply it  
                                 to install the packages.  
                                 Note, that you need to be administrator (root) for the system  
                                 to do that.  
                                 </para>  
                         </section>  
                         <section><title>Build Binaries from Source Packages</title>  
                                 <para>  
                                 This section describes howto build RPM install-packages  
                                 from RPM source-packages.  
                                 This adapts and optimizes an install-package specifically  
                                 to your system.  
                                 This is especially helpful to resolve version conflicts of  
                                 dependent packages. Furthermore, install-packages for other  
                                 platforms (e.g. PowerPC) can be created.  
                                 </para>  
   
                                 <para>  
                                 Note: rpm must be at least version 4. Execute  
                                 <literal>rpm --version</literal> to find out about the version.  
                                 </para>  
   
                                 <para>  
                                 You need to do the following preparations to be able to  
                                 build the packages as a regular user. You should now  
                                 perform the package buling as root since this  
                                 might cause damage to your system.  
                         <itemizedlist>  
                         <listitem>  
                                                 <para>  
                                                 Create RPM directory structure:  
                                                 Choose a directory (e.g. $HOME/myrpm) and create the  
                                                 subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.  
                                                 A possible command sequence for this is:  
                                                 <programlisting>  
                                                 mkdir $HOME/freegisrpm  
                                                 cd $HOME/freegisrpm  
                                                 mkdir BUILD RPMS SOURCES SPECS SRPMS  
                                                 </programlisting>  
                                                 </para>  
                                         </listitem>  
                                         <listitem>  
                                                 <para>  
                                                 Set environment variable RPM_DIR:  
                                                 <programlisting>  
                                                 export RPM_DIR=$HOME/freegisrpm  
                                                 </programlisting>  
                                                 </para>  
                                         </listitem>  
                                         <listitem>  
                                                 <para>  
                                                 Create $HOME/.rpmmacros:  
                                                 This file sets general preferences and some  
                                                 specific settings for signing packages.  
                                                 If you don't have a GnuPG-key, you can skip  
                                                 the signature settings i.e. drop the last 4 lines.  
                                                 A signature becomes important when you want to  
                                                 give away packages to third parties.  
                                                 <programlisting>  
 <![CDATA[  
 %packager Name Lastname <[email protected]>  
   
 %_topdir /home/mylogin/myrpm  
   
 %_signature gpg  
 %_gpg_name Name Lastname  
 %_pgp_path ~/.gnupg  
 %_pgpbin /usr/bin/gpg  
 ]]>  
                                                 </programlisting>  
                                                 </para>  
                                         </listitem>  
                         </itemizedlist>  
   
                                 Now you can install any RPM source-package.  
                                 It's components are installed into the corresponding  
                                 subdirectories of your rpm-directory.  
                                 Essentially these are the sources (into directory SOURCES)  
                                 and the so-called spec-file which contains all build  
                                 instructions. The spec-file will go into the SPEC directory.  
                                 Example:  
                                 <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>  
                                 </para>  
   
                                 <para>  
                                 Create install-package:  
                                 Go to the directory with the spec-files and rebuild the  
                                 package:  
                                 <programlisting>  
 cd $HOME/mypm/SPECS  
 rpm -bb thuban.spec  
                                 </programlisting>  
                                 Next, you will find the newly created package in  
                                 $HOME/myrpm/RPMS/i386.  
                                 If you build the package for another architecture than  
                                 i386, then the name of the directory has a corresponding name.  
                                 </para>  
                                 <para>  
                                 For documentation of RPM, either type  
                                 <literal>man rpm</literal> or <literal>rpm --help</literal>.  
                                 This will provide you with information on the various command  
                                 line options of RPM.  
                                 For more information see the  
                         <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.  
                                 </para>  
                         </section>  
                 </section> <!-- Intro - Installation - RPM-->  
   
                 <section><title>Win32 Systems</title>  
                 <para>  
                         A common installation package of Thuban for Win32  
                         systems is available from the Thuban website download  
                         section. This installation package is configured for  
                         displaying file based vector data (Shapefiles). For the  
                         display of raster data or the connection to spatial  
                         databases additional steps are needed.    
                 </para>  
                 <para>  
                         The required Python packages are listed and linked on  
                         the download page as well.  If you don't have Python  
                         installed already, download the packages for Python,  
                         wxPython for Python and the SQLite Python Libraries as  
                         well as the Thuban package. Install all four packages  
                         in the order: Python, wxPython, SQLite, Thuban. Follow  
                         the installation instructions provided by the seperate  
                         setups. The Thuban installation package will add an  
                         entry in the menu folder you configured.  
                 </para>  
                 <section><title>Raster Data: Installation of GDAL</title>  
                 <para>  
                         Enabling the raster data features of Thuban is  
                         straight forward. For the examples we assume that  
                         Thuban has been installed under  
                         <literal>C:\Thuban</literal>:  
                         <itemizedlist>  
                         <listitem>  
                         <para>  
                         Download the zip-archive <ulink  
                         url="ftp://intevation.de/thuban/win2k/gdal-win2k.zip"  
                         >gdal-win2k</ulink>.  
                         </para></listitem>  
                         <listitem><para>Extract the archive (e.g. with  
                         <ulink  
                         url="http://www.info-zip.org/pub/infozip/WiZ.html"  
                         >WiZ (InfoZip)</ulink>) into the  
                         <literal>C:\Thuban\Lib</literal>  
                         directory of your Thuban installation.  
                         </para>  
                         </listitem>  
                         <listitem>  
                         <para>  
                         Extent the <varname>PYTHONPATH</varname>  
                         environment variable (in your Windows Control Panel)  
                         to make the new libraries available for Thuban.  
                         <programlisting>  
 %PYTHONPATH%;C:\Thuban\Lib\gdal;C:\Thuban\Lib\gdal\pymod  
                         </programlisting>  
                         </para>  
                         </listitem>  
                         <listitem>  
                         <para>  
                         Extent also the <varname>PATH</varname>  
                         environment variable accordingly:  
                         <programlisting>  
 %PATH%;C:\Thuban\Lib\gdal  
                         </programlisting>  
                         </para>  
                         </listitem>  
                         </itemizedlist>  
                         After this installation steps Thuban is ready to  
                         display raster data (e.g. the  
                         <literal>island.tif</literal> from the Iceland Demo  
                         data set.  
                 </para>  
                 </section> <!-- Win32: GDAL-->  
   
                 <section><title>Working with PostGIS: Installation of PsycoPG</title>  
                 <para>  
                         To access PostgreSQL/PostGIS spatial databases with  
                         Thuban you have to install the PsycoPG package for  
                         Windows:  
                         <itemizedlist>  
                         <listitem>  
                         <para>  
                         Download the zip-archive  
                         <ulink  
                                 url="http://stickpeople.com/projects/python/win-psycopg/win-psycopg22.zip"  
                         >win-psycopg22.zip</ulink>.  
                         </para>  
                         </listitem>  
                         <listitem>  
                         <para>  
                         Extract the zip-archive into a directory either already  
                         in your <varname>PYTHONPATH</varname> or extent your  
                         <varname>PYTHONPATH</varname> variable to the directory  
                         you have extracted the archive to.  
                         </para>  
                         </listitem>  
                         </itemizedlist>  
                         For installation and maintenance of spatial databases  
                         we refer to the  <ulink  
                         url="http://postgis.refractions.net"  
                         >PostGIS Homepage</ulink>.  
                 </para>  
                 </section> <!-- Win32: PsycoPG-->  
   
                 </section> <!-- Intro - Installation - Win32 -->  
113          </section>          </section>
114    
115          <section><title>Internationalization</title>          <section><title>Internationalization</title>
# Line 624  rpm -bb thuban.spec Line 349  rpm -bb thuban.spec
349          <guimenu>Map</guimenu>          <guimenu>Map</guimenu>
350          <guimenuitem>Add Database Layer</guimenuitem>          <guimenuitem>Add Database Layer</guimenuitem>
351          </menuchoice>.          </menuchoice>.
352          A dialog with two is list is opened. The left list displays all          A dialog with two lists is opened. The left list displays all
353          database connections currently open for the session. You can retrieve          database connections currently open for the session. You can retrieve
354          a list of available layers from the selected database which is          a list of available layers from the selected database which is
355          displayed on the right hand. From this list one layer can be selected,          displayed on the right hand. From this list one layer can be selected,
# Line 1192  rpm -bb thuban.spec Line 917  rpm -bb thuban.spec
917          <section><title>Value</title>          <section><title>Value</title>
918              <para>              <para>
919              The Value column of the classification table is the value that will              The Value column of the classification table is the value that will
920              be matched when the map is being drawn. The type of data that can              be matched when the map is being drawn. The type of filter that can
921              entered into this field depends on the type of data of the              entered into this field depends on the type of data of the
922              classification field.              classification field:
923              </para>              </para>
924              <para>              <para>
925              If the field is of type Text, anything entered              If the field is of type Text, anything entered
926              into the field is valid. The text will be compared literally to the              into the field is valid. By default the text will be compared
927              value of the shape attribute, including case sensitivity.              literally to the
928                value of the shape attribute, including case sensitivity.
929                Alternatively the comparison can be based on regular experessions.
930                Right-click on the row label to open a popup menu with the options
931                <guibutton>Singleton</guibutton> (literal comparison) and  
932                <guibutton>Pattern</guibutton> (regular expressions).  
933                </para>
934                <para>
935              If the type is Integer, then any valid integer may be entered. In              If the type is Integer, then any valid integer may be entered. In
936              addition, with special syntax, a range of values can be entered.              addition, with special syntax, a range of values can be entered.
937              A range from <varname>start</varname> to <varname>end</varname>              A range from <varname>start</varname> to <varname>end</varname>
# Line 1210  rpm -bb thuban.spec Line 942  rpm -bb thuban.spec
942              Decimal. They represent any rational number and can be used in              Decimal. They represent any rational number and can be used in
943              ranges as well.              ranges as well.
944              </para>              </para>
945              </section>         </section>
946              <section><title>Label</title>              <section><title>Label</title>
947              <para>              <para>
948              By default, the text that is displayed for a group in the legend              By default, the text that is displayed for a group in the legend
# Line 1673  rpm -bb thuban.spec Line 1405  rpm -bb thuban.spec
1405                  </para>                  </para>
1406    
1407                  <section><title>Stable extensions</title>                  <section><title>Stable extensions</title>
1408                          <para>                      <para>
1409                          These extensions provide extra-functionality to Thuban                      These extensions provide extra-functionality to Thuban
1410                          that has not (yet) been integrated in the main application.                      that has not (yet) been integrated in the main application.
1411                          They are considered to be free of bugs, but may be                      They are considered to be free of bugs, but may be
1412                          further polished with helpful user interactions.                      further polished with helpful user interactions.
1413                          </para>                      </para>
1414                          <section><title>gns2shp</title>                      <section><title>gns2shp</title>
1415                                  <para>                                  <para>
1416                                  This tool converts data of the Geospatial Names Server                                  This tool converts data of the Geospatial Names Server
1417                                  (GNS, see <ulink url="http://www.nima.mil/gns"/>)                                  (GNS, see <ulink url="http://www.nima.mil/gns"/>)
# Line 1706  rpm -bb thuban.spec Line 1438  rpm -bb thuban.spec
1438                                  is included in the directory                                  is included in the directory
1439                                  <literal>Extensions/gns2shp/test</literal>.                                  <literal>Extensions/gns2shp/test</literal>.
1440                                  </para>                                  </para>
1441                          </section>                      </section>
1442                        <section><title>SVG Export</title>
1443                            <para>
1444                            Map and legend can be exported separately in the
1445                            Thuban-Map-SVG format.
1446                            You get files that comply with
1447                            the Scalable Vector Graphics (SVG) 1.1 Specification
1448                            and can be read by many vector drawing applications.
1449                            </para>
1450                            <para>
1451                            Goal of svgexport is to provide
1452                            the start of a printing pipeline for Thuban.
1453                            For this purpose the written Thuban-Map-SVG files
1454                            contain information that can be used in postprocessing.
1455                            Typically a general vector drawing application is
1456                            more powerful then a geographic information viewer;
1457                            e.g. having much fancier symbols and fonts.
1458                            Also users benefit much more when learning to use a
1459                            more general application they can also use for other
1460                            tasks.  So the charming idea is to enable
1461                            the drawing application to postprocess a Thuban maps.
1462                            So thee xtra information in the format will make it
1463                            possible to export from Thuban and if a few geoobjects
1464                            change, and keep the general layout and style
1465                            of the full map in the vector drawing appplication.
1466                            </para>
1467                            <para>
1468                            Markus Rechtien has developed a prototype of this
1469                            printing pipline as his Diplom thetis, showing
1470                            the feasability of Bernhard Reiter's concept.
1471                            Scripts exist for the drawing application Skencil
1472                            (<ulink url="http://www.skencil.org"/>).
1473                            </para>
1474                            <para>
1475                            Technical notes: the names of the layers are used
1476                            as base for ids within the SVG format.
1477                            If you try to export with two layers having
1478                            the same name, you will get a name clash error.
1479                            Just change one of the layer names and try again.
1480                            </para>
1481                        </section>
1482                  </section>                  </section>
1483                  <section><title>Experimental extensions</title>                  <section><title>Experimental extensions</title>
1484                          <para>                          <para>
Legend:
Removed from v.2447  
changed lines
  Added in v.2727
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26