Example 1.1: Map With A Single Layer: Map /ms4w/apps/tutorial/htdocs/example1-1.map&layer States&mode Map

Example 1.
1: Map with a Single Layer
MapServer can create an image and dump it to a local directory or send it directly to the
requesting web browser, as in this example. You can view it without the need for an html
page, just enter this URL: http://<insert hostname or IP address here>/cgi-bin/mapserv.exe?
map=/ms4w/apps/tutorial/htdocs/example1-1.map&layer=states&mode=map (Remember to
replace "<insert hostname or IP address here >" with your web server's name, e.g.
"localhost", or its IP address, e.g. "127.0.0.1").
This URL can be broken into three parts: the first part, http://<insert hostname or IP address
here>/cgi-bin/mapserv.exe?, calls the MapServer CGI program. If you invoke it as is you will
get this familiar message:
No query information to decode. QUERY_STRING is set, but empty.
The next three parts are what make up the query string. The query string contains the CGI
parameters (variables and their values), with each parameter separated by an ampersand (&).
So, looking at the query string, the first parameter "map" has a value
"/ms4w/apps/tutorial/htdocs/example1-1.map"--this tells the MapServer CGI program
(mapserv or mapserv.exe) what mapfile to process/parse. The next parameter "layer=states",
tells mapserv.exe to "turn on" the states layer--recall that we named our layer object "states".
The last parameter, "mode=map", tells mapserv.exe what to do with the output from the
mapfile. In this case it tells mapserv.exe to dump the image directly to the web browser (the
client), without first creating a temporary image on the server. The MapServer "mode" CGI
variable takes values other than "map". For example if you use "mode=browse", MapServer
will dump the image to a temporary directory on the server. The browse mode will not work
now but we'll come back to it again later.
This is what the mapfile looks like (Example1-1.map):

# The annotated map file (sort of)
# Created by Pericles S. Nacionales for the MapServer tutorial
# 20050408
#
# MapServer map file uses the pound sign (#) to denote the start of a line
# comment--each line that needs to be commented has to be prepended with a
"#".
#
# Map files begin with MAP keyword to signify the start of the map object.
# Well, the entire map file is THE map object. Enclosed between MAP and
END
# at the very bottom of this map file, are keyword/value pairs and other
# objects.
MAP
IMAGETYPE PNG
EXTENT -97.238976 41.619778 -82.122902 49.385620
SIZE 400 300
SHAPEPATH "/ms4w/apps/tutorial/data"
IMAGECOLOR 255 255 255
# Layer objects are defined beneath the map object. You need at least
one
# layer defined in your map file before you can display a map... You can
# define as many layers as you'd like although a limit is typically hard-
coded
# in map.h in the MapServer source. The default limit is set at 100.
You'd
# have to have a very specialized application to need more than 100
layers in
# your application.
# Start of LAYER DEFINITIONS

---------------------------------------------
LAYER # States polygon layer begins here
NAME states
DATA states_ugl
STATUS OFF
TYPE POLYGON
# The class object is defined within the layer object. You can define
as
# many classes as you need (well, there are limits as with layers, but
it's
# senseless to define more than ten on a "normal" layer. There are
# situations, however, where you might have to do it.)
CLASS
NAME "The Upper Great Lakes States"
# There are styles in a class, just like there are classes in a

layer,
# just like there are layers in a map. You can define multiple
styles in
# a class just as you can define multiple classes in a layer and
multiple
# layers in a map.
STYLE
COLOR 232 232 232
OUTLINECOLOR 32 32 32
END
END
END # States polygon layer ends here
# End of LAYER DEFINITIONS -------------------------------
END # All map files must come to an end just as all other things must come
to...
The mapfile is MapServer's basic configuration mechanism. It is made up of "objects" and

