Update: In 2008, Spatial Horizons is currently on hiatus while we work on other projects. The future is uncertain but we hope to return in some form in 2009. Stay tuned…

OpenLayers is a javascript library for creating maps on a web page. In their own words,

OpenLayers is a pure JavaScript library for displaying map data in most modern web browsers, with no server-side dependencies. OpenLayers implements a (still-developing) JavaScript API for building rich web-based geographic applications, similar to the Google Maps and MSN Virtual Earth APIs, with one important difference — OpenLayers is Free Software, developed for and by the Open Source software community. – http://www.openlayers.org/

Setting up OpenLayers is incredibly easy if you want to display data from other existing sources on the web. See their Quick Tutorial page for lots of sample HTML showing how to add a basic map in a web page. In this tutorial, we will focus on how to create a map that uses our own data from MapServer.

Tutorial Requirements

Before beginning, you should already have MapServer setup on your computer. See our previous post to complete this task using the MS4W package. Additionally, we will use GIS data and a MapServer mapfile from our World Map sample dataset.

Download a Web Page from OpenLayers.org

OpenLayers.org has a great screencast tutorial showing how to setup and use OpenLayers. Accompanying the tutorial is a wiki page describing the steps covered in the video. At the bottom of this page is a link to download an HTML document named lite.html that contains a good starting point for our tutorial.

Go ahead and download the file (direct link here) to your desktop and open it in your favorite text editor. On line 10, note the reference to OpenLayers javascript file:

script src="http://openlayers.org/dev/lib/OpenLayers.js"

Further down, lines 13 through 20 contain the all the javascript code necessary to embed a MapServer map in the web page:

var map, layer;

