The MapServer Documentation Release 6-4-0

MapServer DocumentationRelease 6.4.0

The MapServer Team

March 20, 2014

Contents

1 Introduction 31.1 An Introduction to MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 MapServer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1.2 Anatomy of a MapServer Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.3 Installation and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Windows Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.1.4 Introduction to the Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11MAP Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12LAYER Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13CLASS and STYLE Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13SYMBOLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14LABEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16CLASS Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Get MapServer Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Get Demo Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.1.5 Making the Site Your Own . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Adding Data to Your Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Vector Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Raster Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.1.6 Enhancing your site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Adding Query Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Attribute queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Spatial queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Data Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.1.7 How do I get Help? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Users Mailing List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21IRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Reporting bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Test Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

i

2 Tutorial 232.1 MapServer Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.1.1 Tutorial background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Tutorial Timeframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Tutorial Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Before Using the Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Windows, UNIX/Linux Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Other Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

2.1.2 Section 1: Static Maps and the MapFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.1.3 Section 2: CGI variables and the User Interface . . . . . . . . . . . . . . . . . . . . . . . . 26

HTML Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.1.4 Section 3: Query and more about HTML Templates . . . . . . . . . . . . . . . . . . . . . . 262.1.5 Section 4: Advanced User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3 Installation 293.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3.1.1 Compiling on Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Obtaining the necessary software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30libgd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Anti-Grain Geometry Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33OGC Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Spatial Warehousing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

3.1.2 Compiling on Win32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Set up a Project Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Download MapServer Source Code and Supporting Libraries . . . . . . . . . . . . . . . . . . 40The MapServer source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Set Compilation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Compile the Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Compile MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Compiling MapServer with PostGIS support . . . . . . . . . . . . . . . . . . . . . . . . . . 43Common Compiling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Other Helpful Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

3.1.3 PHP MapScript Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Obtaining, Compiling, and Installing PHP and the PHP/MapScript Module . . . . . . . . . . 46FAQ / Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.1.4 .NET MapScript Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Most frequent errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Bug reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

3.1.5 IIS Setup for MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Base configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Php.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Internet Services Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

ii

Under the tree for your new website - add virtual directories for . . . . . . . . . . . . . . . . 58Test PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Mapfiles for IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Configuration files: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

3.1.6 Oracle Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59System Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Compile MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Set Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

4 Mapfile 634.1 Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

