:orphan:

.. _example1-4:

===========
Example 1.4
===========

Labeling the Map
----------------
          
We can also add labels to our map...

.. image:: https://demo.mapserver.org/cgi-bin/mapserv?map=/osgeo/mapserver/tutorial/htdocs/example1-4.map&layer=states_poly&layer=states_line&mode=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: :ref:`Example1-4.map <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 :ref:`MapServer fontset documentation
   <fontset>` 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.

----

:ref:`Back to Example 1.3 <example1-3>` | :ref:`Proceed to Example 1.5 <example1-5>`
