MapServer Documentation

Release 7.0.7

The MapServer Team

2017-11-15
 Contents

1 Introduction 2
1.1 An Introduction to MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 MapServer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2 Anatomy of a MapServer Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.3 Installation and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Windows Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.4 Introduction to the Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
MAP Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
LAYER Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
CLASS and STYLE Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
SYMBOLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
LABEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
CLASS Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Get MapServer Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Get Demo Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.1.5 Making the Site Your Own . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Adding Data to Your Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Vector Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Raster Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.1.6 Enhancing your site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Adding Query Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Attribute queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Spatial queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Data Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.1.7 How do I get Help? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Users Mailing List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
IRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Reporting bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Test Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

i
2 Tutorial 28
2.1 MapServer Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.1.1 Tutorial background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Tutorial Timeframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Tutorial Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Before Using the Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Windows, UNIX/Linux Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Other Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.1.2 Section 1: Static Maps and the MapFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.1.3 Section 2: CGI variables and the User Interface . . . . . . . . . . . . . . . . . . . . . . . . 31
HTML Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.1.4 Section 3: Query and more about HTML Templates . . . . . . . . . . . . . . . . . . . . . . 31
2.1.5 Section 4: Advanced User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

3 Installation 33
3.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.1.1 Compiling on Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Obtaining the necessary software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Anti-Grain Geometry Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
OGC Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Spatial Warehousing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.1.2 Compiling on Win32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Set up a Project Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Download MapServer Source Code and Supporting Libraries . . . . . . . . . . . . . . . . . . 42
The MapServer source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Set Compilation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Compile the Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Compile MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Compiling MapServer with PostGIS support . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Common Compiling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Other Helpful Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.1.3 PHP MapScript Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Obtaining, Compiling, and Installing PHP and the PHP/MapScript Module . . . . . . . . . . 49
FAQ / Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.1.4 .NET MapScript Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Most frequent errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Bug reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
3.1.5 IIS Setup for MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
MapServer Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Configuring with IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Setting up Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Setting up Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

ii
 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.1.6 Oracle Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
System Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Compile MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Set Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.1.7 V8 MapScript Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Obtaining, Compiling, and Installing V8 and V8/MapScript . . . . . . . . . . . . . . . . . . 70

4 Mapfile 72
4.1 Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4.1.1 Cartographical Symbol Construction with MapServer . . . . . . . . . . . . . . . . . . . . . 72
Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Using Cartographical Symbols in MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Construction of Point Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Construction of Line Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Area Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Examples (MapServer 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Mapfile changes related to symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Current Problems / Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
The End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
4.1.2 CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
4.1.3 CLUSTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Supported Layer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Mapfile Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Supported Processing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Mapfile Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Feature attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Handling GetFeatureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
PHP MapScript Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Example: Clustering Railway Stations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
4.1.4 COMPOSITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
4.1.5 Display of International Characters in MapServer . . . . . . . . . . . . . . . . . . . . . . . 133
Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Related Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
How to Enable in Your Mapfile (MapServer >= 7.0) . . . . . . . . . . . . . . . . . . . . . . 134
How to Enable in Your Mapfile (MapServer < 7.0) . . . . . . . . . . . . . . . . . . . . . . . 136
Example Using PHP MapScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.1.6 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Expression Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
String comparison (equality) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Regular expression comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
List expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
“MapServer expressions” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

iii
4.1.7 FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
4.1.8 FONTSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Format of the fontset file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
4.1.9 GEOMTRANSFORM - Geometry Transformations . . . . . . . . . . . . . . . . . . . . . . 151
Transformations for simple styling (CLASS STYLE only) . . . . . . . . . . . . . . . . . . . . 153
Labels (LABEL STYLE only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Expressions and advanced transformations (LAYER and CLASS STYLE) . . . . . . . . . . . . 159
Javascript transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
4.1.10 GRID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Mapfile Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Example1: Grid Displaying Degrees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Example2: Grid Displaying Degrees with Symbol . . . . . . . . . . . . . . . . . . . . . . . 173
Example3: Grid Displayed in Other Projection (Google Mercator) . . . . . . . . . . . . . . . 174
4.1.11 INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
4.1.12 JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Supported Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Mapfile Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Example 1: Join from Shape dataset to DBF file . . . . . . . . . . . . . . . . . . . . . . . . . 178
Example 2: Join from Shape dataset to PostgreSQL table . . . . . . . . . . . . . . . . . . . . 179
Example 3: Join from Shape dataset to CSV file . . . . . . . . . . . . . . . . . . . . . . . . . 180
Example 4: Join from Shape dataset to MySQL . . . . . . . . . . . . . . . . . . . . . . . . . 182
Example 5: One-to-many join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
4.1.13 LABEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
4.1.14 LAYER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
4.1.15 LEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Supported Layer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Mapfile Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Mapfile Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Example: World Countries Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
4.1.16 LEGEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
4.1.17 MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
4.1.18 OUTPUTFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
4.1.19 PROJECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Projections with MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
“Web Mercator” or “Google Mercator” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
PROJECTION AUTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Specifying which EPSG files to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Important Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
4.1.20 QUERYMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
4.1.21 REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
4.1.22 SCALEBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
4.1.23 STYLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
4.1.24 STYLEITEM Javascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Example 1. Single STYLE definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Example 2. CLASS with multiple STYLE definitions . . . . . . . . . . . . . . . . . . . . . . 233

iv
Click here to download full PDF material