each object can have keywords or other objects. It has a hierarchical structure such that some
objects fall under other objects... on top of this hierarchy is the MAP object, all other objects
belong to it. This example shows a very straightforward heirarchy of objects. As you go
through each example, the complexity of these hierarchical trees will increase.
A few quick notes about mapfiles: we define each object in the mapfile with the object name
and we close it with "END" and we precede comments with a pound (#) sign.
Let's break "example1-1.map" down by objects. Its structure looks like this:
MAP
|-LAYER
|-CLASS
|-STYLE
Let's look at the keywords (parameters) within the MAP object:
MAP
Every mapfile starts with the MAP object--the entire mapfile is the MAP object.
IMAGETYPE
The keyword IMAGETYPE is used to define which image format the MapServer CGI
program should use for output. In this case we are using indexed color PNG (similar to GIF).
This could be GIF, if we compiled the GD library with GIF support, WBMP, or JPEG. We
can also specify other output options (PDF, SWF, GeoTIFF) provided that we compiled
support for them and specify them with the OUTPUTFORMAT object. The
OUTPUTFORMAT goes beyond the scope of this tutorial but you can find out more about
by reading through documentations in the MapServer web site.
EXTENT
This parameter specifies the output extent of our map--the bounding box of our initial map.
The EXTENT values are given in this format: <Lower Left X> <Lower Left Y> <Upper
Right X> <Upper Right Y>, with spaces separating each value. This needs to be in the same
units as the data or, if specifying a different output projection, in the same units as the output
projection.
In this example our data is in geographic projection so the units are in decimal degrees. You
can use the utility "ogrinfo", which is part of the GDAL/OGR library package, to get the
extent of a particular shapefile (or other supported vector formats). Here is the command I
used to get the extent for this example:
ogrinfo -al -so states_ugl.shp

This returned the following output:
INFO: Open of `states_ugl.shp'
using driver `ESRI Shapefile' successful.
Layer name: states_ugl

Geometry: Polygon
Feature Count: 204
Extent: (-97.238976, 41.619778) - (-82.122902, 49.385620)
Layer SRS WKT:
(unknown)
AREA: Real (12.3)
PERIMETER: Real (12.3)
STATESP020: Real (11.0)
STATE: String (20.0)
STATE_FIPS: String (2.0)
CLASS: String (5.0)
You can also use ArcView or other open source GIS packages--Quantum GIS, Thuban, etc.
Feel free to change the values of EXTENT to get a better understanding of how it changes
your map.
SIZE
This is the size of the image (the map) that MapServer will generate, in pixels. So our map is
400 pixels wide by 300 pixels high. Again, change this to your heart's content and see how it
affects your map.
SHAPEPATH
This is the path to your data layers. You can provide absolute paths (i.e.
"/ms4w/apps/tutorial/data" or "C:/ms4w/apps/tutorial/data") or paths relative to your
mapfile's location (in this example, you'd use "../data"). This path doesn't have to be web
accessible, and probably shouldn't be unless you want anyone to download your raw data. It
has nothing directly to do with the web so don't even think of URLs here--just make sure that
the user running the web server (usually "nobody" or "apache" in the *nix world) can READ
the data in the SHAPEPATH.
IMAGECOLOR
This is the background color of your map. The values are RGB values so 255 Red, 255
Green, and 255B which results in a white background. Go ahead and play with this values.
Now let's look at the LAYER object parameters:
LAYER
Marks the beginning of a LAYER within the MAP object. You can specify as many layers as
you'd like although you are limited to 100, by default. To change this limit, you will have to
edit the map.h header file (in the soure tree) and recompile MapServer.
NAME
This is the layer identifier. MapServer uses this name to toggle the layer on and off. It won't
work in this example as we have the layer STATUS set to default. We will get back to this in
later examples.
DATA
The name of the data (shapefile in this case). MapServer supports vector data formats other
than ESRI's shapefile through the use of OGR library (part of the GDAL software package).
Please visit the GDAL project web site at http://www.gdal.org/ and read
http://www.gdal.org/ogr/index.html to know more about the different vector formats
MapServer supports. In addition, Jeff McKenna and Tyler Mitchell have written a detailed
guide to using vector data in MapServer. You can download this guide (PDF) from
http://dl.maptools.org/dl/docs/mapserv/ .
TYPE
What type of data is it? If it's a vector data, you can specify whether it is a POLYGON, LINE
(you use LINE even if your data is technically a POLYLINE), or a POINT. You can also
specify RASTER or ANNOTATION data. Here we want to display POLYGON.
STATUS
Layers are turned on or off based on their STATUS. DEFAULT is always on. ON or OFF
works when the LAYER name is passed as part of the query string.
Let's look at the CLASS object parameters:
CLASS
Marks the beginning of a CLASS object within the LAYER object. You can specify as many
classes within a layer although you are limited to 50 by default. You'll have to recompile
MapServer to change this default value.
NAME
The descriptive identifier for this CLASS. LAYER objects can have multiple classes, just like
MAP objects can have multiple layers. CLASS names are used by MapServer as labels for
the legend so make sure to use an appropriate descriptive name when naming classes. We
will talk about legends later in this tutorial.
And finally, let's look at the STYLE object parameters:
STYLE
Marks the beginning of the STYLE object. You can define multiple styles within a class--this
is useful when you want to overlay a style over another.
COLOR
This is the fill color of the polygon. In case the TYPE is LINE, this is the line color. The
values are in RGB format.
OUTLINECOLOR
This is the outline color of the polygons. The values are in RGB format. MapServer doesn't
draw polygon outlines by default, so if you want to see polygon boundaries, you will want to
define an OUTLINECOLOR.
Example 1.2: Static Map with Two Layers
As in the first example, this image was generated by linking the source of the <img> tag to
this URL: http://terrasip.gis.umn.edu/cgi-bin/mapserv.exe?
map=/ms4w/apps/tutorial/htdocs/example1-2.map
&layer=states_poly&layer=states_line&mode=map . This is how most of the examples in this
section work.
Anyway, you'll notice that the map here is the same as the first example. Yes, but the mapfile
is different. Have a look.

