< User Manual

Structure >

1. Installation

1.1. CartoWeb Installation

1.1.1. Prerequisite for Installing CartoWeb

CartoWeb depends on several software components for its proper working. Some are required and others are optional, depending on what you intend to do.

Note

Windows users can ignore this chapter and go directly to Section 1.1.2, “CartoWeb Download”

The required software are:

A Web Server

Such as Apache http://httpd.apache.org

PHP >= 5.0.3

See http://www.php.net for more informations. You will need to have some features available in PHP:
  • Gettext (optional): You need the Gettext module if you want to enable the Internationalization in CartoWeb. See Chapter 15, Internationalization for configuration.

    Note

    If you are using the demo, you need to have Gettext support installed, as it uses Gettext by default.

    If you are using Cygwin, simply install the gettext-devel package.
  • Curl (optional): Some scripts (like i18n) need Curl to fetch files remotely.
  • SOAP (optional if using direct mode only): You need the SOAP module if you want to use CartoWeb as a Webservice or with separated CartoClient and CartoServer. This is related to the cartoserverDirectAccess parameter described in Section 4.2, “ client.ini

Note

If you are using Windows, simply use the Windows Installer Section 1.1.2, “CartoWeb Download”. If you absolutely want to install PHP manually, see Appendix B, Apache & Mapserver Windows Manual Installation.

MapServer PHP/MapScript (from MapServer >= 4.4)

See http://www.maptools.org/php_mapscript/ for more information and installation instructions.

Note

If you are using Debian, and you need to install MapServer, you can have a look at Appendix A, Mapserver Debian Installation

Note

If you are using Windows, simply use the Windows Installer Section 1.1.2, “CartoWeb Download”. If you absolutely want to install MapServer manually, see Appendix B, Apache & Mapserver Windows Manual Installation.

PostgreSQL with PostGIS Support (Optional)

If you want spatial database support in CartoWeb you will need to install PostGIS of the PostgreSQL database. See http://postgis.refractions.net/ for more information.

1.1.2. CartoWeb Download

There are two ways to get CartoWeb:

  1. Complete package from the official website: 

    • Download CartoWeb package from http://cartoweb.org/downloads.html. It is recommended that you download the version with demo for a better user experience.
    • Uncompress the archive somewhere in your path accessible by your web server.

  2. From CVS: Get the current development version via CVS using the following command:

    cvs -d :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public co cartoweb3

    From CVS with cw3setup.php: If you already have the cw3setup.php file, which comes along the CartoWeb package or CVS source, you can fetch CartoWeb from CVS and set up it at once. See Section 1.1.3.2.6, “Install or Reinstall CartoWeb from CVS and Set Up It at Once” for more details.

Once you have CartoWeb, point your web browser to the file located in htdocs/info.php, and check that the PHP information page displays correctly (meaning PHP is correctly setup) and that you have do not have a WARNING message at the top of the page about MapScript failing to load. If it is not the case, CartoWeb will not run correctly. You should install and set up PHP and PHP/MapScript correctly. See Section 1.1.1, “Prerequisite for Installing CartoWeb”.

Having Gettext installed is recommended if you wish to use the multilingual features of CartoWeb.

1.1.3. UNIX-like Installation

CartoWeb installer is cw3setup.php, located in the root directory of the application.

You can run this file with the --help parameter to see the available options. For instance:

<PHP-INTERPRETER> cw3setup.php --help

where <PHP-INTERPRETER> is the location of your php interpreter. On Windows, it can be c:\wamp\php\php.exe or on Unix /usr/lib/cgi-bin/php.

1.1.3.1. List of Available Options

Usage: cw3setup.php ACTION [OPTION]...

Possible actions:

 --help, or -h              Display this help and exit.
 --version or -v            Output version information and exit.
 --install                  Install CartoWeb.
 --fetch-demo               Fetch the demo data from cartoweb.org, and extract
                            it in the demo project if not already there.
 --clean                    Clean generated files and caches.

