HOWTO for Rasters in MapServer 4.2

MapServer supports rendering a variety of raster file formats in maps. The following describes some of the supported formats, and what capabilities are supported with what formats.

This document assumes that you are already familiar with setting up MapServer map files, but does explain the raster specific aspects of map files.

A simple raster layer declaration looks like this. The DATA file is interpreted relative to the SHAPEPATH, much like shapefiles.

LAYER
  NAME "JacksonvilleNC_CIB"
  DATA "Jacksonville.tif"
  TYPE RASTER
  STATUS ON
END

Though not shown rasters can have PROJECTION, METADATA, PROCESSING, MINSCALE, and MAXSCALE information. It cannot have labels, queries, CONNECTION, CONNECTIONTYPE, or FEATURE information.

Rasters can be classified in a manner similar to vectors, with a few exceptions. The CLASSITEM is always the pixel value, which is indicated by the special string "[pixel]" (must be lower case, it was "[value]" in versions before 3.5). The following demonstrates a raster layer with a simple classification scheme applied to it.

LAYER
  NAME "JacksonvilleNC_CIB"
  DATA "Jacksonville.tif"
  TYPE RASTER
  STATUS ON
  CLASSITEM "[pixel]"
  CLASS
    EXPRESSION ([pixel] < 64)
    COLOR 0 0 0
  END
  CLASS
    EXPRESSION ([pixel] >= 64 AND [pixel] < 128)
    COLOR 255 0 0 
  END
  CLASS
    EXPRESSION ([pixel] >= 128 AND [pixel] < 196)
    COLOR 0 255 0 
  END
  CLASS
    EXPRESSION ([pixel] >= 196 AND [pixel] < 256)
    COLOR 0 0 255
  END
END

Some format drivers (ie. GDAL) cast the pixel values to the range 0 to 255 before applying the classification scheme to them, making it hard to use this classification mechanism to classify floating point, or other data not well expressed as unsigned byte data (0-255). This is a bug and should be corrected at some point in the future.

Note that only the COLOR, EXPRESSION and NAME parameters are utilized for raster classifications. The other rendering information is ignored.

What raster formats are supported by MapServer is largely controlled by configuration time options. Some formats are considered to be built-in while the remainder are handled by the optional GDAL raster library.

More information on GDAL can be found at http://www.remotesensing.org/gdal , including the supported formats list. Some of the advanced MapServer raster features, such as resampling, RGB color cube generation and automatic projection capture only work with raster formats used through GDAL. GDAL is normally built and installed separately from MapServer, and then enabled during the build of MapServer using the --with-gdal configuration switch. GDAL formats not listed below include CEOs, DOQ, ECW, ESRI Labelled BIL, Arc/Info Binary Grid, OGDI and Erdas Imagine (.hfa).

To find out what is built into a particular MapServer executable, use the -v flags to discover what build options are enabled. To find out what gdal formats are build, the gdal-config command may be used. For example:

warmerda@gdal[103]% ./mapserv -v
MapServer version 3.5 (pre-alpha) OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP 
SUPPORTS=PROJ SUPPORTS=TTF INPUT=EPPL7 INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
warmerda@gdal[104]% gdal-config --formats
gxf gtiff hfa aigrid aaigrid ceos ceos2 iso8211 sdts raw dted mem jdem 
envisat elas ogdi gif jpeg png fits grass

The following formats are potential builtins.

When handling very large raster layers it is often convenient, and higher performance to split the raster image into a number of smaller images. Each file is a tile of the larger raster mosaic available for display. The list of files forming a layer can be stored in a shapefile with polygons representing the footprint of each file, and the name of the files. This is called a TILEINDEX and works similarly to the same feature in vector layers. The result can be represented in the MAP file as one layer, but MapServer will first scan the tile index, and ensure that only raster files overlapping the current display request will be opened.

The following example shows a simple example. No DATA statement is required because MapServer will fetch the filename of the raster files from the Location attribute column in the hp2.dbf file for records associated with polygons in hp2.shp that intersect the current display region. The polygons in hp2.shp should be rectangles representing the footprint of the corresponding file. Note that the files do not have to be all the same size, the formats can vary and they can even overlap (later files will be drawn over earlier ones); however, they must all be in the same coordinate system (projection) as the layer.

  LAYER
    NAME "hpool"
    STATUS ON
    TILEINDEX "hp2.shp"
    TILEITEM "Location"
    TYPE RASTER
  END

