• Welcome, Apple
• Foursquare is joining the OpenStreetMap movement
• Why (and how) we’ve switched away from Google Maps

The power of free data is incredibly compelling for these companies but it should also resonate with every person who loves maps.

If you haven’t joined OSM yet, you should! Read over their beginner’s guide and learn how to improve the roads and points of interest in your area.

We will take a look at some of the ways you can use OSM data and maps in future posts.

View Larger Map

TileMill is a new map development environment that is free for anyone to use. In their own words:

“TileMill is a modern map design studio powered by open source technology.”

TileMill allows you to take raw GIS data (shapefiles and rasters) and generate high-quality maps. In addition, it allows exporting maps to a set of map tiles which can be used on a website or transferred to a mobile device (there currently is an iPad app available).

Unlike many of our other tutorials, this probably isn’t for beginners. You need to have some background in GIS, HTML/CSS and have access to a Mac or Linux computer. Don’t let this scare you off though as TileMill may just be the future of map design and distribution.

Installation Setup

The TileMill website provides the basic instructions for installing TileMill on Mac or Linux. In our testing, we successfully installed it on an older MacBook running Snow Leopard.

TileMill require several applications to be installed first. Xcode version 4 was first installed from the Mac App Store. Next, Mapnik for Snow Leopard was downloaded and installed.

TileMill’s distribution package was then downloaded from the website as a zip file. After extracting the files, the folder was renamed to just tilemill and copied into the applications folder using the Finder.

Installing from the Terminal

TileMill needs to be built from Mac’s Terminal. We launched Terminal and navigated to the TileMill folder.

cd /Applications/tilemill

Continuing with their instructions on the website, we executed the build command:

./ndistro

The building process runs through a series of steps. In our case, there were 69 steps it slowly progressed through. At step 50, it seemed to hang and even show an error message.

[50/69] libv8.a: deps/v8/SConstruct -> build/default/libv8.a
scons: warning: Ignoring missing SConscript 'obj/test/release/SConscript'
File "/Applications/tilemill/src/node-0.2.6/deps/v8/SConstruct", line 1097, in BuildSpecific

But eventually the process continued and finished. It appears this is known issue according to their support site. The important thing to note is several times it appeared to hang but don’t lose faith!

Running TileMill

TileMill needs to be started from the Terminal by running this command.

cd /applications/tilemill/tilemill.js

A message should appear informing you it is ready to use.

Started TileMill on port 8889

TileMill is a unique in that it is a local, web-based application so you need to open a web browser to access it. Enter the following in the address bar:

http://localhost:8889

TileMill should appear and several demo projects will already be visible.

Explore TileMill

Browse the existing projects to get a sense of how TileMill works. Remember the software is still really new so don’t be surprised if you run into a crash or freeze. In our testing, reloading the browser usually resolved any issues.

Check out this tutorial video on how you can use TileMill. We will explore it in more detail in a future post.

TileMill: Open Source Map Design from Development Seed on Vimeo.

A common task of any mapping application is to place a marker at a specified location. OpenLayers provides several options for doing this but we will focus on using a Marker.

Our simple example will allow a user to plot the location of various US cities on an OpenLayers map. In order to accomplish this, we need to know the longitude (X) and latitude (Y) of each city. We will use this list of city coordinates to create a HTML <select> box.

<select id="jumpTo" onchange="jumpTo();">
    <option value="NA">=== Select a City ===</option>
    <option value="-84.42,33.65">Atlanta</option>
    <option value="-104.87,39.75">Denver</option>  
    <option value="-95.35,29.97">Houston</option>
    <option value="-81.32,28.43">Orlando</option> 
    <option value="-121.50,38.52">Sacramento</option>
    <option value="-95.62,39.07">Topeka</option> 
</select>

Each <option> uses the value attribute to store the city’s coordinates. Note that the longitude coordinate is listed first and uses a negative number because we are in the western hemisphere.

We also added a javascript function call jumpTo that is called when the selected value is changed. This is where we will use OpenLayers to place a marker on the map.

