OSGB Web Map Tools v2.0

• OSGB Web Map Tools API
• OSGB Web Map Tools raster preparation
• Configuration files for GeoServer, a geospatial data server.
• Documentation

These tools enable you to build dynamic maps for your web site and other applications.

Although the OSGB Web Map Tools project does not provide free access to Ordnance Survey data sets, it has been designed specifically to work with Ordnance Survey data. To use Ordnance Survey data you will need a data licence. Ordnance Survey has a wide range of data licences available for businesses and other commercial requirements.
For more information see: http://ordnancesurvey.co.uk/oswebsite/business/

The OSGB Web Map Tools API comprises the following:

• A map viewer.
• Map panning, zooming and overview map controls.
• Map styling, including markers and vector overlays.
• Transformation of National Grid Coordinates to and from WGS84 latitude and longitude.

The OSGB Web Map Tools project is released subject to a BSD licence as set out below.

This open source project should not be confused with OS OpenSpace® which does allow access to some Ordnance Survey data sets by signing up to the Ordnance Survey OpenSpace Developer Agreement where there are terms and conditions and usage limits that apply. The Ordnance Survey OpenSpace Developer Agreement can be found at http://openspace.ordnancesurvey.co.uk/openspace/.

Licence

  Crown Copyright (c) 2009, Secretary of State for Communities and Local Government,
  acting through Ordnance Survey.
  All rights reserved.
 
  Redistribution and use in source and binary forms, with or without modification,
  are permitted provided that the following conditions are met:
 
    Redistributions of source code must retain the above copyright notice,
    this list of conditions and the following disclaimer.
  
    Redistributions in binary form must reproduce the above copyright notice,
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.
  
    Neither the name of the Secretary of State for Communities and Local Government,
    acting through Ordnance Survey nor the names of its contributors
    may be used to endorse or promote products derived from this software
    without specific prior written permission.
 
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  OF THE POSSIBILITY OF SUCH DAMAGE.

Installation Guide

Overview

Licence

Tile Preparation

GeoServer Installation

GeoServer Configuration

API Installation

API Build (optional)

OSGB Web Map Tools Tile Preparation

Overview

The tile mosaic batch process takes standard Ordnance Survey raster TIFF image files and converts them into GeoTIFF format ready to be served as a coverage from GeoServer (using the ImageMosaic plugin). Some of the raster data sets are resampled to provide suitable intermediate steps when zooming the map in and out. This process will normally be run once when the server is setup, but can be run anytime the Ordnance Survey raster data is updated.

The GeoServer ImageMosaic plugin allows the creation of a mosaic from a number of georeferenced rasters. The following files are provided by this installation in order to configure a new coverage with this plugin:

1. A shapefile that contains enclosing polygons for each raster file.
2. A projection file (.prj) for the above-mentioned shapefile.
3. A configuration file (.properties). This file contains properties such as cell size in x and y direction, the number of rasters for the ImageMosaic coverage, etc.

System Requirements

Windows

This set of instructions will install OSGBWebMapTools onto a Windows platform and requires administrator rights to the machine.

OSGBWebMapTools

OSGBWebMapTools 2.0
Project home: http://sourceforge.net/projects/osgbwebmaptools/
Download link: http://sourceforge.net/projects/osgbwebmaptools/files/osgbwebmaptools/osgbwebmaptools-2.0/OSGBWebMapTools-2.0.zip/download

1. Extract the OSGBWebMapTools-2.0.zip archive to the root of your C: drive. This will create a folder c:\OSGBWebMapTools-2.0. NOTE: This installation is different from OSGBWebMapTools-1.0, and so it is advisable to remove any files and directories used in any previous installations.

GDAL/OGR

GDAL 1.6.2 release (Minimalist Windows Executables)
Project home: http://www.gdal.org
Download link: http://download.osgeo.org/gdal/win32/1.6/gdalwin32exe160.zip

1. Extract the gdalwin32exe160.zip archive to the root of your C: drive. The data preparation process uses two executables - gdal_translate and gdalwarp - which should be found in C:\gdalwin32-1.6\bin.

Data Requirements

Ordnance Survey raster map image data in TIFF format, along with the corresponding TIFF World files.
NOTE: You must already have access to this data, no Ordnance Survey raster data is included with this installation.

