Map Server

MapServer DocumentationRelease 6.4.0

The MapServer Team

March 03, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Set up a Project Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Download MapServer Source Code and Supporting Libraries . . . . . . . . . . . . . . . . . . 39The MapServer source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Set Compilation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Compile the Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Compile MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Compiling MapServer with PostGIS support . . . . . . . . . . . . . . . . . . . . . . . . . . 43Common Compiling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Other Helpful Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

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

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

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

ii

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

3.1.6 Oracle Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59System Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Compile 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 CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124.1.3 CLUSTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Supported Layer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Mapfile Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Supported Processing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Mapfile Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Feature attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116PHP MapScript Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Example: Clustering Railway Stations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

4.1.4 Display of International Characters in MapServer . . . . . . . . . . . . . . . . . . . . . . . 118Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Related Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119How to Enable in Your Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Example Using PHP MapScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

4.1.5 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Expression Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124MapServer expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

4.1.6 FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324.1.7 FONTSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Format of the fontset file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334.1.8 GRID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Mapfile Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Example1: Grid Displaying Degrees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Example2: Grid Displaying Degrees with Symbol . . . . . . . . . . . . . . . . . . . . . . . 135Example2: Grid Displayed in Other Projection (Google Mercator) . . . . . . . . . . . . . . . 136

iii

4.1.9 INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

4.1.10 JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Supported Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Mapfile Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Example 1: Join from Shape dataset to DBF file . . . . . . . . . . . . . . . . . . . . . . . . . 140Example 2: Join from Shape dataset to PostgreSQL table . . . . . . . . . . . . . . . . . . . . 141Example 3: Join from Shape dataset to CSV file . . . . . . . . . . . . . . . . . . . . . . . . . 142Example 4: Join from Shape dataset to MySQL . . . . . . . . . . . . . . . . . . . . . . . . . 144

4.1.11 LABEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444.1.12 LAYER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494.1.13 LEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Supported Layer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Mapfile Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Mapfile Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Example: World Countries Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

4.1.14 LEGEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624.1.15 MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634.1.16 OUTPUTFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664.1.17 PROJECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Projections with MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Web Mercator or Google Mercator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171PROJECTION AUTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Important Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

4.1.18 QUERYMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724.1.19 REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724.1.20 SCALEBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1734.1.21 STYLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744.1.22 SYMBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1814.1.23 Symbology Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

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

4.1.24 Templating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Example Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

4.1.25 Union Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Mapfile Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Feature attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Classes and Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

iv

Supported Processing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

4.1.26 WEB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2014.1.27 XML Mapfile support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Enabling the support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Usage: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

4.1.28 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

5 MapScript 2055.1 MapScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

5.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Appendices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Documentation Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205fooObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Additional Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

5.1.2 SWIG MapScript API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208MapScript Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208MapScript Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214MapScript Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

5.1.3 PHP MapScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249PHP MapScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250PHP MapScript Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282By Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

5.1.4 Python MapScript Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

5.1.5 Python MapScript Image Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Imagery Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297The imageObj Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Image Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Images and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

5.1.6 Mapfile Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Mapfile Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299The mapObj Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Children of mapObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

5.1.7 Querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Querying Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Attribute Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Spatial Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

6 MapCache 3056.1 MapCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

6.1.1 Compilation & Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Getting the Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Linux Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Windows Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

6.1.2 Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

v

Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Tileset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

6.1.3 Supported Tile Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326TMS service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326KML Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327OGC WMTS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328OGC WMS Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328GoogleMaps XYZ Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Virtual Earth Tile service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

6.1.4 Seeder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

6.1.5 Cache Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Disk Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332BerkeleyDB Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Sqlite Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Memcache Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336(Geo)TIFF Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

6.1.6 Image Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338JPEG Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338PNG Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Mixed Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

6.1.7 Tileset Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3396.1.8 FeatureInfo Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3396.1.9 Proxying Unsupported Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Parameter Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Proxy Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

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

6.1.11 Tile Assembling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3416.1.12 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

7 Input 3437.1 Data Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