Our OpenLayers map will be a single HTML page that is based on our basic map setup tutorial. We next need to add a variable to track the markers. This will be placed in the <head> along with some basic OpenLayers initialization code.

<script type="text/javascript">
    var map, baseLayer, markers;
    function init(){
        map = new OpenLayers.Map('map');            
        baseLayer = new OpenLayers.Layer.WMS("OpenLayers VMAP0", "http://labs.metacarta.com/wms/vmap0", {layers:"basic"});
        map.addLayer(baseLayer);
        map.setCenter(new OpenLayers.LonLat(-98, 39),3); 
        markers = new OpenLayers.Layer.Markers("Cities");   			
        map.addLayer(markers);            
    }

Within the init() function, the markers layer is added to the map.

markers = new OpenLayers.Layer.Markers("Cities");   			
map.addLayer(markers);

Below that we need to add the jumpTo() function to place a marker on the selected city.

function jumpTo()
{
    markers.clearMarkers();                
    var selectBox = document.getElementById('jumpTo');        		
    if (selectBox.value == "NA") return;
    var parse = selectBox.value.split(',');
    var location = new OpenLayers.LonLat(parse[0],parse[1]); 			
    var size = new OpenLayers.Size(21,25);
    var offset = new OpenLayers.Pixel(-(size.w/2), -size.h);
    var icon = new OpenLayers.Icon('http://www.openlayers.org/dev/img/marker.png',size,offset);
    markers.addMarker(new OpenLayers.Marker(location,icon.clone()));               			
}
</script>

The code first accesses the select box and makes sure the user selected a city. It next collects the coordinates and parses them based on the comma in between. It then creates a LonLat object based on the parsed coordinates.

The next three lines define the marker’s icon and ensures that the marker point is placed exactly on the location (this code comes from the OpenLayers marker example). OpenLayers has markers in several colors which you can view here. All of them are 21×25 pixels in size but if you were to use your own image, be sure to change the size definition in the code.

The entire HTML code should look like this:

<!DOCTYPE html>
<html>
  <head>
    <title>OpenLayers Tutorial - Place a Marker</title>
    <script src="http://openlayers.org/api/OpenLayers.js"></script>
    <script type="text/javascript">
        var map, baseLayer, markers;
        function init(){
            map = new OpenLayers.Map('map');            
            baseLayer = new OpenLayers.Layer.WMS("OpenLayers VMAP0", "http://labs.metacarta.com/wms/vmap0", {layers:"basic"});
            map.addLayer(baseLayer);
            map.setCenter(new OpenLayers.LonLat(-98, 39),3); 
   	    markers = new OpenLayers.Layer.Markers("Cities");   			
            map.addLayer(markers);            
        }
 
        function jumpTo()
        {
            markers.clearMarkers();        	
            var selectBox = document.getElementById('jumpTo');        		
   	    if (selectBox.value == "NA") return;
   	    var parse = selectBox.value.split(',');
   	    var location = new OpenLayers.LonLat(parse[0],parse[1]); 			
   	    var size = new OpenLayers.Size(21,25);
            var offset = new OpenLayers.Pixel(-(size.w/2), -size.h);
            var icon = new OpenLayers.Icon('http://www.openlayers.org/dev/img/marker.png',size,offset);   
            markers.addMarker(new OpenLayers.Marker(location,icon.clone()));               			 
          }
    </script>
 
    <style>
    @media screen
    {
        #map{width: 500px; height:300px; border: 2px solid black;}
    }
    </style>
  </head>
  <body onload="init()">
    <h1>OpenLayers Tutorial - Place a Marker</h1>
    <div id="map"></div>
    <br />
    <label>Place a marker at this city: </label>
    <select id="jumpTo" onchange="jumpTo();">
        <option value="NA">=== Select a City ===</option>
    	<option value="-84.42,33.65">Atlanta</option>
    	<option value="-104.87,39.75">Denver</option>  
    	<option value="-95.35,29.97">Houston</option>
    	<option value="-81.32,28.43">Orlando</option> 
    	<option value="-121.50,38.52">Sacramento</option>
    	<option value="-95.62,39.07">Topeka</option> 
    </select>
  </body>