• Overview1
• Overview2
• MiniScale®
• 1:250 000 Scale Colour Raster (referred to as 250k below)
• 1:50 000 Scale Colour Raster (referred to as 50k below)
• (Optional) 1:25 000 Scale Colour Raster (referred to as 25k below)
• OS Street View®

Data Preparation

1. Create a folder c:\Data\OrdnanceSurvey this will be the top level of the source Ordnance Survey raster data.
2. In that folder we will then create the individual data layers folders and copy the source raster data TIFF and TIFF World files to them. NOTE: The TIFF images should all be stored in a single directory - and not in 100km [HP, HT, HU, etc] or any other sub-directories.
3. Create a folder c:\Data\OrdnanceSurvey\UK_Overview and copy the UK_Overview_1.tif, UK_Overview_1.tfw, UK_Overview_2.tif and UK_Overview_2.tfw files to it.
4. Create a folder c:\Data\OrdnanceSurvey\MiniScale and copy the MiniScale.tif and MiniScale.tfw files to it.
5. Create a folder c:\Data\OrdnanceSurvey\250k and copy all the 250k TIFF and TFW files to it.
6. Create a folder c:\Data\OrdnanceSurvey\50k and copy all the 50k TIFF and TFW files to it.
7. Create a folder c:\Data\OrdnanceSurvey\25k and copy all the 25k TIFF and TFW files to it.
8. Create a folder c:\Data\OrdnanceSurvey\StreetView and copy all the StreetView TIFF and TFW files to it.
9. Create a folder C:\OSGBWebMapTools\Data\Tiles and copy the contents of the c:\OSGBWebMapTools-2.0\Data\Tiles folder to it. This should create a series of sub-directories each containing an equivalently named ESRI Shapefile and properties file (as used by the ImageMosaic plugin).
10. (Optional) If you have installed the raster data into another directory, edit the C:\OSGBWebMapTools\Data\Tiles\gdal_translate.bat file and set the input path environment variables to the directories where your raster map image data is stored.
11. Run C:\OSGBWebMapTools\Data\Tiles\gdal_translate.bat by double clicking on the file. This will generate a series of expanded RGB GeoTIFF images from the Ordnance Survey raster map image data (using gdal_translate). It will also generate resampled versions of the images to provide the intermediate steps when zooming the map (using gdalwarp). NOTE: This process will likely take over a day to run.
12. When the process has finished the command window will be left open, type any key to close.

OSGB Web Map Tools GeoServer Installation

Overview

GeoServer is an open source software server written in Java that allows users to share and edit geospatial data. Designed for interoperability, it publishes data from any major spatial data source using open standards.
This server component enables the serving of the Ordnance Survey raster map tiles.

System Requirements

Java

Java SE Development Kit 1.6 (JDK)
Project home: http://java.sun.com

Tomcat 6 (or equivalent web application container)

Project home: http://tomcat.apache.org
Download link for Windows: http://mirror.public-internet.co.uk/ftp/apache/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.exe
Binary core Windows Service Installer version.
Change port 8080 to port 80 in Tomcat's conf/server.xml file if you are intending to run an externally accessable website.
Install the Tomcat manager http://tomcat.apache.org/tomcat-6.0-doc/manager-howto.html

GeoServer

GeoServer 1.7.6
Project home: http://geoserver.org
Installation instructions are at: http://docs.geoserver.org/1.7.6/user/installation/index.html
This installation uses the GeoServer Web Archive (WAR) mode which runs inside of an external Tomcat servlet container.
Download link: http://downloads.sourceforge.net/geoserver/geoserver-1.7.6-war.zip
Follow the web archive installation instructions at http://docs.geoserver.org/1.7.6/user/installation/geoserver-install.html#war-install
Install the GeoServer WAR file through the Tomcat manager interface http://localhost/manager/html.

GeoServer Configuration

1. Stop GeoServer via the Tomcat manager interface (if it is running).
2. Copy the contents of the c:\OSGBWebMapTools-2.0\GeoServerConfiguration\coverages folder to your GeoServer C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\geoserver\data\coverages directory
   This will create a series of sub-directories, one for each layer, each containing a pre-configured ImageMosaic coverage (in the info.xml file).
