From Ka-Map Wiki

Much of the text on this page is from Tyler Mitchell's article Build AJAX-Based Web Maps Using ka-Map.

Contents 1 Preparing Map Server 1.1 MapScript Programming Library 1.2 Data Preparation 1.3 MapServer Configuration 1.4 Testing the Map File

[edit] Preparing Map Server

To use ka-Map, you need to have a working MapServer application configuration file. In traditional (non-AJAX) MapServer applications, you create web pages, prepare data, create a configuration file that points to the data, and set up the look and feel of the map. For a ka-Map application you can ignore the web page set up by using the default one that comes with it. Instead, the focus is on preparing map data and setting up the MapServer application configuration file.

[edit] MapScript Programming Library

You must have the MapServer programming library, MapScript, up and running. ka-Map uses the PHP MapScript API to render maps. The easiest way to do this is to use one of the binary MapServer installers that are available.

The Windows installer is called MapServer For Windows (MS4W). You simply unzip some files onto your drive and you are ready to go. You can then install other packages that make certain functionality available, e.g. ka-Map. See here to get started with MS4W: http://maptools.org/ms4w.

The Linux installer is called the FOSS GIS Suite (FGS). FGS includes a standardized set of modules, including all library dependencies preconfigured to run together. FGS has an installer shell script, which takes a module and automatically extracts it to your system. It also checks dependencies and grabs other packages as required. Get started with FGS here: http://maptools.org/fgs.

The MapServer website has more installation instructions if you want to start from source code. Tyler Mitchell also walk through this process in Web Mapping Illustrated.

[edit] Data Preparation

Before you move on to creating a simple MapServer configuration file, you need some map data. Global country border data are available here as part of a FreeGIS.org world data package. It provides a basic set of map data in the ESRI Shapefile format. You will need the files starting with countries_simpl. These are low-resolution files to keep the file size small. If you want a higher resolution dataset, grab the one from here instead.

As an image backdrop, you will use a global cloud image from here. It was created from Xplanet data and a weather map hack from the book Mapping Hacks. Using their hack you can download a new image every six hours and have it automatically update your web mapping applications with current global cloud cover. The image is a TIFF file, with an additional TFW file that provides the information to geolocate the image.

Extract both the country boundaries and image file into a folder called data.

[edit] MapServer Configuration

Next, you need to create a MapServer application configuration file. This is a simple text file that tells MapServer how to access data and draw the map. This file is commonly called a mapfile. It contains several sections called objects. They start with a keyword for the object type and close with the END keyword.

Here is a basic map file using the two data layers mentioned above:

MAP
 NAME global_map
 STATUS ON
 SIZE 600 300
 EXTENT -180 -90 180 90
 UNITS DD
 IMAGECOLOR 255 255 255
 IMAGETYPE png

 WEB
   IMAGEPATH "/opt/fgs/apps/kamap-0.1.1/htdocs/tmp/"
   IMAGEURL "/ka-map/tmp/"
 END

 LEGEND
   TRANSPARENT TRUE
 END

 SCALEBAR
   TRANSPARENT TRUE
 END

 LAYER
   NAME clouds
   TYPE RASTER
   STATUS ON
   DATA "data/day_clouds.tif"
 END

 LAYER
   NAME countries
   TYPE LINE
   STATUS ON
   DATA "data/countries_simpl.shp"
   CLASS
     NAME "Country Boundaries"
     STYLE
       COLOR 200 100 100
     END
   END
 END
END #MAP END

Save the above into a simple text file namedglobal.map.

[edit] Testing the Map File

Incorrect settings in your map file will cause problems. Before trying to use a map file with ka-Map, you should test it.

Depending on how you have MapServer installed, you may have a program called shp2img. This command-line tool uses the map file to create an image file. You run it like:

> shp2img -m global.map -o test.png

If all goes well, there should be a test.png image file containing a map. If the program fails or gives errors, then you have a problem with your map file.

Further testing may be required to fully guarantee that the map file is working, but this test is a good first cut. To make sure that the maps created from the map file are going to be readily accessible to a web server, you should also test it in a web environment. This is discussed further in the "Further Adventures" section.