2.8. Annotations in a map#

When you generate a map, MapServer automatically performs multiple tasks. It annotates features and prevents conflicts between adjacent dimensions. It provides the use of bitmapped and TrueType fonts.

View examples#

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

Here is the map file(mfa4.map):

 3    EXTENT -180 -90 180 90
 4    SIZE 600 300
 5    SHAPEPATH "/gdata"
 6    IMAGECOLOR 255 255 255
 7    FONTSET "../fonts/fonts.list"
 8    LAYER
 9        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

Annotated Mapfile

The file contains the font alias font location determined by the FONTSET Keyword assignment.

In order to label each city district with an attribute in the shapefile, determine the name as the value of the LABELITEM keyword. When rendering a country feature, the value of the feature’s NAME attribute will be used to create the label.

If you want to look at Shapefiles, there are several ways. You can open the associated DBF file in Excel or other spreadsheet program that can read DBF files, and you can see the feature attribute values. If you just want to find out the name of the attribute, you can use the utility dbfinfo, part of the shapelib library. In addition, the application ogrinfo provides geographic information, as well as feature values.

Each district will be labelled with the labelling parameters specified in 027 to 030. Label objects start with the keyword Label and end with the keyword END (line 030). Layer object with LABELITEM value set to ‘name’. Select the attribute NAME as the source of the label text. Each label will be drawn black and its size will be small. Besides small, you can choose small, medium, large, or huge.

The MapFile structure, by object, looks like this:

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

The changes in the documents are as follows:

Open the file:diff_mfa4_mfa3.html

Annotation parameter description#

Here, we introduce several parameters and dimension objects:

FONTSET "../fonts/fonts.list"

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

The contents of this file are as follows:

 1# This be the fonts list
 2arial                           Vera.ttf
 3arial-bold                      VeraBd.ttf
 4arial-italic                    VeraIt.ttf
 5arial-bold-italic               VeraBI.ttf
 6times                           VeraSe.ttf
 7times-bold                      VeraSeBd.ttf
 8andale-mono                     VeraMono.ttf
 9vera_sans                       Vera.ttf
10vera_sans-bold                  VeraBd.ttf
11vera_sans-italic                VeraIt.ttf
12vera_sans-bold-italic           VeraBI.ttf
13vera_sans_mono                  VeraMono.ttf
14vera_sans_mono-bold             VeraMoBd.ttf
15vera_sans_mono-italic           VeraMoIt.ttf
16vera_sans_mono-bold-italic      VeraMoBI.ttf
17vera_serif                      VeraSe.ttf
18vera_serif-bold                 VeraSeBd.ttf
19simsun                       simsun.ttc


In the "STATE" case, the specified data attribute is used for the annotation. LABELITEM is a parameter of the layer object.

LABEL Marks the beginning of the definition LABEL Object. Dimension objects can be used for other objects (that is, scale bar objects)

  • COLOR objects within the callout, color specifies the color of the callout text.

  • SHADOWCOLOR specifies the shadow color for dimension text.

  • SHADOWSIZE specifies the size of the shadow. This value corresponds to the transition of pixels at X and Y. Therefore, 2 means two pixels wide by two pixels high.

  • TYPE in the LABEL object, the type specifies what type of font to use. We have a choice of TrueType or Bitmap (built-in fonts). We choose TRUETYPE .

  • FONT If specified as TrueType, you need to specify what font to use. The value mentioned here is “alias”; the “alias” in the font list file.

  • SIZE If using a TrueType font, the value in pixels is the size of the dimension. If it’s a bitmap, say something like “small” or “big”.

  • ANTIALIAS This turns truetype antialiasing on or off. Remember that the value is not OPEN or CLOSE , but TRUE or FALSE .

  • POSITION locates the label point of the label text. The value is a combined vertical and horizontal position. You have the following options: C for center vertical alignment, U for upper, and L for lower. For horizontal alignment you have the following options: C for center, L for left, and R for right. Therefore, to call the center of the callout ID for the text alignment, use the value CC (center - center). Or, if you wanted it to be the ID at the bottom left, you would use LL . Another approach is to let MapServer decide the best location for the label. For this, you can use the AUTO value.

  • PARTIALS tells MapServer whether to generate incomplete label text. The default here is to not generate fragments of the label text. The value is TRUE or FALSE .

  • MINDISTANCE is the minimum distance, in pixels, between duplicate annotations. See what happens if you increase or decrease the value.

  • BUFFER Padding (pixels) of the callout. This is used to improve readability. A buffer of 4 pixels means that no labels will be drawn over the four pixels of each other. Again, change and see how it works.

You can also create dimensions to separate 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 tagging. You will find that the “annotation” layer within the class object has color parameter values. -1 -1 -1 . Negative numbers tell MapServer to give this class a transparent color (the callout logo is not displayed). Again, modify these values and view the results to see how it affects the map.

Automatic optimization of annotations#

To prevent the map from looking cluttered, MapServer optimizes the labeling according to the scale of the data.

Annotation processing#

Since version 6.2, MapServer has been able to draw label lines for functions that are problematic in the label space (usually when the label text is larger than the marked polygon). This feature is done through the addition of MS RFC 81: offset labels with leaders. This feature is for polygon annotations only.

Open the file:diff_mfs8_mfs2.html