Using MapServer (2) – Generating Map Tiles

November 14th, 2007

This post is the second in a series on using MapServer. First-time visitors are encouraged to read part 1 which details how to download, setup, and create a web mapping site using MapServer. Additionally, the topic of map tiles has already been introduced in a previous series.

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:

Precache.php Usage

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.

kaMap Tile Example

kaMap Tile Example

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