List of options:

 --debug                    Turn on output debugging.

 --writableowner OWNER      The user who should have write permissions for
                            generated files.

 --cvs-root                 CVS Root directory to use when fetching
                            CartoWeb/project out of CVS.
 --fetch-from-cvs           Fetch CartoWeb from CVS and install it in the
                            current directory, or in the directory given by
                            the --install-location parameter.
                            NOTE: You must be located where cartoweb3 directory
                            will be created, not inside like other commands.
 --cartoweb-cvs-option OPTIONS  A string which will be given to the cvs checkout
                            command of cartoweb (not projects!).
                            For instance, to fetch a specific branch,
                            use '-r MY_BRANCH'. Or for a specific date,
                            use '-D "2005-09-05 11:00"'.
 --fetch-from-dir DIRECTORY Copy CartoWeb from the specified directory into the
                            current directory, or in the directory given by the
                            --install-location parameter.
                            NOTE 1: You must be located where cartoweb3
                            directory will be created, not inside like other
                            commands.
                            NOTE 2: You may either use a path relative to the
                            target cartoweb3 directory or an absolute path.
 --install-location         Directory where to install CartoWeb
                            (when using --fetch-from-cvs/dir options).

 --delete-existing          Overwrite existing directories if any.
 --no-symlinks              Do not use symbolic links, even if your operating
                            system supports them.

 --config-from-file FILE    Location of a configuration file for automatic
                            variable replacement in .in files.
                            NOTE: You may either use a path relative to the
                            target cartoweb3 directory or an absolute path.
 --config-from-project PROJECT Read the configuration file containing variables
                            to replace in .in files from the specified project.

 --fetch-project-cvs PROJECT Fetch the given project from CVS
                            (see --cvs-root option).
 --fetch-project-dir DIRECTORY Fetch the given project from a directory.

 --default-project PROJECT  Default project to use (this is set automatically
                            if using --config-from-project).
 --base-url BASEURL         URL where you can find client.php.
 --profile PROFILENAME      The profile to use (development/production/custom).

 --clean-views              Clean views (must be used with --clean).

1.1.3.2. Examples of Use

1.1.3.2.1. Basic Setup

To perform a basic setup of CartoWeb, such as if you want to run the demo project, type:

<PHP-INTERPRETER> cw3setup.php --install --base-url 
            http://www.example.com/cartoweb

In this example, http://www.example.com/cartoweb is the address which corresponds to the cartoweb3/htdocs directory. You should find client.php if you type this URL.

1.1.3.2.2. Installing a Project from a Directory

<PHP-INTERPRETER> cw3setup.php --install --fetch-project-dir 
            /home/foo/my_project --base-url http://www.example.com/cartoweb

1.1.3.2.3. Updating CartoWeb after Modifications

When you modify or add new content/features to CartoWeb, you need to update it. This will set relative links or copy new/modified resources files (templates, images, new plugins, ...)

<PHP-INTERPRETER> cw3setup.php --install --base-url 
            http://www.example.com/cartoweb

Same as Section 1.1.3.2.1, “Basic Setup”. Existing files are not overwritten.

1.1.3.2.4. Cleaning Generated Files (Map, PDF, Temporary Files and Smarty Cache)

<PHP-INTERPRETER> cw3setup.php --clean

1.1.3.2.5. Fetching the Demo Data

<PHP-INTERPRETER> cw3setup.php --fetch-demo

1.1.3.2.6. Install or Reinstall CartoWeb from CVS and Set Up It at Once
1.1.3.2.6.1. Install

<PHP-INTERPRETER> cw3setup.php --install --cvs-root 
              :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public
              --fetch-from-cvs --base-url http://www.example.com/cartoweb

Note

Do no execute this command from the cartoweb3 folder! Because this will fetch the whole cartoweb3 hierarchy from cvs, including the cartoweb3 folder. If you executed this from the cartoweb3 folder you would end up with something like cartoweb3/cartoweb3/.... Instead, copy the cw3setup.php in the parent directory, delete (or backup) the cartoweb3 folder and execute the command.

1.1.3.2.6.2. Reinstall

<PHP-INTERPRETER> cw3setup.php --install --cvs-root 
              :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public
              --fetch-from-cvs --delete-existing
              --base-url http://www.example.com/cartoweb