3. Open the file c:\OSGBWebMapTools-2.0\GeoServerConfiguration\namespace.txt file with a text editor.
4. Select and copy all the contents (CTRL_A followed by CTRL-C). Close the editor.
5. Open the file C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\geoserver\data\catalog.xml file with a text editor.
   NOTE: catalog.xml contains a list of all the data sources that GeoServer is configured to serve.
6. Locate the <namespaces> element within catalog.xml - and append the "osgb" namespace (as copied above) to it. The <namespaces> element within catalog.xml should now look as follows:

                    
<namespaces>
  <namespace prefix = "cite" uri = "http://www.opengeospatial.net/cite" />
  <namespace prefix = "it.geosolutions" uri = "http://www.geo-solutions.it" />
  <namespace prefix = "tiger" uri = "http://www.census.gov" />
  <namespace prefix = "sde" uri = "http://geoserver.sf.net" />
  <namespace default = "true" prefix = "topp" uri = "http://www.openplans.org/topp" />
  <namespace prefix = "sf" uri = "http://www.openplans.org/spearfish" />
  <namespace prefix = "nurc" uri = "http://www.nurc.nato.int" />
  <namespace prefix = "osgb" uri = "http://www.ordnancesurvey.co.uk/xml/namespaces/osgb" />
</namespaces> 
                

The contents of c:\OSGBWebMapTools-2.0\GeoServerConfiguration\catalog.txt should then be added to the <formats> element in C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\geoserver\data\catalog.xml as follows:

                    
<formats>
  <!--
    a format configuration element serves as a common data source
    parameters repository for all coverages it holds.
  -->
  <format id = "arcGridSample" enabled = "true" namespace = "nurc" >
    <title>arcGridSample</title>
    <type>ArcGrid</type>
    <url>file:coverages/arc_sample/precip30min.asc</url>
  </format>
  ...
  ...
  ...
  <format id = "25k" enabled = "true" namespace = "osgb" >
    <title>25k</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\25k\25k.shp</url>
  </format>
  <format id = "50k" enabled = "true" namespace = "osgb" >
    <title>50k</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\50k\50k.shp</url>
  </format>
  <format id = "50kResampled" enabled = "true" namespace = "osgb" >
    <title>50kResampled</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\50kResampled\50kResampled.shp</url>
  </format>
  <format id = "250k" enabled = "true" namespace = "osgb" >
    <title>250k</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\250k\250k.shp</url>
  </format>
  <format id = "250kResampled" enabled = "true" namespace = "osgb" >
    <title>250kResampled</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\250kResampled\250kResampled.shp</url>
  </format>
  <format id = "MiniScale" enabled = "true" namespace = "osgb" >
    <title>MiniScale</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\MiniScale\MiniScale.shp</url>
  </format>
  <format id = "MiniScaleResampled" enabled = "true" namespace = "osgb" >
    <title>MiniScaleResampled</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\MiniScaleResampled\MiniScaleResampled.shp</url>
  </format>
  <format id = "Overview1" enabled = "true" namespace = "osgb" >
    <title>Overview1</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\Overview1\Overview1.shp</url>
  </format>
  <format id = "Overview2" enabled = "true" namespace = "osgb" >
    <title>Overview2</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\Overview2\Overview2.shp</url>
  </format>
  <format id = "Overview2Resampled" enabled = "true" namespace = "osgb" >
    <title>Overview2Resampled</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\Overview2Resampled\Overview2Resampled.shp</url>
  </format>
  <format id = "StreetView" enabled = "true" namespace = "osgb" >
    <title>StreetView</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\StreetView\StreetView.shp</url>
  </format>
  <format id = "StreetViewResampled" enabled = "true" namespace = "osgb" >
    <title>StreetViewResampled</title>
    <type>ImageMosaic</type>
    <url>file:C:\OSGBWebMapTools\Data\Tiles\StreetViewResampled\StreetViewResampled.shp</url>
  </format>
</formats>
                

7. Save the changes you have made to catalog.xml
8. Restart GeoServer to initiate all the ImageMosaic coverages for the Ordnance Survey raster map image datasets.

OSGB Web Map Tools API Installation