While there are many ways to produce TILEINDEX shapefiles for use with this command, one option is the gdaltindex program, part of the GDAL utility suite. The gdaltindex program will automatically generate a tile index shapefile from a list of GDAL supported raster files passed on the command line.

Usage: gdaltindex [-tileindex field_name] index_file [gdal_file]*

eg.
  % gdaltindex doq_index.shp doq/*.tif

NOTES:
  o The shapefile (index_file) will be created if it doesn't already exist.
  o The default tile index field is 'location'.
  o Raster filenames will be put in the file exactly as they are specified
    on the commandline.
  o Simple rectangular polygons are generated in the same
    coordinate system as the rasters.

The gdaltindex program can be built as part of GDAL (it isn't part of the default build), or a prebuilt copy for Windows can be downloaded from ftp//gdal.velocet.ca/pub/outgoing/gdaltindex.zip. You will also need supporting libraries ftp//ftp.remotesensing.org/gdal/gdal-1142-ntbin.zip.

MapServer is able to resample GDAL rasters on the fly into new projections. Non-GDAL rasters may only be up or down sampled without any rotation or warping.

Raster warping kicks in if the projection appears to be different for a raster layer than for the map being generated. Warped raster layers are significantly more expensive to render than normal raster layers with rendering time being perhaps 2-4 times long than a normal layer. The projection and datum shifting transformation is computed only at selected points, and generally linearly interpolated along the scanlines (as long as the error appears to be less than 0.333 pixels.

In addition to reprojecting rasters, the raster warping ability can also apply rotation to GDAL rasters with rotational coefficients in their georeferencing information. Currently rotational coefficients won't trigger raster warping unless the map and layer have valid (though matching is fine) projection definitions.

Traditionally MapServer has been used to produce 8 bit pseudo-colored map displays generated from 8bit greyscale or pseudocolored raster data. However, if the raster file to be rendered is actually 24bit (a red, green and blue band) then additional considerations come into play. Currently rendering of 24bit imagery is only supported via the GDAL renderer. The built-in PNG, JPEG and other drivers do not support 24bit input images.

If the output is still 8bit pseudo-colored (the IMAGEMODE is PC256 in the associated OUTPUT format declaration) then the full 24bit RGB colors for input pixels will be converted to a color in the colormap of the output image. By default a color cube is used. That is a fixed set of 175 colors providing 5 levels of red, 7 levels of green and 5 levels of blue is used, plus an additional 32 greyscale color entries. Colors in the input raster are mapped to the closest color in this color cube on the fly. This substantial degrades color quality, especially for smoothly changing images. It also fills up the colors table, limited to 256 colors, quite quickly.

A variation on this approach is to dither the image during rendering. Dithering selects a color for a pixel in a manner that "diffuses error" over pixels. In an area all one color in the source image, a variety of output pixel colors would be selected such that the average of the pixels would more closely approximate the desired color. Dithering also takes advantage of all currently allocated colors, not just those in the color cube. Dithering requires GDAL 1.1.9 or later, and is enabled by providing the PROCESSING "DITHER=YES" option in the mapfile. Dithering is more CPU intensive than using a simple color cube, and should be avoided if possible in performance sensitive situations.

The other new possibility for handling 24bit input imagery in MapServer 4.0 or later, is to produce 24bit output images. The default "IMAGETYPE png24" or "IMAGETYPE jpeg" declaration may be used to produce a 24bit PNG output file, instead of the more common 8bit pseudo-colored PNG file. The OUTPUTFORMAT declaration provides for detailed control of the output format. The IMAGEMODE RGB and IMAGEMODE RGBA options produce 24bit and 32bit (24bit plus 8bit alpha/transparency) for supported formats.

World files are a simple mechanism for associating georeferencing (world coordinates) information with raster files. ESRI was the first company to propagate the use of world files, and they often used with TIFF instead of embedding georeferencing information in the file itself.

The world file contents look like the following. The first coefficient is the X pixel size. The second and third are rotational/shear coefficients (and should normally be 0.0). The fourth is the Y pixel size, normally negative indicating that Y decreases as you move down from the top left origin. The final two values are the X and Y location of the center of the top left pixel. This example is for an image with a 2m x 2m pixel size, and a top left origin at (356800E, 5767999N).

2
0.0000000000
0.0000000000
-2
356800.00
5767999.00

The name of the world file is based on the file it relates to. For instance, the world file for aerial.tif might be aerial.tfw. Conventions vary for appropriate endings, but with MapServer the extension .wld is always OK for world files.