| Author: | Peter Freimuth |
|---|---|
| Contact: | pf at mapmedia.de |
| Author: | Arnulf Christl |
| Contact: | arnulf.christl at wheregroup.com |
| Revision: | $Revision: 8484 $ |
| Date: | $Date: 2009-01-31 07:38:27 -0800 (Sat, 31 Jan 2009) $ |
Table of Contents
This Document refers to the syntax of MAP and symbolfiles for MapServer 4.6. It is based upon 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.
At the end of this document you will find a link to a paper discussing further development of the UMN MapServer software regarding the cartographic rendering capabilities. We will try to get around to also translating it to English asap. We welcome everybody who is interested in this subject to participate in the discussion. As a result of this discussion we want to put together a list with change requests and new requirements for UMN MapServer.
Cartographic characters can be distinguished as point, line and area symbols. These symbols may vary depending on their special attributes (variables). Bertin (1974) created a clear and logical symbol scheme in which symbols can be varied referring to graphical variables. The following variables are 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 1-pixel wide frame which we call OUTLINE.
Complex cartographic effects can be achieved by rendering the same vector data with different attributes, sizes and colors on top of each other. This is an easy workaround to creating complex signatures but obviously it will also reflect on the performance of the application. Every rendering process of the same geometries will take up additional processor time.
As an example consider displaying a highway with a black border line, two yellow lanes and a red center line. You can achieve this by rendering the same highway geometry three times on top of each other. The lowest (in drawing order) is rendered as a broad black line with a width of 9 pixel. The second level lines are rendered in yellow color with a width of 7 pixel. The topmost layer is displayed as the red center line with a width of 3 pixel in size. That way each yellow colored lane will have a width of (7-1)/2 = 3 pixel.
This can be a solution for many kinds of cartographic questions, a combination of different geometry types is also possible. First define a polygon layer as TYPE LINE. It will frame the polygons with a line signature. On top of this include the same geometry a second time but now as TYPE POLYGON with a symbol filling the polygon. This way half of the underlying outline is covered by the polygon with the fill symbol. The clipping effect renders an asymmetric line symbol. To present the outline without clipping just reorder the layers and put the outline presentation on top of the layer with the fill symbol.
Each step growing more complex, yet another way to construct asymmetric line signatures for framed faces 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. A new line symbol for these geometries can use the OFFSET parameter with the y-value set to -99. This is where current development stops short this functions has not been developed further. (Anybody need this feature?). Buffer areas may provide ideal geometry for ambitious cartography, this should be possible as soon as the GEOS library is implemented in MapServer. Until then using PostGIS helps to solve a lot of problems.
There are two basically different ways to handle the display size of symbols and cartographic elements in a map at different scales. The size of cartographic objects is either set in screen pixel or in real world units.
UMN MapServer implements the screen pixel size type for displaying cartographic elements. Additionally the size of cartographic elements can be tied to defined scales, such that the symbols “grow” and “shrink” with the scale. The involved parameters include SYMBOLSCALE, MINSIZE and MAXSIZE settings in the MAP file.
All symbol and style definitions referenced in the following section are contained in the archive at the end of this document.
The following figure shows the theoretical structure of cartographic symbols, which are also used in UMN MapServer:
Figure1: Structure of Cartographic Symbols`
In a MapServer application symbol parameters are taken from the MAP and symbol file as follows:
MAP file:
Symbol file:
The following figure shows the interaction of these elements and explains the configuration in the MAP and the SYMBOL file sections necessary for rendering cartographic symbols in the map:
Figure2: Schema showing interaction of MAP and SYMBOL file
The basic graphic elements in a symbolfile are made up of vectors, truetype fonts, raster images or cartolines and are defined by the TYPE-parameter. The following section explains all four types of basic graphic elements and how they can be combined to create complex cartographic symbols.
The parameter SYMBOLSCALE in the LAYER section specifies the scale number at which the symbol or text label is displayed in exactly the pixel size defined by the SIZE parameter. Observe that the SIZE parameter is tightly connected to the SYMBOLSCALE parameter. The parameters MAXSIZE and MINSIZE inside the STYLE block limit the rendering of symbols to the maximum and minimum scale specified here. Both the minimum reasonable display size for symbols and the minimum of space required to display a symbol within a polygon should be observed.
Symbols of TYPE PIXMAP will not be scaled if used as line and polygon fills! In addition PIXMAPs will not display nicely when rescaled due to roundings caused by the integer arithmetics of the GD. The basic elements of a composite cartographic symbol may change their relative positions to each other, especially at very small scales (large number). They can also slightly change their form when they are displayed as tiny little images.
Furthermore the gaps of line symbols (the pattern itself) will not be scaled. The gaps stay fixed whereas the width is scaled. This can result in strange effects seeming to change the original pattern.
There is no possibility to separately define the display intervals (gaps) with MINSCALE and MAXSCALE in the STYLE-section (anybody need this?), so this tuning has to be solved at the LAYER level. TO do this create several layers with the same geometries for different scale levels and specify the appropriate sizes accordingly.
Always observe that cartographic symbols depend a lot on the scale! So be careful with the interaction of content, symbols and scale when creating projects. All three parameters heavily interact and have to be coordinated to produce a good map.
The TYPE VECTOR defines the form of a symbol by setting x- and y-values in a local caresian coordinate system with the origin at the upper left corner. Each symbol is parenthesized by the tags POINTS and END. The maximum number of points can be increased by changing the parameter MS_MAXVECTORPOINTS in the file mapsymbols.h. The current default is 100. Note that by setting the end point equal to the start point you obtain a closed form (polygon). To use the coordinates -99 -99 to break a line, the following point will not be connected by a line with the preceding one.
When creating symbols of the TYPE VECTOR you should observe some style guidelines. Avoid downtilted lines in area symbols, as they will lead to heavy aliasing effects. Furthermore you should not go below a useful minimum size, which is relevant for all types of symbols. Keep in mind that the points in the local coordinate system are rendered as pixel images, thus only integer values make any sense. Every symbol of the TYPE VECTOR is first rendered as a pixel image and then added to the geometry. This is the basic principle of the GD graphic kernel. PIXMAP symbols may be used directly for drawing.
To create circles and ellipses use the TYPE ELLIPSE. These forms are created by setting the x and y values as the radius of the circle or ellipse inside POINTS and END.
The following figure shows how to combine several basic elements to create a new point symbol. The combination is achieved by adding several STYLEs within one layer. Each basic element references one item of the SYMBOL file, which are centered and overlayed when rendered.
Notice that the SIZE parameter in the STYLE section only refers to the width of the symbol (size in the y-direction). An edgewise rectangle will thus display smaller than a lying rectangle, although both have the same SIZE parameter. When combining several point elements on top of each other, they will not always be centered correctly. We have not found a regular rule yet. We can only recommend to set an even-numbered SIZE for combined elements. Combining elements with even and odd numbered SIZE parameters seem to have larger irregularities.
Figure3: Construction of Point Symbols
For displaying line geometries most often a simple point symbol (filled circle / SYMBOL 0) is used. This point is painted for each pixel along the line, giving a continuous line with rounded ends. To create line patterns use the STYLE section of the SYMBOL file (do not confuse this with the STYLE-section of the CLASS object). Here you state how many pixel of the section shall be displayed and how many are left blank. This pattern will be repeated as many times as that pattern will fit into the element. The following figure shows this effect. Unfortunately up to now no OFFSET (start gap) can be defined to create asymetric patterns. (anybody need this?)
Figure4: Construction of Line Symbols
When using the point character for rendering all line features with have rounded ends. This can be a desired effect or not, it gets more obvious the larger the width of line is set. Alternatively a rectangle can be used to generate a line. It can be enhanced with a STYLE-parameter to create line patterns (see below).
Table 1. Creating a Symbol to Display Railways
| CLASS-section from the Mapfile | Character from the Symbolfile |
|---|---|
CLASS
STYLE
COLOR 102 102 102
SYMBOL 'point'
SIZE 4
END
STYLE
COLOR 255 255 255
SYMBOL 'rectangle-train'
SIZE 2
END
END
|
SYMBOL
NAME 'point'
TYPE ELLIPSE
POINTS
1 1
END
FILLED TRUE
END
SYMBOL
NAME 'rectangle-train'
TYPE VECTOR
POINTS
0 0
0 0.6
1 0.6
1 0
0 0
END
FILLED TRUE
STYLE
8 12 8 12
END
END
|
The STYLE parameter can be used for elements of the SYMBOL file with the TYPE VECTOR, ELLIPSE, CARTOLINE and PIXMAP. It will define the number of intervals in which the symbol is rendered. This can be done using the GAP parameter with TRUETYPE symbols (see below).
When combining of several symbols on a line, they will be positioned on the baseline which is defined by the geometry of the object in pixel coordinates. Again we face the problem of centering. In most cases MapServer corectly centers symbols. The combination of a line displayed in 6 pixel width and overlayed with 4 pixel width results in a line symbol with a 1 pixel border. If the cartographic symbol is to contain a centered line with a width of 1 pixel, then the SIZE parameters have to be reconfiguredfor example to 7 and a 5 pixel. As a rule of thumb only combine even numbered or odd numbered SIZE parameters (see above).
In the STYLE section of the MAP file an OFFSET parameter can be set to shift symbols or characters in the x and y direction. Unfortunately the displacement is set relative to the map border, not the inclination of the line gemoetry (with the exception: OFFSET n -99). Therefore the iterated characters are all shifted in the same direction, independent of which direction the line takes (see Example 2). To generate asymmetrical line symbols apply -99 for the y value of the OFFSET. Then the x-value defines the distance from a parallel to the original geometry, for which the selected symbol is used (what a pity this wasn’t documented anywhere!).
Table 2: Use of the OFFSET parameter with line signatures
| CLASS-section from the Mapfile | Character from the Symbolfile | CLASS-Section from the Mapfile | Character from the Symbolfile |
|---|---|---|---|
CLASS
STYLE
SIZE 1
COLOR 0 0 0
END
STYLE
SYMBOL "circle"
SIZE 7
COLOR 0 0 255
OFFSET 8 -8
END
END
|
SYMBOL
NAME "circle"
TYPE ELLIPSE
POINTS
1 1
END
STYLE
1 10 1 10
END
END
|
CLASS
STYLE
SIZE 1
COLOR 0 0 0
ANTIALIAS
END
STYLE
SYMBOL "circle"
SIZE 12
COLOR 0 0 255
OFFSET -8 -99
ANTIALIAS TRUE
END
END
|
SYMBOL
NAME "circle"
TYPE ELLIPSE
POINTS
1 1
END
STYLE
1 10 1 10
END
END
|
Areas (polygons) can be filled with elements of the SYMBOL file to create e.g. hatches and graticules. These are by default rendered without spacing one after the other in x and y direction and fill out the whole polygon. Simple line hatches (e.g. horizontal, vertical and diagonal) can be created by filling the polygon with a line symbol from the SYMBOL file (see example 5).
The SIZE parameter in the STYLE section for line hatches only specifies the distance between the lines and not their width. Thus in these hatches all lines will always have a width of 1 pixel. Unfortunately there is no additional parameter to define the line width (Anybody need this feature?). Notice that the SIZE parameter is interpreted by MapServer differently for horizontal and vertical lines. Vertical lines with a SIZE parameter of 8 pixel result in a distance of 8 pixel between the lines. Horizontal lines with the same SIZE parameter are instead renderes with a much smaller gap (see example 5). For creating cross hatches composed of vertical and horizontal lines the best method is to use a simple cross from the SYMBOL file. Polygons can also be filled with other POINT elements to obtain special patterns (e.g. with circles or triangles).
Table 3: Construction of a cross hatch with different line distances
| CLASS-Section from the Mapfile | Character from the Symbolfile |
|---|---|
CLASS
STYLE
SYMBOL "line-vertical"
SIZE 8
COLOR 255 102 51
OUTLINECOLOR 0 0 0
END
STYLE
SYMBOL "line-horizontal"
SIZE 8
COLOR 204 102 51
OUTLINECOLOR 0 0 0
END
END
|
SYMBOL
NAME "line-vertical"
TYPE vector
POINTS
0.5 0
0.5 1
END
END
SYMBOL
NAME "line-horizontal"
TYPE vector
POINTS
0 0.5
1 0.5
END
END
|
Symbols of the TYPE PIXMAP are simply small raster images. The name of the raster images are specified in the SYMBOL file with the parameter IMAGE. MapServer supports the raster formats GIF and PNG. Observe the color depth of the images and avoid using 24 bit PNG symbols displayed in 8 bit mode as this may cause unexpected color leaps. When using raster images the color cannot be modified in the SMBOL file subsequently. But you can specify a color with the TRANPARENT parameter which will not be displayed - i.e. it will be transparent. As a result all underlying objects and colors are visible.
The SIZE parameter defines the size of PIXMAP symbols when used as point symbols. Observe that the pixel structure will show when the SIZE grows too large. Prevent this from happening by setting a MAXSIZE parameter. When using PIXMAPS as line symbols or as fill symbols for polygons they will not be resized but are displayed in the original size. So the use of PIXMAP STYLE objects for signatures with a high need of scaling is rather limited.
PIXMAP symbols are always rendered respective to the map border and will not follow the inclination of a line or polygon outline. Only truetype font symbols can follow an inclined line geometry, although with some defects (see below).
To create more complex area symbols, e.g. with defined distances between single characters or hatches with broad lines, raster images are probably the most suitable objects. Depending on the desired pattern you have to generate the raster image with high precision using a graphic editor. To obtain a regular allocation of symbols with defined spacing you could use the raster image as shown in Figure1.
Figure5: Raster image for a regular polygon symbol fill
Figure6: Raster image for a hatched fill
Instead of using circles you can use different characters. B defines the width and H the height of the raster image. For a regular arrangment 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 same x and y distances to the imageborder is enough. A regular hatch with wider lines can be created by using the raster image in fig. 2. To create a 45 degree hatch use:
B = H and x = y
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.
See the example below of 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 regarding the color palette. Observe that you have to specify a COLOR in the STYLE section of the CLASS to display raster PIXMAPS although it has no influence on the output and color of the image.
Table 4: Construction of a horizontally arranged area symbol
| CLASS-Section from the Mapfile | Character from the Symbolfile |
|---|---|
CLASS
STYLE
COLOR 255 255 0
END
STYLE
SYMBOL "in_the_star"
COLOR 0 0 0
OUTLINECOLOR 0 0 0
END
END
|
SYMBOL
NAME "in_the_star"
TYPE PIXMAP
IMAGE "stern.png"
TRANSPARENT 8
END
|
Table 5: Construction of a diagonally arranged area symbol
| CLASS-Section from the Mapfile | Character from the Symbolfile |
|---|---|
CLASS
STYLE
SYMBOL "in_point1"
COLOR 0 0 0
OUTLINECOLOR 0 0 0
END
END
|
SYMBOL
NAME "in_point1"
TYPE PIXMAP
IMAGE "flaeche1_1.png"
TRANSPARENT 13
END
|
Table 6: Construction of a face hatch
| CLASS-Section from the Mapfile | Character from the Symbolfile |
|---|---|
CLASS
STYLE
COLOR 255 255 0
END
STYLE
SYMBOL "in_hatch"
COLOR 0 0 0
OUTLINECOLOR 0 0 0
END
END
|
SYMBOL
NAME "in_hatch"
TYPE PIXMAP
IMAGE "schraffur.png"
TRANSPARENT 2
END
|
The TYPE Cartoline is not really an independent SYMBOL type or basic element but it is useful for creating line signatures. The advantage over the above types is the antialising of lines with any width. Conventional lines can only use antialising with a width of 1 pixel. This line type supports the ANTIALIAS parameter in the STYLE block of the CLASS definition just like the truetype fonts and symbols. Here you can also define line patterns and offsets. The design of the line ends can be controled with the LINECAP parameter. The LINECAP value BUTT stopps the signature exactly at the end of the top line. Author of this features is Tomas Krecmer (tokr(a)tmapy.cz). If you have questions concerning this type of signature or suggestions for improvement please contact the author.
SYMBOL
NAME "cartoline"
TYPE cartoline
LINECAP round #[butt|round|square|triangle]
LINEJOIN miter #[round|miter|bevel]
LINEJOINMAXSIZE 3
STYLE
40 17 1 17 1 17 1 17
END
END
The different values for the parameter LINEJOIN have the following visual effects (see the following figure). Default is ‘not set’ but do not specify the string ‘not set’, just omit the parameter LINEJOIN.
Specify the maximum length of m (only relevant for LINEJOIN type MITER). The value is a multiplication factor (default 3). The actual max length is calculated as follows:
m - current join size
d - symbol size
m_max = d * LINEJOINMAXSIZE
If current m > m_max then the connection length will be set to m_max.
Finally you can use symbols from truetype fonts. The symbol settings are also defined in the SYMBOL file. Specify the ASCII number of the symbol to be used in the CHARACTER parameter. Add the ALIAS name of the font file to the parameter FONT as defined in the file fonts.list. Remember to set the FONTSET parameter in the MAP file to link the correct fonts.list file. With the parameter ANTIALIAS you define whether to apply antialiasing to the symbols or characters. It is recommended to do this especially with more complex symbols and and whenever they don’t fit well into the raster matrix or show a visible pixel structure. Set a POSITION [ul|uc|ur|cl|cc|cr|ll|lc|lr] relative to the geometric origin of the geometry. In the STYLE section of the LAYER object it is possible to define colors for true type symbols (as with signatures of the TYPE VECTOR).
When using truetype chracters to render complex line symbols, you can define the distance in pixel until the symbol is repeated by setting the GAP parmeter in the SYMBOL file. A more complicated pattern like the STYLE parameters for VECTOR, ELLIPSE or PIXMAP type symbols cannot be used not (Anybody need this feature?). The OFFSET parameter is currently not implemented yet. Truetype symbols follow the inclination of the accompanying line.
When using asymmetrical symbols they unfortunately do not always follow the outside or the inside, left or right of a line but change. If possible symbols will always be displayed upside (which makes a lot of sense for string characters, what true type fonts basically are). On vertical lines symbols are rendered to the right or left side depending on the drawing direction of the line. If the line is drawn from bottom to top, the truetype symbol is displayed to the left, if the line is drawn from top to bottom, the symbol is displayed to the right (see table below). In left picture in the table the line is drawn clockwise and in the right picture drawn counterclockwise.
Table 7: TrueType-character used on lines
| CLASS-Section from the Mapfile | Character from the Symbolfile |
|---|---|
CLASS
STYLE
SYMBOL "T"
SIZE 12
COLOR 0 0 255
END
END
|
SYMBOL
NAME "T"
TYPE TRUETYPE
FONT "arial"
CHARACTER "T"
ANTIALIAS TRUE
GAP 10
END
|
To find out the character number of a symbol use one of the following options:
Please note that the numbering of the so-called “symbol fonts” starts at 61440! So if you want to use character T, you have to use 61440 + 84 = . (ain’t that a pain!!)
Find some examples to show different possibilities of the UMN MapServer for cartographical symbols of the vector based mapobjects (this is just a selection!):
The current version of MapServer renders open symbols (e.g. a cross) and empty symbols of the TYPE VECTOR incorrectly by filling them. This bug has been removed during our code examination and should be eliminated with a future release. Additionaly the OUTLINECOLOR-parameter can not be used to create a 1 pixel outline for symbols and characters on a line. This can be achieved in a more flexible way as mentioned above. Another problem concerns the use of line patterns (e.g. dashed line) on features with many points and nooks. The line pattern will then often be displayed irregularly (see Table9).
Table 8: Use of a simple cross on a line
| CLASS-Section from the Mapfile | Character from the Symbolfile |
|---|---|
CLASS
STYLE
SIZE 1
COLOR 0 0 0
END
STYLE
SYMBOL "cross2"
SIZE 8
COLOR 204 153 0
OFFSET 1 -7
END
END
|
SYMBOL
NAME "cross2"
TYPE VECTOR
POINTS
0 0
1 1
-99 -99
0 1
1 0
END
STYLE
1 15 1 15
END
END
|
Table9: Irregularities with line patterns
| CLASS-Section from the Mapfile | Character from the Symbolfile |
|---|---|
CLASS
STYLE
SYMBOL "border2"
SIZE 2
COLOR 255 0 0
END
END
|
SYMBOL
NAME "border2"
TYPE VECTOR
POINTS
0 0
1 0
1 0.8
0 0.8
0 0
END
STYLE
10 6 1 6
END
FILLED TRUE
END
|
All symbols in this document were created with MAP files and SYMBOL files, which can be downloaded. If you want to use this MAP file please note, that your MapServer must at least be able to handle with 50 symbols. Otherwise you get an error while loading the SYMBOL files.
I hope that this document will help you to present your data in a cartographically nice manner with the UMN MapServer and explains some basics and possibilities of the concept of the UMN MapServer as well as some weakness. It would be great to put together a cartographic symbols library for the profit of everyone. This especially concerns truetype-fonts, which were developed for some projects and contain some typical signatures for cartographic needs.
You can also view the discussion paper for the improvement of the MapServer Graphic-Kernel (sorry as yet German only).