</html>

Opening the web page should produce something like this:

Place a marker at this city:
=== Select a City === Atlanta Denver Houston Orlando Sacramento Topeka

Click here to view the final result in a new window

HTML Page Creation

Create a new html file using your favorite text editor.

<!DOCTYPE html>
<html>
  <head>
    <title>OpenLayers Tutorial - Basic Map Setup</title>
    <style>
    @media screen{}
    </style>
  </head>
  <body>
    <h1>OpenLayers Tutorial - Basic Map Setup</h1>  
  </body>
</html>

Reference OpenLayers Javascript

OpenLayers is provided in a single JavaScript file that you can reference remotely or download to a local machine. Let’s keep it simple and just reference the freely available version online. Add this line inside the <head> portion of the file.

<script src="http://openlayers.org/api/OpenLayers.js"></script>

Initialize OpenLayers

Inside <head>, we need to define several variables and create an initializing function.

<script type="text/javascript">
        var map, baseLayer;
        function init(){
            map = new OpenLayers.Map('map');            
            baseLayer = new OpenLayers.Layer.WMS("OpenLayers WMS", "http://labs.metacarta.com/wms/vmap0", {layers:"basic"});
            map.addLayer(baseLayer);    
            map.setCenter(new OpenLayers.LonLat(0,0),1);         
        }
</script>

Inside the init function, the map will be created first. Then a WMS layer is defined using an existing map server. See Wikipedia for more information on WMS. In short, the WMS server in this example provides map tiles of the world upon request. Fortunately, OpenLayers does this behind the scenes and no additional coding is needed. Lastly, the layer is added to the map and the map is centered on zero degrees longitude and latitude.

Call the initialize function from the onload event of the <body>.

<body onload="init()">

Define the Map

The next step is to add a <div> inside the <body> to serve as the container for the map. Most web programmers are already familiar with the broad uses of <div>’s and in the case of OpenLayers, it makes a perfect “map” representative.

<div id="map" ></div>

The size of the map can now be defined using CSS. In the <head> portion, add some variation of the following style.

 <style>
    @media screen
    {
        #map{width: 500px; height:250px; border: 2px solid black;}
    }
 </style>

Full Source Code

Your final HTML page should look something like this.

<!DOCTYPE html>
<html>
  <head>
    <title>OpenLayers Tutorial - Basic Map Setup</title>
    <script src="http://openlayers.org/api/OpenLayers.js"></script>
    <script type="text/javascript">
        var map, baseLayer;
        function init(){
            map = new OpenLayers.Map('map');            
            baseLayer = new OpenLayers.Layer.WMS("OpenLayers WMS", "http://labs.metacarta.com/wms/vmap0", {layers:"basic"});
            map.addLayer(baseLayer);
            map.setCenter(new OpenLayers.LonLat(0,0),1);             
        }
    </script>
 
    <style>
    @media screen
    {
        #map{width: 500px; height:250px; border: 2px solid black;}
    }
    </style>
  </head>
  <body onload="init()">
    <h3>OpenLayers Tutorial - Basic Map Setup</h3>
    <div id="map"></div>
  </body>
</html>

Working Demo

Open the file in a web browser and the map should look like this:

Click here to view the final result in a new window

Flash forward to 2011 where much has changed in GIS and technology. New software, tools and data sources are emerging to dramatically change how maps and geographic information are used. A new set of horizons are ready to be explored. So SpatialHorizons.com is alive again with some great new tutorials lined up. Stay Tuned!

This post introduces OpenLayers as a easy way to embed dynamic maps in a web page. First-time visitors are encouraged to read our previous posts on setting up MapServer and CGI MapServer for background information.

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"></script>

Update: You can now reference OpenLayers using this location:

   <script src="http://openlayers.org/api/OpenLayers.js"></script>

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.

Also, visit our new OpenLayers tutorials for more information.

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.

1. 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.

Continue to part 3

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.