Labels in the map

View example

MapServer has a very flexible labeling engine. It supports local bitmaps and TrueType fonts. Font scaling uses TrueType support. The angle and placement of the callout can be customized.

Below is the map file (

01 MAP
03     EXTENT -180 -90 180 90
04     SIZE 600 300
05     SHAPEPATH "/gdata"
06     IMAGECOLOR 255 255 255
07     FONTSET "../fonts/fonts.list"
08     LAYER
09         NAME "states_poly"
10         DATA "wcountry.shp"
11         STATUS OFF
12         TYPE POLYGON
13         LABELITEM "NAME"
14         CLASS
15             NAME "States"
16             STYLE
17                 COLOR 232 232 232
18             END
19             LABEL
20                 COLOR 132 31 31
21                 SHADOWCOLOR 218 218 218
22                 SHADOWSIZE 2 2
23                 TYPE TRUETYPE
24                 FONT "arial-bold"
25                 SIZE 8
26                 ANTIALIAS TRUE
27                 POSITION CC
28                 PARTIALS FALSE
29                 MINDISTANCE 300
30                 BUFFER 4
31             END
32         END
33     END
34     LAYER
35         NAME "states_line"
36         DATA "wcountry.shp"
37         STATUS OFF
38         TYPE LINE
39         CLASS
40             NAME "State Boundary"
41             STYLE
42                 COLOR 132 132 32
43             END
44         END
45     END
46 END

Annotated Mapfile

The MapFile structure, through the object, looks like this:

      (states_poly) LAYER----------|---------LAYER (states_line)
     (land) CLASS-----|-CLASS (water) |-CLASS

The file changes are as follows:

6    IMAGECOLOR 255 255 2556    IMAGECOLOR 255 255 255
nn7    FONTSET "../fonts/fonts.list"
7    LAYER8    LAYER
11        TYPE POLYGON12        TYPE POLYGON
n12        CLASSITEM "NAME"n13        LABELITEM "NAME"
13        CLASS14        CLASS
n14            NAME "China"n15            NAME "States"
15            EXPRESSION "CHINA"
16            STYLE16            STYLE
n17                COLOR 232 330n17                COLOR 232 232 232
18            END18            END
n19        ENDn
20        CLASS
21            NAME "Others"
22            STYLE19            LABEL
20                COLOR 132 31 31
23                COLOR 198 198 25521                SHADOWCOLOR 218 218 218
22                SHADOWSIZE 2 2
23                TYPE TRUETYPE
24                FONT "arial-bold"
25                SIZE 8
26                ANTIALIAS TRUE
27                POSITION CC
28                PARTIALS FALSE
29                MINDISTANCE 300
30                BUFFER 4
24            END31            END
31        TYPE LINE38        TYPE LINE
n32        CLASSITEM "NAME"n
33        CLASS39        CLASS
n34            NAME "China Boundary"n40            NAME "State Boundary"
35            EXPRESSION "land"
36            STYLE41            STYLE
t37                COLOR 32 32 32t42                COLOR 132 132 32
38                WIDTH 1
39            END
40        END
41        CLASS
42            NAME "Others Boundary"
43            STYLE
44                COLOR 150 150 150
45                WIDTH 0.4
46            END43            END

Labeling parameter description

Here we introduce several parameters and annotation objects:

FONTSET "../fonts/fonts.list"

Here we specify the file for the TrueType font list (or the full path set of the font). This file lists each available font. See the file itself and the MapFile reference for more information. The FONTSET MAP object is a parameter.

The contents of this file are as follows:

01 # This be the fonts list
02 arial                           Vera.ttf
03 arial-bold                      VeraBd.ttf
04 arial-italic                    VeraIt.ttf
05 arial-bold-italic               VeraBI.ttf
06 times                           VeraSe.ttf
07 times-bold                      VeraSeBd.ttf
08 andale-mono                     VeraMono.ttf
09 vera_sans                       Vera.ttf
10 vera_sans-bold                  VeraBd.ttf
11 vera_sans-italic                VeraIt.ttf
12 vera_sans-bold-italic           VeraBI.ttf
13 vera_sans_mono                  VeraMono.ttf
14 vera_sans_mono-bold             VeraMoBd.ttf
15 vera_sans_mono-italic           VeraMoIt.ttf
16 vera_sans_mono-bold-italic      VeraMoBI.ttf
17 vera_serif                      VeraSe.ttf
18 vera_serif-bold                 VeraSeBd.ttf
19 simsun                       simsun.ttc


In the case of "STATE", specify data attributes for labeling. LABELITEM is a parameter of this layer object.

LABEL marks the beginning of defining the LABEL object. Label objects can be used for other objects (ie scale objects)

  • COLOR The object inside the label, the color specifies the color of the label text.
  • SHADOWCOLOR This specifies the shadow color of the dimension text.
  • SHADOWSIZE Specifies the size of the shadow. This value corresponds to the transition of pixels in X and Y. Therefore, 2 means two pixels wide by two pixels wide.
  • TYPE In the LABEL object, the type specifies what type of font to use. We have a choice of TrueType or bitmap (built-in font). We choose TRUETYPE.
  • FONT If you specify the TrueType type, you need to specify which font to use. The value mentioned here is "alias"; the "alias" in the font list file.
  • SIZE If you use TrueType fonts, the pixels of this value are the size. If it is a bitmap, you can say something like "small" or "big".
  • ANTIALIAS This turns the antitype of truetype on or off. Remember that the value is not OPEN or CLOSE but TRUE or FALSE.
  • POSITION Positions the label point of the label text. This value is a combined vertical and horizontal position. You have the following options: C is center-aligned vertically, U, and L is low. For horizontal alignment you have the following choices: C is the center, L is left, and right is R. Therefore, to label the center of the text-aligned callout ID, you use the value CC (center - center). Or, if you want it to be the ID at the bottom left, you will use LL. Another way is to let MapServer decide where to mark the best position. For this, you can use the AUTO value.
  • PARTIALS Tells MapServer whether to generate incomplete label text. The default value here is a fragment that does not produce annotated text. The value is TRUE or FALSE.
  • MINDISTANCE This is the minimum distance between repeated labels, in pixels. If you increase or decrease the value, see what happens.
  • BUFFER fills (pixels) the label. This is used to improve readability. A buffer of 4 pixels means that there are no four pixels labeled to be drawn on each other. Again, change to see how it works.

You can also create callouts to detach a polygon layer. You do it with the data type of the annotation. Take a look at the MapFile of the following example to see how you implement this callout. You will find that the callout layer within the class object has a color parameter value of 1-1-1. Negative numbers tell MapServer to give this class A transparent color (the callout ID is not displayed). One more time, modify these values and view the results to see how it affects the map.

Automatic optimization of annotations

In order to avoid the map looking messy, MapServer will optimize the label according to the scale of the data.