1. Copy the c:\OSGBWebMapTools-2.0\OSGBWebMapTools folder into the ROOT directory of the Tomcat installation C:\Program Files\Apache Software Foundation\Apache Tomcat 6.0.20\webapps\ROOT.
2. Open C:\Program Files\Apache Software Foundation\Apache Tomcat 6.0.20\webapps\ROOT\OSGBWebMapTools\openspace.js with a text editor.
3. Search for and replace ###INSERT_YOUR_SERVER_DOMAIN_NAME_HERE### with your server domain name (and port number if using a port other than port 80). So if your server domain name is www.mydomain.com, the line
   
   {return"http://###INSERT_YOUR_SERVER_DOMAIN_NAME_HERE###/geoserver/wms";},getApiKey:function()
   
   Will end up like
   
   {return"http://www.mydomain.com/geoserver/wms";},getApiKey:function()
   
   
4. Similarly, in C:\Program Files\Apache Software Foundation\Apache Tomcat 6.0.20\webapps\ROOT\OSGBWebMapTools\BasicMap.html search for and replace ###INSERT_YOUR_SERVER_DOMAIN_NAME_HERE### with your server domain name (and port number if using a port other than port 80).

Run the Basic Map Demo

The installation can be checked by running the basic map demo.
Type in http://###INSERT_YOUR_SERVER_DOMAIN_NAME_HERE###/OSGBWebMapTools/BasicMap.html to the location in a web browser and a basic map window should appear.

Troubleshooting

Sometimes it can be useful to stop and restart Tomcat and look in the Tomcat and GeoServer logfiles for any errors.

Advanced build and installation

(Optional) OSGB Web Map Tools API Build

This step is only needed if you wish to build the OSGB Web Map Tools API from the source files.

Install Python 2.6

Project home: http://www.python.org
Download link for Windows: http://www.python.org/ftp/python/2.6/python-2.6.msi

Download OpenLayers

Project home: http://openlayers.org
Download link: http://openlayers.org/download/OpenLayers-2.8.zip

1. Unzip the OpenLayers-2.8.zip file into the root of the c: drive.
2. Copy the contents of the c:\OpenLayers-2.8 directory into the c:\OSGBWebMapTools-2.0\OSGBWebMapTools-API directory (clicking yes to overwrite any files or directories if prompted).
3. Run the c:\OSGBWebMapTools-2.0\OSGBWebMapTools-API\build\build.bat file to start the build process.
4. The resulting Javascript file will be built in c:\OSGBWebMapTools-2.0\OSGBWebMapTools-API\build\openspace.js

(Optional) Change the logo

The logo that appears at the bottom left of the map window can be changed or customised by editing the file c:\OSGBWebMapTools-2.0\OSGBWebMapTools\img\OS\OSGBWebMapTools.png in an image editor.

(Optional) Install GeoWebCache

GeoWebCache is a cache for speeding up the serving of map tiles from GeoServer. It can be run as a separate web application in the Tomcat server container.

Install GeoWebCache 1.2.0-beta

Project home: http://geowebcache.org/trac
Download link for Windows: http://etch.opengeo.org/geowebcache-1.2.0-beta-WAR.zip

1. Install the GeoWebCache WAR file via the Tomcat Manager.
2. Copy the configuration from c:\OSGBWebMapTools-2.0\GeoWebCacheConfiguration\geowebcache.xml to C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\geowebcache\WEB-INF\classes\geowebcache.xml
3. Copy the configuration from c:\OSGBWebMapTools-2.0\GeoWebCacheConfiguration\geowebcache-servlet.xml to C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\geowebcache\WEB-INF\geowebcache-servlet.xml
4. Restart the GeoWebCache application in Tomcat Manager (stop then start).
5. In C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\ROOT\OSGBWebMapTools\openspace.js search for "getTileServerPath" and edit to point at the GeoWebCache WMS instead of the GeoServer WMS:
   
   getTileServerPath:function() {return"/geowebcache/service/wms";},
   

Troubleshooting

Sometimes Tomcat will throw an exception "java.lang.OutOfMemoryError: PermGen space" This happens when you have too many classes loaded in the JVM, and GeoServer in combination with GeoWebCache uses a lot.
Trying adding this parameter to the java options of your Tomcat JVM configuration (tomcatw.exe):

-XX:MaxPermSize=128m

(or a bigger value depending on how many GeoServers/GeoWebCache instances are running in parallel in your JVM).
You can also adjust the maximum JVM memory to something bigger, like:

-Xms48m -Xmx256M