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.

MapFile Structure

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</pre>

The LABEL Object and Keywords

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 fontset) file. This file lists each of the available fonts. See the file itself and the MapServer fontset 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 - deprecated

This specifies the shadow color of the label text.

Note

Since MapServer 6, LABEL STYLE with GEOMTRANSFORM LABELPOLY must be used instead. The tutorial files have not been updated.

SHADOWSIZE - deprecated

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.

Note

Since MapServer 6, LABEL STYLE with GEOMTRANSFORM LABELPOLY must be used instead. The tutorial files have not been updated.

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 | Proceed to Example 1.5