Portable GIS v3.1 Documentation

Contents

Included software (with versions)....................................................................................................2Links to websites for package-specific documentation...................................................................2How to begin using Portable GIS....................................................................................................2

Using the Portable GIS Control Panel........................................................................................3Portable GIS-Specific Instructions..................................................................................................3

Quantum GIS..............................................................................................................................3GDAL/OGR................................................................................................................................4Python.........................................................................................................................................4Loader.........................................................................................................................................4Apache........................................................................................................................................4PostgreSQL.................................................................................................................................5Mapserver....................................................................................................................................5Other utilities...............................................................................................................................5

Data..................................................................................................................................................5License.............................................................................................................................................6

1

Included software (with versions)

• Quantum GIS (1.8.0)

• PostgreSQL (9.0.6)

• PostGIS (1.5.3)

• MS4W (3.0.4, including Mapserver 5.6 and 6.0)

• PgAdmin III (1.12.3)

• Python (2.7)

• Loader

• GDAL Python Libraries (1.9)

The following utilities are also included:

• Firefox (Portable)

• Geany Text Editor (Portable)

• Foxit PDF Reader (Portable)

Links to websites for package-specific documentation

• Quantum GIS: http://www.qgis.org/

• PostgreSQL: http://www.postgresql.org/

• PostGIS: http://postgis.refractions.net/

• PgAdmin III: http://www.pgadmin.org/

• MS4W: http://www.maptools.org/ms4w

• Python: http://www.python.org

• Loader: http://github.com/AstunTechnology/Loader

How to begin using Portable GIS

If you installed the software from the installer to either your C drive or a removable drive such as a USB stick you should see a directory called “usbgis” and a file called “portablegis.exe”. Double-clicking on portablegis.exe will start the Portable GIS control panel. Note that if installed on a USB stick packages may take longer to load than you are used to, due to the slower speed of the USB stick!

While all care has been taken to minimise incompatibility with previously installed versions of these packages, the author cannot guarantee that problems won't occur. Portable GIS is not a

2

“stealth” installation where no trace will be left on your hard drive, and similarly some programs may pick up dlls from your system, or values from your registry.

The Control Panel gives access to the majority of the programs contained within Portable GIS and allows you to cleanly start and stop the server-based processes Apache and PostgreSQL. You should only start and stop these using the control panel to ensure that they start and stop cleanly.

Note that Apache and PostgreSQL are installed on non-default ports (88 and 5433 respectively) to try and avoid conflict with existing installations.

Using the Portable GIS Control Panel

Starting the Control Panel as described above opens up a menu with three tabs:

• Welcome to Portable GIS

This tab explains where to go to get help and training.

• Desktop Modules

This tab gives access to all the desk-top packages contained within Portable GIS, split into sections for Desktop GIS including PgAdmin3 (remember to turn on PostgreSQL from the Web Modules tab before starting!), Utilities, and Loader.

• Server Modules

This tab allows you to switch on the server-based components of Portable GIS- Apache and PostgreSQL. Click the “start” radio buttons to start the packages you need. Note that your firewall might try to block these packages, but they are safe to run. Click the “stop” or “restart” radio buttons to safely restart or close these packages down. Portable GIS will close all the web services when the Control Panel is closed.

Once you have started at least the Apache server, web-based components can be accessed at http://localhost:88.

• Utilities

This tab gives you access to the bundled web browser, pdf reader and text editor.

Portable GIS-Specific Instructions

Note that these instructions relate only to the specifics of the Portable GIS setup, and are not comprehensive instructions for using the software. These can be found at the relevant project websites, listed above.

Quantum GIS

Quantum GIS can be started from the control panel Desktop Modules tab. Quantum GIS includes the GRASS plugin, but no mapbase has been set up- this must be done by each user. Quantum GIS can have additional plugins installed- these can be accessed from the plugins menu.

The speed at which Quantum GIS starts up is partially determined by the number of plugins you

3

have loaded. Disable all plugins that are not required to see a significant improvement in load times. Note that this information is stored in the windows registry, therefore it was not possible to set this as part of the default installation.

To use the QGIS-Server with apache, store your QGIS projects in \usbgis\apps\qgis\projects and call the GetCapabilities request using:

http://localhost:88/qgis/qgis_mapserv.fcgi.exe?service=wms&version=1.3.0&request=GetCapabilities&map=G:\usbgis\apps\qgis\projects\your_project.qgs

GDAL/OGR

This option opens a windows command prompt at the correct location for accessing the ogr and gdal tools with the correct environment variables set. Please note that these environment variables are set only for the session initiated using the control panel menu, so the tools may not work if accessed independently.

Python

The python interpreter can be accessed from the Desktop Modules tab in the control panel- this will start the interactive python command prompt. For use in scripts, the python executable should be used- this can be found at \usbgis\apps\python27\App\python.exe