# 20050408
#
"#".
#
END
# objects.
MAP
IMAGETYPE PNG
EXTENT -97.238976 41.619778 -82.122902 49.385620
SIZE 400 300
SHAPEPATH "/ms4w/apps/tutorial/data"
one
coded
You'd
layers in
# your application.

---------------------------------------------
NAME states_poly
DATA states_ugl
STATUS OFF
TYPE POLYGON
as
it's
CLASS
NAME "States"

layer,
styles in
multiple
# layers in a map.
STYLE
COLOR 232 232 232
END
END
LAYER # States line layer begins here

NAME states_line
DATA states_ugl
STATUS OFF
TYPE LINE
CLASS
NAME "State Boundary"
STYLE
COLOR 32 32 32
END
END
END # States line layer ends here
to...
The mapfile structure, by objects, looks like this:
MAP
LAYER-|-LAYER
CLASS-| |-CLASS
STYLE-| |-STYLE
Here we split the original layer into two layers. The first layer is still a polygon layer but the
STYLE no longer has OUTLINECOLOR. The second layer is similar to the first except that
the TYPE is changed to LINE and the COLOR in the STYLE is changed to the same color as
the OUTLINECOLOR in the first example. This produces the same image as the first one...
So, why do it this way? If we continue to add layers on top of the states layer, the outline will
most likely be covered up by these other layers. To still see the state boundaries after we add
these other layers, we have to separate the states boundary line layer from the states polygon
layer and put it on top of the other other layers. There is order in how we define/add layers
and you'll see it clearly as we proceed in this section.
Example 1.3: Displaying Classes in a Layer
By using non-spatial attribute information in the data, we can create a map like this:

# 20050408
#
"#".
#
END
# objects.
MAP
IMAGETYPE PNG
EXTENT -97.238976 41.619778 -82.122902 49.385620
SIZE 400 300
SHAPEPATH "../data"
one
coded
You'd
layers in
# your application.

---------------------------------------------
NAME states_poly
DATA states_ugl
STATUS OFF
TYPE POLYGON
# CLASSITEM defines the non-spatial attribute that you will be using to

# separate a layer into classes. This attribute will be in the DBF
file
# of your shapefile (it will be different for each data format). In
this
# example the shapefile states_ugl has an associated database
# (states_ugl.dbf) that contains an attribute called "CLASS". You will
be
# using two values in the CLASS attribute to separate the classes (also
# called themes) used in this layer--land and water. CLASSITEM is used
in
# association with the EXPRESSION parameter in the CLASS object. See
below.
CLASSITEM "CLASS"
as
it's
CLASS
NAME 'States'
EXPRESSION 'land' # Only polygons where "CLASS" = 'land' will be
drawn.
layer,
styles in
multiple
# layers in a map.
STYLE
COLOR 232 232 232
END
END
CLASS
NAME 'Water'
EXPRESSION 'water' # Only polygons where "CLASS" = 'water' will be
drawn.
STYLE
COLOR 198 198 255
END
END

