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）：

01 MAP
02     IMAGETYPE "PNG"
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 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:

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

The changes in the documents are as follows:

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:

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

LABELITEM

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.