.. index::
   single: Symbol construction

.. _sym_construction:

*****************************************************************************
 Cartographical Symbol Construction with MapServer 
*****************************************************************************

:Author: Peter Freimuth
:Contact: pf at mapmedia.de
:Author: Arnulf Christl
:Contact: arnulf.christl at wheregroup.com
:Author: Håvard Tveite
:Contact: havard.tveite at nmbu.no

.. contents:: Table of Contents
    :depth: 3
    :local:
    :backlinks: top

Abstract
========

This Document refers to the syntax of *map* and *symbol* files for
MapServer 6.  The first version of the document was based on the
results of a project carried out at the University of Hannover,
Institute of Landscape and Nature Conservation. It was initiated by
Mr. Dipl. Ing. Roland Hachmann. Parts have been taken from a study
carried through by Karsten Hoffmann, student of Geography and
Cartography at the FU Berlin. In the context of a hands-on training in
the company GraS GmbH Mr. Hoffman mainly dealed with the development
of symbols.  (`Download study report`_ in German) His degree
dissertation will also concern this subject.

The document has been heavily revised for MapServer  6.

.. _`Download study report`: http://www.mapmedia.de/fileadmin/user_upload/dokumente/umn_signaturen_howto/Praktikumsarbeit.zip


Introduction
============

A map is an abstract representation that makes use of point, line and
area symbols.  Bertin (1974) created a clear and logical symbol scheme
in which symbols can be varied referring to graphical variables.  The
following graphical variables can be used within MapServer: FORM, SIZE,
PATTERN, COLOR and LIGHTNESS.  Point and area symbols as well as text
fonts (ttf) can additionally be displayed with a frame which we call
OUTLINE.

The following figure shows the theoretical structure of cartographical
symbols, which is also used in MapServer:

