Example 1.5

Adding a Raster Layer


In addition to vector data support (point, lines, polygons), MapServer can also display raster data. Through the use of GDAL library, MapServer can input and output multiple raster formats. Whereas in versions prior to 4.x raster input is limited to single layer, grayscale or indexed color images, recent MapServer versions support RGB and multispectral (multi-layer) images. This example shows how to select what layers to display when using multispectral data.


There might be a noticeable performance hit when using RGB and multispectral images.

Because MapServer uses AGG to generate output images, it supports RGB (24-bit or true color) output as well. So, along with 8-bit (indexed color or grayscale) PNG8, you can now also use PNG (true color) for output. This example uses PNG as IMAGETYPE.


As with RGB input, there might be a noticeable performance hit when using PNG compared to PNG8.

MapServer can actually use GDAL to generate output images as well, but that's another topic. If you want to know more about it, look at the OUTPUTFORMAT object in the mapfile reference.

MapFile Structure

This is what the mapfile looks like: Example1-5.map

The mapfile structure, by objects, looks like this:

             LAYER #1-------------LAYER #2----|----LAYER #3
          (states_poly)           (modis)       (states_line)
             |                                        |
(land) CLASS-|                                        |-CLASS
          |                                               |
    STYLE-|-LABEL                                         |-STYLE

When you look at the mapfile, you'll see that the new LAYER object is added below (after) the state POLYGON layer. Why? MapServer displays layers in reverse order: last in, first out (LIFO). The first layer defined in the mapfile is drawn at the bottom of the map.

So, if we have drawn the state POLYGON layer, it would be on the bottom. Since the raster layer gets drawn on top of it, we won't see it. That's why the first layer gets the STATUS value of OFF. The state LINE layer is defined below the raster layer so it gets drawn on top (and you can see it). This is why we separated the state LINE layer from the state POLYGON layer. Of course the labels get drawn on top of everything.

MapServer can automatically turn layers on or off based on the status of other layers (say you want the states polygon layer turned off when the raster layer is turned on). This is done by using the REQUIRES parameter. Keep this in mind as you might want to use it once you start creating your own MapServer applications.


Let's have a look at the new parameters introduced in the mapfile:


PNG is the 24-bit or true-color version of the PNG format. By the way, try changing this value to PNG8. Notice the time it takes to generate the image using either formats. In choosing between true color and indexed color, take into account the time it takes to generate the image.


Points to the path of the symbol definition file. The symbols in this file are referenced by the SYMBOL parameter in the CLASS object. It's not really needed at this point but I thought I'd throw this here now. Please refer to the Cartographic Symbol Reference for further information.

DATA raster/mod09a12003161_ugl_ll_8bit.tif

In the newly added LAYER object, the DATA parameter points to a GeoTIFF image. Like vector datasets, MapServer supports multiple raster file formats. This support is accomplished through use of the GDAL library. For more information on the different raster formats supported by MapServer and for general discussion on the use of rasters in MapServer, please read the Raster Data Reference.


When using raster data (images) we use the value RASTER for the parameter TYPE, as opposed to the POLYGON, LINE, and POINT values for vector data and its labels.


This LAYER object parameter was added in MapServer 4.x. The PROCESSING keyword has many values but in this case we are using it to select which bands in a multispectral image to display. The values here are strings that will be passed to the GDAL library.


This parameter tells MapServer what pixel values to render as background (or ignore). You can get the pixel values using image processing or image manipulation programs (i.e. Imagine, Photoshop, Gimp).

RGB vs Indexed Color Image

To compare map creation speed when using RGB image as opposed to indexed color image, replace the following lines in the mapfile:

DATA "raster/mod09a12003161_ugl_ll_8bit.tif"
OFFSITE 71 74 65

with these:

DATA "raster/mod09a12003161_ugl_ll_idxa.tif"
OFFSITE 70 74 66

Also, try changing the IMAGETYPE from PNG to PNG8.

Back to Example 1.4 | Proceed to Example 1.6