NAME states_line
DATA states_ugl
STATUS OFF
TYPE LINE
CLASSITEM "CLASS"
CLASS
NAME 'State Boundary'
EXPRESSION 'land'
STYLE
COLOR 32 32 32
END
END
to...
MAP
(states_poly) LAYER----------|---------LAYER (states_line)
| |
(land) CLASS---|---CLASS (water) |-CLASS
| | |
STYLE-| |-STYLE |-STYLE
Our mapfile still only has two layers but the polygon layer has been broken down into two
classes. Let's have a look at the additional parameters:
CLASSITEM
This keyword is used to specify what attribute to use in separating the class objects. In this
example that attribute is "CLASS". If you open the database file associated with this layer's
shapefile, you'll see that there's a column (attribute) called "CLASS".
How do we know which attribute to use? Well, database records in shapefiles are stored in
DBF files. You can open it in a spreadsheet program such as Openoffice.org's Calc, or in a
desktop GIS software such as QGIS, Thuban, or ArcView. If your data came with a metadata
(and it should!), you can skim through through that metadata file for attribute information.
You can also use "ogrinfo" to display basic attribute info in your shapefiles--look back at
example 1.1 (the last few lines after "Layer SRS WKT:" show the attribute names and types).
EXPRESSION
For each class, we specify what attribute value to use. This is the simplest form of
EXPRESSION. EXPRESSIONs can be even more complex than this, allowing one to
evaluate regular or logical expressions. Please look at the mapfile reference page to see what
you can do with EXPRESSION.
Example 1.4: Labeling the Map
We can also add labels to our map...
MapServer has a very flexible labeling engine. It supports native bitmap as well as truetype
fonts. Font scaling is supported with truetype. The labeling angles and placements can be
customized... If you take the time to learn the many parameters involved in creating good
labels, you will be rewarded with informative and aesthetically pleasing maps.
This is what the map file looks like (Example1-4.map):

# 20050408
#
"#".
#
END
# objects.
MAP
IMAGETYPE PNG
EXTENT -97.238976 41.619778 -82.122902 49.385620
SIZE 400 300
SHAPEPATH "../data"
FONTSET "../fonts/fonts.list"
one
coded
You'd
layers in
# your application.

---------------------------------------------
NAME states_poly
DATA states_ugl
STATUS OFF
TYPE POLYGON

file
this
be
in
below.
CLASSITEM "CLASS"
# Just like CLASSITEM, LABELITEM defines the database attribute that

you
# will be using to draw labels. In this case, the values of the
attribute
# "STATE" will be used to label the states polygons.
LABELITEM "STATE"
as
it's
CLASS
NAME 'States'
EXPRESSION 'land'

layer,
styles in
multiple
# layers in a map.
STYLE
COLOR 232 232 232
END
# There can be labels in a class, just like there are classes in a

layer,
labels in
multiple
# layers in a map.
# MapServer has a very flexible labeling system. With that
flexibility
# comes complexity, specially when using truetype fonts. Please read
# through the LABEL section of the MapServer map file documentation
at
# http://ms.gis.umn.edu/docs/reference/mapfile for more information.
LABEL
COLOR 132 31 31
SHADOWCOLOR 218 218 218
SHADOWSIZE 2 2
TYPE TRUETYPE
FONT arial-bold
SIZE 12
ANTIALIAS TRUE
POSITION CL
PARTIALS FALSE
MINDISTANCE 300
BUFFER 4
END # end of label
END
CLASS
NAME 'Water'
EXPRESSION 'water'
STYLE
COLOR 198 198 255
END
END