.. figure:: ../../images/carto-elements.png
   :height: 400
   :width: 600
   :align: center

   Structure of Cartographical Symbols`

Multiple Rendering and Overlay
------------------------------

Say you want to display a highway with a black border line, two yellow
lanes and a red center lane.  This calls for a combination of
signatures.

Complex cartographical effects can be achieved by rendering the same
vector data with different symbols, sizes and colours on top of each
other.  This can be done using separate :ref:`layer`\s.  This could,
however, have performance effects for the application, as every
rendering process of the same geometry will take up additional
processor time.  The preferred solution is to use multiple
:ref:`style`\s to create complex symbols by overlay.

To create the highway symbol mentioned above with a total width of 9
units, the lowest :ref:`style` (in drawing order) will be a broad
black line with a width of 9 units. The second level :ref:`style` will
be a yellow line with a width of 7 units, and the topmost :ref:`style`
will be a red line with a width of 1 unit. That way each yellow
coloured lane will have a width of (7-1)/2 = 3 units.

Combining symbols can be a solution for many kinds of cartographical
questions.  A combination of different geometry types is also
possible.  A polygon data set can be rendered as lines to frame the
polygons with a line signature.  It can also be rendred as polygons
with a symbol filling the polygon.  When the polygon fill is rendered
on top of the lines, the inner part of the underlying outline is
covered by the fill symbol of the polygon.  What is observed here is a
clipping effect tha in will result in an asymmetric symbol for the
boundary line.  To present the outline without clipping, just reorder
the :ref:`layer`\s or :ref:`style`\s and put the outline presentation
on top of the fill.

Yet another way to construct advanced line signatures for framed
polygons is to tamper with the original geometries by buffering or
clipping the original geometry such that the new objects lie inside
the original polygons or grow over the borders.  PostGIS can help
achieve a lot of effects.

The `OPACITY` parameter of :ref:`layer` and :ref:`style` can be used
to achieve transparency (making lower symbols "shine" through upper
symbols).

.. index::
   single: Symbol scaling

Symbol Scaling
--------------

There are two basically different ways of handling the display size of
symbols and cartographical elements in a map at different scales.  The
size of cartographical elements is either set in screen pixels or in
real world units.

- If the size is set in real world units (for example meters), the
  symbol will shrink and grow according to the scale at which the map
  is displayed.

- If the size is set in screen pixels, symbols look the same at all
  scales.

The default behaviour of MapServer is to implement the "screen pixels"
size type for displaying cartographical elements.

"Real world units", as described above, can be achieved using either
the `SIZEUNITS` or the `SYMBOLSCALEDENOM` parameter of the
:ref:`layer`.

- When `SIZEUNITS` is set (and is not `pixels`), symbol sizes are
  specified in real world units (for instance meters).  For available
  units, see the `SIZEUNIT` documentation.

- When `SYMBOLSCALEDENOM` is set, the given symbols size is used for
  the map scale 1:`SYMBOLSCALEDENOM`, for other scales, the symbols
  are scaled proportionally.

:ref:`style` `MAXSIZE` and `MINSIZE` limits the scaling of symbols.


.. index::
   single: Symbol specification

MapServer  and symbol specification
------------------------------------

In a MapServer application, :ref:`symbol` parameters are organised in
the *map* file as follows:

- Each :ref:`layer` has a `TYPE` parameter that defines the type of
  geometry (point, line or polygon).  The symbols are rendered at
  points, along lines or over areas accordingly.
  
- Basic symbols are defined in :ref:`symbol` elements, using the
  parameters `TYPE`, `POINTS`, `IMAGE`, `FILLED`, `ANCHORPOINT` and
  more (:ref:`symbol` elements can be collected in separate *symbol
  files* for reuse).
  
- Colour, lightness, size and outline are defined inside the
  :ref:`style` sections of a :ref:`class` section using the parameters
  `COLOR`, `SIZE`, `WIDTH` and `OUTLINECOLOR`.

- Patterns for styling lines and polygons are defined in :ref:`style`
  sections using `GAP` and `PATTERN`.
  
- Several basic elements can be combined to achieve a complex
  signature using several :ref:`style`\s inside one :ref:`class`.
  
The following example shows the interaction of some of these elements
and explains the configuration in the :ref:`layer` and the
:ref:`symbol` sections necessary for rendering a cartographical point
symbol (a red square with a 1 pixel wide black outline and a smaller
blue circle inside):

.. figure:: ../../images/symcon-overlay.png 
   :align: center                           
                                            
   The generated overlay symbol             

.. table:: Commented :ref:`layer` and :ref:`symbol` sections.

  +----------------------------------------------------------+------------------------------------------------------------------------+
  | :ref:`layer` section of the map file                     | :ref:`symbol` (from a separate symbol file or in-line in the map file) |
  +==========================================================+========================================================================+
  |.. code-block:: mapfile                                   |.. code-block:: mapfile                                                 |
  |                                                          |                                                                        |
  |  # Start of layer definition                             |   # Start of symbol definition                                         |
  |  LAYER                                                   |   SYMBOL                                                               |
  |    # Name of the layer                                   |     # Symbol name (referenced in STYLEs)                               |
  |    NAME "mytest"                                         |     NAME "square"                                                      |
  |    TYPE POINT     # Point geometries                     |     TYPE vector # Type of symbol                                       |
  |    STATUS DEFAULT # Always draw                          |     # Start of the symbol geometry                                     |
  |    # Use the dataset test.shp                            |     POINTS                                                             |
  |    DATA test                                             |       0 0                                                              |
  |    # Start of a Class definition                         |       0 1                                                              |
  |    CLASS                                                 |       1 1                                                              |
  |      # Start of the first Style                          |       1 0                                                              |
  |      STYLE                                               |       0 0                                                              |
  |        # Symbol to be used (reference)                   |     END # end of POINTS                                                |
  |        SYMBOL "square"                                   |     # The symbol should be filled                                      |
  |        # Size of the symbol in pixels                    |     FILLED true                                                        |
  |        SIZE 16                                           |     # Place the according to its center                                |
  |        # Colour (RGB) - red                              |     ANCHORPOINT 0.5 0.5                                                |
  |        COLOR 255 0 0                                     |   END # end of SYMBOL                                                  |
  |        # Outline colour (RGB) - black                    |                                                                        |
  |        OUTLINECOLOR 0 0 0                                |   # Start of symbol definition                                         |
  |      END # end of STYLE                                  |   SYMBOL                                                               |
  |      # Start of the second Style                         |     # Symbol name (referenced in STYLEs)                               |
  |      STYLE                                               |     NAME "circle"                                                      |
  |        # Symbol to be used (reference)                   |     TYPE ellipse # Type of symbol                                      |
  |        SYMBOL "circle"                                   |     # Start of the symbol geometry                                     |
  |        # Size of the symbol in pixels                    |     POINTS                                                             |
  |        SIZE 10                                           |       1 1                                                              |
  |        # Colour (RGB) - blue                             |     END # end of POINTS                                                |
  |        COLOR 0 0 255                                     |     # The symbol should be filled                                      |
  |      END # end of STYLE                                  |     FILLED true                                                        |
  |    END # end of CLASS                                    |     # Place the according to its center                                |
  |  END # end of LAYER                                      |     ANCHORPOINT 0.5 0.5                                                |
  |                                                          |   END # end of SYMBOL                                                  |
  +----------------------------------------------------------+------------------------------------------------------------------------+
                         
.. index::
   single: Cartographical symbols

Using Cartographical Symbols in MapServer
=========================================

Vectors, truetype fonts and raster images are basic graphical elements
that are defined by the `TYPE` parameter in the :ref:`style` element.
This and the following sections explain how these elements
can be combined to create complex cartographical symbols, and they
describes some other important aspects of map rendering in MapServer .

Output formats
--------------

MapServer support raster output formats (e.g. PNG, JPEG and GIF) and
vector output formats (e.g. PDF, SVG).  The raster formats (except for
GIF) use anti-aliasing.  See :ref:`outputformat` (and :ref:`map`
`IMAGETYPE`) for more.

Symbol units
------------

The units used for specifying dimensions is defined in the `SIZEUNITS`
parameter of the :ref:`layer`.  The available units are listed there.
The default unit is `pixels`.

The `MAP` element's `RESOLUTION` and `DEFRESOLUTION` parameters will
determine the resolution of the resulting map and hence the size in
pixels of the symbols on the map.  `DEFRESOLUTION` is by default 72
dpi (dots per inch).  If `RESOLUTION` is set to 144 (and
`DEFRESOLUTION` is 72), all dimensions specified in the map file will
be multiplied by 144/72 = 2.  This can be used to produce higher
resolution images.

Dimensions can be specified using decimals.

.. index::
   single: Scaling of symbols

Scaling of Symbols
------------------

The `SYMBOLSCALEDENOM` parameter in the :ref:`layer` section specifies
the scale at which the symbol or text label is displayed in exactly
the dimensions defined in the :ref:`style`\s (for instance using
`SIZE` and `WIDTH`).  Observe that all the parameters concerned with
the symbol dimensions (`SIZE`\, `WIDTH`\, ...) are tightly connected
to the `SYMBOLSCALEDENOM` parameter.  The `MAXSIZE` and `MINSIZE`
parameters inside the :ref:`style` element limit the scaling of
symbols to the maximum and minimum size specified here (but does not
affect the size calculations).

When symbols are scaled as the scale changes, the elements (defined in
:ref:`style`\s) of a composite cartographical symbol may change their
positions relative to each other.  This is due to rounding effects
when creating the image.  The effect is most noticeable at small scales
(large scale denominators), when the symbols get small.  Due to the
same effects, symbols can also slightly change their shape when they
get small.

It is not possible to define the display intervals with
`MINSCALEDENOM` and `MAXSCALEDENOM` in the :ref:`style`\-section, so
this kind of tuning has to be solved at the :ref:`layer` level.  To do
this, create several :ref:`layer`\s with the same geometries for
different scale levels.

Always observe that cartographical symbols depend a lot on the scale!
So be careful with the interaction of content, symbols and scale.  All
three parameters heavily interact and have to be coordinated to
produce a good map.


.. index::
   single: Point symbols

Construction of Point Symbols
=============================

In the figure below, point symbols of `TYPE` `truetype`, `pixmap`,
`ellipse` and `vector` are demonstrated.  The precise position of the
point for which the symbol is rendered is shown with a small red dot.
A small blue dot is used to show an offset position.

.. figure:: ../../images/symcon-points.png
   :align: center

   Basic point symbol `TYPE`\s, showing effects of size, offset, angle
   and outlinecolor

All point symbols can be rotated using the `ANGLE` parameter.

Since version 6.2, the anchor point / reference point of all point
symbols can be set using the :ref:`symbol` `ANCHORPOINT` parameter.
The default anchorpoint is at the center of the boundingbox of the
symbol (`ANCHORPOINT` 0.5 0.5).

.. index::
   single: Ellipse symbols

.. index::
   single: Vector symbols

Symbols of `TYPE` `vector` and `ellipse`
----------------------------------------

For symbols of `TYPE` `vector` and `ellipse` the shape of the symbol
by setting X and Y values in a local two dimensional coordinate system
with X values increasing to the right and Y values increasing
downwards.  The coordinates defining the symbol is listed in the
`POINTS` parameter, which is explicitly ended using `END`.  Negative
values should not be used.

- `TYPE` `ellipse` is used to create ellipses (and circles).  The
  shape of the ellipse is defined in the `POINTS` parameter (X - size in
  the horizontal direction, Y - size in the vertical direction).  To
  create a circle, let X and Y have the same value.

- `TYPE` `vector` is used to define advanced vector symbols.  The
  shape of the symbol is defined in the `POINTS` parameter.  A `vector`
  symbol can consist of several elements.  The coordinates -99 -99 are
  used to separate the elements.

  To create a polygon vector symbol, the :ref:`symbol` `FILLED`
  parameter must be set to `true`.  If the end point is not equal to
  the start point of a polygon geometry, it will be closed
  automatically.

  The maximum number of points is 100, but this can be increased by
  changing the parameter MS_MAXVECTORPOINTS in the file mapsymbols.h
  before compilation.

  When creating symbols of `TYPE` `vector` you should observe some style
  guidelines.

  - Avoid downtilted lines in area symbols, as they will lead to heavy
    aliasing effects.

  - Do not go below a useful minimum size.  This is relevant for all
    types of symbols.

  - Keep in mind that for pixel images, every symbol of `TYPE`
    `vector` has to be rendered using pixels.

  .. note::

    The bounding box of a vector symbol has (0,0) in the symbol
    coordinate system as its upper left corner.  This can be used to
    precisely control symbol placement.  Since version 6.2
    :ref:`symbol` `ANCHORPOINT` should be used instead.

.. index::
   single: Truetype symbols

Symbols of `TYPE` `truetype`
----------------------------

You can use symbols from truetype fonts. The symbol settings are
defined in the :ref:`symbol` element. Specify the character or the
ASCII number of the character to be used in the `CHARACTER`
parameter. The `FONT` parameter is used to specify the font to be used
(the alias name from the font file - often "fonts.list").  The
`FONTSET` parameter of the `MAP` element must be set for fonts to
work.

For gif output (GD renderer), you can define that you want to apply
antialiasing to the characters by using the parameter `ANTIALIAS`\.
It is recommended to do this especially with more complex symbols and
whenever they don't fit well into the raster matrix or show a visible
pixel structure.

Colours for `truetype` symbols can be specified in :ref:`layer`
:ref:`class` :ref:`style` (as with symbols of the `TYPE` `vector` and
`ellipse`).  You can specify both fill colour and outline colour.

To find out the character number of a symbol use one of the following
options:

- Use the software FontMap (Shareware, with free trial version for
  download, thanks Till!).

- Use the MS Windows truetype map.
 
- Trial and Error. :-) 

Please note that the numbering of the so-called "symbol fonts" starts
at 61440!  So if you want to use character &#84, you have to use 61440
+ 84 = &#61524.  (ain't that a pain!!)

You can also place truetype characters and strings on the map using
`LABEL`.  Then you can control the placing of the text by using the
`POSITION` parameter [ul|uc|ur|cl|cc|cr|ll|lc|lr], that specifies the
position relative to the geometric origin of the geometry.

.. index::
   single: Pixmap symbols

Symbols of `TYPE` `pixmap`
--------------------------

Symbols of the `TYPE` `pixmap` are simply small raster images. The
file name of the raster image is specified in the `IMAGE` parameter of
the :ref:`symbol` element.  MapServer supports the raster formats GIF
and PNG for `pixmap`\s.

Observe the colour depth of the images and avoid using 24 bit PNG
symbols displayed in 8 bit mode as this may cause unexpected colour
leaps.

When using raster images, the colour cannot be modified in the
:ref:`symbol` element subsequently.

You can specify a colour with the `TRANSPARENT` parameter which will
not be displayed - i.e. it will be transparent. As a result,
underlying objects and colours are visible.

The `SIZE` parameter defines the height of `pixmap` symbols when
rendered.  The pixel structure will show when the `SIZE` grows too
large.  If you are using symbol scaling (:ref:`layer`
`SYMBOLSCALEDENOM` is set or :ref:`layer` `SIZEUNITS` is not `pixels`)
and want to prevent this from happening, you should set the
:ref:`style` `MAXSIZE` parameter.


Symbol definitions for the figure that demonstrates point symbols
-----------------------------------------------------------------

This code was used to produce the symbols in the point symbol figure.

First, the symbol definitions:

.. code-block:: mapfile

  SYMBOL
    NAME "o-flag-trans"
    TYPE pixmap
    IMAGE "o-flag-trans.png"
  END # SYMBOL

  SYMBOL
    NAME "circlef"
    TYPE ellipse
    FILLED true
    POINTS
      10 10
    END # POINTS
  END # SYMBOL

  SYMBOL
    NAME "P"
    TYPE truetype
    FONT "arial"
    CHARACTER "P"
  END # SYMBOL

  SYMBOL
    NAME "v-line"
    TYPE vector
    FILLED false
    POINTS
      0  0
      5  10
      10 0
    END # POINTS
  END # SYMBOL

  SYMBOL
    NAME "v-poly"
    TYPE vector
    FILLED true
    POINTS
      0  0
      3.5 8
      7 0
      5.2 0
      3.5 4
      1.8 0
      0 0
    END # POINTS
  END # SYMBOL

Then, the :ref:`layer`\s and :ref:`style`\s used for producing the
polygon V symbols in the point symbol figure:

.. code-block:: mapfile

  LAYER  # Vector v - polygon
    STATUS DEFAULT
    TYPE POINT
    FEATURE
      POINTS
        10 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        COLOR 0 0 0
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 255 0 0
        SIZE 4
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Vector v - polygon, size
    STATUS DEFAULT
    TYPE POINT
    FEATURE
      POINTS
        20 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        COLOR 0 0 0
        SIZE 30
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 255 0 0
        SIZE 4
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Vector v - polygon, size, angle
    STATUS DEFAULT
    TYPE POINT
    FEATURE
      POINTS
        30 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        COLOR 0 0 0
        SIZE 30
        ANGLE 60
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 255 0 0
        SIZE 4
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Vector v - polygon, size, offset
    STATUS DEFAULT
    TYPE POINT
    FEATURE
      POINTS
        40 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        COLOR 0 0 0
        SIZE 30
        OFFSET 0 15
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 255 0 0
        SIZE 4
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Vector v - polygon, size, angle, offset
    STATUS DEFAULT
    TYPE POINT
    FEATURE
      POINTS
        50 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        COLOR 0 0 0
        SIZE 30
        ANGLE 60
        OFFSET 0 15
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 255 0 0
        SIZE 4
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Vector v - polygon, size outline
    STATUS DEFAULT
    TYPE POINT
    FEATURE
      POINTS
        60 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        COLOR 0 0 0
        SIZE 30
        OUTLINECOLOR 0 255 0
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 255 0 0
        SIZE 4
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Vector v - polygon, size, outline, width
    STATUS DEFAULT
    TYPE POINT
    FEATURE
      POINTS
        70 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        COLOR 0 0 0
        SIZE 30
        OUTLINECOLOR 0 255 0
        WIDTH 4
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 255 0 0
        SIZE 4
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Vector v - polygon, size, outline, no color
    STATUS DEFAULT
    TYPE POINT
    FEATURE
      POINTS
        80 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        SIZE 30
        OUTLINECOLOR 0 255 0
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 255 0 0
        SIZE 4
      END # STYLE
    END # CLASS
  END # LAYER

.. index::
   single: Combining symbols

Combining symbols
-----------------

The following figure shows how to combine several basic symbols to
create a complex point symbol. The combination is achieved by adding
several :ref:`style`\s within one :ref:`layer`. Each :ref:`style`
element references one :ref:`symbol` element.  All the basic symbols
are centered and overlaid when rendered.

Notice that the `SIZE` parameter in the :ref:`style` element refers to
the height of the symbol (extent in the Y direction). A standing
rectangle will thus display with a smaller area than a lying
rectangle, although both have the same `SIZE` parameter and the same
maximum Y value in the :ref:`symbol` element.  When combining several
basic point symbols on top of each other, they will not always be
centered correctly due to the integer mathematics required when
rendering raster images.  It is recommended not to combine elements
with even and odd numbered `SIZE` parameters, as this tends to produce
larger irregularities.

.. figure:: ../../images/point-symbols.png
   :width: 730
   :height: 508
   :align: center

   Construction of Point Symbols

.. index::
   single: Line symbols

Construction of Line Symbols
============================

For displaying line geometries, you specify the width of the lines
using the `WIDTH` parameter and the colour using the `COLOR`
parameter.  If no colour is specified, the line will not be rendered.
If no width is specified, a thin line (one unit (pixel) wide) will be
rendered.  The `LINECAP`, `LINEJOIN` and `LINEJOINMAXSIZE` parameters
are used to specify how line ends and corners are to be rendered.

.. index::
   single: Line symbol overlay

Overlaying lines
----------------

When combining several styles / symbols on a line, they will be
positioned on the baseline which is defined by the geometry of the
object.  In most cases MapServer correctly centers symbols.  The
combination of a line displayed in 16 units width and overlaid with a
10 unit width line, results in a line symbol with a 3 unit border.  If
the cartographical symbol is to contain a centered line with a width
of 1 pixel, then the widths should be reconfigured, for example to 11
and 17 units. As a rule of thumb don't combine even numbered and odd
numbered widths.


.. index::
   single: GAP

.. index::
   single: PATTERN

.. _construction_pattern_gap:

Use of the `PATTERN` and `GAP` parameters
-----------------------------------------

The `PATTERN` and `GAP` parameters can be used to produce styled lines
in MapServer.

To create line patterns, use the `PATTERN` parameter of the
:ref:`style`\.  Here you define dashes by specifying the length of the
first dash, followed by the length of the first gap, then the length
of the second dash, followed by the second gap, and so on.  This
pattern will be repeated as many times as that pattern will fit into
the line.  `LINECAP` can be used to control how the ends of the dashes
are rendered.  `LINEJOIN` can be used to control how sharp bends are
rendered.  In the left column of the figure, you will find three
examples where `PATTERN` has been used.  Number 2 from below uses
`LINECAP` `butt`, number 3 from below uses `LINECAP` `round` (and
`LINEJOIN` `miter`) and number 4 from below uses `LINECAP` `butt` (and
is overlaid over a wider, dark grey line).  To produce dots, use 0
for dash length with `LINECAP` 'round'.

Styled lines can be specified using `GAP` and a symbol for styling.
In the figure, you will find examples where `GAP` has been used (in
the right column).  At the bottom a :ref:`symbol` of `TYPE` `ellipse`
has been used, then a :ref:`symbol` of `TYPE` `vector`, then a
:ref:`symbol` of `TYPE` `font` and then a :ref:`symbol` of `TYPE`
`pixmap`.  To control the placement of the symbols relative to the
line (to get asymmetrical styling), use :ref:`symbol` `ANCHORPOINT`
(as explained later).

.. note::

  Since version 6.2 it is possible to specify an offset (start gap)
  when creating asymmetrical patterns using the :ref:`style`
  `INITIALGAP` parameter.  `INITIALGAP` can be used with `GAP` and
  with `PATTERN`.

The following figure shows how to use styles to define different kinds
of line symbols.

- `PATTERN` usage is demonstrated in the 2nd, 3rd, 4th and 5th symbol
  from the bottom in the left column.

- `GAP` usage is demonstrated in the 2nd symbol from the bottom in the
  left column and all the symbols in the right column.

- negative `GAP` value usage is demonstrated in the all the symbols in
  the right column, except for the one at the bottom.

- `INITIALGAP` usage is demonstrated in the 2nd and 5th symbol from
  the bottom in the left column.

- :ref:`style` `OFFSET` usage is demonstrated in the 5th symbol from
  the bottom in the right column

.. figure:: ../../images/symcon-lines.png
   :align: center
   :width: 570
   :height: 390

   Construction of Line Symbols

Below you will find the :ref:`symbol`\s and :ref:`style`\s that were
used to produce the line symbols in "Construction of Line Symbols".
The :ref:`layer`\s are ordered from bottom to top of the figure.

**Styles and symbols for lines**

.. code-block:: mapfile

  SYMBOL
    NAME "circlef"
    TYPE ellipse
    FILLED true
    POINTS
      1 1
    END # POINTS
  END # SYMBOL

  SYMBOL
    NAME "P"
    TYPE truetype
    FONT "arial"
    CHARACTER "P"
  END # SYMBOL

  SYMBOL
    NAME "vertline"
    TYPE vector
    FILLED true
    POINTS
      0 0
      0 10
      2.8 10
      2.8 0
      0 0
    END # POINTS
    ANCHORPOINT 0.5 0
  END # SYMBOL

  SYMBOL
    NAME "o-flag-trans"
    TYPE pixmap
    IMAGE "o-flag-trans.png"
  END # SYMBOL

  ######## Left column ###############

  LAYER  # Simple line
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        5 5
        25 10
        45 10
        35 5
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 6.5
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Dashed line with symbol overlay
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        5 15
        25 20
        45 20
        35 15
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 5.0
        PATTERN 40 10 END
      END # STYLE
      STYLE
        SYMBOL "circlef"
        COLOR 0 0 0
        SIZE 8
        INITIALGAP 20
        GAP 50
      END
    END # CLASS
  END # LAYER

  LAYER  # Dashed line, varying
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        5 25
        25 30
        45 30
        35 25
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 5.0
        LINECAP round #[butt|round|square|triangle]
        LINEJOIN miter #[round|miter|bevel]
        LINEJOINMAXSIZE 3
        PATTERN 40 17 0 17 0 17 0 17 END
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Line dash overlay
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        5 35
        25 40
        45 40
        35 35
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 102 102 102
        WIDTH 4.0
      END # STYLE
      STYLE
        COLOR 255 255 255
        WIDTH 2.0
        LINECAP BUTT
        PATTERN 8 12 END
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Line dashed with dashed overlay
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        5 45
        25 50
        45 50
        35 45
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 16.0
        PATTERN 40 20 20 20 10 20 END
      END # STYLE
      STYLE
        COLOR 209 66 0
        WIDTH 12.0
        INITIALGAP 2
        PATTERN 36 24 16 24 6 24 END
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Line overlay - 3
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        5 55
        25 60
        45 60
        35 55
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 17.0
      END # STYLE
      STYLE
        COLOR 209 66 0
        WIDTH 11.0
      END # STYLE
      STYLE
        COLOR 0 0 0
        WIDTH 1.0
      END # STYLE
    END # CLASS
  END # LAYER

  ######## right column ############

  LAYER  # Line - ellipse overlay
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        50 5
        70 10
        90 10
        80 5
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 3.6
      END # STYLE
      STYLE
        COLOR 0 0 0
        SYMBOL "circlef"
        SIZE 10
        GAP 42
      END # STYLE
      STYLE
        COLOR 255 0 0
        SYMBOL "circlef"
        SIZE 3
        GAP 42
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Line - symbol overlay
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        50 15
        70 20
        90 20
        80 15
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 2.8
      END # STYLE
      STYLE
        COLOR 0 0 0
        SYMBOL "vertline"
        SIZE 10.0
        ANGLE 30
        GAP -50
      END # STYLE
      STYLE
        COLOR 255 0 0
        SYMBOL "circlef"
        SIZE 3
        GAP 50
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Line - font overlay
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        50 25
        70 30
        90 30
        80 25
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 6
      END # STYLE
      STYLE
        COLOR 102 0 0
        SYMBOL "P"
        SIZE 20
        GAP -30
      END # STYLE
      STYLE
        COLOR 255 0 0
        SYMBOL "circlef"
        SIZE 3
        GAP 30
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Line - pixmap overlay
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        50 35
        70 40
        90 40
        80 35
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 6
      END # STYLE
      STYLE
        COLOR 102 0 0
        SYMBOL "o-flag-trans"
        SIZE 20
        GAP -30
      END # STYLE
      STYLE
        COLOR 255 0 0
        SYMBOL "circlef"
        SIZE 3
        GAP 30
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Line - pixmap overlay
    STATUS DEFAULT
    TYPE LINE
    FEATURE
      POINTS
        50 45
        70 50
        90 50
        80 45
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        WIDTH 6
      END # STYLE
      STYLE
        COLOR 102 0 0
        SYMBOL "o-flag-trans"
        SIZE 20
        GAP -30
        OFFSET -10 -99
      END # STYLE
      STYLE
        COLOR 255 0 0
        SYMBOL "circlef"
        SIZE 3
        GAP 30
      END # STYLE
    END # CLASS
  END # LAYER

.. index::
   pair: STYLE; LINECAP

`LINECAP`
...........................

By default, all lines (and patterns) will be drawn with rounded ends
(extending the lines slightly beyond their ends).  This effect gets
more obvious the larger the width of the line is.  It is possible to
alter this behaviour using the `LINECAP` parameter of the
:ref:`style`.  `LINECAP` `butt` will give butt ends (stops the line
exactly at the end), with no extension of the line.  `LINECAP`
`square` will give square ends, with an extension of the line.
`LINECAP` `round` is the default.


.. index::
   pair: STYLE; LINEJOIN

`LINEJOIN`
.......................

The different values for the parameter `LINEJOIN` have the following
visual effects.  Default is `round`.  `miter` will follow line borders
until they intersect and fill the resulting area. `none` will render
each segment using linecap `butt`.  The figure below illustrates the
different linejoins.

.. figure:: ../../images/linejoin.jpg
   :align: center

   Different kinds of linejoins

.. index::
   pair: STYLE; LINEJOINMAXSIZE

`LINEJOINMAXSIZE` (only relevant for `LINEJOIN` `miter`\)
...............................................................................

Specify the maximum length of `miter` linejoin factor `m` (see the
figure below).  The value is a multiplication factor (default 3).

.. figure:: ../../images/miter-linejoin.jpg
   :align: center

   Miter linejoin

The max length of the `miter` join is calculated as follows (`d` is the
line width, specified with the `WIDTH` parameter of the :ref:`style`\):

::

   m_max = d * LINEJOINMAXSIZE
   
If *m* > *m_max*, then the connection length will be set to m_max.


.. index::
   pair: STYLE; OFFSET

Use of the `OFFSET` parameter
-----------------------------

In :ref:`style`\, an OFFSET parameter can be set to shift symbols in
the X and Y direction.  The displacement is not influenced by the
direction of the line geometry.  Therefore the point symbols used for
styling are all shifted in the same direction, independent of the
direction of the line (as defined in style number 2 in the map file
example below - red line in the map image).  A positive X value shifts
to the right.  A positive Y value shifts downwards.

To generate lines that are shifted relative to the original lines, -99
has to be used for the Y value of the OFFSET.  Then the X value
defines the distance to the line from the original geometry
(perpendicular to the line).  A positive X value will shift to the
right (when viewed in the direction of the line), a negative X value
will shift to the left.

The example below shows how OFFSET works with the use of -99 (blue and
green lines) and without the use of -99 (red line).  The thin black
line shows the location of the line geometry.


.. figure:: ../../images/symcon-offset.png 
   :align: left                         

   Use of the `OFFSET` parameter with lines - map image

.. table::

  +--------------------------------------------------------------+
  |Use of the `OFFSET` parameter with lines - Map file excerpt   | 
  +==============================================================+
  |.. code-block:: mapfile                                       |
  |                                                     	 |
  |  LAYER  #                                           	 |
  |    STATUS DEFAULT                                   	 |
  |    TYPE LINE                                        	 |
  |    FEATURE                                          	 |
  |      POINTS                                         	 |
  |        20 20                                        	 |
  |        280 160                                      	 |
  |        280 20                                       	 |
  |        160 20                                       	 |
  |        160 60                                       	 |
  |      END # Points                                   	 |
  |    END # Feature                                    	 |
  |    CLASS                                            	 |
  |      STYLE  # no offset                             	 |
  |        COLOR 0 0 0    # black                       	 |
  |        WIDTH 1                                      	 |
  |      END # STYLE                                    	 |
  |      STYLE  # simple offset left and down           	 |
  |        COLOR 255 0 0  # red                         	 |
  |        WIDTH 2                                      	 |
  |        OFFSET -8 12                                 	 |
  |      END # STYLE                                    	 |
  |      STYLE   # left offset rel. to line direction   	 |
  |        COLOR 0 0 255  # blue                        	 |
  |        WIDTH 5                                      	 |
  |        OFFSET -16 -99                               	 |
  |      END # STYLE                                    	 |
  |      STYLE   # right offset rel. to line direction  	 |
  |        COLOR 0 255 0  # green                       	 |
  |        WIDTH 5                                      	 |
  |        OFFSET 16 -99                                	 |
  |      END # STYLE                                    	 |
  |    END # CLASS                                      	 |
  |  END # LAYER                                        	 |
  +--------------------------------------------------------------+

.. index::
   single: Asymmetrical line styling

Asymmetrical line styling with point symbols
--------------------------------------------

Line number 2 and 5 from the bottom in the right column of the
"Construction of Line Symbols" figure are examples of asymmetrical
line styling using a point symbol.  This can be achieved either by
using an OFFSET (with a Y value of -99), or by using `ANCHORPOINT`, as
described in the tricks section below.  Line number 2 from the bottom
can be produced using `ANCHORPOINT` - this is the best method for
placing symbols on lines.  Line number 5 from the bottom is produced
using :ref:`style` `OFFSET`.  As can be seen, the symbols are here
rendered on the offset line, meaning that at sharp bends, some symbols
will be placed far away from the line.


.. index::
   single: Area symbols

Area Symbols
============

Areas (polygons) can be filled with full colour.  Areas can also be
filled with symbols to create for instance hatches and graticules.

The symbols are by default used as tiles, and rendered (without
spacing) one after the other in the x and y direction, filling the
whole polygon.

If the `SIZE` parameter is used in the :ref:`style`, the symbols will
be scaled to the specified height.

The `GAP` parameter of the :ref:`style` can be used to increase the
spacing of the symbols.

The AGG renderer uses anti-aliasing by default, so edge effects around
the symbols can occur.

.. index::
   single: Hatch polygon fill

.. _construction_hatch_fill:

Hatch fill
----------

Simple line hatches (e.g. horizontal, vertical and diagonal) can be
created by filling the polygon with a hatch symbol.

.. figure:: ../../images/symcon-hatch.png
   :align: center

   Hatch examples

The `SIZE` parameter in the :ref:`style` that uses a :ref:`symbol` of
type `hatch` specifies the distance from center to center between the
lines (the default is 1).  The `WIDTH` parameter specifies the width
of the lines in the hatch pattern (default is 1).  The `ANGLE`
parameter specifies the direction of the lines (default is 0 -
horizontal lines).  Since version 6.2, the `PATTERN` parameter can be
used to create hatches with dashed lines.

The figure demonstrates the use of `SIZE` (bottom left); `WIDTH`
(bottom right); `ANGLE`, `PATTERN` and `SIZE` (top left); and overlay
(top right) of hatches.

The code below shows excerpts of the map file that was used to produce
the figure.

First, the :ref:`symbol` definition:

.. code-block:: mapfile       

  SYMBOL
    NAME "hatchsymbol"
    TYPE hatch
  END

Then the :ref:`class` definitions:

.. table:: Hatches

   +---------------------------------------+
   | :ref:`class` definitions              |
   +=======================================+
   |.. code-block:: mapfile                |
   |                                       |
   |  LAYER # hatch                        |
   |   ...                                 |
   |   CLASS                               |
   |    STYLE                              |
   |      SYMBOL "hatchsymbol"             |
   |      COLOR 0 0 0                      |
   |      SIZE 10                          |
   |    END # STYLE                        |
   |   END # CLASS                         |
   |  END # LAYER                          |
   |                                       |
   |  LAYER # hatch with angle and pattern |
   |   ...                                 |
   |   CLASS                               |
   |    STYLE                              |            
   |      SYMBOL "hatchsymbol"             |
   |      COLOR 0 0 0                      |
   |      SIZE 10                          |
   |      WIDTH 3                          |
   |      ANGLE 45                         |
   |      PATTERN 20 10 10 10 END          |
   |    END # STYLE                        |
   |   END # CLASS                         |
   |  END # LAYER                          |
   |                                       |
   |  LAYER # hatch with wide lines        |
   |   ...                                 |
   |   CLASS                               |
   |    STYLE                              |            
   |      SYMBOL "hatchsymbol"             |
   |      COLOR 0 0 0                      |
   |      SIZE 10                          |
   |      WIDTH 5                          |
   |    END # STYLE                        |
   |   END # CLASS                         |
   |  END # LAYER                          |
   |                                       |
   |  LAYER # cross hatch                  |
   |   ...                                 |
   |   CLASS                               |
   |    STYLE                              |            
   |      SYMBOL "hatchsymbol"             |
   |      COLOR 255 153 0                  |
   |      SIZE 10                          |
   |      WIDTH 4                          |
   |    END # STYLE                        |
   |    STYLE                              |            
   |      SYMBOL "hatchsymbol"             |
   |      COLOR 0 0 255                    |
   |      SIZE 20                          |
   |      ANGLE 90                         |
   |    END # STYLE                        |
   |   END # CLASS                         |
   |  END # LAYER                          |
   |                                       |
   +---------------------------------------+


.. index::
   single: Pixmap polygon fill

Polygon fills with symbols of `TYPE` `pixmap`
---------------------------------------------

Polygons can be filled with pixmaps.

.. note::

  If the :ref:`style` `SIZE` parameter is different from the image
  height of the pixmap, there can be rendering artifacts around the
  pixmaps (visible as a grid with the "background" colour).

`Pixmap` symbols can be rotated using the `ANGLE` parameter, but for
polygon fills, this produces strange effects, and is not recommended.

To create complex area symbols, e.g. with defined distances between
single characters or hatches with broad lines, pixmap fill is probably
the best option.  Depending on the desired pattern you have to
generate the raster image with high precision using a graphical
editor. The figure below is an example of how to obtain a regular
allocation of symbols with defined spacing.

.. figure:: ../../images/polygon-symbol-fill.png
   :height: 321
   :width: 357
   :align: center
   
   Raster image for a regular symbol fill

You can use other shapes than circles. B defines the width and H the
height of the raster image. For a regular arrangement of symbols in a
45 degree angle B = H. For symbols, which are regularly arranged in
parallel and without offset between each other one centered symbol
with the same x and y distances to the imageborder is enough.

The following figure shows an example of how you can design a pixmap
to produce a hatch with wide lines.

.. figure:: ../../images/hatch-symbol-fill.png
   :height: 321
   :width: 321
   :align: center

   Raster image for a hatched fill

To create a 45 degree hatch use:

::

   B = H and x = y
   
.. note::

  When using the MapServer legend, observe that each raster `pixmap`
  is displayed only once in the original size in the middle of the
  legend box.

The example below shows some `pixmap` symbols which can be used as
area symbols with transparency. The raster images were created using
FreeHand, finished with Photoshop and exported to PNG with special
attention to the colour palette.

.. table:: Construction of a horizontally arranged area symbol

   +--------------------------------+-------------------------------------------------+
   | :ref:`class` section           | :ref:`symbol` definition                        |
   +================================+=================================================+
   |.. code-block:: mapfile         |.. code-block:: mapfile                          |
   |                                |                                                 |
   |  CLASS                         |  SYMBOL                                         |
   |    STYLE                       |    NAME "in_the_star"                           |
   |      COLOR 255 255 0           |    TYPE PIXMAP                                  |
   |    END                         |    IMAGE "stern.png"                            |
   |    STYLE                       |    TRANSPARENT 8                                |
   |      SYMBOL "in_the_star"      |  END                                            |
   |    END                         |                                                 |
   |    STYLE                       |.. image:: ../../images/star-symbol.png          |
   |      OUTLINECOLOR 0 0 0        |   :align: left                                  |
   |      WIDTH 1                   |                                                 |
   |    END                         |                                                 |
   |  END                           |                                                 |
   +--------------------------------+-------------------------------------------------+

.. figure:: ../../images/horizontal-area-symbol.png
   :align: center

   Polygon fill - regular grid pattern

.. table:: Construction of a diagonally arranged area symbol

   +--------------------------------+-------------------------------------------------+
   | :ref:`class` section           | :ref:`symbol` definition                        |
   +================================+=================================================+
   |.. code-block:: mapfile         |.. code-block:: mapfile                          |
   |                                |                                                 |
   |  CLASS                         |  SYMBOL                                         |
   |    STYLE                       |    NAME "in_point1"                             |
   |      SYMBOL "in_point1"        |    TYPE PIXMAP                                  |
   |    END                         |    IMAGE "flaeche1_1.png"                       |
   |    STYLE                       |    TRANSPARENT 13                               |
   |      OUTLINECOLOR 0 0 0        |  END                                            |
   |      WIDTH 1                   |                                                 |
   |    END                         |.. image:: ../../images/dot-symbol.png           |
   |  END                           |   :align: left                                  |
   +--------------------------------+-------------------------------------------------+

.. figure:: ../../images/diagonal-area-symbol.png
   :align: center

   Polygon fill - diagonal pattern

.. table:: Construction of a hatch

   +--------------------------------+-------------------------------------------------+
   | :ref:`class` section           | :ref:`symbol` definition                        |
   +================================+=================================================+
   |.. code-block:: mapfile         |.. code-block:: mapfile                          |
   |                                |                                                 |
   |  CLASS                         |  SYMBOL                                         |
   |    STYLE                       |    NAME "in_hatch"                              |
   |      COLOR 255 255 0           |    TYPE PIXMAP                                  |
   |    END                         |    IMAGE "schraffur.png"                        |
   |    STYLE                       |    TRANSPARENT 2                                |
   |      SYMBOL "in_hatch"         |  END                                            |
   |    END                         |                                                 |
   |    STYLE                       |.. image:: ../../images/hatch.png                |
   |      OUTLINECOLOR 0 0 0        |   :align: left                                  |
   |      WIDTH 1                   |                                                 |
   |    END                         |                                                 |
   |  END                           |                                                 |
   +--------------------------------+-------------------------------------------------+

.. figure:: ../../images/hatch-symbol.png
   :align: center

   Polygon fill - hatch

.. index::
   single: Vector polygon fill

Polygon fills with symbols of `TYPE` `vector`
---------------------------------------------

Polygons can be filled with symbols of `TYPE` `vector`.  As for the
other symbol fills, the pattern will be generated by using the
specified symbol for the tiles.  The bounding box of the symbol is
used when tiling.

Creating vector symbols for polygon fills is done in much the same
way as for pixmap symbols.  Precision is necessary to get nice
symmetrical symbols.

The upper left corner of the bounding box of a symbol of `TYPE`
`vector` is always (0, 0) in the symbol's coordinate system.  The
lower right corner of the bounding box is determined by the maximum x
and y values of the symbol definition (`POINTS` parameter).  The fact
that the upper left corner always is at (0,0) makes it convenient to
construct symbols such as the dash signature found as number two from
the bottom in the centre column of the example below.

Both polygon (`FILLED` `true`) and line (`FILLED` `false`) vector
symbols can be used.  For line symbols, the `WIDTH` parameter of the
:ref:`style` will give the line width and the `SIZE` parameter will
specify the height of the symbol.

.. note::

  For vector line symbols (`FILL` off), if a width greater than 1
  is specified, the lines will grow to extend outside the original
  bounding box of the symbol.  The parts that are outside of the
  bounding box will be cut away.

:ref:`style` ANGLE can be used for polygon fills, but will only rotate
each individual symbol, not the pattern as a whole.  It is therefore
quite demanding to generate rotated patterns.

Below you will find some examples of vector symbols used for polygon
fills.  The polygon fill is accompanied by the vector symbol used
for the fill.  The center of the vector symbol is indicated with a
red dot.

.. figure:: ../../images/symcon-polygonvector.png
   :align: center
   :width: 600
   :height: 420

   Polygon fills - vector

Excerpts from the map file for the polygon fill vector examples above
.....................................................................

First, the :ref:`layer`\s

.. code-block:: mapfile

  LAYER  # chess board
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        5 5
        5 25
        45 25
        45 5
        5 5
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "chess"
        COLOR 0 0 0
        SIZE 35
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # x - line
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        5 30
        5 50
        45 50
        45 30
        5 30
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "x-line"
        COLOR 0 0 0
        WIDTH 5
        SIZE 35
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # v polygon
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        5 55
        5 75
        45 75
        45 55
        5 55
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "v-poly"
        COLOR 0 0 0
        SIZE 35
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # Circles
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        5 80
        5 100
        45 100
        45 80
        5 80
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "circlef"
        COLOR 0 0 0
        SIZE 20
        GAP 25
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # x polygon
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        55 5
        55 25
        95 25
        95 5
        55 5
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 0
        SYMBOL "x-poly-fill"
        SIZE 35
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # indistinct marsh
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        55 30
        55 50
        95 50
        95 30
        55 30
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 255
        SYMBOL "ind_marsh_poly"
        SIZE 25
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # diagonal circles
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        55 55
        55 75
        95 75
        95 55
        55 55
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR  255 230 51
        SYMBOL "diag_dots"
        SIZE 30
      END # STYLE
    END # CLASS
  END # LAYER


  LAYER  # diagonal holes in yellow
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        55 80
        55 100
        95 100
        95 80
        55 80
      END # Points
    END # Feature
    CLASS
      STYLE
        SYMBOL "diag_holes"
        SIZE 30
        COLOR 250 220 102
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # v line + circle
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        100 5
        100 25
        140 25
        140 5
        100 5
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 255 0 0
        SYMBOL "circlef"
        SIZE 30
        GAP 45
      END # STYLE
      STYLE
        COLOR 0 0 0
        SYMBOL "v-line"
        LINEJOIN miter
        LINECAP butt
        SIZE 35
        WIDTH 10
        GAP 45
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # indistinct marsh + diagonal holes in yellow
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        100 30
        100 50
        140 50
        140 30
        100 30
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 255
        SYMBOL "ind_marsh_poly"
        SIZE 25
      END # STYLE
      STYLE
        SYMBOL "diag_holes"
        SIZE 30
        COLOR 250 220 0
        OPACITY 75
      END # STYLE
    END # CLASS
  END # LAYER

  LAYER  # x line + circle
    STATUS DEFAULT
    TYPE POLYGON
    FEATURE
      POINTS
        100 55
        100 75
        140 75
        140 55
        100 55
      END # Points
    END # Feature
    CLASS
      STYLE
        COLOR 0 0 255
        SYMBOL "circle"
        WIDTH 5
        SIZE 20
        GAP 30
      END # STYLE
      STYLE
        COLOR 0 204 0
        SYMBOL "x-line"
        SIZE 10
        WIDTH 3
        GAP 30
      END # STYLE
    END # CLASS
  END # LAYER

Then the :ref:`symbol`\s:

.. code-block:: mapfile

  SYMBOL
    NAME "circlef"
    TYPE ellipse
    FILLED true
    POINTS
      10 10
    END # POINTS
  END # SYMBOL

  SYMBOL
    NAME "circle"
    TYPE ellipse
    FILLED false
    POINTS
      10 10
    END # POINTS
  END # SYMBOL

  SYMBOL
    NAME "v-line"
    TYPE vector
    POINTS
      0  0
      5 10
      10 0
    END
  END

  SYMBOL
    NAME "v-poly"
    TYPE vector
    FILLED false
    FILLED true
    POINTS
      0  0
      3.5 8
      7 0
      5.2 0
      3.5 4
      1.8 0
      0 0
    END
  END

  SYMBOL
    NAME "x-line"
    TYPE vector
    POINTS
      0 0
      1 1
      -99 -99
      0 1
      1 0
    END
  END

  SYMBOL
    NAME "chess"
    TYPE vector
    FILLED true
    POINTS
      0 0
      10 0
      10 10
      0 10
      0 0
      -99 -99
      10 10
      20 10
      20 20
      10 20
      10 10
    END
  END

  SYMBOL
    NAME "x-poly-fill"
    TYPE vector
    FILLED true
    POINTS
      0     1.131
      0     0
      1.131 0
      4.566 3.434
      8     0
      9.131 0
      9.131 1.131
      5.697 4.566
      9.131 8
      9.131 9.131
      8     9.131
      4.566 5.697
      1.131 9.131
      0     9.131
      0     8
      3.434 4.566 
      0     1.131
    END # POINTS
  END # SYMBOL

  SYMBOL
    NAME "ind_marsh_poly"
    TYPE vector
    FILLED true
    POINTS
      # Half line
      0 2
      4.5 2
      4.5 3
      0 3
      0 2
      -99 -99
      # Half line
      7 2
      11.5 2
      11.5 3
      7 3
      7 2
      -99 -99
      # Hole line
      1.25 5
      10.25 5
      10.25 6
      1.25 6
      1.25 5
    END  
  END

  SYMBOL
    NAME "diag_dots"
    TYPE vector
    FILLED true
    POINTS
      # Central circle:
      0.7450    0.4500
      0.7365    0.5147
      0.7115    0.5750
      0.6718    0.6268
      0.6200    0.6665
      0.5597    0.6915
      0.4950    0.7000
      0.4303    0.6915
      0.3700    0.6665
      0.3182    0.6268
      0.2785    0.5750
      0.2535    0.5147
      0.2450    0.4500
      0.2535    0.3853
      0.2785    0.3250
      0.3182    0.2732
      0.3700    0.2335
      0.4303    0.2085
      0.4950    0.2000
      0.5597    0.2085
      0.6200    0.2335
      0.6718    0.2732
      0.7115    0.3250
      0.7365    0.3853
      0.7450    0.4500
      -99 -99
      0.25      0.0
      0.2415    0.0647
      0.2165    0.1250
      0.1768    0.1768
      0.1250    0.2165
      0.0647    0.2415
      0.0       0.25
      0.0       0.0
      0.25      0.0
      -99 -99
      1 0.25
      0.9252    0.2415
      0.8649    0.2165
      0.8132    0.1768
      0.7734    0.1250
      0.7485    0.0647
      0.74      0.0
      1 0.0
      1 0.25
      -99 -99
      0.74      1
      0.7485    0.9252
      0.7734    0.8649
      0.8132    0.8132
      0.8649    0.7734
      0.9252    0.7485
      1 0.74
      1 1
      0.74      1
      -99 -99
      0.0       0.74
      0.0647    0.7485
      0.1250    0.7734
      0.1768    0.8132
      0.2165    0.8649
      0.2415    0.9252
      0.25      1
      0.0       1
      0.0       0.74
    END  
  END

  SYMBOL
    NAME "diag_holes"
    TYPE vector
    FILLED true
    POINTS
      0.0     0.0
      # Left half circle
      0.0       0.24
      0.0647    0.2485
      0.1250    0.2734
      0.1768    0.3132
      0.2165    0.3649
      0.2415    0.4252
      0.25      0.5
      0.2415    0.5647
      0.2165    0.6250
      0.1768    0.6768
      0.1250    0.7165
      0.0647    0.7415
      0.0       0.75
    
      0.0       1.0
      # Bottom half circle
      0.24      1
      0.2485    0.9252
      0.2734    0.8649
      0.3132    0.8132
      0.3649    0.7734
      0.4252    0.7485
      0.5       0.74
      0.5647    0.7485
      0.6250    0.7734
      0.6768    0.8132
      0.7165    0.8649
      0.7415    0.9252
      0.75      1
    
      1.0     1.0
      # Right half circle
      1 0.75
      0.9252    0.7415
      0.8649    0.7165
      0.8132    0.6768
      0.7734    0.6250
      0.7485    0.5647
      0.74      0.5
      0.7485    0.4252
      0.7734    0.3649
      0.8132    0.3132
      0.8649    0.2734
      0.9252    0.2485
      1 0.24
    
      1.0     0.0
      # Top half circle
      0.75      0.0
      0.7415    0.0647
      0.7165    0.1250
      0.6768    0.1768
      0.6250    0.2165
      0.5647    0.2415
      0.5       0.25
      0.4252    0.2415
      0.3649    0.2165
      0.3132    0.1768
      0.2734    0.1250
      0.2485    0.0647
      0.24      0.0
    
      0.0     0.0
    END
  END

.. index::
   single: Polygon outlines

Polygon outlines
----------------

Polygon outlines can be created by using `OUTLINECOLOR` in the
:ref:`STYLE`.  `WIDTH` specifies the width of the outline.

.. code-block:: mapfile

   STYLE
     OUTLINECOLOR 0 255 0
     WIDTH 3
   END # STYLE

Dashed polygon outlines can be achieved by using `OUTLINECOLOR`,
`WIDTH` and `PATTERN` (together with `LINECAP`, `LINEJOIN` and
`LINEJOINMAXSIZE`).  For more information on the use of `PATTERN`, see
:ref:`construction_pattern_gap`.

.. code-block:: mapfile

   STYLE
     OUTLINECOLOR 0 255 0
     WIDTH 3
     PATTERN
       10 5
     END # PATTERN
     LINECAP BUTT
   END # STYLE

For some symbol types, it is even possible to style polygon outlines
using `OUTLINECOLOR`, `SYMBOL` and `GAP`.

.. code-block:: mapfile

   STYLE
     OUTLINECOLOR 0 255 0
     SYMBOL 'circle'
     SIZE 5
     GAP 15
   END # STYLE


Examples (MapServer  4)
========================

The examples in this section were made for MapServer 4.

.. note::

  Many of these symbols will not work with later versions of
  MapServer , but they contain a lot of useful symbol definitions and
  are therefore provided as reference.

The symbols were created with *map* files and *symbol* files
(`download_old_symbols`_). If you want to use these MAP files please
note, that your MapServer must at least be able to handle 50
symbols. Otherwise you will get an error while loading the *symbol*
files.

.. _`download_old_symbols`: http://www.mapmedia.de/fileadmin/user_upload/dokumente/umn_signaturen_howto/vortrag_demo.zip


Basic Symbols
-------------

.. image:: ../../images/point-symbol-examples.png

.. image:: ../../images/line-symbol-examples.png

.. image:: ../../images/pattern-symbol-examples.png

Complex Symbols
---------------

.. image:: ../../images/point-symbol-complex.png

.. image:: ../../images/line-symbol-complex.png

.. image:: ../../images/pattern-symbol-complex.png




Tricks
======

.. index::
   single: Symbol center

Changing the center of a point symbol
-------------------------------------

MapServer  does all transformations (offset, rotation) with respect to
the symbol anchor point.  By default, the anchor point is calculated
from the symbol's bounding box.  In some cases it can be useful to
change the anchor point of a symbol.  Since version 6.2, this can be
done using the :ref:`symbol` `ANCHORPOINT`.

Here are some examples of what can be achieved by using the
`ANCHORPOINT` mechanisms for point symbols and decorated lines.  There
are three examples in the illustration, and each example shows the
result with and without the use of `ANCHORPOINT`.  At the top, arrows
are added to lines using `GEOMTRANSFORM` start / end.  In the middle,
tags are added to lines using `GAP` and `ANGLE`.  At the bottom, a
point symbol is shifted and rotated.  The red dots represent the
center points, and the blue dots the offsets.

.. figure:: ../../images/symcon-shifttrick.png
   :align: center

   Shifting trick

Below you will find three tables that contain the :ref:`symbol`\s and
the :ref:`style` mechanisms that were used to generate the shifted
symbols in the illustration.

.. table:: Symbol tricks - shift - arrows

  +--------------------------------+-------------------------------------------------+
  | :ref:`symbol`\s                | :ref:`layer` :ref:`style`\s                     |
  +================================+=================================================+
  |.. code-block:: mapfile         |.. code-block:: mapfile                          |
  |                                |                                                 |
  |  SYMBOL                        |  LAYER  # Line                                  |
  |    NAME "arrow-start"          |    STATUS DEFAULT                               |
  |    TYPE vector                 |    TYPE LINE                                    |
  |    FILLED true                 |    FEATURE                                      |
  |    POINTS                      |      POINTS                                     |
  |      0 0.4                     |        20 80                                    |
  |      3 0.4                     |        40 85                                    |
  |      3 0                       |        60 85                                    |
  |      5 0.8                     |        70 80                                    |
  |      3 1.6                     |      END # Points                               |
  |      3 1.2                     |    END # Feature                                |
  |      0 1.2                     |    CLASS                                        |
  |      0 0.4                     |      STYLE                                      |
  |    END # POINTS                |        COLOR 0 0 0                              |
  |    ANCHORPOINT 0 0.5           |        WIDTH 15                                 |
  |  END # SYMBOL                  |        LINECAP butt                             |
  |  SYMBOL                        |      END # STYLE                                |
  |    NAME "arrow-end"            |      STYLE                                      |
  |    TYPE vector                 |        GEOMTRANSFORM "start"                    |
  |    FILLED true                 |        COLOR 0 255 0                            |
  |    POINTS                      |        SYMBOL "arrow-start"                     |
  |      0 0.4                     |        SIZE 15.0                                |
  |      3 0.4                     |        ANGLE AUTO                               |
  |      3 0                       |      END # STYLE                                |
  |      5 0.8                     |      STYLE                                      |
  |      3 1.6                     |        GEOMTRANSFORM "start"                    |
  |      3 1.2                     |        COLOR 255 0 0                            |
  |      0 1.2                     |        SYMBOL "circlef"                         |
  |      0 0.4                     |        SIZE 3                                   |
  |    END # POINTS                |      END # STYLE                                |
  |    ANCHORPOINT 1 0.5           |      STYLE                                      |
  |  END # SYMBOL                  |        GEOMTRANSFORM "end"                      |
  |                                |       COLOR 0 255 0                             |
  |                                |        SYMBOL "arrow-end"                       |
  |                                |        SIZE 15.0                                |
  |                                |        ANGLE AUTO                               |
  |                                |      END # STYLE                                |
  |                                |      STYLE                                      |
  |                                |        GEOMTRANSFORM "end"                      |
  |                                |        COLOR 255 0 0                            |
  |                                |        SYMBOL "circlef"                         |
  |                                |        SIZE 3                                   |
  |                                |      END # STYLE                                |
  |                                |    END # CLASS                                  |
  |                                |  END # LAYER                                    |
  +--------------------------------+-------------------------------------------------+

.. table:: Symbol tricks - shift - asymmetrical tags

  +--------------------------------+-------------------------------------------------+
  | :ref:`symbol`\s                | :ref:`layer` :ref:`style`\s                     |
  +================================+=================================================+
  |.. code-block:: mapfile         |.. code-block:: mapfile                          |
  |                                |                                                 |
  |  SYMBOL                        |  LAYER  # Line - symbol overlay                 |
  |    NAME "vert-line-shift"      |    STATUS DEFAULT                               |
  |    TYPE vector                 |    TYPE LINE                                    |
  |    POINTS                      |    FEATURE                                      |
  |      0 0                       |      POINTS                                     |
  |      0 10                      |        20 50                                    |
  |    END # POINTS                |        40 55                                    |
  |    ANCHORPOINT 0.5 0           |        60 55                                    |
  |  END # SYMBOL                  |        70 50                                    |
  |                                |      END # Points                               |
  |  SYMBOL                        |    END # Feature                                |
  |    NAME "vert-line"            |    CLASS                                        |
  |    TYPE vector                 |      STYLE                                      |
  |    POINTS                      |        COLOR 0 0 0                              |
  |      0 0                       |        WIDTH 4                                  |
  |      0 10                      |      END # STYLE                                |
  |    END # POINTS                |      STYLE                                      |
  |  END # SYMBOL                  |        COLOR 0 0 0                              |
  |                                |        SYMBOL "vert-line-shift"                 |
  |                                |        SIZE 20.0                                |
  |                                |        WIDTH 3                                  |
  |                                |        ANGLE 30                                 |
  |                                |        GAP -50                                  |
  |                                |      END # STYLE                                |
  |                                |      STYLE                                      |
  |                                |        COLOR 255 0 0                            |
  |                                |        SYMBOL "circlef"                         |
  |                                |        SIZE 3                                   |
  |                                |        GAP 50                                   |
  |                                |      END # STYLE                                |
  |                                |    END # CLASS                                  |
  |                                |  END # LAYER                                    |
  +--------------------------------+-------------------------------------------------+

.. table:: Symbol tricks.  Unshifted symbol (top) and shifted symbol

  +--------------------------------+
  | :ref:`symbol`\s                |
  +================================+
  |.. code-block:: mapfile         |
  |                                |
  |  SYMBOL                        |
  |    NAME "v-line"               |
  |    TYPE vector                 |
  |    POINTS                      |
  |      0  0                      |
  |      5  10                     |
  |      10 0                      |
  |    END # POINTS                |
  |  END # SYMBOL                  |
  |                                |
  |  SYMBOL                        |
  |    NAME "v-line-shift"         |
  |    TYPE vector                 |
  |    POINTS                      |
  |      0   0                     |
  |      5  10                     |
  |      10  0                     |
  |    END # POINTS                |
  |    ANCHORPOINT 0.5 0           |
  |  END # SYMBOL                  |
  +--------------------------------+


Mapfile changes related to symbols
==================================

Version 6.2
-----------

The `ANCHORPOINT` :ref:`symbol` parameter was added.

The `INITIALGAP` :ref:`style` parameter was added.

The `GAP` :ref:`style` parameter's behaviour was modified to specify
center to center spacing.

`PATTERN` support for symbols of `TYPE` `hatch`.

Version 6.0
-----------

Parameters related to styling was moved from the :ref:`symbol` element
to the :ref:`style` element of :ref:`class` (in :ref:`layer`\):

  `PATTERN` (introduced in 5.0, previously called `STYLE`), `GAP`,
  `LINECAP`, `LINEJOIN`, `LINEJOINMAXSIZE`

The :ref:`symbol` `TYPE` `cartoline` is no longer needed, and
therefore not available in version 6.0.


Current Problems / Open Issues
==============================

`GAP` - ``PATTERN`` incompatibility
-----------------------------------

Creating advanced line symbols involving dashed lines is difficult
due to the incompatibility of the dashed line mechanisms (`PATTERN`)
and the symbol on line placement mechanisms (`GAP`).  A solution could
be to allow `GAP` to be a list instead of a single number (perhaps
renaming to GAPS or DISTANCES), but it would also be necessary to
introduce a new parameter to specify the distance to the first symbol
on the line (INTIALGAP has been implemented in the development
version - 6.2).

`GAP` does not support two dimensions (relevant for polygon fills), so
the same gap will have to be used for for the x and the y directions.
The introduction of new parameters - GAPX and GAPY could be a solution
to this.

The End
=========

We hope that this document will help you to present your data in a
cartographically nice manner with MapServer and explains some basics
and possibilities of the concept of MapServer as well as some
weaknesses. It would be great to put together a cartographical symbols
library for the profit of everyone.  This especially concerns truetype
fonts, which have been developed for some projects and contain some
typical signatures for cartographical needs.

You can also view the
`discussion paper for the improvement of the MapServer Graphic-Kernel`_
(German only).

.. _`Discussion paper for the improvement of the MapServer Graphic-Kernel`: http://www.mapmedia.de/fileadmin/user_upload/dokumente/umn_signaturen_howto/DiskussionsPaper-UMNGraphikKernel.pdf