4.1.1 Cartographical Symbol Construction with MapServer . . . . . . . . . . . . . . . . . . . . . 63Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Using Cartographical Symbols in MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . 67Construction of Point Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Construction of Line Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Area Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Examples (MapServer 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Mapfile changes related to symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Current Problems / Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111The End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

4.1.2 Geometry Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Transformations for simple styling (CLASS STYLE only) . . . . . . . . . . . . . . . . . . . . 113Labels (LABEL STYLE only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Expressions and advanced transformations (LAYER and CLASS STYLE) . . . . . . . . . . . . 118

4.1.3 CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264.1.4 CLUSTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Supported Layer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Mapfile Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Supported Processing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Mapfile Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Feature attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131PHP MapScript Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Example: Clustering Railway Stations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

4.1.5 Display of International Characters in MapServer . . . . . . . . . . . . . . . . . . . . . . . 134Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Related Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135How to Enable in Your Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Example Using PHP MapScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

4.1.6 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Expression Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140MapServer expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

4.1.7 FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1484.1.8 FONTSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Format of the fontset file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494.1.9 GRID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

iii

Mapfile Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Example1: Grid Displaying Degrees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Example2: Grid Displaying Degrees with Symbol . . . . . . . . . . . . . . . . . . . . . . . 151Example2: Grid Displayed in Other Projection (Google Mercator) . . . . . . . . . . . . . . . 152

4.1.10 INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

4.1.11 JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Supported Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Mapfile Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Example 1: Join from Shape dataset to DBF file . . . . . . . . . . . . . . . . . . . . . . . . . 156Example 2: Join from Shape dataset to PostgreSQL table . . . . . . . . . . . . . . . . . . . . 157Example 3: Join from Shape dataset to CSV file . . . . . . . . . . . . . . . . . . . . . . . . . 158Example 4: Join from Shape dataset to MySQL . . . . . . . . . . . . . . . . . . . . . . . . . 160

4.1.12 LABEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1604.1.13 LAYER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1654.1.14 LEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Supported Layer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Mapfile Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Mapfile Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Example: World Countries Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

4.1.15 LEGEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784.1.16 MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794.1.17 OUTPUTFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824.1.18 PROJECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Projections with MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Web Mercator or Google Mercator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187PROJECTION AUTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Important Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

4.1.19 QUERYMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884.1.20 REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884.1.21 SCALEBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894.1.22 STYLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1904.1.23 SYMBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1984.1.24 Symbology Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Example 1. Dashed Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Example 2. TrueType font marker symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Example 3. Vector triangle marker symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Example 4. Non-contiguous vector marker symbol (Cross) . . . . . . . . . . . . . . . . . . . 201Example 5. Circle vector symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Example 6. Downward diagonal fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Example 7. Using the Symbol Type HATCH (new in 4.6) . . . . . . . . . . . . . . . . . . . . 201Example 8. Styled lines using GAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

4.1.25 Templating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Example Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

4.1.26 Union Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

iv

Mapfile Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Feature attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Classes and Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Supported Processing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

4.1.27 WEB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2174.1.28 XML Mapfile support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Enabling the support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Usage: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

4.1.29 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

5 MapScript 2215.1 MapScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

5.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Appendices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Documentation Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221fooObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Additional Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

5.1.2 SWIG MapScript API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224MapScript Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224MapScript Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230MapScript Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

5.1.3 PHP MapScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265PHP MapScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266PHP MapScript Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298By Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

5.1.4 Python MapScript Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

5.1.5 Python MapScript Image Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Imagery Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313The imageObj Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Image Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Images and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

5.1.6 Mapfile Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Mapfile Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315The mapObj Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Children of mapObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

5.1.7 Querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Querying Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Attribute Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Spatial Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

6 MapCache 3216.1 MapCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

6.1.1 Compilation & Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

v

Getting the Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Linux Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Windows Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

6.1.2 Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Tileset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

6.1.3 Supported Tile Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342TMS service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342KML Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343OGC WMTS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344OGC WMS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344GoogleMaps XYZ Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344Virtual Earth Tile service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

6.1.4 Seeder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

6.1.5 Cache Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Disk Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348BerkeleyDB Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Sqlite Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Memcache Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352(Geo)TIFF Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

6.1.6 Image Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354JPEG Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354PNG Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Mixed Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

6.1.7 Tileset Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3556.1.8 FeatureInfo Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3556.1.9 Proxying Unsupported Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Parameter Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Proxy Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

6.1.10 Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357HTTP Service Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357WMS Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357MapFile Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

6.1.11 Tile Assembling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3576.1.12 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

7 Input 3597.1 Data Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

7.1.1 Vector Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Data Format Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360ArcInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361ArcSDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365DGN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367ESRI File Geodatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368ESRI Personal Geodatabase (MDB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370ESRI Shapefiles (SHP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372GML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

vi

GPS Exchange Format (GPX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Inline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377KML - Keyhole Markup Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379MapInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382MSSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387NTF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391OGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392Oracle Spatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404PostGIS/PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409SDTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417S57 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419SpatiaLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421USGS TIGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424Vector field rendering - UVraster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426Virtual Spatial Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428WFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

7.1.2 Raster Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434How are rasters added to a Map file? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434Supported Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436Rasters and Tile Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Raster Warping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43824bit RGB Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438Special Processing Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439Raster Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Raster Display Performance Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442Preprocessing Rasters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443Georeference with World Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

8 Output 4478.1 Output Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

8.1.1 AGG Rendering Specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Setting the OutputFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448Modified Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

8.1.2 AntiAliasing with MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449What needs to be done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

8.1.3 Dynamic Charting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Adding a Chart Layer to a Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454Pie Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456Bar Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

8.1.4 Flash Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Installing MapServer with Flash Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458How to Output SWF Files from MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . 459What is Currently Supported and Not Supported . . . . . . . . . . . . . . . . . . . . . . . . 462

8.1.5 HTML Legends with MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463Sample Site Using the HTML Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

8.1.6 HTML Imagemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

vii

Mapfile Layer Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473Request URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Additional Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

8.1.7 OGR Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474OUTPUTFORMAT Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474LAYER Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476MAP / WEB Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476Geometry Types Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477Attribute Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477Return Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477Test Suite Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

8.1.8 PDF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478What is currently supported and not supported . . . . . . . . . . . . . . . . . . . . . . . . . 479Implementing PDF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479PHP/MapScript and PDF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

8.1.9 SVG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Feature Types and SVG Support Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484Testing your SVG Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485goSVG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

8.1.10 Tile Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490Utilization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491

8.1.11 Template-Driven Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494OUTPUTFORMAT Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494Template Substitution Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

8.1.12 Kml Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499General Functionnality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Output format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500Limiting the number of features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501Styling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504Coordinate system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505Warning and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505

9 OGC 5079.1 OGC Support and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

9.1.1 MapServer OGC Specification support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5079.1.2 WMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508Setting Up a WMS Server Using MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . 509Changing the Online Resource URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514WMS 1.3.0 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

viii

Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518FAQ / Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531

9.1.3 INSPIRE View Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532Activation of INSPIRE support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Multi-language support for certain capabilities fields . . . . . . . . . . . . . . . . . . . . . . 533Provision of INSPIRE specific metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534Named group layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535Style section for root layer and possibly existing group layers . . . . . . . . . . . . . . . . . 536

9.1.4 WMS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538Compilation / Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538MapFile Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539Limitations/TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544

9.1.5 WMS Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545Enabling Time Support in MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545Future Additions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549Limitations and Known Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

9.1.6 WMS Dimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549Enabling Dimension Support in MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . 550GetCapabilities Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551Supported Dimension Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551Processing Dimension Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

9.1.7 Map Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552Implementing a Web Map Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552

9.1.8 WFS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559Configuring your MapFile to Serve WFS layers . . . . . . . . . . . . . . . . . . . . . . . . . 560Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563To-do Items and Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

9.1.9 WFS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568Setting up a WFS-client Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568TODO / Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570

9.1.10 WFS-T Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570WFS-T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

9.1.11 WFS Filter Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571Currently Supported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572Get and Post Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572Use of Filter Encoding in MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

9.1.12 SLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579Server Side Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579Client Side Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587Named Styles support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588Other Items Implemented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588Issues Found During Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588

9.1.13 WCS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

ix

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589Configuring Your Mapfile to Serve WCS Layers . . . . . . . . . . . . . . . . . . . . . . . . 590Test Your WCS 1.0 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592WCS 1.1.0+ Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593WCS 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595HTTP-POST support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601Rules for handling SRS in a MapServer WCS . . . . . . . . . . . . . . . . . . . . . . . . . . 604Spatio/Temporal Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605WCS 2.0 Application Profile - Earth Observation (EO-WCS) . . . . . . . . . . . . . . . . . . 605To-do Items and Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606

9.1.14 WCS Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606Landsat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606SPOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607DEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608NetCDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609

9.1.15 SOS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611Setting Up an SOS Server Using MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . 612Limitations / TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617Use of sos_procedure and sos_procedure_item . . . . . . . . . . . . . . . . . . . . . . . . . 621

9.1.16 How to set up MapServer as a client to access a service over https . . . . . . . . . . . . . . 622Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622Default Installation (with apt-get install, rpm, manual, etc) . . . . . . . . . . . . . . . . . . . 623Non-Standard Installation (common with ms4w and fgs) . . . . . . . . . . . . . . . . . . . . 623Remote Server with a Self-Signed SSL Certificate . . . . . . . . . . . . . . . . . . . . . . . 623

9.1.17 MapScript Wrappers for WxS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624Python Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625Perl Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628PHP Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630Use in Non-CGI Environments (mod_php, etc) . . . . . . . . . . . . . . . . . . . . . . . . . 631Post Processing Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

10 TinyOWS 63310.1 TinyOWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633

10.1.1 TinyOWS Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633Requires . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633

10.1.2 Configuring TinyOWS with an XML File . . . . . . . . . . . . . . . . . . . . . . . . . . . 634Configuration file simple Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634Testing your config.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635Structure of the config.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635

10.1.3 Configuring TinyOWS with a standard Mapfile . . . . . . . . . . . . . . . . . . . . . . . . 640Mapfile Config File support for TinyOWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640Mapfile path of each TinyOWS config element . . . . . . . . . . . . . . . . . . . . . . . . . 641

10.1.4 Sample: WFS-T with TinyOWS and OpenLayers . . . . . . . . . . . . . . . . . . . . . . . 64210.1.5 Server Tuning: How to speed up your TinyOWS server . . . . . . . . . . . . . . . . . . . . 647

Tips and Tricks for PostgreSQL / PostGIS databases . . . . . . . . . . . . . . . . . . . . . . 647Tips and Tricks for Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647Using Fast-CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647HTTP GZip compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648

x

10.1.6 Working Around the LibXML2 XSD Schema GML Bug . . . . . . . . . . . . . . . . . . . 648Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648Workaround and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648

11 Optimization 65111.1 Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651

11.1.1 Debugging MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651Steps to Enable MapServer Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652Debugging MapServer using Compiler Debugging Tools . . . . . . . . . . . . . . . . . . . . 659Debugging Older Versions of MapServer (before 5.0) . . . . . . . . . . . . . . . . . . . . . . 661

11.1.2 FastCGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662Obtaining the necessary software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662mod_fcgid Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663Deprecated mod_fcgi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663Common mod_fcgid/mod_fcgi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 663Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664FastCGI on Win32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664

11.1.3 Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

11.1.4 Raster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668Overviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668Tileindexes and Internal Tiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668Image formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668Remote WMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

11.1.5 Tile Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669What is a tileindex and how do I make one? . . . . . . . . . . . . . . . . . . . . . . . . . . . 669Using the tileindex in your mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670Tileindexes may make your map faster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670Tileindexes with tiles in different projections . . . . . . . . . . . . . . . . . . . . . . . . . . 670

11.1.6 Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671Splitting your data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671Shapefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671PostGIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672Databases in General (PostGIS, Oracle, MySQL) . . . . . . . . . . . . . . . . . . . . . . . . 672

12 Utilities 67312.1 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

12.1.1 legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

12.1.2 msencrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673Use in Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674

12.1.3 scalebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

12.1.4 shp2img . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

12.1.5 shptree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

xi

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677Mapfile Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677

12.1.6 shptreetst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678

12.1.7 shptreevis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679

12.1.8 sortshp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68012.1.9 sym2img . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

12.1.10 tile4ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682Short Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682Long Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682

12.1.11 Batch Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685

12.1.12 File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685File Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685Temporary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685

13 CGI 68713.1 CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

13.1.1 MapServer CGI Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

13.1.2 mapserv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68813.1.3 Map Context Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688

Support for Local Map Context Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688Support for Context Files Accessed Through a URL . . . . . . . . . . . . . . . . . . . . . . 688Default Map File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689

13.1.4 MapServer CGI Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689Changing map file parameters via a form or a URL . . . . . . . . . . . . . . . . . . . . . . . 692Specifying the location of mapfiles using an Apache variable . . . . . . . . . . . . . . . . . . 693ROSA-Applet Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694

13.1.5 Run-time Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694Basic Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694Parameters Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695Default values if not provided in the URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696VALIDATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696Magic values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697

13.1.6 A Simple CGI Wrapper Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697Script Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697

13.1.7 MapServer OpenLayers Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698Using the OpenLayers viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698

xii

14 Environment Variables 70114.1 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701

15 Glossary 70515.1 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705

16 Errors 70716.1 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707

16.1.1 drawEPP(): EPPL7 support is not available . . . . . . . . . . . . . . . . . . . . . . . . . . 707Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707

16.1.2 loadLayer(): Unknown identifier. Maximum number of classes reached . . . . . . . . . . . 70716.1.3 loadMapInternal(): Given map extent is invalid . . . . . . . . . . . . . . . . . . . . . . . . 708

How to get a files EXTENT values? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70816.1.4 msGetLabelSize(): Requested font not found . . . . . . . . . . . . . . . . . . . . . . . . . 70816.1.5 msLoadFontset(): Error opening fontset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70916.1.6 msLoadMap(): Failed to open map file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70916.1.7 msProcessProjection(): no options found in init file . . . . . . . . . . . . . . . . . . . . . 70916.1.8 msProcessProjection(): No such file or directory . . . . . . . . . . . . . . . . . . . . . . . . 709

Setting the location of the epsg file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70916.1.9 msProcessProjection(): Projection library error.major axis or radius = 0 not given . . . . . . 710

Valid Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71016.1.10 msQueryByPoint: search returned no results . . . . . . . . . . . . . . . . . . . . . . . . . . 71016.1.11 msReturnPage(): Web application error. Malformed template name . . . . . . . . . . . . . . 71116.1.12 msSaveImageGD(): Unable to access file . . . . . . . . . . . . . . . . . . . . . . . . . . . 71116.1.13 msWMSLoadGetMapParams(): WMS server error. Image Size out of range, WIDTH and

HEIGHT must be between 1 and 2048 pixels . . . . . . . . . . . . . . . . . . . . . . . . . 71116.1.14 Unable to load dll (MapScript) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711

C#-specific information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712

17 FAQ 71317.1 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713

17.1.1 Where is the MapServer log file? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71317.1.2 What books are available about MapServer? . . . . . . . . . . . . . . . . . . . . . . . . . . 71317.1.3 How do I compile MapServer for Windows? . . . . . . . . . . . . . . . . . . . . . . . . . . 71317.1.4 What do MapServer version numbers mean? . . . . . . . . . . . . . . . . . . . . . . . . . . 71317.1.5 Is MapServer Thread-safe? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71417.1.6 What does STATUS mean in a LAYER? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71517.1.7 How can I make my maps run faster? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71517.1.8 What does Polyline mean in MapServer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71517.1.9 What is MapScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71517.1.10 Does MapServer support reverse geocoding? . . . . . . . . . . . . . . . . . . . . . . . . . 71617.1.11 Does MapServer support geocoding? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71617.1.12 How do I set line width in my maps? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71617.1.13 Why do my JPEG input images look crappy via MapServer? . . . . . . . . . . . . . . . . . 71617.1.14 Which image format should I use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71717.1.15 Why doesnt PIL (Python Imaging Library) open my PNGs? . . . . . . . . . . . . . . . . . 71717.1.16 Why do my symbols look poor in JPEG output? . . . . . . . . . . . . . . . . . . . . . . . . 71817.1.17 How do I add a copyright notice on the corner of my map? . . . . . . . . . . . . . . . . . . 718

Example Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719

17.1.18 How do I have a polygon that has both a fill and an outline with a width? . . . . . . . . . . . 71917.1.19 How can I create simple antialiased line features? . . . . . . . . . . . . . . . . . . . . . . . 71917.1.20 Which OGC Specifications does MapServer support? . . . . . . . . . . . . . . . . . . . . . 72017.1.21 Why does my requested WMS layer not align correctly? . . . . . . . . . . . . . . . . . . . 720

xiii

17.1.22 When I do a GetCapabilities, why does my browser want to download mapserv.exe/mapserv? 72117.1.23 Why do my WMS GetMap requests return exception using MapServer 5.0? . . . . . . . . . 72217.1.24 Using MapServer 6.0, why dont my layers show up in GetCapabilities responses or are not

found anymore? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72317.1.25 Where do I find my EPSG code? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72317.1.26 How can I reproject my data using ogr2ogr? . . . . . . . . . . . . . . . . . . . . . . . . . . 72317.1.27 How can I help improve the documentation on this site? . . . . . . . . . . . . . . . . . . . . 72417.1.28 Whats with MapServers logo? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724

18 Copyright 72518.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72518.2 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725

Index 727

xiv

MapServer Documentation, Release 6.4.0

Note: The entire documentation is also available as a single PDF document and ePub documentIf you are upgrading from an earlier version of MapServer, be sure to review the MapServer Migration Guide.

previousversions

Contents 1


2 Contents

CHAPTER 1

Introduction

1.1 An Introduction to MapServer

Revision $Revision$

Date $Date$

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

Contents

An Introduction to MapServer MapServer Overview Anatomy of a MapServer Application Installation and Requirements Introduction to the Mapfile Making the Site Your Own Enhancing your site How do I get Help?

1.1.1 MapServer Overview

MapServer is a popular Open Source project whose purpose is to display dynamic spatial maps over the Internet. Someof 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

3


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 toMapServer, 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.

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 differentvector and raster input data formats, and it can generate a multitude of output formats. Most pre-compiled MapServerdistributions contain most all of its features.

Note: MapScript provides a scripting interface for MapServer for the construction of Web and stand-alone appli-cations. MapScript can be used independently of CGI MapServer, and it is a loadable module that adds MapServercapability 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 notrecognize it.

Geographic Data - MapServer can utilize many geographic data source types. The default format is the ESRIShape format. Many other data formats can be supported, this is discussed further below in Adding data to yoursite.

HTML Pages - the interface between the user and MapServer . They normally sit in Web root. In its simplestform, MapServer can be called to place a static map image on a HTML page. To make the map interactive, theimage is placed in an HTML form on a page.

CGI programs are stateless, every request they get is new and they dont remember anything about the last timethat 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.) inhidden 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 andMapServer. This form could be placed on another page or be replaced by passing the initialization infor-mation as variables in a URL.

Template File - controls how the maps and legends output by MapServer will appear in the browser. Byreferencing MapServer CGI variables in the template HTML, you allow MapServer to populate them withvalues related to the current state of your application (e.g. map image name, reference image name, mapextent, etc.) as it creates the HTML page for the browser to read. The template also determines how theuser can interact with the MapServer application (browse, zoom, pan, query).

4 Chapter 1. Introduction


Figure 1.1: The basic architecture of MapServer applications.

1.1. An Introduction to MapServer 5


MapServer CGI - The binary or executable file that receives requests and returns images, data, etc. It sits in thecgi-bin or scripts directory of the web server. The Web server user must have execute rights for the directory thatit 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 users browser. You need a working Web(HTTP) server, such as Apache or Microsoft Internet Information Server, on the machine on which you areinstalling MapServer.

1.1.3 Installation and Requirements

Windows Installation

OSGeo4W is a new Windows installer that downloads and/or updates MapServer, add-on applications, and also otherOpen Source geospatial software. The following steps illustrate how to use OSGeo4W:

1. Download OSGeo4W http://download.osgeo.org/osgeo4w/osgeo4w-setup.exe

2. Execute (double-click) the .exe

3. Choose Advanced install type

Note: Express contains options for higher-level packages such as MapServer, GRASS, and uDig. Advancedgives you full access to choosing commandline tools and applications for MapServer that are not included in theExpress install

4. Select packages to install


http://httpd.apache.orghttp://download.osgeo.org/osgeo4w/osgeo4w-setup.exe


Note: Click on the Default text beside the higher-level packages (such as Web) to install all of Webs sub-packages, or click on the Skip text beside the sub-package (such as MapServer) to install that package and allof its dependencies.

5. Let the installer fetch the packages.



6. Run the apache-install.bat script to install the Apache Service.

Note: You must run this script under the OSGeo4W Shell. This is usually available as a shortcut on yourdesktop

Note: An apache-uninstall.bat script is also available to remove the Apache service installation.

7. Start Apache from the OSGeo4W shell and navigate to http://127.0.0.1

apache-restart.bat


http://127.0.0.1


8. Verify that MapServer is working



Hardware Requirements

MapServer runs on Linux, Windows, Mac OS X, Solaris, and more. To compile or install some of the required pro-grams, you may need administrative rights to the machine. People commonly ask questions about minimum hardwarespecifications for MapServer applications, but the answers are really specific to the individual application. For devel-opment and learning purposes, a very minimal machine will work fine. For deployment, you will want to investigateOptimization 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 InformationServer, on the machine on which you are installing MapServer. OSGeo4W contains Apache already, but you canreconfigure things to use IIS if you need to. Alternatively, MS4W can be used to install MapServer on Windows.

If you are on a Windows machine, and you dont have a web server installed, you may want to check out MS4W, whichwill install a pre-configured web server, MapServer, and more. The FGS Linux Installer provides similar functionalityfor several Linux distributions.

This introduction will assume you are using pre-compiled OSGeo4W Windows binaries to follow along. ObtainingMapServer or Linux or Mac OS X should be straightforward. Visit download for installing pre-compiled MapServerbuilds on Mac OS X and Linux.

You will also need a Web browser, and a text editor (vi, emacs, notepad, homesite) to modify your HTML and mapfiles.


http://httpd.apache.org/http://www.maptools.org/ms4w/index.phtmlhttp://www.maptools.org/ms4w/index.phtmlhttp://www.maptools.org/fgs/


Skills

In addition to learning how the different components of a MapServer application work together and learning Map Filesyntax, 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 theprimary purpose of a MapServer application is to create maps, you will also need to understand the basics of geographicdata 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.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, aswell as the map image output:

MAPNAME "sample"STATUS ONSIZE 600 400SYMBOLSET "../etc/symbols.txt"EXTENT -180 -90 180 90UNITS DDSHAPEPATH "../data"IMAGECOLOR 255 255 255FONTSET "../etc/fonts.txt"

## Start of web interface definition#WEB

IMAGEPATH "/ms4w/tmp/ms_tmp/"IMAGEURL "/ms_tmp/"

END # WEB

## Start of layer definitions#LAYER

NAME global-rasterTYPE RASTERSTATUS DEFAULTDATA b l u e m a r b le.gif

END # LAYEREND # MAP

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:


http://www.w3.org/MarkUp/Guide/


Figure 1.2: Rendered Bluemarble Image

The mapfile could be placed anywhere, as long as it is accessible to the web server. Normally, onewould try to avoid placing it at a location that makes it accessible on the web. Let us say it is placedin /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/

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 webserver must be able to place files in this directory. The web server must make this directory avail-able 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

MAPNAME "sample"EXTENT -180 -90 180 90 # GeographicSIZE 800 400IMAGECOLOR 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

Note: MapServer currently uses a pixel-center based extent model which is a bit different from what GDAL or WMSuse.



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

LAYERNAME "bathymetry"TYPE RASTERSTATUS DEFAULTDATA "bath_mapserver.tif"

END # LAYER

See also:

Raster Data

Vector Layers

Vector layers of TYPE point, line, or polygon can be displayed. The following example shows how to display onlylines from a TYPE polygon layer, using the OUTLINECOLOR parameter:

LAYERNAME "world_poly"DATA shapefile/countries_area.shpSTATUS ONTYPE POLYGONCLASSNAME The WorldSTYLE

OUTLINECOLOR 0 0 0END # STYLE

END # CLASSEND # LAYER

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 overlayed STYLE objects

CLASSNAME "Primary Roads"STYLESYMBOL "circle"COLOR 178 114 1SIZE 15

END # STYLE



Figure 1.3: Rendered Bluemarble image with vector boundaries

STYLESYMBOL "circle"COLOR 254 161 0SIZE 7

END # STYLEEND # CLASS

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:

MAPNAME "sample"EXTENT -180 -90 180 90 # GeographicSIZE 800 400IMAGECOLOR 128 128 255SYMBOLSET "../etc/symbols.txt"

END # MAP

where symbols.txt might contain:

SYMBOLNAME "ski"TYPE PIXMAPIMAGE "ski.png"

END # SYMBOL

and the mapfile would contain:



Figure 1.4: Rendered Bluemarble image with styled roads



LAYER...CLASSNAME "Ski Area"STYLE

SYMBOL "ski"END # STYLE

END # CLASSEND # LAYER

Figure 1.5: Rendered Bluemarble image with skier 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 forlabeling. The label is displayed by the FONT, declared in the FONTSET file (set in the MAP object). TheFONTSET file contains references to the available font names. ENCODING describes which encoding is usedin the file (see Display of International Characters in MapServer).

An example LABEL object that references one of the above fonts might look like:

LABELFONT "sans-bold"TYPE truetypeENCODING "UTF-8"



SIZE 10POSITION LCPARTIALS FALSECOLOR 100 100 100OUTLINECOLOR 242 236 230

END # LABEL

Figure 1.6: Rendered Bluemarble image with skier symbol and a label

CLASS Expressions

MapServer supports three types of CLASS Expressions in a LAYER (CLASSITEM in LAYER determines the attributeto 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.



INCLUDE

Added to MapServer 4.10, any part of the mapfile can now be stored in a separate file and added to the main mapfileusing the INCLUDE parameter. The filename to be included can have any extension, and it is always relative to themain .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:

LAYERNAME shadedreliefSTATUS ONTYPE RASTERDATA 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:

MAPNAME "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 haveany extension you want, however.

Get MapServer Running

You can test if MapServer is working by running the MapServer executable (mapserv) with the -v parameter on thecommand line (./mapserv -v). Depending on your configuration, the output could be something like this:

MapServer version 6.0.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEGSUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=ICONVSUPPORTS=WMS_SERVER INPUT=SHAPEFILE



You can also send a HTTP request directly to the MapServer CGI program without passing any configuration vari-ables (e.g. http://your.domain.name/cgi-bin/ms4/mapserv.exe). If you receive the message, No query information todecode. QUERY_STRING not set., your installation is working.

Get Demo Running

Download the MapServer Demo. UnZip it and follow the directions in ReadMe.txt. You will need to move the demofiles to their appropriate locations on your web server, and modify the Map File and HTML pages to reflect the pathsand URLs of your server. Next, point your browser to init.html and hit the initialize button. If you get errors, verifythat 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 toyour Map file that refer to your own geographic data layers (you will probably want to delete the existing layers or settheir status to OFF).

Unless you are adding layers that fall within the same geographic area as the demo, modify MAP EXTENT to matchthe extent of your data. To determine the extent of your data, you can use ogrinfo. If you have access to a GIS, youcould 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 ne

Documents

The MapServer Documentation Release 6-4-0