function init(){
   map = new OpenLayers.Map( 'map' );
   layer = new OpenLayers.Layer.MapServer( "OpenLayers WMS",
       "http://labs.metacarta.com/wms/vmap0", {layers: 'basic'} );
   map.addLayer(layer);
   map.zoomToMaxExtent();

In fact, without changing anything, you could open the web page in a browser and it will work fine because the data is coming from a remote server. The controls in the upper-left corner can be used to navigate around the map.

Customizing the Javascript

In order for the web page to display our own MapServer data, several changes need to be made to the Javascript in HTML file.

On line 17, the layer is initialized using the OpenLayers.Layer.MapServer class. Several parameters are required for the layer to work correctly. In the default example, the layer is named OpenLayers WMS (Web Map Server) and the MapServer location is http://labs.metacarta.com/wms/vmap0. The third parameter is informing the server to request the “basic” layer.

For our demonstration, we need to change the three parameters. First we will change the name to World Map. Next, we need to change the location to point to MapServer running on our local machine. Remembering our last post on CGI MapServer, we already know that the path is http://localhost/cgi-bin/mapserv.exe. And finally, instead of requesting a layer name, we can just provide a file path to a mapfile. The final result looks like this:

var map, layer;

function init(){
    map = new OpenLayers.Map( 'map' );
    layer = new OpenLayers.Layer.MapServer( "World Map",
       "http://localhost/cgi-bin/mapserv.exe", {map: 'C:/world_mapfile.map'} );
    map.addLayer(layer);
    map.zoomToMaxExtent();
}

Save the file and open lite.html in a web browser. The map should now display your data described in the mapfile.

More to Come

OpenLayers offers a wide range of functionality that can be added our simple example. For a list of examples, see here.

We’ve already introduced MapServer and showed how to create a mapfile using GIS data. We will now introduce MapServer’s CGI functionality as a way to generate a map image. Later we will build on what we’ve learned to create a map using OpenLayers, a web mapping interface.

Introducing Mapserv.exe

At the heart of MapServer is a single file referred to as “mapserv”. With the MS4W package, it is a single executable found at C:\ms4w\Apache\cgi-bin\mapserv.exe. This file is the map production engine that uses a mapfile to generate a map image.

Mapserv.exe is usually accessed internally by MapServer-based packages such as ka-map or Mapscript. But it can also be called directly from a web browser as long as some required parameters are included.

Mapping from the Web Browser Address Bar

In order to demonstrate Mapserv.exe, we already need to have some data and a mapfile ready to use. We will be using the data and mapfile from our World Map dataset.

Open a web browser and enter the following: http://localhost/cgi-bin/mapserv.exe. If MapServer is correctly configured, you should see the following warning message:

This means mapserv.exe is working correctly so we can next tell it that we want to draw a map. Add ?mode=map to the address so the full address is http://localhost/cgi-bin/mapserv.exe?mode=map. Pressing enter again returns another message:

This is expected because we have not provided a mapfile to display. The next variable to add is named “map” and it’s value is the file path to our mapfile. For example, it could be: http://localhost/cgi-bin/mapserv.exe?mode=map&map=C:\world_mapfile.map. If a valid mapfile is entered the browser will generate an image such as this:

A full list of CGI MapServer parameters can be found here. For example, to generate an image of a specific map extent, the MAPEXT parameter can be used. In our example, we added MAPEXT -20 -20 20 20 in the browser to get an address like this: http://localhost/cgi-bin/mapserv.exe?mode=map&
map=C:\James\GIS\Data\World\world_mapfile.map&mapext=-20 -20 20 20. The image returned reflects the new extent.

Conclusion

Understanding how MapServer uses mapserv.exe to generate images will become more useful in our next post where we will setup a basic web mapping site using OpenLayers that will need to directly access the CGI functionality of MapServer.

Dataset Details

• Number of data layers: 2
• Map Projection: Geographic (see Equirectangular projection)
• Map Units: Decimal degrees
• Map Extent(min x, min y, max x, max y): -180 -90 180 90

Layer 1: Countries Shapefile

The first layer in this dataset is a polygon shapefile containing world countries.

Source: http://www.cipotato.org/diva/data/MoreData.htm
Direct download link: http://www.cipotato.org/diva/data/misc/world_adm0.zip

For more on using this shapefile, see our posts on using QGIS.

Layer 2: World Raster

The second data layer is a raster image of the entire world. The original image was very large but we downloaded it and resized to 600 x 300 pixels. Additionally, we had to create a world file to ensure it would spatially align correctly with our countries shapefile (see this post for more instructions).

Source: http://commons.wikimedia.org/wiki/World_map
Direct link to full-size image (8 MB): http://upload.wikimedia.org/wikipedia/commons/c/cf/WorldMap-A_non-Frame.png
Resized Image: http://www.spatialhorizons.com/downloads/world_raster.tif
World File: http://www.spatialhorizons.com/downloads/world_raster.tfw

Mapfile Creation

The World Map dataset has been used for several of our projects involving MapServer. Since MapServer requires a configuration file called a mapfile, one was generated using QGIS in this post. Some minor modifications were made later on so the final version can be downloaded here.

In the mapfile, the file paths to the data layers should be changed though to reflect your directory structure.

 LAYER
    NAME 'world_raster'
    TYPE RASTER
    DATA 'C:\\Data\\World\\world_raster.tif'
  ...

LAYER
    NAME 'world_adm0'
    TYPE POLYGON
    DATA 'C:\\Data\\World\\world_adm0.shp'
  ...

Once the MapServer for Windows (MS4W) package with ka-Map is installed on your local machine, some new mapping functionality becomes available. One area that interests us is the ability to automatically generate a set of map tiles.

ka-Map Configuration

The first step in creating a set of map tiles is to configure ka-Map to point to a valid MapServer mapfile (see here for more on a mapfile). Navigate to this directory: C:\ms4w\apps\ka-map-1.0\include and open the file named config.php in any text editor.

This configuration file contains several parameters which you should be familiar with before creating our map tiles. We won’t change any of their values yet but it is important to understand what they do. First, on lines 73 and 74, the pixel size of each tile to be generated is defined:

$tileWidth = 256;
$tileHeight = 256;

Lines 106 through 110 define the most important parameters:

$aszGMap = array (
         'title' => 'GMap 75',
         'path' => '../../gmap/htdocs/gmap75.map',
         'scales' => array( 40000000, 25000000, 12000000,
                                 7500000, 3000000, 1000000 ),
         'format' =>'PNG'
 );

By default, ka-Map is setup to use the GMap application that we downloaded and setup in the first post. So the values for the title, path, and scales reflect that.

The path variable is relative based on the location of config.php (config.php is in C:\ms4w\apps\ka-map-1.0\include and the gmap75.map file is in C:\ms4w\apps\gmap\htdocs).

The scales array contains all the map scales at which the tiles will be generated. Determining which scales and how many scale levels is completely configurable based on the user’s preference. For now we will leave them as-is.

Lastly, the output image format is defined as PNG.

Precache.php

ka-Map is a web-based interface for viewing MapServer-based maps using map tiles. Normally, ka-Map generates only the necessary map tiles needed to show in the browser’s window. But there is a separate file, named precache.php, that also comes with the ka-Map that does generate all the map tiles for every scale of the map.

Navigate to the following directory: C:\ms4w\apps\ka-map-1.0\htdocs. Scroll through the list of files to find the file precache.php. The good news is this file does not need to be modified in any way. It relies solely on the config.php settings described above to determine what mapfile and map scales to use when creating the map tiles.

Running Precache.php

Readers are encouraged to first read over this article in the ka-Map wiki about precache.php. You don’t have to understand everything it discusses – just glance over the parameters needed to run precache.php.

Running precache.php requires returning to the world of DOS prompts and command line. It is important to follow these steps exactly as listed otherwise it may not work correctly.

1. Open a command prompt. On Windows, go to Start…Run and type cmd.
2. Type cd C:\ms4w\apps\ka-map-1.0\htdocs to go to the directory with precache.php.
3. Since precache.php is a PHP file, we need to run it using the PHP executable (php.exe). Fortunately this is already included with the MS4W package. Type C:\ms4w\Apache\cgi-bin\php.exe precache.php in the command prompt. We left out the required parameters on purpose here so you can see the usage instructions:

We won’t need to use -f, -m, or -s options but we do need to add the tile_url parameter. This is the web address (hence “_url”) to ka-Map’s tile.php file. Even though the file is stored locally at C:\ms4w\apps\ka-map-1.0\htdocs\tile.php, we need to enter a valid URL. The usage instructions suggest using http://localhost/ka-map/htdocs/tile.php but that didn’t work for us. Instead we will use http://localhost/kamap/tile.php.

4. Type C:\ms4w\Apache\cgi-bin\php.exe precache.php http://localhost/kamap/tile.php. Press enter the map tiles will be generated.

This process will take several minutes as all the tiles at each of the scale levels are generated. The command prompt will display information on each scale level. This information on meta tiles and tile counts is informative but not necessary to understand right now. In short, precache.php requests larger tiles (”meta tiles”) and then cuts them up to arrive at the final set of tiles.

Viewing the Map Tile Cache

Navigate to C:\ms4w\tmp\ms_tmp\kacache\gmap. Inside this folder should be a folder named for each scale level in the map. Inside each scale level folder our folders named __base__ and then a sub-folder named def. This is where the tile images can be found.

Because ka-Map tiles are generally only used internally and not designed for end-user interaction, there is a potentially confusing way to name tiles and tile folders. Anytime a folder or file contains the letters “t” or “l”, it means top or left. So instead of naming tiles with X/Ys or Row/Columns, ka-Map uses the “Left/Top” naming convention.

It also names each tile based on it’s pixel location and tile size. Since the config.php was set to output 256×256 tiles, each tile image will include top and left numbers based on multiples of 256. So if one tile is named t0l0.png, the adjacent tiles on each side would be named t0l256.png and t0l-256.png. Glance through the folders and view some of the individual tiles to get a sense of the tiling structure.

What’s the Benefit?

Traditional usage of precache.php is for improving the load times on a web mapping site by caching all the tiles ahead of time. For our objectives, having a complete set of pre-compiled map tiles means we can create a desktop application without including a GIS code library or GIS data. It also eliminates the extra processing time and would make deploying our applications easier. Instead of including extra DLLs and shapefiles, we simply need to include a folder of map tiles to run the application.

Conclusion

This post is probably the most technical topic we’ve covered to date. For now, simply understanding how to generate map tiles using precache.php is a what’s important. In the next post we will discuss the map tiles in some more depth, including how we can use them in other applications.

Our sample application’s source code is available to download below. It includes everything needed to compile and run the application using Visual C# Express. The SharpMap library, included in the download, is released under the GNU Lesser General Public License. For more information on that, see here.

Zooming By Percentages

The SharpMap.Map class has a Zoom property that stores the map’s current width in the units of the map. To understand this better, add this line of code to the RefreshMap function we’ve already created:

MessageBox.Show(_sharpMap.Zoom.ToString());

Running the program now should immediately display a value of almost exactly 360. This makes sense because our data source is a shapefile of the world, our map units are decimal degrees, and the width of the earth is 360 degrees.

So “zooming” is really just a process of changing the the width of the map. Zooming in will require us to subtract from the SharpMap.Map.Zoom while zooming out adds a value to Zoom. We could simply use a constant value like 20 (degrees) but that is only applicable when our source data is in decimal degrees. If we switched to data in feet for example, adding or subtracting 20 feet from the a map width would takes hundreds of clicks to zoom in and out.

Instead, a better approach for zooming is to use a percentage change. Remember we defined a class-level constant in our the form’s code:

const float ZOOM_FACTOR = 0.3f;

We can use that value to zoom in or out 30% each time our zoom buttons are pressed.

Zooming Code

Double-clicking on the Zoom In button in our form will create the click event for the button. We only need to add 2 lines of code to change the Zoom value (i.e., map width).

private void btnZoomIn_Click(object sender, EventArgs e)
{
    _sharpMap.Zoom -= _sharpMap.Zoom * ZOOM_FACTOR;
    RefreshMap();
}

And zooming out does just the opposite:

private void btnZoomOut_Click(object sender, EventArgs e)
{
    _sharpMap.Zoom += _sharpMap.Zoom * ZOOM_FACTOR;
    RefreshMap();
}

Additionally, our Zoom to Full button click event looks like this:

private void btnZoomFull_Click(object sender, EventArgs e)
{
    _sharpMap.ZoomToExtents();
    RefreshMap();
}

Panning Code

We also can easily implement panning in this application. A map pan (or recenter) will occur any time the user clicks on the map image. The mouse click location will then become the map center. This process requires two steps: (1) convert the “image” coordinates to real-world coordinates and (2) recenter the map.

Fortunately the SharpMap.Map class has a ImageToWorld method to convert the mouse click coordinates to the real-world location in the map. Then we just need the change the map’s center coordinates before refreshing the map. The code is added to Picture Box’s mouse click event and looks like this:

private void picMap_MouseClick(object sender, MouseEventArgs e)
{
    //--> Convert mouse click point from image coordinates to world coordinates
    SharpMap.Geometries.Point p = _sharpMap.ImageToWorld(new PointF(e.X, e.Y));

    //--> Recenter map
    _sharpMap.Center.X = p.X;
    _sharpMap.Center.Y = p.Y;

    RefreshMap();
}

Running the program now allows the user to zoom in and out and pan around the map.

Next time we will add some more functionality to the application before moving on to another topic.

Adding Layer Styles

Adding colors to our countries layer is straightforward. In our form’s constructor, we simply define colors using the Style class:

countriesLayer.Style.Fill = Brushes.LightGreen;
countriesLayer.Style.EnableOutline = true;
countriesLayer.Style.Outline = Pens.DarkGreen;

We also switched the map’s background color:

_sharpMap.BackColor = Color.LightBlue;

Running the program now produces a better looking map:

Adding Labels

SharpMap also allows for creating label layers to add to the map that display text from another layer’s attributes. In our example, we can display the names of the countries on the map using the following code:

SharpMap.Layers.LabelLayer labelLayer =
     new SharpMap.Layers.LabelLayer("Country Names");
labelLayer.DataSource = countriesLayer.DataSource;
labelLayer.LabelColumn = "NAME";
labelLayer.Style.CollisionDetection = true;
labelLayer.Style.CollisionBuffer = new SizeF(10, 10);
labelLayer.MultipartGeometryBehaviour =
     SharpMap.Layers.LabelLayer.MultipartGeometryBehaviourEnum.Largest;
labelLayer.Style.Font = new Font(FontFamily.GenericSansSerif, 8);
_sharpMap.Layers.Add(labelLayer);

In the code, we create a LabelLayer, assign it to the same data source as our countries layer, choose the field that contains the country names (”NAME”), and then define some additional properties. Enabling collision detection avoids some overlapping labels while the multi-part geometry behavior instructs SharpMap to label the largest polygon if a country has multiple shapes.

The final result is not perfect because there are just too many country names to display at once. Setting the collision buffer to 10,10 reduces the number of labels drawn but which country names are displayed is completely arbitrary.

When we add code to the zoom in button in the next post, overlapping labels will become less of an issue:

SharpMap is an easy-to-use mapping library for use in web and desktop applications. It provides access to many types of GIS data, enables spatial querying of that data, and renders beautiful maps. The engine is written in C# and based on the .Net 2.0 framework. SharpMap is released under GNU Lesser General Public License. [quote source]

So let’s go ahead and program a simple mapping application in C# that uses SharpMap. As with our other tutorials, this example is rather primitive on purpose to highlight specifically how easy it use to use SharpMap. Readers are encouraged to use this tutorial as a basis for creating much richer applications.

Data Setup

Before beginning, we need to download a GIS dataset to display in the program. Our recent posts on QGIS discussed several options for download and viewing shapefiles. In part 3 of that tutorial, we downloaded a shapefile showing countries of the world so that shapefile will be used again in this project.

SharpMap Download

We first need to download the latest release of SharpMap here. Download the version 0.9 binary file and unzip it to your hard drive. The zip file contains 4 files but the only file we will use is the SharpMap.dll.

Create a New C# Application

Using the free Visual C# Express program, create a new C# windows application. Here are several links (link 1, link 2) if you need some background on using Visual C# Express.

The first step is to reference the SharpMap.dll we downloaded. Go to the Project menu iten, select Add Reference, then chose browse, and navigate to the SharpMap.dll. It should then appear in the solution explorer as a project reference.

After switching to the form’s design view, add a Picture Box control to serve as our map image area. We added 3 buttons and a label to produce something that looks like this:

Press F5 to run the program although nothing special should happen yet.

Next go ahead and copy the shapefile to a folder in the project’s directory. For example, copy the shapefile (remember it is actually 3 separate files) into the program’s bin\debug folder.

Now switch to the code view for the form and begin by adding some class-level variables and constants. The main class we will use throughout the program is the SharpMap.Map class. Because we have already referenced the SharpMap.dll, Visual C# Express should allow classes from SharpMap’s library to be defined just like any other C# class.

public partial class frmMap : Form
{
    //--> Define the SharpMap object
    SharpMap.Map _sharpMap;  

    //--> Set the zoom factor percentage
    const float ZOOM_FACTOR = 0.3f;

    //--> Define the data name and source
    const string DATA_NAME = "World Countries";
    const string DATA_PATH = @"world_adm0\world_adm0.shp";

Then in the form’s constructor, we first initialize the Map class with a size that matches the size of our Picture Box control.

public frmMap()
{
    //--> Initialize the map
    _sharpMap = new SharpMap.Map(new Size(600, 300));
    _sharpMap.BackColor = Color.White;

Now we can add our shapefile to the map via a 3-step process: (1) define a VectorLayer object, (2) set it’s data source, and (3) add it to the Map.

//--> Add the countries shapefile to the map
SharpMap.Layers.VectorLayer countriesLayer = new SharpMap.Layers.VectorLayer(DATA_NAME);
countriesLayer.DataSource = new SharpMap.Data.Providers.ShapeFile(DATA_PATH);
_sharpMap.Layers.Add(countriesLayer);

Next we need to set the map’s view to the entire extent of our layer using the ZoomToExtents() function.

//--> Zoom the map to the entire extent
_sharpMap.ZoomToExtents();
RefreshMap();

We also needed to alert SharpMap to draw our map and return it as an image. Because we will need to call this function from several spots in our program, a separate function was created called RefreshMap that does just that. The returned map image is then displayed in our Picture Box.

private void RefreshMap()
{
    //--> Use SharpMap to generate the map image
    picMap.Image = _sharpMap.GetMap();
}

Even without adding code to the buttons, we can still run the program at this point. Press F5 and you should see something like this:

The map image was indeed generated by SharpMap but it lacks a decent coloring scheme. Next time we will correct that and later we will add functionality to the zooming buttons.

Python Installation

The Export to MapServer tool will only work if the Python programming language is installed on your computer. The latest version (2.5.1) of Python is required so we first need to download and install it here.

Open a QGIS Map

After the installation, go ahead and open a QGIS map. We will continue to use the world map project created in the previous posts. As a reminder, we have two layers in our map – a vector layer showing country outlines and a raster background image.

Export to MapServer

Under the File menu option, select the “Export to MapServer Map” item:

The window that opens requires you to input some information before creating the mapfile. First you need to select a location for the new mapfile. Then pick the QGIS project file that you will be creating it from (it does not automatically use the currently open project in QGIS). Provide a map name, enter the size, and make sure the units drop-down box matches the map’s units. Our map is only in longitude/latitude units so we chose dd (decimal degrees). We will skip the box covering the Web Interface Definition so our filled out menu looks like this:

Press Ok to run the export and the mapfile will be created.

Viewing the Mapfile

Find the created mapfile and open it in your favorite text editor. The mapfile is a structured document that contains groups of elements that begin with a name (e.g., MAP, PROJECTION, LAYER) and end with END. It also contains single-line attributes using the key-value syntax (e.g., NAME ‘World Map’, TRANSPARENCY 100, OUTLINECOLOR 0 0 0). It is very similar to an XML file but without the brackets and slashes.

For a complete reference on the syntax of mapfiles, check out their help page on the web. Even without reading the help file, most of the mapfile can be understood by simply glancing at the text. For example, our world raster image appears in the mapfile like this:

LAYER
    NAME 'world_raster'
    TYPE RASTER
    DATA 'M:\\World\\world_raster.tif'
    METADATA
      'wms_title' 'world_raster'
    END
    STATUS DEFAULT
    TRANSPARENCY 100
    PROJECTION
    'proj=longlat'
    'ellps=WGS84'
    'datum=WGS84'
    'no_defs'
    END
  END

It is easy to determine the between the LAYER and END tags, the raster is described with it’s name, type, file location, and projection information.

Our shapefile of world countries is slightly longer but similar:

LAYER
    NAME 'world_adm0'
    TYPE POLYGON
    DATA 'M:\\World\\world_adm0.shp'
    METADATA
      'wms_title' 'world_adm0'
    END
    STATUS DEFAULT
    TRANSPARENCY 100
    PROJECTION
    'proj=longlat'
    'ellps=WGS84'
    'datum=WGS84'
    'no_defs'
    END
    CLASS
       NAME 'world_adm0'
       STYLE
         SYMBOL 0
         SIZE 6
         OUTLINECOLOR 0 0 0
         COLOR 144 50 207
       END
    END
  END

The major difference between this and the raster file is the addition of a CLASS and STYLE element. They define the coloring of the countries using the OUTLINECOLOR and COLOR attributes.

Sometimes our mapfile doesn’t exactly match how QGIS had it displayed. In our QGIS map, we displayed the countries with a transparent fill so only the black outlines showed on the map. To make our exported mapfile match that, we need to remove the “COLOR 144 50 207″ line and save the mapfile.

Testing the Mapfile

There are various ways our mapfile could be tested in another application. The coolest example would be to go back to our Mapscript/XNA tutorials. The result of these tutorials was a C# program that uses XNA as the graphics engine and Mapscript (Mapserver’s API) to generate map images from a mapfile (download the project’s source code in this post).

In our program, we simply need to change the line of code where our mapfile path is defined to point to our new mapfile created from the QGIS export.

mapserver = new shMapserver(@"M:\World\world_mapfile.map", 600, 600);

Running the program will prove that our new mapfile works and allow us to zoom around the world.

Conclusion

QGIS is a free, easy-to-use, software program for viewing and exploring geographic data. The reason for discussing it in some depth is that if we want to start developing our own mapping applications, we need to begin acquiring GIS data and making our own maps. QGIS also gives us an easy way to produce MapServer mapfiles as we demonstrated above.