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.

The program we created was built off one of our previous projects (see World Mapper parts 1,2,3) and, as always, the XNA framework. This project turned out to be much more complex than any of our previous programs so it would be impossible to cover all the source code in detail. Instead, this post will provide an overview of the program’s structure and then provide the source code for you to download and explore on your own.

Program Structure

Below is a graphic of all the classes used in the program with our main class named WorldMapper.cs.

We designed three classes to handle the maps tiles – a TileMap, TileSet, and Tile class. The main program only interacts with the TileMap class and the creation of TileSets and Tiles is done automatically.

We also needed a separate class to keep track of where the user is looking on the map. This concept of a “viewport” or “camera” is commonly used in game programming so the program knows which tiles need to be drawn on-screen. It also tracks which TileSet the user is viewing. The class was named GeoCamera2D and contains methods to pan, zoom, and recenter the map. Remembering the discussion in the last post on tile coordinates versus geographic coordinates, our camera stores all it’s location information in tile coordinates like 0,0 or 2.4, 1.3 and relies on the current TileSet class to convert the location to longitude/latitude coordinates when needed.

Both the Keyboard and Mouse classes have been covered in previous posts so we will skip those now. Some of the code was updated but the main functionality remained the same.

C# Programming

Our map tilling program follows the standard XNA structure but with the addition of our tile mapping classes. Some of the source code is covered below.

We first create several variables to store our new classes and constants to define some pixel parameters:

shTileMap _tileMap;
shGeoCamera2D _camera2D;

const int _mapWidth = 800;
const int _mapHeight = 400;

const int _tileWidth = 800;
const int _tileHeight = 400;

In the constructor, we initiate our TileMap class with some general information, including the extent of the entire map (in this case, the entire world). The camera class is also initiated:

_tileMap = new shTileMap("WorldMap", _tileWidth, _tileHeight, -180, -90, 180, 90);
_camera2D = new shGeoCamera2D(_mapWidth, _mapHeight, _tileWidth, _tileHeight);

Next we have to define each of our three TileSets (see part 2 for more information). We first use the AddTileSet method to create a new TileSet with information on it’s zoom level (0), and tile coordinate extent (0,0 to 1,1).

//--> setup TileSet 0
shTileSet newTileSet = _tileMap.AddTileSet(0, 0, 0, 1, 1, _graphics.GraphicsDevice);

We then have to define some conversion parameters (see part 3) to enable the TileSet to convert between tile coordinates and geographic coordinates.

newTileSet.DefineConversionParameters(new Vector2(-180, -90), 360, 180);

We repeat the TileSet creation twice more for the other TileSets.

In the Update method, we check for mouse and keyboard clicks. A mouse click simply shows the user the geographic coordinates of where they clicked on the map.

// check if a mouse click has occured
_mouse.Update();
if (_mouse.LeftButton == ButtonState.Pressed)
{
    //--> convert click position to grid position
    Vector2 gridPos = _camera2D.ConvertScreenPos2GridPos(_mouse.X, _mouse.Y);

    //--> convert grid position to real world position
    Vector2 realPos = _tileMap.ActiveTileSet.ConvertGridPos2RealPos(gridPos.X, gridPos.Y);

    //--> update last click position for display on-screen
    _lastClickPos = realPos;
}

Arrow keys will pan around the map, the Z key zooms in, and the X key zooms out. One of the keyboard checks looks like this:

// check if a key has been pressed
_keyboard.Update(gameTime);
if (_keyboard.IsNewKeyDown(Keys.Left))
{
    _camera2D.PanLeft(_tileMap.ActiveTileSet.MinCol);
}

Every time a pan occurs, we send as a parameter the boundary being approached by the pan to ensure the user can’t go outside the bounding box of the map.

Finally, in the Draw method, displaying the map takes only one line:

_tileMap.Draw(_spriteBatch, _camera2D);

Conclusion

The code involved in this project is rather complex and represents only one approach to making a tile-based mapping program. The objective was to create a framework that could easily be applied to other TileMaps of different sizes, extents, and tile counts. There are aspects of the program that would need to be addressed though before it succeeded in that respect. For example, our program pre-loads all 22 map tiles for convenience but this wouldn’t be practical for a TileMap that has hundreds of tiles. Some form of a “tile cache” would need to be implemented that only loaded and stored tiles within the user’s view.

The source code and compiled program are available to download below. The source code requires the XNA Game Studio Express and the program download requires at minimum the XNA runtime redistributable to run.

We will use this map tile as an example:

Also included in the image is the tile coordinates of it’s four corners (remember that we are naming map tiles based on the lower-left corner so this tile is the 0,0 tile).

The tile also has real-world (geographic) coordinates. We are keeping this simple by using longitude (X) and latitude (Y) so the corner locations look like this:

Our tile mapping program will use tile coordinates throughout the code but numerous functions will require geographic coordinates. So to convert tile coordinates to geographic coordinates, we need two more related pieces of information – the geographic width and height of each tile. In the above example, the geographic width (”tile distance X”) is 180 degrees and the height (”tile distance Y”) is 90 degrees.

Tile Math Example

Let’s envision a scenario where our tile mapping program is centered on the tile coordinate 0.5,0.5 – basically the center of our sample tile. We want to show the user the location of the map center but telling them 0.5, 0.5 is useless. So to display longitude/latitude, we need to perform separate calculations. First, longitude:

Longitude = [Tile Coordinate X] x [Tile Distance X]
Longitude = 0.5 * 180 = 90

And latitude:

Latitude = [Tile Coordinate Y] x [Tile Distance Y]
Latitude = 0.5 * 90 = 45

So converting tile coordinate 0.5,0.5 to geographic coordinates is 90,45.

Special Case – Tile Origin doesn’t match Geographic Origin

The above equations work for TileSets that have their origin at the geographic origin. In some TileSets, this may not be the case. For example, remember this tile from the last post:

This single tile of the entire earth has it’s origin at the lower left corner which is really -180, -90 in terms of longitude and latitude.

When we convert tile coordinates here to geographic coordinates, we must include the tile origin in the equation.

Again, assuming our map is centered on tile coordinate 0.5, 0.5, the geographic center is calculated below. Note that with this tile, the tile distance X is 360 degrees and the tile distance Y is 180 degrees.

Longitude = (0.5 * 360) + -180 = 0

Latitude = (0.5 * 180) + -90 = 0

So converting tile coordinate 0.5, 0.5 to geographic coordinates is 0,0.

The next post will begin constructing our XNA-based tile mapping program so stay tuned.

The original image from the Wikimedia Commons is over 8 MB in size so we can cut it up in a graphics program and create each tile individually. All tiles will be the same size – 800 pixels wide by 400 pixels tall. Our sample TileMap will have 3 TileSets each a different scale (also referred to as “zoom levels”). They will be numbered from 0 to 2 with 0 being the farthest from ground level.

Tile Coordinates

The OSGeo tile map standards document includes an image showing how the tiles are named (see here). Each tile has a set of tile coordinates that describe the tiles column (X) and row (Y) position within the TileSet. It is important to note the a tile’s coordinates are based on the lower left corner of the tile.

Understanding the concept of tile coordinates is crucial to everything we will do with map tiles. They make working with tiles much easier than if we were to use geographic coordinates. In fact, as long as we know some geographic information about each TileSet, we can convert any tile coordinate to it’s corresponding “real-world” location (all of our examples will continue to use only longitude/latitude locations to keep things simple).

TileSet 0

The first zoom level will be the entire world and contain only 1 tile. It’s tile coordinate is then obviously 0,0. Remember a tile coordinate of 0,0 means the lower left corner is 0,0 so if we were convert the origin to longitude/latitude, the origin would be -180, -90.

TileSet 1

The second TileSet zooms in closer (2x), resulting in 4 tiles. The center of the TileSet (0,0) is placed in the middle so in this case it corresponds with the longitude/latitude origin.

TileSet 2

The third and final set zooms in 2x again, resulting in 16 tiles.

Tile Naming Convention

We will name each tile image using the convention: “Map Name” + “Zoom Level” + “Column(x)” + “Row(y)”. So TileSet 1 has these file names:

• WorldMap_1_0_0.jpg
• WorldMap_1_0_-1.jpg
• WorldMap_1_-1_-1.jpg
• WorldMap_1_-1_0.jpg

Click here to download all the map tiles that will we use next time to start making an XNA “tile mapping” program.

The benefits in this scenario are obvious. Maps at any scale can be produced and layers of information (e.g. roads, lakes, etc.) can be turned on or off with each map request. Map colors, shapes, and symbols can even be changed between requests. The unlimited possibilities come a cost though of slower rendering because each request requires the raw data to be accessed, combined with other layers, and the returned as a single image.

An alternative approach made popular by Google Maps involves pre-rendering map tiles at a variety of scales. This 3-tiered approach removed GIS data from the workflow:

The primary benefit here is speed. Having the map images already rendered means the only limitation is how fast the images can be transferred across the web. A secondary result of having the maps “ready-to-go” means that tiles adjacent to the user’s current view can be loaded concurrently to allow for seamless panning. Tiles can also be cached so if the user returns to an area, the images don’t even need to be re-accessed from the web server.

The disadvantage to the tiling approach is that there is only a limited number of map scales and layer combinations available. A pre-tiled map may only have 5-10 map scales (although Google Maps has over 15) which the user can view data from. In most cases, individual layers cannot be turned on or off. The map’s cartography is presented “as-is” so colors, symbols, and sizes cannot be altered.

For a in-depth discussion how Google Maps works, here is a link to a great article.

Map Tiles for Desktop Applications

Pre-rendering map tiles can also be beneficial for desktop mapping applications. In terms of our exploration with XNA, having pre-rendered map tiles allows us to treat them just like a standard texture. We can load them and easily draw, shift, rescale, etc. without even having to rely an outside GIS/mapping engine or API. Basically, we are then using the same technique video game makers have been using to create games for the last decade.

Map Tile Basics

Let’s briefly define some terminology relating to map tiling that will be used in some upcoming projects. Many of the terms come from a document at the Open Source Geospatial Foundation (OSGEO) discussing proposed standards for tile mapping on the web.

• Tile – a single map image
• Tile Format Width – the width of a tile in pixels
• Tile Format Height – the height of a tile in pixels
• TileSet – a set of tiles for a single scale of a map
• Tile Coordinate – the column/row location of a tile in a given TileSet; see this image for more information
• TileMap – the entire “map”; a collection of TileSets at different scales
• Bounding Box – the geographic extent of the entire TileMap described by it’s minimum and maximum X/Y coordinates

The next post will provide a simple example of a TileMap and then we will start using TileMaps in XNA.