Using QGIS (5) – Export to MapServer

October 6th, 2007

Our last post for now on QGIS will cover an interesting feature added in the recent versions. A new “Export to MapServer Map” command creates a MapServer configuration file (simply called a “mapfile”) from an existing QGIS map. That mapfile can be used to then display the data on a website or use it in a desktop application. The desktop option is what we will take a look at because we will now have an easy way to create a mapfile that we can use with some of our MapServer/XNA tutorials we demonstrated in the past.

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.

QGIS Map


Export to MapServer

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

Export to MapServer

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:

Export to MapServer

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.

World Mapfile in XNA

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.