Warning

This command will automatically delete the existing cartoweb3/ folder! Be sure to backup the files and projects you wish to keep.

Note

See note on Section 1.1.3.2.6.1, “Install”. Notice here the --delete-existing parameter. Needed here because cartoweb3/ already exists. Without it the cw3setup script issues a warning and stops.

1.1.3.2.7. Update CartoWeb from CVS

To keep your CartoWeb up-to-date with the development version, simply type the following command in the CartoWeb root folder:

cvs -d :pserver:anonymous@dev.camptocamp.com:/var/lib/cvs/public update

Warning

This may have some serious effects on your existing developments, it is recommended you backup the CartoWeb root folder and all subforders before execution.

1.1.4. Windows Installation

1.1.4.1. Windows Install with Win32 Installer (Recommended)

Once it is installed, you can modify CartoWeb setup with the command-line script cw3setup.php (Section 1.1.3, “UNIX-like Installation”) from either a DOS or a Cygwin prompt. See Section 1.1.4.3, “CartoWeb Setup” for more info about how to use those interfaces.

1.1.4.2. Windows Manual Install

Instructions for Apache/PHP and MapServer installation are given in Appendix B, Apache & Mapserver Windows Manual Installation

Then download CartoWeb as described above (Section 1.1.2, “CartoWeb Download”).

Eventually set CartoWeb up with the command-line script cw3setup.php (Section 1.1.3, “UNIX-like Installation”) from either a DOS or a Cygwin prompt. See Section 1.1.4.3, “CartoWeb Setup” for more info about how to use those interfaces.

1.1.4.3. CartoWeb Setup

1.1.4.3.1. CartoWeb Setup with DOS

Open a command prompt (Start menu > Run > "cmd") and go to the CartoWeb root:

cd C:\wamp\www\cartoweb3

Then see Section 1.1.3.2.1, “Basic Setup”

Note

To enable you to execute PHP scripts easily (like php cw3setup.php --someparameters instead of C:\wamp\php.exe cw3setup.php --someparameters), set the path to the PHP binary in your PATH environment variable (control panel > system > Advanced > Environment Variables. If there is no PATH variable, add a new one. If a PATH variable is already present, you can add the path to php.exe at the end of the existing path values, but add a ";" inbetween: path1;path2;path3):

C:\wamp\php;

The example above is true if the PHP binary are installed in C:\wamp\php.

Note

If you are using the demo, you need to have Gettext support installed, as it uses Gettext by default. If you used the win32 installer, Gettext is already installed, otherwise you must install it manually. You can get a version of Gettext for Windows there http://gnuwin32.sourceforge.net/packages/gettext.htm. Also set the path to the Gettext binary in your PATH environment variable.

C:\Program Files\GnuWin32\bin;

The example above is true if the Gettext binaries are installed in C:\Program Files\GnuWin32\bin. This is needed by the po2mo.php script to merge and compile the languages translation files.

Note

If you intend to use CVS in command line, you need to install a CVS client. Use WinCVS or TortoiseCVS, both are free Open Source clients. You must add the path to the CVS binary in your PATH environment variable.

C:\Program Files\TortoiseCVS;

The example above is true if you installed TortoiseCVS in C:\Program Files\TortoiseCVS.

1.1.4.3.2. CartoWeb Setup with Cygwin

Open a Cygwin window and go to the CartoWeb root:

cd C:
cd wamp/www/cartoweb3/

Then see Section 1.1.3.2.1, “Basic Setup”

Note

You can download Cygwin here Cygwin . When you install Cygwin, be sure to select the packages tar (or unzip) and cvs. You can also install the gettext-devel package, so you wont need to get an external gettext installation later. If you have already installed Cygwin, type the following command to see what package are currently installed.

cygcheck -c

If the packages mentioned above are not present, run Cygwin setup again and add the missing packages.

Note

To enable you to execute PHP scripts easily, set the path to the PHP binary in your .bashrc (in C:\cygwin\home\Administrator\ by default):

export PATH=$PATH:/cygdrive/c/wamp/php

