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):

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 mapfile reference 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.

Back to Example 1.3 | Back to the Section 1 | Back to the Sections Page | Proceed to Example 1.5