/[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 2023 by frank, Fri Dec 5 13:54:46 2003 UTC revision 2482 by bernhard, Sat Dec 18 02:36:59 2004 UTC
# 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>
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>CVS version $Id$</revnumber>          <revnumber>CVS version $Id$</revnumber>
29          <date></date>          <date></date>
30          <revremark>Under development.</revremark>          <revremark>Under development.</revremark>
31       </revision>       </revision>
32  -->       <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>       <revision>
41          <revnumber>1.0pre3</revnumber>          <revnumber>1.0pre3</revnumber>
42          <date>04-Dec-2003</date>          <date>04-Dec-2003</date>
43          <revremark>          <revremark>
44                          Corresponds to Thuban 1.0rc1                          Corresponds to Thuban 1.0rc1.
45                          New: I18n, right button legend menu, EPSG projectons,                          New: I18n, right button legend menu, EPSG projectons,
46              PostGIS support.              PostGIS support.
47                  </revremark>                  </revremark>
# Line 60  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 76  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 93  Line 100 
100          <para>          <para>
101          Required:          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>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>                          (<literal>http://www.wxwindows.org</literal>)
108              <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>                          </para></listitem>
109                <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>          </itemizedlist>
122          </para>          </para>
123          <para>          <para>
124          Optional:          Optional:
125          <itemizedlist>          <itemizedlist>
126              <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>              <listitem><para>GDAL 1.1.8
127              <listitem><para>psycopg 1.0.8 (<literal>http://initd.org/software/psycopg</literal>)</para></listitem>                          (<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>                  <section><title>RPM-based GNU/Linux Systems</title>
140                          <section><title>Installing Binary Packages</title>                          <section><title>Installing Binary Packages</title>
141                                  <para>                                  <para>
142                                  The most wide-spread RPM-based GNU/Linux Systems are RedHat,                                  The most wide-spread RPM-based GNU/Linux
143                                  Mandrake and SuSE. The documentation of these distributions                                  Systems are RedHat, Mandrake and SuSE.
144                                  should contain information about how to install third-party                                  The documentation of these distributions
145                                  RPM packages. Nonetheless, a short summary is provided here.                                  should contain information about how to
146                                    install third-party RPM packages.
147                                    Nonetheless, a short summary is provided here.
148                                  </para>                                  </para>
149                                  <para>                                  <para>
150                                  RPM packages can be installed applying several tools.                                  RPM packages can be installed applying several
151                                  The most basic one is the command line program "rpm".                                  tools. The most basic one is the command line
152                                  The hardware architecture is identified in the name                                  program "rpm".  The hardware architecture is
153                                  of RPM packages, eg. 'i386' for most Intel/AMD architectures.                                  identified in the name of RPM packages, eg.
154                                  If you have a different hardware architecture, where no                                  'i386' for most Intel/AMD architectures.  
155                                  binary RPM packages are provided, you must rebuild binary                                  If you have a different hardware architecture,
156                                  packages from the RPM source packages first (see below).                                  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:                                  Typical rpm commands look like:
160    
161                                  <programlisting>                                  <programlisting>
162                                  rpm --install Thuban-0.9.0-1.i386.rpm                                  rpm --install Thuban-0.9.0-1.i386.rpm
163                                  </programlisting>                                  </programlisting>
164    
165                                  Depending on what you already have installed on your                                  Depending on what you already have installed
166                                  system, you are informed that some packages are                                  on your system, you are informed that some
167                                  required, but not installed. You need to install them                                  packages are required, but not installed.
168                                  first. Either they are provided by your GNU/Linux distributor                                  You need to install them first. Either they
169                                  or available somewhere on the Internet.                                  are provided by your GNU/Linux distributor
170                                  The more essential and special ones are provided together                                  or available somewhere on the Internet.  
171                                  with the Thuban package.                                  The more essential and special ones are
172                                    provided together with the Thuban package.
173                                  </para>                                  </para>
174    
175                                  <para>                                  <para>
# Line 256  rpm -bb thuban.spec Line 284  rpm -bb thuban.spec
284                          <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.                          <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
285                                  </para>                                  </para>
286                          </section>                          </section>
287                  </section>                  </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>          <section><title>Internationalization</title>
# Line 268  rpm -bb thuban.spec Line 396  rpm -bb thuban.spec
396              <listitem><para>French</para></listitem>              <listitem><para>French</para></listitem>
397              <listitem><para>German</para></listitem>              <listitem><para>German</para></listitem>
398              <listitem><para>Italian</para></listitem>              <listitem><para>Italian</para></listitem>
399                    <listitem><para>Portuguese (Brazilian)</para></listitem>
400              <listitem><para>Russian</para></listitem>              <listitem><para>Russian</para></listitem>
401              <listitem><para>Spanish</para></listitem>              <listitem><para>Spanish</para></listitem>
402          </itemizedlist>          </itemizedlist>
# Line 279  rpm -bb thuban.spec Line 408  rpm -bb thuban.spec
408          LC_ALL=fr_FR for the french language support). Please check your          LC_ALL=fr_FR for the french language support). Please check your
409          systems documentation for details and supported settings.          systems documentation for details and supported settings.
410          Specifiying LC_ALL on the command line while launching thuban          Specifiying LC_ALL on the command line while launching thuban
411          allows appication specific language settings.          allows appication specific language settings:
412          </para>          </para>
413            <programlisting>
414            LC_ALL=fr_FR thuban.py
415            </programlisting>
416    
417          <para>          <para>
418          MS Windows users have to specify the language to be used via the control          MS Windows users have to specify the language to be used via the control
# Line 352  rpm -bb thuban.spec Line 484  rpm -bb thuban.spec
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 366  rpm -bb thuban.spec Line 498  rpm -bb thuban.spec
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 379  rpm -bb thuban.spec Line 523  rpm -bb thuban.spec
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 1524  rpm -bb thuban.spec Line 1673  rpm -bb thuban.spec
1673                  </para>                  </para>
1674    
1675                  <section><title>Stable extensions</title>                  <section><title>Stable extensions</title>
1676                          <para>                      <para>
1677                          These extensions provide extra-functionality to Thuban                      These extensions provide extra-functionality to Thuban
1678                          that has not (yet) been integrated in the main application.                      that has not (yet) been integrated in the main application.
1679                          They are considered to be free of bugs, but may be                      They are considered to be free of bugs, but may be
1680                          further polished with helpful user interactions.                      further polished with helpful user interactions.
1681                          </para>                      </para>
1682                          <section><title>gns2shp</title>                      <section><title>gns2shp</title>
1683                                  <para>                                  <para>
1684                                  This tool converts data of the Geospatial Names Server                                  This tool converts data of the Geospatial Names Server
1685                                  (GNS, see <ulink url="http://www.nima.mil/gns"/>)                                  (GNS, see <ulink url="http://www.nima.mil/gns"/>)
# Line 1557  rpm -bb thuban.spec Line 1706  rpm -bb thuban.spec
1706                                  is included in the directory                                  is included in the directory
1707                                  <literal>Extensions/gns2shp/test</literal>.                                  <literal>Extensions/gns2shp/test</literal>.
1708                                  </para>                                  </para>
1709                          </section>                      </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>                  </section>
1751                  <section><title>Experimental extensions</title>                  <section><title>Experimental extensions</title>
1752                          <para>                          <para>
# Line 1702  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 1938  extensions_menu.InsertItem('hello_world' Line 2125  extensions_menu.InsertItem('hello_world'
2125      <figure>      <figure>
2126      <title>Database Management Dialog</title>      <title>Database Management Dialog</title>
2127      <mediaobject>      <mediaobject>
2128      <imageobject><imagedata fileref="./images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>      <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>      <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
2130      </mediaobject>      </mediaobject>
2131      </figure>      </figure>
# Line 1952  extensions_menu.InsertItem('hello_world' Line 2139  extensions_menu.InsertItem('hello_world'
2139          <figure>          <figure>
2140          <title>Add Database Dialog</title>          <title>Add Database Dialog</title>
2141          <mediaobject>          <mediaobject>
2142          <imageobject><imagedata fileref="./images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>          <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>          <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
2144          </mediaobject>          </mediaobject>
2145          </figure>          </figure>
# Line 1982  extensions_menu.InsertItem('hello_world' Line 2169  extensions_menu.InsertItem('hello_world'
2169          <figure>          <figure>
2170          <title>Add Database Dialog</title>          <title>Add Database Dialog</title>
2171          <mediaobject>          <mediaobject>
2172          <imageobject><imagedata fileref="./images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>          <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>          <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
2174          </mediaobject>          </mediaobject>
2175          </figure>          </figure>
Legend:
Removed from v.2023  
changed lines
  Added in v.2482
[email protected]
 ViewVC Help
Powered by ViewVC 1.1.26