The example above is true if the PHP binary are installed in c:\wamp\php.

If you do not want to install the cvs and gettext Cygwin package, you need to add also the path to the external CVS and gettext binaries.

export PATH=$PATH:/cygdrive/c/program Files/GnuWin32/bin
export PATH=$PATH:/cygdrive/c/program Files/TortoiseCVS

See the note in Section 1.1.4.3.1, “CartoWeb Setup with DOS”

1.2. Demos Installation

1.2.1. Introduction

A few demos are embedded in CartoWeb to demonstrate the range of functionalities that CartoWeb offers and give users examples on how to implement them:

  • demoCW3 : this is an overview of the standard functionalities that are somehow visible for an end-user in CartoWeb,
  • demoPlugins : it shows the new functionalities that are available in CartoWeb since the latest version,

Demo data are freely downloadable. Next section explains how to install them. Configuration and programming details are then described.

1.2.2. Installation

Before installing these demos, you need to have a working CartoWeb installation. You can refer to the previous chapters how to install it.

To install the demoCW3 project, you need to gather the data by launching the cw3setup.php with the --fetch-demo option.

On the other hand, the demoPlugins project uses plugins that work with databases. Consequently some databases settings and configuration are required. We describe here how to install these databases and how to use cw3setup.php.

Step by step guide:

  1. Install PostgreSQL with PostGIS support.  Prerequisite: Postgresql >= 8.0

    Note

    If you are on Debian, you can have a look at Appendix A, Mapserver Debian Installation

  2. Create a PostgreSQL database using the following command: 

    $ createdb demo_plugins

  3. Integrate PostGIS functionalities in this database.  Typically, you can type:

    $ createlang plpgsql demo_plugins
    $ psql -d demo_plugins -f lwpostgis.sql
    $ psql -d demo_plugins -f spatial_ref_sys.sql

    Note

    psql is a terminal-based front-end for PostgreSQL. It enables you to type in queries interactively, issue them to PostgreSQL, and see the query results. Don't forget to specify its location on your system to use it. If the lwpostgis.sql and spatial_ref_sys.sql files aren't in the current directory, you have to specify their path.

  4. Create tables used by the DemoLocation extension to allow you to do a search by name.  To do so, you should export the free downloadable layers airport, agglo, district and town in PostgreSQL/PostGIS tables by typing the following command:

    $ shp2pgsql aerofacp.shp airport > /tmp/aiport.sql
    $ psql -d demo_plugins -f /tmp/airport.sql
    
    $ shp2pgsql builtupa.shp agglo > /tmp/agglo.sql
    $ psql -d demo_plugins -f /tmp/agglo.sql
    
    $ shp2pgsql polbnda.shp district > /tmp/district.sql
    $ psql -d demo_plugins -f /tmp/district.sql
    
    $ shp2pgsql mispopp.shp town > /tmp/town.sql
    $ psql -d demo_plugins -f /tmp/town.sql

    Note

    shp2pgsql is a command-line program that exports a shapefile into SQL commands. Don't forget to specify its location on your system to use it. You have to specify the path to the shapefiles if they aren't in the current directory.

  5. Execute cw3setup.php file, with the --fetch-demo option to download geographic datas.

  6. cw3setup.php Options.  To finish demoPlugins installation, you will need to launch the cw3setup.php with the --config-from-file parameter pointing to a property file containing database configuration informations. Such a file is provided in the cartoweb3/projects/demoPlugins/demo.properties file. You need to edit this file and change the parameter to match your environment. In particular the DB_HOST, DB_USER, DB_PASSWD and DB_PORT options need to match your database access configuration. This file contains comments about the description of each variables. Here's an example how to call the cw3setup.php script with the --config-from-file option.

    php cw3setup.php --install --base-url http://www.example.com/cartoweb 
                    --config-from-file projects/demoPlugins/demo.properties

Note

Routing fonctionnalities are also integrated in this demo. But they need a more advanced configuration and the Pgdijkstra module installed in the database, so they aren't integrated in the basic installation. The steps to integrate routing fonctionnalities and create database tables are described in next section.