NAME states_line
DATA states_ugl
STATUS OFF
TYPE LINE
CLASSITEM "CLASS"
CLASS
EXPRESSION 'land'
STYLE
COLOR 64 64 64
END
END
to...
The map file structure, by objects, looks like this:
MAP
(states_poly) LAYER----------|---------LAYER (states_line)
(land) CLASS-----|-CLASS (water) |-CLASS
STYLE-|-LABEL |-STYLE |-STYLE
Here we introduce a few more parameters along with the LABEL object:
FONTSET
Here we specify the full path to our truetype fonts list (or font set) file. This file lists each of
the available fonts. See the file itself and the MapServer font set documentation for more
info. FONTSET is a parameter of the MAP object.
LABELITEM
This specifies which data attribute to use for labeling, in this case "STATE". LABELITEM is
a parameter of the LAYER object.
LABEL
Marks the beginning of the LABEL object. The label object can be used under other objects
(i.e. the SCALEBAR object).
COLOR
Within the LABEL object, COLOR specifies the color of the label text.
SHADOWCOLOR
This specifies the shadow color of the label text.
SHADOWSIZE
Specifies the shadow size. The value corresponds to the X and the Y shifts in pixels. So, "2
2" means two pixels wide by two pixels high.
TYPE
Within the LABEL object, TYPE specifies what type of font to use. We have the choice of
TRUETYPE or BITMAP (the built-in fonts). We choose TRUETYPE.
FONT
If you specify TYPE as TRUETYPE, you need to specify what font to use. The value here is
the "alias" in the font list file.
SIZE
If using truetype fonts, the value is size in pixels. If bitmap, you can say something like
"small" or "large".
ANTIALIAS
This turns truetype antialiasing on or off. Remember the value isn't on or off but TRUE or
FALSE.
POSITION
Where to position the label text in relation to the label points. The value is a combination of
vertical and horizontal positions. You have the following choices for vertical alignment: C for
center, U for upper, and L for lower. For horizontal alignment you have the following
choices: C for center, L for left, and R for right. So, to align the label text to the center of
label ID you'd use the value "CC" (center-center). Or if you'd like it to be on the lower left of
the ID, you'd use LL. Another way is to let MapServer decide the best position for your
labels. For this you would use the value "AUTO".
PARTIALS
Tells MapServer whether to generate incomplete label texts or not. The default here is not to
generate fragments of a label text. The value is either TRUE or FALSE.
MINDISTANCE
This is the minimum distance in pixels between duplicate labels. See what happens if you
increase or decrease this value.
BUFFER
The padding (in pixels) for each label. This is used to enhance readability. A BUFFER of 4
pixels mean that no label will be drawn within four pixels of each other. Again, change to see
how it works.
You can also create labels separate from a POLYGON layer. You do this with the
ANNOTATION data type. Have a look at the next example's map file to see how you'd
implement this kind of labeling. You will notice that the CLASS object within the "label"
layer has a COLOR parameter value of "-1 -1 -1". The negative number tells MapServer to
give this CLASS a transparent color (the label IDs don't show up). Once again, play with the
values to understand how it affects the map.
Example 1.5: Adding a Raster Layer

In addition to vector data support (point, lines, polygons, and annotations), 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 5.x uses GD version 2.0.x library 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.

# 20050408
#
"#".
#
END
# objects.
MAP
IMAGETYPE PNG24
EXTENT -97.238976 41.619778 -82.122902 49.385620
SIZE 400 300
SHAPEPATH "../data"
SYMBOLSET "../symbols/symbols35.sym"
one
coded
You'd
layers in
# your application.
#
---------------------------------------------
NAME states
DATA states_ugl
STATUS OFF
TYPE POLYGON

file
this
be
in
below.
CLASSITEM "CLASS"
as
it's
CLASS
NAME 'States'
EXPRESSION 'land'

layer,
styles in
multiple
# layers in a map.
STYLE
COLOR 232 232 232
END
END
# In addition to vector data (shapefiles are vector data), MapServer

supports
# a host of raster formats. In GIS world, one of the most common raster
# formats is GeoTIFF, a TIFF image with geospatial headers. MapServer
also
# supports JPEG, PNG, GIF, and other common formats. Other raster
formats
# supported by MapServer include ESRI Arc/Info grid, HDF and HDF-EOS,
NetCDF,
# Generic raster binaries, OGC Web Map Service (WMS) layers, etc. Pretty
much
# any raster format you can think of is probably supported, thanks to the
# impressive Geospatial Data Abstraction Library (GDAL, pronounced
"GOODALL"
# or GOODLE?). More information on GDAL is available at
http://www.gdal.org.
#
# MapServer 4.x can read and display bitmapped (like GIFs), RGB/A (true
# color), and multispectral (images with more than 3 bands, like raw
LandSat
# images) rasters.
LAYER # MODIS raster layer begins here
NAME modis
DATA "raster/mod09a12003161_ugl_ll_8bit.tif"
STATUS OFF
TYPE RASTER
PROCESSING "BANDS=1,2,3"
OFFSITE 71 74 65
END # MODIS raster layer ends here

NAME states_line
DATA states_ugl
STATUS OFF
TYPE LINE
CLASSITEM "CLASS"
CLASS
EXPRESSION 'land'
STYLE
SYMBOL 'line5'
COLOR 64 64 64
SIZE 1
END
END
# Labels can be defined in its own layer. This is useful if, say, you
want
# to label a polygon layer that's covered by another layer. By keeping
the
# label separate from the polygon and placing it near the bottom of the
map
# file (so its drawn on, or near the, top), you can still see the label
even
# though you might not be able to see the polygon. It is also a good
# alternate to point symbols.
#
# A label layer is actually defined with ANNOTATION type (This is derived
from
# points, Node IDs for lines, or polygon IDs).
LAYER # States label layer begins here
NAME states_label
DATA states_ugl
STATUS OFF
TYPE ANNOTATION
CLASSITEM "CLASS"

you
attribute
LABELITEM "STATE"
CLASS
EXPRESSION 'land'
STYLE
COLOR -1 -1 -1
END

layer,
labels in
multiple
# layers in a map.
flexibility
at
LABEL
COLOR 132 31 31
SHADOWSIZE 2 2
TYPE TRUETYPE
FONT arial-bold
SIZE 12
ANTIALIAS TRUE
POSITION CL
PARTIALS FALSE
MINDISTANCE 300
BUFFER 4
END # end of label
END # end of class
END # States label layer ends here
to...

MAP
LAYER #1-------------LAYER #2----|----LAYER #3--------LAYER
#4
(states_poly) (modis) (states_line)
(states_label)
| | |
(land) CLASS-|-CLASS (water) |-CLASS |-
CLASS
| | | |
STYLE-| |-STYLE |-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 SYMBOLOGY reference for further information.
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
http://ms.gis.umn.edu/docs/howto/raster_data .
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 ANNOTATION
for label IDs.
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:
STATUS DEFAULT
TYPE RASTER
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.
Example 1.6: Defining Projections and Extents

Whoa! What happened here?
You've just experienced on-the-fly reprojection. When a PROJECTION object is defined in

the mapfile, MapServer passes the layer and projection info to the Proj.4 library which does
the reprojection. For more information about the Proj.4 library, please visit
http://proj.maptools.org/ .
This example attempts to shed some light on the projection support in MapServer.

# 20050408
#
"#".
#
END
# objects.
MAP
IMAGETYPE PNG24
# EXTENT 199949.651166 -371954.772084 1472121.6862 632767.19157
EXTENT 201621.496941 -294488.285333 1425518.020722 498254.511514 #
LAEA
#EXTENT -97.5 41.619778 -82.122902 49.38562 # Geographic
SIZE 400 300
SHAPEPATH "../data"
SYMBOLSET "../symbols/symbols35.sym"
# The projection object is typically used within the map and the layer
# objects. You only define it once within the map object and this
definition
# becomes your output projection--MapServer will render your maps in this
# projection. You also use the projection object within the layer object
to
# define your input projection. Your layers can be in different
# projections--MapServer will reproject them into your output projection.
# If no projection is defined within the layer object, MapServer assumes
# your input projection is the same as your output projection. This is
not
# a required object unless you're creating a map file that supports one
of
# the OGC interoperability web services specifications (WMS/WFS/WCS).
#
# This is the output PROJECTION definition ------
PROJECTION
# Projection parameters can be defined in two ways...
# This is the traditional Proj.4 definition of Lambert Azimuthal Equal-
Area
# projection for the Continental U.S.
"proj=laea"
"ellps=clrk66"
"lat_0=45"
"lon_0=-100"
# Alternatively, you can specify an EPSG code.

# This is the EPSG code for Lambert Azimuthal Equal-Area
# projection for the U.S.
#
# "init=epsg:2163"
END # End of the output Projection definition ---
one
coded
You'd
layers in
# your application.
#
---------------------------------------------
NAME states
DATA states_ugl
STATUS OFF
TYPE POLYGON
# Here's an example of the input projection definition.

# EPSG:4326 is code for geographic (latlong) projection
# using the WGS84 datum.
#
# PROJECTION objects within the LAYER object define the input
# projection--this is the native projection of your data.
PROJECTION
"init=epsg:4326"
END

file
this
be
in
below.
CLASSITEM "CLASS"
as
it's
CLASS
NAME 'States'
EXPRESSION 'land'

layer,
styles in
multiple
# layers in a map.
STYLE
COLOR 232 232 232
END
END
# In addition to vector data (shapefiles are vector data), MapServer

supports
# a host of raster formats. In GIS world, one of the most common raster
# formats is GeoTIFF, a TIFF image with geospatial headers. MapServer
also
# supports JPEG, PNG, GIF, and other common formats. Other raster
formats
# supported by MapServer include ESRI Arc/Info grid, HDF and HDF-EOS,
NetCDF,
# Generic raster binaries, OGC Web Map Service (WMS) layers, etc. Pretty
much
# any raster format you can think of is probably supported, thanks to the
# impressive Geospatial Data Abstraction Library (GDAL, pronounced
"GOODALL"
# or GOODLE?). More information on GDAL is available at
http://www.gdal.org.
#
# MapServer 4.x can read and display bitmapped (like GIFs), RGB/A (true
# color), and multispectral (images with more than 3 bands, like raw
LandSat
# images) rasters.
LAYER # MODIS raster layer begins here
NAME modis
STATUS OFF
TYPE RASTER
OFFSITE 71 74 65
PROJECTION
"init=epsg:4326"
END
END # MODIS raster layer ends here

NAME states
DATA states_ugl
STATUS OFF
TYPE LINE
PROJECTION
"init=epsg:4326"
END
CLASSITEM "CLASS"
CLASS
EXPRESSION 'land'
STYLE
SYMBOL 'line5'
COLOR 64 64 64
SIZE 1
END
END
LAYER # States label layer begins here

NAME states_label
DATA states_ugl
STATUS OFF
TYPE ANNOTATION
PROJECTION
"init=epsg:4326"
END
CLASSITEM "CLASS"

you
attribute
LABELITEM "STATE"
CLASS
EXPRESSION 'land'
STYLE
COLOR -1 -1 -1
END

layer,
labels in
multiple
# layers in a map.
flexibility
at
LABEL
COLOR 132 31 31
SHADOWSIZE 2 2
TYPE TRUETYPE
FONT arial-bold
SIZE 12
ANTIALIAS TRUE
POSITION CL
PARTIALS FALSE
MINDISTANCE 300
BUFFER 4
END # end of label
END # end of class
END # States label layer ends here
to...
The first thing you might have noticed with our mapfile is the original EXTENT has been
commented out and the new EXTENT values don't look anything like latitude and longitude
values. Also, we have added a PROJECTION object near the top and within each of our
layers.
Let's have a look at the new object and parameter:
EXTENT 201621.496941 -294488.285333 1425518.020722 498254.511514

The extent we provide to MapServer needs to be in the same units as the output projection.
Since Lambert Azimuthal Equal-Area's units are in meters, we have to give the new extent in
meters. We can calculate the new extent using ArcView or some other GIS package, or you
can use Proj.4's cs2cs utility. The command below is what can be used to reproject the
original extent values:
cs2cs +proj=latlong +datum=WGS84 +to +proj=laea +ellps=clrk66 +lat_0=45

+lon_0=-100
After typing the command, enter the southwestern coordinate pair (the lower left
coordinates), separated by a space: -97.5 41.619778
to which the "cs2cs" utility gives the values:
208398.01 -372335.44 0.000
I then type the northeastern coordinate pair (upper right corner coordinates), again separated
by space: -82.122902 49.38562 and the following values are returned:
1285308.08 632638.93 0.000
You will notice that "cs2cs" returns a set of three values. You can ignore the third value,
0.000, as it means to represent altitute (which we're not using). Anyway, we can not present
the EXTENT as:
EXTENT 208398.01 -372335.44 1285308.08 632638.93
But it doesn't match up the extent above, you say. Well, that's what usually happens when
you reproject--the map doesn't necessarily get centered as you'd expect. You can fudge
around it, taking a few thousand meters off to the left and adding a few to the right. Or, you
can use a graphical GIS package to give you the extent. Here are the instructions for getting
EXTENT using ArcView.
MapServer can take projection definitions in two ways. The first is shown in the mapfile's
output PROJECTION object (the first PROJECTION block). This is the traditional way of
passing parameters to the Proj.4 library. The other way is to use the EPSG codes. These
codes are standard projection codes (or spatial reference identifiers) as defined by the
European Petroleum Survey Group (EPSG). In the case of our Lambert Azimuthal Equal-
Area projection, it has a code of "2163". If you comment out the four lines after
PROJECTION and uncomment the line "init=epsg:2163", this will provide the same
information to Proj.4. If you want to learn more about EPSG codes, have a look at
"/usr/local/share/proj/epsg" or "C:/proj/nad/epsg" ("/ms4w/proj/nad" in MS4W). Also, check
out the EPSG web site at http://www.epsg.org .
If you need to learn more about projections, please look through some of the links below:
http://www.colorado.edu/geography/gcraft/notes/mapproj/mapproj_f.html
http://www.geography.hunter.cuny.edu/mp/
http://www.nationalatlas.gov/articles/mapping/a_projections.html
http://en.wikipedia.org/wiki/Map_projection
http://erg.usgs.gov/isb/pubs/MapProjections/projections.html
You can find more by searching the web for "map projection".

Example 1.1: Map With A Single Layer: Map /ms4w/apps/tutorial/htdocs/example1-1.map&layer States&mode Map

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Example 1.1: Map With A Single Layer: Map /ms4w/apps/tutorial/htdocs/example1-1.map&layer States&mode Map

Uploaded by

Copyright:

Available Formats

Example 1.

1: Map with a Single Layer

No query information to decode. QUERY_STRING is set, but empty.

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

# Start of LAYER DEFINITIONS

# There are styles in a class, just like there are classes in a

The mapfile is MapServer's basic configuration mechanism. It is made up of "objects" and

Let's look at the keywords (parameters) within the MAP object:

ogrinfo -al -so states_ugl.shp

Layer name: states_ugl

Now let's look at the LAYER object parameters:

Let's look at the CLASS object parameters:

And finally, let's look at the STYLE object parameters:

Example 1.2: Static Map with Two Layers

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

# The annotated map file (sort of)

# Start of LAYER DEFINITIONS

# There are styles in a class, just like there are classes in a

LAYER # States line layer begins here

The mapfile structure, by objects, looks like this:

Example 1.3: Displaying Classes in a Layer

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

# Start of LAYER DEFINITIONS

# CLASSITEM defines the non-spatial attribute that you will be using to

LAYER # States line layer begins here

The mapfile structure, by objects, looks like this:

Example 1.4: Labeling the Map

We can also add labels to our map...

This is what the map file looks like (Example1-4.map):

# Start of LAYER DEFINITIONS

# CLASSITEM defines the non-spatial attribute that you will be using to

# Just like CLASSITEM, LABELITEM defines the database attribute that

# There are styles in a class, just like there are classes in a

# There can be labels in a class, just like there are classes in a

LAYER # States line layer begins here

The map file structure, by objects, looks like this:

Example 1.5: Adding a Raster Layer

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

# CLASSITEM defines the non-spatial attribute that you will be using to

# There are styles in a class, just like there are classes in a

# In addition to vector data (shapefiles are vector data), MapServer

LAYER # States line layer begins here

# Just like CLASSITEM, LABELITEM defines the database attribute that

# There can be labels in a class, just like there are classes in a

The mapfile structure, by objects, looks like this:

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

Also, try changing the IMAGETYPE from PNG24 to PNG.

Example 1.6: Defining Projections and Extents

You've just experienced on-the-fly reprojection. When a PROJECTION object is defined in

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

# Alternatively, you can specify an EPSG code.

# Here's an example of the input projection definition.

# CLASSITEM defines the non-spatial attribute that you will be using to

# There are styles in a class, just like there are classes in a

# In addition to vector data (shapefiles are vector data), MapServer

LAYER # States line layer begins here

LAYER # States label layer begins here

# Just like CLASSITEM, LABELITEM defines the database attribute that

# There can be labels in a class, just like there are classes in a

Let's have a look at the new object and parameter:

EXTENT 201621.496941 -294488.285333 1425518.020722 498254.511514

cs2cs +proj=latlong +datum=WGS84 +to +proj=laea +ellps=clrk66 +lat_0=45