MapServer Documentation

MapServer Documentation
Release 7.0.6
The MapServer Team
2017-06-21
Contents
1
Introduction
1.1 An Introduction to MapServer . . . . . . . . .
1.1.1
MapServer Overview . . . . . . . . .
1.1.2
Anatomy of a MapServer Application
1.1.3
Installation and Requirements . . . .
Hardware Requirements . . . . . . . .
Software Requirements . . . . . . . . .
Skills . . . . . . . . . . . . . . . . . .
Windows Installation . . . . . . . . . .
1.1.4
Introduction to the Mapfile . . . . . .
MAP Object . . . . . . . . . . . . . .
LAYER Object . . . . . . . . . . . . .
CLASS and STYLE Objects . . . . . .
SYMBOLs . . . . . . . . . . . . . . .
LABEL . . . . . . . . . . . . . . . . .
CLASS Expressions . . . . . . . . . .
INCLUDE . . . . . . . . . . . . . . .
Get MapServer Running . . . . . . . .
Get Demo Running . . . . . . . . . . .
1.1.5
Making the Site Your Own . . . . . .
Adding Data to Your Site . . . . . . . .
Vector Data . . . . . . . . . . . . . . .
Raster Data . . . . . . . . . . . . . . .
Projections . . . . . . . . . . . . . . .
1.1.6
Enhancing your site . . . . . . . . . .
Adding Query Capability . . . . . . . .
Attribute queries . . . . . . . . . . . .
Spatial queries . . . . . . . . . . . . .
Interfaces . . . . . . . . . . . . . . . .
Data Optimization . . . . . . . . . . .
1.1.7
How do I get Help? . . . . . . . . . .
Documentation . . . . . . . . . . . . .
Users Mailing List . . . . . . . . . . .
IRC . . . . . . . . . . . . . . . . . . .
Reporting bugs . . . . . . . . . . . . .
Tutorial . . . . . . . . . . . . . . . . .
Test Suite . . . . . . . . . . . . . . . .
Books . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2
2
3
4
6
6
6
6
7
14
16
16
17
18
19
22
22
23
23
24
24
24
24
24
25
25
25
25
25
25
26
26
26
26
26
26
27
27
i
2
3
Tutorial
2.1 MapServer Tutorial . . . . . . . . . . . . . . . . . . . . . .
2.1.1
Tutorial background . . . . . . . . . . . . . . . . .
Tutorial Timeframe . . . . . . . . . . . . . . . . . .
Tutorial Data . . . . . . . . . . . . . . . . . . . . .
Before Using the Tutorial . . . . . . . . . . . . . .
Windows, UNIX/Linux Issues . . . . . . . . . . . .
Other Resources . . . . . . . . . . . . . . . . . . .
2.1.2
Section 1: Static Maps and the MapFile . . . . . .
2.1.3
Section 2: CGI variables and the User Interface . .
HTML Templates . . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . . . . .
2.1.4
Section 3: Query and more about HTML Templates
2.1.5
Section 4: Advanced User Interfaces . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
28
28
28
28
28
29
29
30
30
31
31
31
31
32
Installation
3.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1
Compiling on Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining the necessary software . . . . . . . . . . . . . . . . . . . . . .
Anti-Grain Geometry Support . . . . . . . . . . . . . . . . . . . . . . . .
OGC Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Spatial Warehousing . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2
Compiling on Win32 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set up a Project Directory . . . . . . . . . . . . . . . . . . . . . . . . . .
Download MapServer Source Code and Supporting Libraries . . . . . . . .
The MapServer source code . . . . . . . . . . . . . . . . . . . . . . . . .
Set Compilation Options . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compile the Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compile MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling MapServer with PostGIS support . . . . . . . . . . . . . . . .
Common Compiling Errors . . . . . . . . . . . . . . . . . . . . . . . . .
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Other Helpful Information . . . . . . . . . . . . . . . . . . . . . . . . . .
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.3
PHP MapScript Installation . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining, Compiling, and Installing PHP and the PHP/MapScript Module
FAQ / Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.4
.NET MapScript Compilation . . . . . . . . . . . . . . . . . . . . . . .
Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Most frequent errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bug reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.5
IIS Setup for MapServer . . . . . . . . . . . . . . . . . . . . . . . . . .
Base configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Php.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Internet Services Manager . . . . . . . . . . . . . . . . . . . . . . . . . .
Under the tree for your new website - add virtual directories for . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
33
33
33
33
34
35
35
37
38
39
41
41
42
42
42
43
44
45
45
46
46
47
47
47
47
48
49
52
54
54
56
57
59
59
59
60
60
60
61
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
ii
Test PHP . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapfiles for IIS . . . . . . . . . . . . . . . . . . . . . . . .
Configuration files: . . . . . . . . . . . . . . . . . . . . . .
3.1.6
Oracle Installation . . . . . . . . . . . . . . . . . . . . .
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System Assumptions . . . . . . . . . . . . . . . . . . . . .
Compile MapServer . . . . . . . . . . . . . . . . . . . . .
Set Environment Variables . . . . . . . . . . . . . . . . . .
3.1.7
V8 MapScript Support . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining, Compiling, and Installing V8 and V8/MapScript
4
Mapfile
4.1 Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.1
Cartographical Symbol Construction with MapServer
Abstract . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . .
Using Cartographical Symbols in MapServer . . . . .
Construction of Point Symbols . . . . . . . . . . . . .
Construction of Line Symbols . . . . . . . . . . . . .
Area Symbols . . . . . . . . . . . . . . . . . . . . . .
Examples (MapServer 4) . . . . . . . . . . . . . . . .
Tricks . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapfile changes related to symbols . . . . . . . . . .
Current Problems / Open Issues . . . . . . . . . . . .
The End . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.2
CLASS . . . . . . . . . . . . . . . . . . . . . . . .
4.1.3
CLUSTER . . . . . . . . . . . . . . . . . . . . . .
Description . . . . . . . . . . . . . . . . . . . . . . .
Supported Layer Types . . . . . . . . . . . . . . . . .
Mapfile Parameters . . . . . . . . . . . . . . . . . . .
Supported Processing Options . . . . . . . . . . . . .
Mapfile Snippet . . . . . . . . . . . . . . . . . . . . .
Feature attributes . . . . . . . . . . . . . . . . . . . .
Handling GetFeatureInfo . . . . . . . . . . . . . . . .
PHP MapScript Usage . . . . . . . . . . . . . . . . .
Example: Clustering Railway Stations . . . . . . . . .
4.1.4
COMPOSITE . . . . . . . . . . . . . . . . . . . . .
Background . . . . . . . . . . . . . . . . . . . . . . .
Parameters . . . . . . . . . . . . . . . . . . . . . . .
Usage . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.5
Display of International Characters in MapServer . .
Credit . . . . . . . . . . . . . . . . . . . . . . . . . .
Related Links . . . . . . . . . . . . . . . . . . . . . .
Requirements . . . . . . . . . . . . . . . . . . . . . .
How to Enable in Your Mapfile (MapServer >= 7.0) .
How to Enable in Your Mapfile (MapServer < 7.0) . .
Example Using PHP MapScript . . . . . . . . . . . .
Notes . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.6
Expressions . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . .
Expression Types . . . . . . . . . . . . . . . . . . . .
String comparison (equality) . . . . . . . . . . . . . .
Regular expression comparison . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
61
61
62
62
62
62
63
63
65
66
66
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
68
68
68
70
70
73
74
81
93
109
115
119
119
120
120
122
123
123
123
123
123
124
124
125
125
127
127
127
128
129
129
130
130
130
132
133
134
134
135
136
136
137
iii
4.1.7
4.1.8
4.1.9
4.1.10
4.1.11
4.1.12
4.1.13
4.1.14
4.1.15
4.1.16
4.1.17
4.1.18
4.1.19
4.1.20
4.1.21
4.1.22
4.1.23
4.1.24
List expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
“MapServer expressions” . . . . . . . . . . . . . . . . . . . . . . . . .
FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FONTSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Format of the fontset file . . . . . . . . . . . . . . . . . . . . . . . . .
GEOMTRANSFORM - Geometry Transformations . . . . . . . . . .
Transformations for simple styling (CLASS STYLE only) . . . . . . . .
Labels (LABEL STYLE only) . . . . . . . . . . . . . . . . . . . . . . .
Expressions and advanced transformations (LAYER and CLASS STYLE)
Javascript transformation . . . . . . . . . . . . . . . . . . . . . . . . .
GRID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapfile Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example1: Grid Displaying Degrees . . . . . . . . . . . . . . . . . . .
Example2: Grid Displaying Degrees with Symbol . . . . . . . . . . .
Example3: Grid Displayed in Other Projection (Google Mercator) . . .
INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapfile Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example 1: Join from Shape dataset to DBF file . . . . . . . . . . . . .
Example 2: Join from Shape dataset to PostgreSQL table . . . . . . . .
Example 3: Join from Shape dataset to CSV file . . . . . . . . . . . . .
Example 4: Join from Shape dataset to MySQL . . . . . . . . . . . . .
Example 5: One-to-many join . . . . . . . . . . . . . . . . . . . . . .
LABEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LAYER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Layer Types . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapfile Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapfile Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: World Countries Labels . . . . . . . . . . . . . . . . . . . .
LEGEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OUTPUTFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROJECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Projections with MapServer . . . . . . . . . . . . . . . . . . . . . . .
“Web Mercator” or “Google Mercator” . . . . . . . . . . . . . . . . .
PROJECTION AUTO . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying which EPSG files to use . . . . . . . . . . . . . . . . . . .
Important Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
For More Information . . . . . . . . . . . . . . . . . . . . . . . . . .
QUERYMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCALEBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STYLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STYLEITEM Javascript . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
138
139
145
146
146
147
149
153
155
163
168
168
168
168
169
170
171
172
172
173
173
173
173
174
175
176
178
178
179
186
199
200
200
200
200
201
204
205
209
213
213
213
214
215
215
215
215
216
216
217
219
227
228
228
iv
4.1.25
4.1.26
4.1.27
4.1.28
4.1.29
4.1.30
4.1.31
5
Example 1. Single STYLE definition . . . . . . . . . . .
Example 2. CLASS with multiple STYLE definitions . . .
Example 3. Printing logs in MapServer logs . . . . . . . .
SYMBOL . . . . . . . . . . . . . . . . . . . . . . . . .
Symbology Examples . . . . . . . . . . . . . . . . . . .
Example 1. Dashed Line . . . . . . . . . . . . . . . . . .
Example 2. TrueType font marker symbol . . . . . . . . .
Example 3. Vector triangle marker symbol . . . . . . . .
Example 4. Non-contiguous vector marker symbol (Cross)
Example 5. Circle vector symbol . . . . . . . . . . . . . .
Example 6. Downward diagonal fill . . . . . . . . . . . .
Example 7. Using the Symbol Type HATCH (new in 4.6) .
Example 8. Styled lines using GAP . . . . . . . . . . . .
Templating . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . .
Format . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example Template . . . . . . . . . . . . . . . . . . . . .
Union Layer . . . . . . . . . . . . . . . . . . . . . . . .
Description . . . . . . . . . . . . . . . . . . . . . . . . .
Requirements . . . . . . . . . . . . . . . . . . . . . . . .
Mapfile Configuration . . . . . . . . . . . . . . . . . . .
Feature attributes . . . . . . . . . . . . . . . . . . . . . .
Classes and Styles . . . . . . . . . . . . . . . . . . . . .
Projections . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Processing Options . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . . . . . . . .
WEB . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML Mapfile support . . . . . . . . . . . . . . . . . . .
Enabling the support . . . . . . . . . . . . . . . . . . . .
Usage: . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . .
MapScript
5.1 MapScript . . . . . . . . . . . . . . . . . .
5.1.1
Introduction . . . . . . . . . . . . .
Appendices . . . . . . . . . . . . . .
Documentation Elements . . . . . . .
fooObj . . . . . . . . . . . . . . . .
Additional Documentation . . . . . .
5.1.2
SWIG MapScript API Reference . .
Introduction . . . . . . . . . . . . . .
MapScript Constants . . . . . . . . .
MapScript Functions . . . . . . . . .
MapScript Classes . . . . . . . . . .
5.1.3
PHP MapScript . . . . . . . . . . .
Introduction . . . . . . . . . . . . . .
PHP MapScript API . . . . . . . . .
PHP MapScript Migration Guide . .
By Example . . . . . . . . . . . . . .
5.1.4
Python MapScript Appendix . . . .
Introduction . . . . . . . . . . . . . .
Classes . . . . . . . . . . . . . . . .
Exception Handling . . . . . . . . .
5.1.5
Python MapScript Image Generation
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
229
229
229
230
232
232
233
233
233
234
234
234
235
235
236
237
244
246
246
246
246
247
247
248
248
248
251
253
253
253
254
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
255
255
255
255
255
255
256
256
258
259
265
265
301
301
303
339
343
353
353
353
355
355
v
Introduction . . . . . .
Imagery Overview . .
The imageObj Class .
Image Output . . . . .
Images and Symbols .
5.1.6
Mapfile Manipulation
Introduction . . . . . .
Mapfile Overview . .
The mapObj Class . .
Children of mapObj .
Metadata . . . . . . .
5.1.7
Querying . . . . . .
Introduction . . . . . .
Querying Overview . .
Attribute Queries . . .
Spatial Queries . . . .
6
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
355
356
356
356
357
357
358
358
358
359
360
360
361
361
362
362
MapCache
6.1 MapCache 1.4 . . . . . . . . . . .
6.1.1
Compilation & Installation
Getting the Source . . . . .
Linux Instructions . . . . .
Windows Instructions . . . .
6.1.2
Configuration File . . . . .
Source . . . . . . . . . . .
Cache . . . . . . . . . . . .
Format . . . . . . . . . . .
Grid . . . . . . . . . . . . .
Tileset . . . . . . . . . . . .
Services . . . . . . . . . . .
Miscellaneous . . . . . . .
6.1.3
Supported Tile Services . .
TMS Service . . . . . . . .
KML Service . . . . . . . .
OGC WMTS Service . . . .
OGC WMS Service . . . . .
GoogleMaps XYZ Service .
Virtual Earth tile service . .
6.1.4
Seeder . . . . . . . . . . .
Usage . . . . . . . . . . . .
6.1.5
Cache Types . . . . . . . .
Disk Caches . . . . . . . .
Berkeley DB Caches . . . .
SQLite Caches . . . . . . .
MBTiles Caches . . . . . .
Memcache Caches . . . . .
(Geo)TIFF Caches . . . . .
REST Caches . . . . . . . .
Meta Caches . . . . . . . .
Riak Caches . . . . . . . .
6.1.6
Image Formats . . . . . .
JPEG Format . . . . . . . .
PNG Format . . . . . . . .
Mixed Format . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
363
363
363
364
364
371
374
374
376
377
378
381
385
386
387
387
389
389
389
391
392
393
393
396
396
398
398
401
402
402
405
407
409
409
409
409
410
vi
6.1.7
6.1.8
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
410
410
410
410
411
411
411
412
412
413
413
413
413
414
414
414
415
415
415
Input
7.1 Data Input . . . . . . . . . . . . . . . . .
7.1.1
Vector Data . . . . . . . . . . . .
Data Format Types . . . . . . . . .
ArcInfo . . . . . . . . . . . . . . .
ArcSDE . . . . . . . . . . . . . . .
Contour . . . . . . . . . . . . . . .
DGN . . . . . . . . . . . . . . . .
ESRI File Geodatabase . . . . . . .
ESRI Personal Geodatabase (MDB)
ESRI Shapefiles (SHP) . . . . . . .
GML . . . . . . . . . . . . . . . .
GPS Exchange Format (GPX) . . .
Inline . . . . . . . . . . . . . . . .
KML - Keyhole Markup Language
MapInfo . . . . . . . . . . . . . . .
MSSQL . . . . . . . . . . . . . . .
MySQL . . . . . . . . . . . . . . .
NTF . . . . . . . . . . . . . . . . .
OGR . . . . . . . . . . . . . . . .
Oracle Spatial . . . . . . . . . . . .
PostGIS/PostgreSQL . . . . . . . .
SDTS . . . . . . . . . . . . . . . .
S57 . . . . . . . . . . . . . . . . .
SpatiaLite . . . . . . . . . . . . . .
USGS TIGER . . . . . . . . . . .
Vector field rendering - UVraster . .
Virtual Spatial Data . . . . . . . . .
WFS . . . . . . . . . . . . . . . .
7.1.2
Raster Data . . . . . . . . . . . .
Introduction . . . . . . . . . . . . .
How are rasters added to a Map file?
Supported Formats . . . . . . . . .
Rasters and Tile Indexing . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
417
417
417
418
419
420
423
426
427
429
431
433
435
437
438
445
446
451
455
456
471
476
485
487
489
492
494
496
501
502
503
503
505
506
6.1.9
6.1.10
6.1.11
6.1.12
6.1.13
6.1.14
7
Tileset Dimensions . . . . . . .
HTTP Requests . . . . . . . . .
Specifying the URL . . . . . . .
Timeouts . . . . . . . . . . . . .
Headers . . . . . . . . . . . . . .
FeatureInfo Requests . . . . . .
Proxying Unsupported Requests
Parameter Filtering . . . . . . . .
Proxy Destination . . . . . . . .
Data Sources . . . . . . . . . .
WMS Sources . . . . . . . . . .
MapFile Sources . . . . . . . . .
WMTS Sources . . . . . . . . . .
Tile Assembling . . . . . . . . .
Locking Mechanisms . . . . . .
Disk Locks . . . . . . . . . . . .
Memcache Locks . . . . . . . . .
Fallback Locks . . . . . . . . . .
Features . . . . . . . . . . . . .
vii
Raster Warping . . . . . . . . . .
24bit RGB Rendering . . . . . .
Special Processing Directives . .
Raster Query . . . . . . . . . . .
Raster Display Performance Tips
Preprocessing Rasters . . . . . .
Georeference with World Files . .
7.1.3
Virtual File System . . . . . . .
Virtual File System . . . . . . . .
8
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
507
507
508
510
512
512
514
514
515
Output
8.1 Output Generation . . . . . . . . . . . . . . . . . . . .
8.1.1
AGG Rendering Specifics . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . .
Setting the OutputFormat . . . . . . . . . . . . .
New Features . . . . . . . . . . . . . . . . . . .
Modified Behavior . . . . . . . . . . . . . . . .
8.1.2
AntiAliasing with MapServer . . . . . . . . . .
What needs to be done . . . . . . . . . . . . . .
8.1.3
Dynamic Charting . . . . . . . . . . . . . . .
Setup . . . . . . . . . . . . . . . . . . . . . . .
Adding a Chart Layer to a Mapfile . . . . . . . .
Pie Charts . . . . . . . . . . . . . . . . . . . . .
Bar Graphs . . . . . . . . . . . . . . . . . . . .
8.1.4
Flash Output . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . .
Installing MapServer with Flash Support . . . .
How to Output SWF Files from MapServer . . .
What is Currently Supported and Not Supported
8.1.5
HTML Legends with MapServer . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . .
Sample Site Using the HTML Legend . . . . . .
8.1.6
HTML Imagemaps . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . .
Mapfile Layer Definition . . . . . . . . . . . . .
Templates . . . . . . . . . . . . . . . . . . . . .
Request URL . . . . . . . . . . . . . . . . . . .
Additional Notes . . . . . . . . . . . . . . . . .
More Information . . . . . . . . . . . . . . . . .
8.1.7
Kernel Density Estimation (Dynamic Heatmap)
Introduction . . . . . . . . . . . . . . . . . . . .
Configuration . . . . . . . . . . . . . . . . . . .
Advanced sample weighting and filtering . . . .
Raster Color Ramping . . . . . . . . . . . . . .
Example mapfiles . . . . . . . . . . . . . . . . .
8.1.8
OGR Output . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . .
OUTPUTFORMAT Declarations . . . . . . . .
LAYER Metadata . . . . . . . . . . . . . . . . .
MAP / WEB Metadata . . . . . . . . . . . . . .
Geometry Types Supported . . . . . . . . . . . .
Attribute Field Definitions . . . . . . . . . . . .
Return Packaging . . . . . . . . . . . . . . . . .
Test Suite Example . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
519
519
519
519
519
520
521
521
522
525
525
526
528
530
531
531
532
533
536
537
537
545
546
546
547
547
548
548
548
549
549
550
552
552
553
555
556
556
557
558
559
559
559
560
viii
8.1.9
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
560
560
561
561
563
565
565
566
567
569
572
572
573
573
576
577
577
578
578
582
582
582
583
583
583
583
584
587
588
588
588
589
589
589
589
589
590
OGC
9.1 OGC Support and Configuration . . . . . . . . . . . . . . .
9.1.1
MapServer OGC Specification support . . . . . . .
9.1.2
WMS Server . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . .
Setting Up a WMS Server Using MapServer . . . .
Changing the Online Resource URL . . . . . . . . .
WMS 1.3.0 Support . . . . . . . . . . . . . . . . .
Reference Section . . . . . . . . . . . . . . . . . .
FAQ / Common Problems . . . . . . . . . . . . . .
9.1.3
INSPIRE View Service . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . .
Activation of INSPIRE support . . . . . . . . . . .
Multi-language support for certain capabilities fields
Provision of INSPIRE specific metadata . . . . . . .
Named group layers . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
591
591
591
591
592
593
599
602
603
616
617
618
618
618
620
621
8.1.10
8.1.11
8.1.12
8.1.13
8.1.14
9
PDF Output . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . .
What is currently supported and not supported
Implementing PDF Output . . . . . . . . . . .
PHP/MapScript and PDF Output . . . . . . . .
SVG . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . .
Feature Types and SVG Support Status . . . .
Testing your SVG Output . . . . . . . . . . .
goSVG . . . . . . . . . . . . . . . . . . . . .
Tile Mode . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . .
Configuration . . . . . . . . . . . . . . . . . .
Utilization . . . . . . . . . . . . . . . . . . .
Template-Driven Output . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . .
OUTPUTFORMAT Declarations . . . . . . .
Template Substitution Tags . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . .
Kml Output . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . .
General Functionality . . . . . . . . . . . . . .
Output format . . . . . . . . . . . . . . . . . .
Build . . . . . . . . . . . . . . . . . . . . . .
Limiting the number of features . . . . . . . .
Map . . . . . . . . . . . . . . . . . . . . . . .
Layers . . . . . . . . . . . . . . . . . . . . . .
Styling . . . . . . . . . . . . . . . . . . . . .
Attributes . . . . . . . . . . . . . . . . . . . .
Coordinate system . . . . . . . . . . . . . . .
Warning and Error Messages . . . . . . . . . .
UTFGrid Output . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . .
Functionality . . . . . . . . . . . . . . . . . .
Build . . . . . . . . . . . . . . . . . . . . . .
Setting the OutputFormat . . . . . . . . . . . .
Exposing Feature Properties . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
ix
9.1.4
9.1.5
9.1.6
9.1.7
9.1.8
9.1.9
9.1.10
9.1.11
9.1.12
9.1.13
9.1.14
Style section for root layer and possibly existing group layers
WMS Client . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compilation / Installation . . . . . . . . . . . . . . . . . . .
MapFile Configuration . . . . . . . . . . . . . . . . . . . . .
Limitations/TODO . . . . . . . . . . . . . . . . . . . . . . .
WMS Time . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling Time Support in MapServer . . . . . . . . . . . . .
Future Additions . . . . . . . . . . . . . . . . . . . . . . . .
Limitations and Known Bugs . . . . . . . . . . . . . . . . .
WMS Dimension . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling Dimension Support in MapServer . . . . . . . . . .
GetCapabilities Output . . . . . . . . . . . . . . . . . . . . .
Supported Dimension Requests . . . . . . . . . . . . . . . .
Processing Dimension Requests . . . . . . . . . . . . . . . .
Map Context . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Implementing a Web Map Context . . . . . . . . . . . . . . .
WFS Server . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring your MapFile to Serve WFS layers . . . . . . . .
Stored queries (WFS 2.0) . . . . . . . . . . . . . . . . . . . .
Reference Section . . . . . . . . . . . . . . . . . . . . . . .
To-do Items and Known Limitations . . . . . . . . . . . . . .
INSPIRE Download Service . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Activation of INSPIRE support . . . . . . . . . . . . . . . .
Multi-language support for certain capabilities fields . . . . .
Provision of INSPIRE specific metadata . . . . . . . . . . . .
WFS Client . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up a WFS-client Mapfile . . . . . . . . . . . . . . . .
TODO / Known Limitations . . . . . . . . . . . . . . . . . .
WFS-T Server . . . . . . . . . . . . . . . . . . . . . . . . .
WFS-T . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WFS Filter Encoding . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Currently Supported Features . . . . . . . . . . . . . . . . .
Get and Post Requests . . . . . . . . . . . . . . . . . . . . .
Use of Filter Encoding in MapServer . . . . . . . . . . . . .
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Side Support . . . . . . . . . . . . . . . . . . . . . .
Client Side Support . . . . . . . . . . . . . . . . . . . . . . .
Named Styles support . . . . . . . . . . . . . . . . . . . . .
Other Items Implemented . . . . . . . . . . . . . . . . . . .
Issues Found During Implementation . . . . . . . . . . . . .
WCS Server . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Your Mapfile to Serve WCS Layers . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
621
623
623
624
625
631
631
632
632
636
636
636
636
636
637
638
638
638
639
639
646
646
647
652
654
659
659
660
660
661
662
663
663
664
668
668
668
668
669
669
670
671
673
673
677
677
678
685
687
687
687
687
688
689
x
9.1.15
9.1.16
9.1.17
9.1.18
Test Your WCS 1.0 Server . . . . . . . . . . . . . . . . . . . . . .
WCS 1.1.0+ Issues . . . . . . . . . . . . . . . . . . . . . . . . . .
WCS 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HTTP-POST support . . . . . . . . . . . . . . . . . . . . . . . . .
Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . .
Rules for handling SRS in a MapServer WCS . . . . . . . . . . . .
Spatio/Temporal Indexes . . . . . . . . . . . . . . . . . . . . . . .
WCS 2.0 Application Profile - Earth Observation (EO-WCS) . . . .
To-do Items and Known Limitations . . . . . . . . . . . . . . . . .
WCS Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . .
Landsat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NetCDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Up an SOS Server Using MapServer . . . . . . . . . . . . .
Limitations / TODO . . . . . . . . . . . . . . . . . . . . . . . . .
Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of sos_procedure and sos_procedure_item . . . . . . . . . . .
How to set up MapServer as a client to access a service over https
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Installation (with apt-get install, rpm, manual, etc) . . . . .
Non-Standard Installation (common with ms4w and fgs) . . . . . .
Remote Server with a Self-Signed SSL Certificate . . . . . . . . .
MapScript Wrappers for WxS Services . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Python Examples . . . . . . . . . . . . . . . . . . . . . . . . . . .
Perl Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PHP Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use in Non-CGI Environments (mod_php, etc) . . . . . . . . . . .
Post Processing Capabilities . . . . . . . . . . . . . . . . . . . . .
10 TinyOWS
10.1 TinyOWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.1 TinyOWS Installation . . . . . . . . . . . . . . . . . . .
Requires . . . . . . . . . . . . . . . . . . . . . . . . . .
10.1.2 Configuring TinyOWS with an XML File . . . . . . . .
Configuration file simple Example . . . . . . . . . . . . .
Testing your config.xml file . . . . . . . . . . . . . . . .
Structure of the config.xml file . . . . . . . . . . . . . . .
10.1.3 Configuring TinyOWS with a standard Mapfile . . . . .
Mapfile Config File support for TinyOWS . . . . . . . . .
Mapfile path of each TinyOWS config element . . . . . .
10.1.4 Sample: WFS-T with TinyOWS and OpenLayers . . . .
10.1.5 Server Tuning: How to speed up your TinyOWS server .
Tips and Tricks for PostgreSQL / PostGIS databases . . .
Tips and Tricks for Apache . . . . . . . . . . . . . . . . .
Using Fast-CGI . . . . . . . . . . . . . . . . . . . . . . .
HTTP GZip compression . . . . . . . . . . . . . . . . . .
10.1.6 Working Around the LibXML2 XSD Schema GML Bug
Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
691
693
694
700
703
707
707
708
708
708
708
709
710
711
713
714
714
719
719
724
725
726
726
726
726
727
728
728
728
729
732
733
735
735
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
737
737
737
737
738
738
739
739
744
744
745
746
751
751
751
751
752
752
752
xi
Workaround and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
11 Optimization
11.1 Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.1.1 Debugging MapServer . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . .
Steps to Enable MapServer Debugging . . . . . . . . .
Debugging MapServer using Compiler Debugging Tools
Debugging Older Versions of MapServer (before 5.0) . .
11.1.2 FastCGI . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining the necessary software . . . . . . . . . . . .
mod_fcgid Configuration . . . . . . . . . . . . . . . . .
Deprecated mod_fcgi Configuration . . . . . . . . . . .
Common mod_fcgid/mod_fcgi Configuration . . . . . .
Common Problems . . . . . . . . . . . . . . . . . . . .
FastCGI on Win32 . . . . . . . . . . . . . . . . . . . .
11.1.3 Mapfile . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . .
11.1.4 Raster . . . . . . . . . . . . . . . . . . . . . . . . . .
Overviews . . . . . . . . . . . . . . . . . . . . . . . .
Tileindexes and Internal Tiling . . . . . . . . . . . . . .
Image formats . . . . . . . . . . . . . . . . . . . . . .
Remote WMS . . . . . . . . . . . . . . . . . . . . . .
11.1.5 Tile Indexes . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . .
What is a tileindex and how do I make one? . . . . . . .
Using the tileindex in your mapfile . . . . . . . . . . . .
Tileindexes may make your map faster . . . . . . . . . .
Tileindexes with tiles in different projections . . . . . .
11.1.6 Vector . . . . . . . . . . . . . . . . . . . . . . . . . .
Splitting your data . . . . . . . . . . . . . . . . . . . .
Shapefiles . . . . . . . . . . . . . . . . . . . . . . . . .
PostGIS . . . . . . . . . . . . . . . . . . . . . . . . . .
Databases in General (PostGIS, Oracle, MySQL) . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
755
755
755
756
756
764
766
767
767
767
768
768
769
769
769
771
771
773
773
773
774
774
774
774
775
775
775
776
776
777
777
777
777
12 Utilities
12.1 Utilities . . . . . . . .
12.1.1 legend . . . .
Purpose . . . .
Syntax . . . .
12.1.2 msencrypt . .
Purpose . . . .
Syntax . . . .
Use in Mapfile
12.1.3 scalebar . . .
Purpose . . . .
Syntax . . . .
12.1.4 shp2img . . .
Purpose . . . .
Syntax . . . .
12.1.5 shptree . . . .
Purpose . . . .
Description . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
779
779
779
779
779
779
779
779
780
781
781
781
781
781
782
784
784
784
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xii
Syntax . . . . . .
Mapfile Notes . . .
12.1.6 shptreetst . . . .
Purpose . . . . . .
Syntax . . . . . .
12.1.7 shptreevis . . . .
Purpose . . . . . .
Syntax . . . . . .
12.1.8 sortshp . . . . . .
12.1.9 sym2img . . . .
Purpose . . . . . .
Syntax . . . . . .
12.1.10 tile4ms . . . . .
Purpose . . . . . .
Description . . . .
Syntax . . . . . .
Short Example . .
Long Example . .
12.1.11 Batch Scripting .
Windows . . . . .
Linux . . . . . . .
12.1.12 File Management
File Placement . .
Temporary Files .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
784
785
785
785
785
786
786
786
787
789
789
789
789
789
790
790
790
790
793
793
793
793
793
793
13 CGI
13.1 CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.1.1 MapServer CGI Introduction . . . . . . . . . . . . . . . .
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.1.2 mapserv . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.1.3 Map Context Files . . . . . . . . . . . . . . . . . . . . .
Support for Local Map Context Files . . . . . . . . . . . .
Support for Context Files Accessed Through a URL . . . .
Default Map File . . . . . . . . . . . . . . . . . . . . . . .
13.1.4 MapServer CGI Controls . . . . . . . . . . . . . . . . . .
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing map file parameters via a form or a URL . . . . .
Specifying the location of mapfiles using an Apache variable
ROSA-Applet Controls . . . . . . . . . . . . . . . . . . . .
13.1.5 Run-time Substitution . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Example . . . . . . . . . . . . . . . . . . . . . . . .
Parameters Supported . . . . . . . . . . . . . . . . . . . .
Default values if not provided in the URL . . . . . . . . . .
VALIDATION . . . . . . . . . . . . . . . . . . . . . . . .
Magic values . . . . . . . . . . . . . . . . . . . . . . . . .
13.1.6 A Simple CGI Wrapper Script . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . .
Script Information . . . . . . . . . . . . . . . . . . . . . .
13.1.7 MapServer OpenLayers Viewer . . . . . . . . . . . . . .
Using the OpenLayers viewer . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
795
795
795
795
795
796
796
796
796
797
797
797
800
802
802
802
802
803
803
804
805
805
805
806
806
807
807
14 Environment Variables
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
809
xiii
14.1 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
15 Glossary
812
15.1 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
16 Errors
16.1 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.1.1 drawEPP(): EPPL7 support is not available . . . . . . . . . . . . . . . . . . . . . . .
Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.1.2 loadLayer(): Unknown identifier. Maximum number of classes reached . . . . . . . .
16.1.3 loadMapInternal(): Given map extent is invalid . . . . . . . . . . . . . . . . . . . . .
How to get a file’s EXTENT values? . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.1.4 msGetLabelSize(): Requested font not found . . . . . . . . . . . . . . . . . . . . . .
16.1.5 msLoadFontset(): Error opening fontset . . . . . . . . . . . . . . . . . . . . . . . . .
16.1.6 msLoadMap(): Failed to open map file . . . . . . . . . . . . . . . . . . . . . . . . . .
16.1.7 msProcessProjection(): no options found in ‘init’ file . . . . . . . . . . . . . . . . . .
16.1.8 msProcessProjection(): No such file or directory . . . . . . . . . . . . . . . . . . . . .
Setting the location of the epsg file . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.1.9 msProcessProjection(): Projection library error.major axis or radius = 0 not given . . .
Valid Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.1.10 msQueryByPoint: search returned no results . . . . . . . . . . . . . . . . . . . . . . .
16.1.11 msReturnPage(): Web application error. Malformed template name . . . . . . . . . . .
16.1.12 msSaveImageGD(): Unable to access file . . . . . . . . . . . . . . . . . . . . . . . .
16.1.13 msWMSLoadGetMapParams(): WMS server error. Image Size out of range, WIDTH
HEIGHT must be between 1 and 2048 pixels . . . . . . . . . . . . . . . . . . . . . .
16.1.14 Unable to load dll (MapScript) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C#-specific information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
and
. . .
. . .
. . .
17 FAQ
17.1 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.1 Where is the MapServer log file? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.2 What books are available about MapServer? . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.3 How do I compile MapServer for Windows? . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.4 What do MapServer version numbers mean? . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.5 Is MapServer Thread-safe? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.6 What does STATUS mean in a LAYER? . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.7 How can I make my maps run faster? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.8 What does Polyline mean in MapServer? . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.9 What is MapScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.10 Does MapServer support reverse geocoding? . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.11 Does MapServer support geocoding? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.12 How do I set line width in my maps? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.13 Why do my JPEG input images look different via MapServer? . . . . . . . . . . . . . . . .
17.1.14 Which image format should I use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.15 Why doesn’t PIL (Python Imaging Library) open my PNGs? . . . . . . . . . . . . . . . . .
17.1.16 Why do my symbols look poor in JPEG output? . . . . . . . . . . . . . . . . . . . . . . . .
17.1.17 How do I add a copyright notice on the corner of my map? . . . . . . . . . . . . . . . . . .
Example Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.18 How do I have a polygon that has both a fill and an outline with a width? . . . . . . . . . . .
17.1.19 How can I create simple antialiased line features? . . . . . . . . . . . . . . . . . . . . . . .
17.1.20 Which OGC Specifications does MapServer support? . . . . . . . . . . . . . . . . . . . . .
17.1.21 Why does my requested WMS layer not align correctly? . . . . . . . . . . . . . . . . . . .
17.1.22 When I do a GetCapabilities, why does my browser want to download mapserv.exe/mapserv?
815
815
815
815
815
816
816
817
817
817
817
818
818
818
818
819
819
820
820
820
820
822
822
822
822
822
822
823
824
824
824
825
825
825
825
825
826
826
827
827
827
828
828
829
830
830
831
xiv
17.1.23 Why do my WMS GetMap requests return exception using MapServer 5.0? . . . . . . . . .
17.1.24 Using MapServer 6.0, why don’t my layers show up in GetCapabilities responses or are not
found anymore? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.25 Where do I find my EPSG code? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.26 How can I reproject my data using ogr2ogr? . . . . . . . . . . . . . . . . . . . . . . . . . .
17.1.27 How can I help improve the documentation on this site? . . . . . . . . . . . . . . . . . . . .
17.1.28 What’s with MapServer’s logo? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
831
832
832
832
833
833
18 Copyright
834
18.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
18.2 Documentation License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
18.3 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
xv
MapServer Documentation, Release 7.0.6
Note: The entire documentation is also available as a single PDF document
If you are upgrading from an earlier version of MapServer, be sure to review the MapServer Migration Guide.
Documentation for earlier versions of MapServer can be found on the Download page.
Contents
1
CHAPTER 1
Introduction
1.1 An Introduction to MapServer
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Author David Fawcett
Contact david.fawcett at moea.state.mn.us
Author Howard Butler
Contact hobu.inc at gmail.com
Last Updated 2017-02-08
Contents
• An Introduction to MapServer
– MapServer Overview
– Anatomy of a MapServer Application
– Installation and Requirements
* Hardware Requirements
* Software Requirements
* Skills
* Windows Installation
– Introduction to the Mapfile
* MAP Object
* LAYER Object
* CLASS and STYLE Objects
* SYMBOLs
* LABEL
* CLASS Expressions
2
MapServer Documentation, Release 7.0.6
* INCLUDE
* Get MapServer Running
* Get Demo Running
– Making the Site Your Own
* Adding Data to Your Site
* Vector Data
* Raster Data
* Projections
– Enhancing your site
* Adding Query Capability
* Attribute queries
* Spatial queries
* Interfaces
* Data Optimization
– How do I get Help?
* Documentation
* Users Mailing List
* IRC
* Reporting bugs
* Tutorial
* Test Suite
* Books
1.1.1 MapServer Overview
MapServer is a popular Open Source project whose purpose is to display dynamic spatial maps over the Internet. Some
of its major features include:
• support for display and querying of hundreds of raster, vector, and database formats
• ability to run on various operating systems (Windows, Linux, Mac OS X, etc.)
• support for popular scripting languages and development environments (PHP, Python, Perl, Ruby, Java, .NET)
• on-the-fly projections
• high quality rendering
• fully customizable application output
• many ready-to-use Open Source application environments
In its most basic form, MapServer is a CGI program that sits inactive on your Web server. When a request is sent to
MapServer, it uses information passed in the request URL and the Mapfile to create an image of the requested map.
The request may also return images for legends, scale bars, reference maps, and values passed as CGI variables.
1.1. An Introduction to MapServer
3
MapServer Documentation, Release 7.0.6
See also:
The Glossary contains an overview of many of the jargon terms in this document.
MapServer can be extended and customized through MapScript or templating. It can be built to support many different
vector and raster input data formats, and it can generate a multitude of output formats. Most pre-compiled MapServer
distributions contain most all of its features.
See also:
Compiling on Unix and Compiling on Win32
Note: MapScript provides a scripting interface for MapServer for the construction of Web and stand-alone applications. MapScript can be used independently of CGI MapServer, and it is a loadable module that adds MapServer
capability to your favorite scripting language. MapScript currently exists in PHP, Perl, Python, Ruby, Tcl, Java, and
.NET flavors.
This guide will not explicitly discuss MapScript, check out the MapScript Reference for more information.
1.1.2 Anatomy of a MapServer Application
A simple MapServer application consists of:
• Map File - a structured text configuration file for your MapServer application. It defines the area of your map,
tells the MapServer program where your data is and where to output images. It also defines your map layers,
including their data source, projections, and symbology. It must have a .map extension or MapServer will not
recognize it.
See also:
MapServer Mapfile Reference
• Geographic Data - MapServer can utilize many geographic data source types. The default format is the ESRI
Shape format. Many other data formats can be supported, this is discussed further below in Adding data to your
site.
See also:
Vector Input Reference and Raster Input Reference
• HTML Pages - the interface between the user and MapServer . They normally sit in Web root. In it’s simplest
form, MapServer can be called to place a static map image on a HTML page. To make the map interactive, the
image is placed in an HTML form on a page.
CGI programs are ‘stateless’, every request they get is new and they don’t remember anything about the last time
that they were hit by your application. For this reason, every time your application sends a request to MapServer,
it needs to pass context information (what layers are on, where you are on the map, application mode, etc.) in
hidden form variables or URL variables.
A simple MapServer CGI application may include two HTML pages:
– Initialization File - uses a form with hidden variables to send an initial query to the web server and
MapServer. This form could be placed on another page or be replaced by passing the initialization information as variables in a URL.
– Template File - controls how the maps and legends output by MapServer will appear in the browser. By
referencing MapServer CGI variables in the template HTML, you allow MapServer to populate them with
values related to the current state of your application (e.g. map image name, reference image name, map
extent, etc.) as it creates the HTML page for the browser to read. The template also determines how the
user can interact with the MapServer application (browse, zoom, pan, query).
1.1. An Introduction to MapServer
4
MapServer Documentation, Release 7.0.6
Fig. 1.1: The basic architecture of MapServer applications.
1.1. An Introduction to MapServer
5
MapServer Documentation, Release 7.0.6
See also:
Templating
• MapServer CGI - The binary or executable file that receives requests and returns images, data, etc. It sits in the
cgi-bin or scripts directory of the web server. The Web server user must have execute rights for the directory that
it sits in, and for security reasons, it should not be in the web root. By default, this program is called mapserv
• Web/HTTP Server - serves up the HTML pages when hit by the user’s browser. You need a working Web
(HTTP) server, such as Apache or Microsoft Internet Information Server, on the machine on which you are
installing MapServer.
1.1.3 Installation and Requirements
Hardware Requirements
MapServer runs on Linux, Windows, Mac OS X, Solaris, and more. To compile or install some of the required programs, you may need administrative rights to the machine. People commonly ask questions about minimum hardware
specifications for MapServer applications, but the answers are really specific to the individual application. For development and learning purposes, a very minimal machine will work fine. For deployment, you will want to investigate
Optimization of everything from your data to server configuration.
Software Requirements
You need a working and properly configured Web (HTTP) server, such as Apache or Microsoft Internet Information
Server, on the machine on which you are installing MapServer.
If you are on a Windows machine, and you don’t have a web server installed, it is recommended that you use MS4W,
which will install a pre-configured web server, MapServer, MapCache, PHP, TinyOWS, and many more utilities.
Windows users can optionally check out the OSGeo4W installer as well.
This introduction will assume you are using an MS4W installation to follow along. Obtaining MapServer on Linux or
Mac OS X should be straightforward. Visit download for installing pre-compiled MapServer builds on Mac OS X and
Linux.
Note: The OSGeo-Live virtual machine contains MapServer ready to use as well.
You will also need a Web browser, and a text editor (vi, emacs, notepad++, textpad, homesite) to modify your HTML
and mapfiles.
Skills
In addition to learning how the different components of a MapServer application work together and learning Map File
syntax, building a basic application requires some conceptual understanding and proficiency in several skill areas.
You need to be able to create or at least modify HTML pages and understand how HTML forms work. Since the
primary purpose of a MapServer application is to create maps, you will also need to understand the basics of geographic
data and likely, map projections. As your applications get more complex, skills in SQL, DHTML/Javascript, Java,
databases, expressions, compiling, and scripting may be very useful.
1.1. An Introduction to MapServer
6
MapServer Documentation, Release 7.0.6
Windows Installation
Note: Pre-compiled binaries for MapServer are available from a variety of sources, refer to the windows section of
the Downloads page.
MS4W (MapServer for Windows) is the long-time installer that contains the Apache Web server, MapServer, and all
of its dependencies and tools; MS4W also contains several add-on packages, that contain over 60+ pre-configured
MapServer configuration files (mapfiles) and data. The following steps illustrate how to install MS4W:
1. Download MS4W (this example will use the -setup.exe file) from http://ms4w.com/
2. Execute (double-click) the .exe
3. Click the “Agree” button, to accept the license.
Note: MS4W uses the very open MIT/X license.
4. Select packages to install. Be sure to also select the “MapServer Itasca Demo Application”, as we will be using
this demo later.
Note: You can optionally install other packages, by clicking the checkbox beside the package name.
1.1. An Introduction to MapServer
7
MapServer Documentation, Release 7.0.6
5. Click the “Next” button
6. Click the “Browse...” button, to choose an installation path. You can safely leave the default (C:/), and the
installer will create C:/ms4w.
Note: Folders will spaces are supported, if you are using the -setup.exe installer.
1.1. An Introduction to MapServer
8
MapServer Documentation, Release 7.0.6
7. Click the “Next” button
8. Enter a port number to use for the Apache service. In most cases you can leave the port as 80, unless something
is using that port such as an IIS service.
Note: You can specify any number above 1024, such as 8081 or 8082.
1.1. An Introduction to MapServer
9
MapServer Documentation, Release 7.0.6
10. Click the “Install” button
1.1. An Introduction to MapServer
10
MapServer Documentation, Release 7.0.6
11. Once you see a message of “Installer Complete”, then click the “Close” button
1.1. An Introduction to MapServer
11
MapServer Documentation, Release 7.0.6
12. On your desktop, click on the “MS4W-Localhost” shortcut, and your browser should open http://127.0.0.1 that
loads an MS4W introduction page.
1.1. An Introduction to MapServer
12
MapServer Documentation, Release 7.0.6
13. Verify that MapServer is working, by clicking on the /cgi-bin/mapserv.exe link in the “Features” section of the
page.
Note: If MapServer is working properly, you will receive a message stating: “No query information to
decode. QUERY_STRING is set, but empty.“
1.1. An Introduction to MapServer
13
MapServer Documentation, Release 7.0.6
1.1.4 Introduction to the Mapfile
The .map file is the basic configuration file for data access and styling for MapServer. The file is an ASCII text file,
and is made up of different objects. Each object has a variety of parameters available for it. All .map file (or mapfile)
parameters are documented in the mapfile reference. A simple mapfile example displaying only one layer follows, as
well as the map image output:
MAP
NAME "sample"
STATUS ON
SIZE 600 400
SYMBOLSET "../etc/symbols.txt"
EXTENT -180 -90 180 90
UNITS DD
SHAPEPATH "../data"
IMAGECOLOR 255 255 255
FONTSET "../etc/fonts.txt"
#
# Start of web interface definition
#
WEB
IMAGEPATH "/ms4w/tmp/ms_tmp/"
IMAGEURL "/ms_tmp/"
1.1. An Introduction to MapServer
14
MapServer Documentation, Release 7.0.6
END # WEB
#
# Start of layer definitions
#
LAYER
NAME 'global-raster
TYPE RASTER
STATUS DEFAULT
DATA bluemarble.gif
END # LAYER
END # MAP
Fig. 1.2: Rendered Bluemarble Image
Note:
• Comments in a mapfile are specified with a ‘#’ character
• MapServer parses mapfiles from top to bottom, therefore layers at the end of the mapfile will be drawn last
(meaning they will be displayed on top of other layers)
• Using relative paths is always recommended
• Paths should be quoted (single or double quotes are accepted)
• The above example is built on the following directory structure:
– The mapfile could be placed anywhere, as long as it is accessible to the web server. Normally, one
would try to avoid placing it at a location that makes it accessible on the web. Let us say it is placed
in /home/msuser/mapfiles/
– The location of the font file is given relative to the map file, in this case: /home/msuser/etc/fonts.txt
– The location of the datasets (bluemarble.gif ) is given relative to the map file, in this case:
/home/msuser/data/
1.1. An Introduction to MapServer
15
MapServer Documentation, Release 7.0.6
– The location of the symbol file is given relative to the map file, in this case: /home/msuser/etc/symbols.txt
– The files generated by MapServer will be placed in the directory /ms4w/tmp/ms_tmp/. The web
server must be able to place files in this directory. The web server must make this directory available as /ms_tmp (if the web server is on www.ms.org, the web address to the directory must be:
httpd://www.ms.org/ms_tmp/.
MAP Object
MAP
NAME "sample"
EXTENT -180 -90 180 90 # Geographic
SIZE 800 400
IMAGECOLOR 128 128 255
END # MAP
• EXTENT is the output extent in the units of the output map
• SIZE is the width and height of the map image in pixels
• IMAGECOLOR is the default image background color
Tip: MapServer accepts colors in RGB values, or as a hexadecimal string.
Note: MapServer currently uses a pixel-center based extent model which is a bit different from what GDAL or WMS
use.
LAYER Object
• starting with MapServer 5.0, there is no limit to the number of layers in a mapfile
• the DATA parameter is relative to the SHAPEPATH parameter of the MAP object
• if no DATA extension is provided in the filename, MapServer will assume it is ESRI Shape format (.shp)
Raster Layers
LAYER
NAME "bathymetry"
TYPE RASTER
STATUS DEFAULT
DATA "bath_mapserver.tif"
END # LAYER
See also:
Raster Data
1.1. An Introduction to MapServer
16
MapServer Documentation, Release 7.0.6
Vector Layers
Vector layers of TYPE point, line, or polygon can be displayed. The following example shows how to display only
lines from a TYPE polygon layer, using the OUTLINECOLOR parameter:
LAYER
NAME "world_poly"
DATA 'shapefile/countries_area.shp'
STATUS ON
TYPE POLYGON
CLASS
NAME 'The World'
STYLE
OUTLINECOLOR 0 0 0
END # STYLE
END # CLASS
END # LAYER
Tip: MapServer accepts colors in RGB values, or as a hexadecimal string.
See also:
Vector Data
Fig. 1.3: Rendered Bluemarble image with vector boundaries
CLASS and STYLE Objects
• typical styling information is stored within the CLASS and STYLE objects of a LAYER
• starting with MapServer 5.0, there is no limit to the number of classes or styles in a mapfile
• the following example shows how to display a road line with two colors by using overlaid STYLE objects
1.1. An Introduction to MapServer
17
MapServer Documentation, Release 7.0.6
CLASS
NAME "Primary Roads"
STYLE
SYMBOL "circle"
COLOR 178 114 1
SIZE 15
END # STYLE
STYLE
SYMBOL "circle"
COLOR 254 161 0
SIZE 7
END # STYLE
END # CLASS
Tip: MapServer accepts colors in RGB values, or as a hexadecimal string.
Fig. 1.4: Rendered Bluemarble image with styled roads
SYMBOLs
• can be defined directly in the mapfile, or in a separate file
• the separate file method must use the SYMBOLSET parameter in the MAP object:
1.1. An Introduction to MapServer
18
MapServer Documentation, Release 7.0.6
MAP
NAME "sample"
EXTENT -180 -90 180 90 # Geographic
SIZE 800 400
IMAGECOLOR 128 128 255
SYMBOLSET "../etc/symbols.txt"
END # MAP
where symbols.txt might contain:
SYMBOL
NAME "ski"
TYPE PIXMAP
IMAGE "ski.png"
END # SYMBOL
and the mapfile would contain:
LAYER
...
CLASS
NAME "Ski Area"
STYLE
SYMBOL "ski"
END # STYLE
END # CLASS
END # LAYER
See also:
Cartographical Symbol Construction with MapServer, Symbology Examples, and SYMBOL
LABEL
• defined within a CLASS object
• the LABELITEM parameters in the LAYER object can be used to specify an attribute in the data to be used for
labeling. The label is displayed by the FONT, declared in the FONTSET file (set in the MAP object). The
FONTSET file contains references to the available font names. ENCODING describes which encoding is used
in the file (see Display of International Characters in MapServer).
An example LABEL object that references one of the above fonts might look like:
LABEL
FONT "sans-bold"
TYPE truetype
ENCODING "UTF-8"
SIZE 10
POSITION LC
PARTIALS FALSE
COLOR 100 100 100
OUTLINECOLOR 242 236 230
END # LABEL
See also:
LABEL, FONTSET
1.1. An Introduction to MapServer
19
MapServer Documentation, Release 7.0.6
Fig. 1.5: Rendered Bluemarble image with skier symbol
1.1. An Introduction to MapServer
20
MapServer Documentation, Release 7.0.6
Fig. 1.6: Rendered Bluemarble image with skier symbol and a label
1.1. An Introduction to MapServer
21
MapServer Documentation, Release 7.0.6
CLASS Expressions
MapServer supports three types of CLASS Expressions in a LAYER (CLASSITEM in LAYER determines the attribute
to be used for the two first types of expressions):
1. String comparisons
EXPRESSION "africa"
2. Regular expressions
EXPRESSION /^9|^10/
3. Logical expressions
EXPRESSION ([POPULATION] > 50000 AND '[LANGUAGE]' eq 'FRENCH')
Note: Logical expressions should be avoided wherever possible as they are very costly in terms of drawing time.
See also:
Expressions
INCLUDE
Added to MapServer 4.10, any part of the mapfile can now be stored in a separate file and added to the main mapfile
using the INCLUDE parameter. The filename to be included can have any extension, and it is always relative to the
main .map file. Here are some potential uses:
• LAYERs can be stored in files and included to any number of applications
• STYLEs can also be stored and included in multiple applications
The following is an example of using mapfile includes to include a layer definition in a separate file:
If ‘shadedrelief.lay’ contains:
LAYER
NAME 'shadedrelief'
STATUS ON
TYPE RASTER
DATA 'GLOBALeb3colshade.jpg'
END # LAYER
therefore the main mapfile would contain:
MAP
...
INCLUDE "shadedrelief.lay"
...
END # MAP
The following is an example of a mapfile where all LAYER s are in separate .lay files, and all other objects (WEB,
REFERENCE, SCALEBAR, etc.) are stored in a ”.ref” file:
1.1. An Introduction to MapServer
22
MapServer Documentation, Release 7.0.6
MAP
NAME "base"
#
# include reference objects
#
INCLUDE "../templates/template.ref"
#
# Start of layer definitions
#
INCLUDE "../layers/usa/usa_outline.lay"
INCLUDE "../layers/canada/base/1m/provinces.lay"
INCLUDE "../layers/canada/base/1m/roads_atlas_of_canada_1m.lay"
INCLUDE "../layers/canada/base/1m/roads_atlas_of_canada_1m_shields.lay"
INCLUDE "../layers/canada/base/1m/populated_places.lay"
END # MAP
Warning: Mapfiles must have the .map extension or MapServer will not recognize them. Include files can have
any extension you want, however.
See also:
INCLUDE
Get MapServer Running
You can test if MapServer is working by running the MapServer executable (mapserv) with the -v parameter on the
command line (./mapserv -v).
MS4W users that installed through the -setup.exe installer, can use the MS4W-Shell shortcut on the desktop, and then
run mapserv -v at the commandline. MS4W users who did not use the -setup.exe installer can open a Command
Prompt window, cd to their installation folder, and then execute setenv.bat, before testing a mapserv -v command.
Depending on your configuration, the output could be something like this:
MapServer version 7.0.1 (MS4W 3.1.4) OUTPUT=PNG OUTPUT=JPEG OUTPUT=KML
SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=CAIRO SUPPORTS=ICONV
SUPPORTS=FRIBIDI SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER
SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI
SUPPORTS=THREADS SUPPORTS=GEOS INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL
INPUT=SHAPEFILE
You can also send a HTTP request directly to the MapServer CGI program without passing any configuration variables (e.g. http://127.0.0.1/cgi-bin/mapserv.exe). If you receive the message, ‘No query information to decode.
QUERY_STRING not set.’, your installation is working.
Get Demo Running
Warning: MS4W users do not have to do this step, as the above instructions already installed the demo. You
should see a “MapServer Itasca Demo Application” section on the bottom of the page (after clicking the MS4WLocalhost shortcut).
1.1. An Introduction to MapServer
23
MapServer Documentation, Release 7.0.6
Download the MapServer Demo. UnZip it and follow the directions in ReadMe.txt. You will need to move the demo
files to their appropriate locations on your web server, and modify the Map File and HTML pages to reflect the paths
and URLs of your server. Next, point your browser to init.html and hit the ‘initialize button’. If you get errors, verify
that you have correctly modified the demo files.
1.1.5 Making the Site Your Own
Now that you have a working MapServer demo, you can use the demo to display your own data. Add new LAYERs to
your Map file that refer to your own geographic data layers (you will probably want to delete the existing layers or set
their status to OFF).
Unless you are adding layers that fall within the same geographic area as the demo, modify MAP EXTENT to match
the extent of your data. To determine the extent of your data, you can use ogrinfo. If you have access to a GIS, you
could use that as well. The MAP EXTENT needs to be in the units of your output projection.
If you add geographic data layers with different geographical reference systems, you will need to modify your Map
File to add a PROJECTION block to the MAP (defines the output projection / geographical reference system) and each
of the LAYERs (defines the geographical reference system of the layer dataset).
Adding Data to Your Site
MapServer supports several data input formats ‘natively’, and many more if it is compiled with the Open Source
libraries GDAL and OGR.
Vector Data
Vector data includes features made up of points, lines, and polygons. MapServer support the ESRI Shape format by
default, but it can be compiled to support spatially enabled databases such as PostgreSQL-PostGIS, and file formats
such as Geography Markup Language (GML), MapInfo, delimited text files, and more formats with OGR.
See the Vector Data reference for examples on how to add different geographic data sources to your MapServer project.
Raster Data
Raster data is image or grid data. Through GDAL, MapServer supports most raster formats - see the GDAL format
list. More specific information can be found in the Raster Data reference.
Note: Since version 6.2 MapServer relies on GDAL for all raster access.
Projections
Because the earth is round and your monitor (or paper map) is flat, distortions will occur when you display geographic
data in a two-dimensional image. Projections allow you to represent geographic data on a flat surface. In doing
so, some of the original properties (e.g. area, direction, distance, scale or conformity) of the data will be distorted.
Different projections excel at accurately portraying different properties. A good primer on map projections can be
found at the University of Colorado.
With MapServer, if you keep all of your spatial data sets in the same projection (or unprojected Latitude and Longitude), you do not need to include any projection info in your Map File. In building your first MapServer application,
this simplification is recommended.
1.1. An Introduction to MapServer
24
MapServer Documentation, Release 7.0.6
On-the-fly projection can be accomplished when MapServer is compiled with PROJ.4 support. Instructions on how to
enable PROJ.4 support on Windows can be found on the Wiki.
1.1.6 Enhancing your site
Adding Query Capability
There are two primary ways to query spatial data. Both methods return data through the use of templates and CGI
variable replacement. A QUERYMAP can be used to map the results of the query.
To be queryable, each mapfile LAYER must have a TEMPLATE defined, or each CLASS within the LAYER must have a
TEMPLATE defined. More information about the CGI variables used to define queries can be found in the MapServer
CGI Reference.
Attribute queries
The user selects features based on data associated with that feature. ‘Show me all of the lakes where depth is greater
than 100 feet’, with ‘depth’ being a field in the Shape dataset or the spatial database. Attribute queries are accomplished
by passing query definition information to MapServer in the URL (or form post). Mode=itemquery returns a single
result, and mode=itemnquery returns multiple result sets.
The request must also include a QLAYER, which identifies the layer to be queried, and a QSTRING which contains
the query string. Optionally, QITEM, can be used in conjunction with QSTRING to define the field to be queried.
Attribute queries only apply within the EXTENT set in the map file.
Spatial queries
The user selects features based on a click on the map or a user-defined selection box. Again the request is passed
through a URL or form post. By setting mode=QUERY, a user click will return the one closest feature. In
mode=NQUERY, all features found by a map click or user-defined selection box are returned. Additional query
options can be found in the CGI documentation.
Interfaces
See: OpenLayers http://openlayers.org, GeoMOOSE http://geomoose.org
Note: MS4W users can install both OpenLayers and GeoMOOSE as ready-to-use packages.
Data Optimization
Data organization is at least as important as hardware configuration in optimizing a MapServer application for performance. MapServer is quite efficient at what it does, but by reducing the amount of processing that it needs to do at the
time of a user request, you can greatly increase performance. Here are a few rules:
• Index Your data - By creating spatial indexes for your Shape datasets using shptree. Spatial indexes should
also be created for spatially aware databases such as PostGIS and Oracle Spatial.
• Tile Your Data - Ideally, your data will be ‘sliced up’ into pieces about the size in which it will be displayed.
There is unnecessary overhead when searching through a large Shape dataset or image of which you are only
going to display a small area. By breaking the data up into tiles and creating a tile index, MapServer only
needs to open up and search the data files of interest. Shape datasets can be broken into smaller tiles and then a
1.1. An Introduction to MapServer
25
MapServer Documentation, Release 7.0.6
tileindex Shape dataset can be created using the tile4ms utility. A tileindex Shape dataset for raster files can also
be created.
• Pre-Classify Your Data - MapServer allows for the use of quite complex EXPRESSIONs to classify data.
However, using logical and regular expressions is more resource intensive than string comparisons. To increase
efficiency, you can divide your data into classes ahead of time, create a field to use as the CLASSITEM and
populate it with a simple value that identifies the class, such as 1,2,3, or 4 for a four class data set. You can then
do a simple string comparison for the class EXPRESSION.
• Pre-Process Your Images - Do resource intensive processing up front. See the Raster Data reference for more
info.
• Generalize for Overview - create a more simple, generalized data layer to display at small scales, and then use
scale-dependent layers utilizing LAYER MINSCALE and LAYER MAXSCALE to show more detailed data layers
as the user zooms in. This same concept applies to images.
See also:
Optimization
1.1.7 How do I get Help?
Documentation
• Official MapServer documentation lives here on this site.
• User contributed documentation exists on the MapServer Wiki.
Users Mailing List
Register and post questions to the MapServer Users mailing list. Questions to the list are usually answered quickly
and often by the developers themselves. A few things to remember:
1. Search the archives for your answer first, people get tired of answering the same questions over and over.
2. Provide version and configuration information for your MapServer installation, and relevant snippets of your
map and template files.
3. Always post your responses back to the whole list, as opposed to just the person who replied to your question.
IRC
MapServer users and developers can be found on Internet Relay Chat. The channel is #mapserver on irc.freenode.net.
Reporting bugs
Software bugs are reported on the MapServer issue tracker. Documentation bugs are reported on the MapServer
documentation issue tracker.
Tutorial
Here is a quick tutorial for new users.
1.1. An Introduction to MapServer
26
MapServer Documentation, Release 7.0.6
Test Suite
Download the MapServer Test Suite for a demonstration of some MapServer functionality.
Books
Web Mapping Illustrated, a book by Tyler Mitchell that describes well and provides real-world examples for the use
of Web mapping concepts, Open Source GIS software, MapServer, Web services, and PostGIS.
Mapping Hacks, by Schuyler Erle, Rich Gibson, and Jo Walsh, creatively demonstrates digital mapping tools and
concepts. MapServer only appears in a handful of the 100 hacks, but many more are useful for concepts and inspiration.
Beginning MapServer: Opensource GIS Development, by Bill Kropla. According to the publisher, it covers installation and configuration, basic MapServer topics and features, incorporation of dynamic data, advanced topics,
MapScript, and the creation of an actual application.
1.1. An Introduction to MapServer
27
CHAPTER 2
Tutorial
2.1 MapServer Tutorial
Author Pericles S. Nacionales
Contact pnaciona at gmail.com
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Updated 2017-02-08
This tutorial (initially created in the early-2000’s by Perry) was designed to give new users a quick (relatively speaking)
introduction to the concepts behind MapServer. It is arranged into four sections with each section having one or more
examples and increasing in complexity. Users can jump to any section at any time although it is recommended that
absolute beginners work on the first three sections sequentially.
Section one focuses on basic MapServer configuration concepts such as layer and class ordering, using vector and
raster data, projections and labeling. Section two provides examples on how to use HTML templates to create a simple
interface for an interactive web mapping application. Section three introduces the use of HTML templates to provide
a “query” interface. Finally, section four introduces some advanced user interface concepts.
2.1.1 Tutorial background
Tutorial Timeframe
While some users can go through this tutorial in one day, those who work on each example in detail can probably
expect to finish in one week.
Tutorial Data
The dataset used in this tutorial was taken from the U.S. Department of the Interior’s National Atlas of the United States
(which is now hosted by data.gov). The dataset was clipped to the upper great lakes region (Minnesota, Michigan,
and Wisconsin) to reduce storage size. Additional raster images were added courtesy of the TerraSIP project at the
University of Minnesota. When using this tutorial, you are encouraged to use your own dataset.
Like MapServer itself, this tutorial is open and customizable to anyone. This was done in the hope that someone (or
some folks) will help design and develop it further.
Download the data (and all html files) for this tutorial at http://download.osgeo.org/mapserver/docs/mapserver-tutorial.
zip.
28
MapServer Documentation, Release 7.0.6
Before Using the Tutorial
There are some prerequisites to using this tutorial:
1. Users will need to have a web server installed and running on their computer. This web server has to have
support for common gateway interface (CGI) programs.
2. Users should have a basic understanding of web servers and internet security. A poorly configured web server
can easily be attacked by malicious people. At the very least your software installation will be corrupted and
you’ll lose hours of productivity, at worst your computer can be used to attack other computers on the internet.
3. It is recommended that users of this tutorial read the Introduction to MapServer before proceeding with this
tutorial.
4. To use this tutorial, users will need to have a MapServer CGI program (mapserv or mapserv.exe) installed in
their systems. MapServer source code is available for download here. Documentation exists on how to compile
and install MapServer:
• for UNIX users, please read the MapServer UNIX Compilation and Installation HOWTO.
• Windows users should read the MapServer Win32 Compilation and Installation HOWTO
In addition, precompiled binaries exist for a number of platform (see the download page).
Windows, UNIX/Linux Issues
Paths
This tutorial was created on Linux/UNIX but should work with minimal changes on Windows platform. The main
differences are the paths in the map files. Windows users need to specify the drive letter of the hard disk where their
tutorial files reside. Here’s an example:
A UNIX map file might include a parameter like this:
SHAPEPATH "/data/projects/tutorial/data"
In Windows, the same parameters might look like this:
SHAPEPATH "C:/data/projects/tutorial/data"
or:
SHAPEPATH "C:\data\projects\tutorial\data".
Notice that either slash or backslash works in Windows. The usual backslash may work well for you if you want to
make a distinction between virtual (as in URLs or web addresses) and local paths in your map file. However, if you
plan to move your application to UNIX at some point, you’ll have the tedious task of switching all backslashes to
slashes.
While we’re on the subject of paths, keep in mind that paths in mapfiles are typically relative to the system’s root
directory: the slash (“/”) in UNIX or some drive letter (“C:”) in Windows. This is true except when specifically asked
to enter a URL or when referencing a URL. When working with HTML template files, paths are relative to the web
server’s root directory. i.e., “/tutorial/” is relative to “http://demo.mapserver.org/”. Please read http://www.alistapart.
com/articles/slashforward/ for a few insights on URLs.
2.1. MapServer Tutorial
29
MapServer Documentation, Release 7.0.6
Executable
Another issue is that UNIX executable files don’t require a .EXE or .COM extensions, but they do in Windows. If
you are using Windows, append .exe to all instances of “/cgi-bin/mapserv” or “/cgi-bin/mapserv50” to make it “/cgibin/mapserv.exe” or “/cgi-bin/mapserv50.exe”.
Other Resources
Other documentation exist to give you better understanding of the many customizations MapServer offer. Please visit
the MapServer documentation page at http://www.mapserver.org/documentation.html. There you will find several
HOWTO documents, from getting started to using MapScript, a scripting interface for MapServer.
Back to Tutorial home | Proceed to Section 1
2.1.2 Section 1: Static Maps and the MapFile
• Take a Shapefile dataset. Any Shapefile dataset. We can use MapServer to display that Shapefile dataset in a
web browser. Look...
– Example 1.1 - A map with a single layer
• We can display the same Shapefile dataset repeatedly. We can display the polygon attributes in one LAYER and
the line attributes in another...
– Example 1.2 - A map with two layers
• And we can select which parts of the Shapefile dataset to display. We do this using the CLASS object...
– Example 1.3 - Using classes to make a “useful” map
• We can also label our maps...
– Example 1.4 - Labeling layers and label layers
• Or add raster data such as satellite images, aerial photographs, or shaded reliefs...
– Example 1.5 - Adding a raster layer
• We can reproject our data from just about any projection to just about any... Yeah, check it out!
– Example 1.6 - Projection/Reprojection
• And we can use layers from other map servers on the Internet (for example WMS servers)...
– Example 1.7 - Adding a WMS layer
• MapServer can output to various formats such as PDF and GeoTIFF.
– Example 1.8 - A different output format
• MapServer not only generates static maps, it can also create interactive maps...
– Example 1.9 - The difference between map mode and browse mode
Back to Tutorial home | Proceed to Section 2
2.1. MapServer Tutorial
30
MapServer Documentation, Release 7.0.6
2.1.3 Section 2: CGI variables and the User Interface
So far we have only looked at the mapfile when creating maps. In creating web mapping applications, it is usually
our intention to make maps that can be changed by the user (of the application) interactively. That is, a user should be
able to change the content of (or the information in) the map. To accomplish this interactivity, we use the MapServer
HTML templates.
HTML Templates
A MapServer HTML template is essentially an HTML file with a few MapServer specific tags. These tags are the
MapServer CGI variables and are enclosed in square brackets “[]”. When the MapServer CGI program processes an
application, it first parses the query string and the mapfile, and produces the necessary output. Some of this output
will need to be written to the HTML template file which you would have to also specify in the mapfile using the web
template keyword (or in a separate HTML initialization file). The CGI program will replace all the variables in the
HTML template with the proper value before sending it back to the web browser. If you are to directly view an HTML
template in a web browser, there won’t be any maps rendered and you will instead get blank images and other junk.
Variables
MapServer provides several variables for web mapping: the “img” variable which you’ve seen in Example 1.9 is but
one example. There area few core CGI variables originally designed as part of the mapping interface but practically
all the mapfile parameters can be defined as variables. The definitive reference to the MapServer CGI variables can be
found here.
We can also define our own variables, which MapServer will pass along to our application. For example, we can create
a variable called “root” to represent the root directory of this tutorial, the value for “root” will then be “/tutorial”.
When the MapServer CGI program processes our HTML template, it will replace every instance of he “[root]” tag
with “/tutorial”. You will see this in action for each of the following examples.
Examples
So, let’s build an interactive interface for our application...
• Users of a web mapping application should be able to pan and zoom on the map: Example 2.1 - Pan and Zoom
Controls
• They also should be able to turn on and off layers on a map: Example 2.2 - Layer Control
• A map should always include a scalebar. Example 2.3 - Adding a Scalebar
• If users are to navigate through the map, a reference map should be provided: Example 2.4 - Adding a Reference
Map
• The map should include a legend. Example 2.5- Adding a Legend
Back to Section 1 index | Proceed to Section 3
2.1.4 Section 3: Query and more about HTML Templates
To learn more about query and HTML templates with MapServer, see examples 3.1 to 3.4 in the Tutorial Viewer.
Back to Section 2 index | Proceed to Section 4
2.1. MapServer Tutorial
31
MapServer Documentation, Release 7.0.6
2.1.5 Section 4: Advanced User Interfaces
To learn more about advanced navigation such as pan and rubber-band zoom with Javascript and MapServer CGI, see
examples 4.1 to 4.4 in the Tutorial Viewer.
Back to Section 3 index | Tutorial home
Begin tutorial
2.1. MapServer Tutorial
32
CHAPTER 3
Installation
3.1 Installation
3.1.1 Compiling on Unix
Author Howard Butler
Contact hobu.inc at gmail.com
Author Thomas Bonfort
Contact thomas.bonfort at gmail.com
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2016-06-13
Table of Contents
• Compiling on Unix
– Introduction
– Obtaining the necessary software
– Anti-Grain Geometry Support
– OGC Support
– Spatial Warehousing
– Compiling
– Installation
Introduction
The University of Minnesota’s MapServer is an open-source and freely available map rendering engine for the web.
Due to its open-source nature, it can be compiled on a wide variety of platforms and operating systems. We will focus
on how to obtain, compile and install MapServer on UNIX-like platforms.
33
MapServer Documentation, Release 7.0.6
Note: Detailed configuration options are maintained in the INSTALL.CMAKE file packaged at the root of the source
directory:
You might also check the MapServerCompilation wiki page for additional information.
Obtaining the necessary software
You can obtain the MapServer source code as well as the demo package from the download section.
You can also get the latest MapServer source code from git.
Required External Libraries
• libpng: libpng should be on your system by default. Versions back to 1.2.7 should work.
• freetype: Version 2.x or above is required.
• libjpeg: libjpeg allows MapServer to render images in JPEG format. A sufficient version should be installed by
default on your system (probably version 6b from 1998).
Warning: Direct JPEG support was deprecated in MapServer 5.8+, and you should now depend on GDAL
for raster read support in MapServer. JPEG support is however still required for producing (i.e. writing)
images.
• zlib: Zlib should be on your system by default. Though not used directly by mapserver, it’s a mandatory
dependency of libpng.
Highly Recommended Libraries
• libproj: libproj provides projection support for MapServer. Version 4.4.6 or greater is required.
• libcurl: libcurl is the foundation of OGC (WFS/WMS/WCS) client and server support. Version 7.10 or greater
is required.
• OGR: OGR provides access to a lot of vector formats.
• GDAL: GDAL provides access to a lot of raster formats.
Optional External Libraries
• GEOS: GEOS allows MapServer to do spatial predicate and algebra operations (within, touches, etc & union,
difference, intersection).
New in version 4.10.
• libxml: libxml is required to use OGC SOS support in MapServer
New in version 4.10.
• Oracle Spatial OCI: The client libraries for your platform are available for download from Oracle’s website.
Ideally, your client library matches the database you are querying from, but this is not a hard requirement.
3.1. Installation
34
MapServer Documentation, Release 7.0.6
• libpq: libpq is required to support the use of PostGIS geometries within the PostgreSQL database. Ideally, your
client library matches the database you are querying from.
• giflib: libgif / libgif is is used for reading GIF files used as PIXMAP symbols.
• FastCGI: FastCGI is a popular protocol for interfacing MapServer with various web servers. You will need to
install the development package. More details on how to use this feature in MapServer is here FastCGI. On
Ubuntu, that would be:
$ apt-get -y install libfcgi-dev
• Cairo (SVG, PDF) support: This library is required to produce PDF and SVG outputs. If you’re on an ubuntu
system, it can be installed with “apt-get install -y libcairo2-dev”
• KML support: This renderer is has no external dependency.
• HarfBuff: Support complex script shaping (to simplify: the tool that will insert ligatures between characters).
Harfbuzz algorithms will be applied on text strings that have been determined to not be latin (i.e. the slowdown
induced by harfbuzz is limited to those languages that actually require shaping). Requires FriBidi.
See also:
rfc98
New in version 7.0.
• MySQL: Support joining with MySQL (the WITH_MYSQL option).
Optional Features
• Cairo SVG parser support: The WITH_SVGCAIRO option is part of a proposal to improve SVG support. Using
this feature requires installing the libsvg-cairo library available here: http://cairographics.org/snapshots/ . You
will need to compile and install cairo, libsvg, and libsvg-cairo.
• SVG support can be enabled either through the unmaintained libsvg / libsvg-cairo combo, or through librsvg
(the WITH_RSVG option) at the cost of more dependencies. Use librsvg if your distro provides a package for
it, or fall back to libsvgcairo if the cost of compiling the librsvg dependencies is too important.
Anti-Grain Geometry Support
Since version 5.0 MapServer supports the AGG rendering backend. MapServer 5.6+ embeds it directly in the source
tree and you do not have to do anything special to have support for it.
OGC Support
MapServer provides support for many OGC specifications. For an overview, see MapServer OGC Specification support.
WMS support
WMS Server
Support for WMS server is automatically enabled.
You can check it by looking for the following in your configure output:
3.1. Installation
35
MapServer Documentation, Release 7.0.6
--
* WMS SERVER: ENABLED
If, for some reason you don’t want WMS support, you can force it off using “-DWITH_WMS=OFF”.
More information on using this feature is available in WMS Server.
WMS Client
Cascading is also supported. This allows mapserver to transparently fetch remote layers over WMS, basically acting
like a client, and combine them with other layers to generate the final map.
In order to enable this feature, you will need to pass the WITH_CLIENT_WMS option to the configure script.
MapServer will automatically look for libcurl, which is also required.
To verify that this feature is enabled, check the configure output for:
--
* WMS CLIENT: ENABLED
Note: This feature is disabled by default, you have to specifically request it.
More information on using this feature is available in WMS Client.
WFS support
WFS Server
Support for WFS server is enabled by default. OGR and PROJ.4 support is required.
To verify that this feature is enabled, check the configure output for:
--
* WFS SERVER: ENABLED
If, for some reason you don’t want WFS support, you can force it off using “-DWITH_WFS=OFF”.
More information on using this feature is available in WFS Server.
WFS Client
MapServer can also act as a WFS client. This effectively means that MapServer reads it’s data from a remote server’s
WFS output and renders it into a map, just like it would when reading data from a shapefile.
In order to enable this feature, you will need to make sure you have OGR (built with Xerces support) and PROJ.4
support, and pass the WITH_CLIENT_WFS option to your configure script. MapServer will automatically look for
libcurl, which is also required.
To verify that this feature is enabled, check the configure output for:
--
* WFS CLIENT: ENABLED
Note: This feature is disabled by default, you have to specifically request it.
More information on using this feature is available in WFS Client.
3.1. Installation
36
MapServer Documentation, Release 7.0.6
WCS Server
Support for WCS server is enabled by default. WCS must be compiled against certain libraries. More information on
this service is available in WCS Server.
To verify that this feature is enabled, check the configure output for:
--
* WCS SERVER: ENABLED
If, for some reason you don’t want WCS support, you can force it off using “-DWITH_WCS=OFF”.
SOS Server
Support for SOS is enabled by using the WITH_SOS option. More information on this service is available in SOS
Server.
To verify that this feature is enabled, check the configure output for:
--
* SOS SERVER: ENABLED
Note: This feature is disabled by default, you have to specifically request it.
Spatial Warehousing
MapServer can use a wide variety of sources of data input. One of the solutions growing in popularity is to use spatially
enabled databases to store data, and to use them directly to draw maps for the web.
Here you will find out how to enable mapserver to talk to one of these products. Please refer to the MapFile reference
for more details on how to use these. This section only details how to compile MapServer for their use.
PostGIS
PostGIS adds support for geographic objects to the PostgreSQL object-relational database. In effect, PostGIS “spatially enables” the PostgreSQL server, allowing it to be used as a backend spatial database for geographic information
systems (GIS), much like ESRI’s SDE or Oracle’s Spatial extension. PostGIS is included in many distributions’
packaging system, but you can also roll your own if needed.
MapServer can use PostGIS as a data source. PostGIS support is enabled by default.
To verify that this feature is enabled, check the configure output for:
--
* POSTGIS: /usr/local/pgsql/lib/libpq.so
If, for some reason you don’t want PostGIS support, you can force it off using “-DWITH_POSTGIS=OFF”.
To help cmake find your PostGIS installation, you can use the CMAKE_PREFIX_PATH option (for instance “DCMAKE_PREFIX_PATH=/usr/local/pgsql”).
Oracle Spatial
Oracle’s Spatial is also supported by MapServer. In order to connect to it, you will need to compile MapServer against
the Oracle libraries by using the WITH_ORACLESPATIAL option. You will very likely need an ORACLE_HOME
environment variable set to have it configure things correctly.
3.1. Installation
37
MapServer Documentation, Release 7.0.6
To verify that this feature is enabled, check the configure output for:
--
* Oracle Spatial: <path to oracle spatial shared library>
Compiling
First prepare the ground by making sure all of your required and/or recommended libraries are installed before attempting to compile MapServer. This will make your life much less complicated ;). Here is the order that I usually
use:
1. Compile GDAL/OGR. Describing how to compile GDAL/OGR is beyond the scope of this document. If you
have requirements for lots of different formats, make sure to install those libraries first. I often find that building
up a GDAL/OGR library often takes as long as compiling MapServer itself!
2. Compile PROJ.4. PROJ.4 is a straight-forward configure/make/make install library.
3. Compile libcurl. libcurl is a straight-forward configure/make/make install library. This library is only used
along with other features, so “–with-curl-config” won’t do anything unless something like “–with-wmsclient”
or “–with-wfsclient” is also selected.
Note: If you want to configure MapServer to use SSL when accessing a WMS/WFS server libcurl must be
configured / compiled with the “–with-ssl” option. Details about how to set this up is available in How to set up
MapServer as a client to access a service over https.
4. Compile/install optional libraries. These might include PostGIS, Oracle Spatial, AGG, Ming, PDFlib, or MyGIS. Mix and match as you need them.
5. Unpack the MapServer tarball and cd into the mapserver directory:
$ tar -zxvf mapserver-X.Y.Z.tar.gz
6. Create the build directory and configure your environment.
Create the build directory:
$ cd mapserver-X.Y.Z
$ mkdir build
$ cd build
Configure your environment using “cmake” (this is an example):
$ cmake -DCMAKE_INSTALL_PREFIX=/opt \
-DCMAKE_PREFIX_PATH=/usr/local/pgsql/91:/usr/local:/opt \
-DWITH_CLIENT_WFS=ON \
-DWITH_CLIENT_WMS=ON \
-DWITH_CURL=ON \
-DWITH_SOS=ON \
-DWITH_PHP=ON \
-DWITH_PERL=ON \
-DWITH_RUBY=ON \
-DWITH_JAVA=ON \
-DWITH_CSHARP=ON \
-DWITH_PYTHON=ON \
-DWITH_SVGCAIRO=ON \
-DWITH_ORACLESPATIAL=ON \
-DWITH_MSSQL2008=ON \
../ >../configure.out.txt
3.1. Installation
38
MapServer Documentation, Release 7.0.6
The following options are enabled by default (version 7.0: WITH_PROJ, WITH_WMS, WITH_FRIBIDI,
WITH_HARFBUFF, WITH_ICONV, WITH_CAIRO, WITH_FCGI, WITH_GEOS, WITH_POSTGIS,
WITH_GDAL, WITH_OGR, WITH_WFS, WITH_WCS, WITH_LIBXML2, WITH_GIF.
If you want to also build a static version
LINK_STATIC_LIBMAPSERVER options can be used,
of
the
library,
the
BUILD_STATIC
and
There are a number of other options available. For an up-to-date list of available cmake options, refer to the
CMakeLists.txt.
It can be a good idea to place the configuration commands in a file and change its mode to executable (+x) to
save typing and have a record of how MapServer was configured.
7. Now that you have configured your build options and selected all the libraries you wish mapserver to use, you’re
ready to compile the source code.
This is actually quite simple, just execute “make”:
$ make
8. Install the MapServer libraries:
# make install
To make sure all went well, look for the file called mapserv:
$ ls -al mapserv
-rwxr-xr-x 1 user user 13745 mars
11 17:45 mapserv
A simple test is to try and run it:
$ ./mapserv
This script can only be used to decode form results and
should be initiated as a CGI process via a httpd server.
The message above is perfectly normal, and means exactly what it says. If you get anything else, something
went terribly wrong.
Installation
MapServer binary
The MapServer program itself consists of only one file, the “mapserv” binary executable. This is a CGI executable,
meant to be called and run by your web server.
In this section, we will assume you are running Apache under its default directory structure in /usr/local/apache2. You
may need to have privileges to edit your httpd.conf (the main apache configuration file), or have someone (such as
your webmaster) help you with the configuration details.
If you don’t have apache installed, and you want apache, php, fastcgi, etc, that might look something like this:
$ apt-get install -y apache2 apache2-mpm-worker libapache2-mod-fastcgi
$ a2enmod actions fastcgi alias
$ apt-get install libapache2-mod-php5 php5-common php5-cli php5-fpm php5
The main goal is to get the “mapserv” binary installed in a publicly accessible directory that is configured to run CGI
programs and scripts.
3.1. Installation
39
MapServer Documentation, Release 7.0.6
1. Locate your cgi-bin directory. Under a default configuration, the CGI directory is “/usr/local/apache2/cgi-bin”
(RedHat: “/home/httpd/cgi-bin”, Debian: “/usr/lib/cgi-bin”). If you’re using apache, there should be a ScriptAlias directive in your http.conf, or default site, something like:
$ cat /etc/apache2/sites-available/default | grep 'cgi-bin'
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
2. Locate the installation path of your freshly compiled mapserv executable. This is shown when you run “make
install”, something like this:
-- Installing: /usr/local/bin/mapserv
-- Set runtime path of "/usr/local/bin/mapserv" to
"/usr/local/lib:/usr/local/pgsql/91/lib"
3. You’ll want to setup a symlink to that executable from your cgi-bin directory:
# ln -s /usr/local/bin/mapserv /usr/lib/cgi-bin/mapserv
Warning: Make sure you are linking against the installed mapserv file (after running ‘make install’) and
NOT against where it was compiled in your source tree.
Testing your new Install
Placing the mapserv file in this directory makes it accessible by the following URL: “http://yourhostname.com/cgi-bin/
mapserv”. When accessing this URL through your web client, you should expect the following output if all has worked
well: “No query information to decode. QUERY_STRING is set, but empty.” If you get this message, you’re done
installing MapServer.
Common problems
File permissions
The most common problem one is likely to encounter when attempting to install the binary are permissions issues:
• You do not have write permissions into your web server’s CGI Directory. Ask your webmaster to install the file
for you.
• The web server gives you a “403 Permission denied” error. Make sure the user the web server runs as (usually
“nobody”) has execute permission on the binary executable. Making the file world executable is perfectly fine
and safe:
$ chmod o+x mapserv
Apache errors
You may receive a few different type of errors as well if your web server configuration isn’t right:
• 500 Internal server error: This is a fairly generic error message. All it basically tells you is that the web server
was unsuccessful in running the program. You will have to consult the web server’s error log to find out more,
and may need to enlist the help of your webmaster/system administrator. The apache docs also have pointers on
setting up cgi-bin.
3.1. Installation
40
MapServer Documentation, Release 7.0.6
:: Check your server logs $ tail /var/log/apache2/error.log
Where to go once you’ve got it compiled
The An Introduction to MapServer document provides excellent coverage of getting started with MapServer.
3.1.2 Compiling on Win32
Author Pericles Nacionales
Contact pnaciona at gmail.com
Table of Contents
• Compiling on Win32
– Introduction
– Compiling
– Set up a Project Directory
– Download MapServer Source Code and Supporting Libraries
– The MapServer source code
– Set Compilation Options
– Compile the Libraries
– Compile MapServer
– Compiling MapServer with PostGIS support
– Common Compiling Errors
– Installation
– Other Helpful Information
– Acknowledgements
Introduction
This document provides a simple set of compilation procedures for MapServer on Win32 platforms.
If you’ve made it this far, chances are you already know about MapServer and are at least tempted to try compiling it
for yourself. Pre-compiled binaries for MapServer are available from a variety of sources. Refer to windows. Building
MapServer for win32 platforms can be a daunting task, so if existing binaries are sufficient for your needs, it is strongly
advised that they be used in preference to trying to build everything from source.
However, there can be a variety of reasons to want to build MapServer from source on win32. Reasons include the
need to enable specific options, to build with alternate versions of support libraries (such as GDAL), the desire for
MapScript support not part of the core builds, the need to debug and fix bugs or even to implement new features in
MapServer. To make it easy for users and developers, I’ve made a list of steps to compile MapServer. Background
information is provided in each step, along with examples. Each example is a continuation of the previous one and in
the end will produce the MapServer DLL (libmap.dll), the CGI program (the mapserv.exe), and utility programs.
3.1. Installation
41
MapServer Documentation, Release 7.0.6
Warning: This document may refer to older library versions. You may want to try to use more recent library
versions for your build.
Compiling
If you are new to Windows programming, please follow this document carefully. The compilation steps are fairly
simple but I’ve added a few blurbs in each step to help you understand how MapServer compiles. For the more
experienced programmers, perhaps reading the README.Win32 that accompanies the MapServer source code would
be more useful. For those who are antsy, compiling MapServer involves download and unpacking the source codes,
editing the make files, and invoking Microsoft’s Visual C++ compiler from the command prompt. The resulting
mapserv.exe is the CGI program that installs in the cgi-bin directory of your web server.
For those who are willing to take the time, the compilation steps follow.
Set up a Project Directory
Before you start to compile MapServer, I recommend creating a directory called “projects” where you can put the
source code for MapServer and its supporting libraries. Since you will be working with DOS-style commands, you
might as well get used to the Windows command prompt. For Windows 95/98 users the command processor would be
called command.com. For Windows NT/2000/XP, it would be cmd.exe. So fire up the old command prompt and go to
the drive where you want to create the project directory.
Here is an example of how to create a directory called projects on the C: drive:
C:\Users> mkdir C:\Projects
To go to that directory:
C:\Users> cd \Projects
C:\Projects>
From the projects directory, you can extract the source codes for MapServer and its libraries. Now you’re ready to
download the source codes.
Download MapServer Source Code and Supporting Libraries
After creating a project directory, download the MapServer source code and the codes for the supporting libraries and
save the source code packages in the newly created “projects” directory. These source codes are usually packaged as
ZIP, or as UNIX TAR and GZIP files. You’ll need a software that can unzip these packages. 7-Zip is an example of
software that can handle these files.
Cygwin is a free, open-source software package which is a port of these tools on Windows. You can use the gzip and
tar utilities from this tool collection. Cygwin is available from http://www.cygwin.com.
In order to compile the MapServer CGI program, you must download a few required and optional libraries. At
its simplest configuration, MapServer only requires the GD (to provide the image output) and REGEX (to provide
regular expression support) libraries. This configuration allows the developer/data provider to use shapefiles as input
and, depending on the version of GD library used, GIF or PNG images as output. Additional libraries are needed for
input data in alternative formats. The libraries that work with MapServer are listed below.
3.1. Installation
42
MapServer Documentation, Release 7.0.6
The MapServer source code
The MapServer source code can be downloaded from the download page. If you’d like to get the current development
version of the software, following the nightly snapshot link under the Interim Builds title. The absolute latest copy of
the source code can be obtained from git; however, the GitHub repository does not contain several important source
files (maplexer.c, mapparser.c and mapparser.h) normally generated on unix, so if possible, using a nightly snaphot is
substantially easier than working directly from git.
Required Libraries
GD Library: MapServer uses the GD graphics library for rendering map images in GIF, PNG and JPEG format.
These map images are displayed in web browser clients using the MapServer CGI. The current official version
of GD is 2.0.33. The distributed makefiles are setup to use the prebuilt GD Win32 DLL binaries which include
GD, libjpeg, libpng, libz, libgif and FreeType 2 all within one DLL. This package is generally listed as “Windows
DLL .zip” and the latest version is normally available at http://www.boutell.com/gd/http/gdwin32.zip.
Regex: Regex is the regular expression library used by MapServer. It can be downloaded at http://ftp.gnu.org/old-gnu/
regex/regex-0.12.tar.gz
Optional Libraries
JPEG library: This library is required by GD to render JPEG images, if building GD from source. You may download this library at http://www.ijg.org/files/jpegsrc.v6b.tar.gz
PNG library: This library is required by GD to render PNG images, if building GD from source. You may download
this library at http://sourceforge.net/projects/libpng/
Zlib: This library is required by libpng to provide graphics compression support. It can be downloaded along with
the PNG library, or at http://www.gzip.org/zlib.zip .
FreeType 2: FreeType provides TrueType support in MapServer via GD. We only need to build FreeType separately
if building GD from source. It can be downloaded at http://gnuwin32.sourceforge.net/packages/freetype.htm .
PROJ.4: PROJ.4 provides on-the-fly projection support to MapServer. Users whose data are in different projection
systems can use this library to reproject into a common projection. It is also required for WMS, WFS or WCS
services.
GDAL/OGR: The GDAL/OGR library allows MapServer to read a variety of geospatial raster formats (GDAL) and
vector formats (OGR). It can be downloaded at http://www.gdal.org/.
ArcSDE: ArcSDE is an ESRI proprietary spatial database engine. Most users will not have access to it but if you
have ArcSDE license, you can use its libraries to give MapServer access to SDE databases.
EPPL7: This library allows MapServer to read EPPL7 datasets, as well as the older Erdas LAN/GIS files. This library
is set as a default library in MapServer so there’s no special source code to download.
Now that you have reviewed the libraries that provide support to MapServer, it is time to decide which ones to compile
and use. We will work with the pre-built GD distributed on Boutell.com with PNG, GIF, JPEG, and FreeType “built
in”. If you want to provide OGC Web Services (ie. WMS, WFS) or want to perform on the fly reprojection then the
PROJ.4 library will be needed. If you need additional raster and vector data sources consider including GDAL/OGR
support. GDAL is also required for WCS service.
Our example calls for the required libraries and on-the-fly projection support so we need to download GD, regex, and
PROJ.4 libraries. Go ahead and get those libraries.
3.1. Installation
43
MapServer Documentation, Release 7.0.6
Set Compilation Options
MapServer, like many of it’s support libraries, comes with a Visual C++ makefile called Makefile.vc. It includes the
file nmake.opt which contains many of the site specific definitions. We will only need to edit the nmake.opt file to
configure the build for our local site options, and support libraries. The Makefile.vc, and nmake.opt template file have
been provided by Assefa Yewondwossen, and the DM Solutions folks.
As of MapServer 4.4, the default MapServer build options only include GD, and regex. MapServer is built using the
/MD option (which means MSVCRT.DLL should be used), so if any support libraries are being built statically (rather
than as DLLs) we need to use /MD when building them as well. By default modern PROJ.4 builds use /MD so we
should be able to use the default PROJ.4 build without tweaking.
The example will compile with the GDWin32 pre-built DLL as well as regex-0.12, and PROJ.4. The PROJ.4 support
will ensure we can enable MapServer OGC-WMS compatibility. Use notepad or another text editor to open the
nmake.opt file and make the following changes.
Comments
Use the pound sign ( # ) to comment out the lines that you want to disable, or remove the pound sign to enable an
option for NMAKE.
A. Enable PROJ.4 support, and update the path to the PROJ.4 directory. Uncomment the PROJ= line, and the
PROJ_DIR= line as follows, and update the PROJ_DIR path to point to your PROJ build.
# Reprojecting.
# If you would like mapserver to be able to reproject data from one
# geographic projection to another, uncomment the following flag
# PROJ.4 distribution (cartographic projection routines). PROJ.4 is
# also required for all OGC services (WMS, WFS, and WCS).
#
# For PROJ_DIR use full path to PROJ.4 distribution
PROJ=-DUSE_PROJ -DUSE_PROJ_API_H
PROJ_DIR=c:\projects\proj-4.4.9
If you look down later in the file, you can see that once PROJ is enabled, MapServer will be linked with proj_i.lib, the
PROJ.4 stub library, meaning that MapServer will be using the PROJ.DLL as opposed to statically linking in PROJ.4.
2. Uncomment the WMS option.
# Use this flag to compile with WMS Server support.
# To find out more about the OpenGIS Web Map Server Specification go to
# http://www.opengis.org/
WMS=-DUSE_WMS_SVR
3. Update to use GD. Here’s what it should look like in our example.
GD_DIR=c:/projects/gdwin32
GD_LIB=$(GD_DIR)/bgd.lib
Note: As distributed the GDWin32 binary build does not include the bgd.lib stub library. It is necessary to run the
makemsvcimport.bat script in the gdwin32 directory first.
D. Make sure the regex path is set correctly. In order for the “delete” command in the “nmake /f makefile.vc clean”
target to work properly it is necessary to use backslashes in the REGEX_DIR definition.
# REGEX Library
#
3.1. Installation
44
MapServer Documentation, Release 7.0.6
#
#
#
#
VC++ does not include the REGEX library... so we must provide our one.
The following definitions will try to build GNU regex-0.12 located in the
regex-0.12 sub-directory.
If it was not included in the source distribution, then you can get it from:
#
ftp://ftp.gnu.org/pub/gnu/regex/regex-0.12.tar.gz
# Provide the full path to the REGEX project directory
# You do not need this library if you are compiling for PHP mapscript.
# In that case the PHP regex library will be used instead
!IFNDEF PHP
REGEX_DIR=c:\projects\regex-0.12
!ENDIF
Your Makefile is now set.
Compile the Libraries
Before compiling MapServer, you must first compile its supporting libraries. How this is done varies for each library.
For the PROJ.4 library a nmake /f makefile.vc command in the proj-4.4.9src directory should be sufficient. The
regex-0.12 code is actually built by the MapServer build process, so you don’t need to do anything there.
Compiling libcurl
Previously, curl libraries can be compiled using the following command:
nmake /f makefile.vc6 CFG=release
This creates a static library, libcurl.lib, to which you compile against. Versions newer than version 7.10.x should be
compiled as dynamic library. This is accomplished using the command:
nmake /f makefile.vc6 CFG=release-dll
You will then need to edit MapServer’s nmake.opt to replace the CURL_LIB variable with this line:
CURL_LIB = $(CURL_DIR)/lib/libcurl_imp.lib
Compile MapServer
Once you have compiled the supporting libraries successfully, you are ready to take the final compilation step. If
you have not already done so, open a command prompt and set the VC++ environment variables by running the
vcvars32.bat usually located in C:Program FilesMicrosoft Visual StudioVC98binvcvars32.bat.
C:\Users> cd \projects\mapserver
C:\Projects\mapserver&> C:\Program Files\Microsoft Visual Studio\VC98\Bin\vcvars32.bat
˓→"
C:\Projects\mapserver>
Setting environment for using Microsoft Visual C++ tool.
C:\Projects\mapserver>
Now issue the command: nmake /f Makefile.vc and wait for it to finish compiling. If it compiles successfully, you
should get mapserver.lib, libmap.dll, mapserv.exe, and other .EXE files. That’s it for the compilation process. If you
run into problems, read section 4 about compiling errors. You can also ask for help from the helpful folks in the
MapServer-dev e-mail list.
3.1. Installation
45
MapServer Documentation, Release 7.0.6
Compiling MapServer with PostGIS support
To compile PostGIS support into MapServer, here’s what you need to do:
1. download the PostgreSQL 8.0.1 (or later) source from: ftp://ftp.heanet.ie/pub/postgresql/source/
2. I extracted them to C:projectspostgresql-8.0.1
3. download the Microsoft Platform SDK otherwise you get link errors on shfolder.lib.
4. compile libpq under C:projectspostgresql-8.0.1srcinterfaceslibpq using the win32.mak makefile
5. copy everything from C:projectspostgresql-8.0.1srcinterfaceslibpqrelease
8.0.1srcinterfaceslibpq as the MapServer makefile will try to find it there
to
C:projectspostgresql-
6. Define the following in the nmake.opt for MapServer: POSTGIS =-DUSE_POSTGIS POSTGIS_DIR
=c:/projects/postgresql-8.0.1/src
7. nmake /f makefile.vc
8. don’t forget to copy libpq.dll (from C:projectspostgresql-8.0.1srcinterfaceslibpqrelease) into a location where
MapServer can find it.
Common Compiling Errors
Following are a few common errors you may encounter while trying to build MapServer.
• Visual C++ Tools Not Properly Initialized.
C:\projects\mapserver> nmake -f /makefile.vc
'nmake' is not recognized as an internal or external command,
operable program or batch file.
This occurs if you have not properly defined the path and other environment variables required to use MS
VisualC++ from the command shell. Invoke the VCVARS32.BAT script, usually with the command C:Program
FilesMicrosoft Visual StudioVC98binvcvars32.bat or something similar if visual studio was installed in an
alternate location. To test if VC++ is available, just type “nmake” or “cl” in the command shell and ensure it is
found.
• Regex Build Problems.
regex.obj : error LNK2001: unresolved external symbol _printchar
libmap.dll : fatal error LNK1120: 1 unresolved externals
NMAKE : fatal error U1077: 'link' : return code '0x460'
Stop.
This occurs if you use the stock regex-0.12 we referenced. I work around this by commenting out the “extern”
statement for the printchar() function, and replacing it with a stub implementation in regex-0.12regex.c.
//extern void printchar ();
void printchar( int i ) {}
• GD Import Library Missing.
LINK : fatal error LNK1104: cannot open file 'c:/projects/gdwin32/bgd.lib'
NMAKE : fatal error U1077: 'link' : return code '0x450'
Stop.
If you are using the pre-built GD binaries, you still need to run the makemsvcimport.bat script in the gdwin32
directory to create a VC++ compatible stub library (bgd.lib).
3.1. Installation
46
MapServer Documentation, Release 7.0.6
Installation
The file we are most interested in is mapserv.exe. The other executable files are the MapServer utility programs.
See also:
MapServer Utilities
to learn more about these utilities.
To test that the CGI program is working, type mapserv.exe at the command prompt. You should see the following
message:
This script can only be used to decode form results and
should be initiated as a CGI process via a httpd server.
You may instead get a popup indicating that a DLL (such as bgd.dll) is missing. You will need to copy all the required
DLLs (ie. bgd.dll, and proj.dll) to the same directory as the mapserv.exe program.
Now type mapserv -v at the command prompt to get this message:
MapServer version 4.4.0-beta3 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER INPUT=SHAPEFILE
DEBUG=MSDEBUG
This tells us what data formats and other options are supported by mapserv.exe. Assuming you have your web server
set up, copy mapserv.exe, libmap.dll, bgd.dll, proj.dll and any other required DLLs to the cgi-bin directory.
You are now ready to download the demo application and try out your own MapServer CGI program. If you wish,
you can also create a directory to store the utility programs. I’d suggest making a subdirectory called “bin” under
the directory “projects” and copy the executables to that subdirectory. You might find these programs useful as you
develop MapServer applications.
Other Helpful Information
The MapServer Unix Compilation and Installation HOWTO has good descriptions of some MapServer compilation
options and library issues. I will write more about those options and issues on the next revision of this HOWTO.
The README documents of each of the supporting libraries provide compilation instructions for Windows.
The MapServer User community has a collective knowledge of the nuances of MapServer compilation. Seek their
advice wisely.
Acknowledgements
Thanks to Assefa Yewondwossen for providing the Makefile.vc. I would not have been able to write this HOWTO
without that file.
Thanks to Bart van den Eijnden for the libcurl and PostGIS compilation info.
Thanks to the Steve Lime for developing MapServer and to the many developers who contribute time and effort in
order to keep the MapServer project successful.
3.1.3 PHP MapScript Installation
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
3.1. Installation
47
MapServer Documentation, Release 7.0.6
Last Updated 2016-06-15
Table of Contents
• PHP MapScript Installation
– Introduction
– Obtaining, Compiling, and Installing PHP and the PHP/MapScript Module
– FAQ / Common Problems
Introduction
The PHP/MapScript module is a PHP dynamically loadable module that makes MapServer’s MapScript functions and
classes available in a PHP environment.
The original version of MapScript (in Perl) uses SWIG, but since SWIG does not support the PHP language, the
module has to be maintained separately and may not always be in sync with the Perl version.
The PHP module was developed by DM Solutions Group and is currently maintained by Mapgears.
This document assumes that you are already familiar with certain aspects of your operating system:
• For Unix/Linux users, a familiarity with the build environment, notably make.
• For Windows users, some compilation skills if you don’t have ready access to a pre-compiled installation and
need to compile your own copy of MapServer with the PHP/MapScript module.
Which version of PHP is supported?
PHP MapScript was originally developed for PHP-3.0.14 but after MapServer 3.5 support for PHP3 has been dropped
and as of the last update of this document, PHP 4.3.11 or more recent was required (PHP5 is well supported).
The best combinations of MapScript and PHP versions are:
• MapScript 4.10 with PHP 5.2.1 and up
• MapScript 4.10 with PHP 4.4.6 and up
Warning: PHP 7 support is still in development; please follow along and contribute through the associated ticket.
How to Get More Information on the PHP/MapScript Module for MapServer
• For a list of all classes, properties, and methods available in the module see the PHP MapScript API reference
document.
• More information on the PHP/MapScript module can be found on the PHP/MapScript page on MapTools.org.
• The MapServer Wiki also has PHP/MapScript build and installation notes and some php code snippets.
• Questions regarding the module should be forwarded to the MapServer mailing list.
3.1. Installation
48
MapServer Documentation, Release 7.0.6
Obtaining, Compiling, and Installing PHP and the PHP/MapScript Module
Download PHP and PHP/MapScript
• The PHP source or the Win32 binaries can be obtained from the PHP web site.
• Once you have verified that PHP is installed and is running, you need to get the latest MapServer source and
compile MapServer and the PHP module.
Setting Up PHP on Your Server
Unix
• Check if you have PHP already installed (several Linux distributions have it built in).
• If not, see the PHP manual’s “Installation on Unix systems” section.
Windows
• MS4W (MapServer For Windows) is a package that contains Apache, PHP, and PHP/MapScript ready to use in
a simple zipfile. Several Open Source applications are also available for use in MS4W.
• Windows users can follow steps in the Installing Apache, PHP and MySQL on Windows tutorial to install
Apache and PHP manually on their system.
• Window users running IIS can follow iis.net’s howto for installing PHP.
Note: When setting up PHP on Windows, make sure that PHP is configured as a CGI and not as an Apache module
because php_mapscript.dll is not thread-safe and does not work as an Apache module (See the Example Steps of a Full
Windows Installation section of this document).
Build/Install the PHP/MapScript Module
Building on a Linux Box
NOTE: For UNIX users, see the README.CONFIGURE file in the MapServer source, or see the Compiling on Unix
HowTo.
• The main MapServer configure script will automatically setup the main makefile to compile php_mapscript.so
if you pass the –with-php=DIR argument to the configure script.
• Copy the php_mapscript.so library to your PHP extensions directory, and then use the dl() function to load the
module at the beginning of your PHP scripts. See also the PHP function extension_loaded() to check whether
an extension is already loaded.
• The file mapscript/php3/examples/phpinfo_mapscript.phtml will test that the php_mapscript module is properly
installed and can be loaded.
• If you get an error from PHP complaining that it cannot load the library, then make sure that you recompiled
and reinstalled PHP with support for dynamic libraries. On RedHat 5.x and 6.x, this means adding “-rdynamic”
to the CLDFLAGS in the main PHP3 Makefile after running ./configure Also make sure all directories in the
path to the location of php_mapscript.so are at least r-x for the HTTPd user (usually ‘nobody’), otherwise dl()
may complain that it cannot find the file even if it’s there.
Building on Windows
3.1. Installation
49
MapServer Documentation, Release 7.0.6
• For Windows users, it is recommended to look for a precompiled binary for your PHP version on the MapServer
download page or use the MS4W installer.
• If for some reason you really need to compile your own Windows binary then see the README.WIN32 file in
the MapServer source (good luck!).
Installing PHP/MapScript
Simply copy the file php4_mapscript.dll to your PHP4 extensions directory (pathto/php/extensions)
Using phpinfo()
To verify that PHP and PHP/MapScript were installed properly, create a ‘.php’ file containing the following code and
try to access it through your web server:
<HTML>
<BODY>
<?php
if (PHP_OS == "WINNT" || PHP_OS == "WIN32")
{
dl("php_mapscript.dll");
}
else
{
dl("php_mapscript.so");
}
phpinfo();
?>
</BODY>
</HTML>
If PHP and PHP/MapScript were installed properly, several tables should be displayed on your page, and ‘MapScript’
should be listed in the ‘Extensions’ table.
Example Steps of a Full Windows Installation
Using MS4W (MapServer for Windows)
1. Download the latest MS4W base package.
2. Extract the files in the archive to the root of one of your drives (e.g. C:/ or D:/).
3. Double-click the file /ms4w/apache-install.bat to install and start the Apache Web server.
4. In a web browser goto http://127.0.0.1. You should see an MS4W opening page. You are now running PHP,
PHP/MapScript, and Apache.
5. You can now optionally install other applications that are pre-configured for MS4W, which are located on the
MS4W download page.
Manual Installation Using Apache Server
1. Download the Apache Web Server and extract it to the root of a directory (eg. D:/Apache).
2. Download PHP4 and extract it to your Apache folder (eg. D:/Apache/PHP4).
3.1. Installation
50
MapServer Documentation, Release 7.0.6
3. Create a temp directory to store MapServer created GIFs. NOTE: This directory is specified in the IMAGEPATH
parameter of the WEB Object in the Mapfile reference. For this example we will call the temp directory
“ms_tmp” (eg. E:/tmp/ms_tmp).
4. Locate the file httpd.conf in the conf directory of Apache, and open it in a text viewer (eg. TextPad, Emacs,
Notepad).
In the Alias section of this file, add aliases to the ms_tmp folder and any other folder you require (for this
example we will use the msapps folder):
Alias
Alias
/ms_tmp/
/msapps/
"path/to/ms_tmp/"
"path/to/msapps/"
In the ScriptAlias section of this file, add an alias for the PHP4 folder.
ScriptAlias
/cgi-php4/
"pathto/apache/php4/"
In the AddType section of this file, add a type for php4 files.
AddType application/x-httpd-php4
.php
In the Action section of this file, add an action for the php.exe file.
Action application/x-httpd-php4
"/cgi-php4/php.exe"
5. Copy the file php4.ini-dist located in your Apache/php4 directory and paste it into your WindowsNT folder (eg.
c:/winnt), and then rename this file to php.ini in your WindowsNT folder.
6. If you want specific extensions loaded by default, open the php.ini file in a text viewer and uncomment the
appropriate extension.
7. Place the file php_mapscript.dll into your Apache/php4/extensions folder.
Installation Using Microsoft’s IIS
(please see the IIS Setup for MapServer document for uptodate steps)
1. Install IIS if required (see the IIS installation procedure).
2. Install PHP and PHP/MapScript (see above).
3. Open the Internet Service Manager (eg. C/WINNT/system32/inetsrv/inetmgr.exe).
4. Select the Default web site and create a virtual directory (right click, select New/Virtual directory). For this
example we will call the directory msapps.
5. In the Alias field enter msapps and click Next.
6. Enter the path to the root of your application (eg. “c:/msapps”) and click Next.
7. Set the directory permissions and click Finish.
8. Select the msapps virtual directory previously created and open the directory property sheets (by right clicking
and selecting properties) and then click on the Virtual directory tab.
9. Click on the Configuration button and then click the App Mapping tab.
10. Click Add and in the Executable box type: path/to/php4/php.exe %s %s. You MUST have the %s %s on the
end, PHP will not function properly if you fail to do this. In the Extension box, type the file name extension to
be associated with your PHP scripts. Usual extensions needed to be associated are phtml and php. You must
repeat this step for each extension.
3.1. Installation
51
MapServer Documentation, Release 7.0.6
11. Create a temp directory in Explorer to store MapServer created GIFs.
Note: This directory is specified in the IMAGEPATH parameter of the WEB Object in the Mapfile. For this
example we will call the temp directory ms_tmp (eg. C:/tmp/ms_tmp).
12. Open the Internet Service Manager again.
13. Select the Default web site and create a virtual directory called ms_tmp (right click, select New/Virtual directory). Set the path to the ms_tmp directory (eg. C:/tmp/ms_tmp) . The directory permissions should at least be
set to Read/Write Access.
FAQ / Common Problems
Questions Regarding Documentation
Q Is there any documentation available?
A The main reference document is the PHP MapScript reference, which describes all of the current
classes, properties and methods associated with the PHP/MapScript module.
To get a more complete description of each class and the meaning of their member variables, see the
MapScript reference and the MapFile reference.
The MapServer Wiki also has PHP/MapScript build and installation notes and some php code snippets.
Q Where can I find sample scripts?
A Some examples are included in directory mapserver/mapscript/php3/examples/ in the MapServer
source distribution. A good one to get started is test_draw_map.phtml: it’s a very simple script
that just draws a map, legend and scalebar in an HTML page.
A good intermediate example is the PHP MapScript By Example guide (note that this document was
created for an earlier MapServer version but the code might be still useful).
The original example is the “Gmap demo”, download the whole source and data files from the
MapTools.org download page.
Questions About Installation
Q How can I tell that the module is properly installed on my server?
A Create a file called phpinfo.phtml with the following contents:
<?php
dl("php_mapscript.so");
phpinfo();
?>
Make sure you replace the php_mapscript.so with the name under which you installed it, it could be
php_mapscript_46.so on Unix, or php_mapscript_46.dll on Windows
You can then try the second test page mapserver/mapscript/php3/examples/test_draw_map.phtml.
This page simply opens a MapServer .map file and inserts its map, legend, and scalebar in an HTML
page. Modify the page to access one of your own MapServer .map files, and if you get the expected
result, then everything is probably working fine.
3.1. Installation
52
MapServer Documentation, Release 7.0.6
Q I try to display my .phtml or .php page in my browser but the page is shown as it would it
Notepad.
A The problem is that your PHP installation does not recognize ”.phtml” as a PHP file extension. Assuming you’re using PHP4 under Apache then you need to add the following line with the other
PHP-related AddType lines in the httpd.conf:
AddType application/x-httpd-php .phtml
For a more detailed explanation, see the Example Steps of a Full Windows Installation section of
this document.
Q I installed the PROJ.4, GDAL, or one of the support libraries on my system, it is recognized by
MapServer’s “configure” as a system lib but at runtime I get an error: “libproj.so.0: No such
file or directory”.
A You are probably running a RedHat Linux system if this happened to you. This happens because the
libraries install themselves under /usr/local/lib but this directory is not part of the runtime library
path by default on your system.
(I’m still surprised that “configure” picked PROJ.4 as a system lib since it’s not in the system’s lib
path...probably something magic in autoconf that we’ll have to look into)
There are a couple of possible solutions:
1. Add a “setenv LD_LIBRARY_PATH” to your httpd.conf to contain that directory
2. Edit /etc/ld.so.conf to add /usr/local/lib, and then run “/sbin/ldconfig”. This will permanently
add /usr/local/lib to your system’s runtime lib path.
3. Configure MapServer with the following options:
--with-proj=/usr/local --enable-runpath
and the /usr/local/lib directory will be hardcoded in the exe and .so files
I (Daniel Morissette) personally prefer option #2 because it is permanent and applies to everything
running on your system.
Q Does PHP/MapScript have to be setup as a CGI? If so, why?
A Yes, please see the PHP/MapScript CGI page in the MapServer Wiki for details.
Q I have compiled PHP as a CGI and when PHP tries to load the php_mapscript.so, I get an
“undefined symbol: _register_list_destructors” error. What’s wrong?
A Your PHP CGI executable is probably not linked to support loading shared libraries. The MapServer
configure script must have given you a message about a flag to add to the PHP Makefile to enable
shared libs.
Edit the main PHP Makefile and add “-rdynamic” to the LDFLAGS at the top of the Makefile, then
relink your PHP executable.
Note: The actual parameter to add to LDFLAGS may vary depending on the system you’re running
on. On Linux it is “-rdynamic”, and on *BSD it is “-export-dynamic”.
3.1. Installation
53
MapServer Documentation, Release 7.0.6
Q What are the best combinations of MapScript and PHP versions?
A The best combinations are:
• MapScript 4.10 with PHP 5.2.1 and up
• MapScript 4.10 with PHP 4.4.6 and up
Q I am dynamically loading gd.so and php_mapscript.so and running into problems, why?
A The source of the problems could be a mismatch of GD versions. The PHP GD module compiles its
own version of libgd, and if the GD library is loaded before the mapscript library, mapscript will
use the php-specific version. Wherever possible you should use a gd.so built with the same GD as
PHPMapScript. A workaround is to load the php_mapscript module before the GD module.
3.1.4 .NET MapScript Compilation
Author Tamas Szekeres
Contact szekerest at gmail.com
Compilation
Before compiling C# MapScript you should compile MapServer with the options for your requirements. For more
information about the compilation of MapServer please see Win32 Compilation and Installation Guide. It is highly
recommended to minimize the library dependency of your application, so when compiling MapServer enable only the
features really needed. To compile the C# binding SWIG 1.3.31 or later is required.
Warning: This document may refer to older library versions. You may want to try to use more recent library
versions for your build.
Win32 compilation targeting the MS.NET framework 1.1
You should compile MapServer, MapScript and all of the subsequent libraries using Visual Studio 2003. Download
and uncompress the latest SWIGWIN package that contains the precompiled swig.exe Open the Visual Studio .NET
2003 Command Prompt and step into the /mapscript/csharp directory. Edit makefile.vc and set the SWIG variable to
the location of your swig.exe
Use:
nmake -f makefile.vc
to compile mapscript.dll and mapscript_csharp.dll.
Win32 compilation targeting the MS.NET framework 2.0
You should compile MapServer, MapScript and all of the subsequent libraries using Visual Studio 2005. Download
and uncompress the latest SWIGWIN package that contains the precompiled swig.exe Open the Visual Studio 2005
3.1. Installation
54
MapServer Documentation, Release 7.0.6
Command Prompt and step into the /mapscript/csharp directory Edit makefile.vc and set the SWIG variable to the
location of your swig.exe.
Use:
nmake -f makefile.vc
to compile mapscript.dll and mapscript_csharp.dll.
Win32 compilation targeting the MONO framework
Before the compilation you should download and install the recent mono Win32 setup package (eg. mono-1.1.13.2gtksharp-2.8.1-win32-1.exe) Edit makefile.vc and set the CSC variable to the location of your mcs.exe. Alternatively
you can define:
MONO = YES
in your nmake.opt file.
You should use the same compiler for compiling MapScript as the compiler has been used for the MapServer compilation. To compile MapScript open the Command Prompt supplied with your compiler and use:
nmake -f makefile.vc
to compile mapscript.dll and mapscript_csharp.dll.
Alternative compilation methods on Windows
Beginning from MapServer 4.8.3 you can invoke the C# compilation from the MapServer directory by uncommenting
DOT_NET in nmake.opt:
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# .NET/C# MapScript
# ---------------------------------------------------------------------# .NET will of course only work with MSVC 7.0 and 7.1. Also note that
# you will definitely want USE_THREAD defined.
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#DOT_NET = YES
and invoking the compilation by:
nmake -f makefile.vc csharp
You can also use:
nmake -f makefile.vc install
for making the compilation an copying the targets into a common output directory.
Testing the compilation
For testing the compilation and the runtime environment you can use:
3.1. Installation
55
MapServer Documentation, Release 7.0.6
nmake -f makefile.vc test
within the csharp directory for starting the sample applications compiled previously. Before making the test the
location of the corresponding libraries should be included in the system PATH.
Linux compilation targeting the MONO framework
Before the compilation you should download and install the recent mono Linux package. Some distributions have precompiled binaries to install, but for using the latest version you might want to compile and install it from the source.
Download and uncompress the latest SWIG release. You should probably compile it from the source if pre-compiled
binaries are not available for your platform.
Before compiling MapScript, MapServer should be configured and compiled. Beginning from MapServer 4.8.2 during
configuration the mapscript/csharp/Makefile will be created according to the configuration options. Edit this file and
set the SWIG and CSC for the corresponding executable paths if the files could not be accessed by default. To compile
at a console step into the /mapscript/csharp directory use:
make
to compile libmapscript.so and mapscript_csharp.dll.
For testing the compilation and the runtime environment you can use:
make test
for starting the sample applications compiled previously.
OSX compilation targeting the MONO framework
Beginning from 4.10.0 the csharp/Makefile supports the OSX builds. Before making the build the recent MONO
package should be installed on the system.
Before compiling MapScript, MapServer should be configured and compiled. Beginning from MapServer 4.8.2 during
configuration the mapscript/csharp/Makefile will be created according to the configuration options. Edit this file and
set the SWIG and CSC for the corresponding executable paths if the files could not be accessed by default. To compile
at a console step into the /mapscript/csharp directory use:
make
to compile libmapscript.dylib and mapscript_csharp.dll.
For testing the compilation and the runtime environment you can use:
make test
for starting the sample applications compiled previously.
To run the applications mapscript_csharp.dll.config is needed along with the mapscript_csharp.dll file. This file is
created during the make process
Installation
The files required for your application should be manually installed. It is highly recommended to copy the files into
the same folder as the executable resides.
3.1. Installation
56
MapServer Documentation, Release 7.0.6
Known issues
Visual Studio 2005 requires a manifest file to load the CRT native assembly wrapper
If you have compiled MapServer for using the CRT libraries and you are using the MS.NET framework 2.0 as the
execution runtime you should supply a proper manifest file along with your executable, like:
<?xml version="1.0" encoding="utf-8"?>
<assembly xsi:schemaLocation="urn:schemas-microsoft-com:asm.v1
assembly.adaptive.xsd" manifestVersion="1.0"
xmlns:asmv1="urn:schemas-microsoft-com:asm.v1"
xmlns:asmv2="urn:schemas-microsoft-com:asm.v2"
xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
xmlns="urn:schemas-microsoft-com:asm.v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<assemblyIdentity name="drawmap.exe" version="1.0.0.0" type="win32" />
<dependency>
<dependentAssembly asmv2:dependencyType="install"
asmv2:codebase="Microsoft.VC80.CRT.manifest" asmv2:size="522">
<assemblyIdentity name="Microsoft.VC80.CRT" version="8.0.50608.0"
publicKeyToken="1fc8b3b9a1e18e3b" processorArchitecture="x86"
type="win32" />
<hash xmlns="urn:schemas-microsoft-com:asm.v2">
<dsig:Transforms>
<dsig:Transform Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
</dsig:Transforms>
<dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<dsig:DigestValue>UMOlhUBGeKRrrg9DaaPNgyhRjyM=</dsig:DigestValue>
</hash>
</dependentAssembly>
</dependency>
</assembly>
This will inform the CLR that your exe depends on the CRT and the proper assembly wrapper is to be used. If you are
using the IDE the manifest file could be pregenerated by adding a reference to Microsoft.VC80.CRT.manifest within
the /Microsoft Visual Studio 8/VC/redist/x86/Microsoft.VC80.CRT directory.
Manifests for the dll-s must be embedded as a resource
According to the windows makefile the MapScript compilation target (mapscript.dll) is linked with the /MD option. In
this case the VS2005 linker will generate a manifest file containing the unmanaged assembly dependency. The sample
contents of the manifest file are:
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<assembly xmlns='urn:schemas-microsoft-com:asm.v1' manifestVersion='1.0'>
<dependency>
<dependentAssembly>
<assemblyIdentity type='win32' name='Microsoft.VC80.CRT'
version='8.0.50608.0' processorArchitecture='x86'
publicKeyToken='1fc8b3b9a1e18e3b' />
</dependentAssembly>
</dependency>
</assembly>
Like previously mentioned if you are creating a windows application the common language runtime will search for a
manifest file for the application. The name of the manifest file should be the same as the executable append and end
3.1. Installation
57
MapServer Documentation, Release 7.0.6
with the .manifest extension. However if the host process is not controlled by you (like web mapping applications using
aspnet_wp.exe as the host process) you will not be certain if the host process (.exe) will have a manifest containing a
reference to the CRT wrapper. In this case you may have to embed the manifest into the dll as a resource using the mt
tool like:
mt /manifest mapscript.dll.manifest /outputresource:mapscript.dll;#2
the common language runtime will search for the embedded resource and load the CRT assembly properly.
Normally it is enough to load the CRT with the root dll (mapscript.dll), but it is not harmful embedding the manifest
into the dependent libraries as well.
Issue with regex and Visual Studio 2005
When compiling with Microsoft Visual Studio 2005 variable name collision may occur between regex.c and crtdefs.h.
For more details see:
https://github.com/mapserver/mapserver/issues/1651
C# MapScript library name mapping with MONO
Using the MapScript interface created by the SWIG interface generator the communication between the C# wrapper
classes (mapscript_csharp.dll) and the C code (mapscript.dll) takes place using platform invoke like:
[DllImport("mapscript", EntryPoint="CSharp_new_mapObj")]
public static extern IntPtr new_mapObj(string jarg1);
The DllImport declaration contains the library name, however to transform the library name into a file name is platform
dependent. On Windows the library name is simply appended with the .dll extension (mapscript.dll). On the Unix
systems the library file name normally starts with the lib prefix and appended with the .so extension (libmapscript.so).
Mapping of the library name may be manually controlled using a dll.config file. This simply maps the library file
the DllImport is looking for to its unix equivalent. The file normally contains the following information (mapscript_csharp.dll.config):
<configuration>
<dllmap dll="mapscript" target="libmapscript.so" />
</configuration>
and with the OSX builds:
<configuration>
<dllmap dll="mapscript" target="libmapscript.dylib" />
</configuration>
The file should be placed along with the corresponding mapscript_csharp.dll file, and created by default during the
make process. For more information see:
https://github.com/mapserver/mapserver/issues/1596 http://www.mono-project.com/Interop_with_Native_Libraries
Localization issues with MONO/Linux
According to https://github.com/mapserver/mapserver/issues/1762 MapServer may not operate equally well on different locale settings. Especially when the decimal separator is other than ”.” inside the locale of the process may cause
3.1. Installation
58
MapServer Documentation, Release 7.0.6
parse errors when the mapfile contains float numbers. Since the MONO process takes over the locale settings of the
environment it is worth considering to set the default locale to “C” of the host process, like:
LC_ALL=C mono ./drawmap.exe ../../tests/test.map test_csharp.png
Most frequent errors
This chapter will summarize the most frequent problems the user can run into. The issues were collected mainly from
the -users list and the IRC.
Unable to load dll (MapScript)
You can get this problem on Windows and in most cases it can be dedicated to a missing or an unloadable shared
library. The error message talks about mapscript.dll but surely one or more of the dll-s are missing that libmap.dll
depends on. So firstly you might want to check for the dependencies of your libmap.dll in your application directory.
You can use the Visual Studio Dependency Walker to accomplish this task. You can also use a file monitoring tool
(like SysInternal’s filemon) to detect the dll-s that could not be loaded. I propose to store all of the dll-s required by
your application in the application folder. If you can run the drawmap C# sample application with your mapfile your
compilation might be correct and all of the dlls are available.
You may find that the MapScript C# interface behaves differently for the desktop and the ASP.NET applications.
Although you can run the drawmap sample correctly you may encounter the dll loading problem with the ASP.NET
applications. When creating an ASP.NET project your application folder will be ‘Inetpubwwwroot[YourApp]bin’
by default. The host process of the application will aspnet_wp.exe or w3wp.exe depending on your system. The
application will run under a different security context than the interactive user (under the context of the ASPNET
user by default). When placing the dll-s outside of your application directory you should consider that the PATH
environment variable may differ between the interactive and the ASPNET user and/or you may not have enough
permission to access a dll outside of your application folder.
Bug reports
If you find a problem dedicated to the MapScript C# interface feel free to file a bug report to the Issue Tracker.
3.1.5 IIS Setup for MapServer
Author Debbie Paqurek
Last Updated 2005/12/12
Table of Contents
• IIS Setup for MapServer
– Base configuration
– Php.ini file
– Internet Services Manager
– Under the tree for your new website - add virtual directories for
– Test PHP
3.1. Installation
59
MapServer Documentation, Release 7.0.6
– Mapfiles for IIS
– Configuration files:
Some help on how to set up MapServer/Chameleon/PhpPgAdmin on Microsoft IIS (v5.0). Contains note on changes
to the php.ini file and necessary changes to the MapServer mapfiles. Please contribute or make changes as required.
Base configuration
• Windows 2000
• IIS 5.0
• MS4W 1.2.1
• Chameleon 2.2
• PHP 4.3.11
• MapServer 4.7
• PhpPgAdmin 3.5.4 (if using postgresql/postgis)
• Postgres 8.0.3 (if using postgresql/postgis)
• Postgis 1.0.3 (if using postgresql/postgis)
This setup assumes that MS4W was unzipped to form c:\ms4w\ directory.<br>
Php.ini file
• session.save_path (absolute path to your tmp directory)
• extension_dir (relative path to your php/extensions directory)
• cgi.force_redirect = 0</li>
• enable the pg_sql extension (php_pgsql.dll) (for Postgresql)
Internet Services Manager
Under your website tree, create a new website (e.g. msprojects). View the properties for the new website.
Web Site Tab
• set the IP address and under the Advanced tab put the complete Host Header name (e.g.msprojects.gc.ca).
Home Directory Tab
• content should come from: A directory located on this computer.
• Local Path: c:\ms4w\Apache\htdocs
• Read access + whatever else you need
• Execute Permissions: Scripts only
• Configuration button - App Mappings (Add extensions .php and .phtml, Executable is
c:\ms4w\Apache\cgi-bin\php.exe,select All verbs, Script Engine, and check that file exists<br>
Documents Tab
• Add index.phtml and index.html
3.1. Installation
60
MapServer Documentation, Release 7.0.6
• Directory Security Tab
– Anonymous access amd authentication control
– Select Anonymous access and the edit button should indicate the IUSR_account
Server Extensions Tab
• Enable authoring is selected and client scripting says Javascript
Under the tree for your new website - add virtual directories for
cgi-bin Under Properties, virtual directory tab Local Path should point to c:\ms4w\apache\cgi-bin. Select Read.
Execute Permissions should say “scripts and executables”
ms_tmp Under Properties, virtual directory tab Local Path should point to c:\ms4w\tmp\ms_tmp. Select Read, Write.
Execute Permissions should say “scripts only”. This is where temporary images are written to so in the File
system Security tab (use windows explorer), the c:\ms4w\tmp\ms_tmp directory should have permissions set
for the Internet Guest Account (Read and execute, Read, Write, List Folder Contents).
tmp Under Properties, virtual directory tab Local Path should point to c:\ms4w\tmp. Select Read, Write. Execute
Permissions should say “scripts only”. This is where chameleon writes sessions to so in the File system Security tab (use windows explorer), the c:\ms4w\tmp directory should have permissions set for the Internet Guest
Accounnt (Read and execute, Read, Write, List Folder Contents).
chameleon Under Properties, virtual directory tab Local Path should point to C:\ms4w\apps\chameleon\htdocs. Select
Read. Execute Permissions should say “scripts only”. Under the Chameleon tree, you can add virtual directories
for admin (c:\ms4w\apps\chameleon\admin\htdocs), samples (c:\ms4w\apps\chameleon\samples\htdocs), cwc2
(c:\ms4w\apps\chameleon\cwc2\htdocs)
phppgadmin If using postgresql/postgis, under Properties, virtual directory tab Local Path should point to
C:\ms4w\Apache\htdocs\phpPgAdmin. Select Read, Write. Execute Permissions should say “scripts and executables”. Under Documents - add index.php.
Note: We had to unzip the phppgadmin package into this directory in order to get phppgadmin to show us the login
page at http://yourserver/phppgadmin/index.php. You might want additional security on this directory.
gmap Good for testing purposes. Remember to change your mapfiles as discussed in Mapfiles for IIS below. Under
Properties, virtual directory tab Local Path should point to C:\ms4w\apps\gmap\htdocs. Select Read. Execute
Permissions should say “scripts only”.
Test PHP
In a command line window, navigate to c:\ms4w\apache\cgi-bin and run php -i. This should return the output that the phpinfo() function returns. I got an error about how it couldn’t find ntwdblib.dll. I found this in
c:\ms4w\apache\php\dlls and I copied it to the cgi-bin directory.
Mapfiles for IIS
• Add a config line to the MAP level of the mapfile
CONFIG PROJ_LIB "c:\ms4w\proj\nad\"
• change the IMAGEPATH to be an absolute path to your tmp/ms_tmp folder
3.1. Installation
61
MapServer Documentation, Release 7.0.6
IMAGEPATH "c:\ms4w\tmp\ms_tmp"
Configuration files:
For Chameleon
C:\ms4w\apps\chameleon\config\chameleon.xml
C:\ms4w\apps\chameleon\config\cwc2.xml
For phppgadmin: (if using postgresql/postgis)
C:\ms4w\apps\phpPgAdmin\conf\config.inc.php
3.1.6 Oracle Installation
Author Till Adams
Last Updated 2007/02/16
Table of Contents
• Oracle Installation
– Preface
– System Assumptions
– Compile MapServer
– Set Environment Variables
Preface
This document explains the whole configuration needed to get the connect between MapServer CGI and an Oracle
database server on a linux (Ubuntu) box. The aim of this document is just to put a lot of googled knowledge in ONE
place. Hopefully it will preserve many of people spending analog amount of time than I did!
This manual was written, because I spent several days googling around to get my UMN having access to an oracle
database. I’m NOT an oracle expert, so the aim of this document is just to put a lot of googled knowledge in ONE
place. Hopefully it will preserve many of people spending analog amount of time than I did! (Or: If you have the
choice: Try PostGIS ;-))
Before we start, some basic knowledge, I didn’t know before:
• MapServer can access oracle spatial as well as geodata from any oracle locator installation! Oracle locator
comes with every oracle instance, there is no need for an extra license.
• There is no need for further installation of any packages beside oracle/oracle OCI
System Assumptions
We assume that Oracle is already installed, there is a database and there is some geodata in the database. The following
paths should be known by the reader:
3.1. Installation
62
MapServer Documentation, Release 7.0.6
• ORACLE_HOME
• ORACLE_SID
• ORACLE_BASE
• LD_LIBRARY_PATH
We also assume that you have installed apache2 (our version was 2.0.49) and you are used to work with Linux/UNIX
systems. We also think you are able to handle the editor vi/vim.
We ensure that the Oracle user who later accesses the database has write-access to the oracle_home directory.
We also assume, that you already have setup the tnsnames.ora file. It should look like that:
MY_ORACLE =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = host)(PORT = 1521))
(CONNECT_DATA =
(SERVICE_NAME = your_name)
)
)
It is important that you know the NAME of the datasource, in this example this is “MY_ORACLE” and will be used
further on. Done that, you’re fine using User/Password@MY_ORACLE in your mapfile to connect to the oracle
database. But first we have to do some more stuff.
Compile MapServer
Compile as normal compilation and set this flag:
--with-oraclespatial=/path/to/oracle/home/</p>
If MapServer configure and make runs well, try
./mapserv -v
This should at least give this output:
INPUT=ORACLESPATIAL
If you got that, you’re fine from the MapServer point of view.
Set Environment Variables
It is important to set all environment variables correctly. There are one the one hand system-wide environment variables to be set, on the other hand there should be set some for the cgi-directory in your Apache configuration.
System Variables
On Ubuntu (and on many other systems) there is the file “/etc/profile” which sets environment variables for all users
on the system (you may also dedicate user-specific environment variables by editing the users ”.profile” file in their
home directory, but usually the oracle database users are not users of the system with their own home)
Set the following variables:
3.1. Installation
63
MapServer Documentation, Release 7.0.6
$ cd /etc
$ echo export ORACLE_HOME=/path/to/oracle/home >> /etc/profile
# **(e.g. ORACLE_HOME=/app/oracle/ora10g)
$ echo export ORACLE_BASE=path/to/oracle >> /etc/profile
# **(e.g. ORACLE_HOME=/app/oracle)
$ echo export ORACLE_SID=MY_ORACLE >> /etc/profile
$ echo export LD_LIBRARY_PATH=path/to/oracle/home/lib >> /etc/profile
# **(e.g. ORACLE_HOME=/app/oracle/ora10g/lib)
The command comes silent, so there is no system output if you didn’t mistype anything!
Setting the Apache Environment
Sometimes it is confusing WHERE to set WHAT in the split apache2.conf-files.
In the folder
“/etc/apache2/sites_available” you find your sites-file. If you did not do sth. Special e.g. installing virtual hosts,
the file is named “default”. In this file, the apache cgi-directory is defined. Our file looks like this:
ScriptAlias /cgi-bin/ /var/www/cgi-bin/
<Directory "/var/www/cgi-bin">
AllowOverride None
Options ExecCGI -MultiViews +SymLinksIfOwnerMatch
Order allow,deny
Allow from all
</Directory></p>
In this file, the local apache environment variables must be set. We did it within a location-block like this:
<Location "/cgi-bin/">
SetEnv ORACLE_HOME "/path/to/oracle/home"
</Location></p>
Where /cgi-bin/ in the opening location block refers to the script alias /cgi-bin/ and the TNS_ADMIN directory point
to the location of the tnsnames.ora file.
Then restart apache:
$ /etc/init.d/apache2 force-reload
Create mapfile
Before we start creating our mapfile ensure that you have a your access data (User/Password) and that you know the
Oracle SRID, which could be different from the proj-EPSG!
The data access parameters:
• CONNECTIONTYPE oraclespatial
• CONNECTION ‘user/password@MY_ORACLE‘
3.1. Installation
64
MapServer Documentation, Release 7.0.6
• DATA ‘GEOM FROM MY_LAYER USING SRID 82032’
[...]
Where:
• GEOM is the name of the geometry column
• MY_LAYER the name of the table
• 82032 is equivalent to the EPSG code 31468 (German projection system)
Testing & Error handling
So you are fine now. Load the mapfile in your application and try it. If everything goes well: Great, if not, possibly this
ugly error-emssage occurs (this one cmae by querying MapServer through the WMS interface as a GetMap-request):
<ServiceExceptionReport version="1.0.1">
<ServiceException>
msDrawMap(): Image handling error. Failed to draw layer named 'test1'.
msOracleSpatialLayerOpen(): OracleSpatial error. Cannot create OCI Handlers.
Connection failure. Check the connection string. Error: .
</ServiceException>
</ServiceExceptionReport>
This points us towards, that there might be a problem with the connection to the database. First of all, let’s check, if
the mapfile is all right. Therefore we use the MapServer utility program shp2img.
Let’s assume you are in the directory, where you compiled MapServer and run shp2img:
$ cd /var/src/mapserver_version/
$ shp2img -m /path/to/mapfile/mapfile.map -i png -o /path/to/output/output.png
The output of the command should look like this:
[Fri Feb
[Fri Feb
[Fri Feb
2 14:32:17 2007].522395 msDrawMap(): Layer 0 (test1), 0.074s
2 14:32:17 2007].522578 msDrawMap(): Drawing Label Cache, 0.000s
2 14:32:17 2007].522635 msDrawMap() total time: 0.075s
If not, this possibly points you towards any error in your mapfile or in the way to access the data directly. In this
case, take a look at Oracle Spatial. If there is a problem with your oracle connect, the same message as above
(MsDrawMap() ...) occurs. Check your mapfile syntax and/or the environment settings for Oracle.
For Debian/Ubuntu it’s worth also checking the file “/etc/environment” and test-wise to add the system variables
comparable to System Variables
If the output is OK, you may have a look at the generated image (output.png). Then your problem reduces to the access
of apache to oracle home directory. Carefully check your apache configuration. Please note, that the apache.config file
differs in several linux-distributions. For this paper we talk about Ubuntu, which should be the same as Debian.
3.1.7 V8 MapScript Support
Author Alan Boudreault
Contact aboudreault@mapgears.com
3.1. Installation
65
MapServer Documentation, Release 7.0.6
Table of Contents
• V8 MapScript Support
– Introduction
– Obtaining, Compiling, and Installing V8 and V8/MapScript
Introduction
The V8/MapScript cannot be used as its own like other mapscripts. V8 is currently used internally to add 2 functionalities:
• Javascript Styleitem: rfc102
• Javascript Geomtransform: rfc106
These instructions are for Unix/Linux users.
Version of V8 supported
You have to use v8 3.20, which is the version of the nodejs release:0.11.7. For future compatibility, this is a good thing
to be synchronized to nodejs project.
Obtaining, Compiling, and Installing V8 and V8/MapScript
Download and Compile V8
• The V8 source can be obtained from the v8 website.
Download v8:
git clone git://github.com/v8/v8.git v8
Compile the v8 library:
cd v8
git checkout 3.20
make dependencies
library=shared make -j8 x64.release
Note: Use ia32.release if you are using a 32bits machine.
Install the v8 library and include headers:
mkdir -p /opt/v8/lib && cp ./out/x64.release/lib.target/libv8.so /opt/v8/lib
mkdir /opt/v8/include && cp include/v8* /opt/v8/include
Note: Modify the library path if needed (32bits)
Setup the v8 lib in the system paths:
3.1. Installation
66
MapServer Documentation, Release 7.0.6
echo "/opt/v8/lib" > /etc/ld.so.conf.d/v8.conf
ldconfig
Compile MapServer with V8 Support
Configure:
cd mapserver
mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=/opt/v8 -DWITH_V8=yes ..
Compile and install: (from the build directory)
make install
Verify the V8 support:
/path/to/mapserv -v
You should see: SUPPORTS=V8. You can now refer to the following pages to try the javascript functionalities:
• Javascript Styleitem: STYLEITEM Javascript
• Javascript Geomtransform: Javascript transformation
3.1. Installation
67
CHAPTER 4
Mapfile
4.1 Mapfile
Author Steve Lime
Contact steve.lime at dnr.state.mn.us
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2017-06-16
The Mapfile is the heart of MapServer. It defines the relationships between objects, points MapServer to where data
are located and defines how things are to be drawn.
The Mapfile consists of a MAP object, which has to start with the word MAP.
There are some important concepts that you must understand before you can reliably use mapfiles to configure
MapServer. First is the concept of a LAYER. A layer is the combination of data plus styling. Data, in the form of
attributes plus geometry, are given styling using CLASS and STYLE directives.
See also:
An Introduction to MapServer for “An Introduction to the Mapfile”
4.1.1 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
Table of Contents
• Abstract
• Introduction
68
MapServer Documentation, Release 7.0.6
– Multiple Rendering and Overlay
– Symbol Scaling
– MapServer and symbol specification
• Using Cartographical Symbols in MapServer
– Output formats
– Symbol units
– Scaling of Symbols
• Construction of Point Symbols
– Symbols of TYPE vector and ellipse
– Symbols of TYPE truetype
– Symbols of TYPE pixmap
– Symbol definitions for the figure that demonstrates point symbols
– Combining symbols
• Construction of Line Symbols
– Overlaying lines
– Use of the PATTERN and GAP parameters
* LINECAP
* LINEJOIN
* LINEJOINMAXSIZE (only relevant for LINEJOIN miter)
– Use of the OFFSET parameter
– Asymmetrical line styling with point symbols
• Area Symbols
– Hatch fill
– Polygon fills with symbols of TYPE pixmap
– Polygon fills with symbols of TYPE vector
* Excerpts from the map file for the polygon fill vector examples above
– Polygon outlines
• Examples (MapServer 4)
– Basic Symbols
– Complex Symbols
• Tricks
– Changing the center of a point symbol
• Mapfile changes related to symbols
– Version 6.2
– Version 6.0
4.1. Mapfile
69
MapServer Documentation, Release 7.0.6
• Current Problems / Open Issues
– GAP - PATTERN incompatibility
• The End
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.
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:
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 LAYERs. 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 STYLEs to create complex symbols by overlay.
To create the highway symbol mentioned above with a total width of 9 units, the lowest STYLE (in drawing order) will
be a broad black line with a width of 9 units. The second level STYLE will be a yellow line with a width of 7 units,
and the topmost 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 LAYERs or STYLEs 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 LAYER and STYLE can be used to achieve transparency (making lower symbols “shine”
through upper symbols).
4.1. Mapfile
70
MapServer Documentation, Release 7.0.6
Fig. 4.1: Structure of Cartographical Symbols‘
4.1. Mapfile
71
MapServer Documentation, Release 7.0.6
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 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.
STYLE MAXSIZE and MINSIZE limits the scaling of symbols.
MapServer and symbol specification
In a MapServer application, SYMBOL parameters are organised in the map file as follows:
• Each 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 SYMBOL elements, using the parameters TYPE, POINTS, IMAGE, FILLED, ANCHORPOINT and more (SYMBOL elements can be collected in separate symbol files for reuse).
• Colour, lightness, size and outline are defined inside the STYLE sections of a CLASS section using the parameters
COLOR, SIZE, WIDTH and OUTLINECOLOR.
• Patterns for styling lines and polygons are defined in STYLE sections using GAP and PATTERN.
• Several basic elements can be combined to achieve a complex signature using several STYLEs inside one CLASS.
The following example shows the interaction of some of these elements and explains the configuration in the LAYER
and the 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):
Fig. 4.2: The generated overlay symbol
4.1. Mapfile
72
MapServer Documentation, Release 7.0.6
Table 4.1: Commented LAYER and SYMBOL sections.
LAYER section of the map file
SYMBOL (from a separate symbol file or in-line in
the map file)
# Start of layer definition
LAYER
# Name of the layer
NAME "mytest"
TYPE POINT
# Point geometries
STATUS DEFAULT # Always draw
# Use the dataset test.shp
DATA test
# Start of a Class definition
CLASS
# Start of the first Style
STYLE
# Symbol to be used (reference)
SYMBOL "square"
# Size of the symbol in pixels
SIZE 16
# Colour (RGB) - red
COLOR 255 0 0
# Outline colour (RGB) - black
OUTLINECOLOR 0 0 0
END # end of STYLE
# Start of the second Style
STYLE
# Symbol to be used (reference)
SYMBOL "circle"
# Size of the symbol in pixels
SIZE 10
# Colour (RGB) - blue
COLOR 0 0 255
END # end of STYLE
END # end of CLASS
END # end of LAYER
# Start of symbol definition
SYMBOL
# Symbol name (referenced in STYLEs)
NAME "square"
TYPE vector # Type of symbol
# Start of the symbol geometry
POINTS
0 0
0 1
1 1
1 0
0 0
END # end of POINTS
# The symbol should be filled
FILLED true
# Place the according to its center
ANCHORPOINT 0.5 0.5
END # end of SYMBOL
# Start of symbol definition
SYMBOL
# Symbol name (referenced in STYLEs)
NAME "circle"
TYPE ellipse # Type of symbol
# Start of the symbol geometry
POINTS
1 1
END # end of POINTS
# The symbol should be filled
FILLED true
# Place the according to its center
ANCHORPOINT 0.5 0.5
END # end of SYMBOL
Using Cartographical Symbols in MapServer
Vectors, truetype fonts and raster images are basic graphical elements that are defined by the TYPE parameter in the
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 OUTPUTFORMAT (and MAP IMAGETYPE) for more.
4.1. Mapfile
73
MapServer Documentation, Release 7.0.6
Symbol units
The units used for specifying dimensions is defined in the SIZEUNITS parameter of the 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.
Scaling of Symbols
The SYMBOLSCALEDENOM parameter in the LAYER section specifies the scale at which the symbol or text label is
displayed in exactly the dimensions defined in the STYLEs (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 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 STYLEs) 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 STYLEsection, so this kind of tuning has to be solved at the LAYER level. To do this, create several LAYERs 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.
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.
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 SYMBOL ANCHORPOINT parameter. The default anchorpoint is at the center of the boundingbox of the symbol (ANCHORPOINT 0.5
0.5).
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.
4.1. Mapfile
74
MapServer Documentation, Release 7.0.6
Fig. 4.3: Basic point symbol TYPEs, showing effects of size, offset, angle and outlinecolor
• 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 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 SYMBOL ANCHORPOINT should
be used instead.
Symbols of TYPE truetype
You can use symbols from truetype fonts. The symbol settings are defined in the SYMBOL element. Specify the
character or the ASCII number of the character to be used in the CHARACTER parameter. The FONT parameter is
4.1. Mapfile
75
MapServer Documentation, Release 7.0.6
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 LAYER CLASS 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.
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 SYMBOL element. MapServer supports the raster formats GIF and PNG for pixmaps.
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 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 (LAYER SYMBOLSCALEDENOM is set or LAYER SIZEUNITS
is not pixels) and want to prevent this from happening, you should set the 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:
SYMBOL
NAME "o-flag-trans"
TYPE pixmap
IMAGE "o-flag-trans.png"
END # SYMBOL
SYMBOL
NAME "circlef"
TYPE ellipse
FILLED true
POINTS
4.1. Mapfile
76
MapServer Documentation, Release 7.0.6
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 LAYERs and STYLEs used for producing the polygon V symbols in the point symbol figure:
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
4.1. Mapfile
77
MapServer Documentation, Release 7.0.6
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"
4.1. Mapfile
78
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
79
MapServer Documentation, Release 7.0.6
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
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 STYLEs within one LAYER. Each STYLE element references one SYMBOL element. All
the basic symbols are centered and overlaid when rendered.
Notice that the SIZE parameter in the 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 SYMBOL element. When combining several basic point symbols on
4.1. Mapfile
80
MapServer Documentation, Release 7.0.6
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.
Fig. 4.4: Construction of Point 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.
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.
4.1. Mapfile
81
MapServer Documentation, Release 7.0.6
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 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 SYMBOL of TYPE ellipse has been used, then a SYMBOL of TYPE
vector, then a SYMBOL of TYPE font and then a SYMBOL of TYPE pixmap. To control the placement of the symbols
relative to the line (to get asymmetrical styling), use 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
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.
• STYLE OFFSET usage is demonstrated in the 5th symbol from the bottom in the right column
Below you will find the SYMBOLs and STYLEs that were used to produce the line symbols in “Construction of Line
Symbols”. The LAYERs are ordered from bottom to top of the figure.
Styles and symbols for lines
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
4.1. Mapfile
82
MapServer Documentation, Release 7.0.6
Fig. 4.5: Construction of Line Symbols
4.1. Mapfile
83
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
84
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
85
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
86
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
87
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
88
MapServer Documentation, Release 7.0.6
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
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 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.
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.
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).
4.1. Mapfile
89
MapServer Documentation, Release 7.0.6
Fig. 4.6: Different kinds of linejoins
Fig. 4.7: Miter linejoin
4.1. Mapfile
90
MapServer Documentation, Release 7.0.6
The max length of the miter join is calculated as follows (d is the line width, specified with the WIDTH parameter of
the STYLE):
m_max = d * LINEJOINMAXSIZE
If m > m_max, then the connection length will be set to m_max.
Use of the OFFSET parameter
In 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.
Fig. 4.8: Use of the OFFSET parameter with lines - map image
4.1. Mapfile
91
MapServer Documentation, Release 7.0.6
Use of the OFFSET parameter
with lines - Map file excerpt
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 do
COLOR 255 0 0 # red
WIDTH 2
OFFSET -8 12
END # STYLE
STYLE
# left offset rel. to line
COLOR 0 0 255 # blue
WIDTH 5
OFFSET -16 -99
END # STYLE
STYLE
# right offset rel. to lin
COLOR 0 255 0 # green
WIDTH 5
OFFSET 16 -99
END # STYLE
END # CLASS
END # LAYER
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 bot-
4.1. Mapfile
92
MapServer Documentation, Release 7.0.6
tom is produced using 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.
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 STYLE, the symbols will be scaled to the specified height.
The GAP parameter of the 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.
Hatch fill
Simple line hatches (e.g. horizontal, vertical and diagonal) can be created by filling the polygon with a hatch symbol.
Fig. 4.9: Hatch examples
The SIZE parameter in the STYLE that uses a 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.
4.1. Mapfile
93
MapServer Documentation, Release 7.0.6
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 SYMBOL definition:
SYMBOL
NAME "hatchsymbol"
TYPE hatch
END
Then the CLASS definitions:
4.1. Mapfile
94
MapServer Documentation, Release 7.0.6
Table 4.2: Hatches
CLASS definitions
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
4.1.END
Mapfile
# CLASS
END # LAYER
95
MapServer Documentation, Release 7.0.6
Polygon fills with symbols of TYPE pixmap
Polygons can be filled with pixmaps.
Note: If the 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.
Fig. 4.10: 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.
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
4.1. Mapfile
96
MapServer Documentation, Release 7.0.6
Fig. 4.11: Raster image for a hatched fill
palette.
Table 4.3: Construction of a horizontally arranged area symbol
CLASS section
SYMBOL definition
CLASS
STYLE
COLOR 255 255 0
END
STYLE
SYMBOL "in_the_star"
END
STYLE
OUTLINECOLOR 0 0 0
WIDTH 1
END
END
SYMBOL
NAME "in_the_star"
TYPE PIXMAP
IMAGE "stern.png"
TRANSPARENT 8
END
Fig. 4.12: Polygon fill - regular grid pattern
4.1. Mapfile
97
MapServer Documentation, Release 7.0.6
Table 4.4: Construction of a diagonally arranged area symbol
CLASS section
SYMBOL definition
CLASS
STYLE
SYMBOL "in_point1"
END
STYLE
OUTLINECOLOR 0 0 0
WIDTH 1
END
END
SYMBOL
NAME "in_point1"
TYPE PIXMAP
IMAGE "flaeche1_1.png"
TRANSPARENT 13
END
Fig. 4.13: Polygon fill - diagonal pattern
Table 4.5: Construction of a hatch
CLASS section
SYMBOL definition
CLASS
STYLE
COLOR 255 255 0
END
STYLE
SYMBOL "in_hatch"
END
STYLE
OUTLINECOLOR 0 0 0
WIDTH 1
END
END
SYMBOL
NAME "in_hatch"
TYPE PIXMAP
IMAGE "schraffur.png"
TRANSPARENT 2
END
Fig. 4.14: Polygon fill - hatch
4.1. Mapfile
98
MapServer Documentation, Release 7.0.6
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 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.
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.
Fig. 4.15: Polygon fills - vector
4.1. Mapfile
99
MapServer Documentation, Release 7.0.6
Excerpts from the map file for the polygon fill vector examples above
First, the LAYERs
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
4.1. Mapfile
100
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
101
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
102
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
103
MapServer Documentation, Release 7.0.6
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 SYMBOLs:
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
4.1. Mapfile
104
MapServer Documentation, Release 7.0.6
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.1. Mapfile
105
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
106
MapServer Documentation, Release 7.0.6
0.4303
0.3700
0.3182
0.2785
0.2535
0.2450
0.2535
0.2785
0.3182
0.3700
0.4303
0.4950
0.5597
0.6200
0.6718
0.7115
0.7365
0.7450
-99 -99
0.25
0.2415
0.2165
0.1768
0.1250
0.0647
0.0
0.0
0.25
-99 -99
1 0.25
0.9252
0.8649
0.8132
0.7734
0.7485
0.74
1 0.0
1 0.25
-99 -99
0.74
0.7485
0.7734
0.8132
0.8649
0.9252
1 0.74
1 1
0.74
-99 -99
0.0
0.0647
0.1250
0.1768
0.2165
0.2415
0.25
0.0
0.0
4.1. Mapfile
0.6915
0.6665
0.6268
0.5750
0.5147
0.4500
0.3853
0.3250
0.2732
0.2335
0.2085
0.2000
0.2085
0.2335
0.2732
0.3250
0.3853
0.4500
0.0
0.0647
0.1250
0.1768
0.2165
0.2415
0.25
0.0
0.0
0.2415
0.2165
0.1768
0.1250
0.0647
0.0
1
0.9252
0.8649
0.8132
0.7734
0.7485
1
0.74
0.7485
0.7734
0.8132
0.8649
0.9252
1
1
0.74
107
MapServer Documentation, Release 7.0.6
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
4.1. Mapfile
108
MapServer Documentation, Release 7.0.6
0.75
0.7415
0.7165
0.6768
0.6250
0.5647
0.5
0.4252
0.3649
0.3132
0.2734
0.2485
0.24
0.0
END
END
0.0
0.0647
0.1250
0.1768
0.2165
0.2415
0.25
0.2415
0.2165
0.1768
0.1250
0.0647
0.0
0.0
Polygon outlines
Polygon outlines can be created by using OUTLINECOLOR in the STYLE. WIDTH specifies the width of the outline.
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 Use of the PATTERN and GAP parameters.
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.
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.
4.1. Mapfile
109
MapServer Documentation, Release 7.0.6
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.
Basic Symbols
4.1. Mapfile
110
MapServer Documentation, Release 7.0.6
4.1. Mapfile
111
MapServer Documentation, Release 7.0.6
4.1. Mapfile
112
MapServer Documentation, Release 7.0.6
Complex Symbols
4.1. Mapfile
113
MapServer Documentation, Release 7.0.6
4.1. Mapfile
114
MapServer Documentation, Release 7.0.6
Tricks
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 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.
Below you will find three tables that contain the SYMBOLs and the STYLE mechanisms that were used to generate the
shifted symbols in the illustration.
4.1. Mapfile
115
MapServer Documentation, Release 7.0.6
Fig. 4.16: Shifting trick
4.1. Mapfile
116
MapServer Documentation, Release 7.0.6
Table 4.6: Symbol tricks - shift - arrows
SYMBOLs
LAYER STYLEs
SYMBOL
NAME "arrow-start"
TYPE vector
FILLED true
POINTS
0 0.4
3 0.4
3 0
5 0.8
3 1.6
3 1.2
0 1.2
0 0.4
END # POINTS
ANCHORPOINT 0 0.5
END # SYMBOL
SYMBOL
NAME "arrow-end"
TYPE vector
FILLED true
POINTS
0 0.4
3 0.4
3 0
5 0.8
3 1.6
3 1.2
0 1.2
0 0.4
END # POINTS
ANCHORPOINT 1 0.5
END # SYMBOL
LAYER # Line
STATUS DEFAULT
TYPE LINE
FEATURE
POINTS
20 80
40 85
60 85
70 80
END # Points
END # Feature
CLASS
STYLE
COLOR 0 0 0
WIDTH 15
LINECAP butt
END # STYLE
STYLE
GEOMTRANSFORM "start"
COLOR 0 255 0
SYMBOL "arrow-start"
SIZE 15.0
ANGLE AUTO
END # STYLE
STYLE
GEOMTRANSFORM "start"
COLOR 255 0 0
SYMBOL "circlef"
SIZE 3
END # STYLE
STYLE
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
4.1. Mapfile
117
MapServer Documentation, Release 7.0.6
Table 4.7: Symbol tricks - shift - asymmetrical tags
SYMBOLs
LAYER STYLEs
SYMBOL
NAME "vert-line-shift"
TYPE vector
POINTS
0 0
0 10
END # POINTS
ANCHORPOINT 0.5 0
END # SYMBOL
LAYER # Line - symbol overlay
STATUS DEFAULT
TYPE LINE
FEATURE
POINTS
20 50
40 55
60 55
70 50
END # Points
END # Feature
CLASS
STYLE
COLOR 0 0 0
WIDTH 4
END # STYLE
STYLE
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
SYMBOL
NAME "vert-line"
TYPE vector
POINTS
0 0
0 10
END # POINTS
END # SYMBOL
4.1. Mapfile
118
MapServer Documentation, Release 7.0.6
Table 4.8: Symbol tricks. Unshifted symbol (top) and shifted symbol
SYMBOLs
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 SYMBOL parameter was added.
The INITIALGAP STYLE parameter was added.
The GAP 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 SYMBOL element to the STYLE element of CLASS (in LAYER):
PATTERN (introduced in 5.0, previously called STYLE), GAP, LINECAP, LINEJOIN, LINEJOINMAXSIZE
The 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
4.1. Mapfile
119
MapServer Documentation, Release 7.0.6
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).
4.1.2 CLASS
BACKGROUNDCOLOR [r] [g] [b] | [hexadecimal string]
Deprecated since version 6.0: Use CLASS STYLEs.
COLOR [r] [g] [b] | [hexadecimal string]
Deprecated since version 6.0: Use CLASS STYLEs.
DEBUG [on|off] Enables debugging of the class object. Verbose output is generated and sent to the standard error
output (STDERR) or the MapServer logfile if one is set using the LOG parameter in the WEB object.
See also:
rfc28
EXPRESSION [string] Four types of expressions are now supported to define which class a feature belongs to:
String comparisons, regular expressions, logical expressions, and string functions (see Expressions). If no expression is given, then all features are said to belong to this class.
• String comparisons are case sensitive and are the fastest to evaluate. No special delimiters are necessary although strings must be quoted if they contain special characters. (As a matter of good habit, it is
recommended that you quote all strings). The attribute to use for comparison is defined in the LAYER
CLASSITEM parameter.
• Regular expression are limited using slashes (/regex/). The attribute to use for comparison is defined in the
LAYER CLASSITEM parameter.
• Logical expressions allow the building of fairly complex tests based on one or more attributes and therefore are only available with shapefiles. Logical expressions are delimited by parentheses “(expression)”.
Attribute names are delimited by square brackets “[ATTRIBUTE]”. Attribute names are case sensitive and
must match the items in the shapefile. For example:
EXPRESSION ([POPULATION] > 50000 AND '[LANGUAGE]' eq 'FRENCH')
The following logical operators are supported: =, >, <, <=, >=, =, or, and, lt, gt, ge, le, eq, ne, in, ~, ~*. As
one might expect, this level of complexity is slower to process.
– One string function exists: length(). It computes the length of a string:
EXPRESSION (length('[NAME_E]') < 8)
4.1. Mapfile
120
MapServer Documentation, Release 7.0.6
String comparisons and regular expressions work from the classitem defined at the layer level. You may mix
expression types within the different classes of a layer.
GROUP [string] Allows for grouping of classes. It is only used when a CLASSGROUP at the LAYER level is set.
If the CLASSGROUP parameter is set, only classes that have the same group name would be considered at
rendering time. An example of a layer with grouped classes might contain:
LAYER
...
CLASSGROUP "group1"
...
CLASS
NAME "name1"
GROUP "group1"
...
END
CLASS
NAME "name2"
GROUP "group2"
...
END
CLASS
NAME "name3"
GROUP "group1"
...
END
...
END # layer
KEYIMAGE [filename] Full filename of the legend image for the CLASS. This image is used when building a legend
(or requesting a legend icon via MapScript or the CGI application).
LABEL Signals the start of a LABEL object. A class can contain multiple labels (since MapServer 6.2).
LEADER Signals the start of a LEADER object. Use this along with a LABEL object to create label leader lines.
New in version 6.2.
MAXSCALEDENOM [double] Minimum scale at which this CLASS is drawn. Scale is given as the denominator
of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer
5.0, to replace the deprecated MAXSCALE parameter.
See also:
Map Scale
MAXSIZE [integer]
Deprecated since version 6.0: Use CLASS STYLEs.
MINSCALEDENOM [double] Maximum scale at which this CLASS is drawn. Scale is given as the denominator of
the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer
5.0, to replace the deprecated MINSCALE parameter.
See also:
Map Scale
MINSIZE [integer]
Deprecated since version 6.0: Use CLASS STYLEs.
NAME [string] Name to use in legends for this class. If not set class won’t show up in legend.
4.1. Mapfile
121
MapServer Documentation, Release 7.0.6
OUTLINECOLOR [r] [g] [b] | [hexadecimal string]
Deprecated since version 6.0: Use CLASS STYLEs.
SIZE [integer]
Deprecated since version 6.0: Use CLASS STYLEs.
STATUS [on|off] Sets the current display status of the class. Default turns the class on.
STYLE Signals the start of a STYLE object. A class can contain multiple styles. Multiple styles can be used create
complex symbols (by overlay/stacking). See Cartographical Symbol Construction with MapServer for more
information on advanced symbol construction.
SYMBOL [integer|string|filename]
Deprecated since version 6.0: Use CLASS STYLEs.
TEMPLATE [filename] Template file or URL to use in presenting query results to the user. See Templating for more
info.
TEXT [string|expression] Text to label features in this class with. This overrides values obtained from the LAYER
LABELITEM. The string can contain references to feature attributes. This allows you to concatenate multiple
attributes into a single label. You can for example concatenate the attributes FIRSTNAME and LASTNAME
like this:
TEXT '[FIRSTNAME] [LASTNAME]'
More advanced Expressions can be used to specify the labels. Since version 6.0, there are functions available
for formatting numbers:
TEXT ("Area is: " + tostring([area],"%.2f"))
VALIDATION Signals the start of a VALIDATION block.
As of MapServer 5.4.0, VALIDATION blocks are the preferred mechanism for specifying validation patterns for
CGI param runtime substitutions. See Run-time Substitution.
4.1.3 CLUSTER
Table of Contents
• CLUSTER
– Description
– Supported Layer Types
– Mapfile Parameters
– Supported Processing Options
– Mapfile Snippet
– Feature attributes
– Handling GetFeatureInfo
– PHP MapScript Usage
– Example: Clustering Railway Stations
4.1. Mapfile
122
MapServer Documentation, Release 7.0.6
Description
Since version 6.0, MapServer has the ability to combine multiple features from a point layer into single (aggregated)
features based on their relative positions. Only POINT layers are supported. This feature was added through rfc69.
Supported Layer Types
Only layers of TYPE POINT are supported.
Mapfile Parameters
MAXDISTANCE [double] Specifies the distance of the search region (rectangle or ellipse) in pixel positions.
REGION [string] Defines the search region around a feature in which the neighbouring features are negotiated. Can
be ‘rectangle’ or ‘ellipse’.
BUFFER [double] Defines a buffer region around the map extent in pixels. Default is 0. Using a buffer allows that
the neighbouring shapes around the map are also considered during the cluster creation.
GROUP [string] This expression evaluates to a string and only the features that have the same group value are negotiated. This parameter can be omitted. The evaluated group value is available in the ‘Cluster_Group’ feature
attribute.
FILTER [string] We can define the FILTER expression filter some of the features from the final output. This expression evaluates to a boolean value and if this value is false the corresponding shape is filtered out. This expression
is evaluated after the the feature negotiation is completed, therefore the ‘Cluster_FeatureCount’ parameter can
also be used, which provides the option to filter the shapes having too many or to few neighbors within the
search region.
Supported Processing Options
The following processing options can be used with the cluster layers:
CLUSTER_GET_ALL_SHAPES=ON Return all shapes contained by a cluster instead of a single shape. This setting affects both the drawing and the query processing (especially useful for GetFeatureInfo requests). Example
usage: PROCESSING “CLUSTER_GET_ALL_SHAPES=ON”
CLUSTER_KEEP_LOCATIONS=ON Set whether the location of the cluster shape should be preserved (setting
this will show all points in the cluster). Example usage: PROCESSING “CLUSTER_KEEP_LOCATIONS=ON”
CLUSTER_USE_MAP_UNITS=ON Provide scale independent clustering (maxdistance and the buffer parameters
are specified in map units). Example usage: PROCESSING “CLUSTER_USE_MAP_UNITS=ON”
ITEMS Specify the feature attributes in the cluster to expose during a query, separated by a comma. Example usage:
PROCESSING “ITEMS=attribute_x,attribute_y,attribute_z”
Mapfile Snippet
LAYER
NAME "my-cluster"
TYPE POINT
...
CLUSTER
MAXDISTANCE 20 # in pixels
REGION "ellipse" # can be rectangle or ellipse
4.1. Mapfile
123
MapServer Documentation, Release 7.0.6
GROUP (expression) # an expression to create separate groups for each value
FILTER (expression) # a logical expression to specify the grouping condition
END
LABELITEM "Cluster_FeatureCount"
CLASS
...
LABEL
...
END
END
...
END
Feature attributes
The clustered layer itself provides the following aggregated attributes:
1. Cluster_FeatureCount - count of the features in the clustered shape
2. Cluster_Group - The group value of the cluster (to which the group expression is evaluated)
Note: If you are using MapServer version 6.x these attributes contain a ”:” in their names instead, such
as Cluster:FeatureCount & Cluster:Group. The “_” was changed in MapServer 7.
These attributes (in addition to the attributes provided by the original data source) can be used to configure the labels
of the features and can also be used in expressions. The ITEMS processing option can be used to specify a subset of
the attributes from the original layer in the query operations according to the user’s preference.
We can use simple aggregate functions (Min, Max, Sum, Count) to specify how the clustered attribute should be
calculated from the original attributes. The aggregate function should be specified as a prefix separated by ‘:’ in the
attribute definition, like: [Max:itemname]. If we don’t specify aggregate functions for the source layer attributes, then
the actual value of the cluster attribute will be non-deterministic if the cluster contains multiple shapes with different
values. The Count aggregate function in fact provides the same value as Cluster_FeatureCount.
Handling GetFeatureInfo
If you want to allow WMS GetFeatureInfo on all features inside a cluster, you must 1) set the “wms_include_items”
metadata as usual, and 2) set the following PROCESSING parameters in the layer:
PROCESSING "CLUSTER_GET_ALL_SHAPES=ON"
PROCESSING "ITEMS=attribute_x,attribute_y,attribute_z"
So your layer might look like the following:
LAYER
NAME "my-cluster"
TYPE POINT
METADATA
"wms_title"
"myttitle"
"wms_include_items" "all"
END
...
CLUSTER
...
4.1. Mapfile
124
MapServer Documentation, Release 7.0.6
END
LABELITEM "Cluster_FeatureCount"
CLASS
...
LABEL
...
END
END
...
PROCESSING "CLUSTER_GET_ALL_SHAPES=ON"
PROCESSING "ITEMS=name,description"
END
PHP MapScript Usage
The CLUSTER object is exposed through PHP MapScript. An example follows:
$map = ms_newMapobj("/var/www/vhosts/mysite/httpdocs/test.map");
$layer1=$map->getLayerByName("test1");
$layer1->cluster;
Example: Clustering Railway Stations
The following example uses a point datasource, in this case in KML format, to display clusters of railway stations.
Two classes are used: one to style and label the cluster, and one to style and label the single railway station.
Note: Since we can’t declare 2 labelitems, for the single railway class we use the TEXT parameter to label the station.
Mapfile Layer
####################
# Lightrail Stations
####################
SYMBOL
NAME "lightrail"
TYPE PIXMAP
IMAGE "../etc/lightrail.png"
END
LAYER
NAME "lightrail"
GROUP "default"
STATUS DEFAULT
TYPE POINT
CONNECTIONTYPE OGR
CONNECTION "lightrail-stations.kml"
DATA "lightrail-stations"
LABELITEM "Cluster_FeatureCount"
CLASSITEM "Cluster_FeatureCount"
###########################
# Define the cluster object
###########################
4.1. Mapfile
125
MapServer Documentation, Release 7.0.6
CLUSTER
MAXDISTANCE 50
REGION "ellipse"
END
################################
# Class1: For the cluster symbol
################################
CLASS
NAME "Clustered Lightrail Stations"
EXPRESSION ("[Cluster_FeatureCount]" != "1")
STYLE
SIZE 30
SYMBOL "citycircle"
COLOR 255 0 0
END
LABEL
FONT scb
TYPE TRUETYPE
SIZE 8
COLOR 255 255 255
ALIGN CENTER
PRIORITY 10
BUFFER 1
PARTIALS TRUE
POSITION cc
END
END
################################
# Class2: For the single station
################################
CLASS
NAME "Lightrail Stations"
EXPRESSION "1"
STYLE
SIZE 30
SYMBOL "lightrail"
END
TEXT "[Name]"
LABEL
FONT scb
TYPE TRUETYPE
SIZE 8
COLOR 0 0 0
OUTLINECOLOR 255 255 255
ALIGN CENTER
PRIORITY 9
BUFFER 1
PARTIALS FALSE
POSITION ur
END
END
# the following is used for a query
TOLERANCE 50
UNITS PIXELS
HEADER "../htdocs/templates/cluster_header.html"
FOOTER "../htdocs/templates/cluster_footer.html"
TEMPLATE "../htdocs/templates/cluster_query.html"
END
4.1. Mapfile
126
MapServer Documentation, Release 7.0.6
Map Image
4.1.4 COMPOSITE
Background
The COMPOSITE block is used to achieve blending effects with MapServer.
Some cartographic renderings benefit from the addition of advanced blending modes, as explained in detail in Blend
Modes. This functionality is essential for more pleasant renderings of raster hillshadings over vector surfaces. It is
also useful for simulating different kinds of overprinting effects.
See also:
rfc113
Performance is affected by advanced blending (all modes except src-over).
Parameters
OPACITY [integer] Sets the opacity level (or the inability to see through the layer) of all classed pixels for a given
layer. A value of 100 is opaque and 0 is fully transparent.
COMPOP [string] Name of the compositing operator to use when blending the temporary image onto the main map
image. See http://en.wikipedia.org/wiki/Blend_modes. The default compositing operator is “src-over”.
Available operators are:
• clear
4.1. Mapfile
127
MapServer Documentation, Release 7.0.6
• color-burn
• color-dodge
• contrast*
• darken
• difference
• dst
• dst-atop
• dst-in
• dst-out
• dst-over
• exclusion
• hard-light
• invert*
• invert-rgb*
• lighten
• minus*
• multiply
• overlay
• plus
• screen
• soft-light
• src
• src-atop
• src-in
• src-out
• src-over
• xor
Operators marked with a star (*) will only be supported when using an AGG backends and when pixman support
is not enabled, and will fall back to “src-over” when this is not the case.
Usage
Simple transparency / opacity is achieved by only specifying the OPACITY parameter (this achieves the same effect as
the legacy LAYER OPACITY parameter):
LAYER
COMPOSITE
OPACITY 70
END # COMPOSITE
4.1. Mapfile
128
MapServer Documentation, Release 7.0.6
...
END # LAYER
The darkening effect is achieved by adding the COMPOP parameter with the value darken:
LAYER
COMPOSITE
OPACITY 100
COMPOP "darken"
END # COMPOSITE
...
END # LAYER
4.1.5 Display of International Characters in MapServer
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2016-04-08
Table of Contents
• Display of International Characters in MapServer
– Credit
– Related Links
– Requirements
– How to Enable in Your Mapfile (MapServer >= 7.0)
* Step 1: Verify ICONV Support and MapServer Version
* Step 2: Verify That Your Files’ Encoding is Supported by ICONV
* Step 3: Add ENCODING Parameter to your LAYER Object
* Step 4: Test with the shp2img utility
– How to Enable in Your Mapfile (MapServer < 7.0)
* Add ENCODING Parameter to your LABEL Object
– Example Using PHP MapScript
– Notes
Credit
Initial functionality was added to MapServer 4.4.0 as a part of a project sponsored by the Information-technology
Promotion Agency (IPA), in Japan. Project members included: Venkatesh Raghavan, Masumoto Shinji, Nonogaki
Susumu, Nemoto Tatsuya, Hirai Naoki (Osaka City University, Japan), Mario Basa, Hagiwara Akira, Niwa Makoto,
Mori Toru (Orkney Inc., Japan), and Hattori Norihiro (E-Solution Service, Inc., Japan).
4.1. Mapfile
129
MapServer Documentation, Release 7.0.6
Related Links
• MapServer ticket:858 (original implementation)
• RFC 103: Layer Level Character Encoding changes in MapServer 7
• MapServer ticket:4758 (MapServer 7 updates)
Requirements
• MapServer >= 4.4.0 (MapServer >= 7.0 for layer-level encoding)
• MapServer compiled with the libiconv library
How to Enable in Your Mapfile (MapServer >= 7.0)
The MapServer 7.0 release contained changes in how MapServer handles encoding; new in 7.0 is that encoding is
set at the LAYER level. This makes it much easier to manage having multiple layers in different encodings, in the
same mapfile. The reason for this change was that the encoding of a dataset affects the whole layer, not only the
labels. MapServer 7 will also convert any strings into UTF8 in the background, and any output (such as through OGC
GetCapabilities, GetFeature, or queries) will be returned in UTF8.
The mapfile LAYER object’s ENCODING parameter accepts the encoding name as its parameter.
MapServer uses GNU’s libiconv library to deal with encodings. The libiconv web site has a list of supported encodings.
One can also use the “iconv -l” command on a system with libiconv installed to get the complete list of supported
encodings on that specific system.
Note: The label object’s ENCODING parameter is deprecated, but some logic still exists to handle that use in that
scenario, in MapServer 7.
Step 1: Verify ICONV Support and MapServer Version
Execute ‘’mapserv -v’ at the commandline, and verify that your MapServer version >= 7.0 and it includes ‘’SUPPORTS=ICONV’‘, such as:
> mapserv -v
MapServer version 7.0.1 (MS4W 3.1.3) OUTPUT=PNG OUTPUT=JPEG
OUTPUT=KML SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=CAIRO
SUPPORTS=ICONV SUPPORTS=FRIBIDI SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT
SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER
SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS SUPPORTS=GEOS
INPUT=JPEG INPUT=POSTGIS INPUT=ORACLESPATIAL INPUT=OGR INPUT=GDAL
INPUT=SHAPEFILE
Step 2: Verify That Your Files’ Encoding is Supported by ICONV
Since MapServer uses the libiconv library to handle encodings, you can check the list of supported encodings here:
http://www.gnu.org/software/libiconv/
Unix users can also use the iconv -l command on a system with libiconv installed to get the complete list of supported
encodings on that specific system.
4.1. Mapfile
130
MapServer Documentation, Release 7.0.6
Step 3: Add ENCODING Parameter to your LAYER Object
Now you can simply add the ENCODING parameter to your mapfile LAYER object, such as:
MAP
...
LAYER
...
ENCODING "SHIFT_JIS"
CLASS
...
END #class
END #layer
END #map
Note: Make sure you save your mapfile in the “UTF-8” encoding in your text editor.
LAYER
NAME "åIJřåŘ "
DATA "chimei.shp"
STATUS DEFAULT
TYPE POINT
ENCODING "SHIFT_JIS"
LABELITEM "NAMAE"
CLASS
NAME "åIJřåŘ "
STYLE
COLOR 10 100 100
END
LABEL
TYPE TRUETYPE
FONT "pgothic"
COLOR 220 20 20
SIZE 7
POSITION CL
PARTIALS FALSE
BUFFER 3
END
END
END
Step 4: Test with the shp2img utility
• see shp2img commandline utility
4.1. Mapfile
131
MapServer Documentation, Release 7.0.6
How to Enable in Your Mapfile (MapServer < 7.0)
Older MapServer versions only allowed encoding to be set at the LABEL level in the mapfile.
Add ENCODING Parameter to your LABEL Object
Add the ENCODING parameter to your mapfile LABEL object, such as:
MAP
...
LAYER
...
CLASS
...
LABEL
...
ENCODING "SHIFT_JIS"
END
END
4.1. Mapfile
132
MapServer Documentation, Release 7.0.6
END
END
Here is an example layer using the encoding set at the LABEL level:
LAYER
NAME "chimei"
DATA "chimei.shp"
STATUS DEFAULT
TYPE POINT
LABELITEM "NAMAE"
CLASS
NAME "CHIMEI"
STYLE
COLOR 10 100 100
END
LABEL
TYPE TRUETYPE
FONT "kochi-gothic"
COLOR 220 20 20
SIZE 10
POSITION CL
PARTIALS FALSE
BUFFER 0
ENCODING "SHIFT_JIS"
END
END
END
Example Using PHP MapScript
For PHP Mapscript, the Encoding parameter is included in the LabelObj Class (for MapServer < 7), so that the
encoding parameter of a layer can be modified such as:
// Loading the php_mapscript library
dl("php_mapscript.so");
// Loading the map file
$map = ms_newMapObj("example.map");
// get the desired layer
$layer = $map->getLayerByName("chimei");
// get the layer's class object
$class = $layer->getClass(0);
// get the class object's label object
$clabel= $class->label;
// get encoding parameter
$encode_str = $clabel->encoding;
print "Encoding = ".$encode_str."\n";
// set encoding parameter
$clabel->set("encoding","UTF-8");
4.1. Mapfile
133
MapServer Documentation, Release 7.0.6
Notes
Note:
During initial implementation, this functionality was tested using the different Japanese encoding systems:
Shift-JIS, EUC-JP, UTF-8, as well as Thai’s TIS-620 encoding system.
Examples of encodings for the Latin alphabet supported by libiconv are: ISO-8859-1 (Latin alphabet No. 1 - also
known as LATIN-1 - western European languages), ISO-8859-2 (Latin alphabet No. 2 - also known as LATIN-2 eastern European languages), CP1252 (Microsoft Windows Latin alphabet encoding - English and some other Western
languages).
4.1.6 Expressions
Author Dirk Tilger
Contact dirk at MIRIUP.DE
Author Umberto Nicoletti
Contact umberto.nicoletti at gmail.com
Last Updated 2016-11-26
Contents
• Expressions
– Introduction
* String quotation
* Quotes escaping in strings
* Using attributes
– Expression Types
– String comparison (equality)
– Regular expression comparison
– List expressions
– “MapServer expressions”
* Typing
* Logical expressions
* String expressions that return a logical value
* Arithmetic expressions that return a logical value
* Spatial expressions that return a logical value (GEOS)
* String operations that return a string
* Functions that return a string
* String functions that return a number
* Arithmetic operations and functions that return a number
4.1. Mapfile
134
MapServer Documentation, Release 7.0.6
* Spatial functions that return a number (GEOS)
* Spatial functions that return a shape (GEOS)
* Temporal expressions
Introduction
As of version 6.0, expressions are used in four places:
• In LAYER FILTER to specify the features of the dataset that are to be included in the layer.
• In CLASS EXPRESSION to specify to which features of the dataset the CLASS applies to.
• In CLASS TEXT to specify text for labeling features.
• In STYLE GEOMTRANSFORM.
String quotation
Strings can be quoted using single or double quotes:
'This is a string'
"And this is also a string"
Quotes escaping in strings
Note: Quotes escaping is not supported in MapServer versions lower than 5.0.
Starting with MapServer 5.0, if your dataset contains double-quotes, you can use a C-like escape sequence:
"National \"hero\" statue"
To escape a single quote use the following sequence instead:
"National \'hero\' statue"
Starting with MapServer 6.0 you don’t need to escape single quotes within double quoted strings and you don’t need
to escape double quotes within single quoted strings. In 6.0 you can also write the string as follows:
'National "hero" statue'
...
To escape a single quote use the following sequence instead:
"National 'hero' statue"
Using attributes
Attribute values can be referenced in the Map file and used in expressions. Attribute references are case sensitive and
can be used in the following types of expressions:
4.1. Mapfile
135
MapServer Documentation, Release 7.0.6
• In LAYER FILTER
• In CLASS EXPRESSION
• In CLASS TEXT
Referencing an attribute is done by enclosing the attribute name in square brackets, like this: [ATTRIBUTENAME].
Then, every occurrence of “[ATTRIBUTENAME]” will be replaced by the actual value of the attribute “ATTRIBUTENAME”.
Example: The data set of our layer has the attribute “BUILDING_NAME”. We want the value of this attribute to
appear inside a string. This can be accomplished as follows (single or double quotes):
'The [BUILDING_NAME] building'
For the building which has its BUILDING_NAME attribute set to “Historical Museum”, the resulting string is:
'The Historical Museum building'
For Raster Data layers special attributes have been defined that can be used for classification, for example:
• [PIXEL] ... will become the pixel value as number
• [RED], [GREEN], [BLUE] ... will become the color value for the red, green and blue component in the pixel
value, respectively.
Expression Types
Expression are used to match attribute values with certain logical checks. There are three different types of expressions
you can use with MapServer:
• String comparisons: A single attribute is compared with a string value.
• Regular expressions: A single attribute is matched with a regular expression.
• List expressions: Compare a string attribute to a list of multiple possible values
• Logical “MapServer expressions”: One or more attributes are compared using logical expressions.
String comparison (equality)
String comparison means, as the name suggests, that attribute values are checked if they are equal to some value.
String comparisons are the simplest form of MapServer expressions and the fastest option.
To use a string comparison for filtering a LAYER, both FILTERITEM and FILTER must be set. FILTERITEM is set to
the attribute name. FILTER is set to the value for comparison. The same rule applies to CLASSITEM in the LAYER
object and EXPRESSION in the CLASS object.
Example for a simple string comparison filter
FILTER "2005"
FILTERITEM "year"
would match all records that have the attribute “year” set to “2005”. The rendered map would appear as if the dataset
would only contain those items that have the “year” set to “2005”.
Similarly, a classification for the items matched above would be done by setting the CLASSITEM in the LAYER and
the EXPRESSION in the CLASS:
4.1. Mapfile
136
MapServer Documentation, Release 7.0.6
LAYER
NAME "example"
CLASSITEM "year"
...
CLASS
NAME "year-2005"
EXPRESSION "2005"
...
END
END
For reasons explained later, the values for both CLASSITEM and FILTERITEM should start with neither a ‘/’ nor a ‘(‘
character.
Regular expression comparison
Regular expressions are a standard text pattern matching mechanism from the Unix world. The functionality of regular
expression matching is provided by the operating system on UNIX systems and therefore slightly operating system
dependent. However, their minimum set of features are those defined by the POSIX standard. The documentation of
the particular regular expression library is usually in the “regex” manual page (“man regex”) on Unix systems.
Regular expression with MapServer work similarly to string comparison, but allow more complex operation. They
are slower than pure string comparisons, but might be still faster than logical expression. As for string comparison,
when using a regular expressions, FILTERITEM (LAYER FILTER) or CLASSITEM (CLASS EXPRESSION) has to be
defined if the items are not included in the LAYER FILTER or CLASS EXPRESSION.
A regular expression typically consists of characters with special meanings and characters that are interpreted as they
are. Alphanumeric characters (A-Z, a-z and 0-9) are taken as they are. Characters with special meanings are:
• . will match a single character.
• [ and ] are used for grouping. For example [A-Z] would match the characters A,B,C,...,X,Y,Z.
• {, }, and * are used to specify how often something should match.
• ^ matches the beginning, $ matches the end of the value.
• The backslash \ is used to take away the special meaning. For example \$ would match the dollar sign.
MapServer supports two regex operators:
• ~ case sensitive regular expression
• ~* case insensitive regular expression
The following LAYER configuration would have all records rendered on the map that have “hotel” in the attribute
named “placename”
LAYER
NAME 'regexp-example'
FILTERITEM 'placename'
FILTER /hotel/
...
END
Note: For FILTER, the regular expression is case-sensitive, thus records having “Hotel” in them would not have
matched.
4.1. Mapfile
137
MapServer Documentation, Release 7.0.6
Example: Match records that have a value from 2000 to 2010 in the attribute “year”:
FILTERITEM "year"
FILTER /^20[0-9][0-9]/
Example: Match all the records that are either purely numerical or empty
FILTER /^[0-9]*$/
Example: Match all the features where the name attribute ends with “by”, “BY”, “By” or “bY” (case insensitive
matching):
EXPRESSION ('[name]' ~* 'by$')
Example: Match all the features where the rdname attribute starts with “Main”.
LAYER
...
CLASSITEM 'rdname'
CLASS
EXPRESSION /^Main.*$/
Note: If you experience frequently segmentation faults when working with MapServer and regular expressions, it
might be that your current working environment is linked against more than one regular expression library. This can
happen when MapServer is linked with components that bring their own copy, like the Apache httpd or PHP. In these
cases the author has made best experiences with making all those components using the regular expression library of
the operating system (i.e. the one in libc). That involved editing the build files of some of the components, however.
List expressions
New in version 6.4.
List expressions (see rfc95) are a performant way to compare a string attribute to a list of multiple possible values.
Their behavior duplicates the existing regex or mapserver expressions, however they are significantly more performant.
To activate them enclose a comma separated list of values between {}, without adding quotes or extra spaces.
LAYER
NAME 'list-example'
CLASSITEM 'roadtype'
...
CLASS
EXPRESSION {motorway,trunk}
#equivalent to regex EXPRESSION /motorway|trunk/
#equivalent to mapserver EXPRESSION ("[roadtype]" IN "motorway,trunk")
...
END
CLASS
EXPRESSION {primary,secondary}
...
END
END
4.1. Mapfile
138
MapServer Documentation, Release 7.0.6
Warning: List expressions do not support quote escaping, or attribute values that contain a comma in them.
“MapServer expressions”
MapServer expressions are the most complex and depending how they are written can become quite slow. They can
match any of the attributes and thus allow filtering and classification depending on more than one attribute. Besides
pure logical operations there are also expressions that allow certain arithmetic, string and time operations.
To be able to use a MapServer expression for a FILTER or EXPRESSION value, the expression has to finally become
a logical value.
Typing
The type of attributes and literals is determined as followed :
• Strings: enclosed in quote or single quote characters
"[string_attribute]" or '[string_attribute]'
"string_literal" or 'string_literal'
• Numbers: no quoting
[numeric_attribute]
numeric_value
• Date-time: enclosed in backquote characters
`[date_time_attribute]`
`date_time_literal`
Logical expressions
Syntactically, a logical expression is everything encapsulated in round brackets. Logical expressions take logical
values as their input and return logical values. A logical expression is either ‘true’ or ‘false’.
• ( ( Expression1 ) AND ( Expression2 ) )
( ( Expression1 ) && ( Expression2 ) )
returns true when both of the logical expressions (Expression1 and Expression2) are true.
• ( ( Expression1 ) OR ( Expression2 ) )
( ( Expression1 ) || ( Expression2 ) )
returns true when at least one of the logical expressions (Expression1 or Expression2) is true.
• NOT ( Expression1 )
! ( Expression1 )
returns true when Expression1 is false.
4.1. Mapfile
139
MapServer Documentation, Release 7.0.6
String expressions that return a logical value
Syntactically, a string is something encapsulated in single or double quotes.
• ( “String1” eq “String2” )
( “String1” == “String2” ) - deprecated since 6.0
( “String1” = “String2” )
returns true when the strings are equal. Case sensitive.
• ( “String1” =* “String2” )
returns true when the strings are equal. Case insensitive.
• ( “String1” != “String2” )
( “String1” ne “String2” )
returns true when the strings are not equal.
• ( “String1” < “String2” )
( “String1” lt “String2” )
returns true when “String1” is lexicographically smaller than “String2”
• ( “String1” > “String2” )
( “String1” gt “String2” )
returns true when “String1” is lexicographically larger than “String2”.
• ( “String1” <= “String2” )
( “String1” le “String2” )
returns true when “String1” is lexicographically smaller than or equal to “String2”
• ( “String1” >= “String2” )
( “String1” ge “String2” )
returns true when “String1” is lexicographically larger than or equal to “String2”.
• ( “String1” IN “token1,token2,...,tokenN” )
returns true when “String1” is equal to one of the given tokens.
Note: The separator for the tokens is the comma. That means that there can not be unnecessary white space in
the list and that tokens that have commas in them cannot be compared.
• ( “String1” ~ “regexp” )
returns true when “String1” matches the regular expression “regexp”. This operation is identical to the regular
expression matching described earlier.
• ( “String1” ~* “regexp” )
returns true when “String1” matches the regular expression “regexp” (case insensitive). This operation is identical to the regular expression matching described earlier.
4.1. Mapfile
140
MapServer Documentation, Release 7.0.6
Arithmetic expressions that return a logical value
The basic element for arithmetic operations is the number. Arithmetic operations that return numbers will be covered
in the next section.
• ( n1 eq n2 )
( n1 == n2 ) - deprecated since 6.0
( n1 = n2 )
returns true when the numbers are equal.
• ( n1 != n2 )
( n1 ne n2 )
returns true when the numbers are not equal.
• ( n1 < n2 )
( n1 lt n2 )
returns true when n1 is smaller than n2.
• ( n1 > n2 )
( n1 gt n2 )
returns true when n1 is larger than n2.
• ( n1 <= n2 )
( n1 le n2 )
returns true when n1 is smaller than or equal to n2.
• ( n1 >= n2 )
( n1 ge n2 )
returns true when n1 is larger than or equal to n2.
• ( n1 IN “number1,number2,...,numberN” )
returns true when n1 is equal to one of the given numbers.
Spatial expressions that return a logical value (GEOS)
• ( shape1 eq shape2 )
returns true if shape1 and shape2 are equal
• ( shape1 intersects shape2 )
returns true if shape1 and shape2 intersect
New in version 6.0.
• ( shape1 disjoint shape2 )
returns true if shape1 and shape2 are disjoint
New in version 6.0.
4.1. Mapfile
141
MapServer Documentation, Release 7.0.6
• ( shape1 touches shape2 )
returns true if shape1 and shape2 touch
New in version 6.0.
• ( shape1 overlaps shape2 )
returns true if shape1 and shape2 overlap
New in version 6.0.
• ( shape1 crosses shape2 )
returns true if shape1 and shape2 cross
New in version 6.0.
• ( shape1 within shape2 )
returns true if shape1 is within shape2
New in version 6.0.
• ( shape1 contains shape2 )
returns true if shape1 contains shape2
New in version 6.0.
• ( shape1 dwithin shape2 )
returns true if the distance between shape1 and shape2 is equal to 0
New in version 6.0.
• ( shape1 beyond shape2 )
returns true if the distance between shape1 and shape2 is greater than 0
New in version 6.0.
String operations that return a string
• “String1” + “String2’
returns “String1String2”, that is, the two strings concatenated to each other.
Functions that return a string
• tostring ( n1, “Format1” )
uses “Format1” to format the number n1 (C style formatting - sprintf).
New in version 6.0.
• commify ( “String1” )
adds thousands separators (commas) to a long number to make it more readable
New in version 6.0.
4.1. Mapfile
142
MapServer Documentation, Release 7.0.6
• upper ( “String1” )
force all characters to uppercase
New in version 7.0.
• lower ( “String1” )
force all characters to lowercase
New in version 7.0.
• initcap ( “String1” )
force the first character to uppercase and the rest of the characters to lower case for EACH word in the string.
New in version 7.0.
• firstcap ( “String1” )
force the first character to uppercase and the rest of the characters to lower case in the first word in the string.
New in version 7.0.
String functions that return a number
• length ( “String1” )
returns the number of characters of “String1”
Arithmetic operations and functions that return a number
• round ( n1 , n2 )
returns n1 rounded to a multiple of n2: n2 * round(n1/n2)
New in version 6.0.
• n1 + n2
returns the sum of n1 and n2
• n1 - n2
returns n2 subtracted from n1
• n1 * n2
returns n1 multiplicated with n2
• n1 / n2>
returns n1 divided by n2
• -n1
returns n1 negated
• n1 ^ n2
returns n1 to the power of n2
Note: When the numerical operations above are used like logical operations, the following rule applies: values equal
to zero will be taken as ‘false’ and everything else will be ‘true’. That means the expression
4.1. Mapfile
143
MapServer Documentation, Release 7.0.6
( 6 + 5 )
would return true, but
( 5 - 5 )
would return false.
Spatial functions that return a number (GEOS)
• area ( shape1 )
returns the area of shape1
New in version 6.0.
Spatial functions that return a shape (GEOS)
• fromtext ( “String1” )
returns the shape corresponding to String1 (WKT - well known text)
fromText('POINT(500000 5000000)')
New in version 6.0.
• buffer (shape1 , n1 )
returns the shape that results when shape1 is buffered with bufferdistance n1
New in version 6.0.
• difference ( shape1 , shape2 )
returns the shape that results when the common area of shape1 and shape2 is subtracted from shape1
New in version 6.0.
Temporal expressions
MapServer uses an internal time type to do comparison. To convert a string into this time type it will check the list
below from the top and down to check if the specified time matches, and if so, it will do the conversion. The following
are integer values: YYYY - year, MM - month, DD - date, hh - hours, mm - minutes, ss - seconds. The following
are character elements of the format: - (dash) - date separator, : (colon) - time separator, T - marks the start of the
time component (ISO 8601), space - marks the end of the date and start of the time component, Z - zulu time (0 UTC
offset).
• ‘YYYY-MM-DDThh:mm:ssZ‘
• ‘YYYY-MM-DDThh:mm:ss‘
• ‘YYYY-MM-DD hh:mm:ss‘
• ‘YYYY-MM-DDThh:mm‘
• ‘YYYY-MM-DD hh:mm‘
• ‘YYYY-MM-DDThh‘
4.1. Mapfile
144
MapServer Documentation, Release 7.0.6
• ‘YYYY-MM-DD hh‘
• ‘YYYY-MM-DD‘
• ‘YYYY-MM‘
• ‘YYYY‘
• ‘Thh:mm:ssZ‘
• ‘Thh:mm:ss‘
For temporal values obtained this way, the following operations are supported:
• ( t1 eq t2 )
( t1 == t2 ) - deprecated since 6.0
( t1 = t2 )
returns true when the times are equal.
• ( t1 != t2 )
( t1 ne t2 )
returns true when the times are not equal.
• ( t1 < t2 )
( t1 lt t2 )
returns true when t1 is earlier than t2
• ( t1 > t2 )
( t1 gt t2 )
returns true when t1 is later than t2.
• ( t1 <= t2 )
( t1 le t2 )
returns true when t1 is earlier than or equal to t2
• ( t1 >= t2 )
( t1 ge t2 )
returns true when t1 is later than or equal to t2.
4.1.7 FEATURE
POINTS A set of xy pairs terminated with an END, for example:
POINTS 1 1 50 50 1 50 1 1 END
Note: POLYGON/POLYLINE layers POINTS must start and end with the same point (i.e. close the feature).
Multipart features can be created by adding further sets of points, for example:
4.1. Mapfile
145
MapServer Documentation, Release 7.0.6
FEATURE
POINTS 1 1 50 50 1 50 1 1 END
POINTS 100 100 50 50 100 50 100 100 END
END
ITEMS Comma separated list of the feature attributes:
ITEMS "value1;value2;value3"
Note: Specifying the same number of items is recommended for each feature of the same layer. The item
names should be specified as a PROCESSING option of the layer.
TEXT [string] String to use for labeling this feature.
WKT [string] A geometry expressed in OpenGIS Well Known Text geometry format. This feature is only supported
if MapServer is built with OGR or GEOS support.
WKT "POLYGON((500 500, 3500 500, 3500 2500, 500 2500, 500 500))"
WKT "POINT(2000 2500)"
Note: Inline features should be defined as their own layers in the mapfile. If another CONNECTIONTYPE is
specified in the same layer, MapServer will always use the inline features to draw the layer and ignore the other
CONNECTIONTYPEs.
4.1.8 FONTSET
Author Kari Guerts
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2008/10/08
Contents
• FONTSET
– Format of the fontset file
FONTSET is a MAP parameter. The syntax is:
FONTSET [filename]
Where filename gives the location of the fontset file of the system. The location of the system fontset file could for
instance be /usr/share/fonts/truetype/font.list (Debian). The location can be specified using a relative or absolute path.
Format of the fontset file
The format of the fontset file is very simple. Each line contains 2 items: An alias and the name/path of the font
separated by white space. The alias is simply the name you refer to the font as in your Mapfile (eg. times-bold). The
4.1. Mapfile
146
MapServer Documentation, Release 7.0.6
name is the actual name of the TrueType file. If not full path then it is interpreted as relative to the location of the
fontset. Here’s the fontset I use (the font.list file and all .ttf files are stored in the same sub-directory).
Note: Aliases are case sensitive. Excellent reference information about the TrueType format and online font resources
is available from the FreeType.
arial
arial-bold
arial-italic
arial-bold-italic
arial_black
comic_sans
comic_sans-bold
courier
courier-bold
courier-italic
courier-bold-italic
georgia
georgia-bold
georgia-italic
georgia-bold-italic
impact
monotype.com
recreation_symbols
times
times-bold
times-italic
times-bold-italic
trebuchet_ms
trebuchet_ms-bold
trebuchet_ms-italic
trebuchet_ms-bold-italic
verdana
verdana-bold
verdana-italic
verdana-bold-italic
arial.ttf
arialbd.ttf
ariali.ttf
arialbi.ttf
ariblk.ttf
comic.ttf
comicbd.ttf
cour.ttf
courbd.ttf
couri.ttf
courbi.ttf
georgia.ttf
georgiab.ttf
georgiai.ttf
georgiaz.ttf
impact.ttf
monotype.ttf
recreate.ttf
times.ttf
timesbd.ttf
timesi.ttf
timesbi.ttf
trebuc.ttf
trebucbd.ttf
trebucit.ttf
trebucbi.ttf
verdana.ttf
verdanab.ttf
verdanai.ttf
verdanaz.ttf
4.1.9 GEOMTRANSFORM - Geometry Transformations
Author HÃěvard Tveite
Contact havard.tveite@nmbu.no
Table of Contents
• Transformations for simple styling (CLASS STYLE only)
– bbox
– centroid
– end and start
– vertices
4.1. Mapfile
147
MapServer Documentation, Release 7.0.6
• Labels (LABEL STYLE only)
– labelpnt and labelpoly
• Expressions and advanced transformations (LAYER and CLASS STYLE)
– Combining / chaining expressions
* buffer
– generalize ([shape], tolerance)
– simplify([shape], tolerance)
– simplifypt([shape], tolerance)
– smoothsia ( [shape], smoothing_size, smoothing_iterations, preprocessing )
* Tuning the behaviour of smoothsia
* Dataset resolution is too high
* Dataset resolution is too low
* Curves
• Javascript transformation
– Introduction
– Usage
* Example 1. Simple Geomtransform
* Example 2. Printing logs in MapServer logs
– Basic API
* pointObj
· Constructor
· Members
· Methods
* lineObj
· Constructor
· Members
· Methods
* shapeObj
· Constructor
· Members
· Methods
Geometry transformations return a new geometry. The purpose of a geometry transformation can be to achieve special
effects for symbol rendering and labeling.
Geometry transformation is available at the LAYER level and the STYLE level. At the LAYER level (since 6.4), the
original vector geometry (“real world” coordinates) is used. At the STYLE level, pixel coordinates are used.
It may be useful to apply pixel values also at the LAYER level, and that is possible. If UNITS is defined in the LAYER,
4.1. Mapfile
148
MapServer Documentation, Release 7.0.6
the [map_cellsize] variable can be used to convert to pixel values at the LAYER level:
GEOMTRANSFORM (simplify([shape], [map_cellsize]*10))
Transformations for simple styling (CLASS STYLE only)
The following simple geometry transformations are available at the CLASS STYLE level:
• bbox
• centroid
• end
• start
• vertices
bbox
• GEOMTRANSFORM bbox returns the bounding box of the geometry.
– GEOMTRANSFORM “bbox”
Note: Only available for STYLE in the CLASS context.
Fig. 4.17: Geomtransform bbox
Class definitions for the example:
CLASS
STYLE
COLOR 0 0 0
WIDTH 6
END # STYLE
STYLE
GEOMTRANSFORM "bbox"
OUTLINECOLOR 255 0 0
WIDTH 1
PATTERN 1 2 END
END # STYLE
END # CLASS
4.1. Mapfile
149
MapServer Documentation, Release 7.0.6
centroid
• GEOMTRANSFORM centroid returns the centroid of the geometry.
– GEOMTRANSFORM “centroid”
Note: Only available for STYLE in the CLASS context.
Fig. 4.18: Geomtransform centroid
Style definitions for the example.:
STYLE
GEOMTRANSFORM "centroid"
COLOR 255 0 0
SYMBOL circlef
SIZE 5
END # STYLE
Symbol definition for the circlef symbol:
SYMBOL
NAME "circlef"
TYPE ellipse
FILLED true
POINTS
1 1
END # POINTS
END # SYMBOL
end and start
• GEOMTRANSFORM end returns the end point of a line.
• GEOMTRANSFORM start returns the start point of a line.
– GEOMTRANSFORM “start”
– GEOMTRANSFORM “end” (since END is used to end objects in the map file, end must be embedded in
quotes)
The direction of the line at the start / end point is available for rendering effects.
Note: Only available for STYLE in the CLASS context.
4.1. Mapfile
150
MapServer Documentation, Release 7.0.6
Fig. 4.19: Geomtransform start and end usage
Class definitions for the example.
Lower part of the figure:
CLASS
STYLE
GEOMTRANSFORM "start"
SYMBOL "circlef"
COLOR 255 0 0
SIZE 20
END # STYLE
STYLE
COLOR 0 0 0
WIDTH 4
END # STYLE
STYLE
GEOMTRANSFORM "end"
SYMBOL "circlef"
COLOR 0 255 0
SIZE 20
END # STYLE
END # CLASS
Upper part of the figure:
CLASS
STYLE
COLOR 0 0 0
WIDTH 4
END # STYLE
STYLE
GEOMTRANSFORM "start"
SYMBOL "startarrow"
COLOR 255 0 0
SIZE 20
ANGLE auto
END # STYLE
4.1. Mapfile
151
MapServer Documentation, Release 7.0.6
STYLE
GEOMTRANSFORM "start"
SYMBOL "circlef"
COLOR 0 0 255
SIZE 5
END # STYLE
STYLE
GEOMTRANSFORM "end"
SYMBOL "endarrow"
COLOR 0 255 0
SIZE 20
ANGLE auto
END # STYLE
STYLE
GEOMTRANSFORM "end"
SYMBOL "circlef"
COLOR 0 0 255
SIZE 5
END # STYLE
END # CLASS
The startarrow symbol definition (endarrow is the same, except for ANCHORPOINT (value for endarrow: 1 0.5):
SYMBOL
NAME "startarrow"
TYPE vector
FILLED true
POINTS
0 0.4
3 0.4
3 0
5 0.8
3 1.6
3 1.2
0 1.2
0 0.4
END # POINTS
ANCHORPOINT 0 0.5
END # SYMBOL
vertices
• GEOMTRANSFORM vertices produces the set of vertices of a line (with direction information).
– GEOMTRANSFORM “vertices”
Note: Only available for STYLE in the CLASS context.
Class definitions for the example:
CLASS
STYLE
COLOR 0 0 0
WIDTH 4
END # STYLE
4.1. Mapfile
152
MapServer Documentation, Release 7.0.6
Fig. 4.20: Geomtransform vertices
STYLE
GEOMTRANSFORM "vertices"
SYMBOL "vertline"
COLOR 0 0 0
WIDTH 2
SIZE 20
ANGLE AUTO
END # STYLE
END # CLASS
The vertline symbol definition:
SYMBOL
NAME "vertline"
TYPE vector
POINTS
0 0
0 1
END # POINTS
END # SYMBOL
Labels (LABEL STYLE only)
The following simple geometry transformations are available at the LABEL STYLE level:
• labelpnt
• labelpoly
These are used for label styling (background colour, background shadow, background frame).
Note: The result of using labelpnt is affected by the LAYER LABELCACHE setting. If LABELCACHE is ON (the
default), the label will be shifted when a non-zero sized symbol is added using labelpnt.
labelpnt and labelpoly
• GEOMTRANSFORM labelpnt produces the geographic position the label is attached to. This corresponds to the
center of the label text only if the label is in position CC.
– GEOMTRANSFORM “labelpnt”
• GEOMTRANSFORM labelpoly produces a polygon that covers the label plus a 1 pixel padding.
4.1. Mapfile
153
MapServer Documentation, Release 7.0.6
– GEOMTRANSFORM “labelpoly”
Note: Only available for STYLE in the LABEL context.
These transformations can be used to make background rectangles for labels and add symbols to the label points.
Fig. 4.21: Geomtransform labelpnt and labelpoly
Class definitions for the example:
CLASS
STYLE
OUTLINECOLOR 255 255 204
END # STYLE
LABEL
SIZE giant
POSITION UC
STYLE # shadow
GEOMTRANSFORM "labelpoly"
COLOR 153 153 153
OFFSET 3 3
END # Style
STYLE # background
GEOMTRANSFORM "labelpoly"
COLOR 204 255 204
END # Style
STYLE # outline
GEOMTRANSFORM "labelpoly"
OUTLINECOLOR 0 0 255
WIDTH 1
END # Style
STYLE
GEOMTRANSFORM "labelpnt"
SYMBOL 'circlef'
COLOR 255 0 0
SIZE 15
END # Style
END # Label
END # Class
Symbol definition for the circlef symbol:
SYMBOL
NAME "circlef"
TYPE ellipse
FILLED true
4.1. Mapfile
154
MapServer Documentation, Release 7.0.6
POINTS
1 1
END # POINTS
END # SYMBOL
Expressions and advanced transformations (LAYER and CLASS STYLE)
Combining / chaining expressions
A geometry transformation produces a geometry, and that geometry can be used as input to another geometry transformation. There are (at least) two ways to accomplish this. One is to combine basic geometry transformation expressions
into more complex geometry transformation expressions, and another is to combine a geometry transformation expression at the LAYER level with a geometry transformation expressions or a simple geometry transformation at the CLASS
STYLE level.
Combining geometry transformation expressions A geometry transformation expression contains a [shape] part. The
[shape] part can be replaced by a geometry transformation expression.
For example:
GEOMTRANSFORM (simplify(buffer([shape], 20),10))
In this transformation, buffer is first applied on the geometry ([shape]). The resulting geometry is then used as input
to simplify.
A style that demonstrates this:
STYLE
GEOMTRANSFORM (simplify(buffer([shape], 20),10))
OUTLINECOLOR 255 0 0
WIDTH 2
END # STYLE
The result of this transformation is shown at the top of the following figure (red line). The original polygon is shown
with a full black line and the buffer with a dashed black line.
Combining expressions with simple geometry transformations Simple geometry transformations are only available for
CLASS STYLE, but can be combined with geometry transformation expressions at the LAYER level.
Excerpts from a layer definitions that does this kind of combination:
LAYER
...
GEOMTRANSFORM (simplify(buffer([shape], 10),5))
CLASS
...
STYLE
GEOMTRANSFORM "vertices"
COLOR 255 102 102
SYMBOL vertline
SIZE 20
WIDTH 2
ANGLE auto
END # STYLE
END # CLASS
END # LAYER
4.1. Mapfile
155
MapServer Documentation, Release 7.0.6
The result of this transformation is shown at the bottom of the following figure (the red lines). The result of the LAYER
level geomtransform is shown with a full black line. The original polygon is the same as the one used at the top of the
figure.
Fig. 4.22: Combining geomtransform expressions
buffer
• GEOMTRANSFORM buffer returns the buffer of the original geometry. The result is always a polygon geometry.
– GEOMTRANSFORM (buffer ([shape], buffersize))
Note: Negative values for buffersize (setback) is not supported.
Note: Can be used at the LAYER level and for STYLE in the CLASS context.
Note: Buffer does not seem to work for point geometries.
Some class definitions for the example.
Lower part (polygon with buffers):
CLASS
STYLE
OUTLINECOLOR 0 255 0
GEOMTRANSFORM (buffer([shape], 20))
WIDTH 1
END # STYLE
STYLE
OUTLINECOLOR 0 0 255
GEOMTRANSFORM (buffer([shape], 10))
WIDTH 1
4.1. Mapfile
#
156
MapServer Documentation, Release 7.0.6
Fig. 4.23: Geomtransform buffer
END # STYLE
STYLE
COLOR 255 0 0
GEOMTRANSFORM (buffer([shape], 5))
END # STYLE
STYLE
COLOR 0 0 0
END # STYLE
END # CLASS
#
Upper right part (layer level geomtransform):
LAYER # line buffer layer
STATUS DEFAULT
TYPE LINE
FEATURE
POINTS
80 70
80 75
END # Points
END # Feature
GEOMTRANSFORM (buffer([shape], 10))
CLASS
STYLE
COLOR 0 0 255
END # STYLE
END # CLASS
END # LAYER
generalize ([shape], tolerance)
• GEOMTRANSFORM generalize simplifies a geometry ([shape]) in a way comparable to FMEâĂŹs ThinNoPoint algorithm. See http://trac.osgeo.org/gdal/ticket/966 for more information.
4.1. Mapfile
157
MapServer Documentation, Release 7.0.6
– GEOMTRANSFORM (generalize([shape], tolerance))
tolerance is mandatory, and is a specification of the maximum deviation allowed for the generalized line compared to the original line. A higher value for tolerance will give a more generalised / simplified line.
Note: Can be used at the LAYER level and for STYLE in the CLASS context.
Note: Depends on GEOS.
The figure below shows the result of applying generalize at the STYLE level with increasing values for tolerance (10 green, 20 - blue and 40 - red).
Fig. 4.24: Geomtransform generalize
One of the STYLE definitions for the example (tolerance 40):
STYLE
GEOMTRANSFORM (generalize([shape], 40))
COLOR 255 0 0
WIDTH 1
PATTERN 3 3 END
END # STYLE
simplify([shape], tolerance)
• GEOMTRANSFORM simplify simplifies a geometry ([shape]) using the standard Douglas-Peucker algorithm.
– GEOMTRANSFORM (simplify([shape], tolerance))
tolerance is mandatory, and is a specification of the maximum deviation allowed for the generalized line compared to the original line. A higher value for tolerance will give a more generalised / simplified line.
Note: Can be used at the LAYER level and for STYLE in the CLASS context.
4.1. Mapfile
158
MapServer Documentation, Release 7.0.6
The figure below shows the result of applying simplify at the STYLE level with increasing values for tolerance (10 green, 20 - blue and 40 - red).
Fig. 4.25: Geomtransform simplify
One of the STYLE definitions for the example (tolerance 40):
STYLE
GEOMTRANSFORM (simplify([shape], 40))
COLOR 255 0 0
WIDTH 1
PATTERN 3 3 END
END # STYLE
simplifypt([shape], tolerance)
• GEOMTRANSFORM simplifypt simplifies a geometry ([shape]), ensuring that the result is a valid geometry
having the same dimension and number of components as the input. tolerance must be non-negative.
– GEOMTRANSFORM (simplifypt([shape], tolerance))
tolerance is mandatory, and is a specification of the maximum deviation allowed for the generalized line compared to the original line. A higher value for tolerance will give a more generalised / simplified line.
Note: Can be used at the LAYER level and for STYLE in the CLASS context.
The figure below shows the result of applying simplifypt at the STYLE level with increasing values for tolerance (10 green, 20 - blue and 40 - red).
One of the STYLE definitions for the example (tolerance 40):
STYLE
GEOMTRANSFORM (simplifypt([shape], 40))
COLOR 255 0 0
WIDTH 1
4.1. Mapfile
159
MapServer Documentation, Release 7.0.6
Fig. 4.26: Geomtransform simplifypt
PATTERN 3 3 END
END # STYLE
smoothsia ( [shape], smoothing_size, smoothing_iterations, preprocessing )
• GEOMTRANSFORM smoothsia returns a smoothed version of a line.
– GEOMTRANSFORM (smoothsia ( [shape], smoothing_size, smoothing_iterations, preprocessing ))
The following parameters are used:
– shape (mandatory). Specify the geometry to be used
– smoothing_size (optional). The window size (number of points) used by the algorithm. The default is 3.
– smoothing_iterations (optional). The number of iterations of the algorithm. The default is 1.
– preprocessing (optional). Preprocessing method to add more vertices to the geometry prior to smoothing,
described below. There are two possible preprocessing methods:
* all Adds two intermediate vertices on each side of each original vertex. This is useful to preserve the
general shape of the line with low resolution data.
* angle Add vertices at some specific places based on angle detection.
Note: Can be used at the LAYER level and for STYLE in the CLASS context.
Example of a simple layer definition:
LAYER NAME "my_layer"
TYPE LINE
STATUS DEFAULT
DATA roads.shp
GEOMTRANSFORM (smoothsia([shape], 3, 1, 'angle'))
CLASS
4.1. Mapfile
160
MapServer Documentation, Release 7.0.6
STYLE
WIDTH 2
COLOR 255 0 0
END
END
Here are some examples showing results with different parameter values.
Fig. 4.27: Original geometry (left) and smoothsia with default parameters (right)
Tuning the behaviour of smoothsia
smoothsia has several parameters that can be used to tune its behaviour. The following sections describe some cases /
possibilities.
Dataset resolution is too high
If you are trying to smooth a line that has a very high resolution (high density of vertices at the current view scale),
you may not get the expected result because the vertices are too dense for the smoothing window size. In this case
you might want to simplify the geometries before the smoothing. You can combine smoothing and simplification in a
single geomtransform for that:
GEOMTRANSFORM (smoothsia(simplifypt([shape], 10)))
See RFC 89: Layer Geomtransform for more info. Here’s a visualization of the issue:
4.1. Mapfile
161
MapServer Documentation, Release 7.0.6
Fig. 4.28: Smoothsia - Larger window size (left) and larger window size with more iterations (right)
Fig. 4.29: High resolution geometry, smoothing and simplification
4.1. Mapfile
162
MapServer Documentation, Release 7.0.6
Dataset resolution is too low
If you are trying to smooth a long line that has a low density of vertices, you may not get the expected result in
some situations. You may lose some important parts of the geometry during the smoothing, for instance around acute
angles. You can improve the result by enabling a preprocessing step to add intermediate vertices along the line prior
to smoothing.
This behavior is controlled using the all value in the preprocessing argument of the smoothsia geomtransform:
GEOMTRANSFORM (smoothsia([shape], 3, 1, 'all'))
This preprocessing will be performed before the smoothing. It adds 2 intermediate vertices on each side of each
original vertex. This is useful if we really need to preserve the general shape of the low resolution line. Note that this
might have an impact on the rendering since there will be more vertices in the output.
Here’s a visualization of the issue:
Fig. 4.30: Effects of normal smoothing and preprocessing
Curves
The preprocessing step might not be appropriate for all cases since it can impact the smoothing result significantly.
However, without it, you might notice bad smoothing for curved lines with large distances between the line vertices.
See this example:
You can improve that by enabling another type of preprocessing: angle. This one will add points at some specific
places based on angle detection to recognize the curves. Here’s how you can enable it:
GEOMTRANSFORM (smoothsia([shape], 3, 1, 'angle'))
Javascript transformation
Author Alan Boudreault
Contact aboudreault at mapgears.com
Last Updated 2013/16/12
Introduction
Using GEOMTRANSFORM this way makes it possible to modify the geometry programmatically in addition to the
built-in geomtransform functions.
4.1. Mapfile
163
MapServer Documentation, Release 7.0.6
Fig. 4.31: Effects of normal smoothing (without preprocessing)
Fig. 4.32: The use of angle with smoothsia
4.1. Mapfile
164
MapServer Documentation, Release 7.0.6
Usage
Simply declare the javascript plugin this way:
MAP
...
LAYER
...
GEOMTRANSFORM "javascript://transform.js" # relative path
CLASS
END
END
END
The path can also be absolute.
MAP
...
LAYER
...
GEOMTRANSFORM "javascript:///home/user/transform.js" # absolute path
CLASS
END
END
END
The javascript plugin has to implement a function named geomtransform that will be automatically called. This
function has to return a new shape. Note that only the geometry of this new shape will be used, so your original shape
attributes will be preserved.
Access to the feature attributes is made through the shape.attributes javascript object.
The following javascript functions are available:
• alert(str1, str2, ..., str) print some text in MapServer logs
• print(str1, str2, ..., str) print some text in MapServer logs
• require(path_to_lib1, path_to_lib2, ..., path_to_lib) include one or more javascript lib
Example 1. Simple Geomtransform
This example does a simple vertical translation ...
function geomtransform() {
new_shape = new shapeObj();
new_shape.add(new lineObj());
new_point = new pointObj();
new_point.x = shape.line(0).point(0).x;
new_point.y = shape.line(0).point(0).y+30000;
new_shape.line(0).add(new_point);
return new_shape;
}
Example 2. Printing logs in MapServer logs
Extends example 1 by printing information to the MapServer log.
4.1. Mapfile
165
MapServer Documentation, Release 7.0.6
MAP
...
CONFIG "MS_ERRORFILE" "/tmp/mapserver.log"
DEBUG 1
LAYER
...
GEOMTRANSFORM "javascript://transform.js"
...
END
END
function geomtransform() {
new_shape = new shapeObj();
new_shape.add(new lineObj());
new_point = new pointObj();
new_point.x = shape.line(0).point(0).x;
new_point.y = shape.line(0).point(0).y+30000;
print('Modified y value from: ' + shape.line(0).point(0).y + ' to: '+new_point.y);
new_shape.line(0).add(new_point);
return new_shape;
}
Basic API
A minimal API is currently available to create a new shape.
pointObj
Constructor
new pointObj()
Members
Type
double
double
double
double
Name
x
y
z
m
Note
Methods
void setXY(double x, double y[, double m]) Set the x,y[,m] values.
void setXYZ(double x, double y, double Z[, double m]) Set the x,y,z[,m] values.
lineObj
4.1. Mapfile
166
MapServer Documentation, Release 7.0.6
Constructor
new lineObj()
Members
Type
int
Name
numpoints
Note
read-only
Methods
pointObj point(int index) Returns the point at the index position.
void add(pointObj point) Add a point to the line.
void addXY(double x, double y[, double m]) Add point to the line from an x,y[,m] values.
void addXYZ(double x, double y, double Z[, double m]) Add point to the line from an x,y,z[,m] values.
shapeObj
Constructor
new shapeObj(int type)
‘type’ is one of shapeObj.Point, shapeObj.Line, shapeObj.Polygon or shapeObj.Null
Members
Type
int
int
int
int
int
int
text
object
Name
numvalues
numlines
index
type
tileindex
classindex
text
attributes
Note
read-only
read-only
read-only
read-only
read-only
read-only
Methods
shapeObj clone() Returns a clone of the shape.
lineObj line(int index) Returns the line at the index position.
void add(lineObj line) Add a line to the shape.
void setGeometry(shapeObj shape) Replace the geometry of the object with the shape geometry.
4.1. Mapfile
167
MapServer Documentation, Release 7.0.6
4.1.10 GRID
Description
The GRID object can be used to add labeled graticule lines to your map. Initially developed in 2003 by John Novak, the
GRID object is designed to be used inside a LAYER object to allow multiple GRID objects for a single map (allowing
for example: a lat/long GRID, a State Plane GRID, and a UTM GRID to be displayed on the same map image).
Mapfile Parameters:
LABELFORMAT [DD|DDMM|DDMMSS|C format string] Format of the label. “DD” for degrees, “DDMM” for
degrees minutes, and “DDMMSS” for degrees, minutes, seconds. A C-style formatting string is also allowed,
such as “%gÂř” to show decimal degrees with a degree symbol. The default is decimal display of whatever SRS
you’re rendering the GRID with.
MINARCS [double] The minimum number of arcs to draw. Increase this parameter to get more lines. Optional.
MAXARCS [double] The maximum number of arcs to draw. Decrease this parameter to get fewer lines. Optional.
MININTERVAL [double] The minimum number of intervals to try to use. The distance between the grid lines, in
the units of the grid’s coordinate system. Optional.
MAXINTERVAL [double] The maximum number of intervals to try to use. The distance between the grid lines, in
the units of the grid’s coordinate system. Optional.
MINSUBDIVIDE [double] The minimum number of segments to use when rendering an arc. If the lines should be
very curved, use this to smooth the lines by adding more segments. Optional.
MAXSUBDIVIDE [double] The maximum number of segments to use when rendering an arc. If the graticule should
be very straight, use this to minimize the number of points for faster rendering. Optional, default 256.
Example1: Grid Displaying Degrees
LAYER
NAME "grid"
METADATA
"DESCRIPTION" "Grid"
END
TYPE LINE
STATUS ON
CLASS
NAME "Graticule"
COLOR 0 0 0
LABEL
COLOR 255 0 0
FONT "sans"
TYPE truetype
SIZE 8
POSITION AUTO
PARTIALS FALSE
BUFFER 2
OUTLINECOLOR 255 255 255
END
END
PROJECTION
"init=epsg:4326"
END
4.1. Mapfile
168
MapServer Documentation, Release 7.0.6
GRID
LABELFORMAT "DD"
END
END # Layer
Example2: Grid Displaying Degrees with Symbol
LAYER
NAME "grid"
METADATA
"DESCRIPTION" "Grid"
END
TYPE LINE
STATUS ON
CLASS
NAME "Graticule"
COLOR 0 0 0
LABEL
COLOR 255 0 0
FONT "sans"
TYPE truetype
SIZE 8
POSITION AUTO
PARTIALS FALSE
BUFFER 2
OUTLINECOLOR 255 255 255
END
4.1. Mapfile
169
MapServer Documentation, Release 7.0.6
END
PROJECTION
"init=epsg:4326"
END
GRID
LABELFORMAT '%gÂř'
END
END # Layer
Example3: Grid Displayed in Other Projection (Google Mercator)
LAYER
NAME "grid"
METADATA
"DESCRIPTION" "Grid"
END
TYPE LINE
STATUS ON
CLASS
NAME "Graticule"
COLOR 0 0 0
LABEL
COLOR 255 0 0
FONT "sans"
TYPE truetype
SIZE 8
POSITION AUTO
4.1. Mapfile
170
MapServer Documentation, Release 7.0.6
PARTIALS FALSE
BUFFER 2
OUTLINECOLOR 255 255 255
END
END
PROJECTION
"init=epsg:3857"
END
GRID
LABELFORMAT '%.0fm'
MININTERVAL 5000000
END
END # Layer
Note: Pay attention to the values you use for the INTERVAL parameter; it is possible to confuse/overload MapServer
by telling it to draw a graticule line every meter (MININTERVAL 1).
4.1.11 INCLUDE
When this directive is encountered parsing switches to the included file immediately. As a result the included file can
be comprised of any valid mapfile syntax. For example:
INCLUDE 'myLayer.map'
Performance does not seem to be seriously impacted with limited use, however in high performance instances you
4.1. Mapfile
171
MapServer Documentation, Release 7.0.6
may want to use includes in a pre-processing step to build a production mapfile. The C pre-processor can also be used
(albeit with a different syntax) and is far more powerful.
Notes
• Supported in versions 4.10 and higher.
• The name of the file to be included MUST be quoted (single or double quotes).
• Includes may be nested, up to 5 deep.
• File location can be given as a full path to the file, or (in MapServer >= 4.10.1) as a path relative to the mapfile.
• Debugging can be problematic because:
1. the file an error occurs in does not get output to the user
2. the line number counter is not reset for each file. Here is one possible error that is thrown when the include
file cannot be found:
msyylex(): Unable to access file. Error opening included file "parks_include.
˓→map"
Example
MAP
NAME "include_mapfile"
EXTENT 0 0 500 500
SIZE 250 250
INCLUDE "test_include_symbols.map"
INCLUDE "test_include_layer.map"
END
where test_include_symbols.map contains:
SYMBOL
NAME 'square'
TYPE VECTOR
FILLED TRUE
POINTS 0 0 0 1 1 1 1 0 0 0 END
END
and test_include_layer.map contains:
LAYER
TYPE POINT
STATUS DEFAULT
FEATURE
POINTS 10 10 40 20 300 300 400 10 10 400 END
END
CLASS
NAME 'Church'
COLOR 0 0 0
SYMBOL 'square'
SIZE 7
STYLE
4.1. Mapfile
172
MapServer Documentation, Release 7.0.6
SYMBOL "square"
SIZE 5
COLOR 255 255 255
END
STYLE
SYMBOL "square"
SIZE 3
COLOR 0 0 255
END
END
END
4.1.12 JOIN
Description
Joins are defined within a LAYER object. It is important to understand that JOINs are ONLY available once a query
has been processed. You cannot use joins to affect the look of a map. The primary purpose is to enable lookup tables
for coded data (e.g. 1 => Forest) but there are other possible uses.
Supported Formats
• DBF/XBase files
• CSV (comma delimited text file)
• PostgreSQL tables
• MySQL tables
Mapfile Parameters:
CONNECTION [string] Parameters required for the join table’s database connection (not required for DBF or CSV
joins). The following is an example connection for PostgreSQL:
CONNECTION "host=127.0.0.1 port=5432 user=pg password=pg dbname=somename"
CONNECTIONTYPE POSTGRESQL
CONNECTIONTYPE [csv|mysql|postgresql] Type of connection (not required for DBF joins). For PostgreSQL
use postgresql, for CSV use csv, for MySQL use mysql.
FOOTER [filename] Template to use after a layer’s set of results have been sent. In other words, this header HTML
will be displayed after the contents of the TEMPLATE HTML.
FROM [column] Join column in the dataset. This is case sensitive.
HEADER [filename] Template to use before a layer’s set of results have been sent. In other words, this header HTML
will be displayed before the contents of the TEMPLATE HTML.
NAME [string] Unique name for this join. Required.
TABLE [filename|tablename] For file-based joins this is the name of XBase or comma delimited file (relative to the
location of the mapfile) to join TO. For PostgreSQL support this is the name of the PostgreSQL table to join
TO.
4.1. Mapfile
173
MapServer Documentation, Release 7.0.6
TEMPLATE [filename] Template to use with one-to-many joins. The template is processed once for each record
and can only contain substitutions for columns in the joined table. Refer to the column in the joined table in
your template like [joinname_columnname], where joinname is the NAME specified for the JOIN object.
TO [column] Join column in the table to be joined. This is case sensitive.
TYPE [ONE-TO-ONE|ONE-TO-MANY] The type of join. Default is one-to-one.
Example 1: Join from Shape dataset to DBF file
Mapfile Layer
LAYER
NAME "prov_bound"
TYPE POLYGON
STATUS DEFAULT
DATA "prov.shp"
CLASS
NAME "Province"
STYLE
OUTLINECOLOR 120 120 120
COLOR 255 255 0
END
END
TEMPLATE "../htdocs/cgi-query-templates/prov.html"
HEADER "../htdocs/cgi-query-templates/prov-header.html"
FOOTER "../htdocs/cgi-query-templates/footer.html"
JOIN
NAME "test"
TABLE "../data/lookup.dbf"
FROM "ID"
TO "IDENT"
TYPE ONE-TO-ONE
END
END # layer
Ogrinfo
>ogrinfo lookup.dbf lookup -summary
INFO: Open of `lookup.dbf'
using driver `ESRI Shapefile' successful.
Layer name: lookup
Geometry: None
Feature Count: 12
Layer SRS WKT:
(unknown)
IDENT: Integer (2.0)
VAL: Integer (2.0)
>ogrinfo prov.shp prov -summary
INFO: Open of `prov.shp'
using driver `ESRI Shapefile' successful.
Layer name: prov
4.1. Mapfile
174
MapServer Documentation, Release 7.0.6
Geometry: Polygon
Feature Count: 12
Extent: (-2340603.750000, -719746.062500) - (3009430.500000, 3836605.250000)
Layer SRS WKT:
(unknown)
NAME: String (30.0)
ID: Integer (2.0)
Template
<tr bgcolor="#EFEFEF">
<td align="left">[NAME]</td>
<td align="left">[test_VAL]</td>
</tr>
Example 2: Join from Shape dataset to PostgreSQL table
Mapfile Layer
LAYER
NAME "prov_bound"
TYPE POLYGON
STATUS DEFAULT
DATA "prov.shp"
CLASS
NAME "Province"
STYLE
OUTLINECOLOR 120 120 120
COLOR 255 255 0
END
END
TOLERANCE 20
TEMPLATE "../htdocs/cgi-query-templates/prov.html"
HEADER "../htdocs/cgi-query-templates/prov-header.html"
FOOTER "../htdocs/cgi-query-templates/footer.html"
JOIN
NAME "test"
CONNECTION "host=127.0.0.1 port=5432 user=pg password=pg dbname=join"
CONNECTIONTYPE postgresql
TABLE "lookup"
FROM "ID"
TO "ident"
TYPE ONE-TO-ONE
END
END # layer
Ogrinfo
>ogrinfo -ro PG:"host=127.0.0.1 port=5432 user=pg password=pg dbname=join"
lookup -summary
INFO: Open of `PG:host=127.0.0.1 port=5432 user=pg password=pg dbname=join'
4.1. Mapfile
175
MapServer Documentation, Release 7.0.6
using driver `PostgreSQL' successful.
Layer name: lookup
Geometry: Unknown (any)
Feature Count: 12
Layer SRS WKT:
(unknown)
ident: Integer (0.0)
val: Integer (0.0)
Template
<tr bgcolor="#EFEFEF">
<td align="left">[NAME]</td>
<td align="left">[test_val]</td>
</tr>
Example 3: Join from Shape dataset to CSV file
Mapfile Layer
LAYER
NAME "prov_bound"
TYPE POLYGON
STATUS DEFAULT
DATA "prov.shp"
CLASS
NAME "Province"
STYLE
OUTLINECOLOR 120 120 120
COLOR 255 255 0
END
END
TOLERANCE 20
TEMPLATE "../htdocs/cgi-query-templates/prov.html"
HEADER "../htdocs/cgi-query-templates/prov-header.html"
FOOTER "../htdocs/cgi-query-templates/footer.html"
JOIN
NAME "test"
CONNECTIONTYPE CSV
TABLE "../data/lookup.csv"
FROM "ID"
#TO "IDENT" # see note below
TO "1"
# see note below
TYPE ONE-TO-ONE
END
END # layer
4.1. Mapfile
176
MapServer Documentation, Release 7.0.6
CSV File Structure
"IDENT","VAL"
1,12
2,11
3,10
4,9
5,8
6,7
7,6
8,5
9,4
10,3
11,2
12,1
Note: The CSV driver currently doesn’t read column names from the first row. It just uses indexes (1, 2, ... n) to
reference the columns. It’s ok to leave column names as the first row since they likely won’t match anything but they
aren’t used. Typically you’d see something like TO “1” in the JOIN block. Then in the template you’d use [name_1],
[name_2], etc...
Ogrinfo
>ogrinfo lookup.csv lookup -summary
INFO: Open of `lookup.csv'
using driver `CSV' successful.
Layer name: lookup
Geometry: None
Feature Count: 12
Layer SRS WKT:
(unknown)
IDENT: String (0.0)
VAL: String (0.0)
Template (prov.html)
Ideally this the template should look like this:
<!-- MapServer Template -->
<tr bgcolor="#EFEFEF">
<td align="left">[NAME]</td>
<td align="left">[test_VAL]</td>
</tr>
But since attribute names are not supported for CSV files (see note above), the following will have to be used:
<!-- MapServer Template -->
<tr bgcolor="#EFEFEF">
<td align="left">[NAME]</td>
<td align="left">[test_2]</td>
</tr>
4.1. Mapfile
177
MapServer Documentation, Release 7.0.6
Example 4: Join from Shape dataset to MySQL
Mapfile Layer
LAYER
NAME "prov_bound"
TYPE POLYGON
STATUS DEFAULT
DATA "prov.shp"
CLASS
NAME "Province"
STYLE
OUTLINECOLOR 120 120 120
COLOR 255 255 0
END # style
END # class
TOLERANCE 20
TEMPLATE "../htdocs/cgi-query-templates/prov.html"
HEADER "../htdocs/cgi-query-templates/prov-header.html"
FOOTER "../htdocs/cgi-query-templates/footer.html"
JOIN
NAME "mysql-join"
CONNECTIONTYPE MYSQL
CONNECTION 'server:user:password:database'
TABLE "mysql-tablename"
FROM "ID"
TO "mysql-column"
TYPE ONE-TO-ONE
END # join
END # layer
Example 5: One-to-many join
In a join of type ONE-TO-MANY, the JOIN object needs to contain a TEMPLATE. This TEMPLATE is used for each
matching record in the join table. Columns in the join table are referenced using <join_name>_<join_column_name>.
Columns in the layer table are referenced using <column_name>.
For a one-to-many join, the LAYER TEMPLATE file has to contain a reference to the the JOIN object, as follows:
[join_<join_name>].
In this example, it is assumed that the join table many.dbf contains the columns MANYFIELD1 and MANYFIELD2
in addition to the join column (IDENT).
Layer object:
LAYER
NAME "joinonetomany"
TYPE POLYGON
STATUS DEFAULT
DATA "prov.shp"
CLASS
NAME "Province"
STYLE
OUTLINECOLOR 120 120 120
4.1. Mapfile
178
MapServer Documentation, Release 7.0.6
COLOR 255 255 0
END # style
END # class
TEMPLATE "oneToMany.html"
HEADER "oneToMany_header.html"
FOOTER "oneToMany_footer.html"
JOIN
NAME "onetomanytest"
TABLE "many.dbf"
FROM "ID"
TO "IDENT"
TYPE ONE-TO-MANY
TEMPLATE "oneToMany_join.html"
END # join
END # layer
Template oneToMany_header.html:
<!-- MapServer Template -->
<html>
<head><title>One to Many Join</title></head>
<body>
<h1>MapServer output</h1>
<table>
Template oneToMany.html:
<!-- MapServer Template -->
<tr>
<td><strong>[ID]</strong></td>
<td><table>
[join_onetomanytest]
</table></td>
</tr>
Template oneToMany_join.html:
<!-- MapServer Template -->
<tr>
<td>[NAME]</td>
<td>[onetomanytest_MANYFIELD1]</td>
<td>[onetomanytest_MANYFIELD2]</td>
</tr>
Template oneToMany_footer.html:
<!-- MapServer Template -->
</table>
</body>
<html>
4.1.13 LABEL
ALIGN [left|center|right] Specifies text alignment for multiline labels (see WRAP) Note that the alignment algorithm
is far from precise, so don’t expect fabulous results (especially for right alignment) if you’re not using a fixed
width font.
4.1. Mapfile
179
MapServer Documentation, Release 7.0.6
New in version 5.4.
ANGLE [double|auto|auto2|follow|attribute]
• Angle, counterclockwise, given in degrees, to draw the label. Default is 0.
• AUTO allows MapServer to compute the angle. Valid for LINE layers only.
• AUTO2 same as AUTO, except no logic is applied to try to keep the text from being rendered in reading
orientation (i.e. the text may be rendered upside down). Useful when adding text arrows indicating the
line direction.
• FOLLOW was introduced in version 4.10 and tells MapServer to compute a curved label for appropriate
linear features (see RFC11 for specifics). See also MAXOVERLAPANGLE.
• [Attribute] was introduced in version 5.0, to specify the item name in the attribute table to use for angle values. The hard brackets [] are required. For example, if your shapefile’s DBF has a field named
“MYANGLE” that holds angle values for each record, your LABEL object might contain:
LABEL
COLOR 150 150 150
OUTLINECOLOR 255 255 255
FONT "sans"
TYPE truetype
SIZE 6
ANGLE [MYANGLE]
POSITION AUTO
PARTIALS FALSE
END
The associated RFC document for this feature is RFC19.
ANTIALIAS [true|false] Should text be antialiased? Note that this requires more available colors, decreases drawing
performance, and results in slightly larger output images. Only useful for GD (gif) rendering. Default is false.
Has no effect for the other renderers (where anti-aliasing can not be turned off).
BACKGROUNDCOLOR [r] [g] [b] | [hexadecimal string] Color to draw a background rectangle (i.e. billboard).
Off by default.
Note: Removed in 6.0. Use a LABEL STYLE object with GEOMTRANSFORM labelpoly and COLOR.
BACKGROUNDSHADOWCOLOR [r] [g] [b] | [hexadecimal string] Color to draw a background rectangle (i.e.
billboard) shadow. Off by default.
Note: Removed in 6.0. Use a LABEL STYLE object with GEOMTRANSFORM labelpoly, COLOR and OFFSET.
BACKGROUNDSHADOWSIZE [x][y] How far should the background rectangle be offset? Default is 1.
Note: Removed in 6.0. Use a LABEL STYLE object with GEOMTRANSFORM labelpoly, COLOR and OFFSET.
BUFFER [integer] Padding, in pixels, around labels. Useful for maintaining spacing around text to enhance readability. Available only for cached labels. Default is 0.
COLOR [r] [g] [b] | [hexadecimal string] | [attribute]
4.1. Mapfile
180
MapServer Documentation, Release 7.0.6
• Color to draw text with.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
COLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
COLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
COLOR "#FF00FFCC"
• [Attribute] was introduced in version 5.0, to specify the item name in the attribute table to use for color
values. The hard brackets [] are required. For example, if your shapefile’s DBF has a field named “MYCOLOR” that holds color values for each record, your LABEL object might contain:
LABEL
COLOR [MYCOLOR]
OUTLINECOLOR 255 255 255
FONT "sans"
TYPE truetype
SIZE 6
POSITION AUTO
PARTIALS FALSE
END
The associated RFC document for this feature is RFC19.
ENCODING [string] Supported encoding format to be used for labels. If the format is not supported, the label will
not be drawn. Requires the iconv library (present on most systems). The library is always detected if present on
the system, but if not, the label will not be drawn.
Required for displaying international characters in MapServer. More information can be found in the Label
Encoding document.
Deprecated since version 7.0: Removed. UTF-8 is now the encoding used by MapServer, and data set encodings
are handled using LAYER ENCODING.
EXPRESSION [string] Expression that determines when the LABEL is to be applied. See EXPRESSION in CLASS.
New in version 6.2.
FONT [name|attribute]
• Font alias (as defined in the FONTSET) to use for labeling.
• [Attribute] was introduced in version 5.6 to specfify the font alias.
• May contain a comma-separated list of up to MS_MAX_LABEL_FONTS (usually 5) font aliases used as
fallback fonts in renderers supporting it, if a glyph is not available in a font. If specified directly, be sure
to enclose the list with quotes. See RFC80.
FORCE [true|false] Forces labels for a particular class on, regardless of collisions. Available only for cached labels.
Default is false. If FORCE is true and PARTIALS is false, FORCE takes precedence, and partial labels are
drawn.
4.1. Mapfile
181
MapServer Documentation, Release 7.0.6
MAXLENGTH [integer] This keyword interacts with the WRAP keyword so that line breaks only occur after the
defined number of characters.
Table 4.9: Interaction with WRAP keyword
wrap =
âĂŸcharâĂŹ
no wrap
maxlength = 0
always wrap at the WRAP
character
no processing
maxlength > 0
newline at the first WRAP character after
MAXLENGTH characters
skip label if it contains more than MAXLENGTH
characters
The associated RFC document for this feature is RFC40.
New in version 5.4.
Support for negative MAXLENGTH that implied forced linebreaks is not supported since version 7, a
workaround implies pre-processing such labels to include linebreaks or wrap characters.
MAXOVERLAPANGLE [double] Angle threshold to use in filtering out ANGLE FOLLOW labels in which characters overlap (floating point value in degrees). This filtering will be enabled by default starting with MapServer
6.0. The default MAXOVERLAPANGLE value will be 22.5 degrees, which also matches the default in
GeoServer. Users will be free to tune the value up or down depending on the type of data they are dealing
with and their tolerance to bad overlap in labels. As per RFC 60, if MAXOVERLAPANGLE is set to 0, then we
fall back on pre-6.0 behavior which was to use maxoverlapangle = 0.4*MS_PI (40% of 180 degrees = 72degree).
The associated RFC document for this feature is RFC60.
MAXSCALEDENOM [double] Minimum scale at which this LABEL is drawn. Scale is given as the denominator
of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000.
New in version 5.4.
See also:
Map Scale
MAXSIZE [double] Maximum font size to use when scaling text (pixels). Default is 256. Starting from version 5.4,
the value can also be a fractional value (and not only integer). See LAYER SYMBOLSCALEDENOM.
MINDISTANCE [integer] Minimum distance between duplicate labels. Given in pixels.
MINFEATURESIZE [integer|auto] Minimum size a feature must be to be labeled. Given in pixels. For line data
the overall length of the displayed line is used, for polygons features the smallest dimension of the bounding box
is used. “Auto” keyword tells MapServer to only label features that are larger than their corresponding label.
Available for cached labels only.
MINSCALEDENOM [double] Maximum scale at which this LABEL is drawn. Scale is given as the denominator of
the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000.
New in version 5.4.
See also:
Map Scale
MINSIZE [double] Minimum font size to use when scaling text (pixels). Default is 4. Starting from version 5.4, the
value can also be a fractional value (and not only integer). See LAYER SYMBOLSCALEDENOM.
OFFSET [x][y] Offset values for labels, relative to the lower left hand corner of the label and the label point. Given
in pixels. In the case of rotated text specify the values as if all labels are horizontal and any rotation will be
compensated for.
4.1. Mapfile
182
MapServer Documentation, Release 7.0.6
When used with FOLLOW angle, two additional options are available to render the label parallel to the original
feature:
• OFFSET x -99 : will render the label to the left or to the right of the feature, depending on the sign of {x}.
• OFFSET x 99 : will render the label above or below the feature, depending on the sign of {x}.
See LAYER SYMBOLSCALEDENOM.
OUTLINECOLOR [r] [g] [b] | [hexadecimal string] | [attribute]
• Color to draw a one pixel outline around the characters in the text.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
OUTLINECOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
OUTLINECOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
OUTLINECOLOR "#FF00FFCC"
• [attribute] was introduced in version 5.0, to specify the item name in the attribute table to use for color
values. The hard brackets [] are required. For example, if your shapefile’s DBF has a field named “MYOUTCOLOR” that holds color values for each record, your LABEL object might contain:
LABEL
COLOR 150 150 150
OUTLINECOLOR [MYOUTCOLOR]
FONT "sans"
TYPE truetype
SIZE 6
POSITION AUTO
PARTIALS FALSE
END
The associated RFC document for this feature is RFC19.
OUTLINEWIDTH [integer] Width of the outline if OUTLINECOLOR has been set. Defaults to 1. Currently only
the AGG renderer supports values greater than 1, and renders these as a ‘halo’ effect: recommended values are
3 or 5. If the renderer supports it and the text size is variable, the outline will be scaled proportionally to the
text and the value specified as OUTLINEWIDTH is therefore the width at the same scale at which the SIZE is
specified.
PARTIALS [true|false] Can text run off the edge of the map? Default is true. If FORCE is true and PARTIALS is
false, FORCE takes precedence, and partial labels are drawn.
POSITION [ul|uc|ur|cl|cc|cr|ll|lc|lr|auto] Position of the label relative to the labeling point (layers only). First letter
is “Y” position, second letter is “X” position. “Auto” tells MapServer to calculate a label position that will not
interfere with other labels. With points, MapServer selects from the 8 outer positions (i.e. excluding cc). With
polygons, MapServer selects from cc (added in MapServer 5.4), uc, lc, cl and cr as possible positions. With
lines, it only uses lc or uc, until it finds a position that doesn’t collide with labels that have already been drawn.
If all positions cause a conflict, then the label is not drawn (Unless the label’s FORCE a parameter is set to
“true”). “Auto” placement is only available with cached labels.
4.1. Mapfile
183
MapServer Documentation, Release 7.0.6
PRIORITY [integer]|[item_name]|[attribute] The priority parameter takes an integer value between 1 (lowest) and
10 (highest). The default value is 1. It is also possible to bind the priority to an attribute (item_name) using
square brackets around the [item_name]. e.g. “PRIORITY [someattribute]”
Labels are stored in the label cache and rendered in order of priority, with the highest priority levels rendered
first. Specifying an out of range PRIORITY value inside a map file will result in a parsing error. An out of range
value set via MapScript or coming from a shape attribute will be clamped to the min/max values at rendering
time. There is no expected impact on performance for using label priorities.
[Attribute] was introduced in version 5.6.
New in version 5.0.
REPEATDISTANCE [integer] The label will be repeated on every line of a multiline shape and will be repeated
multiple times along a given line at an interval of REPEATDISTANCE pixels.
The associated RFC document for this feature is RFC57.
New in version 5.6.
SHADOWCOLOR [r] [g] [b] | [hexadecimal string] Color of drop shadow. A label with the same text will be
rendered in this color before the main label is drawn, resulting in a shadow effect on the the label characters.
The offset of the renderered shadow is set with SHADOWSIZE.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
SHADOWCOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
SHADOWCOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
SHADOWCOLOR "#FF00FFCC"
SHADOWSIZE [x][y]|[attribute][attribute]|[x][attribute]|[attribute][y] Shadow offset in pixels, see SHADOWCOLOR.
[Attribute] was introduced in version 6.0, and can be used like:
SHADOWSIZE
SHADOWSIZE
SHADOWSIZE
SHADOWSIZE
2 2
[shadowsizeX] 2
2 [shadowsizeY]
[shadowsize] [shadowsize]
SIZE [integer]|[tiny|small|medium|large|giant]|[attribute]
• Text size. Use a number to give the size in pixels of your TrueType font based label, or any of the other 5
listed keywords for bitmap fonts.
When scaling is in effect (SYMBOLSCALEDENOM is specified for the LAYER), SIZE gives the size of the
font to be used at the map scale 1:SYMBOLSCALEDENOM.
• [Attribute] was introduced in version 5.0, to specify the item name in the attribute table to use for size values. The hard brackets [] are required. For example, if your shapefile’s DBF has a field named “MYSIZE”
that holds size values for each record, your LABEL object might contain:
4.1. Mapfile
184
MapServer Documentation, Release 7.0.6
LABEL
COLOR 150 150 150
OUTLINECOLOR 255 255 255
FONT "sans"
TYPE truetype
SIZE [MYSIZE]
POSITION AUTO
PARTIALS FALSE
END
The associated RFC document for this feature is RFC19.
Note: The SIZE value can only be an integer (not a fractional value), because the renderer Freetype only
accepts integers.
STYLE The start of a STYLE object.
Label specific mechanisms of the STYLE object are the GEOMTRANSFORM options:
GEOMTRANSFORM [labelpnt|labelpoly] Creates a geometry that can be used for styling the label. Does
not apply to ANGLE FOLLOW labels.
• labelpnt draws a marker on the geographic position the label is attached to. This corresponds to the
center of the label text only if the label is in position CC.
• labelpoly generates the bounding rectangle for the text, with 1 pixel of padding added in all directions.
The resulting geometries can be styled using the mechanisms available in the STYLE object.
Example - draw a red background rectangle for the labels (i.e. billboard) with a “shadow” in
gray:
STYLE
GEOMTRANSFORM 'labelpoly'
COLOR 153 153 153
OFFSET 3 2
END # STYLE
STYLE
GEOMTRANSFORM 'labelpoly'
COLOR 255 0 0
END # STYLE
New in version 6.0.
TEXT [string|expression] Text to label features with (useful when multiple labels are used). Overrides values obtained from the LAYER LABELITEM and the CLASS TEXT. See TEXT in CLASS.
New in version 6.2.
TYPE [bitmap|truetype] Type of font to use. Generally bitmap fonts are faster to draw then TrueType fonts. However, TrueType fonts are scalable and available in a variety of faces. Be sure to set the FONT parameter if you
select TrueType.
Note: Bitmap fonts are only supported with the AGG and GD renderers.
WRAP [character] Character that represents an end-of-line condition in label text, thus resulting in a multi-line label.
Interacts with MAXLENGTH for conditional line wrapping after a given number of characters
4.1. Mapfile
185
MapServer Documentation, Release 7.0.6
4.1.14 LAYER
CLASS Signals the start of a CLASS object.
Inside a layer, only a single class will be used for the rendering of a feature. Each feature is tested against each
class in the order in which they are defined in the mapfile. The first class that matches the its min/max scale
constraints and its EXPRESSION check for the current feature will be used for rendering.
CLASSGROUP [string] Specify the class’s group that would be considered at rendering time. The CLASS object’s
GROUP parameter must be used in combination with CLASSGROUP.
CLASSITEM [attribute] Item name in attribute table to use for class lookups.
CLUSTER Signals the start of a CLUSTER object.
The CLUSTER configuration option provides to combine multiple features from the layer into single (aggregated) features based on their relative positions. Supported only for POINT layers.
See also:
rfc69
COMPOSITE Signals the start of a COMPOSITE object.
One or more COMPOSITE blocks can be used to signal that rendering should be done in a temporary image
and merged onto the final map image in a final step. The options defined inside the COMPOSITE block will
determine how this merging should be done (e.g. by appying opacity, composition operator, or pixel filters)
See also:
rfc113
CONNECTION [string] Database connection string to retrieve remote data.
An SDE connection string consists of a hostname, instance name, database name, username and password
separated by commas.
Warning: MapServer’s native SDE driver was removed for the MapServer 7.0 release (see discussion).
SDE support can still be accessed through the OGR driver.
A PostGIS connection string is basically a regular PostgreSQL connection string, it takes the form of
“user=nobody password=****** dbname=dbname host=localhost port=5432”
An Oracle connection string: user/pass[@db]
See also:
Vector Data for specific connection information for various data sources.
See also:
See Kernel Density Estimation (Dynamic Heatmap) for specific connection information for kernel density estimation.
CONNECTIONTYPE [contour|kerneldensity|local|ogr|oraclespatial|plugin|postgis|sde|union|uvraster|wfs|wms]
Type of connection. Default is local. See additional documentation for any other type.
See also:
Vector Data for specific connection information for various data sources. See Union Layer for combining layers,
added in MapServer 6.0
See also:
4.1. Mapfile
186
MapServer Documentation, Release 7.0.6
See Kernel Density Estimation (Dynamic Heatmap) for specific connection information for kernel density estimation.
Note: mygis is another connectiontype, but it is deprecated; please see the MySQL section of the Vector Data
document for connection details.
DATA [filename]|[sde parameters][postgis table/column][oracle table/column] Full filename of the spatial data to
process. No file extension is necessary for shapefiles. Can be specified relative to the SHAPEPATH option from
the Map Object.
If this is an SDE layer, the parameter should include the name of the layer as well as the geometry column, i.e.
“mylayer,shape,myversion”.
If this is a PostGIS layer, the parameter should be in the form of “<columnname> from <tablename>”, where
“columnname” is the name of the column containing the geometry objects and “tablename” is the name of the
table from which the geometry data will be read.
For Oracle, use “shape FROM table” or “shape FROM (SELECT statement)” or even more complex Oracle
compliant queries! Note that there are important performance impacts when using spatial subqueries however.
Try using MapServer’s FILTER whenever possible instead. You can also see the SQL submitted by forcing an
error, for instance by submitting a DATA parameter you know won’t work, using for example a bad column
name.
See also:
Vector Data for specific connection information for various data sources.
DEBUG [off|on|0|1|2|3|4|5] Enables debugging of a layer in the current map.
Debugging with MapServer versions >= 5.0:
Verbose output is generated and sent to the standard error output (STDERR) or the MapServer errorfile if one
is set using the “MS_ERRORFILE” environment variable. You can set the environment variable by using the
CONFIG parameter at the MAP level of the mapfile, such as:
CONFIG "MS_ERRORFILE" "/ms4w/tmp/ms_error.txt"
You can also set the environment variable in Apache by adding the following to your httpd.conf:
SetEnv MS_ERRORFILE "/ms4w/tmp/ms_error.txt"
Once the environment variable is set, the DEBUG mapfile parameter can be used to control the level of debugging output. Here is a description of the possible DEBUG values:
• DEBUG O or OFF - only msSetError() calls are logged to MS_ERRORFILE. No msDebug() output at
all. This is the default and corresponds to the original behavior of MS_ERRORFILE in MapServer 4.x
• DEBUG 1 or ON - includes all output from DEBUG 0 plus msDebug() warnings about common pitfalls,
failed assertions or non-fatal error situations (e.g. missing or invalid values for some parameters, missing
shapefiles in tileindex, timeout error from remote WMS/WFS servers, etc.)
• DEBUG 2 - includes all output from DEBUG 1 plus notices and timing information useful for tuning
mapfiles and applications
• DEBUG 3 - all of DEBUG 2 plus some debug output useful in troubleshooting problems such as WMS
connection URLs being called, database connection calls, etc. This is the recommended level for debugging mapfiles.
• DEBUG 4 - DEBUG 3 plus even more details...
4.1. Mapfile
187
MapServer Documentation, Release 7.0.6
• DEBUG 5 - DEBUG 4 plus any msDebug() output that might be more useful to the developers than to the
users.
You can also set the debug level by using the “MS_DEBUGLEVEL” environment variable.
The DEBUG setting can also be specified for the entire map, by setting the DEBUG parameter in the MAP
object.
For more details on this debugging mechanism, please see RFC28.
Debugging with MapServer versions < 5:
Verbose output is generated and sent to the standard error output (STDERR) or the MapServer logfile if one is
set using the LOG parameter in the WEB object. Apache users will see timing details for drawing in Apache’s
error_log file. Requires MapServer to be built with the DEBUG=MSDEBUG option (–with-debug configure
option).
DUMP [true|false] Since 6.0, DUMP is not used anymore. LAYER METADATA is used instead.
Switch to allow MapServer to return data in GML format. Useful when used with WMS GetFeatureInfo operations. “false” by default.
Deprecated since version 6.0: LAYER METADATA is used instead.
See also:
WMS Server
ENCODING [string] The encoding used for text in the layer data source. The value must be supported by ICONV
(for example “LATIN1”). When ENCODING is set (and not equal to “UTF-8”), the data source text attributes
will be converted to UTF-8.
New in version 7.0.
EXTENT [minx] [miny] [maxx] [maxy] The spatial extent of the data. In most cases you will not need to specify
this, but it can be used to avoid the speed cost of having MapServer compute the extents of the data. An
application can also possibly use this value to override the extents of the map.
FEATURE Signals the start of a FEATURE object.
FILTER [string]
This parameter allows for data specific attribute filtering that is done at the same time spatial filtering is
done, but before any CLASS expressions are evaluated. The string is simply a MapServer expression:
FILTER ("[type]"='road' and [size]<2)
Native filters are supported through the NATIVE_FILTER PROCESSING key:
PROCESSING 'NATIVE_FILTER=id=234'
Note: Until MapServer 6, native filters could be specified as:
FILTER 'where id=234'.
But this is no longer supported.
FILTERITEM [attribute] Item to use with simple FILTER expressions. OGR and shapefiles only.
FOOTER [filename] Template to use after a layer’s set of results have been sent. Multiresult query modes only.
4.1. Mapfile
188
MapServer Documentation, Release 7.0.6
GEOMTRANSFORM [<expression>|<Javascript file>] Used to indicate that the current feature will be transformed. Introduced in version 6.4.
• <expression>: Applies the given expression to the geometry.
Supported expressions:
– (buffer([shape],dist)): Buffer the geometry ([shape]) using dist pixels as buffer distance. For polygons, a negative dist will produce a setback.
– (simplify([shape],tolerance)): simplifies a geometry ([shape]) using the standard Douglas-Peucker
algorithm.
– (simplifypt([shape], tolerance)): simplifies a geometry ([shape]), ensuring that the result is a valid
geometry having the same dimension and number of components as the input. tolerance must be
non-negative.
– (generalize([shape],tolerance)): simplifies a geometry ([shape]) in way comparable to FME’s
ThinNoPoint algorithm. See http://trac.osgeo.org/gdal/ticket/966 for more information.
– (smoothsia([shape], smoothing_size, smoothing_iteration, preprocessing)): will smooth a geometry
([shape]) using the SIA algorithm
See also:
GEOMTRANSFORM - Geometry Transformations and shape_smoothing
There is a difference between STYLE and LAYER GEOMTRANSFORM. LAYER-level will receive
ground coordinates (meters, degress, etc) and STYLE-level will receive pixel coordinates. The argument
to methods such as simplify() must be in the same units as the coordinates of the shapes at that point of the
rendering workflow, i.e. pixels at the STYLE-level and in ground units at the LAYER-level.
LAYER NAME "my_layer"
TYPE LINE
STATUS DEFAULT
DATA "lines.shp"
GEOMTRANSFORM (simplify([shape], 10)) ## 10 ground units
CLASS
STYLE
GEOMTRANSFORM (buffer([shape], 5) ## 5 pixels
WIDTH 2
COLOR 255 0 0
END
END
END
The [map_cellsize] variable is available if you need to pass a pixel value at the LAYER-level.
LAYER NAME "my_layer"
TYPE LINE
STATUS DEFAULT
DATA "lines.shp"
UNITS meters
# 10 * [map_cellsize] == 10 pixels converted to ground units
GEOMTRANSFORM (simplify([shape], [map_cellsize]*10))
...
To get this variable working in the math expression parser, the [map_cellsize] has to be converted into the
layer ground unit. If you choose to use [map_cellsize] in your GEOMTRANSFORM expression, you must
explicitly set the UNITS option in the layer.
4.1. Mapfile
189
MapServer Documentation, Release 7.0.6
• <Javascript file>: A Javascript file that returns a new geometry. See Javascript transformation.
LAYER
...
GEOMTRANSFORM "javascript://transform.js" # relative path
END
or
LAYER
...
GEOMTRANSFORM "javascript:///home/user/transform.js" # absolute path
END
New in version 7.0.
Note: Requires V8 MapScript Support.
See also:
GEOMTRANSFORM - Geometry Transformations
GRID Signals the start of a GRID object.
GROUP [name] Name of a group that this layer belongs to. The group name can then be reference as a regular layer
name in the template files, allowing to do things like turning on and off a group of layers at once.
If a group name is present in the LAYERS parameter of a CGI request, all the layers of the group are returned
(the STATUS of the LAYERs have no effect).
HEADER [filename] Template to use before a layer’s set of results have been sent. Multiresult query modes only.
JOIN Signals the start of a JOIN object.
LABELANGLEITEM [attribute] (As of MapServer 5.0 this parameter is no longer available. Please see the LABEL
object’s ANGLE parameter) For MapServer versions < 5.0, this is the item name in attribute table to use for
class annotation angles. Values should be in degrees.
Deprecated since version 5.0.
LABELCACHE [on|off] Specifies whether labels should be drawn as the features for this layer are drawn, or whether
they should be cached and drawn after all layers have been drawn. Default is on. Label overlap removal, auto
placement etc... are only available when the label cache is active.
LABELITEM [attribute] Item name in attribute table to use for class annotation (i.e. labeling).
LABELMAXSCALEDENOM [double] Minimum scale at which this LAYER is labeled. Scale is given as the
denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented
in MapServer 5.0, to replace the deprecated LABELMAXSCALE parameter.
See also:
Map Scale
LABELMINSCALEDENOM [double] Maximum scale at which this LAYER is labeled. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in
MapServer 5.0, to replace the deprecated LABELMINSCALE parameter.
See also:
Map Scale
4.1. Mapfile
190
MapServer Documentation, Release 7.0.6
LABELREQUIRES [expression] Sets context for labeling this layer, for example:
LABELREQUIRES "![orthoquads]"
means that this layer would NOT be labeled if a layer named “orthoquads” is on. The expression consists of
a boolean expression based on the status of other layers, each [layer name] substring is replaced by a 0 or a 1
depending on that layer’s STATUS and then evaluated as normal. Logical operators AND and OR can be used.
LABELSIZEITEM [attribute] (As of MapServer 5.0 this parameter is no longer available. Please see the LABEL
object’s SIZE parameter) For MapServer versions < 5.0, this is the item name in attribute table to use for class
annotation sizes. Values should be in pixels.
Deprecated since version 5.0.
MASK [layername] The data from the current layer will only be rendered where it intersects features from the
[layername] layer. [layername] must reference the NAME of another LAYER defined in the current mapfile. can
be any kind of mapserver layer, i.e. vector or raster. If the current layer has labelling configured, then only
labels who’s label-point fall inside the unmasked area will be added to the labelcache (the actual glyphs for the
label may be rendered ontop of the masked-out area.
Note: Unless you want the features of [layername] to actually appear on the generated map, [layername] should
usually be set to STATUS OFF.
See also:
rfc79
MAXFEATURES [integer] Specifies the number of features that should be drawn for this layer in the CURRENT
window. Has some interesting uses with annotation and with sorted data (i.e. lakes by area).
MAXGEOWIDTH [double] Maximum width, in the map’s geographic units, at which this LAYER is drawn. If
MAXSCALEDENOM is also specified then MAXSCALEDENOM will be used instead.
The width of a map in geographic units can be found by calculating the following from the extents:
[maxx] - [minx]
New in version 5.4.0.
MAXSCALEDENOM [double] Minimum scale at which this LAYER is drawn. Scale is given as the denominator
of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000.
New in version 5.0.0: Replaced MAXSCALE.
See also:
Map Scale
METADATA This keyword allows for arbitrary data to be stored as name value pairs. This is used with OGC WMS
to define things such as layer title. It can also allow more flexibility in creating templates, as anything you put
in here will be accessible via template tags.
Example:
METADATA
"title" "My layer title"
"author" "Me!"
END
4.1. Mapfile
191
MapServer Documentation, Release 7.0.6
MINGEOWIDTH [double] Minimum width, in the map’s geographic units, at which this LAYER is drawn. If
MINSCALEDENOM is also specified then MINSCALEDENOM will be used instead.
The width of a map in geographic units can be found by calculating the following from the extents:
[maxx] - [minx]
New in version 5.4.0.
MINSCALEDENOM [double] Maximum scale at which this LAYER is drawn. Scale is given as the denominator
of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer
5.0, to replace the deprecated MINSCALE parameter.
See also:
Map Scale
NAME [string] Short name for this layer. This name is the link between the mapfile and web interfaces that refer to
this name. They must be identical. The name should be unique, unless one layer replaces another at different
scales. Use the GROUP option to associate layers with each other. It is recommended that the name not contain
spaces, special characters, or begin with a number (which could cause problems through interfaces such as OGC
services).
OFFSITE [r] [g] [b] | [hexadecimal string] Sets the color index to treat as transparent for raster layers.
• r, g and b shall be integers [0..255]. To specify black pixels, the following is used:
OFFSITE 0 0 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
OFFSITE "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
OFFSITE "#FF00FFCC"
OPACITY [integer|alpha]
Deprecated since version 7.0: Use a COMPOSITE block instead.
PLUGIN [filename] Additional library to load by MapServer, for this layer. This is commonly used to load specific
support for SDE and Microsoft SQL Server layers, such as:
CONNECTIONTYPE PLUGIN
CONNECTION "hostname,port:xxx,database,username,password"
PLUGIN "C:/ms4w/Apache/specialplugins/msplugin_sde_92.dll"
DATA "layername,geometrycolumn,SDE.DEFAULT"
POSTLABELCACHE [true|false] Tells MapServer to render this layer after all labels in the cache have been drawn.
Useful for adding neatlines and similar elements. Default is false.
PROCESSING [string] Passes a processing directive to be used with this layer. The supported processing directives
vary by layer type, and the underlying driver that processes them.
• ArcSDE Directives - All ArcSDE processing options are described in ArcSDE. Here are two examples.
PROCESSING "QUERYORDER=ATTRIBUTE"
PROCESSING "OBJECTID=OBJECTID"
4.1. Mapfile
192
MapServer Documentation, Release 7.0.6
• Attributes Directive - The ITEMS processing option allows to specify the name of attributes for inline
layers or specify the subset of the attributes to be used by the layer, such as:
PROCESSING "ITEMS=itemname1,itemname2,itemname3"
• Clustering - cluster object directives are described in CLUSTER
PROCESSING
PROCESSING
PROCESSING
PROCESSING
"CLUSTER_GET_ALL_SHAPES=ON"
"CLUSTER_KEEP_LOCATIONS=ON"
"CLUSTER_USE_MAP_UNITS=ON"
"ITEMS=attribute1,attribute2,attribute3"
• Connection Pooling Directive - This is where you can enable connection pooling for certain layer layer
types. Connection pooling will allow MapServer to share the handle to an open database or layer connection throughout a single map draw process. Additionally, if you have FastCGI enabled, the connection
handle will stay open indefinitely, or according to the options specified in the FastCGI configuration. Oracle Spatial, ArcSDE, OGR and PostGIS/PostgreSQL currently support this approach. “DEFER” enables
connection pooling; “ALWAYS” will always close the connection after use, and will also not try to reuse
a shared connection from the pool that might come from another layer.
PROCESSING "CLOSE_CONNECTION=DEFER"
or
PROCESSING "CLOSE_CONNECTION=ALWAYS"
• Contour Directives - contour directives are described in Contour.
PROCESSING
PROCESSING
PROCESSING
PROCESSING
"BANDS=1"
"CONTOUR_INTERVAL=5"
"CONTOUR_LEVELS=100,500,1000"
"CONTOUR_ITEM=elevation"
• Kernel density radius - Radius in pixels of the gaussian filter to apply to the bitmap array once all features
have been accumulated. Higher values result in increased cpu time needed to compute the filtered data.
PROCESSING "KERNELDENSITY_RADIUS=10"
New in version 7.0.
• Kernel density compute borders - A kernel of radius “r” cannot be applied to “r” pixels along the borders
of the image. The default is to extend the search rectangle of the input datasource to include features “r”
pixels outside of the current map extent so that the computed heatmap extends to the full extent of the
resulting image. This can be deactivated when tiling if the tiling software applies a metabuffer of “r”
pixels to its requests, to avoid the performance overhead of computing this extra information.
PROCESSING "KERNELDENSITY_COMPUTE_BORDERS=ON|OFF"
New in version 7.0.
• Kernel density normalization- If set to “AUTO”, the created raster band will be scaled such that its
intensities range from 0 to 255, in order to fully span the configured color ramp. Such behavior may not be
desirable (typically for tiling) as the resulting intensity of a pixel at a given location will vary depending
on the extent of the current map request. If set to a numeric value, the samples will be multiplied by the
given value. It is up to the user to determine which scaling value to use to make the resulting pixels span
the full 0-255 range; determining that value is mostly a process of trial and error. Pixels that fall outside
the 0-255 range will be clipped to 0 or 255.
4.1. Mapfile
193
MapServer Documentation, Release 7.0.6
PROCESSING "KERNELDENSITY_NORMALIZATION=AUTO|numeric"
New in version 7.0.
• Raster colour ramping - RANGE_COLORSPACE=RGB|HSL - The default RANGE support interpolates
colors between stops in RGB space, which usually results in washed out colors. The interpolation can be
done in HSL space which usually results in wanted output for heatmaps.
PROCESSING "RANGE_COLORSPACE=HSL"
New in version 7.0.
• Label Directive - The LABEL_NO_CLIP processing option can be used to skip clipping of shapes when
determining associated label anchor points. This avoids changes in label position as extents change between map draws. It also avoids duplicate labels where features appear in multiple adjacent tiles when
creating tiled maps.
PROCESSING "LABEL_NO_CLIP=True"
• Line Rendering Directive - The POLYLINE_NO_CLIP processing option can be used to skip clipping
of shapes when rendering styled lines (dashed or styled with symbols). This avoids changes in the line
styling as extents change between map draws. It also avoids edge effects where features appear in multiple
adjacent tiles when creating tiled maps.
PROCESSING "POLYLINE_NO_CLIP=True"
• OGR Styles Directive - This directive can be used for obtaining label styles through MapScript. For more
information see the MapServer’s OGR document.
PROCESSING "GETSHAPE_STYLE_ITEMS=all"
• MSSQL specific options - MSSQL_READ_WKB=TRUE - Uses WKB (Well Known Binary) format
instead of native format when fetching geometries.
PROCESSING "MSSQL_READ_WKB=TRUE"
• Native filter Directive - This directive can be used to do driver specific filtering. For database connections
the string is a SQL WHERE clause that is valid with respect to the underlying database.
PROCESSING "NATIVE_FILTER=id=234"
New in version 7.0.
• PostGIS specific options - FORCE2D=YES can be used to force 2D only geometries to be retrieved from
PostGIS.
PROCESSING "FORCE2D=YES"
• Vector field specific rendering options - UV_SPACING: The spacing is the distance, in pixels, between
arrows to be displayed in the vector field. Default is 32. UV_SIZE_SCALE: Used to convert the vector
lengths (magnitude) of the raster to pixels for a better rendering. Default is 1.
PROCESSING "UV_SPACING=40"
PROCESSING "UV_SIZE_SCALE=0.2"
4.1. Mapfile
194
MapServer Documentation, Release 7.0.6
• AGG renderer tweaking - This directive can be used for setting the linear gamma to be used when
rendering polygon features. The default value of 0.75 (that can be overridden at the OUTPUTFORMAT
level) can be set to a lower value to limit/remove the faint outlines that appear between adjacent polygons.
A value of 0.5 is usually good enough.
PROCESSING "GAMMA=0.5"
• Raster Directives - All raster processing options are described in Raster Data. Here we see the SCALE
and BANDs directives used to autoscale raster data and alter the band mapping.
PROCESSING "SCALE=AUTO"
PROCESSING "BANDS=3,2,1"
• Union layer Directives - The following processing options can be used with the union layers:
UNION_STATUS_CHECK (TRUE or FALSE) - controls whether the status of the source layes should
be checked and the invisible layers (STATUS=OFF) should be skipped. Default value is FALSE.
UNION_SCALE_CHECK (TRUE or FALSE) - controls whether the scale range of the source layes should
be checked and the invisible layers (falling outside of the scale range and zoom range) should be skipped.
Default value is TRUE. UNION_SRCLAYER_CLOSE_CONNECTION - override the connection pool
setting of the source layers. By introducing this setting we alter the current behaviour which is equivalent
to: “UNION_SRCLAYER_CLOSE_CONNECTION=ALWAYS”
PROCESSING "UNION_STATUS_CHECK=FALSE"
PROCESSING "UNION_SCALE_CHECK=TRUE"
PROCESSING "UNION_SRCLAYER_CLOSE_CONNECTION=ALWAYS"
PROJECTION Signals the start of a PROJECTION object.
REQUIRES [expression] Sets context for displaying this layer (see LABELREQUIRES).
SCALETOKEN Signals the start of a SCALETOKEN object. Allows scale dependent string substitutions. See rfc86.
LAYER
...
SCALETOKEN
NAME "%pri%"
VALUES
"0" "1"
"1000" "2"
"10000" "3"
END # VALUES
END # SCALETOKEN
# data from a specific table:
DATA "geom from mytable_%pri%"
# data from a specific Shapefile format dataset:
DATA "/path/to/roads_%pri%.shp"
# data from a specific column in the table:
DATA "geom_%pri% from roads"
# filtering:
DATA "geom_%pri% from (select * from roads where pri > %pri%) as foo"
CLASS
...
END # CLASS
END # LAYER
In the previous example, %pri% would be replaced by:
• “1” for scale denominators smaller than 1,000, giving:
4.1. Mapfile
195
MapServer Documentation, Release 7.0.6
DATA
DATA
DATA
DATA
"geom from mytable_1"
"/path/to/roads_1.shp"
"geom_1 from roads"
"geom_1 from (select * from roads where pri > 1) as foo"
• “2” for scale denominators between 1,000 and 10,000:
DATA
DATA
DATA
DATA
"geom from mytable_2"
"/path/to/roads_2.shp"
"geom_2 from roads"
"geom_2 from (select * from roads where pri > 2) as foo"
• “3” for scale denominators larger than 10,000:
DATA
DATA
DATA
DATA
"geom from mytable_3"
"/path/to/roads_3.shp"
"geom_3 from roads"
"geom_3 from (select * from roads where pri > 3) as foo"
New in version 6.4.
SIZEUNITS [feet|inches|kilometers|meters|miles|nauticalmiles|pixels] Sets the unit of CLASS object SIZE values
(default is pixels). Useful for simulating buffering. nauticalmiles was added in MapServer 5.6.
STATUS [on|off|default] Sets the current status of the layer. Often modified by MapServer itself. Default turns the
layer on permanently.
Note: In CGI mode, layers with STATUS DEFAULT cannot be turned off using normal mechanisms. It is
recommended to set layers to STATUS DEFAULT while debugging a problem, but set them back to ON/OFF in
normal use.
Note: For WMS, layers in the server mapfile with STATUS DEFAULT are always sent to the client.
Note: The STATUS of the individual layers of a GROUP has no effect when the group name is present in the
LAYERS parameter of a CGI request - all the layers of the group will be returned.
STYLEITEM [<attribute>|auto|<javascript file>] Styling based on attributes or generated with Javascript
• <attribute>: Item to use for feature specific styling. The style information may be represented by a
separate attribute (style string) attached to the feature. MapServer supports the following style string
representations:
– MapServer STYLE definition - The style string can be represented as a MapServer STYLE block
according to the following example:
STYLE BACKGROUNDCOLOR 128 0 0 COLOR 0 0 208 END
– MapServer CLASS definition - By specifying the entire CLASS instead of a single style allows to
use further options (like setting expressions, label attributes, multiple styles) on a per feature basis.
– OGR Style String - MapServer support rendering the OGR style string format according to the OGR
- Feature Style Specification documentation. Currently only a few data sources support storing the
styles along with the features (like MapInfo, AutoCAD DXF, Microstation DGN), however those
4.1. Mapfile
196
MapServer Documentation, Release 7.0.6
styles can easily be transferred to many other data sources as a separate attribute by using the ogr2ogr
command line tool as follows:
ogr2ogr -sql "select *, OGR_STYLE from srclayer" "dstlayer" "srclayer"
• AUTO: The value: AUTO can be used for automatic styling.
– Automatic styling can be provided by the driver. Currently, only the OGR driver supports automatic
styling.
– When used for a Union Layer, the styles from the source layers will be used.
• <Javascript file>: A Javascript file that returns a new string containing either a STYLE definition or a
CLASS definition with one or multiple styles. See STYLEITEM Javascript.
LAYER
...
STYLEITEM "javascript://myscript.js" # relative path
CLASS
END
END
or
LAYER
...
STYLEITEM "javascript:///home/user/myscript.js" # absolute path
CLASS
END
END
New in version 6.6.
Note: Requires V8 MapScript Support.
SYMBOLSCALEDENOM [double] The scale at which symbols and/or text appear full size. This allows for dynamic scaling of objects based on the scale of the map. If not set then this layer will always appear at the
same size. Scaling only takes place within the limits of MINSIZE and MAXSIZE as described above. Scale is
given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000.
Implemented in MapServer 5.0, to replace the deprecated SYMBOLSCALE parameter.
See also:
Map Scale
TEMPLATE [file|url] Used as a global alternative to CLASS TEMPLATE. See Templating for more info.
TILEINDEX [filename|layername] Name of the tileindex file or layer. A tileindex is similar to an ArcInfo library
index. The tileindex contains polygon features for each tile. The item that contains the location of the tiled data
is given using the TILEITEM parameter. When a file is used as the tileindex for shapefile or raster layers, the
tileindex should be a shapefile. For CONNECTIONTYPE OGR layers, any OGR supported datasource can be
a tileindex. Normally the location should contain the path to the tile file relative to the shapepath, not relative to
the tileindex itself. If the DATA parameter contains a value then it is added to the end of the location. When a
tileindex layer is used, it works similarly to directly referring to a file, but any supported feature source can be
used (ie. postgres, oracle).
Note: All files in the tileindex should have the same coordinate system, and for vector files the same set of
4.1. Mapfile
197
MapServer Documentation, Release 7.0.6
attributes in the same order.
Note: Starting with MapServer 6.4, raster layers can use a tileindex with tiles of different projections. For that,
the TILESRS parameter must be specified.
TILEITEM [attribute] Item that contains the location of an individual tile, default is “location”.
TILESRS [attribute] Name of the attribute that contains the SRS of an individual tile. That SRS can be expressed
in WKT format, as an EPSG:XXXX code or as a PROJ.4 string. If the tileindex contains rasters in different
projections, this option must be specified. If the tileindex has been generated with gdaltindex (GDAL >= 2.0),
the value of TILESRS is the value of the -src_srs_name option of gdaltindex. See Tileindexes with tiles in
different projections
Note: This option is currently available only on raster layers.
TOLERANCE [double] Sensitivity for point based queries (i.e. via mouse and/or map coordinates). Given in TOLERANCEUNITS. If the layer is a POINT or a LINE, the default is 3. For all other layer types, the default is 0.
To restrict polygon searches so that the point must occur in the polygon set the tolerance to zero. This setting
does not apply to WFS GetFeature operations.
TOLERANCEUNITS [pixels|feet|inches|kilometers|meters|miles|nauticalmiles|dd] Units of the TOLERANCE
value. Default is pixels. Nauticalmiles was added in MapServer 5.6.
TRANSPARENCY [integer|alpha] - deprecated
Deprecated since version 5.0: Use OPACITY instead.
Deprecated since version 7.0: Use COMPOSITE instead.
TRANSFORM [true|false] | [ul|uc|ur|cl|cc|cr|ll|lc|lr] Tells MapServer whether or not a particular layer needs to be
transformed from some coordinate system to image coordinates. Default is true. This allows you to create
shapefiles in image/graphics coordinates and therefore have features that will always be displayed in the same
location on every map. Ideal for placing logos or text in maps. Remember that the graphics coordinate system
has an origin in the upper left hand corner of the image, contrary to most map coordinate systems.
Version 4.10 introduces the ability to define features with coordinates given in pixels (or percentages, see
UNITS), most often inline features, relative to something other than the UL corner of an image. That is what
‘TRANSFORM FALSE’ means. By setting an alternative origin it allows you to anchor something like a copyright statement to another portion of the image in a way that is independent of image size.
TYPE [chart|circle|line|point|polygon|raster|query] Specifies how the data should be drawn. Need not be the same
as the shapefile type. For example, a polygon shapefile may be drawn as a point layer, but a point shapefile may
not be drawn as a polygon layer. Common sense rules.
In order to differentiate between POLYGONs and POLYLINEs (which do not exist as a type), simply respectively use or omit the COLOR keyword when classifying. If you use it, it’s a polygon with a fill color, otherwise
it’s a polyline with only an OUTLINECOLOR.
A circle must be defined by a a minimum bounding rectangle. That is, two points that define the smallest square
that can contain it. These two points are the two opposite corners of said box. The following is an example
using inline points to draw a circle:
LAYER
NAME 'inline_circles'
TYPE CIRCLE
STATUS ON
4.1. Mapfile
198
MapServer Documentation, Release 7.0.6
FEATURE
POINTS
74.01 -53.8
110.7 -22.16
END
END
CLASS
STYLE
COLOR 0 0 255
END
END
END
TYPE query means the layer can be queried but not drawn.
Note: TYPE annotation has been deprecated since version 6.2. Identical functionality can be obtained by
adding LABEL level STYLE blocks, and do not require loading the datasets twice in two different layers as was
the case with layers of TYPE annotation.
See also:
The Dynamic Charting HowTo for TYPE chart.
UNITS [dd|feet|inches|kilometers|meters|miles|nauticalmiles|percentages|pixels] Units of the layer. percentages
(in this case a value between 0 and 1) was added in MapServer 4.10 and is mostly geared for inline features.
nauticalmiles was added in MapServer 5.6.
UTFDATA [string] A UTFGrid JSON template. MapServer expression syntax (expressionObj). If no UTFDATA is
provided, no data beyond the UTFITEM values will be exposed. If UTFITEM is set, the UTFDATA expose those
so that keys and data can be connected. See rfc93 and UTFGrid Output.
UTFDATA "{\"id\":\"[fid]\", \"name\":\"[name]\", \"area\":\"[area]\"}"
New in version 7.0.
UTFITEM [string] The attribute to use as the ID for the UTFGrid. If a UTFITEM is not set, the sequential id (based
on rendering order) is being used. If UTFITEM is set, the UTFDATA expose those so that keys and data can be
connected. See rfc93 and UTFGrid Output.
UTFITEM "fid"
New in version 7.0.
VALIDATION Signals the start of a VALIDATION block.
As of MapServer 5.4.0, VALIDATION blocks are the preferred mechanism for specifying validation patterns for
CGI param runtime substitutions. See Run-time Substitution.
4.1.15 LEADER
Table of Contents
• LEADER
– Description
4.1. Mapfile
199
MapServer Documentation, Release 7.0.6
– Supported Layer Types
– Mapfile Parameters
– Mapfile Snippet
– Example: World Countries Labels
Description
Since version 6.2, MapServer has the ability to draw label lines to features where space is an issue for the label (often
when the label text is larger than the polygon being labelled). This feature was added through rfc81.
Supported Layer Types
POLYGON
Mapfile Parameters
GRIDSTEP [integer] Specifies the number of pixels between positions that are tested for a label line. You might
start with a value of 5, and increase depending on performance (see example below).
MAXDISTANCE [integer] Specifies the maximum distance in pixels from the normal label location that a leader
line can be drawn. You might start with a value of 30, and increase depending on the resulting placement (see
example below).
STYLE Signals the start of a STYLE object. Use this to style the leader line.
Mapfile Snippet
LAYER
NAME "my-labels"
TYPE POLYGON
...
CLASS
...
LABEL
...
END
LEADER
GRIDSTEP 5 # number of pixels between positions that are tested
MAXDISTANCE 30 # distance in pixels that leader text can be drawn
STYLE # normal line styles are supported
COLOR 255 0 0
WIDTH 1
END
END
END
END
4.1. Mapfile
200
MapServer Documentation, Release 7.0.6
Example: World Countries Labels
The following example uses a polygon layer to display country labels.
Note: The data and mapfile for this example are available for download at: http://download.osgeo.org/mapserver/
tickets/label-leader.zip (11MB).
Mapfile Example #1
MAP
NAME "leader-test"
STATUS ON
SIZE 800 600
SYMBOLSET "../etc/symbols.txt"
EXTENT -43 10 83 83
UNITS DD
SHAPEPATH "../data"
IMAGECOLOR 255 255 255
FONTSET "../etc/fonts.txt"
WEB
IMAGEPATH "/ms4w/tmp/ms_tmp/"
IMAGEURL "/ms_tmp/"
END
#
# Start of layer definitions
#
LAYER
NAME "continents"
TYPE POLYGON
STATUS ON
DATA "world_countries-dissolve"
LABELITEM "NA2DESC"
CLASS
NAME "World Countries"
STYLE
COLOR 200 200 200
OUTLINECOLOR 120 120 120
END
LABEL
COLOR 0 0 0
FONT sans
TYPE truetype
SIZE 8
POSITION AUTO
PARTIALS FALSE
OUTLINECOLOR 255 255 255
MINFEATURESIZE 2
MINDISTANCE 1000
BUFFER 5
END
4.1. Mapfile
201
MapServer Documentation, Release 7.0.6
################################
# Leader Object
################################
LEADER
GRIDSTEP 40
MAXDISTANCE 1000
STYLE
COLOR 200 100 100
WIDTH 2
END
END
END
END
END # Map File
Map Image
Mapfile Example #2
This time use a shorter maximum leader line (MAXDISTANCE) and increase the number of tests (GRIDSTEP).
4.1. Mapfile
202
MapServer Documentation, Release 7.0.6
MAP
LAYER
...
CLASS
...
LABEL
...
END
################################
# Leader Object
################################
LEADER
GRIDSTEP 10
MAXDISTANCE 100
STYLE
COLOR 200 100 100
WIDTH 2
END
END
END
END
END # Map File
4.1. Mapfile
203
MapServer Documentation, Release 7.0.6
Map Image
4.1.16 LEGEND
The size of the legend image is NOT known prior to creation so be careful not to hard-code width and height in the
<IMG> tag in the template file.
IMAGECOLOR [r] [g] [b] | [hexadecimal string] Color to initialize the legend with (i.e. the background).
• r, g and b shall be integers [0..255]. To specify green, the following is used:
IMAGECOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
IMAGECOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
IMAGECOLOR "#FF00FFCC"
4.1. Mapfile
204
MapServer Documentation, Release 7.0.6
INTERLACE [on|off] Default is [on]. This keyword is now deprecated in favor of using the FORMATOPTION
“INTERLACE=ON” line in the OUTPUTFORMAT declaration.
Deprecated since version 4.6.
KEYSIZE [x][y] Size of symbol key boxes in pixels. Default is 20 by 10.
KEYSPACING [x][y] Spacing between symbol key boxes ([y]) and labels ([x]) in pixels. Default is 5 by 5.
LABEL Signals the start of a LABEL object
OUTLINECOLOR [r] [g] [b] | [hexadecimal string] Color to use for outlining symbol key boxes.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
OUTLINECOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
OUTLINECOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
OUTLINECOLOR "#FF00FFCC"
POSITION [ul|uc|ur|ll|lc|lr] Where to place an embedded legend in the map. Default is lr.
POSTLABELCACHE [true|false] Tells MapServer to render this legend after all labels in the cache have been
drawn. Useful for adding neatlines and similar elements. Default is false.
STATUS [on|off|embed] Is the legend image to be created.
TEMPLATE [filename] HTML legend template file.
See also:
HTML Legends with MapServer
TRANSPARENT [on|off] Should the background color for the legend be transparent. This flag is now deprecated in
favor of declaring transparency within OUTPUTFORMAT declarations. Default is off.
Deprecated since version 4.6.
4.1.17 MAP
Note: The map object is started with the word MAP, and ended with the word END.
ANGLE [double] Angle, given in degrees, to rotate the map. Default is 0. The rendered map will rotate in a clockwise
direction. The following are important notes:
• Requires a PROJECTION object specified at the MAP level and for each LAYER object (even if all layers
are in the same projection).
• Requires MapScript (SWIG, PHP MapScript). Does not work with CGI mode.
• If using the LABEL object’s ANGLE or the LAYER object’s LABELANGLEITEM parameters as well, these
parameters are relative to the map’s orientation (i.e. they are computed after the MAP object’s ANGLE).
For example, if you have specified an ANGLE for the map of 45, and then have a layer LABELANGLEITEM
4.1. Mapfile
205
MapServer Documentation, Release 7.0.6
value of 45, the resulting label will not appear rotated (because the resulting map is rotated clockwise 45
degrees and the label is rotated counter-clockwise 45 degrees).
• More information can be found on the MapRotation Wiki Page.
CONFIG [key] [value] This can be used to specify several values at run-time, for both MapServer and GDAL/OGR
libraries. Developers: values will be passed on to CPLSetConfigOption(). Details on GDAL/OGR options
are found in their associated driver documentation pages (GDAL/OGR). The following options are available
specifically for MapServer:
CGI_CONTEXT_URL [value] This CONFIG parameter can be used to enable loading a map context from a
URL. See the Map Context HowTo for more info.
MS_ENCRYPTION_KEY [filename] This CONFIG parameter can be used to specify an encryption key that
is used with MapServer’s msencypt utility.
MS_ERRORFILE [filename] This CONFIG parameter can be used to write MapServer errors to a file (as of
MapServer 5.0). With MapServer 5.x, a full path (absolute reference) is required, including the filename.
Starting with MapServer 6.0, a filename with relative path can be passed via this CONFIG directive, in
which case the filename is relative to the mapfile location. Note that setting MS_ERRORFILE via an
environment variable always requires an absolute path since there would be no mapfile to make the path
relative to. For more on this see the DEBUG parameter below.
MS_NONSQUARE [yes|no] This CONFIG parameter can be used to allow non-square pixels (meaning that
the pixels represent non-square regions). For “MS_NONSQUARE” “yes” to work, the MAP, and each
LAYER will have to have a PROJECTION object.
Note: Has no effect for WMS.
ON_MISSING_DATA [FAIL|LOG|IGNORE] This CONFIG parameter can be used to tell MapServer how
to handle missing data in tile indexes (as of MapServer 5.3-dev, r8015). Previous MapServer versions
required a compile-time switch (“IGNORE_MISSING_DATA”), but this is no longer required.
FAIL This will cause MapServer to throw an error and exit (to crash, in other words) on a missing file in
a tile index. This is the default.
CONFIG "ON_MISSING_DATA" "FAIL"
LOG This will cause MapServer to log the error message for a missing file in a tile index, and continue
with the map creation. Note: DEBUG parameter and CONFIG “MS_ERRORFILE” need to be set for
logging to occur, so please see the DEBUG parameter below for more information.
CONFIG "ON_MISSING_DATA" "LOG"
IGNORE This will cause MapServer to not report or log any errors for missing files, and map creation
will occur normally.
CONFIG "ON_MISSING_DATA" "IGNORE"
PROJ_LIB [path] This CONFIG parameter can be used to define the location of your EPSG files for the
PROJ.4 library. Setting the [key] to PROJ_LIB and the [value] to the location of your EPSG files will
force PROJ.4 to use this value. Using CONFIG allows you to avoid setting environment variables to point
to your PROJ_LIB directory. Here are some examples:
1. Unix
CONFIG "PROJ_LIB" "/usr/local/share/proj/"
4.1. Mapfile
206
MapServer Documentation, Release 7.0.6
2. Windows
CONFIG "PROJ_LIB" "C:/somedir/proj/nad/"
DATAPATTERN [regular expression] This defines a regular expression to be applied to requests to change DATA
parameters via URL requests (i.e. map.layer[layername]=DATA+...). If a pattern doesn’t exist then web users
can’t monkey with support files via URLs. This allows you to isolate one application from another if you desire,
with the default operation being very conservative. See also TEMPLATEPATTERN.
DEBUG [off|on|0|1|2|3|4|5] Enables debugging of all of the layers in the current map.
Debugging with MapServer versions >= 5.0:
Verbose output is generated and sent to the standard error output (STDERR) or the MapServer errorfile if one
is set using the “MS_ERRORFILE” environment variable. You can set the environment variable by using the
CONFIG parameter at the MAP level of the mapfile, such as:
CONFIG "MS_ERRORFILE" "/ms4w/tmp/ms_error.txt"
You can also set the environment variable in Apache by adding the following to your httpd.conf:
SetEnv MS_ERRORFILE "/ms4w/tmp/ms_error.txt"
Once the environment variable is set, the DEBUG mapfile parameter can be used to control the level of debugging output. Here is a description of the possible DEBUG values:
• DEBUG O or OFF - only msSetError() calls are logged to MS_ERRORFILE. No msDebug() output at
all. This is the default and corresponds to the original behavior of MS_ERRORFILE in MapServer 4.x.
• DEBUG 1 or ON - includes all output from DEBUG 0 plus msDebug() warnings about common pitfalls,
failed assertions or non-fatal error situations (e.g. missing or invalid values for some parameters, missing
shapefiles in tileindex, timeout error from remote WMS/WFS servers, etc.).
• DEBUG 2 - includes all output from DEBUG 1 plus notices and timing information useful for tuning
mapfiles and applications.
• DEBUG 3 - all of DEBUG 2 plus some debug output useful in troubleshooting problems such as WMS
connection URLs being called, database connection calls, etc. This is the recommended level for debugging mapfiles.
• DEBUG 4 - DEBUG 3 plus even more details...
• DEBUG 5 - DEBUG 4 plus any msDebug() output that might be more useful to the developers than to the
users.
You can also set the debug level by using the “MS_DEBUGLEVEL” environment variable.
The DEBUG setting can also be specified for a layer, by setting the DEBUG parameter in the LAYER object.
For more details on this debugging mechanism, please see the Debugging MapServer document.
Debugging with MapServer versions < 5:
Verbose output is generated and sent to the standard error output (STDERR) or the MapServer logfile if one is
set using the LOG parameter in the WEB object. Apache users will see timing details for drawing in Apache’s
error_log file. Requires MapServer to be built with the DEBUG=MSDEBUG option (–with-debug configure
option).
DEFRESOLUTION [int] Sets the reference resolution (pixels per inch) used for symbology. Default is 72.
Used to automatically scale the symbology when RESOLUTION is changed, so the map maintains the same
look at each resolution. The scale factor is RESOLUTION / DEFRESOLUTION.
4.1. Mapfile
207
MapServer Documentation, Release 7.0.6
New in version 5.6.
EXTENT [minx] [miny] [maxx] [maxy] The spatial extent of the map to be created. In most cases you will need to
specify this, although MapServer can sometimes (expensively) calculate one if it is not specified.
FONTSET [filename] Filename of fontset file to use. Can be a path relative to the mapfile, or a full path.
IMAGECOLOR [r] [g] [b] | [hexadecimal string] Color to initialize the map with (i.e. background color). When
transparency is enabled (TRANSPARENT ON in OUTPUTFORMAT) for the typical case of 8-bit pseudocolored
map generation, this color will be marked as transparent in the output file palette. Any other map components
drawn in this color will also be transparent, so for map generation with transparency it is best to use an otherwise
unused color as the background color.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
IMAGECOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
IMAGECOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
IMAGECOLOR "#FF00FFCC"
IMAGEQUALITY [int] Deprecated Use FORMATOPTION “QUALITY=n” in the OUTPUTFORMAT declaration to specify compression quality for JPEG output.
Deprecated since version 4.6.
IMAGETYPE [jpeg|pdf|png|svg|...|userdefined] Output format (raster or vector) to generate. The name used here
must match the ‘NAME’ of a user defined or internally available OUTPUTFORMAT. For a complete list of
available IMAGEFORMATs, see the OUTPUTFORMAT section.
INTERLACE [on|off] Deprecated Use FORMATOPTION “INTERLACE=ON” in the OUTPUTFORMAT declaration to specify if the output images should be interlaced.
Deprecated since version 4.6.
LAYER Signals the start of a LAYER object.
LEGEND Signals the start of a LEGEND object.
MAXSIZE [integer] Sets the maximum size of the map image. This will override the default value. For example,
setting this to 4096 means that you can have up to 4096 pixels in both dimensions (i.e. max of 4096x4096).
Default is 4096 for MapServer version >= 7.0.3 (for earlier versions the default was 2048).
NAME [name] Prefix attached to map, scalebar and legend GIF filenames created using this mapfile. It should be
kept short.
PROJECTION Signals the start of a PROJECTION object.
QUERYMAP Signals the start of a QUERYMAP object.
REFERENCE Signals the start of a REFERENCE MAP object.
RESOLUTION [int] Sets the pixels per inch for output, only affects scale computations. Default is 72.
SCALEDENOM [double] Computed scale of the map. Set most often by the application. Scale is given as the
denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented
in MapServer 5.0, to replace the deprecated SCALE parameter.
4.1. Mapfile
208
MapServer Documentation, Release 7.0.6
See also:
Map Scale
SCALEBAR Signals the start of a SCALEBAR object.
SHAPEPATH [filename] Path to the directory holding the shapefiles or tiles. There can be further subdirectories
under SHAPEPATH.
SIZE [x][y] Size in pixels of the output image (i.e. the map).
STATUS [on|off] Is the map active? Sometimes you may wish to turn this off to use only the reference map or scale
bar.
SYMBOLSET [filename] Filename of the symbolset to use. Can be a path relative to the mapfile, or a full path.
Note: The SYMBOLSET file must start with the word SYMBOLSET and end with the word END.
SYMBOL Signals the start of a SYMBOL object.
TEMPLATEPATTERN [regular expression] This defines a regular expression to be applied to requests to change
the TEMPLATE parameters via URL requests (i.e. map.layer[layername].template=...). If a pattern doesn’t exist
then web users can’t monkey with support files via URLs. This allows you to isolate one application from
another if you desire, with the default operation being very conservative. See also DATAPATTERN.
TRANSPARENT [on|off]
Deprecated since version 4.6.
Use TRANSPARENT ON in the OUTPUTFORMAT declaration to specify if the output images should be
transparent.
UNITS [dd|feet|inches|kilometers|meters|miles|nauticalmiles] Units of the map coordinates. Used for scalebar and
scale computations. Nauticalmiles was added in MapServer 5.6.
WEB Signals the start of a WEB object.
4.1.18 OUTPUTFORMAT
A map file may have zero, one or more OUTPUTFORMAT object declarations, defining available output formats
supported including formats like PNG, GIF, JPEG, GeoTIFF, SVG, PDF and KML.
If OUTPUTFORMAT sections declarations are not found in the map file, the following implicit declarations will be
made. Only those for which support is compiled in will actually be available. The GeoTIFF depends on building with
GDAL support, and the PDF and SVG depend on building with cairo support.
OUTPUTFORMAT
NAME "png"
DRIVER AGG/PNG
MIMETYPE "image/png"
IMAGEMODE RGB
EXTENSION "png"
FORMATOPTION "GAMMA=0.75"
END
OUTPUTFORMAT
NAME "gif"
DRIVER GD/GIF
MIMETYPE "image/gif"
IMAGEMODE PC256
EXTENSION "gif"
4.1. Mapfile
209
MapServer Documentation, Release 7.0.6
END
OUTPUTFORMAT
NAME "png8"
DRIVER AGG/PNG8
MIMETYPE "image/png; mode=8bit"
IMAGEMODE RGB
EXTENSION "png"
FORMATOPTION "QUANTIZE_FORCE=on"
FORMATOPTION "QUANTIZE_COLORS=256"
FORMATOPTION "GAMMA=0.75"
END
OUTPUTFORMAT
NAME "jpeg"
DRIVER AGG/JPEG
MIMETYPE "image/jpeg"
IMAGEMODE RGB
EXTENSION "jpg"
FORMATOPTION "GAMMA=0.75"
END
OUTPUTFORMAT
NAME "svg"
DRIVER CAIRO/SVG
MIMETYPE "image/svg+xml"
IMAGEMODE RGB
EXTENSION "svg"
END
OUTPUTFORMAT
NAME "pdf"
DRIVER CAIRO/PDF
MIMETYPE "application/x-pdf"
IMAGEMODE RGB
EXTENSION "pdf"
END
OUTPUTFORMAT
NAME "GTiff"
DRIVER GDAL/GTiff
MIMETYPE "image/tiff"
IMAGEMODE RGB
EXTENSION "tif"
END
OUTPUTFORMAT
NAME "kml"
DRIVER KML
MIMETYPE "application/vnd.google-earth.kml.xml"
IMAGEMODE RGB
EXTENSION "kml"
END
OUTPUTFORMAT
NAME "kmz"
DRIVER KMZ
MIMETYPE "application/vnd.google-earth.kmz"
IMAGEMODE RGB
EXTENSION "kmz"
END
OUTPUTFORMAT
NAME "cairopng"
DRIVER CAIRO/PNG
MIMETYPE "image/png"
4.1. Mapfile
210
MapServer Documentation, Release 7.0.6
IMAGEMODE RGB
EXTENSION "png"
END
OUTPUTFORMAT
NAME "myUTFGrid"
DRIVER UTFGRID
FORMATOPTION "LABELS=true"
FORMATOPTION "UTFRESOLUTION=4"
FORMATOPTION "DUPLICATES=false"
END
DRIVER [name] The name of the driver to use to generate this output format. Some driver names include the definition of the format if the driver supports multiple formats. For AGG, the possible driver names are “AGG/PNG”
and “AGG/JPEG”. For GD the possible driver names are “GD/Gif” and “GD/PNG”. For output through OGR the
OGR driver name is appended, such as “OGR/Mapinfo File”. For output through GDAL the GDAL shortname
for the format is appended, such as “GDAL/GTiff”. Note that PNG, JPEG and GIF output can be generated with
either GDAL or GD (GD is generally more efficient). TEMPLATE should be used for template based output.
(mandatory). Other drivers: KML, KMZ and UTFGRID.
EXTENSION [type] Provide the extension to use when creating files of this type. (optional)
FORMATOPTION [option] Provides a driver or format specific option. Zero or more FORMATOPTION statement
may be present within a OUTPUTFORMAT declaration. (optional)
• AGG/*: “GAMMA=n” is used to specify the gamma correction to apply to polygon rendering. Allowed
values are [0.0,1.0] , default is 0.75. This value is used to prevent artifacts from appearing on the border of
contiguous polygons. Set to 1.0 to disable gamma correction.
• AGG/JPEG: The “QUALITY=n” option may be used to set the quality of jpeg produced (value from
0-100).
• AGG/PNG: “COMPRESSION=n” is used to determine the ZLIB compression applied to the png creation.
n is expected to be an integer value from 0 to 9, with 0 meaning no compression (not recommended),
1 meaning fastest compression, and 9 meaning best compression. The compression levels come at a
cost (be it in terms of cpu processing or file size, chose the setting that suits you most). The default is
COMPRESSION=6.
• AGG/PNG supports quantizing from 24/32 bits to 8bits, in order to reduce the final image size (and therefore save bandwidth) (see also MapServer issue #2436 for strategies when applying these options):
– “QUANTIZE_FORCE=on” used to reduce an RGB or RGBA image into an 8bit (or less) paletted
images. The colors used in the palette are selected to best fit the actual colors in the RGB or RGBA
image.
– “QUANTIZE_COLORS=256” used to specify the number of colors to be used when applying quantization. Maximum value is 256. Specifying anything between 17 and 255 is probably a waste of
quality as each pixel is still encoded with a full byte. Specifying a value under 16 will produce tiny
images, but severely degraded.
– “PALETTE=/path/to/palette.txt” is used to define the absolute path where palette colors can be found.
This file must contain 256 entries of r,g,b triplets for RGB imagemodes, or r,g,b,a quadruplets for
RGBA imagemodes. The expected format is one triplet (or quadruplet) per line, each value separated
by commas, and each triplet/quadruplet on a single line. If you want to use transparency with a palette,
it is important to have these two colors in the palette file: 0,0,0,0 and 255,255,255,255.
Note: 0,0,0,0 is important if you have fully transparent areas. 255,255,255,255 is opaque white. The
important colors to have in your palette really depend on your actual map, although 0,0,0,0 , 0,0,0,255
4.1. Mapfile
211
MapServer Documentation, Release 7.0.6
, and 255,255,255,255 are very likely to show up most of the time.
– “PALETTE_FORCE=on” is used to reduce image depth with a predefined palette. This option is
incompatible with the previous quantization options. To allow additional colours for anti-aliasing
other than those in the predefined palette, use with “QUANTIZE_COLORS”.
• CAIRO/PDF:
– “GEO_ENCODING=ISO32000” or “GEO_ENCODING=OGC_BP”: Geospatial PDF will be generated. Requires GDAL 1.10 with PDF driver. See the GDAL Geospatial PDF documentation for
requirements.
New in version 6.2.
– “METADATA_ITEM:option=value”: Additional PDF options can be provided using the METADATA_ITEM prefix. The following options are available: AUTHOR, CREATOR, CREATION_DATE,
KEYWORDS, PRODUCER, SUBJECT, TITLE.
New in version 6.2.
Example:
OUTPUTFORMAT
NAME pdf
DRIVER "CAIRO/PDF"
MIMETYPE "application/x-pdf"
IMAGEMODE RGB
EXTENSION "pdf"
FORMATOPTION "GEO_ENCODING=ISO32000"
FORMATOPTION "METADATA_ITEM:CREATOR=MapServer, with GDAL trunk"
FORMATOPTION "METADATA_ITEM:PRODUCER=MapServer, with GDAL trunk"
END
• GD/PNG: The “INTERLACE=[ON/OFF]” option may be used to turn interlacing on or off.
• GD/GIF: The “INTERLACE=[ON/OFF]” option may be used to turn interlacing on or off.
• GDAL/GTiff: Supports the “TILED=YES”, “BLOCKXSIZE=n”, “BLOCKYSIZE=n”, “INTERLEAVE=[PIXEL/BAND]” and “COMPRESS=[NONE,PACKBITS,JPEG,LZW,DEFLATE]” format specific options.
• GDAL/*: All FORMATOPTIONs are passed onto the GDAL create function. Options supported by GDAL
are described in the detailed documentation for each GDAL format.
• GDAL/*: “NULLVALUE=n” is used in raw image modes (IMAGEMODE BYTE/INT16/FLOAT) to preinitialize the raster and an attempt is made to record this in the resulting file as the nodata value. This is
automatically set in WCS mode if rangeset_nullvalue is set.
• OGR/*: See the OGR Output document for details of OGR format options.
• UTFGRID: See rfc93.
– “LABELS=true”. Labels can be rendered using their parent feature id (derived via UTFITEM) where
the labels bounding box is drawn to the map.
– “UTFRESOLUTION=4”. The resolution of the grid. A larger resolution will make the grid smaller
and therefore reduce its weight but also its precision.
– “DUPLICATES=false”. It may be desirable NOT to remove duplicate feature id/key pairs since that
process could be expensive depending on the number of features in the map. This option can be used
to skip this step. The resulting JSON file will be a bit larger.
4.1. Mapfile
212
MapServer Documentation, Release 7.0.6
IMAGEMODE [PC256|RGB|RGBA|INT16|FLOAT32|FEATURE] Selects the imaging mode in which the output
is generated. Does matter for non-raster formats like Flash. Not all formats support all combinations. For
instance GD supports only PC256. (optional)
• PC256: Produced a pseudocolored result with up to 256 colors in the palette (legacy MapServer mode).
Only supported for GD/GIF and GD/PNG.
• RGB: Render in 24bit Red/Green/Blue mode. Supports all colors but does not support transparency.
• RGBA: Render in 32bit Red/Green/Blue/Alpha mode. Supports all colors, and alpha based transparency.
All features are rendered against an initially transparent background.
• BYTE: Render raw 8bit pixel values (no presentation). Only works for RASTER layers (through GDAL)
and WMS layers currently.
• INT16: Render raw 16bit signed pixel values (no presentation). Only works for RASTER layers (through
GDAL) and WMS layers currently.
• FLOAT32: Render raw 32bit floating point pixel values (no presentation). Only works for RASTER layers
(through GDAL) and WMS layers currently.
• FEATURE: Output is a non-image result, such as features written via templates or OGR.
MIMETYPE [type] Provide the mime type to be used when returning results over the web. (optional)
NAME [name] The name to use in the IMAGETYPE keyword of the map file to select this output format. This name
is also used in metadata describing wxs formats allowed, and can be used (sometimes along with mimetype) to
select the output format via keywords in OGC requests. (optional)
TRANSPARENT [on|off] Indicates whether transparency should be enabled for this format. Note that transparency
does not work for IMAGEMODE RGB output. Not all formats support transparency (optional). When transparency is enabled for the typical case of 8-bit pseudocolored map generation, the IMAGECOLOR color will be
marked as transparent in the output file palette. Any other map components drawn in this color will also be transparent, so for map generation with transparency it is best to use an otherwise unused color as the background
color.
4.1.19 PROJECTION
Background
There are thousands of geographical reference systems. In order to combine datasets with different geographical
reference systems into a map, the datasets will have to be transformed (projected) to the chosen geographical reference
system of the map. If you want to know more about geographical reference systems and map projections in general,
please see the More Information links below, or look into Geomatics courses (Geographical Information Systems,
Cartography, Geodesy), as projections are an advanced topic for beginners.
Projections with MapServer
To set up projections you must define one projection object for the output image (in the MAP object) and one projection
object for each layer (in the LAYER objects) to be projected. MapServer relies on the PROJ.4 library for projections.
Projection objects therefore consist of a series of PROJ.4 keywords, which are either specified within the object directly
or referred to in an EPSG file. An EPSG file is a lookup file containing projection parameters, and is part of the PROJ.4
library.
The following two examples both define the same projection (UTM zone 15, NAD83), but use 2 different methods:
Example 1: Inline Projection Parameters
4.1. Mapfile
213
MapServer Documentation, Release 7.0.6
PROJECTION
"proj=utm"
"ellps=GRS80"
"datum=NAD83"
"zone=15"
"units=m"
"north"
"no_defs"
END
Note: For a list of all of the possible PROJ.4 projection parameters, see the PROJ.4 parameters page.
Example 2: EPSG Projection Use
PROJECTION
"init=epsg:26915"
END
Note: This refers to an EPSG lookup file that contains a ‘26915’ code with the full projection parameters. “epsg” in
this instance is case-sensitive because it is referring to a file name. If your file system is case-sensitive, this must be
lower case, or MapServer (PROJ.4 actually) will complain about not being able to find this file.
Note: See http://spatialreference.org/ref/epsg/26915/ for more information on this coordinate system.
The next two examples both display how to possibly define unprojected lat/long (“geographic”):
Example 3: Inline Projection Parameters
PROJECTION
"proj=latlong"
"ellps=WGS84"
"datum=WGS84"
END
Example 4: epsg Projection Use
PROJECTION
"init=epsg:4326"
END
“Web Mercator” or “Google Mercator”
The EPSG code for the commonly used “Web” or “Google” mercator projection is ‘3857’. See http://spatialreference.
org/ref/sr-org/7483/ for more information on this coordinate system. This code was also unofficially referred to as
EPSG:900913; you are recommended to use the official EPSG:3857 code instead, such as:
PROJECTION
"init=epsg:3857"
END
4.1. Mapfile
214
MapServer Documentation, Release 7.0.6
PROJECTION AUTO
The following syntax may be used in LAYERs that are OGR connections, shapefile layers or raster layers :
PROJECTION
AUTO
END
• In case of a OGR connection, the projection will be retrieved from the OGR layer.
• In case of a shapefile layer, the projection will be retrieved from the associated .prj file.
• In case of raster layers refereing to single raster (DATA keyword), the projection will be retrieved from the
GDAL datasource. If the raster layer refers to a tile index (OGR layer or shapefile tileindex), the projection will
be retrieved according to the above describe rules.
Note: For other layer types, this syntax is invalid.
Specifying which EPSG files to use
MAP CONFIG can be used to specify the location of EPSG files:
MAP
CONFIG "PROJ_LIB" "/usr/share/proj/"
PROJECTION
"init=epsg:3857"
END # PROJECTION
...
It is important that CONFIG “PROJ_LIB” line comes before the PROJECTION block.
Important Notes
• If all of your data in the mapfile is in the same projection, you DO NOT have to specify any projection objects.
MapServer will assume that all of the data is in the same projection.
• Think of the MAP-level projection object as your output projection. The EXTENT and UNITS values at the
MAP-level must be in the output projection units. Also, if you have layers in other projections (other than the
MAP-level projection) then you must define PROJECTION objects for those layers, to tell MapServer what
projections they are in.
• If you specify a MAP-level projection, and then only one other LAYER projection object, MapServer will assume
that all of the other layers are in the specified MAP-level projection.
• Always refer to the EPSG file in lowercase, because it is a lowercase filename and on Linux/Unix systems this
parameter is case sensitive.
For More Information
• If you get projection errors, refer to the Errors to check if your exact error has been discussed.
• Search the MapServer-users email list archives, odds are that someone has faced your exact issue before.
• See the PROJ.4 user guides for complete descriptions of supported projections and coordinate systems.
4.1. Mapfile
215
MapServer Documentation, Release 7.0.6
• Refer to the Cartographical Map Projections page for background information on projections.
• A respected author on map projections is John P. Snyder, if you are wishing for printed material to review.
4.1.20 QUERYMAP
COLOR [r] [g] [b] | [hexadecimal string] Color in which features are highlighted. Default is yellow.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
COLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
COLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
COLOR "#FF00FFCC"
SIZE [x][y] Size of the map in pixels. Defaults to the size defined in the map object.
STATUS [on|off] Is the query map to be drawn?
STYLE [normal|hilite|selected] Sets how selected features are to be handled. Layers not queried are drawn as usual.
• Normal: Draws all features according to the settings for that layer.
• Hilite: Draws selected features using COLOR. Non-selected features are drawn normally.
• Selected: draws only the selected features normally.
4.1.21 REFERENCE
Three types of reference maps are supported. The most common would be one showing the extent of a map in an
interactive interface. It is also possible to request reference maps as part of a query. Point queries will generate an
image with a marker (see below) placed at the query point. Region based queries will depict the extent of the area of
interest. Finally, feature based queries will display the selection feature(s) used.
COLOR [r] [g] [b] | [hexadecimal string] Color in which the reference box is drawn. Set any component to -1 for
no fill. Default is red.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
COLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
COLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
4.1. Mapfile
216
MapServer Documentation, Release 7.0.6
COLOR "#FF00FFCC"
EXTENT [minx][miny][maxx][maxy] The spatial extent of the base reference image.
IMAGE [filename] Full filename of the base reference image. Must be a GIF image.
MARKER [integer|string] Defines a symbol (from the symbol file) to use when the box becomes too small (see
MINBOXSIZE and MAXBOXSIZE below). Uses a crosshair by default.
MARKERSIZE [integer] Defines the size of the symbol to use instead of a box (see MARKER above).
MINBOXSIZE [integer] If box is smaller than MINBOXSIZE (use box width or height) then use the symbol defined
by MARKER and MARKERSIZE.
MAXBOXSIZE [integer] If box is greater than MAXBOXSIZE (use box width or height) then draw nothing (Often
the whole map gets covered when zoomed way out and it’s perfectly obvious where you are).
OUTLINECOLOR [r] [g] [b] | [hexadecimal string] Color to use for outlining the reference box. Set any component to -1 for no outline.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
OUTLINECOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
OUTLINECOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
OUTLINECOLOR "#FF00FFCC"
SIZE [x][y] Size, in pixels, of the base reference image.
STATUS [on|off] Is the reference map to be created? Default it off.
4.1.22 SCALEBAR
Scalebars currently do not make use of TrueType fonts. The size of the scalebar image is NOT known prior to
rendering, so be careful not to hard-code width and height in the <IMG> tag in the template file. Future versions will
make the image size available.
ALIGN [left|center|right] Defines how the scalebar is aligned within the scalebar image. Default is center. Available
in versions 5.2 and higher.
New in version 5.2.
BACKGROUNDCOLOR [r] [g] [b] | [hexadecimal string] Color to use for scalebar background, not the image
background.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
BACKGROUNDCOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
4.1. Mapfile
217
MapServer Documentation, Release 7.0.6
BACKGROUNDCOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
BACKGROUNDCOLOR "#FF00FFCC"
COLOR [r] [g] [b] | [hexadecimal string] Color to use for drawing all features if attribute tables are not used.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
COLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
COLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
COLOR "#FF00FFCC"
IMAGECOLOR [r] [g] [b] | [hexadecimal string] Color to initialize the scalebar with (i.e. background).
• r, g and b shall be integers [0..255]. To specify green, the following is used:
IMAGECOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
IMAGECOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
IMAGECOLOR "#FF00FFCC"
INTERLACE [true|false] Should output images be interlaced? Default is [on]. This keyword is now deprecated in
favour of using the FORMATOPTION “INTERLACE=ON” line in the OUTPUTFORMAT declaration.
Deprecated since version 4.6.
INTERVALS [integer] Number of intervals to break the scalebar into. Default is 4.
LABEL Signals the start of a LABEL object.
OUTLINECOLOR [r] [g] [b] | [hexadecimal string] Color to use for outlining individual intervals. Set any component to -1 for no outline which is the default.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
OUTLINECOLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
4.1. Mapfile
218
MapServer Documentation, Release 7.0.6
OUTLINECOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
OUTLINECOLOR "#FF00FFCC"
POSITION [ul|uc|ur|ll|lc|lr] Where to place an embedded scalebar in the image. Default is lr.
POSTLABELCACHE [true|false] For use with embedded scalebars only. Tells the MapServer to embed the scalebar after all labels in the cache have been drawn. Default is false.
SIZE [x][y] Size in pixels of the scalebar. Labeling is not taken into account.
STATUS [on|off|embed] Is the scalebar image to be created, and if so should it be embedded into the image? Default
is off. (Please note that embedding scalebars require that you define a markerset. In essence the scalebar
becomes a custom marker that is handled just like any other annotation.)
STYLE [integer] Chooses the scalebar style. Valid styles are 0 and 1.
TRANSPARENT [on|off] Should the background color for the scalebar be transparent. This flag is now deprecated
in favor of declaring transparency within OUTPUTFORMAT declarations. Default is off.
Deprecated since version 4.6.
UNITS [feet|inches|kilometers|meters|miles|nauticalmiles] Output scalebar units, default is miles. Used in conjunction with the map’s units to develop the actual graphic. Note that decimal degrees are not valid scalebar
units. Nauticalmiles was added in MapServer 5.6.
4.1.23 STYLE
Style holds parameters for symbolization and styling. Multiple styles may be applied within a CLASS or LABEL.
This object appeared in 4.0 and the intention is to separate logic from looks. The final intent is to have named styles
(Not yet supported) that will be re-usable through the mapfile. This is the way of defining the appearance of an object
(a CLASS or a LABEL).
ANGLE [double|attribute|AUTO] Angle, given in degrees, to rotate the symbol (counter clockwise). Default is 0
(no rotation). If you have an attribute that specifies angles in a clockwise direction (compass direction), you
have to adjust the angle attribute values before they reach MapServer (360-ANGLE), as it is not possible to use
a mathematical expression for ANGLE.
• For points, it specifies the rotation of the symbol around its center.
• For decorated lines, the behaviour depends on the value of the GAP element.
– For negative GAP values it specifies the rotation of the decoration symbol relative to the direction of
the line. An angle of 0 means that the symbol’s x-axis is oriented along the direction of the line.
– For non-negativ (or absent) GAP values it specifies the rotation of the decoration symbol around its
center. An angle of 0 means that the symbol is not rotated.
• For polygons, it specifies the angle of the lines in a HATCH symbol (0 - horizontal lines), or it specifies
the rotation of the symbol used to generate the pattern in a polygon fill (it does not specify the rotation of
the fill as a whole). For its use with hatched lines, see Example #7 in the symbology examples.
• [attribute] was introduced in version 5.0, to specify the attribute to use for angle values. The hard brackets
[] are required. For example, if your data source has an attribute named “MYROTATE” that holds angle
values for each feature, your STYLE object for hatched lines might contain:
4.1. Mapfile
219
MapServer Documentation, Release 7.0.6
STYLE
SYMBOL 'hatch-test'
COLOR 255 0 0
ANGLE [MYROTATE]
SIZE 4.0
WIDTH 3.0
END
The associated RFC document for this feature is RFC19.
• The AUTO keyword was added in version 5.4, and currently only applies when coupled with the GEOMTRANSFORM keyword.
Note: Rotation using ANGLE is not supported for SYMBOLs of TYPE ellipse with the GD renderer (gif).
ANGLEITEM [string] ANGLE[attribute] must now be used instead.
Deprecated since version 5.0.
ANTIALIAS [true|false] Should TrueType fonts be antialiased. Only useful for GD (gif) rendering. Default is false.
Has no effect for the other renderers (where anti-aliasing can not be turned off).
BACKGROUNDCOLOR [r] [g] [b] | [hexadecimal string] - deprecated Color to use for non-transparent symbols.
Note: Multiple STYLEs can be used instead:
STYLE
BACKGROUNDCOLOR 0 0 0
SYMBOL "foo"
COLOR 255 0 0
END
can be replaced with:
STYLE
COLOR 0 0 0
END
STYLE
SYMBOL "foo"
COLOR 255 0 0
END
Deprecated since version 6.2.
COLOR [r] [g] [b] | [hexadecimal string] | [attribute] Color to use for drawing features.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
COLOR 0 255 0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
COLOR "#FF00FF"
4.1. Mapfile
220
MapServer Documentation, Release 7.0.6
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
COLOR "#FF00FFCC"
• [attribute] was introduced in version 5.0, to specify the attribute to use for color values. The hard brackets
[] are required. For example, if your data set has an attribute named “MYPAINT” that holds color values
for each record, use: object for might contain:
COLOR [MYPAINT]
If COLOR is not specified, and it is not a SYMBOL of TYPE pixmap, then the symbol will not be rendered.
The associated RFC document for this feature is RFC19.
GAP [double] GAP specifies the distance between SYMBOLs (center to center) for decorated lines and polygon fills
in layer SIZEUNITS. For polygon fills, GAP specifies the distance between SYMBOLs in both the X and the Y
direction. For lines, the centers of the SYMBOLs are placed on the line. As of MapServer 5.0 this also applies
to PixMap symbols.
When scaling of symbols is in effect (SYMBOLSCALEDENOM is specified for the LAYER), GAP specifies the
distance in layer SIZEUNITS at the map scale 1:SYMBOLSCALEDENOM.
• For lines, if INITIALGAP is not specified, the first symbol will be placed GAP/2 from the start of the line.
• For lines, a negative GAP value will cause the symbols’ X axis to be aligned relative to the tangent of the
line.
• For lines, a positive GAP value aligns the symbols’ X axis relative to the X axis of the output device.
• For lines, a GAP of 0 (the default value) will cause the symbols to be rendered edge to edge
• For polygons, a missing GAP or a GAP of less than or equal to the size of the symbol will cause the
symbols to be rendered edge to edge.
Symbols can be rotated using ANGLE.
New in version 6.0: moved from SYMBOL
Note: The behaviour of GAP has not been stable over time. It has specified the amount of space between
the symbols, and also something in between the amount of space between the symbols and the center to center
distance. Since 6.2 GAP specifies the center to center distance between the symbols.
GEOMTRANSFORM [bbox|centroid|end|labelpnt|labelpoly|start|vertices|<expression>] Used to indicate that
the current feature will be transformed before the actual style is applied. Introduced in version 5.4.
• bbox: produces the bounding box of the current feature geometry.
• centroid: produces the centroid of the current feature geometry.
• end: produces the last point of the current feature geometry. When used with ANGLE AUTO, it can for
instance be used to render arrowheads on line segments.
• labelpnt: used for LABEL styles. Draws a marker on the geographic position the label is attached to. This
corresponds to the center of the label text only if the label is in position CC.
• labelpoly: used for LABEL styles. Produces a polygon that covers the label plus a 1 pixel padding.
• start: produces the first point of the current feature geometry. When used with ANGLE AUTO, it can for
instance be used to render arrow tails on line segments.
4.1. Mapfile
221
MapServer Documentation, Release 7.0.6
• vertices: produces all the intermediate vertices (points) of the current feature geometry (the start and end
are excluded). When used with ANGLE AUTO, the marker is oriented by the half angle formed by the two
adjacent line segments.
• <expression>: Applies the given expression to the geometry. Supported expressions:
– (buffer([shape],dist)): Buffer the geometry ([shape]) using dist pixels as buffer distance. For polygons, a negative dist will produce a setback.
– (generalize([shape],tolerance)): simplifies a geometry ([shape]) in way comparable to FME’s
ThinNoPoint algorithm. See http://trac.osgeo.org/gdal/ticket/966 for more information.
Note: Depends on GEOS.
– (simplify([shape],tolerance)): simplifies a geometry ([shape]) using the standard Douglas-Peucker
algorithm.
– (simplifypt([shape],tolerance)): simplifies a geometry ([shape]), ensuring that the result is a valid
geometry having the same dimension and number of components as the input. tolerance must be
non-negative.
– (smoothsia([shape], smoothing_size, smoothing_iteration, preprocessing)): will smooth a geometry
([shape]) using the SIA algorithm
Example (polygon data set) - draw a two pixel wide line 5 pixels inside the boundary of the polygon:
STYLE
OUTLINECOLOR 255 0 0
WIDTH 2
GEOMTRANSFORM (buffer([shape],-5))
END
There is a difference between STYLE and LAYER GEOMTRANSFORM. LAYER-level will receive ground
coordinates (meters, degrees, etc) and STYLE-level will receive pixel coordinates. The argument to methods
such as simplify() must be in the same units as the coordinates of the shapes at that point of the rendering
workflow, i.e. pixels at the STYLE-level and in ground units at the LAYER-level.
LAYER NAME "my_layer"
TYPE LINE
STATUS DEFAULT
DATA "lines.shp"
GEOMTRANSFORM (simplify([shape], 10)) ## 10 ground units
CLASS
STYLE
GEOMTRANSFORM (buffer([shape], 5) ## 5 pixels
WIDTH 2
COLOR 255 0 0
END
END
END
See also:
GEOMTRANSFORM - Geometry Transformations
INITIALGAP [double] INITIALGAP is useful for styling dashed lines.
If used with GAP, INITIALGAP specifies the distance to the first symbol on a styled line.
If used with PATTERN, INITIALGAP specifies the distance to the first dash on a dashed line.
4.1. Mapfile
222
MapServer Documentation, Release 7.0.6
Example 1 - dashed line styled with circles:
STYLE
COLOR 0 0 0
WIDTH 4
PATTERN 40 10 END
END
STYLE
SYMBOL "circlef"
COLOR 0 0 0
SIZE 8
INITIALGAP 20
GAP 50
END
Example 1 - dashed line styled with dashed line overlay:
STYLE
COLOR 0 0 0
WIDTH 6
PATTERN 40 10 END
END
STYLE
COLOR 255 255 255
WIDTH 4
INITIALGAP 2
PATTERN 36 14 END
END
New in version 6.2.
LINECAP [butt|round|square] Sets the line cap type for lines. Default is round. See Cartographical Symbol Construction with MapServer for explanation and examples.
New in version 6.0: moved from SYMBOL
LINEJOIN [round|miter|bevel|none] Sets the line join type for lines. Default is round. See Cartographical Symbol
Construction with MapServer for explanation and examples.
New in version 6.0: moved from SYMBOL
LINEJOINMAXSIZE [int] Sets the max length of the miter LINEJOIN type. The value represents a coefficient
which multiplies a current symbol size. Default is 3. See Cartographical Symbol Construction with MapServer
for explanation and examples.
New in version 6.0: moved from SYMBOL
MAXSCALEDENOM [double] Minimum scale at which this STYLE is drawn. Scale is given as the denominator of
the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000.
New in version 5.4.
See also:
Map Scale
MAXSIZE [double] Maximum size in pixels to draw a symbol. Default is 500. Starting from version 5.4, the value
can also be a decimal value (and not only integer). See LAYER SYMBOLSCALEDENOM.
MAXWIDTH [double] Maximum width in pixels to draw the line work. Default is 32. Starting from version 5.4,
the value can also be a decimal value (and not only integer). See LAYER SYMBOLSCALEDENOM.
4.1. Mapfile
223
MapServer Documentation, Release 7.0.6
MINSCALEDENOM [double] Maximum scale at which this STYLE is drawn. Scale is given as the denominator of
the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000.
New in version 5.4.
See also:
Map Scale
MINSIZE [double] Minimum size in pixels to draw a symbol. Default is 0. Starting from version 5.4, the value can
also be a decimal value (and not only integer). See LAYER SYMBOLSCALEDENOM.
MINWIDTH [double] Minimum width in pixels to draw the line work. Default is 0. Starting from version 5.4, the
value can also be a decimal value (and not only integer). See LAYER SYMBOLSCALEDENOM.
OFFSET [x][y] Geometry offset values in layer SIZEUNITS. In the general case, SIZEUNITS will be pixels.
When scaling of symbols is in effect (SYMBOLSCALEDENOM is specified for the LAYER), OFFSET gives
offset values in layer SIZEUNITS at the map scale 1:SYMBOLSCALEDENOM.
An OFFSET of 20 40 will shift the geometry 20 SIZEUNITS to the left and 40 SIZEUNITS down before rendering.
For lines, an OFFSET of y = -99 will produce a line geometry that is shifted x SIZEUNITS perpendicular to
the original line geometry. A positive x shifts the line to the right when seen along the direction of the line. A
negative x shifts the line to the left when seen along the direction of the line.
For lines, an OFFSET of y = -999 (added in version 6.4) will produce a multiline geometry corresponding to
the borders of a line that is x SIZEUNITS wide. This can be used to render only the outlines of a thick line.
OPACITY [integer|attribute] Opacity to draw the current style (applies to 5.2+, AGG Rendering Specifics only, does
not apply to pixmap symbols)
• [attribute] was introduced in version 5.6, to specify the attribute to use for opacity values.
OUTLINECOLOR [r] [g] [b] | [hexadecimal string] | [attribute] Color to use for outlining polygons and certain
marker symbols (ellipse, vector polygons and truetype). Has no effect for lines. The width of the outline can be
specified using WIDTH. If no WIDTH is specified, an outline of one pixel will be drawn.
If there is a SYMBOL defined for the STYLE, the OUTLINECOLOR will be used to create an outline for that
SYMBOL (only ellipse, truetype and polygon vector symbols will get an outline). If there is no SYMBOL defined
for the STYLE, the polygon will get an outline.
• r, g and b shall be integers [0..255]. To specify green, the following is used:
OUTLINECOLOR 0 255 0
WIDTH 3.0
• hexadecimal string can be
– RGB value: “#rrggbb”. To specify magenta, the following is used:
OUTLINECOLOR "#FF00FF"
– RGBA value (adding translucence): “#rrggbbaa”. To specify a semi-translucent magenta, the following is used:
OUTLINECOLOR "#FF00FFCC"
• [attribute] was introduced in version 5.0, to specify the attribute to use for color values. The hard brackets
[] are required. For example, if your data set has an attribute named “MYPAINT” that holds color values
for each record, use: object for might contain:
4.1. Mapfile
224
MapServer Documentation, Release 7.0.6
OUTLINECOLOR [MYPAINT]
The associated RFC document for this feature is RFC19.
OUTLINEWIDTH [double|attribute] Width in pixels for the outline. Default is 0.0. The thickness of the outline
will not depend on the scale.
New in version 5.4.
PATTERN [double on] [double off] [double on] [double off] ... END Used to define a dash pattern for line work
(lines, polygon outlines, hatch lines, ...). The numbers (doubles) specify the lengths of the dashes and gaps
of the dash pattern in layer SIZEUNITS. When scaling of symbols is in effect (SYMBOLSCALEDENOM is
specified for the LAYER), the numbers specify the lengths of the dashes and gaps in layer SIZEUNITS at the
map scale 1:SYMBOLSCALEDENOM.
LINECAP, LINEJOIN and LINEJOINMAXSIZE can be used to control the appearance of the dashed lines.
To specify a dashed line that is 5 units wide, with dash lengths of 5 units and gaps of 5 units, the following style
can be used:
STYLE
COLOR 0 0 0
WIDTH 5.0
LINECAP BUTT
PATTERN 5.0 5.0 END
END
Since version 6.2, PATTERN can be used to create dashed lines for SYMBOLs of TYPE hatch. Patterns for
hatches are always drawn with LINECAP butt. The patterns are generated relative to the edges of the bounding
box of the polygon (an illustrated example can be found in the hatch fill section of the symbol construction
document).
New in version 6.0: moved from SYMBOL
POLAROFFSET [double|attribute] [double|attribute] Offset given in polar coordinates.
The first parameter is a double value in layer SIZEUNITS (or the name of a layer attribute) that specifies the
radius/distance.
The second parameter is a double value (or the name of a layer attribute) that specifies the angle (counter
clockwise).
When scaling of symbols is in effect (SYMBOLSCALEDENOM is specified for the LAYER), POLAROFFSET
gives the distance in layer SIZEUNITS at the map scale 1:SYMBOLSCALEDENOM.
A POLAROFFSET of 20 40 will shift the geometry to a position that is 20 SIZEUNITS away along a line that is
at an angle of 40 degrees with a line that goes horizontally to the right.
When POLAROFFSET is used with layers that have CONNECTIONTYPE uvraster (vector field), the special
attributes uv_length, uv_length_2, uv_angle and uv_minus_angle are available, making it convenient to specify
arrow heads and tails. Example:
LAYER
...
TYPE POINT
CONNECTIONTYPE uvraster
...
CLASS
STYLE
SYMBOL "arrowbody"
ANGLE [uv_angle]
4.1. Mapfile
225
MapServer Documentation, Release 7.0.6
SIZE [uv_length]
WIDTH 3
COLOR 100 255 0
END
STYLE
SYMBOL "arrowhead"
ANGLE [uv_angle]
SIZE 10
COLOR 255 0 0
POLAROFFSET [uv_length_2] [uv_angle]
END
STYLE
SYMBOL "arrowtail"
ANGLE [uv_angle]
SIZE 10
COLOR 255 0 0
POLAROFFSET [uv_length_2] [uv_minus_angle]
END
END #class
END #layer
New in version 6.2: (rfc78)
SIZE [double|attribute] Height, in layer SIZEUNITS, of the symbol/pattern to be used. Default value depends on
the SYMBOL TYPE. For pixmap: the height (in pixels) of the pixmap; for ellipse and vector: the maximum y
value of the SYMBOL POINTS parameter, for hatch: 1.0, for truetype: 1.0.
When scaling of symbols is in effect (SYMBOLSCALEDENOM is specified for the LAYER), SIZE gives the
height, in layer SIZEUNITS, of the symbol/pattern to be used at the map scale 1:SYMBOLSCALEDENOM.
• For symbols of TYPE hatch, the SIZE is the center to center distance between the lines. For its use with
hatched lines, see Example#8 in the symbology examples.
• [attribute] was introduced in version 5.0, to specify the attribute to use for size values. The hard brackets
[] are required. For example, if your data set has an attribute named “MYHEIGHT” that holds size values
for each feature, your STYLE object for hatched lines might contain:
STYLE
SYMBOL 'hatch-test'
COLOR 255 0 0
ANGLE 45
SIZE [MYHEIGHT]
WIDTH 3.0
END
The associated RFC document for this feature is RFC19.
• Starting from version 5.4, the value can also be a decimal value (and not only integer).
SYMBOL [integer|string|filename|url|attribute] The symbol to use for rendering the features.
• Integer is the index of the symbol in the symbol set, starting at 1 (the 5th symbol is symbol number 5).
• String is the name of the symbol (as defined using the SYMBOL NAME parameter).
• Filename specifies the path to a file containing a symbol. For example a PNG file. Specify the path relative
to the directory containing the mapfile.
• URL specifies the address of a file containing a pixmap symbol. For example a PNG file. A URL must
start with “http”:
4.1. Mapfile
226
MapServer Documentation, Release 7.0.6
SYMBOL "http://myserver.org/path/to/file.png"
New in version 6.0.
• [attribute] allows individual rendering of features by using an attribute in the dataset that specifies the
symbol name (as defined in the SYMBOL NAME parameter). The hard brackets [] are required.
New in version 5.6.
If SYMBOL is not specified, the behaviour depends on the type of feature.
• For points, nothing will be rendered.
• For lines, SYMBOL is only relevant if you want to style the lines using symbols, so the absence of SYMBOL
means that you will get lines as specified using the relevant line rendering parameters (COLOR, WIDTH,
PATTERN, LINECAP, ...).
• For polygons, the interior of the polygons will be rendered using a solid fill of the color specified in the
COLOR parameter.
See also:
SYMBOL
WIDTH [double|attribute] WIDTH refers to the thickness of line work drawn, in layer SIZEUNITS. Default is 1.0.
When scaling of symbols is in effect (SYMBOLSCALEDENOM is specified for the LAYER), WIDTH refers to
the thickness of the line work in layer SIZEUNITS at the map scale 1:SYMBOLSCALEDENOM.
• If used with SYMBOL and OUTLINECOLOR, WIDTH specifies the width of the symbol outlines. This
applies to SYMBOL TYPE vector (polygons), ellipse and truetype.
• For lines, WIDTH specifies the width of the line.
• For polygons, if used with OUTLINECOLOR, WIDTH specifies the thickness of the polygon outline.
• For a symbol of SYMBOL TYPE hatch, WIDTH specifies the thickness of the hatched lines. For its use
with hatched lines, see Example #7 in the symbology examples.
• [attribute] was added in version 5.4 to specify the attribute to use for the width value. The hard brackets []
are required.
• Starting from version 5.4, the value can also be a decimal value (and not only integer).
4.1.24 STYLEITEM Javascript
Author Charles-ÃL’ric Bourget
Contact cbourget at mapgears.com
Author Alan Boudreault
Contact aboudreault at mapgears.com
Last Updated 2015-05-21
Table of Contents
• STYLEITEM Javascript
– Introduction
4.1. Mapfile
227
MapServer Documentation, Release 7.0.6
– Usage
– Example 1. Single STYLE definition
– Example 2. CLASS with multiple STYLE definitions
– Example 3. Printing logs in MapServer logs
Introduction
Using STYLEITEM this way makes it possible to style features programmatically rather than with the standard
MapServer expressions.
Usage
Simply declare the javascript plugin this way:
MAP
...
LAYER
...
STYLEITEM "javascript://myscript.js" # relative path
CLASS
END
END
END
The path can also be absolute.
MAP
...
LAYER
...
STYLEITEM "javascript:///home/user/myscript.js" # absolute path
CLASS
END
END
END
The javascript plugin has to implement a function named styleitem that will be automatically called. This function
has to return one of these two options:
• a STYLE definition (Plain String)
• a CLASS definition with one or multiple styles (Plain String)
Note: Features are parsed one at a time and each one makes a call to the javascript plugin. That means the STYLE or
CLASS returned is applied to that specific feature only. Therefore, a CLASS block should not contain an EXPRESSION definition and the corresponding LAYER should not contain a CLASSITEM definition.
Note: Declaring an empty CLASS is mandatory
Access to the feature attributes is made through the shape.attributes javascript object.
4.1. Mapfile
228
MapServer Documentation, Release 7.0.6
The following javascript functions are available:
• alert(str1, str2, ..., str) print some text in MapServer logs
• print(str1, str2, ..., str) print some text in MapServer logs
• require(path_to_lib1, path_to_lib2, ..., path_to_lib) include one or more javascript lib
Example 1. Single STYLE definition
This example returns a single STYLE definition ...
function styleitem() {
//Make symbol size 14 or 7
var size = shape.attributes.NAME.length > 10 ? 14:7;
var style = "STYLE SIZE " + size + " SYMBOL 'circle'";
var red = Math.random()*255;
var green = Math.random()*255;
var blue = Math.random()*255;
style += "COLOR " + red + " " + green + " " + blue + " END";
//Return style to MapServer
return style;
}
Example 2. CLASS with multiple STYLE definitions
This example returns a single CLASS with multiple STYLE definitions ...
function styleitem() {
var cls = "CLASS";
//Make symbol size 14 or 7
var size = shape.attributes.NAME.length > 10 ? 14:7;
var style1 = "STYLE SIZE " + size + " SYMBOL 'circle'";
var style2 = "STYLE SIZE " + size + " SYMBOL 'cross'";
var red = Math.random()*255;
var green = Math.random()*255;
var blue = Math.random()*255;
style1 += "COLOR " + red + " " + green + " " + blue + " END";
style2 += "COLOR " + red + " " + green + " " + blue + " END";
cls += " " + style1 + " " + style2 + " END";
//Return class to MapServer
return cls;
}
Example 3. Printing logs in MapServer logs
This example prints some javascript logs in MapServer logs.
4.1. Mapfile
229
MapServer Documentation, Release 7.0.6
MAP
...
CONFIG "MS_ERRORFILE" "/tmp/mapserver.log"
DEBUG 1
LAYER
...
STYLEITEM "javascript://myscript.js"
CLASS
END
END
END
function styleitem() {
//Print some logs in MapServer logs
alert("Processing feature " + shape.attributes.NAME)
//Make symbol size 14 or 7
var size = shape.attributes.NAME.length > 10 ? 14:7;
var style = "STYLE SIZE " + size + " SYMBOL 'circle'";
var red = Math.random()*255;
var green = Math.random()*255;
var blue = Math.random()*255;
style += "COLOR " + red + " " + green + " " + blue + " END";
//Return style to MapServer
return style;
}
4.1.25 SYMBOL
• Symbol definitions can be included within the main map file or, more commonly, in a separate file. Symbol
definitions in a separate file are designated using the SYMBOLSET keyword, as part of the MAP object. This
recommended setup is ideal for re-using symbol definitions across multiple MapServer applications.
• There are 3 main types of symbols in MapServer: Markers, Lines and Shadesets.
• Symbol 0 is always the degenerate case for a particular class of symbol. For points, symbol 0 is a single pixel,
for shading (i.e. filled polygons) symbol 0 is a solid fill, and for lines, symbol 0 is a single pixel wide line.
• Symbol definitions contain no color information, colors are set within STYLE objects.
• Line styling was moved to CLASS STYLE in MapServer version 5. The mechanisms are no longer available in
SYMBOL.
• For MapServer versions < 5 there is a maximum of 64 symbols per file. This can be changed by editing
mapsymbol.h and changing the value of MS_MAXSYMBOLS at the top of the file. As of MapServer 5.0 there
is no symbol limit.
• More information can be found in the Construction of Cartographic Symbols document.
ANCHORPOINT [x] [y] Used to specify the location (within the symbol) that is to be used as an anchorpoint when
rotating the symbol and placing the symbol on a map. Default is 0.5 0.5 (corresponding to the center of the
symbol).
x: A double in the range [0,1] that specifies the location within the symbol along the x axis. 0
specifies the left edge of the symbol, 1 specifies the right edge of the symbol. 0.5 specifies the center
4.1. Mapfile
230
MapServer Documentation, Release 7.0.6
of the symbol (in the x direction).
y: A double in the range [0,1] that specifies the location within the symbol along the y axis. 0
specifies the top edge of the symbol, 1 specifies the lower edge of the symbol. 0.5 specifies the center
of the symbol (in the y direction).
ANCHORPOINT can be used with SYMBOLs of TYPE ellipse, pixmap, svg, truetype and vector. To ensure
proper behaviour for vector symbols, the left and top edges of the bounding box of the symbol should be at 0.
New in version 6.2.
ANTIALIAS [true|false] Should TrueType fonts be antialiased. Only useful for GD (gif) rendering. Default is false.
Has no effect for the other renderers (where anti-aliasing can not be turned off).
CHARACTER [char] Character used to reference a particular TrueType font character. You’ll need to figure out the
mapping from the keyboard character to font character.
FILLED [true|false] If true, the symbol will be filled with a user defined color (using STYLE COLOR). Default is
false.
If true, symbols of TYPE ellipse and vector will be treated as polygons (fill color specified using STYLE COLOR
and outline specified using STYLE OUTLINECOLOR and WIDTH).
If false, symbols of TYPE ellipse and vector will be treated as lines (the lines can be given a color using STYLE
COLOR and a width using STYLE WIDTH).
FONT [string] Name of TrueType font to use as defined in the FONTSET.
IMAGE [string] Image (GIF or PNG) to use as a marker or brush for type pixmap symbols.
NAME [string] Alias for the symbol. To be used in CLASS STYLE objects.
POINTS [x y] [x y] ... END
Signifies the start of a sequence of points that make up a symbol of TYPE vector or that define the x and y
radius of a symbol of TYPE ellipse. The end of this section is signified with the keyword END. The x and
y values can be given using decimal numbers. The maximum x and y values define the bounding box of
the symbol. The size (actually height) of a symbol is defined in the STYLE. You can create non-contiguous
paths by inserting “-99 -99” at the appropriate places.
x values increase to the right, y values increase downwards.
For symbols of TYPE ellipse, a single point is specified that defines the x and y radius of the ellipse.
Circles are created when x and y are equal.
Note: If a STYLE using this symbol doesn’t contain an explicit size, then the default symbol size will
be based on the range of “y” values in the point coordinates. e.g. if the y coordinates of the points in the
symbol range from 0 to 5, then the default size for this symbol will be assumed to be 5.
TRANSPARENT [color index] Sets a transparent color for the input image for pixmap symbols, or determines
whether all shade symbols should have a transparent background. For shade symbols it may be desirable to
have background features “show through” a transparent hatching pattern, creating a more complex map. By
default a symbol’s background is the same as the parent image (i.e. color 0). This is user configurable.
Note: The default (AGG) renderer does not support the TRANSPARENT parameter. It is supported by the GD
renderer (GIF).
TYPE [ellipse|hatch|pixmap|svg|truetype|vector]
• ellipse: radius values in the x and y directions define an ellipse.
4.1. Mapfile
231
MapServer Documentation, Release 7.0.6
• hatch: produces hatched lines throughout the (polygon) shape.
• pixmap: a user supplied image will be used as the symbol.
• svg: scalable vector graphics (SVG) symbol. Requires the libsvg/libsvg-cairo libraries (or alternatively the
librsvg library).
• truetype: TrueType font to use as defined in the MAP FONTSET.
• vector: a vector drawing is used to define the shape of the symbol.
Note: TYPE cartoline is no longer used. Dashed lines are specified using PATTERN, LINECAP, LINEJOIN
and LINEJOINMAXSIZE in STYLE. Examples in Construction of Cartographic Symbols.
4.1.26 Symbology Examples
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Author HÃěvard Tveite
Contact havard.tveite at nmbu.no
Last Updated 2011/05/11
Table of Contents
• Symbology Examples
– Example 1. Dashed Line
– Example 2. TrueType font marker symbol
– Example 3. Vector triangle marker symbol
– Example 4. Non-contiguous vector marker symbol (Cross)
– Example 5. Circle vector symbol
– Example 6. Downward diagonal fill
– Example 7. Using the Symbol Type HATCH (new in 4.6)
– Example 8. Styled lines using GAP
Example 1. Dashed Line
This example creates a dashed line that is 5 SIZEUNITS wide, with 10 SIZEUNITS on, 5 off, 5 on, 10 off ...
LAYER
...
CLASS
...
STYLE
COLOR 0 0 0
WIDTH 5
LINECAP butt
4.1. Mapfile
232
MapServer Documentation, Release 7.0.6
PATTERN 10 5 5 10 END
END
END
END
Example 2. TrueType font marker symbol
This example symbol is a star, used to represent the national capital, hence the name. The font name in defined in
the FONTSET file. The code number “114” varies, you can use MS Windows’ character map to figure it out, or
guestimate.
SYMBOL
NAME "natcap"
TYPE TRUETYPE
FONT "geo"
FILLED true
ANTIALIAS true # only necessary for GD rendering
CHARACTER "&#114;"
END
Example 3. Vector triangle marker symbol
This example is fairly straight forward. Note that to have 3 sides you need 4 points, hence the first and last points are
identical. The triangle is not filled.
SYMBOL
NAME "triangle"
TYPE vector
POINTS
0 4
2 0
4 4
0 4
END
END
Example 4. Non-contiguous vector marker symbol (Cross)
This example draws a cross, that is 2 lines (vectors) that are not connected end-to-end (Like the triangle in the previous
example). The negative values separate the two.
SYMBOL
NAME "cross"
TYPE vector
POINTS
2.0 0.0
2.0 4.0
-99 -99
0.0 2.0
4.0 2.0
END
END
4.1. Mapfile
233
MapServer Documentation, Release 7.0.6
Example 5. Circle vector symbol
This example creates a simple filled circle. Using non-equal values for the point will give you an actual ellipse.
SYMBOL
NAME "circle"
TYPE ellipse
FILLED true
POINTS
1 1
END
END
Example 6. Downward diagonal fill
This example creates a symbol that can be used to create a downward diagonal fill for polygons.
SYMBOL
NAME "downwarddiagonalfill"
TYPE vector
TRANSPARENT 0
POINTS
0 1
1 0
END
END
Example 7. Using the Symbol Type HATCH (new in 4.6)
As of MapServer 4.6, you can use the symbol type HATCH to produce hatched lines. The following will display
hatched lines at a 45 degree angle, 10 SIZEUNITS apart (center to center), and 3 SIZEUNITS wide.
Symbol definition:
SYMBOL
NAME 'hatch-test'
TYPE HATCH
END
Layer definition:
LAYER
...
CLASS
...
STYLE
SYMBOL 'hatch-test'
COLOR 255 0 0
ANGLE 45
SIZE 10
WIDTH 3
END
END
END
Other parameters available for HATCH are: MINSIZE, MAXSIZE, MINWIDTH, and MAXWIDTH.
4.1. Mapfile
234
MapServer Documentation, Release 7.0.6
Example 8. Styled lines using GAP
This example shows how to style lines with symbols.
A 5 SIZEUNITS wide black line is decorated with ellipses that are 15 SIZEUNITS long (and 7.5 SIZEUNITS‘wide).
The ellipses are placed 30 ‘SIZEUNITS apart, and the negative GAP value ensures that the ellipses are oriented relative
to the direction of the line. The ellipses are rotated 30 degrees counter clock-wise from their position along the line.
Symbol definition:
SYMBOL
NAME "ellipse2"
TYPE ellipse
FILLED true
POINTS
1 2
END
END
Layer definition:
LAYER
...
CLASS
...
STYLE
WIDTH 5
COLOR 0 0 0
END
STYLE
SYMBOL 'ellipse2'
COLOR 0 0 0
ANGLE 30
SIZE 15
GAP -30
END
END
END
4.1.27 Templating
Author Frank Koormann
Contact frank.koormann at intevation.de
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2017-03-03
Table of Contents
• Templating
– Introduction
– Format
4.1. Mapfile
235
MapServer Documentation, Release 7.0.6
– Example Template
Introduction
Templates are used:
• to define the look of a MapServer CGI application interface
• to present the results of a query.
• to create custimised output (see Template-Driven Output)
They guide the presentation of results, either a query or a map, to the user. Templates are almost always HTML files
although they can also be a URL (e.g.. http://www.somewhere.com/{[}ATTRIBUTE{]}/info.html). URL templates
can only be used with simple QUERY or ITEMQUERY results so many substitutions defined below are not available for them. Simple pan/zoom interfaces use a single template file while complicated queries often require many
templates. Templates often use JavaScript to enhance the basic interface.
Notes
• Templates must contain the magic string ‘mapserver template’ in the first line of the template. Often this takes
the form of an HTML, javascript or XML comment. This line is not written to the client. The magic string is
not case sensitive.
• MapServer will only accept certain file extensions for templates; valid file extensions are:
.gml
.html
.htm
.js
.kml
.svg
.tmpl
.wml
.xml
• All CGI parameters can be referenced in template substitutions, MapServer specific parameters as well as user
defined ones. In principle parameters are handed through by the MapServer 1:1. This feature is essential for
implementing MapServer applications.
The reference below only lists special template substitution strings which are needed to obtain information
modified by the MapServer, e.g. a new scale, query results, etc.
• Template substitution strings are case sensitive.
• Attribute item substitutions must be the same case as the item names in the dbase file.
• ArcView and ArcInfo generally produce dbase files with item names that are all uppercase. Appropriate URL
encoding (i.e. ‘ ‘ to ‘+’) is applied when templates are URLs.
• Some substitutions are also available in escaped form (i.e. URL encoded).
As an example this is needed when generating links within a template. This might pass the current mapextent to a new
MapServer call. [mapext] is substituted by a space delimited set of lower left and upper right coordinates. This would
break the URL. [mapext_esc] is substituted by a proper encoded set.
4.1. Mapfile
236
MapServer Documentation, Release 7.0.6
Format
Templates are simply HTML files or URL strings that contains special characters that are replaced by mapserv each
time the template is processed. The simple substitution allows information such as active layers or the spatial extent
to be passed from the user to mapserv and back again. Most often the new values are dumped into form variables that
will be passed on again. The list of special characters and form variables is given below. HTML templates can include
just about anything including JavaScript and Java calls.
In HTML files, the attribute values can be inside quotes(“”). Writing attribute values inside quotes allows you to set
special characters in value that you couldn’t use normally (ie: ],=,” and space). To write a single quote in a attribute
value, just use two quotes (“”).
General
[date] Outputs the date (as per the web server’s clock). The default format is the same as is used by Apache’s Common
Log format, which looks like:
01/Dec/2010:17:34:58 -0800
Available arguments:
• format= A format string as supported by the standard C strftime() function. As an example, the default
format is defined as:
[date format="%d/%b/%Y:%H:%M:%S %z"]
• tz= timezone to use for the date returned. Default is “local”. Valid values are:
– “gmt” Output date will be Greenwich time
– “local” Output the time in the web server’s local time zone.
Additionally or alternatively, the %z and %Z strftime format strings allow the timezone offset or name
to be output.
[version] The MapServer version number.
[id] Unique session id. The id can be passed in via a form but is more commonly generated by the software. In that
case the id is a concatenation of UNIX time (or NT equivalent) and the process id. Unless you’re getting more
requests in a second than the system has process ids the id can be considered unique. ;->
[host] Hostname of the web server.
[port] Port the web server is listening to.
[post or get variable name], [post or get variable name_esc] The contents of any variables passed to the
MapServer, whether they were used or not, can be echoed this way. One use might be to have the user set
a map title or north arrow style in an interactive map composer. The system doesn’t care about the values, but
they might be real important in creating the final output, e.g. if you specified a CGI parameter like myvalue=....
you can access this in the template file with [myvalue].
Also available as escaped version.
[web_meta data key],[web_meta data key_esc] Web object meta data access (e.g [web_projection]
Also available as escaped version.
[errmsg], [errmsg_esc] Current error stack output. Various error messages are delimited by semi-colons.
Also available as escaped version.
4.1. Mapfile
237
MapServer Documentation, Release 7.0.6
File Reference
[img] Path (relative to document root) of the new image, just the image name if IMAGE_URL is not set in the mapfile.
In a map interface template, [img] is substituted with the path to the map image. In a query results template, it
is substituted with the path to the querymap image (if a QUERYMAP object is defined in the Mapfile).
[ref] Path (relative to document root) of the new reference image.
[legend] Path (relative to document root) of new legend image rendered by the MapServer.
Since version 3.5.1 a new HTML Legend template is provided by MapServer. If a template is defined in the
Mapfile the [legend] string is replaced by the processed legend as. See the HTML Legends with MapServer for
details.
[scalebar] Path (relative to document root) of new scalebar image.
[queryfile] Path to the query file (if savequery was set as a CGI Parameter).
[map] Path to the map file (if savemap was set as a CGI Parameter).
Image Geometry
[center] Computed image center in pixels. Useful for setting imgxy form variable when map sizes change.
[center_x], [center_y] Computed image center X or Y coordinate in pixels.
[mapsize], [mapsize_esc] Current image size in cols and rows (separated by spaces).
Also available as escaped version.
[mapwidth], [mapheight] Current image width or height.
[scaledenom] Current image scale. The exact value is not appropriate for user information but essential for some
applications. The value can be rounded e.g. using JavaScript or server side post processing.
[scale] - deprecated Since MapServer 5.0 the proper parameter to use is [scaledenom] instead. The deprecated [scale]
is the current image scale. The exact value is not appropriate for user information but essential for some applications. The value can be rounded e.g. using JavaScript or server side post processing.
[cellsize] Size of an pixel in the current image in map units. Useful for distance measurement tools in user interfaces.
Map Geometry
[mapx], [mapy] X and Y coordinate of mouse click.
[mapext], [mapext_esc] Full mapextent (separated by spaces).
Also available as escaped version. (mapext_esc is deprecated in MapServer 5.2. You should use the “escape=”
argument instead)
The default template [mapext] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
• escape= Escape the coordinates returned. Default is “none”. Valid values are:
– “url” Use URL escape codes to encode the coordinates returned.
– “none” Do not escape.
4.1. Mapfile
238
MapServer Documentation, Release 7.0.6
• expand= Expand the bounds of the extents by a specific value. Specified in map coordinates. For example,
[mapext] might return:
123456 123456 567890 567890
and [mapext expand=1000] would therefore return:
122456 122456 568890 568890
• format= Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add
commas to the coordinates you would use:
[mapext format="$minx,$miny,$maxx,$maxy"]
• precision= The number of decimal places to output for coordinates (default is 0).
[minx], [miny], [maxx], [maxy] Minimum / maximum X or Y coordinate of new map extent.
[dx], [dy] The differences of minimum / maximum X or Y coordinate of new map extent.
Useful for creating cachable extents (i.e. 0 0 dx dy) with legends and scalebars
[rawext], [rawext_esc] Raw mapextent, that is the extent before fitting to a window size (separated by spaces). In
cases where input came from imgbox (via Java or whatever) rawext refers to imgbox coordinates transformed
to map units. Useful for spatial query building.
Also available as escaped version. (rawext_esc is deprecated in MapServer 5.2. You should use the “escape=”
argument instead)
The default template [rawext] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
• escape= Escape the coordinates returned. Default is “none”. Valid values are:
– “url” Use URL escape codes to encode the coordinates returned.
– “none” Do not escape.
• expand= Expand the bounds of the extents by a specific value. Specified in map coordinates. For example,
[rawext] might return:
123456 123456 567890 567890
and [rawext expand=1000] would therefore return:
122456 122456 568890 568890
• format= Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add
commas to the coordinates you would use:
[rawext format="$minx,$miny,$maxx,$maxy"]
• precision= The number of decimal places to output for coordinates (default is 0).
[rawminx], [rawminy], [rawmaxx], [rawmaxy] Minimum / maximum X or Y coordinate of a raw map/search extent.
The following substitutions are only available if the MapServer was compiled with PROJ support and a PROJECTION
is defined in the Mapfile.
[maplon], [maplat] Longitude / latitude value of mouse click. Available only when projection enabled.
4.1. Mapfile
239
MapServer Documentation, Release 7.0.6
[mapext_latlon], [mapext_latlon_esc] Full mapextent (separated by spaces). Available only when projection enabled.
Also available as escaped version. (mapext_latlon_esc is deprecated in MapServer 5.2. You should use the
“escape=” argument instead)
The default template [mapext_latlon] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
• escape= Escape the coordinates returned. Default is “none”. Valid values are:
– “url” Use URL escape codes to encode the coordinates returned.
– “none” Do not escape.
• expand= Expand the bounds of the extents by a specific value. Specified in map coordinates. For example,
[mapext_latlon] might return:
123456 123456 567890 567890
and [mapext_latlon expand=1000] would therefore return:
122456 122456 568890 568890
• format= Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add
commas to the coordinates you would use:
[mapext_latlon format="$minx,$miny,$maxx,$maxy"]
• precision= The number of decimal places to output for coordinates (default is 0).
[minlon], [minlat], [maxlon] [maxlat] Minimum / maximum longitude or latitude value of mapextent. Available
only when projection enabled.
[refext], [refext_esc] Reference map extent (separated by spaces).
This template has been added with version 4.6 on behalf of an enhancement request. See the thread in the
MapServer ticket#1102 for potential use cases.
Also available as escaped version. (refext_esc is deprecated in MapServer 5.2. You should use the “escape=”
argument instead)
The default template [refext] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
• escape= Escape the coordinates returned. Default is “none”. Valid values are:
– “url” Use URL escape codes to encode the coordinates returned.
– “none” Do not escape.
• expand= Expand the bounds of the extents by a specific value. Specified in map coordinates. For example,
[refext] might return:
123456 123456 567890 567890
and [refext expand=1000] would therefore return:
122456 122456 568890 568890
• format= Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add
commas to the coordinates you would use:
4.1. Mapfile
240
MapServer Documentation, Release 7.0.6
[refwext format="$minx,$miny,$maxx,$maxy"]
• precision= The number of decimal places to output for coordinates (default is 0).
Layer
[layers] | [layers_esc] All active layers space delimited. Used for a “POST” request.
Also available as escaped version.
[toggle_layers] | [toggle_layers_esc] List of all layers that can be toggled, i.e. all layers defined in the Mapfile which
status is currently not default.
Also available as escaped version.
[layername_check | select] Used for making layers persistent across a map creation session. String is replaced with
the keyword “checked”, “selected” or “” if layername is on. Layername is the name of a layer as it appears in
the Mapfile. Does not work for default layers.
[layername_meta data key] Layer meta data access (e.g. [streets_build] the underscore is essential).
Zoom
[zoom_minzoom to maxzoom_check|select] Used for making the zoom factor persistent. Zoom values can range
from -25 to 25 by default. The string is replaced with the HTML keyword “checked”, “selected” or “” depending
on the current zoom value.
E.g. if the zoom is 12, a [zoom_12_select] is replaced with “selected”, while a [zoom_13_select] in the same
HTML template file is not.
[zoomdir_-1|0|1_check|select] Used for making the zoom direction persistent. Use check with a radio control or
select with a selection list. See the demo for an example. The string is replaced with the HTML keyword
“checked”, “selected” or “” depending on the current value of zoomdir.
Query
The following substitutions are only available when the template is processed as a result of a query.
[shpext], [shpext_esc] Extent of current shape plus a 5 percent buffer. Available only when processing query results.
The default template [shpext] returns coordinates in the format of: mixx miny maxx maxy
Available arguments:
• escape= Escape the coordinates returned. Default is “none”. Valid values are:
– “url”
Use URL escape codes to encode the coordinates returned.
– “none” Do not escape.
• expand= Expand the bounds of the extents by a specific value. Specified in map coordinates. For example,
[shpext] might return:
123456 123456 567890 567890
and [shpext expand=1000] would therefore return:
4.1. Mapfile
241
MapServer Documentation, Release 7.0.6
122456 122456 568890 568890
• format= Format of the coordinates. Default is “$minx $miny $maxx $maxy”. For example, to add
commas to the coordinates you would use:
[shpext format="$minx,$miny,$maxx,$maxy"]
• precision= The number of decimal places to output for coordinates (default is 0).
[shpminx], [shpminy], [shpmaxx], [shpmaxy] Minimum / maximum X or Y coordinate of shape extent. Available
only when processing query results.
[shpmid] Middle of the extent of current shape. Available only when processing query results.
[shpmidx], [shpmidy] X or Y coordinate of middle of the extent of the current shape. Available only when processing
query results.
[shpidx] Index value of the current shape. Available only when processing query results.
[shpclass] Classindex value of the current shape. Available only when processing query results.
[shpxy formatting options] The list of shape coordinates, with list formatting options, especially useful for SVG.
The default template [shpxy] returns a comma separated list of space delimited of coordinates (i.e. x1 y1, x2 y2,
x3 y3).
Available only when processing query results.
Available attributes (h = header, f=footer, s=separator):
• buffer=, Buffer size, currently the only unit available is pixels. Default is 0.
• centroid= Should only the centroid of the shape be used? true or false (case insensitive). Default is false.
• cs= Coordinate separator. Default is ”,”.
• irh=, irf=, orh=, orf=
Characters to be put before (irh) and after (irf ) inner rings, and before (orh) and after (orf ) outer
rings of polygons with holes. Defaults are “”.
Note: Within each polygon, the outer ring is always output first, followed by the inner rings.
If neither irh nor orh are set, rings are output as “parts” using ph/pf /ps.
• ph=, pf=, ps= Characters to put before (ph) and after (pf ) and separators between (ps) feature parts (e.g.
rings of multigeometries). Defaults are ph=””, pf=”” and ps=” ”.
• precision= The number of decimal places to output for coordinates. Default is 0.
• proj= The output projection definition for the coordinates, a special value of “image” will convert to
image coordinates. Default is none.
• scale=, scale_x=, scale_y= Scaling factor for coordinates: Both axes (scale), x axis (scale_x) and y axis
(scale_y). Defaults are 1.0.
• sh=, sf= Characters to put before (sh) and after (sf ) a feature. Defaults are “”.
• xh=, xf= Characters to put before (xh) and after (xf ) the x coordinates. Defaults are xh=”” and xf=”,”).
• yh= yf= Characters to put before (yh) and after (yf ) the y coordinates. Defaults are “”.
As a simple example:
4.1. Mapfile
242
MapServer Documentation, Release 7.0.6
[shpxy xh="(" yf=")"] will result in: (x1 y1),(x2 y2),(x3 y3)
or
[shpxy precision="2" xh="(" yf=")"] will result in: (x1,y1) (x2,y2) (x3,y3)
or
[shpxy precision="2" xf=" " xh="(" yf=")"] will result in: (x1 y1) (x2 y2) (x3 y3)
And a more complicated example of outputting KML for multipolygons which may potentially have holes (note
that the parameters must all be on one line):
<MultiGeometry>
<Point>
<coordinates>[shplabel proj=epsg:4326 precision=10],0</coordinates>
</Point>
[shpxy ph="<Polygon><tessellate>1</tessellate>" pf="</Polygon>" xf=","
xh=" " yh=" " yf=",0 " orh="<outerBoundaryIs><LinearRing><coordinates>"
orf="</coordinates></LinearRing></outerBoundaryIs>"
irh="<innerBoundaryIs><LinearRing><coordinates>"
irf="</coordinates></LinearRing></innerBoundaryIs>" proj=epsg:4326
precision=10]
</MultiGeometry>
[tileindex] Index value of the current tile. If no tiles used for the current shape this is replaced by “-1”. Available only
when processing query results.
[item formatting options] An attribute table “item”, with list formatting options. The “name” attribute is required.
Available only when processing query results.
Available attributes:
• name = The name of an attribute, case insenstive. (required)
• precision = The number of decimal places to use for numeric data. Use of this will force display as a
number and will lead to unpredicable results with non-numeric data.
• pattern = Regular expression to compare the value of an item against. The tag is output only if there is a
match.
• uc = Set this attribute to “true” to convert the attribute value to upper case.
• lc = Set this attribute to “true” to convert the attribute value to lower case.
• commify = Set this attribute to “true” to add commas to a numeric value. Again, only useful with numeric
data.
• escape = Default escaping is for HTML, but you can escape for inclusion in a URL (=url), or not escape
at all (=none).
• format = A format string used to output the attribute value. The token “$value” is used to place the value
in a more complex presentation. Default is to output only the value.
• nullformat = String to output if the attribute value is NULL, empty or doesn’t match the pattern (if defined). If not set and any of these conditions occur the item tag is replaced with an empty string.
As a simple example:
[item name="area" precision="2" commify="2" format="Area is $value"]
4.1. Mapfile
243
MapServer Documentation, Release 7.0.6
[attribute name],[attrribute name_esc],[attribute item name_raw] Attribute name from the data table of a queried
layer. Only attributes for the active query layers are accessible. Case must be the same as what is stored in the
data file. ArcView, for example, uses all caps for shapefile field names. Available only when processing query
results.
By default the attributes are encoded especially for HTML representation. In addition the escaped version (for
use in URLs) as well as the raw data is available.
[Join name_attribute name],[Join name_attribute name_esc], [Join name_attribute name_raw]
One-to-one joins: First the join name (as specified in the Mapfile has to be given, second the tables fields
can be accessed similar to the layers attribute data. Available only when processing query results.
By default the attributes are encoded especially for HTML representation. In addition the escaped version
(for use in URLs) as well as the raw data is available.
[join_Join name] One-to-many joins: The more complex variant. If the join type is multiple (one-to-many) the
template is replaced by the set of header, template file and footer specified in the Mapfile.
[metadata_meta data key], [metadata_meta data key_esc] Queried
data_projection]
layer
meta
data
access
(e.g
[meta-
Also available as escaped version.
For query modes that allow for multiple result sets, the following string substitutions are available. For FEATURESELECT and FEATURENSELECT modes the totals a re adjusted so as not to include the selection layer. The selection
layer results ARE available for display to the user.
[nr] Total number of results. Useful in web header and footers. Available only when processing query results.
[nl] Number of layers returning results. Useful in web header and footers. Available only when processing query
results.
[nlr] Total number of results within the current layer. Useful in web header and footers. Available only when processing query results.
[rn] Result number within all layers. Starts at 1. Useful in web header and footers. Available only when processing
query results.
[lrn] Result number within the current layer. Starts at 1. Useful in query templates. Available only when processing
query results.
[cl] Current layer name. Useful in layer headers and footers. Available only when processing query results.
Example Template
A small example to give an idea how to work with templates. Note that it covers MapServer specific templates (e.g.
the [map], [mapext]) and user defined templates (e.g. [htmlroot] or [program]) used to store application settings.
1
2
3
4
5
6
7
<!-- MapServer Template -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/transitional.dtd">
<html>
<head>
<title>MapServer Template Sample</title>
</head>
8
9
10
<body>
MapServer Template Sample<br>
11
12
<!-- The central form the application is based on. -->
4.1. Mapfile
244
MapServer Documentation, Release 7.0.6
13
<form method="GET" action="[program]">
14
15
16
17
18
19
20
21
22
23
24
25
<!-- CGI MapServer applications are server stateless in principle,
all information must be "stored" in the client. This includes
some basic settings as below.
The example is based on the pan and zoom test suite:
http://maps.dnr.state.mn.us/mapserver_demos/tests36/
<input type="hidden" name="map" value="[map]">
<input type="hidden" name="imgext" value="[mapext]">
<input type="hidden" name="imgxy" value="149.5 199.5">
<input type="hidden" name="program" value="[program]">
<input type="hidden" name="htmlroot" value="[htmlroot]">
<input type="hidden" name="map_web" value="[map_web]">
-->
26
27
28
29
30
31
32
33
34
35
36
37
38
<!-- A table for minimal page formatting. -->
<table border=0 cellpadding=5>
<tr>
<!-- First column: Map and scale bar -->
<td align=center>
<!-- The map -->
<input type="image" name="img" src="[img]"
style="border:0;width:300;height:400">
<br>
<!-- The scale bar-->
<img src="[scalebar]" alt="Scale Bar">
</td>
39
40
41
42
43
44
45
46
47
48
49
50
<!-- Second column: Zoom direction, Legend and Reference -->
<td valign=top>
<!-- Zoom direction -->
<b>Map Controls</b><br>
Set your zoom option:<br>
<select name="zoom" size="1">
<option value="2" [zoom_2_select]> Zoom in 2 times
<option value="1" [zoom_1_select]> Recenter Map
<option value="-2" [zoom_-2_select]> Zoom out 2 times
</select>
<br>
51
<!-- Legend -->
<b>Legend</b><br>
<img src="[legend]" alt="Legend"><br><br><br><br>
52
53
54
55
56
57
58
59
60
61
<!-- Reference map -->
<input type="image" name="ref" src="[ref]"
style="border:0;width:150;height:150">
</td>
</tr>
</table>
62
63
</form>
64
65
66
</body>
</html>
4.1. Mapfile
245
MapServer Documentation, Release 7.0.6
4.1.28 Union Layer
Author Tamas Szekeres
Contact szekerest at gmail.com
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2011-04-11
Table of Contents
• Union Layer
– Description
– Requirements
– Mapfile Configuration
– Feature attributes
– Classes and Styles
– Projections
– Supported Processing Options
– Examples
* Mapfile Example
* PHP MapScript Example
Description
Since version 6.0, MapServer has the ability to display features from multiple layers (called ‘source layers’) in a single
mapfile layer. This feature was added through rfc68.
Requirements
This is a native MapServer option that doesn’t use any external libraries to support it.
Mapfile Configuration
• The CONNECTIONTYPE parameter must be set to UNION.
• The CONNECTION parameter must contain a comma separated list of the source layer names.
• All of the source layers and the union layer must be the same TYPE (e.g. all must be TYPE POINT, or all TYPE
POLYGON etc.)
Note: You may wish to disable the visibility (change their STATUS) of the source layers to avoid displaying the
features twice.
4.1. Mapfile
246
MapServer Documentation, Release 7.0.6
For example:
LAYER
NAME "union-layer"
TYPE POINT
STATUS DEFAULT
CONNECTIONTYPE UNION
CONNECTION "layer1,layer2,layer3" # reference to the source layers
PROCESSING "ITEMS=itemname1,itemname2,itemname3"
...
END
LAYER
NAME "layer1"
TYPE POINT
STATUS OFF
CONNECTIONTYPE OGR
CONNECTION ...
...
END
LAYER
NAME "layer2"
TYPE POINT
STATUS OFF
CONNECTIONTYPE OGR
CONNECTION ...
...
END
LAYER
NAME "layer3"
TYPE POINT
STATUS OFF
CONNECTIONTYPE OGR
CONNECTION ...
...
END
Feature attributes
In the LAYER definition you may refer to any attributes supported by each of the source layers. In addition to the
source layer attributes the union layer provides the following additional attributes:
1. Combine_SourceLayerName - The name of the source layer the feature belongs to
2. Combine_SourceLayerGroup - The group of the source layer the feature belongs to
During the selection / feature query operations only the ‘Combine_SourceLayerName’ and ‘Combine_SourceLayerGroup’ attributes are provided by default. The set of the provided attributes can manually
be overridden (and further attributes can be exposed) by using the ITEMS processing option (refer to the example
above).
Classes and Styles
We can define the symbology and labelling for the union layers in the same way as for any other layer by specifying the
classes and styles. In addition the STYLEITEM AUTO option is also supported for the union layer, which provides to
display the features as specified at the source layers. The source layers may also use the STYLEITEM AUTO setting
if the underlying data source provides that.
4.1. Mapfile
247
MapServer Documentation, Release 7.0.6
Projections
For speed, it is recommended to always use the same projection for the union layer and source layers. However
MapServer will reproject the source layers to the union layer if requested. (for more information on projections in
MapServer refer to PROJECTION)
Supported Processing Options
The following processing options can be used with the union layers:
UNION_STATUS_CHECK (TRUE or FALSE) Controls whether the status of the source layes should be checked
and the invisible layers (STATUS=OFF) should be skipped. Default value is FALSE.
UNION_SCALE_CHECK (TRUE or FALSE) Controls whether the scale range of the source layes should be
checked and the invisible layers (falling outside of the scale range and zoom range) should be skipped. Default value is TRUE.
UNION_SRCLAYER_CLOSE_CONNECTION Override the connection pool setting of the source layers. By
introducing this setting we alter the current behaviour which is equivalent to:
UNION_SRCLAYER_CLOSE_CONNECTION=ALWAYS
Examples
Mapfile Example
The follow example contains 3 source layers in different formats, and one layer (yellow) in a different projection.
The union layer uses the STYLEITEM “AUTO” parameter to draw the styles from the source layers. (in this case
MapServer will reproject the yellow features, in EPSG:4326, for the union layer, which is in EPSG:3978).
4.1. Mapfile
248
MapServer Documentation, Release 7.0.6
MAP
...
PROJECTION
"init=epsg:3978"
END
...
LAYER
NAME 'unioned'
TYPE POLYGON
STATUS DEFAULT
CONNECTIONTYPE UNION
CONNECTION "red,green,yellow"
STYLEITEM "AUTO"
# Define an empty class that will be filled at runtime from the color and
# styles read from each source layer.
CLASS
END
PROJECTION
"init=epsg:3978"
END
END
LAYER
NAME 'red'
TYPE POLYGON
STATUS OFF
DATA 'nb.shp'
CLASS
NAME 'red'
STYLE
4.1. Mapfile
249
MapServer Documentation, Release 7.0.6
OUTLINECOLOR 0 0 0
COLOR 255 85 0
END
END
END
LAYER
NAME 'green'
TYPE POLYGON
STATUS OFF
CONNECTIONTYPE OGR
CONNECTION 'ns.mif'
CLASS
NAME 'green'
STYLE
OUTLINECOLOR 0 0 0
COLOR 90 218 71
END
END
END
LAYER
NAME 'yellow'
TYPE POLYGON
STATUS OFF
CONNECTIONTYPE OGR
CONNECTION 'pei.gml'
CLASS
NAME 'yellow'
STYLE
OUTLINECOLOR 0 0 0
COLOR 255 255 0
END
END
PROJECTION
"init=epsg:4326"
END
END
END # Map
PHP MapScript Example
<?php
// open map
$oMap = ms_newMapObj( "D:/ms4w/apps/osm/map/osm.map" );
// create union layer
$oLayer = ms_newLayerObj($oMap);
$oLayer->set("name", "unioned");
$oLayer->set("type", MS_LAYER_POLYGON);
$oLayer->set("status", MS_ON);
$oLayer->setConnectionType(MS_UNION);
$oLayer->set("connection", "red,green,yellow");
$oLayer->set("styleitem", "AUTO");
4.1. Mapfile
250
MapServer Documentation, Release 7.0.6
$oLayer->setProjection("init=epsg:3978");
// create empty class
$oClass = ms_newClassObj($oLayer);
...
?>
4.1.29 WEB
BROWSEFORMAT [mime-type] Format of the interface output, using MapServer CGI. (added to MapServer 4.8.0)
The default value is “text/html”. Example:
BROWSEFORMAT "image/svg+xml"
EMPTY [url] URL to forward users to if a query fails. If not defined the value for ERROR is used.
ERROR [url] URL to forward users to if an error occurs. Ugly old MapServer error messages will appear if this is
not defined
FOOTER [filename] Template to use AFTER anything else is sent. Multiresult query modes only.
HEADER [filename] Template to use BEFORE everything else has been sent. Multiresult query modes only.
IMAGEPATH [path] Path to the temporary directory for writing temporary files and images. Must be writable by
the user the web server is running as. Must end with a / or depending on your platform.
IMAGEURL [path] Base URL for IMAGEPATH. This is the URL that will take the web browser to IMAGEPATH
to get the images.
LEGENDFORMAT [mime-type] Format of the legend output, using MapServer CGI. (added to MapServer 4.8.0)
The default value is “text/html”. Example:
LEGENDFORMAT "image/svg+xml"
LOG [filename] Since MapServer 5.0 the recommended parameters to use for debugging are the MAP object’s CONFIG and DEBUG parameters instead (see the Debugging MapServer document).
File to log MapServer activity in. Must be writable by the user the web server is running as.
Deprecated since version 5.0.
MAXSCALEDENOM [double] Minimum scale at which this interface is valid. When a user requests a map at
a smaller scale, MapServer automatically returns the map at this scale. This effectively prevents user from
zooming too far out. Scale is given as the denominator of the actual scale fraction, for example for a map at a
scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MAXSCALE parameter.
See also:
Map scale
MAXSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is MAXSCALEDENOM instead. The deprecated MAXSCALE is the minimum scale at which this interface is valid. When a user requests
a map at a smaller scale, MapServer automatically returns the map at this scale. This effectively prevents user
from zooming too far out. Scale is given as the denominator of the actual scale fraction, for example for a map
at a scale of 1:24,000 use 24000.
Deprecated since version 5.0.
MAXTEMPLATE [file|url] Template to be used if below the minimum scale for the app (the denominator of the
requested scale is larger than MAXSCALEDENOM), useful for nesting apps.
4.1. Mapfile
251
MapServer Documentation, Release 7.0.6
METADATA This keyword allows for arbitrary data to be stored as name value pairs.
• Used with OGC services (WMS Server, WFS Server, WCS Server, SOS Server, ...) to define things such
as layer title.
• It can also allow more flexibility in creating templates, as anything you put in here will be accessible via
template tags.
• If you have XMP support enabled, you can also embed xmp_metadata in your output images by specifying
XMP tag information here. Example:
METADATA
title "My layer title"
author "Me!"
xmp_dc_Title "My Map Title"
END
• labelcache_map_edge_buffer
For tiling, the amount of gutter around an image where no labels are to be placed is controlled by the
parameter labelcache_map_edge_buffer. The unit is pixels. The value had to be a negative value for 6.0
and earlier versions. From 6.2 the absolute value is taken, so the sign does not matter.
METADATA
"labelcache_map_edge_buffer" "10"
END
• ms_enable_modes
Enable / disable modes (see rfc90).
Use the asterisk “*” to specify all modes and a preceding exclamation sign ”!” to negate the given condition
To disable all CGI modes:
METADATA
"ms_enable_modes" "!*"
END
To disable everything but MAP and LEGEND:
METADATA
"ms_enable_modes" "!* MAP LEGEND"
END
MINSCALEDENOM [double] Maximum scale at which this interface is valid. When a user reqests a map at a larger
scale, MapServer automatically returns the map at this scale. This effectively prevents the user from zooming
in too far. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of
1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MINSCALE parameter.
See also:
Map scale
MINSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is MINSCALEDENOM instead. The deprecated MINSCALE is the maximum scale at which this interface is valid. When a user reqests a
map at a larger scale, MapServer automatically returns the map at this scale. This effectively prevents the user
from zooming in too far. Scale is given as the denominator of the actual scale fraction, for example for a map at
a scale of 1:24,000 use 24000.
Deprecated since version 5.0.
4.1. Mapfile
252
MapServer Documentation, Release 7.0.6
MINTEMPLATE [file|url] Template to be used if above the maximum scale for the app (the denominator of the
requested scale is smaller than MINSCALEDENOM), useful for nesting apps.
QUERYFORMAT [mime-type] Format of the query output. (added to MapServer 4.8.0) This works for
mode=query (using query templates in CGI mode), but not for mode=browse. The default value is “text/html”.
Example:
QUERYFORMAT "image/svg+xml"
TEMPLATE [filename|url]
Template file or URL to use in presenting the results to the user in an interactive mode (i.e. map generates
map and so on ... ).
URL is not a remote file, rather a template. For example:
TEMPLATE 'http://someurl/somescript.cgi?mapext=[mapext]'
TEMPPATH [path] Path for storing temporary files. If not set, the standard system temporary file path will be used
(e.g. tmp for unix). TEMPPATH can also be set using the environment variable MS_TEMPPATH.
TEMPPATH is used in many contexts (see rfc66).
Make sure that that MapServer has sufficient rights to read and write files at the specified location.
New in version 6.0.
VALIDATION Signals the start of a VALIDATION block.
As of MapServer 5.4.0, VALIDATION blocks are the preferred mechanism for specifying validation patterns for
CGI param runtime substitutions. See Run-time Substitution.
4.1.30 XML Mapfile support
MapServer is able to load XML mapfiles automatically, without user XSLT transformations. Basically, MapServer
will simply do an XSLT transformation when the mapfile passed to it is an XML one, convert it to a text mapfile in a
temporary file on disk, then process the mapfile normally.
New Dependencies
• libxslt
• libexslt
Enabling the support
You can enable the XML mapfile support by adding the following option: –with-xml-mapfile. This configure option
will enable the libxslt and libexslt check up. If your libxslt/libexslt are not installed in /usr, you’ll have to add the
following options:
--with-xslt=/path/to/xslt/installation
--with-exslt=/path/to/exslt/installation
Usage:
In order to enable this feature, set the MS_XMLMAPFILE_XSLT environment variable to point to the location of the
XSLT to use for the XML->text mapfile conversion. e.g. in Apache:
4.1. Mapfile
253
MapServer Documentation, Release 7.0.6
SetEnv MS_XMLMAPFILE_XSLT /path/to/mapfile.xsl
PassEnv MS_XMLMAPFILE_XSLT
With this enabled, passing an .xml filename to the CGI map parameter will automatically trigger the conversion.
Note: This is a first step to XML mapfile loading support. Obviously, there is a cost to parse and translate the XML
mapfile, but this allows easier use of XML mapfiles.
4.1.31 Notes
• The Mapfile is NOT case-sensitive.
• The Mapfile is read from top to bottom by MapServer; this means that LAYERs near the
top of your Mapfile will be drawn before those near the bottom. Therefore users commonly place background
imagery and other background layer types near the top of their mapfile, and lines and points near the bottom of
their mapfile.
• Strings containing non-alphanumeric characters or a MapServer keyword MUST be quoted. It is recommended
to put ALL strings in double-quotes.
• Mapfiles are expected to be UTF-8 encoded. Non UTF-8 encoded mapfiles will need to be iconvâĂŹed to
UTF-8.
New in version 7.0.
• For MapServer versions < 5, there was a default maximum of 200 layers per mapfile (there is no layer limit with
MapServer >= 5). This can be changed by editing the map.h file to change the value of MS_MAXLAYERS to
the desired number and recompiling. Here are other important default limits when using a MapServer version <
5:
– MAXCLASSES 250 (set in map.h)
– MAXSTYLES 5 (set in map.h)
– MAXSYMBOLS 64 (set in mapsymbol.h)
MapServer versions >= 5 have no limits for classes, styles, symbols, or layers.
• File paths may be given as absolute paths, or as paths relative to the location of the mapfile. In addition, data
files may be specified relative to the SHAPEPATH.
• The mapfile has a hierarchical structure, with the MAP object being the “root”. All other objects fall under this
one.
• Comments are designated with a #.
• Attributes are named using the following syntax: [ATTRIBUTENAME].
Note: that the name of the attribute included between the square brackets IS CASE SENSITIVE. Generally
ESRI generated shape data sets have their attributes (.dbf column names) all in upper-case for instance, and for
PostGIS, ALWAYS use lower-case.
• MapServer Regular Expressions are used through the operating system’s C Library. For information on how to
use and write Regular Expressions on your system, you should read the documentation provided with your C
Library. On Linux, this is GLibC, and you can read “man 7 regex” ... This man page is also available on most
UNIX’s. Since these RegEx’s are POSIX compliant, they should be the same on Windows as well, so windows
users can try searching the web for “man 7 regex” since man pages are available all over the web.
4.1. Mapfile
254
CHAPTER 5
MapScript
5.1 MapScript
Release 7.0.6
5.1.1 Introduction
This is language agnostic documentation for the MapScript interface to MapServer generated by SWIG. This document
is intended for developers and to serve as a reference for writers of more extensive, language specific documentation
located at Mapfile
Appendices
Language-specific extensions are described in the following appendices
Python Appendix
Documentation Elements
Classes will be documented in alphabetical order in the manner outlined below. Attributes and methods will be
formatted as definition lists with the attribute or method as item, the type or return type as classifier, and a concise
description. To make the document as agnostic as possible, we refer to the following types: int, float, and string. There
are yet no mapscript methods that return arrays or sequences or accept array or sequence arguments.
We will use the SWIG term immutable to indicate that an attribute’s value is read-only.
fooObj
A paragraph or two about class fooObj.
fooObj Attributes
attribute [type [access]] Concise description of the attribute.
255
MapServer Documentation, Release 7.0.6
Attribute name are completely lower case. Multiple words are packed together like outlinecolor.
Note that because of the way that mapscript is generated many confusing, meaningless, and even dangerous attributes
are creeping into objects. See outputFormatObj.refcount for example. Until we get a grip on the structure members
we are exposing to SWIG this problem will continue to grow.
fooObj Methods
method(type mandatory_parameter [, type optional_parameter=default]) [type] Description of the method including elaboration on the method arguments, the method’s actions, and returned values. Optional parameters
and their default values are enclosed in brackets.
Class method names are camel case with a leading lower case character like getExpressionString.
Additional Documentation
There’s no point in duplicating the MapServer Mapfile Reference, which remains the primary reference for mapscript
class attributes.
5.1.2 SWIG MapScript API Reference
Author Sean Gillies
Author Steve Lime
Contact steve.lime at dnr.state.mn.us
Author Frank Warmerdam
Contact warmerdam at pobox.com
Author Umberto Nicoletti
Contact umberto.nicoletti at gmail.com
Author Tamas Szekeres
Contact szekerest at gmail.com
Author Daniel Morissette
Contact dmorisette at mapgears.com
Last Updated 2016-08-22
Contents
• SWIG MapScript API Reference
– Introduction
* Appendices
* Documentation Elements
* fooObj
* Additional Documentation
– MapScript Constants
5.1. MapScript
256
MapServer Documentation, Release 7.0.6
* Version
* Logical Control - Boolean Values
* Logical Control - Status Values
* Map Units
* Layer Types
* Label Positions
* Label Size (Bitmap only)
* Shape Types
* Measured Shape Types
* Shapefile Types
* Query Types
* File Types
* Querymap Styles
* Connection Types
* DB Connection Types
* Join Types
* Line Join Types (for rendering)
* Image Types
* Image Modes
* Symbol Types
* Return Codes
* Limiters
* Error Return Codes
– MapScript Functions
– MapScript Classes
* classObj
* colorObj
* errorObj
* fontSetObj
* hashTableObj
* imageObj
* intarray
* labelCacheMemberObj
* labelCacheObj
* labelObj
5.1. MapScript
257
MapServer Documentation, Release 7.0.6
* layerObj
* legendObj
* lineObj
* mapObj
* markerCacheMemberObj
* outputFormatObj
* OWSRequest
* pointObj
* projectionObj
* rectObj
* referenceMapObj
* resultCacheMemberObj
* resultCacheObj
* scalebarObj
* shapefileObj
* shapeObj
* styleObj
* symbolObj
* symbolSetObj
* webObj
Introduction
This is language agnostic documentation for the mapscript interface to MapServer generated by SWIG. This document
is intended for developers and to serve as a reference for writers of more extensive, language specific documentation
in DocBook format for the MDP.
Appendices
Language-specific extensions are described in the following appendices
Python MapScript Appendix
Documentation Elements
Classes will be documented in alphabetical order in the manner outlined below. Attributes and methods will be
formatted as definition lists with the attribute or method as item, the type or return type as classifier, and a concise
description. To make the document as agnostic as possible, we refer to the following types: int, float, and string. There
are yet no mapscript methods that return arrays or sequences or accept array or sequence arguments.
We will use the SWIG term immutable to indicate that an attribute’s value is read-only.
5.1. MapScript
258
MapServer Documentation, Release 7.0.6
fooObj
A paragraph or two about class fooObj.
fooObj Attributes
attribute [type [access]] Concise description of the attribute.
Attribute name are completely lower case. Multiple words are packed together like outlinecolor.
Note that because of the way that mapscript is generated many confusing, meaningless, and even dangerous attributes
might be exposed by objects.
fooObj Methods
method(type mandatory_parameter [, type optional_parameter=default]) [type] Description of the method including elaboration on the method arguments, the method’s actions, and returned values. Optional parameters
and their default values are enclosed in brackets.
might be exposed byClass method names are camel case with a leading lower case character like getExpressionString.
Additional Documentation
There’s no point in duplicating the MapServer Mapfile Reference, which remains the primary reference for mapscript
class attributes.
MapScript Constants
The constants are ordered alphabetically within each group.
Version
Name
MS_VERSION
Type
character
Logical Control - Boolean Values
Name
MS_FALSE
MS_NO
MS_OFF
MS_ON
MS_TRUE
MS_YES
Type
integer
integer
integer
integer
integer
integer
5.1. MapScript
259
MapServer Documentation, Release 7.0.6
Logical Control - Status Values
Name
MS_DEFAULT
MS_DELETE
MS_EMBED
Type
integer
integer
integer
Map Units
Name
MS_DD
MS_FEET
MS_INCHES
MS_METERS
MS_MILES
MS_NAUTICALMILES
MS_PIXELS
Type
integer
integer
integer
integer
integer
integer
integer
Layer Types
Name
MS_LAYER_ANNOTATION (deprecated since 6.2)
MS_LAYER_CIRCLE
MS_LAYER_LINE
MS_LAYER_POINT
MS_LAYER_POLYGON
MS_LAYER_QUERY
MS_LAYER_RASTER
MS_LAYER_TILEINDEX
Type
integer
integer
integer
integer
integer
integer
integer
integer
Label Positions
Name
MS_AUTO
MS_CC
MS_CL
MS_CR
MS_LC
MS_LL
MS_LR
MS_UC
MS_UL
MS_UR
Type
integer
integer
integer
integer
integer
integer
integer
integer
integer
integer
5.1. MapScript
260
MapServer Documentation, Release 7.0.6
Label Size (Bitmap only)
Name
MS_GIANT
MS_LARGE
MS_MEDIUM
MS_SMALL
MS_TINY
Type
integer
integer
integer
integer
integer
Shape Types
Name
MS_SHAPE_LINE
MS_SHAPE_NULL
MS_SHAPE_POINT
MS_SHAPE_POLYGON
Type
integer
integer
integer
integer
Measured Shape Types
Name
MS_SHP_ARCM
MS_SHP_MULTIPOINTM
MS_SHP_POINTM
MS_SHP_POLYGONM
Type
integer
integer
integer
integer
Shapefile Types
Name
MS_SHAPEFILE_ARC
MS_SHAPEFILE_MULTIPOINT
MS_SHAPEFILE_POINT
MS_SHAPEFILE_POLYGON
Type
integer
integer
integer
integer
Query Types
Name
MS_MULTIPLE
MS_SINGLE
Type
integer
integer
File Types
Name
MS_FILE_MAP
MS_FILE_SYMBOL
5.1. MapScript
Type
integer
integer
261
MapServer Documentation, Release 7.0.6
Querymap Styles
Name
MS_HILITE
MS_NORMAL
MS_SELECTED
Type
integer
integer
integer
Connection Types
Name
MS_GRATICULE
MS_INLINE
MS_MYGIS
MS_OGR
MS_ORACLESPATIAL
MS_POSTGIS
MS_RASTER
MS_SDE
MS_SHAPEFILE
MS_TILED_SHAPEFILE
MS_WFS
MS_WMS
Typ
integer
integer
integer
integer
integer
integer
integer
integer
integer
integer
integer
integer
DB Connection Types
Name
MS_DB_CSV
MS_DB_MYSQL
MS_DB_ORACLE
MS_DB_POSTGRES
MS_DB_XBASE
Type
integer
integer
integer
integer
integer
Join Types
Name
MS_JOIN_ONE_TO_MANY
MS_JOIN_ONE_TO_ONE
Type
integer
integer
Line Join Types (for rendering)
Name
MS_CJC_BEVEL
MS_CJC_BUTT
MS_CJC_MITER
MS_CJC_NONE
MS_CJC_ROUND
MS_CJC_SQUARE
MS_CJC_TRIANGLE
5.1. MapScript
Type
integer
integer
integer
integer
integer
integer
integer
262
MapServer Documentation, Release 7.0.6
Image Types
Name
GD/GIF
GD/JPEG
GD/PNG
GD/PNG24
GD/WBMP
GDAL/GTiff
imagemap
pdf
swf
Type
integer
integer
integer
integer
integer
integer
integer
integer
integer
Image Modes
Name
MS_GD_ALPHA
MS_IMAGEMODE_BYTE
MS_IMAGEMODE_FLOAT32
MS_IMAGEMODE_INT16
MS_IMAGEMODE_NULL
MS_IMAGEMODE_PC256
MS_IMAGEMODE_RGB
MS_IMAGEMODE_RGBA
MS_NOOVERRIDE
Type
integer
integer
integer
integer
integer
integer
integer
integer
integer
Symbol Types
Name
MS_SYMBOL_ELLIPSE
MS_SYMBOL_PIXMAP
MS_SYMBOL_SIMPLE
MS_SYMBOL_TRUETYPE
MS_SYMBOL_VECTOR
Type
integer
integer
integer
integer
integer
Return Codes
Name
MS_DONE
MS_FAILURE
MS_SUCCESS
5.1. MapScript
Type
integer
integer
integer
263
MapServer Documentation, Release 7.0.6
Limiters
Name
MS_IMAGECACHESIZE
MS_MAXSTYLELENGTH
MS_MAXSYMBOLS
MS_MAXVECTORPOINTS
Type
long
long
long
long
Error Return Codes
Name
MESSAGELENGTH
MS_CGIERR
MS_CHILDERR
MS_DBFERR
MS_EOFERR
MS_GDERR
MS_HASHERR
MS_HTTPERR
MS_IDENTERR
MS_IMGERR
MS_IOERR
MS_JOINERR
MS_MAPCONTEXTERR
MS_MEMERR
MS_MISCERR
MS_NOERR
MS_NOTFOUND
MS_NUMERRORCODES
MS_OGRERR
MS_ORACLESPATIALERR
MS_PARSEERR
MS_PROJERR
MS_QUERYERR
MS_REGEXERR
MS_SDEERR
MS_SHPERR
MS_SYMERR
MS_TTFERR
MS_TYPEERR
MS_WCSERR
MS_WEBERR
MS_WFSCONNERR
MS_WFSERR
MS_WMSCONNERR
MS_WMSERR
ROUTINELENGTH
5.1. MapScript
Type
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
long
264
MapServer Documentation, Release 7.0.6
MapScript Functions
msCleanup() [void] msCleanup() attempts to recover all dynamically allocated resources allocated by MapServer
code and dependent libraries. It it used primarily for final cleanup in scripts that need to do memory leak testing
to get rid of “noise” one-time allocations. It should not normally be used by production code.
msGetVersion() [string] Returns a string containing MapServer version information, and details on what optional
components are built in. The same report as produced by “mapserv -v”.
msGetVersionInt() [int] Returns the MapServer version number (x.y.z) as an integer (x*10000 + y*100 + z). (New
in v5.0) e.g. V5.4.3 would return 50403.
msIO_getStdoutBufferBytes() [binary data] Fetch the current stdout buffer contents as a binary buffer. The exact
form of this buffer will vary by mapscript language (eg. string in Python, byte[] array in Java and C#, unhandled
in perl)
msIO_getStdoutBufferString() [string] Fetch the current stdout buffer contents as a string. This method does not
clear the buffer.
msIO_installStdinFromBuffer() [void] Installs a mapserver IO handler directing future stdin reading (ie. post request capture) to come from a buffer.
msIO_installStdoutToBuffer() [void] Installs a mapserver IO handler directing future stdout output to a memory
buffer.
msIO_resetHandlers() [void] Resets the default stdin and stdout handlers in place of “buffer” based handlers.
msIO_stripStdoutBufferContentHeaders(): void Strip all Content-* headers off the stdout buffer if it has ones.
msIO_stripStdoutBufferContentType() [string] Strip the Content-type header off the stdout buffer if it has one, and
if a content type is found it is return (otherwise NULL/None/etc).
msResetErrorList() [void] Clears the current error stack.
MapScript Classes
classObj
An instance of classObj is associated with with one instance of layerObj:
+-------+ 0..*
1 +-------+
| Class | <--------> | Layer |
+-------+
+-------+
The other important associations for classObj are with styleObj, labelObj, and hashTableObj:
+-------+ 1
0..* +-------+
| Class | ---------> | Style |
+-------+
+-------+
+-------+ 1
0..* +-------+
| Class | ---------> | Label |
+-------+
+-------+
+-------+ 1
1 +-----------+
| Class | ---------> | HashTable |
+-------+
|
-|
| metadata |
+-----------+
5.1. MapScript
265
MapServer Documentation, Release 7.0.6
Multiple class styles have been supported since 4.1, and multiple class labels since 6.2. See the styleObj section for
details on use of multiple class styles.
classObj Attributes
debug [int] MS_TRUE or MS_FALSE
keyimage [string] TODO Not sure what this attribute is for
label [labelObj immutable] Definition of class labeling. Removed (6.2) - use addLabel, getLabel and removeLabel
instead.
layer [layerObj immutable] Reference to the parent layer
maxscaledenom [float] The minimum scale at which class is drawn
metadata [hashTableObj immutable] class metadata hash table.
minscaledenom [float] The maximum scale at which class is drawn
name [string] Unique within a layer
numlabels [int] Number of labels for class.
New in version 6.2.
numstyles [int] Number of styles for class. In the future, probably the 4.4 release, this attribute will be made immutable.
status [int] MS_ON or MS_OFF. Draw features of this class or do not.
template [string] Template for queries
title [string] Text used for legend labeling
type [int] The layer type of its parent layer
classObj Methods
new classObj( [ layerObj parent_layer=NULL ] ) [classObj] Create a new child classObj instance at the tail (highest
index) of the class array of the parent_layer. A class can be created outside the context of a parent layer by
omitting the single constructor argument.
addLabel( labelObj ) [int] Add a labelObj to the classObj and return its index in the labels array.
New in version 6.2.
clone( ) [classObj] Return an independent copy of the class without a parent layer.
convertToString() [string] Saves the object to a string. Provides the inverse option for updateFromString.
New in version 6.4.
createLegendIcon( mapObj map, layerObj layer, int width, int height ) [imageObj] Draw and return a new legend
icon.
drawLegendIcon( mapObj map, layerObj layer, int width, int height, imageObj image, int dstx, int dsty ) [int]
Draw the legend icon onto image at dstx, dsty. Returns MS_SUCCESS or MS_FAILURE.
getExpressionString() [string] Return a string representation of the expression enclosed in the quote characters appropriate to the expression type.
5.1. MapScript
266
MapServer Documentation, Release 7.0.6
getFirstMetaDataKey() [string] Returns the first key in the metadata hash table. With getNextMetaDataKey(), provides an opaque iterator over keys.
Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed
in a future version. Replaced by direct metadata access, see hashTableObj.
getLabel( int index ) [labelObj] Return a reference to the labelObj at index in the labels array.
See the labelObj section for more details on multiple class labels.
New in version 6.2.
getMetaData( string key ) [string] Return the value of the classObj metadata at key.
Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed
in a future version. Replaced by direct metadata access, see hashTableObj.
getNextMetaDataKey( string lastkey ) [string] Returns the next key in the metadata hash table or NULL if lastkey
is the last valid key. If lastkey is NULL, returns the first key of the metadata hash table.
Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed
in a future version. Replaced by direct metadata access, see hashTableObj.
getStyle( int index ) [styleObj] Return a reference to the styleObj at index in the styles array.
See the styleObj section for more details on multiple class styles.
getTextString() [string] Return a string representation of the text enclosed in the quote characters appropriate to the
text expression type (logical or simple string).
insertStyle( styleObj style [, int index=-1 ] ) [int] Insert a copy of style into the styles array at index index. Default
is -1, or the end of the array. Returns the index at which the style was inserted.
moveStyleDown( int index ) [int] Swap the styleObj at index with the styleObj index + 1.
moveStyleUp( int index ) [int] Swap the styleObj at index with the styleObj index - 1.
removeLabel( int index ) [labelObj] Remove the labelObj at index from the labels array and return a reference to the
labelObj. numlabels is decremented, and the array is updated.
New in version 6.2.
removeStyle( int index ) [styleObj] Remove the styleObj at index from the styles array and return a copy.
setExpression( string expression ) [int] Set expression string where expression is a MapServer regular, logical or
string expression. Returns MS_SUCCESS or MS_FAILUIRE.
setMetaData( string key, string value ) [int] Insert value into the classObj metadata at key. Returns MS_SUCCESS
or MS_FAILURE.
Note: setMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata access,
see hashTableObj.
setText( string text ) [int] Set text string where text is a MapServer text expression. Returns MS_SUCCESS or
MS_FAILUIRE.
5.1. MapScript
267
MapServer Documentation, Release 7.0.6
Note: Older versions of MapScript (pre-4.8) featured the an undocumented setText() method that required a
layerObj be passed as the first argument. That argument was completely bogus and has been removed.
colorObj
Since the 4.0 release, MapServer colors are instances of colorObj. A colorObj may be a lone object or an attribute of
other objects and have no other associations.
colorObj Attributes
alpha [int] Alpha (opacity) component of color in range [0-255]
blue [int] Blue component of color in range [0-255]
green [int] Green component of color in range [0-255]
red [int] Red component of color in range [0-255]
colorObj Methods
new colorObj( [ int red=0, int green=0, int blue=0, int alpha=255 ] ) [colorObj] Create a new instance. The color
arguments are optional.
setHex( string hexcolor ) [int] Set the color to values specified in case-independent hexadecimal notation. hex must
start with a ‘#’ followed by three or four hex bytes, e.g. ‘#ffffff’ or ‘#ffffffff’. If only three hex bytes are
supplied, the alpha will be set to 255. Calling setHex(‘#ffffff’) therefore assigns values of 255 to each color
component, including the alpha. Returns MS_SUCCESS or MS_FAILURE.
setRGB( int red, int green, int blue, int alpha=255 ) [int] Set all four RGBA components. Returns MS_SUCCESS
or MS_FAILURE.
toHex() [string] Complement to setHex, returning a hexadecimal representation of the color components. If alpha is
255 then this is three hex bytes “#rrggbb”, otherwise four hex bytes “#rrggbbaa”.
errorObj
This class allows inspection of the MapServer error stack. Only needed for the Perl module as the other language
modules expose the error stack through exceptions.
errorObj Attributes
code [int] MapServer error code such as MS_IMGERR (1).
message [string] Context-dependent error message.
routine [string] MapServer function in which the error was set.
errorObj Methods
next [errorObj] Returns the next error in the stack or NULL if the end has been reached.
5.1. MapScript
268
MapServer Documentation, Release 7.0.6
fontSetObj
A fontSetObj is always a ‘fontset’ attribute of a mapObj.
fontSetObj Attributes
filename [string immutable] Path to the fontset file on disk.
fonts [hashTableObj immutable] Mapping of fonts.
numfonts [int immutable] Number of fonts in set.
fontSetObj Methods
None
hashTableObj
A hashTableObj is a very simple mapping of case-insensitive string keys to single string values. Map, Layer, and Class
metadata have always been hash hables and now these are exposed directly. This is a limited hash that can contain no
more than 41 values.
hashTableObj Attributes
numitems [int immutable] Number of hash items.
hashTableObj Methods
clear( ) [void] Empties the table of all items.
get( string key [, string default=NULL ] ) [string] Returns the value of the item by its key, or default if the key does
not exist.
nextKey( [string key=NULL] ) [string] Returns the name of the next key or NULL if there is no valid next key. If
the input key is NULL, returns the first key.
remove( string key ) [int] Removes the hash item by its key. Returns MS_SUCCESS or MS_FAILURE.
set( string key, string value ) [int] Sets a hash item. Returns MS_SUCCESS or MS_FAILURE.
imageObj
An image object is a wrapper for GD and GDAL images.
imageObj Attributes
format [outputFormatObj immutable] Image format.
height [int immutable] Image height in pixels.
imagepath [string immutable] If image is drawn by mapObj.draw(), this is the mapObj’s web.imagepath.
5.1. MapScript
269
MapServer Documentation, Release 7.0.6
imageurl [string immutable] If image is drawn by mapObj.draw(), this is the mapObj’s web.imageurl.
renderer [int] MS_RENDER_WITH_GD, MS_RENDER_WITH_SWF, MS_RENDER_WITH_RAWDATA,
MS_RENDER_WITH_PDF, or MS_RENDER_WITH_IMAGEMAP. Don’t mess with this!
size [int immutable] To access this attribute use the getSize method.
Note: the getSize method is inefficient as it does a call to getBytes and then computes the size of the byte array.
The bytearray is then immediately discarded. In most cases it is more efficient to call getBytes directly.
width [int immutable] Image width in pixels.
imageObj Methods
new imageObj( int width, int height [, outputFormatObj format=NULL [, string filename=NULL ] ] )
[imageObj] Create new instance of imageObj. If filename is specified, an imageObj is created from the
file and any specified width, height, and format parameters will be overridden by values of the image in
filename. Otherwise, if format is specified an imageObj is created using that format. See the format attribute
above for details. If filename is not specified, then width and height should be specified.
getBytes() [binary data] Returns the image contents as a binary buffer. The exact form of this buffer will vary by
mapscript language (eg. string in Python, byte[] array in Java and C#, unhandled in perl)
getSize() [int] Resturns the size of the binary buffer representing the image buffer.
Note: the getSize method is inefficient as it does a call to getBytes and then computes the size of the byte array.
The byte array is then immediately discarded. In most cases it is more efficient to call getBytes directly.
save( string filename [, mapObj parent_map=NULL ] ) [int] Save image to filename. The optional parent_map parameter must be specified if saving GeoTIFF images.
write( [ FILE file=NULL ] ) [int] Write image data to an open file descriptor or, by default, to stdout. Returns
MS_SUCCESS or MS_FAILURE.
Note: This method is current enabled for Python and C# only. C# supports writing onto a Stream object.
User-contributed typemaps are needed for Perl, Ruby, and Java.
Note: The free() method of imageObj has been deprecated. In MapServer revisions 4+ all instances of imageObj will
be properly disposed of by the interpreter’s garabage collector. If the application can’t wait for garabage collection,
then the instance can simply be deleted or undef’d.
intarray
An intarray is a utility class generated by SWIG useful for manipulating map layer drawing order.
See mapObj::getLayersDrawingOrder for discussion of mapscript use and see
http://www.swig.org/Doc1.3/Library.html#Library_nn5 for a complete reference.
5.1. MapScript
270
MapServer Documentation, Release 7.0.6
intarray Attributes
None
intarray Methods
new intarray( int numitems ) [intarray] Returns a new instance of the specified length.
labelCacheMemberObj
An individual feature label. The labelCacheMemberObj class is associated with labelCacheObj:
+------------------+ 0..*
1 +------------+
| LabelCacheMember | <--------- | LabelCache |
+------------------+
+------------+
labelCacheMemberObj Attributes
classindex [int immutable] Index of the class of the labeled feature.
featuresize [float immutable] TODO
label [labelObj immutable] Copied from the class of the labeled feature.
layerindex [int immutable] The index of the layer of the labeled feature.
numstyles [int immutable] Number of styles as for the class of the labeled feature.
point [pointObj immutable] Label point.
poly [shapeObj immutable] Label bounding box.
shapeindex [int immutable] Index within shapefile of the labeled feature.
status [int immutable] Has the label been drawn or not?
styles [styleObj immutable] TODO this should be protected from SWIG.
text [string immutable] Label text.
tileindex [int immutable] Tileindex of the layer of the labeled feature.
labelCacheMemberObj Methods
None.
Note: No real scripting control over labeling currently, but there may be some interesting new possibilities if users
have control over labeling text, position, and status.
5.1. MapScript
271
MapServer Documentation, Release 7.0.6
labelCacheObj
Set of a map’s cached labels. Has no other existence other than as a ‘labelcache’ attribute of a mapObj. Associated
with labelCacheMemberObj and markerCacheMemberObj:
+------------+ 1
0..* +-------------------+
| LabelCache | ---------> | LabelCacheMember |
+------------+
+ ----------------- +
| MarkerCacheMember |
+-------------------+
labelCacheObj Attributes
cachesize [int immutable] TODO
markercachesize [int immutable] TODO
numlabels [int immutable] Number of label members.
nummarkers [int immutable] Number of marker members.
labelCacheObj Methods
freeCache( ) [void] Free the labelcache.
labelObj
A labelObj is associated with a classObj, a scalebarObj, or a legendObj:
+-------+ 0..1
1 +----------+
| Label | <--------- | Scalebar |
+-------+
| -------- |
| Legend
|
+----------+
+-------+ 0..*
1 +-------+
| Label | <--------- | Class |
+-------+
+-------+
An instance of labelObj can exist outside of a classObj container and be explicitly inserted into the classObj:
new_label = new labelObj()
the_class.addLabel(new_label)
labelObj Attributes
angle [float] TODO
antialias [int] MS_TRUE or MS_FALSE
autoangle [int] MS_TRUE or MS_FALSE
autofollow [int] MS_TRUE or MS_FALSE. Tells mapserver to compute a curved label for appropriate linear features
(see rfc11 for specifics).
5.1. MapScript
272
MapServer Documentation, Release 7.0.6
autominfeaturesize: int MS_TRUE or MS_FALSE
backgroundcolor [colorObj] Color of background rectangle or billboard.
Deprecated since version 6.0: Use styleObj and geomtransform.
backgroundshadowcolor [colorObj] Color of background rectangle or billboard shadow.
Deprecated since version 6.0: Use styleObj and geomtransform.
backgroundshadowsizex [int] Horizontal offset of drop shadow in pixels.
Deprecated since version 6.0: Use styleObj and geomtransform.
backgroundshadowsizey [int] Vertical offset of drop shadow in pixels.
Deprecated since version 6.0: Use styleObj and geomtransform.
buffer [int] Maybe this should’ve been named ‘padding’ since that’s what it is: padding in pixels around a label.
color [colorObj] Foreground color.
encoding [string] Supported encoding format to be used for labels. If the format is not supported, the label will not
be drawn. Requires the iconv library (present on most systems). The library is always detected if present on the
system, but if not the label will not be drawn. Required for displaying international characters in MapServer.
More information can be found at: http://www.foss4g.org/FOSS4G/MAPSERVER/mpsnf-i18n-en.html.
font [string] Name of TrueType font.
force [int] MS_TRUE or MS_FALSE.
maxsize [int] Maximum height in pixels for scaled labels. See symbolscale attribute of layerObj.
mindistance [int] Minimum distance in pixels between duplicate labels.
minfeaturesize [int] Features of this size of greater will be labeled.
minsize [int] Minimum height in pixels.
numstyles [int] Number of label styles
offsetx [int] Horizontal offset of label.
offsety [int] Vertical offset of label.
outlinecolor [colorObj] Color of one point outline.
partials [int] MS_TRUE (default) or MS_FALSE. Whether or not labels can flow past the map edges.
position [int] MS_UL, MS_UC, MS_UR, MS_CL, MS_CC, MS_CR, MS_LL, MS_LC, MS_LR, or MS_AUTO.
shadowcolor [colorObj] Color of drop shadow.
shadowsizex [int] Horizontal offset of drop shadow in pixels.
shadowsizey [int] Vertical offset of drop shadow in pixels.
size [int] Annotation height in pixels.
type : removed in version 7.0. All labels are truetype.
wrap [string] Character on which legend text will be broken to make multi-line legends.
labelObj Methods
convertToString() [string] Saves the object to a string. Provides the inverse option for updateFromString.
New in version 6.4.
5.1. MapScript
273
MapServer Documentation, Release 7.0.6
getBinding( int binding ) [string] Get the attribute binding for a specified label property. Returns NULL if there is
no binding for this property.
getExpressionString( ) [string] Returns the label expression string.
getStyle( int index ) [styleObj] Return a reference to the styleObj at index in the styles array.
getTextString( ) [string] Returns the label text string.
insertStyle( styleObj style [, int index=-1 ] ) [int] Insert a copy of style into the styles array at index index. Default
is -1, or the end of the array. Returns the index at which the style was inserted.
moveStyleDown( int index ) [int] Swap the styleObj at index with the styleObj index + 1.
moveStyleUp( int index ) [int] Swap the styleObj at index with the styleObj index - 1.
removeBinding( int binding ) [int] Remove the attribute binding for a specfiled label property.
removeStyle( int index ) [styleObj] Remove the styleObj at index from the styles array and return a copy.
setBinding ( int binding, string item ) [int] Set the attribute binding for a specified label property. Binding constants
look like this: MS_LABEL_BINDING_[attribute name]:
setBinding(MS_LABEL_BINDING_COLOR, "FIELD_NAME_COLOR");
setExpression( string expression ) [int] Set the label expression.
setText( string text ) [int] Set the label text.
updateFromString ( string snippet ) [int]
MS_SUCCESS/MS_FAILURE.
Update
a
label
from
a
string
snippet.
Returns
layerObj
A layerObj is associated with mapObj. In the most recent revision, an instance of layerObj can exist outside of a
mapObj:
+-------+ 0..* 0..1 +-----+
| Layer | <--------> | Map |
+-------+
+-----+
The other important association for layerObj is with classObj:
+-------+ 1
0..* +-------+
| Layer | <--------> | Class |
+-------+
+-------+
and hashTableObj:
+-------+ 1
1 +-----------+
| Layer | ---------> | HashTable |
+-------+
|
-|
| metadata |
+-----------+
layerObj Attributes
bandsitem [string] The attribute from the index file used to select the source raster band(s) to be used. Normally
NULL for default bands processing.
5.1. MapScript
274
MapServer Documentation, Release 7.0.6
classitem [string] The attribute used to classify layer data.
connection [string] Layer connection or DSN.
connectiontype [int] See MS_CONNECTION_TYPE in mapserver.h for possible values. When setting the connection type setConnectionType() should be used in order to initialize the layer vtable properly.
data [string] Layer data definition, values depend upon connectiontype.
debug [int] Enable debugging of layer. MS_ON or MS_OFF (default).
dump [int] Since 6.0, dump is not available anymore. metadata is used instead.
Switch to allow mapserver to return data in GML format. MS_TRUE or MS_FALSE. Default is MS_FALSE.
Deprecated since version 6.0: metadata is used instead.
extent [rectObj] optional limiting extent for layer features.
filteritem [string] Attribute defining filter.
footer [string] TODO
group [string] Name of a group of layers.
header [string] TODO
index [int immutable] Index of layer within parent map’s layers array.
labelangleitem [string] Attribute defining label angle.
labelcache [int] MS_ON or MS_OFF. Default is MS_ON.
labelitem [string] Attribute defining feature label text.
labelmaxscaledenom [float] Minimum scale at which layer will be labeled.
labelminscaledenom [float] Maximum scale at which layer will be labeled.
labelrequires [string] Logical expression.
labelsizeitem [string] Attribute defining label size.
map [mapObj immutable] Reference to parent map.
mask [string] Layer name for masking. (rfc79)
maxfeatures [int] Maximum number of layer features that will be drawn. For shapefile data this means the first N
features where N = maxfeatures.
maxscaledenom [float] Minimum scale at which layer will be drawn.
metadata [hashTableObj immutable] Layer metadata.
minscaledenom [float] Maximum scale at which layer will be drawn.
name [string] Unique identifier for layer.
numclasses [int immutable] Number of layer classes.
numitems [int immutable] Number of layer feature attributes (items).
numjoins [int immutable] Number of layer joins.
numprocessing [int immutable] Number of raster processing directives.
offsite [colorObj] transparent pixel value for raster layers.
5.1. MapScript
275
MapServer Documentation, Release 7.0.6
opacity [int] Layer opacity percentage in range [0, 100]. The special value of MS_GD_ALPHA (1000) indicates that
the alpha transparency of pixmap symbols should be honored, and should be used only for layers that use RGBA
pixmap symbols.
postlabelcache [int] MS_TRUE or MS_FALSE. Default is MS_FALSE.
requires [string] Logical expression.
sizeunits [int] Units of class size values. MS_INCHES, MS_FEET, MS_MILES, MS_NAUTICALMILES,
MS_METERS, MS_KILOMETERS, MS_DD or MS_PIXELS
status [int] MS_ON, MS_OFF, or MS_DEFAULT.
styleitem [string] Attribute defining styles.
symbolscaledenom [float] Scale at which symbols are default size.
template [string] Template file. Note that for historical reasons, the query attribute must be non-NULL for a layer to
be queryable.
tileindex [string] Layer index file for tiling support.
tileitem [string] Attribute defining tile paths.
tolerance [float] Search buffer for point and line queries.
toleranceunits [int] MS_INCHES, MS_FEET,
MS_KILOMETERS, MS_DD or MS_PIXELS
MS_MILES,
MS_NAUTICALMILES,
MS_METERS,
transform [int] Whether or not layer data is to be transformed to image units. MS_TRUE or MS_FALSE. Default is
MS_TRUE. Case of MS_FALSE is for data that are in image coordinates such as annotation points.
type [int] See MS_LAYER_TYPE in mapserver.h.
units [int] Units of the layer. See MS_UNITS in mapserver.h.
layerObj Methods
new layerObj( [ mapObj parent_map=NULL ] ) [layerObj] Create a new layerObj in parent_map. The layer index
of the new layerObj will be equal to the parent_map numlayers - 1. The parent_map arg is now optional and
Layers can exist outside of a Map.
addFeature( shapeObj shape ) [int] Add a new inline feature on a layer. Returns -1 on error. TODO: Is this similar
to inline features in a mapfile? Does it work for any kind of layer or connection type?
addProcessing( string directive ) [void] Adds a new processing directive line to a layer, similar to the PROCESSING
directive in a map file. Processing directives supported are specific to the layer type and underlying renderer.
applySLD( string sld, string stylelayer ) [int] Apply the SLD document to the layer object. The matching between
the sld document and the layer will be done using the layer’s name. If a namedlayer argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the layer. See SLD HOWTO
for more information on the SLD support.
applySLDURL( string sld, string stylelayer ) [int] Apply the SLD document pointed by the URL to the layer object.
The matching between the sld document and the layer will be done using the layer’s name. If a namedlayer
argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the
layer. See SLD HOWTO for more information on the SLD support.
clearProcessing() [int] Clears the layer’s raster processing directives. Returns the subsequent number of directives,
which will equal MS_SUCCESS if the directives have been cleared.
clone() [layerObj] Return an independent copy of the layer with no parent map.
5.1. MapScript
276
MapServer Documentation, Release 7.0.6
close() [void] Close the underlying layer.
convertToString() [string] Saves the object to a string. Provides the inverse option for updateFromString.
New in version 6.4.
Note: demote() is removed in MapServer 4.4
draw( mapObj map, imageObj image ) [int] Renders this layer into the target image, adding labels to the cache if
required. Returns MS_SUCCESS or MS_FAILURE. TODO: Does the map need to be the map on which the
layer is defined? I suspect so.
drawQuery( mapObj map, imageObj image ) : Draw query map for a single layer into the target image. Returns
MS_SUCCESS or MS_FAILURE.
executeWFSGetFeature( layer ) [string] Executes a GetFeature request on a WFS layer and returns the name of the
temporary GML file created. Returns an empty string on error.
generateSLD() [void] Returns an SLD XML string based on all the classes found in the layer (the layer must have
STATUS on).
getClass( int i ) [classObj] Fetch the requested class object. Returns NULL if the class index is out of the legal range.
The numclasses field contains the number of classes available, and the first class is index 0.
getExtent() [rectObj] Fetches the extents of the data in the layer. This normally requires a full read pass through the
features of the layer and does not work for raster layers.
getFeature( int shapeindex [, int tileindex=-1 ] ) [shapeObj] Return the layer feature at shapeindex and tileindex.
Note: getFeature has been removed as of version 6.0 and replaced by getShape
getFilterString() [string] Returns the current filter expression.
getFirstMetaDataKey() [string] Returns the first key in the metadata hash table. With getNextMetaDataKey(), provides an opaque iterator over keys.
Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed
in a future version. Replaced by direct metadata access, see hashTableObj.
getItem( int i ) [string] Returns the requested item. Items are attribute fields, and this method returns the item name
(field name). The numitems field contains the number of items available, and the first item is index zero.
getMetaData( string key ) [string] Return the value at key from the metadata hash table.
Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed
in a future version. Replaced by direct metadata access, see hashTableObj.
getNextMetaDataKey( string lastkey ) [string] Returns the next key in the metadata hash table or NULL if lastkey
is the last valid key. If lastkey is NULL, returns the first key of the metadata hash table.
Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed
in a future version. Replaced by direct metadata access, see hashTableObj.
5.1. MapScript
277
MapServer Documentation, Release 7.0.6
getNumFeatures() [int] Returns the number of inline features in a layer. TODO: is this really only online features or
will it return the number of non-inline features on a regular layer?
getNumResults() [int] Returns the number of entries in the query result cache for this layer.
getProcessing( int index) [string] Return the raster processing directive at index.
getProjection( ) [string] Returns the PROJ.4 definition of the layer’s projection.
getResult( int i ) [resultCacheMemberObj] Fetches the requested query result cache entry, or NULL if the index is
outside the range of available results. This method would normally only be used after issuing a query operation.
getResults() [resultCacheObj] Returns a reference to layer’s result cache. Should be NULL prior to any query, or
after a failed query or query with no results.
getResultsBounds() [rectObj] Returns the bounds of the features in the result cache.
getShape( resultCacheMemberObj result ) [int] Get a shape from layer data. Argument is a result cache member
from layerObj::getResult(i)
getWMSFeatureInfoURL( mapObj map, int click_x, int click_y, int feature_count, string info_format ) [string]
Return a WMS GetFeatureInfo URL (works only for WMS layers) clickX, clickY is the location of to query
in pixel coordinates with (0,0) at the top left of the image. featureCount is the number of results to return.
infoFormat is the format the format in which the result should be requested. Depends on remote server’s
capabilities. MapServer WMS servers support only “MIME” (and should support “GML.1” soon). Returns “”
and outputs a warning if layer is not a WMS layer or if it is not queriable.
insertClass( classObj class [, int index=-1 ] ) [int] Insert a copy of the class into the layer at the requested index.
Default index of -1 means insertion at the end of the array of classes. Returns the index at which the class was
inserted.
isVisible( ) [int] Returns MS_TRUE or MS_FALSE after considering the layer status, minscaledenom, and maxscaledenom within the context of the parent map.
moveClassDown( int class ) [int] The class specified by the class index will be moved up into the array of layers.
Returns MS_SUCCESS or MS_FAILURE. ex. moveClassDown(1) will have the effect of moving class 1 down
to position 2, and the class at position 2 will be moved to position 1.
moveClassUp( int class ) [int] The class specified by the class index will be moved up into the array of layers. Returns MS_SUCCESS or MS_FAILURE. ex. moveClassUp(1) will have the effect of moving class 1 up to
position 0, and the class at position 0 will be moved to position 1.
nextShape( ) [shapeObj] Called after msWhichShapes has been called to actually retrieve shapes within a given area
returns a shape object or MS_FALSE
example of usage:
mapObj map = new mapObj("d:/msapps/gmap-ms40/htdocs/gmap75.map");
layerObj layer = map.getLayerByName('road');
int status = layer.open();
status = layer.whichShapes(map.extent);
shapeObj shape;
while ((shape = layer.nextShape()) != null)
{
...
}
layer.close();
open() [void] Opens the underlying layer. This is required before operations like getFeature() will work, but is not
required before a draw or query call.
5.1. MapScript
278
MapServer Documentation, Release 7.0.6
Note: promote() is eliminated in MapServer 4.4.
queryByAttributes( mapObj map, string qitem, string qstring, int mode ) [int] Query layer for shapes that intersect current map extents. qitem is the item (attribute) on which the query is performed, and qstring is the expression to match. The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE
value or that match any class in a layer that contains a LAYER TEMPLATE value.
Note that the layer’s FILTER/FILTERITEM are ignored by this function. Mode is MS_SINGLE or
MS_MULTIPLE depending on number of results you want. Returns MS_SUCCESS if shapes were found
or MS_FAILURE if nothing was found or if some other error happened.
queryByFeatures( mapObj map, int slayer ) [int] Perform a query set based on a previous set of results from another
layer. At present the results MUST be based on a polygon layer. Returns MS_SUCCESS if shapes were found
or MS_FAILURE if nothing was found or if some other error happened
queryByIndex( mapObj map, int shapeindex, int tileindex [, int bAddToQuery=MS_FALSE ]) [int] Pop a query
result member into the layer’s result cache. By default clobbers existing cache. Returns MS_SUCCESS or
MS_FAILURE.
queryByPoint( mapObj map, pointObj point, int mode, float buffer ) [int] Query layer at point location specified
in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a
CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE
value. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Passing buffer <=0
defaults to tolerances set in the map file (in pixels) but you can use a constant buffer (specified in ground units)
instead. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other
error happened.
queryByRect( mapObj map, rectObj rect ) [int] Query layer using a rectangle specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains
a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Returns
MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened.
queryByShape( mapObj map, shapeObj shape ) [int] Query layer based on a single shape, the shape has to be a
polygon at this point. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or
if some other error happened
removeClass( int index ) [classObj] Removes the class indicated and returns a copy, or NULL in the case of a failure.
Note that subsequent classes will be renumbered by this operation. The numclasses field contains the number
of classes available.
removeMetaData( string key ) [int] Delete the metadata hash at key. Returns MS_SUCCESS or MS_FAILURE.
Note: removeMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata
access, see hashTableObj.
resultsGetShape(int shapeindex [, int tileindex = -1]) [shapeObj] Retrieve shapeObj from a layer’s resultset by index. Tileindex is optional and is used only for tiled shapefiles, Simply omit or pass tileindex = -1 for other data
sources. Added in MapServer 5.6.0 due to the one-pass query implementation.
setConnectionType(int connectiontype, string library_str) [int] Changes the connectiontype of the layer and recreates the vtable according to the new connection type. This method should be used instead of setting the connectiontype parameter directly. In case when the layer.connectiontype = MS_PLUGIN the library_str parameter
should also be specified so as to select the library to load by mapserver. For the other connection types this
parameter is not used.
5.1. MapScript
279
MapServer Documentation, Release 7.0.6
setExtent( float minx, float miny, float maxx, float maxy ) [int] Sets the extent of a layer. Returns MS_SUCCESS
or MS_FAILURE.
setFilter( string filter ) [int] Sets a filter expression similarly to the FILTER expression in a map file. Returns
MS_SUCCESS on success or MS_FAILURE if the expression fails to parse.
setMetaData( string key, string value ) [int] Assign value to the metadata hash at key. Return MS_SUCCESS or
MS_FAILURE.
Note: setMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata access,
see hashTableObj.
setProcessingKey( string key, string value ) [void] Adds or replaces a processing directive of the form “key=value”.
Unlike the addProcessing() call, this will replace an existing processing directive for the given key value. Processing directives supported are specific to the layer type and underlying renderer.
setProjection( string proj4 ) [int] Set the layer projection using a PROJ.4 format projection definition (ie.
“+proj=utm +zone=11 +datum=WGS84” or “init=EPSG:26911”). Returns MS_SUCCESS or MS_FAILURE.
setWKTProjection( string wkt ) [int] Set the layer projection using OpenGIS Well Known Text format. Returns
MS_SUCCESS or MS_FAILURE.
whichShapes( rectObj rect ) [int] Performs a spatial, and optionally an attribute based feature search. The function
basically prepares things so that candidate features can be accessed by query or drawing functions (eg using
nextShape function). Returns MS_SUCCESS, MS_FAILURE or MS_DONE. MS_DONE is returned if the
layer extent does not overlap rect.
legendObj
legendObj is associated with mapObj:
+--------+ 0..1
1 +-----+
| Legend | <--------> | Map |
+--------+
+-----+
and with labelObj:
+--------+ 1
1 +-------+
| Legend | ---------> | Label |
+--------+
+-------+
legendObj Attributes
height [int] Legend height.
imagecolor [colorObj] Legend background color.
keysizex [int] Width in pixels of legend keys.
keysizey [int] Pixels.
keyspacingx [int] Horizontal padding around keys in pixels.
keyspacingy [int] Vertical padding.
label [labelObj immutable] legend label.
5.1. MapScript
280
MapServer Documentation, Release 7.0.6
map [mapObj immutable] Reference to parent mapObj.
outlinecolor [colorObj] key outline color.
position [int] MS_UL, MS_UC, MS_UR, MS_LL, MS_LC, or MS_LR.
postlabelcache [int] MS_TRUE or MS_FALSE.
status [int] MS_ON, MS_OFF, or MS_EMBED.
template [string] Path to template file.
width [int] Label width.
legendObj Methods
convertToString() [string] Saves the object to a string. Provides the inverse option for updateFromString.
New in version 6.4.
lineObj
A lineObj is composed of one or more pointObj instances:
+------+ 0..1 1..* +-------+
| Line | ---------> | Point |
+------+
+-------+
lineObj Attributes
numpoints [int immutable] Number of points in the line.
lineObj Methods
new lineObj( ) [lineObj] Create a new instance.
add(pointObj point) [int] Add point to the line. Returns MS_SUCCESS or MS_FAILURE.
get(int index) [pointObj] Return reference to point at index.
project(projectionObj proj_in, projectionObj proj_out) [int] Transform line in place from proj_in to proj_out. Returns MS_SUCCESS or MS_FAILURE.
set(int index, pointObj point) [int] Set the point at index to point. Returns MS_SUCCESS or MS_FAILURE.
mapObj
A mapObj is primarily associated with instances of layerObj:
+-----+ 0..1 0..* +-------+
| Map | <--------> | Layer |
+-----+
+-------+
Secondary associations are with legendObj, scalebarObj, referenceMapObj:
5.1. MapScript
281
MapServer Documentation, Release 7.0.6
+-----+ 1
0..1 +--------------+
| Map | ---------> | Legend
|
+-----+
| ------------ |
| Scalebar
|
| ------------ |
| ReferenceMap |
+--------------+
outputFormatObj:
+-----+ 1
1..* +--------------+
| Map | ---------> | OutputFormat |
+-----+
+------------- +
mapObj Attributes
cellsize [float] Pixel size in map units.
configoptions [hashObj immutable] A hash table of configuration options from CONFIG keywords in the .map. Direct access to config options is discouraged. Use the setConfigOption() and getConfigOption() methods instead.
datapattern [string] TODO not sure this is meaningful for mapscript.
debug [int] MS_TRUE or MS_FALSE.
extent [rectObj] Map’s spatial extent.
fontset [fontSetObj immutable] The map’s defined fonts.
height [int] Map’s output image height in pixels.
Note: direct setting of height is deprecated in MapServer version 4.4. Users should set width and height
simultaneously using setSize().
imagecolor [colorObj] Initial map background color.
imagequality [int] JPEG image quality.
Note: map imagequality is deprecated in MapServer 4.4 and should instead be managed through map outputformats.
imagetype [string immutable] Name of the current output format.
interlace [int] Output image interlacing.
Note: map interlace is deprecated in MapServer 4.4 and should instead be managed through map outputformats.
lablecache [labelCacheObj immutable] Map’s labelcache.
legend [legendObj immutable] Reference to map’s legend.
mappath [string] Filesystem path of the map’s mapfile.
maxsize [int] TODO ?
name [string] Unique identifier.
5.1. MapScript
282
MapServer Documentation, Release 7.0.6
numlayers [int immutable] Number of map layers.
numoutputformats [int] The number of output formats currently configured on the map object. Can be used to iterate
over the list of output formats with the getOutputFormat(idx) method (see below).
outputformat [outputFormatObj] The currently selected output format.
Note: Map outputformat should not be modified directly. Use the selectOutputFormat() method to select named
formats.
outputformatlist [outputFormatObj[]] Array of the available output formats.
Note: Currently only available for C#. A proper typemaps should be implemented for the other languages.
Note: As of 6.2 other languages can use the getoutputFormat(idx) and getNumoutputformats() functions to
iterate over the format array.
querymap [queryMapObj immutable] TODO should this be exposed to mapscript?
reference [referenceMapObj immutable] Reference to reference map.
resolution [float] Nominal DPI resolution. Default is 72.
scalebar [scalebarObj immutable] Reference to the scale bar.
scaledenom [float] The nominal map scale. A value of 25000 means 1:25000 scale.
shapepath [string] Base filesystem path to layer data.
status [int] MS_OFF, MS_ON, or MS_DEFAULT.
symbolset [symbolSetObj immutable] The map’s set of symbols.
templatepattern [string] TODO not sure this is meaningful for mapscript.
transparent [int] MS_TRUE or MS_FALSE.
Note: map transparent is deprecated in MapServer 4.4 and should instead be managed through map outputformats.
units [int] MS_DD, MS_METERS, etc.
web [webObj immutable] Reference to map’s web definitions.
width [int] Map’s output image width in pixels.
Note: direct setting of width is deprecated in MapServer version 4.4. Users should set width and height
simultaneously using setSize().
mapObj Methods
new mapObj( [ string filename=” ] ) [mapObj] Create a new instance of mapObj. Note that the filename is now
optional.
5.1. MapScript
283
MapServer Documentation, Release 7.0.6
appendOutputFormat( outputFormatObj format ) [int] Attach format to the map’s output format list. Returns the
updated number of output formats.
applyConfigOptions( ) [void] Apply the defined configuration options set by setConfigOption().
applySLD( string sldxml ) [int] Parse the SLD XML string sldxml and apply to map layers. Returns MS_SUCCESS
or MS_FAILURE.
applySLDURL( string sldurl ) [int] Fetch SLD XML from the URL sldurl and apply to map layers. Returns
MS_SUCCESS or MS_FAILURE.
clone( ) [mapObj] Returns a independent copy of the map, less any caches.
Note: In the Java module this method is named ‘cloneMap’.
convertToString() [string] Saves the object to a string.
Note: The inverse method updateFromString does not exist for the mapObj
New in version 6.4.
draw( ) [imageObj] Draw the map, processing layers according to their defined order and status. Return an imageObj.
drawLabelCache( imageObj image ) [int] Draw map’s label cache on image.
MS_FAILURE.
Returns MS_SUCCESS or
drawLegend( ) [imageObj] Draw map legend, returning an imageObj.
drawQuery( ) [imageObj] Draw query map, returning an imageObj.
drawReferenceMap( ) [imageObj] Draw reference map, returning an imageObj.
drawScalebar( ) [imageObj] Draw scale bar, returning an imageObj.
embedLegend( imageObj image ) [int] Embed map’s legend in image. Returns MS_SUCCESS or MS_FAILURE.
embedScalebar( imageObj image ) [int] Embed map’s scalebar in image.
MS_FAILURE.
Returns MS_SUCCESS or
freeQuery( [ int qlayer=-1 ] ) [void] Clear layer query result caches. Default is -1, or all layers.
generateSLD( ) [string] Return SLD XML as a string for map layers that have STATUS on.
getConfigOption( string key ) [string] Fetches the value of the requested configuration key if set. Returns NULL if
the key is not set.
getFirstMetaDataKey( ) [string] Returns the first key in the web.metadata hash table. With getNextMetaDataKey( ),
provides an opaque iterator over keys.
getLabel( int labelindex ) [labelCacheMemberObj] Return label at specified index from the map’s labelcache.
getLayer( int index ) [layerObj] Returns a reference to the layer at index.
getLayerByName( string name ) [layerObj] Returns a reference to the named layer.
getLayersDrawingOrder( ) [int*] Returns an array of layer indexes in drawing order.
Note: Unless the proper typemap is implemented for the module’s language a user is more likely to get back
an unusable SWIG pointer to the integer array.
getMetaData( string key ) [string] Return the value at key from the web.metadata hash table.
5.1. MapScript
284
MapServer Documentation, Release 7.0.6
getNextMetaDataKey( string lastkey ) [string] Returns the next key in the web.metadata hash table or NULL if
lastkey is the last valid key. If lastkey is NULL, returns the first key of the metadata hash table.
getNumSymbols( ) [int] Return the number of symbols in map.
getOutputFormat(int i): outputFormatObj Returns the output format at the specified i index from the output formats array or null if i is beyond the array bounds. The number of outpuFormats can be retrieved by calling
getNumoutputformats.
getOutputFormatByName( string imagetype ) [outputFormatObj] Return the output format corresponding to
driver name imagetype or to format name imagetype. This works exactly the same as the IMAGETYPE directive in a mapfile, is case insensitive and allows an output format to be found either by driver (like ‘GD/PNG’)
or name (like ‘PNG24’).
getProjection( ) [string] Returns the PROJ.4 definition of the map’s projection.
getSymbolByName( string name ) [int] Return the index of the named symbol in the map’s symbolset.
Note: This method is poorly named and too indirect. It is preferable to use the getSymbolByName method of
symbolSetObj, which really does return a symbolObj reference, or use the index method of symbolSetObj to
get a symbol’s index number.
insertLayer( layerObj layer [, int nIndex=-1 ] ) [int] Insert a copy of layer into the Map at index nIndex. The default value of nIndex is -1, which means the last possible index. Returns the index of the new Layer, or -1 in the
case of a failure.
loadMapContext( string filename [, int useUniqueNames=MS_FALSE ] ) [int] Load an OGC map context file to
define extents and layers of a map.
loadOWSParameters( OWSRequest request [, string version=‘1.1.1’ ] ) [int] Load OWS request parameters
(BBOX, LAYERS, &c.) into map. Returns MS_SUCCESS or MS_FAILURE.
loadQuery( string filename ) [int] Load a saved query. Returns MS_SUCCESS or MS_FAILURE.
moveLayerDown( int layerindex ) [int] Move the layer at layerindex down in the drawing order array, meaning that
it is drawn later. Returns MS_SUCCESS or MS_FAILURE.
moveLayerUp( int layerindex ) [int] Move the layer at layerindex up in the drawing order array, meaning that it is
drawn earlier. Returns MS_SUCCESS or MS_FAILURE.
nextLabel( ) [labelCacheMemberObj] Return the next label from the map’s labelcache, allowing iteration over labels.
Note: nextLabel() is deprecated and will be removed in a future version. Replaced by getLabel().
OWSDispatch( OWSRequest req ) [int] Processes and executes the passed OpenGIS Web Services request on the
map. Returns MS_DONE (2) if there is no valid OWS request in the req object, MS_SUCCESS (0) if an OWS
request was successfully processed and MS_FAILURE (1) if an OWS request was not successfully processed.
OWS requests include WMS, WFS, WCS and SOS requests supported by MapServer. Results of a dispatched
request are written to stdout and can be captured using the msIO services (ie. msIO_installStdoutToBuffer() and
msIO_getStdoutBufferString())
prepareImage( ) [imageObj] Returns an imageObj initialized to map extents and outputformat.
prepareQuery( ) [void] TODO this function only calculates the scale or am I missing something?
processLegendTemplate( string names[], string values[], int numitems ) [string] Process MapServer legend template and return HTML.
5.1. MapScript
285
MapServer Documentation, Release 7.0.6
Note: None of the three template processing methods will be usable unless the proper typemaps are implemented in the module for the target language. Currently the typemaps are not implemented.
processQueryTemplate( string names[], string values[], int numitems ) [string] Process MapServer query template and return HTML.
Note: None of the three template processing methods will be usable unless the proper typemaps are implemented in the module for the target language. Currently the typemaps are not implemented.
processTemplate( int generateimages, string names[], string values[], int numitems ) [string] Process MapServer
template and return HTML.
Note: None of the three template processing methods will be usable unless the proper typemaps are implemented in the module for the target language. Currently the typemaps are not implemented.
queryByFeatures( int layerindex ) [int] Query map layers, result sets contain features that intersect or are contained within the features in the result set of the MS_LAYER_POLYGON type layer at layerindex. Returns
MS_SUCCESS or MS_FAILURE.
queryByPoint( pointObj point, int mode, float buffer ) [int] Query map layers, result sets contain one or more
features, depending on mode, that intersect point within a tolerance buffer. Returns MS_SUCCESS or
MS_FAILURE.
queryByRect( rectObj rect ) [int] Query map layers, result sets contain features that intersect or are contained within
rect. Returns MS_SUCCESS or MS_FAILURE.
queryByShape( shapeObj shape ) [int] Query map layers, result sets contain features that intersect or are contained
within shape. Returns MS_SUCCESS or MS_FAILURE.
removeLayer( int index ) [int] Remove the layer at index.
removeMetaData( string key ) [int] Delete the web.metadata hash at key.
MS_FAILURE.
Returns MS_SUCCESS or
removeOutputFormat( string name ) [int] Removes the format named name from the map’s output format list. Returns MS_SUCCESS or MS_FAILURE.
save( string filename ) [int] Save map to disk as a new map file. Returns MS_SUCCESS or MS_FAILURE.
saveMapContext( string filename ) [int] Save map definition to disk as OGC-compliant XML. Returns
MS_SUCCESS or MS_FAILURE.
saveQuery( string filename ) [int] Save query to disk. Returns MS_SUCCESS or MS_FAILURE.
saveQueryAsGML( string filename ) [int] Save query to disk. Returns MS_SUCCESS or MS_FAILURE.
selectOutputFormat( string imagetype ) [void] Set the map’s active output format to the internal format named
imagetype. Built-in formats are “PNG”, “PNG24”, “JPEG”, “GIF”, “GTIFF”.
setConfigOption( string key, string value ) [void] Set the indicated key configuration option to the indicated value.
Equivalent to including a CONFIG keyword in a map file.
setExtent( float minx, float miny, float maxx, float maxy ) [int] Set the map extent, returns MS_SUCCESS
or MS_FAILURE. This method will correct the extents (width/height ratio) before setting the
minx,miny,maxx,maxy values. See extent properties to set up a custom extent from rectObj.
5.1. MapScript
286
MapServer Documentation, Release 7.0.6
offsetExtent( float x, float y) [int] Offset the map extent based on the given distances in map coordinates, returns
MS_SUCCESS or MS_FAILURE.
scaleExtent( float zoomfactor, float minscaledenom, float maxscaledenom) [int] Scale the map extent using the
zoomfactor and ensure the extent within the minscaledenom and maxscaledenom domain. If minscaledenom and/or maxscaledenom is 0 then the parameter is not taken into account. returns MS_SUCCESS or
MS_FAILURE.
setCenter( pointObj center ) [int] Set the map center to the given map point, returns MS_SUCCESS or
MS_FAILURE.
setFontSet( string filename ) [int] Load fonts defined in filename into map fontset. The existing fontset is cleared.
Returns MS_SUCCESS or MS_FAILURE.
setImageType( string name ) [void] Sets map outputformat to the named format.
Note: setImageType() remains in the module but it’s use is deprecated in favor of selectOutputFormat().
setLayersDrawingOrder( int layerindexes[]) [int] Set map layer drawing order.
Note: Unless the proper typemap is implemented for the module’s language users will not be able to pass
arrays or lists to this method and it will be unusable.
setMetaData( string key, string value ) [int] Assign value to the web.metadata hash at key. Return MS_SUCCESS
or MS_FAILURE.
setOutputFormat( outputFormatObj format ) [void] Sets map outputformat.
setProjection( string proj4 ) [int] Set map projection from PROJ.4 definition string proj4.
setRotation( float rotation_angle ) [int] Set map rotation angle. The map view rectangle (specified in EXTENTS)
will be rotated by the indicated angle in the counter- clockwise direction. Note that this implies the rendered
map will be rotated by the angle in the clockwise direction. Returns MS_SUCCESS or MS_FAILURE.
setSize( int width, int height ) [int] Set map’s image width and height together and carry out the necessary subsequent geotransform computation. Returns MS_SUCCESS or MS_FAILURE.
setSymbolSet( string filename ) [int] Load symbols defined in filename into map symbolset. The existing symbolset
is cleared. Returns MS_SUCCESS or MS_FAILURE.
setWKTProjection( string wkt ) [int] Sets map projection from OGC definition wkt.
zoomPoint( int zoomfactor, pointObj imgpoint, int width, int height, rectObj extent, rectObj maxextent ) [int]
Zoom by zoomfactor to imgpoint in pixel units within the image of height and width dimensions and
georeferenced extent. Zooming can be constrained to a maximum maxextent. Returns MS_SUCCESS or
MS_FAILURE.
zoomRectangle( rectObj imgrect, int width, int height, rectObj extent, rectObj maxextent ) : int Zoom to a pixel
coordinate rectangle in the image of width and height dimensions and georeferencing extent. Zooming can be
constrained to a maximum maxextent. The imgrect rectangle contains the coordinates of the LL and UR coordinates in pixel: the maxy in the rect object should be < miny value. Returns MS_SUCCESS or MS_FAILURE:
------- UR (values in the rect object : maxx, maxy)
|
|
|
|
|
|
-----LL (values in the rectobject minx, miny)
5.1. MapScript
287
MapServer Documentation, Release 7.0.6
zoomScale( float scale, pointObj imgpoint, int width, int height, rectObj extent, rectObj maxextent) [int]
the previous methods, but zooms to the point at a specified scale.
Like
markerCacheMemberObj
An individual marker. The markerCacheMemberObj class is associated with labelCacheObj:
+------------------+ 0..*
1 +------------+
| MarkerCacheMember | <--------- | LabelCache |
+------------------+
+------------+
markerCacheMemberObj Attributes
id [int immutable] Id of the marker.
poly [shapeObj immutable] Marker bounding box.
markerCacheMemberObj Methods
None.
outputFormatObj
An outputFormatObj is associated with a mapObj:
+--------------+ 1..*
1 +-----+
| OutputFormat | <--------- | Map |
+--------------+
+-----+
and can also be an attribute of an imageObj.
outputFormatObj Attributes
bands [int] The number of bands in the raster. Only used for the “raw” modes, MS_IMAGEMODE_BYTE,
MS_IMAGEMODE_INT16, and MS_IMAGEMODE_FLOAT32. Normally set via the BAND_COUNT formatoption ... this field should be considered read-only.
driver [string] A string such as ‘GD/PNG’ or ‘GDAL/GTiff’.
extension [string] Format file extension such as ‘png’.
imagemode [int]
MS_IMAGEMODE_PC256,
MS_IMAGEMODE_RGB,
MS_IMAGEMODE_RGBA,
MS_IMAGEMODE_INT16,
MS_IMAGEMODE_FLOAT32,
MS_IMAGEMODE_BYTE,
or
MS_IMAGEMODE_NULL.
mimetype [string] Format mimetype such as ‘image/png’.
name [string] A unique identifier.
numformatoptions: int The number of option values set on this format. Can be used to iterate over the options array
in conjunction with getOptionAt
5.1. MapScript
288
MapServer Documentation, Release 7.0.6
renderer [int] MS_RENDER_WITH_GD, MS_RENDER_WITH_SWF, MS_RENDER_WITH_RAWDATA,
MS_RENDER_WITH_PDF, or MS_RENDER_WITH_IMAGEMAP. Normally set internally based on the
driver and some other setting in the constructor.
transparent [int] MS_ON or MS_OFF.
outputFormatObj Methods
new outputFormatObj( string driver [, string name=driver ] ) [outputFormatObj] Create new instance. If name is
not provided, the value of driver is used as a name.
getOption( string key [, string defaultvalue=”” ] ) [string] Return the format option at key or defaultvalue if key is
not a valid hash index.
getOptionAt(int idx): string Returns the option at idx or null if the index is beyond the array bounds. The option
is returned as the original KEY=VALUE string. The number of available options can be obtained by calling
getNumformatoptions.
setExtension( string extension ) [void] Set file extension for output format such as ‘png’ or ‘jpg’. Method could
probably be deprecated since the extension attribute is mutable.
setMimetype( string mimetype ) [void] Set mimetype for output format such as ‘image/png’ or ‘image/jpeg’.
Method could probably be deprecated since the mimetype attribute is mutable.
setOption( string key, string value ) [void] Set the format option at key to value. Format options are mostly driver
specific.
validate() [int] Checks some internal consistency issues, and returns MS_TRUE if things are OK and MS_FALSE if
there are problems. Some problems are fixed up internally. May produce debug output if issues encountered.
OWSRequest
Not associated with other mapscript classes. Serves as a message intermediary between an application and
MapServer’s OWS capabilities. Using it permits creation of lightweight WMS services:
wms_map = mapscript.mapObj('wms.map')
wms_request = mapscript.OWSRequest()
# Convert application request parameters (req.args)
for param, value in req.args.items():
wms_request.setParam(param, value)
# Map loads parameters from OWSRequest, adjusting its SRS, extents,
# active layers accordingly
wms_map.loadWMSRequest('1.1.0', wms_request)
# Render the Map
img = wms_map.draw()
OWSRequest Attributes
NumParams [int immutable] Number of request parameters. Eventually should be changed to numparams lowercase
like other attributes.
postrequest [string] TODO
5.1. MapScript
289
MapServer Documentation, Release 7.0.6
type [int] MS_GET_REQUEST or MS_POST_REQUEST.
OWSRequest Methods
new OWSRequest( ) [OWSRequest] Create a new instance.
Note: MapServer’s OWSRequest supports only single valued parameters.
addParameter( string name, string value ) [void] Add a request parameter, even if the parameter key was previousely set. This is useful when multiple parameters with the same key are required. For example:
request.addParameter('SIZE', 'x(100)')
request.addParameter('SIZE', 'y(100)')
getName( int index ) [string] Return the name of the parameter at index in the request’s array of parameter names.
getValue( int index ) [string] Return the value of the parameter at index in the request’s array of parameter values.
getValueByName( string name) [string] Return the value associated with the parameter name.
loadParams() [int] Initializes the OWSRequest object from the cgi environment variables REQUEST_METHOD,
QUERY_STRING and HTTP_COOKIE. Returns the number of name/value pairs collected. Warning: most
errors will result in a process exit!
loadParamsFromURL( string url ) [int] Initializes the OWSRequest object from the provided URL which is treated
like a QUERY_STRING. Note that REQUEST_METHOD=GET and no post data is assumed in this case. This
method was added in MapServer 6.0.
setParameter( string name, string value ) [void] Set a request parameter. For example:
request.setParameter('REQUEST', 'GetMap')
request.setParameter('BBOX', '-107.0,40.0,-106.0,41.0')
pointObj
A pointObj instance may be associated with a lineObj:
+-------+ 1..* 0..1 +------+
| Point | <--------- | Line |
+-------+
+------+
pointObj Attributes
m [float] Measure. Meaningful only for measured shapefiles. Given value -2e38 if not otherwise assigned to indicate
“nodata”.
x [float] Easting
y [float] Northing
z [float] Elevation
5.1. MapScript
290
MapServer Documentation, Release 7.0.6
pointObj Methods
new pointObj( [ float x=0.0, float y=0.0, float z=0.0, float m=-2e38 ] ) [pointObj] Create new instance. Easting,
northing, and measure arguments are optional.
distanceToPoint( pointObj point ) [float] Returns the distance to point.
distanceToSegment( pointObj point1, pointObj point2 ) [float] Returns the minimum distance to a hypothetical
line segment connecting point1 and point2.
distanceToShape( shapeObj shape ) [float] Returns the minimum distance to shape.
draw( mapObj map, layerObj layer, imageObj image, int classindex, string text ) [int] Draw the point using the
styles defined by the classindex class of layer and labeled with string text. Returns MS_SUCCESS or
MS_FAILURE.
project( projectionObj proj_in, projectionObj proj_out ) [int] Reproject point from proj_in to proj_out. Transformation is done in place. Returns MS_SUCCESS or MS_FAILURE.
setXY( float x, float y [, float m=2e-38 ] ) [int] Set spatial coordinate and, optionally, measure values simultaneously.
The measure will be set only if the value of m is greater than the ESRI measure no-data value of 1e-38. Returns
MS_SUCCESS or MS_FAILURE.
setXYZ( float x, float y, float z [, float m=-2e38 ] ) [int] Set spatial coordinate and, optionally, measure values simultaneously. The measure will be set only if the value of m is greater than the ESRI measure no-data value of
-1e38. Returns MS_SUCCESS or MS_FAILURE.
setXYZM( float x, float y, float z, float m ) [int] Set spatial coordinate and, optionally, measure values simultaneously. The measure will be set only if the value of m is greater than the ESRI measure no-data value of -1e38.
Returns MS_SUCCESS or MS_FAILURE.
toShape() [shapeObj] Convience method to quickly turn a point into a shapeObj.
toString() [string] Return a string formatted like:
{ 'x': %f , 'y': %f, 'z': %f }
with the coordinate values substituted appropriately. Python users can get the same effect via the pointObj
__str__ method:
>>> p = mapscript.pointObj(1, 1)
>>> str(p)
{ 'x': 1.000000 , 'y': 1.000000, 'z': 1.000000 }
projectionObj
This class is not really fully implemented yet. MapServer’s Maps and Layers have Projection attributes, and these
are C projectionObj structures, but are not directly exposed by the mapscript module. Currently we have to do some
round-a-bout logic like this:
point.project(projectionObj(mapobj.getProjection(),
projectionObj(layer.getProjection())
to project a point from map to layer reference system.
5.1. MapScript
291
MapServer Documentation, Release 7.0.6
projectionObj Attributes
numargs [int immutable] Number of PROJ.4 arguments.
projectionObj Methods
new projectionObj( string proj4 ) [projectionObj] Create new instance of projectionObj. Input parameter proj4 is a
PROJ.4 definition string such as “init=EPSG:4269”.
getUnits() [int] Returns the units of a projection object. Returns -1 on error.
rectObj
A rectObj may be a lone object or an attribute of another object and has no other associations.
rectObj Attributes
maxx [float] Maximum easting
maxy [float] Maximum northing
minx [float] Minimum easting
miny [float] Minimum northing
rectObj Methods
new rectObj( [ float minx=-1.0, float miny=-1.0, float maxx=-1.0, float maxy=-1.0, int imageunits=MS_FALSE ] )
[rectObj] Create new instance. The four easting and northing arguments are optional and default to -1.0. Note
the new optional fifth argument which allows creation of rectangles in image (pixel/line) units which are also
tested for validity.
draw( mapObj map, layerObj layer, imageObj img, int classindex, string text ) [int] Draw rectangle into img using style defined by the classindex class of layer. The rectangle is labeled with the string text. Returns
MS_SUCCESS or MS_FAILURE.
getCenter() [pointObj] Return the center point of the rectagle.
project( projectionObj proj_in, projectionObj proj_out ) [int] Reproject rectangle from proj_in to proj_out. Transformation is done in place. Returns MS_SUCCESS or MS_FAILURE.
toPolygon() [shapeObj] Convert to a polygon of five vertices.
toString() [string] Return a string formatted like:
{ 'minx': %f , 'miny': %f , 'maxx': %f , 'maxy': %f }
with the bounding values substituted appropriately. Python users can get the same effect via the rectObj __str__
method:
>>> r = mapscript.rectObj(0, 0, 1, 1)
>>> str(r)
{ 'minx': 0 , 'miny': 0 , 'maxx': 1 , 'maxy': 1 }
5.1. MapScript
292
MapServer Documentation, Release 7.0.6
referenceMapObj
A referenceMapObj is associated with mapObj:
+--------------+ 0..1
1 +-----+
| ReferenceMap | <--------> | Map |
+--------------+
+-----+
referenceMapObj Attributes
color [colorObj] Color of reference box.
extent [rectObj] Spatial extent of reference in units of parent map.
height [int] Height of reference map in pixels.
image [string] Filename of reference map image.
map [mapObj immutable] Reference to parent mapObj.
marker [int] Index of a symbol in the map symbol set to use for marker.
markername [string] Name of a symbol.
markersize [int] Size of marker.
maxboxsize [int] Pixels.
minboxsize [int] Pixels.
outlinecolor [colorObj] Outline color of reference box.
status [int] MS_ON or MS_OFF.
width [int] In pixels.
referenceMapObj Methods
convertToString() [string] Saves the object to a string. Provides the inverse option for updateFromString.
New in version 6.4.
resultCacheMemberObj
Has no associations with other MapScript classes and has no methods. By using several indexes, a resultCacheMemberObj refers to a single layer feature.
resultCacheMemberObj Attributes
classindex [int immutable] The index of the layer class into which the feature has been classified.
shapeindex [int immutable] Index of the feature within the layer.
tileindex [int immutable] Meaningful for tiled layers only, index of the shapefile data tile.
5.1. MapScript
293
MapServer Documentation, Release 7.0.6
resultCacheObj
See querying-HOWTO.txt for extra guidance in using the new 4.4 query API.
resultCacheObj Attributes
bounds [rectObj immutable] Bounding box of query results.
numresults [int immutable] Length of result set.
resultCacheObj Methods
getResult( int i ) [resultCacheMemberObj] Returns the result at index i, like layerObj::getResult, or NULL if index
is outside the range of results.
scalebarObj
A scalebarObj is associated with mapObj:
+----------+ 0..1
1 +-----+
| Scalebar | <--------- | Map |
+----------+
+-----+
and also with labelObj:
+----------+ 1
1 +-------+
| Scalebar | ---------> | Label |
+----------+
+-------+
scalebarObj Attributes
backgroundcolor [colorObj] Scalebar background color.
color [colorObj] Scalebar foreground color.
height [int] Pixels.
imagecolor [colorObj] Background color of scalebar.
intervals [int] Number of intervals.
label [labelObj] Scalebar label.
outlinecolor [colorObj] Foreground outline color.
position [int] MS_UL, MS_UC, MS_UR, MS_LL, MS_LC, or MS_LR.
postlabelcache [int] MS_TRUE or MS_FALSE.
status [int] MS_ON, MS_OFF, or MS_EMBED.
style [int] 0 or 1.
units [int] See MS_UNITS in mapserver.h.
width [int] Pixels.
5.1. MapScript
294
MapServer Documentation, Release 7.0.6
scalebarObj Methods
convertToString() [string] Saves the object to a string. Provides the inverse option for updateFromString.
New in version 6.4.
shapefileObj
shapefileObj Attributes
bounds [rectObj] Extent of shapes.
numshapes [int] Number of shapes.
type [int] See mapshape.h for values of type.
shapefileObj Methods
new shapefileObj( string filename [, int type=-1 ] ) [shapefileObj] Create a new instance. Omit the type argument
or use a value of -1 to open an existing shapefile.
add( shapeObj shape ) [int] Add shape to the shapefile. Returns MS_SUCCESS or MS_FAILURE.
get( int i, shapeObj shape ) [int] Get the shapefile feature from index i and store it in shape. Returns MS_SUCCESS
or MS_FAILURE.
getShape( int i ) [shapeObj] Returns the shapefile feature at index i. More efficient than get.
TODO
shapeObj
Each feature of a layer’s data is a shapeObj. Each part of the shape is a closed lineObj:
+-------+ 1
1..* +------+
| Shape | --------> | Line |
+-------+
+------+
shapeObj Attributes
bounds [rectObj] Bounding box of shape.
classindex [int] The class index for features of a classified layer.
index [int] Feature index within the layer.
numlines [int immutable] Number of parts.
numvalues [int immutable] Number of shape attributes.
text [string] Shape annotation.
tileindex [int] Index of tiled file for tileindexed layers.
type [int] MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON, or MS_SHAPE_NULL.
5.1. MapScript
295
MapServer Documentation, Release 7.0.6
shapeObj Methods
new shapeObj( int type ) [shapeObj] Return a new shapeObj of the specified type. See the type attribute above. No
attribute values created by default. initValues should be explicitly called to create the required number of values.
add( lineObj line ) [int] Add line (i.e. a part) to the shape. Returns MS_SUCCESS or MS_FAILURE.
boundary() [shapeObj] Returns the boundary of the existing shape. Requires GEOS support. Returns NULL/undef
on failure.
buffer( int distance ) [shapeObj] Returns a new buffered shapeObj based on the supplied distance (given in the coordinates of the existing shapeObj). Requires GEOS support. Returns NULL/undef on failure.
clone() [shapeObj] Return an independent copy of the shape.
contains( pointObj point ) [int] Returns MS_TRUE if the point is inside the shape, MS_FALSE otherwise.
contains( shapeObj shape2 ) [int] Returns MS_TRUE if shape2 is entirely within the shape. Returns -1 on error and
MS_FALSE otherwise. Requires GEOS support.
convexHull() [shapeObj] Returns the convex hull of the existing shape.
NULL/undef on failure.
Requires GEOS support.
Returns
copy( shapeObj shape_copy ) [int] Copy the shape to shape_copy. Returns MS_SUCCESS or MS_FAILURE.
crosses( shapeObj shape2 ) [int] Returns MS_TRUE if shape2 crosses the shape.
MS_FALSE otherwise. Requires GEOS support.
Returns -1 on error and
difference( shapeObj shape ) [shapeObj] Returns the computed difference of the supplied and existing shape. Requires GEOS support. Returns NULL/undef on failure.
disjoint( shapeObj shape2 ) [int] Returns MS_TRUE if shape2 and the shape are disjoint. Returns -1 on error and
MS_FALSE otherwise. Requires GEOS support.
distanceToPoint( pointObj point ) [float] Return distance to point.
distanceToShape( shapeObj shape ) [float] Return the minimum distance to shape.
draw( mapObj map, layerObj layer, imageObj img ) [int] Draws the individual shape using layer.
MS_SUCCESS or MS_FAILURE.
Returns
equals( shapeObj shape2 ) [int] Returns MS_TRUE if the shape and shape2 are equal (geometry only). Returns -1
on error and MS_FALSE otherwise. Requires GEOS support.
fromWKT( char \*wkt ) [shapeObj] Returns a new shapeObj based on a well-known text representation of a geometry. Requires GEOS support. Returns NULL/undef on failure.
get( int index ) [lineObj] Returns a reference to part at index. Reference is valid only during the life of the shapeObj.
getArea() [double] Returns the area of the shape (if applicable). Requires GEOS support.
getCentroid() [pointObj] Returns the centroid for the existing shape. Requires GEOS support. Returns NULL/undef
on failure.
getLength() [double] Returns the length (or perimeter) of a shape. Requires GEOS support.
getValue( int i ) [string] Return the shape attribute at index i.
initValues( int numvalues ) [void] Allocates memory for the requested number of values.
intersects( shapeObj shape ) [int] Returns MS_TRUE if the two shapes intersect, MS_FALSE otherwise.
Note: Does not require GEOS support but will use GEOS functions if available.
5.1. MapScript
296
MapServer Documentation, Release 7.0.6
intersection( shapeObj shape ) [shapeObj] Returns the computed intersection of the supplied and existing shape.
Requires GEOS support. Returns NULL/undef on failure.
overlaps( shapeObj shape2 ) [int] Returns MS_TRUE if shape2 overlaps shape. Returns -1 on error and MS_FALSE
otherwise. Requires GEOS support.
project( projectionObj proj_in, projectionObj proj_out ) [int] Reproject shape from proj_in to proj_out. Transformation is done in place. Returns MS_SUCCESS or MS_FAILURE.
setBounds [void] Must be called to calculate new bounding box after new parts have been added.
TODO: should return int and set msSetError.
setValue( int i, string value ) [int] Set the shape value at index i to value.
simplify( double tolerance ): shapeObj Given a tolerance, returns a simplified shape object or NULL on error. Requires GEOS support (>=3.0).
symDifference( shapeObj shape ) [shapeObj] Returns the computed symmetric difference of the supplied and existing shape. Requires GEOS support. Returns NULL/undef on failure.
topologyPreservingSimplify( double tolerance ): shapeObj Given a tolerance, returns a simplified shape object or
NULL on error. Requires GEOS support (>=3.0).
touches( shapeObj shape2 ) [int] Returns MS_TRUE if the shape and shape2 touch. Returns -1 on error and
MS_FALSE otherwise. Requires GEOS support.
toWKT() [string] Returns the well-known text representation of a shapeObj. Requires GEOS support. Returns
NULL/undef on failure.
Union( shapeObj shape ) [shapeObj] Returns the union of the existing and supplied shape. Shapes must be of the
same type. Requires GEOS support. Returns NULL/undef on failure.
within( shapeObj shape2 ) [int] Returns MS_TRUE if the shape is entirely within shape2. Returns -1 on error and
MS_FALSE otherwise. Requires GEOS support.
styleObj
An instance of styleObj is associated with one instance of classObj:
+-------+ 0..*
1 +-------+
| Style | <-------- | Class |
+-------+
+-------+
An instance of styleObj can exist outside of a classObj container and be explicitly inserted into the classObj for use in
mapping:
new_style = new styleObj()
the_class.insertStyle(new_style)
It is important to understand that insertStyle inserts a copy of the styleObj instance, not a reference to the instance
itself.
The older use case:
new_style = new styleObj(the_class)
remains supported. These will be the only ways to access the styles of a class. Programmers should no longer directly
access the styles attribute.
5.1. MapScript
297
MapServer Documentation, Release 7.0.6
styleObj Attributes
angle [double] Angle, given in degrees, to draw the line work. Default is 0. For symbols of Type HATCH, this is the
angle of the hatched lines.
angleitem [string] Deprecated since version 5.0: Use setBinding.
backgroundcolor [colorObj] Background pen color.
color [colorObj] Foreground or fill pen color.
mincolor [colorObj] Attribute for Color Range Mapping (rfc6). mincolor, minvalue, maxcolor, maxvalue define the
range for mapping a continuous feature value to a continuous range of colors when rendering the feature on the
map.
minsize [int] Minimum pen or symbol width for scaling styles.
minvalue [double] Attribute for Color Range Mapping (rfc6). mincolor, minvalue, maxcolor, maxvalue define the
range for mapping a continuous feature value to a continuous range of colors when rendering the feature on the
map.
minwidth [int] Minimum width of the symbol.
maxcolor [colorObj] Attribute for Color Range Mapping (rfc6). mincolor, minvalue, maxcolor, maxvalue define the
range for mapping a continuous feature value to a continuous range of colors when rendering the feature on the
map.
maxsize [int] Maximum pen or symbol width for scaling.
maxvalue [double] Attribute for Color Range Mapping (rfc6). mincolor, minvalue, maxcolor, maxvalue define the
range for mapping a continuous feature value to a continuous range of colors when rendering the feature on the
map.
maxwidth [int] Maximum width of the symbol.
offsetx [int] Draw with pen or symbol offset from map data.
offsety [int] Draw with pen or symbol offset from map data.
outlinecolor [colorObj] Outline pen color.
pattern [array of double values] List of on, off values to define a dash pattern for line work (lines, polygon outlines,
hatch lines, ...)
patternlength [int] Number of elements in the pattern attribute.
rangeitem [string] Attribute/field that stores the values for the Color Range Mapping (rfc6).
size [int] Pixel width of the style’s pen or symbol.
sizeitem [string] Deprecated since version 5.0: Use setBinding.
symbol [int] The index within the map symbolset of the style’s symbol.
symbolname [string immutable] Name of the style’s symbol.
width [int] Width refers to the thickness of line work drawn, in pixels. Default is 1. For symbols of Type HATCH,
the with is how thick the hatched lines are.
styleObj Methods
new styleObj( [ classObj parent_class ] ) [styleObj] Returns new default style Obj instance. The parent_class is
optional.
5.1. MapScript
298
MapServer Documentation, Release 7.0.6
clone [styleObj] Returns an independent copy of the style with no parent class.
convertToString() [string] Saves the object to a string. Provides the inverse option for updateFromString.
New in version 6.4.
getBinding( int binding ) [string] Get the attribute binding for a specified style property. Returns NULL if there is
no binding for this property.
removeBinding( int binding ) [int] Remove the attribute binding for a specfiled style property.
setBinding ( int binding, string item ) [int] Set the attribute binding for a specified style property. Binding constants
look like this: MS_STYLE_BINDING_[attribute name]:
setBinding(MS_STYLE_BINDING_SIZE, 'mySizeItem');
setSymbolByName(mapObj map, string symbolname) [int] Setting the symbol of the styleObj given the reference
of the map object and the symbol name.
updateFromString ( string snippet ) [int]
MS_SUCCESS/MS_FAILURE.
Update
a
style
from
a
string
snippet.
Returns
symbolObj
A symbolObj is associated with one symbolSetObj:
+--------+ 0..*
1 +-----------+
| Symbol | <-------- | SymbolSet |
+--------+
+-----------+
A styleObj will often refer to a symbolObj by name or index, but this is not really an object association, is it?
symbolObj Attributes
antialias [int] MS_TRUE or MS_FALSE.
character [string] For TrueType symbols.
filled [int] MS_TRUE or MS_FALSE.
font [string] For TrueType symbols.
gap [int] Moved to STYLE
imagepath [string] Path to pixmap file.
inmapfile [int] If set to TRUE, the symbol will be saved inside the mapfile. Added in MapServer 5.6.1
linecap [int] Moved to STYLE
linejoin [int] Moved to STYLE
linejoinmaxsize [float] Moved to STYLE
name [string] Symbol name
numpoints [int immutable] Number of points of a vector symbol.
position [int] No more available?
sizex [float] TODO what is this?
sizey [float] TODO what is this?
5.1. MapScript
299
MapServer Documentation, Release 7.0.6
stylelength [int] Number of intervals
transparent [int] TODO what is this?
transparentcolor [int] TODO is this a derelict attribute?
type [int]
MS_SYMBOL_SIMPLE,
MS_SYMBOL_VECTOR,
MS_SYMBOL_PIXMAP, or MS_SYMBOL_TRUETYPE.
MS_SYMBOL_ELLIPSE,
symbolObj Methods
new symbolObj( string symbolname [, string imagefile ] ) [symbolObj] Create new default symbol named name.
If imagefile is specified, then the symbol will be of type MS_SYMBOL_PIXMAP.
getImage() [imageObj] Returns a pixmap symbol’s imagery as an imageObj.
getPoints() [lineObj] Returns the symbol points as a lineObj.
setImage( imageObj image ) [int] Set a pixmap symbol’s imagery from image.
setPoints( lineObj line ) [int] Sets the symbol points from the points of line. Returns the updated number of points.
setStyle( int index, int value ) [int] Set the style at index to value. Returns MS_SUCCESS or MS_FAILURE.
symbolSetObj
A symbolSetObj is an attribute of a mapObj and is associated with instances of symbolObj:
+-----------+ 1
0..* +--------+
| SymbolSet | --------> | Symbol |
+-----------+
+--------+
symbolSetObj Attributes
filename [string] Symbolset filename
numsymbols [int immutable] Number of symbols in the set.
symbolSetObj Methods
new symbolSetObj( [ string symbolfile ] ) [symbolSetObj] Create new instance. If symbolfile is specified, symbols
will be loaded from the file.
appendSymbol( symbolObj symbol ) [int] Add a copy of symbol to the symbolset and return its index.
getSymbol( int index ) [symbolObj] Returns a reference to the symbol at index.
getSymbolByName( string name ) [symbolObj] Returns a reference to the symbol named name.
index( string name ) [int] Return the index of the symbol named name or -1 in the case that no such symbol is found.
removeSymbol( int index ) [symbolObj] Remove the symbol at index and return a copy of the symbol.
save( string filename ) [int] Save symbol set to a file. Returns MS_SUCCESS or MS_FAILURE.
5.1. MapScript
300
MapServer Documentation, Release 7.0.6
webObj
Has no other existence than as an attribute of a mapObj. Serves as a container for various run-time web application
definitions like temporary file paths, template paths, etc.
webObj Attributes
empty [string] TODO
error [string] TODO
extent [rectObj] Clipping extent.
footer [string] Path to footer document.
header [string] Path to header document.
imagepath [string] Filesystem path to temporary image location.
imageurl [string] URL to temporary image location.
log [string] TODO
map [mapObj immutable] Reference to parent mapObj.
maxscaledenom [float] Minimum map scale.
maxtemplate [string] TODO
metadata [hashTableObj immutable] metadata hash table.
minscaledenom [float] Maximum map scale.
mintemplate [string] TODO
queryformat [string] TODO
template [string] Path to template document.
webObj Methods
convertToString() [string] Saves the object to a string. Provides the inverse option for updateFromString.
New in version 6.4.
5.1.3 PHP MapScript
Release 7.0.6
Introduction
This is a PHP module that makes MapServer’s MapScript functionalities available in a PHP Dynamically Loadable
Library. In simple terms, this module will allow you to use the powerful PHP scripting language to dynamically create
and modify map images in MapServer.
5.1. MapScript
301
MapServer Documentation, Release 7.0.6
Versions Supported
PHP 5.2.0 or more recent is required; since MapServer 6.0, support for PHP 4, PHP 5.0 and PHP 5.1 have been
dropped. PHP MapScript was originally developed for PHP 3.0.14, and after MapServer 3.5 support for PHP 3 was
dropped.
The module has been tested and used on Linux, Solaris, *BSD, and Windows.
Note: If you are using MapServer 5.6 and older, please refer to the PHP MapScript 5.6 documentation
instead.
Note: If you are migrating your existing application that is based on MapServer 5.6 or older, to
MapServer 6.0 or beyond, please read the PHP MapScript Migration Guide for important changes.
How to Get More Information on PHP MapScript
• For installation questions regarding the PHP MapScript module, see PHP MapScript Installation.
• The MapServer Wiki has information on this module, that was contributed by users.
• New PHP MapScript users should read the By Example document.
• The project’s home is the PHP/MapScript page on MapTools.org.
• Also, see the MapScript, and the Mapfile sections of this site.
• Refer to the main PHP site for their official documentation.
Memory Management
Normally, you should not have to worry about the memory management because php has a garbage collector and will
free resources for you. If you write only small scripts that don’t do a lot of processing, it’s not worth to care about
that. Everything will be freed at the end of the script.
However, it may be useful to free resources during the execution if the script executes many tasks. To do so, you’ll
have to call the free() method of the mapscript objects and unset the php variables. The purpose of the free methods is
to break the circular references between an object and its properties to allow the zend engine to free the resources.
Here’s an example of a script that doesn’t free things during the execution:
$map = new mapObj("mapfile.map");
$of = $map->outputformat;
echo $map->extent->minx." - ".$map->extent->miny." - ".
$map->extent->maxx." - ".$map->extent->maxy."\n";
echo "Outputformat name: $of->name\n";
unset($of);
unset($map); // Even if we unset the php variables, resources
// won't be freed. Resources will be only freed
// at the end of the script
and the same script that frees resources as soon as it can
5.1. MapScript
302
MapServer Documentation, Release 7.0.6
$map = new mapObj("mapfile.map");
$of = $map->outputformat;
echo $map->extent->minx." - ".$map->extent->miny." - ".
$map->extent->maxx." - ".$map->extent->maxy."\n";
echo "Outputformat name: $of->name\n";
unset($of);
$map->free(); // break the circular references
// at this place, the outputformat ($of) and the rect object
// ($map->extent) resources are freed
unset($map);
// the map object is immediately freed after the unset (before the
// end of the script)
PHP MapScript API
Author Daniel Morissette
Contact dmorissette at mapgears.com
Author Yewondwossen Assefa
Contact yassefa at dmsolutions.ca
Author Alan Boudreault
Contact aboudreault at mapgears.com
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Note: If you are using MapServer 5.6 and older, please refer to the PHP MapScript 5.6 documentation instead.
Warning: PHP 7 support is still in development; please follow along and contribute through
the associated ticket.
Contents
• PHP MapScript API
– Important Note
– Constants
– Functions
– Classes
* classObj
* clusterObj
* colorObj
* errorObj
5.1. MapScript
303
MapServer Documentation, Release 7.0.6
* gridObj
* hashTableObj
* imageObj
* labelcacheMemberObj
* labelcacheObj
* labelObj
* layerObj
* legendObj
* lineObj
* mapObj
* outputformatObj
* OwsrequestObj
* pointObj
* projectionObj
* querymapObj
* rectObj
* referenceMapObj
* resultObj
* scalebarObj
* shapefileObj
* shapeObj
* styleObj
* symbolObj
* webObj
Important Note
• Constant names and class member variable names are case-sensitive in PHP.
Constants
The following MapServer constants are available:
Boolean values MS_TRUE, MS_FALSE, MS_ON, MS_OFF, MS_YES, MS_NO
Map units MS_INCHES, MS_FEET, MS_MILES, MS_METERS, MS_KILOMETERS, MS_DD, MS_PIXELS,
MS_NAUTICALMILES
Layer types MS_LAYER_POINT, MS_LAYER_LINE, MS_LAYER_POLYGON, MS_LAYER_RASTER,
MS_LAYER_ANNOTATION (deprecated since 6.2), MS_LAYER_QUERY, MS_LAYER_CIRCLE,
MS_LAYER_TILEINDEX, MS_LAYER_CHART
5.1. MapScript
304
MapServer Documentation, Release 7.0.6
Layer/Legend/Scalebar/Class Status MS_ON, MS_OFF, MS_DEFAULT, MS_EMBED, MS_DELETE
Layer alpha transparency allows alpha transparent pixmaps to be used with RGB map images MS_GD_ALPHA
Label positions MS_UL, MS_LR, MS_UR, MS_LL, MS_CR, MS_CL, MS_UC, MS_LC, MS_CC, MS_XY,
MS_AUTO, MS_AUTO2, MS_FOLLOW, MS_NONE
Bitmap font styles MS_TINY , MS_SMALL, MS_MEDIUM, MS_LARGE, MS_GIANT
Shape types MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON, MS_SHAPE_NULL
Shapefile types MS_SHP_POINT, MS_SHP_ARC, MS_SHP_POLYGON, MS_SHP_MULTIPOINT
Query/join types MS_SINGLE, MS_MULTIPLE
Querymap styles MS_NORMAL, MS_HILITE, MS_SELECTED
Connection Types MS_INLINE,
MS_SHAPEFILE,
MS_TILED_SHAPEFILE,
MS_SDE,
MS_OGR,
MS_TILED_OGR, MS_POSTGIS, MS_WMS, MS_ORACLESPATIAL, MS_WFS, MS_GRATICULE,
MS_RASTER, MS_PLUGIN, MS_UNION
Error codes MS_NOERR, MS_IOERR, MS_MEMERR, MS_TYPEERR, MS_SYMERR, MS_REGEXERR,
MS_TTFERR, MS_DBFERR, MS_GDERR, MS_IDENTERR, MS_EOFERR, MS_PROJERR,
MS_MISCERR, MS_CGIERR, MS_WEBERR, MS_IMGERR, MS_HASHERR, MS_JOINERR,
MS_NOTFOUND, MS_SHPERR, MS_PARSEERR, MS_SDEERR, MS_OGRERR, MS_QUERYERR,
MS_WMSERR, MS_WMSCONNERR, MS_ORACLESPATIALERR, MS_WFSERR, MS_WFSCONNERR,
MS_MAPCONTEXTERR, MS_HTTPERR, MS_WCSERR
Symbol types MS_SYMBOL_SIMPLE,
MS_SYMBOL_VECTOR,
MS_SYMBOL_PIXMAP, MS_SYMBOL_TRUETYPE
MS_SYMBOL_ELLIPSE,
Image Mode types (outputFormatObj) MS_IMAGEMODE_PC256,
MS_IMAGEMODE_RGB,
MS_IMAGEMODE_RGBA,
MS_IMAGEMODE_INT16,
MS_IMAGEMODE_FLOAT32,
MS_IMAGEMODE_BYTE, MS_IMAGEMODE_FEATURE, MS_IMAGEMODE_NULL
Style/Attribue binding MS_STYLE_BINDING_SIZE,
MS_STYLE_BINDING_ANGLE,
MS_STYLE_BINDING_COLOR,
MS_STYLE_BINDING_OUTLINECOLOR,
MS_STYLE_BINDING_SYMBOL, MS_STYLE_BINDING_WIDTH
Label/Attribute binding MS_LABEL_BINDING_SIZE,
MS_LABEL_BINDING_ANGLE,
MS_LABEL_BINDING_COLOR,
MS_LABEL_BINDING_OUTLINECOLOR,
MS_LABEL_BINDING_FONT, MS_LABEL_BINDING_PRIORITY, MS_LABEL_BINDING_POSITION,
MS_LABEL_BINDING_SHADOWSIZEX, MS_LABEL_BINDING_SHADOWSIZEY
Alignment MS_ALIGN_LEFT, MS_ALIGN_CENTER, MS_ALIGN_RIGHT
OwsRequest MS_GET_REQUEST, MS_POST_REQUEST
Functions
string ms_GetVersion() Returns the MapServer version and options in a string. This string can be parsed to find out
which modules were compiled in, etc.
int ms_GetVersionInt() Returns the MapServer version number (x.y.z) as an integer (x*10000 + y*100 + z). (New
in v5.0) e.g. V5.4.3 would return 50403.
int ms_iogetStdoutBufferBytes() Writes the current buffer to stdout. The PHP header() function should be used to
set the documents’s content-type prior to calling the function. Returns the number of bytes written if output is
sent to stdout. See MapScript Wrappers for WxS Services for more info.
void ms_iogetstdoutbufferstring() Fetch the current stdout buffer contents as a string. This method does not clear
the buffer.
5.1. MapScript
305
MapServer Documentation, Release 7.0.6
void ms_ioinstallstdinfrombuffer() Installs a mapserver IO handler directing future stdin reading (ie. post request
capture) to come from a buffer.
void ms_ioinstallstdouttobuffer() Installs a mapserver IO handler directing future stdout output to a memory buffer.
void ms_ioresethandlers() Resets the default stdin and stdout handlers in place of “buffer” based handlers.
string ms_iostripstdoutbuffercontenttype() Strip the Content-type header off the stdout buffer if it has one, and if a
content type is found it is return. Otherwise return false.
void ms_iostripstdoutbuffercontentheaders() Strip all the Content-* headers off the stdout buffer if it has some.
array ms_TokenizeMap(string map_file_name) Preparses a mapfile through the MapServer parser and return an array with one item for each token from the mapfile. Strings, logical expressions, regex expressions and comments
are returned as individual tokens.
Classes
The following class objects are available through PHP MapScript.
classObj
Constructor
Class Objects can be returned by the layerObj class, or can be created using:
new classObj(layerObj layer [, classObj class])
or using the old constructor
classObj ms_newClassObj(layerObj layer [, classObj class])
The second argument class is optional. If given, the new class created will be a copy of this class.
Members
Type
string
string
labelObj
double
hashTableObj
double
string
int
int
int
string
string
int
5.1. MapScript
Name
group
keyimage
label
maxscaledenom
metadata
minscaledenom
name
numlabels
numstyles
status
template
title
type
Note
Removed (6.2) - use addLabel, getLabel, ...
read-only (since 6.2)
read-only
MS_ON, MS_OFF or MS_DELETE
306
MapServer Documentation, Release 7.0.6
Methods
int addLabel( labelObj label) Add a labelObj to the classObj and return its index in the labels array.
New in version 6.2.
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
imageObj createLegendIcon(int width, int height) Draw the legend icon and return a new imageObj.
int deletestyle(int index) Delete the style specified by the style index. If there are any style that follow the deleted
style, their index will decrease by 1.
int drawLegendIcon(int width, int height, imageObj im, int dstX, int dstY) Draw the legend icon on im object at
dstX, dstY. Returns MS_SUCCESS/MS_FAILURE.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
string getExpressionString() Returns the expression string for the class object.
labelObj getLabel(int index) Return a reference to the labelObj at index in the labels array.
See the labelObj section for more details on multiple class labels.
New in version 6.2.
int getMetaData(string name) Fetch class metadata entry by name. Returns “” if no entry matches the name. Note
that the search is case sensitive.
Note: getMetaData’s query is case sensitive.
styleObj getStyle(int index) Return the style object using an index. index >= 0 && index < class->numstyles.
string getTextString() Returns the text string for the class object.
int movestyledown(int index) The style specified by the style index will be moved down into the array of classes.
Returns MS_SUCCESS or MS_FAILURE. ex class->movestyledown(0) will have the effect of moving style 0
up to position 1, and the style at position 1 will be moved to position 0.
int movestyleup(int index) The style specified by the style index will be moved up into the array of classes. Returns
MS_SUCCESS or MS_FAILURE. ex class->movestyleup(1) will have the effect of moving style 1 up to position
0, and the style at position 0 will be moved to position 1.
labelObj removeLabel(int index) Remove the labelObj at index from the labels array and return a reference to the
labelObj. numlabels is decremented, and the array is updated.
New in version 6.2.
int removeMetaData(string name) Remove a metadata entry for the class. Returns MS_SUCCESS/MS_FAILURE.
int set(string property_name, new_value) Set object property to a new value.
int setExpression(string expression) Set the expression string for the class object.
int setMetaData(string name, string value) Set
MS_SUCCESS/MS_FAILURE.
a
metadata
entry
for
the
class.
Returns
int settext(string text) Set the text string for the class object.
int updateFromString(string snippet) Update
MS_SUCCESS/MS_FAILURE.
5.1. MapScript
a
class
from
a
string
snippet.
Returns
307
MapServer Documentation, Release 7.0.6
/*set the color */
$oClass->updateFromString('CLASS STYLE COLOR 255 0 255 END END');
clusterObj
Constructor
Instance of clusterObj is always embedded inside the layerObj.
Members
Type
double
double
string
Name
buffer
maxdistance
region
Methods
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
string getFilterString() Returns the expression for this cluster filter or NULL on error.
string getGroupString() Returns the expression for this cluster group or NULL on error.
int setFilter(string expression) Set layer filter expression.
int setGroup(string expression) Set layer group expression.
colorObj
Constructor
Instances of colorObj are always embedded inside other classes.
Members
Type
int
int
int
int
Name
red
green
blue
alpha
Methods
int setRGB(int red, int green, int blue, int alpha = 255) Set red, green, blue and alpha values.
MS_SUCCESS.
Returns
string toHex() Get the color as a hex string “#rrggbb” or (if alpha is not 255) “#rrggbbaa”.
5.1. MapScript
308
MapServer Documentation, Release 7.0.6
int setHex(string hex) Set red, green, blue and alpha values. The hex string should have the form “#rrggbb” (alpha
will be set to 255) or “#rrggbbaa”. Returns MS_SUCCESS.
errorObj
Instances of errorObj are created internally by MapServer as errors happen. Errors are managed as a chained list with
the first item being the most recent error. The head of the list can be fetched using ms_GetErrorObj(), and the list can
be cleared using ms_ResetErrorList()
Functions
errorObj ms_GetErrorObj() Returns a reference to the head of the list of errorObj.
void ms_ResetErrorList() Clear the current error list. Note that clearing the list invalidates any errorObj handles
obtained via the $error->next() method.
Members
Type
int
string
string
Name
code //See error code constants above
message
routine
Method
errorObj next() Returns the next errorObj in the list, or NULL if we reached the end of the list.
Example
This example draws a map and reports all errors generated during the draw() call, errors can potentially come from
multiple layers.
ms_ResetErrorList();
$img = $map->draw();
$error = ms_GetErrorObj();
while($error && $error->code != MS_NOERR)
{
printf("Error in %s: %s<br>\n", $error->routine, $error->message);
$error = $error->next();
}
gridObj
Constructor
The grid is always embedded inside a layer object defined as a grid (layer->connectiontype = MS_GRATICULE) (for
more docs : https://github.com/mapserver/mapserver/wiki/MapServerGrid)
A layer can become a grid layer by adding a grid object to it using : ms_newGridObj(layerObj layer)
5.1. MapScript
309
MapServer Documentation, Release 7.0.6
$oLayer = ms_newlayerobj($oMap);
$oLayer->set("name", "GRID");
ms_newgridobj($oLayer);
$oLayer->grid->set("labelformat", "DDMMSS");
Members
Type
string
double
double
double
double
double
double
Name
labelformat
maxacrs
maxinterval
maxsubdivide
minarcs
mininterval
minsubdivide
Methods
int set(string property_name, new_value) Set object property to a new value.
hashTableObj
Constructor
Instance of hashTableObj is always embedded inside the classObj, layerObj, mapObj and webObj. It is uses a read
only.
$hashTable = $oLayer->metadata;
$key = null;
while ($key = $hashTable->nextkey($key))
echo "Key: ".$key." value: ".$hashTable->get($key)."<br/>";
Methods
void clear() Clear all items in the hashTable (To NULL).
string get(string key) Fetch class metadata entry by name. Returns “” if no entry matches the name. Note that the
search is case sensitive.
string nextkey(string previousKey) Return the next key or first key if previousKey = NULL. Return NULL if no
item is in the hashTable or end of hashTable is reached
int remove(string key) Remove a metadata entry in the hashTable. Returns MS_SUCCESS/MS_FAILURE.
int set(string key, string value) Set a metadata entry in the hashTable. Returns MS_SUCCESS/MS_FAILURE.
imageObj
5.1. MapScript
310
MapServer Documentation, Release 7.0.6
Constructor
Instances of imageObj are always created by the mapObj class methods.
Members
Type
int
int
int
int
string
string
Name
width
height
resolution
resolutionfactor
imagepath
imageurl
Note
read-only
read-only
read-only
read-only
Methods
void pasteImage(imageObj srcImg, int transparentColorHex [[, int dstX, int dstY], int angle]) Copy srcImg on
top of the current imageObj. transparentColorHex is the color (in 0xrrggbb format) from srcImg that should
be considered transparent (i.e. those pixels won’t be copied). Pass -1 if you don’t want any transparent color.
If optional dstx,dsty are provided then it defines the position where the image should be copied (dstx,dsty =
top-left corner position). The optional angle is a value between 0 and 360 degrees to rotate the source image
counterclockwise. Note that if an angle is specified (even if its value is zero) then the dstx and dsty coordinates
specify the CENTER of the destination area. Note: this function works only with 8 bits GD images (PNG or
GIF).
int saveImage([string filename, MapObj oMap]) Writes image object to specified filename. Passing no filename
or an empty filename sends output to stdout. In this case, the PHP header() function should be used to set the
document’s content-type prior to calling saveImage(). The output format is the one that is currently selected
in the map file. The second argument oMap is not manadatory. It is usful when saving to formats like GTIFF
that needs georeference information contained in the map file. On success, it returns either MS_SUCCESS if
writing to an external file, or the number of bytes written if output is sent to stdout.
string saveWebImage() Writes image to temp directory. Returns image URL. The output format is the one that is
currently selected in the map file.
labelcacheMemberObj
Accessible only through the mapObj (map->getLabel()).
5.1. MapScript
311
MapServer Documentation, Release 7.0.6
Members
Type
int
int
int
int
int
int
int
string
int
Name
classindex
featuresize
layerindex
markerid
numstyles
shapeindex
status
text
tileindex
Note
read-only
read-only
read-only
read-only
read-only
read-only
read-only
read-only
read-only
Method
None
labelcacheObj
Accessible only through the mapObj (map->labelcache). This object is only used to give the possibility to free the
label cache (map->labelcache->freeCache())
Method
boolean freeCache() Free the label cache. Always returns MS_SUCCESS. Ex : map->labelcache->freeCache();
labelObj
Constructor
labelObj are always embedded inside other classes.
new labelObj()
Members
Type
int
double
int
int
int
colorObj
colorObj
int
5.1. MapScript
Name
align
angle
anglemode
antialias
autominfeaturesize
backgroundcolor (deprecated since 6.0)
backgroundshadowcolor (deprecated since 6.0)
backgroundshadowsizex (deprecated since 6.0)
Continued on next page
312
MapServer Documentation, Release 7.0.6
Table 5.2 – continued from previous page
Type
Name
int
backgroundshadowsizey (deprecated since 6.0)
int
buffer
colorObj color
string
encoding
string
font
int
force
int
maxlength
int
maxsize
int
mindistance
int
minfeaturesize
int
minlength
int
minsize
int
numstyles
int
offsetx
int
offsety
colorObj outlinecolor
int
outlinewidth
int
partials
int
position
int
priority
int
repeatdistance
colorObj shadowcolor
int
shadowsizex
int
shadowsizey
int
size
int
wrap
Methods
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
int deleteStyle(int index) Delete the style specified by the style index. If there are any style that follow the deleted
style, their index will decrease by 1.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
string getBinding(const labelbinding) Get the attribute binding for a specified label property. Returns NULL if there
is no binding for this property.
Example:
$oLabel->setbinding(MS_LABEL_BINDING_COLOR, "FIELD_NAME_COLOR");
echo $oLabel->getbinding(MS_LABEL_BINDING_COLOR); // FIELD_NAME_COLOR
string getExpressionString() Returns the label expression string.
styleObj getStyle(int index) Return the style object using an index. index >= 0 && index < label->numstyles.
string getTextString() Returns the label text string.
int moveStyleDown(int index) The style specified by the style index will be moved down into the array of classes.
Returns MS_SUCCESS or MS_FAILURE. ex label->movestyledown(0) will have the effect of moving style 0
up to position 1, and the style at position 1 will be moved to position 0.
5.1. MapScript
313
MapServer Documentation, Release 7.0.6
int moveStyleUp(int index) The style specified by the style index will be moved up into the array of classes. Returns
MS_SUCCESS or MS_FAILURE. ex label->movestyleup(1) will have the effect of moving style 1 up to position
0, and the style at position 0 will be moved to position 1.
int removeBinding(const labelbinding) Remove the attribute binding for a specfiled style property.
Example:
$oStyle->removebinding(MS_LABEL_BINDING_COLOR);
int set(string property_name, new_value) Set object property to a new value.
int setBinding(const labelbinding, string value) Set the attribute binding for a specified label property.
Example:
$oLabel->setbinding(MS_LABEL_BINDING_COLOR, "FIELD_NAME_COLOR");
This would bind the color parameter with the data (ie will extract the value of the color from the field called
“FIELD_NAME_COLOR”
int setExpression( string expression ) Set the label expression.
int setText( string text ) Set the label text.
int updateFromString(string snippet) Update
MS_SUCCESS/MS_FAILURE.
a
label
from
a
string
snippet.
Returns
layerObj
Constructor
Layer Objects can be returned by the mapObj class, or can be created using:
layerObj ms_newLayerObj(MapObj map [, layerObj layer])
A second optional argument can be given to ms_newLayerObj() to create the new layer as a copy of an existing layer.
If a layer is given as argument then all members of a this layer will be copied in the new layer created.
Members
Type
int
hashTableObj
string
string
clusterObj
string
int
string
int
int
string
string
Name
annotate
bindvals
classgroup
classitem
cluster
connection
connectiontype
data
debug
dump
filteritem
footer
Note
read-only, use setConnectionType() to set it
deprecated since 6.0
Continued on next page
5.1. MapScript
314
MapServer Documentation, Release 7.0.6
Type
gridObj
string
string
int
int
string
double
double
string
string
int
double
hashTableObj
double
string
int
int
colorObj
int
projectionObj
int
string
int
int
int
string
double
string
string
string
double
int
int
int
Table 5.3 – continued from previous page
Name
Note
grid
only available on a layer defined as grid (MS_GRATICULE)
group
header
index
read-only
labelcache
labelitem
labelmaxscaledenom
labelminscaledenom
labelrequires
mask
maxfeatures
maxscaledenom
metadata
minscaledenom
name
num_processing
numclasses
read-only
offsite
opacity
projection
postlabelcache
requires
sizeunits
startindex
status
MS_ON, MS_OFF, MS_DEFAULT or MS_DELETE
styleitem
symbolscaledenom
template
tileindex
tileitem
tolerance
toleranceunits
transform
type
Methods
int addFeature(shapeObj shape) Add a new feature in a layer. Returns MS_SUCCESS or MS_FAILURE on error.
int applySLD(string sldxml, string namedlayer) Apply the SLD document to the layer object. The matching between the sld document and the layer will be done using the layer’s name. If a namedlayer argument is passed
(argument is optional), the NamedLayer in the sld that matchs it will be used to style the layer. See SLD HowTo
for more information on the SLD support.
int applySLDURL(string sldurl, string namedlayer) Apply the SLD document pointed by the URL to the layer object. The matching between the sld document and the layer will be done using the layer’s name. If a namedlayer
argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the
layer. See SLD HowTo for more information on the SLD support.
void clearProcessing() Clears all the processing strings.
void close() Close layer previously opened with open().
5.1. MapScript
315
MapServer Documentation, Release 7.0.6
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
int draw(imageObj image) Draw a single layer, add labels to cache if required.
MS_FAILURE on error.
Returns MS_SUCCESS or
int drawQuery(imageObj image) Draw query map for a single layer.
string executeWFSGetfeature() Executes a GetFeature request on a WFS layer and returns the name of the temporary GML file created. Returns an empty string on error.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
string generateSLD() Returns an SLD XML string based on all the classes found in the layer (the layer must have
STATUS on).
classObj getClass(int classIndex) Returns a classObj from the layer given an index value (0=first class)
int getClassIndex(shape [, classgroup, numclasses]) Get the class index of a shape for a given scale. Returns -1 if
no class matches. classgroup is an array of class ids to check (Optional). numclasses is the number of classes
that the classgroup array contains. By default, all the layer classes will be checked.
rectObj getExtent() Returns the layer’s data extents or NULL on error. If the layer’s EXTENT member is set then
this value is used, otherwise this call opens/closes the layer to read the extents. This is quick on shapefiles, but
can be an expensive operation on some file formats or data sources. This function is safe to use on both opened
or closed layers: it is not necessary to call open()/close() before/after calling it.
string getFilterString() Returns the expression for this layer or NULL on error.
array getGridIntersectionCoordinates() Returns an array containing the grid intersection coordinates. If there are
no coordinates, it returns an empty array.
array getItems() Returns an array containing the items. Must call open function first. If there are no items, it returns
an empty array.
int getMetaData(string name) Fetch layer metadata entry by name. Returns “” if no entry matches the name. Note
that the search is case sensitive.
Note: getMetaData’s query is case sensitive.
int getNumResults() Returns the number of results in the last query.
array getProcessing() Returns an array containing the processing strings. If there are no processing strings, it returns
an empty array.
string getProjection() Returns a string representation of the projection. Returns NULL on error or if no projection is
set.
resultObj getResult(int index) Returns a resultObj by index from a layer object with index in the range 0 to
numresults-1. Returns a valid object or FALSE(0) if index is invalid.
rectObj getResultsBounds() Returns the bounding box of the latest result.
shapeObj getShape(resultObj result]) If the resultObj passed has a valid resultindex, retrieve shapeObj from a
layer’s resultset. (You get it from the resultObj returned by getResult() for instance). Otherwise, it will do
a single query on the layer to fetch the shapeindex
$map = new mapObj("gmap75.map");
$l = $map->getLayerByName("popplace");
$l->queryByRect($map->extent);
for ($i=0; $i<$l->getNumResults();$i++){
$s = $l->getShape($l->getResult($i));
5.1. MapScript
316
MapServer Documentation, Release 7.0.6
echo $s->getValue($l,"Name");
echo "\n";
}
string getWMSFeatureInfoURL(int clickX, int clickY, int featureCount, string infoFormat) Returns a WMS
GetFeatureInfo URL (works only for WMS layers) clickX, clickY is the location of to query in pixel coordinates with (0,0) at the top left of the image. featureCount is the number of results to return. infoFormat is the
format the format in which the result should be requested. Depends on remote server’s capabilities. MapServer
WMS servers support only “MIME” (and should support “GML.1” soon). Returns “” and outputs a warning if
layer is not a WMS layer or if it is not queriable.
boolean isVisible() Returns MS_TRUE/MS_FALSE depending on whether the layer is currently visible in the map
(i.e. turned on, in scale, etc.).
int moveclassdown(int index) The class specified by the class index will be moved down into the array of layers.
Returns MS_SUCCESS or MS_FAILURE. ex layer->moveclassdown(0) will have the effect of moving class 0
up to position 1, and the class at position 1 will be moved to position 0.
int moveclassup(int index) The class specified by the class index will be moved up into the array of layers. Returns MS_SUCCESS or MS_FAILURE. ex layer->moveclassup(1) will have the effect of moving class 1 up to
position 0, and the class at position 0 will be moved to position 1.
int open() Open the layer for use with getShape(). Returns MS_SUCCESS/MS_FAILURE.
shapeobj nextShape() Called after msWhichShapes has been called to actually retrieve shapes within a given area.
Returns a shape object or NULL on error.
$map = ms_newmapobj("d:/msapps/gmap-ms40/htdocs/gmap75.map");
$layer = $map->getLayerByName('road');
$status = $layer->open();
$status = $layer->whichShapes($map->extent);
while ($shape = $layer->nextShape())
{
echo $shape->index ."<br>\n";
}
$layer->close();
int queryByAttributes(string qitem, string qstring, int mode) Query layer for shapes that intersect current map extents. qitem is the item (attribute) on which the query is performed, and qstring is the expression to match. The
query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match
any class in a layer that contains a LAYER TEMPLATE value. Note that the layer’s FILTER/FILTERITEM are
ignored by this function. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want.
Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error
happened (note that the error message in case nothing was found can be avoided in PHP using the ‘@’ control
operator).
int queryByFeatures(int slayer) Perform a query set based on a previous set of results from another layer. At present
the results MUST be based on a polygon layer. Returns MS_SUCCESS if shapes were found or MS_FAILURE
if nothing was found or if some other error happened (note that the error message in case nothing was found can
be avoided in PHP using the ‘@’ control operator).
int queryByPoint(pointObj point, int mode, double buffer) Query layer at point location specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS
that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value.
Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Passing buffer -1 defaults
to tolerances set in the map file (in pixels) but you can use a constant buffer (specified in ground units) instead.
Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error
5.1. MapScript
317
MapServer Documentation, Release 7.0.6
happened (note that the error message in case nothing was found can be avoided in PHP using the ‘@’ control
operator).
int queryByRect(rectObj rect) Query layer using a rectangle specified in georeferenced map coordinates (i.e. not
pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value
or that match any class in a layer that contains a LAYER TEMPLATE value. Returns MS_SUCCESS if shapes
were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message
in case nothing was found can be avoided in PHP using the ‘@’ control operator).
int queryByShape(shapeObj shape) Query layer based on a single shape, the shape has to be a polygon at this
point. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other
error happened (note that the error message in case nothing was found can be avoided in PHP using the ‘@’
control operator).
classObj removeClass(int index) Removes the class indicated and returns a copy, or NULL in the case of a failure.
Note that subsequent classes will be renumbered by this operation. The numclasses field contains the number
of classes available.
int removeMetaData(string name) Remove a metadata entry for the layer. Returns MS_SUCCESS/MS_FAILURE.
int set(string property_name, new_value) Set object property to a new value.
int setConnectionType(int connectiontype [,string plugin_library]) Changes the connectiontype of the layer and
recreates the vtable according to the new connection type. This method should be used instead of setting the
connectiontype parameter directly. In the case when the layer.connectiontype = MS_PLUGIN the plugin_library
parameter should also be specified so as to select the library to load by MapServer. For the other connection
types this parameter is not used.
int setFilter(string expression) Set layer filter expression.
int setMetaData(string name, string value) Set
MS_SUCCESS/MS_FAILURE.
a
metadata
entry
for
the
layer.
Returns
int setProcessing(string) Add the string to the processing string list for the layer. The layer->num_processing is
incremented by 1. Returns MS_SUCCESS or MS_FAILURE on error.
$oLayer->setprocessing("SCALE_1=AUTO");
$oLayer->setprocessing("SCALE_2=AUTO");
int setProjection(string proj_params) Set layer projection and coordinate system. Parameters are given as a single
string of comma-delimited PROJ.4 parameters. Returns MS_SUCCESS or MS_FAILURE on error.
int setWKTProjection(string proj_params) Same as setProjection(), but takes an OGC WKT projection definition
string as input.
Note: setWKTProjection requires GDAL support
int updateFromString(string snippet) Update
MS_SUCCESS/MS_FAILURE.
a
layer
from
a
string
snippet.
Returns
/*modify the name */
$oLayer->updateFromString('LAYER NAME land_fn2 END');
/*add a new class*/
$oLayer->updateFromString('LAYER CLASS STYLE COLOR 255 255 0 END END END');
int whichshapes(rectobj) Performs a spatial, and optionally an attribute based feature search. The function basically
prepares things so that candidate features can be accessed by query or drawing functions (eg using nextshape
function). Returns MS_SUCCESS, MS_FAILURE or MS_DONE. MS_DONE is returned if the layer extent
does not overlap the rectObj.
5.1. MapScript
318
MapServer Documentation, Release 7.0.6
legendObj
Constructor
Instances of legendObj are always are always embedded inside the mapObj.
Members
Type
int
colorObj
int
int
int
int
labelObj
colorObj
int
int
int
string
int
Name
height
imagecolor
keysizex
keysizey
keyspacingx
keyspacingy
label
outlinecolor
position
postlabelcache
status
template
width
Note
Color of outline of box, -1 for no outline
for embedded legends, MS_UL, MS_UC, ...
MS_TRUE, MS_FALSE
MS_ON, MS_OFF, MS_EMBED
Methods
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
int set(string property_name, new_value) Set object property to a new value.
int updateFromString(string snippet) Update
MS_SUCCESS/MS_FAILURE.
a
legend
from
a
string
snippet.
Returns
lineObj
Constructor
new lineObj()
or using the old constructor
LineObj ms_newLineObj()
Members
Type
int
Name
numpoints
5.1. MapScript
Note
read-only
319
MapServer Documentation, Release 7.0.6
Methods
int add(pointObj point) Add a point to the end of line. Returns MS_SUCCESS/MS_FAILURE.
int addXY(double x, double y [, double m]) Add a point to the end of line. Returns MS_SUCCESS/MS_FAILURE.
Note: the 3rd parameter m is used for measured shape files only. It is not mandatory.
int addXYZ(double x, double y, double z [, double m]) Add
MS_SUCCESS/MS_FAILURE.
a
point
to
the
end
of
line.
Returns
Note: the 4th parameter m is used for measured shape files only. It is not mandatory.
PointObj point(int i) Returns a reference to point number i.
int project(projectionObj in, projectionObj out) Project the line from “in” projection (1st argument) to “out” projection (2nd argument). Returns MS_SUCCESS/MS_FAILURE.
mapObj
Constructor
new mapObj(string map_file_name [, string new_map_path])
or using the old constructors
mapObj ms_newMapObj(string map_file_name [, string new_map_path]) Returns a new object to deal with a
MapServer map file.
mapObj ms_newMapObjFromString(string map_file_string [, string new_map_path]) Construct
mapObj from a mapfile string. Returns a new object to deal with a MapServer map file.
a
new
Note: By default, the SYMBOLSET, FONTSET, and other paths in the mapfile are relative to the mapfile location.
If new_map_path is provided then this directory will be used as the base path for all the rewlative paths inside the
mapfile.
Members
Type
double
int
double
rectObj
string
int
colorObj
int
Name
cellsize
debug
defresolution
extent;
fontsetfilename
height
imagecolor
keysizex
Note
pixels per inch, defaults to 72
read-only, set by setFontSet()
see setSize()
Continued on next page
5.1. MapScript
320
MapServer Documentation, Release 7.0.6
Type
int
int
int
labelcacheObj
legendObj
string
int
hashTableObj
string
int
outputformatObj
int
projectionObj
querymapObj
referenceMapObj
double
scalebarObj
double
string
int
string
int
webObj
int
Table
Name
keysizey
keyspacingx
keyspacingy
labelcache
legend
mappath
maxsize
metadata
name
numlayers
outputformat
numoutputformats
projection
querymap
reference
resolution
scalebar
scaledenom
shapepath
status
symbolsetfilename
units
web
width
5.4 – continued from previous page
Note
no members. Used only to free the label cache (map->labelcache->free()
read-only
read-only
pixels per inch, defaults to 72
read-only, set by drawMap()
read-only, set by setSymbolSet()
map units type
see setSize()
Methods
int applyconfigoptions() Applies the config options set in the map file. For example setting the PROJ_LIB using
the setconfigoption only modifies the value in the map object. applyconfigoptions will actually change the
PROJ_LIB value that will be used when dealing with projection.
int applySLD(string sldxml) Apply the SLD document to the map file. The matching between the sld document and
the map file will be done using the layer’s name. See SLD HowTo for more information on the SLD support.
int applySLDURL(string sldurl) Apply the SLD document pointed by the URL to the map file. The matching
between the sld document and the map file will be done using the layer’s name. See SLD HowTo for more
information on the SLD support.
string convertToString() Saves the object to a string.
Note: The inverse method updateFromString does not exist for the mapObj
New in version 6.4.
imageObj draw() Render map and return an image object or NULL on error.
int drawLabelCache(imageObj image) Renders the labels for a map. Returns MS_SUCCESS or MS_FAILURE on
error.
imageObj drawLegend() Render legend and return an image object.
imageObj drawQuery() Render a query map and return an image object or NULL on error.
5.1. MapScript
321
MapServer Documentation, Release 7.0.6
imageObj drawReferenceMap() Render reference map and return an image object.
imageObj drawScaleBar() Render scale bar and return an image object.
int embedLegend(imageObj image) embeds a legend. Actually the legend is just added to the label cache so you
must invoke drawLabelCache() to actually do the rendering (unless postlabelcache is set in which case it is
drawn right away). Returns MS_SUCCESS or MS_FAILURE on error.
int embedScalebar(imageObj image) embeds a scalebar. Actually the scalebar is just added to the label cache so
you must invoke drawLabelCache() to actually do the rendering (unless postlabelcache is set in which case it is
drawn right away). Returns MS_SUCCESS or MS_FAILURE on error.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
void freeQuery(layerindex) Frees the query result on a specified layer. If the layerindex is -1, all queries on layers
will be freed.
string generateSLD() Returns an SLD XML string based on all the classes found in all the layers that have STATUS
on.
array getAllGroupNames() Return an array containing all the group names used in the layers. If there are no groups,
it returns an empty array.
array getAllLayerNames() Return an array containing all the layer names. If there are no layers, it returns an empty
array.
colorObj getColorbyIndex(int iCloIndex) Returns a colorObj corresponding to the color index in the palette.
string getConfigOption(string key) Returns the config value associated with the key. Returns an empty sting if key
not found.
labelcacheMemberObj getLabel(int index) Returns a labelcacheMemberObj from the map given an index value
(0=first label). Labelcache has to be enabled.
while ($oLabelCacheMember = $oMap->getLabel($i)) {
/* do something with the labelcachemember */
++$i;
}
layerObj getLayer(int index) Returns a layerObj from the map given an index value (0=first layer)
layerObj getLayerByName(string layer_name) Returns a layerObj from the map given a layer name. Returns
NULL if layer doesn’t exist.
array getLayersDrawingOrder() Return an array containing layer’s index in the order which they are drawn. If
there are no layers, it returns an empty array.
array getLayersIndexByGroup(string groupname) Return an array containing all the layer’s indexes given a group
name. If there are no layers, it returns an empty array.
int getMetaData(string name) Fetch metadata entry by name (stored in the WEB object in the map file). Returns “”
if no entry matches the name.
Note: getMetaData’s query is case sensitive.
int getNumSymbols() Return the number of symbols in map.
string getProjection() Returns a string representation of the projection. Returns NULL on error or if no projection is
set.
int getSymbolByName(string symbol_name) Returns the symbol index using the name.
5.1. MapScript
322
MapServer Documentation, Release 7.0.6
symbol getSymbolObjectById(int symbolid) Returns the symbol object using a symbol id. Refer to the symbol
object reference section for more details.
int insertLayer( layerObj layer [, int nIndex=-1 ] ) Insert a copy of layer into the Map at index nIndex. The default
value of nIndex is -1, which means the last possible index. Returns the index of the new Layer, or -1 in the case
of a failure.
int loadMapContext(string filename [, boolean unique_layer_name]) Available only if WMS support is enabled.
Load a WMS Map Context XML file into the current mapObj. If the map already contains some layers then
the layers defined in the WMS Map context document are added to the current map. The 2nd argument
unique_layer_name is optional and if set to MS_TRUE layers created will have a unique name (unique prefix added to the name). If set to MS_FALSE the layer name will be the the same name as in the context. The
default value is MS_FALSE. Returns MS_SUCCESS/MS_FAILURE.
int loadOWSParameters(owsrequest request, string version) Load OWS request parameters (BBOX, LAYERS,
&c.) into map. Returns MS_SUCCESS or MS_FAILURE. 2nd argument version is not mandatory. If not given,
the version will be set to 1.1.1
int loadQuery(filename) Loads a query from a file. Returns MS_SUCCESS or MS_FAILURE. To be used with
savequery.
int moveLayerDown(int layerindex) Move layer down in the hierarchy of drawing. Returns MS_SUCCESS or
MS_FAILURE on error.
int moveLayerUp(int layerindex) Move layer up in the hierarchy of drawing.
MS_FAILURE on error.
Returns MS_SUCCESS or
int offsetExtent(double x, double y) Offset the map extent based on the given distances in map coordinates. Returns
MS_SUCCESS or MS_FAILURE.
int owsDispatch(owsrequest request) Processes and executes the passed OpenGIS Web Services request on the map.
Returns MS_DONE (2) if there is no valid OWS request in the req object, MS_SUCCESS (0) if an OWS
request was successfully processed and MS_FAILURE (1) if an OWS request was not successfully processed.
OWS requests include WMS, WFS, WCS and SOS requests supported by MapServer. Results of a dispatched
request are written to stdout and can be captured using the msIO services (ie. ms_ioinstallstdouttobuffer() and
ms_iogetstdoutbufferstring())
imageObj prepareImage() Return a blank image object.
void prepareQuery() Calculate the scale of the map and set map->scaledenom.
string processLegendTemplate(array params) Process legend template files and return the result in a buffer.
See also:
processtemplate
string processQueryTemplate(array params, boolean generateimages) Process query template files and return the
result in a buffer. Second argument generateimages is not mandatory. If not given it will be set to TRUE.
See also:
processtemplate
string processTemplate(array params, boolean generateimages) Process the template file specified in the web object and return the result in a buffer. The processing consists of opening the template file and replace all the tags
found in it. Only tags that have an equivalent element in the map object are replaced (ex [scaledenom]). The are
two exceptions to the previous statement :
• [img], [scalebar], [ref], [legend] would be replaced with the appropriate url if the parameter generateimages
is set to MS_TRUE. (Note : the images corresponding to the different objects are generated if the object is
set to MS_ON in the map file)
5.1. MapScript
323
MapServer Documentation, Release 7.0.6
• the user can use the params parameter to specify tags and their values. For example if the user have a
specific tag call [my_tag] and would like it to be replaced by “value_of_my_tag” he would do
$tmparray["my_tag"] = "value_of_my_tag";
$map->processtemplate($tmparray, MS_FALSE);
int queryByFeatures(int slayer) Perform a query based on a previous set of results from a layer. At present the
results MUST be based on a polygon layer. Returns MS_SUCCESS if shapes were found or MS_FAILURE if
nothing was found or if some other error happened (note that the error message in case nothing was found can
be avoided in PHP using the ‘@’ control operator).
int queryByIndex(layerindex, tileindex, shapeindex[, addtoquery]) Add a specific shape on a given layer to the
query result. If addtoquery (which is a non mandatory argument) is set to MS_TRUE, the shape will be added
to the existing query list. Default behavior is to free the existing query list and add only the new shape.
int queryByPoint(pointObj point, int mode, double buffer) Query all selected layers in map at point location specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of
a CLASS that contains a Templating value or that match any class in a layer that contains a LAYER TEMPLATE
value. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Passing buffer -1
defaults to tolerances set in the map file (in pixels) but you can use a constant buffer (specified in ground units)
instead. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other
error happened (note that the error message in case nothing was found can be avoided in PHP using the ‘@’
control operator).
int queryByRect(rectObj rect) Query all selected layers in map using a rectangle specified in georeferenced map
coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a Templating value or that match any class in a layer that contains a LAYER TEMPLATE value. Returns
MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened
(note that the error message in case nothing was found can be avoided in PHP using the ‘@’ control operator).
int queryByShape(shapeObj shape) Query all selected layers in map based on a single shape, the shape has to be
a polygon at this point. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found
or if some other error happened (note that the error message in case nothing was found can be avoided in PHP
using the ‘@’ control operator).
layerObj removeLayer( int nIndex ) Remove a layer from the mapObj. The argument is the index of the layer to be
removed. Returns the removed layerObj on success, else null.
int removeMetaData(string name) Remove a metadata entry for the map (stored in the WEB object in the map file).
Returns MS_SUCCESS/MS_FAILURE.
int save(string filename) Save current map object state to a file. Returns -1 on error. Use absolute path. If a relative
path is used, then it will be relative to the mapfile location.
int saveMapContext(string filename) Available only if WMS support is enabled. Save current map object state
in WMS Map Context format. Only WMS layers are saved in the WMS Map Context XML file. Returns
MS_SUCCESS/MS_FAILURE.
int saveQuery(string filename[, int results]) Save the current query in a file. Results determines the save format MS_TRUE (or 1/true) saves the query results (tile index and shape index), MS_FALSE (or 0/false) the query
parameters (and the query will be re-run in loadquery). Returns MS_SUCCESS or MS_FAILURE. Either save
format can be used with loadquery. See RFC 65 and ticket #3647 for details of different save formats.
int scaleExtent(double zoomfactor, double minscaledenom, double maxscaledenom) Scale the map extent using
the zoomfactor and ensure the extent within the minscaledenom and maxscaledenom domain. If minscaledenom and/or maxscaledenom is 0 then the parameter is not taken into account. Returns MS_SUCCESS or
MS_FAILURE.
int selectOutputFormat(string type) Selects the output format to be used in the map.
MS_SUCCESS/MS_FAILURE.
5.1. MapScript
Returns
324
MapServer Documentation, Release 7.0.6
Note: the type used should correspond to one of the output formats declared in the map file. The type argument
passed is compared with the mimetype parameter in the output format structure and then to the name parameter
in the structure.
int appendOutputFormat(outputFormatObj outputFormat) Appends outputformat object in the map object. Returns the new numoutputformats value.
int removeOutputFormat(string name) Remove
MS_SUCCESS/MS_FAILURE.
outputformat
from
the
map.
Returns
outputFormatObj getOutputFormat(int index) Returns the outputformat at index position.
int set(string property_name, new_value) Set map object property to new value.
int setCenter(pointObj center) Set the map center to the given map point.
MS_FAILURE.
Returns MS_SUCCESS or
int setConfigOption(string key, string value) Sets a config parameter using the key and the value passed
void setExtent(double minx, double miny, double maxx, double maxy) Set the map extents using the georef extents passed in argument. Returns MS_SUCCESS or MS_FAILURE on error.
int setFontSet(string fileName) Load and set a new FONTSET.
boolean setLayersDrawingOrder(array layeryindex) Set the layer’s order array. The argument passed must be a
valid array with all the layer’s index. Returns MS_SUCCESS or MS_FAILURE on error.
int setMetaData(string name, string value) Set a metadata entry for the map (stored in the WEB object in the map
file). Returns MS_SUCCESS/MS_FAILURE.
int setProjection(string proj_params, boolean bSetUnitsAndExtents) Set map projection and coordinate system.
Returns MS_SUCCESS or MS_FAILURE on error.
Parameters are given as a single string of comma-delimited PROJ.4 parameters. The argument : bSetUnitsAndExtents is used to automatically update the map units and extents based on the new projection. Possible
values are MS_TRUE and MS_FALSE. By default it is set at MS_FALSE.
int setRotation(double rotation_angle) Set map rotation angle. The map view rectangle (specified in EXTENTS)
will be rotated by the indicated angle in the counter- clockwise direction. Note that this implies the rendered
map will be rotated by the angle in the clockwise direction. Returns MS_SUCCESS or MS_FAILURE.
int setSize(int width, int height) Set the map width and height. This method updates the internal geotransform and
other data structures required for map rotation so it should be used instead of setting the width and height
members directly. Returns MS_SUCCESS or MS_FAILURE.
int setSymbolSet(string fileName) Load and set a symbol file dynamically.
int setWKTProjection(string proj_params, boolean bSetUnitsAndExtents) Same as setProjection(), but takes an
OGC WKT projection definition string as input. Returns MS_SUCCESS or MS_FAILURE on error.
Note: setWKTProjection requires GDAL support
int zoomPoint(int nZoomFactor, pointObj oPixelPos, int nImageWidth, int nImageHeight, rectObj oGeorefExt)
Zoom to a given XY position. Returns MS_SUCCESS or MS_FAILURE on error.
Parameters are
• Zoom factor : positive values do zoom in, negative values zoom out. Factor of 1 will recenter.
• Pixel position (pointObj) : x, y coordinates of the click, with (0,0) at the top-left
5.1. MapScript
325
MapServer Documentation, Release 7.0.6
• Width : width in pixel of the current image.
• Height : Height in pixel of the current image.
• Georef extent (rectObj) : current georef extents.
• MaxGeoref extent (rectObj) : (optional) maximum georef extents. If provided then it will be impossible
to zoom/pan outside of those extents.
int zoomRectangle(rectObj oPixelExt, int nImageWidth, int nImageHeight, rectObj oGeorefExt) Set the map
extents to a given extents. Returns MS_SUCCESS or MS_FAILURE on error.
Parameters are :
• oPixelExt (rect object) : Pixel Extents
• Width : width in pixel of the current image.
• Height : Height in pixel of the current image.
• Georef extent (rectObj) : current georef extents.
int zoomScale(double nScaleDenom, pointObj oPixelPos, int nImageWidth, int nImageHeight, rectObj oGeorefExt [, rectObj oM
Zoom in or out to a given XY position so that the map is displayed at specified scale. Returns MS_SUCCESS
or MS_FAILURE on error.
Parameters are :
• ScaleDenom : Scale denominator of the scale at which the map should be displayed.
• Pixel position (pointObj) : x, y coordinates of the click, with (0,0) at the top-left
• Width : width in pixel of the current image.
• Height : Height in pixel of the current image.
• Georef extent (rectObj) : current georef extents.
• MaxGeoref extent (rectObj) : (optional) maximum georef extents. If provided then it will be impossible
to zoom/pan outside of those extents.
outputformatObj
Constructor
Instance of outputformatObj is always embedded inside the mapObj. It is uses a read only.
No constructor available (coming soon, see ticket 979)
Members
Type
string
string
int
string
string
int
int
Name
driver
extension
imagemode
mimetype
name
renderer
transparent
5.1. MapScript
Note
MS_IMAGEMODE_* value.
326
MapServer Documentation, Release 7.0.6
Methods
string getOption(string property_name) Returns the associated value for the format option property passed as argument. Returns an empty string if property not found.
int set(string property_name, new_value) Set object property to a new value.
void setOption(string property_name, string new_value) Add or Modify the format option list. return true on success.
$oMap->outputformat->setOption("OUTPUT_TYPE", "RASTER");
int validate() Checks some internal consistency issues, Returns MS_SUCCESS or MS_FAILURE. Some problems
are fixed up internally. May produce debug output if issues encountered.
OwsrequestObj
Constructor
new OWSRequestObj()
or using the old constructor
request = ms_newOwsrequestObj();
Create a new ows request object.
Members
Type
int
int
Name
numparams (read-only)
type (read-only): MS_GET_REQUEST or MS_POST_REQUEST
Methods
int addParameter(string name, string value) Add a request parameter, even if the parameter key was previousely
set. This is useful when multiple parameters with the same key are required. For example :
$request->addparameter('SIZE', 'x(100)');
$request->addparameter('SIZE', 'y(100)');
string getName(int index) Return the name of the parameter at index in the request’s array of parameter names.
string getValue(int index) Return the value of the parameter at index in the request’s array of parameter values.
string getValueByName(string name) Return the value associated with the parameter name.
int loadParams() Initializes the OWSRequest object from the cgi environment variables REQUEST_METHOD,
QUERY_STRING and HTTP_COOKIE. Returns the number of name/value pairs collected.
int setParameter(string name, string value) Set a request parameter. For example :
$request->setparameter('REQUEST', 'GetMap');
5.1. MapScript
327
MapServer Documentation, Release 7.0.6
pointObj
Constructor
new pointObj()
or using the old constructor
PointObj ms_newPointObj()
Members
Type
double
double
double
double
Name
x
y
z
m
Note
used for 3d shape files. set to 0 for other types
used only for measured shape files - set to 0 for other types
Methods
double distanceToLine(pointObject p1, pointObject p2) Calculates distance between a point ad a lined defined by
the two points passed in argument.
double distanceToPoint(pointObj poPoint) Calculates distance between two points.
double distanceToShape(shapeObj shape) Calculates the minimum distance between a point and a shape.
int draw(mapObj map, layerObj layer, imageObj img, int class_index [, string text]) Draws the individual point
using layer. The class_index is used to classify the point based on the classes defined for the layer. The text
string is used to annotate the point. (Optional) Returns MS_SUCCESS/MS_FAILURE.
int project(projectionObj in, projectionObj out) Project the point from “in” projection (1st argument) to “out” projection (2nd argument). Returns MS_SUCCESS/MS_FAILURE.
int setXY(double x, double y [, double m]) Set X,Y coordinate values.
Note: the 3rd parameter m is used for measured shape files only. It is not mandatory.
int setXYZ(double x, double y , double z, [, double m]) Set X,Y,Z coordinate values.
Note: the 4th parameter m is used for measured shape files only. It is not mandatory.
projectionObj
Constructor
new projectionObj(string projectionString)
or using the old constructor
5.1. MapScript
328
MapServer Documentation, Release 7.0.6
ProjectionObj ms_newProjectionObj(string projectionString)
Creates a projection object based on the projection string passed as argument.
$projInObj = ms_newprojectionobj("proj=latlong")
will create a geographic projection class.
The following example will convert a lat/long point to an LCC projection:
$projInObj = ms_newprojectionobj("proj=latlong");
$projOutObj = ms_newprojectionobj("proj=lcc,ellps=GRS80,lat_0=49,".
"lon_0=-95,lat_1=49,lat_2=77");
$poPoint = ms_newpointobj();
$poPoint->setXY(-92.0, 62.0);
$poPoint->project($projInObj, $projOutObj);
Methods
int getUnits() Returns the units of a projection object. Returns -1 on error.
querymapObj
Constructor
Instances of querymapObj are always are always embedded inside the mapObj.
Members
Type
colorObj
int
int
int
Name
color
height
width
style
Note
MS_NORMAL, MS_HILITE, MS_SELECTED
Methods
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
int set(string property_name, new_value) Set object property to a new value.
int updateFromString(string snippet) Update
MS_SUCCESS/MS_FAILURE.
5.1. MapScript
a
queryMap
object
from
a
string
snippet.
Returns
329
MapServer Documentation, Release 7.0.6
rectObj
Constructor
rectObj are sometimes embedded inside other objects. New ones can also be created with:
new rectObj()
or using the old constructor
RectObj ms_newRectObj()
Note: the members (minx, miny, maxx ,maxy) are initialized to -1;
Members:
Type
double
double
double
double
Name
minx
miny
maxx
maxy
Methods
int draw(mapObj map, layerObj layer, imageObj img, int class_index [, string text]) Draws the individual rectangle using layer. The class_index is used to classify the rectangle based on the classes defined for the layer.
The text string is used to annotate the rectangle. (Optional) Returns MS_SUCCESS/MS_FAILURE.
double fit(int width, int height) Adjust extents of the rectangle to fit the width/height specified.
int project(projectionObj in, projectionObj out) Project the rectangle from “in” projection (1st argument) to “out”
projection (2nd argument). Returns MS_SUCCESS/MS_FAILURE.
int set(string property_name, new_value) Set object property to a new value.
void setextent(double minx, double miny, double maxx, double maxy) Set the rectangle extents.
referenceMapObj
Constructor
Instances of referenceMapObj are always embedded inside the mapObj.
5.1. MapScript
330
MapServer Documentation, Release 7.0.6
Members
Type
ColorObj
int
rectObj
string
int
string
int
int
int
ColorObj
int
int
Name
color
height
extent
image
marker
markername
markersize
maxboxsize
minboxsize
outlinecolor
status
width
Methods
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
int set(string property_name, new_value) Set object property to a new value.
int updateFromString(string snippet) Update a referenceMap object from a string snippet.
MS_SUCCESS/MS_FAILURE.
Returns
resultObj
Constructor
new resultObj(int shapeindex)
or using the layerObj‘s getResult() method.
Members
Type
int
int
int
int
Name
classindex
resultindex
shapeindex
tileindex
Note
read-only
read-only
read-only
read-only
Method
None
5.1. MapScript
331
MapServer Documentation, Release 7.0.6
scalebarObj
Constructor
Instances of scalebarObj are always embedded inside the mapObj.
Members
Type
int
colorObj
colorObj
int
colorObj
int
labelObj
colorObj
int
int
int
int
int
int
Name
align
backgroundcolor
color
height
imagecolor
intervals
label
outlinecolor
position
postlabelcache
status
style
units
width
Note
for embedded scalebars, MS_UL, MS_UC, ...
MS_ON, MS_OFF, MS_EMBED
Methods
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
int set(string property_name, new_value) Set object property to a new value.
int setImageColor(int red, int green, int blue) Sets the imagecolor property (baclground) of the object. Returns
MS_SUCCESS or MS_FAILURE on error.
int updateFromString(string snippet) Update
MS_SUCCESS/MS_FAILURE.
a
scalebar
from
a
string
snippet.
Returns
shapefileObj
Constructor
new shapeFileObj(string filename, int type)
or using the old constructor
shapefileObj ms_newShapefileObj(string filename, int type)
Opens a shapefile and returns a new object to deal with it. Filename should be passed with no extension.
To create a new file (or overwrite an existing one), type should be one of MS_SHP_POINT, MS_SHP_ARC,
5.1. MapScript
332
MapServer Documentation, Release 7.0.6
MS_SHP_POLYGON or MS_SHP_MULTIPOINT. Pass type as -1 to open an existing file for read-only access, and
type=-2 to open an existing file for update (append).
Members
Type
rectObj
int
string
int
Name
bounds
numshapes
source
type
Note
read-only
read-only
read-only
read-only
Methods
int addPoint(pointObj point) Appends a point to an open shapefile.
int addShape(shapeObj shape) Appends a shape to an open shapefile.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
Note: The shape file is closed (and changes committed) when the object is destroyed. You can explicitly close
and save the changes by calling $shapefile->free(); unset($shapefile), which will also free the php object.
rectObj getExtent(int i) Retrieve a shape’s bounding box by index.
shapeObj getPoint(int i) Retrieve point by index.
shapeObj getShape(int i) Retrieve shape by index.
shapeObj getTransformed(mapObj map, int i) Retrieve shape by index.
shapeObj
Constructor
new shapeObj(int type)
or using the old constructor
ShapeObj ms_newShapeObj(int type)
‘type’ is one of MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON or MS_SHAPE_NULL
ShapeObj ms_shapeObjFromWkt(string wkt)
Creates new shape object from WKT string.
5.1. MapScript
333
MapServer Documentation, Release 7.0.6
Members
Type
rectObj
int
int
int
int
int
string
int
array
Name
bounds
classindex
index
numlines
numvalues
tileindex
text
type
values
Note
read-only
read-only
read-only
read-only
read-only
read-only
The values array is an associative array with the attribute values for this shape. It is set only on shapes obtained from
layer->getShape(). The key to the values in the array is the attribute name, e.g.
$population = $shape->values["Population"];
Methods
int add(lineObj line) Add a line (i.e. a part) to the shape.
shapeobj boundary() Returns the boundary of the shape. Only available if php/mapscript is built with GEOS library.
shapeobj buffer(width) Returns a new buffered shapeObj based on the supplied distance (given in the coordinates of
the existing shapeObj). Only available if php/mapscript is built with GEOS library.
int containsShape(shapeobj shape2) Returns true if shape2 passed as argument is entirely within the shape. Else
return false. Only available if php/mapscript is built with GEOS library.
shapeobj convexhull() Returns a shape object representing the convex hull of shape. Only available if php/mapscript
is built with GEOS library.
boolean contains(pointObj point) Returns MS_TRUE if the point is inside the shape, MS_FALSE otherwise.
int crosses(shapeobj shape) Returns true if the shape passed as argument crosses the shape. Else return false. Only
available if php/mapscript is built with GEOS library.
shapeobj difference(shapeobj shape) Returns a shape object representing the difference of the shape object with the
one passed as parameter. Only available if php/mapscript is built with GEOS library.
int disjoint(shapeobj shape) Returns true if the shape passed as argument is disjoint to the shape. Else return false.
Only available if php/mapscript is built with GEOS library.
int draw(mapObj map, layerObj layer, imageObj img) Draws the individual shape using layer.
MS_SUCCESS/MS_FAILURE.
Returns
int equals(shapeobj shape) Returns true if the shape passed as argument is equal to the shape (geometry only). Else
return false. Only available if php/mapscript is built with GEOS library.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
double getArea() Returns the area of the shape (if applicable). Only available if php/mapscript is built with GEOS
library.
pointObj getCentroid() Returns a point object representing the centroid of the shape. Only available if php/mapscript
is built with GEOS library.
5.1. MapScript
334
MapServer Documentation, Release 7.0.6
pointObj getLabelPoint() Returns a point object with coordinates suitable for labelling the shape.
double getLength() Returns the length (or perimeter) of the shape. Only available if php/mapscript is built with
GEOS library.
pointObj getMeasureUsingPoint(pointObject point) Apply only on Measured shape files. Given an XY Location,
find the nearest point on the shape object. Return a point object of this point with the m value set.
pointObj getPointUsingMeasure(double m) Apply only on Measured shape files. Given a measure m, retun the
corresponding XY location on the shapeobject.
string getValue(layerObj layer, string filedname) Returns the value for a given field name.
shapeobj intersection(shapeobj shape) Returns a shape object representing the intersection of the shape object with
the one passed as parameter. Only available if php/mapscript is built with GEOS library.
boolean intersects(shapeObj shape) Returns MS_TRUE if the two shapes intersect, MS_FALSE otherwise.
LineObj line(int i) Returns a reference to line number i.
int overlaps(shapeobj shape) Returns true if the shape passed as argument overlaps the shape. Else returns false.
Only available if php/mapscript is built with GEOS library.
int project(projectionObj in, projectionObj out) Project the shape from “in” projection (1st argument) to “out”
projection (2nd argument). Returns MS_SUCCESS/MS_FAILURE.
int set(string property_name, new_value) Set object property to a new value.
int setBounds() Updates the bounds property of the shape. Must be called to calculate new bounding box after new
parts have been added.
shapeObj simplify(double tolerance) Given a tolerance, returns a simplified shape object or NULL on error. Only
available if php/mapscript is built with GEOS library (>=3.0).
shapeobj symdifference(shapeobj shape) Returns the computed symmetric difference of the supplied and existing
shape. Only available if php/mapscript is built with GEOS library.
shapeObj topologyPreservingSimplify(double tolerance) Given a tolerance, returns a simplified shape object or
NULL on error. Only available if php/mapscript is built with GEOS library (>=3.0).
int touches(shapeobj shape) Returns true if the shape passed as argument touches the shape. Else return false. Only
available if php/mapscript is built with GEOS library.
string toWkt() Returns WKT representation of the shape’s geometry.
shapeobj union(shapeobj shape) Returns a shape object representing the union of the shape object with the one
passed as parameter. Only available if php/mapscript is built with GEOS library
int within(shapeobj shape2) Returns true if the shape is entirely within the shape2 passed as argument. Else returns
false. Only available if php/mapscript is built with GEOS library.
styleObj
Constructor
Instances of styleObj are always embedded inside a classObj or labelObj.
new styleObj(classObj class [, styleObj style])
// or
new styleObj(labelObj label [, styleObj style])
or using the old constructor (do not support a labelObj at first argument)
5.1. MapScript
335
MapServer Documentation, Release 7.0.6
styleObj ms_newStyleObj(classObj class [, styleObj style])
The second argument ‘style’ is optional. If given, the new style created will be a copy of the style passed as argument.
Members
Type
double
int
colorObj
colorObj
double
double
double
double
double
double
int
int
int
colorObj
string
double
int
string
double
Name
angle
antialias
backgroundcolor
color
maxsize
maxvalue
maxwidth
minsize
minvalue
minwidth
offsetx
offsety
opacity
outlinecolor
rangeitem
size
symbol
symbolname
width
Note
only supported for the AGG driver
Methods
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
string getBinding(const stylebinding) Get the attribute binding for a specfiled style property. Returns NULL if there
is no binding for this property.
$oStyle->setbinding(MS_STYLE_BINDING_COLOR, "FIELD_NAME_COLOR");
echo $oStyle->getbinding(MS_STYLE_BINDING_COLOR); // FIELD_NAME_COLOR
string getGeomTransform()
int removeBinding(const stylebinding) Remove the attribute binding for a specfiled style property. Added in
MapServer 5.0.
$oStyle->removebinding(MS_STYLE_BINDING_COLOR);
int set(string property_name, new_value) Set object property to a new value.
int setBinding(const stylebinding, string value) Set the attribute binding for a specfiled style property. Added in
MapServer 5.0.
5.1. MapScript
336
MapServer Documentation, Release 7.0.6
$oStyle->setbinding(MS_STYLE_BINDING_COLOR, "FIELD_NAME_COLOR");
This would bind the color parameter with the data (ie will extract the value of the color from the field called
“FIELD_NAME_COLOR”
int setGeomTransform(string value)
int updateFromString(string snippet) Update
MS_SUCCESS/MS_FAILURE.
a
style
from
a
string
snippet.
Returns
symbolObj
Constructor
new symbolObj(mapObj map, string symbolname)
or using the old constructor
int ms_newSymbolObj(mapObj map, string symbolname)
Creates a new symbol with default values in the symbolist.
Note: Using the new constructor, the symbol is automatically returned. The old constructor returns the id of the new
symbol.
If a symbol with the same name exists, it (or its id) will be returned. To get a symbol object using the old constructor,
you need to use a method on the map object:
$nId = ms_newSymbolObj($map, "symbol-test");
$oSymbol = $map->getSymbolObjectById($nId);
Members
Type
int
string
int
string
string
int
int
int
string
int
double
double
int
int
Name
antialias
character
filled
font
imagepath
inmapfile
patternlength
position
name
numpoints
sizex
sizey
transparent
transparentcolor
5.1. MapScript
Note
read-only
If set to TRUE, the symbol will be saved inside the mapfile.
read-only
read-only
337
MapServer Documentation, Release 7.0.6
Methods
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
array getPatternArray() Returns an array containing the pattern. If there is no pattern, it returns an empty array.
array getPointsArray() Returns an array containing the points of the symbol. Refer to setpoints to see how the array
should be interpreted. If there are no points, it returns an empty array.
int set(string property_name, new_value) Set object property to a new value.
int setImagePath(char filename) Loads a pixmap symbol specified by the filename. The file should be of either Gif
or Png format.
int setPattern(array int) Set the pattern
MS_SUCCESS/MS_FAILURE.
of
the
symbol
(used
for
dash
patterns).
Returns
int setPoints(array double) Set the points of the symbol. Note that the values passed is an array containing the x and
y values of the points. Returns MS_SUCCESS/MS_FAILURE. Example:
$array[0] = 1 # x value of the first point
$array[1] = 0 # y values of the first point
$array[2] = 1 # x value of the 2nd point
....
Example of usage
1. create a symbol to be used as a dash line
$nId = ms_newsymbolobj($gpoMap, "mydash");
$oSymbol = $gpoMap->getsymbolobjectbyid($nId);
$oSymbol->set("filled", MS_TRUE);
$oSymbol->set("sizex", 1);
$oSymbol->set("sizey", 1);
$oSymbol->set("inmapfile", MS_TRUE);
$aPoints[0] = 1;
$aPoints[1] = 1;
$oSymbol->setpoints($aPoints);
$aPattern[0] = 10;
$aPattern[1] = 5;
$aPattern[2] = 5;
$aPattern[3] = 10;
$oSymbol->setpattern($aPattern);
$style->set("symbolname", "mydash");
2. Create a TrueType symbol
$nId = ms_newSymbolObj($gpoMap, "ttfSymbol");
$oSymbol = $gpoMap->getSymbolObjectById($nId);
$oSymbol->set("type", MS_SYMBOL_TRUETYPE);
$oSymbol->set("filled", true);
$oSymbol->set("character", "&#68;");
$oSymbol->set("font", "ttfFontName");
5.1. MapScript
338
MapServer Documentation, Release 7.0.6
webObj
Constructor
Instances of webObj are always are always embedded inside the mapObj.
Members
Type
string
string
string
rectObj
string
string
string
string
string
string
double
string
hashTableObj
double
string
string
string
string
Name
browseformat
empty
error
extent
footer
header
imagepath
imageurl
legendformat
log
maxscaledenom
maxtemplate
metadata
minscaledenom
mintemplate
queryformat
template
temppath
Note
read-only
read-only
read-only
Methods
string convertToString() Saves the object to a string. Provides the inverse option for updateFromString.
void free() Free the object properties and break the internal references. Note that you have to unset the php variable
to free totally the resources.
int set(string property_name, new_value) Set object property to a new value.
int updateFromString(string snippet) Update
MS_SUCCESS/MS_FAILURE.
a
web
object
from
a
string
snippet.
Returns
PHP MapScript Migration Guide
Author Alan Boudreault
Contact aboudreault at mapgears.com
Revision $Revision: 10033 $
Date $Date: 2010-03-30 15:58:30 -0400 (Tue, 30 Mar 2010) $
5.1. MapScript
339
MapServer Documentation, Release 7.0.6
Table of Contents
• PHP MapScript Migration Guide
– Introduction
– Migrating 5.6 to 6.0
* PHP Version Required
* Error Reporting
* Manipulating Objects
* Class Properties
* Class Methods
* layerObj
* mapObj
* referenceMapObj
* shapeFileObj
* labelCacheObj
* Methods that now return MS_SUCCESS/MS_FAILURE
* Methods that now return NULL on failure
* Methods that now return an empty array
Introduction
This document describes the changes that must be made to PHP MapScript applications when migrating from one
MapServer version to another (i.e. backwards incompatibilities), as well as information on some of the new features.
Migrating 5.6 to 6.0
PHP Version Required
PHP 5.2.0 or more recent is required. The support for earlier versions has been dropped.
Error Reporting
PHP MapScript now uses exceptions for error reports. All errors are catchable. There are no more fatal errors reported
via the standard uncatchable PHP system (Only Warnings).
Manipulating Objects
• Object properties can be set like all other PHP objects.
$map->scaledenom = 25000;
5.1. MapScript
340
MapServer Documentation, Release 7.0.6
Note: The set/setProperty methods are still available.
• Objects can be created with the PHP “new” operator.
$myShape = ms_newShapeObj(MS_SHAPE_LINE); // or
$myShape = new shapeObj(MS_SHAPE_LINE);
Note: All object constructors throw an exception on failure.
Note: ms_newSymbolObj() and new symbolObj() are different
• ms_newSymbolObj() returns the id of the new/existing symbol.
• new symbolObj() returns the symbolObj. You don’t need to get it with getSymbolObjectById().
• Cloneable objects should be cloned with the PHP clone keyword. There is no more clone methods.
Class Properties
Class properties that have been removed:
• classObj: maxscale, minscale
• layerObj: labelsizeitem, labelangleitem, labelmaxscale, labelminscale, maxscale, minscale, symbolscale, transparency
• legendObj: interlace, transparent
• mapObj: imagetype, imagequality, interlace, scale, transparent
• scalebarObj: interlace, transparent
• symbolObj: gap, stylelength
• webObj: minscale, maxscale
Class Methods
Class methods that have been removed:
• imageObj: free
• layerObj: getFilter, getShape
• lineObj: free
• pointObj: free
• projectionObj: free
• rectObj: free
• shapeObj: union_geos
• symbolObj: getstylearray
• classObj: clone
5.1. MapScript
341
MapServer Documentation, Release 7.0.6
• styleObj: clone
• mapObj: clone
• outputFormatObj: getformatoption, setformatoption
layerObj
layerObj->clearProcessing() method now returns void.
mapObj
mapObj->queryByIndex(): default behavior for the addToQuery parameter was not ok, now it is.
referenceMapObj
referenceMapObj has new properties: marker, markername, markersize, maxboxsize, minboxsize.
shapeFileObj
shapeFileObj is automatically closed/writed on destroy. (At the end of the script or with an explicit free(), unset())
labelCacheObj
To free the cache, you’ll have to call the method freeCache() rather than free().
Methods that now return MS_SUCCESS/MS_FAILURE
• layerObj: setProcessing, addFeature, draw
• mapObj: moveLayerUp, moveLayerDown, zoomRectangle, zoomScale, setProjection, setWKTProjection, setLayersDrawingOrder
• outputFormatObj: validate
• scalebarObj: setImageColor
• symbolObj: setPoints, setPattern
Methods that now return NULL on failure
• classObj: clone
• mapObj: clone, draw, drawQuery getLayerByName, getProjection
• layerObj: nextShape, getExtent
• styleObj: clone
5.1. MapScript
342
MapServer Documentation, Release 7.0.6
Methods that now return an empty array
• layerObj: getItems, getProcessing, getGridIntersectionCoordinates
• mapObj: getLayersIndexByGroup, getAllGroupNames, getLayersDrawingOrder, getAllLayerNames
• symbolObj: getPatternArray
By Example
Author Vinko Vrsalovic
Contact el at vinko.cl
Last Updated 2005/12/12
Contents
• By Example
– Introduction
– MapScript overview
– Our first application
– Conclusions
Introduction
The purpose of this document is to be a step by step explanation of the PHP MapScript API with practical examples
for each of them. It is assumed a basic knowledge of MAP and MapServer, and familiarity with the PHP (scripting)
and HTML (markup) languages . This document was originally created for MapServer v4.0, but the examples still
apply to more recent versions.
Let’s Begin...
Hello, kind reader. I am Tut, thank you for downloading me. I am sorry, but I am just a technical manual so I cannot
answer any questions. The maintainer, a handsome, very nice and lazy guy according to what I saw from the other
side of the screen, maybe will be able to answer your question(s). I am currently here to tell you about MapScript in
its PHP incarnation. At my current age, I will be more useful to beginners than advanced users, even though I hope
that some day I will be sufficiently old to be useful to advanced MapScript programmers.
Let’s hope I live long enough... sigh.
But enough with my personal problems, let myself begin. My duty is to familiarize you with MapScript, and in
particular with PHP MapScript. When I end, you are expected to understand what MapScript is, and to be able to
write applications to display and navigate that is, zooming and panning over shapefiles via a web browser.
What follows are the questions you must answer affirmatively before accompanying me through the rest of this journey
(I apologize for my maintainer’s lack of literary taste).
Do you have running somewhere...
• a web server capable of running PHP as a CGI (Apache will do)?
• the PHP language configured as a CGI, version 4.1.2 or higher? I recommend 4.3 onwards.
5.1. MapScript
343
MapServer Documentation, Release 7.0.6
• PHP MapScript, version 4.0 or later? PHP MapScript Installation
Can you...
• code PHP or are willing to learn how to?
• write and understand HTML documents? (Note that Javascript is a plus)
• tell somebody what on earth is a shapefile [or a PostGIS table]?
Outline of this Document
• A general overview of MapScript, in a language independent way
• A trivial example
• A simple example
• Conclusion
You can also go to each part directly through my table of contents located at the top, if you wish to skip some sections.
MapScript overview
Ok, now I’m at last arriving at a point I will enjoy. This overview intends to clear some common misconceptions
beginners encounter when first facing MapScript and to give a general overview about MapScript’s internals. For now,
just look at the following diagram (I apologize again for the maintainer’s lack of graphic design taste).
5.1. MapScript
344
MapServer Documentation, Release 7.0.6
It all starts as everything on the Web. A browser requests a certain URL through HTTP. The request arrives at the web
server, which, in turn, delivers a file or executes a program and then delivers its output back to the browser. Yes, I
know you knew that, but I have been told to be as complete as possible, and I will try to.
In MapScript’s case, the server executes a certain script, which contains standard language functionality, that is, the
same functionality you would have in that language without MapScript, plus access to almost all of the MapServer C
API, the level of completeness of MapServer API support varies a bit with the language you choose, but I think it is my
duty to tell you almost every available flavor of MapScript is usable. This API, exposed now in your scripting language
through the MapScript module, allows you to do many GIS-like operations on spatial data, including read-write access
to shapefiles, reprojection of data, and many others. For more information on the API, click over the link above. For
other flavors, you can check their own documentation, you will see there is not much difference.
The CGI version of MapServer is not required to run MapScript applications, just as you don’t need a particular
MapScript module to run the CGI. The CGI version has many features out-of-the-box, MapScript is just an API,
so with MapScript you must start from scratch or with some of the examples available. Think of the CGI as of a
MapScript application written directly in C, with direct access to the MapServer C API. Sometimes the out-of-the-box
functionality has some limits which can be surpassed by MapScript, but not embedded within the CGI. In other words,
the CGI is not scriptable, but you can program all the CGI and more with MapScript. This may seem a strange thing
to clarify, but is a common misconception, just check the list archives if you are not inclined to believe me.
As with MapServer itself, MapScript can be configured using only map files, but, unlike the CGI, also includes the
5.1. MapScript
345
MapServer Documentation, Release 7.0.6
possibility of dynamically create maps or modify existing ones and to (and here is the key to the flexibility that
MapScript has) mix this information with other sources of non GIS data, such as user input, non spatial and spatial
databases, text files, etc. and that you can use every single module your language provides. The power of this
approach is tremendous, and the most restrictive limit is your imagination. As always, flexibility comes with a price,
performance. It’s generally slower to use a scripting language instead of C, but nowadays this shouldn’t be a big worry.
And you can still program directly in C (there are not much documents about how to do it, though you might want to
check the mapserver-dev list) if you would like to.
The input and output formats MapScript can handle are exactly the same as the ones configured when you build
MapServer/MapScript. But one of the most important things to remember is that, basically, you feed geographic data
and relevant user input (for instance clicks over the map image) to MapScript and as a result get one or more file(s),
typically standard image files such as a PNG or JPEG. So you can apply anything you’ve seen in any server side
scripted web application, DHTML, Java applets, CSS, HTML templates, sessions, you name it.
Our first application
In this first example, I will tell you how to display a shapefile on a web page using a map file.
The Map File
Here’s the map file:
1
2
3
4
5
6
7
NAME "Europe in purple"
SIZE 400 400
STATUS ON
SYMBOLSET "/var/www/html/maps/symbols/symbols.sym"
EXTENT -5696501 1923039 5696501 11022882
UNITS METERS
SHAPEPATH "/var/www/html/maps/data"
8
9
WEB
IMAGEPATH "/var/www/html/maps/tmp/"
IMAGEURL "/tmp/"
10
11
12
END
13
14
15
16
17
18
19
20
21
22
23
24
25
26
LAYER
NAME "Europe"
TYPE POLYGON
STATUS ON
DATA "europe"
CLASS
STYLE
COLOR 110 50 100
OUTLINECOLOR 200 200 200
SYMBOL 0
END
END
END
27
28
END
Here I have shown a map with a single layer, where the europe.shp, europe.shx and europe.dbf files must be located in
the subdirectory called data. The symbols are located in the symbols subdirectory. All this locations are relative from
the place the map file is, but better safe than sorry, I guess. The web section is used to define where will the images be
saved and in what URL will they be available.
5.1. MapScript
346
MapServer Documentation, Release 7.0.6
Displaying the map with MapScript
To display a map the following MapScript objects and methods will be used:
• MapObj object
• imageObj object
MapObj methods:
• The constructor method: MapObj ms_newMapObj(string map_file_name[,string new_map_path])
• The draw method: imageObj draw()
imageObj methods:
• The saveWebImage method: string saveWebImage()
The code looks like this:
1
<?php
2
3
dl('php_mapscript.so');
4
5
$map_path="/var/www/html/ms/map_files/";
6
7
8
9
$map = ms_newMapObj($map_path."europe.map");
$image=$map->draw();
$image_url=$image->saveWebImage();
10
11
?>
12
13
14
15
16
17
18
19
20
<HTML>
<HEAD>
<TITLE>Example 1: Displaying a map</TITLE>
</HEAD>
<BODY>
<IMG SRC=<?php echo $image_url; ?> >
</BODY>
</HTML>
The code I will present through the rest of this document will follow the following rule:
• Every non empty line is numbered
This code will render an image corresponding to the shapefile europe and display it on a HTML page.
Code Explanation
• In line 2 it is loaded the MapScript extension (you may not need it if your php.ini file is configured to automatically load it).
• Line 3 declares a variable that holds the absolute path for the mapfile.
• Line 4 creates an instance of the MapObj object using the constructor. As you can see, the constructor receives
the location of the map file as its only required parameter, and the map file received the europe.map name.
• Afterwards the draw method of the map object is called to render the image defined by the map file (line 5). The
result (an imageObj) is saved in the $image variable.
• Line 6 calls the saveWebImage method to generate the image file, it returns a string which represents the URL
as defined in the mapfile (in this case, /tmp/filename.png).
5.1. MapScript
347
MapServer Documentation, Release 7.0.6
• The rest of the lines are pure HTML, except line 13, that defines the source URL of the image will be the value
stored in $image_url.
You should test the application on your system, to check that it really works and to solve the problems that may arise
on your particular configuration before moving on to the more complex examples.
Output
The output (using the europe shapefile) should look like this:
Zooming and Panning
Now I will tell you how to add zoom and pan capabilities to the code.
Here goes the list of new methods and objects called.
New Objects:
• pointObj
5.1. MapScript
348
MapServer Documentation, Release 7.0.6
• rectObj
New Methods and Members called:
• The zoompoint method of the map object: void zoompoint(int nZoomFactor, pointObj oPixelPos, int nImageWidth, int nImageHeight, rectObj oGeorefExt).
• The setextent method of the map object: $map->setextent(double minx, double miny, double maxx, double
maxy);.
• The extent, width and height members of the map object.
• The constructors of RectObj and PointObj: $point = ms_newPointObj(); $rect = ms_newRectObj();
• The setXY method of the point object: $point->setXY(double x_coord, double y_coord);
• The setextent method of the rectangle object: $rect->setextent(double minx, double miny, double maxx, double
maxy);
The .map file remains the same as the one presented in the previous example.
PHP/MapScript Code
Here I present the new code.
1
<?php
2
3
dl('php_mapscript.so');
4
5
// Default values and configuration
6
7
8
9
10
$val_zsize=3;
$check_pan="CHECKED";
$map_path="/var/www/html/ms/map_files/";
$map_file="europe.map";
11
12
$map = ms_newMapObj($map_path.$map_file);
13
14
15
16
if ( isset($_POST["mapa_x"]) && isset($_POST["mapa_y"])
&& !isset($_POST["full"]) ) {
17
18
$extent_to_set = explode(" ",$_POST["extent"]);
19
20
21
$map->setextent($extent_to_set[0],$extent_to_set[1],
$extent_to_set[2],$extent_to_set[3]);
22
23
24
$my_point = ms_newpointObj();
$my_point->setXY($_POST["mapa_x"],$_POST["mapa_y"]);
25
26
$my_extent = ms_newrectObj();
27
28
29
$my_extent->setextent($extent_to_set[0],$extent_to_set[1],
$extent_to_set[2],$extent_to_set[3]);
30
31
32
33
34
35
$zoom_factor = $_POST["zoom"]*$_POST["zsize"];
if ($zoom_factor == 0) {
$zoom_factor = 1;
$check_pan = "CHECKED";
$check_zout = "";
5.1. MapScript
349
MapServer Documentation, Release 7.0.6
$check_zin = "";
} else if ($zoom_factor < 0) {
$check_pan = "";
$check_zout = "CHECKED";
$check_zin = "";
} else {
$check_pan = "";
$check_zout = "";
$check_zin = "CHECKED";
}
36
37
38
39
40
41
42
43
44
45
46
$val_zsize = abs($zoom_factor);
47
48
$map->zoompoint($zoom_factor,$my_point,$map->width,$map->height,
$my_extent);
49
50
51
52
}
53
54
55
56
$image=$map->draw();
$image_url=$image->saveWebImage();
57
58
59
$extent_to_html = $map->extent->minx." ".$map->extent->miny." "
.$map->extent->maxx." ".$map->extent->maxy;
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
?>
<HTML>
<HEAD>
<TITLE>Map 2</TITLE>
</HEAD>
<BODY>
<CENTER>
<FORM METHOD=POST ACTION=<?php
<TABLE>
<TR>
<TD>
<INPUT TYPE=IMAGE
</TD>
</TR>
<TR>
<TD>
Pan
</TD>
<TD>
<INPUT TYPE=RADIO
</TD>
</TR>
<TR>
<TD>
Zoom In
</TD>
<TD>
<INPUT TYPE=RADIO
</TD>
</TR>
<TR>
<TD>
Zoom Out
5.1. MapScript
echo $HTTP_SERVER_VARS['PHP_SELF']?>>
NAME="mapa" SRC="<?php echo $image_url?>">
NAME="zoom" VALUE=0 <?php echo $check_pan?>>
NAME="zoom" VALUE=1 <?php echo $check_zin?>>
350
MapServer Documentation, Release 7.0.6
94
95
</TD>
<TD>
<INPUT TYPE=RADIO NAME="zoom" VALUE=-1 <?php echo $check_zout?>>
96
97
98
99
100
</TD>
</TR>
<TR>
<TD>
Zoom Size
101
102
103
</TD>
<TD>
<INPUT TYPE=TEXT NAME="zsize" VALUE="<?php echo $val_zsize?>"
SIZE=2>
104
105
106
107
108
109
</TD>
</TR>
<TR>
<TD>
Full Extent
110
111
112
</TD>
<TD>
<INPUT TYPE=SUBMIT NAME="full" VALUE="Go"
SIZE=2>
113
114
115
116
117
118
119
120
121
</TD>
</TABLE>
<INPUT TYPE=HIDDEN NAME="extent" VALUE="<?php echo $extent_to_html?>">
</FORM>
</CENTER>
</BODY>
</HMTL>
This code will zoom out, zoom in, pan, and restore to full extent the image displayed in the previous example.
It looks much more complicated than it really is, much of the lines are the HTML code, and much of the remaining
PHP code is just to deal with the forms and such.
You should try it and look at how it works first. Try it in your own server by copying and pasting the code.
Now it’s time for you to play with it a little and look at the source in your browser to check how it changes.
Done?, now let’s start the explanation with the HTML part.
Code Explanation - HTML
Line 49 declares a form, and line 53 declares the image generated by MapScript to be part of that form, so when you
click on it, the X and Y coordinates of the click (in pixels) will be sent along with the other data for the PHP code to
process.
If you are familiar with HTML and PHP, the rest of the HTML code should be straightforward for you to understand
with the exception of line 98, that will be explained in due time.
Code Explanation - PHP
Now look at the PHP code, it’s almost the same code used in example 1, with the addition of lines 9 to 37. What do
these lines do?
Line 9 checks the relevant variables from the form have been set. ‘mapa_x’ and ‘mapa_y’ represent the X and Y
coordinates of the click over the image, and ‘full’ represents the click on the ‘Full Extent’ button.
5.1. MapScript
351
MapServer Documentation, Release 7.0.6
The first time the page is displayed the code between the if statement doesn’t get executed, but the rest of the code
does. Lines 40 and 41 set the ‘$extent_to_html’ variable with the values of the extent defined in the map file separated
by spaces; that value will be put in the HTML variable ‘extent’ in line 98.
Now look at line 11 and 12. We are inside the if statement, that means the form has been submitted at least once. We
grab the extent stored in the previous execution (the ‘extent’ HTML variable) of the code and set the extent of the map
to be that last extent. This allows to zoom or pan with respect of the previous extent, not the extent that is set in the
map file.
From that last paragraph you can deduce that all the default values are set in the map file, and anything that you change
through MapScript and would like to remain in your code, must be stored somehow. In this case it is done through
hidden variables in a form. For more advanced applications you could use session variables or a database.
Now you should be able to see why the ‘Full Extent’ button works. If you check line 10, it says that if you haven’t
pressed the button, skip the code in the if statement, so the extent is reset to the value that the map file has. You should
also see that it isn’t necessarily a full extent (in case the extent in the map file is not full extent).
Lines 14 and 15 declare a new point object and initialize it with the values the user clicked on. You should not forget
that those values are in pixels, not in georeferenced coordinates.
Lines 16 through 18 create a new rectangle object and set it with the extent of the previous image, just like it is done
on line 12. In fact this would work too: $my_extent = $map->extent;.
To do all the zooming and panning, the zoompoint function in called on line 35, but first the arguments it receives must
be prepared. You can determine the point the user clicked on, and the extent of the image ($my_point and $my_extent,
respectively), but now you have to determine the zoom factor. That’s what lines 19 to 33 do. If you wondered why the
values of the radio buttons where 0, -1, and 1 for pan, zoom in and zoom out, now you will know the reason.
A zoom factor of 1 tells zoompoint that the operation is pan, a negative value indicates zoom out and a positive value
indicates zoom in. So, by means of multiplying the value received for the radio buttons (HTML variable ‘zoom’) by
the size of the zoom the user entered the zoom factor is calculated. If that value is 0, that means the user selected the
pan operation, so ‘$zoom_factor’ is set to 1, otherwise the result of the multiplication is the zoom factor zoompoint
needs to receive. The other lines are to preserve the button the user clicked on the next time. Line 34 tries to preserve
the value of the zoom size the user entered (It doesn’t do that all the time, when and why that line fails? That’s for you
to find out).
And finally, line 34 calls the zoompoint method with the zoom factor obtained, the point built from the pixel coordinates (I insist on that issue because zoompoint is almost the only method that receives the coordinates in pixels, for the
other methods you must convert pixels to georeferenced coordinates on your own), the height and width of the image,
and the extent.
After calling zoompoint, the extent of the image is changed accordingly to the operation performed (or, better put, the
zoom factor). So then the image is drawn and the current extent saved (after the zooming) for use in the next iteration.
Conclusions
Well, it’s time for me to go recharge my batteries. So I will use this last energy to share some final words. The
examples I have managed to present here are very basic but you should now be able to devise ways to improve them
and suit things to your needs. Keep in mind that you can preprocess, store, read, write data from any source you
can usually read through PHP, plus all the sources MapServer can handle for GIS data. You can even process some
GIS data with PHP only if the need would arise (SQL sources are a good example of this). You can also do hybrid
approaches where some script prepares data which is then shown through the CGI interface to MapServer, or create
data on the fly based on input from a GPS, etc, etc. The possibilities are just too many to enumerate completely. As I
already said your imagination is the limit. The next version of this document will include examples that include more
than one layer, with different datasources (not just shapefiles) and creation of dynamic layers and classes. If you have
a better idea or would like to see some other thing here first, please drop a note to my maintainer.
5.1. MapScript
352
MapServer Documentation, Release 7.0.6
In the meantime, if you need bigger examples you can refer to the original “GMap demo” (you can download the source
here), or the MapTools site (for the older MapLab, Chameleon applications, which were built on PHPMapScript).
Goodbye, and thanks for reading this far.
5.1.4 Python MapScript Appendix
Author Sean Gillies
Contents
• Python MapScript Appendix
– Introduction
– Classes
– Exception Handling
Introduction
The Python MapScript module contains some class extension methods that have not yet been implemented for other
languages.
Classes
References to sections below will be added here as the documentation grows.
imageObj
The Python Imaging Library, http://www.pythonware.com/products/pil/, is an indispensable tool for image manipulation. The extensions to imageObj are all geared towards better integration of PIL in MapScript applications.
imageObj Methods
imageObj( PyObject arg1, PyObject arg2 [, PyObject arg3 ] ) [imageObj] Create a new instance which is either
empty or read from a Python file-like object that refers to a GD format image.
The constructor has 2 different modes. In the blank image mode, arg1 and arg2 should be the desired width and
height in pixels, and the optional arg3 should be either an instance of outputFormatObj or a GD driver name as
a shortcut to a format. In the image file mode, arg1 should be a filename or a Python file or file-like object. If
the file-like object does not have a “seek” attribute (such as a urllib resource handle), then a GD driver name
must be provided as arg2.
Here’s an example of creating a 320 pixel wide by 240 pixel high JPEG using the constructor’s blank image
mode:
image = mapscript.imageObj(320, 240, 'GD/JPEG')
In image file mode, interesting values of arg1 to try are instances of StringIO:
5.1. MapScript
353
MapServer Documentation, Release 7.0.6
s = StringIO()
pil_image.save(s)
# Save an image manipulated with PIL
ms_image = imageObj(s)
Or the file-like object returned from urlopen
url = urllib.urlopen('http://mapserver.gis.umn.edu/bugs/ant.jpg')
ms_image = imageObj(url, 'GD/JPEG')
write( [ PyObject file ] ) [void] Write image data to a Python file-like object. Default is stdout.
pointObj
pointObj Methods
__str__() [string] Return a string formatted like
{ 'x': %f , 'y': %f }
with the coordinate values substituted appropriately. Usage example:
>>> p = mapscript.pointObj(1, 1)
>>> str(p)
{ 'x': 1.000000 , 'y': 1.000000 }
Note that the return value can be conveniently eval’d into a Python dictionary:
>>> p_dict = eval(str(p))
>>> p_dict['x']
1.000000
rectObj
rectObj Methods
__contains__( pointObj point ) [boolean] Returns True if point is inside the rectangle, otherwise returns False.
>>> r
>>> p
>>> p
False
>>> p
True
= mapscript.rectObj(0, 0, 1, 1)
= mapscript.pointObj(2, 0)
in r
# outside
not in r
__str__() [string] Return a string formatted like
{ 'minx': %f , 'miny': %f , 'maxx': %f , 'maxy': %f }
with the bounding values substituted appropriately. Usage example:
>>> r = mapscript.rectObj(0, 0, 1, 1)
>>> str(r)
{ 'minx': 0.000000 , 'miny': 0.000000 , 'maxx': 1.000000 , 'maxy': 1.000000 }
5.1. MapScript
354
MapServer Documentation, Release 7.0.6
Note that the return value can be conveniently eval’d into a Python dictionary:
>>> r_dict = eval(str(r))
>>> r_dict['minx']
0.000000
Exception Handling
The Python MapScript module maps a few MapServer errors into Python exceptions. Attempting to load a non-existent
mapfile raises an ‘IOError’, for example
>>> import mapscript
>>> mapfile = '/no/such/file.map'
>>> m = mapscript.mapObj(mapfile)
Traceback (most recent call last):
File "<stdin>", line 1, in ?
File "/usr/lib/python2.3/site-packages/mapscript.py", line 799, in __init__
newobj = _mapscript.new_mapObj(*args)
IOError: msLoadMap(): Unable to access file. (/no/such/file.map)
>>>
The message of the error is written by ‘msSetError’ and so is the same message that CGI mapserv users see in error
logs.
5.1.5 Python MapScript Image Generation
Author Sean Gillies
Last Updated 2008/07/15
Table of Contents
• Python MapScript Image Generation
– Introduction
– Imagery Overview
– The imageObj Class
– Image Output
– Images and Symbols
Introduction
The MapScript HOWTO docs are intended to complement the API reference with examples of usage for specific
subjects. All examples in this document refer to the mapfile and testing layers distributed with MapServer 4.2+ and
found under mapserver/tests.
5.1. MapScript
355
MapServer Documentation, Release 7.0.6
Pseudocode
All examples will use a pseudocode that is consistent with the language independent API reference. Each line is a
statement. For object attributes and methods we use the dot, ‘.’, operator. Creation and deletion of objects will be
indicated by ‘new’ and ‘del’ keywords. Other than that, the pseudocode looks a lot like Python.
Imagery Overview
The most common use of MapServer and MapScript is to create map imagery using the built-in GD format drivers:
GD/GIF, GD/PNG, GD/PNG24, and GD/JPEG. This imagery might be saved to a file on disk or be streamed directly
to another device.
The imageObj Class
Imagery is represented in MapScript by the imageObj class. Please see the API Reference (MapScript.txt) for class
attribute and method details.
Creating imageObj from a mapObj
The mapObj class has two methods that return instances of imageObj: ‘draw’, and ‘prepareImage’. The first returns a
full-fledged map image just as one would obtain from the mapserv CGI program
test_map = MapScript.mapObj('tests/test.map')
map_image = test_map.draw()
A properly sized and formatted blank image, without any layers, symbols, or labels, will be generated by ‘prepareImage’
blank_image = test_map.prepareImage()
Creating a new imageObj
The imageObj class constructor creates new instances without need of a map
format = MapScript.outputFormatObj('GD/JPEG')
image = MapScript.imageObj(300, 200, format)
# 300 wide, 200 high JPEG
and can even initialize from a file on disk
# First three args are overridden by attributes of the disk image file
disk_image = MapScript.imageObj(-1, -1, NULL, 'tests/test.png')
Image Output
Creating files on disk
Imagery is saved to disk by using the ‘save’ method. By accessing the ‘extension’ attribute of an image’s format, the
proper file extension can be used without making any assumptions
5.1. MapScript
356
MapServer Documentation, Release 7.0.6
filename = 'test.' + map_image.format.extension
map_image.save(filename)
If the image is using a GDAL/GTiff-based format, a GeoTIFF file can be created on disk by adding a mapObj as a
second optional argument to ‘save’
map_image.save(filename, test_map)
Direct Output
An image can be dumped to an open filehandle using the ‘write’ method. By default, the filehandle is ‘stdout’
# Send an image to a web browser
print "Content-type: " + map_image.format.mimetype + "\n\n"
map_image.write()
This method is not fully functional for all SWIG MapScript languages. See the API Reference (MapScript.txt) for
details. The ‘write’ method is new in 4.4.
Images and Symbols
The symbolObj::getImage() method will return an instance of imageObj for pixmap symbols
symbol = test_map.symbolset.getSymbolByName('home-png')
image = symbol.getImage()
There is a symmetric ‘setImage’ method which loads imagery into a symbol, allowing pixmap symbols to be created
dynamically
new_symbol = MapScript.symbolObj('from_image')
new_symbol.type = MapScript.MS_SYMBOL_PIXMAP
new_symbol.setImage(image)
index = test_map.symbolset.appendSymbol(new_symbol)
The get/setImage methods are new in MapServer 4.4.
5.1.6 Mapfile Manipulation
Author Sean Gillies
Contents
• Mapfile Manipulation
– Introduction
– Mapfile Overview
– The mapObj Class
– Children of mapObj
– Metadata
5.1. MapScript
357
MapServer Documentation, Release 7.0.6
Introduction
The MapScript HowTo docs are intended to complement the API reference with examples of usage for specific subjects. All examples in this document refer to the mapfile and testing layers distributed with MapServer 4.2+ and found
under mapserver/tests.
Pseudocode
All examples will use a pseudocode that is consistent with the language independent API reference. Each line is a
statement. For object attributes and methods we use the dot, ‘.’, operator. Creation and deletion of objects will be
indicated by ‘new’ and ‘del’ keywords. Other than that, the pseudocode looks a lot like Python.
Mapfile Overview
By “Mapfile” here, I mean all the elements that can occur in (nearly) arbitrary numbers within a MapScript mapObj:
Layers, Classes, and Styles. MapServer 4.4 has greatly improved capability to manipulate these objects.
The mapObj Class
An instance of mapObj is a parent for zero to many layerObj children.
New instances
The mapfile path argument to the mapscript.mapObj constructor is now optional
empty_map = new mapscript.mapObj
generates a default mapObj with no layers. A mapObj is initialized from a mapfile on disk in the usual manner:
test_map = new mapscript.mapObj('tests/test.map')
Cloning
An independent copy, less result and label caches, of a mapObj can be produced by the new mapObj.clone() method:
clone_map = test_map.clone()
Note: the Java MapScript module implements a “cloneMap” method to avoid conflict with the clone method of Java’s
Object class.
Saving
A mapObj can be saved to disk using the save method:
clone_map.save('clone.map')
Frankly, the msSaveMap() function which is the foundation for mapObj::save is incomplete. Your mileage may vary.
5.1. MapScript
358
MapServer Documentation, Release 7.0.6
Children of mapObj
There is a common parent/child object API for Layers, Classes, and Styles in MapServer 4.4.
Referencing a Child
References to Layer, Class, and Style children are obtained by “getChild”-like methods of their parent:
layer_i
= test_map.getLayer(i)
class_ij = layer_i.getClass(j)
style_ijk = class_ij.getStyle(k)
These references are for convenience only. MapScript doesn’t have any reference counting, and you are certain to run
into trouble if you try to use these references after the parent mapObj has been deleted and freed from memory.
Cloning a Child
A completely independent Layer, Class, or Style can be created using the clone method of layerObj, classObj, and
styleObj:
clone_layer = layer_i.clone()
This instance has no parent, and is self-owned.
New Children
Uninitialized instances of layerObj, classObj, or styleObj can be created with the new constructors:
new_layer = new mapscript.layerObj
new_class = new mapscript.classObj
new_style = new mapscript.styleObj
and are added to a parent object using “insertChild”-like methods of the parent which returns the index at which the
child was inserted:
li = test_map.insertLayer(new_layer)
ci = test_map.getLayer(li).insertClass(new_class)
si = test_map.getLayer(li).getClass(ci).insertStyle(new_style)
The insert* methods create a completely new copy of the object and store it in the parent with all ownership taken on
by the parent.
see the API reference for more details.
Backwards Compatibility
The old style child object constructors with the parent object as a single argument:
new_layer = new mapscript.layerObj(test_map)
new_class = new mapscript.classObj(new_layer)
new_style = new mapscript.styleObj(new_class)
remain in MapServer 4.4.
5.1. MapScript
359
MapServer Documentation, Release 7.0.6
Removing Children
Child objects can be removed with “removeChild”-like methods of parents, which return independent copies of the
removed object:
# following from the insertion example ...
# remove the inserted style, returns a copy of the original new_style
removed_style = test_map.getLayer(li).getClass(ci).removeStyle(si)
removed_class = test_map.getLayer(li).removeClass(ci)
removed_layer = test_map.removeLayer(li)
Metadata
Map, Layer, and Class metadata are the other arbitrarily numbered elements (well, up to the built-in limit of 41) of a
mapfile.
New API
In MapServer 4.4, the metadata attributes of mapObj.web, layerObj, and classObj are instances of hashTableObj, a
class which functions like a limited dictionary
layer.metadata.set('wms_name', 'foo')
name = layer.metadata.get('wms_name')
# returns 'foo'
You can iterate over all keys in a hashTableObj like
key = NULL
while (1):
key = layer.metadata.nextKey(key)
if key == NULL:
break
value = layer.metadata.get(key)
...
See the API Reference (mapscript.txt) for more details.
Backwards Compatibility for Metadata
The old getMetaData and setMetaData methods of mapObj, layerObj, and classObj remain for use by older programs.
5.1.7 Querying
Author Sean Gillies
Contents
• Querying
– Introduction
– Querying Overview
5.1. MapScript
360
MapServer Documentation, Release 7.0.6
– Attribute Queries
– Spatial Queries
Introduction
All examples in this document refer to the mapfile and testing layers distributed with MapServer 4.2+ and found under
mapserver/tests.
Pseudocode
All examples will use a pseudocode that is consistent with the language independent API reference. Each line is a
statement. For object attributes and methods we use the dot, ‘.’, operator. Creation and deletion of objects will be
indicated by ‘new’ and ‘del’ keywords. Other than that, the pseudocode looks a lot like Python.
Querying Overview
The Query Result Set
Map layers can be queried to select features using spatial query methods or the attribute query method. Ignoring for
the moment whether we are executing a spatial or attribute query, results are obtained like so:
layer.query()
results = layer.getResults()
# not an actual method!
In the case of a failed query or query with zero results, ‘getResults’ returns NULL.
Result Set Members
Individual members of the query results are obtained like:
...
# continued
if results:
for i in range(results.numresults):
result = results.getResult(i)
# iterate over results
This result object is a handle, of sorts, for a feature of the layer, having ‘shapeindex’ and ‘tileindex’ attributes that can
be used as arguments to ‘getFeature’.
Resulting Features
The previous example code can now be extended to the case of obtaining all queried features:
layer.query()
results = layer.getResults()
if results:
# open layer in preparation of reading shapes
layer.open()
5.1. MapScript
361
MapServer Documentation, Release 7.0.6
for i in range(results.numresults):
result = results.getResult(i)
layer.getFeature(result)
...
# do something with this feature
# Close when done
layer.close()
Backwards Compatibility
The API changed substantially with version 6.0 and backward compatibility was broken. Scripts will have to be
updated to work with the new API.
Attribute Queries
By Attributes
queryByAttributes()
Spatial Queries
By Rectangle
queryByRect()
By Point
queryByRect()
By Shape
queryByShape()
By Selection
queryByFeatures()
5.1. MapScript
362
CHAPTER 6
MapCache
6.1 MapCache 1.4
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
MapCache is a server that implements tile caching to speed up access to WMS layers. The primary objectives are to
be fast and easily deployable, while offering the essential features (and more!) expected from a tile caching solution.
6.1.1 Compilation & Installation
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
Author Alan Boudreault
Contact aboudreaut at magears.com
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Author Mathieu Coudert
Contact mathieu.coudert at gmail.com
Last Updated 2016-02-02
Table of Contents
• Compilation & Installation
– Getting the Source
– Linux Instructions
* Apache Module Specific Instructions
* nginx Specific Instructions
* CGI/FastCGI Specific Instructions
* Customizing the Build, Or If Something Went Wrong
363
MapServer Documentation, Release 7.0.6
– Windows Instructions
* Dependencies
* Configure Your Makefile
* Compilation
* Move the Module Into the Apache Directory
* Configure Your Installed Apache
* Test Your MapCache Module
Getting the Source
The MapCache project is located at https://github.com/mapserver/mapcache, and can be checked out with either:
# readonly
git clone git://github.com/mapserver/mapcache.git
# ssh authenticated
git clone git@github.com:mapserver/mapcache.git
# tarball
wget https://github.com/mapserver/mapcache/zipball/master
Linux Instructions
These instructions target a Debian/Ubuntu setup, but should apply with few modifications to any Linux installation.
MapCache requires a number of library headers in order to compile correctly:
• apache / apr / apr-util / apx2: these are included in the apache2-prefork-dev or apache2-threaded-dev packages, depending on which Apache MPM you are running. This package will pull in the necessary APR headers
that you would have to manually install if you are not buidling an Apache module (libaprutil1-dev and libapr1dev)
• png: libpng12-dev
• jpeg: libjpeg62-dev
• curl: libcurl4-gnutls-dev
The following libraries are not required, but recommended:
• pcre: libpcre3-dev. This will give you more powerful regular expression syntax when creating validation expressions for dimensions
• pixman: libpixman-1-dev. The pixel manipulation library is used for scaling and alpha-compositing images.
MapCache ships with some code to perform these tasks, but Pixman is generally faster as it includes code
optimized for modern CPUs (SSE2, MMX, etc...)
The following libraries are not required, but needed to enable additional functionalities:
• fcgi: libfcgi-dev. Needed to build a FastCGI program if you don’t want to run MapCache as an Apache module
• gdal / geos: libgdal1-dev libgeos-dev. Needed to enable advanced seeding options (for only seeding tiles that
intersect a given geographical feature)
• sqlite: libsqlite3-dev. For enabling the SQLite backend storages
• tiff: libtiff4-dev. For enabling the TIFF backend storages
6.1. MapCache 1.4
364
MapServer Documentation, Release 7.0.6
• berkeley db libdb4.8-dev : For enabling the Berkeley DB backend storages
Note: MapCache now builds with CMake.
For Unix users installing all packages to the default locations, the compilation process should continue with:
$
$
$
$
$
$
$
cd mapcache
mkdir build
cd build
cmake ..
# follow instructions below if missing a dependency
make
sudo make install
Apache Module Specific Instructions
The make install above installs the Apache module, but if you specifically need to install only the Apache module you
can do the following:
$ sudo make install-module
$ sudo ldconfig
The installation script takes care of putting the built module in the Apache module directory. The process for activating
a module is usually distro specific, but can be resumed by the following snippet that should be present in the Apache
configuration file ( e.g. /usr/local/httpd/conf/httpd.conf or /etc/apache2/sites-available/default ):
LoadModule mapcache_module
modules/mod_mapcache.so
Next, a MapCache configuration is mapped to the server URL with the following snippet:
For Apache < 2.4:
<IfModule mapcache_module>
<Directory /path/to/directory>
Order Allow,Deny
Allow from all
</Directory>
MapCacheAlias /mapcache "/path/to/directory/mapcache.xml"
</IfModule>
For Apache >= 2.4:
<IfModule mapcache_module>
<Directory /path/to/directory>
Require all granted
</Directory>
MapCacheAlias /mapcache "/path/to/directory/mapcache.xml"
</IfModule>
Before you restart, copy the example mapcache.xml file to the location specified in your Apache configuration:
$ cp mapcache.xml /path/to/directory/mapcache.xml
Finally, restart Apache to take the modified configuration into account
6.1. MapCache 1.4
365
MapServer Documentation, Release 7.0.6
$ sudo apachectl restart
If you have not disabled the demo service, you should now have access to it on http://myserver/mapcache/demo
nginx Specific Instructions
Warning: Working with nginx is still somewhat experimental. The following workflow has only been tested on
the development version, i.e. nginx-1.1.x
For nginx support you need to build MapCache’s nginx module against the nginx source. Download the nginx source
code:
$
$
$
$
$
$
cd /usr/local/src
mkdir nginx
cd nginx
wget http://nginx.org/download/nginx-1.1.19.tar.gz
tar -xzvf nginx-1.1.19.tar.gz
cd nginx-1.1.19/
Run the configure command with the flag --add-module. This flag must point to MapCache’s nginx child directory.
Assuming that MapServer source was cloned or un tarred into to /usr/local/src, an example configure command
for nginx would look like this:
$ ./configure --add-module=/usr/local/src/mapcache/nginx
Then build nginx:
$ make
$ sudo make install
Due to nginx’s non-blocking architecture, the MapCache nginx module does not perform any operations that may lead
to a worker process being blocked by a long computation (i.e.: requesting a (meta)tile to be rendered if not in the
cache, proxying a request to an upstream WMS server, or waiting for a tile to be rendered by another worker): It will
instead issue a 404 error. This behavior is essential so as not to occupy all nginx worker threads, thereby preventing
it from responding to all other incoming requests. While this isn’t an issue for completely seeded tilesets, it implies
that these kinds of requests need to be proxied to another MapCache instance that does not suffer from these starvation
issues (i.e. either a FastCGI MapCache, or an internal proxied Apache server). In this scenario, both the nginx
MapCache instance and the Apache/FastCGI MapCache instance should be running with the same mapcache.xml
configuration file.
MapCache supplies an nginx.conf in its nginx child directory. The conf contains an example configuration to load
MapCache. The most relevant part of the configuration is the location directive that points the ^/mapcache URI to
the mapcache.xml path. You will need to change this path to point to your own mapcache.xml in the MapCache
source.
The basic configuration without any proxying (which will return 404 errors on unseeded tile requests) is:
location ~ ^/mapcache(?<path_info>/.*|$) {
set $url_prefix "/mapcache";
mapcache /usr/local/src/mapcache/mapcache.xml;
}
6.1. MapCache 1.4
366
MapServer Documentation, Release 7.0.6
If proxying unseeded tile requests to a MapCache instance running on an Apache server, we will proxy all 404 MapCache errors to a mapcache.apache.tld server listening on port 8080, configured to respond to MapCache
requests on the /mapcache location.
location ~ ^/mapcache(?<path_info>/.*|$) {
set $url_prefix "/mapcache";
mapcache /usr/local/src/mapcache/mapcache.xml;
error_page 404 = @apache_mapcache;
}
location @apache_mapcache {
proxy_pass http://mapcache.apache.tld:8080;
}
If using FastCGI instances of MapCache, spawned with e.g. spawn-fcgi or supervisord on port 9001 (make sure to
enable FastCGI when building MapCache, and to set the MAPCACHE_CONFIG_FILE environment variable before
spawning):
location ~ ^/mapcache(?<path_info>/.*|$) {
set $url_prefix "/mapcache";
mapcache /usr/local/src/mapcache/mapcache.xml;
error_page 404 = @fastcgi_mapcache;
}
location @fastcgi_mapcache {
fastcgi_pass
localhost:9001;
fastcgi_param QUERY_STRING
fastcgi_param REQUEST_METHOD
fastcgi_param CONTENT_TYPE
fastcgi_param CONTENT_LENGTH
fastcgi_param PATH_INFO
fastcgi_param SERVER_NAME
fastcgi_param SERVER_PORT
fastcgi_param SCRIPT_NAME
}
$query_string;
$request_method;
$content_type;
$content_length;
$path_info;
$server_name;
$server_port;
"/mapcache";
Copy the relevant sections of nginx.conf from MapCache’s nginx directory into nginx’s conf file (in this
case /usr/local/nginx/conf/nginx.conf). You should now have access to the demo at http://myserver/
mapcache/demo
CGI/FastCGI Specific Instructions
A binary CGI/FastCGI is located in the mapcache/ subfolder, and is named “mapcache”. Activating FastCGI for the
MapCache program on your web server is not part of these instructions; more details may be found on the FastCGI
page or on more general pages across the web.
The MapCache FastCGI program looks for its configuration file in the environment variable called MAPCACHE_CONFIG_FILE, which must be set by the web server before spawning the MapCache processes.
See also:
Configuration File
For Apache with mod_cgi:
SetEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapcache/mapcache.xml"
For Apache with mod_fcgid:
6.1. MapCache 1.4
367
MapServer Documentation, Release 7.0.6
FcgidInitialEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapcache/mapcache.xml
If you have not disabled the demo service, you should now have access to it on http://myserver/fcgi-bin/mapcache/
demo, assuming your fcgi processes are accessed under the fcgi-bin alias.
With a working mod_fcgid Apache instance, the full httpd.conf snippet to activate MapCache could be:
<IfModule mod_fcgid.c>
IPCCommTimeout 120
MaxProcessCount 10
FcgidInitialEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapcache/mapcache.xml"
<Location /map.fcgi>
Order Allow,Deny
Allow from all
SetHandler fcgid-script
</Location>
ScriptAlias /map.fcgi "/path/to/mapcache/src/mapcache"
</IfModule>
The MapCache service would then be accessible at http://myserver/map.fcgi{[}/demo]
Customizing the Build, Or If Something Went Wrong
Depending on which packages are available in the default locations of your system, the “cmake ..” step will most
probably have failed with messages indicating missing dependencies (by default, MapCache has some of those). The
error message that CMake prints out should give you a rather good idea of what steps you should take next, depending
on whether the failed dependency is a feature you require in your build.
mod_mapcache requires Apache, libcurl, libjpeg and libpng development headers. The CMake script will try to locate
them in default system locations, but these locations can be overridden or specified with -D switches. For example,
if you get a message such as ‘Could NOT find APR ‘, you can use a command such as (assuming that APR is at
/usr/local/apr) :
$ cmake -DCMAKE_PREFIX_PATH="/usr/local/apr;" ..
If you don’t want e.g. fcgi, you can disable the dependency by re-running CMake with -DWITH_DEPENDENCY=0,
e.g.
$ cmake .. -DWITH_FCGI=0
Options Supported By the MapCache CMake Builder
Here is a list of supported options that can be enabled/disabled at build.
option(WITH_PIXMAN "Use Pixman for SSE optimized image manipulations" ON)
option(WITH_SQLITE "Use SQLite as a cache backend" ON)
option(WITH_BERKELEY_DB "Use Berkeley DB as a cache backend" OFF)
option(WITH_MEMCACHE "Use memcache as a cache backend (requires recent apr˓→util)" OFF)
option(WITH_TIFF "Use TIFFs as a cache backend" OFF)
option(WITH_TIFF_WRITE_SUPPORT "Enable (experimental) support for writable
˓→TIFF cache backends" OFF)
option(WITH_GEOTIFF "Allow GeoTIFF metadata creation for TIFF cache backends
˓→" OFF)
option(WITH_PCRE "Use PCRE for regex tests" OFF)
6.1. MapCache 1.4
368
MapServer Documentation, Release 7.0.6
option(WITH_MAPSERVER "Enable (experimental) support for the MapServer
˓→library" OFF)
option(WITH_GEOS "Choose whether GEOS geometry operations support should be
˓→built in" ON)
option(WITH_OGR "Choose whether OGR/GDAL input vector support should be
˓→built in" ON)
option(WITH_CGI "Choose whether CGI executable should be built" ON)
option(WITH_FCGI "Choose whether CGI executable should support FastCGI" ON)
option(WITH_VERSION_STRING "Show MapCache in server version string" ON)
option(WITH_APACHE "Build Apache Module" ON)
• Pixman (recommended, from 0.5 onwards)
-DWITH_PIXMAN=[0|1]
Pixman is a pixel manipulation library used to assemble image tiles when responding to non-tiled
WMS requests. Pixman support is recommended as it is highly optimized and will take advantage of
recent processor extensions (MMX, SSE2, etc.) to speed up blending and resampling operations. If
the Pixman library is not found, MapCache will fall back to internal pixel operations that are slower.
• SQLite (optional, from 0.5 onwards)
-DWITH_SQLITE=[0|1]
SQLite is used to enable the SQLite and MBTiles cache backend. Version 3.5.0 or newer is required.
• GDAL (optional, from 0.4 onwards, also requires geos)
-DWITH_OGR=[0|1]
GDAL (actually OGR) is used by the seeding utility to allow the seeding of tiles only intersecting a
given polygon, e.g. to preseed all the tiles of a given country.
• GEOS (optional, from 0.5 onwards)
-DWITH_GEOS=[0|1]
Along with GDAL/OGR, GEOS is needed by the seeder to test for the intersection of tiles with
geographical features. A sufficiently recent version of GEOS (with support for prepared geometries)
is required (but not enforced by the configure script, so you’ll end up with compilation errors if a
too old GEOS version is used).
• PCRE (optional)
-DWITH_PCRE=[0|1]
PCRE (Perl Compatible Regular Expressions) can be used instead of POSIX regular expressions for
validating WMS dimensions. They are more powerful than POSIX REs (and might be slower). You
don’t need this if you aren’t planning on using WMS dimension support with regex validation, or if
your validation needs are covered by posix REs.
See also:
Tileset Dimensions
• FastCGI Support (optional)
-DWITH_FCGI=[0|1]
6.1. MapCache 1.4
369
MapServer Documentation, Release 7.0.6
MapCache can run as a FastCGI executable. Note that the overhead of FastCGI is non-negligible
with respect to the throughput you may obtain with a native Apache module. The FastCGI build is
less tested, and may lag behind the Apache module version on some minor details. YMMV.
• TIFF read/write Cache Support (optional)
Use TIFFs as a cache backend (READONLY) :
-DWITH_TIFF=[0|1]
TIFF write support (for creating new TIFF files and adding tiles to existing TIFF files) is still experimental and disabled by default. There is a risk of ending up with corrupt TIFF files if they are
placed on a filesystem that does not honor file locking, as in that case multiple processes might end
up writing to the same file. File locking across concurrent threads is also problematic, although
MapCache tries to detect this situation and apply sufficient locking workarounds. To stay on the
safe side, write support should for now only be enabled on local filesystems, with a prefork MPM
or FastCGI MapCache install.
-DWITH_TIFF_WRITE_SUPPORT=[0|1]
When writing TIFF files, MapCache can also optionally add georeferencing information if compiled
with libtiff support. GeoTiff writing does not produce the full tags needed for defining which preojection the grid is in, but will only produce those defining the pixel scale and the tiepoints (i.e. the
equivalent information found in the accompanying .tfw files).
-DWITH_GEOTIFF=[0|1]
See also:
(Geo)TIFF Caches
• Memcached Cache Support (optional)
-DWITH_MEMCACHE=[0|1]
The memcached cache backend is disabled by default. You can optionally enable it as it does not
depend on other external libraries (support is obtained through apr-util).
See also:
Memcache Caches
• Apache Module Options
You can disable the Apache module building if you only plan on using the FastCGI executable or
the seeder.
-DWITH_APACHE=[0|1]
MapCache adds itself to the version string reported by the Apache server. This can be disabled with:
-DWITH_VERSION_STRING=[0|1]
• Native MapServer Mode (experimental options)
MapCache is by default not linked to MapServer in any way, and communicates through the WMS
protocol only. For improved performance, it is possible to directly use the MapServer C library
and avoid an HTTP request and an image compression/decompression. This integration is still
experimental and should be used cautiously.
6.1. MapCache 1.4
370
MapServer Documentation, Release 7.0.6
-DWITH_MAPSERVER=[0|1]
This will use the libmapserver.so from MapServer’s install directory. MapServer itself should be
compiled with thread-safety enabled, unless you plan to use the prefork MPM or FastCGI, and you
do not plan to use the seeder. For thread safety on the MapServer side, you might want to have a
look at tickets #4041 and #4044.
• Debug Mode (work in progress)
Note: Since the CMake migration, this has to be done.
It enables some extra tests inside the code, and prints out many more debugging messages to the
server logs. you should probably not enable this unless you want to track down a problem happening
inside MapCache.
Windows Instructions
Warning: The following instructions are outdated. Windows builds are now handled identically to the Unix ones
with CMake.
These instructions target a Windows 7 setup with an Apache httpd compiled from source. The Apache MapCache
module has been successfully built with with Microsoft Visual Studio C++ versions 2003, 2008 and 2010.
Dependencies
Required:
• Apache / APR / APR-UTIL: included with Apache httpd installation
These can be installed manually, or using the appropriate Windows SDK from: http://www.gisinternals.com/sdk/
• PNG
• JPEG
• CURL
Recommended:
• PCRE: ftp://ftp.gnu.org/pub/gnu/regex/regex-0.12.tar.gz
Optional:
• FCGI: Needed to build a FastCGI program if you don’t want to run MapCache as an Apache module
• GDAL / GEOS: Needed to enable advanced seeding options (for only seeding tiles that intersect a given geographical feature)
• SQLITE: For enabling the SQLite backend storages
• TIFF: For enabling the TIFF backend storages
Configure Your Makefile
Open nmake.opt and modify the paths to point to the various libraries.
6.1. MapCache 1.4
371
MapServer Documentation, Release 7.0.6
Compilation
$ nmake /f Makefile.vc
If successful, the resulting libraries and executables will be generated in their associated directories:
apache/ Apache module (mod_mapcache.dll)
cgi/ FastCGI MapCache executable (mapcache.exe)
util/ MapCache utilities (mapcache_seed.exe)
Move the Module Into the Apache Directory
Copy the mod_mapcache.dll file into one of your Apache subdirectories.
Note: Although other modules are installed into /Apache/modules/, you should place mod_mapcache.dll wherever its
required dll files (libcurl.dll, zlib.dll, etc.) live, to avoid any loading issues later on.
Configure Your Installed Apache
• Modify your httpd.conf file to load the module:
LoadModule mapcache_module "D:/ms4w/Apache/cgi-bin/mod_mapcache.dll"
• Next, configure your MapCache directory with the following snippet:
<IfModule mapcache_module>
<Directory "D:/ms4w/apps/mapcache/">
Order Allow,Deny
Allow from all
</Directory>
MapCacheAlias /mapcache "D:/ms4w/apps/mapcache/mapcache.xml"
</IfModule>
• Configure your mapcache.xml file (see the Configuration section for help).
Warning: If you receive an error such as “cache disk: host system does not support file symbolic linking”
you should comment out the line “<symlink_blank/>” in your mapcache.xml file, such as the following:
<cache name="disk" type="disk">
<base>D:/ms4w/tmp/ms_tmp/cache</base>
<!--<symlink_blank/>-->
</cache>
• Finally, restart your Apache. You should see a message in Apache’s error.log with a message similar to:
[notice] Apache/2.2.21 (Win32) mod-mapcache/0.5-dev configured -- resuming normal
˓→operations
6.1. MapCache 1.4
372
MapServer Documentation, Release 7.0.6
Test Your MapCache Module
• In your web browser, visit the local MapCache demo page: http://127.0.0.1/mapcache/demo/. You should see a
clickable list of demo links:
tms
wmts
gmaps
kml
ve
wms
• Click on one of the demos (such as http://127.0.0.1/mapcache/demo/wmts). A map viewer should load, similar
to the image below.
• Zoom in a few times. Your configured cache location should be generating tiles (in this case inside
D:/ms4w/tmp/ms_tmp/cache/).
6.1. MapCache 1.4
373
MapServer Documentation, Release 7.0.6
6.1.2 Configuration File
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
The configuration file determines how mod-mapcache will serve incoming requests. It is an XML file comprising a
list of entries, as outlined here:
<mapcache>
<grid>....</grid>
<source>....</source>
<cache>...</cache>
<format>...</format>
<tileset>...</tileset>
<services>...</services>
</mapcache>
Source
A source is a service mod-mapcache can query to obtain image data. This is typically a WMS server accessible by
a URL. (There are currently no sources other than WMS implemented, though others may be added later if the need
arises).
<source name="vmap0" type="wms">
<!-Extra parameters that will be added to the GetMap request. You can
6.1. MapCache 1.4
374
MapServer Documentation, Release 7.0.6
specify any parameter here, e.g. VERSION if you want to override the
version of the WMS request.
The LAYERS parameter is mandatory.
Usual parameters here are FORMAT, or MAP if using MapServer.
-->
<getmap>
<params>
<FORMAT>image/png</FORMAT>
<LAYERS>basic</LAYERS>
</params>
</getmap>
<!-- HTTP URL and parameters to be used when making WMS requests -->
<http>
<!-- URL of the WMS service, without any parameters -->
<url>http://vmap0.tiles.osgeo.org/wms/vmap0</url>
<!-HTTP headers added to the request. Make sure you know what you are
doing when adding headers here, as they take precedence over any
default headers curl will be adding to the request.
Typical headers that can be added here are User-Agent and Referer.
When adding a <key>value</key> element here, the request to the WMS
source will contain the
key: value\r\n
HTTP header.
You may also forward a header from the incoming client request using
the <MyHeader>{X-Header-To-Forward}<MyHeader> syntax.
-->
<headers>
<User-Agent>mod-mapcache/r175</User-Agent>
<Referer>http://www.mysite.com?param=2&amp;par=4</Referer>
</headers>
<!-- Timeout in seconds before bailing out from a request -->
<connection_timeout>30</connection_timeout>
</http>
</source>
• The name and type attributes are straightforward: type is “wms”, and name
• is the key by which this source will be referenced; <url> is the HTTP
• location where the service can be accessed; and <wmsparams> is a list of
• parameters that will be added to the WMS request. You should probably at the
• very least add the FORMAT and LAYERS parameters. By convention(?), WMS
• parameters are uppercase, and you should respect this convention in your
• configuration file.
6.1. MapCache 1.4
375
MapServer Documentation, Release 7.0.6
•
• This is where you can also override some default WMS parameters if needed. By
• default, the parameters that will be used are: <REQUEST>GetMap</REQUEST>
• <SERVICE>WMS</SERVICE> <STYLES></STYLES> <VERSION>1.1.0</VERSION>
Cache
A cache is a location where received tiles will be stored.
<cache name="disk" type="disk">
<!-- base
Absolute filesystem path where the tile structure will be stored.
This directory needs to be readable and writable by the user running
Apache.
-->
<base>/tmp</base>
<!-- symlink_blank
Enable blank (i.e. uniform color) tile detection. Blank tiles will be
detected at creation time and linked to a single blank tile on disk
to preserve disk space.
-->
<symlink_blank/>
</cache>
<cache name="tmpl" type="disk" layout="template">
<!-- template
String template that will be used to map a tile (by tileset, grid
name, dimension, format, x, y, and z) to a filename on the filesystem.
The following replacements are performed:
-
{tileset}
{grid}
{dim}
{ext}
{x},{y},{z}
{inv_x},{inv_y},{inv_z}
:
:
:
:
:
:
the tileset name
the grid name
string concatenating the tile's dimension
tile's image-format filename extension
tile's x,y,z values
inverted x,y,z values
(For inverted x,y,z values, (inv_x = level->maxx - x - 1). This is
mainly used to support grids where one axis is inverted (e.g. the
Google schema) and you want to create on offline cache.)
* Note that this type of cache does not support blank-tile detection
and symlinking.
* Warning: It is up to you to make sure that the template you choose
creates a unique filename for your given tilesets (e.g. do not omit
the {grid} parameter if your tilesets reference multiple grids.)
Failure to do so will result in filename collisions!
6.1. MapCache 1.4
376
MapServer Documentation, Release 7.0.6
-->
<template>/tmp/template-test/{tileset}#{grid}#{dim}/{z}/{x}/{y}.{ext}</template>
</cache>
<!-- memcache cache
Entry accepts multiple <server> entries.
Requires a fairly recent apr-util library and headers.
-->
<cache name="memcache" type="memcache">
<server>
<host>localhost</host>
<port>11211</port>
</server>
</cache>
<!-- sqlite cache
Requires building with "with-sqlite".
-->
<cache name="sqlite" type="sqlite3">
<!-- dbfile
Absolute filename path of the SQLite database file to use.
This file needs to be readable and writable by the user running the
MapCache instance.
-->
</cache>
<cache name="mbtiles" type="mbtiles">
<dbfile>/path/to/MapBox/tiles/natural-earth-1.mbtiles</dbfile>
</cache>
Format
A format is an image format that will be used to return tile data to clients, and to store tile data on disk.
<format name="PNGQ_FAST" type ="PNG">
<!-- compression
PNG compression: best or fast
Note that "best" compression is CPU intensive for little gain over
the default default compression obtained by leaving out this tag.
-->
<compression>fast</compression>
<!-- colors
If supplied, this enables PNG quantization which reduces the number
of colors in an image to attain higher compression. This operation is
destructive, and can cause artifacts in the stored image.
The number of colors can be between 2 and 256.
6.1. MapCache 1.4
377
MapServer Documentation, Release 7.0.6
-->
<colors>256</colors>
</format>
<format name="myjpeg" type ="JPEG">
<!-- quality
JPEG compression quality, ranging from 0 to 100.
95 produces high quality images with few visual artifacts. Values
under around 80 produce small images but with visible artifacts.
YMMV.
-->
<quality>75</quality>
<!-- photometric
Photometric interpretation of the bands created in the JPEG image.
Default is "ycbcr", which produces the smallest images. Can also be
"rgb", which usually results in x2 or x3 image sizes.
-->
<photometric>ycbcr</photometric>
</format>
<format name="PNG_BEST" type ="PNG">
<compression>best</compression>
</format>
<format name="mixed" type="MIXED">
<transparent>PNG_BEST</transparent>
<opaque>JPEG</opaque>
</format>
Grid
A grid is the matrix that maps tiles onto an area, and consists of a spatial reference, a geographic extent, resolutions,
and tile sizes.
Mandatory Configuration Options
• <size>: The width and height of an individual tile, in pixels. Must be specified as positive integers separated by
a space character. The most common tile size is:
<size>256 256</size>
• <extent>: The geographical extent covered by the grid, in ground units (e.g. meters, degrees, feet, etc.). Must
be specified as 4 floating point numbers separated by spaces, ordered as minx, miny, maxx, maxy.
MapCache expects all of its extents to be given in lonlat, and does the translation to latlon at request time if
needed.
The (minx,miny) point defines the origin of the grid, i.e. the pixel at the bottom left of the bottom-left most tile
is always placed on the (minx,miny) geographical point.
6.1. MapCache 1.4
378
MapServer Documentation, Release 7.0.6
The (maxx,maxy) point is used to determine how many tiles there are for each zoom level.
<extent>-180 -90 180 90</extent>
• <srs>: The projection of the grid, usually given by it EPSG identifier. This value isn’t used directly by MapCache to compute reprojections; it is only used to look up which grid to use when receiving WMS requests.
<srs>epsg:4326</srs>
Note: This is the value that is passed on to the source when requesting a tile that is not already cached for the
current grid. You must make sure that the source that is queried is capable of returning image data for this SRS.
• <units>: The ground units used by the grid’s projection. This entry is not used directly by MapCache aside
from calculating scales for the WMTS capabilities document. Allowed values are:
– m : meters
– dd : decimal degrees
– ft : feet
<units>dd</units>
• <resolutions>: This is a list of resolutions for each of the zoom levels defined by the grid. This must be supplied
as a list of positive floating point values, separated by spaces and ordered from largest to smallest. The largest
value will correspond to the grid’s zoom level 0. Resolutions are expressed in “units-per-pixel”, depending on
the unit used by the grid (e.g. resolutions are in meters per pixel for most grids used in webmapping).
<resolutions>0.703125000000000 0.351562500000000 0.175781250000000 8.
˓→78906250000000e-2 4.39453125000000e-2 2.19726562500000e-2 1.09863281250000e-2 5.
˓→49316406250000e-3 2.74658203125000e-3 1.37329101562500e-3 6.86645507812500e-4 3.
˓→43322753906250e-4 1.71661376953125e-4 8.58306884765625e-5 4.29153442382812e-5 2.
˓→14576721191406e-5 1.07288360595703e-5 5.36441802978516e-6</resolutions>
Optional Configuration Options
• <srsalias>: This tag can be specified multiple times, and allows the user to add multiple SRS entries for a given
grid. This is especially useful if the EPSG id for a given projection has evolved over time, or to support catalogs
other than the EPSG one (which is the only catalog supported by the WMS specification).
<srs>EPSG:310024802</srs>
<srsalias>IGNF:GEOPORTALFXX</srsalias>
<srsalias>EPSG:310024001</srsalias>
• <metadata>:
– <title>: The name of the grid, in human readable form. Appears in the capabilities documents.
<title>This grid covers the area blah blah blah</title>
– <WellKnownScaleSet>: See the WMTS keyword. This will add a WellKnownScaleSet entry to the
WMTS capabilities document. It is up to the user to make sure that the supplied resolutions for the grid
actually match the pre-defined WellKnownScaleSet.
6.1. MapCache 1.4
379
MapServer Documentation, Release 7.0.6
<WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleCRS84Quad</
˓→WellKnownScaleSet>
• <origin>: Specifies the origin of the grid. Valid values are top-left, bottom-left, top-right and bottom-right.
If not used, the grid will have the bottom-left corner as reference point.
<origin>top-left</origin>
Preconfigured Grids
There are three predefined grids you can use without defining them in the mapcache.xml file:
• The “WGS84” grid corresponds to a grid where the whole world is rendered on two 256x256-pixel tiles at level
0 (i.e. the (-180,-90,180,90) extent fits on a 512x256 image). It goes down to zoom level 17.
<grid name="WGS84">
<metadata>
<title>GoogleCRS84Quad</title>
<WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleCRS84Quad</
˓→WellKnownScaleSet>
</metadata>
<extent>-180 -90 180 90</extent>
<srs>EPSG:4326</srs>
<units>dd</units>
<size>256 256</size>
<resolutions>0.703125000000000 0.351562500000000 0.175781250000000 8.
˓→78906250000000e-2 4.39453125000000e-2 2.19726562500000e-2 1.09863281250000e-2 5.
˓→49316406250000e-3 2.74658203125000e-3 1.37329101562500e-3 6.86645507812500e-4 3.
˓→43322753906250e-4 1.71661376953125e-4 8.58306884765625e-5 4.29153442382812e-5 2.
˓→14576721191406e-5 1.07288360595703e-5 5.36441802978516e-6</resolutions>
</grid>
• The “g” grid may be used to overlay tiles on top of GoogleMaps, and is the default tiling scheme used in
webmapping applications. This grid goes down to zoom level 18. Level 0 is a single 256x256 tile. This grid’s
default SRS is EPSG:900913, which is non-standard but in wider use than than its official EPSG:3857 entry.
<grid name="g">
<metadata>
<title>GoogleMapsCompatible</title>
<WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleMapsCompatible</
˓→WellKnownScaleSet>
</metadata>
<extent>-20037508.3427892480 -20037508.3427892480 20037508.3427892480 20037508.
˓→3427892480</extent>
<srs>EPSG:900913</srs>
<srsalias>EPSG:3857</srsalias>
<units>m</units>
<size>256 256</size>
<resolutions>156543.0339280410 78271.51696402048 39135.75848201023 19567.
˓→87924100512 9783.939620502561 4891.969810251280 2445.984905125640 1222.
˓→992452562820 611.4962262814100 305.7481131407048 152.8740565703525 76.
˓→43702828517624 38.21851414258813 19.10925707129406 9.554628535647032 4.
˓→777314267823516 2.388657133911758 1.194328566955879 0.5971642834779395</
˓→resolutions>
</grid>
6.1. MapCache 1.4
380
MapServer Documentation, Release 7.0.6
• The “GoogleMapsCompatible” grid is nearly identical to the “g” grid, except that its default SRS is EPSG:3857
instead of EPSG:900913.
<grid name="GoogleMapsCompatible">
<metadata>
<title>GoogleMapsCompatible</title>
<WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleMapsCompatible</
˓→WellKnownScaleSet>
</metadata>
<extent>-20037508.3427892480 -20037508.3427892480 20037508.3427892480 20037508.
˓→3427892480</extent>
<srs>EPSG:3857</srs>
<srsalias>EPSG:900913</srsalias>
<units>m</units>
<size>256 256</size>
<resolutions>156543.0339280410 78271.51696402048 39135.75848201023 19567.
˓→87924100512 9783.939620502561 4891.969810251280 2445.984905125640 1222.
˓→992452562820 611.4962262814100 305.7481131407048 152.8740565703525 76.
˓→43702828517624 38.21851414258813 19.10925707129406 9.554628535647032 4.
˓→777314267823516 2.388657133911758 1.194328566955879 0.5971642834779395</
˓→resolutions>
</grid>
Tileset
A tileset is the essential configuration item for mod-mapcache, and corresponds to a set of tiles coming from a source,
stored in a cache, and returned to the client in a given format.
<tileset name="test">
<!-- source
The "name" attribute of a preconfigured <source>.
If the tileset does not contain a <source> element, then it is
considered read-only and its cache will never be updated. In this
case, your seeder and webserver would have slightly different
mapcache.xml files.
Blank tiles may be dealt with by setting the <errors> directive to
"empty_img".
-->
<source>vmap0</source>
<!-- cache
The "name" attribute of a preconfigured <cache>
-->
<cache>sqlite</cache>
<!-- grid
The "name" attribute of a preconfigured <grid>.
You can also use the following notation to limit the area that will
be cached and served to clients:
6.1. MapCache 1.4
381
MapServer Documentation, Release 7.0.6
<grid restricted_extent="-10 40 10 50">WGS84</grid>
This is better than using a grid with a limited extent, as in this
way the tiles that are already cached are not invalidated should you
want to modify the restricted extent in the future. When using the
restricted_extent attribute, you should give the corresponding
information to the client that will be using the service.
You can also limit the zoom levels that are cached/accessible by
using the minzoom and maxzoom attributes.
NOTE: When adding a <grid> element, you *MUST* make sure that the
source you have selected is able to return images in the grid's SRS.
-->
<grid restricted_extent="-10 40 10 50" minzoom="4" maxzoom="17">WGS84</grid>
<grid>g</grid>
<!-- You may store hidden intermediate levels of tiles to enable higher
quality output when reassembling tiles. This may be needed when
caching maps containing labels to avoid the text from becoming too
small or too blurry when requesting resolutions that are far away
from the native grid resolutions.
Supposing grid "mygrid" consists of 256x256 pixel tiles, with
resolutions r1,r2,r3,r4,...rn, MapCache will populate a hidden grid
called "mygrid_intermediate_0.5" containing tiles of size
256+256*0.5=384 with resolutions r1+(r2-r1)*0.5, r2+(r3-r2)*0.5, ...
r(n-1)+(r(n)-r(n-1)*0.5. That is, a tile with a given extent will be
stored once in a 256x256 tile, and once in a 384x384 one.
This intermediate grid is private to MapCache and will not be exposed
to tiled requests. It will only be used for WMS requests that require
horizontal assembling.
-->
<grid use_wms_intermediate_resolutions="true">mygrid</grid>
<!-- metadata
Optional metadata tags used for responding to GetCapabilities
requests. You can put anything here, but only the title and abstract
tags are currently used to populate the GetCapabilities document.
-->
<metadata>
<title>vmap0 map</title>
<abstract>blabla</abstract>
</metadata>
<!-- watermark
Optional tag to add a watermark to the tiles *before* storing them to
cache. The supplied image MUST be exactly the same size as the size
as the tiles configured in the <grid>.
The supplied image is read when the configuration is loaded. If you
make changes to the image, they will NOT be reflected in tiles
already stored in the cache, nor on newly stored tiles, until the
server is restarted.
-->
6.1. MapCache 1.4
382
MapServer Documentation, Release 7.0.6
<watermark>/path/to/static/watermark.png</watermark>
<!-- format
(Optional) format to use when storing a tile. This should be a format
with high compression, e.g. PNG with compression "best", as the
compression operation is only done once at tile creation time. If
omitted, no recompression is applied to the image and mod-mapcache
will store the exact image received from the <source>.
Note that the <format> tag is mandatory if <metatile>, <metabuffer> or
<watermark> are supplied, as in those cases recompression must be
done.
-->
<format>PNG</format>
<!-- metatile
Number of columns and rows to use for metatiling. See
http://geowebcache.org/docs/current/concepts/metatiles.html
-->
<metatile>5 5</metatile>
<!-- metabuffer
Area around the tile or metatile that will be cut off to prevent some
edge artifacts. If this is specified, the configured source must be
instructed not to put any labels inside this area, as otherwise
labels will be truncated. (For MapServer, use the
"labelcache_map_edge_buffer" "-10" metadata entry, along with label
PARTIALS FALSE.)
-->
<metabuffer>10</metabuffer>
<!-- expires
Optional tile expiration value in seconds. This is expressed as
number of seconds after creation date of the tile. This is the value
that will be set in the HTTP Expires and Cache-Control headers, and
has no effect on the actual expiration of tiles in the caches (see
<auto_expire> for that).
-->
<expires>3600</expires>
<!-- auto_expire
Tiles older (in seconds) than this value will be re-requested and
updated in the cache. Note that this will only delete tiles from the
cache when they are accessed: You cannot use this configuration to
limit the size of the created cache. Note that, if set, this value
overrides the value given by <expires>.
-->
<auto_expire>86400</auto_expire>
<!-- dimensions
Optional dimensions that should be cached.
6.1. MapCache 1.4
383
MapServer Documentation, Release 7.0.6
The order of the <dimension> tags inside the <dimensions> block is
important, as it is used to create the directory structure for the
disk cache. That is, if you change the order of these values, any
tiles that have been previously cached are invalidated: They are not
removed from the cache, but they no longer exist for mod-mapcache.
-->
<dimensions>
<!-- values dimension
The example here creates a DIM1 dimension.
* WMS and WMTS clients can now add a &DIM1=value to their request
string. If they don't specify this key/value, the default will
be to use DIM1=foobar.
* The allowed values for DIM1= are foobar (it is important to add
the default value to the allowed values entry), foobarbaz, foo
and bar.
* The value specified for DIM1 will be forwarded to the WMS
source.
* The produced tile will be stored in the file
base/gridname/DIM1/value/xx/xx/xx/xx/xx/xx.png. That is, there
are as many different caches created as there are values in the
<values> tag.
-->
<dimension type="values" name="DIM1" default="foobar">foobar,foobarbaz,foo,bar</
˓→dimension>
<!-- regex dimension
The following creates a MAPFILE dimension, for using the same
mod-mapcache tileset with different MapServer mapfiles. The name
of the mapfiles need not be known to mod-mapcache, and can
therefore be created even after mod-mapcache has been started.
When a user passes a MAPFILE=/path/to/mapfile, the string
"/path/to/mapfile" is validated against the supplied (PCRE)
regular expression. The one in this example allows a name composed
of aphanumeric characters separated by slashes (/) and ending in
".map" ( [a-zA-Z0-9\./]*\.map$ ), but will fail if there are two
consecutive dots (..) in the path, to prevent filesystem traversal
( (?!.*\.\.) ).
-->
<dimension type="regex" name="MAPFILE" default="/path/to/mapfile.map">^(?!.*\.\.
˓→)[a-zA-Z0-9\./]*\.map$</dimension>
<!-- intervals dimension
The syntax is the same as common-ows, i.e. a comma-separated list
of "min/max/resolution" entries, e.g:
* 0/5000/1000 allows the values 0,1000,2000,3000,4000 and 5000.
* 0/100/0 allows any values between 0 and 100.
* Both values can be combined: 0/5000/1000,0/100/0.
-->
<dimension name="ELEVATION" type="intervals" default="0">0/5000/1000</dimension>
<!-- Coming in a future version: support for ISO8601 date/time dimensions -->
6.1. MapCache 1.4
384
MapServer Documentation, Release 7.0.6
</dimensions>
</tileset>
Services
Services are the type of request that mod-mapcache will respond to. You should, of course, enable at least one.
<service type="wms" enabled="true">
<!-This service should actually be called "ogc". It is different from
the other services as it does not listen on the /wms endpoint, but
directly on /. It will intercept WMS GetMap requests that can be
satisfied from configured tilesets, and can optionally forward all
the rest to (an)other server(s).
TODO: This needs way more documenting.
<forwarding_rule name="foo rule">
<append_pathinfo>true</append_pathinfo>
<http>
<url>http://localhost/mapcacheproxy</url>
</http>
</forwarding_rule>
-->
<!-- full_wms
Configure response to WMS requests that are not aligned to a
tileset's grids. Responding to requests that are not in the SRS of a
configured grid is not supported, but this should never happen as
only the supported SRSs are publicized in the capabilities document.
Allowed values are:
- error
: Return a 404 error (default).
- assemble : Build the full image by assembling cached tiles.
- forward : Forward the request to the configured source.
-->
<full_wms>assemble</full_wms>
<!-- resample mode
Filter applied when resampling tiles for full WMS requests. Can be
either:
- nearest : Fastest, poor quality.
- bilinear : Slower, higher qulity.
-->
<resample_mode>bilinear</resample_mode>
<!-- format
Image format to use when assembling tiles.
-->
<format allow_client_override="true">myjpeg</format>
</service>
6.1. MapCache 1.4
385
MapServer Documentation, Release 7.0.6
<service
<service
<service
<service
<service
<service
type="wmts" enabled="true"/>
type="tms" enabled="true"/>
type="kml" enabled="true"/>
type="gmaps" enabled="true"/>
type="ve" enabled="true"/>
type="demo" enabled="true"/>
Miscellaneous
<!-- default_format
Format to use when a client asks for an image that is dynamically
created from multiple cached tiles. Note that using a PNG format with
"best" compression is not recommended here as it is computationally
expensive. It is better to use a PNG format with "fast"compression here,
unless you have plenty of server CPU power and/or limited bandwidth.
-->
<default_format>JPEG</default_format>
<!-- services
Services that mod-mapcache will respond to. Each service is accessible
at the URL http://host/path/to/mapcache/{service}, e.g.
http://myhost/mapcache/wms for OGC WMS.
-->
<!-- errors
Configure how errors will be reported back to a client:
- log
- report
- empty_img
: No error is reported back, except an HTTP error code.
: Return the error message to the client in textual format.
: Return an empty image to the client. The actual error
code is in the X-Mapcache-Error HTTP header.
- report_img : Return an image with the error text included inside. (Not
implemented yet.)
The default setting is to report the error message back to the user. In
production, you might want to set this to "log" if you're paranoid, or
to "empty_img" if you want to play nice with non-conforming clients.
-->
<errors>report</errors>
<locker type="disk"> <!-- this is the default -->
<!-Where to put lockfiles (to block other clients while a metatile is being
rendered). Defaults to /tmp. This location should be writable by the
Apache user.
-->
<directory>/tmp</directory>
<retry>0.01</retry> <!-- check back every .01 seconds -->
<timeout>60</timeout> <!-- Consider a lock stale after this many seconds.
May cause issues if WMS rendering time exceeds
this value. -->
</locker>
6.1. MapCache 1.4
386
MapServer Documentation, Release 7.0.6
For specific information about locking, read this.
<!-- log_level
For CGI/FastCGI only; For the Apache module use the httpd.conf LogLevel
key.
Defines the verbosity of logged information. Valid values are:
-
debug
info
notice
warn (default)
error
crit
alert
emerg
-->
<log_level>warn</log_level>
<!-- auto_reload
For FastCGI only. If set to true, the configuration will be
automatically reloaded if the configuration file has changed. Default is
false.
-->
<auto_reload>true</auto_reload>
6.1.3 Supported Tile Services
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
Author Stephen Woodbridge
MapCache has the ability to serve tiles using a variety of different request protocols and tile-naming conventions. This
document describes these. The various services must be turned on in the mapcache.xml file for MapCache to respond
to these specific requests.
All services are available on the demo interface, from which you are highly encouraged to copy/paste the JavaScript
code to get started when creating your own pages accessing the MapCache tiles.
The following notation is used on this page and refers to object names in the mapcache.xml configuration file.
• <tileset_name> - name of a configured tileset
• <grid_name> - name of explicitly or implicitly defined grid
• <quadkey> - specific to the Virtual Earth tile service
• <z> - zoom level in zxy naming scheme
• <y> - row number in zxy naming scheme
• <x> - column number in zxy naming scheme
TMS Service
The TMS service uses a z/x/y tile naming scheme where:
6.1. MapCache 1.4
387
MapServer Documentation, Release 7.0.6
• z is the zoom level
• x is the column number
• y is the row number
To activate the TMS service, add these lines to the mapcache.xml configuration file:
<service type="tms" enabled="true"/>
A “capabilities” document can be fetched via:
http://myhost.com/mapcache/tms/1.0.0/
Tiles are requested using this scheme:
http://myhost.com/mapcache/tms/1.0.0/<tileset_name>@<grid_name>/<z>/<x>/<y>.png
For EPSG:3857, EPSG:900913, or GoogleMapsCompatible grids, with cell = [z/x/y]:
z0:
[0/0/0]
z1:
[1/0/0][1/1/0]
[1/0/1][1/1/1]
z2:
[2/0/0][2/1/0][2/2/0][2/3/0]
[2/0/1][2/1/1][2/2/1][2/3/1]
[2/0/2]...
[2/0/3]...
etc...
For EPSG:4326 or WGS84 grids:
Note: The OGC WMTS specification rather absurdly requires the GoogleCRS84Quad WellKnownScaleset to have a
level 0 whose extent is -180,-180,180,180. The default “WGS84” MapCache grid honors this, which may cause some
incompatibilities with software that expects level 0 to be 2x1 tiles with extent -180,-90,180,90
z0:
[0/0/0]
z1:
[1/0/0][1/1/0]
z2:
[2/0/0][2/1/0][2/2/0][2/3/0]
[2/0/1][2/1/1][2/2/1][2/3/1]
etc.
6.1. MapCache 1.4
388
MapServer Documentation, Release 7.0.6
KML Service
The KML service produces Super-Overlays for tilesets that are aligned to the WGS84 / EPSG:4326 grids. A SuperOverlay is a KML file that links to an image URL, and to a set of other KML URLs corresponding to neighboring
resolutions. The KML service uses a z/x/y tile naming scheme where:
• z is the zoom level
• x is the column number
• y is the row number
Note: For the KML service to be functional, the TMS service must also be activated, as the KML super-overlays link
to images using this spec.
To activate the KML service, add these lines to the mapcache.xml configuration file:
<service type="tms" enabled="true"/>
<service type="kml" enabled="true"/>
Tiles are requested using this scheme:
http://myhost.com/mapcache/kml/<tileset_name>@<grid_name>/<z>/<x>/<y>.kml
OGC WMTS Service
To activate the WMTS service, add these lines to the mapcache.xml configuration file:
<service type="wmts" enabled="true"/>
This service follows the standard OGC WMTS requests and supports both the classical OGC-style key-value-pair
encoded and REST-style requests.
http://myhost.com/mapcache/wmts?SERVICE=WMTS&VERSION=1.0.0&...
http://myhost.com/mapcache/wmts/1.0.0/....
The capabilities are obtained through:
http://myhost.com/mapcache/wmts?service=wmts&request=getcapabilities&version=1.0.0
http://myhost.com/mapcache/wmts/1.0.0/WMTSCapabilities.xml
See also:
FeatureInfo Requests
See also:
Tileset Dimensions
OGC WMS Service
MapCache responds to WMS version 1.1.1 requests, and has limited support for version 1.3.0 ones.
<service type="wms" enabled="true"/>
6.1. MapCache 1.4
389
MapServer Documentation, Release 7.0.6
Note: Note that the WMS service is a little different than the other MapCache services, as it listens on the root of the
configured instance instead of on an additional endpoint (i.e. the service replies on http://server/mapcache/? and not
on http://server/mapcache/wms?). This behavior is required in order to enable proxying of unsupported requests while
offering a single endpoint for all OGC services.
Note: MapCache primarily supports version 1.1.1 WMS requests, but has limited support for the newer version 1.3.0
ones. For 1.3.0 requests, MapCache will determine which grid to use by using the CRS= parameter instead of the
SRS= one, and will correctly honor axis ordering for the EPSG reference systems that switch the usual x/y ordering
of the BBOX parameter.
See also:
FeatureInfo Requests
See also:
Tileset Dimensions
See also:
Tile Assembling
WMS requests follow the classical key-value-pair encoded style:
http://myhost.com/mapcache?SERVICE=WMS&VERSION=1.1.1&REQUEST=....
The capabilities document is returned by:
http://myhost.com/mapcache?service=wms&request=getcapabilities
Optional WMS Configuration Options
Untiled GetMap Support
Support for untiled (non WMS-C) GetMap requests can be enabled or disabled:
<service type="wms" enabled="true">
<!-- full_wms
Configure response to WMS requests that are not aligned to a tileset's grids.
Responding to requests that are not in the SRS of a configured grid is not
˓→supported, but
this should never happen as only the supported SRSs are publicized in the
˓→capabilities
document.
Allowed values are:
- error: return a 404 error (default)
- assemble: build the full image by assembling the tiles from the cache
- forward: forward the request to the configured source.
-->
<full_wms>assemble</full_wms>
</service>
6.1. MapCache 1.4
390
MapServer Documentation, Release 7.0.6
GetMap Image Format
You may explicitly set which image format should be returned to the client for an untiled WMS request (i.e. whenever
the tile data cannot be served directly from the caches but needs to go through a decompression/recompression phase).
<service type="wms" enabled="true">
<format allow_client_override="true/false">myjpegformat</format>
</service>
If the allow_client_override attribute is set to true, then MapCache will honor the FORMAT=... parameter sent by the
client. By default MapCache ignores this parameter and uses its configured image format.
Image Resampling Quality
<service type="wms" enabled="true">
<!-- resample mode
Filter applied when resampling tiles for full WMS requests.
Can be either:
- nearest : fastest, poor quality
- bilinear: slower, higher qulity
-->
<resample_mode>bilinear</resample_mode>
</service>
GoogleMaps XYZ Service
<service type="gmaps" enabled="true"/>
Prerequisites: Your WMS should be capable of producing images in the EPSG:900913 or EPSG:3857 SRS, i.e. it
should reference the “g” or “GoogleMapsCompatible” grid.
This is the minimal HTML page that should get you going. The important bits are in the urlTemplate (for V2) and
getTileURL (for V3) variables:
• /mapcache is the Apache path where MapCache handles requests.
• test@g is the tileset and grid name to use, joined by a ‘@’ - the {Z}/{X}/{Y} should be left alone.
• The final extension should be changed to “jpg” if you are using a JPEG format with your tileset.
V2 API
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google/MapServer Tile Example</title>
<script src="http://maps.google.com/maps?file=api&v=2&key=ABQIAAAAnfs7bKE82qgb3Zc2YyS˓→oBT2yXp_ZAY8_ufC3CFXhHIE1NvwkxSySz_REpPq-4WZA27OwgbtyR3VcA"
type="text/javascript"></script>
<script type="text/javascript">
6.1. MapCache 1.4
391
MapServer Documentation, Release 7.0.6
function load() {
if (GBrowserIsCompatible()) {
var urlTemplate = '/mapcache/gmaps/test@g/{Z}/{X}/{Y}.png';
var myLayer = new GTileLayer(null,0,18,{
tileUrlTemplate:urlTemplate,
isPng:true,
opacity:0.8 });
var map = new GMap2(document.getElementById("map"));
map.addControl(new GLargeMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(0, 0), 1);
map.addOverlay(new GTileLayerOverlay(myLayer));
}
}
</script>
</head>
<body onload="load()" onunload="GUnload()">
<div id="map" style="width: 500px; height: 500px"></div>
</body>
</html>
V3 API
The previous JavaScript for the V2 example should be slightly changed to:
var map = new google.maps.Map("<element-id>", { /*options*/ });
var layerOptions = {
getTileUrl: function(coord, zoom) {
return "/mapcache/gmaps/test@g/" + zoom + "/" + coord.x + "/" + coord.y + ".png";
},
tileSize: new google.maps.Size(256,256) // or whatever
};
map.overlayMapTypes.insertAt(0, new google.maps.ImageMapType(layerOptions));
Virtual Earth tile service
Tiles are organized in one of two different layouts depending on whether they are using a Spherical Mercator projection, like EPSG:3857 or EPSG:900913, or if they are using a geographical projection, like EPSG:4326.
Tiles are requested using this scheme:
http://myhost.com/mapcache/ve?LAYER=<tileset_name>@<grid_name>&tile=<quadkey>
For EPSG:3857, EPSG:900913, or GoogleMapsCompatible grids, <quadkey> are arranged:
z0:
[0]
http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=0
z1:
6.1. MapCache 1.4
392
MapServer Documentation, Release 7.0.6
[00][01]
[02][03]
http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=00
http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=01
http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=02
http://myhost.com/mapcache/ve?LAYER=osm@GoogleMapsCompatible&tile=03
etc.
For EPSG:4326 or WGS84 grids, <quadkey> are arranged:
z1:
[0][1]
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=0
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=1
z2:
[00][01][10][11]
[02][03][12][13]
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=00
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=01
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=02
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=03
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=10
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=11
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=12
http://myhost.com/mapcache/ve?LAYER=osm@WGS84&tile=13
etc.
6.1.4 Seeder
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
Author Mathieu Coudert
Contact mathieu.coudert at gmail.com
Mod-mapcache ships with an advanced seeding tool, whose main features are:
• configurable number of seeding threads, to speed up the rendering
• ability to reseed tiles older than a certain timestamp
• ability to seed tiles given a shapefile/OGR datasource
Usage
The seeding utility is named mapcache_seed, and is located under your install directory (default is /usr/local/bin).
6.1. MapCache 1.4
393
MapServer Documentation, Release 7.0.6
Commandline Options
Options are available in short and long versions (e.g. -c or –config).
-c | –config [file]: path to the mapcache.xml configuration file that contains the tilesets that need to be seeded.
-D | –dimension “DIMENSION=VALUE”: used to specify which dimension to use if the tileset supports dimensions.
Can be used multiple times to set multiple dimensions, e.g. -D “DIM1=VAL1” -D “DIM2=VAL2”.
-e | –extent minx,miny,maxx,maxy: bounding box of the area to seed.
-f | –force: force recreation of existing tiles.
-g | –grid [grid]: name of the grid that must be seeded (the selected tileset must reference the given grid).
-h | –help: show help
-i | –iteration-mode: either “drill-down” or “level-by-level”. Default is to use drill-down for g, WGS84 and
GoogleMapsCompatible grids, and level-by-level for others. Use this flag to override.
-m | –mode: the mode to use the seeder: “seed”, “delete” or “transfer”. Default is seed (mode: seed).
-M | –metasize: override metatile size while seeding, e.g. 8,8.
-n | –nthreads: number of parallel threads that should be used to request tiles from the WMS source. The default is
1, but can be set higher if the WMS server can withstand parallel requests. (As a rule of thumb, the value chosen here
should never be much higher than the number of CPUs on the WMS server.)
Note: This option is imcompatible with the -p | –nprocesses option.
-o | –older [timestamp|now]: only seed tiles that are older than the given value. The value can either be the string
“now”, or a date formatted like year/month/day hour:minute, e.g. “2011/01/31 20:45”.
Note: A full timestamp should be quoted.
-p | –nprocesses: number of parallel processes that should be used to request tiles from the WMS source.
Note: This option is imcompatible with the -n | –nthreads option.
Warning: When working with multiple processes (-p switch) and SQLite cache backends, some errors may
appear under high concurrency when writing to the SQLite database (error: SQL logic error or missing database
(1)). Upgrading to SQLite >= 3.7.15 seems to resolve this issue.
-q | –quiet: don’t print progress messages to the standard output.
-t | –tileset [tileset]: name of the tileset that must be seeded.
-v | –verbose: print verbose debugging info (if compiled in).
-x | –transfer: the tileset to transfer when seeder is run in transfer mode.
-z | –zoom minzoom,maxzoom: start and end zoom levels that must be seeded.
6.1. MapCache 1.4
394
MapServer Documentation, Release 7.0.6
Optional Commandline Options When Using OGR/GEOS
At compile time, if OGR and GEOS are found on the system, the seeder tool will support additional options to seed
only the tiles that cover an arbitrary geographical area. Important: Note that, for the time being, the OGR datasource
should be in the same projection as the grid you are seeding, as there is no automatic reprojection from the datasource
projection to the grid projection.
-d | –ogr-datasource [ogr_datasource]: OGR connection to the spatial source. Consult the OGR documentation for
all that is supported. In the simplest case (e.g. a Shapefile), this is just the full filename of the shapefile.
-l | –ogr-layer [ogr_layer]: for datasources that contain multiple layers (e.g. PostGIS, with multiple tables), determines which layer will be used.
-s | –ogr-sql [ogr_sql]: OGR SQL expression that can be applied (see OGR SQL).
-w | –ogr-where [ogr_where]: SQL “where” expression to filter out returned values. This would typically be used to
select only the geometry of a given country if the datasource contains all the world contours.
Important Note
The seeding utility must be run under the same user account as the user running the webserver. This is required so the
permissions on the tiles created by the seeder are accessible by the webserver, and conversely so the seeder has the
rights to write files to directories created by the webserver.
A sample seeding session goes like this:
[user@host]$ sudo www-data
[www-data@host]$ /path/to/mapcache/src/mapcache_seed -c /path/to/www/conf/mapcache.
˓→xml [[options]]
[www-data@host]$ logout
[user@host]$
Examples
Seed the “osm” tileset with the “g” (Google / Web Mercator) grid:
./src/mapcache_seed -c mapcache.xml -t osm -g g
Seed levels 0 through 12:
./src/mapcache_seed -c mapcache.xml -t osm -g g -z 0,12
Given a shapefile that contains the world country contours, seed only the areas that are covered by land (i.e. skip the
oceans). Also, use 4 request threads in parallel:
./src/mapcache_seed -c mapcache.xml -t osm -g g -z 0,12 -n 4 -d /path/to/seed.shp
Same as beforehand, but only seed the USA (notice the quote usage, required to create valid SQL with a single-quoted
‘US’:
./src/mapcache_seed -c mapcache.xml -t osm -g g -z 0,12 -n 4 -d /path/to/seed.shp -w
˓→"FIPS_A2='US'"
Reseed levels 0 to 12 (this could also be done by deleting the cache for levels 0 to 12 and doing a classic seed, but
doing so this way does not slow down access from web clients):
6.1. MapCache 1.4
395
MapServer Documentation, Release 7.0.6
./src/mapcache_seed -c mapcache.xml -t osm -g g -z 0,12 -o now
6.1.5 Cache Types
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
This document details the different cache backends that can be used to store tiles.
Disk Caches
The disk based cache is the simplest cache to configure, and the one with the the fastest access to existing tiles. It is
ideal for small tile repositories, but will often cause trouble for sites hosting millions of tiles, as the number of files or
directories may rapidly overcome the capabilities of the underlying filesystem. Additionally, the block size chosen for
the filesystem must closely match the mean size of a stored tile: ideally, any given tile should just fit inside a filesystem
block, so as not to waste storage space inside each block, and not have to use up multiple blocks per tile.
The location of the files/directories has to be readable and writable by the user running the tile server.
Common Configuration
Disk caches are added via
<cache name="disk_cache" type="disk" layout="...">
...
<symlink_blank/>
<creation_retry>3</creation_retry>
</cache>
All caches except the “template” one support the <symlink_blank/> option which (depending on platform availability)
will detect tiles of uniform color and create a symbolic link to a single uniform color tile instead of storing the actual
blank data in the tile’s file.
All caches support the <creation_retry> option, which specifies the number of times MapCache should retry if it failed
to create a tile’s file or symlink. The default is to fail immediately: You may want to set this to a positive value if using
a network mounted filesystem where transient errors are common.
Default Structure
The default disk cache stores tiles in a structure nearly identical to the file/directory hierarchy used by TileCache. The
only change is that a top level directory structure corresponding to the name of the grid and the eventual value of the
tileset’s dimensions is added.
This cache is capable of detecting blank (i.e. uniform color) tiles and using a symbolic link to a single blank tile to
gain disk space.
<cache name="disk" type="disk">
<base>/tmp</base>
<symlink_blank/>
</cache>
6.1. MapCache 1.4
396
MapServer Documentation, Release 7.0.6
The only two configuration keys are the root directory where the tiles will be stored, and a key to activate the symbolic
linking of blank tiles.
Arcgis Compatible Structure
<cache name="arcgis" type="disk" layout="arcgis">
<base>/tmp</base>
<symlink_blank/>
</cache>
This layout creates a tile structure compatible with an arcgis exploded cache. Tiles will be stored in files that resemble
/tmp/{tileset}/{grid}/{dimension}/L{z}/R{y}/C{x}.{ext}
Worldwind Compatible Structure
<cache name="worldwind" type="disk" layout="worldwind">
<base>/tmp</base>
<symlink_blank/>
</cache>
This layout creates a tile structure compatible with a worldwind cache. Tiles will be stored in files that resemble
/tmp/{tileset}/{grid}/{dimension}/{z}/{y}/{y}_{x}.ext
Template Structure
The template based disk cache allows you to create (or reuse an existing) tile structure that you define in advance.
The <template> parameter takes a string argument where various template entries will be replaced at runtime by the
correct value for each tile to store.
<cache name="tmpl" type="disk" layout="template">
<!-- template
string template that will be used to map a tile (by tileset, grid name,
dimension,
format, x, y, and z) to a filename on the filesystem
the following replacements are performed:
- {tileset} : the tileset name
- {grid} : the grid name
- {dim} : a string that concatenates the tile's dimension
- {ext} : the filename extension for the tile's image format
- {x},{y},{z} : the tile x,y,z values
- {inv_x}, {inv_y}, {inv_z} : inverted x,y,z values (inv_x = level->maxx - x ˓→1). This
is mainly used to support grids where one axis is inverted (e.g. the
˓→google schema)
and you want to create on offline cache.
˓→
˓→
* Note that this type of cache does not support blank-tile detection and
symlinking.
* Warning: It is up to you to make sure that the template you chose creates a
unique
filename for your given tilesets. e.g. do not omit the {grid} parameter if
˓→your
˓→
6.1. MapCache 1.4
397
MapServer Documentation, Release 7.0.6
tilesets reference multiple grids. Failure to do so will result in filename
collisions !
-->
<template>/tmp/template-test/{tileset}#{grid}#{dim}/{z}/{x}/{y}.{ext}</template>
</cache>
Berkeley DB Caches
The Berkeley DB cache backend stores tiles in a key-value flat-file database, and therefore does not have the disadvantages of disk caches with regards to the number of files stored on the filesystem. As the image blobs are stored
contiguously, the block size chosen for the filesystem has no influence on the storage capacity of the volume.
Note that for a given bdb cache, only a single database file is created, which will store the tiles of its associated tilesets
(i.e. there is not a database file created per tileset, grid, and/or dimension). If you need to store different tilesets to
different files, then use multiple dbd cache entries. It is not possible to use multiple database files for tileset grids or
dimensions.
The Berkeley DB based caches are a bit faster than the disk based caches during reads, but may be a bit slower during
concurrent writes if a high number of threads all try to insert new tiles concurrently.
<cache name="bdb" type="bdb">
<!-- base (required)
absolute filesystem path where the Berkeley DB database file is to be stored.
this directory must exist, and be writable
-->
<base>/tmp/foo/</base>
<!-- key_template (optional)
string template used to create the key for a tile entry in the database.
defaults to the value below. you should include {tileset}, {grid} and {dim} here
unless you know what you are doing, or you will end up with mixed tiles
<key_template>{tileset}-{grid}-{dim}-{z}-{y}-{x}.{ext}</key_template>
-->
</cache>
SQLite Caches
There are two different SQLite caches that vary by the database schema they create and query. SQLite caches have
the advantage that they store tiles as blobs inside a single database file, and therefore do not have the disadvantages
of disk caches with regards to the number of files stored. As the image blobs are stored contiguously, the block size
chosen for the filesystem has no influence on the storage capacity of the volume.
The SQLite based caches are a bit slower than the disk based caches, and may have write-locking issues at seed time
if a high number of threads all try to insert new tiles concurrently.
Default Schema
Tiles are stored in the configured SQLite file created by MapCache with
create table if not exists tiles(
tileset text,
grid text,
x integer,
6.1. MapCache 1.4
398
MapServer Documentation, Release 7.0.6
y integer,
z integer,
data blob,
dim text,
ctime datetime,
primary key(tileset,grid,x,y,z,dim)
);
<cache name="sqlite" type="sqlite3">
<dbfile>/path/to/dbfile.sqlite3</dbfile>
</cache>
You may also add custom SQLite pragmas that will be executed when first connecting to a SQLite db, e.g. to override
some compiled-in SQLite defaults
<cache name="sqlite" type="sqlite3">
<dbfile>/tmp/sqlitefile.db</dbfile>
<pragma name="max_page_count">10000000</pragma>
</cache>
<pragma> entries will result in a call to
PRAGMA max_page_count = 1000000;
Custom Schema
This cache can use any database schema: It is up to you to supply the SQL that will be exectuted to select or insert a
new tile.
In order to use such functionality you should supply the SQL queries that will be used against your custom schema. It
is up to you to make sure your queries are correct and will return the correct data for a given tileset, dimension, grid,
x, y and z.
<cache name="sqlitecustom" type="sqlite3">
<dbfile>/tmp/sqlitefile.db</dbfile>
<queries>
<create>create table if not exists tiles(tileset text, grid text, x integer, y
˓→integer, z integer, data blob, dim text, ctime datetime, primary key(tileset,grid,x,
˓→y,z,dim))</create>
<exists>select 1 from tiles where x=:x and y=:y and z=:z and dim=:dim and
˓→tileset=:tileset and grid=:grid</exists>
<get>select data,strftime("%s",ctime) from tiles where tileset=:tileset and
˓→grid=:grid and x=:x and y=:y and z=:z and dim=:dim</get>
<set>insert or replace into tiles(tileset,grid,x,y,z,data,dim,ctime) values (:
˓→tileset,:grid,:x,:y,:z,:data,:dim,datetime('now'))</set>
<delete>delete from tiles where x=:x and y=:y and z=:z and dim=:dim and tileset=:
˓→tileset and grid=:grid</delete>
</queries>
</cache>
Note that for the <get> query that returns data for a given tile, the first returned argument is considered to be the image
blob, and the second optional one a timestamp representing the creation timestamp for that tile.
6.1. MapCache 1.4
399
MapServer Documentation, Release 7.0.6
Blank Tile Detection
MapCache’s SQLite caches support the detection and storage of blank (i.e. uniform color) tiles, and will store a
quadruplet of the rgba color component in the data blob instead of the compressed image data itself. That quadruplet
will be transformed on-the-fly to a 1-bit palleted PNG before being returned to the client.
<cache name="sqliteblank" type="sqlite3">
<dbfile>/tmp/sqlitefile.db</dbfile>
<detect_blank/>
</cache>
Note: SQLite files created with this option will only be fully understood by MapCache as each tile blob may contain
a #rgba quadruplet instead of the expected PNG or JPEG data.
Using Multiple SQLite Database Files
You may want to split an SQLite cache into multiple files, for organisational purposes, or to keep the size of each file
to a reasonable limit if caching large amounts of data.
In order to do so you may use a template to determine which file should be used for a given file:
<cache name="sqlite" type="sqlite3">
<dbfile>/path/to/{grid}/{dim}/{tileset}.sqlite3</dbfile>
</cache>
You may also limit the x and y number of tiles to be stored inside a single database file:
<cache name="sqlite" type="sqlite3">
<dbfile>/path/to/{grid}/{dim}/{tileset}/{z}/{x}-{y}.sqlite3</dbfile>
<xcount>1000</xcount>
<ycount>1000</ycount>
</cache>
In this case you should include the {x}, {y} and {z} replacements in the template determining the file to use. In the previous example, tile (z,x,y)=(15,3024,1534) would be stored in a file named /path/to/g/mytileset/15/3000-1000.sqlite3
and tile (5,2,8) would be stored in a file named /path/to/g/mytileset/5/0-0.sqlite3
The following template keys are available for operating on the given tile’s x,y, and z:
• {z} is replaced by the zoom level.
• {x} is replaced by the x value of the leftmost tile inside the SQLite file containing the requested tile.
• {inv_x} is replaced by the x value of the rightmost tile.
• {y} is replaced by the y value of the bottommost tile.
• {inv_y} is replaced by the y value of the topmost tile.
• {div_x} is replaced by the index of the SQLite file starting from the left of the grid (i.e. {div_x} = {x}/<xcount>).
• {inv_div_x} same as {div_x} but starting from the right.
• {div_y} is replaced by the index of the SQLite file starting from the bottom of the grid (i.e. {div_y} =
{y}/<ycount>).
• {inv_div_y} same as {div_y} but starting from the top.
6.1. MapCache 1.4
400
MapServer Documentation, Release 7.0.6
Note: {inv_x} and {inv_div_x} will probably be rarely used, whereas {inv_y} and {inv_div_y} will find some usage
by people who prefer to index their dbfiles files from top to bottom rather than bottom to top.
In some cases, it may be desirable to have a precise hand on the filename to use for a given x,y,z tile lookup, e.g.
to look for a file named Z03-R00003-C000009.sqlite3 instead of just Z3-R3-C9.sqlite3. The <dbfile> entry supports
formatting attributes, following the Unix printf syntax ( c.f.: http://linux.die.net/man/3/printf ), by suffixing each
template key with “_fmt”, e.g.:
<cache name="mysqlite" type="sqlite3">
<dbfile
x_fmt="%08d"
inv_y_fmt="%08d"
>/data/{tileset}/{grid}/L{z}/R{inv_y}/C{x}.sqlite</template>
</cache>
Note: If not specified, the default behavior is to use “%d” for formatting.
MBTiles Caches
This cache type is a shortcut to the previous custom schema SQLite cache, with pre-populated SQL queries that
correspond to the MBTiles specification.
Although the default MBTiles schema is very simple, MapCache uses the same multi- table schema found in most
downloadable MBTiles files, notably to enable storing blank (i.e. uniform) tiles without duplicating the encoded
image data (in the same way the disk cache supports tile symlinking).
The MBTiles schema is created with:
create table if not exists images(
tile_id text,
tile_data blob,
primary key(tile_id));
create table if not exists map (
zoom_level integer,
tile_column integer,
tile_row integer,
tile_id text,
foreign key(tile_id) references images(tile_id),
primary key(tile_row,tile_column,zoom_level));
create table if not exists metadata(
name text,
value text); -- not used or populated yet
create view if not exists tiles
as select
map.zoom_level as zoom_level,
map.tile_column as tile_column,
map.tile_row as tile_row,
images.tile_data as tile_data
from map
join images on images.tile_id = map.tile_id;
6.1. MapCache 1.4
401
MapServer Documentation, Release 7.0.6
<cache name="mbtiles" type="mbtiles">
<dbfile>/Users/XXX/Documents/MapBox/tiles/natural-earth-1.mbtiles</dbfile>
</cache>
Note: Contrarily to the standard SQLite MapCache schema, the MBTiles db file only supports a single tileset per
cache. The behavior if multiple tilesets are associated to the same MBTiles cache is undefined, and will definitely
produce incorrect results.
Warning: When working with multiple processes (-p switch) and SQLite cache backends, some errors may
appear under high concurrency when writing to the SQLite database (error: SQL logic error or missing database
(1)). Upgrading to SQLite >= 3.7.15 seems to resolve this issue.
Memcache Caches
This cache type stores tiles to an external memcached server running on the local machine or accessible on the network.
This cache type has the advantage that memcached takes care of expiring tiles, so the size of the cache will never exceed
what has been configured in the memcache instance.
Memcache support requires a rather recent version of the apr-util library. Note that under very high loads (usually
only attainable on synthetic benchmarks on localhost), the memcache implementation of apr-util may fail and start
dropping connections for some intervals of time before coming back online afterwards.
You can add multiple <server> entries.
<cache name="memcache" type="memcache">
<server>
<host>localhost</host>
<port>11211</port>
</server>
</cache>
Note: Tiles stored in memcache backends are configured to expire in 1 day by default. This can be overridden at the
tileset level with the <auto_expire> keyword.
To limit the memory used by blank tiles inside the memcache instance, you may enable blank tile detection, in which
case a #rgba quadruplet will be stored to the cache instead of the actual image data. MapCache will convert that
on-the-fly to a 1-bit palleted PNG image before returning it to the client.
<cache name="memcache" type="memcache">
<detect_blank/>
...
</cache>
(Geo)TIFF Caches
TIFF caches are the most recent addition to the family of caches, and use the internal tile structure of the TIFF
specification to access tile data. Tiles can be stored in JPEG only (TIFF does not support PNG tiles).
As a single TIFF file may contain many tiles, there is a drastic reduction in the number of files that have to be stored
on the filesystem, which solves the major shortcomings of the disk cache. Another advantage is that the same TIFF
6.1. MapCache 1.4
402
MapServer Documentation, Release 7.0.6
files can be used by programs or WMS servers that only understand regular GIS raster formats, and be served up with
high performance for tile access.
The TIFF cache should be considered read-only for the time being. Write access is already possible but should be
considered experimental as there might be some file corruption issues, notably on network filesystems. Note that
until all the tiles in a given TIFF file have been seeded/created, the TIFF file is said to be “sparse” in the sense that
it is missing a number of JPEG tiles. As such, most non-GDAL based programs will have problems opening these
incomplete files.
Note that the TIFF tile structure must exactly match the structure of the grid used by the tileset, and the TIFF file
names must follow strict naming rules.
Defining the TIFF File Sizes
The number of tiles stored in each of the horizontal and vertical directions must be defined:
• <xcount> the number of tiles stored along the x (horizontal) direction of the TIFF file
• <ycount> the number of tiles stored along the y (vertical) direction of the TIFF file
<cache name="tiff" type="tiff">
<xcount>64</xcount>
<ycount>64</ycount>
...
</cache>
Setting Up the File Naming Convention
The <template> tag sets the template to use when looking up a TIFF file name given the x,y,z of the requested tile
<cache name="tiff" type="tiff">
<template>/data/tiffs/{tileset}/{grid}/L{z}/R{inv_y}/C{x}.tif</template>
...
</cache>
The following template keys are available for operating on the given tile’s x,y, and z:
• {x} is replaced by the x value of the leftmost tile inside the TIFF file containing the requested tile.
• {inv_x} is replaced by the x value of the rightmost tile.
• {y} is replaced by the y value of the bottommost tile.
• {inv_y} is replaced by the y value of the topmost tile.
• {div_x} is replaced by the index of the TIFF file starting from the left of the grid (i.e. {div_x} = {x}/<xcount>).
• {inv_div_x} same as {div_x} but starting from the right.
• {div_y} is replaced by the index of the TIFF file starting from the bottom of the grid (i.e. {div_y} =
{y}/<ycount>).
• {inv_div_y} same as {div_y} but starting from the top.
Note: {inv_x} and {inv_div_x} will probably be rarely used, whereas {inv_y} and {inv_div_y} will find some usage
by people who prefer to index their TIFF files from top to bottom rather than bottom to top.
6.1. MapCache 1.4
403
MapServer Documentation, Release 7.0.6
Customizing the Template Keys
In some cases, it may be desirable to have a precise hand on the filename to use for a given x,y,z tile lookup, e.g.
to look for a file named “Z03-R00003-C000009.tif” instead of just “Z3-R3-C9.tif”. The <template> entry supports
formatting attributes, following the Unix printf syntax ( c.f.: http://linux.die.net/man/3/printf ), by suffixing each
template key with “_fmt”, e.g.:
<cache name="tiff" type="tiff">
<template
x_fmt="%08d"
inv_y_fmt="%08d"
>/data/tiffs/{tileset}/{grid}/L{z}/R{inv_y}/C{x}.tif</template>
</cache>
Note: If not specified, the default behavior is to use “%d” for formatting.
Setting JPEG Compression Options
An additional optional parameter defines which JPEG compression should be applied to the tiles when saved into the
TIFF file:
• <format> the name of the (JPEG) format to use
See also:
JPEG Format
<cache name="tiff" type="tiff">
...
<format>myjpeg</format>
</cache>
In this example, assuming a grid using 256x256 tiles, the files that are read to load the tiles are tiled TIFFs with JPEG
compression, whose size are 16384x16384. The number of files to store on disk is thus reduced 4096 times compared
to the basic disk cache.
Using a Specific Locker
MapCache needs to create a lock when writing inside a TIFF file to ensure that no two instances are updating the same
file concurrently. By default the global MapCache locker will be used; you can, however, configure a different locking
mechanism or behavior by configuring it inside the TIFF cache itself.
See also:
Locking Mechanisms
<cache name="tiff" type="tiff">
...
<locker> .... </locker>
</cache>
6.1. MapCache 1.4
404
MapServer Documentation, Release 7.0.6
GeoTIFF Support
If compiled with GeoTIFF and write support, MapCache will add referencing information to the TIFF files it creates,
so that the TIFF files can be used in any GeoTIFF-enabled software. Write support does not produce full GeoTIFFs
with the definition of the projection used, but only the pixel scale and tie-points, i.e. what is usually found in .tfw files.
For reference, here is the gdalinfo output on a TIFF file created by MapCache when compiled with GeoTIFF support:
LOCAL_CS["unnamed",
UNIT["metre",1,
AUTHORITY["EPSG","9001"]]]
Origin = (-20037508.342789247632027,20037508.342789247632027)
Pixel Size = (156543.033928040997125,-156543.033928040997125)
Metadata:
AREA_OR_POINT=Area
Image Structure Metadata:
COMPRESSION=YCbCr JPEG
INTERLEAVE=PIXEL
SOURCE_COLOR_SPACE=YCbCr
Corner Coordinates:
Upper Left (-20037508.343,20037508.343)
Lower Left (-20037508.343,-20037508.343)
Upper Right (20037508.343,20037508.343)
Lower Right (20037508.343,-20037508.343)
Center
(
0.0000000,
0.0000000)
REST Caches
The following cache types store and retrieve tiles through standard HTTP GET and PUT operations, and can be used
to store tiles in popular cloud storage providers.
Pure REST Cache
This cache type can be used to store tiles to a WebDAV enabled server. You must provide a template URL that should
be used when accessing a tile with a given x,y,z, etc...
<cache name="myrestcache" type="rest">
<url>https://myserver/webdav/{tileset}/{grid}/{z}/{x}/{y}.{ext}</url>
</cache>
Specifying HTTP Headers
You can customize which headers get added to the HTTP request, either globally for every HTTP request, or specifically for a given type of request (i.e. when getting, setting or deleting a tile):
<cache name="myrestcache" type="rest">
<url>https://myserver/webdav/{tileset}/{grid}/{z}/{x}/{y}.{ext}</url>
<headers>
<Host>my-virtualhost-alias.domain.com</Host>
</headers>
<operation type="put">
<headers>
<X-my-specific-put-header>foo</X-my-specific-put-header>
6.1. MapCache 1.4
405
MapServer Documentation, Release 7.0.6
</headers>
</operation>
<operation type="get">
<headers>
<X-my-specific-get-header>foo</X-my-specific-get-header>
</headers>
</operation>
<operation type="head">
<headers>
<X-my-specific-head-header>foo</X-my-specific-head-header>
</headers>
</operation>
<operation type="delete">
<headers>
<X-my-specific-delete-header>foo</X-my-specific-delete-header>
</headers>
</operation>
</cache>
Amazon S3 REST Caches
The REST cache has been specialized to enable access to Amazon S3, in order to add the layer of authentication/authorization needed for that platform.
<cache name="s3" type="s3">
<url>https://foo.s3.amazonaws.com/tiles/{tileset}/{grid}/{z}/{x}/{y}/{ext}</url>
<headers>
<Host>foo.s3.amazonaws.com</Host>
</headers>
<id>AKIE3SDEIT6TUG8DXEQI</id>
<secret>5F+dGsTfsdfkjdsfSDdasf4555d/sSff56sd/RDS</secret>
<region>eu-west-1</region>
<operation type="put">
<headers>
<x-amz-storage-class>REDUCED_REDUNDANCY</x-amz-storage-class>
<x-amz-acl>public-read</x-amz-acl>
</headers>
</operation>
</cache>
The <id> <secret> and <region> tags are required and are obtained and configured through your Amazon management
console. You should read the documentation as to what headers you want to be adding to your requests depending on
your use case (the supplied example hosts tiles on cheaper storage, and allows them to be publicly accessible).
Microsoft Azure REST Caches
The REST cache has been specialized to enable access to Azure storage, in order to add the layer of authentication/authorization needed for that platform.
<cache name="azure" type="azure">
<url>https://foo.blob.core.windows.net/tiles/{tileset}/{grid}/{z}/{x}/{y}/{ext}</
˓→url>
<headers>
<Host>foo.blob.core.windows.net</Host>
6.1. MapCache 1.4
406
MapServer Documentation, Release 7.0.6
</headers>
<id>foo</id>
<secret>foobarcccccccccccccccccccccyA==</secret>
<container>tiles</container>
</cache>
The <id> <secret> and <container> tags are required and are obtained and configured through your management
console. You should read the documentation as to what headers you want to be adding to your requests depending on
your use case.
Google Cloud Storage REST Caches
The REST cache has been specialized to enable access to Google Cloud Storage, in order to add the layer of authentication/authorization needed for that platform.
<cache name="google" type="google">
<url>https://storage.googleapis.com/mytiles-mapcache/{tileset}/{grid}/{z}/{x}/{y}.
˓→{ext}</url>
<access>GOOGPGDWFDG345SDFGSD</access>
<secret>sdfgsdSDFwedfwefr2345324dfsGdsfgs</secret>
<operation type="put">
<headers>
<x-amz-acl>public-read</x-amz-acl>
</headers>
</operation>
</cache>
The <access> and <secret> tags are required and are obtained and configured through your management console. You
should read the documentation as to what headers you want to be adding to your requests depending on your use case.
Note that support for Google Cloud Storage uses its Amazon compatibility layer.
Meta Caches
These cache types do not store tiles themselves, but rather delegate the storage of a tile to a number of child caches
based on a set of rules or behaviors. These caches are mostly useful for large MapCache deployments across multiple
instances, with shared cache backends (i.e. dedicated memcache servers, and network mounted filer filesystems).
Composite Caches
This cache uses different child caches depending on the tile’s zoom level, and can be used for example to store low
zoom-level tiles to permanent storage, and higher zoom-level tiles to a temporary (i.e. memcache) cache.
<cache name="mydisk" ...> ... </cache>
<cache name="mymemcache" ...> ... </cache>
<cache name="composite" type="composite">
<cache grids="mygrid,g">mycache</cache>
<cache min-zoom="0" max-zoom="8">mydisk</cache>
<cache min-zoom="9">mymemcache</cache>
</cache>
<tileset ...>
<cache>composite</cache>
...
</tileset>
6.1. MapCache 1.4
407
MapServer Documentation, Release 7.0.6
For each tile, the caches are tested in the order in which they have been defined in the configuration file, and the first
one to satisfy the min/max zoom and grids constraints is used. It’s up to the user to make sure the succession of
min/max zoom values and grids makes sense, e.g.:
<cache name="composite" type="composite">
<cache min-zoom="0">cache1</cache>
<cache min-zoom="9">this_cache_will_never_be_used</cache>
</cache>
Fallback Caches
These cache types will return tiles from the first configured subcache that does not return an error. They can be used
when one of the caches is prone to error conditions (e.g. remote REST caches, memcache)
<cache name="fallback" type="fallback">
<cache>mymemcache</cache>
<cache>mysqlitecache</cache>
</cache>
When writing a tile to such a cache, it will be written to all the child caches.
Multitier Caches
These cache types can be used to combine fast/expensive caches with slow/cheap ones.
<cache name="multitier" type="multitier">
<cache>fast</cache>
<cache>cheap</cache>
</cache>
If a given tile isn’t found in the first child cache, it will be read from the second child cache and copied into the first
child cache for subsequent accesses. This cache type is meant to be used when the first cache does automatic pruning
of the least recently used tiles (i.e. a memcache one).
When writing a tile to such a cache, it will be written to the last child.
Cache Combinations
All these meta caches can be combined together to fine tune the availability and performance depending on storage
costs, time to recreate missing tiles, etc...
<cache name="slow_and_permanent" type="sqlite">...</cache>
<cache name="fast_and_transient" type="memcache">...</cache>
<cache name="low_zooms" type="multitier">
<cache>fast_and_transient</cache>
<cache>slow_and_permanent</cache>
<cache>
<cache name="mycache" type="composite">
<cache maxzoom="12">low_zooms</cache>
<cache>fast_and_transient</cache>
<cache>
<tileset>
<cache>mycache</cache>
6.1. MapCache 1.4
408
MapServer Documentation, Release 7.0.6
...
</tileset>
In the previous example, all tiles are primarily accessed from a memcache instance, however the lower zoom level tiles
are backed up to a permanent SQLite cache which will be used to populate the fast memcache cache e.g. on restarts.
Riak Caches
requires https://github.com/trifork/riack
<cache name="myriak" type="riak">
<server>
<host>riakhost</host>
<port>12345</port>
<bucket>mytiles</bucket>
</server>
</cache>
6.1.6 Image Formats
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
MapCache allows you to configure how the image should be saved to a cache once it has been requested from a source.
The JPEG format should mostly be used for raster imagery, whereas the PNG format is most useful for vector based
imagery where there are large uniform areas.
JPEG Format
The JPEG format saves tiles to JPEG. You can configure the JPEG compression level (from 1 to 100) and the colorspace
that should be used (RGB or YCbCr)
<format name="myjpeg" type="JPEG">
<quality>85</quality>
<photometric>ycbcr</photometric>
</format>
• quality: This is the typical JPEG quality setting. Values under 50 produce lighter images but with notable
compression artifacts. 100 should be avoided as it produces very heavy images.
• photometric: By default the YCbCr colorspace is used as it produces images that tend to be 2 to 3 times lighter.
Use RGB if you don’t want the default.
PNG Format
The PNG format creates PNG images, with optional quantization (reduction of the number of colors to create an 8-bit
palleted PNG).
<format name="mypng" type="PNG">
<compression>fast</compression>
<colors>256</colors>
</format>
6.1. MapCache 1.4
409
MapServer Documentation, Release 7.0.6
• compression: Choose which zlib compression to apply to the image data. Recognized values are “fast” and
“best”. Omit the key to use the default zlib compression.
• colors: Number of colors to use for quantization. Omit this key to produce 24 or 32 bit RGB/RGBA PNGs, or
set to a value between 2 and 256 to create an 8-bit palleted PNG. The quantization step is destructive: There is
no guarantee that pixels will not have a noticeable shift in color in the case when the tile contains many colors.
Mixed Format
There is a third special format which mixes JPEG and PNG compression depending on the contents of the image.
This format allows creation of caches for raster imagery using JPEG compression (which is more efficient) on zones
with imagery data, and PNG compression (which supports trasnparency) on zones with no imagery or on a boundary
between imagery and emptiness.
<format name="mymixed" type="MIXED">
<opaque>myjpeg</opaque>
<transparent>mypng</transparent>
</format>
• opaque: The format to use when the image has only fully opaque pixels
• transparent: The format to use when the image has some transparent or semi-opaque pixels.
6.1.7 Tileset Dimensions
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
6.1.8 HTTP Requests
HTTP configuration blocks are used in multiple places in the MapCache configuration.
Specifying the URL
The simplest HTTP configuration block requires a single <url> child element:
<http>
<url>http://server/path?key=value</url>
</http>
Timeouts
You may configure the timeouts after which an HTTP request is abandoned:
<http>
<url>http://server/path?key=value</url>
<!-- timeout in seconds to wait while establishing a connection. This may be needed
for
firewalled MapCache or HTTP instances -->
<connection_timeout>30</connection_timeout>
˓→
6.1. MapCache 1.4
410
MapServer Documentation, Release 7.0.6
<!-- total maximum time allowed for the whole request. Includes the time needed to
transfer data down the wire -->
<timeout>60</timeout>
</http>
Headers
You can insert custom headers in the request, or forward headers received from the client request:
<http>
<url>http://server/path?key=value</url>
<headers>
<User-Agent>My MapCache User-Agent</User-Agent>
<!-- hard coded header -->
<X-My-Forwarded-Header>{X-Received-Header}<X-My-Forwarded-Header> <!-- Forwarded
˓→from client, optionally changing the header name -->
<X-My-Forwarded-Header-2>foobar-{X-Received-Header}-baz<X-My-Forwarded-Header-2>
˓→<!-- Forwarded and modified from client, optionally changing the header name -->
</headers>
</http>
6.1.9 FeatureInfo Requests
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
TBD
6.1.10 Proxying Unsupported Requests
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
Note: This page is a work in progress.
MapCache has the ability to forward any incoming request that it cannot natively respond to (either by returning a tile
directly, by merging multiple tiles, etc.).
This setup allows MapCache to be placed transparently in front of an existing OGC-service supplying server to accelerate tiled or GetMap requests for a selected number of grids, while maintaining service compatibility for, e.g.,
unsupported grids, WFS requests, ...
Note: The proxying of requests is configured inside the WMS MapCache service, which is semantically awkward.
The configuration for this behavior is activated by a succession of entries inside the <forwarding_rule> element of the
wms <service>. Rules are tested for in the order in which they appear in the mapcache.xml configuration file, and the
first one that matches is used. If no rules are defined, or if no rule matches the incoming request, an error is returned
to the user.
6.1. MapCache 1.4
411
MapServer Documentation, Release 7.0.6
<service type="wms" enabled="true">
<forwarding_rule name="first rule">
<!-- rule tests -->
<!-- proxy destination -->
</forwarding_rule>
<forwarding_rule name="second rule">
<!-- rule tests -->
<!-- proxy destination -->
</forwarding_rule>
</service>
A <forwarding_rule> consists of a set of matching rules and an <http> block defining where the request should be
forwarded to.
Parameter Filtering
The rules apply to the key-value pair parameters received in the incoming request, and are added with the <param>
keyword:
<forwarding_rule name="first rule">
<param name="SERVICE" type="values">WFS,WCS</param>
<!-- ... !>
<forwarding_rule>
The “type” attribute is the same as what is allowed for dimensions, i.e. allowed values are “values”, “regex”, and
“intervals”. In the previous example, the rule would match any incoming request having ...&SERVICE=WFS&... or
...&SERVICE=WCS&... in its request parameters.
<forwarding_rule name="first rule">
<param name="SERVICE" type="values">WFS,WCS</param>
<param name="LAYERS" type="values">somelayername</param>
<!-- ... !>
<forwarding_rule>
Multiple rules can be used if the filtering has to be done on multiple parameters. In the previous example, the rule
would match a WFS or WCS request that concerns the “somelayername” layer only.
A <forwarding_rule> that has no <param> child will match any incoming request that could not be serviced by
MapCache directly from its cache, and can be used to forward all unsupported request to a full OGC- compliant
server so that an un-cached response can be returned to the client.
See also:
Tileset Dimensions
Proxy Destination
Once a <forwarding_rule> matches, its <http> child will be used to proxy the request to another server.
<forwarding_rule name="first rule">
<!-- ... !>
<http>
<url>http://wmsserver/ogc.cgi?</url>
</http>
<forwarding_rule>
6.1. MapCache 1.4
412
MapServer Documentation, Release 7.0.6
See also:
HTTP Requests
6.1.11 Data Sources
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
MapCache uses the concept of a “source” as a service that is able to return image data given a set of parameters
(namely an extent, an image size, and a projection). Typically, a source is the third-party WMS server that you want
to put a tile cache in front of.
WMS Sources
A WMS server is the main upstream server type used by MapCache. When processing a given tile, if it is not found
in its cache, MapCache will query a WMS server with a GetMap request, split the returned image data into individual
tiles, and store those tiles in its cache for subsequent requests.
<source name="mywmsserver" type="wms">
<http> .... </http>
<getmap>
<params>
<map>/path/to/mapserver/mapfile.map</map>
<layers>value2</layers>
</params>
</getmap>
</source>
See also:
HTTP Requests to configure how the <http> block should be expressed
Warning: You should usually only supply vendor-specific parameters to the <params> block. Never include any
hardcoded BBOX, WIDTH, HEIGHT, SRS or any parameters related to dimensions inside this block, as these are
calculated by MapCache itself at runtime.
MapFile Sources
Experimental
WMTS Sources
MapCache WMTS source uses GDAL WMTS driver under the hood. Note that GDAL version must be > 2.1 to be
able to enable the driver correctly. GDAL WMTS driver documentation can be found on: http://www.gdal.org/frmt_
wmts.html
GDAL WMTS xml file is needed, example command to construct such a file directly from wmts source equipped with
basic auth & user/pass is: gdal_translate “WMTS:https://<url to capabilities>,layer=<layer id>” gdal_wmts.xml -of
WMTS –config GDAL_HTTP_AUTH BASIC –config GDAL_HTTP_USERPWD <user:pass>
After GDAL WMTS xml file is constructed, it’s validity can be checked with command “gdalinfo <name of xml file>”.
6.1. MapCache 1.4
413
MapServer Documentation, Release 7.0.6
last step is to enable the new WMTS source with following configuration in mapcache.xml.
<source type="gdal" name="foo">
<data>/path/to/gdal/file (gdal_wmts.xml)</data>
</source>
6.1.12 Tile Assembling
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
TBD
6.1.13 Locking Mechanisms
Author Thomas Bonfort
Contact tbonfort at terriscope.fr
MapCache sometimes needs exclusive access to a given resource, and provides some mechanisms to ensure that no
more than one MapCache instance can operate on that resource. This may happen when:
• Sending a request to a source WMS server for a given metatile. Only a single MapCache instance should be
sending that request; other MapCache instances processing a tile from that same metatile should wait for that
request to finish rather than sending the same exact request again (in order not to overload the WMS server).
• Writing a tile inside a TIFF cache. The TIFF library does not handle concurrent writes, so MapCache must
ensure that only a single instance is accessing a given TIFF file for writing.
A locker is configured with:
<locker type="...">
<timeout>60</timeout>
<retry>0.1</retry>
...
</locker>
When a MapCache instance cannot acquire a lock because it has already been acquired by another instance, it will:
• Check back every <retry> seconds to see if the lock has been released by the other instance.
• Consider that after <timeout> seconds the other instance has failed, and delete the lock before acquiring it itself.
Disk Locks
This locking mechanism places a file somewhere in the filesystem. The filesystem can be a network share in order to
synchronize multiple MapCache instances.
<locker type="disk">
<directory>/path/to/lockdir</directory>
</locker>
The configured directory should be read/write accessible by the MapCache instance.
6.1. MapCache 1.4
414
MapServer Documentation, Release 7.0.6
Memcache Locks
This locking mechanism uses a third-party memcache instance to keep track of the locks.
<locker type="memcache">
<server>
<host>localhost</host>
<port>11211</port>
</server>
<server>
<host>memcache-host</host>
<port>11212</port>
</server>
</locker>
Fallback Locks
This “meta” locker will fall back to its second configured locker if the first one fails (typically used with a memcache
instance if the memcache instance goes down).
<locker type="fallback"
<locker type="memcache">
<server>
<host>localhost</host>
<port>11211</port>
</server>
<server>
<host>memcache-host</host>
<port>11212</port>
</server>
</locker>
<locker type="disk">
<directory>/path/to/lockdir</directory>
</locker>
</locker>
See also:
MapCache presentation slides at FOSS4G2011
6.1.14 Features
• services WMS, WMTS, TMS, VirtualEarth/Bing and Google Maps requests: Supported Tile Services
• ability to respond to untiled WMS requests by merging tiles from the cache or forwarding them to the WMS
source: Tile Assembling
• responds to WMS/WMTS GetFeatureInfo requests (forwarded to source service)
• KML superoverlay generation
• data provided by WMS backends (GDAL supported sources planned)
• cache types:
– Disk
– SQLite
6.1. MapCache 1.4
415
MapServer Documentation, Release 7.0.6
– Memcached
– Tiled TIFFs
– REST (S3, Azure, Google)
– Riak
– Combined caches
– Berkeley DB
• configurable metatiling
• on-the-fly tile merging for combining multiple tiles into a single image
• image post-processing (recompression and quantization) when arriving from a backend
• interprets and produces cache control headers: Last-Modified, If-Modified-Since, Expires
• multithreaded seeding utility that can seed specific zoom levels or specific areas (e.g. seed levels 0 to 12 of all
tiles intersecting Colorado)
• ability to add a custom watermark on stored tiles
• produces a CGI/FastCGI executable for use with webservers other than Apache
• configurable symbolic linking of blank tiles to save disk space
• configurable error reporting: plain HTTP error code, textual message, or empty (blank) image
• ability to specify vendor parameters or dimensions to be forwarded to the WMS backend (and to build a cache
that takes these parameters into account): Tileset Dimensions
6.1. MapCache 1.4
416
CHAPTER 7
Input
7.1 Data Input
7.1.1 Vector Data
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Author Tyler Mitchell
Contact tmitchell at osgeo.org
Last Updated 2016-12-19
This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,
visit: http://creativecommons.org/licenses/by-sa/2.0/ca/ or send a letter to Creative Commons, 559 Nathan Abbott
Way, Stanford, California 94305, USA.
What is vector data? This quote from is a good description of what vector data is:
Vector: “An abstraction of the real world where positional data is represented in the form of coordinates.
In vector data, the basic units of spatial information are points, lines and polygons. Each of these units
is composed simply as a series of one or more coordinate points. For example, a line is a collection of
related points, and a polygon is a collection of related lines. Vector images are defined mathematically
as a series of points joined by lines. Vector-based drawings are resolution independent. This means that
they appear at the maximum resolution of the output device, such as a printer or monitor. Each object is
self-contained, with properties such as color, shape, outline, size, and position on the screen.”
From: http://www8.nos.noaa.gov/coris_glossary/index.aspx?letter=v
The rest of this document is the data format guide. This guide is structured to show the fundamentals of each
MapServer supported data format. Each section discusses one format, ranging from one to several pages in length.
The sections typically start with a summary of the most important information about the format, followed by examples
of file listings, connection methods, ogrinfo usage and MapServer map file syntax examples.
Each section has been designed to stand alone, so you may notice that certain warnings and comments are repeated
or redundant. This is intentional. Each format is presented in rough order of popular use, based on a survey of the
MapServer community.
The following formats are included:
417
MapServer Documentation, Release 7.0.6
Data Format Types
Each type of data is made up of a data source and (one or more) layers. These two definitions apply to MapServer and
OGR.
Data Source - a group of layers stored in a common repository. This may be a file that handles several layers within
it, or a folder that has several files.
Layer - a sub-set of a data source often containing information in one type of vector format (point, line, polygon).
There are three types of data mapping and GIS data formats. Each type is handled differently. Below are the types and
some example formats:
• File-based- Shapefiles, Microstation Design Files (DGN), GeoTIFF images
• Directory-based - ESRI ArcInfo Coverages, US Census TIGER
• Database connections - PostGIS, ESRI ArcSDE, MySQL
File-based Data
File-based data consists of one or more files stored in any arbitrary folder. In many cases a single file is used (e.g.
DGN) but ESRI Shapefiles, for example, consist of at least 3 files each with a different filename extension: SHP, DBF,
SHX. In this case all 3 files are required because they each perform a different task internally.
Filenames usually serve as the data source name and contain layers that may or may not be obvious from the filename.
In Shapefiles, for example, there is one data source per shapefile and one layer which has the same name as that of the
file.
Directory-based Data
Directory-based data consists of one or more files stored in a particular way within a parent folder. In some cases
(e.g. Coverages) they may also require additional folders in other locations in the file tree in order to be accessed. The
directory itself may be the data source. Different files within the directory often represent the layers of data available.
For example, ESRI ArcInfo Coverages consist of more than one file with an ADF file extension, within a folder. The
PAL.ADF file represents the Polygon data. ARC.ADF holds the arc or line string data. The folder holds the data
source and each ADF file is a layer.
Database Connections
Database Connections are very similar to file and directory-based structures in one respect: they provide geographic
coordinate data for MapServer to interpret. That may be oversimplifying what is happening inside MapServer, but in
essence all you need is access to the coordinates making up the vector datasets.
Database connections provide a stream of coordinate data that is temporarily stored (e.g. in memory) and read by
MapServer to create the map. Other attribute or tabular data may also be required, but the focus of this guide is
coordinate data.
One important distinction between databases must be made. The databases discuss here are spatial databases, those
which can hold geographic data in its own data type. This is opposed to strictly tabular databases which cannot hold
geographic coordinates in the same way. It is possible to store some very simple coordinate data in regular tables, but
for anything but the most simple use a spatial database is required. There are spatial extensions to many databases
(Open Source and commercial). One of the most robust is the PostGIS extension to the PostgreSQL database. This
database not only allows the storage of geographic data, but also allows the manipulation of that data using SQL
commands. The other Open Source database with spatial capabilities is MySQL.
7.1. Data Input
418
MapServer Documentation, Release 7.0.6
Connections to databases usually consist of the following pieces of connection information:
Host - Directions to the server or computer hosting the database.
Database name - The name of the database you wish to access that is running on the host.
User name / passwords - Access privileges are usually restricted by user.
Note: Some databases (e.g. Oracle) use a name service identifier that includes both the host and database names.
Access to specific pieces of coordinate data usually require:
Table/View name - The name of the table or view holding the coordinate data.
Geographic column name - Where the geometry or coordinates are stored.
ArcInfo
ESRI ArcInfo Coverage Files are also known as simply as Coverages and less commonly as ADF files.
File listing
Coverages are made up of a set of files within a folder. The folder itself is the coverage name. The files roughly
represent different layers, usually representing different types of topology or feature types.
> ls /data/coverage/brazil
aat.adf arc.adf arx.adf bnd.adf
lab.adf
prj.adf
tic.adf
tol.adf
A folder with the name INFO is also part of the coverage. It sits at the same hierarchical level as the coverage folder
itself. Therefore, to copy a coverage (using regular file system tools) the coverage folder and the INFO folder must
both be copied. The INFO folder holds some catalogue information about the coverage.
> ls /data/coverage/info
arc0000.dat arc0001.dat
arc0000.nit arc0001.nit
arc0002.dat
arc0002.nit
arc.dir
Data Access / Connection Method
• CONNECTIONTYPE OGR must be used. The ability to use coverages is not built into MapServer.
• The path to the coverage folder name is required.
• The layer name (feature type) is specified in the DATA parameter
OGRINFO Examples
The directory is the data source. Layers are found within the directory. Using ogrinfo on a coverage directory:
> ogrinfo /data/coverage/brazil -summary
INFO: Open of `brazil'
using driver `AVCBin' successful.
1: ARC (Line String)
2: CNT (Point)
7.1. Data Input
419
MapServer Documentation, Release 7.0.6
3: LAB (Point)
4: PAL (Polygon)
Using ogrinfo to examine the structure of a layer:
> ogrinfo /data/coverage/brazil PAL -summary
Had to open data source read-only.
INFO: Open of `brazil'
using driver `AVCBin' successful.
Layer name: PAL
Geometry: Polygon
Feature Count: 1
Extent: (1272793.274958, 795381.617050) - (1287078.382785, 807302.747284)
Layer SRS WKT:
(unknown)
ArcIds: IntegerList (0.0)
AREA: Real (18.5)
PERIMETER: Real (18.5)
F_OPER#: Integer (5.0)
F_OPER-ID: Integer (5.0)
OPER: String (2.0)
FCODE: String (10.0)
Map File Example:
LAYER
NAME Brazil_bounds
TYPE POLYGON
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "/data/coverage/brazil"
DATA "PAL"
CLASS
NAME "Brazil Admin Areas"
STYLE
OUTLINECOLOR 153 102 0
SIZE 2
END
END
END
ArcSDE
Warning: MapServer’s native SDE driver was removed for the MapServer 7.0 release (see discussion). SDE
support can still be accessed through the OGR driver.
Spatial Database Engine (SDE) is one of ESRI‘s products which enables spatial data to be stored, managed, and
quickly retrieved from leading commercial database management systems like Oracle, Microsoft SQL Server, Sybase,
IBM DB2, and Informix.
7.1. Data Input
420
MapServer Documentation, Release 7.0.6
Supported ArcSDE Operations
• Versioned queries (query geometry and attributes from a specified version)
• queryByAttributes (select geometry and attributes based on the values of an attribute)
• Limited join support for within-database tables</li>
• queryByRect (select geometry based on an extent)
• Projection on the fly
• SDE for Coverages (a read-only type of SDE for coverage, shapefile, and ArcStorm/ArcLibrarian repositories)
• SDE 8.1, 8.2, 8.3, 9.0, 9.1, and 9.2
• Linux, Windows, and Solaris (platforms that have SDE C API support)
Unsupported ArcSDE Operations
• queryByShape (pass in a shape with MapScript and use it for queries)
• Direct Connect (bypass SDE to connect directly to the database with the SDE C API)
How to make a connection to SDE:
• Install the SDE C API client libraries for your platform (preferably matched to the server version you are using,
ie 8.2 client -> 8.2 server, 8.3 client -> 8.3 server)
• Compile MapServer with SDE support MapServer Unix Compilation Howto for specific details)
• Define a LAYER block in a MapFile that uses SDE as the CONNECTIONTYPE
LAYER
NAME
states
TYPE
POLYGON
CONNECTION "sdemachine.iastate.edu,port:5151,sde,username,password"
CONNECTIONTYPE SDE
DATA "HOBU.STATES_LAYER,SHAPE,SDE.DEFAULT"
FILTER "where MYCOLUMN is not NULL"
PROCESSING "QUERYORDER=ATTRIBUTE" # <-- MapServer 4.10 and above
# Within database one-to-one join support
# MapServer 5.0 and above
PROCESSING "JOINTABLE=SDE_MASTER.GEOSERVWRITE.JOINTABLE"
# MapServer 5.0 and above
CLASSITEM "SDE_MASTER.GEOSERVWRITE.JOINTABLE.VAL"
# MapServer 5.0 and above
FILTER "SDE_MASTER.GEOSERVWRITE.JOINTABLE.AQ_TAG=SDE_MASTER.GEOSERVWRITE.
˓→JOINTESTLAYER.AQ_TAG"
# ObjectID column manipulation
# MapServer 5.0 and above
PROCESSING "OBJECTID=OBJECTID"
TEMPLATE '/where/the/template/file/is/located'
7.1. Data Input
421
MapServer Documentation, Release 7.0.6
CLASS
STYLE
SYMBOL 'circle'
SIZE 3
COLOR -1 -1 -1
OUTLINECOLOR 0 0 0
END
END
END
CONNECTION - Order is important!
• sdemachine.iastate.edu - The name of the machine you are connecting to. In some instances, this may need
to be the IP address of the machine rather than the name if the server running MapServer is not configured to
cascade DNS lookups
• port:5151 - The port number of SDE. The port: is important as SDE expects you to define the service in this
slot, and it can be other names like sde:oracle (for direct connect) or esri_sde (for systems with port 5151
defined as esri_sde in /etc/services)
• sde - The database username that the SDE server is using to connect to your database. It is often only important
for SDE setups that are connecting to Oracle (and even then, not so important). Just leave it as sde if you don’t
know what it should be.
• username - The username that will be connecting to SDE. This user must have been granted rights to select
the layer that you will be specifying in the DATA directive. You can use ArcCatalog or the SDE command-line
utilities to grant the appropriate rights to layers.
• password - Password of the user connecting to SDE. Case Sensitive.
DATA - Order is important!
• HOBU.STATES_LAYER - The layer name you are querying. This the full name of the table in which the layer
resides. If you are using Oracle or Microsoft SQL Server as the DB for SDE, the schema name must also be
supplied.
• SHAPE - The column that contains the geometry. SDE technically allows for storage of multiple geometry
types in the same layer, but in practice this isn’t desirable. Also, expect to have problems if there are invalid or
null geometries in the layer (or versions of the layer).
• SDE.DEFAULT - As of MapServer 4.2, you can query against a specific version of the layer. SDE supports multi-user editing with versions. If a layer has been Registered with the GeoDatabase and Registered
as Versioned (ArcGIS terms), MapServer can query against specified versions of those edits. If not specified,
SDE.DEFAULT will be used for all queries. Case Sensitive.
Note: The version parameter is located in a different spot than MapServer 4.2, which had it on the CONNECTION
string.
TEMPLATE
• /where/the/template/file/is/located - A template directive must be specified (can point to a dummy file) in order
for MapServer to be able to query attributes from SDE. If you are only going to be drawing layers, this directive
7.1. Data Input
422
MapServer Documentation, Release 7.0.6
is unnecessary and will slow down the query operations of SDE (especially for layers with lots of attribute
columns).
PROCESSING
• PROCESSING “QUERYORDER=ATTRIBUTE” - Allows you to force SDE to use the WHERE clause that
was defined in your FILTER statement first, without attempting to hit the spatial index. Only in very special
cases will you want to do this.
• PROCESSING “OBJECTID=OBJECTID” - If you are having trouble with the SDE driver detecting your
unique ID column, you can override it with this processing parameter. Doing so will also have a slight performance benefit because it will save a couple of extra queries to the database.
• PROCESSING “ATTRIBUTE_QUALIFIED=TRUE” - User can set this option to always use fully qualified
attribute names.
Within-database Join Support
MapServer’s SDE driver, as of MapServer 5.0, allows you to join a single attribute table that has no geometries to
the layer that you are rendering. This feature allows you to use the data in the joined table much as you would in a
composite query that was made with something like PostGIS or Oracle Spatial. That is, the columns in the right table
of the join are available for CLASSITEM, LABELITEM and so on. The biggest constraint, however, is that fully
qualified names must be used or it most likely will not work. The join support is activated through PROCESSING
options.
• PROCESSING “JOINTABLE=SDE_MASTER.GEOSERVWRITE.JOINTABLE” - The JOINTABLE
processing option tells the driver which table you are joining the current layer to.
• CLASSITEM “SDE_MASTER.GEOSERVWRITE.JOINTABLE.VAL” - A CLASSITEM or LABELITEM
for a joined table using this mechanism must be fully qualified.
• FILTER “SDE_MASTER.GEOSERVWRITE.JOINTABLE.AQ_TAG=SDE_MASTER.GEOSERVWRITE.JOINTESTLA
- An important part of the join is defining how the join is to be made. Use a FILTER to do so.
Contour
1. Overview
MapServer can compute and render a contour layer on the fly from a raster source. The raster source is one band
of raster data, which represents a digital elevation model (DEM). More info about DEMs at: http://en.wikipedia.org/
wiki/Digital_elevation_model
2. How it works
CONNECTIONTYPE CONTOUR. The new type is a hybrid layer, which has a raster data source as input and vector
features as output. Initially, only the line representation of those vector features will be supported.
Since the internal layer is of type vector, queries will be supported and operate on the vectors (not on the raw raster
source). In the future we might see a need to add a query mode that queries the raster source, but this is not included
in this phase of work.
To render a contour layer, we need to define a layer in the mapfile with the following options:
• Set the layer TYPE to LINE.
7.1. Data Input
423
MapServer Documentation, Release 7.0.6
• Set CONNECTIONTYPE to CONTOUR.
• Set the DATA to the raster file that contains the elevation band. Starting with MapServer 7.0.1, a TILEINDEX
can also be used, together with WMS Time to specify which raster of the tileindex must be used.
• Specify the band to use as elevation using PROCESSING “BANDS”, same as regular raster.
• Specify one or more classes and styles to render the line features.
PROCESSING settings:
These options should be specified at layer level:
• CONTOUR_INTERVAL: elevation interval between contours
• CONTOUR_LEVELS: comma-separated list of one or more ‘fixed levels’ to extract
• CONTOUR_ITEM: provides a name for the item (attribute) in which to put the elevation. (optional)
You can also provide explicit min/max scaledenom in the CONTOUR_iNTERVAL or CONTOUR_LEVELS values if you wish to use scale-dependent contour spacing. This is done by
adding an optional “miscaledenom,maxscaledenom:” prefix to the value or list of values. See
the example below.
Example of a simple layer definition:
LAYER NAME "my_contour_layer"
TYPE LINE
STATUS DEFAULT
CONNECTIONTYPE CONTOUR
DATA "/mnt/data/raster/grib/dem.grib"
PROCESSING "BANDS=1"
PROCESSING "CONTOUR_ITEM=elevation"
PROCESSING "CONTOUR_INTERVAL=10"
CLASS
STYLE
WIDTH 2
COLOR 255 0 0
END
END
Example of a layer definition with scale-dependent contour ranges:
LAYER NAME "my_contour_layer"
TYPE LINE
STATUS DEFAULT
CONNECTIONTYPE CONTOUR
DATA "/mnt/data/raster/grib/dem.grib"
PROCESSING "BANDS=1"
PROCESSING "CONTOUR_ITEM=elevation"
PROCESSING "CONTOUR_INTERVAL=0,25000:5" # interval of 5 for scales of 25000 or less
PROCESSING "CONTOUR_INTERVAL=25000,500000:10" # interval of 10 for scales in the
˓→25000 to 500000 range
PROCESSING "CONTOUR_LEVELS=500000,0:10,25,50,100" # explicit list of levels for
˓→scales of 500000 and up
LABELITEM "elevation"
CLASS
STYLE
WIDTH 2
COLOR 255 0 0
END
LABEL
7.1. Data Input
424
MapServer Documentation, Release 7.0.6
...
END
END
Example of a layer definition with a tile index and WMS TIME support:
LAYER NAME "my_contour_layer"
TYPE LINE
STATUS OFF
CONNECTIONTYPE CONTOUR
TILEINDEX "data/contour_ti.shp"
TILEITEM "location"
PROCESSING "BANDS=1"
PROCESSING "CONTOUR_ITEM=elevation"
PROCESSING "CONTOUR_INTERVAL=20"
CLASS
STYLE
WIDTH 1
COLOR 255 0 0
END # STYLE
END # CLASS
METADATA
"DESCRIPTION" "contour"
"wms_title" "contour"
"wms_timeitem" "TIME"
"wms_timeextent" "2004-01-01/2004-02-01"
END # METADATA
END # LAYER
2.1 Data cellsize
The data produced by the gdal contour algorithm are generally in high resolution. A lot of point are used to generated
contours with precision. You might want to generalize/simplify the line in some cases (ie. Shape Smoothing). The
[data_cellsize] attribute binding represents the cellsize of the extend fetched from the raster file. This is different than
the map cellsize.
In the following example, I generalize my shape with a tolerance of 25% of the data cellsize to produce smooth
contours at all scales:
LAYER
NAME "MyContourLayer"
STATUS DEFAULT
DATA "wind.tif"
TYPE LINE
CONNECTIONTYPE CONTOUR
PROJECTION AUTO END
PROCESSING "BANDS=1"
PROCESSING "CONTOUR_ITEM=elevation"
PROCESSING "CONTOUR_INTERVAL=0,0:1"
GEOMTRANSFORM (smoothsia(generalize([shape], 0.25*[data_cellsize])))
CLASS
EXPRESSION ([elevation] >= 0)
STYLE
COLOR 0 0 255
END # STYLE
7.1. Data Input
425
MapServer Documentation, Release 7.0.6
END # CLASS
END # LAYER
DGN
File listing
Data are encapsulated in a single file, usually with the suffix .dgn.
0824t.dgn
Data Access / Connection Method
• Access is available in MapServer through OGR.
• The CONNECTIONTYPE OGR parameter must be used.
• The path to the dgn file is required, file extension is needed.
• All types of features in a DGN file are held in one “layer” of data. The layer is called elements and is the first
and only layer.
• The type of feature to be read from the DGN depends on the TYPE parameter in the map file.
• DGN files typically contain POINT, LINE, POLYGON and ANNOTATION feature types.
• DGN files contain “styling” information - how to color and present the data. This is used, optionally, by specifying the STYLEITEM “AUTO” parameter.
Note: DGN files typically use white as a color for their features and therefore are not visible on maps with white
backgrounds.
OGRINFO Examples
Using ogrinfo on a single DGN file:
> ogrinfo /data/dgn/0824t.dgn
Had to open data source read-only.
INFO: Open of `0842t.dgn'
using driver `DGN' successful.
1: elements
Note: No geometry/feature type for the layer is identified because it can be multiple types.
DGN files are not really GIS data files. They evolved from drafting formats used by computer aided drafting/design
(CADD) programs.
They carry a few key attributes which are usually consistent across all DGN files. Most of the attributes relate to
graphical styling of features for map presentation, such as ColorIndex, Style, etc.
Spatial reference system information is not always encoded into DGN files. This can be a major problem when trying
to adequately reference the DGN data in another mapping program.
7.1. Data Input
426
MapServer Documentation, Release 7.0.6
Measurement units can be a problem. In some cases the features could be located in kilometers or feet even though
it is not obvious from the output of ogrinfo. Sometimes the only way to identify or correct a problem with units is to
open the file in Microstation software.
Using ogrinfo to examine the structure of the file/layer:
> ogrinfo -summary /data/dgn/0824t.dgn elements
INFO: Open of '0824t.dgn'
using driver 'DGN' successful.
Layer name: elements
Geometry: Unknown (any)
Feature Count: 22685
Extent: (-513183.050000, 150292.930000) - (-224583.220000, 407463.360000)
Layer SRS WKT:
(unknown)
Type: Integer (2.0)
Level: Integer (2.0)
GraphicGroup: Integer (4.0)
ColorIndex: Integer (3.0)
Weight: Integer (2.0)
Style: Integer (1.0)
EntityNum: Integer (8.0)
MSLink: Integer (10.0)
Text: String (0.0)
Map File Example:
LAYER
NAME dgn
TYPE LINE
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "dgn/0824t.dgn"
STYLEITEM "AUTO"
CLASS
END
END # Layer
ESRI File Geodatabase
ESRI File Geodatabases exist in a file folder and offer improved performance and size limitations. For more information see the ESRI description page.
Note: Only file geodatabases created by AcrGIS 10.0 and above can be read by GDAL/MapServer.
File listing
File geodatabases are made up of a set of files within a folder. The files are made up of geographic data, attribute data,
index files, and lock files. A better description of the file contents can be found here.
7.1. Data Input
427
MapServer Documentation, Release 7.0.6
Data Access / Connection Method
File geodatabase access is available through OGR. See the OGR driver page for specific driver information. The driver
is available for GDAL >= 1.9.0.
The CONNECTION parameter must be used to point to the name of the file folder, and the DATA parameter should
be the name of the spatial table (or OGR layer).
CONNECTIONTYPE ogr
CONNECTION "filegdb-folder"
DATA "layername"
Note: The CONNECTION path is relative to the mapfile (SHAPEPATH is not used here). Full paths can also be
used.
OGRINFO Examples
First you should make sure that your GDAL/OGR build contains the file geodatabase “FileGDB” driver, by using the
‘–formats’ command:
>ogrinfo --formats
Supported Formats:
...
"FileGDB" (read/write)
"ESRI Shapefile" (read/write)
"MapInfo File" (read/write)
"UK .NTF" (readonly)
"SDTS" (readonly)
"TIGER" (read/write)
...
If you don’t have the driver, see GDAL’s BuildHints page for compiling the driver.
Once you have the FileGDB driver you are ready to try an ogrinfo command on your database to get a list of spatial
tables. In the example below our folder is named us_states.gdb:
ogrinfo us_states.gdb
INFO: Open of `us_states.gdb'
using driver `FileGDB' successful.
1: statesp020 (Multi Polygon)
Now use ogrinfo to get information on the structure of the statesp020 table:
ogrinfo us_states.gdb statesp020 -summary
INFO: Open of `us_states.gdb'
using driver `FileGDB' successful.
Layer name: statesp020
Geometry: Multi Polygon
Feature Count: 2895
Extent: (-179.000000, 17.000000) - (179.000000, 71.000000)
Layer SRS WKT:
GEOGCS["GCS_North_American_1983",
DATUM["North_American_Datum_1983",
SPHEROID["GRS_1980",6378137.0,298.257222101]],
7.1. Data Input
428
MapServer Documentation, Release 7.0.6
PRIMEM["Greenwich",0.0],
UNIT["Degree",0.017453292519943295]]
FID Column = OBJECTID
Geometry Column = SHAPE
AREA: Real (0.0)
PERIMETER: Real (0.0)
STATESP020: Real (0.0)
STATE: String (0.0)
STATE_FIPS: String (0.0)
Mapfile Example
LAYER
NAME "fgdb_poly"
TYPE POLYGON
STATUS ON
CONNECTIONTYPE OGR
CONNECTION "../data/filegdb/us_states.gdb"
DATA "statesp020"
LABELITEM "STATE"
CLASS
NAME "US States"
STYLE
COLOR 120 120 120
OUTLINECOLOR 0 0 0
END
LABEL
COLOR 255 255 255
OUTLINECOLOR 0 0 0
END
END
END
ESRI Personal Geodatabase (MDB)
ESRI Personal Geodatabases are basically Microsoft Access files that contain spatial information. For more information see the ESRI description page.
File listing
Similar to other database formats, the mdb file consists of several tables. The geometry is held in a BLOB table
column.
Data Access / Connection Method
Personal geodatabase access is available through OGR. See the OGR driver page for specific driver information. The
driver is standard in any win32 build of GDAL/OGR version 1.3.2 or later. For Linux/Unix, MDBTools ODBC drivers
can be used for this (with some difficulty).
OGR uses the names of spatial tables within the personal geodatabase (tables with a Shape column) as layers.
7.1. Data Input
429
MapServer Documentation, Release 7.0.6
The CONNECTION parameter must include the mdb extension, and the DATA parameter should be the name of the
spatial table (or OGR layer).
CONNECTIONTYPE ogr
CONNECTION "pgeodatabase.mdb"
DATA "layername"
OGRINFO Examples
First you should make sure that your GDAL/OGR build contains the personal geodatabase “PGeo” driver, by using
the ‘–formats’ command:
>ogrinfo --formats
Loaded OGR Format Drivers:
...
-> "ODBC" (read/write)
-> "PGeo" (readonly)
-> "PostgreSQL" (read/write)
...
If you don’t have the driver, you might want to try the FWTools or MS4W packages, which include the driver.
Once you have the PGeo driver you are ready to try an ogrinfo command on your database to get a list of spatial tables:
>ogrinfo test.mdb
INFO: Open of `test.mdb'
using driver `PGeo' successful.
1: counties
Now use ogrinfo to get information on the structure of the spatial table:
>ogrinfo test.mdb counties -summary
INFO: Open of `test.mdb'
using driver `PGeo' successful.
Layer name: counties
Geometry: Unknown (any)
Feature Count: 67
Extent: (-87.634943, 24.543945) - (-80.031369, 31.000975)
Layer SRS WKT:
GEOGCS["GCS_WGS_1984",
DATUM["WGS_1984",
SPHEROID["WGS_1984",6378137.0,298.257223563]],
PRIMEM["Greenwich",0.0],
UNIT["Degree",0.0174532925199433]]
OBJECTID_1: Integer (10.0)
OBJECTID: Integer (10.0)
NAME: String (32.0)
STATE_NAME: String (25.0)
STATE_FIPS: String (2.0)
CNTY_FIPS: String (3.0)
FIPS: String (5.0)
...
Note that you can also use an ODBC connection to access all of the tables in your geodatabase:
7.1. Data Input
430
MapServer Documentation, Release 7.0.6
>ogrinfo PGeo:testDSN counties -summary
INFO: Open of `testDSN'
using driver `PGeo' successful.
1: counties
2: counties_Shape_Index
...
(where “testDSN” is the name of your System DSN)
Mapfile Example
Direct Access to MDB
LAYER
NAME my_geodatabase
TYPE POLYGON
CONNECTIONTYPE ogr
CONNECTION "test.mdb"
DATA "counties"
STATUS ON
CLASS
NAME "counties"
STYLE
COLOR 255 255 120
END
END
END
Through an ODBC Connection
LAYER
NAME my_geodatabase
TYPE POLYGON
CONNECTIONTYPE ogr
CONNECTION "PGeo:testDSN"
DATA "counties"
STATUS ON
CLASS
NAME "counties"
STYLE
COLOR 255 255 120
END
END
END
ESRI Shapefiles (SHP)
Also known as ESRI ArcView Shapefiles or ESRI Shapefiles. ESRI is the company that introduced this format.
ArcView was the first product to use shapefiles.
7.1. Data Input
431
MapServer Documentation, Release 7.0.6
File listing
Shapefiles are made up of a minimum of three similarly named files, with different suffixes:
Countries_area.dbf
Countries_area.shp
Countries_area.shx
Data Access / Connection Method
Shapefile access is built directly into MapServer. It is also available through OGR, but direct access without OGR
is recommended and discussed here. The path to the shapefile is required. No file extension should be specified.
Shapefiles only hold one layer of data, therefore no distinction needs to be made.
OGRINFO Examples
• The directory can serve as a data source.
• Each shapefile in a directory serves as a layer.
• A shapefile can also be a data source. In this case the layer has the same prefix as the shapefile.
Using ogrinfo on a directory with multiple shapefiles:
> ogrinfo /data/shapefiles/
INFO: Open of `/data/shapefiles/'
using driver `ESRI Shapefile' successful.
1: wpg_h2o (Line String)
2: wpg_roads (Line String)
3: wpg_roads_dis (Line String)
4: wpgrestaurants (Point)
Using ogrinfo on a single shapefile:
> ogrinfo /data/shapefiles/Countries_area.shp
Had to open data source read-only.
INFO: Open of `Countries_area.shp'
using driver `ESRI Shapefile' successful.
1: Countries_area (Polygon)
Using ogrinfo to examine the structure of the file/layer:
> ogrinfo -summary /data/shapefiles/Countries_area.shp Countries_area
Had to open data source read-only.
INFO: Open of `Countries_area.shp'
using driver `ESRI Shapefile' successful.
Layer name: Countries_area
Geometry: Polygon
Feature Count: 27458
Extent: (-180.000000, -90.000000) - (180.000000, 83.627419)
Layer SRS WKT:
(unknown)
FAC_ID: Integer (5.0)
TILE: Integer (3.0)
ARCLIST: String (254.0)
7.1. Data Input
432
MapServer Documentation, Release 7.0.6
NAM: String (77.0)
PERIMETER: Real (22.17)
POLYGONCOU: Integer (6.0)
NA2DESC: String (45.0)
Map File Example:
LAYER
NAME my_shapefile
TYPE POLYGON
DATA countries_area
STATUS OFF
CLASS
NAME "Countries"
OUTLINECOLOR 0 0 0
END
END
GML
Also known as Geographic Markup Language and GML/XML. GML is a text-based, XML format that can represent
vector and attribute data. This is an Open Geospatial Consortium specification for data interchange. More information
is available at http://www.opengeospatial.org/standards/gml
File listing
GML files are usually a single text file with a GML filename extension. Some may use XML as the filename extension:
coal_dep.gml
XML schema documents often accompany GML files that have been translated from some other format (e.g. using
the ogr2ogr utility).
GML uses sets of nested tags to define attributes and geometry coordinates. Example of text in a GML file:
<gml:featureMember>
<Coal_Deposits fid="1">
<UNKNOWN>0.000</UNKNOWN>
<NA>0.000</NA>
<ID>2</ID>
<ID2>2</ID2>
<MARK>7</MARK>
<COALKEY>110</COALKEY>
<COALKEY2>110</COALKEY2>
<ogr:geometryProperty>
<gml:Point>
<gml:coordinates>78.531,50.694</gml:coordinates>
</gml:Point>
</ogr:geometryProperty>
</Coal_Deposits>
</gml:featureMember>
7.1. Data Input
433
MapServer Documentation, Release 7.0.6
Data Access / Connection Method
• GML access is available in MapServer through OGR. More information on OGR GML support is available at
http://www.gdal.org/ogr/drv_gml.html
• The CONNECTIONTYPE OGR parameter must be used.
• The path to the GML file is required, including file extension. There can be multiple layers in a GML file,
including multiple feature types.
OGRINFO Examples
Using ogrinfo on a single GML file:
> ogrinfo /data/gml/coal_dep.gml
Had to open data source read-only.
INFO: Open of `coal_dep.gml'
using driver `GML' successful.
1: Coal_Deposits
Using ogrinfo to examine the structure of one layer:
> ogrinfo -summary /data/gml/coal_dep.gml Coal_Deposits
Had to open data source read-only.
INFO: Open of `coal_dep.gml'
using driver `GML' successful.
Layer name: Coal_Deposits
Geometry: Unknown (any)
Feature Count: 266
Extent: (23.293650, 37.986340) - (179.272550, 80.969670)
Layer SRS WKT:
(unknown)
UNKNOWN: Real (0.0)
NA: Real (0.0)
ID: Integer (0.0)
ID2: Integer (0.0)
MARK: Integer (0.0)
COALKEY: Integer (0.0)
COALKEY2: Integer (0.0)
LONG: Real (0.0)
LAT: Real (0.0)
Map File Example:
LAYER
NAME coal_deposits
TYPE POINT
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "gml/coal_dep.gml"
CLASS
STYLE
COLOR 0 0 0
SYMBOL 'circle'
SIZE 6
END
7.1. Data Input
434
MapServer Documentation, Release 7.0.6
END
END
GPS Exchange Format (GPX)
GPX (the GPS Exchange Format) is a light-weight XML data format containing GPS data (waypoints, routes, and
tracks). For more information see the official GPX site.
File listing
All waypoints, routes, and tracks are stored in a single .gpx file.
Data Access / Connection Method
• GPX access is available through OGR. See the OGR driver page for specific driver information.
• A relative path to the .gpx file can be used in the mapfile LAYER’s CONNECTION string.
• The feature type is specified in the DATA parameter
– the “tracks” feature type will usually be the track line
– the “track_points” feature type will usually be the points that make up the track line
OGRINFO Examples
First you should make sure that your GDAL/OGR build contains the “GPX” driver, by using the ‘–formats’ command:
>ogrinfo --formats
Loaded OGR Format Drivers:
...
-> "CSV" (read/write)
-> "GML" (read/write)
-> "GPX" (read/write)
-> "KML" (read/write)
...
If you don’t have the driver, you might want to try the FWTools or MS4W packages, which include the driver.
Once you have the GPX driver you are ready to try an ogrinfo command on your file to get a list of feature types:
>ogrinfo test.gpx
INFO: Open of `test.gpx'
using driver `GPX' successful.
1: waypoints (Point)
2: routes (Line String)
3: tracks (Multi Line String)
4: route_points (Point)
5: track_points (Point)
Now use ogrinfo to get information on one of the feature types:
7.1. Data Input
435
MapServer Documentation, Release 7.0.6
>ogrinfo test.gpx track_points -summary
INFO: Open of `test.gpx'
using driver `GPX' successful.
Layer name: track_points
Geometry: Point
Feature Count: 661
Extent: (-66.694270, 47.985570) - (-66.675222, 47.990791)
Layer SRS WKT:
GEOGCS["WGS 84",
DATUM["WGS_1984",
SPHEROID["WGS 84",6378137,298.257223563,
AUTHORITY["EPSG","7030"]],
AUTHORITY["EPSG","6326"]],
PRIMEM["Greenwich",0,
AUTHORITY["EPSG","8901"]],
UNIT["degree",0.01745329251994328,
AUTHORITY["EPSG","9122"]],
AUTHORITY["EPSG","4326"]]
track_fid: Integer (0.0)
track_seg_id: Integer (0.0)
track_seg_point_id: Integer (0.0)
ele: Real (0.0)
time: DateTime (0.0)
magvar: Real (0.0)
geoidheight: Real (0.0)
name: String (0.0)
cmt: String (0.0)
desc: String (0.0)
src: String (0.0)
...
Mapfile Example
Since you have confirmed that OGR can read your GPX file, now you can create a MapServer layer:
LAYER
NAME gpx
TYPE POINT
STATUS ON
CONNECTIONTYPE OGR
CONNECTION test.gpx
DATA "track_points"
CLASS
NAME "gpx"
STYLE
SYMBOL 'circle'
COLOR 0 119 255
SIZE 2
END
END
END # layer
7.1. Data Input
436
MapServer Documentation, Release 7.0.6
Inline
Inline features refer to coordinates entered directly into the map file. They are not a file or database format and do not
require any DATA or CONNECTION parameters. Instead they use a FEATURE section to define the coordinates.
Inline features can be used to define points, lines and polygons as if taken from an external file. This requires direct
entry of coordinate pairs in the map file using a particular syntax.
Data Access / Connection Method
This is a native MapServer option that doesn’t use any external libraries to support it.
Map File Example
Points
• Each FEATURE..END section defines a feature.
• Multiple points can be defined in a FEATURE section. If multiple points are defined in the same layer, they will
have the same CLASS settings, e.g. for colours and styles.
• Coordinates are entered in the units set in the layer’s projection. In this case it is assuming the map file projection
is using decimal degrees.
LAYER
NAME inline_stops
TYPE POINT
STATUS DEFAULT
FEATURE
POINTS
72.36 33.82
END
TEXT "My House"
END
FEATURE
POINTS
69.43 35.15
71.21 37.95
72.02 38.60
END
TEXT "My Stores"
END
CLASS
STYLE
COLOR 0 0 250
SYMBOL 'circle'
SIZE 6
END
END
END
Lines
Lines are simply a list of points strung together, but the layer must be TYPE LINE instead of TYPE POINT.
7.1. Data Input
437
MapServer Documentation, Release 7.0.6
LAYER
NAME inline_track
TYPE LINE
STATUS DEFAULT
MAXSCALE 10000000
FEATURE
POINTS
72.36 33.82
70.85 34.32
69.43 35.15
70.82 36.08
70.90 37.05
71.21 37.95
END
END
CLASS
STYLE
COLOR 255 10 0
SYMBOL 'circle'
SIZE 2
END
END
END
Polygons
Polygons are the same as the line example, just a list of points. They require the TYPE POLYGON parameter.
Polygons also require the final coordinate pair to be the same as the first, making it a closed polygon.
KML - Keyhole Markup Language
Table of Contents
• KML - Keyhole Markup Language
– Links to KML-Related Information
– Data Access / Connection Method
– Example 1: Displaying a .KML file
– Example 2: Displaying a .KMZ file
– Example 3: Displaying a “Superoverlay” KML file
Keyhole Markup Language (KML) is an XML-based language for managing the display of 3D geospatial data. KML
is a standard maintained by the Open Geospatial Consoritum (OGC).
Links to KML-Related Information
• Google’s KML Reference
• OGC’s KML Specification
7.1. Data Input
438
MapServer Documentation, Release 7.0.6
• KML Validator
• KML Validator (against OGC KML 2.2)
Data Access / Connection Method
KML access in MapServer is available through OGR. See the OGR driver page for specific driver information. Read
support was initially added to GDAL/OGR version 1.5.0. A more complete KML reader was added to GDAL/OGR in
version 1.8.0, through the libKML driver (including the ability to read multigeometry, and KMZ files).
The CONNECTION parameter must include the kml or kmz extension, and the DATA parameter should be the name
of the layer.
CONNECTIONTYPE OGR
CONNECTION "filename.kml"
DATA "layername"
Example 1: Displaying a .KML file
OGRINFO
First you should make sure that your GDAL/OGR build contains the “KML” driver, by using the ‘–formats’ command:
>ogrinfo --formats
Loaded OGR Format Drivers:
...
-> "GML" (read/write)
-> "GPX" (read/write)
-> "KML" (read/write)
...
If you don’t have the driver, you might want to try the FWTools or MS4W packages, which include the driver.
Once you have the KML driver you are ready to try an ogrinfo command on your file to get a list of available layers:
>ogrinfo myplaces.kml
INFO: Open of `myplaces.kml'
using driver `KML' successful.
1: Layer #0 (Point)
Now use ogrinfo to get information on the structure of the layer:
>ogrinfo fountains-hotel.kml "Layer #0" -summary
Had to open data source read-only.
INFO: Open of `fountains-hotel.kml'
using driver `KML' successful.
Layer name: Layer #0
Geometry: Point
Feature Count: 1
Extent: (18.424930, -33.919627) - (18.424930, -33.919627)
Layer SRS WKT:
GEOGCS["WGS 84",
DATUM["WGS_1984",
SPHEROID["WGS 84",6378137,298.257223563,
AUTHORITY["EPSG","7030"]],
7.1. Data Input
439
MapServer Documentation, Release 7.0.6
AUTHORITY["EPSG","6326"]],
PRIMEM["Greenwich",0,
AUTHORITY["EPSG","8901"]],
UNIT["degree",0.01745329251994328,
AUTHORITY["EPSG","9122"]],
AUTHORITY["EPSG","4326"]]
Name: String (0.0)
Description: String (0.0)
Mapfile Example
LAYER
NAME "kml_example"
TYPE POINT
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "kml/fountains-hotel.kml"
DATA "Layer #0"
LABELITEM "NAME"
CLASS
NAME "My Places"
STYLE
COLOR 250 0 0
OUTLINECOLOR 255 255 255
SYMBOL 'circle'
SIZE 6
END
LABEL
SIZE TINY
COLOR 0 0 0
OUTLINECOLOR 255 255 255
POSITION AUTO
END
END
END
Example 2: Displaying a .KMZ file
OGRINFO
First you should make sure that your GDAL/OGR build contains the “LIBKML” driver, by using the ‘–formats’
command:
>ogrinfo --formats
Loaded OGR Format Drivers:
...
-> "GML" (read/write)
-> "GPX" (read/write)
-> "LIBKML" (read/write)
-> "KML" (read/write)
...
7.1. Data Input
440
MapServer Documentation, Release 7.0.6
If you don’t have the driver, you might want to try the FWTools or MS4W packages, which include the driver. Or you
can follow the compiling notes for libKML and GDAL/OGR.
Once you have the LIBKML driver you are ready to try an ogrinfo command on your file to get a list of available
layers:
>ogrinfo Lunenburg_Municipality.kmz
INFO: Open of `Lunenburg_Municipality.kmz'
using driver `LIBKML' successful.
1: Lunenburg_Municipality
Now use ogrinfo to get information on the structure of the layer:
>ogrinfo Lunenburg_Municipality.kmz Lunenburg_Municipality -summary
INFO: Open of `Lunenburg_Municipality.kmz'
using driver `LIBKML' successful.
Layer name: Lunenburg_Municipality
Geometry: Unknown (any)
Feature Count: 1
Extent: (-64.946433, 44.133207) - (-64.230281, 44.735125)
Layer SRS WKT:
GEOGCS["WGS 84",
DATUM["WGS_1984",
SPHEROID["WGS 84",6378137,298.257223563,
AUTHORITY["EPSG","7030"]],
TOWGS84[0,0,0,0,0,0,0],
AUTHORITY["EPSG","6326"]],
PRIMEM["Greenwich",0,
AUTHORITY["EPSG","8901"]],
UNIT["degree",0.0174532925199433,
AUTHORITY["EPSG","9108"]],
AUTHORITY["EPSG","4326"]]
Name: String (0.0)
description: String (0.0)
timestamp: DateTime (0.0)
begin: DateTime (0.0)
end: DateTime (0.0)
altitudeMode: String (0.0)
tessellate: Integer (0.0)
extrude: Integer (0.0)
visibility: Integer (0.0)
Mapfile Example
LAYER
NAME "lunenburg"
TYPE POLYGON
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "Lunenburg_Municipality.kmz"
DATA "Lunenburg_Municipality"
CLASS
NAME "Lunenburg"
STYLE
COLOR 244 244 16
OUTLINECOLOR 199 199 199
7.1. Data Input
441
MapServer Documentation, Release 7.0.6
END
END
END # layer
Example 3: Displaying a “Superoverlay” KML file
A superoverlay is a KML file that contains tiled data, that is broken up into “regions”; this is an efficient way to display
large images. For more background on superoverlays see the Google Developers KML Tutorial.
MapServer can access superoverlays through GDAL.
Note: The following was tested with GDAL 2.0.2-dev on 2016-01-17; several enhancements to GDAL were made
when testing this superoverlay (see tickets 6310 and 6311).
GDALINFO
First you should make sure that your GDAL/OGR build contains the “KMLSUPEROVERLAY” driver, by using the
‘–formats’ command:
>gdalinfo --formats
Supported Formats:
...
R -raster- (rwv): R Object Data Store
MAP -raster- (rov): OziExplorer .MAP
KMLSUPEROVERLAY -raster- (rwv): Kml Super Overlay
PDF -raster,vector- (rw+vs): Geospatial PDF
...
If you don’t have the driver, you might want to check if your platform has a ready-to-use package/installer (Windows
users please see MS4W), which include the driver.
Note: For this example, we will use the remote KML file referenced in the Google Developers Tutorial (http://mw1.
google.com/mw-earth-vectordb/kml-samples/mv-doqq.kml). We will also access this remote file directly through
vsicurl, which has been available in GDAL since 1.8.0
Now use gdalinfo to get information on the structure of the layer:
>gdalinfo /vsicurl/http://mw1.google.com/mw-earth-vectordb/kml-samples/mv-doqq.kml
Driver: KMLSUPEROVERLAY/Kml Super Overlay
Files: none associated
Size is 16384, 16384
Coordinate System is:
GEOGCS["WGS 84",
DATUM["WGS_1984",
SPHEROID["WGS 84",6378137,298.257223563,
AUTHORITY["EPSG","7030"]],
AUTHORITY["EPSG","6326"]],
PRIMEM["Greenwich",0,
AUTHORITY["EPSG","8901"]],
UNIT["degree",0.0174532925199433,
7.1. Data Input
442
MapServer Documentation, Release 7.0.6
AUTHORITY["EPSG","9122"]],
AUTHORITY["EPSG","4326"]]
Origin = (-122.129312658577720,37.439803353779496)
Pixel Size = (0.000004270647777,-0.000004095141704)
Metadata:
DESCRIPTION=The original is a 7008 x 6720 DOQQ of Mountain View in 1991. (Source:
http://gis.ca.gov/). This is a Region NetworkLink hierarchy of 900+
GroundOverlays each of 256 x 256 pixels arranged in a hierarchy such
that more detailed images are loaded and shown as the viewpoint nears.
Enable the "Boxes" NetworkLink to see a LineString for
each Region. Tour the "Boxes" to visit each tile. Visit the
"A" and "B" Placemarks to see multiple levels of
hierarchy together. Use the slider on various images in the hierarchy
to see how the resolution varies and of the entire hierarchy to see
the imagery below. (Find the Google Campus...).
NAME=SuperOverlay: MV DOQQ
Image Structure Metadata:
INTERLEAVE=PIXEL
Corner Coordinates:
Upper Left (-122.1293127, 37.4398034) (122d 7'45.53"W, 37d26'23.29"N)
Lower Left (-122.1293127, 37.3727086) (122d 7'45.53"W, 37d22'21.75"N)
Upper Right (-122.0593424, 37.4398034) (122d 3'33.63"W, 37d26'23.29"N)
Lower Right (-122.0593424, 37.3727086) (122d 3'33.63"W, 37d22'21.75"N)
Center
(-122.0943275, 37.4062560) (122d 5'39.58"W, 37d24'22.52"N)
Band 1 Block=256x256 Type=Byte, ColorInterp=Red
Overviews: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
Mask Flags: PER_DATASET ALPHA
Overviews of mask band: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
Band 2 Block=256x256 Type=Byte, ColorInterp=Green
Overviews: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
Mask Flags: PER_DATASET ALPHA
Overviews of mask band: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
Band 3 Block=256x256 Type=Byte, ColorInterp=Blue
Overviews: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
Mask Flags: PER_DATASET ALPHA
Overviews of mask band: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
Band 4 Block=256x256 Type=Byte, ColorInterp=Alpha
Overviews: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
Mapfile Example
Finally, access the superoverlay image through a MapServer layer with TYPE RASTER, as you would other rasters,
such as:
MAP
NAME "superoverlay"
STATUS ON
SIZE 400 300
EXTENT -122.1293127 37.3727086 -122.0593424 37.4398034
UNITS DD
IMAGECOLOR 255 255 255
LAYER
NAME "mountain-view-superoverlay"
TYPE RASTER
7.1. Data Input
443
MapServer Documentation, Release 7.0.6
STATUS ON
DATA "/vsicurl/http://mw1.google.com/mw-earth-vectordb/kml-samples/mv-doqq.kml"
CLASS
NAME "Superoverlay"
STYLE
END #style
END #class
END #layer
END #Map
Test Your Mapfile with the shp2img Command
The easiest way to test your superoverlay mapfile is with the MapServer shp2img utility.
>shp2img -m superoverlay-kml.map -o ttt.png -all_debug 3
msLoadMap(): 0.000s
msDrawMap(): rendering using outputformat named png (AGG/PNG).
msDrawMap(): WMS/WFS set-up and query, 0.000s
msDrawRasterLayerLow(mountain-view-superoverlay): entering.
msDrawRasterLayerGDAL(): Entering transform.
msDrawRasterLayerGDAL(): src=0,0,16384,16384, dst=44,0,312,300
msDrawRasterLayerGDAL(): source raster PL (-4.888,-27.409) for dst PL (44,0).
msDrawRasterLayerGDAL(): red,green,blue,alpha bands = 1,2,3,4
msDrawMap(): Layer 0 (mountain-view-superoverlay), 4.314s
msDrawMap(): Drawing Label Cache, 0.008s
msDrawMap() total time: 4.347s
msSaveImage(ttt.png) total time: 0.090s
shp2img total time: 4.441s
The following map image should be generated:
7.1. Data Input
444
MapServer Documentation, Release 7.0.6
MapInfo
File listing
The following files are also associated with .TAB files: .DAT, .ID, .MAP. An example is:
border.DAT
border.ID
border.MAP
border.TAB
The term MID/MIF refers to files with .MID and .MIF extension.
Data Access / Connection Method
TAB and MID/MIF access is available in MapServer through OGR.
• The CONNECTIONTYPE OGR parameter must be used.
• The path to the (*.tab or *.mif) file is required, and the file extension is needed.
• The path may be relative to the SHAPEPATH
• MapInfo files already contain styling information. This styling information can be used optionally by specifying
the STYLEITEM “AUTO” parameter in the LAYER object of the map file.
Note: If you use STYLEITEM “AUTO” you must have an empty class in the layer.
7.1. Data Input
445
MapServer Documentation, Release 7.0.6
OGRINFO Examples
Using ogrinfo on a single TAB file
> ogrinfo elev5_poly.TAB
Had to open data source read-only.
INFO: Open of `elev5_poly.TAB'
using driver `MapInfo File' successful.
1: elev5_poly (Polygon)
Using ogrinfo to examine the structure of the file/layer
> ogrinfo elev5_poly.TAB elev5_poly
Had to open data source read-only.
INFO: Open of `elev5_poly.TAB'
using driver `MapInfo File' successful.
Layer name: elev5_poly
Geometry: Polygon
Feature Count: 2236
Extent: (-141.000000, 60.000000) - (-124.403310, 69.300251)
Layer SRS WKT:
GEOGCS["unnamed",
DATUM["MIF 0",
SPHEROID["WGS 84 (MAPINFO Datum 0)",6378137.01,298.257223563],
TOWGS84[0,0,0,0,0,0,0]],
PRIMEM["Greenwich",0],
UNIT["degree",0.0174532925199433]]
AREA: Real (0.0)
PERIMETER: Real (0.0)
ELEV5_: Integer (0.0)
ELEV5_ID: Integer (0.0)
TYPE: Real (4.0)
ELEV5: Real (4.0)
...
Map File Example
LAYER
NAME Elevation_Poly_5
TYPE POLYGON
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "./hypso/elev5_poly.TAB"
STYLEITEM "AUTO"
CLASS
NAME "Elevation Poly 5"
END
END # Layer
MSSQL
Author Tamas Szekeres
Contact szekerest at gmail.com
7.1. Data Input
446
MapServer Documentation, Release 7.0.6
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2012-09-26
Contents
• MSSQL
– Introduction
– Creating Spatial Data Tables in MSSQL 2008
– Connecting to Spatial Data in MSSQL 2008
* OPTION 1: Connect Through OGR
· Verify Local Support for MSSQLSpatial
· Test OGR Connection Parameters
· Create MapServer Layer using CONNECTIONTYPE OGR
* OPTION 2: Connect Through MapServer Plugin
· Create MapServer Layer
· Selecting the Type of the Geometry Column
· Expected Location of the MSSQL Plugin
· Binaries Containing the MSSQL Plugin
* Using Spatial Indexes
* Layer Processing Options
– More Information
Introduction
Microsoft SQL Server 2008+ supports storing spatial data by using the built-in geometry/geography data types.
MapServer can connect to MSSQL through either: 1) an OGR connectiontype, or 2) a driver that accesses these
tables containing spatial columns, which is compiled as a plugin (“msplugin_mssql2008.dll”).
Creating Spatial Data Tables in MSSQL 2008
There are several ways to create spatial data tables in MSSQL 2008. You can easily upload existing data to an MSSQL
table by using the ogr2ogr commandline tool and the OGR’s MSSQL Spatial driver Here is an example that uploads a
shapefile (province.shp) into an MSSQL 2008 instance:
ogr2ogr -f MSSQLSpatial -a_srs EPSG:4326 "MSSQL:server=.\SQLEXPRESS;database=geo;
˓→trusted_connection=yes" province.shp
7.1. Data Input
447
MapServer Documentation, Release 7.0.6
Connecting to Spatial Data in MSSQL 2008
In order to connect to the MSSQL 2008 spatial database you should set up a valid connection string to the database
like the following examples:
Server=.\MSSQLSERVER2008;Database=Maps;Integrated Security=true
Server=55.55.55.55,1433;uid=a_user;pwd=a_password;database=a_database;
Integrated Security=True
Server=55.55.55.55\SQLEXPRESS,1433;uid=a_user;pwd=a_password;
database=a_database;Integrated Security=True
OPTION 1: Connect Through OGR
GDAL/OGR (and therefore MapServer) can read spatial tables in MSSQL 2008 through the MSSQLSpatial driver.
Verify Local Support for MSSQLSpatial
Use the command “ogrinfo –formats” to verify that your local GDAL is built with support for MSSQL; the response
should contain “MSSQLSpatial” such as:
Supported Formats:
-> "OCI" (read/write)
-> "ESRI Shapefile" (read/write)
-> "MapInfo File" (read/write)
...
-> "MSSQLSpatial" (read/write)
...
Test OGR Connection Parameters
Use the ogrinfo commandline utility to test your connection through the MSSQLSpatial driver, such as:
ogrinfo "MSSQL:server=.\SQLEXPRESS;database=geo;trusted_connection=yes" province ˓→summary
Create MapServer Layer using CONNECTIONTYPE OGR
Your layer should contain a CONNECTIONTYPE OGR statement, as well as a CONNECTION. The connection
should also contact a “tables=” parameter, and also the name of the geometry column in brackets. You do not need
to specify the DATA parameter unless you define an sql select statement starting with the ‘WHERE’ keyword. For
example:
LAYER
NAME "provinces"
TYPE POLYGON
STATUS ON
####
CONNECTIONTYPE OGR
7.1. Data Input
448
MapServer Documentation, Release 7.0.6
CONNECTION "MSSQL:server=.\SQLEXPRESS;uid=xx;pwd=xxx;database=geo;trusted_
connection=yes;tables=province(ogr_geometry)"
####
PROJECTION
"init=epsg:4326"
END
CLASS
NAME "Land"
STYLE
COLOR 240 240 240
OUTLINECOLOR 199 199 199
END
END
PROCESSING 'CLOSE_CONNECTION=DEFER'
END # layer
˓→
Note: The usual CONNECTIONTYPE terms ‘using unique’ and ‘using srid’ are not meaningful for the OGR driver
in this case, as these parameters are automatically retrieved from the ‘geometry_columns’ metadata table.
OPTION 2: Connect Through MapServer Plugin
Create MapServer Layer
Once the connection can be established to the server the layer can be configured to access MSSQL2008 as follows:
LAYER
NAME "rivers_mssql_spatial"
TYPE POLYGON
STATUS DEFAULT
CONNECTIONTYPE PLUGIN
PLUGIN "msplugin_mssql2008.dll"
CONNECTION "Server=.\MSSQLSERVER2008;Database=Maps;Integrated Security=true"
DATA "ogr_geometry from rivers USING UNIQUE ogr_fid USING SRID=4326"
...
END
The DATA parameter is used to perform the SQL select statement to access your table in MSSQL. The geometry
column is required in the select statement; in the above example the ogr_geometry column is the geometry column in
the rivers table. The table should also have an unique column (ogr_fid) which is provided for random access to the
features in the feature query operations.
The DATA section should also contain the spatial reference id (SRID) of the features in the data table The SRID is used
when specifying the search shapes during the intersect operations which should match with the SRID of the features
otherwise no features are returned in a particular query. if you omit specifying the SRID value in the DATA section
the diver will use SRID=0 when defining the search shapes.
Selecting the Type of the Geometry Column
For the geometry columns MSSQL supports 2 data types: “geometry” and “geography”. By default the driver considers the type of the geometry column is “geometry”. In case if the type of the geometry column is “geography” we
must specify the data type in the DATA section explicitly, like:
7.1. Data Input
449
MapServer Documentation, Release 7.0.6
DATA "ogr_geometry(geography) from rivers USING UNIQUE ogr_fid USING SRID=4326"
Expected Location of the MSSQL Plugin
On Windows platforms the DLLs needed by the program are searched for in the following order:
1. The directory from which the application loaded.
2. The current directory.
3. The system directory. Use the GetSystemDirectory function to get the path of this directory.
4. The 16-bit system directory.
5. The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.
6. The directories that are listed in the PATH environment variable.
Binaries Containing the MSSQL Plugin
Currently the following binary distributions contain msplugin_mssql2008.dll:
• GISInternals
• MS4W distributions
Using Spatial Indexes
In order to speed up the access to the features a spatial index should be created to the geometry column which could
easily be done with the OGR MSSQL Spatial driver like:
ogrinfo -sql "create spatial index on rivers"
"MSSQL:server=.\MSSQLSERVER2008;database=Maps;
Integrated Security=true"
In general we can safely rely on the query optimizer to select the most appropriate index in the sql query operations.
In some cases - however - we should force the optimizer to use the spatial index by specifying the index hint in the
DATA section like:
DATA "ogr_geometry from rivers using index ogr_geometry_sidx
USING UNIQUE ogr_fid USING SRID=4326"
Layer Processing Options
We can control the behaviour of the MSSQL driver by using the following PROCESSING options:
• CLOSE_CONNECTION=DEFER - This is where you can enable connection pooling for certain layer types.
Connection pooling will allow MapServer to share the handle to an open database or layer connection throughout
a single map draw process.
• MSSQL_READ_WKB=TRUE - Uses WKB (Well Known Binary) format instead of native format when fetching geometries.
7.1. Data Input
450
MapServer Documentation, Release 7.0.6
More Information
• OGR MSSQL Spatial driver page (describes the OGR MSSQL support)
• ogr2ogr application (describes the ogr2ogr commandline application)
• Vector Data (MapServer Vector Data Access Guide)
MySQL
Author David Fawcett
Contact david.fawcett at moea.state.mn.us
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2010-07-29
Contents
• MySQL
– Introduction
– Connecting to Spatial Data in MySQL
* Requirements
* Verify MySQL Support in OGR Build
* Test Connection with ogrinfo
* Create MapServer Layer
– Connecting to non-Spatial Data in MySQL
* Requirements
* Create .ovf file
* Test Connection with ogrinfo
* Create MapServer Layer
– More Information
Introduction
The following methods connect to MySQL through OGR’s MySQL driver, thus avoiding the need to set up an ODBC
connection.
Connecting to Spatial Data in MySQL
This section describes how to display a spatial MySQL table (meaning that the table has a column of type geometry)
in MapServer. OGR’s MySQL driver was expanded in OGR version 1.3.2 to support access to MySQL spatial tables.
7.1. Data Input
451
MapServer Documentation, Release 7.0.6
Requirements
• MapServer compiled with OGR support
• OGR/GDAL version 1.3.2 or more recent compiled with MySQL support
Verify MySQL Support in OGR Build
You can verify that your local build of OGR contains MySQL support by using the ogrinfo commandline utility, and
making sure that “MySQL” is returned:
ogrinfo --formats
Supported Formats:
-> "ESRI Shapefile" (read/write)
-> "MapInfo File" (read/write)
...
-> "PostgreSQL" (read/write)
-> "MySQL" (read/write)
...
Test Connection with ogrinfo
MySQL connection strings in OGR are in the following format:
MYSQL:database,host=yourhost,user=youruser,password=yourpass,tables=yourtable
Therefore an example ogrinfo command would be:
> ogrinfo MYSQL:test,user=root,password=mysql,port=3306
which should return a list of all of your tables in the ‘test’ database:
INFO: Open of `MYSQL:test,user=root,password=mysql,port=3306'
using driver `MySQL' successful.
1: province (Polygon)
and you can return a summary of the MySQL spatial layer:
> ogrinfo MYSQL:test,user=root,password=mysql,port=3306 province -summary
INFO: Open of `MYSQL:test,user=root,password=mysql,port=3306'
using driver `MySQL' successful.
Layer name: province
Geometry: Polygon
Feature Count: 48
Extent: (-13702.315770, 3973784.599548) - (1127752.921471, 4859616.714055)
Layer SRS WKT:
PROJCS["ED50_UTM_zone_30N",
...
FID Column = OGR_FID
Geometry Column = SHAPE
7.1. Data Input
452
MapServer Documentation, Release 7.0.6
id: Real (2.0)
...
Create MapServer Layer
LAYER
NAME "spain_provinces_mysql_spatial"
TYPE POLYGON
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "MySQL:test,user=root,password=mysql,port=3306"
DATA "SELECT SHAPE,admin_name from province"
LABELITEM "admin_name"
CLASS
NAME "Spain Provinces"
STYLE
COLOR 240 240 240
OUTLINECOLOR 199 199 199
END
LABEL
COLOR 0 0 0
FONT sans
TYPE truetype
SIZE 8
POSITION AUTO
PARTIALS FALSE
OUTLINECOLOR 255 255 255
END
END
END # layer
The DATA parameter is used to perform the SQL select statement to access your table in MySQL. The geometry
column is required in the select statement; in the above example the SHAPE column is the geometry column in the
province table.
Connecting to non-Spatial Data in MySQL
This section describes how to display a non-spatial MySQL table (meaning the table does not have a column of type
geometry) in MapServer.
Support for this functionality is found in GDAL/OGR 1.2.6 and older on Windows and GDAL/OGR 1.3.2 on Linux.
Requirements
• MySQL database containing a table with fields containing x and y coordinates
• .ovf file, a small xml file you will create
• MapServer compiled with OGR version supporting this functinality
Create .ovf file
Here is the .ovf file named aqidata.ovf
7.1. Data Input
453
MapServer Documentation, Release 7.0.6
<OGRVRTDataSource>
<OGRVRTLayer name="aqidata">
<SrcDataSource>MYSQL:aqiTest,user=uuuuu,password=ppppp,host=192.170.1.100,
˓→port=3306,tables=testdata</SrcDataSource>
<SrcSQL>SELECT areaID, x, y, sampleValue FROM testdata</SrcSQL>
<GeometryType>wkbPoint</GeometryType>
<GeometryField encoding="PointFromColumns" x="x" y="y"/>
</OGRVRTLayer>
</OGRVRTDataSource>
If you look at the connection string in <SrcDataSource>
• The MySQL database name is ‘aqiTest’
• ‘testdata’ is the table containing the coordinate data
• host and port are for MySQL server
Use the GeometryField element to tell OGR which fields store the x and y coordinate data. Mine are simply named x
and y.
Test Connection with ogrinfo
# usr/local/bin/ogrinfo /maps/aqidata.ovf
ogrinfo returns
ERROR 4: Update access not supported for VRT datasources.
Had to open data source read-only.
INFO: Open of `/maps/aqidata.ovf'
using driver `VRT' successful.
1: aqidata (Point)
Don’t worry about the error, this is just telling you that it is a read-only driver. If it really bugs you, call ogrinfo with
the -ro (read only) flag.
To see the actual data
# usr/local/bin/ogrinfo /maps/aqidata.ovf -al
Create MapServer Layer
LAYER
NAME "MyAqi"
STATUS DEFAULT
TYPE POINT
CONNECTIONTYPE OGR
CONNECTION "aqidata.ovf"
DATA "aqidata"
CLASS
NAME "MyClass"
STYLE
SYMBOL 'circle'
SIZE 15
COLOR 0 255 0
7.1. Data Input
454
MapServer Documentation, Release 7.0.6
END
END
END
DATA in the LAYER definition should be the same as the name attribute of the OGRVRTLayer element in the ovf file.
For this to draw, you need to have a SYMBOLSET defined in your mapfile and have a symbol called ‘circle’ in your
symbols.sym file.
More Information
• OGR (MapServer OGR document)
• Vector Data (MapServer Vector Data Access Guide)
• MySQL wiki page (describes the deprecated mygis support)
NTF
NTF files are mostly used by the United Kingdom Ordnance Survey (OS). For more on the Ordnance Survey, see their
website at: http://www.ordnancesurvey.co.uk/oswebsite/
File listing
NTF files have an NTF extension.
Data Access / Connection Method
• NTF access requires OGR.
• The path to the NTF file is required in the CONNECTION string. It may be relative to the SHAPEPATH setting
in the map file or the full path.
• The DATA parameter is used to specify the layer to use
OGRINFO Examples
Using ogrinfo on an NTF file to retrieve layer names:
> ogrinfo llcontours.ntf
ERROR 4: NTF Driver doesn't support update.
Had to open data source read-only.
INFO: Open of `llcontours.ntf'
using driver `UK .NTF' successful.
1: LANDLINE_POINT (Point)
2: LANDLINE_LINE (Line String)
3: LANDLINE_NAME (Point)
4: FEATURE_CLASSES (None)
Using ogrinfo to examine the structure of an NTF layer:
7.1. Data Input
455
MapServer Documentation, Release 7.0.6
> ogrinfo llcontours.ntf LANDLINE_LINE -summary
ERROR 4: NTF Driver doesn't support update.
Had to open data source read-only.
INFO: Open of `llcontours.ntf'
using driver `UK .NTF' successful.
Layer name: LANDLINE_LINE
Geometry: Line String
Feature Count: 491
Extent: (279000.000000, 187000.000000) - (280000.000000, 188000.000000)
Layer SRS WKT:
PROJCS["OSGB 1936 / British National Grid",
GEOGCS["OSGB 1936",
DATUM["OSGB_1936",
SPHEROID["Airy 1830",6377563.396,299.3249646,
AUTHORITY["EPSG","7001"]],
AUTHORITY["EPSG","6277"]],
PRIMEM["Greenwich",0,
AUTHORITY["EPSG","8901"]],
UNIT["degree",0.0174532925199433],
AUTHORITY["EPSG","4277"]],
PROJECTION["Transverse_Mercator"],
PARAMETER["latitude_of_origin",49],
PARAMETER["central_meridian",-2],
PARAMETER["scale_factor",0.999601272],
PARAMETER["false_easting",400000],
PARAMETER["false_northing",-100000],
UNIT["metre",1,
AUTHORITY["EPSG","9001"]],
AUTHORITY["EPSG","27700"]]
LINE_ID: Integer (6.0)
FEAT_CODE: String (4.0)
...
Map File Example:
LAYER
NAME ntf_uk
TYPE LINE
CONNECTIONTYPE OGR
CONNECTION "./ntf/llcontours.ntf"
DATA "LANDLINE_LINE"
STATUS DEFAULT
CLASS
NAME "Contours"
STYLE
COLOR 0 150 200
END
END
END
OGR
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
7.1. Data Input
456
MapServer Documentation, Release 7.0.6
Last Updated 2017-03-21
Table of Contents
• OGR
– Introduction
– What is OGR?
* What Does OGR Add to MapServer?
* What Data Formats are Supported?
* How to Get More Information on the OGR Project
– Obtaining and Compiling MapServer with OGR Support
– Integrating OGR Support with MapServer Applications
* Using OGR Data Sources in the Map File
* Examples of Layer Definitions Using OGR
* How to Use “OGRINFO”
* Queries Through OGR Format
* TILEINDEX with OGR
* Connection Pooling
– STYLEITEM “AUTO” - Rendering Layers Using Style Information from the OGR File
* How to Implement
* Examples
* Important Notes
* Mapping of OGR Style Info to the MapServer CLASS Members
* Accessing OGR STYLEITEMAUTO Label Styles Through MapScript
– Sample Sites Using OGR/MapServer
– FAQ / Common Problems
– Credits
Introduction
MapServer includes the ability to access vector data sets in formats other than Shapefile in their native format using
the OGR library. The following document describes the process for implementing OGR support within MapServer
applications.
This document assumes that you are already familiar with certain aspects of MapServer:
• MapServer application development and especially setting up .map files.
• Some compilation skills if you don’t have ready access to a pre-compiled installation and need to compile your
own copy of MapServer with OGR support.
• access to OGR utilities, such as ogrinfo (for Windows users these are included in MS4W).
7.1. Data Input
457
MapServer Documentation, Release 7.0.6
Readers should also check out the Vector Data Access Guide, which has lots of examples of how to access specific
vector formats.
What is OGR?
The OGR Simple Features Library is a C++ Open Source library (and command-line tools) providing read (and
sometimes write) access to a variety of vector file formats including ESRI Shapefiles, and MapInfo mid/mif and TAB
formats.
OGR is actually part of the GDAL library, so you will notice that some references point to GDAL (such as the mailing
list).
What Does OGR Add to MapServer?
The OGR Simple Features Library allows MapServer users to display several types of vector data files in their native
formats. For example, MapInfo Mid/Mif and TAB data do not need to be converted to ESRI shapefiles when using
OGR support with MapServer.
What Data Formats are Supported?
See http://www.gdal.org/ogr_formats.html for the latest list of supported formats. At the date this document was
written, the following formats were supported:
• ArcInfo Binary Coverages
• ArcInfo E00 Coverages
• Atlas BNA
• Comma Separated Value (.csv)
• DODS/OPeNDAP
• ESRI ArcSDE
• ESRI Personal GeoDatabase
• ESRI Shapefiles
• FMEObjects Gateway
• GÃl’oconcept Export
• GeoJSON
• GeoRSS
• GML
• GMT
• GRASS
• GPX
• Informix DataBlade
• INGRES
• INTERLIS
7.1. Data Input
458
MapServer Documentation, Release 7.0.6
• KML
• MapInfo files
• Memory
• Microstation DGN files
• MySQL
• ODBC
• OGDI Vectors
• Oracle Spatial
• PostgreSQL
• SDTS
• SQLite
• UK.NTF (National Transfer Format)
• US Census TIGER/Line
• VRT - Virtual Datasource
• WFS
• X-Plane/Flighgear aeronautical data
Note: Some of the above formats (e.g. OGDI) have external dependencies and are not always included in the
pre-compiled binary distributions of MapServer with OGR support.*
Note: Some of the above formats are not well suited for random access by nature, that’s the case of MapInfo MIF/MID
files which is a TEXT format and will give very poor performance for a web application. On the other hand, some
binary formats such as MapInfo TAB are better suited for random access and will give performance comparable to
native shapefile access in MapServer.*
How to Get More Information on the OGR Project
• More information on the OGR Simple Features Project can be found at http://gdal.org/1.11/ogr/.
• The GDAL mailing list can be used for OGR related questions. Always search the list archives before sending
new questions.
• The GDAL Wiki has lots of good information for users and developers.
• The #gdal IRC channel on irc.freenode.net might also be of help. For info on IRC see the MapServer IRC page.
The main developer of the OGR library is currently Even Rouault (with original development by Frank Warmerdam)
and the integration of OGR within MapServer was done by Daniel Morissette.
Obtaining and Compiling MapServer with OGR Support
• Follow the instructions on the OGR page to compile/install OGR/GDAL.
• Obtain the MapServer source.
7.1. Data Input
459
MapServer Documentation, Release 7.0.6
For UNIX users, see the UNIX Compilation and Installation. If GDAL/OGR is normally installed it should be sufficient to add -DWITH_OGR=ON to the cmake line before (re)building MapServer. Linux users might want to try FGS,
a Linux installer for MapServer.
For Windows users, it is recommended to look for a pre-compiled binary on the MapServer site (MS4W is recommended). If you want to compile your own then see the README.WIN32 file in the MapServer source.
Starting with MapServer 7.0, 2.5D geometries, when handled by OGR drivers and data sources, can be taken into
account by MapServer if it is built with -DWITH_POINT_Z_M=ON.
Note: Output of 2.5D geometries in WFS requires explicit metadata item to be specified at the layer level. See WFS
server documentation.
Integrating OGR Support with MapServer Applications
The only change that is needed to integrate OGR support with a MapServer application is with the .map file.
The LAYER’s DATA parameter is expanded to three parameters (CONNECTIONTYPE OGR, CONNECTION and
DATA).
The syntax for this differs depending on the type of data being used (the Vector Data Access Guide is an excellent
resource for this). In OGR, a data source can be either a set of files that share a common basename (e.g. .shp/.shx/.dbf
for ArcView Shapefiles, or .tab/.map/.dat/.ind/.id for MapInfo TAB files) or a whole directory of files (e.g. TIGER).
Let’s call the former “File-based data sources” and the later “Directory-based data sources”. When accessing a filebased data source you specify the filename of one of the files in the set (e.g. roads.shp or roads.tab) and when
accessing a directory-based data source you specify the directory name and OGR reads all the files in the directory
as a single data source with potentially several layers (e.g. TIGER files).
Some OGR drivers (e.g. SHP, TAB) can have dual behaviors, that is if they’re pointed to a single file then they behave
as a file-based data source and if they’re pointed to a directory then they will behave as a directory-based data source
and then every file in the directory becomes a new layer in the data source.
See the OGR formats page for more info on the specific file format you’re using. (Click on the format name for more
specific driver info on that format)
Using OGR Data Sources in the Map File
The .map file LAYER definition for file-based sources is as follows:
LAYER
...
CONNECTIONTYPE OGR
CONNECTION "<datasource_name>"
DATA "<layer_definition>"
...
END
<datasource_name> is the name of the datasource to read from and is prefixed by the CONNECTION keyword. The
exact organization depends on the format driver in use. The format driver to use is automatically selected by OGR
based on the nature of the string passed as the datasource, and/or the format of the file referenced by it.
• For file based datasources this is the name of the file, including the extension, using an absolute path, or a relative
path. Relative paths are interpreted relative to the SHAPEPATH first, if not found then we try again relative to
the .map file location.
7.1. Data Input
460
MapServer Documentation, Release 7.0.6
Note: Before version 4.1 the SHAPEPATH was ignored for OGR datasources.
• For directory based datasources, such as TIGER/Line, or Arc/Info Binary Coverages this is the name of the
directory containing the files. If the path is relative it is interpreted relative to the .map file.
• For virtual datasources such as database systems, and OGDI this is the service connection string
and is generally not related to the filesystem.
For instance, for Oracle Spatial this might be
“OCI:warmerda/Password@gdal800.velocet.ca”.
<layer_definition> is the name, number or SQL definition of the layer to use from the datasource. It is indicated via
the DATA keyword in the map file.
• Layer Name: The (case insenstive) layer name may be used to select a layer.
• Layer Number: The layer number (starting from 0 for the first layer) may be used to select a layer. Generally
the layer name is preferred to this since it is more self describing.
• Omitted: If no DATA keyword is provided, this is equivalent to selecting layer 0.
• SQL SELECT: If an SQL SELECT statement is used, it is interpreted in a driver specific manner to try and
generate a temporary pseudo-layer. For some formats this a restricted subset of SQL is interpreted within OGR.
For RDBMS based drivers (such as PostGIS and Oracle) this is passed through to the underlying database.
The OGRINFO utility can be used to find out the list of layers and their names in a data source.
Examples of Layer Definitions Using OGR
Please see the Vector Data Access Guide for details and examples of each data format supported.
Example 1. MapInfo TAB file
LAYER
NAME "Builtup_Areas_tab"
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "data/tab/092b06_builtup_a.tab"
STATUS ON
CLASS
...
END
...
END
Example 2. Microstation DGN file using <layer_index>
The entire DGN file is represented in OGR as one layer (see the DGN driver page for more details):
LAYER
NAME "dgn"
TYPE LINE
CONNECTIONTYPE OGR
CONNECTION "dgn/santabarbara02.dgn"
DATA "0"
STATUS ON
STYLEITEM "AUTO"
CLASS
...
7.1. Data Input
461
MapServer Documentation, Release 7.0.6
END
END # Layer
Example 3. TIGER/Line file using <layer_name>
LAYER
NAME "Roads_tig"
TYPE line
CONNECTIONTYPE OGR
CONNECTION "full/path/to/tiger/TGR25001"
DATA "CompleteChain"
STATUS ON
CLASS
...
END
END
Example 4. Directory of Shapefiles using SQL JOIN
LAYER
NAME "Parks_cov"
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "data/shppoly"
DATA "SELECT eas_id, idl.Name FROM pol LEFT JOIN idl ON pol.eas_id = idl.eas_id"
STATUS ON
CLASSITEM "idlink.Name"
CLASS
...
END
END
How to Use “OGRINFO”
OGRINFO is part of the GDAL/OGR distribution (which is included in MS4W for Windows users). It is an executable
that can be used to obtain layer information about OGR supported files. The parameters are:
ogrinfo [-ro] [-q] datasource_name [layer [layer...]]
• -ro opens the file as read only (optional)
• -q executes in quiet mode, only the layer idex line will be returned (optional)
• datasource_name is the filename including extension (eg. roads.tab); for TIGER/Line files, datasource_name is the directory containing the TIGER files (eg. ogrinfo TGR25001)
Example 5. To get the list of layers in a file:
$ ogrinfo
popplace.tab
Had to open data source read-only.
INFO: Open of `popplace.tab'
using driver `MapInfo File' successful.
1: popplace (Point)
which shows that there is one point layer in the popplace.tab file.
Example 6. To get a dump of a specific layer, including field names, projection, etc:
7.1. Data Input
462
MapServer Documentation, Release 7.0.6
$ ogrinfo popplace.tab popplace
Had to open data source read-only.
INFO: Open of `popplace.tab'
using driver `MapInfo File' successful.
Layer name: popplace
Geometry: Point
Feature Count: 497
Layer SRS WKT: PROJCS["unnamed",GEOGCS["unnamed",DATUM["North ...snipped...
AREA: Real (15.3)
PERIMETER: Real (15.3)
POPPLACE_: Real (11.0)
POPPLACE_I: Real (15.0)
NAME: String (50.0)
OGRFeature(popplace):1
AREA (Real) =
0.000
PERIMETER (Real) =
0.000
POPPLACE_ (Real) =
1
POPPLACE_I (Real) =
1
NAME (String) = Port Hope Simpson
POINT (2437287.249 1153656.751)
OGRFeature(popplace):2
AREA (Real) =
0.000
PERIMETER (Real) =
0.000
POPPLACE_ (Real) =
2
POPPLACE_I (Real) =
1
NAME (String) = Hopedale
...
...
Example 7. To get a list of layers in a TIGER/Line Directory:
$ ogrinfo TGR25001
Had to open data source read-only.
INFO: Open of `TGR25001'
using driver `TIGER' successful.
1: CompleteChain (Line String)
2: AltName (None)
3: FeatureIds (None)
4: ZipCodes (None)
5: Landmarks (Point)
6: AreaLandmarks (None)
7: KeyFeatures (None)
8: Polygon (None)
9: EntityNames (Point)
10: IDHistory (None)
11: PolyChainLink (None)
12: PIP (Point)
13: TLIDRange (None)
14: ZipPlus4 (None)
The above example shows that there are 14 layers in the TGR25001 directory.
Example 8. To get a summary of a specific TIGER layer, including only field names, projection, and extent
7.1. Data Input
463
MapServer Documentation, Release 7.0.6
$ ogrinfo TGR25001 Landmarks -summary
Had to open data source read-only.
INFO: Open of `TGR25001'
using driver `TIGER' successful.
Layer name: Landmarks
Geometry: Point
Feature Count: 777
Extent: (-70.674324, 41.519817) - (-69.969211, 42.046868)
Layer SRS WKT: GEOGCS["NAD83",DATUM["North_American_Datum_1983",
SPHEROID["GRS 1980",6378137,298.257222101]],PRIMEM["Greenwich",0],
UNIT["degree",0.0174532925199433]]
MODULE: String (8.0)
FILE: String (5.0)
STATE: Integer (2.0)
COUNTY: Integer (3.0)
LAND: Integer (10.0)
SOURCE: String (1.0)
CFCC: String (3.0)
LANAME: String (30.0)
Queries Through OGR Format
OGR layers can be queried the same way as regular shapefiles in MapServer.
TILEINDEX with OGR
OGR layers can utilize tile indexes in a similar fashion to Shapefile based layers. The TILEINDEX keyword should
contain the connection string for the tile index file. The tile index file may be any supported OGR format, including
shapefiles.
The TILEITEM keyword in the LAYER definition indicates what attribute from the tile index file should be used as the
datasource location. If omitted, the default TILEITEM value is “location”. The value in the location field should be a
connection string the same as would have been used in the CONNECTION field for OGR layers. The CONNECTION
keyword is not needed (and will be ignored) for layers using the OGR connection type and having the TILEINDEX
keyword.
Tileindex files can be prepared in an external GIS, or using the OGR utility ogrtindex. Details can be found on the
OGR Utilities Page.
The following is a simple example of a point layer using a tile index.
LAYER
NAME "ogr_points"
TYPE POINT
CONNECTIONTYPE OGR
TILEINDEX "PIP_ogr_tiles.shp,0"
STATUS ON
CLASS
NAME "points"
STYLE
SYMBOL "default-circle"
COLOR 255 0 0
SIZE 6
7.1. Data Input
464
MapServer Documentation, Release 7.0.6
END
END
END
OGR tileindex layers should support all normal query and attribute fetching mechanisms, including from MapScript;
however, this has not been heavily tested as of April/2002. Please report problems via the MapServer Trac. If auto
projection support is used for tileindexed OGR layers, the tileindex is read for the projection (not the component tiles).
Problems may (or may not) be encountered if the component tiles have differing schemas (different sets of attributes).
Connection Pooling
For some OGR supported formats, connecting to the dataset is quite expensive in terms of CPU use and amount of
disk IO. For instance, establishing access to an S-57 dataset results in a complete read into memory of the data files.
Connection pooling control aims at reducing this overhead in situations where the same file is used for several different
map layers.
To ensure that an OGR supported dataset is only opened once per map render (instead of separately for each map
LAYER referencing the dataset, use the CLOSE_CONNECTION PROCESSING option. The default value is for
CLOSE_CONNECTION is NORMAL, but if set to DEFER the dataset will be kept open till the map render is
complete. It will be reused by any other layers with using the same datasource.
Example 9. Preserve S-57 connection for two layers
In this example, we are using the same dataset (NO410810.000) for two layers. To avoid re-reading the dataset, we
mark the first layer to defer closing the connection till layer. In the second (or last) layer we request NORMAL
connection handling (though this could have been left out as normal handling is the default).
LAYER
NAME "AdminAreas"
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "NO410810.000"
DATA "ADMARE"
PROCESSING "CLOSE_CONNECTION=DEFER"
STATUS ON
...
END
LAYER
NAME "Land Areas"
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "NO410810.000"
DATA "LNDARE"
PROCESSING "CLOSE_CONNECTION=NORMAL"
STATUS ON
...
END
1. The text of the CONNECTION keyword must match exactly between layers for the connection to be reused.
2. Some dataset connections are quite memory expensive, and keeping them open may result in increased memory
use.
3. If all layers rendered for a particular connection defer closing the connection, it will remain open till MapServer
terminates. For normal cgi or MapScript use this is likely OK.
4. This use of CLOSE_CONNECTION handling is unique to OGR layers, and may be changed at some point in
the future as part of a broader implementation of connection pooling in MapServer.
7.1. Data Input
465
MapServer Documentation, Release 7.0.6
STYLEITEM “AUTO” - Rendering Layers Using Style Information from the OGR File
Note: This feature is only supported with MapInfo TAB and Microstation DGN files at the moment, but eventually
other formats that carry colors and styles at the shape-level may also be supported through OGR.*
In MapServer, ArcView, and other shapefile-based applications, colors and styles are usually defined at the layer level.
This means that all the shapes in a given layer are usually rendered using the same color and styles.
On the other hand, some formats supported by OGR such as MapInfo TAB do have color and style information attached
to each shape. OGR adds support for the ‘STYLEITEM “AUTO”’ layer parameter which allows you to request that the
shapes in a layer be rendered using colors and styles coming from the data source instead of being driven by CLASSes
as was traditionally done with MapServer.
How to Implement
In order to have a layer rendered using colours and styles coming from the OGR data source, your must do the
following:
• Your layer definition must contain the STYLEITEM “AUTO” parameter.
• Your layer definition needs to contain at least one CLASS (which may be empty) and optionally a CLASSITEM
to match the expressions if your CLASS contains an expression. The empty CLASS in the layer will be updated
dynamically at runtime to contain colours and styles coming from the data source for each shape.
Examples
Example 10. Layer Definition Using STYLEITEM “AUTO” without a CLASSITEM
LAYER
NAME "test_dgn"
STATUS ON
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "../data/dgn/test.dgn"
# This enables use of colors and styles from the source file.
STYLEITEM "AUTO"
# Define an empty class that will be filled at runtime from the
# color and styles read on each shape in the source file.
CLASS
END
END # layer
Example 11. Layer Definition Using STYLEITEM “AUTO” with a CLASSITEM
LAYER
NAME "Builtup_Areas_tab"
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "data/tab/092b06_builtup_a.tab"
STATUS ON
# This enables use of colors and styles from the source file.
7.1. Data Input
466
MapServer Documentation, Release 7.0.6
STYLEITEM "AUTO"
# Define an empty class that will be filled at runtime from the
# color and styles read on each shape in the source file.
CLASSITEM "CATEGORY"
CLASS
EXPRESSION "1"
END
END
Please Note:
CLASS EXPRESSIONs are still working, so it is still possible to query and classify layers that are using STYLEITEM
“AUTO”. The only difference is that instead of using static class definitions, the colors and style will be read from the
data file.
Important Notes
NOTE 1 Even though MapInfo and other OGR data sources may support layers with mixed geometry
types (e.g. points, lines and polygons in the same file) this is not yet supported in MapServer. So
you still have to define a layer ‘TYPE’ and make sure that all the shapes in the OGR data source
are compatible with that layer type, otherwise MapServer may produce an error about incompatible
geometry types at runtime.
NOTE 2 Due to the dynamic nature of this feature, it is not compatible with the labelcache, so the labelcache is automatically disabled for layers that make use of ‘STYLEITEM “AUTO”’.
NOTE 3 When you use STYLEITEM AUTO, MapServer tries to match symbol names returned by OGR
to names in your symbol file. For a quick solution, try using the following symbol file:
http://demo.mapserver.org/ogr-demos/yk_demo/etc/symbols_mapinfo.txt
The name of the symbols returned by OGR to MapServer depends on the file format. In the case of MapInfo files, it
will be:
• For “old-style” symbols (default MapInfo 3.0 symbols numbered 32 to 67) the symbol name will be ‘mapinfosym-##’ where ‘##’ is the symbol number, e.g. ‘mapinfo-sym-32’.
• For “Font Symbols”, the symbol name is also ‘mapinfo-sym-##’ where ‘##’ is the symbol number in the font.
In this case, the name of the font itself is ignored by MapServer.
• MapInfo also supports “custom symbols” (bitmap symbols)... I’m not sure what you would get from OGR for
this, but I’m pretty sure that MapServer doesn’t do anything useful with them.
The OGRINFO utility can be used to find out exactly which symbol names OGR will return to MapServer. Look at
the “Style” string in the ogrinfo output for each shape that is read.
Mapping of OGR Style Info to the MapServer CLASS Members
Here is the list of style parameters that are currently supported from OGR data sources and how they’re mapped in
MapServer:
Line color The line colour (PEN.c) is mapped to CLASS.STYLE.COLOR
Line thickness The line thickness (PEN.w) is mapped to CLASS.STYLE.WIDTH. The default will be 1 pixel line
(as it always is with MapServer).
Line pattern The line pattern (PEN.p) is mapped to CLASS.STYLE.PATTERN. The default is a solid line.
7.1. Data Input
467
MapServer Documentation, Release 7.0.6
Line cap and join The line cap (PEN.cap) is mapped to CLASS.STYLE.CAP and the join to CLASS.STYLE.JOIN.
Line offset The line perpendicular offset (PEN.dp) is mapped to CLASS.STYLE.OFFSET
Line symbol OGR provides MapServer with symbol names (PEN.id), and if the symbol name returned by OGR to
MapServer matches the name of one of the symbols in your symbolset then this symbol will be used.
Polygon background color Polygon
background
CLASS.STYLE.BACKGROUNDCOLOR
color
(BRUSH.bc)
is
mapped
directly
to
Polygon fill color Polygon fill color (BRUSH.fc) is mapped directly to CLASS.STYLE.COLOR
Polygon outline If a polygon has an outline color (PEN.c) and thickness defined in the data source then the
same rule as for line color and thickness above will apply, except that the outline color is mapped to
CLASS.STYLE.OUTLINECOLOR
Polygon symbols OGR provides MapServer with symbol names (BRUSH.id), and if the symbol name returned by
OGR to MapServer matches the name of one of the symbols in your symbolset then this symbol will be used.
Polygon symbol color (BRUSH.fc) is directly mapped to CLASS.STYLE.COLOR. Polygon symbol size
(BRUSH.s) is directly mapped to CLASS.STYLE.SIZE. Polygon symbol spacing (note the OGR BRUSH.dx
and BRUSH?dy parameters mus be equal) is directly mapped to CLASS.STYLE.GAP. Polygon symbol angle
(BRUSH.a) is directly mapped to CLASS.STYLE.ANGLE.
Point symbols Point symbol color (SYMBOL.c) is directly mapped to CLASS.STYLE.COLOR. Point symbol outline color (SYMBOL.c) is directly mapped to CLASS.STYLE.OUTLINECOLOR. Point symbol size (SYMBOL.s) is directly mapped to CLASS.STYLE.SIZE.
If your symbolset contains a symbol called “default-marker” then this symbol will be used, otherwise the default
will be CLASS.SYMBOL=0 (i.e. a 1 pixel dot)
It is also possible (with a bit of work) to control which symbol gets used in rendering point symbols. OGR
provides MapServer with symbol names (SYMBOL.id), and if the symbol name returned by OGR to MapServer
matches the name of one of the symbols in your symbolset then this symbol will be used.
For MapInfo point symbols (numbered 32 to 67 in the MapInfo MIF spec), the name returned by OGR is
“mapinfo-sym-X” where X should be replaced with the MapInfo symbol number (e.g. “mapinfo-sym-35” is the
star symbol).
If the OGR symbol id is a web reference (http://.../mysymbol.png), the symbol will be downloaded and a new
symbol entry will be created referring to it.
Text labels The text string (LABEL.t) is mapped to CLASS.LABEL.TEXT
Text color (LABEL.c) is mapped to CLASS.LABEL.COLOR
Text background color (LABEL.b) is mapped to CLASS.LABEL.BACKGROUNDCOLOR
Text shadow color (LABEL.h) is mapped to CLASS.LABEL.SHADOWCOLOR
Text outline color (LABEL.h) is mapped to CLASS.LABEL.OUTLINECOLOR
Text height (LABEL.s) is mapped to CLASS.LABEL.SIZE
Text angle (LABEL.a) is mapped to CLASS.LABEL.ANGLE
Text anchor position (LABEL.p) is mapped to CLASS.LABEL.POSITION
Text font mapping follows the following rules:
1. If TTF fonts are supported:
(a) If the native font name (e.g. “Arial”) is found in your fontset then this font will be used. The font
styles bold and italic are supported as follows: Arial bold fontname maps to arial-bold. Arial italic
7.1. Data Input
468
MapServer Documentation, Release 7.0.6
fontname maps to arial-italic. Arial bold italic fontname maps to arial-bold-italic. If the styles are
not available, arial will be used.
(b) If 1a. failed and a font called “default” is present in your fontset then this “default” font will be used.
2. If TTF fonts are not supported or if all above cases failed, then BITMAP MEDIUM font will be used.
Starting with MapServer 7.0, multiple OGR tools (i.e. pen, brush, symbols) can be supported per feature. The
corresponding STYLE object are created in the order the OGR tools appear in the OGR FeatureStyle string, i.e.
the last one in the string is drawn on top of previous ones. This rule is true except if the priority level parameters
(PEN/BRUSH/SYMBOL.l) of OGR tools is defined, in which case it has precedence over the apparition order of the
OGR tools.
Accessing OGR STYLEITEMAUTO Label Styles Through MapScript
OGR STYLEITEMAUTO label styles can be accessed through MapScript, such as PHP/MapScript’s getshape() or
getvalue() methods, by setting the LAYER’s PROCESSING parameter to “GETSHAPE_STYLE_ITEMS=all”. Therefore, the LAYER must contain:
LAYER
...
PROCESSING "GETSHAPE_STYLE_ITEMS=all"
...
END
The following label styles are supported:
Label Style
Description
OGR:LabelFont Comma-delimited list of fonts names
OGR:LabelSize Numeric value with units
OGR:LabelText Label text string
OGR:LabelAngle Rotation angle (in degrees)
OGR:LabelFColorForeground color
OGR:LabelBColorBackground color
OGR:LabelPlacement
How is the text drawn relative to the feature’s geometry
OGR:LabelAnchorA value from 1 to 12 defining the label’s position relative to the
point to which it is attached.
OGR:LabelDx
X offset
OGR:LabelDy
Y offset
OGR:LabelPerp Perpendicular offset
OGR:LabelBold Bold text
OGR:LabelItalic Italic text
OGR:LabelUnderline
Underlined text
OGR:LabelPriorityNumeric value defining the order in which style parts should be
drawn.
OGR:LabelStrikeout
Strike out text (gdal >= 1.4.0)
OGR:LabelStretchStretch factor changes the width of all characters in the font by
factor percent. (gdal >= 1.4.0)
OGR:LabelAdjHorHorizontally adjacent text (gdal >= 1.4.0)
OGR:LabelAdjVertVertically adjacent text (gdal >= 1.4.0)
OGR:LabelHColorShadow color (gdal >= 1.4.0)
OGR:LabelOColorOutline color (gdal > 1.6.0)
MapServer Version
Implemented
5.4
5.2.0
5.2.0
5.2.0
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
5.4
Please see the OGR Feature Style Specification document for more details on those specific styles.
7.1. Data Input
469
MapServer Documentation, Release 7.0.6
Sample PHP MapScript code to access the “OGR:LabelText” label style follows:
<?php
// define variables
define( "MAPFILE", "D:/ms4w/apps/ogr-demos/nfld_demo/test.map" );
// open map
$oMap = ms_newMapObj( MAPFILE );
//get layer
$oLayer = $oMap->getLayerByName("Map_Labels");
//get styles
$status = $oLayer->open();
$status = $oLayer->whichShapes($oMap->extent);
while ($oShape = $oLayer->nextShape())
{
//echo $oShape->index ."<br>\n";
echo $oShape->getValue($oLayer,"OGR:LabelText");
echo "\n";
}
$oLayer->close();
?>
Sample Sites Using OGR/MapServer
The following sites use OGR’s STYLEITEM “AUTO” feature:
• http://demo.mapserver.org/ogr-demos/yk_demo/demo_init.html
• http://demo.mapserver.org/ogr-demos/nfld_demo/demo_init.html
The following site uses OGR, as well as MapInfo’s ‘Seamless Map Layers’ feature:
• http://demo.mapserver.org/ogr-demos/ro_demo/demo_init.html
The following site uses OGR to display TIGER 2000 files:
• http://demo.mapserver.org/ogr-demos/tig_demo/demo_init.html
FAQ / Common Problems
Q What Does “OGR” Stand For?
A Basically, OGR does not stand for anything. For a detailed explanation of how OGR was named, see
GDAL’s FAQ at http://trac.osgeo.org/gdal/wiki/FAQ.
Q When using STYLEITEM AUTO, what should I have in my .sym symbols file?
A When you use STYLEITEM AUTO, MapServer tries to match symbol names returned by OGR to
names in your symbol file. For a quick solution, try using the following symbol file:
http://demo.mapserver.org/ogr-demos/yk_demo/etc/symbols_mapinfo.txt
The name of the symbols returned by OGR to MapServer depends on the file format. In the case of
MapInfo files, it will be:
7.1. Data Input
470
MapServer Documentation, Release 7.0.6
• For “old-style” symbols (default MapInfo 3.0 symbols numbered 32 to 67) the symbol name
will be ‘mapinfo-sym-##’ where ‘##’ is the symbol number, e.g. ‘mapinfo-sym-32’.
• For “Font Symbols”, the symbol name is also ‘mapinfo-sym-##’ where ‘##’ is the symbol
number in the font. In this case, the name of the font itself is ignored by MapServer.
• MapInfo also supports “custom symbols” (bitmap symbols)... I’m not sure what you would get
from OGR for this, but I’m pretty sure that MapServer doesn’t do anything useful with them.
The OGRINFO utility can be used to find out exactly which symbol names OGR will return to
MapServer. Look at the “Style” string in the ogrinfo output for each shape that is read.
Credits
Improvements in mapping from OGR Feature style to MapServer styling developed for Faunalia (http://www.faunalia.
it) with funding from Regione Toscana - Settore SISTEMA INFORMATIVO TERRITORIALE ED AMBIENTALE (
http://www.geografia.toscana.it ) (CIG:Z410C90D94)
Oracle Spatial
Author Bart van den Eijnden
Last Updated 2005/12/12
Table of Contents
• Oracle Spatial
– What MapServer 5.2 with Oracle Spatial
– Binaries
– Installation
– Two options for using Oracle Spatial with MapServer
– Mapfile syntax for native Oracle Spatial support
– Using subselects in the DATA statement
– Additional keywords - [FUNCTION]
– Additional keywords - [VERSION]
– More information
– Example of a LAYER
– Mapfile syntax for OGR Oracle Spatial support
Oracle Spatial is a spatial cartridge for the Oracle database. Remember that all Oracle databases come with Locator,
which has less features than Oracle Spatial. The differences between Locator and Spatial can be found in the Oracle
Spatial FAQ.
You can also see the original OracleSpatial wiki page that this document was based on.
7.1. Data Input
471
MapServer Documentation, Release 7.0.6
What MapServer 5.2 with Oracle Spatial
• mode=map
• query modes: query, nquery, itemnquery
• MapScript query functions such as querybyattributes
• OGC:WMS: GetCapabilities, GetMap, GetFeatureInfo, DescribeLayer
• OGC:WFS, GetCapabilities, DescribeFeatureType, GetFeature
Binaries
MapServer Windows plugins with Oracle spatial support can be downloaded from MS4W. But you need Oracle client
software in the server on which you are running MapServer. Oracle client software can be obtained for development
purposes from the Oracle website, but you need to register, which by the way is free. The most recent version is
Oracle Database 10g Release 1 Client. The ORACLE TECHNOLOGY NETWORK DEVELOPMENT LICENSE
AGREEMENT applies to this software. The instant client will be satisfactory, and you can download the instant
client. Make sure though your MapServer is compiled against the same version as your Oracle client, for compiling
you need a full client install, not just the instant client.
Installation
See Oracle Installation for more configuration and installation information for MapServer’s native Oracle support
Note: If you receive error messages like “Error: .”. It’s likely related to MapServer being unable access or locate the
ORACLE_HOME.
Two options for using Oracle Spatial with MapServer
Oracle Spatial layers in MapServer can be used through 2 interfaces:
• The native built-in support through maporaclespatial.c
• OGR, but watch out: OGR is not compiled with Oracle Spatial support so it won’t work without compiling in
OCI (Oracle client) yourself. This requires both recompiling GDAL/OGR as well as recompiling MapServer
itself against the new GDAL/OGR !!!!
Mapfile syntax for native Oracle Spatial support
The DATA statement for a LAYER of CONNECTIONTYPE oraclespatial can now have 4 options. This change is
backwards compatible, i.e. the old ways of specifying DATA still work. The new options are an extension to the
old DATA statements, as they needed to include identification of the primary key to be used for the query modes
(UNIQUE).
The following options are valid DATA statements:
"[geom_column]
FROM
[table]| [(
SELECT [...]
7.1. Data Input
472
MapServer Documentation, Release 7.0.6
FROM [table]|[Spatial Operator]
[WHERE condition] )]
[USING [UNIQUE column]
| [SRID #srid]
| [FUNCTION]
| [VERSION #version]
]"
Example 1
The most simple DATA statement, in this case you only need to define one geometry column and one table. This
option assumes you do not have an SRID defined.
LAYER
...
CONNECTIONTYPE oraclespatial
DATA "MYGEOMETRY FROM MYTABLE"
...
END
Example 2
It’s composed of the first option plus the USING UNIQUE parameter. These new features are necessary when you
want to use any query function. When it is used you must pass a numeric column type. This option assumes you do
not have an SRID defined.
LAYER
...
CONNECTIONTYPE oraclespatial
DATA "MYGEOMETRY FROM MYTABLE USING UNIQUE MYTABLE_ID"
...
END
Example 3
This option is an extension to the first option. In this mode you must define the USING SRID parameter when the
SRID value in your data is different from NULL.
LAYER
...
CONNECTIONTYPE oraclespatial
DATA "MYGEOMETRY FROM MYTABLE USING SRID 90112"
...
END
Example 4
This option is a combination of examples 2 and 3.
7.1. Data Input
473
MapServer Documentation, Release 7.0.6
LAYER
...
CONNECTIONTYPE oraclespatial
DATA "MYGEOMETRY FROM MYTABLE USING UNIQUE MYTABLE_ID SRID 90112"
...
END
Using subselects in the DATA statement
It is possible to define the source of the date as a subselect and not only as a table. As source of data, used in FROM
token, you can define any SQL, table, function, or operator that returns a SDO_GEOMETRY. For example:
DATA "[geom_column] FROM (SELECT [columns] FROM [table]|[Spatial function])"
If the LAYER definition contains a CLASSITEM, LABELITEM or FILTER, it is necessary that the fields used are
returned by the query. When you define CLASSITEM you can use an expression without any problems.
Additional keywords - [FUNCTION]
You can add three keywords to the DATA statement for [FUNCTION] option that influence the query which will be
executed in Oracle:
USING FILTER
"[geom_column] FROM [table]|([Subselect]) USING FILTER"
Using this keyword triggers MapServer to use the Oracle Spatial SDO_FILTER operator. This operator executes only
the Oracle Spatial primary filter over your query data. In the Oracle User guide they explain: The primary filter
compares geometric approximations, it returns a superset of exact result. The primary filter therefore should be as
efficient (that is, selective yet fast) as possible. This operator uses the spatial index, so you need to define your spatial
index correctly to retrieve an exact result. If the result of the query is not exact you can try the next option.
USING RELATE
"[geom_column] FROM [table]|([Subselect]) USING RELATE"
Using this keyword triggers MapServer to use the Oracle Spatial SDO_RELATE operator. This operator applies the
primary and secondary Oracle Spatial filters. It’s performance can be slightly slow but the result is extremely correct.
You can use this mode when you want a perfect result or when you can’t readjust the spatial index.
USING GEOMRELATE
"[geom_column] FROM [table]|([Subselect]) USING GEOMRELATE"
Using this keyword triggers MapServer to use the geometry function SDO_GEOM.RELATE, a function that searches
the relations between geometries. SDO_GEOM.RELATE does not use the spatial index and your performance is more
slow than operators but it’s very accurate. You can use this mode when you can’t use the spatial index or when it
doesn’t exist.
7.1. Data Input
474
MapServer Documentation, Release 7.0.6
USING NONE
"[geom_column] FROM [table]|([Subselect]) USING NONE"
Using this keyword triggers MapServer to don’t use any geometry function or spatial operator. So, the internal SQL
don’t retrict, bases in the extent, the data from source. All the data from source will be returned for MapServer. The
NONE token is very useful when the source of the data don’t contains any spatial index. It’s usually occur when
the source is a function like SDO_BUFFER, SDO_XOR, SDO_INTERSECTION...... So this mode is recommended
when you can’t use the spatial index or when it doesn’t exist.
Additional keywords - [VERSION]
You can define what version of database you are using to improve the internal sql. This is very useful when using
geodetic SRIDs and MapServer functions that retrieve the extent from data.
USING VERSION 8i
"[geom_column] FROM [table]|([Subselect]) USING VERSION 8i"
This indicates MapServer to use a internal SQL that it’s compatible with Oracle 8i version.
USING VERSION 9i
"[geom_column] FROM [table]|([Subselect]) USING VERSION 9i"
The second indicates MapServer to use 9i version, is recommended to use this parameter if you are using 9i version
because the internal SQL will use specific spatial functions that is need to retrieve data correctly from 9i Oracle Spatial
versions.
USING VERSION 10g
"[geom_column] FROM [table]|([Subselect]) USING VERSION 10g"
This indicates MapServer to use a internal SQL that it’s compatible with Oracle 10g version.
More information
• You can define any PROJECTION to your LAYER without problem, can be used for data with or without an
SRID in Oracle.
• The native support for Oracle Spatial supports the defaults definition for SDO_GEOMETRY in database, the
Oracle Spatial SDO package.
• Information about the primary and secondary Oracle Spatial filters can be found in the Oracle Spatial User Guide
(the “Query Model” section). Information about the SDO_FILTER and SDO_RELATE operators can be found
in the “Spatial Operators” section, and information about the SDO_GEOM.RELATE function can be found in
the “Geometry Function” section of the Oracle Spatial User Guide.
7.1. Data Input
475
MapServer Documentation, Release 7.0.6
Example of a LAYER
LAYER
NAME kwadranten
TYPE POLYGON
CONNECTIONTYPE oraclespatial
CONNECTION "user/pwd"
DATA "GEOMETRIE FROM KWADRANTEN USING SRID 90112"
CLASS
STYLE
OUTLINECOLOR 0 0 0
COLOR 0 128 128
END
END
END
You can specify the SID for your database, the SID alias needs to be supplied in the tnsnames.ora file of the Oracle
client, e.g.
Example for tnsnames.ora:
MYDB =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = server_ip)(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = DB1)
)
)
So after this you can define you layer connection as:
CONNECTION "user/pwd@MYDB"
Mapfile syntax for OGR Oracle Spatial support
Syntax for your MAP file:
CONNECTION "OCI:user/pwd@service"
CONNECTIONTYPE OGR
DATA "Tablename"
Note: Make sure you set the wms_extent METADATA for the LAYER, as otherwise the “Getcapabilities” request
takes a lot of time.
PostGIS/PostgreSQL
Last Updated 2014-11-06
7.1. Data Input
476
MapServer Documentation, Release 7.0.6
Table of Contents
• PostGIS/PostgreSQL
– PostGIS/PostgreSQL
– Data Access /Connection Method
– OGRINFO Examples
– Mapfile Example
– Support for 2.5D geometries
– Support for SQL/MM Curves
* Example#1: CircularString in MapServer
* Example#2: CompoundCurve in MapServer
* Example#3: CurvePolygon in MapServer
* Example#4: MultiCurve in MapServer
* Example#5: MultiSurface in MapServer
* Using MapServer < 6.0
PostGIS/PostgreSQL
PostGIS spatially enables the Open Source PostgreSQL database.
The PostGIS wiki page may include additional information.
Data Access /Connection Method
PostGIS is supported directly by MapServer and must be compiled into MapServer to work.
The PostgreSQL client libraries (libpq.so or libpq.dll) must be present in the system’s path environment for functionality to be present.
The CONNECTIONTYPE parameter must be set to POSTGIS.
The CONNECTION parameter is used to specify the parameters to connect to the database. CONNECTION parameters can be in any order. Most are optional. dbname is required. user is required. host defaults to localhost, port
defaults to 5432 (the standard port for PostgreSQL).
The DATA parameter is used to specify the data used to draw the map. The form of DATA is “[geometry_column]
from [table_name|sql_subquery] using unique [unique_key] using srid=[spatial_reference_id]”. The “using unique”
and “using srid=” clauses are optional when drawing features, but using them improves performance. If you want to
make MapServer query calls to a PostGIS layer, your DATA parameter must include “using unique”. Omitting it will
cause the query to fail.
Here is a simple generic example:
CONNECTIONTYPE POSTGIS
CONNECTION "host=yourhostname dbname=yourdatabasename user=yourdbusername
password=yourdbpassword port=yourpgport"
DATA "geometrycolumn from yourtablename"
7.1. Data Input
477
MapServer Documentation, Release 7.0.6
This example shows specifying the unique key and srid in the DATA line:
CONNECTIONTYPE POSTGIS
CONNECTION "dbname=yourdatabasename user=yourdbusername"
DATA "the_geom from the_database using unique gid using srid=4326"
This example shows using a SQL subquery to perform a join inside the database and map the result in MapServer.
Note the “as subquery” string in the statement – everything between “from” and “using” is sent to the database for
evaluation:
CONNECTIONTYPE POSTGIS
CONNECTION "dbname=yourdatabasename user=yourdbusername"
DATA "the_geom from (select g.gid, g.the_geom, a.attr1, a.attr2 from
geotable g join attrtable a on g.gid = a.aid) as subquery
using unique gid using srid=4326"
This example shows using a geometry function and database sort to limit the number of features and vertices returned
to MapServer:
CONNECTIONTYPE POSTGIS
CONNECTION "dbname=yourdatabasename user=yourdbusername"
DATA "the_geom from (select g.gid, ST_Simplify(g.the_geom, 10.0) as
the_geom from geotable g order by ST_Area(g.the_geom) desc
limit 10) as subquery using unique gid using srid=4326"
This example shows the use of the !BOX! substitution string to over-ride the default inclusion of the map bounding
box in the SQL. By default the spatial box clause is appended to the SQL in the DATA clause, but you can use !BOX!
to insert it anywhere you like in the statement. In general, you won’t need to use !BOX!, because the PostgreSQL
planner will generate the optimal plan from the generated SQL, but in some cases (complex sub-queries) a better plan
can be generated by placing the !BOX! closer to the middle of the query:
CONNECTIONTYPE POSTGIS
CONNECTION "dbname=yourdatabasename user=yourdbusername"
DATA "the_geom from (select g.gid, ST_Union(g.the_geom, 10.0) as
the_geom from geotable g where ST_Intersects(g.geom,!BOX!)) as
subquery using unique gid using srid=4326"
OGRINFO Examples
OGRINFO can be used to read out metadata about PostGIS tables directly from the database.
First you should make sure that your GDAL/OGR build contains the PostgreSQL driver, by using the ‘–formats’
command:
>ogrinfo --formats
Loaded OGR Format Drivers:
...
-> "PGeo" (readonly)
-> "PostgreSQL" (read/write)
-> "MySQL" (read/write)
...
If you don’t have the driver, you might want to try the FWTools or MS4W packages, which include the driver.
Once you have the driver you are ready to try an ogrinfo command on your database to get a list of spatial tables:
7.1. Data Input
478
MapServer Documentation, Release 7.0.6
>ogrinfo PG:"host=127.0.0.1 user=postgres password=postgres dbname=canada port=5432"
using driver `PostgreSQL' successful.
1: province (Multi Polygon)
Now use ogrinfo to get information on the structure of the spatial table:
>ogrinfo PG:"host=127.0.0.1 user=postgres password=postgres dbname=canada port=5432"
province -summary
INFO: Open of `PG:host=127.0.0.1 user=postgres password=postgres dbname=canada'
using driver `PostgreSQL' successful.
Layer name: province
Geometry: Multi Polygon
Feature Count: 1068
Extent: (-2340603.750000, -719746.062500) - (3009430.500000, 3836605.250000)
Layer SRS WKT:
(unknown)
FID Column = gid
Geometry Column = the_geom
area: Real (0.0)
island: String (30.0)
island_e: String (30.0)
island_f: String (30.0)
name: String (30.0)
...
Mapfile Example
LAYER
NAME "province"
STATUS ON
TYPE POLYGON
CONNECTIONTYPE POSTGIS
CONNECTION "host=127.0.0.1 port=5432 dbname=canada user=postgres password=postgres"
DATA "the_geom from province"
CLASS
...
END
END
For more info about PostGIS and MapServer see the PostGIS docs: http://postgis.net/documentation/
Support for 2.5D geometries
In addition to horizontal coordinates (X,Y or longitude,latitude), PostGIS can support geometries with a vertical
component, often called 2.5D geometries.
As of MapServer 7.0, such 2.5D geometries will be taken into account if MapServer is built with DWITH_POINT_Z_M=ON.
Note: Output of 2.5D geometries in WFS requires explicit metadata item to be specified at the layer level. See WFS
server documentation.
7.1. Data Input
479
MapServer Documentation, Release 7.0.6
Note: It is still possible to force 2D only geometries to be retrieved from PostGIS by setting the following PROCESSING option
PROCESSING "FORCE2D=YES"
Support for SQL/MM Curves
PostGIS is able to store circular interpolated curves, as part of the SQL Multimedia Applications Spatial specification
(read about the SQL/MM specification).
For more information about PostGIS’ support, see the SQL-MM Part 3 section in the PostGIS documentation, such as
here.
As of MapServer 6.0, the PostGIS features CircularString, CompoundCurve, CurvePolygon, MultiCurve, and MultiSurface can be drawn through MapServer directly.
Example#1: CircularString in MapServer
The following is the Well Known Text of the feature loading into PostGIS:
INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText('CIRCULARSTRING(0 0,
4 0, 4 4, 0 4, 0 0)', -1), 2);
An example MapServer layer might look like:
LAYER
NAME "curves_poly"
STATUS DEFAULT
TYPE POLYGON
CONNECTIONTYPE postgis
CONNECTION "user=postgres password=postgres dbname=curves host=localhost port=5432"
DATA "g from test using SRID=-1 using unique id"
CLASS
STYLE
COLOR 128 128 128
ANTIALIAS true
END
END
END
And testing with shp2img should produce a map image of:
7.1. Data Input
480
MapServer Documentation, Release 7.0.6
Example#2: CompoundCurve in MapServer
The following is the Well Known Text of the feature loading into PostGIS:
INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText('COMPOUNDCURVE(
CIRCULARSTRING(0 0, 1 1, 1 0),(1 0, 0 1))', -1), 3);
An example MapServer layer might look like:
LAYER
NAME "curves_poly"
STATUS DEFAULT
TYPE POLYGON
CONNECTIONTYPE postgis
CONNECTION "user=postgres password=postgres dbname=curves host=localhost port=5432"
DATA "g from test using SRID=-1 using unique id"
CLASS
STYLE
COLOR 128 128 128
ANTIALIAS true
END
END
END
And testing with shp2img should produce a map image of:
Example#3: CurvePolygon in MapServer
The following is the Well Known Text of the feature loading into PostGIS:
INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText('CURVEPOLYGON(
CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0),(1 1, 3 3,
3 1, 1 1))', -1), 4);
An example MapServer layer might look like:
LAYER
NAME "curves_poly"
STATUS DEFAULT
TYPE POLYGON
CONNECTIONTYPE postgis
CONNECTION "user=postgres password=postgres dbname=curves host=localhost port=5432"
DATA "g from test using SRID=-1 using unique id"
CLASS
STYLE
COLOR 128 128 128
ANTIALIAS true
END
7.1. Data Input
481
MapServer Documentation, Release 7.0.6
END
END
And testing with shp2img should produce a map image of:
Example#4: MultiCurve in MapServer
The following is the Well Known Text of the feature loading into PostGIS:
INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText('MULTICURVE((0 0,
5 5),CIRCULARSTRING(4 0, 4 4, 8 4))', -1), 6);
An example MapServer layer might look like:
LAYER
NAME "curves_poly"
STATUS DEFAULT
TYPE POLYGON
CONNECTIONTYPE postgis
CONNECTION "user=postgres password=postgres dbname=curves host=localhost port=5432"
DATA "g from test using SRID=-1 using unique id"
CLASS
STYLE
COLOR 128 128 128
ANTIALIAS true
END
END
END
And testing with shp2img should produce a map image of:
7.1. Data Input
482
MapServer Documentation, Release 7.0.6
Example#5: MultiSurface in MapServer
The following is the Well Known Text of the feature loading into PostGIS:
INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText('MULTISURFACE(
CURVEPOLYGON(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4,
0 0),(1 1, 3 3, 3 1, 1 1)),((10 10, 14 12, 11 10,
10 10),(11 11, 11.5 11, 11 11.5, 11 11)))', -1), 7);
An example MapServer layer might look like:
LAYER
NAME "curves_poly"
STATUS DEFAULT
TYPE POLYGON
CONNECTIONTYPE postgis
CONNECTION "user=postgres password=postgres dbname=curves host=localhost port=5432"
DATA "g from test using SRID=-1 using unique id"
CLASS
STYLE
COLOR 128 128 128
ANTIALIAS true
END
END
END
And testing with shp2img should produce a map image of:
7.1. Data Input
483
MapServer Documentation, Release 7.0.6
Using MapServer < 6.0
If you cannot upgrade to MapServer 6.0, then you can use the PostGIS function ST_CurveToLine() in your MapServer
LAYER to draw the curves (note that this is much slower however):
LAYER
NAME "curves_poly"
STATUS DEFAULT
TYPE POLYGON
CONNECTIONTYPE postgis
CONNECTION "user=postgres password=postgres dbname=curves host=localhost port=5432"
DATA "wkb_geometry from (select c.id, ST_CurveToLine(c.g) as
wkb_geometry from c) as subquery using
unique id using SRID=-1"
CLASS
STYLE
COLOR 128 128 128
ANTIALIAS true
END
END
END
7.1. Data Input
484
MapServer Documentation, Release 7.0.6
SDTS
This is a United States Geological Survey (USGS) format. SDTS has a raster and a vector format. The raster format
is not supported in MapServer. Only the vector formats are supported, including VTP and DLG files.
File listing
• SDTS files are often organized into state-sized pieces. For example, all of the state of Maryland (MD), U.S.A.
• Files are also available for multiple types of features including hydrography, transportation and administrative
boundaries.
This example uses transportation data, which consists of 35 separate files, each with the suffix DDF:
MDTRAHDR.DDF
MDTRDQCG.DDF
MDTRNA03.DDF
MDTRAMTF.DDF
MDTRDQHL.DDF
MDTRNE03.DDF
MDTRARDF.DDF
MDTRDQLC.DDF
MDTRNO01.DDF
MDTRARDM.DDF
MDTRDQPA.DDF
MDTRNO02.DDF
MDTRARRF.DDF
MDTRFF01.DDF
MDTRNO03.DDF
MDTRBFPS.DDF
MDTRIDEN.DDF
MDTRPC01.DDF
MDTRBMTA.DDF
MDTRIREF.DDF
MDTRPC02.DDF
MDTRCATD.DDF
MDTRLE01.DDF
MDTRPC03.DDF
MDTRCATS.DDF
MDTRLE02.DDF
MDTRSPDM.DDF
MDTRCATX.DDF
MDTRLE03.DDF
MDTRSTAT.DDF
MDTRDDSH.DDF
MDTRNA01.DDF
MDTRXREF.DDF
MDTRDQAA.DDF
MDTRNA02.DDF
Data Access / Connection Method
• SDTS access is available in MapServer through OGR.
• The CONNECTIONTYPE OGR parameter must be used.
• The path (which can be relative) to the catalog file (????CATD.DDF) is required, including file extension.
• There are multiple layers in the SDTS catalog, some of which are only attributes and have no geometries.
• The layer name is specified with the DATA parameter
OGRINFO Examples
Using ogrinfo on a catalog file (note that the first 7 layers do not have geometries):
> ogrinfo /data/sdts/MD/MDTRCATD.DDF
Had to open data source read-only.
INFO: Open of `MDTRCATD.DDF'
using driver `SDTS' successful.
1: ARDF (None)
2: ARRF (None)
3: AMTF (None)
4: ARDM (None)
5: BFPS (None)
6: BMTA (None)
7: AHDR (None)
8: NE03 (Point)
9: NA01 (Point)
7.1. Data Input
485
MapServer Documentation, Release 7.0.6
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
NA02
NA03
NO01
NO02
NO03
LE01
LE02
LE03
PC01
PC02
PC03
(Point)
(Point)
(Point)
(Point)
(Point)
(Line String)
(Line String)
(Line String)
(Polygon)
(Polygon)
(Polygon)
Using ogrinfo to examine the structure of the file/layer:
> ogrinfo /data/sdts/MD/MDTRCATD.DDF LE01 -summary
Had to open data source read-only.
INFO: Open of `MDTRCATD.DDF'
using driver `SDTS' successful.
Layer name: LE01
Geometry: Line String
Feature Count: 780
Extent: (-80.000289, 36.999774) - (-74.999711, 40.000225)
Layer SRS WKT:
GEOGCS["NAD27",
DATUM["North_American_Datum_1927",
SPHEROID["Clarke 1866",6378206.4,294.978698213901]],
PRIMEM["Greenwich",0],
UNIT["degree",0.0174532925199433]]
RCID: Integer (0.0)
SNID: Integer (0.0)
ENID: Integer (0.0)
ENTITY_LABEL: String (7.0)
ARBITRARY_EXT: String (1.0)
RELATION_TO_GROUND: String (1.0)
VERTICAL_RELATION: String (1.0)
OPERATIONAL_STATUS: String (1.0)
ACCESS_RESTRICTION: String (1.0)
OLD_RAILROAD_GRADE: String (1.0)
WITH_RAILROAD: String (1.0)
COVERED: String (1.0)
HISTORICAL: String (1.0)
LIMITED_ACCESS: String (1.0)
PHOTOREVISED: String (1.0)
LANES: Integer (2.0)
ROAD_WIDTH: Integer (3.0)
BEST_ESTIMATE: String (1.0)
ROUTE_NUMBER: String (7.0)
ROUTE_TYPE: String (9.0)
Map File Example:
LAYER
NAME sdts_maryland
TYPE LINE
CONNECTIONTYPE OGR
CONNECTION "data/sdts/MD/MDTRCATD.DDF"
DATA "LE01"
7.1. Data Input
486
MapServer Documentation, Release 7.0.6
STATUS DEFAULT
CLASS
STYLE
COLOR 0 0 0
END
END
END
S57
Also known as S57. The IHO S-57 format is a vector interchange format used for maritime charts. It was developed by
the International Hydrographic Organisation (IHO). For more information about the IHO see: http://www.iho.shom.fr/
File listing
Individual S57 data files have an extension of *.000. For example:
US1BS02M.000
Data Access / Connection Method
• S57 access in MapServer occurs through OGR, CONNECTIONTYPE OGR must be used.
• Specify a full path or a relative path from the SHAPEPATH to the .000 file for the CONNECTION
• Use the DATA parameter to specify the s57 layer name
Special Notes
The underlying OGR code requires two files from your GDAL/OGR installation when reading S57 data in
MapServer : s57objectclasses.csv and s57attributes.csv. These files can be found in the /GDAL/data/ folder (unix:
/usr/local/share/gdal windows: /ms4w/gdaldata). If you receive an error in MapServer such as:
msDrawMap(): Image handling error. Failed to draw layer named 's57'.
msOGRFileOpen(): OGR error. xxx failed for OGR connection
you may have to point MapServer to these files using the CONFIG parameter in the main section of your map file:
CONFIG GDAL_DATA "C:\ms4w\gdaldata"
OGRINFO Examples
Using ogrinfo on an S57 file to get the layer name:
> ogrinfo us1bs02m.000
ERROR 4: S57 Driver doesn't support update.
Had to open data source read-only.
INFO: Open of `us1bs02m.000'
using driver `IHO S-57 (ENC)' successful.
1: ADMARE (Polygon)
7.1. Data Input
487
MapServer Documentation, Release 7.0.6
2: CBLSUB (Line String)
3: CTNARE
4: COALNE (Line String)
5: DEPARE
6: DEPCNT (Line String)
7: LNDARE
8: LNDELV
9: LNDRGN
10: LNDMRK
11: LIGHTS (Point)
12: OBSTRN
13: RDOSTA (Point)
14: SEAARE
15: SBDARE
16: SLCONS
17: SOUNDG (Multi Point)
18: UWTROC (Point)
19: WATTUR
20: WRECKS
21: M_COVR (Polygon)
22: M_NPUB (Polygon)
23: M_NSYS (Polygon)
24: M_QUAL (Polygon)
25: C_ASSO (None)
Using ogrinfo to examine the structure of an S57 layer:
> ogrinfo us1bs02m.000 DEPARE -summary
ERROR 4: S57 Driver doesn't support update.
Had to open data source read-only.
INFO: Open of `us1bs02m.000'
using driver `IHO S-57 (ENC)' successful.
Layer name: DEPARE
Geometry: Unknown (any)
Feature Count: 297
Extent: (165.666667, 48.500000) - (180.000000, 60.750000)
Layer SRS WKT:
GEOGCS["WGS 84",
DATUM["WGS_1984",
SPHEROID["WGS 84",6378137,298.257223563]],
PRIMEM["Greenwich",0],
UNIT["degree",0.0174532925199433]]
GRUP: Integer (3.0)
OBJL: Integer (5.0)
RVER: Integer (3.0)
AGEN: Integer (2.0)
FIDN: Integer (10.0)
FIDS: Integer (5.0)
LNAM: String (16.0)
LNAM_REFS: StringList (16.0)
DRVAL1: Real (0.0)
DRVAL2: Real (0.0)
QUASOU: String (0.0)
SOUACC: Real (0.0)
VERDAT: Integer (0.0)
INFORM: String (0.0)
NINFOM: String (0.0)
7.1. Data Input
488
MapServer Documentation, Release 7.0.6
NTXTDS:
SCAMAX:
SCAMIN:
TXTDSC:
RECDAT:
RECIND:
...
String (0.0)
Integer (0.0)
Integer (0.0)
String (0.0)
String (0.0)
String (0.0)
Map File Example:
LAYER
NAME s57
TYPE POLYGON
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "./s57/us1bs02m.000"
DATA "DEPARE"
CLASS
STYLE
COLOR 247 237 219
OUTLINECOLOR 120 120 120
END
END
END # Layer
SpatiaLite
SpatiaLite spatially enables the file-based SQLite database. For more information see the SpatiaLite description page.
File listing
Similar to other database formats, the .sqlite file consists of several tables. The geometry is held in a BLOB table
column.
Data Access / Connection Method
Spatialite access is available through OGR. See the OGR driver page for specific driver information. The driver is
available in GDAL/OGR version 1.7.0 or later.
OGR uses the names of spatial tables within the SpatiaLite database (tables with a geometry column that are registered
in the geometry_columns table) as layers.
The CONNECTION parameter must include the sqlite extension, and the DATA parameter should be the name of the
spatial table (or OGR layer).
CONNECTIONTYPE OGR
CONNECTION "spatialite_db.sqlite"
DATA "layername"
7.1. Data Input
489
MapServer Documentation, Release 7.0.6
OGRINFO Examples
First you should make sure that your GDAL/OGR build contains the spatialite “SQLite” driver, by using the ‘–formats’
command:
>ogrinfo --formats
Loaded OGR Format Drivers:
...
-> "GMT" (read/write)
-> "SQLite" (read/write)
-> "ODBC" (read/write)
...
If you don’t have the driver, you might want to try the MS4W or OSGeo4W packages, which include the driver.
Once you have confirmed that you have the SQLite driver you are ready to try an ogrinfo command on your database
to get a list of spatial tables:
>ogrinfo counties.sqlite
INFO: Open of `counties.sqlite'
using driver `SQLite' successful.
1: mn_counties (Polygon)
Now use ogrinfo to get information on the structure of the spatial table:
>ogrinfo counties.sqlite county -summary
INFO: Open of `counties.sqlite'
using driver `SQLite' successful.
Layer name: mn_counties
Geometry: Polygon
Feature Count: 87
Extent: (189783.560000, 4816309.330000) - (761653.524114, 5472346.500000)
Layer SRS WKT:
PROJCS["NAD83 / UTM zone 15N",
GEOGCS["NAD83",
DATUM["North_American_Datum_1983",
SPHEROID["GRS 1980",6378137,298.257222101,
AUTHORITY["EPSG","7019"]],
TOWGS84[0,0,0,0,0,0,0],
AUTHORITY["EPSG","6269"]],
PRIMEM["Greenwich",0,
AUTHORITY["EPSG","8901"]],
UNIT["degree",0.0174532925199433,
AUTHORITY["EPSG","9122"]],
AUTHORITY["EPSG","4269"]],
UNIT["metre",1,
AUTHORITY["EPSG","9001"]],
PROJECTION["Transverse_Mercator"],
PARAMETER["latitude_of_origin",0],
PARAMETER["central_meridian",-93],
PARAMETER["scale_factor",0.9996],
PARAMETER["false_easting",500000],
PARAMETER["false_northing",0],
AUTHORITY["EPSG","26915"],
AXIS["Easting",EAST],
AXIS["Northing",NORTH]]
FID Column = PK_UID
7.1. Data Input
490
MapServer Documentation, Release 7.0.6
Geometry Column = Geometry
AREA: Real (0.0)
PERIMETER: Real (0.0)
COUNTY_ID: Integer (0.0)
FIPS: String (0.0)
...
Mapfile Example
Standard connection
LAYER
NAME my_counties_layer
TYPE POLYGON
CONNECTIONTYPE ogr
CONNECTION "counties.sqlite"
DATA "mn_counties"
STATUS ON
CLASS
NAME "mncounties"
STYLE
COLOR 255 255 120
END
END
END
Connection utilizing SQL syntax
LAYER
NAME my_counties_layer
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "counties.sqlite"
DATA "select geometry from mn_counties"
STATUS ON
CLASS
NAME "mncounties"
STYLE
COLOR 255 255 120
END
END
END
Connection utilizing joined table for additional attributes
LAYER
NAME my_counties_layer
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "counties.sqlite"
DATA "SELECT mn.geometry, c.fips FROM mn_counties mn inner
7.1. Data Input
491
MapServer Documentation, Release 7.0.6
join county_data c on mn.county_id = c.county_id'
STATUS ON
CLASS
NAME "mncounties"
STYLE
COLOR 255 255 120
END
END
END
Standard Connection with a filter
LAYER
NAME my_counties_layer
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "counties.sqlite"
DATA "mn_counties"
FILTER ('[fips]' = '27031')
STATUS ON
CLASS
NAME "mncounties"
STYLE
COLOR 255 255 120
END
END
END
Filter utilizing SQL syntax
LAYER
NAME my_counties_layer
TYPE POLYGON
CONNECTIONTYPE OGR
CONNECTION "counties.sqlite"
DATA "select geometry from mn_counties where fips = '27031"
STATUS ON
CLASS
NAME "mncounties"
STYLE
COLOR 255 255 120
END
END
END
USGS TIGER
TIGER/Line files are created by the US Census Bureau and cover the entire US. They are often referred simply as
TIGER files. For more information see: http://www.census.gov/geo/www/tiger/.
7.1. Data Input
492
MapServer Documentation, Release 7.0.6
File listing
TIGER/Line files are text files and directory-based data sources. For example, one county folder TGR06059 contains
several associated files:
TGR06059.RT1
TGR06059.RT6
TGR06059.RTC
TGR06059.RTR
TGR06059.RT2
TGR06059.RT7
TGR06059.RTH
TGR06059.RTS
TGR06059.RT4
TGR06059.RT8
TGR06059.RTI
TGR06059.RTT
TGR06059.RT5
TGR06059.RTA
TGR06059.RTP
TGR06059.RTZ
Data Access / Connection Method
• TIGER/Line access occurs through an OGR CONNECTION
• The full path to the directory containing the associated files is required in the CONNECTION string.
• The feature type is specified in the DATA parameter
OGRINFO Examples
Using ogrinfo on a TIGER directory to retrieve feature types:
> ogrinfo TGR06059 (NOTE that this is a directory)
ERROR 4: Tiger Driver doesn't support update.
Had to open data source read-only.
INFO: Open of `TGR06059'
using driver `TIGER' successful.
1: CompleteChain (Line String)
2: AltName (None)
3: FeatureIds (None)
4: ZipCodes (None)
5: Landmarks (Point)
6: AreaLandmarks (None)
7: Polygon (None)
8: PolygonCorrections (None)
9: EntityNames (Point)
10: PolygonEconomic (None)
11: IDHistory (None)
12: PolyChainLink (None)
13: PIP (Point)
14: TLIDRange (None)
15: ZeroCellID (None)
16: OverUnder (None)
17: ZipPlus4 (None)
Using ogrinfo to examine the structure of the TIGER feature type CompleteChain:
> ogrinfo TGR06059 CompleteChain -summary
ERROR 4: Tiger Driver doesn't support update.
Had to open data source read-only.
INFO: Open of `TGR06059'
using driver `TIGER' successful.
Layer name: CompleteChain
Geometry: Line String
7.1. Data Input
493
MapServer Documentation, Release 7.0.6
Feature Count: 123700
Extent: (-118.125898, 33.333992) - (-117.412987, 33.947512)
Layer SRS WKT:
GEOGCS["NAD83",
DATUM["North_American_Datum_1983",
SPHEROID["GRS 1980",6378137,298.257222101]],
PRIMEM["Greenwich",0],
UNIT["degree",0.0174532925199433]]
MODULE: String (8.0)
TLID: Integer (10.0)
SIDE1: Integer (1.0)
SOURCE: String (1.0)
FEDIRP: String (2.0)
FENAME: String (30.0)
FETYPE: String (4.0)
FEDIRS: String (2.0)
CFCC: String (3.0)
FRADDL: String (11.0)
TOADDL: String (11.0)
FRADDR: String (11.0)
TOADDR: String (11.0)
FRIADDL: String (1.0)
TOIADDL: String (1.0)
FRIADDR: String (1.0)
TOIADDR: String (1.0)
ZIPL: Integer (5.0)
Map File Example:
LAYER
NAME Complete_Chain
TYPE LINE
STATUS DEFAULT
CONNECTIONTYPE OGR
CONNECTION "/path/to/data/tiger/TGR06059"
DATA "CompleteChain"
CLASS
STYLE
COLOR 153 102 0
END
END
END # Layer
Vector field rendering - UVraster
Vector fields are used for instance in meteorology to store/display wind direction and magnitude.
The source is two bands of raster data, the first band represents the U component of the vector, and the second band
the V component. Using the u,v values at a given location we can compute a rotation and magnitude and use that to
draw an arrow of a size proportional to the magnitude and pointing in the direction of the phenomenon (wind, current,
etc.)
For more details about vector fields, refer to: Vector field
A vector field LAYER is a hybrid layer, which has a raster data source as input and vector features as output. The
output features are represented as points. Queries are not supported.
7.1. Data Input
494
MapServer Documentation, Release 7.0.6
Since the data source is a raster, all raster processing options can be used (e.g. RESAMPLE). RESAMPLE=AVERAGE generally gives a good result, and the default. This can be overridden by explicitly specifying
the type of resampling.
Vector field layers are of TYPE point, and have CONNECTIONTYPE uvraster. The raster data set is specified in
DATA. The two bands that define the vector field are specified using PROCESSING BANDS (U first, V second).
The UVraster connection type offers the following attributes:
• [u]: the raw u value
• [v]: the raw v value
• [uv_angle]: the vector angle
• [uv_minus_angle]: the vector angle - opposite direction
• [uv_length]: the vector length (scaled with the UV_SIZE_SCALE optional value)
• [uv_length_2]: half the vector length
Optional PROCESSING settings:
• UV_SPACING: The spacing is simply the distance, in pixels, between arrows to be displayed in the vector field.
Default is 32.
• UV_SIZE_SCALE: The uv size scale is used to convert the vector lengths (magnitude) of the raster to pixels for
a better rendering. Default is 1.
Example of a layer definition:
SYMBOL
NAME "horizline"
TYPE VECTOR
POINTS
0 0
1 0
END # points
END # symbol
SYMBOL
NAME "arrowhead"
TYPE vector
FILLED true
#ANCHORPOINT 0 0.5
POINTS
0 2
4 1
0 0
END # points
END # symbol
SYMBOL
NAME "arrowtail"
TYPE vector
FILLED true
ANCHORPOINT 1 0.5 # to shift the arrowtail
POINTS
0 2
4 1
0 0
-99 -99
0 1
4 1
END # points
7.1. Data Input
495
MapServer Documentation, Release 7.0.6
END # symbol
LAYER
NAME "my_uv_test"
TYPE POINT
STATUS DEFAULT
CONNECTIONTYPE uvraster
DATA /path/wind.grib2
PROCESSING "BANDS=1,2"
PROCESSING "UV_SPACING=40"
PROCESSING "UV_SIZE_SCALE=0.2"
CLASS
STYLE
SYMBOL "horizline"
ANGLE [uv_angle]
SIZE [uv_length]
WIDTH 3
COLOR 100 255 0
END # style
STYLE
SYMBOL "arrowhead"
ANGLE [uv_angle]
SIZE 10
COLOR 255 0 0
POLAROFFSET [uv_length_2] [uv_angle]
END # style
STYLE
SYMBOL "arrowtail"
ANGLE [uv_angle]
SIZE 10
COLOR 255 0 0
POLAROFFSET [uv_length_2] [uv_minus_angle]
END # style
END # class
END # layer
New in version 6.2: (rfc78)
Virtual Spatial Data
Table of Contents
• Virtual Spatial Data
– Types of Databases
– Types of Flat Files
– Steps for Display
This is an OGR extension to MapServer. It allows you to connect to databases that do not explicitly hold spatial data,
as well as flat text files. Your data must have an X and a Y column, and the data may be accessed through an ODBC
connection or a direct pointer to a text file.
The original VirtualSpatialData wiki page may contain additional information.
7.1. Data Input
496
MapServer Documentation, Release 7.0.6
Types of Databases
The VirtualSpatialData OGR extension has been tested with the following databases and should, in theory, support all
ODBC data sources.
• Oracle
• MySQL
• SQL Server
• Access
• PostgreSQL
Types of Flat Files
Comma, tab or custom delimited text/flat files work with VirtualSpatialData.
Steps for Display
1. Create the Datasource Name (DSN)
• Specific notes about creating a DSN on Windows and Linux can be found by searching the MapServer reference
documents site
• On some Windows systems you must create a SYSTEM DSN.
2. Test your Connection
Test your connection with ogrinfo. The syntax for this command is:
> ogrinfo ODBC:user/pass@DSN table
Windows users may not be required to specify a user/password, so the syntax would be:
> ogrinfo ODBC:@DSN table
Example: Accessing a comma separated text file through ODBC using ogrinfo
The following is a snippet of the flat text file coal_dep.txt containing lat/long points:
unknown,na,id,id2,mark,coalkey,coalkey2,long,lat
0.000,0.000,1,1,7,87,87,76.90238,51.07161
0.000,0.000,2,2,7,110,110,78.53851,50.69403
0.000,0.000,3,3,3,112,112,83.22586,71.24420
0.000,0.000,4,4,6,114,114,80.79896,73.41175
If the DSN name is Data_txt, the ogrinfo command to see a list of applicable files in the directory is:
> ogrinfo ODBC:jeff/test@Data_txt
INFO: Open of `ODBC:jeff/test@Data_txt'
using driver `ODBC' successful.
1: coal_dep.csv
2: coal_dep.txt
7.1. Data Input
497
MapServer Documentation, Release 7.0.6
3: coal_dep_nf.txt
4: coal_dep_trim.txt
5: Copy of coal_dep.txt
6: deposit.csv
7: maruia.asc
8: oahuGISbathy.csv
9: oahuGISbathy.txt
10: on_pts.txt
11: on_pts_utm.txt
12: test.txt
13: utm_test.txt
Username and password may be optional, so the following may also be valid:
> ogrinfo ODBC:@Data_txt
Therefore, the command to see more information about one of the specific layers is:
> ogrinfo ODBC:@Data_txt coal_dep.txt
INFO: Open of `ODBC:@Data_txt'
using driver `ODBC' successful.
Layer name: coal_dep.txt
Geometry: Unknown (any)
Feature Count: 266
Layer SRS WKT:
(unknown)
UNKNOWN: String (255.0)
NA: String (255.0)
ID: String (255.0)
ID2: String (255.0)
MARK: String (255.0)
COALKEY: String (255.0)
COALKEY2: String (255.0)
LONG: String (255.0)
LAT: String (255.0)
OGRFeature(coal_dep.txt):0
UNKNOWN (String) = 0.000
....
3. Create a Virtual Data File
This is a file with an ovf extension and looks like the following:
<OGRVRTDataSource>
<OGRVRTLayer name="mylayer">
<SrcDataSource>ODBC:user/pass@DSN</SrcDataSource>
<SrcLayer>tablename</SrcLayer>
<GeometryType>wkbPoint</GeometryType>
<LayerSRS>WGS84</LayerSRS>
<GeometryField encoding="PointFromColumns" x="x" y="y"/>
</OGRVRTLayer>
</OGRVRTDataSource>
More information on ovf files can be found at: http://www.gdal.org/ogr/drv_vrt.html
Example ovf file for coal_dep.txt:
7.1. Data Input
498
MapServer Documentation, Release 7.0.6
<OGRVRTDataSource>
<OGRVRTLayer name="coal-test">
<SrcDataSource>ODBC:Data_txt</SrcDataSource>
<SrcLayer>coal_dep.txt</SrcLayer>
<GeometryField encoding="PointFromColumns" x="Long" y="Lat"/>
<GeometryType>wkbPoint</GeometryType>
</OGRVRTLayer>
</OGRVRTDataSource>
4. Test Virtual Data File with ogrinfo
Use ogrinfo to test your new ovf file, such as:
> ogrinfo coal.ovf coal-test
ERROR 4: Update access not supported for VRT datasources.
Had to open data source read-only.
INFO: Open of `myfile.ovf'
using driver `VRT' successful.
Layer name: coal_dep.txt
Geometry: Unknown (any)
Feature Count: 266
Layer SRS WKT:
(unknown)
UNKNOWN: String (255.0)
NA: String (255.0)
ID: String (255.0)
ID2: String (255.0)
MARK: String (255.0)
...
5. Mapfile Layer
Using an ovf file your layer may look like:
LAYER
CONNECTION "coal.ovf"
CONNECTIONTYPE OGR
DATA "coal-test"
METADATA
"wms_srs"
"4326"
"wms_title"
"coal-test"
END
NAME "coal-test"
SIZEUNITS PIXELS
STATUS ON
TOLERANCE 0
TOLERANCEUNITS PIXELS
TYPE POINT
UNITS METERS
CLASS
STYLE
COLOR 255 0 0
MAXSIZE 100
7.1. Data Input
499
MapServer Documentation, Release 7.0.6
MINSIZE 1
SIZE 6
SYMBOL "star"
END
END
END
Note: For the CONNECTION, you can specify an absolute path, or a relative path. Relative paths are interpreted
relative to the SHAPEPATH first, if not found then MapServer will try again relative to the .map location. For more
information about connection rules please read the MapServer OGR document.
Or you may specify the ovf contents inline such as:
LAYER
CONNECTION "<OGRVRTDataSource>
<OGRVRTLayer name='coal-test'>
<SrcDataSource>ODBC:@Data_txt</SrcDataSource>
<SrcLayer>coal_dep.txt</SrcLayer>
<GeometryField encoding='PointFromColumns' x='Long' y='Lat'/>
<GeometryType>wkbPoint</GeometryType>
</OGRVRTLayer>
</OGRVRTDataSource>"
CONNECTIONTYPE OGR
DATA "coal-test"
METADATA
"wms_srs"
"4326"
"wms_title"
"coal-test"
END
NAME "coal-test"
SIZEUNITS PIXELS
STATUS ON
TOLERANCE 0
TOLERANCEUNITS PIXELS
TYPE POINT
UNITS METERS
CLASS
STYLE
COLOR 255 0 0
MAXSIZE 100
MINSIZE 1
SIZE 6
SYMBOL "star"
END
END
END
6. Test your Mapfile
The first thing you should try is to use the shp2img utility:
shp2img -m mymapfile.map -o test.png
Once you successfully created a map image, then try your application. Note Windows users may come across a
problem where shp2img works but their application throws an error similar to this:
7.1. Data Input
500
MapServer Documentation, Release 7.0.6
Warning: [MapServer Error]: msOGRFileOpen(): Open failed for OGR connection `coal.ovf
˓→'.
Unable to initialize ODBC connection to DSN for jeff/test@Data_txt,
[Microsoft][ODBC Driver Manager] Data source name not found
and no default driver specified in D:\ms4w\Apache\htdocs\quickmap.php on line 40
If that happens you should make sure you have created a System DSN.
WFS
WFS is an Open Geospatial Consortium (OGC) specification. For more information about the format itself, see:
http://www.opengeospatial.org/standards/wfs
WFS allows a client to retrieve geospatial data encoded in Geography Markup Language (GML) from multiple Web
Feature Services. GML is built on the standard web language XML.
WFS differs from the popular Web Map Service (WMS) specification in that WFS returns a subset of the data in valid
GML format, not just a graphic image of data.
Capabilities
Requesting the capabilities using the GetCapabilities request to a WFS server returns an XML document showing
what layers and projections are available, etc. Example of a WFS GetCapabilities URL:
http://demo.mapserver.org/cgi-bin/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=
GetCapabilities
Example of the Resulting XML from GetCapabilties:
...
<FeatureTypeList>
<Operations>
<Query/>
</Operations>
<FeatureType>
<Name>continents</Name>
<Title>World continents</Title>
<SRS>EPSG:4326</SRS>
<LatLongBoundingBox minx="-180" miny="-90" maxx="180" maxy="83.6274"/>
</FeatureType>
<FeatureType>
<Name>cities</Name>
<Title>World cities</Title>
<SRS>EPSG:4326</SRS>
<LatLongBoundingBox minx="-178.167" miny="-54.8" maxx="179.383" maxy="78.9333"/>
</FeatureType>
</FeatureTypeList>
...
Data Access / Connection Method
• WFS access is a core MapServer feature. MapServer currently supports WFS version 1.0.0.
• WFS access is also supported through OGR.
7.1. Data Input
501
MapServer Documentation, Release 7.0.6
• CONNECTIONTYPE WFS or CONNECTIONTYPE OGR must be used (see the OGR documentation for
details on how to use WFS through OGR).
• WFS layers can be requested through a layer in a map file, or you can request the GML directly through the
browser with a GetFeature request. You can specify a specific layer with the TypeName request. In a map file
the name/value pairs should be put into a METADATA object.
• You can limit the number of features returned in the GML by using the MaxFeatures option (e.g. &MAXFEATURES=100).
Example of a WFS Request Directly Through the Browser:
The following URL requests the GML for the layer continents. (see the GetCapabilities above for the possible layers
available on this test server) . The URL is all one line, broken up here for readability (click here for a working link).
http://demo.mapserver.org/cgi-bin/wfs?
SERVICE=WFS&
VERSION=1.0.0&
REQUEST=getfeature&
TYPENAME=continents&
MAXFEATURES=100
Map File Example
LAYER
NAME "continents"
TYPE POLYGON
STATUS ON
CONNECTION "http://demo.mapserver.org/cgi-bin/wfs?"
CONNECTIONTYPE WFS
METADATA
"wfs_typename"
"continents"
"wfs_version"
"1.0.0"
"wfs_connectiontimeout" "60"
"wfs_maxfeatures"
"10"
END
PROJECTION
"init=epsg:4326"
END
CLASS
NAME "Continents"
STYLE
COLOR 255 128 128
OUTLINECOLOR 96 96 96
END
END
END # Layer
7.1.2 Raster Data
Author Frank Warmerdam
Contact warmerdam at pobox.com
Last Updated 2013/07/04
7.1. Data Input
502
MapServer Documentation, Release 7.0.6
Table of Contents
• Raster Data
– Introduction
– How are rasters added to a Map file?
– Supported Formats
– Rasters and Tile Indexing
– Raster Warping
– 24bit RGB Rendering
– Special Processing Directives
– Raster Query
– Raster Display Performance Tips
– Preprocessing Rasters
– Georeference with World Files
Introduction
MapServer supports rendering a variety of raster file formats in maps. The following describes some of the supported
formats, and what capabilities are supported with what formats.
This document assumes that you are already familiar with setting up MapServer Mapfile, but does explain the raster
specific aspects of mapfiles.
How are rasters added to a Map file?
A simple raster layer declaration looks like this. The DATA file is interpreted relative to the SHAPEPATH, much like
shapefiles.
LAYER
NAME "JacksonvilleNC_CIB"
DATA "Jacksonville.tif"
TYPE RASTER
STATUS ON
END
Though not shown rasters can have PROJECTION, METADATA, PROCESSING, MINSCALE, and MAXSCALE information. It cannot have labels, CONNECTION, CONNECTIONTYPE, or FEATURE information.
Classifying Rasters
Rasters can be classified in a manner similar to vectors, with a few exceptions.
There is no need to specify a CLASSITEM. The raw pixel value itself (“[pixel]”) and, for paletted images, the red, green
and blue color associated with that pixel value (“[red]”, “[green]” and “[blue]”) are available for use in classifications.
When used in an evaluated expression the pixel, red, green and blue keywords must be in lower case.
7.1. Data Input
503
MapServer Documentation, Release 7.0.6
LAYER
NAME "JacksonvilleNC_CIB"
DATA "Jacksonville.tif"
TYPE RASTER
STATUS ON
CLASSITEM "[pixel]"
# class using simple string comparison, equivalent to ([pixel] = 0)
CLASS
EXPRESSION "0"
STYLE
COLOR 0 0 0
END
END
# class using an EXPRESSION using only [pixel].
CLASS
EXPRESSION ([pixel] >= 64 AND [pixel] < 128)
STYLE
COLOR 255 0 0
END
END
# class using the red/green/blue values from the palette
CLASS
NAME "near white"
EXPRESSION ([red] > 200 AND [green] > 200 AND [blue] > 200)
STYLE
COLOR 0 255 0
END
END
# Class using a regular expression to capture only pixel values ending in 1
CLASS
EXPRESSION /*1/
STYLE
COLOR 0 0 255
END
END
END
As usual, CLASS definitions are evaluated in order from first to last, and the first to match is used. If a CLASS has a
NAME attribute it may appear in a LEGEND. Only the COLOR, EXPRESSION and NAME parameters within a CLASS
definition are utilized for raster classifications. The other styling or control information is ignored.
Raster classifications always take place on only one raster band. It defaults to the first band in the referenced file,
but this can be altered with the BANDS PROCESSING directive. In particular this means that including even a single
CLASS declaration in a raster layer will result in the raster layer being rendered using the one band classification rules
instead of other rules that might have applied (such as 3 band RGB rendering).
Classifying Non-8bit Rasters
As of MapServer 4.4 support has been added for classifying non-8bit raster inputs. That is input rasters with values
outside the range 0-255. Mostly this works transparently but there are a few caveats and options to provide explicit
control.
Classifying raster data in MapServer is accomplished by pre-classifying all expected input values and using that table
of classification results to lookup each pixel as it is rendered. This is done because evaluating a pixel value against a
series of CLASS definitions is relatively expensive to do for the hundreds of thousands of pixels in a typical rendered
image.
7.1. Data Input
504
MapServer Documentation, Release 7.0.6
For simple 8bit inputs, only 256 input values need to be pre-classified. But for non-8bit inputs more values need to be
classified. For 16bit integer inputs all 65536 possible input values are pre-classified. For floating point and other input
data types, up to 65536 values are pre-classified based on the maximum expected range of input values.
The PROCESSING directive can be used to override the range of values to be pre-classified, or the number of values (aka Buckets) in that range to classify. The SCALE=min,max PROCESSING directive controls the range. The
SCALE_BUCKETS PROCESSING directive controls the number of buckets. In some cases rendering can be accelerated considerable by selecting a restricted range of input values and a reduced number of scaling values (buckets).
The following example classifies a floating raster, but only 4 values over the range -10 to 10 are classified. In particular,
the values classified would be -7.5, -2.5, 2.5, and 7.5 (the middle of each “quarter” of the range). So those four value
are classified, and one of the classification results is selected based on which value is closest to the pixel value being
classified.
LAYER
NAME grid1
TYPE raster
STATUS default
DATA data/float.tif
PROCESSING "SCALE=-10,10"
PROCESSING "SCALE_BUCKETS=4"
CLASS
NAME "red"
EXPRESSION ([pixel] < -3)
STYLE
COLOR 255 0 0
END
END
CLASS
NAME "green"
EXPRESSION ([pixel] >= -3 and [pixel] < 3)
STYLE
COLOR 0 255 0
END
END
CLASS
NAME "blue"
EXPRESSION ([pixel] >= 3)
STYLE
COLOR 0 0 255
END
END
END
Supported Formats
Since version 6.2, MapServer raster input support is through the GDAL raster library only.
More information on GDAL can be found at http://www.gdal.org, including the supported formats list. Some of the
advanced MapServer raster features, such as resampling, RGB color cube generation and automatic projection capture
only work with raster formats used through GDAL. GDAL is normally built and installed separately from MapServer,
and then enabled during the build of MapServer using the –with-gdal configuration switch.
To find out if GDAL support is built into a particular MapServer executable, use the -v flag to discover what build
options are enabled. To find out what GDAL formats are available, the “gdalinfo –formats” command may be used.
For example:
7.1. Data Input
505
MapServer Documentation, Release 7.0.6
warmerda@gdal2200[124]% mapserv -v
MapServer version 6.2.0 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG
SUPPORTS=PROJ SUPPORTS=GD SUPPORTS=AGG SUPPORTS=FREETYPE
SUPPORTS=CAIRO SUPPORTS=OPENGL SUPPORTS=ICONV SUPPORTS=WMS_SERVER
SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT
SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI
SUPPORTS=THREADS SUPPORTS=GEOS INPUT=JPEG INPUT=POSTGIS INPUT=OGR
INPUT=GDAL INPUT=SHAPEFILE
warmerda@gdal2200[18]% gdalinfo --formats
Supported Formats:
VRT (rw+v): Virtual Raster
GTiff (rw+vs): GeoTIFF
NITF (rw+vs): National Imagery Transmission Format
RPFTOC (rovs): Raster Product Format TOC format
ECRGTOC (rovs): ECRG TOC format
...
Rasters and Tile Indexing
When handling very large raster layers it is often convenient, and higher performance to split the raster image into a
number of smaller images. Each file is a tile of the larger raster mosaic available for display. The list of files forming a
layer can be stored in a shapefile with polygons representing the footprint of each file, and the name of the files. This
is called a ‘TILEINDEX’ and works similarly to the same feature in vector layers. The result can be represented in
the Mapfile as one layer, but MapServer will first scan the tile index, and ensure that only raster files overlapping the
current display request will be opened.
The following example shows a simple example. No DATA statement is required because MapServer will fetch the
filename of the raster files from the Location attribute column in the hp2.dbf file for records associated with polygons
in hp2.shp that intersect the current display region. The polygons in hp2.shp should be rectangles representing the
footprint of the corresponding file. Note that the files do not have to be all the same size, the formats can vary and they
can even overlap (later files will be drawn over earlier ones).
Starting with MapServer 6.4, the files can have different coordinate system (projection). This requires specifying the
TILESRS keyword and generating the tileindex with a few additional options. See Tileindexes with tiles in different
projections.
LAYER
NAME "hpool"
STATUS ON
TILEINDEX "hp2.shp"
TILEITEM "Location"
TYPE RASTER
END
The filenames in the tileindex are searched for relative to the SHAPEPATH or map file, not relative to the tileindex.
Great care should be taken when establishing the paths put into the tileindex to ensure they will evaluate properly in
use. Often it is easiest to place the tileindex in the SHAPEPATH directory, and to create the tileindex with a path
relative to the SHAPEPATH directory. When all else fails, absolute paths can be used in tileindex, but then they cannot
be so easily moved from system to system.
While there are many ways to produce TILEINDEX shapefiles for use with this command, one option is the gdaltindex
program, part of the GDAL utility suite. The gdaltindex program will automatically generate a tile index shapefile
from a list of GDAL supported raster files passed on the command line.
7.1. Data Input
506
MapServer Documentation, Release 7.0.6
Usage: gdaltindex [-tileindex field_name] index_file [gdal_file]*
% gdaltindex doq_index.shp doq/*.tif
Tile Index Notes
• The shapefile (index_file) will be created if it doesn’t already exist.
• The default tile index field is ‘location’.
• Simple rectangular polygons must be generated in the same coordinate system as the raster layer. If the files in
the tileindex are not in the same projection as the raster layer, or are in heterogeneous projections, the TILESRS
keyword must be specified in the LAYER definition. See Tileindexes with tiles in different projections
• Raster filenames will be put in the file exactly as they are specified on the commandline.
• Many problems with tile indexes relate to how relative paths in the tile index are evaluated. They should be
evaluated relative to the SHAPEPATH if one is set, otherwise relative to the tileindex file. When in doubt
absolute paths may avoid path construction problems.
The gdaltindex program is built as part of GDAL. Prebuilt binaries for GDAL including the gdaltindex program can
be downloaded as part of the OSGeo4W, FWTools and MS4W distributions.
See also:
Tile Indexes
Raster Warping
MapServer is able to resample GDAL rasters on the fly into new projections. Non-GDAL rasters may only be up or
down sampled without any rotation or warping.
Raster warping kicks in if the projection appears to be different for a raster layer than for the map being generated.
Warped raster layers are significantly more expensive to render than normal raster layers with rendering time being
perhaps 2-4 times long than a normal layer. The projection and datum shifting transformation is computed only at
selected points, and generally linearly interpolated along the scanlines (as long as the error appears to be less than
0.333 pixels.
In addition to reprojecting rasters, the raster warping ability can also apply rotation to GDAL rasters with rotational
coefficients in their georeferencing information. Currently rotational coefficients won’t trigger raster warping unless
the map and layer have valid (though matching is fine) projection definitions.
24bit RGB Rendering
Traditionally MapServer has been used to produce 8 bit pseudo-colored map displays generated from 8bit greyscale
or pseudocolored raster data. However, if the raster file to be rendered is actually 24bit (a red, green and blue band)
then additional considerations come into play. Rendering of 24bit imagery is supported via the GDAL renderer.
If the output is still 8bit pseudo-colored (the IMAGEMODE is PC256 in the associated OUTPUTFORMAT declaration)
then the full 24bit RGB colors for input pixels will be converted to a color in the colormap of the output image. By
default a color cube is used. That is a fixed set of 175 colors providing 5 levels of red, 7 levels of green and 5 levels
of blue is used, plus an additional 32 greyscale color entries. Colors in the input raster are mapped to the closest color
in this color cube on the fly. This substantial degrades color quality, especially for smoothly changing images. It also
fills up the colors table, limited to 256 colors, quite quickly.
7.1. Data Input
507
MapServer Documentation, Release 7.0.6
A variation on this approach is to dither the image during rendering. Dithering selects a color for a pixel in a manner
that “diffuses error” over pixels. In an area all one color in the source image, a variety of output pixel colors would
be selected such that the average of the pixels would more closely approximate the desired color. Dithering also takes
advantage of all currently allocated colors, not just those in the color cube. Dithering requires GDAL 1.1.9 or later, and
is enabled by providing the PROCESSING “DITHER=YES” option in the mapfile. Dithering is more CPU intensive
than using a simple color cube, and should be avoided if possible in performance sensitive situations.
The other new possibility for handling 24bit input imagery in MapServer 4.0 or later, is to produce 24bit output images.
The default “IMAGETYPE png24” or “IMAGETYPE jpeg” declaration may be used to produce a 24bit PNG output
file, instead of the more common 8bit pseudo-colored PNG file. The OUTPUTFORMAT declaration provides for
detailed control of the output format. The IMAGEMODE RGB and IMAGEMODE RGBA options produce 24bit and
32bit (24bit plus 8bit alpha/transparency) for supported formats.
Special Processing Directives
As of MapServer 4.0, the PROCESSING parameter was added to the LAYER of the Mapfile. It is primarily used to
pass specialized raster processing options to the GDAL based raster renderer. The following processing options are
supported in MapServer 4.0 and newer.
BANDS=red_or_grey[,green,blue[,alpha]] This directive allows a specific band or bands to be selected from a raster
file. If one band is selected, it is treated as greyscale. If 3 are selected, they are treated as red, green and blue. If
4 are selected they are treated as red, green, blue and alpha (opacity).
Example:
PROCESSING "BANDS=4,2,1"
COLOR_MATCH_THRESHOLD=n Alter the precision with which colors need to match an entry in the color
table to use it when producing 8bit colormapped output (IMAGEMODE PC256). Normally colors from a raster
colormap (or greyscale values) need to match exactly. This relaxes the requirement to being within the specified
color distance. So a COLOR_MATCH_THRESHOLD of 3 would mean that an existing color entry within 3
(sum of difference in red, green and blue) would be used instead of creating a new colormap entry. Especially
with greyscale raster layers, which would normally use all 256 color entries if available, this can be a good way
to avoid “stealing” your whole colormap for a raster layer. Normally values in the range 2-6 will give good
results.
Example:
PROCESSING "COLOR_MATCH_THRESHOLD=3"
DITHER=YES This turns on error diffusion mode, used to convert 24bit images to 8bit with error diffusion to get
better color results.
Example:
PROCESSING "DITHER=YES"
EXTENT_PRIORITY=WORLD Override GDAL with a world file.
Example:
PROCESSING "EXTENT_PRIORITY=WORLD"
LOAD_FULL_RES_IMAGE=YES/NO This option affects how image data is loaded for the resampler when reprojecting or otherwise going through complex resampling (as opposed to the fast default image decimation code
path). This forces the source image to be loaded at full resolution if turned on (default is NO). This helps work
around problems with default image resolution selection in when radical warping is being done. It can result in
very slow processing if the source image is large.
7.1. Data Input
508
MapServer Documentation, Release 7.0.6
LOAD_WHOLE_IMAGE=YES/NO This option affects how image data is loaded for the resampler (as above). This
option, if turned on, will cause the whole source image to be loaded and helps make up for problem identifying
the area required, usually due to radical image reprojection near a dateline or projection “horizon”. The default
is NO. Turning this on can dramatically affect rendering performance and memory requirements.
LUT[_n]=<lut_spec> This directive (MapServer 4.9+) instructs the GDAL reader to apply a custom LUT (lookup
table) to one or all color bands as a form of on the fly color correction. If LUT is used, the LUT is applied to all
color bands. If LUT_n is used it is applied to one color band (n is 1 for red, 2 for green, 3 for blue, 4 for alpha).
The LUT can be specified inline in the form:
<lut_spec> = <in_value>:<out_value>[,<in_value>:<out_value>]*
This essentially establish particular input values which are mapped to particular output values. The list implicitly
begins with 0:0, and 255:255. An actual 256 entry lookup table is created from this specification, linearly
interpolating between the values. The in values must be in increasing order. The LUT specification may also be
in a text file with the <lut_spec> being the filename. The file contents should be in the same syntax, and the file
is searched relative to the mapfile.
Example:
PROCESSING
PROCESSING
PROCESSING
or
PROCESSING
"LUT_1=red.lut"
"LUT_2=green.lut"
"LUT_3=blue.lut"
"LUT=100:30,160:128,210:200"
As a special case there is also support for GIMP format curve files. That is the text files written out by the
Tools->Color->Curves tool. If this is specified as the filename then it will be internally converted into linear
segments based on the curve control points. Note that this will not produce exactly the same results as the
GIMP because linear interpolation is used between control points instead of curves as used in the GIMP. For a
reasonable number of control points the results should be similar. Also note that GIMP color curve files include
an overall “value” curve, and curves for red, green, blue and alpha. The value curve and the appropriate color
curve will be composed internally to produce the final LUT.
Example:
PROCESSING "LUT=munich.crv"
OVERSAMPLE_RATIO=double Default is 2.5.
PLE_RATIO.
Rendering time will increase with increasing OVERSAM-
Example:
PROCESSING "OVERSAMPLE_RATIO=1.0"
RESAMPLE=NEAREST/AVERAGE/BILINEAR This option can be used to control the resampling kernel used
sampling raster images. The default (and fastest) is NEAREST. AVERAGE will perform compute the average
pixel value of all pixels in the region of the disk file being mapped to the output pixel (or possibly just a sampling
of them). BILINEAR will compute a linear interpolation of the four pixels around the target location. This topic
is discussed in more detail in rfc4.
Resampling options other than NEAREST result in use of the generalized warper and can dramatically slow
down raster processing. Generally AVERAGE can be desirable for reducing noise in dramatically downsampled
data, and can give something approximating antialiasing for black and white linework. BILINEAR can be
helpful when oversampling data to give a smooth appearance.
Example (chose one):
7.1. Data Input
509
MapServer Documentation, Release 7.0.6
PROCESSING "RESAMPLE=NEAREST"
PROCESSING "RESAMPLE=AVERAGE"
PROCESSING "RESAMPLE=BILINEAR"
SCALE[_n]=AUTO or min,max This directive instructs the GDAL reader to pre-scale the incoming raster data. It
is primarily used to scale 16bit or floating point data to the range 0-255, but can also be used to constrast stretch
8bit data. If an explicit min/max are provided then the input data is stretch (or squished) such that the minimum
value maps to zero, and the maximum to 255. If AUTO is used instead, a min/max is automatically computed.
To control the scaling of individual input bands, use the SCALE_1, SCALE_2 and SCALE_3 keywords (for
red, green and blue) instead of SCALE which applies to all bands.
Example:
PROCESSING
or
PROCESSING
PROCESSING
PROCESSING
"SCALE=AUTO"
"SCALE_1=409,1203"
"SCALE_2=203,296"
"SCALE_3=339,1004"
WORLDFILE=<file> Specifies an alternative world file (for georeferencing). If a path only is specified, the base
name of the dataset will be appended. The suffix (.wld / .tfw / ...) can be omitted.
Example:
PROCESSING "WORLDFILE=/path/"
or
PROCESSING "WORLDFILE=/path/file.wld"
or
PROCESSING "WORLDFILE=/path/file"
Raster Query
A new feature added in MapServer 4.4 is the ability to perform queries on rasters in a manner similar to queries
against vector layers. Raster queries on raster layers return one point feature for each pixel matching the query. The
point features will have attributes indicating the value of different bands at that pixel, the final rendering color and
the class name. The resulting feature can be directly access in MapScript, or processed through templates much like
normal vector query results. Only raster layers with a query TEMPLATE associated can be queried, even for the query
methods that don’t actually use the query template (much like vector data).
Raster query supports QueryByPoint, QueryByRect, and QueryByShape. QueryByPoint supports single and multiple
result queries. Other query operations such as QueryByIndex, QueryByIndexAdd, QueryByAttributes and QueryByFeature are not supported for raster layers.
Raster layers do not support saving queries to disk, nor query maps.
Raster queries return point features with some or all of the following attributes:
x georeferenced X location of pixel.
y georeferenced Y location of pixel.
value_list a comma separated list of the values of all selected bands at the target pixel.
value_n the value for the n’th band in the selected list at this pixel (zero based). There is one value_n
entry for each selected band.
class Name of the class this pixel is a member of (classified layers only).
red red component of the display color for this pixel.
7.1. Data Input
510
MapServer Documentation, Release 7.0.6
green green component of the display color for this pixel.
blue blue component of the display color for this pixel.
The red, green and blue attribute are intended to be the final color the pixel would be rendered with, but in some subtle
cases it can be wrong (ie. classified floating point results). The selected bands are normally the band that would be
used to render the layer. For a pure query-only layer BANDS PROCESSING directive can be used to select more
bands than could normally be used in a render operation. For instance for a 7 band landsat scene a PROCESSING
“BANDS=1,2,3,4,5,6,7” directive could be used to get query results for all seven bands in results to a query operation.
Care should be taken to avoid providing a large query area (selecting a lot of pixels) as each selected pixel requires
over 100 bytes of memory for temporary caching. The RASTER_QUERY_MAX_RESULT PROCESSING item can
be used to restrict the maximum number of query results that will be returned. The default is one million which would
take on the order of 100MB of RAM.
Query results can be returned as HTML via the normal substitution into query template HTML. Query results are also
accessible via WMS GetFeatureInfo calls, and from MapScript. The following example shows executing a feature
query from Python MapScript and fetching back the results:
map = mapscript.Map('rquery.map')
layer = map.getLayer(0)
pnt = mapscript.Point()
pnt.x = 440780
pnt.y = 3751260
layer.queryByPoint( map, pnt, mapscript.MS_MULTIPLE, 180.0 )
layer.open()
for i in range(1000):
result = layer.getResult( i )
if result is None:
break
s = layer.getShape( result )
for i in range(layer.numitems):
print '%s: %s' % (layer.getItem(i), s.getValue(i))
layer.close()
This following is a simple example query TEMPLATE file. The raster pixel attributes will be substituted in before the
query result is returned to the user as HTML.
Pixel:<br>
values=[value_list]<br>
value_0=[value_0]<br>
value_1=[value_1]<br>
value_2=[value_2]<br>
RGB = [red],[green],[blue]<p>
Class = [class]<br>
Internally raster query results are essentially treated as a set of temporary features cached in RAM. Issuing a new
query operation clears the existing query cache on the layer. The transitory in-memory representation of raster query
results is also responsible for the inability to save raster query results since saved query results normally only contain
the feature ids, not the entire features. Some addition information is available in the RasterQuery Wiki topic.
7.1. Data Input
511
MapServer Documentation, Release 7.0.6
Raster Display Performance Tips
• Build overview levels for large rasters to ensure only a reasonable amount of data needs to be touched to display
an overview of a large layer. Overviews can be implemented as a group of raster layers at different resolutions,
using MINSCALEDENOM, and MAXSCALEDENOM to control which layers are displayed at different resolutions. Another, perhaps easier way, is to build overviews for GDAL supported formats using the gdaladdo
utility.
• When using tileindexes to manage many raster files as a single file, it is especially important to have an overview
layer that kicks in at high scales to avoid having to open a large number of raster files to fulfill the map request.
• Preprocess RGB images to eightbit with a colormap to reduce the amount of data that has to be read, and the
amount of computation to do on the fly.
• For large images use tiling to reduce the overhead for loading a view of a small area. This can be accomplished
using the TILEINDEX mechanism of the mapfile, or by creating a tiled format file (ie. TIFF with GDAL).
• Ensure that the image is kept on disk in the most commonly requested projection to avoid on-the-fly image
warping which is fairly expensive.
• If you are getting debug output from MapServer in your web server log file, check to see if the message msResampleGDALToMap in effect appears. If so, the raster layer is being resampled. If you don’t think it should be
resampled carefully review your map file to ensure that the layer projection exactly matches the map projection
or that the layer has no projection definition.
Preprocessing Rasters
The following operations use GDAL commandline utilities, some of which are python scripts. They are generally
available on any GDAL installation with python support.
Producing Tiled Datasets
The TIFF and Erdas Imagine formats support internal tiling within files, and will generally give better display speed
for local map requests from large images. To produce a GeoTIFF file in internally tiled format using the TILED=YES
creation option with the gdal_translate utility:
gdal_translate -co TILED=YES original.tif tiled.tif
Erdas Imagine (HFA) files are always tiled, and can be larger than 4GB (the GeoTIFF limit). Use a command like the
following to translate a raster to Imagine format:
gdal_translate -of HFA original.tif tiled.img
Reducing RGB to 8bit
Rendering and returning 24bit images (especially as PNG) can be quite expensive in render/compress time and bandwidth. Pre-reducing raster data to 8bit can save disk space, processing time, and bandwidth. However, such a color
reduction also implicitly reduces the quality of the resulting map. The color reduction can be done on the fly by
MapServer but this requires even more processing. A faster approach is to pre-reduce the colors of 24bit imagery to
8bit. This can be accomplished with the GDAL rgb2pct.py script like this:
rgb2pct.py original.tif 8bit.tif
7.1. Data Input
512
MapServer Documentation, Release 7.0.6
By default images will be reduced to 256 colors but this can mean there are not enough colors to render other colors
in the map. So it may be desired to reduce to even less colors:
rgb2pct.py -n 200 original.tif 8bit.tif
Downsampling to 8bit should be done before internal tiling and overview building. The rgb2pct.py script tries to
compute an optimal color table for a given image, and then uses error diffusion during the 24bit to 8bit reduction.
Other packages (such as ImageMagick or Photoshop) may have alternative color reduction algorithms that are more
appropriate for some uses.
Building Internal Overviews
Most GDAL supported raster formats can have overviews pre-built using the gdaladdo utility. However, a few formats,
such as JPEG2000, MrSID, and ECW already contain implicit overviews in the format themselves and will not generally benefit from external overviews. For other formats (such as GeoTIFF, and Erdas Imagine format) use a command
like the following to build overviews:
gdaladdo tile.tif 2 4 8 16 32 64 128
The above would build overviews at x2 through x128 decimation levels. By default it uses “nearest neighbour”
downsampling. That is one of the pixels in the input downsampled area is selected for each output pixel. For some
kinds of data averaging can give much smoother overview results, as might be generated with this command:
gdaladdo -r average tiled.tif 2 4 8 16 32 64 128
Note that overview building should be done after translating to a final format. Overviews are lost in format conversions
using gdal_translate. Also, nothing special needs to be done to make MapServer use GDAL generated overviews. They
are automatically picked up by GDAL when mapserver requests a reduced resolution map.
Building External Overviews
When working with large collections of raster files using a MapServer tileindex, it is desirable to build reduced
resolution overview layers that kick in at high scales (using MINSCALEDENOM / MAXSCALEDENOM to control
which layer activates). Preparing the overviews can be a somewhat complex process. One approach is to use the
gdal_merge.py script to downsample and mosaic all the images. For instance if we want to produce an overview of
many 1meter ortho photos with 250 meter pixels we might do something like:
gdal_merge.py -o overview.tif -ps 250 250 ortho_*.tif
The gdal_merge.py utility suffers from a variety of issues, including no support for different resampling kernels. With
GDAL 1.3.2 or later it should be able to accomplish something similar with the more flexible gdalwarp utility:
gdalwarp -rc -tr 250 250 ortho_*.tif overview.tif
In some cases the easiest way of generating an overview is to let MapServer do it using the shp2img utility. For
instance if the tileindex layer is called ‘’orthos” we could do something like:
shp2img -m ortho.map -l orthos -o overview.png
Note that the overview will be generated with the extents and size in the .map file, so it may be necessary to temporarily
adjust the map extents and size values to match the raster extents and the desired output size. Also, if using this method,
don’t leave large files in PNG (or GIF or JPEG) format as they are slow formats to extract subareas from.
7.1. Data Input
513
MapServer Documentation, Release 7.0.6
Georeference with World Files
World files are a simple mechanism for associating georeferencing (world coordinates) information with raster files.
ESRI was the first company to propagate the use of world files, and they are often used with TIFF instead of embedding
georeferencing information in the file itself.
The world file contents look like the following. The first coefficient is the X pixel size. The second and third are
rotational/shear coefficients (and should normally be 0.0). The fourth is the Y pixel size, normally negative indicating
that Y decreases as you move down from the top left origin. The final two values are the X and Y location of the
center of the top left pixel. This example is for an image with a 2m x 2m pixel size, and a top left origin at (356800E,
5767999N):
2
0.0000000000
0.0000000000
-2
356800.00
5767999.00
The name of the world file is based on the file it relates to. For instance, the world file for aerial.tif might be aerial.tfw.
Conventions vary for appropriate endings, but with MapServer the extension .wld is always OK for world files.
7.1.3 Virtual File System
Author Jeff McKenna
Contact jmckenna at gatewaygeomatics.com
Last Updated 2016-06-23
Table of Contents
• Virtual File System
– Virtual File System
* More Information on Virtual File System
* Display Compressed File Directly in MapServer
· Step 1: Verify Format is “Virtual” Enabled
· Step 2: Test Access through ogrinfo/gdalinfo
· Step 3: Configure MapServer Layer
· Step 4: Test your Mapfile
* Display Remote Compressed File Directly in MapServer
· Test Access through ogrinfo/gdalinfo
· Configure MapServer Layer
* Display Remote (RASTER) File Directly in MapServer
· Test Access through gdalinfo
· Configure MapServer Layer
7.1. Data Input
514
MapServer Documentation, Release 7.0.6
Virtual File System
Starting with GDAL version 1.8.0, it is possible to read and display “virtual” VECTOR and RASTER files, such as
to a remote file by pointing to a URL, or a compressed local .zip file that contains an OGR data source, and display
that in MapServer. Useful mapfile parameters include /vsizip/, /vsigzip/, /vsitar/, /vsicurl/
More Information on Virtual File System
• Blog post by initial developer Even Rouault
• GDAL Trac page
Display Compressed File Directly in MapServer
The following example uses a compressed shapefile, “test.zip”, that contains 3 files:
test.shp
test.dbf
test.zip
Step 1: Verify Format is “Virtual” Enabled
Execute ogrinfo –formats (for vector) or gdalinfo –formats (for raster) to check if the format lists a “v” beside the
driver name, such as:
> ogrinfo --formats
Supported Formats:
PCIDSK -raster,vector- (rw+v): PCIDSK Database File
netCDF -raster,vector- (rw+s): Network Common Data Format
PDF -raster,vector- (rw+vs): Geospatial PDF
DB2ODBC -raster,vector- (rw+): IBM DB2 Spatial Database
ESRI Shapefile -vector- (rw+v): ESRI Shapefile
MapInfo File -vector- (rw+v): MapInfo File
...
The “(rw+v)” beside shapefile indicates that virtual files are supported.
Step 2: Test Access through ogrinfo/gdalinfo
Use ogrinfo with /vsizip/ to summarize the features of the zipped shapefile. Follow the OGR document examples for
how to use the ogrinfo command with layers, such as:
> ogrinfo /vsizip/test.zip/test.shp test -summary
Note that “test.zip” exists in the same directory where we are running the ogrinfo command.
INFO: Open of `/vsizip/test.zip/test.shp'
using driver `ESRI Shapefile' successful.
Layer name: test
Metadata:
7.1. Data Input
515
MapServer Documentation, Release 7.0.6
DBF_DATE_LAST_UPDATE=2000-03-17
Geometry: Polygon
Feature Count: 665
Extent: (-2750564.750000, -936638.500000) - (3583872.500000, 4673125.000000)
Layer SRS WKT:
(unknown)
AREA: Real (15.3)
PERIMETER: Real (15.3)
...
Step 3: Configure MapServer Layer
Once you have verified that you can read the features with ogrinfo (or gdalinfo for raster), then we can try creating a
map in MapServer.
Warning: A full (absolute) path is required for the CONNECTION parameter, for these virtual layers.
LAYER
NAME "test"
TYPE POLYGON
STATUS ON
CONNECTIONTYPE OGR
CONNECTION "/vsizip/C:/ms4w/apps/test/data/test.zip/test.shp"
DATA "test"
CLASS
NAME "test"
STYLE
COLOR 240 240 240
OUTLINECOLOR 199 199 199
END
END
END # layer
Note: You can omit the filename from the connection (test.shp) if there are no other files inside the zip than expected
for a shapefile. When you omit it, the zip is recognized as a directory and it is the same logic as executing ogrinfo on
a directory.
Step 4: Test your Mapfile
Verify that MapServer can generate a map image by using the shp2img utility:
shp2img -m mymapfile.map -o test.png -all_debug 5
msDrawMap(): rendering using outputformat named png (AGG/PNG).
msDrawMap(): WMS/WFS set-up and query, 0.000s
GDAL: GDALOpen(/vsizip/C:/ms4w/apps/test/data/test.zip/test.shp, this=07D691D8)
˓→succeeds as ESRI Shapefile.
Shape: 492 features read on layer 'test'.
GDAL: GDALClose(/vsizip/C:/ms4w/apps/test/data/test.zip/test.shp, this=07D691D8)
msDrawMap(): Layer 0 (test), 0.016s
7.1. Data Input
516
MapServer Documentation, Release 7.0.6
msDrawMap(): Drawing Label Cache, 0.000s
msDrawMap() total time: 0.031s
msSaveImage(ttt.png) total time: 0.000s
msFreeMap(): freeing map at 06289688.
Display Remote Compressed File Directly in MapServer
We can also display an external compressed file, that is accessible through HTTP, using /vsicurl/ with /vsizip/
Test Access through ogrinfo/gdalinfo
> ogrinfo -ro /vsizip/vsicurl/http://download.osgeo.org/mapserver/docs/vsicurl-test.
˓→zip/test.shp test -summary
Configure MapServer Layer
LAYER
NAME "test"
TYPE POLYGON
STATUS ON
CONNECTIONTYPE OGR
CONNECTION "/vsizip/vsicurl/http://download.osgeo.org/mapserver/docs/vsicurl-test.
˓→zip/test.shp"
DATA "test"
CLASS
NAME "test"
STYLE
COLOR 240 240 240
OUTLINECOLOR 199 199 199
END
END
END # layer
Warning: Virtual layers have a “cost” / are not as fast to display in MapServer as regular layers.
Display Remote (RASTER) File Directly in MapServer
Remote raster files can also be accessed through HTTP, using /vsicurl/
Test Access through gdalinfo
> gdalinfo /vsicurl/http://download.osgeo.org/gdal/data/gtiff/small_world.tif
Driver: GTiff/GeoTIFF
Files: /vsicurl/http://download.osgeo.org/gdal/data/gtiff/small_world.tif
Size is 400, 200
7.1. Data Input
517
MapServer Documentation, Release 7.0.6
Coordinate System is:
GEOGCS["WGS 84",
DATUM["WGS_1984",
SPHEROID["WGS 84",6378137,298.257223563,
AUTHORITY["EPSG","7030"]],
AUTHORITY["EPSG","6326"]],
PRIMEM["Greenwich",0],
UNIT["degree",0.0174532925199433],
AUTHORITY["EPSG","4326"]]
Origin = (-180.000000000000000,90.000000000000000)
Pixel Size = (0.900000000000000,-0.900000000000000)
...
Configure MapServer Layer
LAYER
NAME "test"
TYPE RASTER
STATUS ON
DATA "/vsicurl/http://download.osgeo.org/gdal/data/gtiff/small_world.tif"
CLASS
NAME "test"
END
END # layer
Since the GDAL/OGR library is used for vector and raster access in MapServer, many more formats are supported, so
please see the OGR (vector) and GDAL (raster) formats pages.
7.1. Data Input
518
CHAPTER 8
Output
8.1 Output Generation
8.1.1 AGG Rendering Specifics
Author Thomas Bonfort
Contact thomas.bonfort at gmail
Last Updated 2008/11/24
Table of Contents
• AGG Rendering Specifics
– Introduction
– Setting the OutputFormat
– New Features
– Modified Behavior
Introduction
MapServer 5.0 released with a new rendering backend. This howto details the changes and new functionality that this
adds to map creation. This howto assumes you already now the basics of mapfile syntax. If not, you should probably
be reading the mapfile syntax.
Setting the OutputFormat
24 bit png (high quality, large fil