1.2.3. Routing specific installation

  • Install the Pgdijkstra PostgreSQL module. 

    Note

    To do so,

  • Execute the dijkstra.sql file to install the functions in your database by typing: 

    $ psql -d demo_plugins -f dijkstra.sql

  • If you have PostGIS installed, you should launch dijkstra_postgis.sql

    $ psql -d demo_plugins -f dijkstra_postgis.sql

  • Import Europe road geodata in PostGIS, create its graph structure and configure plugin routing database.  To do so, simply execute the demo_routing.sql file, located in the <CARTOWEB_HOME>/projects/demoPlugins/server_conf/sql directory.

    Note

    These steps are detailed in the next section.

  • Edit the cartoweb3/projects/demoPlugins/demo.properties file.  and uncomment the line beginning with ;ROUTING_PLUGINS

  • Execute cw3setup.php file, with the --config-from-file option as described in the previous steps.

1.2.4. Extensions Description

1.2.4.1. demoLocation Extension

This extension allows you to select geographic objects of a layer by specifying a name.

According to the name selected, the corresponding id is fetched from the search name database and submitted to the recentering coreplugin. This coreplugin selects the geographic object in the shapefile according to the id, the selected layer and recenter on it.

The names of the id and the names on which the search is done must be specified in the metadata of the mapfile for each queryable layer. These metadata are respectively "id_attribute_string" for the id and "recenter_name_string" for the name. You also will have to use the metadata "exported_values" to transmit these metadata to the client. For example, you can type:

METADATA
  "exported_values" "recenter_name_string,id_attribute_string"
  "recenter_name_string" "NAM"
  "id_attribute_string" "OGC_FID|string"
END

The name of the database must be specified in the location.ini file.

Note

In the location.ini, you also need to specify the layers on which you want to do a search by name (idRecenterLayers options) and activate the coreplugin idRecenter (idRecenterActive option).

1.2.4.2. demoRouting Extension

The routing module is a set of functions that compute a shortest path from a set of edges and vertices. Some functions are provided for importing data from geometric tables, and for generating results as geometries.

Note

For more information on these functions, you can have a look to the routing module README file http://www.cartoweb.org/downloads/pgdijkstra/README.txt.

This section explains the main steps to integrate the routing fonctionnalities in a custom application. We describe the steps followed to install the routing demo. To make short, we used an Europe roads shapefile, imported it in PostGIS, generated the graph tables and configured files to suggest a search of the shortest path between two European towns.

1.2.4.2.1. Europe Road Geodata Importation in PostGIS

$ shp2pgsql roadl.shp roads_europe_tmp > /tmp/roadl.sql
$ psql -d demo_plugins -f /tmp/roadl.sql

1.2.4.2.2. Graph Importation

The first step is to delete unneeded columns of the table roads_europe_tmp. To do so, you can type:

$ CREATE TABLE roads_europe (gid int UNIQUE, source_id int, target_id int);
$ SELECT AddGeometryColumn('roads_europe', 'the_geom', -1, 'MULTILINESTRING', 2 );
$ INSERT INTO roads_europe (gid, the_geom) (SELECT gid, the_geom FROM roads_europe);

The resulting table is so roads_europe. You can then fill the columns source_id and target_id with the "assign_vertex_id" function.

$ SELECT assign_vertex_id('roads_europe', 1);

Here is the content of the roads_europe table:

$ SELECT gid, source_id, target_id, edge_id, AStext(the_geom) FROM roads_europe limit 3;
 
  gid  | source_id | target_id | edge_id |                              AStext
-------+-----------+-----------+---------+----------------------------------------------
 13115 |     11051 |     11099 |      14 | MULTILINESTRING((1062096.06 4861316.234,...))
 12869 |     10918 |     10916 |     267 | MULTILINESTRING((250681.597 4779596.532,...))
 12868 |     10918 |     10913 |     268 | MULTILINESTRING((250681.597 4779596.532,...))
(3 lignes)

But if the data quality is poor, you need to delete the duplicates edges (they have the same source-target pairs of vertices). For example, to check that you have duplicated edges, you can type:

$ SELECT * FROM (SELECT source_id, target_id, count(*) AS c FROM roadl group by 
source_id, target_id order by c)
AS foo where foo.c = 2;

If there is duplicated edges, to delete one of two rows, you can type:

$ CREATE TABLE roads_europe_tmp AS SELECT * FROM roads_europe WHERE gid  in
(SELECT gid FROM (SELECT DISTINCT on (source_id, target_id) source_id, gid 
FROM roads_europe) AS doublon);
$ DELETE FROM roads_europe;
$ INSERT INTO roads_europe (SELECT * FROM roads_europe_tmp);
$ ALTER TABLE roads_europe ADD COLUMN edge_id int;

The following step is to create and fill the edges and vertices tables of the resulting graph. To do so, you can use "create_graph_tables" function.

$ SELECT create_graph_tables('roads_europe', 'int4');

SELECT * FROM roads_europe_edges LIMIT 3;
 id | source | target | cost | reverse_cost 
----+--------+--------+------+--------------
  1 |      1 |      2 |      |             
  2 |      3 |      3 |      |             
  4 |      2 |      2 |      |             
(3 rows)

We can see that it contains NULL values for the cost column. The function update_cost_from_distance can update the cost column with the distance of the lines contained in the geometry table, attached to each edge:

$ SELECT update_cost_from_distance('roads_europe');

The costs are now:

 id | source | target |       cost       | reverse_cost
----+--------+--------+------------------+--------------
  1 |      1 |      2 | 6857.46585793103 |
  2 |      3 |      4 | 37349.9592156392 |
  3 |      5 |      6 | 14040.5673116933 |
(3 lignes)

Now, all is set up correctly for using the shortest path function on these data. But to include the routing fonctionnalities in a custom project, we must respect some rules dictated by the routing plugin.

1.2.4.2.3. Routing Plugin Database Configuration

The two things to do are to:

  • create the routing results table. In this example the table is routing_results.
    $ CREATE TABLE routing_results (
        results_id integer,
        "timestamp" bigint,
        gid integer
      );
    $ SELECT AddGeometryColumn('','routing_results','the_geom','-1',
    'MULTILINESTRING',2);
  • create the 'routing_results_seq' sequence.
    $ CREATE SEQUENCE routing_results_seq
        INCREMENT 1
        MINVALUE 1
        MAXVALUE 9223372036854775807
        START 1
        CACHE 1;

1.2.4.2.4. Mapfile Configuration

In the mapfile, you must include the routing layer, its connection to the database, a symbology for the route and a first route using a unique identifier. The data parameter will be overwritten by the routing plugin to draw the route chosen by the end-user. Example:

LAYER
  NAME "graph"
  TYPE LINE
  TRANSPARENCY 80
  CONNECTIONTYPE postgis
    CONNECTION "user=@DB_USER@ password=@DB_PASSWD@ host=@DB_HOST@ dbname=@DB_NAME@"
    DATA "the_geom from (SELECT the_geom from routing_results) as foo using unique
    gid using srid=-1"
  TEMPLATE "t"
  CLASS
    NAME "0"
    STYLE
      SYMBOL "circle"
      SIZE 10
      COLOR 90 27 191
    END
  END
END

1.2.4.2.5. General Configuration

For the demo, we suggest that you select your route by starting from a town until an other town. This is possible because for each object of a european-towns layer, we have identified the nearest object of the roads_europe_vertices table. That is why in the demoRouting configuration there is a client-side configuration. Normally, in the plugin routing, client-side only allows you to type an id of object, from which to start and an other to finish the route. No configuration is needed. So, if you use demoRouting extension, you must specify client-side, the:

  • postgresRoutingVerticesTable: vertices table
  • stepName: vertices table col containing informations you want to propose a choice on
  • dsn: the connexion string to the database

Anyway, server-side, you must specify :

  • the routing table (postgresRoutingTable option),
  • the routing layer in the mapfile (postgresRoutingResultsLayer option),
  • the results routing table (postgresRoutingResultsTable),
  • the connexion string to the database (dsn option).

valid xhtml 1.0 valid css