The python install includes easy_install for installing additional python libraries. Please see the python documentation for usage. The module lxml has been included as it is a requirement for Loader to run (see below).

To use the gdal libraries, use “from osgeo import gdal” in your python interpreter or scripts.

Loader

Loader is an Astun Technology tool that allows the simple loading of KML and GML into a postgresql database, using Python. Iit can be found in ..\usbgis\apps\loader. It must be configured before use, using the text-based config file, loader.config, which is found in \..usbgis\apps\loader\python but can be accessed from the Desktop Modules tab in the control panel. Once configured, it should be run using the “Run Loader” button. This will open a command prompt into which the correct syntax must be entered (an example is given).

Note that Loader will work much more quickly if a temporary working directory is set up on the C drive rather than on a removable disk. The location of this directory can be set using the Tools Menu → “Set Working Directory”. This will also set an environment variable %TMPDIR% which can be used in the Loader config file as the temporary output directory. The Tools Menu → “Empty working directory” will remove any files from the output directory.

Apache

The directory that all web pages should be installed in is as follows: ..\usbgis\apps\ms4w\Apache\htdocs.

Pages in this directory (and sub folders) will be accessible via http://localhost:88. There is an

4

example OpenLayers map, using data included in the ..\usbgis\data\OpenData folder at http://localhost:88/opendatamap.htm and some information on the MS4W components at http://localhost:88/README_INSTALL.htm

To run cgi scripts, please place them in the folder: ..\usbgis\apps\ms4w\Apache\cgi-bin, or edit the apache configuration files (see below) to give the server permission to execute scripts from other folders.

The apache configuration files can be found in: ..\usbgis\apps\ms4w\Apache\conf. Please note that changes to this file may cause apache to stop working.

PostgreSQL

PostgreSQL is set up with the following options: Default username: pgis Password: pgis. Please create new users if you wish to use this installation in a public environment. The data directory is ..\usbgis\data\PGDATA, and the log file is in: ..\usbgis\data\pg_log.

Please use the IP address 127.0.0.1 to refer to the database on the local PostgreSQL server if you are using Windows Vista or later.

The postgis extensions are installed in the template database template_postgis, so new databases must be created using that template to be spatially enabled. PostgreSQL can be administered with the tool PgAdmin3 from the control panel, or with the command line tools found here: ..\usbgis\apps\postgresql\bin.

Mapserver

There are two versions of Mapserver installed- versions 5.6 and 6.0. These are installed in usbgis\apps\ms4w\Apache\cgi-bin and usbgis\apps\ms4w\Apache\cgi-bin5.6 respectively. The example Mapserver .map file \usbgis\data\_MapserverConfig\OSOpenData.map includes the syntax for both versions but is currently set to use version 5.6. This map file contains the correct configuration for fonts, symbols, proj and shapepath so new files should follow this syntax and be placed in the same folder.

Mapserver can be tested at the browser using http://localhost:88/cgi-bin56/mapserv.exe and http://localhost:88/cgi-bin/mapserv.exe for versions 5.6 and 6 respectively. Called with no additional parameters, it will display an error message.

Mapserver 6 comes with a built in openlayers viewer, that can be called using the new syntax “mode=browse&template=openlayers”. This will call an openlayers javascript library located on the mapserver website by default, but a local copy of this library has been provided. To use this, add the following line to your mapserver 6 map file at map level:

CONFIG “MS_OPENLAYERS_JS_URL” “http://localhost:88/cgi-bin/openlayers/openlayers-ms60.js”

Note that this will not work with Mapserver 5.6.

Other utilities

PortableGIS contains portable versions of Firefox, a text editor called Geany, and Foxit PDF

5

Reader. These can be accessed from the relevant folders of ..\usbgis\apps but will not launch as the default applications for web browsing, editing text or reading pdfs unless specifically set.

Data

Some Ordnance Survey open data is included within this distribution for testing purposes. This can be found in the ..\usbgis\data\OpenData folder. This includes Ordnance Survey Open Data for a region of Southampton. The map files in ..\usbgis\data\_MapserverConfig and the osopendatamap.htm file in ..\usbgis\apps\ms4w\Apache\htdocs are configured to use this data. These map files are also configured to use some sample Mastermap data, loaded into a database called mapbase. As we are unable to distribute this data, the user will need to download it from http://www.ordnancesurvey.co.uk/docs/sample-data/os-mastermap-topography-layer-sample-data.zip. If this is extracted into the folder ..\usbgis\data\OpenData\OS MasterMap then the default config file for Loader will be configured to load it into the correct database.

License

This product as a whole is distributed under the GNU General Public License version 3, but it is subordinate to the License Agreements of the constituent software packages. These may be more or less restrictive than the GNU GPL. Please ensure that you agree with the terms of all the licenses before using this software- these can be found in the folders for the constituent programs.

The full license can be found at: .\usbgis\docs\license.txt

6