7.1.1 Vector Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Data Format Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344ArcInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345ArcSDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349DGN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351ESRI File Geodatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352ESRI Personal Geodatabase (MDB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354ESRI Shapefiles (SHP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356GML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358GPS Exchange Format (GPX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Inline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361KML - Keyhole Markup Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363MapInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

vi

MSSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371NTF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375OGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376Oracle Spatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388PostGIS/PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393SDTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401S57 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403SpatiaLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405USGS TIGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408Vector field rendering - UVraster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Virtual Spatial Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412WFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

7.1.2 Raster Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418How are rasters added to a Map file? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418Supported Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Rasters and Tile Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421Raster Warping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42224bit RGB Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422Special Processing Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423Raster Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425Raster Display Performance Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426Preprocessing Rasters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427Georeference with World Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

8 Output 4318.1 Output Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

8.1.1 AGG Rendering Specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Setting the OutputFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432Modified Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

8.1.2 AntiAliasing with MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433What needs to be done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

8.1.3 Dynamic Charting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Adding a Chart Layer to a Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438Pie Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Bar Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

8.1.4 Flash Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Installing MapServer with Flash Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442How to Output SWF Files from MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . 443What is Currently Supported and Not Supported . . . . . . . . . . . . . . . . . . . . . . . . 446

8.1.5 HTML Legends with MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Sample Site Using the HTML Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

8.1.6 HTML Imagemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456Mapfile Layer Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Request URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458Additional Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

vii

More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4588.1.7 OGR Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458OUTPUTFORMAT Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458LAYER Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460MAP / WEB Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460Geometry Types Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461Attribute Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461Return Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461Test Suite Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

8.1.8 PDF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462What is currently supported and not supported . . . . . . . . . . . . . . . . . . . . . . . . . 463Implementing PDF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463PHP/MapScript and PDF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

8.1.9 SVG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467Feature Types and SVG Support Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468Testing your SVG Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469goSVG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

8.1.10 Tile Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Utilization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

8.1.11 Template-Driven Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478OUTPUTFORMAT Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478Template Substitution Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

8.1.12 Kml Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483General Functionnality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Output format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484Limiting the number of features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485Styling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488Coordinate system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489Warning and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

9 OGC 4919.1 OGC Support and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491

9.1.1 MapServer OGC Specification support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4919.1.2 WMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492Setting Up a WMS Server Using MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . 493Changing the Online Resource URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498WMS 1.3.0 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502FAQ / Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

9.1.3 INSPIRE View Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516

viii

Activation of INSPIRE support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517Multi-language support for certain capabilities fields . . . . . . . . . . . . . . . . . . . . . . 517Provision of INSPIRE specific metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518Named group layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519Style section for root layer and possibly existing group layers . . . . . . . . . . . . . . . . . 520

9.1.4 WMS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522Compilation / Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522MapFile Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523Limitations/TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528

9.1.5 WMS Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Enabling Time Support in MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Future Additions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Limitations and Known Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533

9.1.6 WMS Dimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Enabling Dimension Support in MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . 534GetCapabilities Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535Supported Dimension Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535Processing Dimension Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535

9.1.7 Map Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536Implementing a Web Map Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

9.1.8 WFS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543Configuring your MapFile to Serve WFS layers . . . . . . . . . . . . . . . . . . . . . . . . . 544Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547To-do Items and Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

9.1.9 WFS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552Setting up a WFS-client Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552TODO / Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554

9.1.10 WFS-T Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554WFS-T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

9.1.11 WFS Filter Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555Currently Supported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556Get and Post Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556Use of Filter Encoding in MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559

9.1.12 SLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563Server Side Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563Client Side Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571Named Styles support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572Other Items Implemented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572Issues Found During Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

9.1.13 WCS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573Configuring Your Mapfile to Serve WCS Layers . . . . . . . . . . . . . . . . . . . . . . . . 574Test Your WCS 1.0 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576WCS 1.1.0+ Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

ix

WCS 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579HTTP-POST support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585Rules for handling SRS in a MapServer WCS . . . . . . . . . . . . . . . . . . . . . . . . . . 588Spatio/Temporal Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589WCS 2.0 Application Profile - Earth Observation (EO-WCS) . . . . . . . . . . . . . . . . . . 589To-do Items and Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590

9.1.14 WCS Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590Landsat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590SPOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591DEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592NetCDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

9.1.15 SOS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595Setting Up an SOS Server Using MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . 596Limitations / TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601Use of sos_procedure and sos_procedure_item . . . . . . . . . . . . . . . . . . . . . . . . . 605

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

9.1.17 MapScript Wrappers for WxS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608Python Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609Perl Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612PHP Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614Use in Non-CGI Environments (mod_php, etc) . . . . . . . . . . . . . . . . . . . . . . . . . 615Post Processing Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

10 TinyOWS 61710.1 TinyOWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

10.1.1 TinyOWS Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617Requires . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

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

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

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

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

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

x

11 Optimization 63511.1 Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635

11.1.1 Debugging MapServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635Steps to Enable MapServer Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636Debugging MapServer using Compiler Debugging Tools . . . . . . . . . . . . . . . . . . . . 643Debugging Older Versions of MapServer (before 5.0) . . . . . . . . . . . . . . . . . . . . . . 645

11.1.2 FastCGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646Obtaining the necessary software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646mod_fcgid Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647Deprecated mod_fcgi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647Common mod_fcgid/mod_fcgi Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 647Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648FastCGI on Win32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648

11.1.3 Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650

11.1.4 Raster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652Overviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652Tileindexes and Internal Tiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652Image formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652Remote WMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

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

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

12 Utilities 65712.1 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

12.1.1 legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

12.1.2 msencrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657Use in Mapfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

12.1.3 scalebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

12.1.4 shp2img . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

12.1.5 shptree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661Mapfile Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

xi

12.1.6 shptreetst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662

12.1.7 shptreevis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663

12.1.8 sortshp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66412.1.9 sym2img . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

12.1.10 tile4ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666Short Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666Long Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

12.1.11 Batch Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

12.1.12 File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669File Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669Temporary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

13 CGI 67113.1 CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

13.1.1 MapServer CGI Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

13.1.2 mapserv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67213.1.3 Map Context Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672

Support for Local Map Context Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672Support for Context Files Accessed Through a URL . . . . . . . . . . . . . . . . . . . . . . 672Default Map File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

13.1.4 MapServer CGI Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673Changing map file parameters via a form or a URL . . . . . . . . . . . . . . . . . . . . . . . 676Specifying the location of mapfiles using an Apache variable . . . . . . . . . . . . . . . . . . 677ROSA-Applet Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678

13.1.5 Run-time Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678Basic Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678Parameters Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679Default values if not provided in the URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680VALIDATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680Magic values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

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

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

14 Environment Variables 68514.1 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685

xii

15 Glossary 68915.1 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689

16 Errors 69116.1 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691

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

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

How to get a files EXTENT values? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69216.1.4 msGetLabelSize(): Requested font not found . . . . . . . . . . . . . . . . . . . . . . . . . 69216.1.5 msLoadFontset(): Error opening fontset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69316.1.6 msLoadMap(): Failed to open map file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69316.1.7 msProcessProjection(): no options found in init file . . . . . . . . . . . . . . . . . . . . . 69316.1.8 msProcessProjection(): No such file or directory . . . . . . . . . . . . . . . . . . . . . . . . 693

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

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

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

C#-specific information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696

17 FAQ 69717.1 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697

17.1.1 Where is the MapServer log file? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69717.1.2 What books are available about MapServer? . . . . . . . . . . . . . . . . . . . . . . . . . . 69717.1.3 How do I compile MapServer for Windows? . . . . . . . . . . . . . . . . . . . . . . . . . . 69717.1.4 What do MapServer version numbers mean? . . . . . . . . . . . . . . . . . . . . . . . . . . 69717.1.5 Is MapServer Thread-safe? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69817.1.6 What does STATUS mean in a LAYER? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69917.1.7 How can I make my maps run faster? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69917.1.8 What does Polyline mean in MapServer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69917.1.9 What is MapScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69917.1.10 Does MapServer support reverse geocoding? . . . . . . . . . . . . . . . . . . . . . . . . . 70017.1.11 Does MapServer support geocoding? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70017.1.12 How do I set line width in my maps? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70017.1.13 Why do my JPEG input images look crappy via MapServer? . . . . . . . . . . . . . . . . . 70017.1.14 Which image format should I use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70117.1.15 Why doesnt PIL (Python Imaging Library) open my PNGs? . . . . . . . . . . . . . . . . . 70117.1.16 Why do my symbols look poor in JPEG output? . . . . . . . . . . . . . . . . . . . . . . . . 70217.1.17 How do I add a copyright notice on the corner of my map? . . . . . . . . . . . . . . . . . . 702

Example Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703

17.1.18 How do I have a polygon that has both a fill and an outline with a width? . . . . . . . . . . . 70317.1.19 How can I create simple antialiased line features? . . . . . . . . . . . . . . . . . . . . . . . 70317.1.20 Which OGC Specifications does MapServer support? . . . . . . . . . . . . . . . . . . . . . 70417.1.21 Why does my requested WMS layer not align correctly? . . . . . . . . . . . . . . . . . . . 70417.1.22 When I do a GetCapabilities, why does my browser want to download mapserv.exe/mapserv? 70517.1.23 Why do my WMS GetMap requests return exception using MapServer 5.0? . . . . . . . . . 706

xiii

17.1.24 Using MapServer 6.0, why dont my layers show up in GetCapabilities responses or are notfound anymore? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707

17.1.25 Where do I find my EPSG code? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70717.1.26 How can I reproject my data using ogr2ogr? . . . . . . . . . . . . . . . . . . . . . . . . . . 70717.1.27 How can I help improve the documentation on this site? . . . . . . . . . . . . . . . . . . . . 70817.1.28 Whats with MapServers logo? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708

18 Copyright 70918.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70918.2 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709

Index 711

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



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



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.



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:



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 need to modify your MapFile to add a PROJECTION block to the MAP (defines the output projection / geographical reference system) and eachof the LAYERs (defines the geographical reference system of the layer dataset).

Adding Data to Your Site

MapServer supports several data input formats natively, and many more if it is compiled with the open sourcelibraries GDAL and OGR.

Vector Data

Vector data includes features made up of points, lines, and polygons. MapServer support the ESRI Shape format bydefault, but it can be compiled to support spatially enabled databases such as PostgreSQL-PostGIS, and file formatssuch as Geography Markup Language (GML), MapInfo, delimited

Documents

Map Server