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, MapServer now supports 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) PNG, you can now also use PNG24 (true color) for output. This example uses PNG24 as IMAGETYPE. As with RGB input, there might be a noticeable performance hit when using PNG24.

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.

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

The mapfile structure, by objects, looks like this:

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

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:

IMAGETYPE
This is not new but the value "PNG24" is. PNG24 is the 24-bit or true-color version of the PNG format. Instead of being limited to 256 color combinations for our output image, MapServer now have millions. By the way, try changing this value back to PNG. 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.

SYMBOLSET
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 mapfile reference and the Cartographic Symbol Construction with MapServer 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 how-to at https://mapserver.org/input/raster.html .

TYPE RASTER
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.

PROCESSING "BANDS=1,2,3"
This LAYER object parameter is new 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. Documentation for this is currently minimal but please see the Mapfile Reference for more examples of using the PROCESSING keyword.

OFFSITE
This parameters 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).

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"
STATUS DEFAULT
TYPE RASTER
PROCESSING "BANDS=1,2,3"
OFFSITE 71 74 65

with these:

DATA "raster/mod09a12003161_ugl_ll_idxa.tif"
STATUS DEFAULT
TYPE RASTER
OFFSITE 70 74 66

Also, try changing the IMAGETYPE from PNG24 to PNG.

Back to Example 1.4 | Back to the Section 1 | Back to the Sections Page | Proceed to Example 1.6