Map Server

MapServer Documentation
Release 6.0.1
The MapServer Team
December 16, 2011
Contents
1 2
About An Introduction to MapServer 2.1 MapServer Overview . . . . . . . . . 2.2 Anatomy of a MapServer Application 2.3 Installation and Requirements . . . . 2.4 Introduction to the Maple . . . . . . 2.5 Making the Site Your Own . . . . . . 2.6 Enhancing your site . . . . . . . . . 2.7 How do I get Help? . . . . . . . . . .
3 5 5 6 8 14 22 23 24 27 27 27 28 28 29 29 30 31 31 33 33 41 47 53 58 61
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
MapServer Tutorial 3.1 Tutorial Timeframe . . . . . . . . . . . . . . . 3.2 Tutorial Data . . . . . . . . . . . . . . . . . . 3.3 Before Using the Tutorial . . . . . . . . . . . 3.4 Windows, UNIX/Linux Issues . . . . . . . . . 3.5 Other Resources . . . . . . . . . . . . . . . . 3.6 Section 1: Static Maps and the MapFile . . . . 3.7 Section 2: CGI variables and the User Interface 3.8 Section 3: Query and more HTML Templates . 3.9 Section 4: Advanced User Interfaces . . . . . Installation 4.1 Compiling on Unix . . . . . . 4.2 Compiling on Win32 . . . . . 4.3 PHP MapScript Installation . 4.4 .NET MapScript Compilation 4.5 IIS Setup for MapServer . . . 4.6 Oracle Installation . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
Maple 65 5.1 Cartographical Symbol Construction with MapServer . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.2 CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 5.3 CLUSTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.4 5.5 5.6 5.7 5.8 5.9 5.10 5.11 5.12 5.13 5.14 5.15 5.16 5.17 5.18 5.19 5.20 5.21 5.22 5.23 5.24 5.25 5.26 5.27 5.28 6
Display of International Characters in MapServer Expressions . . . . . . . . . . . . . . . . . . . . FEATURE . . . . . . . . . . . . . . . . . . . . FONTSET . . . . . . . . . . . . . . . . . . . . GRID . . . . . . . . . . . . . . . . . . . . . . . INCLUDE . . . . . . . . . . . . . . . . . . . . JOIN . . . . . . . . . . . . . . . . . . . . . . . LABEL . . . . . . . . . . . . . . . . . . . . . . LAYER . . . . . . . . . . . . . . . . . . . . . . LEGEND . . . . . . . . . . . . . . . . . . . . . MAP . . . . . . . . . . . . . . . . . . . . . . . OUTPUTFORMAT . . . . . . . . . . . . . . . PROJECTION . . . . . . . . . . . . . . . . . . QUERYMAP . . . . . . . . . . . . . . . . . . . REFERENCE . . . . . . . . . . . . . . . . . . SCALEBAR . . . . . . . . . . . . . . . . . . . STYLE . . . . . . . . . . . . . . . . . . . . . . SYMBOL . . . . . . . . . . . . . . . . . . . . Symbology Examples . . . . . . . . . . . . . . Templating . . . . . . . . . . . . . . . . . . . . Union Layer . . . . . . . . . . . . . . . . . . . Variable Substitution . . . . . . . . . . . . . . . WEB . . . . . . . . . . . . . . . . . . . . . . . XML Maple support . . . . . . . . . . . . . . Notes . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . .
119 123 132 133 134 135 136 141 145 153 154 157 160 162 162 163 163 168 169 173 183 187 188 189 190 191 191 192 228 264 266 268 271 273
MapScript 6.1 Introduction . . . . . . . . . . . . . 6.2 SWIG MapScript API Reference . . 6.3 PHP MapScript . . . . . . . . . . . . 6.4 Python MapScript Appendix . . . . . 6.5 Python MapScript Image Generation 6.6 Maple Manipulation . . . . . . . . 6.7 Querying . . . . . . . . . . . . . . . 6.8 MapScript Variables . . . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
Data Input 281 7.1 Vector Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 7.2 Raster Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Output Generation 8.1 AGG Rendering Specics . . . . 8.2 AntiAliasing with MapServer . . 8.3 Dynamic Charting . . . . . . . . 8.4 Flash Output . . . . . . . . . . . 8.5 HTML Legends with MapServer 8.6 HTML Imagemaps . . . . . . . . 8.7 OGR Output . . . . . . . . . . . 8.8 PDF Output . . . . . . . . . . . . 8.9 SVG . . . . . . . . . . . . . . . 8.10 Tile Mode . . . . . . . . . . . . 8.11 Template-Driven Output . . . . . 8.12 Kml Output . . . . . . . . . . . . OGC Support and Conguration 365 365 367 370 375 380 389 391 396 400 407 411 416 423
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
9 ii
9.1 9.2 9.3 9.4 9.5 9.6 9.7 9.8 9.9 9.10 9.11 9.12 9.13 9.14
Mapserver OGC Specication support . . . . . . . . . . . . . . . WMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . WMS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . WMS Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . WFS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . WFS Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WFS Filter Encoding . . . . . . . . . . . . . . . . . . . . . . . . SLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WCS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . WCS Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . SOS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to set up MapServer as a client to access a service over https MapScript Wrappers for WxS Services . . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
423 423 446 453 458 465 474 477 484 493 510 515 526 528 537 537 548 551 553 555 556 559 559 559 561 561 563 564 565 566 568 569 573 573 575 575 576 576 577 582 585 587 587 588 589 589
10 Optimization 10.1 Debugging MapServer 10.2 FastCGI . . . . . . . . 10.3 Maple . . . . . . . . 10.4 Raster . . . . . . . . . 10.5 Tile Indexes . . . . . 10.6 Vector . . . . . . . . . 11 Utilities 11.1 legend . . . . . 11.2 msencrypt . . . 11.3 scalebar . . . . . 11.4 shp2img . . . . 11.5 shptree . . . . . 11.6 shptreetst . . . . 11.7 shptreevis . . . . 11.8 sortshp . . . . . 11.9 sym2img . . . . 11.10 tile4ms . . . . . 11.11 Batch Scripting . 11.12 File Management 12 CGI 12.1 12.2 12.3 12.4 12.5 12.6
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
MapServer CGI Introduction . mapserv . . . . . . . . . . . . Map Context Files . . . . . . MapServer CGI Controls . . . Run-time Substitution . . . . A Simple CGI Wrapper Script
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
13 Community Activities 13.1 IRC . . . . . . . . . . . . . . 13.2 Mailing Lists . . . . . . . . . 13.3 MapServer Wiki Pages . . . . 13.4 MapServer Service Providers
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
14 Development 591 14.1 Sponsors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 14.2 MapServer Release Plans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 14.3 Announcements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 iii
14.4 14.5 14.6 14.7 14.8 14.9 14.10
Bug Submission . . . . . . . . . . Subversion . . . . . . . . . . . . . Documentation Development Guide Testing . . . . . . . . . . . . . . . Request for Comments . . . . . . . Maple Editing . . . . . . . . . . . External Links . . . . . . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
597 598 598 606 613 843 844 845 845 845 846 847 849 853 857 857 857 858 859 859 859 859 859 860 861 861 862 862 862 863 863 863 863 863 864 865 865 865 866 866 866 866 866 867 867 868 868 869 870
15 Download 15.1 Source . . . . . . 15.2 Documentation . . 15.3 Binaries . . . . . . 15.4 Demo Application 16 Environment Variables 17 Glossary
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
18 Errors 18.1 drawEPP(): EPPL7 support is not available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2 loadLayer(): Unknown identier. Maximum number of classes reached . . . . . . . . . . . . . . . . 18.3 loadMapInternal(): Given map extent is invalid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.4 msGetLabelSize(): Requested font not found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.5 msLoadFontset(): Error opening fontset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.6 msLoadMap(): Failed to open map le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.7 msProcessProjection(): no options found in init le . . . . . . . . . . . . . . . . . . . . . . . . . . 18.8 msProcessProjection(): No such le or directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.9 msProcessProjection(): Projection library error.major axis or radius = 0 not given . . . . . . . . . . . 18.10 msQueryByPoint: search returned no results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.11 msReturnPage(): Web application error. Malformed template name . . . . . . . . . . . . . . . . . . 18.12 msSaveImageGD(): Unable to access le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.13 msWMSLoadGetMapParams(): WMS server error. Image Size out of range, WIDTH and HEIGHT must be between 1 and 2048 pixels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.14 Unable to load dll (MapScript) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 FAQ 19.1 19.2 19.3 19.4 19.5 19.6 19.7 19.8 19.9 19.10 19.11 19.12 19.13 19.14 19.15 19.16 19.17 19.18 19.19 iv
Where is the MapServer log le? . . . . . . . . . . . . . . . . . . . . . What books are available about MapServer? . . . . . . . . . . . . . . . How do I compile MapServer for Windows? . . . . . . . . . . . . . . . What do MapServer version numbers mean? . . . . . . . . . . . . . . . Is MapServer Thread-safe? . . . . . . . . . . . . . . . . . . . . . . . . . What does STATUS mean in a LAYER? . . . . . . . . . . . . . . . . . . How can I make my maps run faster? . . . . . . . . . . . . . . . . . . . What does Polyline mean in MapServer? . . . . . . . . . . . . . . . . . What is MapScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . Does MapServer support reverse geocoding? . . . . . . . . . . . . . . . Does MapServer support geocoding? . . . . . . . . . . . . . . . . . . . How do I set line width in my maps? . . . . . . . . . . . . . . . . . . . Why do my JPEG input images look crappy via MapServer? . . . . . . . Which image format should I use? . . . . . . . . . . . . . . . . . . . . . Why doesnt PIL (Python Imaging Library) open my PNGs? . . . . . . . Why do my symbols look poor in JPEG output? . . . . . . . . . . . . . How do I add a copyright notice on the corner of my map? . . . . . . . . How do I have a polygon that has both a ll and an outline with a width? How can I create simple antialiased line features? . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
19.20 19.21 19.22 19.23 19.24 19.25 19.26 19.27 19.28
Which OGC Specications does MapServer support? . . . . . . . . . . . . . . . . . . . . . . Why does my requested WMS layer not align correctly? . . . . . . . . . . . . . . . . . . . . When I do a GetCapabilities, why does my browser want to download mapserv.exe/mapserv? Why do my WMS GetMap requests return exception using MapServer 5.0? . . . . . . . . . . Using MapServer 6.0, why dont my layers show up in GetCapabilities responses or are not anymore? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where do I nd my EPSG code? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How can I reproject my data using ogr2ogr? . . . . . . . . . . . . . . . . . . . . . . . . . . How can I help improve the documentation on this site? . . . . . . . . . . . . . . . . . . . . Whats with MapServers logo? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . found . . . . . . . . . . . . . . . . . . . .
870 871 871 872 873 873 873 874 874 875 877 879 881
20 License 21 Credits Bibliography Index
vi
MapServer Documentation, Release 6.0.1
Note: The entire documentation is also available as a single PDF document
and ePub document
If you plan on upgrading to the MapServer 6.0 release, be sure to review the MapServer Migration Guide. Table 1: Quick Links An Introduction to MapServer MapScript OGC Support and Conguration Development genindex installation Data Input Optimization Glossary About Maple Output Generation Utilities Errors Community Activities
Contents
Contents
CHAPTER 1
About
MapServer is an Open Source geographic data rendering engine written in C. Beyond browsing GIS data, MapServer allows you create geographic image maps, that is, maps that can direct users to content. For example, the Minnesota DNR Recreation Compass provides users with more than 10,000 web pages, reports and maps via a single application. The same application serves as a map engine for other portions of the site, providing spatial context where needed. MapServer was originally developed by the University of Minnesota (UMN) ForNet project in cooperation with NASA, and the Minnesota Department of Natural Resources (MNDNR). Later it was hosted by the TerraSIP project, a NASA sponsored project between the UMN and a consortium of land management interests. MapServer is now a project of OSGeo, and is maintained by a growing number of developers (nearing 20) from around the world. It is supported by a diverse group of organizations that fund enhancements and maintenance, and administered within OSGeo by the MapServer Project Steering Committee made up of developers and other contributors. Advanced cartographic output Scale dependent feature drawing and application execution Feature labeling including label collision mediation Fully customizable, template driven output TrueType fonts Map element automation (scalebar, reference map, and legend) Thematic mapping using logical- or regular expression-based classes Support for popular scripting and development environments PHP, Python, Perl, Ruby, Java, and .NET Cross-platform support Linux, Windows, Mac OS X, Solaris, and more Support of numerous Open Geospatial Consortium <OGC (OGC) standards WMS (client/server), non-transactional WFS (client/server), WMC, WCS, Filter Encoding, SLD, GML, SOS, OM A multitude of raster and vector data formats TIFF/GeoTIFF, EPPL7, and many others via GDAL
ESRI shaples, PostGIS, ESRI ArcSDE, Oracle Spatial, MySQL and many others via OGR Map projection support On-the-y map projection with 1000s of projections through the Proj.4 library
Chapter 1. About
CHAPTER 2
An Introduction to MapServer
Revision $Revision: 12521 $ Date $Date: 2011-09-06 10:48:20 -0700 (Tue, 06 Sep 2011) $ 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 Maple Making the Site Your Own Enhancing your site How do I get Help?
2.1 MapServer Overview

MapServer is a popular Open Source project whose purpose is to display dynamic spatial maps over the Internet. Some of its major features include: support for display and querying of hundreds of raster, vector, and database formats ability to run on various operating systems (Windows, Linux, Mac OS X, etc.) support for popular scripting languages and development environments (PHP, Python, Perl, Ruby, Java, .NET) on-the-y projections
high quality rendering fully customizable application output many ready-to-use Open Source application environments In its most basic form, MapServer is a CGI program that sits inactive on your Web server. When a request is sent to MapServer, it uses information passed in the request URL and the Maple 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 different vector and raster input data formats, and it can generate a multitude of output formats. Most pre-compiled MapServer distributions contain most all of its features. See Also: Compiling on Unix and Compiling on Win32 Note: MapScript provides a scripting interface for MapServer for the construction of Web and stand-alone applications. MapScript can be used independently of CGI MapServer, and it is a loadable module that adds MapServer capability to your favorite scripting language. MapScript currently exists in PHP, Perl, Python, Ruby, Tcl, Java, and .NET avors. This guide will not explicitly discuss MapScript, check out the MapScript Reference for more information.
2.2 Anatomy of a MapServer Application

A simple MapServer application consists of: Map File - a structured text conguration le for your MapServer application. It denes the area of your map, tells the MapServer program where your data is and where to output images. It also denes your map layers, including their data source, projections, and symbology. It must have a .map extension or MapServer will not recognize it. See Also: MapServer Maple Reference Geographic Data - MapServer can utilize many geographic data source types. The default format is the ESRI Shape format. Many other data formats can be supported, this is discussed further below in Adding data to your site. See Also: Vector Input Reference and Raster Input Reference HTML Pages - the interface between the user and MapServer . They normally sit in Web root. In its simplest form, MapServer can be called to place a static map image on a HTML page. To make the map interactive, the image is placed in an HTML form on a page. CGI programs are stateless, every request they get is new and they dont remember anything about the last time that they were hit by your application. For this reason, every time your application sends a request to MapServer, it needs to pass context information (what layers are on, where you are on the map, application mode, etc.) in hidden form variables or URL variables. A simple MapServer CGI application may include two HTML pages:
Chapter 2. An Introduction to MapServer
Figure 2.1: The basic architecture of MapServer applications.
2.2. Anatomy of a MapServer Application
Initialization File - uses a form with hidden variables to send an initial query to the web server and MapServer. This form could be placed on another page or be replaced by passing the initialization information as variables in a URL. Template File - controls how the maps and legends output by MapServer will appear in the browser. By referencing MapServer CGI variables in the template HTML, you allow MapServer to populate them with values related to the current state of your application (e.g. map image name, reference image name, map extent, etc.) as it creates the HTML page for the browser to read. The template also determines how the user can interact with the MapServer application (browse, zoom, pan, query). See Also: Templating MapServer CGI - The binary or executable le that receives requests and returns images, data, etc. It sits in the cgi-bin or scripts directory of the web server. The Web server user must have execute rights for the directory that it sits in, and for security reasons, it should not be in the web root. By default, this program is called mapserv Web/HTTP Server - serves up the HTML pages when hit by the users browser. You need a working Web (HTTP) server, such as Apache or Microsoft Internet Information Server, on the machine on which you are installing MapServer.
2.3 Installation and Requirements

2.3.1 Windows Installation
OSGeo4W is a new Windows installer that downloads and/or updates MapServer, add-on applications, and also other Open 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. Advanced gives you full access to choosing commandline tools and applications for MapServer that are not included in the Express install 4. Select packages to install
2.3. Installation and Requirements
Note: Click on the Default text beside the higher-level packages (such as Web) to install all of Webs subpackages, or click on the Skip text beside the sub-package (such as MapServer) to install that package and all of its dependencies. 5. Let the installer fetch the packages.
10
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 your desktop 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
11
8. Verify that MapServer is working
12
2.3.2 Hardware Requirements

MapServer runs on Linux, Windows, Mac OS X, Solaris, and more. To compile or install some of the required programs, you may need administrative rights to the machine. People commonly ask questions about minimum hardware specications for MapServer applications, but the answers are really specic to the individual application. For development and learning purposes, a very minimal machine will work ne. For deployment, you will want to investigate Optimization of everything from your data to server conguration.
2.3.3 Software Requirements

You need a working and properly congured Web (HTTP) server, such as Apache or Microsoft Internet Information Server, on the machine on which you are installing MapServer. OSGeo4W contains Apache already, but you can recongure 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, which will install a pre-congured web server, MapServer, and more. The FGS Linux Installer provides similar functionality for several Linux distributions. This introduction will assume you are using pre-compiled OSGeo4W Windows binaries to follow along. Obtaining MapServer or Linux or Mac OS X should be straightforward. Visit Download for installing pre-compiled MapServer builds 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 maples.
13
2.3.4 Skills
In addition to learning how the different components of a MapServer application work together and learning Map File syntax, building a basic application requires some conceptual understanding and prociency in several skill areas. You need to be able to create or at least modify HTML pages and understand how HTML forms work. Since the primary purpose of a MapServer application is to create maps, you will also need to understand the basics of geographic data and likely, map projections. As your applications get more complex, skills in SQL, DHTML/Javascript, Java, databases, expressions, compiling, and scripting may be very useful.
2.4 Introduction to the Maple

The .map le is the basic conguration le for data access and styling for MapServer. The le is an ASCII text le, and is made up of different objects. Each object has a variety of parameters available for it. All .map le (or maple) parameters are documented in the maple reference. A simple maple example displaying only one layer follows, as well as the map image output:
MAP NAME "sample" STATUS ON SIZE 600 400 SYMBOLSET "../etc/symbols.txt" EXTENT -180 -90 180 90 UNITS DD SHAPEPATH "../data" IMAGECOLOR 255 255 255 FONTSET "../etc/fonts.txt" # # Start of web interface definition # WEB IMAGEPATH "/ms4w/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" END # WEB # # Start of layer definitions # LAYER NAME global-raster TYPE RASTER STATUS DEFAULT DATA b l u e m a r b le.gif END # LAYER END # MAP
Note: Comments in a maple are specied with a # character MapServer parses maples from top to bottom, therefore layers at the end of the maple 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)
14
Figure 2.2: Rendered Bluemarble Image The above example is built on the following directory structure: The maple could be placed anywhere, as long as it is accessible to the web server. Normally, one would try to avoid placing it at a location that makes it accessible on the web. Let us say it is placed in /home/msuser/maples/ The location of the font le is given relative to the map le, in this case: /home/msuser/etc/fonts.txt The location of the datasets (bluemarble.gif ) is given relative to the map le, in this case: /home/msuser/data/ The location of the symbol le is given relative to the map le, in this case: /home/msuser/etc/symbols.txt The les generated by Mapserver will be placed in the directory /ms4w/tmp/ms_tmp/. The web server must be able to place les in this directory. The web server must make this directory available as /ms_tmp (if the web server is on www.ms.org, the web address to the directory must be: httpd://www.ms.org/ms_tmp/.
2.4.1 MAP Object

MAP NAME "sample" EXTENT -180 -90 180 90 # Geographic SIZE 800 400 IMAGECOLOR 128 128 255 END # MAP
EXTENT is the output extent in the units of the output map SIZE is the width and height of the map image in pixels IMAGECOLOR is the default image background color Note: MapServer currently uses a pixel-center based extent model which is a bit different from what GDAL or WMS use.
2.4. Introduction to the Maple
15
2.4.2 LAYER Object

starting with MapServer 5.0, there is no limit to the number of layers in a maple the DATA parameter is relative to the SHAPEPATH parameter of the MAP object if no DATA extension is provided in the lename, MapServer will assume it is ESRI Shape format (.shp) Raster Layers
LAYER NAME "bathymetry" TYPE RASTER STATUS DEFAULT DATA "bath_mapserver.tif" END # LAYER
See Also: Raster Data Vector Layers Vector layers of TYPE point, line, or polygon can be displayed. The following example shows how to display only lines from a TYPE polygon layer, using the OUTLINECOLOR parameter:
LAYER NAME "world_poly" DATA shapefile/countries_area.shp STATUS ON TYPE POLYGON CLASS NAME The World STYLE OUTLINECOLOR 0 0 0 END # STYLE END # CLASS END # LAYER
See Also: Vector Data
2.4.3 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 maple the following example shows how to display a road line with two colors by using overlayed STYLE objects
CLASS NAME "Primary Roads" STYLE SYMBOL "circle" COLOR 178 114 1 SIZE 15 END # STYLE
16
Figure 2.3: Rendered Bluemarble image with vector boundaries
STYLE SYMBOL "circle" COLOR 254 161 0 SIZE 7 END # STYLE END # CLASS
2.4.4 SYMBOLs
can be dened directly in the maple, or in a separate le the separate le method must use the SYMBOLSET parameter in the MAP object:
MAP NAME "sample" EXTENT -180 -90 180 90 # Geographic SIZE 800 400 IMAGECOLOR 128 128 255 SYMBOLSET "../etc/symbols.txt" END # MAP
where symbols.txt might contain:

SYMBOL NAME "ski" TYPE PIXMAP IMAGE "ski.png" END # SYMBOL
and the maple would contain:
17
Figure 2.4: Rendered Bluemarble image with styled roads
18
LAYER ... CLASS NAME "Ski Area" STYLE SYMBOL "ski" END # STYLE END # CLASS END # LAYER
Figure 2.5: Rendered Bluemarble image with skier symbol See Also: Cartographical Symbol Construction with MapServer, Symbology Examples, and SYMBOL
2.4.5 LABEL
dened within a CLASS object the LABELITEM parameters in the LAYER object can be used to specify an attribute in the data to be used for labeling. The label is displayed by the FONT, declared in the FONTSET le (set in the MAP object). The FONTSET le contains references to the available font names. ENCODING describes which encoding is used in the le (see Display of International Characters in MapServer). An example LABEL object that references one of the above fonts might look like:
19
LABEL FONT "sans-bold" TYPE truetype ENCODING "UTF-8" SIZE 10 POSITION LC PARTIALS FALSE COLOR 100 100 100 OUTLINECOLOR 242 236 230 END # LABEL
Figure 2.6: Rendered Bluemarble image with skier symbol and a label See Also: LABEL, FONTSET
2.4.6 CLASS Expressions

MapServer supports three types of CLASS Expressions in a LAYER (CLASSITEM in LAYER determines the attribute to be used for the two rst types of expressions): 1. String comparisons
EXPRESSION "africa"
2. Regular expressions
20
EXPRESSION /^9|^10/
3. Logical expressions
EXPRESSION ([POPULATION] > 50000 AND [LANGUAGE] eq FRENCH)
Note: Logical expressions should be avoided wherever possible as they are very costly in terms of drawing time. See Also: Expressions
2.4.7 INCLUDE
Added to MapServer 4.10, any part of the maple can now be stored in a separate le and added to the main maple using the INCLUDE parameter. The lename to be included can have any extension, and it is always relative to the main .map le. Here are some potential uses: LAYERs can be stored in les and included to any number of applications STYLEs can also be stored and included in multiple applications The following is an example of using maple includes to include a layer denition in a separate le: If shadedrelief.lay contains:
LAYER NAME shadedrelief STATUS ON TYPE RASTER DATA GLOBALeb3colshade.jpg END # LAYER
therefore the main maple would contain:

MAP ... INCLUDE "shadedrelief.lay" ... END # MAP
The following is an example of a maple where all LAYER s are in separate .lay les, and all other objects (WEB, REFERENCE, SCALEBAR, etc.) are stored in a .ref le:
MAP NAME "base" # # include reference objects # INCLUDE "../templates/template.ref" # # Start of layer definitions # INCLUDE "../layers/usa/usa_outline.lay" INCLUDE "../layers/canada/base/1m/provinces.lay" INCLUDE "../layers/canada/base/1m/roads_atlas_of_canada_1m.lay" INCLUDE "../layers/canada/base/1m/roads_atlas_of_canada_1m_shields.lay" INCLUDE "../layers/canada/base/1m/populated_places.lay" END # MAP
21
Warning: Maples must have the .map extension or MapServer will not recognize them. Include les can have any extension you want, however. See Also: INCLUDE
2.4.8 Get MapServer Running

You can test if MapServer is working by running the Mapserver executable (mapserv) with the -v parameter on the command line (./mapserv -v). Depending on your conguration, the output could be something like this:
MapServer version 6.0.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=WMS_SERVER INPUT=SHAPEFILE
You can also send a HTTP request directly to the MapServer CGI program without passing any conguration variables (e.g. http://your.domain.name/cgi-bin/ms4/mapserv.exe). If you receive the message, No query information to decode. QUERY_STRING not set., your installation is working.
2.4.9 Get Demo Running

Download the MapServer Demo. UnZip it and follow the directions in ReadMe.txt. You will need to move the demo les to their appropriate locations on your web server, and modify the Map File and HTML pages to reect the paths and URLs of your server. Next, point your browser to init.html and hit the initialize button. If you get errors, verify that you have correctly modied the demo les.
2.5 Making the Site Your Own

Now that you have a working MapServer demo, you can use the demo to display your own data. Add new LAYERs to your Map le that refer to your own geographic data layers (you will probably want to delete the existing layers or set their status to OFF). Unless you are adding layers that fall within the same geographic area as the demo, modify MAP EXTENT to match the extent of your data. To determine the extent of your data, you can use ogrinfo. If you have access to a GIS, you could use that as well. The MAP EXTENT needs to be in the units of your output projection. If you add geographic data layers with different geographical reference systems, you will need to modify your Map File to add a PROJECTION block to the MAP (denes the output projection / geograpical reference system) and each of the LAYERs (denes the geographical reference system of the layer dataset).
2.5.1 Adding Data to Your Site

MapServer supports several data input formats natively, and many more if it is compiled with the open source libraries GDAL and OGR.
2.5.2 Vector Data

Vector data includes features made up of points, lines, and polygons. MapServer support the ESRI Shape format by default, but it can be compiled to support spatially enabled databases such as PostgreSQL-PostGIS, and le formats such as Geography Markup Language (GML), MapInfo, delimited text les, and more formats with OGR. 22 Chapter 2. An Introduction to MapServer
See the Vector Data reference for examples on how to add different geographic data sources to your MapServer project.
2.5.3 Raster Data

Raster data is image or grid data. By default, MapServer supports Tiff/GeoTiff, and EPPL7. With GDAL, it supports GRASS, Jpeg2000, ArcInfo Grids, and more formats. If you do compile MapServer with GDAL, which includes tiff support, do not compile with native tiff support, as this will cause a conict. More specic information can be found in the Raster Data reference.
2.5.4 Projections
Because the earth is round and your monitor (or paper map) is at, distortions will occur when you display geographic data in a two-dimensional image. Projections allow you to represent geographic data on a at surface. In doing so, some of the original properties (e.g. area, direction, distance, scale or conformity) of the data will be distorted. Different projections excel at accurately portraying different properties. A good primer on map projections can be found at the University of Colorado. With MapServer, if you keep all of your spatial data sets in the same projection (or unprojected Latitude and Longitude), you do not need to include any projection info in your Map File. In building your rst MapServer application, this simplication is recommended. On-the-y projection can be accomplished when MapServer is compiled with Proj.4 support. Instructions on how to enable Proj.4 support on Windows can be found on the Wiki.
2.6 Enhancing your site

2.6.1 Adding Query Capability
There are two primary ways to query spatial data. Both methods return data through the use of templates and CGI variable replacement. A QUERYMAP can be used to map the results of the query. To be queryable, each maple LAYER must have a TEMPLATE dened, or each CLASS within the LAYER must have a TEMPLATE dened. More information about the CGI variables used to dene queries can be found in the MapServer CGI Reference.
2.6.2 Attribute queries

The user selects features based on data associated with that feature. Show me all of the lakes where depth is greater than 100 feet, with depth being a eld in the Shape dataset or the spatial database. Attribute queries are accomplished by passing query denition information to MapServer in the URL (or form post). Mode=itemquery returns a single result, and mode=itemnquery returns multiple result sets. The request must also include a QLAYER, which identies the layer to be queried, and a QSTRING which contains the query string. Optionally, QITEM, can be used in conjunction with QSTRING to dene the eld to be queried. Attribute queries only apply within the EXTENT set in the map le.
2.6.3 Spatial queries

The user selects features based on a click on the map or a user-dened selection box. Again the request is passed through a URL or form post. By setting mode=QUERY, a user click will return the one closest feature. In
2.6. Enhancing your site
23
mode=NQUERY, all features found by a map click or user-dened selection box are returned. Additional query options can be found in the CGI documentation.
2.6.4 Interfaces
See: OpenLayers http://openlayers.org
2.6.5 Data Optimization

Data organization is at least as important as hardware conguration in optimizing a MapServer application for performance. MapServer is quite efcient at what it does, but by reducing the amount of processing that it needs to do at the time of a user request, you can greatly increase performance. Here are a few rules: Index Your data - By creating spatial indexes for your Shape datasets using shptree. Spatial indexes should also be created for spatially aware databases such as PostGIS and Oracle Spatial. Tile Your Data - Ideally, your data will be sliced up into pieces about the size in which it will be displayed. There is unnecessary overhead when searching through a large Shape dataset or image of which you are only going to display a small area. By breaking the data up into tiles and creating a tile index, MapServer only needs to open up and search the data les of interest. Shape datasets can be broken into smaller tiles and then a tileindex Shape dataset can be created using the tile4ms utility. A tileindex Shape dataset for raster les can also be created. Pre-Classify Your Data - MapServer allows for the use of quite complex EXPRESSIONs to classify data. However, using logical and regular expressions is more resource intensive than string comparisons. To increase efciency, you can divide your data into classes ahead of time, create a eld to use as the CLASSITEM and populate it with a simple value that identies the class, such as 1,2,3, or 4 for a four class data set. You can then do a simple string comparison for the class EXPRESSION. Pre-Process Your Images - Do resource intensive processing up front. See the Raster Data reference for more info. Generalize for Overview - create a more simple, generalized data layer to display at small scales, and then use scale-dependent layers utilizing LAYER MINSCALE and LAYER MAXSCALE to show more detailed data layers as the user zooms in. This same concept applies to images. See Also: Optimization
2.7 How do I get Help?

2.7.1 Documentation
Ofcial MapServer documentation lives here on this site. User contributed documentation exists on the MapServer Wiki.
2.7.2 Users Mailing List

Register and post questions to the MapServer Users mailing list. Questions to the list are usually answered quickly and often by the developers themselves. A few things to remember: 1. Search the archives for your answer rst, people get tired of answering the same questions over and over. 24 Chapter 2. An Introduction to MapServer
2. Provide version and conguration information for your MapServer installation, and relevant snippets of your map and template les. 3. Always post your responses back to the whole list, as opposed to just the person who replied to your question.
2.7.3 IRC
MapServer users and developers can be found on Internet Relay Chat. The channel is #mapserver on irc.freenode.net.
2.7.4 Reporting bugs

Bugs (software and documentation) are reported on the Mapserver issue tracker.
2.7.5 Gallery
See examples (currently shut down) of existing MapServer applications.
2.7.6 Tutorial
Perry Nacionales built a great Tutorial on how to build a MapServer application (Mapserver version 5).
2.7.7 Test Suite

Download the MapServer Test Suite for a demonstration of some MapServer functionality.
2.7.8 Books
Web Mapping Illustrated, a book by Tyler Mitchell that describes well and provides real-world examples for the use of Web mapping concepts, Open Source GIS software, MapServer, Web services, and PostGIS. Mapping Hacks, by Schuyler Erle, Rich Gibson, and Jo Walsh, creatively demonstrates digital mapping tools and concepts. MapServer only appears in a handful of the 100 hacks, but many more are useful for concepts and inspiration. Beginning MapServer: Opensource GIS Development, by Bill Kropla. According to the publisher, it covers installation and conguration, basic MapServer topics and features, incorporation of dynamic data, advanced topics, MapScript, and the creation of an actual application.
2.7. How do I get Help?
25
26
CHAPTER 3
MapServer Tutorial
Author Pericles S. Nacionales Contact pnaciona at gmail.com Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Updated 2010-04-07 This tutorial was designed to give new users a quick (relatively speaking) introduction to the concepts behind MapServer. It is arranged into four sections with each section having one or more examples and increasing in complexity. Users can jump to any section at any time although it is recommended that absolute beginners work on the rst three sections sequentially. Section one focuses on basic MapServer conguration concepts such as layer and class ordering, using vector and raster data, projections and labeling. Section two provides examples on how to use HTML templates to create a simple interface for an interactive web mapping application. Section three introduces the use of HTML templates to provide a query interface. Finally, section four introduces some advanced user interface concepts.
3.1 Tutorial Timeframe

While some users can go through this tutorial in one day, those who work on each example in detail can probably expect to nish in one week.
3.2 Tutorial Data

The dataset used in this tutorial was taken from the U.S. Department of the Interiors National Atlas of the United States. You can visit their web site at http://www.nationalatlas.gov. The dataset was clipped to the upper great lakes region (Minnesota, Michigan, and Wisconsin) to reduce storage size. Additional raster images were added courtesy of the TerraSIP project at the University of Minnesota. When using this tutorial, you are encouraged to use your own dataset. Like MapServer itself, this tutorial is open and customizable to anyone. This was done in the hope that someone (or some folks) will help design and develop it further.
27
Download the data (and all html les) for this tutorial at http://download.osgeo.org/mapserver/docs/mapservertutorial.zip.
3.3 Before Using the Tutorial

There are some prerequisites to using this tutorial: 1. Users will need to have a web server installed and running on your computer. This web server has to have support for common gateway interface (CGI) programs. 2. Users should have a basic understanding of web servers and internet security. A poorly congured web server can easily be attacked by malicious people. At the very least your software installation will be corrupted and youll lose hours of productivity, at worst your computer can be used to attack other computers on the internet. 3. It is recommended that users of this tutorial read the Introduction to MapServer before proceeding with this tutorial. 4. To use this tutorial, users will need to have a web server and a MapServer CGI program (mapserv or mapserv.exe) installed in their systems. MapServer source code is available for download here. Documentation exists on how to compile and install MapServer: for UNIX users, please read the MapServer UNIX Compilation and Installation HOWTO. Windows users should read the MapServer Win32 Compilation and Installation HOWTO In addition, Windows users can also download precompiled binaries from here.
3.4 Windows, UNIX/Linux Issues

3.4.1 Paths
This tutorial was created in Linux/UNIX but should work with minimal changes on Windows platform. The main differences are the paths in the map les. Windows users need to specify the drive letter of the hard disk where their tutorial les reside. Heres an example: A UNIX map le might include a parameter like this:
SHAPEPATH "/data/projects/tutorial/data"
In Windows, the same parameters might look like this:

SHAPEPATH "C:/data/projects/tutorial/data"
or:
SHAPEPATH "C:\data\projects\tutorial\data".
Notice that either slash or backslash works in Windows. The usual backslash may work well for you if you want to make a distinction between virtual (as in URLs or web addresses) and local paths in your map le. However, if you plan to move your application to UNIX at some point, youll have the tedious task of switching all backslashes to slashes. While were on the subject of paths, keep in mind that paths in maples are typically relative to the systems root directory: the slash (/) in UNIX or some drive letter (C:) in Windows. This is true except when specically asked to enter a URL or when referencing a URL. When working with HTML template les, paths are relative to the web servers root directory. i.e., /tutorial/ is relative to http://demo.mapserver.org/. Please read http://www.alistapart.com/articles/slashforward/ for a few insights on URLs. 28 Chapter 3. MapServer Tutorial
3.4.2 Executable
Another issue is that UNIX executable les dont require a .EXE or .COM extensions, but they do in Windows. If you are using Windows, append .exe to all instances of /cgi-bin/mapserv or /cgi-bin/mapserv50 to make it /cgibin/mapserv.exe or /cgi-bin/mapserv50.exe.
3.5 Other Resources

Other documentation exist to give you better understanding of the many customizations MapServer offer. Please visit the MapServer documentation page at http://www.mapserver.org. There you will nd several HOWTO documents, from getting started to using MapScript, a scripting interface for MapServer.
Back to Tutorial home | Proceed to Section 1
3.6 Section 1: Static Maps and the MapFile

Take a shapele. Any shapele. We can use MapServer to display that shapele on a web browser. Look... Example 1.1 - A map with a single layer We can display the same shapele repeatedly. We can display the polygon attributes on one LAYER and and the line attributes on another... Example 1.2 - A map with two layers And we can select which parts of the shapele to display. We do this using the CLASS object... Example 1.3 - Using classes to make a useful map We can also label our maps... Example 1.4 - Labeling layers and label layers Or add raster data such as satellite images, aerial photographs, or shaded reliefs... Example 1.5 - Adding a raster layer We can reproject our data from just about any projection to just about any... Yeah, check it out! Example 1.6 - Projection/Reprojection <example1-6 And we can use layers from other map servers on the internet (as long as they are WMS servers)... Example 1.7 - Adding a WMS layer MapServer can output to various formats such as PDF and GeoTIFF. Example 1.8 - A different output format MapServer not only generates static maps, it can also create interactive maps... Example 1.9 - The difference between map and browse mode
Back to Tutorial home | Proceed to Section 2
3.5. Other Resources
29
3.7 Section 2: CGI variables and the User Interface

So far we have only looked at the maple when creating maps. In creating web mapping applications, it is usually our intention to make maps that can be changed by the user (of the application) interactively. That is, a user should be able to change the content of (or the information in) the map. To accomplish this interactivity, we use the MapServer HTML templates.
3.7.1 HTML Templates

A MapServer HTML template is essentially an HTML le with a few MapServer specic tags. These tags are the MapServer CGI variables and are enclosed in square brackets []. When the MapServer CGI program processes an application, it rst parses the query string and the maple, and produces the necessary output. Some of this output will need to be written to the HTML template le which you would have to also specify in the maple using the web template keyword (or in a separate HTML initialization le). The CGI program will replace all the variables in the HTML template with the proper value before sending it back to the web browser. If you are to directly view an HTML template on a web browser, there wont be any maps rendered and you will instead get blank images and other junk. Variables MapServer provides several variables for web mapping: the img variable which youve seen in Example 1.9 is but one example. There area few core CGI variables originally designed as part of the mapping interface but practically all the maple parameters can be dened as variables. The denitive reference to the CGI variables can be found at here. We can also dene our own variables, which MapServer will pass along to our application. For example, we can create a variable called root to represent the root directory of this tutorial, the value for root will then be /tutorial. When the MapServer CGI program processes our HTML template, it will replace every instance of he [root] tag with /tutorial. You will see this in action for each of the following examples.
3.7.2 Examples
So, lets build an interactive interface for our application... Users of a web mapping application should be able to pan and zoom on the map: Example 2.1 - Pan and Zoom Controls They also should be able to turn on and off layers on a map: Example 2.2 - Layer Control A map should always include a scalebar. Example 2.3 - Adding a Scalebar If users are to navigate through the map, a reference map should be provided: Example 2.4 - Adding a Reference Map The map should include a legend. Example 2.5- Adding a Legend
Back to Section 1 index | Proceed to Section 3
30
Chapter 3. MapServer Tutorial
3.8 Section 3: Query and more HTML Templates

To learn more about query and HTML templates with MapServer, see examples 3.1 to 3.4 in the Tutorial Viewer.
Back to Section 2 index | Proceed to Section 4
3.9 Section 4: Advanced User Interfaces

To learn more about advanced navigation such as pan and rubber-band zoom with Javascript and MapServer CGI, see examples 4.1 to 4.4 in the Tutorial Viewer.
Back to Section 3 index | Tutorial home
Begin tutorial
3.8. Section 3: Query and more HTML Templates
31
32
Chapter 3. MapServer Tutorial
CHAPTER 4
Installation
4.1 Compiling on Unix

Author J.F. Doyon Contact jdoyon at nrcan.gc.ca Author Howard Butler Contact hobu.inc at gmail.com Revision $Revision: 12501 $ Date $Date: 2011-08-28 02:51:27 -0700 (Sun, 28 Aug 2011) $ Table of Contents Compiling on Unix Introduction Obtaining the necessary software libgd Anti-Grain Geometry Support OGC Support Spatial Warehousing Compiling Installation
4.1.1 Introduction
The University of Minnesotas MapServer is an open-source and freely available map rendering engine for the web. Due to its open-source nature, it can be compiled on a wide variety of platforms and operating systems. We will focus on how to obtain, compile and install MapServer on UNIX-like platforms. You might also check the MapServerCompilation wiki page for additional information.
33
4.1.2 Obtaining the necessary software

You can obtain the MapServer source code as well as the demo package from the Download section. You can also get the latest MapServer source code from Subversion. Required External Libraries libpng: libpng should be on your system by default. 1.2.12 is the current release with security patches, although versions all the way back to 1.2.7 should work. freetype: Version 2.x or above is required by GD. GD: libgd is used by MapServer for rendering images. Version 2.0.28 or greater required. Version 2.0.29 or later is required to use curved (following) labels, and version 2.0.34 is required for antialiasing (1 pixel wide lines/outlines). zlib: Zlib should be on your system by default. 1.2.1 is the current release with security patches. Highly Recommended Libraries libproj: libproj provides projection support for MapServer. Version 4.4.6 or greater is required. libcurl: libcurl is the foundation of OGC (WFS/WMS/WCS) client and server support. Version 7.10 or greater is required OGR: OGR provides access to at least 18 different vector formats. GDAL: GDAL provides access to at least 42 different raster formats. AGG: AGG (Anti-Grain Geometry) is an optional dependency to enable high quality antialiased output for vector data. Currently versions 2.4 and 2.5 are identical featurewise, and only vary in their licence (2.4 is BSD, 2.5 is GPL) Optional External Libraries libtiff: libtiff provides TIFF (Tagged Image File Format) reading support to MapServer. libgeotiff libgeotiff provides support to read GeoTIFF les (TIFF les with geographic referencing). libjpeg: libjpeg allows MapServer to render images in JPEG format. A sufcient version should be installed by default on your system. Version 6b is the current version and dates back to 1998. GEOS: GEOS allows MapServer to do spatial predicate and algebra operations (within, touches, etc & union, difference, intersection). Requires version 4.10 or greater. libxml: libxml is required to use OGC SOS support in MapServer (versions 4.10 and greater). SDE Client Library: The client libraries for your platform should be part of the ArcSDE media kit. They are not publicly available for download. Oracle Spatial OCI: The client libraries for your platform are available for download from Oracles website. Ideally, your client library matches the database you are querying from, but this is not a hard requirement. libpq: libpq is required to support the use of PostGIS geometries within the PostgreSQL database. Ideally, your client library matches the database you are querying from. pdib (lite): PDFlib Lite is the Open Source version of PDFlib that allows MapServer to produce PDF output. Version 4.0.3 or greater is required.
34
Chapter 4. Installation
libming: libming provides Macromedia Flash output to MapServer. Version 0.2a is required. Later versions are not known to work.
4.1.3 libgd
There are a number of issues that you should be aware of when using GD in combination with MapServer. Minimum libgd versions MapServer aggressively takes advantage of new features and bug xes in the latest versions of libgd. The minimum required version to run MapServer is 2.0.29. Upgrading to at least 2.0.34 is advised as it includes an important bug x for antialiased lines. Congure should detect which version of libgd you have installed, but you can quickly check yourself by issuing the following command:
gdlib-config --version
libiconv If you intend to use international character sets, your version of libgd must be compiled against the GNU iconv libraries. If you are using a pre-packaged version, it is very likely that this is the case. To check for yourself, issue the following command and look for -liconv in the output:
gdlib-config --libs
Pre-packaged/system libraries If you intend to use your systems libgd, ensure that you have the development package also installed so MapServer can nd and use the appropriate headers. MacOSX A useful FAQ on for libgd on OSX is available at http://www.libgd.org/DOC_INSTALL_OSX FreeType support The GD you compile MapServer against MUST be compiled against the FreeType library in order to use TrueType fonts. MapServer no longer uses its own interface to FreeType, using it through GD instead. When you run your congure script, look for the following output:
using GD ( -DUSE_GD_GIF -DUSE_GD_PNG -DUSE_GD_JPEG -DUSE_GD_WBMP -DUSE_GD_TTF -DGD_HAS_GDIMAGEGIFPTR) from system libs.
If your GD is built against FreeType, you will see either -DUSE_GD_TTF (Or -DUSE_GD_FT for Freetype 2.x) part. If its missing, you will need to recompile your GD to make sure you include FreeType support. See the GD documentation for more information. Also note that the congure script looks for the FreeType library separately as well, generating output looking somewhat like this:
4.1. Compiling on Unix
35
checking where FreeType is installed... checking for FT_Init_FreeType in -lfreetype... yes using libfreetype -lfreetype from system libs.
Even though you have FreeType installed on your system and the congure script nds it, does NOT mean you will have TrueType font support. GD MUST be compiled against FreeType either way. 1px Anti-Aliasing and segfaults Versions of libgd earlier than 2.0.34 contain a one very signicant bug and will always cause a segfault if you attempt to do one pixel wide antialiasing. You can manually patch older gds, or better yet upgrade to at least GD 2.0.34. In gd.c, function gdImageSetAAPixelColor() change:
int dr,dg,db,p,r,g,b; p = gdImageGetPixel(im,x,y);
to
int dr,dg,db,p,r,g,b; if (!gdImageBoundsSafeMacro (im, x, y)) return; p = gdImageGetPixel(im,x,y);
More detail about this patch (if you need any) was described by Steve Lime in a post to mapserver-users. Curved label support ANGLE FOLLOW, a new feature that allows MapServer to draw curved labels about a linear feature like a road, requires libgd 2.0.29 and TrueType font support. Congure should autodetect if you have a sufcient libgd and TrueType support to be able to use this feature.
4.1.4 Anti-Grain Geometry Support

Since version 5.0 MapServer supports the AGG rendering backend. Download the 2.4 tarball from the antigrain website and just type make in the root directory. If you intend on using mapscript, you must beforehand tweak the agg makele to add -fPIC to the compiler options.
4.1.5 OGC Support

MapServer provides support for many OGC specications. At 4.2.3, it provides support for WMS (Web Mapping Service), SLD (Styled Layer Descriptor), WFS (Web Feature Service), and experimental support for WCS (Web Coverage Service). WMS support
WMS Server
Support for this specication is automatically enabled when you include PROJ.4 support. (with-proj) You can check this yourself by looking for the following in your congure output:
checking whether we should include WMS support... OGC WMS compatibility enabled (-DUSE_WMS).
36
If, for some reason you DONT want WMS support, you can force it off by passing without-wms to your congure script. More information on using this feature is available in the WMS Server HOWTO available on the MapServer website.
WMS Client
Cascading is also supported. This allows mapserver to transparently fetch remote layers over WMS, basically acting like a client, and combine them with other layers to generate the nal map. In order to enable this feature, you will need to pass the with-wmsclient option to the congure script. MapServer will automatically look for libcurl, which is also required. To verify that the WMS Client feature is enabled, check the output from the congure script:
checking whether we should include WMS Client Connections support... OGC WMS Client Connections enabled (-DUSE_WMS_LYR).
Note that this feature is disabled by default, you have to specically request it. More information on using this feature is available in the WMS Client HOWTO available on the MapServer website. WFS support
WFS Server
Support for this specication is enabled by passing the congure script the with-wfs option. OGR and PROJ.4 support is required. You can check this yourself by looking for the following in your congure output:
checking whether we should include WFS Server support... OGC WFS Server support enabled (-DUSE_WFS_SVR).
Note that this feature is disabled by default, you have to specically request it. More information on using this feature is available in the WFS Server HOWTO available on the MapServer website.
WFS Client
MapServer can also act as a WFS client. This effectively means that MapServer reads its data from a remote servers WFS output and renders it into a map, just like it would when reading data from a shapele. In order to enable this feature, you will need to make sure you include OGR (Built with Xerces support) and PROJ.4 support, and pass the with-wfsclient option to your congure script. MapServer will automatically look for libcurl, which is also required. To verify that the WFS Client feature is enabled, check the output from the congure script:
checking whether we should include WFS Client Connections support... OGC WFS Client Connections enabled (-DUSE_WFS_LYR).
Note that this feature is disabled by default, you have to specically request it. More information on using this feature is available in the WFS Client HOWTO available on the MapServer website.
37
4.1.6 Spatial Warehousing

MapServer can use a wide variety of sources of data input. One of the solutions growing in popularity is to use spatially enabled databases to store data, and to use them directly to draw maps for the web. Here you will nd out how to enable mapserver to talk to one of these products. Please refer to the MapFile reference for more details on how to use these. This section only details how to compile MapServer for their use. PostGIS PostGIS adds support for geographic objects to the PostgreSQL object-relational database. In effect, PostGIS spatially enables the PostgreSQL server, allowing it to be used as a backend spatial database for geographic information systems (GIS), much like ESRIs SDE or Oracles Spatial extension. PostGIS is included in many distributions packaging system, but you can also roll your own if needed. MapServer can use PostGIS as a data source. In order to do so simply use with-postgis when running your congure script.
--with-postgis=/usr/local/pgsql/bin/pg_config
ArcSDE MapServer allows you to use SDE as a data source both for geometry and attributes. In order to achieve this, you must have the SDE client librairies at your disposition, and have them installed on the machine running MapServer. In order to enable SDE support in MapServer, you have to compile it with two options specied:
--with-sde=/opt/sdeexe90 --with-sde-version=90
Oracle Spatial Oracles Spatial Warehousing cartridge is also supported by MapServer. In order to connect to it, you will need to compile MapServer against the Oracle libraries by passing the with-oraclespatial argument to your congure script. You will very likely need an ORACLE_HOME environment variable set to have it congure things correctly.
--with-oraclespatial=/opt/oracle
4.1.7 Compiling
First prepare the ground by making sure all of your required and/or recommended libraries are installed before attempting to compile MapServer. This will make your life much less complicated ;). Here is the order that I usually use: 1. Compile GD. This often means acquiring libjpeg, libpng, zlib, and freetype before actually compiling the library. You shouldnt have too much trouble nding binaries of the libraries that GD requires, and often, they will already be installed with your system. On unix, Ive had very little luck nding pre-compiled binaries of the required GD library. See libgd section for notes about patching libgd if you plan to use antialiasing. 2. Compile GDAL/OGR. Describing how to compile GDAL/OGR is beyond the scope of this document. If you have requirements for lots of different formats, make sure to install those libraries rst. I often nd that building up a GDAL/OGR library often takes as long as compiling MapServer itself! 3. Compile Proj.4. Proj.4 is a straight-forward congure/make/make install library.
38
4. Compile libcurl. libcurl is a straight-forward congure/make/make install library. 5. Compile/install optional libraries. These might include SDE, PostGIS, Oracle Spatial, AGG, Ming, PDFlib, or MyGIS. Mix and match as you need them. 6. Unpack the MapServer tarball and cd into the mapserver directory:
[user@host user]$ tar -zxvf mapserver-X.Y.Z.tar.gz
7. Congure your environment using congure. I often place my congure command in its own le and changes its mode to be executable (+x) to save typing and have a record of how MapServer was congured.
./configure --with-sde=/usr/sde/sdeexe90 \ --with-sde-version=90 \ --with-ogr=/usr/local/bin/gdal-config \ --with-gdal=/usr/local/bin/gdal-config \ --with-httpd=/usr/sbin/httpd \ --with-wfsclient \ --with-wmsclient \ --enable-debug \ --with-curl-config=/usr/bin/curl-config \ --with-proj=/usr/local \ --with-tiff \ --with-gd=/usr/local/ \ --with-jpeg \ --with-freetype=/usr/ \ --with-oraclespatial=/usr/oracle \ --with-threads \ --with-wcs \ --with-postgis=/usr/local/database/bin/pg_config \ --with-libiconv=/usr \ # new in 4.8 --with-geos=/usr/local/bin/geos-config \ # new in 4.8 --with-libiconv=/usr \ # new in 4.8 --with-xml2-config=/usr/bin/xml2-config \ # new in 4.10 --with-sos \ # new in 4.10 --with-agg=/path/to/agg-2.4
8. Now that you have congured your build options and selected all the libraries you wish mapserver to use, youre ready to compile the source code into an executable. This is actually quite simple, just execute make:
[user@host mapserver]$ make
9. There is no make install step in the installation of MapServer. The output of the compilation of MapServer is a binary executable that you can use in a CGI execution environment. To make sure all went well, look for the le called mapserv
[user@host mapserver]$ ls -al mapserv -rwxr-xr-x 1 user user 351177 Dec 21 11:38 mapserv
A simple test is to try and run it:

[user@host mapserver]$ ./mapserv This script can only be used to decode form results and should be initiated as a CGI process via a httpd server. [user@host mapserver]$
The message above is perfectly normal, and means exactly what it says. If you get anything else, something went terribly wrong.
39
4.1.8 Installation
MapServer binary The MapServer program itself consists of only one le, the mapserv binary executable. This is a CGI executable, meant to be called and run by your web server. In this section, we will assume you are running Apache under its default directory structure in /usr/local/apache. You may need to have privileges to edit your httpd.conf (the main apache conguration le), or have someone (such as your webmaster) help you with the conguration details. The main goal is to get the mapserv binary installed in a publicly accessible directory that is congured to run CGI programs and scripts.
The basic install

Under a default conguration, the CGI directory is /usr/local/apache/cgi-bin (RedHat users will use /home/httpd/cgi-bin). Placing the mapserv le in this directory makes it accessible by the following URL: http://yourhostname.com/cgi-bin/mapserv. When accessing this URL through your web client, you should expect the following output if all has worked well: No query information to decode. QUERY_STRING is set, but empty. If you get this message, youre done installing MapServer. Common problems
File permissions
The most common problem one is likely to encounter when attempting to install the binary are permissions issues: You do not have write permissions into your web servers CGI Directory. Ask your webmaster to install the le for you. The web server gives you a 403 Permission denied error. Make sure the user the web server runs as (usually nobody) has execute permission on the binary executable. Making the le world executable is perfectly ne and safe:
[user@host cgi-bin]$ chmod o+x mapserv
Apache errors
You may receive a few different type of errors as well if your web server conguration isnt right: 500 Internal server error: This is a fairly generic error message. All it basically tells you is that the web server was unsuccessful in running the program. You will have to consult the web servers error log to nd out more, and may need to enlist the help of your webmaster/system administrator. Where to go once youve got it compiled The An Introduction to MapServer document provides excellent coverage of getting started with MapServer.
40
4.2 Compiling on Win32

Author Pericles Nacionales Contact pnaciona at gmail.com Revision $Revision: 12501 $ Date $Date: 2011-08-28 02:51:27 -0700 (Sun, 28 Aug 2011) $ Table of Contents Compiling on Win32 Introduction Compiling Set up a Project Directory Download MapServer Source Code and Supporting Libraries The MapServer source code Set Compilation Options Compile the Libraries Compile MapServer Compiling MapServer with PostGIS support Common Compiling Errors Installation Other Helpful Information Acknowledgements
4.2.1 Introduction
This document provides a simple set of compilation procedures for MapServer on Win32 platforms. If youve made it this far, chances are you already know about MapServer and are at least tempted to try compiling it for yourself. Pre-compiled binaries for MapServer are available from a variety of sources. Refer to Windows. Building MapServer for win32 platforms can be a daunting task, so if existing binaries are sufcient for your needs, it is strongly advised that they be used in preference to trying to build everything from source. However, there can be a variety of reasons to want to build MapServer from source on win32. Reasons include the need to enable specic options, to build with alternate versions of support libraries (such as GDAL), the desire for MapScript support not part of the core builds, the need to debug and x bugs or even to implement new features in MapServer. To make it easy for users and developers, Ive made a list of steps to compile MapServer. Background information is provided in each step, along with examples. Each example is a continuation of the previous one and in the end will produce the MapServer DLL (libmap.dll), the CGI program (the mapserv.exe), and utility programs. Warning: This document may refer to older library versions. You may want to try to use more recent library versions for your build.
4.2.2 Compiling
If you are new to Windows programming, please follow this document carefully. The compilation steps are fairly simple but Ive added a few blurbs in each step to help you understand how MapServer compiles. For the more experienced programmers, perhaps reading the README.Win32 that accompanies the MapServer source code would be more useful. For those who are antsy, compiling MapServer involves download and unpacking the source codes,
4.2. Compiling on Win32
41
editing the make les, and invoking Microsofts Visual C++ compiler from the command prompt. The resulting mapserv.exe is the CGI program that installs in the cgi-bin directory of your web server. For those who are willing to take the time, the compilation steps follow.
4.2.3 Set up a Project Directory

Before you start to compile MapServer, I recommend creating a directory called projects where you can put the source code for MapServer and its supporting libraries. Since you will be working with DOS-style commands, you might as well get used to the Windows command prompt. For Windows 95/98 users the command processor would be called command.com. For Windows NT/2000/XP, it would be cmd.exe. So re up the old command prompt and go to the drive where you want to create the project directory. Here is an example of how to create a directory called projects on the C: drive:
C:\Users> mkdir C:\Projects
To go to that directory:
C:\Users> cd \Projects C:\Projects>
From the projects directory, you can extract the source codes for MapServer and its libraries. Now youre ready to download the source codes.
4.2.4 Download MapServer Source Code and Supporting Libraries

After creating a project directory, download the MapServer source code and the codes for the supporting libraries and save the source code packages in the newly created projects directory. These source codes are usually packaged as ZIP, or as UNIX TAR and GZIP les. Youll need a software that can unzip these packages. 7-Zip is an example of software that can handle these les. Cygwin is a free, open-source software package which is a port of these tools on Windows. You can use the gzip and tar utilities from this tool collection. Cygwin is available from http://www.cygwin.com. In order to compile the MapServer CGI program, you must download a few required and optional libraries. At its simplest conguration, MapServer only requires the GD (to provide the image output) and REGEX (to provide regular expression support) libraries. This conguration allows the developer/data provider to use shapeles as input and, depending on the version of GD library used, GIF or PNG images as output. Additional libraries are needed for input data in alternative formats. The libraries that work with MapServer are listed below.
4.2.5 The MapServer source code

The MapServer source code can be downloaded from the download page. If youd like to get the current development version of the software, following the nightly snapshot link under the Interim Builds title. The absolute latest copy of the source code can be obtained from SVN; however, the SVN respository does not contain several important source les (maplexer.c, mapparser.c and mapparser.h) normally generated on unix, so if possible, using a nightly snaphot is substantially easier than working directly from Subversion. Required Libraries GD Library: MapServer uses the GD graphics library for rendering map images in GIF, PNG and JPEG format. These map images are displayed in web browser clients using the MapServer CGI. The current ofcial version of GD is 2.0.33. The distributed makeles are setup to use the prebuilt GD Win32 DLL binaries which include 42 Chapter 4. Installation
GD, libjpeg, libpng, libz, libgif and FreeType 2 all within one DLL. This package is generally listed as Windows DLL .zip and the latest version is normally available at http://www.boutell.com/gd/http/gdwin32.zip. Regex: Regex is the regular expression library used by MapServer. It can be downloaded at http://ftp.gnu.org/oldgnu/regex/regex-0.12.tar.gz Optional Libraries JPEG library: This library is required by GD to render JPEG images, if building GD from source. You may download this library at http://www.ijg.org/les/jpegsrc.v6b.tar.gz PNG library: This library is required by GD to render PNG images, if building GD from source. You may download this library at http://sourceforge.net/projects/libpng/ Zlib: This library is required by libpng to provide graphics compression support. It can be downloaded along with the PNG library, or at http://www.gzip.org/zlib.zip . FreeType 2: FreeType provides TrueType support in MapServer via GD. We only need to build FreeType seperately if building GD from source. It can be downloaded at http://gnuwin32.sourceforge.net/packages/freetype.htm . PROJ.4: Proj.4 provides on-the-y projection support to MapServer. Users whose data are in different projection systems can use this library to reproject into a common projection. It is also required for WMS, WFS or WCS services. GDAL/OGR: The GDAL/OGR library allows MapServer to read a variety of geospatial raster formats (GDAL) and vector formats (OGR). It can be downloaded at http://www.gdal.org/. ArcSDE: ArcSDE is an ESRI proprietary spatial database engine. Most users will not have access to it but if you have ArcSDE license, you can use its libraries to give MapServer access to SDE databases. EPPL7: This library allows MapServer to read EPPL7 datasets, as well as the older Erdas LAN/GIS les. This library is set as a default library in MapServer so theres no special source code to download. Now that you have reviewed the libraries that provide support to MapServer, it is time to decide which ones to compile and use. We will work with the pre-built GD distributed on Boutell.com with PNG, GIF, JPEG, and FreeType built in. If you want to provide OGC Web Services (ie. WMS, WFS) or want to perform on the y reprojection then the PROJ.4 library will be needed. If you need additional raster and vector data sources consider including GDAL/OGR support. GDAL is also required for WCS service. Our example calls for the required libraries and on-the-y projection support so we need to download GD, regex, and Proj.4 libraries. Go ahead and get those libraries.
4.2.6 Set Compilation Options

MapServer, like many of its support libraries, comes with a Visual C++ makele called Makele.vc. It includes the le nmake.opt which contains many of the site specic denitions. We will only need to edit the nmake.opt le to congure the build for our local site options, and support libraries. The Makele.vc, and nmake.opt template le have been provided by Assefa Yewondwossen, and the DM Solutions folks. As of MapServer 4.4, the default MapServer build options only include GD, and regex. MapServer is built using the /MD option (which means MSVCRT.DLL should be used), so if any support libraries are being built statically (rather than as DLLs) we need to use /MD when building them as well. By default modern PROJ.4 builds use /MD so we should be able to use the default PROJ.4 build without tweaking. The example will compile with the GDWin32 pre-built DLL as well as regex-0.12, and PROJ.4. The PROJ.4 support will ensure we can enable MapServer OGC-WMS compatibility. Use notepad or another text editor to open the nmake.opt le and make the following changes.
43
Comments Use the pound sign ( # ) to comment out the lines that you want to disable, or remove the pound sign to enable an option for NMAKE. A. Enable PROJ.4 support, and update the path to the PROJ.4 directory. Uncomment the PROJ= line, and the PROJ_DIR= line as follows, and update the PROJ_DIR path to point to your PROJ build.
# Reprojecting. # If you would like mapserver to be able to reproject data from one # geographic projection to another, uncomment the following flag # Proj.4 distribution (cartographic projection routines). PROJ.4 is # also required for all OGC services (WMS, WFS, and WCS). # # For PROJ_DIR use full path to Proj.4 distribution PROJ=-DUSE_PROJ -DUSE_PROJ_API_H PROJ_DIR=c:\projects\proj-4.4.9
If you look down later in the le, you can see that once PROJ is enabled, MapServer will be linked with proj_i.lib, the PROJ.4 stub library, meaning that MapServer will be using the PROJ.DLL as opposed to statically linking in PROJ.4. 2. Uncomment the WMS option.
# Use this flag to compile with WMS Server support. # To find out more about the OpenGIS Web Map Server Specification go to # http://www.opengis.org/ WMS=-DUSE_WMS_SVR
3. Update to use GD. Heres what it should look like in our example.
GD_DIR=c:/projects/gdwin32 GD_LIB=$(GD_DIR)/bgd.lib
Note: As distributed the GDWin32 binary build does not include the bgd.lib stub library. It is necessary to run the makemsvcimport.bat script in the gdwin32 directory rst. D. Make sure the regex path is set correctly. In order for the delete command in the nmake /f makele.vc clean target to work properly it is necessary to use backslashes in the REGEX_DIR denition.
# # # # # # REGEX Libary VC++ does not include the REGEX library... so we must provide our one. The following definitions will try to build GNU regex-0.12 located in the regex-0.12 sub-directory. If it was not included in the source distribution, then you can get it from:
# ftp://ftp.gnu.org/pub/gnu/regex/regex-0.12.tar.gz # Provide the full path to the REGEX project directory # You do not need this library if you are compiling for PHP mapscript. # In that case the PHP regex library will be used instead !IFNDEF PHP REGEX_DIR=c:\projects\regex-0.12 !ENDIF
Your Makele is now set.
44
4.2.7 Compile the Libraries

Before compiling MapServer, you must rst compile its supporting libraries. How this is done varies for each library. For the PROJ.4 library a nmake /f makele.vc command in the proj-4.4.9src directory should be sufcient. The regex-0.12 code is actually built by the MapServer build process, so you dont need to do anything there. Compiling libcurl Previously, curl libraries can be compiled using the following command:
nmake /f makefile.vc6 CFG=release
This creates a static library, libcurl.lib, to which you compile against. Versions newer than version 7.10.x should be compiled as dynamic library. This is accomplished using the command:
nmake /f makefile.vc6 CFG=release-dll
You will then need to edit MapServers nmake.opt to replace the CURL_LIB variable with this line:
CURL_LIB = $(CURL_DIR)/lib/libcurl_imp.lib
4.2.8 Compile MapServer

Once you have compiled the supporting libraries successfully, you are ready to take the nal compilation step. If you have not already done so, open a command prompt and set the VC++ environment variables by running the vcvars32.bat usually located in C:Program FilesMicrosoft Visual StudioVC98binvcvars32.bat.
C:\Users> cd \projects\mapserver C:\Projects\mapserver&> C:\Program Files\Microsoft Visual Studio\VC98\Bin\vcvars32.bat" C:\Projects\mapserver> Setting environment for using Microsoft Visual C++ tool. C:\Projects\mapserver>
Now issue the command: nmake /f Makele.vc and wait for it to nish compiling. If it compiles successfully, you should get mapserver.lib, libmap.dll, mapserv.exe, and other .EXE les. Thats it for the compilation process. If you run into problems, read section 4 about compiling errors. You can also ask for help from the helpful folks in the MapServer-dev e-mail list.
4.2.9 Compiling MapServer with PostGIS support

To compile PostGIS support into MapServer, heres what you need to do: 1. download the PostgreSQL 8.0.1 (or later) source from: ftp://ftp.heanet.ie/pub/postgresql/source/ 2. I extracted them to C:projectspostgresql-8.0.1 3. download the Microsoft Platform SDK otherwise you get link errors on shfolder.lib. 4. compile libpq under C:projectspostgresql-8.0.1srcinterfaceslibpq using the win32.mak makele 5. copy everything from C:projectspostgresql-8.0.1srcinterfaceslibpqrelease 8.0.1srcinterfaceslibpq as the MapServer makele will try to nd it there to C:projectspostgresql-
6. Dene the following in the nmake.opt for MapServer: POSTGIS =-DUSE_POSTGIS POSTGIS_DIR =c:/projects/postgresql-8.0.1/src
45
7. nmake /f makele.vc 8. dont forget to copy libpq.dll (from C:projectspostgresql-8.0.1srcinterfaceslibpqrelease) into a location where MapServer can nd it.
4.2.10 Common Compiling Errors

Following are a few common errors you may encounter while trying to build MapServer. Visual C++ Tools Not Properly Initialized.
C:\projects\mapserver> nmake -f /makefile.vc nmake is not recognized as an internal or external command, operable program or batch file.
This occurs if you have not properly dened the path and other environment variables required to use MS VisualC++ from the command shell. Invoke the VCVARS32.BAT script, usually with the command C:Program FilesMicrosoft Visual StudioVC98binvcvars32.bat or something similar if visual studio was installed in an alternate location. To test if VC++ is available, just type nmake or cl in the command shell and ensure it is found. Regex Build Problems.
regex.obj : error LNK2001: unresolved external symbol _printchar libmap.dll : fatal error LNK1120: 1 unresolved externals NMAKE : fatal error U1077: link : return code 0x460 Stop.
This occurs if you use the stock regex-0.12 we referenced. I work around this by commenting out the extern statement for the printchar() function, and replacing it with a stub implementation in regex-0.12regex.c.
//extern void printchar (); void printchar( int i ) {}
GD Import Library Missing.

LINK : fatal error LNK1104: cannot open file c:/projects/gdwin32/bgd.lib NMAKE : fatal error U1077: link : return code 0x450 Stop.
If you are using the pre-built GD binaries, you still need to run the makemsvcimport.bat script in the gdwin32 directory to create a VC++ compatible stub library (bgd.lib).
4.2.11 Installation
The le we are most interested in is mapserv.exe. The other executable les are the MapServer utility programs. See Also: MapServer Utilities to learn more about these utilities. To test that the CGI program is working, type mapserv.exe at the command prompt. You should see the following message:
This script can only be used to decode form results and should be initiated as a CGI process via a httpd server.
46
You may instead get a popup indicating that a DLL (such as bgd.dll) is missing. You will need to copy all the required DLLs (ie. bgd.dll, and proj.dll) to the same directory as the mapserv.exe program. Now type mapserv -v at the command prompt to get this message:
MapServer version 4.4.0-beta3 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER INPUT=SHAPEFILE DEBUG=MSDEBUG
This tells us what data formats and other options are supported by mapserv.exe. Assuming you have your web server set up, copy mapserv.exe, libmap.dll, bgd.dll, proj.dll and any other required DLLs to the cgi-bin directory. You are now ready to download the demo application and try out your own MapServer CGI program. If you wish, you can also create a directory to store the utility programs. Id suggest making a subdirectory called bin under the directory projects and copy the executables to that subdirectory. You might nd these programs useful as you develop MapServer applications.
4.2.12 Other Helpful Information

The MapServer Unix Compilation and Installation HOWTO has good descriptions of some MapServer compilation options and library issues. I will write more about those options and issues on the next revision of this HOWTO. The README documents of each of the supporting libraries provide compilation instructions for Windows. The MapServer User community has a collective knowledge of the nuances of MapServer compilation. Seek their advice wisely.
4.2.13 Acknowledgements
Thanks to Assefa Yewondwossen for providing the Makele.vc. I would not have been able to write this HOWTO without that le. Thanks to Bart van den Eijnden for the libcurl and PostGIS compilation info. Thanks to the Steve Lime for developing MapServer and to the many developers who contribute time and effort in order to keep the MapServer project successful.
4.3 PHP MapScript Installation

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Revision $Revision: 12108 $ Date $Date: 2011-08-24 01:58:40 -0700 (Wed, 24 Aug 2011) $ Table of Contents PHP MapScript Installation Introduction Obtaining, Compiling, and Installing PHP and the PHP/MapScript Module FAQ / Common Problems
4.3. PHP MapScript Installation
47
4.3.1 Introduction
The PHP/MapScript module is a PHP dynamically loadable module that makes MapServers MapScript functions and classes available in a PHP environment. The original version of MapScript (in Perl) uses SWIG, but since SWIG does not support the PHP language, the module has to be maintained separately and may not always be in sync with the Perl version. The PHP module was developed by DM Solutions Group and is currently maintained by Mapgears. This document assumes that you are already familiar with certain aspects of your operating system: For Unix/Linux users, a familiarity with the build environment, notably make. For Windows users, some compilation skills if you dont have ready access to a pre-compiled installation and need to compile your own copy of MapServer with the PHP/MapScript module. Which version of PHP is supported? PHP MapScript was originally developed for PHP-3.0.14 but after MapServer 3.5 support for PHP3 has been dropped and as of the last update of this document, PHP 4.3.11 or more recent was required (PHP5 is well supported). The best combinations of MapScript and PHP versions are: MapScript 4.10 with PHP 5.2.1 and up MapScript 4.10 with PHP 4.4.6 and up How to Get More Information on the PHP/MapScript Module for MapServer For a list of all classes, properties, and methods available in the module see the php reference document. More information on the PHP/MapScript module can be found on the PHP/MapScript page on MapTools.org. The MapServer Wiki also has PHP/MapScript build and installation notes and some php code snippets. Questions regarding the module should be forwarded to the MapServer mailing list.
4.3.2 Obtaining, Compiling, and Installing PHP and the PHP/MapScript Module
Download PHP and PHP/MapScript The PHP source or the Win32 binaries can be obtained from the PHP web site. Once you have veried that PHP is installed and is running, you need to get the latest MapServer source and compile MapServer and the PHP module. Setting Up PHP on Your Server Unix Check if you have PHP already installed (several Linux distributions have it built in). If not, see the PHP manuals Installation on Unix systems section. Windows MS4W (MapServer For Windows) is a package that contains Apache, PHP, and PHP/MapScript ready to use in a simple ziple. Several Open Source applications are also available for use in MS4W. 48 Chapter 4. Installation
Windows users can follow steps in the Installing Apache, PHP and MySQL on Windows tutorial to install Apache and PHP manually on their system. Window users running PWS/IIS can follow php.nets howto for installing PHP for PWS/IIS 3, PWS 4 or newer, and IIS 4 or newer. Note: When setting up PHP on Windows, make sure that PHP is congured as a CGI and not as an Apache module because php_mapscript.dll is not thread-safe and does not work as an Apache module (See the Example Steps of a Full Windows Installation section of this document). Build/Install the PHP/MapScript Module Building on a Linux Box NOTE: For UNIX users, see the README.CONFIGURE le in the MapServer source, or see the Compiling on Unix HowTo. The main MapServer congure script will automatically setup the main makele to compile php_mapscript.so if you pass the with-php=DIR argument to the congure script. Copy the php_mapscript.so library to your PHP extensions directory, and then use the dl() function to load the module at the beginning of your PHP scripts. See also the PHP function extension_loaded() to check whether an extension is already loaded. The le mapscript/php3/examples/phpinfo_mapscript.phtml will test that the php_mapscript module is properly installed and can be loaded. If you get an error from PHP complaining that it cannot load the library, then make sure that you recompiled and reinstalled PHP with support for dynamic libraries. On RedHat 5.x and 6.x, this means adding -rdynamic to the CLDFLAGS in the main PHP3 Makele after running ./congure Also make sure all directories in the path to the location of php_mapscript.so are at least r-x for the HTTPd user (usually nobody), otherwise dl() may complain that it cannot nd the le even if its there. Building on Windows For Windows users, it is recommended to look for a precompiled binary for your PHP version on the MapServer download page or on MapTools.org. If for some reason you really need to compile your own Windows binary then see the README.WIN32 le in the MapServer source (good luck!). Installing PHP/MapScript Simply copy the le php4_mapscript.dll to your PHP4 extensions directory (pathto/php/extensions) Using phpinfo() To verify that PHP and PHP/MapScript were installed properly, create a .php le containing the following code and try to access it through your web server:
<HTML> <BODY> <?php if (PHP_OS == "WINNT" || PHP_OS == "WIN32") { dl("php_mapscript.dll"); } else {
49
dl("php_mapscript.so"); } phpinfo(); ?> </BODY> </HTML>
If PHP and PHP/MapScript were installed properly, several tables should be displayed on your page, and MapScript should be listed in the Extensions table. Example Steps of a Full Windows Installation Using MS4W (MapServer for Windows) 1. Download the latest MS4W base package. 2. Extract the les in the archive to the root of one of your drives (e.g. C:/ or D:/). 3. Double-click the le /ms4w/apache-install.bat to install and start the Apache Web server. 4. In a web browser goto http://127.0.0.1. You should see an MS4W opening page. You are now running PHP, PHP/MapScript, and Apache. 5. You can now optionally install other applications that are pre-congured for MS4W, which are located on the MS4W download page. Manual Installation Using Apache Server 1. Download the Apache Web Server and extract it to the root of a directory (eg. D:/Apache). 2. Download PHP4 and extract it to your Apache folder (eg. D:/Apache/PHP4). 3. Create a temp directory to store MapServer created GIFs. NOTE: This directory is specied in the IMAGEPATH parameter of the WEB Object in the Maple reference. For this example we will call the temp directory ms_tmp (eg. E:/tmp/ms_tmp). 4. Locate the le httpd.conf in the conf directory of Apache, and open it in a text viewer (eg. TextPad, Emacs, Notepad). In the Alias section of this le, add aliases to the ms_tmp folder and any other folder you require (for this example we will use the msapps folder):
Alias Alias /ms_tmp/ /msapps/ "path/to/ms_tmp/" "path/to/msapps/"
In the ScriptAlias section of this le, add an alias for the PHP4 folder.
ScriptAlias /cgi-php4/ "pathto/apache/php4/"
In the AddType section of this le, add a type for php4 les.
AddType application/x-httpd-php4 .php
In the Action section of this le, add an action for the php.exe le.
Action application/x-httpd-php4 "/cgi-php4/php.exe"
5. Copy the le php4.ini-dist located in your Apache/php4 directory and paste it into your WindowsNT folder (eg. c:/winnt), and then rename this le to php.ini in your WindowsNT folder.
50
6. If you want specic extensions loaded by default, open the php.ini le in a text viewer and uncomment the appropriate extension. 7. Place the le php_mapscript.dll into your Apache/php4/extensions folder. Installation Using Microsofts IIS (please see the IIS Setup for MapServer document for uptodate steps) 1. Install IIS if required (see the IIS 4.0 installation procedure). 2. Install PHP and PHP/MapScript (see above). 3. Open the Internet Service Manager (eg. C/WINNT/system32/inetsrv/inetmgr.exe). 4. Select the Default web site and create a virtual directory (right click, select New/Virtual directory). For this example we will call the directory msapps. 5. In the Alias eld enter msapps and click Next. 6. Enter the path to the root of your application (eg. c:/msapps) and click Next. 7. Set the directory permissions and click Finish. 8. Select the msapps virtual directory previously created and open the directory property sheets (by right clicking and selecting properties) and then click on the Virtual directory tab. 9. Click on the Conguration button and then click the App Mapping tab. 10. Click Add and in the Executable box type: path/to/php4/php.exe %s %s. You MUST have the %s %s on the end, PHP will not function properly if you fail to do this. In the Extension box, type the le name extension to be associated with your PHP scripts. Usual extensions needed to be associated are phtml and php. You must repeat this step for each extension. 11. Create a temp directory in Explorer to store MapServer created GIFs. Note: This directory is specied in the IMAGEPATH parameter of the WEB Object in the Maple. For this example we will call the temp directory ms_tmp (eg. C:/tmp/ms_tmp). 12. Open the Internet Service Manager again. 13. Select the Default web site and create a virtual directory called ms_tmp (right click, select New/Virtual directory). Set the path to the ms_tmp directory (eg. C:/tmp/ms_tmp) . The directory permissions should at least be set to Read/Write Access.
4.3.3 FAQ / Common Problems

Questions Regarding Documentation Q Is there any documentation available? A The main reference document is the PHP MapScript reference, which describes all of the current classes, properties and methods associated with the PHP/MapScript module. To get a more complete description of each class and the meaning of their member variables, see the MapScript reference and the MapFile reference. The MapServer Wiki also has PHP/MapScript build and installation notes and some php code snippets.
Q Where can I nd sample scripts?
51
A Some examples are included in directory mapserver/mapscript/php3/examples/ in the MapServer source distribution. A good one to get started is test_draw_map.phtml: its a very simple script that just draws a map, legend and scalebar in an HTML page. A good intermediate example is the PHP MapScript By Example guide (note that this document was created for an earlier MapServer version but the code might be still useful). The next example is the GMap demo. You can download the whole source and data les from the MapTools.org download page. Questions About Installation Q How can I tell that the module is properly installed on my server? A Create a le called phpinfo.phtml with the following contents:
<?php ?> dl("php_mapscript.so"); phpinfo();
Make sure you replace the php_mapscript.so with the name under which you installed it, it could be php_mapscript_46.so on Unix, or php_mapscript_46.dll on Windows You can then try the second test page mapserver/mapscript/php3/examples/test_draw_map.phtml. This page simply opens a MapServer .map le and inserts its map, legend, and scalebar in an HTML page. Modify the page to access one of your own MapServer .map les, and if you get the expected result, then everything is probably working ne.
Q I try to display my .phtml or .php page in my browser but the page is shown as it would it Notepad. A The problem is that your PHP installation does not recognize .phtml as a PHP le extension. Assuming youre using PHP4 under Apache then you need to add the following line with the other PHP-related AddType lines in the httpd.conf:
AddType application/x-httpd-php .phtml
For a more detailed explanation, see the Example Steps of a Full Windows Installation section of this document.
Q I installed the PROJ.4, GDAL, or one of the support libraries on my system, it is recognized by MapServers congure as a system lib but at runtime I get an error: libproj.so.0: No such le or directory. A You are probably running a RedHat Linux system if this happened to you. This happens because the libraries install themselves under /usr/local/lib but this directory is not part of the runtime library path by default on your system. (Im still surprised that congure picked proj.4 as a system lib since its not in the systems lib path...probably something magic in autoconf that well have to look into) There are a couple of possible solutions: 1. Add a setenv LD_LIBRARY_PATH to your httpd.conf to contain that directory 2. Edit /etc/ld.so.conf to add /usr/local/lib, and then run /sbin/ldcong. This will permanently add /usr/local/lib to your systems runtime lib path.
52
3. Congure MapServer with the following options:

--with-proj=/usr/local --enable-runpath
and the /usr/local/lib directory will be hardcoded in the exe and .so les I (Daniel Morissette) personally prefer option #2 because it is permanent and applies to everything running on your system.
Q Does PHP/MapScript have to be setup as a CGI? If so, why? A Yes, please see the PHP/MapScript CGI page in the MapServer Wiki for details.
Q I have compiled PHP as a CGI and when PHP tries to load the php_mapscript.so, I get an undened symbol: _register_list_destructors error. Whats wrong? A Your PHP CGI executable is probably not linked to support loading shared libraries. The MapServer congure script must have given you a message about a ag to add to the PHP Makele to enable shared libs. Edit the main PHP Makele and add -rdynamic to the LDFLAGS at the top of the Makele, then relink your PHP executable. Note: The actual parameter to add to LDFLAGS may vary depending on the system youre running on. On Linux it is -rdynamic, and on *BSD it is -export-dynamic.
Q What are the best combinations of MapScript and PHP versions? A The best combinations are: MapScript 4.10 with PHP 5.2.1 and up MapScript 4.10 with PHP 4.4.6 and up
Q I am dynamically loading gd.so and php_mapscript.so and running into problems, why? A The source of the problems could be a mismatch of GD versions. The PHP GD module compiles its own version of libgd, and if the GD library is loaded before the mapscript library, mapscript will use the php-specic version. Wherever possible you should use a gd.so built with the same GD as PHPMapScript. A workaround is to load the php_mapscript module before the GD module.
4.4 .NET MapScript Compilation

Author Tamas Szekeres Contact szekerest at gmail.com Revision $Revision: 12501 $ Date $Date: 2011-08-28 02:51:27 -0700 (Sun, 28 Aug 2011) $
4.4. .NET MapScript Compilation
53
4.4.1 Compilation
Before compiling C# MapScript you should compile MapServer with the options for your requirements. For more information about the compilation of MapServer please see Win32 Compilation and Installation Guide. It is highly recommended to minimize the library dependency of your application, so when compiling MapServer enable only the features really needed. To compile the C# binding SWIG 1.3.31 or later is required. Warning: This document may refer to older library versions. You may want to try to use more recent library versions for your build.
Win32 compilation targeting the MS.NET framework 1.1 You should compile MapServer, MapScript and all of the subsequent libraries using Visual Studio 2003. Download and uncompress the latest SWIGWIN package that contains the precompiled swig.exe Open the Visual Studio .NET 2003 Command Prompt and step into the /mapscript/csharp directory. Edit makele.vc and set the SWIG variable to the location of your swig.exe Use
nmake -f makefile.vc
to compile mapscript.dll and mapscript_csharp.dll. Win32 compilation targeting the MS.NET framework 2.0 You should compile MapServer, MapScript and all of the subsequent libraries using Visual Studio 2005. Download and uncompress the latest SWIGWIN package that contains the precompiled swig.exe Open the Visual Studio 2005 Command Prompt and step into the /mapscript/csharp directory Edit makele.vc and set the SWIG variable to the location of your swig.exe. Use
to compile mapscript.dll and mapscript_csharp.dll. Win32 compilation targeting the MONO framework Before the compilation you should download and install the recent mono Win32 setup package (eg. mono-1.1.13.2gtksharp-2.8.1-win32-1.exe) Edit makele.vc and set the CSC variable to the location of your mcs.exe. Alternatively you can dene
MONO = YES
in your nmake.opt le. You should use the same compiler for compiling MapScript as the compiler has been used for the MapServer compilation. To compile MapScript open the Command Prompt supplied with your compiler and use
to compile mapscript.dll and mapscript_csharp.dll.
54
Alternative compilation methods on Windows Beginning from MapServer 4.8.3 you can invoke the C# compilation from the MapServer directory by uncommenting DOT_NET in nmake.opt
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # .NET/C# MapScript # ---------------------------------------------------------------------# .NET will of course only work with MSVC 7.0 and 7.1. Also note that # you will definitely want USE_THREAD defined. #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #DOT_NET = YES
and invoking the compilation by

nmake -f makefile.vc csharp
You can also use

nmake -f makefile.vc install
for making the compilation an copying the targets into a common output directory. Testing the compilation For testing the compilation and the runtime environment you can use
nmake -f makefile.vc test
within the csharp directory for starting the sample applications compiled previously. Before making the test the location of the corresponding libraries should be included in the system PATH. Linux compilation targeting the MONO framework Before the compilation you should download and install the recent mono Linux package. Some distributions have precompiled binaries to install, but for using the latest version you might want to compile and install it from the source. Download and uncompress the latest SWIG release. You should probably compile it from the source if pre-compiled binaries are not available for your platform. Before compiling MapScript, MapServer should be congured and compiled. Beginning from MapServer 4.8.2 during conguration the mapscript/csharp/Makele will be created according to the conguration options. Edit this le and set the SWIG and CSC for the corresponding executable pathes if the les could not be accessed by default. To compile at a console step into the /mapscript/csharp directory use.
make
to compile libmapscript.so and mapscript_csharp.dll. For testing the compilation and the runtime environment you can use
make test
for starting the sample applications compiled previously. OSX compilation targeting the MONO framework Beginning from 4.10.0 the csharp/Makele supports the OSX builds. Before making the build the recent MONO package should be installed on the system. 4.4. .NET MapScript Compilation 55
Before compiling MapScript, MapServer should be congured and compiled. Beginning from MapServer 4.8.2 during conguration the mapscript/csharp/Makele will be created according to the conguration options. Edit this le and set the SWIG and CSC for the corresponding executable pathes if the les could not be accessed by default. To compile at a console step into the /mapscript/csharp directory use
make
to compile libmapscript.dylib and mapscript_csharp.dll. For testing the compilation and the runtime environment you can use
make test
for starting the sample applications compiled previously. To run the applications mapscript_csharp.dll.cong is needed along with the mapscript_csharp.dll le. This le is created during the make process
4.4.2 Installation
The les required for your application should be manually installed. It is highly recommended to copy the les into the same folder as the executable resides.
4.4.3 Known issues

Visual Studio 2005 requires a manifest le to load the CRT native assembly wrapper If you have compiled MapServer for using the CRT libraries and you are using the MS.NET framework 2.0 as the execution runtime you should supply a proper manifest le along with your executable, like:
<?xml version="1.0" encoding="utf-8"?> <assembly xsi:schemaLocation="urn:schemas-microsoft-com:asm.v1 assembly.adaptive.xsd" manifestVersion <assemblyIdentity name="drawmap.exe" version="1.0.0.0" type="win32" /> <dependency> <dependentAssembly asmv2:dependencyType="install" asmv2:codebase="Microsoft.VC80.CRT.manifest" asmv2: <assemblyIdentity name="Microsoft.VC80.CRT" version="8.0.50608.0" publicKeyToken="1fc8b3b9a1e18e3b" p <hash xmlns="urn:schemas-microsoft-com:asm.v2"> <dsig:Transforms> <dsig:Transform Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" /> </dsig:Transforms> <dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" /> <dsig:DigestValue>UMOlhUBGeKRrrg9DaaPNgyhRjyM=</dsig:DigestValue> </hash> </dependentAssembly> </dependency> </assembly>
This will inform the CLR that your exe depends on the CRT and the proper assembly wrapper is to be used. If you are using the IDE the manifest le could be pregenerated by adding a reference to Microsoft.VC80.CRT.manifest within the /Microsoft Visual Studio 8/VC/redist/x86/Microsoft.VC80.CRT directory. Manifests for the dll-s must be embedded as a resource According to the windows makele the MapScript compilation target (mapscript.dll) is linked with the /MD option. In this case the VS2005 linker will generate a manifest le containing the unmanaged assembly dependency. The sample contents of the manifest le are: 56 Chapter 4. Installation
<?xml version=1.0 encoding=UTF-8 standalone=yes?> <assembly xmlns=urn:schemas-microsoft-com:asm.v1 manifestVersion=1.0> <dependency> <dependentAssembly> <assemblyIdentity type=win32 name=Microsoft.VC80.CRT version=8.0.50608.0 processorArchitecture= </dependentAssembly> </dependency> </assembly>
Like previously mentioned if you are creating a windows application the common language runtime will search for a manifest le for the application. The name of the manifest le should be the same as the executable append and end with the .manifest extension. However if the host process is not controlled by you (like web mapping applications using aspnet_wp.exe as the host process) you will not be certain if the host process (.exe) will have a manifest containing a reference to the CRT wrapper. In this case you may have to embed the manifest into the dll as a resource using the mt tool like:
mt /manifest mapscript.dll.manifest /outputresource:mapscript.dll;#2
the common language runtime will search for the embedded resource and load the CRT assembly properly. Normally it is enough to load the CRT with the root dll (mapscript.dll), but it is not harmful embedding the manifest into the dependent libraries as well. Issue with regex and Visual Studio 2005 When compiling with Microsoft Visual Studio 2005 variable name collision may occur between regex.c and crtdefs.h. For more details see: http://trac.osgeo.org/mapserver/ticket/1651 C# MapScript library name mapping with MONO Using the MapScript interface created by the SWIG interface generator the communication between the C# wrapper classes (mapscript_csharp.dll) and the C code (mapscript.dll) takes place using platform invoke like:
[DllImport("mapscript", EntryPoint="CSharp_new_mapObj")] public static extern IntPtr new_mapObj(string jarg1);
The DllImport declaration contains the library name, however to transform the library name into a le name is platform dependent. On Windows the library name is simply appended with the .dll extension (mapscript.dll). On the Unix systems the library le name normally starts with the lib prex and appended with the .so extension (libmapscript.so). Mapping of the library name may be manually controlled using a dll.cong le. This simply maps the library le the DllImport is looking for to its unix equivalent. The le normally contains the following information (mapscript_csharp.dll.cong):
<configuration> <dllmap dll="mapscript" target="libmapscript.so" /> </configuration>
and with the OSX builds:

<configuration> <dllmap dll="mapscript" target="libmapscript.dylib" /> </configuration>
4.4. .NET MapScript Compilation
57
The le should be placed along with the corresponding mapscript_csharp.dll le, and created by default during the make process. For more information see: http://trac.osgeo.org/mapserver/ticket/1596 http://www.mono-project.com/Interop_with_Native_Libraries Localization issues with MONO/Linux According to http://trac.osgeo.org/mapserver/ticket/1762 MapServer may not operate equally well on different locale settings. Especially when the decimal separator is other than . inside the locale of the process may cause parse errors when the maple contains oat numbers. Since the MONO process takes over the locale settings of the environment it is worth considering to set the default locale to C of the host process, like:
LC_ALL=C mono ./drawmap.exe ../../tests/test.map test_csharp.png
4.4.4 Most frequent errors

This chapter will summarize the most frequent problems the user can run into. The issues were collected mainly from the -users list and the IRC. Unable to load dll (MapScript) You can get this problem on Windows and in most cases it can be dedicated to a missing or an unloadable shared library. The error message talks about mapscript.dll but surely one or more of the dll-s are missing that libmap.dll depends on. So rstly you might want to check for the dependencies of your libmap.dll in your application directory. You can use the Visual Studio Dependency Walker to accomplish this task. You can also use a le monitoring tool (like SysInternals lemon) to detect the dll-s that could not be loaded. I propose to store all of the dll-s required by your application in the application folder. If you can run the drawmap C# sample application with your maple your compilation might be correct and all of the dlls are available. You may nd that the MapScript C# interface behaves differently for the desktop and the ASP.NET applications. Although you can run the drawmap sample correctly you may encounter the dll loading problem with the ASP.NET applications. When creating an ASP.NET project your application folder will be Inetpubwwwroot[YourApp]bin by default. The host process of the application will aspnet_wp.exe or w3wp.exe depending on your system. The application will run under a different security context than the interactive user (under the context of the ASPNET user by default). When placing the dll-s outside of your application directory you should consider that the PATH environment variable may differ between the interactive and the ASPNET user and/or you may not have enough permission to access a dll outside of your application folder.
4.4.5 Bug reports

If you nd a problem dedicated to the MapScript C# interface feel free to le a bug report to the Issue Tracker.
4.5 IIS Setup for MapServer

Author Debbie Paqurek Last Updated 2005/12/12
58
Table of Contents IIS Setup for MapServer Base conguration Php.ini le Internet Services Manager Under the tree for your new website - add virtual directories for Test PHP Maples for IIS Conguration les: Some help on how to set up MapServer/Chameleon/PhpPgAdmin on Microsoft IIS (v5.0). Contains note on changes to the php.ini le and necessary changes to the MapServer maples. Please contribute or make changes as required.
4.5.1 Base conguration

Windows 2000 IIS 5.0 MS4W 1.2.1 Chameleon 2.2 PHP 4.3.11 MapServer 4.7 PhpPgAdmin 3.5.4 (if using postgresql/postgis) Postgres 8.0.3 (if using postgresql/postgis) Postgis 1.0.3 (if using postgresql/postgis) This setup assumes that MS4W was unzipped to form c:\ms4w\ directory.<br>
4.5.2 Php.ini le
session.save_path (absolute path to your tmp directory) extension_dir (relative path to your php/extensions directory) cgi.force_redirect = 0</li> enable the pg_sql extension (php_pgsql.dll) (for Postgresql)
4.5.3 Internet Services Manager

Under your website tree, create a new website (e.g. msprojects). View the properties for the new website. Web Site Tab set the IP address and under the Advanced tab put the complete Host Header name (e.g.msprojects.gc.ca). Home Directory Tab content should come from: A directory located on this computer. Local Path: c:\ms4w\Apache\htdocs 4.5. IIS Setup for MapServer 59
Read access + whatever else you need Execute Permissions: Scripts only Conguration button - App Mappings (Add extensions .php and .phtml, Executable is c:\ms4w\Apache\cgi-bin\php.exe,select All verbs, Script Engine, and check that le exists<br> Documents Tab Add index.phtml and index.html Directory Security Tab Anonymous access amd authentication control Select Anonymous access and the edit button should indicate the IUSR_account Server Extensions Tab Enable authoring is selected and client scripting says Javascript
4.5.4 Under the tree for your new website - add virtual directories for
cgi-bin Under Properties, virtual directory tab Local Path should point to c:\ms4w\apache\cgi-bin. Select Read. Execute Permissions should say scripts and executables ms_tmp Under Properties, virtual directory tab Local Path should point to c:\ms4w\tmp\ms_tmp. Select Read, Write. Execute Permissions should say scripts only. This is where temporary images are written to so in the File system Security tab (use windows explorer), the c:\ms4w\tmp\ms_tmp directory should have permissions set for the Internet Guest Account (Read and execute, Read, Write, List Folder Contents). tmp Under Properties, virtual directory tab Local Path should point to c:\ms4w\tmp. Select Read, Write. Execute Permissions should say scripts only. This is where chameleon writes sessions to so in the File system Security tab (use windows explorer), the c:\ms4w\tmp directory should have permissions set for the Internet Guest Accounnt (Read and execute, Read, Write, List Folder Contents). chameleon Under Properties, virtual directory tab Local Path should point to C:\ms4w\apps\chameleon\htdocs. Select Read. Execute Permissions should say scripts only. Under the Chameleon tree, you can add virtual directories for admin (c:\ms4w\apps\chameleon\admin\htdocs), samples (c:\ms4w\apps\chameleon\samples\htdocs), cwc2 (c:\ms4w\apps\chameleon\cwc2\htdocs) phppgadmin If using postgresql/postgis, under Properties, virtual directory tab Local Path should point to C:\ms4w\Apache\htdocs\phpPgAdmin. Select Read, Write. Execute Permissions should say scripts and executables. Under Documents - add index.php. Note: We had to unzip the phppgadmin package into this directory in order to get phppgadmin to show us the login page at http://yourserver/phppgadmin/index.php. You might want additional security on this directory. gmap Good for testing purposes. Remember to change your maples as discussed in Maples for IIS below. Under Properties, virtual directory tab Local Path should point to C:\ms4w\apps\gmap\htdocs. Select Read. Execute Permissions should say scripts only.
4.5.5 Test PHP

In a command line window, navigate to c:\ms4w\apache\cgi-bin and run php -i. This should return the output that the phpinfo() function returns. I got an error about how it couldnt nd ntwdblib.dll. I found this in c:\ms4w\apache\php\dlls and I copied it to the cgi-bin directory.
60
4.5.6 Maples for IIS

Add a cong line to the MAP level of the maple
CONFIG PROJ_LIB "c:\ms4w\proj\nad\"
change the IMAGEPATH to be an absolute path to your tmp/ms_tmp folder

IMAGEPATH "c:\ms4w\tmp\ms_tmp"
4.5.7 Conguration les:

For Chameleon
C:\ms4w\apps\chameleon\config\chameleon.xml C:\ms4w\apps\chameleon\config\cwc2.xml
For phppgadmin: (if using postgresql/postgis)

C:\ms4w\apps\phpPgAdmin\conf\config.inc.php
4.6 Oracle Installation

Author Till Adams Last Updated 2007/02/16 Table of Contents Oracle Installation Preface System Assumptions Compile MapServer Set Environment Variables
4.6.1 Preface
This document explains the whole conguration needed to get the connect between MapServer CGI and an Oracle database server on a linux (Ubuntu) box. The aim of this document is just to put a lot of googled knowledge in ONE place. Hopefully it will preserve many of people spending analog amount of time than I did! This manual was written, because I spent several days googling around to get my UMN having access to an oracle database. Im NOT an oracle expert, so the aim of this document is just to put a lot of googled knowledge in ONE place. Hopefully it will preserve many of people spending analog amount of time than I did! (Or: If you have the choice: Try PostGIS ;-)) Before we start, some basic knowledge, I didnt know before: MapServer can access oracle spatial as well as geodata from any oracle locator installation! Oracle locator comes with every oracle instance, there is no need for an extra license. There is no need for further installation of any packages beside oracle/oracle OCI
4.6. Oracle Installation
61
4.6.2 System Assumptions

We assume that Oracle is already installed, there is a database and there is some geodata in the database. The following paths should be known by the reader: ORACLE_HOME ORACLE_SID ORACLE_BASE LD_LIBRARY_PATH We also assume that you have installed apache2 (our version was 2.0.49) and you are used to work with Linux/UNIX systems. We also think you are able to handle the editor vi/vim. We ensure that the Oracle user who later accesses the database has write-access to the oracle_home directory. We also assume, that you already have setup the tnsnames.ora le. It should look like that:
MY_ORACLE = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = host)(PORT = 1521)) (CONNECT_DATA = (SERVICE_NAME = your_name) ) )
It is important that you know the NAME of the datasource, in this example this is MY_ORACLE and will be used further on. Done that, youre ne using User/Password@MY_ORACLE in your maple to connect to the oracle database. But rst we have to do some more stuff.
4.6.3 Compile MapServer

Compile as normal compilation and set this ag:
--with-oraclespatial=/path/to/oracle/home/</p>
If MapServer congure and make runs well, try

./mapserv -v
This should at least give this output:

INPUT=ORACLESPATIAL
If you got that, youre ne from the MapServer point of view.
4.6.4 Set Environment Variables

It is important to set all environment variables correctly. There are one the one hand system-wide environment variables to be set, on the other hand there should be set some for the cgi-directory in your Apache conguration. System Variables On Ubuntu (and on many other systems) there is the le /etc/prole which sets environment variables for all users on the system (you may also dedicate user-specic environment variables by editing the users .prole le in their home directory, but usually the oracle database users are not users of the system with their own home)
62
Set the following variables:

$ cd /etc
$ echo export ORACLE_HOME=/path/to/oracle/home >> /etc/profile # **(e.g. ORACLE_HOME=/app/oracle/ora10g) $ echo export ORACLE_BASE=path/to/oracle >> /etc/profile # **(e.g. ORACLE_HOME=/app/oracle) $ echo export ORACLE_SID=MY_ORACLE >> /etc/profile $ echo export LD_LIBRARY_PATH=path/to/oracle/home/lib >> /etc/profile # **(e.g. ORACLE_HOME=/app/oracle/ora10g/lib)
The command comes silent, so there is no system output if you didnt mistype anything! Setting the Apache Environment Sometimes it is confusing WHERE to set WHAT in the splitted apache2.conf-les. In the folder /etc/apache2/sites_available you nd your sites-le. If you did not do sth. Special e.g. installing virtual hosts, the le is named default. In this le, the apache cgi-directory is dened. Our le looks like this:
ScriptAlias /cgi-bin/ /var/www/cgi-bin/ <Directory "/var/www/cgi-bin"> AllowOverride None Options ExecCGI -MultiViews +SymLinksIfOwnerMatch Order allow,deny Allow from all </Directory></p>
In this le, the local apache environment variables must be set. We did it within a location-block like this:
<Location "/cgi-bin/"> SetEnv ORACLE_HOME "/path/to/oracle/home" </Location></p>
Where /cgi-bin/ in the opening location block refers to the script alias /cgi-bin/ and the TNS_ADMIN directory point to the location of the tnsnames.ora le. Then restart apache:
$ /etc/init.d/apache2 force-reload
Create maple Before we start creating our maple ensure that you have a your access data (User/Password) and that you know the Oracle SRID, which could be different from the proj-EPSG! The data access parameters: CONNECTIONTYPE oraclespatial CONNECTION user/password@MY_ORACLE
4.6. Oracle Installation
63
DATA GEOM FROM MY_LAYER USING SRID 82032 [...] Where: GEOM is the name of the geometry column MY_LAYER the name of the table 82032 is equivalent to the EPSG code 31468 (German projection system) Testing & Error handling So you are ne now. Load the maple in your application and try it. If everything goes well: Great, if not, possibly this ugly error-emssage occurs (this one cmae by querying MapServer through the WMS interface as a GetMap-request):
<ServiceExceptionReport version="1.0.1"> <ServiceException> msDrawMap(): Image handling error. Failed to draw layer named test1. msOracleSpatialLayerOpen(): OracleSpatial error. Cannot create OCI Handlers. Connection failure. Check the connection string. Error: . </ServiceException> </ServiceExceptionReport>
This points us towards, that there might be a problem with the connection to the database. First of all, lets check, if the maple is all right. Therefore we use the MapServer utility program shp2img. Lets assume you are in the directory, where you compiled MapServer and run shp2img:
$ cd /var/src/mapserver_version/ $ shp2img -m /path/to/mapfile/mapfile.map -i png -o /path/to/output/output.png
The output of the command should look like this:

[Fri Feb [Fri Feb [Fri Feb 2 14:32:17 2007].522395 msDrawMap(): Layer 0 (test1), 0.074s 2 14:32:17 2007].522578 msDrawMap(): Drawing Label Cache, 0.000s 2 14:32:17 2007].522635 msDrawMap() total time: 0.075s
If not, this possibly points you towards any error in your maple or in the way to access the data directly. In this case, take a look at Oracle Spatial. If there is a problem with your oracle connect, the same message as above (MsDrawMap() ...) occurs. Check your maple syntax and/or the environment settings for Oracle. For Debian/Ubuntu its worth also checking the le /etc/environment and test-wise to add the system variables comparable to System Variables If the output is OK, you may have a look at the generated image (output.png). Then your problem reduces to the access of apache to oracle home directory. Carefully check your apache conguration. Please note, that the apache.cong le differs in several linux-distributions. For this paper we talk about Ubuntu, which should be the same as Debian.
64
CHAPTER 5
Maple
Author Steve Lime Contact steve.lime at dnr.state.mn.us Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Author Jean-Franois Doyon Contact jdoyon at ccrs.nrcan.gc.ca The Maple is the heart of MapServer. It denes the relationships between objects, points MapServer to where data are located and denes how things are to be drawn. The Maple consists of a MAP object, which has to start with the word MAP. There are some important concepts that you must understand before you can reliably use maples to congure MapServer. First is the concept of a LAYER. A layer is the combination of data plus styling. Data, in the form of attributes plus geometry, are given styling using CLASS and STYLE directives. See Also: An Introduction to MapServer for An Introduction to the Maple
5.1 Cartographical Symbol Construction with MapServer

Author Peter Freimuth Contact pf at mapmedia.de Author Arnulf Christl Contact arnulf.christl at wheregroup.com Author Hvard Tveite Contact havard.tveite at umb.no Revision $Revision: 12735 $ Date $Date: 2011-11-01 09:19:58 -0700 (Tue, 01 Nov 2011) $
65
Table of Contents Cartographical Symbol Construction with MapServer Abstract Introduction * Multiple Rendering and Overlay * Symbol Scaling * Mapserver and symbol specication Using Cartographical Symbols in MapServer * Output formats * Symbol units * Scaling of Symbols Construction of Point Symbols * Symbols of TYPE vector and ellipse * Symbols of TYPE truetype * Symbols of TYPE pixmap * Symbol denitions for the gure that demonstrates point symbols * Combining symbols Construction of Line Symbols * Overlaying lines * Use of the PATTERN and GAP parameters * Use of the OFFSET parameter * Asymmetrical line styling with point symbols Area Symbols * Hatch ll * Polygon lls with symbols of TYPE pixmap * Polygon lls with symbols of TYPE vector * Polygon outlines Examples (Mapserver 4) * Basic Symbols * Complex Symbols Tricks * Changing the center of a point symbol Maple changes related to symbols Current Problems / Open Issues * GAP - PATTERN incompatibility The End
5.1.1 Abstract
This Document refers to the syntax of map and symbol les for MapServer 6. The rst version of the document was based on the results of a project carried out at the University of Hannover, Institute of Landscape and Nature Conservation. It was initiated by Mr. Dipl. Ing. Roland Hachmann. Parts have been taken from a study carried through by Karsten Hoffmann, student of Geography and Cartography at the FU Berlin. In the context of a hands-on training in the company GraS GmbH Mr. Hoffman mainly dealed with the development of symbols. (Download study report in German) His degree dissertation will also concern this subject. The document has been heavily revised for Mapserver 6.
66
Chapter 5. Maple
5.1.2 Introduction
A map is an abstract representation that makes use of point, line and area symbols. Bertin (1974) created a clear and logical symbol scheme in which symbols can be varied referring to graphical variables. The following graphical variables can be used within MapServer: FORM, SIZE, PATTERN, COLOR and LIGHTNESS. Point and area symbols as well as text fonts (ttf) can additionally be displayed with a frame which we call OUTLINE. The following gure shows the theoretical structure of cartographical symbols, which is also used in MapServer:
Figure 5.1: Structure of Cartographical Symbols
Multiple Rendering and Overlay Say you want to display a highway with a black border line, two yellow lanes and a red center lane. This calls for a combination of signatures. Complex cartographical effects can be achieved by rendering the same vector data with different symbols, sizes and colours on top of each other. This can be done using separate LAYERs. This could, however, have performance effects for the application, as every rendering process of the same geometry will take up additional processor time. The preferred solution is to use multiple STYLEs to create complex symbols by overlay. To create the highway symbol mentioned above with a total width of 9 units, the lowest STYLE (in drawing order) will be a broad black line with a width of 9 units. The second level STYLE will be a yellow line with a width of 7 units, and the topmost STYLE will be a red line with a width of 1 unit. That way each yellow coloured lane will have a width of (7-1)/2 = 3 units.
5.1. Cartographical Symbol Construction with MapServer
67
Combining symbols can be a solution for many kinds of cartographical questions. A combination of different geometry types is also possible. A polygon data set can be rendered as lines to frame the polygons with a line signature. It can also be rendred as polygons with a symbol lling the polygon. When the polygon ll is rendered on top of the lines, the inner part of the underlying outline is covered by the ll symbol of the polygon. What is observed here is a clipping effect tha in will result in an asymmetric symbol for the boundary line. To present the outline without clipping, just reorder the LAYERs or STYLEs and put the outline presentation on top of the ll. Yet another way to construct advanced line signatures for framed polygons is to tamper with the original geometries by buffering or clipping the original geometry such that the new objects lie inside the original polygons or grow over the borders. PostGIS can help achieve a lot of effects. The OPACITY parameter of LAYER and STYLE can be used to achieve transparency (making lower symbols shine through upper symbols). Symbol Scaling There are two basically different ways of handling the display size of symbols and cartographical elements in a map at different scales. The size of cartographical elements is either set in screen pixels or in real world units. If the size is set in real world units (for example meters), the symbol will shrink and grow according to the scale at which the map is displayed. If the size is set in screen pixels, symbols look the same at all scales. The default behaviour of MapServer is to implement the screen pixels size type for displaying cartographical elements. Real world units, as described above, can be achieved using either the SIZEUNITS or the SYMBOLSCALEDENOM parameter of the LAYER. When SIZEUNITS is set (and is not pixels), symbol sizes are specied in real world units (for instance meters). For available units, see the SIZEUNIT documentation. When SYMBOLSCALEDENOM is set, the given symbols size is used for the map scale 1:SYMBOLSCALEDENOM, for other scales, the symbols are scaled proportionally. STYLE MAXSIZE and MINSIZE limits the scaling of symbols. Mapserver and symbol specication In a MapServer application, SYMBOL parameters are organised in the map le as follows: Each LAYER has a TYPE parameter that denes the type of geometry (point, line or polygon). The symbols are rendered at points, along lines or over areas accordingly. Basic symbols are dened in SYMBOL elements, using the parameters TYPE, POINTS, IMAGE, FILLED, and more (SYMBOL elements can be collected in separate symbol les for reuse). Colour, lightness, size and outline are dened inside the STYLE sections of a CLASS section using the parameters COLOR, SIZE, WIDTH and OUTLINECOLOR. Patterns for styling lines and polygons are dened in STYLE sections using GAP and PATTERN. Several basic elements can be combined to achieve a complex signature using several STYLEs inside one CLASS. The following example shows the interaction of some of these elements and explains the conguration in the LAYER and the SYMBOL sections necessary for rendering a cartographical point symbol (a red square with a 1 pixel wide black outline and a smaller blue circle inside):
68
Chapter 5. Maple
Figure 5.2: The generated overlay symbol
Table 5.1: Commented LAYER and SYMBOL sections. LAYER section of the map le # Start of layer definition LAYER # Name of the layer NAME "mytest" TYPE POINT # Point geometries STATUS DEFAULT # Always draw # Use the dataset test.shp DATA t e s t # Start of a Class definition CLASS # Start of the first Style STYLE # Symbol to be used (reference) SYMBOL "square" # Size of the symbol in pixels SIZE 16 # Colour (RGB) - red COLOR 255 0 0 # Outline colour (RGB) - black OUTLINECOLOR 0 0 0 END # end of STYLE # Start of the second Style STYLE # Symbol to be used (reference) SYMBOL "circle" # Size of the symbol in pixels SIZE 10 # Colour (RGB) - blue COLOR 0 0 255 END # end of STYLE END # end of CLASS END # end of LAYER SYMBOL (from a separate symbol le or in-line in the map le) # Start of symbol definition SYMBOL # Symbol name (referenced in STYLEs) NAME "square" TYPE vector # Type of symbol # Start of the symbol geometry POINTS 0 0 0 1 1 1 1 0 0 0 END # end of POINTS # The symbol should be filled FILLED true END # end of SYMBOL # Start of symbol definition SYMBOL # Symbol name (referenced in STYLEs) NAME "circle" TYPE ellipse # Type of symbol # Start of the symbol geometry POINTS 1 1 END # end of POINTS # The symbol should be filled FILLED true END # end of SYMBOL
5.1.3 Using Cartographical Symbols in MapServer

Vectors, truetype fonts and raster images are basic graphical elements that are dened by the TYPE parameter in the STYLE element. This and the following sections explain how these elements can be combined to create complex cartographical symbols, and they describes some other important aspects of map rendering in Mapserver.
69
Output formats MapServer support raster output formats (e.g. PNG, JPEG and GIF) and vector output formats (e.g. PDF, SVG). The raster formats (except for GIF) use anti-aliasing. See OUTPUTFORMAT (and MAP IMAGETYPE) for more. Symbol units The units used for specifying dimensions is dened in the SIZEUNITS parameter of the LAYER. The available units are listed there. The default unit is pixels. The MAP elements RESOLUTION and DEFRESOLUTION parameters will determine the resolution of the resulting map and hence the size in pixels of the symbols on the map. DEFRESOLUTION is by default 72 dpi (dots per inch). If RESOLUTION is set to 144 (and DEFRESOLUTION is 72), all dimensions specied in the map le will be multiplied by 144/72 = 2. This can be used to produce higher resolution images. Dimensions can be specied using decimals. Scaling of Symbols The SYMBOLSCALEDENOM parameter in the LAYER section species the scale at which the symbol or text label is displayed in exactly the dimensions dened in the STYLEs (for instance using SIZE and WIDTH). Observe that all the parameters concerned with the symbol dimensions (SIZE, WIDTH, ...) are tightly connected to the SYMBOLSCALEDENOM parameter. The MAXSIZE and MINSIZE parameters inside the STYLE element limit the scaling of symbols to the maximum and minimum size specied here (but does not affect the size calculations). When symbols are scaled as the scale changes, the elements (dened in STYLEs) of a composite cartographical symbol may change their positions relative to each other. This is due to rounding effects when creating the image. The effect is most noticable at small scales (large scale denominators), when the symbols get small. Due to the same effects, symbols can also slightly change their shape when they get small. It is not possibile to dene the display intervals with MINSCALEDENOM and MAXSCALEDENOM in the STYLEsection, so this kind of tuning has to be solved at the LAYER level. To do this, create several LAYERs with the same geometries for different scale levels. Always observe that cartographical symbols depend a lot on the scale! So be careful with the interaction of content, symbols and scale. All three parameters heavily interact and have to be coordinated to produce a good map.
5.1.4 Construction of Point Symbols

In the gure below, point symbols of TYPE truetype, pixmap, ellipse and vector are demonstrated. The precise position of the point for which the symbol is rendered is shown with a small red dot. A small blue dot is used to show an offset position. All point symbols can be rotated using the ANGLE parameter. Symbols of TYPE vector and ellipse For symbols of TYPE vector and ellipse the shape of the symbol by setting X and Y values in a local two dimensional coordinate system with X values increasing to the right and Y values increasing downwards. The coordinates dening the symbol is listed in the POINTS parameter, which is explicitly ended using END. TYPE ellipse is used to create ellipses (and circles). The shape of the ellipse is dened in the POINTS parameter (X - size in the horizontal direction, Y - size in the vertical direction). To create a circle, let X and Y have the same value.
70
Chapter 5. Maple
Figure 5.3: Basic point symbol TYPEs, showing effects of size, offset, angle and outlinecolor TYPE vector is used to dene advanced vector symbols. The shape of the symbol is dened in the POINTS parameter. A vector symbol can consist of several elements. The coordinates -99 -99 are used to separate the elements. To create a polygon vector symbol, the SYMBOL FILLED parameter must be set to true. If the end point is not equal to the start point of a polygon geometry, it will be closed automatically. The maximum number of points is 100, but this can be increased by changing the parameter MS_MAXVECTORPOINTS in the le mapsymbols.h before compilation. When creating symbols of TYPE vector you should observe some style guidelines. Avoid downtilted lines in area symbols, as they will lead to heavy aliasing effects. Do not go below a useful minimum size. This is relevant for all types of symbols. Keep in mind that for pixel images, every symbol of TYPE vector has to be rendered using pixels. Note: The bounding box of a vector symbol has (0,0) as its upper left corner. This can be used to precisely control symbol placement. Symbols of TYPE truetype You can use symbols from truetype fonts. The symbol settings are dened in the SYMBOL element. Specify the character or the ASCII number of the character to be used in the CHARACTER parameter. The FONT parameter is used to specify the font to be used (the alias name from the font le - often fonts.list). The FONTSET parameter of the MAP element must be set for fonts to work.
71
For gif output (GD renderer), you can dene that you want to apply antialiasing to the characters by using the parameter ANTIALIAS. It is recommended to do this especially with more complex symbols and whenever they dont t well into the raster matrix or show a visible pixel structure. Colours for truetype symbols can be specied in LAYER CLASS STYLE (as with symbols of the TYPE vector and ellipse). You can specify both ll colour and outline colour. To nd out the character number of a symbol use one of the following options: Use the software FontMap (Shareware, with free trial version for download, thanks Till!). Use the MS Windows truetype map. Trial and Error. :-) Please note that the numbering of the so-called symbol fonts starts at 61440! So if you want to use character &#84, you have to use 61440 + 84 = &#61524. (aint that a pain!!) You can also place truetype characters and strings on the map using LABEL. Then you can control the placing of the text by using the POSITION parameter [ul|uc|ur|cl|cc|cr|ll|lc|lr], that species the position relative to the geometric origin of the geometry. Symbols of TYPE pixmap Symbols of the TYPE pixmap are simply small raster images. The le name of the raster image is specied in the IMAGE parameter of the SYMBOL element. MapServer supports the raster formats GIF and PNG for pixmaps. Observe the colour depth of the images and avoid using 24 bit PNG symbols displayed in 8 bit mode as this may cause unexpected colour leaps. When using raster images, the colour cannot be modied in the SYMBOL element subsequently. You can specify a colour with the TRANSPARENT parameter which will not be displayed - i.e. it will be transparent. As a result, underlying objects and colours are visible. The SIZE parameter denes the height of pixmap symbols when rendered. The pixel structure will show when the SIZE grows too large. If you are using symbol scaling (LAYER SYMBOLSCALEDENOM is set or LAYER SIZEUNITS is not pixels) and want to prevent this from happening, you should set the STYLE MAXSIZE parameter. Symbol denitions for the gure that demonstrates point symbols This code was used to produce the symbols in the point symbol gure. First, the symbol denitions:
SYMBOL NAME "o-flag-trans" TYPE pixmap IMAGE "o-flag-trans.png" END # SYMBOL SYMBOL NAME "circlef" TYPE ellipse FILLED true POINTS 10 10 END # POINTS END # SYMBOL
72
Chapter 5. Maple
SYMBOL NAME "P" TYPE truetype FONT "arial" CHARACTER "P" END # SYMBOL SYMBOL NAME "v-line" TYPE vector FILLED false POINTS 0 0 5 10 10 0 END # POINTS END # SYMBOL SYMBOL NAME "v-poly" TYPE vector FILLED true POINTS 0 0 3.5 8 7 0 5.2 0 3.5 4 1.8 0 0 0 END # POINTS END # SYMBOL
Then, the LAYERs and STYLEs used for producing the polygon V symbols in the point symbol gure:
LAYER # Vector v - polygon STATUS DEFAULT TYPE POINT FEATURE POINTS 10 30 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" COLOR 0 0 0 END # STYLE STYLE SYMBOL "circlef" COLOR 255 0 0 SIZE 4 END # STYLE END # CLASS END # LAYER LAYER # Vector v - polygon, size STATUS DEFAULT TYPE POINT
73
FEATURE POINTS 20 30 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" COLOR 0 0 0 SIZE 30 END # STYLE STYLE SYMBOL "circlef" COLOR 255 0 0 SIZE 4 END # STYLE END # CLASS END # LAYER LAYER # Vector v - polygon, size, angle STATUS DEFAULT TYPE POINT FEATURE POINTS 30 30 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" COLOR 0 0 0 SIZE 30 ANGLE 60 END # STYLE STYLE SYMBOL "circlef" COLOR 255 0 0 SIZE 4 END # STYLE END # CLASS END # LAYER LAYER # Vector v - polygon, size, offset STATUS DEFAULT TYPE POINT FEATURE POINTS 40 30 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" COLOR 0 0 0 SIZE 30 OFFSET 0 15 END # STYLE STYLE
74
Chapter 5. Maple
SYMBOL "circlef" COLOR 255 0 0 SIZE 4 END # STYLE END # CLASS END # LAYER LAYER # Vector v - polygon, size, angle, offset STATUS DEFAULT TYPE POINT FEATURE POINTS 50 30 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" COLOR 0 0 0 SIZE 30 ANGLE 60 OFFSET 0 15 END # STYLE STYLE SYMBOL "circlef" COLOR 255 0 0 SIZE 4 END # STYLE END # CLASS END # LAYER LAYER # Vector v - polygon, size outline STATUS DEFAULT TYPE POINT FEATURE POINTS 60 30 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" COLOR 0 0 0 SIZE 30 OUTLINECOLOR 0 255 0 END # STYLE STYLE SYMBOL "circlef" COLOR 255 0 0 SIZE 4 END # STYLE END # CLASS END # LAYER LAYER # Vector v - polygon, size, outline, width STATUS DEFAULT TYPE POINT FEATURE
75
POINTS 70 30 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" COLOR 0 0 0 SIZE 30 OUTLINECOLOR 0 255 0 WIDTH 4 END # STYLE STYLE SYMBOL "circlef" COLOR 255 0 0 SIZE 4 END # STYLE END # CLASS END # LAYER LAYER # Vector v - polygon, size, outline, no color STATUS DEFAULT TYPE POINT FEATURE POINTS 80 30 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" SIZE 30 OUTLINECOLOR 0 255 0 END # STYLE STYLE SYMBOL "circlef" COLOR 255 0 0 SIZE 4 END # STYLE END # CLASS END # LAYER
Combining symbols The following gure shows how to combine several basic symbols to create a complex point symbol. The combination is achieved by adding several STYLEs within one LAYER. Each STYLE element references one SYMBOL element. All the basic symbols are centered and overlayed when rendered. Notice that the SIZE parameter in the STYLE element refers to the height of the symbol (extent in the Y direction). A standing rectangle will thus display with a smaller area than a lying rectangle, although both have the same SIZE parameter and the same maximum Y value in the SYMBOL element. When combining several basic point symbols on top of each other, they will not always be centered correctly due to the integer mathematics required when rendering raster images. It is recommended not to combine elements with even and odd numbered SIZE parameters, as this tends to produce larger irregularities.
76
Chapter 5. Maple
Figure 5.4: Construction of Point Symbols
77
5.1.5 Construction of Line Symbols

For displaying line geometries, you specify the width of the lines using the WIDTH parameter and the colour using the COLOR parameter. If no colour is specied, the line will not be rendered. If no width is specied, a thin line (one unit (pixel) wide) will be rendered. The LINECAP, LINEJOIN and LINEJOINMAXSIZE parameters are used to specify how line ends and corners are to be rendered. Overlaying lines When combining several styles / symbols on a line, they will be positioned on the baseline which is dened by the geometry of the object. In most cases MapServer correctly centers symbols. The combination of a line displayed in 16 units width and overlayed with a 10 unit width line, results in a line symbol with a 3 unit border. If the cartographical symbol is to contain a centered line with a width of 1 pixel, then the widths should be recongured, for example to 11 and 17 units. As a rule of thumb dont combine even numbered and odd numbered widths. Use of the PATTERN and GAP parameters The PATTERN and GAP parameters can be used to produce styled lines in MapServer. To create line patterns, use the PATTERN parameter of the STYLE. Here you dene dashes by specifying the length of the rst dash, followed by the length of the rst gap, then the length of the second dash, followed by the second gap, and so on. This pattern will be repeated as many times as that pattern will t into the line. LINECAP can be used to control how the ends of the dashes are rendered. LINEJOIN can be used to control how sharp bends are rendered. In the left column of the gure, you will nd three examples where PATTERN has been used. Number 2 from below uses LINECAP butt, number 3 from below uses LINECAP round (and LINEJOIN miter) and number 4 from below uses LINECAP butt (and is overlayed over a wider, dark grey line). To produce dots, use 0 for dash length with LINECAP round. Styled lines can be specied using GAP and a symbol for styling. In the gure, you will nd examples where GAP has been used (in the right column). At the bottom a SYMBOL of TYPE ellipse has been used, then a SYMBOL of TYPE vector, then a SYMBOL of TYPE font and then a SYMBOL of TYPE pixmap. Note: It is currently not possible to specify an offset (start gap) when creating asymmetrical patterns. The following gure shows how to use styles to dene different kinds of line symbols. Note: For the styled lines in the right column, if center to center distance had been used for gap, the red dots would have coincided with the black dots. But currently GAP is not implemented that way. Below you will nd the SYMBOLs and STYLEs that were used to produce the line symbols in Construction of Line Symbols. The LAYERs are ordered from bottom to top of the gure. Styles and symbols for lines
SYMBOL NAME "circlef" TYPE ellipse FILLED true POINTS 1 1 END # POINTS END # SYMBOL SYMBOL NAME "P" TYPE truetype FONT "arial"
78
Chapter 5. Maple
Figure 5.5: Construction of Line Symbols
79
CHARACTER "P" END # SYMBOL SYMBOL NAME "vertline" TYPE vector FILLED true POINTS 0 5 0 10 1.4 10 1.4 5 0 5 END # POINTS END # SYMBOL SYMBOL NAME "o-flag-trans" TYPE pixmap IMAGE "o-flag-trans.png" END # SYMBOL ######## Left column ############### LAYER # Simple line STATUS DEFAULT TYPE LINE FEATURE POINTS 5 5 25 10 45 10 35 5 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 6.5 END # STYLE END # CLASS END # LAYER LAYER # Dashed line STATUS DEFAULT TYPE LINE FEATURE POINTS 5 15 25 20 45 20 35 15 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 5.0
80
Chapter 5. Maple
PATTERN 40 10 END END # STYLE END # CLASS END # LAYER LAYER # Dashed line, varying STATUS DEFAULT TYPE LINE FEATURE POINTS 5 25 25 30 45 30 35 25 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 5.0 LINECAP round #[butt|round|square|triangle] LINEJOIN miter #[round|miter|bevel] LINEJOINMAXSIZE 3 PATTERN 40 17 0 17 0 17 0 17 END END # STYLE END # CLASS END # LAYER LAYER # Line dash overlay STATUS DEFAULT TYPE LINE FEATURE POINTS 5 35 25 40 45 40 35 35 END # Points END # Feature CLASS STYLE COLOR 102 102 102 WIDTH 4.0 END # STYLE STYLE COLOR 255 255 255 WIDTH 2.0 LINECAP BUTT PATTERN 8 12 END END # STYLE END # CLASS END # LAYER LAYER # Line overlay - 2 STATUS DEFAULT TYPE LINE FEATURE POINTS
81
5 45 25 50 45 50 35 45 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 16.0 END # STYLE STYLE COLOR 209 66 0 WIDTH 10.0 END # STYLE END # CLASS END # LAYER LAYER # Line overlay - 3 STATUS DEFAULT TYPE LINE FEATURE POINTS 5 55 25 60 45 60 35 55 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 17.0 END # STYLE STYLE COLOR 209 66 0 WIDTH 11.0 END # STYLE STYLE COLOR 0 0 0 WIDTH 1.0 END # STYLE END # CLASS END # LAYER ######## right column ############ LAYER # Line - ellipse overlay STATUS DEFAULT TYPE LINE FEATURE POINTS 50 5 70 10 90 10 80 5 END # Points END # Feature
82
Chapter 5. Maple
CLASS STYLE COLOR 0 0 0 WIDTH 3.6 END # STYLE STYLE COLOR 0 0 0 SYMBOL "circlef" SIZE 10 GAP 42 END # STYLE STYLE COLOR 255 0 0 SYMBOL "circlef" SIZE 3 GAP 42 END # STYLE END # CLASS END # LAYER LAYER # Line - symbol overlay STATUS DEFAULT TYPE LINE FEATURE POINTS 50 15 70 20 90 20 80 15 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 2.8 END # STYLE STYLE COLOR 0 0 0 SYMBOL "vertline" SIZE 20.0 ANGLE 30 GAP -50 END # STYLE END # CLASS END # LAYER LAYER # Line - font overlay STATUS DEFAULT TYPE LINE FEATURE POINTS 50 25 70 30 90 30 80 25 END # Points END # Feature CLASS
83
STYLE COLOR 0 0 0 WIDTH 6 END # STYLE STYLE COLOR 102 0 0 SYMBOL "P" SIZE 20 GAP -30 END # STYLE END # CLASS END # LAYER LAYER # Line - pixmap overlay STATUS DEFAULT TYPE LINE FEATURE POINTS 50 35 70 40 90 40 80 35 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 6 END # STYLE STYLE COLOR 102 0 0 SYMBOL "o-flag-trans" SIZE 20 GAP -30 END # STYLE END # CLASS END # LAYER LAYER # Line - pixmap overlay STATUS DEFAULT TYPE LINE FEATURE POINTS 50 45 70 50 90 50 80 45 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 6 END # STYLE STYLE COLOR 102 0 0 SYMBOL "o-flag-trans" SIZE 20
84
Chapter 5. Maple
GAP -30 OFFSET -10 -99 END # STYLE END # CLASS END # LAYER
LINECAP
By default, all lines (and patterns) will be drawn with rounded ends (extending the lines slightly beyond their ends). This effect gets more obvious the larger the width of the line is. It is possible to alter this behaviour using the LINECAP parameter of the STYLE. LINECAP butt will give butt ends (stops the line exactly at the end), with no extension of the line. LINECAP square will give square ends, with an extension of the line. LINECAP round is the default.
LINEJOIN
The different values for the parameter LINEJOIN have the following visual effects. Default is round. miter will follow line borders until they intersect and ll the resulting area. none will render each segment using linecap butt. The gure below illustrates the different linejoins.
Figure 5.6: Different kinds of linejoins
LINEJOINMAXSIZE (only relevant for LINEJOIN miter )

Specify the maximum length of m (see the gure below). The value is a multiplication factor (default 3). The max length of the miter join is calculated as follows (d is the line width, specied with the WIDTH parameter of the STYLE):
m_max = d * LINEJOINMAXSIZE
If m > m_max, then the connection length will be set to m_max. Use of the OFFSET parameter In STYLE, an OFFSET parameter can be set to shift symbols in the X and Y direction. The displacement is not inuenced by the direction of the line geometry. Therefore the point symbols used for styling are all shifted in the same direction, independent of the direction of the line (as dened in style number 2 in the map le example below red line in the map image). A positive X value shifts to the right. A positive Y value shifts downwards. To generate lines that are shifted relative to the original lines, -99 has to be used for the Y value of the OFFSET. Then the X value denes the distance to the line from the original geometry (perpendicular to the line). A positive X value will shift to the right (when viewed in the direction of the line), a negative X value will shift to the left.
85
Figure 5.7: Miter linejoin The example below shows how OFFSET works with the use of -99 (blue and green lines) and without the use of -99 (red line). The thin black line shows the location of the line geometry.
Figure 5.8: Use of the OFFSET parameter with lines - map image
86
Chapter 5. Maple
Use of the OFFSET parameter with lines - Map le excerpt LAYER # STATUS DEFAULT TYPE LINE FEATURE POINTS 20 20 280 160 280 20 160 20 160 60 END # Points END # Feature CLASS STYLE # no offset COLOR 0 0 0 # black WIDTH 1 END # STYLE STYLE # simple offset left and down COLOR 255 0 0 # red WIDTH 2 OFFSET -8 12 END # STYLE STYLE # left offset rel. to line direction COLOR 0 0 255 # blue WIDTH 5 OFFSET -16 -99 END # STYLE STYLE # right offset rel. to line direction COLOR 0 255 0 # green WIDTH 5 OFFSET 16 -99 END # STYLE END # CLASS END # LAYER
Asymmetrical line styling with point symbols Line number 2 and 5 from the bottom in the right column of the Construction of Line Symbols gure are examples of asymmetrical line styling using a point symbol. This can be achieved either by using an OFFSET (with a Y value of -99), or by using an asymmetrical point symbol of TYPE vector, as described in the tricks section below. Line number 2 from the bottom is produced using an asymmetrical point symbol - this is the best method for placing symbols on lines. Line number 5 from the bottom is produced using STYLE OFFSET. As can be seen, the symbols are here rendered on the offset line, meaning that at sharp bends, some symbols will be placed far away from the line.
5.1.6 Area Symbols

Areas (polygons) can be lled with full colour. Areas can also be lled with symbols to create for instance hatches and graticules.
87
The symbols are by default used as tiles, and rendered (without spacing) one after the other in the x and y direction, lling the whole polygon. If the SIZE parameter is used in the STYLE, the symbols will be scaled to the specied height. The GAP parameter of the STYLE can be used to increase the spacing of the symbols. The AGG renderer uses anti-aliasing by default, so edge effects around the symbols can occure. Hatch ll Simple line hatches (e.g. horizontal, vertical and diagonal) can be created by lling the polygon with a hatch symbol.
Figure 5.9: Hatch examples The SIZE parameter in the STYLE that uses a SYMBOL of type hatch species the distance from center to center between the lines (the default is 1). The WIDTH parameter species the width of the lines in the hatch pattern (default is 1). The ANGLE parameter species the direction of the lines (default is 0 - horizontal lines). The gure demonstrates the use of SIZE (bottom left), WIDTH (bottom right), ANGLE (top left) and overlay (top right) of hatches. The code below shows excerpts of the map le that was used to produce the gure. First, the SYMBOL denition:
SYMBOL NAME "hatchsymbol" TYPE hatch END
Then the CLASS denitions:
88
Chapter 5. Maple
Table 5.2: Hatches CLASS denitions LAYER # hatch ... CLASS STYLE SYMBOL "hatchsymbol" COLOR 0 0 0 SIZE 10 END # STYLE END # CLASS END # LAYER LAYER # hatch with angle ... CLASS STYLE SYMBOL "hatchsymbol" COLOR 0 0 0 SIZE 10 ANGLE 45 END # STYLE END # CLASS END # LAYER LAYER # hatch with wide lines ... CLASS STYLE SYMBOL "hatchsymbol" COLOR 0 0 0 SIZE 10 WIDTH 5 END # STYLE END # CLASS END # LAYER LAYER # cross hatch ... CLASS STYLE SYMBOL "hatchsymbol" COLOR 255 153 0 SIZE 10 WIDTH 4 END # STYLE STYLE SYMBOL "hatchsymbol" COLOR 0 0 255 SIZE 20 ANGLE 90 END # STYLE END # CLASS END # LAYER 5.1. Cartographical Symbol Construction with MapServer 89
Polygon lls with symbols of TYPE pixmap Polygons can be lled with pixmaps. Note: If the STYLE SIZE parameter is different from the image height of the pixmap, there can be rendering artefacts around the pixmaps (visible as a grid with the background colour). Pixmap symbols can be rotated using the ANGLE parameter, but for polygon lls, this produces strange effects, and is not recommended. To create complex area symbols, e.g. with dened distances between single characters or hatches with broad lines, pixmap ll is probably the best option. Depending on the desired pattern you have to generate the raster image with high precision using a graphical editor. The gure below is an example of how to obtain a regular allocation of symbols with dened spacing.
Figure 5.10: Raster image for a regular symbol ll You can use other shapes than circles. B denes the width and H the height of the raster image. For a regular arrangment of symbols in a 45 degree angle B = H. For symbols, which are regularly arranged in parallel and without offset between each other one centered symbol with the same x and y distances to the imageborder is enough. The following gure shows an example of how you can design a pixmap to produce a hatch with wide lines. To create a 45 degree hatch use:
B = H and x = y
Note: When using the MapServer legend, observe that each raster pixmap is displayed only once in the original size in the middle of the legend box. The example below shows some pixmap symbols which can be used as area symbols with transparency. The raster images were created using FreeHand, nished with Photoshop and exported to PNG with special attention to the colour palette.
90
Chapter 5. Maple
Figure 5.11: Raster image for a hatched ll
Table 5.3: Construction of a horizontally arranged area symbol CLASS section CLASS STYLE COLOR 255 255 0 END STYLE SYMBOL "in_the_star" END STYLE OUTLINECOLOR 0 0 0 WIDTH 1 END END SYMBOL denition SYMBOL NAME "in_the_star" TYPE PIXMAP IMAGE "stern.png" TRANSPARENT 8 END
Figure 5.12: Polygon ll - regular grid pattern
91
Table 5.4: Construction of a diagonally arranged area symbol CLASS section CLASS STYLE SYMBOL "in_point1" END STYLE OUTLINECOLOR 0 0 0 WIDTH 1 END END SYMBOL denition SYMBOL NAME "in_point1" TYPE PIXMAP IMAGE "flaeche1_1.png" TRANSPARENT 13 END
Figure 5.13: Polygon ll - diagonal pattern Table 5.5: Construction of a hatch CLASS section CLASS STYLE COLOR 255 255 0 END STYLE SYMBOL "in_hatch" END STYLE OUTLINECOLOR 0 0 0 WIDTH 1 END END SYMBOL denition SYMBOL NAME "in_hatch" TYPE PIXMAP IMAGE "schraffur.png" TRANSPARENT 2 END
Figure 5.14: Polygon ll - hatch
Polygon lls with symbols of TYPE vector Polygons can be lled with symbols of TYPE vector. As for the other symbol lls, the pattern will be generated by using the specied symbol for the tiles. The bounding box of the symbol is used when tiling. 92 Chapter 5. Maple
The upper left corner of the bounding box of a symbols of TYPE vector is always (0, 0). The lower right corner of the bounding box is determined by the maximum x and y values of the symbol denition (POINTS parameter). Creating vector symbols for polygon lls is done in much the same way as for pixmap symbols. Precision is necessary to get nice symmetrical symbols. Both polygon (FILLED true) and line (FILLED false) vector symbols can be used. For line symbols, the WIDTH parameter of the STYLE will give the line width and the SIZE parameter will specify the height of the symbol. Note: For vector line symbols (FILL off), if a width greater than 1 is specied, the lines will grow to extend outside the original bounding box of the symbol. The parts that are outside of the bounding box will be cut away. STYLE ANGLE can be used for polygon lls, but will only rotate each individual symbol, not the pattern as a whole. It is therefore quite demanding to generate rotated patterns. Below you will nd some examples of vector symbols used for polygon lls. The polygon ll is accompanied by the vector symbol used for the ll. The centre of the vector symbol is indicated with a red dot.
Figure 5.15: Polygon lls - vector
Excerpts from the map le for the polygon ll vector examples above
First, the LAYERs
LAYER # chess board STATUS DEFAULT
93
TYPE POLYGON FEATURE POINTS 5 5 5 25 45 25 45 5 5 5 END # Points END # Feature CLASS STYLE SYMBOL "chess" COLOR 0 0 0 SIZE 35 END # STYLE END # CLASS END # LAYER LAYER # x - line STATUS DEFAULT TYPE POLYGON FEATURE POINTS 5 30 5 50 45 50 45 30 5 30 END # Points END # Feature CLASS STYLE SYMBOL "x-line" COLOR 0 0 0 WIDTH 5 SIZE 35 END # STYLE END # CLASS END # LAYER LAYER # v polygon STATUS DEFAULT TYPE POLYGON FEATURE POINTS 5 55 5 75 45 75 45 55 5 55 END # Points END # Feature CLASS STYLE SYMBOL "v-poly" COLOR 0 0 0 SIZE 35
94
Chapter 5. Maple
END # STYLE END # CLASS END # LAYER LAYER # Circles STATUS DEFAULT TYPE POLYGON FEATURE POINTS 5 80 5 100 45 100 45 80 5 80 END # Points END # Feature CLASS STYLE SYMBOL "circlef" COLOR 0 0 0 SIZE 20 GAP 18 END # STYLE END # CLASS END # LAYER LAYER # x polygon STATUS DEFAULT TYPE POLYGON FEATURE POINTS 55 5 55 25 95 25 95 5 55 5 END # Points END # Feature CLASS STYLE COLOR 0 0 0 SYMBOL "x-poly-fill" SIZE 35 END # STYLE END # CLASS END # LAYER LAYER # indistinct marsh STATUS DEFAULT TYPE POLYGON FEATURE POINTS 55 30 55 50 95 50 95 30 55 30 END # Points
95
END # Feature CLASS STYLE COLOR 0 0 255 SYMBOL "ind_marsh_poly" SIZE 25 END # STYLE END # CLASS END # LAYER LAYER # diagonal circles STATUS DEFAULT TYPE POLYGON FEATURE POINTS 55 55 55 75 95 75 95 55 55 55 END # Points END # Feature CLASS STYLE COLOR 255 230 51 SYMBOL "diag_dots" SIZE 30 END # STYLE END # CLASS END # LAYER
LAYER # diagonal holes in yellow STATUS DEFAULT TYPE POLYGON FEATURE POINTS 55 80 55 100 95 100 95 80 55 80 END # Points END # Feature CLASS STYLE SYMBOL "diag_holes" SIZE 30 COLOR 250 220 102 END # STYLE END # CLASS END # LAYER LAYER # v line + circle STATUS DEFAULT TYPE POLYGON FEATURE POINTS
96
Chapter 5. Maple
100 5 100 25 140 25 140 5 100 5 END # Points END # Feature CLASS STYLE COLOR 255 0 0 SYMBOL "circlef" SIZE 30 GAP 45 END # STYLE STYLE COLOR 0 0 0 SYMBOL "v-line" LINEJOIN miter LINECAP butt SIZE 35 WIDTH 10 GAP 45 END # STYLE END # CLASS END # LAYER LAYER # indistinct marsh + diagonal holes in yellow STATUS DEFAULT TYPE POLYGON FEATURE POINTS 100 30 100 50 140 50 140 30 100 30 END # Points END # Feature CLASS STYLE COLOR 0 0 255 SYMBOL "ind_marsh_poly" SIZE 25 END # STYLE STYLE SYMBOL "diag_holes" SIZE 30 COLOR 250 220 0 OPACITY 75 END # STYLE END # CLASS END # LAYER LAYER # x line + circle STATUS DEFAULT TYPE POLYGON FEATURE POINTS
97
100 55 100 75 140 75 140 55 100 55 END # Points END # Feature CLASS STYLE COLOR 0 0 255 SYMBOL "circle" WIDTH 5 SIZE 20 GAP 30 END # STYLE STYLE COLOR 0 204 0 SYMBOL "x-line" SIZE 10 WIDTH 3 GAP 30 END # STYLE END # CLASS END # LAYER
Then the SYMBOLs:

SYMBOL NAME "circlef" TYPE ellipse FILLED true POINTS 10 10 END # POINTS END # SYMBOL SYMBOL NAME "circle" TYPE ellipse FILLED false POINTS 10 10 END # POINTS END # SYMBOL SYMBOL NAME "v-line" TYPE vector POINTS 0 0 5 10 10 0 END END SYMBOL NAME "v-poly" TYPE vector FILLED false
98
Chapter 5. Maple
FILLED true POINTS 0 0 3.5 8 7 0 5.2 0 3.5 4 1.8 0 0 0 END END SYMBOL NAME "x-line" TYPE vector POINTS 0 0 1 1 -99 -99 0 1 1 0 END END SYMBOL NAME "chess" TYPE vector FILLED true POINTS 0 0 10 0 10 10 0 10 0 0 -99 -99 10 10 20 10 20 20 10 20 10 10 END END SYMBOL NAME "x-poly-fill" TYPE vector FILLED true POINTS 0 1.131 0 0 1.131 0 4.566 3.434 8 0 9.131 0 9.131 1.131 5.697 4.566 9.131 8 9.131 9.131
99
8 9.131 4.566 5.697 1.131 9.131 0 9.131 0 8 3.434 4.566 0 1.131 END # POINTS END # SYMBOL SYMBOL NAME "ind_marsh_poly" TYPE vector FILLED true POINTS # Half line 0 2 4.5 2 4.5 3 0 3 0 2 -99 -99 # Half line 7 2 11.5 2 11.5 3 7 3 7 2 -99 -99 # Hole line 1.25 5 10.25 5 10.25 6 1.25 6 1.25 5 END END SYMBOL NAME "diag_dots" TYPE vector FILLED true POINTS # Central circle: 0.7450 0.4500 0.7365 0.5147 0.7115 0.5750 0.6718 0.6268 0.6200 0.6665 0.5597 0.6915 0.4950 0.7000 0.4303 0.6915 0.3700 0.6665 0.3182 0.6268 0.2785 0.5750 0.2535 0.5147 0.2450 0.4500 0.2535 0.3853
100
Chapter 5. Maple
0.2785 0.3182 0.3700 0.4303 0.4950 0.5597 0.6200 0.6718 0.7115 0.7365 0.7450 -99 -99 0.25 0.2415 0.2165 0.1768 0.1250 0.0647 0.0 0.0 0.25 -99 -99 1 0.25 0.9252 0.8649 0.8132 0.7734 0.7485 0.74 1 0.0 1 0.25 -99 -99 0.74 0.7485 0.7734 0.8132 0.8649 0.9252 1 0.74 1 1 0.74 -99 -99 0.0 0.0647 0.1250 0.1768 0.2165 0.2415 0.25 0.0 0.0 END END
0.3250 0.2732 0.2335 0.2085 0.2000 0.2085 0.2335 0.2732 0.3250 0.3853 0.4500 0.0 0.0647 0.1250 0.1768 0.2165 0.2415 0.25 0.0 0.0
0.2415 0.2165 0.1768 0.1250 0.0647 0.0
1 0.9252 0.8649 0.8132 0.7734 0.7485
1 0.74 0.7485 0.7734 0.8132 0.8649 0.9252 1 1 0.74
SYMBOL NAME "diag_holes" TYPE vector FILLED true
101
POINTS 0.0 0.0 # Left half circle 0.0 0.24 0.0647 0.2485 0.1250 0.2734 0.1768 0.3132 0.2165 0.3649 0.2415 0.4252 0.25 0.5 0.2415 0.5647 0.2165 0.6250 0.1768 0.6768 0.1250 0.7165 0.0647 0.7415 0.0 0.75 0.0 1.0 # Bottom half circle 0.24 1 0.2485 0.9252 0.2734 0.8649 0.3132 0.8132 0.3649 0.7734 0.4252 0.7485 0.5 0.74 0.5647 0.7485 0.6250 0.7734 0.6768 0.8132 0.7165 0.8649 0.7415 0.9252 0.75 1 1.0 1.0 # Right half circle 1 0.75 0.9252 0.7415 0.8649 0.7165 0.8132 0.6768 0.7734 0.6250 0.7485 0.5647 0.74 0.5 0.7485 0.4252 0.7734 0.3649 0.8132 0.3132 0.8649 0.2734 0.9252 0.2485 1 0.24 1.0 0.0 # Top half circle 0.75 0.0 0.7415 0.0647 0.7165 0.1250 0.6768 0.1768 0.6250 0.2165 0.5647 0.2415 0.5 0.25
102
Chapter 5. Maple
0.4252 0.3649 0.3132 0.2734 0.2485 0.24 0.0 END END
0.2415 0.2165 0.1768 0.1250 0.0647 0.0 0.0
Polygon outlines Polygon outlines can be created by using OUTLINECOLOR in the STYLE. WIDTH species the width of the outline.
STYLE OUTLINECOLOR 0 255 0 WIDTH 3 END # STYLE
Dashed polygon outlines can be achieved by using OUTLINECOLOR, WIDTH and PATTERN (together with LINECAP, LINEJOIN and LINEJOINMAXSIZE). For more information on the use of PATTERN, see Use of the PATTERN and GAP parameters.
STYLE OUTLINECOLOR 0 255 0 WIDTH 3 PATTERN 10 5 END # PATTERN LINECAP BUTT END # STYLE
For some symbol types, it is even possible to style polygon outlines using OUTLINECOLOR, SYMBOL and GAP.
STYLE OUTLINECOLOR 0 255 0 SYMBOL circle SIZE 5 GAP 15 END # STYLE
5.1.7 Examples (Mapserver 4)

The examples in this section were made for MapServer 4. Note: Many of these symbols will not work with later versions of Mapserver, but they contain a lot of useful symbol denitions and are therefore provided as reference. The symbols were created with map les and symbol les (download_old_symbols). If you want to use these MAP les please note, that your MapServer must at least be able to handle 50 symbols. Otherwise you will get an error while loading the symbol les.
103
Basic Symbols
104
Chapter 5. Maple
105
Complex Symbols
106
Chapter 5. Maple
107
5.1.8 Tricks
Changing the center of a point symbol Mapserver does all transformations (offset, rotation) with respect to the symbol center point. The center point is calculated from the symbols bounding box. In some cases it can be useful to change the center point of a symbol. Currently there is no way of explicitly specifying the center point of a SYMBOL. A mechanism for this (a new keyword in SYMBOL that species the symbol center point) has been suggested in RFC45, but has not been implemented so far. When determining the position of the symbol center point, the lower x and y values of the bounding box is always set to 0. Here are some examples of what can be achieved by taking advantage of this for point symbols and decorated lines. There are three examples in the illustration, and each example shows the result with and without the offset trick. At the top arrows are added to lines using GEOMTRANSFORM start / end. In the middle, tags are added to lines using GAP and ANGLE. At the bottom, a point symbol is shifted and rotated. The red dots represent the center points, and the blue dots the offsets. Below you will nd three tables that contain the SYMBOLs and the STYLE mechanisms that were used to generate the shifted symbols in the illustration.
108
Chapter 5. Maple
Figure 5.16: Shifting trick
109
Table 5.6: Symbol tricks - shift - arrows SYMBOLs SYMBOL NAME "arrow-offset-end" TYPE vector FILLED true POINTS -5 0.4 -2 0.4 -2 0 0 0.8 -2 1.6 -2 1.2 -5 1.2 -5 0.4 END # POINTS END # SYMBOL SYMBOL NAME "arrow-offset-start" TYPE vector FILLED true POINTS 5 0.4 8 0.4 8 0 10 0.8 8 1.6 8 1.2 5 1.2 5 0.4 END # POINTS END # SYMBOL LAYER STYLEs LAYER # Line STATUS DEFAULT TYPE LINE FEATURE POINTS 20 65 40 70 60 70 70 65 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 15 LINECAP butt END # STYLE STYLE GEOMTRANSFORM "start" COLOR 0 255 0 SYMBOL "arrow-offset-start" SIZE 15.0 ANGLE AUTO END # STYLE STYLE GEOMTRANSFORM "start" COLOR 255 0 0 SYMBOL "circlef" SIZE 3 END # STYLE STYLE GEOMTRANSFORM "end" COLOR 0 255 0 SYMBOL "arrow-offset-end" SIZE 15.0 ANGLE AUTO END # STYLE STYLE GEOMTRANSFORM "end" COLOR 255 0 0 SYMBOL "circlef" SIZE 3 END # STYLE END # CLASS END # LAYER
110
Chapter 5. Maple
Table 5.7: Symbol tricks - shift - asymmetrical tags SYMBOLs SYMBOL NAME "fence-tag" TYPE vector POINTS 0 5 0 10 END # POINTS END # SYMBOL SYMBOL NAME "vert-line" TYPE vector POINTS 0 0 0 10 END # POINTS END # SYMBOL LAYER STYLEs LAYER # Line - symbol overlay STATUS DEFAULT TYPE LINE FEATURE POINTS 20 50 40 55 60 55 70 50 END # Points END # Feature CLASS STYLE COLOR 0 0 0 WIDTH 4 END # STYLE STYLE COLOR 0 0 0 SYMBOL "fence-tag" SIZE 40.0 WIDTH 3 ANGLE 30 GAP -50 END # STYLE STYLE COLOR 255 0 0 SYMBOL "circlef" SIZE 1 GAP -50 END # STYLE END # CLASS END # LAYER
111
Table 5.8: Symbol tricks. Unshifted symbol v-line, shifted symbol v-line-offs SYMBOLs SYMBOL NAME "v-line" TYPE vector POINTS 0 0 5 10 10 0 END # POINTS END # SYMBOL SYMBOL NAME "v-line-offs" TYPE vector POINTS 0 10 5 20 10 10 END # POINTS END # SYMBOL
5.1.9 Maple changes related to symbols

In version 6.0, parameters related to styling was moved from the SYMBOL element to the STYLE element of CLASS (in LAYER): PATTERN (introduced in 5.0, previously called STYLE), GAP, LINECAP, LINEJOIN, LINEJOINMAXSIZE The SYMBOL TYPE cartoline is no longer needed, and therefore not available in version 6.0.
5.1.10 Current Problems / Open Issues

GAP - PATTERN incompatibility Creating advanced line symbols involving dashed lines are difcult due to the incompatibility of the dashed line mechanisms (PATTERN) and the symbol on line placement mechanisms (GAP). A solution could be to allow GAP to be a list instead of a single number (perhaps renaming to GAPS or DISTANCES), but it would also be necessary to introduce a new parameter to specify the distance to the rst symbol on the line (STARTGAP / FIRSTDISTANCE?). GAP does not support two dimensions (relevant for polygon lls), so the same gap will have to be used for for the x and the y directions. The introduction of new parameters - GAPX and GAPY could be a solution to this.
5.1.11 The End

We hope that this document will help you to present your data in a cartographically nice manner with MapServer and explains some basics and possibilities of the concept of MapServer as well as some weaknesses. It would be great to put together a cartographical symbols library for the prot of everyone. This especially concerns truetype fonts, which have been developed for some projects and contain some typical signatures for cartographical needs.
112
Chapter 5. Maple
You can also view the discussion paper for the improvement of the MapServer Graphic-Kernel (German only).
5.2 CLASS
BACKGROUNDCOLOR [r] [g] [b] Color to use for non-transparent symbols. COLOR [r] [g] [b] Color to use for drawing features. DEBUG [on|off] Enables debugging of the class object. Verbose output is generated and sent to the standard error output (STDERR) or the MapServer logle if one is set using the LOG parameter in the WEB object. See Also: MS RFC 28: Redesign of LOG/DEBUG output mechanisms EXPRESSION [string] Four types of expressions are now supported to dene which class a feature belongs to: String comparisons, regular expressions, logical expressions, and string functions (see Expressions). If no expression is given, then all features are said to belong to this class. String comparisons are case sensitive and are the fastest to evaluate. No special delimiters are necessary although strings must be quoted if they contain special characters. (As a matter of good habit, it is recommended that you quote all strings). The attribute to use for comparison is dened in the LAYER CLASSITEM parameter. Regular expression are limited using slashes (/regex/). The attribute to use for comparison is dened in the LAYER CLASSITEM parameter. Logical expressions allow the building of fairly complex tests based on one or more attributes and therefore are only available with shapeles. Logical expressions are delimited by parentheses (expression). Attribute names are delimited by square brackets [ATTRIBUTE]. Attribute names are case sensitive and must match the items in the shapele. For example:
EXPRESSION ([POPULATION] > 50000 AND [LANGUAGE] eq FRENCH)
The following logical operators are supported: =, >, <, <=, >=, =, or, and, lt, gt, ge, le, eq, ne, in, ~, ~*. As one might expect, this level of complexity is slower to process. One string function exists: length(). It computes the length of a string:
EXPRESSION (length([NAME_E]) < 8)
String comparisons and regular expressions work from the classitem dened at the layer level. You may mix expression types within the different classes of a layer. GROUP [string] Allows for grouping of classes. It is only used when a CLASSGROUP at the LAYER level is set. If the CLASSGROUP parameter is set, only classes that have the same group name would be considered at rendering time. An example of a layer with grouped classes might contain:
LAYER ... CLASSGROUP "group1" ... CLASS NAME "name1" GROUP "group1" ... END CLASS
5.2. CLASS
113
NAME "name2" GROUP "group2" ... END CLASS NAME "name3" GROUP "group1" ... END ... END # layer
KEYIMAGE [lename] Full lename of the legend image for the CLASS. This image is used when building a legend (or requesting a legend icon via MapScript or the CGI application). LABEL Signals the start of a LABEL object. MAXSCALEDENOM [double] Minimum scale at which this CLASS is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MAXSCALE parameter. See Also: Map Scale MAXSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is MAXSCALEDENOM instead. The deprecated MAXSCALE is the minimum scale at which this class is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. MAXSIZE [integer] Maximum size in pixels to draw a symbol. Default is 50. See LAYER SYMBOLSCALEDENOM. MINSCALEDENOM [double] Maximum scale at which this CLASS is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MINSCALE parameter. See Also: Map Scale MINSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is MINSCALEDENOM instead. The deprecated MINSCALE is the maximum scale at which this CLASS is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. MINSIZE [integer] Minimum size in pixels to draw a symbol. Default is 0. See LAYER SYMBOLSCALEDENOM. NAME [string] Name to use in legends for this class. If not set class wont show up in legend. OUTLINECOLOR [r] [g] [b] Color to use for outlining polygons and certain marker symbols. Line symbols do not support outline colors. SIZE [integer] Height, in pixels, of the symbol/pattern to be used. Only useful with scalable symbols. For vector (and ellipse) SYMBOL TYPEs the default size is based on the range of Y values in the POINTS dening the symbol. For symbols of type pixmap, the default is the vertical size of the image. Default size is 1 for TTF symbols. STATUS [on|off] Sets the current display status of the class. Default turns the class on. STYLE Signals the start of a STYLE object. A class can contain multiple styles. Multiple styles can be used create complex symbols (by overlay/stacking). See Cartographical Symbol Construction with MapServer for more information on advanced symbol construction.
114
Chapter 5. Maple
SYMBOL [integer|string|lename] The symbol name or number to use for all features if attribute tables are not used. The number is the index of the symbol in the symbol le, starting at 1, the 5th symbol in the le is therefore symbol number 5. You can also give your symbols names using the NAME parameter in the symbol denition le, and use those to refer to them. Default is 0, which results in a single pixel, single width line, or solid polygon ll, depending on layer type. You can also specify a gif or png lename. The path is relative to the location of the maple. See Cartographical Symbol Construction with MapServer for more information on advanced symbol construction. TEMPLATE [lename] Template le or URL to use in presenting query results to the user. See Templating for more info. TEXT [string|expression] Text to label features in this class with. This overrides values obtained from the LAYER LABELITEM. The string can contain references to feature attributes. This allows you to concatenate multiple attributes into a single label. You can for example concatenate the attributes FIRSTNAME and LASTNAME like this:
TEXT [FIRSTNAME] [LASTNAME]
More advanced Expressions can be used to specify the labels. Since version 6.0, there are functions available for formatting numbers:
TEXT ("Area is: " + tostring([area],"%.2f"))
VALIDATION Signals the start of a VALIDATION block. As of MapServer 5.4.0, VALIDATION blocks are the preferred mechanism for specifying validation patterns for CGI param runtime substitutions. See Run-time Substitution. Although the recommended way of making stacked symbols to achieve interesting effects is to use STYLEs, you can also stack 2 symbols without using STYLEs. You dene the second symbol, which effectively sits on top of the rst symbol (as dened above). The following parameters allow you to dene the second symbol, and they are equivalent to their non-overlay counterparts: OVERLAYBACKGROUNDCOLOR OVERLAYCOLOR OVERLAYOUTLINECOLOR OVERLAYSIZE OVERLAYMINSIZE OVERLAYMAXSIZE OVERLAYSYMBOL
5.3 CLUSTER
5.3. CLUSTER
115
Table of Contents CLUSTER Description Supported Layer Types Maple Parameters Maple Snippet Feature attributes PHP MapScript Usage Example: Clustering Railway Stations
5.3.1 Description
Since version 6.0, MapServer has the ability to combine multiple features from a point layer into single (aggregated) features based on their relative positions. Only POINT layers are supported. This feature was added through MS RFC 69: Support for clustering of features in point layers.
5.3.2 Supported Layer Types

POINT
5.3.3 Maple Parameters

MAXDISTANCE [double] Species the distance of the search region (rectangle or ellipse) in pixel positions. REGION [string] Denes the search region around a feature in which the neighbouring features are negotiated. Can be rectangle or ellipse. BUFFER [double] Denes a buffer region around the map extent in pixels. Default is 0. Using a buffer allows that the neighbouring shapes around the map are also considered during the cluster creation. GROUP [string] This expression evaluates to a string and only the features that have the same group value are negotiated. This parameter can be omitted. The evaluated group value is available in the Cluster:Group feature attribute. FILTER [string] We can dene the FILTER expression lter some of the features from the nal output. This expression evaluates to a boolean value and if this value is false the corresponding shape is ltered out. This expression is evaluated after the the feature negotiation is completed, therefore the Cluster:FeatureCount parameter can also be used, which provides the option to lter the shapes having too many or to few neighbors within the search region.
5.3.4 Maple Snippet

LAYER NAME "my-cluster" TYPE POINT ... CLUSTER MAXDISTANCE 20 # in pixels REGION ellipse # can be rectangle or ellipse GROUP (expression) # we can define an expression to create separate groups for each value FILTER (expression) # we can define a logical expression to specify the grouping condition
116
Chapter 5. Maple
END LABELITEM "Cluster:FeatureCount" CLASS ... LABEL ... END END ... END
5.3.5 Feature attributes

The clustered layer itself provides the following aggregated attributes: 1. Cluster:FeatureCount - count of the features in the clustered shape 2. Cluster:Group - The group value of the cluster (to which the group expression is evaluated) These attributes (in addition to the attributes provided by the original data source) can be used to congure the labels of the features and can also be used in expressions. The ITEMS processing option can be used to specify a subset of the attributes from the original layer in the query operations according to the users preference. We can use simple aggregate functions (Min, Max, Sum, Count) to specify how the clustered attribute should be calculated from the original attributes. The aggregate function should be specied as a prex separated by : in the attibute denition, like: [Max:itemname]. If we dont specify aggregate functions for the source layer attributes, then the actual value of the cluster attribute will be non-deterministic if the cluster contains multiple shapes with different values. The Count aggregate function in fact provides the same value as Cluster:FeatureCount.
5.3.6 PHP MapScript Usage

The CLUSTER object is exposed through PHP MapScript. An example follows:
$map = ms_newMapobj("/var/www/vhosts/mysite/httpdocs/test.map"); $layer1=$map->getLayerByName("test1"); $layer1->cluster;
5.3.7 Example: Clustering Railway Stations

The following example uses a point datasource, in this case in KML format, to display clusters of railway stations. Two classes are used: one to style and label the cluster, and one to style and label the single railway station. Note: Since we cant declare 2 labelitems, for the single railway class we use the TEXT parameter to label the station. Maple Layer
#################### # Lightrail Stations #################### SYMBOL NAME "lightrail" TYPE PIXMAP IMAGE "../etc/lightrail.png" END
5.3. CLUSTER
117
LAYER NAME "lightrail" GROUP "default" STATUS DEFAULT TYPE POINT CONNECTIONTYPE OGR CONNECTION "lightrail-stations.kml" DATA "lightrail-stations" LABELITEM "Cluster:FeatureCount" CLASSITEM "Cluster:FeatureCount" ########################### # Define the cluster object ########################### CLUSTER MAXDISTANCE 50 REGION "ellipse" END ################################ # Class1: For the cluster symbol ################################ CLASS NAME "Clustered Lightrail Stations" EXPRESSION ("[Cluster:FeatureCount]" != "1") STYLE SIZE 30 SYMBOL "citycircle" COLOR 255 0 0 END LABEL FONT s c b TYPE TRUETYPE SIZE 8 COLOR 255 255 255 ALIGN CENTER PRIORITY 10 BUFFER 1 PARTIALS TRUE POSITION cc END END ################################ # Class2: For the single station ################################ CLASS NAME "Lightrail Stations" EXPRESSION "1" STYLE SIZE 30 SYMBOL "lightrail" END TEXT "[Name]" LABEL FONT s c b TYPE TRUETYPE SIZE 8 COLOR 0 0 0 OUTLINECOLOR 255 255 255 ALIGN CENTER
118
Chapter 5. Maple
PRIORITY 9 BUFFER 1 PARTIALS FALSE POSITION ur END END # the following is used for a query TOLERANCE 50 UNITS PIXELS HEADER "../htdocs/templates/cluster_header.html" FOOTER "../htdocs/templates/cluster_footer.html" TEMPLATE "../htdocs/templates/cluster_query.html" END
Map Image
5.4 Display of International Characters in MapServer

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Revision $Revision: 12506 $ Date $Date: 2011-08-29 14:26:49 +0200 (Mon, 29 Aug 2011) $
5.4. Display of International Characters in MapServer
119
Table of Contents Display of International Characters in MapServer Credit Related Links Requirements How to Enable in Your Maple * Step 1: Verify ICONV Support and MapServer Version * Step 2: Verify That Your Files Encoding is Supported by ICONV * Step 3: Add ENCODING Parameter to your LABEL Object * Step 4: Test with the shp2img utility Example Using PHP MapScript Notes
5.4.1 Credit
The following functionality was added to MapServer 4.4.0 as a part of a project sponsored by the Informationtechnology Promotion Agency (IPA), in Japan. Project members included: Venkatesh Raghavan, Masumoto Shinji, Nonogaki Susumu, Nemoto Tatsuya, Hirai Naoki (Osaka City University, Japan), Mario Basa, Hagiwara Akira, Niwa Makoto, Mori Toru (Orkney Inc., Japan), and Hattori Norihiro (E-Solution Service, Inc., Japan).
5.4.2 Related Links

MapServer ticket:858
5.4.3 Requirements
MapServer >= 4.4.0 MapServer compiled with the libiconv library
5.4.4 How to Enable in Your Maple

The maple LABEL objects parameter named ENCODING can be used to convert strings from its original encoding system into one that can be understood by the True Type Fonts. The ENCODING parameter accepts the encoding name as its parameter. Mapserver uses GNUs libiconv library ( http://www.gnu.org/software/libiconv/ ) to deal with encodings. The libiconv web site has a list of supported encodings. One can also use the iconv -l command on a system with libiconv installed to get the complete list of supported encodings on that specic system. So, theoretically, every string with an encoding system supported by libiconv can be displayed as labels in MapServer as long as it has a matching font-set. Step 1: Verify ICONV Support and MapServer Version Execute mapserv -v at the commandline, and verify that your MapServer version >= 4.4.0 and it includes SUPPORTS=ICONV, such as:
> mapserv -v MapServer version 5.6.5 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ
120
Chapter 5. Maple
SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=FRIBIDI SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS SUPPORTS=GEOS SUPPORTS=RGBA_PNG SUPPORTS=TILECACHE INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
Step 2: Verify That Your Files Encoding is Supported by ICONV Since MapServer uses the libiconv library to handle encodings, you can check the list of supported encodings here: http://www.gnu.org/software/libiconv/ Unix users can also use the iconv -l command on a system with libiconv installed to get the complete list of supported encodings on that specic system. Step 3: Add ENCODING Parameter to your LABEL Object Now you can simply add the ENCODING parameter to your maple LAYER object, such as:
MAP ... LAYER ... CLASS ... LABEL ... ENCODING "SHIFT_JIS" END END END END
One of the benets of having an ENCODING parameter within the LABEL object is that different LAYERS with different encoding systems can be combined together and display labels within a single map. For example, labels from a Layer using Shapele as it source which contains attributes in SHIFT-JIS can be combined with a Layer from a PostGIS database server with EUC-JP attributes. A sample Maple can look like this:
LAYER NAME "chimei" DATA c h i m e i STATUS DEFAULT TYPE POINT LABELITEM "NAMAE" CLASS NAME "CHIMEI" STYLE COLOR 10 100 100 END LABEL TYPE TRUETYPE FONT k o c h i - g o t h i c COLOR 220 20 20 SIZE 10 POSITION CL PARTIALS FALSE
5.4. Display of International Characters in MapServer
121
BUFFER 0 ENCODING S H I F T _ J I S END END END LAYER NAME "chimeipg" CONNECTION "user=username password=password dbname=gis host=localhost port=5432" CONNECTIONTYPE postgis DATA "the_geom from chimei" STATUS DEFAULT TYPE POINT LABELITEM "NAMAE" CLASS NAME "CHIMEI PG" STYLE COLOR 10 100 100 END LABEL TYPE TRUETYPE FONT k o c h i - m i n c h o COLOR 20 220 20 SIZE 10 POSITION CL PARTIALS FALSE BUFFER 0 ENCODING E UC- J P END END END
Step 4: Test with the shp2img utility see shp2img commandline utility
5.4.5 Example Using PHP MapScript

For PHP Mapscript, the Encoding parameter is included in the LabelObj Class, so that the encoding parameter of a layer can be modied such as:
// Loading the php_mapscript library dl("php_mapscript.so"); // Loading the map file $map = ms_newMapObj("example.map"); // get the desired layer $layer = $map->getLayerByName("chimei"); // get the layers class object $class = $layer->getClass(0); // get the class objects label object $clabel= $class->label;
122
Chapter 5. Maple
// get encoding parameter $encode_str = $clabel->encoding; print "Encoding = ".$encode_str."\n"; // set encoding parameter $clabel->set("encoding","UTF-8");
5.4.6 Notes
Note: During initial implementation, this functionality was tested using the different Japanese encoding systems: Shift-JIS, EUC-JP, UTF-8, as well as Thais TIS-620 encoding system. Examples of encodings for the Latin alphabet supported by libiconv are: ISO-8859-1 (Latin alphabet No. 1 - also known as LATIN-1 - western European languages), ISO-8859-2 (Latin alphabet No. 2 - also known as LATIN-2 - eastern European languages), CP1252 (Microsoft Windows Latin alphabet encoding - English and some other Western languages).
5.5 Expressions
Author Dirk Tilger Contact dirk at MIRIUP.DE Author Umberto Nicoletti Contact umberto.nicoletti at gmail.com Revision $Revision: 12611 $ Date $Date: 2011-09-30 13:44:12 -0700 (Fri, 30 Sep 2011) $ Last Updated 2011/06/30 Contents Expressions Introduction * String quotation * Quotes escaping in strings * Using attributes Expression Types * String comparison (equality) * Regular expression comparison MapServer expressions * Logical expressions * String expressions that return a logical value * Arithmetic expressions that return a logical value * Spatial expressions that return a logical value (GEOS) * String operations that return a string * Functions that return a string * String functions that return a number * Arithmetic operations and functions that return a number * Spatial functions that return a number (GEOS) * Spatial functions that return a shape (GEOS) * Temporal expressions
5.5. Expressions
123
5.5.1 Introduction
As of version 6.0, expressions are used in four places: In LAYER FILTER to specify the features of the dataset that are to be included in the layer. In CLASS EXPRESSION to specify to which features of the dataset the CLASS applies to. In CLASS TEXT to specify text for labeling features. In STYLE GEOMTRANSFORM. String quotation Stings can be quoted using single or double quotes:
This is a string "And this is also a string"
Quotes escaping in strings Note: Quotes escaping is not supported in MapServer versions lower than 5.0. Starting with MapServer 5.0, if your dataset contains double-quotes, you can use a C-like escape sequence:
"National \"hero\" statue"
To escape a single quote use the following sequence instead:

"National \hero\ statue"
Starting with Mapserver 6.0 you dont need to escape single quotes within double qouted strings and you dont need to escape double quotes within single quoted strings. In 6.0 you can also write the string as follows:
National "hero" statue ...
To escape a single quote use the following sequence instead:

"National hero statue"
Using attributes Attribute values can be referenced in the Map le and used in expressions. Attribute references are case sensitive and can be used in the following types of expressions: In LAYER FILTER In CLASS EXPRESSION In CLASS TEXT Referencing an attribute is done by enclosing the attribute name in square brackets, like this: [ATTRIBUTENAME]. Then, every occurrence of [ATTRIBUTENAME] will be replaced by the actual value of the attribute ATTRIBUTENAME. Example: The data set of our layer has the attribute BUILDING_NAME. We want the value of this attribute to appear inside a string. This can be accomplished as follows (single or double qoutes):
124
Chapter 5. Maple
The [BUILDING_NAME] building
For the building which has its BUILDING_NAME attribute set to Historical Museum, the resulting string is:
The Historical Museum building
For Raster Data layers special attributes have been dened that can be used for classication, for example: [PIXEL] ... will become the pixel value as number [RED], [GREEN], [BLUE] ... will become the color value for the red, green and blue component in the pixel value, respectively.
5.5.2 Expression Types

Expression are used to match attribute values with certain logical checks. There are three different types of expressions you can use with MapServer: String comparisons: A single attribute is compared with a string value. Regular expressions: A single attribute is matched with a regular expression. Logical MapServer expressions: One or more attributes are compared using logical expressions. String comparison (equality) String comparison means, as the name suggests, that attribute values are checked if they are equal to some value. String comparisons are the simplest form of MapServer expressions and the fastest option. To use a string comparison for ltering a LAYER, both FILTERITEM and FILTER must be set. FILTERITEM is set to the attribute name. FILTER is set to the value for comparison. The same rule applies to CLASSITEM in the LAYER object and EXPRESSION in the CLASS object. Example for a simple string comparison lter
FILTER "2005" FILTERITEM "year"
would match all records that have the attribute year set to 2005. The rendered map would appear as if the dataset would only contain those items that have the year set to 2005. Similarly, a classication for the items matched above would be done by setting the CLASSITEM in the LAYER and the EXPRESSION in the CLASS:
LAYER NAME "example" CLASSITEM "year" ... CLASS NAME "year-2005" EXPRESSION "2005" ... END END
For reasons explained later, the values for both CLASSITEM and FILTERITEM should start with neither a / nor a ( character.
5.5. Expressions
125
Regular expression comparison Regular expressions are a standard text pattern matching mechanism from the Unix world. The functionality of regular expression matching is provided by the operating system on UNIX systems and therefore slightly operating system dependent. However, their minimum set of features are those dened by the POSIX standard. The documentation of the particular regular expression library is usually in the regex manual page (man regex) on Unix systems. Regular expression with MapServer work similarly to string comparison, but allow more complex operation. They are slower than pure string comparisons, but might be still faster than logical expression. As for string comparison, when using a regular expressions, FILTERITEM (LAYER FILTER) or CLASSITEM (CLASS EXPRESSION) has to be dened if the items are not included in the LAYER FILTER or CLASS EXPRESSION. A regular expression typically consists of characters with special meanings and characters that are interpreted as they are. Alphanumeric characters (A-Z, a-z and 0-9) are taken as they are. Characters with special meanings are: . will match a single character. [ and ] are used for grouping. For example [A-Z] would match the characters A,B,C,...,X,Y,Z. {, }, and * are used to specify how often something should match. ^ matches the beginning, $ matches the end of the value. The backslash \ is used to take away the special meaning. For example \$ would match the dollar sign. Mapserver supports two regex operators: ~ case insensitive regular expression ~* case sensitive regular expression The following LAYER conguration would have all records rendered on the map that have hotel in the attribute named placename
LAYER NAME regexp-example FILTERITEM placename FILTER /hotel/ ... END
Note: For FILTER, the regular expression is case-sensitive, thus records having Hotel in them would not have matched. Example: Match records that have a value from 2000 to 2010 in the attribute year:
FILTERITEM "year" FILTER /^20[0-9][0-9]/
Example: Match all the records that are either purely numerical or empty
FILTER /^[0-9]*$/
Example: Match all the features where the name attribute ends with by, BY, By or bY (case insensitive matching):
EXPRESSION ([name] ~* by$)
Example: Match all the features where the rdname attribute starts with Main.
LAYER ... CLASSITEM rdname CLASS
126
Chapter 5. Maple
EXPRESSION /^Main.*$/
Note: If you experience frequently segmentation faults when working with MapServer and regular expressions, it might be that your current working environment is linked against more than one regular expression library. This can happen when MapServer is linked with components that bring their own copy, like the Apache httpd or PHP. In these cases the author has made best experiences with making all those components using the regular expression library of the operating system (i.e. the one in libc). That involved editing the build les of some of the components, however.
5.5.3 MapServer expressions

MapServer expressions are the most complex and depending how they are written can become quite slow. They can match any of the attributes and thus allow ltering and classication depending on more than one attribute. Besides pure logical operations there are also expressions that allow certain arithmetic, string and time operations. To be able to use a MapServer expression for a FILTER or EXPRESSION value, the expression has to nally become a logical value. Logical expressions Syntactically, a logical expression is everything encapsulated in round brackets. Logical expressions take logical values as their input and return logical values. A logical expression is either true or false. ( ( Expression1 ) AND ( Expression2 ) ) ( ( Expression1 ) && ( Expression2 ) ) returns true when both of the logical expressions (Expression1 and Expression2) are true. ( ( Expression1 ) OR ( Expression2 ) ) ( ( Expression1 ) || ( Expression2 ) ) returns true when at least one of the logical expressions (Expression1 or Expression2) is true. NOT ( Expression1 ) ! ( Expression1 ) returns true when Expression1 is false. String expressions that return a logical value Syntactically, a sting is something encapsulated in single or double quotes. ( String1 eq String2 ) ( String1 == String2 ) - deprecated since 6.0 ( String1 = String2 ) returns true when the strings are equal. Case sensitive. ( String1 =* String2 ) returns true when the strings are equal. Case insensitive. ( String1 != String2 ) ( String1 ne String2 ) returns true when the strings are not equal. 5.5. Expressions 127
( String1 < String2 ) ( String1 lt String2 ) returns true when String1 is lexicographically smaller than String2 ( String1 > String2 ) ( String1 gt String2 ) returns true when String1 is lexicographically larger than String2. ( String1 <= String2 ) ( String1 le String2 ) returns true when String1 is lexicographically smaller than or equal to String2 ( String1 >= String2 ) ( String1 ge String2 ) returns true when String1 is lexicographically larger than or equal to String2. ( String1 IN token1,token2,...,tokenN ) returns true when String1 is equal to one of the given tokens. Note: The separator for the tokens is the comma. That means that there can not be unnecessary white space in the list and that tokens that have commas in them cannot be compared. ( String1 ~ regexp ) returns true when String1 matches the regular expression regexp. This operation is identical to the regular expression matching described earlier. ( String1 ~* regexp ) returns true when String1 matches the regular expression regexp (case insensitive). This operation is identical to the regular expression matching described earlier. Arithmetic expressions that return a logical value The basic element for arithmetic operations is the number. Arithmetic operations that return numbers will be covered in the next section. ( n1 eq n2 ) ( n1 == n2 ) - deprecated since 6.0 ( n1 = n2 ) returns true when the numbers are equal. ( n1 != n2 ) ( n1 ne n2 ) returns true when the numbers are not equal. ( n1 < n2 ) ( n1 lt n2 ) returns true when n1 is smaller than n2.
128
Chapter 5. Maple
( n1 > n2 ) ( n1 gt n2 ) returns true when n1 is larger than n2. ( n1 <= n2 ) ( n1 le n2 ) returns true when n1 is smaller than or equal to n2. ( n1 >= n2 ) ( n1 ge n2 ) returns true when n1 is larger than or equal to n2. ( n1 IN number1,number2,...,numberN ) returns true when n1 is equal to one of the given numbers. Spatial expressions that return a logical value (GEOS) ( shape1 eq shape2 ) returns true if shape1 and shape2 are equal ( shape1 intersects shape2 ) returns true if shape1 and shape2 intersect New in version 6.0. ( shape1 disjoint shape2 ) returns true if shape1 and shape2 are disjoint New in version 6.0. ( shape1 touches shape2 ) returns true if shape1 and shape2 touch New in version 6.0. ( shape1 overlaps shape2 ) returns true if shape1 and shape2 overlap New in version 6.0. ( shape1 crosses shape2 ) returns true if shape1 and shape2 cross New in version 6.0. ( shape1 within shape2 ) returns true if shape1 is within shape2 New in version 6.0. ( shape1 contains shape2 ) returns true if shape1 contains shape2 New in version 6.0. ( shape1 dwithin shape2 ) returns true if the distance between shape1 and shape2 is equal to 0 New in version 6.0. ( shape1 beyond shape2 ) returns true if the distance between shape1 and shape2 is greater than 0 New in version 6.0.
5.5. Expressions
129
String operations that return a string String1 + String2 returns String1String2, that is, the two strings concatenated to each other. Functions that return a string tostring ( n1, Format1 ) uses Format1 to format the number n1 (C style formatting - sprintf). New in version 6.0. commify ( String1 ) adds thousands separators (commas) to a long number to make it more readable New in version 6.0. String functions that return a number length ( String1 ) returns the number of characters of String1 Arithmetic operations and functions that return a number round ( n1 , n2 ) returns n1 rounded to a multiple of n2: n2 * round(n1/n2) New in version 6.0. n1 + n2 returns the sum of n1 and n2 n1 - n2 returns n2 subtracted from n1 n1 * n2 returns n1 multiplicated with n2 n1 / n2> returns n1 divided by n2 -n1 returns n1 negated n1 ^ n2 returns n1 to the power of n2 Note: When the numerical operations above are used like logical operations, the following rule applies: values equal to zero will be taken as false and everything else will be true. That means the expression
( 6 + 5 )
would return true, but

( 5 - 5 )
would return false.
130
Chapter 5. Maple
Spatial functions that return a number (GEOS) area ( shape1 ) returns the area of shape1 New in version 6.0. Spatial functions that return a shape (GEOS) fromtext ( String1 ) returns the shape corresponding to String1 (WKT - well known text)
fromText(POINT(500000 5000000))
New in version 6.0. buffer (shape1 , n1 ) returns the shape that results when shape1 is buffered with bufferdistance n1 New in version 6.0. difference ( shape1 , shape2 ) returns the shape that results when the common area of shape1 and shape2 is subtracted from shape1 New in version 6.0. Temporal expressions MapServer uses an internal time type to do comparison. To convert a string into this time type it will check the list below from the top and down to check if the specied time matches, and if so, it will do the conversion. The following are integer values: YYYY - year, MM - month, DD - date, hh - hours, mm - minutes, ss - seconds. The following are character elements of the format: - (dash) - date separator, : (colon) - time separator, T - marks the start of the time component (ISO 8601), space - marks the end of the date and start of the time component, Z - zulu time (0 UTC offset). YYYY-MM-DDThh:mm:ssZ YYYY-MM-DDThh:mm:ss YYYY-MM-DD hh:mm:ss YYYY-MM-DDThh:mm YYYY-MM-DD hh:mm YYYY-MM-DDThh YYYY-MM-DD hh YYYY-MM-DD YYYY-MM YYYY Thh:mm:ssZ Thh:mm:ss For temporal values obtained this way, the following operations are supported:
5.5. Expressions
131
( t1 eq t2 ) ( t1 == t2 ) - deprecated since 6.0 ( t1 = t2 ) returns true when the times are equal. ( t1 != t2 ) ( t1 ne t2 ) returns true when the times are not equal. ( t1 < t2 ) ( t1 lt t2 ) returns true when t1 is earlier than t2 ( t1 > t2 ) ( t1 gt t2 ) returns true when t1 is later than t2. ( t1 <= t2 ) ( t1 le t2 ) returns true when t1 is earlier than or equal to t2 ( t1 >= t2 ) ( t1 ge t2 ) returns true when t1 is later than or equal to t2.
5.6 FEATURE
POINTS A set of xy pairs terminated with an END, for example:
POINTS 1 1 50 50 1 50 1 1 END
Note: POLYGON/POLYLINE layers POINTS must start and end with the same point (i.e. close the feature). ITEMS Comma separated list of the feature attributes:
ITEMS "value1;value2;value3"
Note: Specifying the same number of items is recommended for each features of the same layer. The item names should be specied as a PROCESSING option of the layer. TEXT [string] String to use for labeling this feature. WKT [string] A geometry expressed in OpenGIS Well Known Text geometry format. This feature is only supported if MapServer is built with OGR or GEOS support.
WKT "POLYGON((500 500, 3500 500, 3500 2500, 500 2500, 500 500))" WKT "POINT(2000 2500)"
Note: Inline features should be dened as their own layers in the maple. If another CONNECTIONTYPE is specied in the same layer, MapServer will always use the inline features to draw the layer and ignore the other CONNECTIONTYPEs.
132
Chapter 5. Maple
5.7 FONTSET
Author Kari Guerts Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Revision $Revision: 12501 $ Date $Date: 2011-08-28 02:51:27 -0700 (Sun, 28 Aug 2011) $ Last Updated 2008/10/08 Contents FONTSET Format of the fontset le FONTSET is a MAP parameter. The syntax is:
FONTSET [filename]
Where lename gives the location of the fontset le of the system. The location of the system fontset le could for instance be /usr/share/fonts/truetype/font.list (Debian). The location can be specied using a relative or absolute path.
5.7.1 Format of the fontset le

The format of the fontset le is very simple. Each line contains 2 items: An alias and the name/path of the font separated by white space. The alias is simply the name you refer to the font as in your Maple (eg. times-bold). The name is the actual name of the TrueType le. If not full path then it is interpreted as relative to the location of the fontset. Heres the fontset I use (the font.list le and all .ttf les are stored in the same sub-directory). Note: Aliases are case sensitive. Excellent reference information about the TrueType format and online font resources is available from the FreeType.
arial arial-bold arial-italic arial-bold-italic arial_black comic_sans comic_sans-bold courier courier-bold courier-italic courier-bold-italic georgia georgia-bold georgia-italic georgia-bold-italic impact monotype.com recreation_symbols times times-bold times-italic arial.ttf arialbd.ttf ariali.ttf arialbi.ttf ariblk.ttf comic.ttf comicbd.ttf cour.ttf courbd.ttf couri.ttf courbi.ttf georgia.ttf georgiab.ttf georgiai.ttf georgiaz.ttf impact.ttf monotype.ttf recreate.ttf times.ttf timesbd.ttf timesi.ttf
5.7. FONTSET
133
times-bold-italic trebuchet_ms trebuchet_ms-bold trebuchet_ms-italic trebuchet_ms-bold-italic verdana verdana-bold verdana-italic verdana-bold-italic
timesbi.ttf trebuc.ttf trebucbd.ttf trebucit.ttf trebucbi.ttf verdana.ttf verdanab.ttf verdanai.ttf verdanaz.ttf
5.8 GRID
LABELFORMAT [DD|DDMM|DDMMSS|C format string] Format of the label. DD for degrees, DDMM for degrees minutes, and DDMMSS for degrees, minutes, seconds. A C-style formatting string is also allowed, such as %g to show decimal degrees with a degree symbol. The default is decimal display of whatever SRS youre rendering the GRID with. MINARCS [double] The minimum number of arcs to draw. Increase this parameter to get more lines. Optional. MAXARCS [double] The maximum number of arcs to draw. Decrease this parameter to get fewer lines. Optional. MININTERVAL [double] The minimum number of intervals to try to use. The distance between the grid lines, in the units of the grids coordinate system. Optional. MAXINTERVAL [double] The maximum number of intervals to try to use. The distance between the grid lines, in the units of the grids coordinate system. Optional. MINSUBDIVIDE [double] The minimum number of segments to use when rendering an arc. If the lines should be very curved, use this to smooth the lines by adding more segments. Optional. MAXSUBDIVIDE [double] The maximum number of segments to use when rendering an arc. If the graticule should be very straight, use this to minimize the number of points for faster rendering. Optional, default 256. The following is an example of a GRID object in use:
LAYER NAME "grid" METADATA "DESCRIPTION" "Grid" END TYPE LINE STATUS ON CLASS NAME "Graticule" COLOR 0 0 0 LABEL COLOR 255 0 0 FONT "fritqat" TYPE truetype SIZE 8 POSITION AUTO PARTIALS FALSE BUFFER 5 OUTLINECOLOR 255 255 255 END END PROJECTION "init=epsg:4326"
134
Chapter 5. Maple
END GRID LABELFORMAT "DDMM" # LABELFORMAT %g # dec degrees with symbol MAXARCS 10 MAXINTERVAL 10 MAXSUBDIVIDE 2 # LABELFORMAT %7.0f m # nice if a projected SRS used # MININTERVAL 20000 # MAXSUBDIVIDE 2 END END # Layer
5.9 INCLUDE
When this directive is encountered parsing switches to the included le immediately. As a result the included le can be comprised of any valid maple syntax. For example:
INCLUDE myLayer.map
Performance does not seem to be seriously impacted with limited use, however in high performance instances you may want to use includes in a pre-processing step to build a production maple. The C pre-processor can also be used (albeit with a different syntax) and is far more powerful.
5.9.1 Notes
Supported in versions 4.10 and higher. The name of the le to be included MUST be quoted (single or double quotes). Includes may be nested, up to 5 deep. File location can be given as a full path to the le, or (in MapServer >= 4.10.1) as a path relative to the maple. Debugging can be problematic because: 1. the le an error occurs in does not get output to the user 2. the line number counter is not reset for each le. Here is one possible error that is thrown when the include le cannot be found:
msyylex(): Unable to access file. Error opening included file "parks_include.map"
5.9.2 Example
MAP NAME "include_mapfile" EXTENT 0 0 500 500 SIZE 250 250 INCLUDE "test_include_symbols.map" INCLUDE "test_include_layer.map" END
where test_include_symbols.map contains:
5.9. INCLUDE
135
SYMBOL NAME square TYPE VECTOR FILLED TRUE POINTS 0 0 0 1 1 1 1 0 0 0 END END
and test_include_layer.map contains:

LAYER TYPE POINT STATUS DEFAULT FEATURE POINTS 10 10 40 20 300 300 400 10 10 400 END END CLASS NAME Church COLOR 0 0 0 SYMBOL square SIZE 7 STYLE SYMBOL "square" SIZE 5 COLOR 255 255 255 END STYLE SYMBOL "square" SIZE 3 COLOR 0 0 255 END END END
5.10 JOIN
5.10.1 Description
Joins are dened within a LAYER object. It is important to understand that JOINs are ONLY available once a query has been processed. You cannot use joins to affect the look of a map. The primary purpose is to enable lookup tables for coded data (e.g. 1 => Forest) but there are other possible uses.
5.10.2 Supported Formats

DBF/XBase les CSV (comma delimited text le) PostgreSQL tables MySQL tables
136
Chapter 5. Maple
5.10.3 Maple Parameters:

CONNECTION [string] Parameters required for the join tables database connection (not required for DBF or CSV joins). The following is an example connection for PostgreSQL:
CONNECTION "host=127.0.0.1 port=5432 user=postgres password=postgres dbname=somename" CONNECTIONTYPE POSTGRESQL
CONNECTIONTYPE [csv|mysql|postgresql] Type of connection (not required for DBF joins). For PostgreSQL use postgresql, for CSV use csv, for MySQL use mysql. FOOTER [lename] Template to use after a layers set of results have been sent. In other words, this header HTML will be displayed after the contents of the TEMPLATE HTML. FROM [item] Join item in the dataset. This is case sensitive. HEADER [lename] Template to use before a layers set of results have been sent. In other words, this header HTML will be displayed before the contents of the TEMPLATE HTML. NAME [string] Unique name for this join. Required. TABLE [lename|tablename] For le-based joins this is the name of XBase or comma delimited le (relative to the location of the maple) to join TO. For PostgreSQL support this is the name of the PostgreSQL table to join TO. TEMPLATE [lename] Template to use with one-to-many joins. The template is processed once for each record and can only contain substitutions for items in the joined table. Refer to the column in the joined table in your template like [joinname_columnname], where joinname is the NAME specied for the JOIN object. TO [item] Join item in the table to be joined. This is case sensitive. TYPE [ONE-TO-ONE|ONE-TO-MANY] The type of join. Default is one-to-one.
5.10.4 Example 1: Join from Shape dataset to DBF le

Maple Layer
LAYER NAME "prov_bound" TYPE POLYGON STATUS DEFAULT DATA "prov.shp" CLASS NAME "Province" STYLE OUTLINECOLOR 120 120 120 COLOR 255 255 0 END END TEMPLATE "../htdocs/cgi-query-templates/prov.html" HEADER "../htdocs/cgi-query-templates/prov-header.html" FOOTER "../htdocs/cgi-query-templates/footer.html" JOIN NAME "test" TABLE "../data/lookup.dbf" FROM "ID" TO "IDENT" TYPE ONE-TO-ONE
5.10. JOIN
137
END END # layer
Ogrinfo
>ogrinfo lookup.dbf lookup -summary INFO: Open of lookup.dbf using driver ESRI Shapefile successful. Layer name: lookup Geometry: None Feature Count: 12 Layer SRS WKT: (unknown) IDENT: Integer (2.0) VAL: Integer (2.0) >ogrinfo prov.shp prov -summary INFO: Open of prov.shp using driver ESRI Shapefile successful. Layer name: prov Geometry: Polygon Feature Count: 12 Extent: (-2340603.750000, -719746.062500) - (3009430.500000, 3836605.250000) Layer SRS WKT: (unknown) NAME: String (30.0) ID: Integer (2.0)
Template
<tr bgcolor="#EFEFEF"> <td align="left">[NAME]</td> <td align="left">[test_VAL]</td> </tr>
5.10.5 Example 2: Join from Shape dataset to PostgreSQL table

Maple Layer
LAYER NAME "prov_bound" TYPE POLYGON STATUS DEFAULT DATA "prov.shp" CLASS NAME "Province" STYLE OUTLINECOLOR 120 120 120 COLOR 255 255 0 END END
138
Chapter 5. Maple
TOLERANCE 20 TEMPLATE "../htdocs/cgi-query-templates/prov.html" HEADER "../htdocs/cgi-query-templates/prov-header.html" FOOTER "../htdocs/cgi-query-templates/footer.html" JOIN NAME "test" CONNECTION "host=127.0.0.1 port=5432 user=postgres password=postgres dbname=join" CONNECTIONTYPE postgresql TABLE "lookup" FROM "ID" TO "ident" TYPE ONE-TO-ONE END END # layer
Ogrinfo
>ogrinfo -ro PG:"host=127.0.0.1 port=5432 user=postgres password=postgre dbname=join" lookup -summary INFO: Open of PG:host=127.0.0.1 port=5432 user=postgres password=postgres dbname=join using driver PostgreSQL successful. Layer name: lookup Geometry: Unknown (any) Feature Count: 12 Layer SRS WKT: (unknown) ident: Integer (0.0) val: Integer (0.0)
Template
<tr bgcolor="#EFEFEF"> <td align="left">[NAME]</td> <td align="left">[test_val]</td> </tr>
5.10.6 Example 3: Join from Shape dataset to CSV le

Maple Layer
LAYER NAME "prov_bound" TYPE POLYGON STATUS DEFAULT DATA "prov.shp" CLASS NAME "Province" STYLE OUTLINECOLOR 120 120 120 COLOR 255 255 0 END
5.10. JOIN
139
END TOLERANCE 20 TEMPLATE "../htdocs/cgi-query-templates/prov.html" HEADER "../htdocs/cgi-query-templates/prov-header.html" FOOTER "../htdocs/cgi-query-templates/footer.html" JOIN NAME "test" CONNECTIONTYPE CSV TABLE "../data/lookup.csv" FROM "ID" TO "IDENT" TYPE ONE-TO-ONE END END # layer
CSV File Structure

"IDENT","VAL" 1,12 2,11 3,10 4,9 5,8 6,7 7,6 8,5 9,4 10,3 11,2 12,1
Note: The CSV driver currently doesnt read column names from the rst row. It just uses indexes (1, 2, ... n) to reference the columns. Its ok to leave column names as the rst row since they likely wont match anything but they arent used. Typically youd see something like TO 1 in the JOIN block. Then in the template youd use [name_1], [name_2], etc... Ogrinfo
>ogrinfo lookup.csv lookup -summary INFO: Open of lookup.csv using driver CSV successful. Layer name: lookup Geometry: None Feature Count: 12 Layer SRS WKT: (unknown) IDENT: String (0.0) VAL: String (0.0)
Template
<tr bgcolor="#EFEFEF"> <td align="left">[NAME]</td>
140
Chapter 5. Maple
<td align="left">[test_VAL]</td> </tr>
5.10.7 Example 4: Join from Shape dataset to MySQL

Maple Layer
LAYER NAME "prov_bound" TYPE POLYGON STATUS DEFAULT DATA "prov.shp" CLASS NAME "Province" STYLE OUTLINECOLOR 120 120 120 COLOR 255 255 0 END # style END # class TOLERANCE 20 TEMPLATE "../htdocs/cgi-query-templates/prov.html" HEADER "../htdocs/cgi-query-templates/prov-header.html" FOOTER "../htdocs/cgi-query-templates/footer.html" JOIN NAME "mysql-join" CONNECTIONTYPE MYSQL CONNECTION server:user:password:database TABLE "mysql-tablename" FROM "ID" TO "mysql-column" TYPE ONE-TO-ONE END # join END # layer
5.11 LABEL
ALIGN [left|center|right] Species text alignment for multiline labels (see WRAP) Note that the alignment algorithm is far from precise, so dont expect fabulous results (especially for right alignment) if youre not using a xed width font. New in version 5.4. ANGLE [double|auto|follow|attribute] Angle, given in degrees, to draw the label. AUTO allows MapServer to compute the angle. Valid for LINE layers only. FOLLOW was introduced in version 4.10 and tells MapServer to compute a curved label for appropriate linear features (see MS RFC 11: Support for Curved Labels for specics). [Attribute] was introduced in version 5.0, to specify the item name in the attribute table to use for angle values. The hard brackets [] are required. For example, if your shapeles DBF has a eld named MYANGLE that holds angle values for each record, your LABEL object might contain:
LABEL COLOR 150 150 150
5.11. LABEL
141
OUTLINECOLOR 255 255 255 FONT "sans" TYPE truetype SIZE 6 ANGLE [ M Y ANGLE] POSITION AUTO PARTIALS FALSE END
The associated RFC document for this feature is MS RFC 19: Style & Label attribute binding. ANTIALIAS [true|false] Should text be antialiased? Note that this requires more available colors, decreases drawing performance, and results in slightly larger output images. Only useful for GD (gif) rendering. Default is false. Has no effect for the other renderers (where anti-aliasing can not be turned off). BACKGROUNDCOLOR [r] [g] [b] Color to draw a background rectangle (i.e. billboard). Off by default. Note: Removed in 6.0. Use a LABEL STYLE object with GEOMTRANSFORM labelpoly and COLOR. BACKGROUNDSHADOWCOLOR [r] [g] [b] Color to draw a background rectangle (i.e. billboard) shadow. Off by default. Note: Removed in 6.0. Use a LABEL STYLE object with GEOMTRANSFORM labelpoly, COLOR and OFFSET. BACKGROUNDSHADOWSIZE [x][y] How far should the background rectangle be offset? Default is 1. Note: Removed in 6.0. Use a LABEL STYLE object with GEOMTRANSFORM labelpoly, COLOR and OFFSET. BUFFER [integer] Padding, in pixels, around labels. Useful for maintaining spacing around text to enhance readability. Available only for cached labels. Default is 0. COLOR [r] [g] [b] | [attribute] Color to draw text with. [Attribute] was introduced in version 5.0, to specify the item name in the attribute table to use for color values. The hard brackets [] are required. For example, if your shapeles DBF has a eld named MYCOLOR that holds color values for each record, your LABEL object might contain:
LABEL COLOR [ M Y COLOR] OUTLINECOLOR 255 255 255 FONT "sans" TYPE truetype SIZE 6 POSITION AUTO PARTIALS FALSE END
The associated RFC document for this feature is MS RFC 19: Style & Label attribute binding. ENCODING [string] Supported encoding format to be used for labels. If the format is not supported, the label will not be drawn. Requires the iconv library (present on most systems). The library is always detected if present on the system, but if not the label will not be drawn. Required for displaying international characters in MapServer. More information can be found in the Label Encoding document. FONT [name|attribute] Font alias (as dened in the FONTSET) to use for labeling.
142
Chapter 5. Maple
[Attribute] was introduced in version 5.6 to specfy the font alias. FORCE [true|false] Forces labels for a particular class on, regardless of collisions. Available only for cached labels. Default is false. If FORCE is true and PARTIALS is false, FORCE takes precedence, and partial labels are drawn. MAXLENGTH [integer] This keyword interacts with the WRAP keyword so that line breaks only occur after the dened number of characters. Table 5.9: Interaction with WRAP keyword wrap = char no wrap maxlength = 0 always wrap at the WRAP character no processing maxlength > 0 newline at the rst WRAP character after MAXLENGTH characters skip label if it contains more than MAXLENGTH characters maxlength < 0 hard wrap (always break at exactly MAXLENGTH characters) hard wrap (always break at exactly MAXLENGTH characters)
The associated RFC document for this feature is MS RFC 40: Support Label Text Transformations. New in version 5.4. MAXOVERLAPANGLE [double] Angle threshold to use in ltering out ANGLE FOLLOW labels in which characters overlap (oating point value in degrees). This ltering will be enabled by default starting with MapServer 6.0. The default MAXOVERLAPANGLE value will be 22.5 degrees, which also matches the default in GeoServer. Users will be free to tune the value up or down depending on the type of data they are dealing with and their tolerance to bad overlap in labels. As per RFC 60, if MAXOVERLAPANGLE is set to 0, then we fall back on pre-6.0 behavior which was to use maxoverlapangle = 0.4*MS_PI (40% of 180 degrees = 72degree). The associated RFC document for this feature is MS RFC 60: Labeling enhancement: ability to skip ANGLE FOLLOW labels with too much character overlap. MAXSIZE [double] Maximum font size to use when scaling text (pixels). Default is 256. Starting from version 5.4, the value can also be a fractional value (and not only integer). See LAYER SYMBOLSCALEDENOM. MINDISTANCE [integer] Minimum distance between duplicate labels. Given in pixels. MINFEATURESIZE [integer|auto] Minimum size a feature must be to be labeled. Given in pixels. For line data the overall length of the displayed line is used, for polygons features the smallest dimension of the bounding box is used. Auto keyword tells MapServer to only label features that are larger than their corresponding label. Available for cached labels only. MINSIZE [double] Minimum font size to use when scaling text (pixels). Default is 4. Starting from version 5.4, the value can also be a fractional value (and not only integer). See LAYER SYMBOLSCALEDENOM. OFFSET [x][y] Offset values for labels, relative to the lower left hand corner of the label and the label point. Given in pixels. In the case of rotated text specify the values as if all labels are horizontal and any rotation will be compensated for. See LAYER SYMBOLSCALEDENOM. OUTLINECOLOR [r] [g] [b] | [attribute] Color to draw a one pixel outline around the characters in the text. [attribute] was introduced in version 5.0, to specify the item name in the attribute table to use for color values. The hard brackets [] are required. For example, if your shapeles DBF has a eld named MYOUTCOLOR that holds color values for each record, your LABEL object might contain:
LABEL COLOR 150 150 150 OUTLINECOLOR [ M Y O U T COLOR] FONT "sans"
5.11. LABEL
143
TYPE truetype SIZE 6 POSITION AUTO PARTIALS FALSE END
The associated RFC document for this feature is MS RFC 19: Style & Label attribute binding. OUTLINEWIDTH [integer] Width of the outline if OUTLINECOLOR has been set. Defaults to 1. Currently only the AGG renderer supports values greater than 1, and renders these as a halo effect: recommended values are 3 or 5. PARTIALS [true|false] Can text run off the edge of the map? Default is true. If FORCE is true and PARTIALS is false, FORCE takes precedence, and partial labels are drawn. POSITION [ul|uc|ur|cl|cc|cr|ll|lc|lr|auto] Position of the label relative to the labeling point (layers only). First letter is Y position, second letter is X position. Auto tells MapServer to calculate a label position that will not interfere with other labels. With points, MapServer selects from the 8 outer positions (i.e. excluding cc). With polygons, MapServer selects from cc (added in MapServer 5.4), uc, lc, cl and cr as possible positions. With lines, it only uses lc or uc, until it nds a position that doesnt collide with labels that have already been drawn. If all positions cause a conict, then the label is not drawn (Unless the labels FORCE a parameter is set to true). Auto placement is only available with cached labels. PRIORITY [integer]|[item_name]|[attribute] The priority parameter takes an integer value between 1 (lowest) and 10 (highest). The default value is 1. It is also possible to bind the priority to an attribute (item_name) using square brackets around the [item_name]. e.g. PRIORITY [someattribute] Labels are stored in the label cache and rendered in order of priority, with the highest priority levels rendered rst. Specifying an out of range PRIORITY value inside a map le will result in a parsing error. An out of range value set via MapScript or coming from a shape attribute will be clamped to the min/max values at rendering time. There is no expected impact on performance for using label priorities. [Attribute] was introduced in version 5.6. New in version 5.0. REPEATDISTANCE [integer] The label will be repeated on every line of a multiline shape and will be repeated multiple times along a given line at an interval of REPEATDISTANCE pixels. The associated RFC document for this feature is MS RFC 57: Labeling enhancements: ability to repeat labels along a line/multiline. New in version 5.6. SHADOWCOLOR [r] [g] [b] Color of drop shadow. A label with the same text will be rendered in this color before the main label is drawn, resulting in a shadow effect on the the label characters. The offset of the renderered shadow is set with SHADOWSIZE. SHADOWSIZE [x][y]|[attribute][attribute]|[x][attribute]|[attribute][y] Shadow offset in pixels, see SHADOWCOLOR. [Attribute] was introduced in version 6.0, and can be used like:
SHADOWSIZE 2 2 SHADOWSIZE [ s h a d o w s i z e X ] 2 SHADOWSIZE 2 [ s h a d o w s i z e Y ] SHADOWSIZE [shadowsize] [shadowsize]
SIZE [double]|[tiny|small|medium|large|giant]|[attribute] Text size. Use a number to give the size in pixels of your TrueType font based label, or any of the other 5 listed keywords for bitmap fonts. When scaling is in effect (SYMBOLSCALEDENOM is specied for the LAYER), SIZE gives the size of the font to be used at the map scale 1:SYMBOLSCALEDENOM.
144
Chapter 5. Maple
Starting from version 5.4, the value can also be a fractional value (and not only integer). [Attribute] was introduced in version 5.0, to specify the item name in the attribute table to use for size values. The hard brackets [] are required. For example, if your shapeles DBF has a eld named MYSIZE that holds size values for each record, your LABEL object might contain:
LABEL COLOR 150 150 150 OUTLINECOLOR 255 255 255 FONT "sans" TYPE truetype SIZE [ M Y SIZE] POSITION AUTO PARTIALS FALSE END
The associated RFC document for this feature is MS RFC 19: Style & Label attribute binding. STYLE The start of a STYLE object. Label specic mechanisms of the STYLE object are the GEOMTRANSFORM options: GEOMTRANSFORM [labelpnt|labelpoly] Creates a geometry that can be used for styling the label. labelpnt draws a marker on the geographic position the label is attached to. This corresponds to the center of the label text only if the label is in position CC. labelpoly generates the bounding rectangle for the text, with 1 pixel of padding added in all directions. The resulting geometries can be styled using the mechanisms available in the STYLE object. Example - draw a red background rectangle for the labels (i.e. billboard) with a shadow in gray:
STYLE GEOMTRANSFORM labelpoly COLOR 153 153 153 OFFSET 3 2 END # STYLE STYLE GEOMTRANSFORM labelpoly COLOR 255 0 0 END # STYLE
New in version 6.0. TYPE [bitmap|truetype] Type of font to use. Generally bitmap fonts are faster to draw then TrueType fonts. However, TrueType fonts are scalable and available in a variety of faces. Be sure to set the FONT parameter if you select TrueType. Note: Bitmap fonts are only supported with the AGG and GD renderers. WRAP [character] Character that represents an end-of-line condition in label text, thus resulting in a multi-line label. Interacts with MAXLENGTH for conditional line wrapping after a given number of characters
5.12 LAYER
CLASS Signals the start of a CLASS object.
5.12. LAYER
145
Inside a layer, only a single class will be used for the rendering of a feature. Each feature is tested against each class in the order in which they are dened in the maple. The rst class that matches the its min/max scale constraints and its EXPRESSION check for the current feature will be used for rendering. CLASSGROUP [string] Specify the classs group that would be considered at rendering time. The CLASS objects GROUP parameter must be used in combination with CLASSGROUP. CLASSITEM [attribute] Item name in attribute table to use for class lookups. CLUSTER Signals the start of a CLUSTER object. The CLUSTER conguration option provides to combine multiple features from the layer into single (aggregated) features based on their relative positions. Supported only for POINT layers. See Also: MS RFC 69: Support for clustering of features in point layers CONNECTION [string] Database connection string to retrieve remote data. An SDE connection string consists of a hostname, instance name, database name, username and password separated by commas. A PostGIS connection string is basically a regular PostgreSQL connection string, it takes the form of user=nobody password=****** dbname=dbname host=localhost port=5432 An Oracle connection string: user/pass[@db] See Also: See Vector Data for specic connection information for various data sources. CONNECTIONTYPE [local|sde|ogr|postgis|oraclespatial|wms|wfs|plugin|union] Type of connection. Default is local. See additional documentation for any other type. See Also: See Vector Data for specic connection information for various data sources. See Union Layer for combining layers, added in MapServer 6.0 Note: mygis is another connectiontype, but it is deprecated; please see the MySQL section of the Vector Data document for connection details. DATA [lename]|[sde parameters][postgis table/column][oracle table/column] Full lename of the spatial data to process. No le extension is necessary for shapeles. Can be specied relative to the SHAPEPATH option from the Map Object. If this is an SDE layer, the parameter should include the name of the layer as well as the geometry column, i.e. mylayer,shape,myversion. If this is a PostGIS layer, the parameter should be in the form of <columnname> from <tablename>, where columnname is the name of the column containing the geometry objects and tablename is the name of the table from which the geometry data will be read. For Oracle, use shape FROM table or shape FROM (SELECT statement) or even more complex Oracle compliant queries! Note that there are important performance impacts when using spatial subqueries however. Try using MapServers FILTER whenever possible instead. You can also see the SQL submitted by forcing an error, for instance by submitting a DATA parameter you know wont work, using for example a bad column name. See Also: See Vector Data for specic connection information for various data sources.
146
Chapter 5. Maple
DEBUG [off|on|0|1|2|3|4|5] Enables debugging of a layer in the current map. Debugging with MapServer versions >= 5.0: Verbose output is generated and sent to the standard error output (STDERR) or the MapServer errorle if one is set using the MS_ERRORFILE environment variable. You can set the environment variable by using the CONFIG parameter at the MAP level of the maple, such as:
CONFIG "MS_ERRORFILE" "/ms4w/tmp/ms_error.txt"
You can also set the environment variable in Apache by adding the following to your httpd.conf:
SetEnv MS_ERRORFILE "/ms4w/tmp/ms_error.txt"
Once the environment variable is set, the DEBUG maple parameter can be used to control the level of debugging output. Here is a description of the possible DEBUG values: DEBUG O or OFF - only msSetError() calls are logged to MS_ERRORFILE. No msDebug() output at all. This is the default and corresponds to the original behavior of MS_ERRORFILE in MapServer 4.x DEBUG 1 or ON - includes all output from DEBUG 0 plus msDebug() warnings about common pitfalls, failed assertions or non-fatal error situations (e.g. missing or invalid values for some parameters, missing shapeles in tileindex, timeout error from remote WMS/WFS servers, etc.) DEBUG 2 - includes all output from DEBUG 1 plus notices and timing information useful for tuning maples and applications DEBUG 3 - all of DEBUG 2 plus some debug output useful in troubleshooting problems such as WMS connection URLs being called, database connection calls, etc. This is the recommended level for debugging maples. DEBUG 4 - DEBUG 3 plus even more details... DEBUG 5 - DEBUG 4 plus any msDebug() output that might be more useful to the developers than to the users. You can also set the debug level by using the MS_DEBUGLEVEL environment variable. The DEBUG setting can also be specied for the entire map, by setting the DEBUG parameter in the MAP object. For more details on this debugging mechanism, please see MS RFC 28: Redesign of LOG/DEBUG output mechanisms. Debugging with MapServer versions < 5: Verbose output is generated and sent to the standard error output (STDERR) or the MapServer logle if one is set using the LOG parameter in the WEB object. Apache users will see timing details for drawing in Apaches error_log le. Requires MapServer to be built with the DEBUG=MSDEBUG option (with-debug congure option). DUMP [true|false] Switch to allow MapServer to return data in GML format. Useful when used with WMS GetFeatureInfo operations. false by default. Deprecated since version 6.0: LAYER METADATA is used instead. See Also: WMS Server EXTENT [minx] [miny] [maxx] [maxy] The spatial extent of the data. In most cases you will not need to specify this, but it can be used to avoid the speed cost of having MapServer compute the extents of the data. An application can also possibly use this value to override the extents of the map. FEATURE Signals the start of a FEATURE object.
5.12. LAYER
147
FILTER [string] This parameter allows for data specic attribute ltering that is done at the same time spatial ltering is done, but before any CLASS expressions are evaluated. For OGR and shapeles the string is simply a mapserver regular expression. For spatial databases the string is a SQL WHERE clause that is valid with respect to the underlying database. For example: FILTER ([type]=road and [size]<2) FILTERITEM [attribute] Item to use with simple FILTER expressions. OGR and shapeles only. FOOTER [lename] Template to use after a layers set of results have been sent. Multiresult query modes only. GRID Signals the start of a GRID object. GROUP [name] Name of a group that this layer belongs to. The group name can then be reference as a regular layer name in the template les, allowing to do things like turning on and off a group of layers at once. If a group name is present in the LAYERS parameter of a CGI request, all the layers of the group are returned (the STATUS of the LAYERs have no effect). HEADER [lename] Template to use before a layers set of results have been sent. Multiresult query modes only. JOIN Signals the start of a JOIN object. LABELANGLEITEM [attribute] (As of MapServer 5.0 this parameter is no longer available. Please see the LABEL objects ANGLE parameter) For MapServer versions < 5.0, this is the item name in attribute table to use for class annotation angles. Values should be in degrees. Deprecated since version 5.0. LABELCACHE [on|off] Species whether labels should be drawn as the features for this layer are drawn, or whether they should be cached and drawn after all layers have been drawn. Default is on. Label overlap removal, auto placement etc... are only available when the label cache is active. LABELITEM [attribute] Item name in attribute table to use for class annotation (i.e. labeling). LABELMAXSCALEDENOM [double] Minimum scale at which this LAYER is labeled. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated LABELMAXSCALE parameter. See Also: Map Scale LABELMAXSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is LABELMAXSCALEDENOM instead. The deprecated LABELMAXSCALE is the minimum scale at which this LAYER is labeled. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. LABELMINSCALEDENOM [double] Maximum scale at which this LAYER is labeled. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated LABELMINSCALE parameter. See Also: Map Scale LABELMINSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is LABELMINSCALEDENOM instead. The deprecated LABELMINSCALE is the maximum scale at which this LAYER is labeled. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. LABELREQUIRES [expression] Sets context for labeling this layer, for example:
LABELREQUIRES "![orthoquads]"
148
Chapter 5. Maple
means that this layer would NOT be labeled if a layer named orthoquads is on. The expression consists of a boolean expression based on the status of other layers, each [layer name] substring is replaced by a 0 or a 1 depending on that layers STATUS and then evaluated as normal. Logical operators AND and OR can be used. LABELSIZEITEM [attribute] (As of MapServer 5.0 this parameter is no longer available. Please see the LABEL objects SIZE parameter) For MapServer versions < 5.0, this is the item name in attribute table to use for class annotation sizes. Values should be in pixels. Deprecated since version 5.0. MAXFEATURES [integer] Species the number of features that should be drawn for this layer in the CURRENT window. Has some interesting uses with annotation and with sorted data (i.e. lakes by area). MAXGEOWIDTH [double] Maximum width, in the maps geographic units, at which this LAYER is drawn. If MAXSCALEDENOM is also specied then MAXSCALEDENOM will be used instead. (added in MapServer 5.4.0) The width of a map in geographic units can be found by calculating the following from the extents:
[maxx] - [minx]
MAXSCALEDENOM [double] Minimum scale at which this LAYER is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MAXSCALE parameter. See Also: Map Scale MAXSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is MAXSCALEDENOM instead. The deprecated MAXSCALE is the minimum scale at which this LAYER is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. METADATA This keyword allows for arbitrary data to be stored as name value pairs. This is used with OGC WMS to dene things such as layer title. It can also allow more exibility in creating templates, as anything you put in here will be accessible via template tags. Example:
METADATA "title" "My layer title" "author" "Me!" END
MINGEOWIDTH [double] Minimum width, in the maps geographic units, at which this LAYER is drawn. If MINSCALEDENOM is also specied then MINSCALEDENOM will be used instead. (added in MapServer 5.4.0) The width of a map in geographic units can be found by calculating the following from the extents:
[maxx] - [minx]
MINSCALEDENOM [double] Maximum scale at which this LAYER is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MINSCALE parameter. See Also: Map Scale MINSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is MINSCALEDENOM instead. The deprecated MINSCALE is the maximum scale at which this LAYER is drawn. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. 5.12. LAYER 149
NAME [string] Short name for this layer. This name is the link between the maple and web interfaces that refer to this name. They must be identical. The name should be unique, unless one layer replaces another at different scales. Use the GROUP option to associate layers with each other. It is recommended that the name not contain spaces, special characters, or begin with a number (which could cause problems through interfaces such as OGC services). OFFSITE [r] [g] [b] Sets the color index to treat as transparent for raster layers. OPACITY [integer|alpha] Sets the opacity level (or the inability to see through the layer) of all classed pixels for a given layer. The value can either be an integer in the range (0-100) or the named symbol ALPHA. A value of 100 is opaque and 0 is fully transparent. Implemented in MapServer 5.0, to replace the deprecated TRANSPARENCY parameter. The ALPHA symbol directs the MapServer rendering code to honor the indexed or alpha transparency of pixmap symbols used to style a layer. This is only needed in the case of RGB output formats, and should be used only when necessary as it is expensive to render transparent pixmap symbols onto an RGB map image. PLUGIN [lename] Additional library to load by MapServer, for this layer. This is commonly used to load specic support for SDE and Microsoft SQL Server layers, such as:
CONNECTIONTYPE PLUGIN CONNECTION "hostname,port:xxx,database,username,password" PLUGIN "C:/ms4w/Apache/specialplugins/msplugin_sde_92.dll" DATA "layername,geometrycolumn,SDE.DEFAULT"
POSTLABELCACHE [true|false] Tells MapServer to render this layer after all labels in the cache have been drawn. Useful for adding neatlines and similar elements. Default is false. PROCESSING [string] Passes a processing directive to be used with this layer. The supported processing directives vary by layer type, and the underlying driver that processes them. Attributes Directive - The ITEMS processing option allows to specify the name of attributes for inline layers or specify the subset of the attributes to be used by the layer, such as:
PROCESSING "ITEMS=itemname1,itemname2,itemname3"
Connection Pooling Directive - This is where you can enable connection pooling for certain layer layer types. Connection pooling will allow MapServer to share the handle to an open database or layer connection throughout a single map draw process. Additionally, if you have FastCGI enabled, the connection handle will stay open indenitely, or according to the options specied in the FastCGI conguration. Oracle Spatial, ArcSDE, OGR and PostGIS/PostgreSQL currently support this approach.
PROCESSING "CLOSE_CONNECTION=DEFER"
Label Directive - The LABEL_NO_CLIP processing option can be used to skip clipping of shapes when determining associated label anchor points. This avoids changes in label position as extents change between map draws. It also avoids duplicate labels where features appear in multiple adjacent tiles when creating tiled maps.
PROCESSING "LABEL_NO_CLIP=True"
OGR Styles Directive - This directive can be used for obtaining label styles through MapScript. For more information see the MapServers OGR document.
PROCESSING "GETSHAPE_STYLE_ITEMS=all"
Raster Directives - All raster processing options are described in Raster Data. Here we see the SCALE and BANDs directives used to autoscale raster data and alter the band mapping.
150
Chapter 5. Maple
PROCESSING "SCALE=AUTO" PROCESSING "BANDS=3,2,1"
PROJECTION Signals the start of a PROJECTION object. REQUIRES [expression] Sets context for displaying this layer (see LABELREQUIRES). SIZEUNITS [pixels|feet|inches|kilometers|meters|miles|nauticalmiles] Sets the unit of CLASS object SIZE values (default is pixels). Useful for simulating buffering. Nauticalmiles was added in MapServer 5.6. STATUS [on|off|default] Sets the current status of the layer. Often modied by MapServer itself. Default turns the layer on permanently. Note: In CGI mode, layers with STATUS DEFAULT cannot be turned off using normal mechanisms. It is recommended to set layers to STATUS DEFAULT while debugging a problem, but set them back to ON/OFF in normal use. Note: For WMS, layers in the server maple with STATUS DEFAULT are always sent to the client. Note: The STATUS of the individual layers of a GROUP has no effect when the group name is present in the LAYERS parameter of a CGI request - all the layers of the group will be returned. STYLEITEM [<attribute>|auto] Item to use for feature specic styling. The style information may be represented by a separate attribute (style string) attached to the feature. MapServer supports the following style string representations: MapServer STYLE denition - The style string can be represented as a MapServer STYLE block according to the following example:
STYLE BACKGROUNDCOLOR 128 0 0 COLOR 0 0 208 END
MapServer CLASS denition - By specifying the entire CLASS instead of a single style allows to use further options (like setting expressions, label attributes, multiple styles) on a per feature basis. OGR Style String - MapServer support rendering the OGR style string format according to the OGR Feature Style Specication documentation. Currently only a few data sources support storing the styles along with the features (like MapInfo, AutoCAD DXF, Microstation DGN), however those styles can easily be transferred to many other data sources as a separate attribute by using the ogr2ogr command line tool as follows:
ogr2ogr -sql "select *, OGR_STYLE from srclayer" "dstlayer" "srclayer"
The value: AUTO can be used for automatic styling. Automatic styling can be provided by the driver. Currently, only the OGR driver supports automatic styling. When used for a Union Layer, the styles from the source layers will be used. SYMBOLSCALEDENOM [double] The scale at which symbols and/or text appear full size. This allows for dynamic scaling of objects based on the scale of the map. If not set then this layer will always appear at the same size. Scaling only takes place within the limits of MINSIZE and MAXSIZE as described above. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated SYMBOLSCALE parameter. See Also: Map Scale SYMBOLSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is SYMBOLSCALEDENOM instead. The deprecated SYMBOLSCALE is the scale at which symbols and/or text appear full size. This allows for dynamic scaling of objects based on the scale of the map. If not set then this layer will always appear at the same size. Scaling only takes place within the limits of MINSIZE and MAXSIZE as described above. 5.12. LAYER 151
Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. TEMPLATE [le|url] Used as a global alternative to CLASS TEMPLATE. See Templating for more info. TILEINDEX [lename|layername] Name of the tileindex le or layer. A tileindex is similar to an ArcInfo library index. The tileindex contains polygon features for each tile. The item that contains the location of the tiled data is given using the TILEITEM parameter. When a le is used as the tileindex for shapele or raster layers, the tileindex should be a shapele. For CONNECTIONTYPE OGR layers, any OGR supported datasource can be a tileindex. Normally the location should contain the path to the tile le relative to the shapepath, not relative to the tileindex itself. If the DATA parameter contains a value then it is added to the end of the location. When a tileindex layer is used, it works similarly to directly referring to a le, but any supported feature source can be used (ie. postgres, oracle). Note: All les in the tileindex should have the same coordinate system, and for vector les the same set of attributes in the same order. TILEITEM [attribute] Item that contains the location of an individual tile, default is location. TOLERANCE [double] Sensitivity for point based queries (i.e. via mouse and/or map coordinates). Given in TOLERANCEUNITS. If the layer is a POINT or a LINE, the default is 3. For all other layer types, the default is 0. To restrict polygon searches so that the point must occur in the polygon set the tolerance to zero. TOLERANCEUNITS [pixels|feet|inches|kilometers|meters|miles|nauticalmiles|dd] Units of the TOLERANCE value. Default is pixels. Nauticalmiles was added in MapServer 5.6. TRANSPARENCY [integer|alpha] - deprecated Since MapServer 5.0 the proper parameter to use is OPACITY. The deprecated TRANSPARENCY parameter sets the transparency level of all classed pixels for a given layer. The value can either be an integer in the range (0-100) or the named symbol ALPHA. Although this parameter is named transparency, the integer values actually parameterize layer opacity. A value of 100 is opaque and 0 is fully transparent. The ALPHA symbol directs the MapServer rendering code to honor the indexed or alpha transparency of pixmap symbols used to style a layer. This is only needed in the case of RGB output formats, and should be used only when necessary as it is expensive to render transparent pixmap symbols onto an RGB map image. Deprecated since version 5.0. See Also: OPACITY TRANSFORM [true|false ul|uc|ur|lc|cc|lr|ll|lc|lr] Tells MapServer whether or not a particular layer needs to be transformed from some coordinate system to image coordinates. Default is true. This allows you to create shapeles in image/graphics coordinates and therefore have features that will always be displayed in the same location on every map. Ideal for placing logos or text in maps. Remember that the graphics coordinate system has an origin in the upper left hand corner of the image, contrary to most map coordinate systems. Version 4.10 introduces the ability to dene features with coordinates given in pixels (or percentages, see UNITS), most often inline features, relative to something other than the UL corner of an image. That is what TRANSFORM FALSE means. By setting an alternative origin it allows you to anchor something like a copyright statement to another portion of the image in a way that is independent of image size. TYPE [point|line|polygon|circle|annotation|raster|query|chart] Species how the data should be drawn. Need not be the same as the shapele type. For example, a polygon shapele may be drawn as a point layer, but a point shapele may not be drawn as a polygon layer. Common sense rules. Annotation means that a label point will be calculated for the features, but the feature itself will not be drawn although a marker symbol can be optionally drawn. this allows for advanced labeling like numbered highway shields. Points are labeled at that point. Polygons are labeled rst using a centroid, and if that doesnt fall in the polygon a scanline approach is used to guarantee the label falls within the feature. Lines are labeled at the middle of the longest arc in the visible portion of the line. Query only means the layer can be queried but not drawn.
152
Chapter 5. Maple
In order to differentiate between POLYGONs and POLYLINEs (which do not exist as a type), simply respectively use or omit the COLOR keyword when classifying. If you use it, its a polygon with a ll color, otherwise its a polyline with only an OUTLINECOLOR. A circle must be dened by a a minimum bounding rectangle. That is, two points that dene the smallest square that can contain it. These two points are the two opposite corners of said box. The following is an example using inline points to draw a circle:
LAYER NAME inline_circles TYPE CIRCLE STATUS ON FEATURE POINTS 74.01 -53.8 110.7 -22.16 END END CLASS STYLE COLOR 0 0 255 END END END
See Also: For CHART layers, see the Dynamic Charting HowTo. UNITS [feet|inches|kilometers|meters|miles|nauticalmiles|dd|pixels|percentages] Units of the layer. Percentages was added in MapServer 4.10 and is mostly geared for inline features. Nauticalmiles was added in MapServer 5.6. VALIDATION Signals the start of a VALIDATION block. As of MapServer 5.4.0, VALIDATION blocks are the preferred mechanism for specifying validation patterns for CGI param runtime substitutions. See Run-time Substitution.
5.13 LEGEND
The size of the legend image is NOT known prior to creation so be careful not to hard-code width and height in the <IMG> tag in the template le. IMAGECOLOR [r] [g] [b] Color to initialize the legend with (i.e. the background). INTERLACE [on|off] Default is [on]. This keyword is now deprecated in favor of using the FORMATOPTION INTERLACE=ON line in the OUTPUTFORMAT declaration. Deprecated since version 4.6. KEYSIZE [x][y] Size of symbol key boxes in pixels. Default is 20 by 10. KEYSPACING [x][y] Spacing between symbol key boxes ([y]) and labels ([x]) in pixels. Default is 5 by 5. LABEL Signals the start of a LABEL object OUTLINECOLOR [r] [g] [b] Color to use for outlining symbol key boxes. POSITION [ul|uc|ur|ll|lc|lr] Where to place an embedded legend in the map. Default is lr. POSTLABELCACHE [true|false] Tells MapServer to render this legend after all labels in the cache have been drawn. Useful for adding neatlines and similar elements. Default is false.
5.13. LEGEND
153
STATUS [on|off|embed] Is the legend image to be created. TEMPLATE [lename] HTML legend template le. See Also: HTML Legends with MapServer TRANSPARENT [on|off] Should the background color for the legend be transparent. This ag is now deprecated in favor of declaring transparency within OUTPUTFORMAT declarations. Default is off. Deprecated since version 4.6.
5.14 MAP
Note: The map object is started with the word MAP, and ended with the word END. ANGLE [double] Angle, given in degrees, to rotate the map. Default is 0. The rendered map will rotate in a clockwise direction. The following are important notes: Requires a PROJECTION object specied at the MAP level and for each LAYER object (even if all layers are in the same projection). Requires MapScript (SWIG, PHP MapScript). Does not work with CGI mode. If using the LABEL objects ANGLE or the LAYER objects LABELANGLEITEM parameters as well, these parameters are relative to the maps orientation (i.e. they are computed after the MAP objects ANGLE). For example, if you have specied an ANGLE for the map of 45, and then have a layer LABELANGLEITEM value of 45, the resulting label will not appear rotated (because the resulting map is rotated clockwise 45 degrees and the label is rotated counter-clockwise 45 degrees). More information can be found on the MapRotation Wiki Page. CONFIG [key] [value] This can be used to specify several values at run-time, for both MapServer and GDAL/OGR libraries. Developers: values will be passed on to CPLSetCongOption(). Details on GDAL/OGR options are found in their associated driver documentation pages (GDAL/OGR). The following options are available specically for MapServer: CGI_CONTEXT_URL [value] This CONFIG parameter can be used to enable loading a map context from a URL. See the Map Context HowTo for more info. MS_ENCRYPTION_KEY [lename] This CONFIG parameter can be used to specify an encryption key that is used with MapServers msencypt utility. MS_ERRORFILE [lename] This CONFIG parameter can be used to write MapServer errors to a le (as of MapServer 5.0). With MapServer 5.x, a full path (absolute reference) is required, including the lename. Starting with MapServer 6.0, a lename with relative path can be passed via this CONFIG directive, in which case the lename is relative to the maple location. Note that setting MS_ERRORFILE via an environment variable always requires an absolute path since there would be no maple to make the path relative to. For more on this see the DEBUG parameter below. MS_NONSQUARE [yes|no] This CONFIG parameter can be used to allow non-square WMS requests. ON_MISSING_DATA [FAIL|LOG|IGNORE] This CONFIG parameter can be used to tell MapServer how to handle missing data in tile indexes (as of MapServer 5.3-dev, r8015). Previous MapServer versions required a compile-time switch (IGNORE_MISSING_DATA), but this is no longer required. FAIL This will cause MapServer to throw an error and exit (to crash, in other words) on a missing le in a tile index. This is the default.
154
Chapter 5. Maple
CONFIG "ON_MISSING_DATA" "FAIL"
LOG This will cause MapServer to log the error message for a missing le in a tile index, and continue with the map creation. Note: DEBUG parameter and CONFIG MS_ERRORFILE need to be set for logging to occur, so please see the DEBUG parameter below for more information.
CONFIG "ON_MISSING_DATA" "LOG"
IGNORE This will cause MapServer to not report or log any errors for missing les, and map creation will occur normally.
CONFIG "ON_MISSING_DATA" "IGNORE"
PROJ_LIB [path] This CONFIG parameter can be used to dene the location of your EPSG les for the Proj.4 library. Setting the [key] to PROJ_LIB and the [value] to the location of your EPSG les will force PROJ.4 to use this value. Using CONFIG allows you to avoid setting environment variables to point to your PROJ_LIB directory. Here are some examples: 1. Unix
CONFIG "PROJ_LIB" "/usr/local/share/proj/"
2. Windows
CONFIG "PROJ_LIB" "C:/somedir/proj/nad/"
DATAPATTERN [regular expression] This denes a regular expression to be applied to requests to change DATA parameters via URL requests (i.e. map_layername_data=...). If a pattern doesnt exist then web users cant monkey with support les via URLs. This allows you to isolate one application from another if you desire, with the default operation being very conservative. See also TEMPLATEPATTERN. DEBUG [off|on|0|1|2|3|4|5] Enables debugging of all of the layers in the current map. Debugging with MapServer versions >= 5.0: Verbose output is generated and sent to the standard error output (STDERR) or the MapServer errorle if one is set using the MS_ERRORFILE environment variable. You can set the environment variable by using the CONFIG parameter at the MAP level of the maple, such as:
You can also set the environment variable in Apache by adding the following to your httpd.conf:
Once the environment variable is set, the DEBUG maple parameter can be used to control the level of debugging output. Here is a description of the possible DEBUG values: DEBUG O or OFF - only msSetError() calls are logged to MS_ERRORFILE. No msDebug() output at all. This is the default and corresponds to the original behavior of MS_ERRORFILE in MapServer 4.x. DEBUG 1 or ON - includes all output from DEBUG 0 plus msDebug() warnings about common pitfalls, failed assertions or non-fatal error situations (e.g. missing or invalid values for some parameters, missing shapeles in tileindex, timeout error from remote WMS/WFS servers, etc.). DEBUG 2 - includes all output from DEBUG 1 plus notices and timing information useful for tuning maples and applications.
5.14. MAP
155
DEBUG 3 - all of DEBUG 2 plus some debug output useful in troubleshooting problems such as WMS connection URLs being called, database connection calls, etc. This is the recommended level for debugging maples. DEBUG 4 - DEBUG 3 plus even more details... DEBUG 5 - DEBUG 4 plus any msDebug() output that might be more useful to the developers than to the users. You can also set the debug level by using the MS_DEBUGLEVEL environment variable. The DEBUG setting can also be specied for a layer, by setting the DEBUG parameter in the LAYER object. For more details on this debugging mechanism, please see the Debugging MapServer document. Debugging with MapServer versions < 5: Verbose output is generated and sent to the standard error output (STDERR) or the MapServer logle if one is set using the LOG parameter in the WEB object. Apache users will see timing details for drawing in Apaches error_log le. Requires MapServer to be built with the DEBUG=MSDEBUG option (with-debug congure option). DEFRESOLUTION [int] Sets the reference resolution (pixels per inch) used for symbology. Default is 72. Used to automatically scale the symbology when RESOLUTION is changed, so the map maintains the same look at each resolution. The scale factor is RESOLUTION / DEFRESOLUTION. New in version 5.6. EXTENT [minx] [miny] [maxx] [maxy] The spatial extent of the map to be created. In most cases you will need to specify this, although MapServer can sometimes (expensively) calculate one if it is not specied. FONTSET [lename] Filename of fontset le to use. Can be a path relative to the maple, or a full path. IMAGECOLOR [r] [g] [b] Color to initialize the map with (i.e. background color). When transparency is enabled (TRANSPARENT ON in OUTPUTFORMAT) for the typical case of 8-bit pseudocolored map generation, this color will be marked as transparent in the output le palette. Any other map components drawn in this color will also be transparent, so for map generation with transparency it is best to use an otherwise unused color as the background color. IMAGEQUALITY [int] Deprecated Use FORMATOPTION QUALITY=n in the OUTPUTFORMAT declaration to specify compression quality for JPEG output. Deprecated since version 4.6. IMAGETYPE [png|jpeg|pdf|...|userdened] Output format (raster or vector) to generate. The name used here must match the NAME of a user dened or internally available OUTPUTFORMAT. For a complete list of available IMAGEFORMATs, see the OUTPUTFORMAT section. INTERLACE [on|off] Deprecated Use FORMATOPTION INTERLACE=ON in the OUTPUTFORMAT declaration to specify if the output images should be interlaced. Deprecated since version 4.6. LAYER Signals the start of a LAYER object. LEGEND Signals the start of a LEGEND object. MAXSIZE [integer] Sets the maximum size of the map image. This will override the default value. For example, setting this to 2048 means that you can have up to 2048 pixels in both dimensions (i.e. max of 2048x2048). Default is 2048. NAME [name] Prex attached to map, scalebar and legend GIF lenames created using this maple. It should be kept short. PROJECTION Signals the start of a PROJECTION object. QUERYMAP Signals the start of a QUERYMAP object. REFERENCE Signals the start of a REFERENCE MAP object.
156
Chapter 5. Maple
RESOLUTION [int] Sets the pixels per inch for output, only affects scale computations. Default is 72. SCALEDENOM [double] Computed scale of the map. Set most often by the application. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated SCALE parameter. See Also: Map Scale SCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is SCALEDENOM instead. The deprecated SCALE is the computed scale of the map. Set most often by the application. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. SCALEBAR Signals the start of a SCALEBAR object. SHAPEPATH [lename] Path to the directory holding the shapeles or tiles. There can be further subdirectories under SHAPEPATH. SIZE [x][y] Size in pixels of the output image (i.e. the map). STATUS [on|off] Is the map active? Sometimes you may wish to turn this off to use only the reference map or scale bar. SYMBOLSET [lename] Filename of the symbolset to use. Can be a path relative to the maple, or a full path. Note: The SYMBOLSET le must start with the word SYMBOLSET and end with the word END. SYMBOL Signals the start of a SYMBOL object. TEMPLATEPATTERN [regular expression] This denes a regular expression to be applied to requests to change the TEMPLATE parameters via URL requests (i.e. map_layername_template=...). If a pattern doesnt exist then web users cant monkey with support les via URLs. This allows you to isolate one application from another if you desire, with the default operation being very conservative. See also DATAPATTERN. TRANSPARENT [on|off] Deprecated since version 4.6. Use TRANSPARENT ON in the OUTPUTFORMAT declaration to specify if the output images should be transparent. UNITS [feet|inches|kilometers|meters|miles|nauticalmiles|dd] Units of the map coordinates. Used for scalebar and scale computations. Nauticalmiles was added in MapServer 5.6. WEB Signals the start of a WEB object.
5.15 OUTPUTFORMAT
A map le may have zero, one or more OUTPUTFORMAT object declarations, dening available output formats supported including formats like PNG, GIF, JPEG, GeoTIFF, SVG, PDF and KML. If OUTPUTFORMAT sections declarations are not found in the map le, the following implicit declarations will be made. Only those for which support is compiled in will actually be available. The GeoTIFF depends on building with GDAL support, and the PDF and SVG depend on building with cairo support.
OUTPUTFORMAT NAME "png" DRIVER AGG/PNG MIMETYPE "image/png" IMAGEMODE RGB EXTENSION "png"
5.15. OUTPUTFORMAT
157
FORMATOPTION "GAMMA=0.75" END OUTPUTFORMAT NAME "gif" DRIVER GD/GIF MIMETYPE "image/gif" IMAGEMODE PC256 EXTENSION "gif" END OUTPUTFORMAT NAME "png8" DRIVER AGG/ P N G 8 MIMETYPE "image/png; mode=8bit" IMAGEMODE RGB EXTENSION "png" FORMATOPTION "QUANTIZE_FORCE=on" FORMATOPTION "QUANTIZE_COLORS=256" FORMATOPTION "GAMMA=0.75" END OUTPUTFORMAT NAME "jpeg" DRIVER AGG/JPEG MIMETYPE "image/jpeg" IMAGEMODE RGB EXTENSION "jpg" FORMATOPTION "GAMMA=0.75" END OUTPUTFORMAT NAME "svg" DRIVER C A I R O / S V G MIMETYPE "image/svg+xml" IMAGEMODE RGB EXTENSION "svg" END OUTPUTFORMAT NAME "pdf" DRIVER C A I R O /PDF MIMETYPE "application/x-pdf" IMAGEMODE RGB EXTENSION "pdf" END OUTPUTFORMAT NAME "GTiff" DRIVER G D A L /GTiff MIMETYPE "image/tiff" IMAGEMODE RGB EXTENSION "tif" END OUTPUTFORMAT NAME "kml" DRIVER K M L MIMETYPE "application/vnd.google-earth.kml.xml" IMAGEMODE RGB EXTENSION "kml" END OUTPUTFORMAT NAME "kmz" DRIVER K M Z
158
Chapter 5. Maple
MIMETYPE "application/vnd.google-earth.kmz" IMAGEMODE RGB EXTENSION "kmz" END OUTPUTFORMAT NAME "cairopng" DRIVER C A I R O /PNG MIMETYPE "image/png" IMAGEMODE RGB EXTENSION "png" END
DRIVER [name] The name of the driver to use to generate this output format. Some driver names include the denition of the format if the driver supports multiple formats. For AGG, the possbile driver names are AGG/PNG and AGG/JPEG. For GD the possible driver names are GD/Gif and GD/PNG. For output through OGR the OGR driver name is appended, such as OGR/Mapinfo File. For output through GDAL the GDAL shortname for the format is appended, such as GDAL/GTiff. Note that PNG, JPEG and GIF output can be generated with either GDAL or GD (GD is generally more efcient). TEMPLATE should be used for template based output. (mandatory) EXTENSION [type] Provide the extension to use when creating les of this type. (optional) FORMATOPTION [option] Provides a driver or format specic option. Zero or more FORMATOPTION statement may be present within a OUTPUTFORMAT declaration. (optional) AGG/JPEG: The QUALITY=n option may be used to set the quality of jpeg produced (value from 0-100). GD/PNG: The INTERLACE=[ON/OFF] option may be used to turn interlacing on or off. GD/GIF: The INTERLACE=[ON/OFF] option may be used to turn interlacing on or off. GDAL/GTiff: Supports the TILED=YES, BLOCKXSIZE=n, BLOCKYSIZE=n, INTERLEAVE=[PIXEL/BAND] and COMPRESS=[NONE,PACKBITS,JPEG,LZW,DEFLATE] format specic options. GDAL/*: All FORMATOPTIONs are passed onto the GDAL create function. Options supported by GDAL are described in the detailed documentation for each GDAL format GDAL/*: NULLVALUE=n is used in raw image modes (IMAGEMODE BYTE/INT16/FLOAT) to preinitialize the raster and an attempt is made to record this in the resulting le as the nodata value. This is automatically set in WCS mode if rangeset_nullvalue is set. OGR/*: See OGR Output document for details of OGR format options. AGG/*: GAMMA=n is used to specify the gamma correction to apply to polygon rendering. Allowed values are ]0.0,1.0] , default is 0.75. This value is used to prevent artifacts from appearing on the border of contiguous polygons. Set to 1.0 to disable gamma correction. AGG/PNG: COMPRESSION=n is used to determine the ZLIB compression applied to the png creation. n is expected to be an integer value from 0 to 9, with 0 meaning no compression (not recommended), 1 meaning fastest compression, and 9 meaning best compression. The compression levels come at a cost (be it in terms of cpu processing or le size, chose the setting that suits you most). The default is COMPRESSION=6. AGG/PNG supports quantizing from 24/32 bits to 8bits, in order to reduce the nal image size (and therefore save bandwidth) (see also http://trac.osgeo.org/mapserver/ticket/2436#comment:4 for strategies when applying these options): QUANTIZE_FORCE=on used to reduce an RGB or RGBA image into an 8bit (or less) paletted images. The colors used in the palette are selected to best t the actual colors in the
5.15. OUTPUTFORMAT
159
RGB or RGBA image. QUANTIZE_COLORS=256 used to specify the number of colors to be used when applying quantization. Maximum value is 256. Specifying anything between 17 and 255 is probably a waste of quality as each pixel is still encoded with a full byte. Specifying a value under 16 will produce tiny images, but severly degraded. PALETTE=/path/to/palette.txt is used to dene the absolute path where palette colors can be found. This le must contain 256 entries of r,g,b triplets for RGB imagemodes, or r,g,b,a quadruplets for RGBA imagemodes. The expected format is one triplet (or quadruplet) per line, each value separated by commas, and each triplet/quadruplet on a single line. If you want to use transparency with a palette, it is important to have these two colors in the palette le: 0,0,0,0 and 255,255,255,255. Note: 0,0,0,0 is important if you have fully transparent areas. 255,255,255,255 is opaque white. The important colors to have in your palette really depend on your actual map, although 0,0,0,0 , 0,0,0,255 , and 255,255,255,255 are very likely to show up most of the time. PALETTE_FORCE=on is used to reduce image depth with a predened palette. This option is incompatible with the previous quantization options. IMAGEMODE [PC256/RGB/RGBA/INT16/FLOAT32/FEATURE] Selects the imaging mode in which the output is generated. Does matter for non-raster formats like Flash. Not all formats support all combinations. For instance GD supports only PC256. (optional) PC256: Produced a pseudocolored result with up to 256 colors in the palette (legacy MapServer mode). Only supported for GD/GIF and GD/PNG. RGB: Render in 24bit Red/Green/Blue mode. Supports all colors but does not support transparency. RGBA: Render in 32bit Red/Green/Blue/Alpha mode. Supports all colors, and alpha based transparency. All features are rendered against an initially transparent background. BYTE: Render raw 8bit pixel values (no presentation). Only works for RASTER layers (through GDAL) and WMS layers currently. INT16: Render raw 16bit signed pixel values (no presentation). Only works for RASTER layers (through GDAL) and WMS layers currently. FLOAT32: Render raw 32bit oating point pixel values (no presentation). Only works for RASTER layers (through GDAL) and WMS layers currently. FEATURE: Output is a non-image result, such as features written via templates or OGR. MIMETYPE [type] Provide the mime type to be used when returning results over the web. (optional) NAME [name] The name to use in the IMAGETYPE keyword of the map le to select this output format. This name is also used in metadata describing wxs formats allowed, and can be used (sometimes along with mimetype) to select the output format via keywords in OGC requests. (optional) TRANSPARENT [ON/OFF] Indicates whether transparency should be enabled for this format. Note that transparency does not work for IMAGEMODE RGB output. Not all formats support transparency (optional). When transparency is enabled for the typical case of 8-bit pseudocolored map generation, the IMAGECOLOR color will be marked as transparent in the output le palette. Any other map components drawn in this color will also be transparent, so for map generation with transparency it is best to use an otherwise unused color as the background color.
5.16 PROJECTION
There are thousands of geographical reference systems. In order to combine datasets with different geographical reference systems into a map, the datasets will have to be transformed (projected) to the chosen geographical reference 160 Chapter 5. Maple
system of the map. If you want to know more about geographical reference systems and map projections, you could take some Geomatics courses (Geographical Information Systems, Cartography, Geodesy, ...). To set up projections you must dene one projection object for the output image (in the MAP object) and one projection object for each layer (in the LAYER objects) to be projected. MapServer relies on the Proj.4 library for projections. Projection objects therefore consist of a series of PROJ.4 keywords, which are either specied within the object directly or referred to in an EPSG le. An EPSG le is a lookup le containing projection parameters, and is part of the PROJ.4 library. The following two examples both dene the same projection (UTM zone 15, NAD83), but use 2 different methods: Example 1: Inline Projection Parameters
PROJECTION "proj=utm" "ellps=GRS80" "datum=NAD83" "zone=15" "units=m" "north" "no_defs" END
Note: For a list of all of the possible PROJ.4 projection parameters, see the PROJ.4 parameters page. Example 2: EPSG Projection Use
PROJECTION "init=epsg:26915" END
Note: This refers to an EPSG lookup le that contains a 26915 code with the full projection parameters. epsg in this instance is case-sensitive because it is referring to a le name. If your le system is case-sensitive, this must be lower case, or MapServer (Proj.4 actually) will complain about not being able to nd this le. Note: See http://spatialreference.org/ref/epsg/26915 for more information on this coordinate system. The next two examples both display how to possibly dene unprojected lat/long (geographic): Example 3: Inline Projection Parameters
PROJECTION "proj=latlong" "ellps=WGS84" "datum=WGS84" END
Example 4: epsg Projection Use

5.16.1 Important Notes

If all of your data in the maple is in the same projection, you DO NOT have to specify any projection objects. MapServer will assume that all of the data is in the same projection. Think of the MAP-level projection object as your output projection. The EXTENT and UNITS values at the MAP-level must be in the output projection units. Also, if you have layers in other projections (other than the
5.16. PROJECTION
161
MAP-level projection) then you must dene PROJECTION objects for those layers, to tell MapServer what projections they are in. If you specify a MAP-level projection, and then only one other LAYER projection object, MapServer will assume that all of the other layers are in the specied MAP-level projection. Always refer to the EPSG le in lowercase, because it is a lowercase lename and on Linux/Unix systems this parameter is case sensitive.
5.16.2 For More Information

If you get projection errors, refer to the Errors to check if your exact error has been discussed. Search the MapServer-users email list archives, odds are that someone has faced your exact issue before. See the PROJ.4 user guides for complete descriptions of supported projections and coordinate systems. Refer to the Cartographical Map Projections page for background information on projections.
5.17 QUERYMAP
COLOR [r] [g] [b] Color in which features are highlighted. Default is yellow. SIZE [x][y] Size of the map in pixels. Defaults to the size dened in the map object. STATUS [on|off] Is the query map to be drawn? STYLE [normal|hilite|selected] Sets how selected features are to be handled. Layers not queried are drawn as usual. Normal: Draws all features according to the settings for that layer. Hilite: Draws selected features using COLOR. Non-selected features are drawn normally. Selected: draws only the selected features normally.
5.18 REFERENCE
Three types of reference maps are supported. The most common would be one showing the extent of a map in an interactive interface. It is also possible to request reference maps as part of a query. Point queries will generate an image with a marker (see below) placed at the query point. Region based queries will depict the extent of the area of interest. Finally, feature based queries will display the selection feature(s) used. COLOR [r] [g] [b] Color in which the reference box is drawn. Set any component to -1 for no ll. Default is red. EXTENT [minx][miny][maxx][maxy] The spatial extent of the base reference image. IMAGE [lename] Full lename of the base reference image. Must be a GIF image. MARKER [integer|string] Denes a symbol (from the symbol le) to use when the box becomes too small (see MINBOXSIZE and MAXBOXSIZE below). Uses a crosshair by default. MARKERSIZE [integer] Denes the size of the symbol to use instead of a box (see MARKER above). MINBOXSIZE [integer] If box is smaller than MINBOXSIZE (use box width or height) then use the symbol dened by MARKER and MARKERSIZE. MAXBOXSIZE [integer] If box is greater than MAXBOXSIZE (use box width or height) then draw nothing (Often the whole map gets covered when zoomed way out and its perfectly obvious where you are).
162
Chapter 5. Maple
OUTLINECOLOR [r] [g] [b] Color to use for outlining the reference box. Set any component to -1 for no outline. SIZE [x][y] Size, in pixels, of the base reference image. STATUS [on|off] Is the reference map to be created? Default it off.
5.19 SCALEBAR
Scalebars currently do not make use of TrueType fonts. The size of the scalebar image is NOT known prior to rendering, so be careful not to hard-code width and height in the <IMG> tag in the template le. Future versions will make the image size available. ALIGN [left|center|right] Denes how the scalebar is aligned within the scalebar image. Default is center. Available in versions 5.2 and higher. New in version 5.2. BACKGROUNDCOLOR [r] [g] [b] Color to use for scalebar background, not the image background. COLOR [r] [g] [b] Color to use for drawing all features if attribute tables are not used. IMAGECOLOR [r] [g] [b] Color to initialize the scalebar with (i.e. background). INTERLACE [true|false] Should output images be interlaced? Default is [on]. This keyword is now deprecated in favour of using the FORMATOPTION INTERLACE=ON line in the OUTPUTFORMAT declaration. Deprecated since version 4.6. INTERVALS [integer] Number of intervals to break the scalebar into. Default is 4. LABEL Signals the start of a LABEL object. OUTLINECOLOR [r] [g] [b] Color to use for outlining individual intervals. Set any component to -1 for no outline which is the default. POSITION [ul|uc|ur|ll|lc|lr] Where to place an embedded scalebar in the image. Default is lr. POSTLABELCACHE [true|false] For use with embedded scalebars only. Tells the MapServer to embed the scalebar after all labels in the cache have been drawn. Default is false. SIZE [x][y] Size in pixels of the scalebar. Labeling is not taken into account. STATUS [on|off|embed] Is the scalebar image to be created, and if so should it be embedded into the image? Default is off. (Please note that embedding scalebars require that you dene a markerset. In essence the scalebar becomes a custom marker that is handled just like any other annotation.) STYLE [integer] Chooses the scalebar style. Valid styles are 0 and 1. TRANSPARENT [on|off] Should the background color for the scalebar be transparent. This ag is now deprecated in favor of declaring transparency within OUTPUTFORMAT declarations. Default is off. Deprecated since version 4.6. UNITS [feet|inches|kilometers|meters|miles|nauticalmiles] Output scalebar units, default is miles. Used in conjunction with the maps units to develop the actual graphic. Note that decimal degrees are not valid scalebar units. Nauticalmiles was added in MapServer 5.6.
5.20 STYLE
Style holds parameters for symbolization and styling. Multiple styles may be applied within a CLASS or LABEL. This object appeared in 4.0 and the intention is to separate logic from looks. The nal intent is to have named styles (Not yet supported) that will be re-usable through the maple. This is the way of dening the appearance of an object (a CLASS or a LABEL). 5.19. SCALEBAR 163
ANGLE [double|attribute|AUTO] Angle, given in degrees, to rotate the symbol (counter clockwise). Default is 0 (no rotation). If you have an attribute that species angles in a clockwise direction (compass direction), you have to adjust the angle attribute values before they reach Mapserver (360-ANGLE), as it is not possible to use a mathematical expression for ANGLE. For points, it species the rotation of the symbol around its center. For decorated lines, the behaviour depends on the value of the GAP element. For negative GAP values it species the rotation of the decoration symbol relative to the direction of the line. An angle of 0 means that the symbols x-axis is oriented along the direction of the line. For non-negativ (or absent) GAP values it species the rotation of the decoration symbol around its center. An angle of 0 means that the symbol is not rotated. For polygons, it species the angle of the lines in a HATCH symbol (0 - horizontal lines), or it species the rotation of the symbol used to generate the pattern in a polygon ll (it does not specify the rotation of the ll as a whole). For its use with hatched lines, see Example #7 in the symbology examples. [attribute] was introduced in version 5.0, to specify the attribute to use for angle values. The hard brackets [] are required. For example, if your data source has an attribute named MYROTATE that holds angle values for each feature, your STYLE object for hatched lines might contain:
STYLE SYMBOL hatch-test COLOR 255 0 0 ANGLE [ M Y R O T A T E ] SIZE 4.0 WIDTH 3.0 END
The associated RFC document for this feature is MS RFC 19: Style & Label attribute binding. The AUTO keyword was added in version 5.4, and currently only applies when coupled with the GEOMTRANSFORM keyword. Note: Rotation using ANGLE is not supported for SYMBOLs of TYPE ellipse with the GD renderer (gif). ANGLEITEM [string] ANGLE[attribute] must now be used instead. Deprecated since version 5.0. ANTIALIAS [true|false] Should TrueType fonts be antialiased. Only useful for GD (gif) rendering. Default is false. Has no effect for the other renderers (where anti-aliasing can not be turned off). BACKGROUNDCOLOR [r] [g] [b] Color to use for non-transparent symbols. COLOR [r] [g] [b] | [attribute] Color to use for drawing features. r, g and b shall be integers [0..255]. To specify green, the following is used:
COLOR 0 255 0
[attribute] was introduced in version 5.0, to specify the attribute to use for color values. The hard brackets [] are required. For example, if your data set has an attribute named MYPAINT that holds color values for each record, use: object for might contain:
COLOR [ M Y P A I N T ]
The associated RFC document for this feature is MS RFC 19: Style & Label attribute binding. GAP [double] GAP species the distance between SYMBOLs (center to center) for decorated lines and polygon lls in layer SIZEUNITS. For polygon lls, GAP species the distance between SYMBOLs in both the X and the Y
164
Chapter 5. Maple
direction. For lines, the centers of the SYMBOLs are placed on the line. As of MapServer 5.0 this also applies to PixMap symbols. When scaling of symbols is in effect (SYMBOLSCALEDENOM is specied for the LAYER), GAP species the distance in layer SIZEUNITS at the map scale 1:SYMBOLSCALEDENOM. For lines, the rst symbol will be placed GAP/2 from the start of the line. For lines, a negative GAP value will cause the symbols X axis to be aligned relative to the tangent of the line. For lines, a positive GAP value aligns the symbols X axis relative to the X axis of the output device. For lines, a GAP of 0 (the default value) will cause the symbols to be rendered edge to edge For polygons, a missing GAP or a GAP of 0 will cause the symbols to be rendered edge to edge. Symbols can be rotated using ANGLE. New in version 6.0: moved from SYMBOL Note: The behaviour of GAP has not been stable over time. It has specied the amount of space between the symbols, and also something in between the amount of space between the symbols and the center to center distance. The goal is to have GAP specify the center to center distance, but in version 6.0 it is the amount of space between the symbols that is specied. GEOMTRANSFORM [bbox|end|labelpnt|labelpoly|start|vertices] Used to indicate that the current feature will be transformed before the actual style is applied. Introduced in version 5.4. bbox: produces the bounding box of the current feature geometry. end: produces the last point of the current feature geometry. When used with ANGLE AUTO, it can for instance be used to render arrowheads on line segments. labelpnt: used for LABEL styles. Draws a marker on the geographic position the label is attached to. This corresponds to the center of the label text only if the label is in position CC. labelpoly: used for LABEL styles. Produces a polygon that covers the label plus a 1 pixel padding. start: produces the rst point of the current feature geometry. When used with ANGLE AUTO, it can for instance be used to render arrow tails on line segments. vertices: produces all the intermediate vertices (points) of the current feature geometry (the start and end are excluded). When used with ANGLE AUTO, the marker is oriented by the half angle formed by the two adjacent line segments. LINECAP [butt|round|square] Sets the line cap type for lines. Default is round. See Cartographical Symbol Construction with MapServer for explanation and examples. New in version 6.0: moved from SYMBOL LINEJOIN [round|miter|bevel] Sets the line join type for lines. Default is round. See Cartographical Symbol Construction with MapServer for explanation and examples. New in version 6.0: moved from SYMBOL LINEJOINMAXSIZE [int] Sets the max length of the miter LINEJOIN type. The value represents a coefcient which multiplies a current symbol size. Default is 3. See Cartographical Symbol Construction with MapServer for explanation and examples. New in version 6.0: moved from SYMBOL MAXSIZE [double] Maximum size in pixels to draw a symbol. Default is 500. Starting from version 5.4, the value can also be a decimal value (and not only integer). See LAYER SYMBOLSCALEDENOM. MAXWIDTH [double] Maximum width in pixels to draw the line work. Default is 32. Starting from version 5.4, the value can also be a decimal value (and not only integer). See LAYER SYMBOLSCALEDENOM. MINSIZE [double] Minimum size in pixels to draw a symbol. Default is 0. Starting from version 5.4, the value can also be a decimal value (and not only integer). See LAYER SYMBOLSCALEDENOM. MINWIDTH [double] Minimum width in pixels to draw the line work. Default is 0. Starting from version 5.4, the value can also be a decimal value (and not only integer). See LAYER SYMBOLSCALEDENOM.
5.20. STYLE
165
OFFSET [x][y] Geometry offset values in layer SIZEUNITS. When scaling of symbols is in effect (SYMBOLSCALEDENOM is specied for the LAYER), OFFSET gives offset values in layer SIZEUNITS at the map scale 1:SYMBOLSCALEDENOM. An OFFSET of 20 40 will shift the geometry 20 SIZEUNITS to the left and 40 SIZEUNITS down before rendering. For lines, an OFFSET of n -99 will produce a line geometry that is shifted n SIZEUNITS perpendicular to the original line geometry. A positive n shifts the line to the right when seen along the direction of the line. A negative n shifts the line to the left when seen along the direction of the line. OPACITY [integer|attribute] Opacity to draw the current style (applies to 5.2+, AGG Rendering Specics only, does not apply to pixmap symbols) [attribute] was introduced in version 5.6, to specify the attribute to use for opacity values. OUTLINECOLOR [r] [g] [b] | [attribute] Color to use for outlining polygons and certain marker symbols (ellipse, vector polygons and truetype). Has no effect for lines. The width of the outline can be specied using WIDTH. If no WIDTH is specied, an outline of one pixel will be drawn. If there is a SYMBOL dened for the STYLE, the OUTLINECOLOR will be used to create an outline for that SYMBOL (only ellipse, truetype and polygon vector symbols will get an outline). If there is no SYMBOL dened for the STYLE, the polygon will get an outline. r, g and b shall be integers [0..255]. To specify green, the following is used:
OUTLINECOLOR 0 255 0 WIDTH 3.0
[attribute] was introduced in version 5.0, to specify the attribute to use for color values. The hard brackets [] are required. For example, if your data set has an attribute named MYPAINT that holds color values for each record, use: object for might contain:
OUTLINECOLOR [ M Y P A I N T ]
The associated RFC document for this feature is MS RFC 19: Style & Label attribute binding. PATTERN [double on] [double off] [double on] [double off] ... END Currently used to denes a dash pattern for line work (lines, polygon outlines, ...). The numbers (doubles) specify the lengths of the dashes and gaps of the dash pattern in layer SIZEUNITS. When scaling of symbols is in effect (SYMBOLSCALEDENOM is specied for the LAYER), the numbers specify the lengths of the dashes and gaps in layer SIZEUNITS at the map scale 1:SYMBOLSCALEDENOM. To specify a dashed line that is 5 units wide, with dash lengths of 5 units and gaps of 5 units, the following style can be used:
STYLE COLOR 0 0 0 WIDTH 5.0 LINECAP BUTT PATTERN 5.0 5.0 END END
New in version 6.0: moved from SYMBOL SIZE [double|attribute] Height, in layer SIZEUNITS, of the symbol/pattern to be used. Default value depends on the SYMBOL TYPE. For pixmap: the hight (in pixels) of the pixmap; for ellipse and vector: the maximum y value of the SYMBOL POINTS parameter, for hatch: 1.0, for truetype: 1.0. When scaling of symbols is in effect (SYMBOLSCALEDENOM is specied for the LAYER), SIZE gives the height, in layer SIZEUNITS, of the symbol/pattern to be used at the map scale 1:SYMBOLSCALEDENOM. 166 Chapter 5. Maple
For symbols of TYPE hatch, the SIZE is the center to center distance between the lines. For its use with hatched lines, see Example#8 in the symbology examples. [attribute] was introduced in version 5.0, to specify the attribute to use for size values. The hard brackets [] are required. For example, if your data set has an attribute named MYHIGHT that holds size values for each feature, your STYLE object for hatched lines might contain:
STYLE SYMBOL hatch-test COLOR 255 0 0 ANGLE 45 SIZE [ M Y H I G H T ] WIDTH 3.0 END
The associated RFC document for this feature is MS RFC 19: Style & Label attribute binding. Starting from version 5.4, the value can also be a decimal value (and not only integer). SIZEITEM [string] SIZE [attribute] must now be used instead. Deprecated since version 5.0. SYMBOL [integer|string|lename|url|attribute] The symbol to use for rendering the features. Integer is the index of the symbol in the symbol set, starting at 1 (the 5th symbol is symbol number 5). String is the name of the symbol (as dened using the SYMBOL NAME parameter). Filename species the path to a le containing a symbol. For example a PNG le. Specify the path relative to the directory containing the maple. URL species the address of a le containing a pixmap symbol. For example a PNG le. A URL must start with http:
SYMBOL "http://myserver.org/path/to/file.png"
New in version 6.0. [attribute] allows individual rendering of features by using an attribute in the dataset that species the symbol name (as dened in the SYMBOL NAME parameter). The hard brackets [] are required. New in version 5.6. If SYMBOL is not specied, the behaviour depends on the type of feature. For points, nothing will be rendered. For lines, SYMBOL is only relevant if you want to style the lines using symbols, so the absence of SYMBOL means that you will get lines as specied using the relevant line rendering parameters (COLOR, WIDTH, PATTERN, LINECAP, ...). For polygons, the interior of the polygons will be rendered using a solid ll of the color specied in the COLOR parameter. See Also: SYMBOL WIDTH [double|attribute] WIDTH refers to the thickness of line work drawn, in layer SIZEUNITS. Default is 1.0. When scaling of symbols is in effect (SYMBOLSCALEDENOM is specied for the LAYER), WIDTH refers to the thickness of the line work in layer SIZEUNITS at the map scale 1:SYMBOLSCALEDENOM. If used with SYMBOL and OUTLINECOLOR, WIDTH species the width of the symbol outlines. This applies to SYMBOL TYPE vector (polygons), ellipse and truetype. For lines, WIDTH species the width of the line.
5.20. STYLE
167
For polygons, if used with OUTLINECOLOR, WIDTH species the thickness of the polygon outline. For a symbol of SYMBOL TYPE hatch, WIDTH species the thickness of the hatched lines. For its use with hatched lines, see Example #7 in the symbology examples. [attribute] was added in version 5.4 to specify the attribute to use for the width value. The hard brackets [] are required. Starting from version 5.4, the value can also be a decimal value (and not only integer).
5.21 SYMBOL
Symbol denitions can be included within the main map le or, more commonly, in a separate le. Symbol denitions in a separate le are designated using the SYMBOLSET keyword, as part of the MAP object. This recommended setup is ideal for re-using symbol denitions across multiple MapServer applications. There are 3 main types of symbols in MapServer: Markers, Lines and Shadesets. Symbol 0 is always the degenerate case for a particular class of symbol. For points, symbol 0 is a single pixel, for shading (i.e. lled polygons) symbol 0 is a solid ll, and for lines, symbol 0 is a single pixel wide line. Symbol denitions contain no color information, colors are set within STYLE objects. For MapServer versions < 5 there is a maximum of 64 symbols per le. This can be changed by editing mapsymbol.h and changing the value of MS_MAXSYMBOLS at the top of the le. As of MapServer 5.0 there is no symbol limit. More information can be found in the Construction of Cartographic Symbols document. ANTIALIAS [true|false] Should TrueType fonts be antialiased. Only useful for GD (gif) rendering. Default is false. Has no effect for the other renderers (where anti-aliasing can not be turned off). CHARACTER [char] Character used to reference a particular TrueType font character. Youll need to gure out the mapping from the keyboard character to font character. FILLED [true|false] If true, the symbol will be lled with a user dened color (using STYLE COLOR). Default is false. If true, symbols of TYPE ellipse and vector will be treated as polygons (ll color specied using STYLE COLOR and outline specied using STYLE OUTLINECOLOR and WIDTH). If false, symbols of TYPE ellipse and vector will be treated as lines (the lines can be given a color using STYLE COLOR and a width using STYLE WIDTH). FONT [string] Name of TrueType font to use as dened in the FONTSET. GAP [int] This keyword has been moved to STYLE in version 6.0. Deprecated since version 6.0. IMAGE [string] Image (GIF or PNG) to use as a marker or brush for type pixmap symbols. NAME [string] Alias for the symbol. To be used in CLASS STYLE objects. LINECAP [butt|round|square|triangle] This keyword has been moved to STYLE in version 6.0. Deprecated since version 6.0. LINEJOIN [round|miter|bevel] This keyword has been moved to STYLE in version 6.0. Deprecated since version 6.0. LINEJOINMAXSIZE [int] This keyword has been moved to STYLE in version 6.0. Deprecated since version 6.0. PATTERN [num on] [num off] [num on] ... END This keyword has been moved to STYLE in version 6.0. Deprecated since version 6.0.
168
Chapter 5. Maple
POINTS [x y] [x y] ... END Signies the start of a sequence of points that make up a symbol of TYPE vector or that dene the x and y radius of a symbol of TYPE ellipse. The end of this section is signied with the keyword END. The x and y values can be given using decimal numbers. The maximum x and y values dene the bounding box of the symbol. The size (actually height) of a symbol is dened in the STYLE. You can create non-contiguous paths by inserting -99 -99 at the appropriate places. x values increase to the right, y values increase downwards. For symbols of TYPE ellipse, a single point is specied that denes the x and y radius of the ellipse. Circles are created when x and y are equal. Note: If a STYLE using this symbol doesnt contain an explicit size, then the default symbol size will be based on the range of y values in the point coordinates. e.g. if the y coordinates of the points in the symbol range from 0 to 5, then the default size for this symbol will be assumed to be 5. STYLE [num on] [num off] [num on] ... END Renamed to PATTERN in MapServer 5.0. Deprecated since version 5.0. TRANSPARENT [color index] Sets a transparent color for the input image for pixmap symbols, or determines whether all shade symbols should have a transparent background. For shade symbols it may be desirable to have background features show through a transparent hatching pattern, creating a more complex map. By default a symbols background is the same as the parent image (i.e. color 0). This is user congurable. Note: The default (AGG) renderer does not support the TRANSPARENT parameter. It is supported by the GD renderer (GIF). TYPE [ellipse|hatch|pixmap|simple|truetype|vector] ellipse: radius values in the x and y directions dene an ellipse. hatch: produces hatched lines throughout the (polygon) shape. pixmap: a user supplied image will be used as the symbol. simple: default symbol type (1 pixel point, 1 pixel line, solid ll). truetype: TrueType font to use as dened in the MAP FONTSET. vector: a vector drawing is used to dene the shape of the symbol.
5.22 Symbology Examples

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Author Hvard Tveite Contact havard.tveite at umb.no Date $Date: 2011-08-28 02:51:27 -0700 (Sun, 28 Aug 2011) $ Revision $Revision: 12501 $ Last Updated 2011/05/11
5.22. Symbology Examples
169
Table of Contents Symbology Examples Example 1. Dashed Line Example 2. TrueType font marker symbol Example 3. Vector triangle marker symbol Example 4. Non-contiguous vector marker symbol (Cross) Example 5. Circle vector symbol Example 6. Downward diagonal ll Example 7. Using the Symbol Type HATCH (new in 4.6) Example 8. Styled lines using GAP
5.22.1 Example 1. Dashed Line

This example creates a dashed line that is 5 SIZEUNITS wide, with 10 SIZEUNITS on, 5 off, 5 on, 10 off ...
LAYER ... CLASS ... STYLE COLOR 0 0 0 WIDTH 5 LINECAP butt PATTERN 10 5 5 10 END END END END
5.22.2 Example 2. TrueType font marker symbol

This example symbol is a star, used to represent the national capital, hence the name. The font name in dened in the FONTSET le. The code number 114 varies, you can use MS Windows character map to gure it out, or guestimate.
SYMBOL NAME "natcap" TYPE TRUETYPE FONT "geo" FILLED true ANTIALIAS true # only necessary for GD rendering CHARACTER "r" END
5.22.3 Example 3. Vector triangle marker symbol

This example is fairly straight forward. Note that to have 3 sides you need 4 points, hence the rst and last points are identical. The triangle is not lled.
SYMBOL NAME "triangle" TYPE vector
170
Chapter 5. Maple
POINTS 0 4 2 0 4 4 0 4 END END
5.22.4 Example 4. Non-contiguous vector marker symbol (Cross)

This example draws a cross, that is 2 lines (vectors) that are not connected end-to-end (Like the triangle in the previous example). The negative values separate the two.
SYMBOL NAME "cross" TYPE vector POINTS 2.0 0.0 2.0 4.0 -99 -99 0.0 2.0 4.0 2.0 END END
5.22.5 Example 5. Circle vector symbol

This example creates a simple lled circle. Using non-equal values for the point will give you an actual ellipse.
SYMBOL NAME "circle" TYPE ellipse FILLED true POINTS 1 1 END END
5.22.6 Example 6. Downward diagonal ll

This example creates a symbol that can be used to create a downward diagonal ll for polygons.
SYMBOL NAME "downwarddiagonalfill" TYPE vector TRANSPARENT 0 POINTS 0 1 1 0 END END
5.22. Symbology Examples
171
5.22.7 Example 7. Using the Symbol Type HATCH (new in 4.6)

As of MapServer 4.6, you can use the symbol type HATCH to produce hatched lines. The following will display hatched lines at a 45 degree angle, 10 SIZEUNITS apart (center to center), and 3 SIZEUNITS wide. Symbol denition:
SYMBOL NAME hatch-test TYPE HATCH END
Layer denition:
LAYER ... CLASS ... STYLE SYMBOL hatch-test COLOR 255 0 0 ANGLE 45 SIZE 10 WIDTH 3 END END END
Other parameters available for HATCH are: MINSIZE, MAXSIZE, MINWIDTH, and MAXWIDTH.
5.22.8 Example 8. Styled lines using GAP

This example shows how to style lines with symbols. A 5 SIZEUNITS wide black line is decorated with ellipses that are 15 SIZEUNITS long (and 7.5 SIZEUNITSwide). The ellipses are placed 30 SIZEUNITS apart, and the negative GAP value ensures that the ellipses are oriented relative to the direction of the line. The ellipses are rotated 30 degrees counter clock-wise from their position along the line. Symbol denition:
SYMBOL NAME "ellipse2" TYPE ellipse FILLED true POINTS 1 2 END END
Layer denition:
LAYER ... CLASS ... STYLE WIDTH 5 COLOR 0 0 0 END STYLE
172
Chapter 5. Maple
SYMBOL ellipse2 COLOR 0 0 0 ANGLE 30 SIZE 15 GAP -30 END END END
5.23 Templating
Author Frank Koormann Contact frank.koormann at intevation.de Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Revision $Revision: 12583 $ Date $Date: 2011-09-24 13:29:22 -0700 (Sat, 24 Sep 2011) $ Table of Contents Templating Introduction Format Example Template
5.23.1 Introduction
Templates are used: to dene the look of a MapServer CGI application interface and to present the results of a query. They guide the presentation of results, either a query or a map, to the user. Templates are almost always HTML les although they can also be a URL (e.g.. http://www.somewhere.com/[ATTRIBUTE]/info.html). URL templates can only be used with simple QUERY or ITEMQUERY results so many substitutions dened below are not available for them. Simple pan/zoom interfaces use a single template le while complicated queries often require many templates. Templates often use JavaScript to enhance the basic interface. Notes Templates must contain the magic string mapserver template in the rst line of the template. Often this takes the form of an HTML, javascript or XML comment. This line is not written to the client. The magic string is not case sensitive. All CGI parameters can be referenced in template substitutions, MapServer specic parameters as well as user dened ones. In principle parameters are handed through by the MapServer 1:1. This feature is essential for implementing MapServer applications.
5.23. Templating
173
The reference below only lists special template substitution strings which are needed to obtain information modied by the MapServer, e.g. a new scale, query results, etc. Template substitution strings are case sensitive. Attribute item substitutions must be the same case as the item names in the dbase le. ArcView and ArcInfo generally produce dbase les with item names that are all uppercase. Appropriate URL encoding (i.e. to +) is applied when templates are URLs. Some substitutions are also available in escaped form (i.e. URL encoded). As an example this is needed when generating links within a template. This might pass the current mapextent to a new MapServer call. [mapext] is substituted by a space delimited set of lower left and upper right coordinates. This would break the URL. [mapext_esc] is substituted by a proper encoded set.
5.23.2 Format
Templates are simply HTML les or URL strings that contains special characters that are replaced by mapserv each time the template is processed. The simple substitution allows information such as active layers or the spatial extent to be passed from the user to mapserv and back again. Most often the new values are dumped into form variables that will be passed on again. The list of special characters and form variables is given below. HTML templates can include just about anything including JavaScript and Java calls. In HTML les, the attribute values can be inside quotes(). Writing attribute values inside quotes allows you to set special characters in value that you couldnt use normaly (ie: ],=, and space). To write a single quote in a attribute value, just use two quotes (). General [date] Outputs the date (as per the web servers clock). The default format is the same as is used by Apaches Common Log format, which looks like:
01/Dec/2010:17:34:58 -0800
Available arguments: format= A format string as supported by the standard C strftime() function. As an example, the default format is dened as:
[date format="%d/%b/%Y:%H:%M:%S %z"]
tz= timezone to use for the date returned. Default is local. Valid values are: gmt Output date will be Greenwich time local Output the time in the web servers local time zone. Additionally or alternatively, the %z and %Z strftime format strings allow the timezone offset or name to be output. [version] The MapServer version number. [id] Unique session id. The id can be passed in via a form but is more commonly generated by the software. In that case the id is a concatenation of UNIX time (or NT equivalent) and the process id. Unless youre getting more requests in a second than the system has process ids the id can be considered unique. ;-> [host] Hostname of the web server. [port] Port the web server is listening to.
174
Chapter 5. Maple
[post or get variable name], [post or get variable name_esc] The contents of any variables passed to the MapServer, whether they were used or not, can be echoed this way. One use might be to have the user set a map title or north arrow style in an interactive map composer. The system doesnt care about the values, but they might be real important in creating the nal output, e.g. if you specied a CGI parameter like myvalue=.... you can access this in the template le with [myvalue]. Also available as escaped version. [web_meta data key],[web_meta data key_esc] Web object meta data access (e.g [web_projection] Also available as escaped version. [errmsg], [errmsg_esc] Current error stack output. Various error messages are delimited by semi-colons. Also available as escaped version. File Reference [img] Path (relative to document root) of the new image, just the image name if IMAGE_URL is not set in the maple. In a map interface template, [img] is substituted with the path to the map image. In a query results template, it is substituted with the path to the querymap image (if a QUERYMAP object is dened in the Maple). [ref] Path (relative to document root) of the new reference image. [legend] Path (relative to document root) of new legend image rendered by the MapServer. Since version 3.5.1 a new HTML Legend template is provided by MapServer. If a template is dened in the Maple the [legend] string is replaced by the processed legend as. See the HTML Legends with MapServer for details. [scalebar] Path (relative to document root) of new scalebar image. [queryle] Path to the query le (if savequery was set as a CGI Parameter). [map] Path to the map le (if savemap was set as a CGI Parameter). Image Geometry [center] Computed image center in pixels. Useful for setting imgxy form variable when map sizes change. [center_x], [center_y] Computed image center X or Y coordinate in pixels. [mapsize], [mapsize_esc] Current image size in cols and rows (separated by spaces). Also available as escaped version. [mapwidth], [mapheight] Current image width or height. [scaledenom] Current image scale. The exact value is not appropriate for user information but essential for some applications. The value can be rounded e.g. using JavaScript or server side post processing. [scale] - deprecated Since MapServer 5.0 the proper parameter to use is [scaledenom] instead. The deprecated [scale] is the current image scale. The exact value is not appropriate for user information but essential for some applications. The value can be rounded e.g. using JavaScript or server side post processing. [cellsize] Size of an pixel in the current image in map units. Useful for distance measurement tools in user interfaces.
5.23. Templating
175
Map Geometry [mapx], [mapy] X and Y coordinate of mouse click. [mapext], [mapext_esc] Full mapextent (separated by spaces). Also available as escaped version. (mapext_esc is deprecated in MapServer 5.2. You should use the escape= argument instead) The default template [mapext] returns coordinates in the format of: mixx miny maxx maxy Available arguments: escape= Escape the coordinates returned. Default is none. Valid values are: url Use URL escape codes to encode the coordinates returned. none Do not escape. expand= Expand the bounds of the extents by a specic value. Specied in map coordinates. For example, [mapext] might return:
123456 123456 567890 567890
and [mapext expand=1000] would therefore return:

122456 122456 568890 568890
format= Format of the coordinates. Default is $minx $miny $maxx $maxy. For example, to add commas to the coordinates you would use:
[mapext format="$minx,$miny,$maxx,$maxy"]
precision= The number of decimal places to output for coordinates (default is 0). [minx], [miny], [maxx], [maxy] Minimum / maximum X or Y coordinate of new map extent. [dx], [dy] The differences of minimum / maximum X or Y coordinate of new map extent. Useful for creating cachable extents (i.e. 0 0 dx dy) with legends and scalebars [rawext], [rawext_esc] Raw mapextent, that is the extent before tting to a window size (separated by spaces). In cases where input came from imgbox (via Java or whatever) rawext refers to imgbox coordinates transformed to map units. Useful for spatial query building. Also available as escaped version. (rawext_esc is deprecated in MapServer 5.2. You should use the escape= argument instead) The default template [rawext] returns coordinates in the format of: mixx miny maxx maxy Available arguments: escape= Escape the coordinates returned. Default is none. Valid values are: url Use URL escape codes to encode the coordinates returned. none Do not escape. expand= Expand the bounds of the extents by a specic value. Specied in map coordinates. For example, [rawext] might return:
123456 123456 567890 567890
and [rawext expand=1000] would therefore return:
176
Chapter 5. Maple
122456 122456 568890 568890
[rawext format="$minx,$miny,$maxx,$maxy"]
precision= The number of decimal places to output for coordinates (default is 0). [rawminx], [rawminy], [rawmaxx], [rawmaxy] Minimum / maximum X or Y coordinate of a raw map/search extent. The following substitutions are only available if the MapServer was compiled with PROJ support and a PROJECTION is dened in the Maple. [maplon], [maplat] Longitude / latitude value of mouse click. Available only when projection enabled. [mapext_latlon], [mapext_latlon_esc] Full mapextent (separated by spaces). Available only when projection enabled. Also available as escaped version. (mapext_latlon_esc is deprecated in MapServer 5.2. You should use the escape= argument instead) The default template [mapext_latlon] returns coordinates in the format of: mixx miny maxx maxy Available arguments: escape= Escape the coordinates returned. Default is none. Valid values are: url Use URL escape codes to encode the coordinates returned. none Do not escape. expand= Expand the bounds of the extents by a specic value. Specied in map coordinates. For example, [mapext_latlon] might return:
123456 123456 567890 567890
and [mapext_latlon expand=1000] would therefore return:

122456 122456 568890 568890
[mapext_latlon format="$minx,$miny,$maxx,$maxy"]
precision= The number of decimal places to output for coordinates (default is 0). [minlon], [minlat], [maxlon] [maxlat] Minimum / maximum longitude or latitude value of mapextent. Available only when projection enabled. [refext], [refext_esc] Reference map extent (separated by spaces). This template has been added with version 4.6 on behalf of an enhancement request. See the thread in the MapServer ticket#1102 for potential use cases. Also available as escaped version. (refext_esc is deprecated in MapServer 5.2. You should use the escape= argument instead) The default template [refext] returns coordinates in the format of: mixx miny maxx maxy Available arguments: 5.23. Templating 177
escape= Escape the coordinates returned. Default is none. Valid values are: url Use URL escape codes to encode the coordinates returned. none Do not escape. expand= Expand the bounds of the extents by a specic value. Specied in map coordinates. For example, [refext] might return:
123456 123456 567890 567890
and [refext expand=1000] would therefore return:

122456 122456 568890 568890
[refwext format="$minx,$miny,$maxx,$maxy"]
precision= The number of decimal places to output for coordinates (default is 0). Layer [layers] | [layers_esc] All active layers space delimited. Used for a POST request. Also available as escaped version. [toggle_layers] | [toggle_layers_esc] List of all layers that can be toggled, i.e. all layers dened in the Maple which status is currently not default. Also available as escaped version. [layername_check | select] Used for making layers persistent across a map creation session. String is replaced with the keyword checked, selected or if layername is on. Layername is the name of a layer as it appears in the Maple. Does not work for default layers. [layername_meta data key] Layer meta data access (e.g. [streets_build] the underscore is essential). Zoom [zoom_minzoom to maxzoom_check|select] Used for making the zoom factor persistent. Zoom values can range from -25 to 25 by default. The string is replaced with the HTML keyword checked, selected or depending on the current zoom value. E.g. if the zoom is 12, a [zoom_12_select] is replaced with selected, while a [zoom_13_select] in the same HTML template le is not. [zoomdir_-1|0|1_check|select] Used for making the zoom direction persistent. Use check with a radio control or select with a selection list. See the demo for an example. The string is replaced with the HTML keyword checked, selected or depending on the current value of zoomdir.
178
Chapter 5. Maple
Query The following substitutions are only available when the template is processed as a result of a query. [shpext], [shpext_esc] Extent of current shape plus a 5 percent buffer. Available only when processing query results. The default template [shpext] returns coordinates in the format of: mixx miny maxx maxy Available arguments: escape= Escape the coordinates returned. Default is none. Valid values are: url Use URL escape codes to encode the coordinates returned. none Do not escape. expand= Expand the bounds of the extents by a specic value. Specied in map coordinates. For example, [shpext] might return:
123456 123456 567890 567890
and [shpext expand=1000] would therefore return:

122456 122456 568890 568890
[shpext format="$minx,$miny,$maxx,$maxy"]
precision= The number of decimal places to output for coordinates (default is 0). [shpminx], [shpminy], [shpmaxx], [shpmaxy] Minimum / maximum X or Y coordinate of shape extent. Available only when processing query results. [shpmid] Middle of the extent of current shape. Available only when processing query results. [shpmidx], [shpmidy] X or Y coordinate of middle of the extent of the current shape. Available only when processing query results. [shpidx] Index value of the current shape. Available only when processing query results. [shpclass] Classindex value of the current shape. Available only when processing query results. [shpxy formatting options] The list of shape coordinates, with list formatting options, especially useful for SVG. The default template [shpxy] returns a comma separated list of space delimited of coordinates (i.e. x1 y1, x2 y2, x3 y3). Available only when processing query results. Available attributes (h = header, f=footer, s=separator): buffer=, Buffer size, currently the only unit available is pixels. Default is 0. centroid= Should only the centroid of the shape be used? true or false (case insensitive). Default is false. cs= Coordinate separator. Default is ,. irh=, irf=, orh=, orf=
5.23. Templating
179
Characters to be put before (irh) and after (irf ) inner rings, and before (orh) and after (orf ) outer rings of polygons with holes. Defaults are . Note: Within each polygon, the outer ring is always output rst, followed by the inner rings. If neither irh nor orh are set, rings are output as parts using ph/pf /ps. ph=, pf=, ps= Characters to put before (ph) and after (pf ) and separators between (ps) feature parts (e.g. rings of multigeometries). Defaults are ph=, pf= and ps= . precision= The number of decimal places to output for coordinates. Default is 0. proj= The output projection denition for the coordinates, a special value of image will convert to image coordinates. Default is none. scale=, scale_x=, scale_y= Scaling factor for coordinates: Both axes (scale), x axis (scale_x) and y axis (scale_y). Defaults are 1.0. sh=, sf= Characters to put before (sh) and after (sf ) a feature. Defaults are . xh=, xf= Characters to put before (xh) and after (xf ) the x coordinates. Defaults are xh= and xf=,). yh= yf= Characters to put before (yh) and after (yf ) the y coordinates. Defaults are . As a simple example:
[shpxy xh="(" yf=")"] will result in: (x1 y1),(x2 y2),(x3 y3)
And a more complicated example of outputting KML for multipolygons which may potentially have holes (note that the parameters must all be on one line):
<MultiGeometry> <Point> <coordinates>[shplabel proj=epsg:4326 precision=10],0</coordinates> </Point> [shpxy ph="<Polygon><tessellate>1</tessellate>" pf="</Polygon>" xf="," xh=" " yh=" " yf=",0 " orh="<outerBoundaryIs><LinearRing><coordinates>" orf="</coordinates></LinearRing></outerBoundaryIs>" irh="<innerBoundaryIs><LinearRing><coordinates>" irf="</coordinates></LinearRing></innerBoundaryIs>" proj=epsg:4326 precision=10] </MultiGeometry>
[tileindex] Index value of the current tile. If no tiles used for the current shape this is replaced by -1. Available only when processing query results. [item formatting options] An attribute table item, with list formatting options. The name attribute is required. Available only when processing query results. Available attributes: name = The name of an attribute, case insenstive. (required) precision = The number of decimal places to use for numeric data. Use of this will force display as a number and will lead to unpredicable results with non-numeric data. pattern = Regular expression to compare the value of an item against. The tag is output only if there is a match. uc = Set this attribute to true to convert the attribute value to upper case. lc = Set this attribute to true to convert the attribute value to lower case.
180
Chapter 5. Maple
commify = Set this attribute to true to add commas to a numeric value. Again, only useful with numeric data. escape = Default escaping is for HTML, but you can escape for inclusion in a URL (=url), or not escape at all (=none). format = A format string used to output the attribute value. The token $value is used to place the value in a more complex presentation. Default is to output only the value. nullformat = String to output if the attribute value is NULL, empty or doesnt match the pattern (if dened). If not set and any of these conditions occur the item tag is replaced with an empty string. As a simple example:
[item name="area" precision="2" commify="2" format="Area is $value"]
[attribute name],[attrribute name_esc],[attribute item name_raw] Attribute name from the data table of a queried layer. Only attributes for the active query layers are accessible. Case must be the same as what is stored in the data le. ArcView, for example, uses all caps for shapele eld names. Available only when processing query results. By default the attributes are encoded especially for HTML representation. In addition the escaped version (for use in URLs) as well as the raw data is available. [Join name_attribute name],[Join name_attribute name_esc], [Join name_attribute name_raw] One-to-one joins: First the join name (as specied in the Maple has to be given, second the tables elds can be accessed similar to the layers attribute data. Available only when processing query results. By default the attributes are encoded especially for HTML representation. In addition the escaped version (for use in URLs) as well as the raw data is available. [join_Join name] One-to-many joins: The more complex variant. If the join type is multiple (one-to-many) the template is replaced by the set of header, template le and footer specied in the Maple. [metadata_meta data key], [metadata_meta data key_esc] Queried data_projection] Also available as escaped version. For query modes that allow for multiple result sets, the following string substitutions are available. For FEATURESELECT and FEATURENSELECT modes the totals a re adjusted so as not to include the selection layer. The selection layer results ARE available for display to the user. [nr] Total number of results. Useful in web header and footers. Available only when processing query results. [nl] Number of layers returning results. Useful in web header and footers. Available only when processing query results. [nlr] Total number of results within the current layer. Useful in web header and footers. Available only when processing query results. [rn] Result number within all layers. Starts at 1. Useful in web header and footers. Available only when processing query results. [lrn] Result number within the current layer. Starts at 1. Useful in query templates. Available only when processing query results. [cl] Current layer name. Useful in layer headers and footers. Available only when processing query results. layer meta data access (e.g [meta-
5.23. Templating
181
5.23.3 Example Template

A small example to give an idea how to work with templates. Note that it covers MapServer specic templates (e.g. the [map], [mapext]) and user dened templates (e.g. [htmlroot] or [program]) used to store application settings.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/transitional.dtd"> <html> <head> <title>MapServer Template Sample</title> </head> <body> MapServer Template Sample<br>  <form method="GET" action="[program]">  <table border=0 cellpadding=5> <tr>  <td align=center>  <input type="image" name="img" src="[img]" style="border:0;width:300;height:400"> <br>  <img src="[scalebar]" alt="Scale Bar"> </td>  <td valign=top>  <b>Map Controls</b><br> Set your zoom option:<br> <select name="zoom" size="1"> <option value="2" [ z o o m _ 2 _ s e l e c t ] > Zoom in 2 times <option value="1" [ z o o m _ 1 _ s e l e c t ] > Recenter Map
-->
<option value="-2" [ z o o m _ - 2 _ s e l e c t ] > Zoom out 2 times </select> <br>  <b>Legend</b><br>
182
Chapter 5. Maple
54 55 56 57 58 59 60 61 62 63 64 65 66
<img src="[legend]" alt="Legend"><br><br><br><br>  <input type="image" name="ref" src="[ref]" style="border:0;width:150;height:150"> </td> </tr> </table> </form> </body> </html>
5.24 Union Layer

Author Tamas Szekeres Contact szekerest at gmail.com Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Last Updated 2011-04-11 Table of Contents Union Layer Description Requirements Maple Conguration Feature attributes Classes and Styles Projections Examples * Maple Example * PHP MapScript Example
5.24.1 Description
Since version 6.0, MapServer has the ability to display features from multiple layers (called source layers) in a single maple layer. This feature was added through MS RFC 68: Support for combining features from multiple layers.
5.24.2 Requirements
This is a native MapServer option that doesnt use any external libraries to support it.
5.24.3 Maple Conguration

The CONNECTIONTYPE parameter must be set to UNION.
5.24. Union Layer
183
The CONNECTION parameter must contain a comma separated list of the source layer names. All of the source layers and the union layer must be the same TYPE (e.g. all must be TYPE POINT, or all TYPE POLYGON etc.) Note: You may wish to disable the visibility (change their STATUS) of the source layers to avoid displaying the features twice. For example:
LAYER NAME "union-layer" TYPE POINT STATUS DEFAULT CONNECTIONTYPE U N I ON CONNECTION "layer1,layer2,layer3" # reference to the source layers PROCESSING "ITEMS=itemname1,itemname2,itemname3" ... END LAYER NAME "layer1" TYPE POINT STATUS OFF CONNECTIONTYPE OGR CONNECTION ... ... END LAYER NAME "layer2" TYPE POINT STATUS OFF CONNECTIONTYPE S H A P E CONNECTION ... ... END LAYER NAME "layer3" TYPE POINT STATUS OFF CONNECTIONTYPE S H A P E CONNECTION ... ... END
5.24.4 Feature attributes

In the LAYER denition you may refer to any attributes supported by each of the source layers. In addition to the source layer attributes the union layer provides the following additional attributes: 1. Combine:SourceLayerName - The name of the source layer the feature belongs to 2. Combine:SourceLayerGroup - The group of the source layer the feature belongs to During the selection / feature query operations only the Combine:SourceLayerName and Combine:SourceLayerGroup attributes are provided by default. The set of the provided attributes can manually be overridden (and further attributes can be exposed) by using the ITEMS processing option (refer to the example above).
184
Chapter 5. Maple
5.24.5 Classes and Styles

We can dene the symbology and labelling for the union layers in the same way as for any other layer by specifying the classes and styles. In addition the STYLEITEM AUTO option is also supported for the union layer, which provides to display the features as specied at the source layers. The source layers may also use the STYLEITEM AUTO setting if the underlying data source provides that.
5.24.6 Projections
For speed, it is recommended to always use the same projection for the union layer and source layers. However MapServer will reproject the source layers to the union layer if requested. (for more information on projections in MapServer refer to PROJECTION)
5.24.7 Examples
Maple Example The follow example contains 3 source layers in different formats, and one layer (yellow) in a different projection. The union layer uses the STYLEITEM AUTO parameter to draw the styles from the source layers. (in this case MapServer will reproject the yellow features, in EPSG:4326, for the union layer, which is in EPSG:3978).
MAP ... PROJECTION "init=epsg:3978" END ...
5.24. Union Layer
185
LAYER NAME unioned TYPE POLYGON STATUS DEFAULT CONNECTIONTYPE U N I ON CONNECTION "red,green,yellow" STYLEITEM "AUTO" # Define an empty class that will be filled at runtime from the color and # styles read from each source layer. CLASS END PROJECTION "init=epsg:3978" END END LAYER NAME red TYPE POLYGON STATUS OFF DATA nb.shp CLASS NAME red STYLE OUTLINECOLOR 0 0 0 COLOR 255 85 0 END END END LAYER NAME green TYPE POLYGON STATUS OFF CONNECTIONTYPE OGR CONNECTION ns.mif CLASS NAME green STYLE OUTLINECOLOR 0 0 0 COLOR 90 218 71 END END END LAYER NAME yellow TYPE POLYGON STATUS OFF CONNECTIONTYPE OGR CONNECTION pei.gml CLASS NAME yellow STYLE OUTLINECOLOR 0 0 0 COLOR 255 255 0 END END
186
Chapter 5. Maple
PROJECTION "init=epsg:4326" END END END # Map
PHP MapScript Example

<?php // open map $oMap = ms_newMapObj( "D:/ms4w/apps/osm/map/osm.map" ); // create union layer $oLayer = ms_newLayerObj($oMap); $oLayer->set("name", "unioned"); $oLayer->set("type", MS_LAYER_POLYGON); $oLayer->set("status", MS_ON); $oLayer->setConnectionType(MS_UNION); $oLayer->set("connection", "red,green,yellow"); $oLayer->set("styleitem", "AUTO"); $oLayer->setProjection("init=epsg:3978"); // create empty class $oClass = ms_newClassObj($oLayer); ... ?>
5.25 Variable Substitution

Syntax: % + variable name + % See Also: Run-time Substitution. Example 1. Connecting securely to a Spatial Database You want to map some senstitive data held in a PostGIS database. The username and password to be used for the database connection are held in 2 cookies previously set by a seperate authentication mechanism, uid and passwd.
CONNECTION "user=%uid% password=%passwd% dbname=postgis"
Example 2. Handling temporary les You have a user based discovery application that generates shapeles and stores them in a users home directory on the server. The username comes from a cookie, the lename comes from a request parameter.
DATA "/home/%username%/tempshp/%filename%"
This feature is only available in the CGI version of MapServer through a maple pre-processor. If you are using MapScript, you will have to code the substitution logic into your application yourself (By writing your own preprocessor).
5.25. Variable Substitution
187
5.26 WEB
BROWSEFORMAT [mime-type] Format of the interface output, using MapServer CGI. (added to MapServer 4.8.0) The default value is text/html. Example:
BROWSEFORMAT "image/svg+xml"
EMPTY [url] URL to forward users to if a query fails. If not dened the value for ERROR is used. ERROR [url] URL to forward users to if an error occurs. Ugly old MapServer error messages will appear if this is not dened FOOTER [lename] Template to use AFTER anything else is sent. Multiresult query modes only. HEADER [lename] Template to use BEFORE everything else has been sent. Multiresult query modes only. IMAGEPATH [path] Path to the temporary directory fro writing temporary les and images. Must be writable by the user the web server is running as. Must end with a / or depending on your platform. IMAGEURL [path] Base URL for IMAGEPATH. This is the URL that will take the web browser to IMAGEPATH to get the images. LEGENDFORMAT [mime-type] Format of the legend output, using MapServer CGI. (added to MapServer 4.8.0) The default value is text/html. Example:
LEGENDFORMAT "image/svg+xml"
LOG [lename] Since MapServer 5.0 the recommeded parameters to use for debugging are the MAP objects CONFIG and DEBUG parameters instead (see the Debugging MapServer document). File to log MapServer activity in. Must be writable by the user the web server is running as. Deprecated since version 5.0. MAXSCALEDENOM [double] Minimum scale at which this interface is valid. When a user requests a map at a smaller scale, MapServer automatically returns the map at this scale. This effectively prevents user from zooming too far out. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MAXSCALE parameter. See Also: Map scale MAXSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is MAXSCALEDENOM instead. The deprecated MAXSCALE is the minimum scale at which this interface is valid. When a user requests a map at a smaller scale, MapServer automatically returns the map at this scale. This effectively prevents user from zooming too far out. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. MAXTEMPLATE [le|url] Template to be used if below the minimum scale for the app (the denominator of the requested scale is larger than MAXSCALEDENOM), useful for nesting apps. METADATA This keyword allows for arbitrary data to be stored as name value pairs. This is used with OGC WMS to dene things such as layer title. It can also allow more exibility in creating templates, as anything you put in here will be accessible via template tags. Example:
METADATA title "My layer title" author "Me!" END
MINSCALEDENOM [double] Maximum scale at which this interface is valid. When a user reqests a map at a larger scale, MapServer automatically returns the map at this scale. This effectively prevents the user from zooming
188
Chapter 5. Maple
in too far. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the deprecated MINSCALE parameter. See Also: Map scale MINSCALE [double] - deprecated Since MapServer 5.0 the proper parameter to use is MINSCALEDENOM instead. The deprecated MINSCALE is the maximum scale at which this interface is valid. When a user reqests a map at a larger scale, MapServer automatically returns the map at this scale. This effectively prevents the user from zooming in too far. Scale is given as the denominator of the actual scale fraction, for example for a map at a scale of 1:24,000 use 24000. Deprecated since version 5.0. MINTEMPLATE Template to be used if above the maximum scale for the app (the denominator of the requested scale is smaller than MINSCALEDENOM), useful for nesting apps. QUERYFORMAT [mime-type] Format of the query output. (added to MapServer 4.8.0) This works for mode=query (using query templates in CGI mode), but not for mode=browse. The default value is text/html. Example:
QUERYFORMAT "image/svg+xml"
TEMPLATE [lename|url] Template le or URL to use in presenting the results to the user in an interactive mode (i.e. map generates map and so on ... ). URL is not a remote le, rather a template. For example:
TEMPLATE http://someurl/somescript.cgi?mapext=[mapext]
TEMPPATH Path for storing temporary les. If not set, the standard system temporary le path will be used (e.g. tmp for unix). TEMPPATH can also be set using the environment variable MS_TEMPPATH. TEMPPATH is used in many contexts (see rfc66). Make sure that that Mapserver has sufcient rights to read and write les at the specied location. New in version 6.0. VALIDATION Signals the start of a VALIDATION block. As of MapServer 5.4.0, VALIDATION blocks are the preferred mechanism for specifying validation patterns for CGI param runtime substitutions. See Run-time Substitution.
5.27 XML Maple support

MapServer is able to load XML maples automatically, without user XSLT tranformations. Basicly, MapServer will simply do an XSLT transformation when the maple passed to it is an XML one, convert it to a text maple in a temporary le on disk, then process the maple normally. New Dependencies libxslt libexslt
5.27.1 Enabling the support

You can enable the XML maple support by adding the following option: with-xml-maple. This congure option will enable the libxslt and libexslt check up. If your libxslt/libexslt are not installed in /usr, youll have to add the following options:
5.27. XML Maple support
189
--with-xslt=/path/to/xslt/installation --with-exslt=/path/to/exslt/installation
5.27.2 Usage:
In order to enable this feature, set the MS_XMLMAPFILE_XSLT environment variable to point to the location of the XSLT to use for the XML->text maple conversion. e.g. in Apache:
SetEnv MS_XMLMAPFILE_XSLT /path/to/mapfile.xsl PassEnv MS_XMLMAPFILE_XSLT
With this enabled, passing an .xml lename to the CGI map parameter will automatically trigger the conversion. Note: This is a rst step to XML maple loading support. Obviously, there is a cost to parse and translate the XML maple, but this allows easier use of XML maples.
5.28 Notes
The Maple is NOT case-sensitive. The Mapfile is read from top to bottom by MapServer; this means that LAYERs near the top of your Maple will be drawn before those near the bottom. Therefore users commonly place background imagery and other background layer types near the top of their maple, and lines and points near the bottom of their maple. Strings containing non-alphanumeric characters or a MapServer keyword MUST be quoted. It is recommended to put ALL strings in double-quotes. For MapServer versions < 5, there was a default maximum of 200 layers per maple (there is no layer limit with MapServer >= 5). This can be changed by editing the map.h le to change the value of MS_MAXLAYERS to the desired number and recompiling. Here are other important default limits when using a MapServer version < 5: MAXCLASSES 250 (set in map.h) MAXSTYLES 5 (set in map.h) MAXSYMBOLS 64 (set in mapsymbol.h) MapServer versions >= 5 have no limits for classes, styles, symbols, or layers. File paths may be given as absolute paths, or as paths relative to the location of the maple. In addition, data les may be specied relative to the SHAPEPATH. The maple has a hierarchical structure, with the MAP object being the root. All other objects fall under this one. Comments are designated with a #. Attributes are named using the following syntax: [ATTRIBUTENAME] ... Note that the name of the attribute included between the square brackets IS CASE SENSITIVE. Generally ESRI generated shapeles have their attributes (.dbf column names) all in upper-case for instance, and for PostGIS, ALWAYS use lower-case. MapServer Regular Expressions are used through the operating systems C Library. For information on how to use and write Regular Expressions on your system, you should read the documentation provided with your C Library. On Linux, this is GLibC, and you can read man 7 regex ... This man page is also available on most UNIXs. Since these RegExs are POSIX compliant, they should be the same on Windows as well, so windows users can try searching the web for man 7 regex since man pages are available all over the web.
190
Chapter 5. Maple
CHAPTER 6
MapScript
Release 6.0.1 Date July 18, 2011
6.1 Introduction
This is language agnostic documentation for the MapScript interface to MapServer generated by SWIG. This document is intended for developers and to serve as a reference for writers of more extensive, language specic documentation located at Maple
6.1.1 Appendices
Language-specic extensions are described in the following appendices Python Appendix
6.1.2 Documentation Elements

Classes will be documented in alphabetical order in the manner outlined below. Attributes and methods will be formatted as denition lists with the attribute or method as item, the type or return type as classier, and a concise description. To make the document as agnostic as possible, we refer to the following types: int, oat, and string. There are yet no mapscript methods that return arrays or sequences or accept array or sequence arguments. We will use the SWIG term immutable to indicate that an attributes value is read-only.
6.1.3 fooObj
A paragraph or two about class fooObj. fooObj Attributes attribute [type [access]] Concise description of the attribute.
191
Attribute name are completely lower case. Multiple words are packed together like outlinecolor. Note that because of the way that mapscript is generated many confusing, meaningless, and even dangerous attributes are creeping into objects. See outputFormatObj.refcount for example. Until we get a grip on the structure members we are exposing to SWIG this problem will continue to grow. fooObj Methods method(type mandatory_parameter [, type optional_parameter=default]) [type] Description of the method including elaboration on the method arguments, the methods actions, and returned values. Optional parameters and their default values are enclosed in brackets. Class method names are camel case with a leading lower case character like getExpressionString.
6.1.4 Additional Documentation

Theres no point in duplicating the MapServer Maple Reference, which remains the primary reference for mapscript class attributes.
6.2 SWIG MapScript API Reference

Author Sean Gillies Author Steve Lime Contact steve.lime at dnr.state.mn.us Author Frank Warmerdam Contact warmerdam at pobox.com Author Umberto Nicoletti Contact umberto.nicoletti at gmail.com Author Tamas Szekeres Contact szekerest at gmail.com Author Daniel Morissette Contact dmorisette at mapgears.com Revision $Revision: 12763 $ Date $Date: 2011-11-08 14:06:14 -0800 (Tue, 08 Nov 2011) $
192
Chapter 6. MapScript
Contents SWIG MapScript API Reference Introduction * Appendices * Documentation Elements * fooObj * Additional Documentation MapScript Functions MapScript Classes * classObj * colorObj * errorObj * fontSetObj * hashTableObj * imageObj * intarray * labelCacheMemberObj * labelCacheObj * labelObj * layerObj * legendObj * lineObj * mapObj * markerCacheMemberObj * outputFormatObj * OWSRequest * pointObj * projectionObj * rectObj * referenceMapObj * resultCacheMemberObj * resultCacheObj * scalebarObj * shapeleObj * shapeObj * styleObj * symbolObj * symbolSetObj * webObj
6.2.1 Introduction
This is language agnostic documentation for the mapscript interface to MapServer generated by SWIG. This document is intended for developers and to serve as a reference for writers of more extensive, language specic documentation in DocBook format for the MDP. Appendices Language-specic extensions are described in the following appendices Python MapScript Appendix
6.2. SWIG MapScript API Reference
193
Documentation Elements Classes will be documented in alphabetical order in the manner outlined below. Attributes and methods will be formatted as denition lists with the attribute or method as item, the type or return type as classier, and a concise description. To make the document as agnostic as possible, we refer to the following types: int, oat, and string. There are yet no mapscript methods that return arrays or sequences or accept array or sequence arguments. We will use the SWIG term immutable to indicate that an attributes value is read-only. fooObj A paragraph or two about class fooObj.
fooObj Attributes
attribute [type [access]] Concise description of the attribute. Attribute name are completely lower case. Multiple words are packed together like outlinecolor. Note that because of the way that mapscript is generated many confusing, meaningless, and even dangerous attributes are creeping into objects. See outputFormatObj.refcount for example. Until we get a grip on the structure members we are exposing to SWIG this problem will continue to grow.
fooObj Methods
method(type mandatory_parameter [, type optional_parameter=default]) [type] Description of the method including elaboration on the method arguments, the methods actions, and returned values. Optional parameters and their default values are enclosed in brackets. Class method names are camel case with a leading lower case character like getExpressionString. Additional Documentation Theres no point in duplicating the MapServer Maple Reference, which remains the primary reference for mapscript class attributes.
6.2.2 MapScript Functions

msCleanup() [void] msCleanup() attempts to recover all dynamically allocated resources allocated by MapServer code and dependent libraries. It it used primarily for nal cleanup in scripts that need to do memory leak testing to get rid of noise one-time allocations. It should not normally be used by production code. msGetVersion() [string] Returns a string containing MapServer version information, and details on what optional components are built in. The same report as produced by mapserv -v. msGetVersionInt() [int] Returns the MapServer version number (x.y.z) as an integer (x*10000 + y*100 + z). (New in v5.0) e.g. V5.4.3 would return 50403. msResetErrorList() [void] Clears the current error stack. msIO_installStdoutToBuffer() [void] Installs a mapserver IO handler directing future stdout output to a memory buffer.
194
msIO_installStdinFromBuffer() [void] Installs a mapserver IO handler directing future stdin reading (ie. post request capture) to come from a buffer. msIO_resetHandlers() [void] Resets the default stdin and stdout handlers in place of buffer based handlers. msIO_getStdoutBufferString() [string] Fetch the current stdout buffer contents as a string. This method does not clear the buffer. msIO_getStdoutBufferBytes() [binary data] Fetch the current stdout buffer contents as a binary buffer. The exact form of this buffer will vary by mapscript language (eg. string in Python, byte[] array in Java and C#, unhandled in perl) msIO_stripStdoutBufferContentType() [string] Strip the Content-type header off the stdout buffer if it has one, and if a content type is found it is return (otherwise NULL/None/etc). msIO_stripStdoutBufferContentHeaders(): void Strip all Content-* headers off the stdout buffer if it has ones.
6.2.3 MapScript Classes

classObj An instance of classObj is associated with with one instance of layerObj.
+-------+ 0..* 1 +-------+ | Class | <--------> | Layer | +-------+ +-------+
The other important associations for classObj are with styleObj, labelObj, and hashTableObj.
+-------+ 1 0..* +-------+ | Class | ---------> | Style | +-------+ +-------+ +-------+ 1 0..1 +-------+ | Class | ---------> | Label | +-------+ +-------+ +-------+ 1 1 +-----------+ | Class | ---------> | HashTable | +-------+ | -| | metadata | +-----------+
Multiple class styles are now supported in 4.1. See the styleObj section for details on use of multiple class styles.
classObj Attributes
debug [int] MS_TRUE or MS_FALSE keyimage [string] TODO Not sure what this attribute is for label [labelObj immutable] Denition of class labeling layer [layerObj immutable] Reference to the parent layer maxscaledenom [oat] The minimum scale at which class is drawn metadata [hashTableObj immutable] class metadata hash table. minscaledenom [oat] The maximum scale at which class is drawn 6.2. SWIG MapScript API Reference 195
name [string] Unique within a layer numstyles [int] Number of styles for class. In the future, probably the 4.4 release, this attribute will be made immutable. status [int] MS_ON or MS_OFF. Draw features of this class or do not. template [string] Template for queries title [string] Text used for legend labeling type [int] The layer type of its parent layer
classObj Methods
new classObj( [ layerObj parent_layer=NULL ] ) [classObj] Create a new child classObj instance at the tail (highest index) of the class array of the parent_layer. A class can be created outside the context of a parent layer by omitting the single constructor argument. clone( ) [classObj] Return an independent copy of the class without a parent layer. createLegendIcon( mapObj map, layerObj layer, int width, int height ) [imageObj] Draw and return a new legend icon. drawLegendIcon( mapObj map, layerObj layer, int width, int height, imageObj image, int dstx, int dsty ) [int] Draw the legend icon onto image at dstx, dsty. Returns MS_SUCCESS or MS_FAILURE. getExpressionString() [string] Return a string representation of the expression enclosed in the quote characters appropriate to the expression type. getFirstMetaDataKey() [string] Returns the rst key in the metadata hash table. With getNextMetaDataKey(), provides an opaque iterator over keys. Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj. getMetaData( string key ) [string] Return the value of the classObj metadata at key. Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj. getNextMetaDataKey( string lastkey ) [string] Returns the next key in the metadata hash table or NULL if lastkey is the last valid key. If lastkey is NULL, returns the rst key of the metadata hash table. Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj. getStyle( int index ) [styleObj] Return a reference to the styleObj at index in the styles array. See the styleObj section for more details on multiple class styles. getTextString() [string] Return a string representation of the text enclosed in the quote characters appropriate to the text expression type (logical or simple string). insertStyle( styleObj style [, int index=-1 ] ) [int] Insert a copy of style into the styles array at index index. Default is -1, or the end of the array. Returns the index at which the style was inserted. moveStyleDown( int index ) [int] Swap the styleObj at index with the styleObj index + 1. moveStyleUp( int index ) [int] Swap the styleObj at index with the styleObj index - 1. removeStyle( int index ) [styleObj] Remove the styleObj at index from the styles array and return a copy.
196
setExpression( string expression ) [int] Set expression string where expression is a MapServer regular, logical or string expression. Returns MS_SUCCESS or MS_FAILUIRE. setMetaData( string key, string value ) [int] Insert value into the classObj metadata at key. Returns MS_SUCCESS or MS_FAILURE. Note: setMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj. setText( string text ) [int] Set text string where text is a MapServer text expression. Returns MS_SUCCESS or MS_FAILUIRE. Note: Older versions of MapScript (pre-4.8) featured the an undocumented setText() method that required a layerObj be passed as the rst argument. That argument was completely bogus and has been removed. colorObj Since the 4.0 release, MapServer colors are instances of colorObj. A colorObj may be a lone object or an attribute of other objects and have no other associations.
colorObj Attributes
blue [int] Blue component of color in range [0-255] green [int] Green component of color in range [0-255] red [int] Red component of color in range [0-255] pen [int] Dont mess with this unless you know what you are doing! Note: Because of the issue with pen, setting colors by individual components is unreliable. Best practice is to use setRGB(), setHex(), or assign to a new instance of colorObj().
colorObj Methods
new colorObj( [ int red=0, int green=0, int blue=0, int pens=-4 ] ) [colorObj] Create a new instance. The color arguments are optional. setRGB( int red, int green, int blue ) [int] Set all three RGB components. MS_FAILURE. Returns MS_SUCCESS or
setHex( string hexcolor ) [int] Set the color to values specied in case-independent hexadecimal notation. Calling setHex(#ffffff) assigns values of 255 to each color component. Returns MS_SUCCESS or MS_FAILURE. toHex() [string] Complement to setHex, returning a hexadecimal representation of the color components. errorObj This class allows inspection of the MapServer error stack. Only needed for the Perl module as the other language modules expose the error stack through exceptions.
197
errorObj Attributes
code [int] MapServer error code such as MS_IMGERR (1). message [string] Context-dependent error message. routine [string] MapServer function in which the error was set.
errorObj Methods
next [errorObj] Returns the next error in the stack or NULL if the end has been reached. fontSetObj A fontSetObj is always a fontset attribute of a mapObj.
fontSetObj Attributes
lename [string immutable] Path to the fontset le on disk. fonts [hashTableObj immutable] Mapping of fonts. numfonts [int immutable] Number of fonts in set.
fontSetObj Methods
None hashTableObj A hashTableObj is a very simple mapping of case-insensitive string keys to single string values. Map, Layer, and Class metadata have always been hash hables and now these are exposed directly. This is a limited hash that can contain no more than 41 values.
hashTableObj Attributes
numitems [int immutable] Number of hash items.
hashTableObj Methods
clear( ) [void] Empties the table of all items. get( string key [, string default=NULL ] ) [string] Returns the value of the item by its key, or default if the key does not exist. nextKey( [string key=NULL] ) [string] Returns the name of the next key or NULL if there is no valid next key. If the input key is NULL, returns the rst key. remove( string key ) [int] Removes the hash item by its key. Returns MS_SUCCESS or MS_FAILURE. set( string key, string value ) [int] Sets a hash item. Returns MS_SUCCESS or MS_FAILURE. 198 Chapter 6. MapScript
imageObj An image object is a wrapper for GD and GDAL images.
imageObj Attributes
format [outputFormatObj immutable] Image format. height [int immutable] Image height in pixels. imagepath [string immutable] If image is drawn by mapObj.draw(), this is the mapObjs web.imagepath. imageurl [string immutable] If image is drawn by mapObj.draw(), this is the mapObjs web.imageurl. renderer [int] MS_RENDER_WITH_GD, MS_RENDER_WITH_SWF, MS_RENDER_WITH_RAWDATA, MS_RENDER_WITH_PDF, or MS_RENDER_WITH_IMAGEMAP. Dont mess with this! size [int immutable] To access this attribute use the getSize method. Note: the getSize method is inefcient as it does a call to getBytes and then computes the size of the byte array. The bytearray is then immediately discarded. In most cases it is more efcient to call getBytes directly. width [int immutable] Image width in pixels.
imageObj Methods
new imageObj( int width, int height [, outputFormatObj format=NULL [, string lename=NULL ] ] ) [imageObj] Create new instance of imageObj. If lename is specied, an imageObj is created from the le and any specied width, height, and format parameters will be overridden by values of the image in lename. Otherwise, if format is specied an imageObj is created using that format. See the format attribute above for details. If lename is not specied, then width and height should be specied. getBytes() [binary data] Returns the image contents as a binary buffer. The exact form of this buffer will vary by mapscript language (eg. string in Python, byte[] array in Java and C#, unhandled in perl) getSize() [int] Resturns the size of the binary buffer representing the image buffer. Note: the getSize method is inefcient as it does a call to getBytes and then computes the size of the byte array. The byte array is then immediately discarded. In most cases it is more efcient to call getBytes directly. save( string lename [, mapObj parent_map=NULL ] ) [int] Save image to lename. The optional parent_map parameter must be specied if saving GeoTIFF images. write( [ FILE le=NULL ] ) [int] Write image data to an open le descriptor or, by default, to stdout. Returns MS_SUCCESS or MS_FAILURE. Note: This method is current enabled for Python and C# only. C# supports writing onto a Stream object. User-contributed typemaps are needed for Perl, Ruby, and Java. Note: The free() method of imageObj has been deprecated. In MapServer revisions 4+ all instances of imageObj will be properly disposed of by the interpreters garabage collector. If the application cant wait for garabage collection, then the instance can simply be deleted or undefd. intarray An intarray is a utility class generated by SWIG useful for manipulating map layer drawing order. See mapObj::getLayersDrawingOrder for discussion of mapscript use and see http://www.swig.org/Doc1.3/Library.html#Library_nn5 for a complete reference. 6.2. SWIG MapScript API Reference 199
intarray Attributes
None
intarray Methods
new intarray( int numitems ) [intarray] Returns a new instance of the specied length. labelCacheMemberObj An individual feature label. The labelCacheMemberObj class is associated with labelCacheObj.
+------------------+ 0..* 1 +------------+ | LabelCacheMember | <--------- | LabelCache | +------------------+ +------------+
labelCacheMemberObj Attributes
classindex [int immutable] Index of the class of the labeled feature. featuresize [oat immutable] TODO label [labelObj immutable] Copied from the class of the labeled feature. layerindex [int immutable] The index of the layer of the labeled feature. numstyles [int immutable] Number of styles as for the class of the labeled feature. point [pointObj immutable] Label point. poly [shapeObj immutable] Label bounding box. shapeindex [int immutable] Index within shapele of the labeled feature. status [int immutable] Has the label been drawn or not? styles [styleObj immutable] TODO this should be protected from SWIG. text [string immutable] Label text. tileindex [int immutable] Tileindex of the layer of the labeled feature.
labelCacheMemberObj Methods
None. Note: No real scripting control over labeling currently, but there may be some interesting new possibilities if users have control over labeling text, position, and status. labelCacheObj Set of a maps cached labels. Has no other existence other than as a labelcache attribute of a mapObj. Associated with labelCacheMemberObj and markerCacheMemberObj.
200
+------------+ 1 0..* +-------------------+ | LabelCache | ---------> | LabelCacheMember | +------------+ + ----------------- + | MarkerCacheMember | +-------------------+
labelCacheObj Attributes
cachesize [int immutable] TODO markercachesize [int immutable] TODO numlabels [int immutable] Number of label members. nummarkers [int immutable] Number of marker members.
labelCacheObj Methods
freeCache( ) [void] Free the labelcache. labelObj A labelObj is associated with a classObj, a scalebarObj, or a legendObj.
+-------+ 0..1 1 +----------+ | Label | <--------- | Class | +-------+ | -------- | | Scalebar | | -------- | | Legend | +----------+
labelObj Attributes
angle [oat] TODO antialias [int] MS_TRUE or MS_FALSE autoangle [int] MS_TRUE or MS_FALSE autofollow [int] MS_TRUE or MS_FALSE. Tells mapserver to compute a curved label for appropriate linear features (see MS RFC 11: Support for Curved Labels for specics). autominfeaturesize: int MS_TRUE or MS_FALSE backgroundcolor [colorObj] Color of background rectangle or billboard. Deprecated since version 6.0: Use styleObj and geomtransform. backgroundshadowcolor [colorObj] Color of background rectangle or billboard shadow. Deprecated since version 6.0: Use styleObj and geomtransform. backgroundshadowsizex [int] Horizontal offset of drop shadow in pixels. Deprecated since version 6.0: Use styleObj and geomtransform. backgroundshadowsizey [int] Vertical offset of drop shadow in pixels. Deprecated since version 6.0: Use styleObj and geomtransform. 6.2. SWIG MapScript API Reference 201
buffer [int] Maybe this shouldve been named padding since thats what it is: padding in pixels around a label. color [colorObj] Foreground color. encoding [string] Supported encoding format to be used for labels. If the format is not supported, the label will not be drawn. Requires the iconv library (present on most systems). The library is always detected if present on the system, but if not the label will not be drawn. Required for displaying international characters in MapServer. More information can be found at: http://www.foss4g.org/FOSS4G/MAPSERVER/mpsnf-i18n-en.html. font [string] Name of TrueType font. force [int] MS_TRUE or MS_FALSE. maxsize [int] Maximum height in pixels for scaled labels. See symbolscale attribute of layerObj. mindistance [int] Minimum distance in pixels between duplicate labels. minfeaturesize [int] Features of this size of greater will be labeled. minsize [int] Minimum height in pixels. numstyles [int] Number of label styles offsetx [int] Horizontal offset of label. offsety [int] Vertical offset of label. outlinecolor [colorObj] Color of one point outline. partials [int] MS_TRUE (default) or MS_FALSE. Whether or not labels can ow past the map edges. position [int] MS_UL, MS_UC, MS_UR, MS_CL, MS_CC, MS_CR, MS_LL, MS_LC, MS_LR, or MS_AUTO. shadowcolor [colorObj] Color of drop shadow. shadowsizex [int] Horizontal offset of drop shadow in pixels. shadowsizey [int] Vertical offset of drop shadow in pixels. size [int] Annotation height in pixels. type [int] MS_BITMAP or MS_TRUETYPE. wrap [string] Character on which legend text will be broken to make multi-line legends.
labelObj Methods
getBinding( int binding ) [string] Get the attribute binding for a specied label property. Returns NULL if there is no binding for this property. getStyle( int index ) [styleObj] Return a reference to the styleObj at index in the styles array. insertStyle( styleObj style [, int index=-1 ] ) [int] Insert a copy of style into the styles array at index index. Default is -1, or the end of the array. Returns the index at which the style was inserted. moveStyleDown( int index ) [int] Swap the styleObj at index with the styleObj index + 1. moveStyleUp( int index ) [int] Swap the styleObj at index with the styleObj index - 1. removeStyle( int index ) [styleObj] Remove the styleObj at index from the styles array and return a copy. removeBinding( int binding ) [int] Remove the attribute binding for a specled label property. setBinding ( int binding, string item ) [int] Set the attribute binding for a specied label property. Binding constants look like this: MS_LABEL_BINDING_[attribute name].
202
setBinding(MS_LABEL_BINDING_COLOR, "FIELD_NAME_COLOR");
updateFromString ( string snippet ) [int] MS_SUCCESS/MS_FAILURE. layerObj
Update
label
from
string
snippet.
Returns
A layerObj is associated with mapObj. In the most recent revision, an intance of layerObj can exist outside of a mapObj.
+-------+ 0..* 0..1 +-----+ | Layer | <--------> | Map | +-------+ +-----+
The other important association for layerObj is with classObj

+-------+ 1 0..* +-------+ | Layer | <--------> | Class | +-------+ +-------+
and hashTableObj
+-------+ 1 1 +-----------+ | Layer | ---------> | HashTable | +-------+ | -| | metadata | +-----------+
layerObj Attributes
bandsitem [string] The attribute from the index le used to select the source raster band(s) to be used. Normally NULL for default bands processing. classitem [string] The attribute used to classify layer data. connection [string] Layer connection or DSN. connectiontype [int] See MS_CONNECTION_TYPE in mapserver.h for possible values. When setting the connection type setConnectionType() should be used in order to initialize the layer vtable properly. data [string] Layer data denition, values depend upon connectiontype. debug [int] Enable debugging of layer. MS_ON or MS_OFF (default). dump [int] Switch to allow mapserver to return data in GML format. MS_TRUE or MS_FALSE. Default is MS_FALSE. Deprecated since version 6.0: metadata is used instead. extent [rectObj] optional limiting extent for layer features. lteritem [string] Attribute dening lter. footer [string] TODO group [string] Name of a group of layers. header [string] TODO index [int immutable] Index of layer within parent maps layers array. labelangleitem [string] Attribute dening label angle.
203
labelcache [int] MS_ON or MS_OFF. Default is MS_ON. labelitem [string] Attribute dening feature label text. labelmaxscaledenom [oat] Minimum scale at which layer will be labeled. labelminscaledenom [oat] Maximum scale at which layer will be labeled. labelrequires [string] Logical expression. labelsizeitem [string] Attribute dening label size. map [mapObj immutable] Reference to parent map. maxfeatures [int] Maximum number of layer features that will be drawn. For shapele data this means the rst N features where N = maxfeatures. maxscaledenom [oat] Minimum scale at which layer will be drawn. metadata [hashTableObj immutable] Layer metadata. minscaledenom [oat] Maximum scale at which layer will be drawn. name [string] Unique identier for layer. numclasses [int immutable] Number of layer classes. numitems [int immutable] Number of layer feature attributes (items). numjoins [int immutable] Number of layer joins. numprocessing [int immutable] Number of raster processing directives. offsite [colorObj] transparent pixel value for raster layers. opacity [int] Layer opacity percentage in range [0, 100]. The special value of MS_GD_ALPHA (1000) indicates that the alpha transparency of pixmap symbols should be honored, and should be used only for layers that use RGBA pixmap symbols. postlabelcache [int] MS_TRUE or MS_FALSE. Default is MS_FALSE. requires [string] Logical expression. sizeunits [int] Units of class size values. MS_INCHES, MS_FEET, MS_MILES, MS_NAUTICALMILES, MS_METERS, MS_KILOMETERS, MS_DD or MS_PIXELS status [int] MS_ON, MS_OFF, or MS_DEFAULT. styleitem [string] Attribute dening styles. symbolscaledenom [oat] Scale at which symbols are default size. template [string] Template le. Note that for historical reasons, the query attribute must be non-NULL for a layer to be queryable. tileindex [string] Layer index le for tiling support. tileitem [string] Attribute dening tile paths. tolerance [oat] Search buffer for point and line queries. toleranceunits [int] MS_INCHES, MS_FEET, MS_KILOMETERS, MS_DD or MS_PIXELS MS_MILES, MS_NAUTICALMILES, MS_METERS,
transform [int] Whether or not layer data is to be transformed to image units. MS_TRUE or MS_FALSE. Default is MS_TRUE. Case of MS_FALSE is for data that are in image coordinates such as annotation points. type [int] See MS_LAYER_TYPE in mapserver.h.
204
units [int] Units of the layer. See MS_UNITS in mapserver.h.
layerObj Methods
new layerObj( [ mapObj parent_map=NULL ] ) [layerObj] Create a new layerObj in parent_map. The layer index of the new layerObj will be equal to the parent_map numlayers - 1. The parent_map arg is now optional and Layers can exist outside of a Map. addFeature( shapeObj shape ) [int] Add a new inline feature on a layer. Returns -1 on error. TODO: Is this similar to inline features in a maple? Does it work for any kind of layer or connection type? addProcessing( string directive ) [void] Adds a new processing directive line to a layer, similar to the PROCESSING directive in a map le. Processing directives supported are specic to the layer type and underlying renderer. applySLD( string sld, string stylelayer ) [int] Apply the SLD document to the layer object. The matching between the sld document and the layer will be done using the layers name. If a namedlayer argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the layer. See SLD HOWTO for more information on the SLD support. applySLDURL( string sld, string stylelayer ) [int] Apply the SLD document pointed by the URL to the layer object. The matching between the sld document and the layer will be done using the layers name. If a namedlayer argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the layer. See SLD HOWTO for more information on the SLD support. clearProcessing() [int] Clears the layers raster processing directives. Returns the subsequent number of directives, which will equal MS_SUCCESS if the directives have been cleared. clone() [layerObj] Return an independent copy of the layer with no parent map. close() [void] Close the underlying layer. Note: demote() is removed in MapServer 4.4 draw( mapObj map, imageObj image ) [int] Renders this layer into the target image, adding labels to the cache if required. Returns MS_SUCCESS or MS_FAILURE. TODO: Does the map need to be the map on which the layer is dened? I suspect so. drawQuery( mapObj map, imageObj image ) : Draw query map for a single layer into the target image. Returns MS_SUCCESS or MS_FAILURE. executeWFSGetFeature( layer ) [string] Executes a GetFeature request on a WFS layer and returns the name of the temporary GML le created. Returns an empty string on error. generateSLD() [void] Returns an SLD XML string based on all the classes found in the layer (the layer must have STATUS on). getClass( int i ) [classObj] Fetch the requested class object. Returns NULL if the class index is out of the legal range. The numclasses eld contains the number of classes available, and the rst class is index 0. getExtent() [rectObj] Fetches the extents of the data in the layer. This normally requires a full read pass through the features of the layer and does not work for raster layers. getFeature( int shapeindex [, int tileindex=-1 ] ) [shapeObj] Return the layer feature at shapeindex and tileindex. getFilterString() [string] Returns the current lter expression. getFirstMetaDataKey() [string] Returns the rst key in the metadata hash table. With getNextMetaDataKey(), provides an opaque iterator over keys. Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj.
205
getItem( int i ) [string] Returns the requested item. Items are attribute elds, and this method returns the item name (eld name). The numitems eld contains the number of items available, and the rst item is index zero. getMetaData( string key ) [string] Return the value at key from the metadata hash table. Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj. getNextMetaDataKey( string lastkey ) [string] Returns the next key in the metadata hash table or NULL if lastkey is the last valid key. If lastkey is NULL, returns the rst key of the metadata hash table. Note: getFirstMetaDataKey(), getMetaData(), and getNextMetaDataKey() are deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj. getNumFeatures() [int] Returns the number of inline features in a layer. TODO: is this really only online features or will it return the number of non-inline features on a regular layer? getNumResults() [int] Returns the number of entries in the query result cache for this layer. Note: getNumResults() and getResult() are deprecated in MapServer 4.4. Users should instead use the new querying API described in querying-HOWTO.txt. layerObj::getResults() is the entry point for the new API. getProcessing( int index) [string] Return the raster processing directive at index. getProjection( ) [string] Returns the PROJ.4 denition of the layers projection. getResult( int i ) [resultCacheMemberObj] Fetches the requested query result cache entry, or NULL if the index is outside the range of available results. This method would normally only be used after issuing a query operation. Note: getNumResults() and getResult() are deprecated in MapServer 4.4. Users should instead use the new querying API described in querying-HOWTO.txt. layerObj::getResults() is the entry point for the new API. getResults() [resultCacheObj] Returns a reference to layers result cache. Should be NULL prior to any query, or after a failed query or query with no results. getResultsBounds() [rectObj] Returns the bounds of the features in the result cache. getShape( shapeObj shape, int tileindex, int shapeindex ) [int] Get a shape from layer data. Note: getShape() is deprecated. Users should adopt getFeature() for new applications. getWMSFeatureInfoURL( mapObj map, int click_x, int click_y, int feature_count, string info_format ) [string] Return a WMS GetFeatureInfo URL (works only for WMS layers) clickX, clickY is the location of to query in pixel coordinates with (0,0) at the top left of the image. featureCount is the number of results to return. infoFormat is the format the format in which the result should be requested. Depends on remote servers capabilities. MapServer WMS servers support only MIME (and should support GML.1 soon). Returns and outputs a warning if layer is not a WMS layer or if it is not queriable. insertClass( classObj class [, int index=-1 ] ) [int] Insert a copy of the class into the layer at the requested index. Default index of -1 means insertion at the end of the array of classes. Returns the index at which the class was inserted. isVisible( ) [int] Returns MS_TRUE or MS_FALSE after considering the layer status, minscaledenom, and maxscaledenom within the context of the parent map. moveClassDown( int class ) [int] The class specied by the class index will be moved up into the array of layers. Returns MS_SUCCESS or MS_FAILURE. ex. moveClassDown(1) will have the effect of moving class 1 down to postion 2, and the class at position 2 will be moved to position 1. moveClassUp( int class ) [int] The class specied by the class index will be moved up into the array of layers. Returns MS_SUCCESS or MS_FAILURE. ex. moveClassUp(1) will have the effect of moving class 1 up to postion 0, and the class at position 0 will be moved to position 1.
206
nextShape( ) [shapeObj] Called after msWhichShapes has been called to actually retrieve shapes within a given area returns a shape object or MS_FALSE example of usage :
mapObj map = new mapObj("d:/msapps/gmap-ms40/htdocs/gmap75.map"); layerObj layer = map.getLayerByName(road); int status = layer.open(); status = layer.whichShapes(map.extent); shapeObj shape; while ((shape = layer.nextShape()) != null) { ... } layer.close();
open() [void] Opens the underlying layer. This is required before operations like getFeature() will work, but is not required before a draw or query call. Note: promote() is eliminated in MapServer 4.4. queryByAttributes( mapObj map, string qitem, string qstring, int mode ) [int] Query layer for shapes that intersect current map extents. qitem is the item (attribute) on which the query is performed, and qstring is the expression to match. The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Note that the layers FILTER/FILTERITEM are ignored by this function. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened. queryByFeatures( mapObj map, int slayer ) [int] Perform a query set based on a previous set of results from another layer. At present the results MUST be based on a polygon layer. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened queryByIndex( mapObj map, int shapeindex, int tileindex [, int bAddToQuery=MS_FALSE ]) [int] Pop a query result member into the layers result cache. By default clobbers existing cache. Returns MS_SUCCESS or MS_FAILURE. queryByPoint( mapObj map, pointObj point, int mode, oat buffer ) [int] Query layer at point location specied in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Passing buffer <=0 defaults to tolerances set in the map le (in pixels) but you can use a constant buffer (specied in ground units) instead. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened. queryByRect( mapObj map, rectObj rect ) [int] Query layer using a rectangle specied in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened. queryByShape( mapObj map, shapeObj shape ) [int] Query layer based on a single shape, the shape has to be a polygon at this point. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened removeClass( int index ) [classObj] Removes the class indicated and returns a copy, or NULL in the case of a failure. Note that subsequent classes will be renumbered by this operation. The numclasses eld contains the number of classes available. removeMetaData( string key ) [int] Delete the metadata hash at key. Returns MS_SUCCESS or MS_FAILURE.
207
Note: removeMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj. setConnectionType(int connectiontype, string library_str) [int] Changes the connectiontype of the layer and recreates the vtable according to the new connection type. This method should be used instead of setting the connectiontype parameter directly. In case when the layer.connectiontype = MS_PLUGIN the library_str parameter should also be specied so as to select the library to load by mapserver. For the other connection types this parameter is not used. setExtent( oat minx, oat miny, oat maxx, oat maxy ) [int] Sets the extent of a layer. Returns MS_SUCCESS or MS_FAILURE. setFilter( string lter ) [int] Sets a lter expression similarly to the FILTER expression in a map le. Returns MS_SUCCESS on success or MS_FAILURE if the expression fails to parse. setMetaData( string key, string value ) [int] Assign value to the metadata hash at key. Return MS_SUCCESS or MS_FAILURE. Note: setMetaData() is deprecated and will be removed in a future version. Replaced by direct metadata access, see hashTableObj. setProcessingKey( string key, string value ) [void] Adds or replaces a processing directive of the form key=value. Unlike the addProcessing() call, this will replace an existing processing directive for the given key value. Processing directives supported are specic to the layer type and underlying renderer. setProjection( string proj4 ) [int] Set the layer projection using a PROJ.4 format projection denition (ie. +proj=utm +zone=11 +datum=WGS84 or init=EPSG:26911). Returns MS_SUCCESS or MS_FAILURE. setWKTProjection( string wkt ) [int] Set the layer projection using OpenGIS Well Known Text format. Returns MS_SUCCESS or MS_FAILURE. int whichShapes( rectObj rect ) [int] Performs a spatial, and optionally an attribute based feature search. The function basically prepares things so that candidate features can be accessed by query or drawing functions (eg using nextShape function). Returns MS_SUCCESS, MS_FAILURE or MS_DONE. MS_DONE is returned if the layer extent does not overlap rect. resultsGetShape(int shapeindex [, int tileindex = -1]) [shapeObj] Retrieve shapeObj from a layers resultset by index. Tileindex is optional and is used only for tiled shapeles, Simply omit or pass tileindex = -1 for other data sources. Added in MapServer 5.6.0 due to the one-pass query implementation. legendObj legendObj is associated with mapObj
+--------+ 0..1 1 +-----+ | Legend | <--------> | Map | +--------+ +-----+
and with labelObj.

+--------+ 1 1 +-------+ | Legend | ---------> | Label | +--------+ +-------+
legendObj Attributes
height [int] Legend height. imagecolor [colorObj] Legend background color. 208 Chapter 6. MapScript
keysizex [int] Width in pixels of legend keys. keysizey [int] Pixels. keyspacingx [int] Horizontal padding around keys in pixels. keyspacingy [int] Vertical padding. label [labelObj immutable] legend label. map [mapObj immutable] Reference to parent mapObj. outlinecolor [colorObj] key outline color. position [int] MS_UL, MS_UC, MS_UR, MS_LL, MS_LC, or MS_LR. postlabelcache [int] MS_TRUE or MS_FALSE. status [int] MS_ON, MS_OFF, or MS_EMBED. template [string] Path to template le. width [int] Label width.
legendObj Methods
None lineObj A lineObj is composed of one or more pointObj instances.
+------+ 0..1 1..* +-------+ | Line | ---------> | Point | +------+ +-------+
lineObj Attributes
numpoints [int immutable] Number of points in the line.
lineObj Methods
add(pointObj point) [int] Add point to the line. Returns MS_SUCCESS or MS_FAILURE. get(int index) [pointObj] Return reference to point at index. project(projectionObj proj_in, projectionObj proj_out) [int] Transform line in place from proj_in to proj_out. Returns MS_SUCCESS or MS_FAILURE. set(int index, pointObj point) [int] Set the point at index to point. Returns MS_SUCCESS or MS_FAILURE. mapObj A mapObj is primarily associated with instances of layerObj.
209
+-----+ 0..1 0..* +-------+ | Map | <--------> | Layer | +-----+ +-------+
Secondary associations are with legendObj, scalebarObj, referenceMapObj,

+-----+ 1 0..1 +--------------+ | Map | ---------> | Legend | +-----+ | ------------ | | Scalebar | | ------------ | | ReferenceMap | +--------------+
outputFormatObj.
+-----+ 1 1..* +--------------+ | Map | ---------> | OutputFormat | +-----+ +------------- +
mapObj Attributes
cellsize [oat] Pixel size in map units. congoptions [hashObj immutable] A hash table of conguration options from CONFIG keywords in the .map. Direct access to cong options is discouraged. Use the setCongOption() and getCongOption() methods instead. datapattern [string] TODO not sure this is meaningful for mapscript. debug [int] MS_TRUE or MS_FALSE. extent [rectObj] Maps spatial extent. fontset [fontSetObj immutable] The maps dened fonts. height [int] Maps output image height in pixels. Note: direct setting of height is deprecated in MapServer version 4.4. Users should set width and height simultaneously using setSize(). imagecolor [colorObj] Initial map background color. imagequality [int] JPEG image quality. Note: map imagequality is deprecated in MapServer 4.4 and should instead be managed through map outputformats. imagetype [string immutable] Name of the current output format. interlace [int] Output image interlacing. Note: map interlace is deprecated in MapServer 4.4 and should instead be managed through map outputformats. lablecache [labelCacheObj immutable] Maps labelcache. legend [legendObj immutable] Reference to maps legend. mappath [string] Filesystem path of the maps maple. maxsize [int] TODO ? name [string] Unique identier.
210
numlayers [int immutable] Number of map layers. numoutputformats [int] Number of output formats. outputformat [outputFormatObj] The currently selected output format. Note: Map outputformat should not be modied directly. Use the selectOutputFormat() method to select named formats. outputformatlist [outputFormatObj[]] Array of the available output formats. Note: Currently only available for C#. A proper typemaps should be implemented for the other languages. querymap [queryMapObj immutable] TODO should this be exposed to mapscript? reference [referenceMapObj immutable] Reference to reference map. resolution [oat] Nominal DPI resolution. Default is 72. scaledenom [oat] The nominal map scale. A value of 25000 means 1:25000 scale. scalebar [scalebarObj immutable] Reference to the scale bar. shapepath [string] Base lesystem path to layer data. status [int] MS_OFF, MS_ON, or MS_DEFAULT. symbolset [symbolSetObj immutable] The maps set of symbols. templatepattern [string] TODO not sure this is meaningful for mapscript. transparent [int] MS_TRUE or MS_FALSE. Note: map transparent is deprecated in MapServer 4.4 and should instead be managed through map outputformats. units [int] MS_DD, MS_METERS, etc. web [webObj immutable] Reference to maps web denitions. width [int] Maps output image width in pixels. Note: direct setting of width is deprecated in MapServer version 4.4. Users should set width and height simultaneously using setSize().
mapObj Methods
new mapObj( [ string lename= ] ) [mapObj] Create a new instance of mapObj. Note that the lename is now optional. appendOutputFormat( outputFormatObj format ) [int] Attach format to the maps output format list. Returns the updated number of output formats. applyCongOptions( ) [void] Apply the dened conguration options set by setCongOption(). applySLD( string sldxml ) [int] Parse the SLD XML string sldxml and apply to map layers. Returns MS_SUCCESS or MS_FAILURE. applySLDURL( string sldurl ) [int] Fetch SLD XML from the URL sldurl and apply to map layers. Returns MS_SUCCESS or MS_FAILURE. clone( ) [mapObj] Returns a independent copy of the map, less any caches. Note: In the Java module this method is named cloneMap. draw( ) [imageObj] Draw the map, processing layers according to their dened order and status. Return an imageObj.
211
drawLabelCache( imageObj image ) [int] Draw maps label cache on image. MS_FAILURE. drawLegend( ) [imageObj] Draw map legend, returning an imageObj. drawQuery( ) [imageObj] Draw query map, returning an imageObj. drawReferenceMap( ) [imageObj] Draw reference map, returning an imageObj. drawScalebar( ) [imageObj] Draw scale bar, returning an imageObj.
Returns MS_SUCCESS or
embedLegend( imageObj image ) [int] Embed maps legend in image. Returns MS_SUCCESS or MS_FAILURE. embedScalebar( imageObj image ) [int] Embed maps scalebar in image. MS_FAILURE. Returns MS_SUCCESS or
freeQuery( [ int qlayer=-1 ] ) [void] Clear layer query result caches. Default is -1, or all layers. generateSLD( ) [string] Return SLD XML as a string for map layers that have STATUS on. getCongOption( string key ) [string] Fetches the value of the requested conguration key if set. Returns NULL if the key is not set. getFirstMetaDataKey( ) [string] Returns the rst key in the web.metadata hash table. With getNextMetaDataKey( ), provides an opaque iterator over keys. getLayer( int index ) [layerObj] Returns a reference to the layer at index. getLayerByName( string name ) [layerObj] Returns a reference to the named layer. getLayersDrawingOrder( ) [int*] Returns an array of layer indexes in drawing order. Note: Unless the proper typemap is implemented for the modules language a user is more likely to get back an unuseable SWIG pointer to the integer array. getMetaData( string key ) [string] Return the value at key from the web.metadata hash table. getNextMetaDataKey( string lastkey ) [string] Returns the next key in the web.metadata hash table or NULL if lastkey is the last valid key. If lastkey is NULL, returns the rst key of the metadata hash table. getNumSymbols( ) [int] Return the number of symbols in map. getOutputFormatByName( string imagetype ) [outputFormatObj] Return the output format corresponding to driver name imagetype or to format name imagetype. This works exactly the same as the IMAGETYPE directive in a maple, is case insensitive and allows an output format to be found either by driver (like GD/PNG) or name (like PNG24). getProjection( ) [string] Returns the PROJ.4 denition of the maps projection. getSymbolByName( string name ) [int] Return the index of the named symbol in the maps symbolset. Note: This method is poorly named and too indirect. It is preferrable to use the getSymbolByName method of symbolSetObj, which really does return a symbolObj reference, or use the index method of symbolSetObj to get a symbols index number. insertLayer( layerObj layer [, int nIndex=-1 ] ) [int] Insert a copy of layer into the Map at index nIndex. The default value of nIndex is -1, which means the last possible index. Returns the index of the new Layer, or -1 in the case of a failure. loadMapContext( string lename [, int useUniqueNames=MS_FALSE ] ) [int] Load an OGC map context le to dene extents and layers of a map. loadOWSParameters( OWSRequest request [, string version=1.1.1 ] ) [int] Load OWS request parameters (BBOX, LAYERS, &c.) into map. Returns MS_SUCCESS or MS_FAILURE. loadQuery( string lename ) [int] Load a saved query. Returns MS_SUCCESS or MS_FAILURE.
212
moveLayerDown( int layerindex ) [int] Move the layer at layerindex down in the drawing order array, meaning that it is drawn later. Returns MS_SUCCESS or MS_FAILURE. moveLayerUp( int layerindex ) [int] Move the layer at layerindex up in the drawing order array, meaning that it is drawn earlier. Returns MS_SUCCESS or MS_FAILURE. nextLabel( ) [labelCacheMemberObj] Return the next label from the maps labelcache, allowing iteration over labels. Note: nextLabel() is deprecated and will be removed in a future version. Replaced by getLabel(). getLabel( int labelindex ) [labelCacheMemberObj] Return label at specied index from the maps labelcache. OWSDispatch( OWSRequest req ) [int] Processes and executes the passed OpenGIS Web Services request on the map. Returns MS_DONE (2) if there is no valid OWS request in the req object, MS_SUCCESS (0) if an OWS request was successfully processed and MS_FAILURE (1) if an OWS request was not successfully processed. OWS requests include WMS, WFS, WCS and SOS requests supported by MapServer. Results of a dispatched request are written to stdout and can be captured using the msIO services (ie. msIO_installStdoutToBuffer() and msIO_getStdoutBufferString()) prepareImage( ) [imageObj] Returns an imageObj initialized to map extents and outputformat. prepareQuery( ) [void] TODO this function only calculates the scale or am I missing something? processLegendTemplate( string names[], string values[], int numitems ) [string] Process MapServer legend template and return HTML. Note: None of the three template processing methods will be useable unless the proper typemaps are implemented in the module for the target language. Currently the typemaps are not implemented. processQueryTemplate( string names[], string values[], int numitems ) [string] Process MapServer query template and return HTML. Note: None of the three template processing methods will be useable unless the proper typemaps are implemented in the module for the target language. Currently the typemaps are not implemented. processTemplate( int generateimages, string names[], string values[], int numitems ) [string] Process MapServer template and return HTML. Note: None of the three template processing methods will be useable unless the proper typemaps are implemented in the module for the target language. Currently the typemaps are not implemented. queryByFeatures( int layerindex ) [int] Query map layers, result sets contain features that intersect or are contained within the features in the result set of the MS_LAYER_POLYGON type layer at layerindex. Returns MS_SUCCESS or MS_FAILURE. queryByPoint( pointObj point, int mode, oat buffer ) [int] Query map layers, result sets contain one or more features, depending on mode, that intersect point within a tolerance buffer. Returns MS_SUCCESS or MS_FAILURE. queryByRect( rectObj rect ) [int] Query map layers, result sets contain features that intersect or are contained within rect. Returns MS_SUCCESS or MS_FAILURE. queryByShape( shapeObj shape ) [int] Query map layers, result sets contain features that intersect or are contained within shape. Returns MS_SUCCESS or MS_FAILURE. removeLayer( int index ) [int] Remove the layer at index. removeMetaData( string key ) [int] Delete the web.metadata hash at key. MS_FAILURE. Returns MS_SUCCESS or
removeOutputFormat( string name ) [int] Removes the format named name from the maps output format list. Returns MS_SUCCESS or MS_FAILURE. save( string lename ) [int] Save map to disk as a new map le. Returns MS_SUCCESS or MS_FAILURE.
213
saveMapContext( string lename ) [int] Save map denition to disk as OGC-compliant XML. Returns MS_SUCCESS or MS_FAILURE. saveQuery( string lename ) [int] Save query to disk. Returns MS_SUCCESS or MS_FAILURE. saveQueryAsGML( string lename ) [int] Save query to disk. Returns MS_SUCCESS or MS_FAILURE. selectOutputFormat( string imagetype ) [void] Set the maps active output format to the internal format named imagetype. Built-in formats are PNG, PNG24, JPEG, GIF, GTIFF. setCongOption( string key, string value ) [void] Set the indicated key conguration option to the indicated value. Equivalent to including a CONFIG keyword in a map le. setExtent( oat minx, oat miny, oat maxx, oat maxy ) [int] Set the map extent, returns MS_SUCCESS or MS_FAILURE. offsetExtent( oat x, oat y) [int] Offset the map extent based on the given distances in map coordinates, returns MS_SUCCESS or MS_FAILURE. scaleExtent( oat zoomfactor, oat minscaledenom, oat maxscaledenom) [int] Scale the map extent using the zoomfactor and ensure the extent within the minscaledenom and maxscaledenom domain. If minscaledenom and/or maxscaledenom is 0 then the parameter is not taken into account. returns MS_SUCCESS or MS_FAILURE. setCenter( pointObj center ) [int] Set the map center to the given map point, returns MS_SUCCESS or MS_FAILURE. setFontSet( string lename ) [int] Load fonts dened in lename into map fontset. The existing fontset is cleared. Returns MS_SUCCESS or MS_FAILURE. setImageType( string name ) [void] Sets map outputformat to the named format. Note: setImageType() remains in the module but its use is deprecated in favor of selectOutputFormat(). setLayersDrawingOrder( int layerindexes[]) [int] Set map layer drawing order. Note: Unless the proper typemap is implemented for the modules language users will not be able to pass arrays or lists to this method and it will be unusable. setMetaData( string key, string value ) [int] Assign value to the web.metadata hash at key. Return MS_SUCCESS or MS_FAILURE. setOutputFormat( outputFormatObj format ) [void] Sets map outputformat. setProjection( string proj4 ) [int] Set map projection from PROJ.4 denition string proj4. setRotation( oat rotation_angle ) [int] Set map rotation angle. The map view rectangle (specied in EXTENTS) will be rotated by the indicated angle in the counterclockwise direction. Note that this implies the rendered map will be rotated by the angle in the clockwise direction. Returns MS_SUCCESS or MS_FAILURE. setSize( int width, int height ) [int] Set maps image width and height together and carry out the necessary subsequent geotransform computation. Returns MS_SUCCESS or MS_FAILURE. setSymbolSet( string lename ) [int] Load symbols dened in lename into map symbolset. The existing symbolset is cleared. Returns MS_SUCCESS or MS_FAILURE. setWKTProjection( string wkt ) [int] Sets map projection from OGC denition wkt. zoomPoint( int zoomfactor, pointObj imgpoint, int width, int height, rectObj extent, rectObj maxextent ) [int] Zoom by zoomfactor to imgpoint in pixel units within the image of height and width dimensions and georeferenced extent. Zooming can be constrained to a maximum maxextent. Returns MS_SUCCESS or MS_FAILURE. zoomRectangle( rectObj imgrect, int width, int height, rectObj extent, rectObj maxextent ) : int Zoom to a pixel coordinate rectangle in the image of width and height dimensions and georeferencing extent. Zooming can be
214
constrained to a maximum maxextent. The imgrect rectangle contains the coordinates of the LL and UR coordinates in pixel: the maxy in the rect object should be < miny value. Returns MS_SUCCESS or MS_FAILURE.
------- UR (values in the rect object : maxx, maxy) | | | | | | -----LL (values in the rectobject minx, miny)
zoomScale( oat scale, pointObj imgpoint, int width, int height, rectObj extent, rectObj maxextent) [int] Like the previous methods, but zooms to the point at a specied scale. markerCacheMemberObj An individual marker. The markerCacheMemberObj class is associated with labelCacheObj.
+------------------+ 0..* 1 +------------+ | MarkerCacheMember | <--------- | LabelCache | +------------------+ +------------+
markerCacheMemberObj Attributes
id [int immutable] Id of the marker. poly [shapeObj immutable] Marker bounding box.
markerCacheMemberObj Methods
None. outputFormatObj An outputFormatObj is associated with a mapObj
+--------------+ 1..* 1 +-----+ | OutputFormat | <--------- | Map | +--------------+ +-----+
and can also be an attribute of an imageObj.
outputFormatObj Attributes
bands [int] The number of bands in the raster. Only used for the raw modes, MS_IMAGEMODE_BYTE, MS_IMAGEMODE_INT16, and MS_IMAGEMODE_FLOAT32. Normally set via the BAND_COUNT formatoption ... this eld should be considered read-only. driver [string] A string such as GD/PNG or GDAL/GTiff. extension [string] Format le extension such as png. imagemode [int] MS_IMAGEMODE_PC256, MS_IMAGEMODE_RGB, MS_IMAGEMODE_RGBA, MS_IMAGEMODE_INT16, MS_IMAGEMODE_FLOAT32, MS_IMAGEMODE_BYTE, or MS_IMAGEMODE_NULL. 6.2. SWIG MapScript API Reference 215
mimetype [string] Format mimetype such as image/png. name [string] A unique identier. renderer [int] MS_RENDER_WITH_GD, MS_RENDER_WITH_SWF, MS_RENDER_WITH_RAWDATA, MS_RENDER_WITH_PDF, or MS_RENDER_WITH_IMAGEMAP. Normally set internally based on the driver and some other setting in the constructor. transparent [int] MS_ON or MS_OFF.
outputFormatObj Methods
new outputFormatObj( string driver [, string name=driver ] ) [outputFormatObj] Create new instance. If name is not provided, the value of driver is used as a name. getOption( string key [, string value= ] ) [string] Return the format option at key or value if key is not a valid hash index. setExtension( string extension ) [void] Set le extension for output format such as png or jpg. Method could probably be deprecated since the extension attribute is mutable. setMimetype( string mimetype ) [void] Set mimetype for output format such as image/png or image/jpeg. Method could probably be deprecated since the mimetype attribute is mutable. setOption( string key, string value ) [void] Set the format option at key to value. Format options are mostly driver specic. validate() [int] Checks some internal consistency issues, and returns MS_TRUE if things are OK and MS_FALSE if there are problems. Some problems are xed up internally. May produce debug output if issues encountered. OWSRequest Not associated with other mapscript classes. Serves as a message intermediary between an application and MapServers OWS capabilities. Using it permits creation of lightweight WMS services:
wms_map = mapscript.mapObj(wms.map) wms_request = mapscript.OWSRequest() # Convert application request parameters (req.args) for param, value in req.args.items(): wms_request.setParam(param, value) # Map loads parameters from OWSRequest, adjusting its SRS, extents, # active layers accordingly wms_map.loadWMSRequest(1.1.0, wms_request) # Render the Map img = wms_map.draw()
OWSRequest Attributes
NumParams [int immutable] Number of request parameters. Eventually should be changed to numparams lowercase like other attributes. postrequest [string] TODO type [int] MS_GET_REQUEST or MS_POST_REQUEST.
216
OWSRequest Methods
new OWSRequest( ) [OWSRequest] Create a new instance. Note: MapServers OWSRequest supports only single valued parameters. setParameter( string name, string value ) [void] Set a request parameter. For example
request.setParameter(REQUEST, GetMap) request.setParameter(BBOX, -107.0,40.0,-106.0,41.0)
addParameter( string name, string value ) [void] Add a request parameter, even if the parameter key was previousely set. This is useful when multiple parameters with the same key are required. For example
request.addParameter(SIZE, x(100)) request.addParameter(SIZE, y(100))
getName( int index ) [string] Return the name of the parameter at index in the requests array of parameter names. getValue( int index ) [string] Return the value of the parameter at index in the requests array of parameter values. getValueByName( string name) [string] Return the value associated with the parameter name. loadParams() [int] Initializes the OWSRequest object from the cgi environment variables REQUEST_METHOD, QUERY_STRING and HTTP_COOKIE. Returns the number of name/value pairs collected. Warning: most errors will result in a process exit! loadParamsFromURL( string url ) [int] Initializes the OWSRequest object from the provided URL which is treated like a QUERY_STRING. Note that REQUEST_METHOD=GET and no post data is assumed in this case. This method was added in MapServer 6.0. pointObj A pointObj instance may be associated with a lineObj.
+-------+ 1..* 0..1 +------+ | Point | <--------- | Line | +-------+ +------+
pointObj Attributes
m [oat] Measure. Meaningful only for measured shapeles. Given value -2e38 if not otherwise assigned to indicate nodata. x [oat] Easting y [oat] Northing z [oat] Elevation
pointObj Methods
new pointObj( [ oat x=0.0, oat y=0.0, oat z=0.0, oat m=-2e38 ] ) [pointObj] Create new instance. Easting, northing, and measure arguments are optional. distanceToPoint( pointObj point ) [oat] Returns the distance to point.
217
distanceToSegment( pointObj point1, pointObj point2 ) [oat] Returns the minimum distance to a hypothetical line segment connecting point1 and point2. distanceToShape( shapeObj shape ) [oat] Returns the minimum distance to shape. draw( mapObj map, layerObj layer, imageObj image, int classindex, string text ) [int] Draw the point using the styles dened by the classindex class of layer and labeled with string text. Returns MS_SUCCESS or MS_FAILURE. project( projectionObj proj_in, projectionObj proj_out ) [int] Reproject point from proj_in to proj_out. Transformation is done in place. Returns MS_SUCCESS or MS_FAILURE. setXY( oat x, oat y [, oat m=2e-38 ] ) [int] Set spatial coordinate and, optionally, measure values simultaneously. The measure will be set only if the value of m is greater than the ESRI measure no-data value of 1e-38. Returns MS_SUCCESS or MS_FAILURE. setXYZ( oat x, oat y, oat z [, oat m=-2e38 ] ) [int] Set spatial coordinate and, optionally, measure values simultaneously. The measure will be set only if the value of m is greater than the ESRI measure no-data value of -1e38. Returns MS_SUCCESS or MS_FAILURE. setXYZM( oat x, oat y, oat z, oat m ) [int] Set spatial coordinate and, optionally, measure values simultaneously. The measure will be set only if the value of m is greater than the ESRI measure no-data value of -1e38. Returns MS_SUCCESS or MS_FAILURE. toString() [string] Return a string formatted like
{ x: %f , y: %f, z: %f }
with the coordinate values substituted appropriately. Python users can get the same effect via the pointObj __str__ method
>>> p = mapscript.pointObj(1, 1) >>> str(p) { x: 1.000000 , y: 1.000000, z: 1.000000 }
toShape() [shapeObj] Convience method to quickly turn a point into a shapeObj. projectionObj This class is not really fully implemented yet. MapServers Maps and Layers have Projection attributes, and these are C projectionObj structures, but are not directly exposed by the mapscript module. Currently we have to do some round-a-bout logic like this
point.project(projectionObj(mapobj.getProjection(), projectionObj(layer.getProjection())
to project a point from map to layer reference system.
projectionObj Attributes
numargs [int immutable] Number of PROJ.4 arguments.
projectionObj Methods
new projectionObj( string proj4 ) [projectionObj] Create new instance of projectionObj. Input parameter proj4 is a PROJ.4 denition string such as init=EPSG:4269.
218
getUnits() [int] Returns the units of a projection object. Returns -1 on error. rectObj A rectObj may be a lone object or an attribute of another object and has no other associations.
rectObj Attributes
maxx [oat] Maximum easting maxy [oat] Maximum northing minx [oat] Minimum easting miny [oat] Minimum northing
rectObj Methods
new rectObj( [ oat minx=-1.0, oat miny=-1.0, oat maxx=-1.0, oat maxy=-1.0, int imageunits=MS_FALSE ] ) [rectObj] Create new instance. The four easting and northing arguments are optional and default to -1.0. Note the new optional fth argument which allows creation of rectangles in image (pixel/line) units which are also tested for validity. draw( mapObj map, layerObj layer, imageObj img, int classindex, string text ) [int] Draw rectangle into img using style dened by the classindex class of layer. The rectangle is labeled with the string text. Returns MS_SUCCESS or MS_FAILURE. getCenter() [pointObj] Return the center point of the rectagle. project( projectionObj proj_in, projectionObj proj_out ) [int] Reproject rectangle from proj_in to proj_out. Transformation is done in place. Returns MS_SUCCESS or MS_FAILURE. toPolygon() [shapeObj] Convert to a polygon of ve vertices. toString() [string] Return a string formatted like
{ minx: %f , miny: %f , maxx: %f , maxy: %f }
with the bounding values substituted appropriately. Python users can get the same effect via the rectObj __str__ method
>>> r = mapscript.rectObj(0, 0, 1, 1) >>> str(r) { minx: 0 , miny: 0 , maxx: 1 , maxy: 1 }
referenceMapObj A referenceMapObj is associated with mapObj.

+--------------+ 0..1 1 +-----+ | ReferenceMap | <--------> | Map | +--------------+ +-----+
219
referenceMapObj Attributes
color [colorObj] Color of reference box. extent [rectObj] Spatial extent of reference in units of parent map. height [int] Height of reference map in pixels. image [string] Filename of reference map image. map [mapObj immutable] Reference to parent mapObj. marker [int] Index of a symbol in the map symbol set to use for marker. markername [string] Name of a symbol. markersize [int] Size of marker. maxboxsize [int] Pixels. minboxsize [int] Pixels. outlinecolor [colorObj] Outline color of reference box. status [int] MS_ON or MS_OFF. width [int] In pixels.
referenceMapObj Methods
None resultCacheMemberObj Has no associations with other MapScript classes and has no methods. By using several indexes, a resultCacheMemberObj refers to a single layer feature.
resultCacheMemberObj Attributes
classindex [int immutable] The index of the layer class into which the feature has been classied. shapeindex [int immutable] Index of the feature within the layer. tileindex [int immutable] Meaningful for tiled layers only, index of the shapele data tile. resultCacheObj See querying-HOWTO.txt for extra guidance in using the new 4.4 query API.
resultCacheObj Attributes
bounds [rectObj immutable] Bounding box of query results. numresults [int immutable] Length of result set.
220
resultCacheObj Methods
getResult( int i ) [resultCacheMemberObj] Returns the result at index i, like layerObj::getResult, or NULL if index is outside the range of results. scalebarObj A scalebarObj is associated with mapObj.
+----------+ 0..1 1 +-----+ | Scalebar | <--------- | Map | +----------+ +-----+
and also with labelObj

+----------+ 1 1 +-------+ | Scalebar | ---------> | Label | +----------+ +-------+
scalebarObj Attributes
backgroundcolor [colorObj] Scalebar background color. color [colorObj] Scalebar foreground color. imagecolor [colorObj] Background color of scalebar. height [int] Pixels. intervals [int] Number of intervals. label [labelObj] Scalebar label. outlinecolor [colorObj] Foreground outline color. position [int] MS_UL, MS_UC, MS_UR, MS_LL, MS_LC, or MS_LR. postlabelcache [int] MS_TRUE or MS_FALSE. status [int] MS_ON, MS_OFF, or MS_EMBED. style [int] 0 or 1. units [int] See MS_UNITS in mapserver.h. width [int] Pixels.
scalebarObj Methods
None shapeleObj
shapeleObj Attributes
bounds [rectObj] Extent of shapes
221
numshapes [int] Number of shapes type [int] See mapshape.h for values of type.
shapeleObj Methods
new shapeleObj( string lename [, int type=-1 ] ) [shapeleObj] Create a new instance. Omit the type argument or use a value of -1 to open an existing shapele. add( shapeObj shape ) [int] Add shape to the shapele. Returns MS_SUCCESS or MS_FAILURE. get( int i, shapeObj shape ) [int] Get the shapele feature from index i and store it in shape. Returns MS_SUCCESS or MS_FAILURE. getShape( int i ) [shapeObj] Returns the shapele feature at index i. More effecient than get. TODO shapeObj Each feature of a layers data is a shapeObj. Each part of the shape is a closed lineObj.
+-------+ 1 1..* +------+ | Shape | --------> | Line | +-------+ +------+
shapeObj Attributes
bounds [rectObj] Bounding box of shape. classindex [int] The class index for features of a classied layer. index [int] Feature index within the layer. numlines [int immutable] Number of parts. numvalues [int immutable] Number of shape attributes. text [string] Shape annotation. tileindex [int] Index of tiled le for tileindexed layers. type [int] MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON, or MS_SHAPE_NULL.
shapeObj Methods
new shapeObj( int type ) [shapeObj] Return a new shapeObj of the specied type. See the type attribute above. No attribute values created by default. initValues should be explicitly called to create the required number of values. add( lineObj line ) [int] Add line (i.e. a part) to the shape. Returns MS_SUCCESS or MS_FAILURE. boundary() [shapeObj] Returns the boundary of the existing shape. Requires GEOS support. Returns NULL/undef on failure. buffer( int distance ) [shapeObj] Returns a new buffered shapeObj based on the supplied distance (given in the coordinates of the existing shapeObj). Requires GEOS support. Returns NULL/undef on failure. contains( pointObj point ) [int] Returns MS_TRUE if the point is inside the shape, MS_FALSE otherwise.
222
contains( shapeObj shape2 ) [int] Returns MS_TRUE if shape2 is entirely within the shape. Returns -1 on error and MS_FALSE otherwise. Requires GEOS support. convexHull() [shapeObj] Returns the convex hull of the existing shape. NULL/undef on failure. Requires GEOS support. Returns
copy( shapeObj shape_copy ) [int] Copy the shape to shape_copy. Returns MS_SUCCESS or MS_FAILURE. clone() [shapeObj] Return an independent copy of the shape. crosses( shapeObj shape2 ) [int] Returns MS_TRUE if shape2 crosses the shape. MS_FALSE otherwise. Requires GEOS support. Returns -1 on error and
difference( shapeObj shape ) [shapeObj] Returns the computed difference of the supplied and existing shape. Requires GEOS support. Returns NULL/undef on failure. disjoint( shapeObj shape2 ) [int] Returns MS_TRUE if shape2 and the shape are disjoint. Returns -1 on error and MS_FALSE otherwise. Requires GEOS support. distanceToPoint( pointObj point ) [oat] Return distance to point. distanceToShape( shapeObj shape ) [oat] Return the minimum distance to shape. draw( mapObj map, layerObj layer, imageObj img ) [int] Draws the individual shape using layer. MS_SUCCESS or MS_FAILURE. Returns
equals( shapeObj shape2 ) [int] Returns MS_TRUE if the shape and shape2 are equal (geometry only). Returns -1 on error and MS_FALSE otherwise. Requires GEOS support. fromWKT( char \*wkt ) [shapeObj] Returns a new shapeObj based on a well-known text representation of a geometry. Requires GEOS support. Returns NULL/undef on failure. get( int index ) [lineObj] Returns a reference to part at index. Reference is valid only during the life of the shapeObj. getArea() [double] Returns the area of the shape (if applicable). Requires GEOS support. getCentroid() [pointObj] Returns the centroid for the existing shape. Requires GEOS support. Returns NULL/undef on failure. getLength() [double] Returns the length (or perimeter) of a shape. Requires GEOS support. getValue( int i ) [string] Return the shape attribute at index i. initValues( int numvalues ) [void] Allocates memory for the requested number of values. intersects( shapeObj shape ) [int] Returns MS_TRUE if the two shapes intersect, MS_FALSE otherwise. Note: Does not require GEOS support but will use GEOS functions if available. intersection( shapeObj shape ) [shapeObj] Returns the computed intersection of the supplied and existing shape. Requires GEOS support. Returns NULL/undef on failure. overlaps( shapeObj shape2 ) [int] Returns MS_TRUE if shape2 overlaps shape. Returns -1 on error and MS_FALSE otherwise. Requires GEOS support. project( projectionObj proj_in, projectionObj proj_out ) [int] Reproject shape from proj_in to proj_out. Transformation is done in place. Returns MS_SUCCESS or MS_FAILURE. setBounds [void] Must be called to calculate new bounding box after new parts have been added. TODO: should return int and set msSetError. setValue( int i, string value ) [int] Set the shape value at index i to value. simplify( double tolerance ): shapeObj Given a tolerance, returns a simplied shape object or NULL on error. Requires GEOS support (>=3.0).
223
symDifference( shapeObj shape ) [shapeObj] Returns the computed symmetric difference of the supplied and existing shape. Requires GEOS support. Returns NULL/undef on failure. topologySimplifyPreservingSimplify( double tolerance ): shapeObj Given a tolerance, returns a simplied shape object or NULL on error. Requires GEOS support (>=3.0). touches( shapeObj shape2 ) [int] Returns MS_TRUE if the shape and shape2 touch. Returns -1 on error and MS_FALSE otherwise. Requires GEOS support. toWKT() [string] Returns the well-known text representation of a shapeObj. Requires GEOS support. Returns NULL/undef on failure. Union( shapeObj shape ) [shapeObj] Returns the union of the existing and supplied shape. Shapes must be of the same type. Requires GEOS support. Returns NULL/undef on failure. within( shapeObj shape2 ) [int] Returns MS_TRUE if the shape is entirely within shape2. Returns -1 on error and MS_FALSE otherwise. Requires GEOS support. styleObj An instance of styleObj is associated with one instance of classObj.
+-------+ 0..* 1 +-------+ | Style | <-------- | Class | +-------+ +-------+
An instance of styleObj can exist outside of a classObj container and be explicitly inserted into the classObj for use in mapping.
new_style = new styleObj() the_class.insertStyle(new_style)
It is important to understand that insertStyle inserts a copy of the styleObj instance, not a reference to the instance itself. The older use case
new_style = new styleObj(the_class)
remains supported. These will be the only ways to access the styles of a class. Programmers should no longer directly access the styles attribute.
styleObj Attributes
angle [double] Angle, given in degrees, to draw the line work. Default is 0. For symbols of Type HATCH, this is the angle of the hatched lines. angleitem [string]Deprecated since version 5.0: Use setBinding. antialias [int] MS_TRUE or MS_FALSE. Should TrueType fonts be antialiased. backgroundcolor [colorObj] Background pen color. color [colorObj] Foreground or ll pen color. mincolor [colorObj] Attribute for Color Range Mapping (MS RFC 6: Color Range Mapping of Continuous Feature Values). mincolor, minvalue, maxcolor, maxvalue dene the range for mapping a continuous feature value to a continuous range of colors when rendering the feature on the map. minsize [int] Minimum pen or symbol width for scaling styles.
224
minvalue [double] Attribute for Color Range Mapping (MS RFC 6: Color Range Mapping of Continuous Feature Values). mincolor, minvalue, maxcolor, maxvalue dene the range for mapping a continuous feature value to a continuous range of colors when rendering the feature on the map. minwidth [int] Minimum width of the symbol. maxcolor [colorObj] Attribute for Color Range Mapping (MS RFC 6: Color Range Mapping of Continuous Feature Values). mincolor, minvalue, maxcolor, maxvalue dene the range for mapping a continuous feature value to a continuous range of colors when rendering the feature on the map. maxsize [int] Maximum pen or symbol width for scaling. maxvalue [double] Attribute for Color Range Mapping (MS RFC 6: Color Range Mapping of Continuous Feature Values). mincolor, minvalue, maxcolor, maxvalue dene the range for mapping a continuous feature value to a continuous range of colors when rendering the feature on the map. maxwidth [int] Maximum width of the symbol. offsetx [int] Draw with pen or symbol offset from map data. offsety [int] Draw with pen or symbol offset from map data. outlinecolor [colorObj] Outline pen color. rangeitem [string] Attribute/eld that stores the values for the Color Range Mapping (MS RFC 6: Color Range Mapping of Continuous Feature Values). size [int] Pixel width of the styles pen or symbol. sizeitem [string]Deprecated since version 5.0: Use setBinding. symbol [int] The index within the map symbolset of the styles symbol. symbolname [string immutable] Name of the styles symbol. width [int] Width refers to the thickness of line work drawn, in pixels. Default is 1. For symbols of Type HATCH, the with is how thick the hatched lines are.
styleObj Methods
new styleObj( [ classObj parent_class ] ) [styleObj] Returns new default style Obj instance. The parent_class is optional. clone [styleObj] Returns an independent copy of the style with no parent class. getBinding( int binding ) [string] Get the attribute binding for a specied style property. Returns NULL if there is no binding for this property. removeBinding( int binding ) [int] Remove the attribute binding for a specled style property. setBinding ( int binding, string item ) [int] Set the attribute binding for a specied style property. Binding constants look like this: MS_STYLE_BINDING_[attribute name].
setBinding(MS_STYLE_BINDING_SIZE, mySizeItem);
updateFromString ( string snippet ) [int] MS_SUCCESS/MS_FAILURE.
Update
style
from
string
snippet.
Returns
setSymbolByName(mapObj map, string symbolname) [int] Setting the symbol of the styleObj given the reference of the map object and the symbol name. updateFromString ( string snippet ) [int] MS_SUCCESS/MS_FAILURE. Update a style from a string snippet. Returns
225
symbolObj A symbolObj is associated with one symbolSetObj.

+--------+ 0..* 1 +-----------+ | Symbol | <-------- | SymbolSet | +--------+ +-----------+
A styleObj will often refer to a symbolObj by name or index, but this is not really an object association, is it?
symbolObj Attributes
antialias [int] MS_TRUE or MS_FALSE. character [string] For TrueType symbols. lled [int] MS_TRUE or MS_FALSE. font [string] For TrueType symbols. gap [int] Moved to STYLE imagepath [string] Path to pixmap le. inmaple [int] If set to TRUE, the symbol will be saved inside the maple. Added in MapServer 5.6.1 linecap [int] Moved to STYLE linejoin [int] Moved to STYLE linejoinmaxsize [oat] Moved to STYLE name [string] Symbol name numpoints [int immutable] Number of points of a vector symbol. position [int] No more available? sizex [oat] TODO what is this? sizey [oat] TODO what is this? stylelength [int] Number of intervals transparent [int] TODO what is this? transparentcolor [int] TODO is this a derelict attribute? type [int] MS_SYMBOL_SIMPLE, MS_SYMBOL_VECTOR, MS_SYMBOL_PIXMAP, or MS_SYMBOL_TRUETYPE. MS_SYMBOL_ELLIPSE,
symbolObj Methods
new symbolObj( string symbolname [, string imagele ] ) [symbolObj] Create new default symbol named name. If imagele is specied, then the symbol will be of type MS_SYMBOL_PIXMAP. getImage() [imageObj] Returns a pixmap symbols imagery as an imageObj. getPoints() [lineObj] Returns the symbol points as a lineObj. setImage( imageObj image ) [int] Set a pixmap symbols imagery from image. setPoints( lineObj line ) [int] Sets the symbol points from the points of line. Returns the updated number of points.
226
setStyle( int index, int value ) [int] Set the style at index to value. Returns MS_SUCCESS or MS_FAILURE. symbolSetObj A symbolSetObj is an attribute of a mapObj and is associated with instances of symbolObj.
+-----------+ 1 0..* +--------+ | SymbolSet | --------> | Symbol | +-----------+ +--------+
symbolSetObj Attributes
lename [string] Symbolset lename numsymbols [int immutable] Number of symbols in the set.
symbolSetObj Methods
new symbolSetObj( [ string symbolle ] ) [symbolSetObj] Create new instance. If symbolle is specied, symbols will be loaded from the le. appendSymbol( symbolObj symbol ) [int] Add a copy of symbol to the symbolset and return its index. getSymbol( int index ) [symbolObj] Returns a reference to the symbol at index. getSymbolByName( string name ) [symbolObj] Returns a reference to the symbol named name. index( string name ) [int] Return the index of the symbol named name or -1 in the case that no such symbol is found. removeSymbol( int index ) [symbolObj] Remove the symbol at index and return a copy of the symbol. save( string lename ) [int] Save symbol set to a le. Returns MS_SUCCESS or MS_FAILURE. webObj Has no other existence than as an attribute of a mapObj. Serves as a container for various run-time web application denitions like temporary le paths, template paths, etc.
webObj Attributes
empty [string] TODO error [string] TODO extent [rectObj] Clipping extent. footer [string] Path to footer document. header [string] Path to header document. imagepath [string] Filesystem path to temporary image location. imageurl [string] URL to temporary image location. log [string] TODO map [mapObj immutable] Reference to parent mapObj. 6.2. SWIG MapScript API Reference 227
maxscaledenom [oat] Minimum map scale. maxtemplate [string] TODO metadata [hashTableObj immutable] metadata hash table. minscaledenom [oat] Maximum map scale. mintemplate [string] TODO queryformat [string] TODO template [string] Path to template document.
webObj Methods
None.
6.3 PHP MapScript

Author Daniel Morissette Contact dmorissette at mapgears.com Author Yewondwossen Assefa Contact yassefa at dmsolutions.ca Author Alan Boudreault Contact aboudreault at mapgears.com Revision $Revision: 12763 $ Date $Date: 2011-11-08 14:06:14 -0800 (Tue, 08 Nov 2011) $ Note: If you are using MapServer 5.6 and older, please refer to the PHP MapScript 5.6 documentation instead. Note: If you are migrating your existing application that is based on MapServer 5.6 or older, to MapServer 6.0 or beyond, please read the PHP MapScript Migration Guide for important changes.
228
Contents PHP MapScript Introduction Versions Supported How to Get More Information on PHP MapScript Important Note Constants Functions Classes * classObj * clusterObj * colorObj * errorObj * gridObj * hashTableObj * imageObj * labelcacheMemberObj * labelcacheObj * labelObj * layerObj * legendObj * lineObj * mapObj * outputformatObj * OwsrequestObj * pointObj * projectionObj * querymapObj * rectObj * referenceMapObj * resultObj * scalebarObj * shapeleObj * shapeObj * styleObj * symbolObj * webObj Memory Management
6.3.1 Introduction
This is a PHP module that makes MapServers MapScript functionalities available in a PHP Dynamically Loadable Library. In simple terms, this module will allow you to use the powerful PHP scripting language to dynamically create and modify map images in MapServer.
6.3.2 Versions Supported

PHP 5.2.0 or more recent is required; since MapServer 6.0, support for PHP 4, PHP 5.0 and PHP 5.1 have been dropped. PHP MapScript was originally developed for PHP 3.0.14, and after MapServer 3.5 support for PHP 3 was dropped.
6.3. PHP MapScript
229
The module has been tested and used on Linux, Solaris, *BSD, and Windows.
6.3.3 How to Get More Information on PHP MapScript

For installation questions regarding the PHP MapScript module, see PHP MapScript Installation. The MapServer Wiki has information on this module, that was contributed by users. New PHP MapScript users should read the php_example document. The projects home is the PHP/MapScript page on MapTools.org. Also, see the MapScript, and the Maple sections of this site. Refer to the main PHP site for their ofcial documentation.
6.3.4 Important Note

Constant names and class member variable names are case-sensitive in PHP.
6.3.5 Constants
The following MapServer constants are available: Boolean values MS_TRUE, MS_FALSE, MS_ON, MS_OFF, MS_YES, MS_NO Map units MS_INCHES, MS_FEET, MS_MILES, MS_METERS, MS_KILOMETERS, MS_DD, MS_PIXELS, MS_NAUTICALMILES Layer types MS_LAYER_POINT, MS_LAYER_LINE, MS_LAYER_POLYGON, MS_LAYER_RASTER, MS_LAYER_ANNOTATION, MS_LAYER_QUERY, MS_LAYER_CIRCLE, MS_LAYER_TILEINDEX, MS_LAYER_CHART Layer/Legend/Scalebar/Class Status MS_ON, MS_OFF, MS_DEFAULT, MS_EMBED, MS_DELETE Layer alpha transparency allows alpha transparent pixmaps to be used with RGB map images MS_GD_ALPHA Font types MS_TRUETYPE, MS_BITMAP Label positions MS_UL, MS_LR, MS_UR, MS_LL, MS_CR, MS_CL, MS_UC, MS_LC, MS_CC, MS_XY, MS_AUTO, MS_AUTO2, MS_FOLLOW, MS_NONE Bitmap font styles MS_TINY , MS_SMALL, MS_MEDIUM, MS_LARGE, MS_GIANT Shape types MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON, MS_SHAPE_NULL Shapele types MS_SHP_POINT, MS_SHP_ARC, MS_SHP_POLYGON, MS_SHP_MULTIPOINT Query/join types MS_SINGLE, MS_MULTIPLE Querymap styles MS_NORMAL, MS_HILITE, MS_SELECTED Connection Types MS_INLINE, MS_SHAPEFILE, MS_TILED_SHAPEFILE, MS_SDE, MS_OGR, MS_TILED_OGR, MS_POSTGIS, MS_WMS, MS_ORACLESPATIAL, MS_WFS, MS_GRATICULE, MS_RASTER, MS_PLUGIN, MS_UNION Error codes MS_NOERR, MS_IOERR, MS_TTFERR, MS_DBFERR, MS_MISCERR, MS_CGIERR, MS_NOTFOUND, MS_SHPERR, MS_MEMERR, MS_TYPEERR, MS_SYMERR, MS_REGEXERR, MS_GDERR, MS_IDENTERR, MS_EOFERR, MS_PROJERR, MS_WEBERR, MS_IMGERR, MS_HASHERR, MS_JOINERR, MS_PARSEERR, MS_SDEERR, MS_OGRERR, MS_QUERYERR,
230
MS_WMSERR, MS_WMSCONNERR, MS_ORACLESPATIALERR, MS_WFSERR, MS_WFSCONNERR, MS_MAPCONTEXTERR, MS_HTTPERR, MS_WCSERR Symbol types MS_SYMBOL_SIMPLE, MS_SYMBOL_VECTOR, MS_SYMBOL_PIXMAP, MS_SYMBOL_TRUETYPE MS_SYMBOL_ELLIPSE,
Image Mode types (outputFormatObj) MS_IMAGEMODE_PC256, MS_IMAGEMODE_RGB, MS_IMAGEMODE_RGBA, MS_IMAGEMODE_INT16, MS_IMAGEMODE_FLOAT32, MS_IMAGEMODE_BYTE, MS_IMAGEMODE_FEATURE, MS_IMAGEMODE_NULL Style/Attribue binding MS_STYLE_BINDING_SIZE, MS_STYLE_BINDING_ANGLE, MS_STYLE_BINDING_COLOR, MS_STYLE_BINDING_OUTLINECOLOR, MS_STYLE_BINDING_SYMBOL, MS_STYLE_BINDING_WIDTH Label/Attribute binding MS_LABEL_BINDING_SIZE, MS_LABEL_BINDING_ANGLE, MS_LABEL_BINDING_COLOR, MS_LABEL_BINDING_OUTLINECOLOR, MS_LABEL_BINDING_FONT, MS_LABEL_BINDING_PRIORITY, MS_LABEL_BINDING_POSITION, MS_LABEL_BINDING_SHADOWSIZEX, MS_LABEL_BINDING_SHADOWSIZEY Alignment MS_ALIGN_LEFT, MS_ALIGN_CENTER, MS_ALIGN_RIGHT OwsRequest MS_GET_REQUEST, MS_POST_REQUEST
6.3.6 Functions
string ms_GetVersion() Returns the MapServer version and options in a string. This string can be parsed to nd out which modules were compiled in, etc. int ms_GetVersionInt() Returns the MapServer version number (x.y.z) as an integer (x*10000 + y*100 + z). (New in v5.0) e.g. V5.4.3 would return 50403. int ms_iogetStdoutBufferBytes() Writes the current buffer to stdout. The PHP header() function should be used to set the documentss content-type prior to calling the function. Returns the number of bytes written if output is sent to stdout. See MapScript Wrappers for WxS Services for more info. void ms_iogetstdoutbufferstring() Fetch the current stdout buffer contents as a string. This method does not clear the buffer. void ms_ioinstallstdinfrombuffer() Installs a mapserver IO handler directing future stdin reading (ie. post request capture) to come from a buffer. void ms_ioinstallstdouttobuffer() Installs a mapserver IO handler directing future stdout output to a memory buffer. void ms_ioresethandlers() Resets the default stdin and stdout handlers in place of buffer based handlers. void ms_iostripstdoutbuffercontenttype() Strip the Content-type header off the stdout buffer if it has one, and if a content type is found it is return. Otherwise return false. array ms_TokenizeMap(string map_le_name) Preparses a maple through the MapServer parser and return an array with one item for each token from the maple. Strings, logical expressions, regex expressions and comments are returned as individual tokens.
6.3.7 Classes
The following class objects are available through PHP MapScript.
6.3. PHP MapScript
231
classObj
Constructor
Class Objects can be returned by the layerObj class, or can be created using:
new classObj(layerObj layer [, classObj class])
or using the old constructor

classObj ms_newClassObj(layerObj layer [, classObj class])
The second argument class is optional. If given, the new class created will be a copy of this class.
Members
Type string string labelObj double hashTableObj double string int int string string int Name group keyimage label maxscaledenom metadata minscaledenom name numstyles status template title type Note
read-only MS_ON, MS_OFF or MS_DELETE
Methods
imageObj createLegendIcon(int width, int height) Draw the legend icon and return a new imageObj. int deletestyle(int index) Delete the style specied by the style index. If there are any style that follow the deleted style, their index will decrease by 1. int drawLegendIcon(int width, int height, imageObj im, int dstX, int dstY) Draw the legend icon on im object at dstX, dstY. Returns MS_SUCCESS/MS_FAILURE. void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. string getExpressionString() Returns the expression string for the class object. int getMetaData(string name) Fetch class metadata entry by name. Returns if no entry matches the name. Note that the search is case sensitive. Note: getMetaDatas query is case sensitive. styleObj getStyle(int index) Return the style object using an index. index >= 0 && index < class->numstyles. string getTextString() Returns the text string for the class object. int movestyledown(int index) The style specied by the style index will be moved down into the array of classes. Returns MS_SUCCESS or MS_FAILURE. ex class->movestyledown(0) will have the effect of moving style 0 up to position 1, and the style at position 1 will be moved to position 0. 232 Chapter 6. MapScript
int movestyleup(int index) The style specied by the style index will be moved up into the array of classes. Returns MS_SUCCESS or MS_FAILURE. ex class->movestyleup(1) will have the effect of moving style 1 up to position 0, and the style at position 0 will be moved to position 1. int removeMetaData(string name) Remove a metadata entry for the class. Returns MS_SUCCESS/MS_FAILURE. int set(string property_name, new_value) Set object property to a new value. int setExpression(string expression) Set the expression string for the class object. int setMetaData(string name, string value) Set MS_SUCCESS/MS_FAILURE. a metadata entry for the class. Returns
int settext(string text) Set the text string for the class object. int updateFromString(string snippet) Update MS_SUCCESS/MS_FAILURE. a class from a string snippet. Returns
/*set the color */ $oClass->updateFromString(CLASS STYLE COLOR 255 0 255 END END);
clusterObj
Constructor
Instance of clusterObj is always embedded inside the layerObj.
Members
Type double double string Name buffer maxdistance region
Methods
string getFilterString() Returns the expression for this cluster lter or NULL on error. string getGroupString() Returns the expression for this cluster group or NULL on error. int setFilter(string expression) Set layer lter expression. int setGroup(string expression) Set layer group expression. colorObj
Constructor
Instances of colorObj are always embedded inside other classes.
6.3. PHP MapScript
233
Members
Type int int int Name red green blue
Methods
void setRGB(int red, int green, int blue) Set red, green, blue values. errorObj Instances of errorObj are created internally by MapServer as errors happen. Errors are managed as a chained list with the rst item being the most recent error. The head of the list can be fetched using ms_GetErrorObj(), and the list can be cleared using ms_ResetErrorList()
Functions
errorObj ms_GetErrorObj() Returns a reference to the head of the list of errorObj. void ms_ResetErrorList() Clear the current error list. Note that clearing the list invalidates any errorObj handles obtained via the $error->next() method.
Members
Type int string string Name code //See error code constants above message routine
Method
errorObj next() Returns the next errorObj in the list, or NULL if we reached the end of the list.
Example
This example draws a map and reports all errors generated during the draw() call, errors can potentially come from multiple layers.
ms_ResetErrorList(); $img = $map->draw(); $error = ms_GetErrorObj(); while($error && $error->code != MS_NOERR) { printf("Error in %s: %s<br>\n", $error->routine, $error->message); $error = $error->next(); }
234
gridObj
Constructor
The grid is always embedded inside a layer object dened as a grid (layer->connectiontype = MS_GRATICULE) (for more docs : http://trac.osgeo.org/mapserver/wiki/MapServerGrid) A layer can become a grid layer by adding a grid object to it using : ms_newGridObj(layerObj layer)
$oLayer = ms_newlayerobj($oMap); $oLayer->set("name", "GRID"); ms_newgridobj($oLayer); $oLayer->grid->set("labelformat", "DDMMSS");
Members
Type string double double double double double double Name labelformat maxacrs maxinterval maxsubdivide minarcs mininterval minsubdivide
Methods
int set(string property_name, new_value) Set object property to a new value. hashTableObj
Constructor
Instance of hashTableObj is always embedded inside the classObj, layerObj, mapObj and webObj. It is uses a read only.
$hashTable = $oLayer->metadata; $key = null; while ($key = $hashTable->nextkey($key)) echo "Key: ".$key." value: ".$hashTable->get($key)."<br/>";
Methods
void clear() Clear all items in the hashTable (To NULL). string get(string key) Fetch class metadata entry by name. Returns if no entry matches the name. Note that the search is case sensitive. string nextkey(string previousKey) Return the next key or rst key if previousKey = NULL. Return NULL if no item is in the hashTable or end of hashTable is reached
6.3. PHP MapScript
235
int remove(string key) Remove a metadata entry in the hashTable. Returns MS_SUCCESS/MS_FAILURE. int set(string key, string value) Set a metadata entry in the hashTable. Returns MS_SUCCESS/MS_FAILURE. imageObj
Constructor
Instances of imageObj are always created by the mapObj class methods.
Members
Type int int int int string string Name width height resolution resolutionfactor imagepath imageurl Note read-only read-only read-only read-only
Methods
void pasteImage(imageObj srcImg, int transparentColorHex [[, int dstX, int dstY], int angle]) Copy srcImg on top of the current imageObj. transparentColorHex is the color (in 0xrrggbb format) from srcImg that should be considered transparent (i.e. those pixels wont be copied). Pass -1 if you dont want any transparent color. If optional dstx,dsty are provided then it denes the position where the image should be copied (dstx,dsty = top-left corner position). The optional angle is a value between 0 and 360 degrees to rotate the source image counterclockwise. Note that if an angle is specied (even if its value is zero) then the dstx and dsty coordinates specify the CENTER of the destination area. Note: this function works only with 8 bits GD images (PNG or GIF). int saveImage([string lename, MapObj oMap]) Writes image object to specied lename. Passing no lename or an empty lename sends output to stdout. In this case, the PHP header() function should be used to set the documents content-type prior to calling saveImage(). The output format is the one that is currently selected in the map le. The second argument oMap is not manadatory. It is usful when saving to formats like GTIFF that needs georeference informations contained in the map le. On success, it returns either MS_SUCCESS if writing to an external le, or the number of bytes written if output is sent to stdout. string saveWebImage() Writes image to temp directory. Returns image URL. The output format is the one that is currently selected in the map le. labelcacheMemberObj Accessible only through the mapObj (map->getLabel()).
236
Members
Type int int int int int int int string int Name classindex featuresize layerindex markerid numstyles shapeindex status text tileindex Note read-only read-only read-only read-only read-only read-only read-only read-only read-only
Method
None labelcacheObj Accessible only through the mapObj (map->labelcache). This object is only used to give the possiblity to free the label cache (map->labelcache->freeCache())
Method
boolean freeCache() Free the label cache. Always returns MS_SUCCESS. Ex : map->labelcache->freeCache(); labelObj
Constructor
labelObj are always embedded inside other classes.
Members
Type int double int int int colorObj colorObj int int int colorObj Name align angle anglemode antialias autominfeaturesize backgroundcolor (deprecated since 6.0) backgroundshadowcolor (deprecated since 6.0) backgroundshadowsizex (deprecated since 6.0) backgroundshadowsizey (deprecated since 6.0) buffer color Continued on next page
6.3. PHP MapScript
237
Table 6.1 continued from previous page string encoding string font int force int maxlength int maxsize int mindistance int minfeaturesize int minlength int minsize int numstyles int offsetx int offsety colorObj outlinecolor int outlinewidth int partials int position int priority int repeatdistance colorObj shadowcolor int shadowsizex int shadowsizey int size int type int wrap
Methods
int deleteStyle(int index) Delete the style specied by the style index. If there are any style that follow the deleted style, their index will decrease by 1. string getBinding(const labelbinding) Get the attribute binding for a specied label property. Returns NULL if there is no binding for this property. Example:
$oLabel->setbinding(MS_LABEL_BINDING_COLOR, "FIELD_NAME_COLOR"); echo $oLabel->getbinding(MS_LABEL_BINDING_COLOR); // FIELD_NAME_COLOR
styleObj getStyle(int index) Return the style object using an index. index >= 0 && index < label->numstyles. void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. int moveStyleDown(int index) The style specied by the style index will be moved down into the array of classes. Returns MS_SUCCESS or MS_FAILURE. ex label->movestyledown(0) will have the effect of moving style 0 up to position 1, and the style at position 1 will be moved to position 0. int moveStyleUp(int index) The style specied by the style index will be moved up into the array of classes. Returns MS_SUCCESS or MS_FAILURE. ex label->movestyleup(1) will have the effect of moving style 1 up to position 0, and the style at position 0 will be moved to position 1. int removeBinding(const labelbinding) Remove the attribute binding for a specled style property. Example:
238
$oStyle->removebinding(MS_LABEL_BINDING_COLOR);
int set(string property_name, new_value) Set object property to a new value. int setBinding(const labelbinding, string value) Set the attribute binding for a specied label property. Example:
$oLabel->setbinding(MS_LABEL_BINDING_COLOR, "FIELD_NAME_COLOR");
This would bind the color parameter with the data (ie will extract the value of the color from the eld called FIELD_NAME_COLOR int updateFromString(string snippet) Update MS_SUCCESS/MS_FAILURE. layerObj a label from a string snippet. Returns
Constructor
Layer Objects can be returned by the mapObj class, or can be created using:
layerObj ms_newLayerObj(MapObj map [, layerObj layer])
A second optional argument can be given to ms_newLayerObj() to create the new layer as a copy of an existing layer. If a layer is given as argument then all members of a this layer will be copied in the new layer created.
Members
Type int hashTableObj string string clusterObj string int string int int string string gridObj string string int int string double double string int Name annotate bindvals classgroup classitem cluster connection connectiontype data debug dump lteritem footer grid group header index labelcache labelitem labelmaxscaledenom labelminscaledenom labelrequires maxfeatures Note
read-only, use setConnectionType() to set it
deprecated since 6.0
only available on a layer dened as grid (MS_GRATICULE)
read-only
Continued on next page
6.3. PHP MapScript
239
double hashTableObj double string int int colorObj int projectionObj int string int int int string double string string string double int int int
Table 6.2 continued from previous page maxscaledenom metadata minscaledenom name num_processing numclasses read-only offsite opacity projection postlabelcache requires sizeunits startindex status MS_ON, MS_OFF, MS_DEFAULT or MS_DELETE styleitem symbolscaledenom template tileindex tileitem tolerance toleranceunits transform type
Methods
int updateFromString(string snippet) Update MS_SUCCESS/MS_FAILURE. a layer from a string snippet. Returns
/*modify the name */ $oLayer->updateFromString(LAYER NAME land_fn2 END); /*add a new class*/ $oLayer->updateFromString(LAYER CLASS STYLE COLOR 255 255 0 END END END);
int set(string property_name, new_value) Set object property to a new value. int draw(imageObj image) Draw a single layer, add labels to cache if required. MS_FAILURE on error. int drawQuery(imageObj image) Draw query map for a single layer. classObj getClass(int classIndex) Returns a classObj from the layer given an index value (0=rst class) int getClassIndex(shape, scaledenom [, classgroup, numclasses]) Get the class index of a shape for a given scale. Returns -1 if no class matches. classgroup is an array of class ids to check (Optionnal). numclasses is the number of classes that the classgroup array contains. By default, all the layer classes will be checked. int queryByPoint(pointObj point, int mode, double buffer) Query layer at point location specied in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Passing buffer -1 defaults to tolerances set in the map le (in pixels) but you can use a constant buffer (specied in ground units) instead. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). Returns MS_SUCCESS or
240
int queryByRect(rectObj rect) Query layer using a rectangle specied in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). int queryByShape(shapeObj shape) Query layer based on a single shape, the shape has to be a polygon at this point. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). int queryByFeatures(int slayer) Perform a query set based on a previous set of results from another layer. At present the results MUST be based on a polygon layer. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). int queryByAttributes(string qitem, string qstring, int mode) Query layer for shapes that intersect current map extents. qitem is the item (attribute) on which the query is performed, and qstring is the expression to match. The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Note that the layers FILTER/FILTERITEM are ignored by this function. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). int setFilter(string expression) Set layer lter expression. string getFilterString() Returns the expression for this layer or NULL on error. string getProjection() Returns a string representation of the projection. Returns NULL on error or if no projection is set. int setProjection(string proj_params) Set layer projection and coordinate system. Parameters are given as a single string of comma-delimited PROJ.4 parameters. Returns MS_SUCCESS or MS_FAILURE on error. int setWKTProjection(string proj_params) Same as setProjection(), but takes an OGC WKT projection denition string as input. Note: setWKTProjection requires GDAL support int getNumResults() Returns the number of results in the last query. resultObj getResult(int index) Returns a resultObj by index from a layer object with index in the range 0 to numresults-1. Returns a valid object or FALSE(0) if index is invalid. rectObj getResultsBounds() Returns the bounding box of the latest result. int open() Open the layer for use with getShape(). Returns MS_SUCCESS/MS_FAILURE. int whichshapes(rectobj) Performs a spatial, and optionally an attribute based feature search. The function basically prepares things so that candidate features can be accessed by query or drawing functions (eg using nextshape function). Returns MS_SUCCESS, MS_FAILURE or MS_DONE. MS_DONE is returned if the layer extent does not overlap the rectObj. shapeobj nextShape() Called after msWhichShapes has been called to actually retrieve shapes within a given area. Returns a shape object or NULL on error.
$map = ms_newmapobj("d:/msapps/gmap-ms40/htdocs/gmap75.map"); $layer = $map->getLayerByName(road); $status = $layer->open(); $status = $layer->whichShapes($map->extent); while ($shape = $layer->nextShape())
6.3. PHP MapScript
241
{ echo $shape->index ."<br>\n"; } $layer->close();
void close() Close layer previously opened with open(). rectObj getExtent() Returns the layers data extents or NULL on error. If the layers EXTENT member is set then this value is used, otherwise this call opens/closes the layer to read the extents. This is quick on shapeles, but can be an expensive operation on some le formats or data sources. This function is safe to use on both opened or closed layers: it is not necessary to call open()/close() before/after calling it. int addFeature(shapeObj shape) Add a new feature in a layer. Returns MS_SUCCESS or MS_FAILURE on error. int getMetaData(string name) Fetch layer metadata entry by name. Returns if no entry matches the name. Note that the search is case sensitive. Note: getMetaDatas query is case sensitive. int setMetaData(string name, string value) Set MS_SUCCESS/MS_FAILURE. a metadata entry for the layer. Returns
int removeMetaData(string name) Remove a metadata entry for the layer. Returns MS_SUCCESS/MS_FAILURE. string getWMSFeatureInfoURL(int clickX, int clickY, int featureCount, string infoFormat) Returns a WMS GetFeatureInfo URL (works only for WMS layers) clickX, clickY is the location of to query in pixel coordinates with (0,0) at the top left of the image. featureCount is the number of results to return. infoFormat is the format the format in which the result should be requested. Depends on remote servers capabilities. MapServer WMS servers support only MIME (and should support GML.1 soon). Returns and outputs a warning if layer is not a WMS layer or if it is not queriable. array getItems() Returns an array containing the items. Must call open function rst. If there are no items, it returns an empty array. int setProcessing(string) Add the string to the processing string list for the layer. The layer->num_processing is incremented by 1. Returns MS_SUCCESS or MS_FAILURE on error.
$oLayer->setprocessing("SCALE_1=AUTO"); $oLayer->setprocessing("SCALE_2=AUTO");
array getProcessing() Returns an array containing the processing strings. If there are no processing strings, it returns an empty array. void clearProcessing() Clears all the processing strings. string executeWFSGetfeature() Executes a GetFeature request on a WFS layer and returns the name of the temporary GML le created. Returns an empty string on error. int applySLD(string sldxml, string namedlayer) Apply the SLD document to the layer object. The matching between the sld document and the layer will be done using the layers name. If a namedlayer argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the layer. See SLD HowTo for more information on the SLD support. int applySLDURL(string sldurl, string namedlayer) Apply the SLD document pointed by the URL to the layer object. The matching between the sld document and the layer will be done using the layers name. If a namedlayer argument is passed (argument is optional), the NamedLayer in the sld that matchs it will be used to style the layer. See SLD HowTo for more information on the SLD support. string generateSLD() Returns an SLD XML string based on all the classes found in the layer (the layer must have STATUS on).
242
int moveclassup(int index) The class specied by the class index will be moved up into the array of layers. Returns MS_SUCCESS or MS_FAILURE. ex layer->moveclassup(1) will have the effect of moving class 1 up to position 0, and the class at position 0 will be moved to position 1. int moveclassdown(int index) The class specied by the class index will be moved down into the array of layers. Returns MS_SUCCESS or MS_FAILURE. ex layer->moveclassdown(0) will have the effect of moving class 0 up to position 1, and the class at position 1 will be moved to position 0. classObj removeClass(int index) Removes the class indicated and returns a copy, or NULL in the case of a failure. Note that subsequent classes will be renumbered by this operation. The numclasses eld contains the number of classes available. boolean isVisible() Returns MS_TRUE/MS_FALSE depending on whether the layer is currently visible in the map (i.e. turned on, in scale, etc.). int setConnectionType(int connectiontype [,string plugin_library]) Changes the connectiontype of the layer and recreates the vtable according to the new connection type. This method should be used instead of setting the connectiontype parameter directly. In the case when the layer.connectiontype = MS_PLUGIN the plugin_library parameter should also be specied so as to select the library to load by MapServer. For the other connection types this parameter is not used. shapeObj getShape(resultObj result]) If the resultObj passed has a valid resultindex, retrieve shapeObj from a layers resultset. (You get it from the resultObj returned by getResult() for instance). Otherwise, it will do a single query on the layer to fetch the shapeindex
$map = new mapObj("gmap75.map"); $l = $map->getLayerByName("popplace"); $l->queryByRect($map->extent); for ($i=0; $i<$l->getNumResults();$i++){ $s = $l->getShape($l->getResult($i)); echo $s->getValue($l,"Name"); echo "\n"; }
array getGridIntersectionCoordinates() Returns an array containing the grid intersection coordinates. If there are no coordinates, it returns an empty array. void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. legendObj
Constructor
Instances of legendObj are always are always embedded inside the mapObj.
6.3. PHP MapScript
243
Members
Type int colorObj int int int int labelObj colorObj int int int string int Name height imagecolor keysizex keysizey keyspacingx keyspacingy label outlinecolor position postlabelcache status template width Note
Color of outline of box, -1 for no outline for embeded legends, MS_UL, MS_UC, ... MS_TRUE, MS_FALSE MS_ON, MS_OFF, MS_EMBED
Methods
void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. int set(string property_name, new_value) Set object property to a new value. int updateFromString(string snippet) Update MS_SUCCESS/MS_FAILURE. lineObj a legend from a string snippet. Returns
Constructor
new lineObj()

LineObj ms_newLineObj()
Members
Type int Name numpoints Note read-only
Methods
int add(pointObj point) Add a point to the end of line. Returns MS_SUCCESS/MS_FAILURE. int addXY(double x, double y [, double m]) Add a point to the end of line. Returns MS_SUCCESS/MS_FAILURE. Note: the 3rd parameter m is used for measured shape les only. It is not mandatory.
244
int addXYZ(double x, double y, double z [, double m]) Add MS_SUCCESS/MS_FAILURE.
point
to
the
end
of
line.
Returns
Note: the 4th parameter m is used for measured shape les only. It is not mandatory. PointObj point(int i) Returns a reference to point number i. int project(projectionObj in, projectionObj out) Project the line from in projection (1st argument) to out projection (2nd argument). Returns MS_SUCCESS/MS_FAILURE. mapObj
Constructor
new mapObj(string map_file_name [, string new_map_path])
or using the old constructors mapObj ms_newMapObj(string map_le_name [, string new_map_path]) Returns a new object to deal with a MapServer map le. mapObj ms_newMapObjFromString(string map_le_string [, string new_map_path]) Construct mapObj from a maple string. Returns a new object to deal with a MapServer map le. a new
Note: By default, the SYMBOLSET, FONTSET, and other paths in the maple are relative to the maple location. If new_map_path is provided then this directory will be used as the base path for all the rewlative paths inside the maple.
Members
Type double int double rectObj string int colorObj int int int int labelcacheObj legendObj string int hashTableObj string int outputformatObj projectionObj querymapObj referenceMapObj Name cellsize debug defresolution extent; fontsetlename height imagecolor keysizex keysizey keyspacingx keyspacingy labelcache legend mappath maxsize metadata name numlayers outputformat projection querymap reference Note
pixels per inch, defaults to 72 read-only, set by setFontSet() see setSize()
no members. Used only to free the label cache (map->labelcache->free()
read-only
Continued on next page
6.3. PHP MapScript
245
double scalebarObj double string int string int webObj int
Table 6.3 continued from previous page resolution pixels per inch, defaults to 72 scalebar scaledenom read-only, set by drawMap() shapepath status symbolsetlename read-only, set by setSymbolSet() units map units type web width see setSize()
Methods
int set(string property_name, new_value) Set map object property to new value. int getsymbolbyname(string symbol_name) Returns the symbol index using the name. symbol getsymbolobjectbyid(int symbolid) Returns the symbol object using a symbol id. Refer to the symbol object reference section for more details. void preparequery() Calculate the scale of the map and set map->scaledenom. imageObj prepareImage() Return a blank image object. imageObj draw() Render map and return an image object or NULL on error. imageObj drawQuery() Render a query map and return an image object or NULL on error. imageObj drawLegend() Render legend and return an image object. imageObj drawReferenceMap() Render reference map and return an image object. imageObj drawScaleBar() Render scale bar and return an image object. int embedlegend(imageObj image) embeds a legend. Actually the legend is just added to the label cache so you must invoke drawLabelCache() to actually do the rendering (unless postlabelcache is set in which case it is drawn right away). Returns MS_SUCCESS or MS_FAILURE on error. int embedScalebar(imageObj image) embeds a scalebar. Actually the scalebar is just added to the label cache so you must invoke drawLabelCache() to actually do the rendering (unless postlabelcache is set in which case it is drawn right away). Returns MS_SUCCESS or MS_FAILURE on error. int drawLabelCache(imageObj image) Renders the labels for a map. Returns MS_SUCCESS or MS_FAILURE on error. labelcacheMemberObj getLabel(int index) Returns a labelcacheMemberObj from the map given an index value (0=rst label). Labelcache has to be enabled.
while ($oLabelCacheMember = $oMap->getLabel($i)) { /* do something with the labelcachemember */ ++$i; }
layerObj getLayer(int index) Returns a layerObj from the map given an index value (0=rst layer) layerObj getLayerByName(string layer_name) Returns a layerObj from the map given a layer name. Returns NULL if layer doesnt exist. colorObj getcolorbyindex(int iCloIndex) Returns a colorObj corresponding to the color index in the palette. void setExtent(double minx, double miny, double maxx, double maxy) Set the map extents using the georef extents passed in argument. Returns MS_SUCCESS or MS_FAILURE on error. 246 Chapter 6. MapScript
int setCenter(pointObj center) Set the map center to the given map point. MS_FAILURE.
Returns MS_SUCCESS or
int offsetExtent(double x, double y) Offset the map extent based on the given distances in map coordinates. Returns MS_SUCCESS or MS_FAILURE. int scaleExtent(double zoomfactor, double minscaledenom, double maxscaledenom) Scale the map extent using the zoomfactor and ensure the extent within the minscaledenom and maxscaledenom domain. If minscaledenom and/or maxscaledenom is 0 then the parameter is not taken into account. Returns MS_SUCCESS or MS_FAILURE. int setRotation(double rotation_angle) Set map rotation angle. The map view rectangle (specied in EXTENTS) will be rotated by the indicated angle in the counterclockwise direction. Note that this implies the rendered map will be rotated by the angle in the clockwise direction. Returns MS_SUCCESS or MS_FAILURE. int setSize(int width, int height) Set the map width and height. This method updates the internal geotransform and other data structures required for map rotation so it should be used instead of setting the width and height members directly. Returns MS_SUCCESS or MS_FAILURE. int zoompoint(int nZoomFactor, pointObj oPixelPos, int nImageWidth, int nImageHeight, rectObj oGeorefExt) Zoom to a given XY postion. Returns MS_SUCCESS or MS_FAILURE on error. Parameters are : Zoom factor : positive values do zoom in, negative values zoom out. Factor of 1 will recenter. Pixel position (pointObj) : x, y coordinates of the click, with (0,0) at the top-left Width : width in pixel of the current image. Height : Height in pixel of the current image. Georef extent (rectObj) : current georef extents. MaxGeoref extent (rectObj) : (optional) maximum georef extents. If provided then it will be impossible to zoom/pan outside of those extents. int zoomrectangle(rectObj oPixelExt, int nImageWidth, int nImageHeight, rectObj oGeorefExt) Set the map extents to a given extents. Returns MS_SUCCESS or MS_FAILURE on error. Parameters are : oPixelExt (rect object) : Pixel Extents Width : width in pixel of the current image. Height : Height in pixel of the current image. Georef extent (rectObj) : current georef extents.
int zoomscale(double nScaleDenom, pointObj oPixelPos, int nImageWidth, int nImageHeight, rectObj oGeorefExt [, rectObj oM Zoom in or out to a given XY position so that the map is displayed at specied scale. Returns MS_SUCCESS or MS_FAILURE on error. Parameters are : ScaleDenom : Scale denominator of the scale at which the map should be displayed. Pixel position (pointObj) : x, y coordinates of the click, with (0,0) at the top-left Width : width in pixel of the current image. Height : Height in pixel of the current image. Georef extent (rectObj) : current georef extents.
6.3. PHP MapScript
247
MaxGeoref extent (rectObj) : (optional) maximum georef extents. If provided then it will be impossible to zoom/pan outside of those extents. int queryByPoint(pointObj point, int mode, double buffer) Query all selected layers in map at point location specied in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a Templating value or that match any class in a layer that contains a LAYER TEMPLATE value. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Passing buffer -1 defaults to tolerances set in the map le (in pixels) but you can use a constant buffer (specied in ground units) instead. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). int queryByRect(rectObj rect) Query all selected layers in map using a rectangle specied in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a Templating value or that match any class in a layer that contains a LAYER TEMPLATE value. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). int queryByShape(shapeObj shape) Query all selected layers in map based on a single shape, the shape has to be a polygon at this point. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). int queryByFeatures(int slayer) Perform a query based on a previous set of results from a layer. At present the results MUST be based on a polygon layer. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the @ control operator). int queryByIndex(layerindex, tileindex, shapeindex[, addtoquery]) Add a specic shape on a given layer to the query result. If addtoquery (which is a non mandatory argument) is set to MS_TRUE, the shape will be added to the existing query list. Default behavior is to free the existing query list and add only the new shape. int savequery(lename) Save the current query in a le. Returns MS_SUCESS or MS_FAILURE. Can be used with loadquery int loadquery(lename) Loads a query from a le. Returns MS_SUCESS or MS_FAILURE. To be used with savequery. void freequery(layerindex) Frees the query result on a specied layer. If the layerindex is -1, all queries on layers will be freed. int save(string lename) Save current map object state to a le. Returns -1 on error. Use absolute path. If a relative path is used, then it will be relative to the maple location. string getProjection() Returns a string representation of the projection. Returns NULL on error or if no projection is set. int setProjection(string proj_params, boolean bSetUnitsAndExtents) Set map projection and coordinate system. Returns MS_SUCCESS or MS_FAILURE on error. Parameters are given as a single string of comma-delimited PROJ.4 parameters. The argument : bSetUnitsAndExtents is used to automatically update the map units and extents based on the new projection. Possible values are MS_TRUE and MS_FALSE. By defualt it is set at MS_FALSE. int setWKTProjection(string proj_params, boolean bSetUnitsAndExtents) Same as setProjection(), but takes an OGC WKT projection denition string as input. Returns MS_SUCCESS or MS_FAILURE on error. Note: setWKTProjection requires GDAL support int getMetaData(string name) Fetch metadata entry by name (stored in the WEB object in the map le). Returns if no entry matches the name.
248
Note: getMetaDatas query is case sensitive. int setMetaData(string name, string value) Set a metadata entry for the map (stored in the WEB object in the map le). Returns MS_SUCCESS/MS_FAILURE. int removeMetaData(string name) Remove a metadata entry for the map (stored in the WEB object in the map le). Returns MS_SUCCESS/MS_FAILURE. array getLayersIndexByGroup(string groupname) Return an array containing all the layers indexes given a group name. If there are no layers, it returns an empty array. array getAllGroupNames() Return an array containing all the group names used in the layers. If there are no groups, it returns an empty array. array getAllLayerNames() Return an array containing all the layer names. If there are no layers, it returns an empty array. int moveLayerUp(int layerindex) Move layer up in the hierarcy of drawing. MS_FAILURE on error. Returns MS_SUCCESS or
int moveLayerDown(int layerindex) Move layer down in the hierarcy of drawing. Returns MS_SUCCESS or MS_FAILURE on error. array getLayersDrawingOrder() Return an array containing layers index in the order which they are drawn. If there are no layers, it returns an empty array. boolean setLayersDrawingOrder(array layeryindex) Set the layers order array. The argument passed must be a valid array with all the layers index. Returns MS_SUCCESS or MS_FAILURE on error. string processTemplate(array params, boolean generateimages) Process the template le specied in the web object and return the result in a buffer. The processing consists of opening the template le and replace all the tags found in it. Only tags that have an equivalent element in the map object are replaced (ex [scaledenom]). The are two exceptions to the previous statement : [img], [scalebar], [ref], [legend] would be replaced with the appropriate url if the parameter generateimages is set to MS_TRUE. (Note : the images corresponding to the different objects are generated if the object is set to MS_ON in the map le) the user can use the params parameter to specify tags and their values. For example if the user have a specic tag call [my_tag] and would like it to be replaced by value_of_my_tag he would do
$tmparray["my_tag"] = "value_of_my_tag"; $map->processtemplate($tmparray, MS_FALSE);
string processquerytemplate(array params, boolean generateimages) Process query template les and return the result in a buffer. Second argument generateimages is not mandatory. If not given it will be set to TRUE. See Also: processtemplate string processlegendtemplate(array params) Process legend template les and return the result in a buffer. See Also: processtemplate int setSymbolSet(string leName) Load and set a symbol le dynamically. int getNumSymbols() Return the number of symbols in map. int setFontSet(string leName) Load and set a new FONTSET. int selectOutputFormat(string type) Selects the output format to be used in the map. MS_SUCCESS/MS_FAILURE. Returns
6.3. PHP MapScript
249
Note: the type used should correspond to one of the output formats declared in the map le. The type argument passed is compared with the mimetype parameter in the output format structure and then to the name parameter in the structure. int saveMapContext(string lename) Available only if WMS support is enabled. Save current map object state in WMS Map Context format. Only WMS layers are saved in the WMS Map Context XML le. Returns MS_SUCCESS/MS_FAILURE. int loadMapContext(string lename [, boolean unique_layer_name]) Available only if WMS support is enabled. Load a WMS Map Context XML le into the current mapObj. If the map already contains some layers then the layers dened in the WMS Map context document are added to the current map. The 2nd argument unique_layer_name is optional and if set to MS_TRUE layers created will have a unique name (unique prex added to the name). If set to MS_FALSE the layer name will be the the same name as in the context. The default value is MS_FALSE. Returns MS_SUCCESS/MS_FAILURE. int applySLD(string sldxml) Apply the SLD document to the map le. The matching between the sld document and the map le will be done using the layers name. See SLD HowTo for more information on the SLD support. int applySLDURL(string sldurl) Apply the SLD document pointed by the URL to the map le. The matching between the sld document and the map le will be done using the layers name. See SLD HowTo for more information on the SLD support. string generateSLD() Returns an SLD XML string based on all the classes found in all the layers that have STATUS on. string getcongoption(string key) Returns the cong value associated with the key. Returns an empty sting if key not found. int setcongoption(string key, string value) Sets a cong parameter using the key and the value passed int applycongoptions() Applies the cong options set in the map le. For example setting the PROJ_LIB using the setcongoption only modies the value in the map object. applycongoptions will actually change the PROJ_LIB value that will be used when dealing with projection. int loadowsparameters(owsrequest request, string version) Load OWS request parameters (BBOX, LAYERS, &c.) into map. Returns MS_SUCCESS or MS_FAILURE. 2nd argument version is not mandatory. If not given, the version will be set to 1.1.1 int owsdispatch(owsrequest request) Processes and executes the passed OpenGIS Web Services request on the map. Returns MS_DONE (2) if there is no valid OWS request in the req object, MS_SUCCESS (0) if an OWS request was successfully processed and MS_FAILURE (1) if an OWS request was not successfully processed. OWS requests include WMS, WFS, WCS and SOS requests supported by MapServer. Results of a dispatched request are written to stdout and can be captured using the msIO services (ie. ms_ioinstallstdouttobuffer() and ms_iogetstdoutbufferstring()) int insertLayer( layerObj layer [, int nIndex=-1 ] ) Insert a copy of layer into the Map at index nIndex. The default value of nIndex is -1, which means the last possible index. Returns the index of the new Layer, or -1 in the case of a failure. layerObj removeLayer( int nIndex ) Remove a layer from the mapObj. The argument is the index of the layer to be removed. Returns the removed layerObj on success, else null. void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources.
250
outputformatObj
Constructor
Instance of outputformatObj is always embedded inside the mapObj. It is uses a read only. No constructor available (coming soon, see ticket 979)
Members
Type string string int string string int int Name driver extension imagemode mimetype name renderer transparent Note
MS_IMAGEMODE_* value.
Methods
string getOption(string property_name) Returns the associated value for the format option property passed as argument. Returns an empty string if property not found. int set(string property_name, new_value) Set object property to a new value. void setOption(string property_name, string new_value) Add or Modify the format option list. return true on success.
$oMap->outputformat->setOption("OUTPUT_TYPE", "RASTER");
int validate() Checks some internal consistency issues, Returns MS_SUCCESS or MS_FAILURE. Some problems are xed up internally. May produce debug output if issues encountered. OwsrequestObj
Constructor
new OWSRequestObj()

request = ms_newOwsrequestObj();
Create a new ows request object.
Members
Type int int Name numparams (read-only) type (read-only): MS_GET_REQUEST or MS_POST_REQUEST
6.3. PHP MapScript
251
Methods
string getname(int index) Return the name of the parameter at index in the requests array of parameter names. string getvalue(int index) Return the value of the parameter at index in the requests array of parameter values. string getvaluebyname(string name) Return the value associated with the parameter name. int loadparams() Initializes the OWSRequest object from the cgi environment variables REQUEST_METHOD, QUERY_STRING and HTTP_COOKIE. Returns the number of name/value pairs collected. int setparameter(string name, string value) Set a request parameter. For example :
$request->setparameter(REQUEST, GetMap);
int addparameter(string name, string value) Add a request parameter, even if the parameter key was previousely set. This is useful when multiple parameters with the same key are required. For example :
$request->addparameter(SIZE, x(100)); $request->addparameter(SIZE, y(100));
pointObj
Constructor
new pointObj()

PointObj ms_newPointObj()
Members
Type double double double double Name x y z m Note
used for 3d shape les. set to 0 for other types used only for measured shape les - set to 0 for other types
Methods
double distanceToLine(pointObject p1, pointObject p2) Calculates distance between a point ad a lined dened by the two points passed in argument. double distanceToPoint(pointObj poPoint) Calculates distance between two points. double distanceToShape(shapeObj shape) Calculates the minimum distance between a point and a shape. int draw(mapObj map, layerObj layer, imageObj img, int class_index, string text) Draws the individual point using layer. The class_index is used to classify the point based on the classes dened for the layer. The text string is used to annotate the point. Returns MS_SUCCESS/MS_FAILURE. int project(projectionObj in, projectionObj out) Project the point from in projection (1st argument) to out projection (2nd argument). Returns MS_SUCCESS/MS_FAILURE.
252
int setXY(double x, double y [, double m]) Set X,Y coordinate values. Note: the 3rd parameter m is used for measured shape les only. It is not mandatory. int setXYZ(double x, double y , double z, [, double m]) Set X,Y,Z coordinate values. Note: the 4th parameter m is used for measured shape les only. It is not mandatory. projectionObj
Constructor
new projectionObj(string projectionString)

ProjectionObj ms_newProjectionObj(string projectionString)
Creates a projection object based on the projection string passed as argument.

$projInObj = ms_newprojectionobj("proj=latlong")
will create a geographic projection class. The following example will convert a lat/long point to an LCC projection:
$projInObj = ms_newprojectionobj("proj=latlong"); $projOutObj = ms_newprojectionobj("proj=lcc,ellps=GRS80,lat_0=49,". "lon_0=-95,lat_1=49,lat_2=77"); $poPoint = ms_newpointobj(); $poPoint->setXY(-92.0, 62.0); $poPoint->project($projInObj, $projOutObj);
Methods
int getUnits() Returns the units of a projection object. Returns -1 on error. querymapObj
Constructor
Instances of querymapObj are always are always embedded inside the mapObj.
Members
Type colorObj int int int Name color height width style Note
MS_NORMAL, MS_HILITE, MS_SELECTED
6.3. PHP MapScript
253
Methods
void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. int set(string property_name, new_value) Set object property to a new value. int updateFromString(string snippet) Update MS_SUCCESS/MS_FAILURE. rectObj a queryMap object from a string snippet. Returns
Constructor
rectObj are sometimes embedded inside other objects. New ones can also be created with:
new rectObj()

RectObj ms_newRectObj()
Note: the members (minx, miny, maxx ,maxy) are initialized to -1;
Members:
Type double double double double Name minx miny maxx maxy
Methods
int draw(mapObj map, layerObj layer, imageObj img, int class_index, string text) Draws the individual rectangle using layer. The class_index is used to classify the rectangle based on the classes dened for the layer. The text string is used to annotate the rectangle. Returns MS_SUCCESS/MS_FAILURE. double t(int width, int height) Adjust extents of the rectangle to t the width/height specied. int project(projectionObj in, projectionObj out) Project the rectangle from in projection (1st argument) to out projection (2nd argument). Returns MS_SUCCESS/MS_FAILURE. int set(string property_name, new_value) Set object property to a new value. void setextent(double minx, double miny, double maxx, double maxy) Set the rectangle extents. referenceMapObj
Constructor
Instances of referenceMapObj are always embedded inside the mapObj.
254
Members
Type ColorObj int rectObj string int string int int int ColorObj int int Name color height extent image marker markername markersize maxboxsize minboxsize outlinecolor status width
Methods
void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. int set(string property_name, new_value) Set object property to a new value. int updateFromString(string snippet) Update a referenceMap object from a string snippet. MS_SUCCESS/MS_FAILURE. resultObj Returns
Constructor
new resultObj(int shapeindex)
or using the layerObjs getResult() method.
Members
Type int int int int Name classindex resultindex shapeindex tileindex Note read-only read-only read-only read-only
Method
None
6.3. PHP MapScript
255
scalebarObj
Constructor
Instances of scalebarObj are always embedded inside the mapObj.
Members
Type int colorObj colorObj int colorObj int labelObj colorObj int int int int int int Name align backgroundcolor color height imagecolor intervals label outlinecolor position postlabelcache status style units width Note
for embeded scalebars, MS_UL, MS_UC, ... MS_ON, MS_OFF, MS_EMBED
Methods
void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. int set(string property_name, new_value) Set object property to a new value. int setimagecolor(int red, int green, int blue) Sets the imagecolor propery (baclground) of the object. Returns MS_SUCCESS or MS_FAILURE on error. int updateFromString(string snippet) Update MS_SUCCESS/MS_FAILURE. shapeleObj a scalebar from a string snippet. Returns
Constructor
new shapeFileObj(string filename, int type)

shapefileObj ms_newShapefileObj(string filename, int type)
Opens a shapele and returns a new object to deal with it. Filename should be passed with no extension. To create a new le (or overwrite an existing one), type should be one of MS_SHP_POINT, MS_SHP_ARC, MS_SHP_POLYGON or MS_SHP_MULTIPOINT. Pass type as -1 to open an existing le for read-only access, and type=-2 to open an existing le for update (append).
256
Members
Type rectObj int string int Name bounds numshapes source type Note read-only read-only read-only read-only
Methods
int addPoint(pointObj point) Appends a point to an open shapele. int addShape(shapeObj shape) Appends a shape to an open shapele. void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. Note: The shape le is closed (and changes committed) when the object is destroyed. You can explicitly close and save the changes by calling $shapele->free(); unset($shapele), which will also free the php object. rectObj getExtent(int i) Retrieve a shapes bounding box by index. shapeObj getPoint(int i) Retrieve point by index. shapeObj getShape(int i) Retrieve shape by index. shapeObj getTransformed(mapObj map, int i) Retrieve shape by index. shapeObj
Constructor
new shapeObj(int type)

ShapeObj ms_newShapeObj(int type)
type is one of MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON or MS_SHAPE_NULL

ShapeObj ms_shapeObjFromWkt(string wkt)
Creates new shape object from WKT string.
6.3. PHP MapScript
257
Members
Type rectObj int int int int int string int array Name bounds classindex index numlines numvalues tileindex text type values Note read-only
read-only read-only read-only read-only read-only
The values array is an associative array with the attribute values for this shape. It is set only on shapes obtained from layer->getShape(). The key to the values in the array is the attribute name, e.g.
$population = $shape->values["Population"];
Methods
int set(string property_name, new_value) Set object property to a new value. int add(lineObj line) Add a line (i.e. a part) to the shape. LineObj line(int i) Returns a reference to line number i. int draw(mapObj map, layerObj layer, imageObj img) Draws the individual shape using layer. MS_SUCCESS/MS_FAILURE. Returns
boolean contains(pointObj point) Returns MS_TRUE if the point is inside the shape, MS_FALSE otherwise. boolean intersects(shapeObj shape) Returns MS_TRUE if the two shapes intersect, MS_FALSE otherwise. int project(projectionObj in, projectionObj out) Project the shape from in projection (1st argument) to out projection (2nd argument). Returns MS_SUCCESS/MS_FAILURE. pointObj getpointusingmeasure(double m) Apply only on Measured shape les. Given a measure m, retun the corresponding XY location on the shapeobject. pointObj getmeasureusingpoint(pointObject point) Apply only on Measured shape les. Given an XY Location, nd the nearest point on the shape object. Return a point object of this point with the m value set. string getvalue(layerObj layer, string ledname) Returns the value for a given eld name. shapeobj buffer(width) Returns a new buffered shapeObj based on the supplied distance (given in the coordinates of the existing shapeObj). Only available if php/mapscript is built with GEOS library. shapeobj convexhull() Returns a shape object representing the convex hull of shape. Only available if php/mapscript is built with GEOS library. shapeobj boundary() Returns the boundary of the shape. Only available if php/mapscript is built with GEOS library. int containsShape(shapeobj shape2) Returns true if shape2 passed as argument is entirely within the shape. Else return false. Only available if php/mapscript is built with GEOS library. shapeobj union(shapeobj shape) Returns a shape object representing the union of the shape object with the one passed as parameter. Only available if php/mapscript is built with GEOS library shapeobj intersection(shapeobj shape) Returns a shape object representing the intersection of the shape object with the one passed as parameter. Only available if php/mapscript is built with GEOS library.
258
shapeobj difference(shapeobj shape) Returns a shape object representing the difference of the shape object with the one passed as parameter. Only available if php/mapscript is built with GEOS library. shapeobj symdifference(shapeobj shape) Returns the computed symmetric difference of the supplied and existing shape. Only available if php/mapscript is built with GEOS library. int overlaps(shapeobj shape) Returns true if the shape passed as argument overlaps the shape. Else returns false. Only available if php/mapscript is built with GEOS library. int within(shapeobj shape2) Returns true if the shape is entirely within the shape2 passed as argument. Else returns false. Only available if php/mapscript is built with GEOS library. int crosses(shapeobj shape) Returns true if the shape passed as argument crosses the shape. Else return false. Only available if php/mapscript is built with GEOS library. int touches(shapeobj shape) Returns true if the shape passed as argument touches the shape. Else return false. Only available if php/mapscript is built with GEOS library. int equals(shapeobj shape) Returns true if the shape passed as argument is equal to the shape (geometry only). Else return false. Only available if php/mapscript is built with GEOS library. int disjoint(shapeobj shape) Returns true if the shape passed as argument is disjoint to the shape. Else return false. Only available if php/mapscript is built with GEOS library. pointObj getCentroid() Returns a point object representing the centroid of the shape. Only available if php/mapscript is built with GEOS library. double getArea() Returns the area of the shape (if applicable). Only available if php/mapscript is built with GEOS library. double getLength() Returns the length (or perimeter) of the shape. Only available if php/mapscript is built with GEOS library. pointObj getLabelPoint() Returns a point object with coordinates suitable for labelling the shape. string toWkt() Returns WKT representation of the shapes geometry. int setBounds() Updates the bounds property of the shape. Must be called to calculate new bounding box after new parts have been added. shapeObj simplify(double tolerance) Given a tolerance, returns a simplied shape object or NULL on error. Only available if php/mapscript is built with GEOS library (>=3.0). shapeObj topologySimplifyPreservingSimplify(double tolerance) Given a tolerance, returns a simplied shape object or NULL on error. Only available if php/mapscript is built with GEOS library (>=3.0). void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. styleObj
Constructor
Instances of styleObj are always embedded inside a classObj or labelObj.
new styleObj(classObj class [, styleObj style]) // or new styleObj(labelObj label [, styleObj style])
or using the old constructor (do not support a labelObj at rst argument)
6.3. PHP MapScript
259
styleObj ms_newStyleObj(classObj class [, styleObj style])
The second argument style is optional. If given, the new style created will be a copy of the style passed as argument.
Members
Type double int colorObj colorObj double double double double double double int int int colorObj string double int string double Name angle antialias backgroundcolor color maxsize maxvalue maxwidth minsize minvalue minwidth offsetx offsety opacity outlinecolor rangeitem size symbol symbolname width Note
only supported for the AGG driver
Methods
void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. string getBinding(const stylebinding) Get the attribute binding for a specled style property. Returns NULL if there is no binding for this property.
$oStyle->setbinding(MS_STYLE_BINDING_COLOR, "FIELD_NAME_COLOR"); echo $oStyle->getbinding(MS_STYLE_BINDING_COLOR); // FIELD_NAME_COLOR
string getGeomTransform() int removeBinding(const stylebinding) Remove the attribute binding for a specled style property. Added in MapServer 5.0.
$oStyle->removebinding(MS_STYLE_BINDING_COLOR);
int set(string property_name, new_value) Set object property to a new value. int setBinding(const stylebinding, string value) Set the attribute binding for a specled style property. Added in MapServer 5.0.
$oStyle->setbinding(MS_STYLE_BINDING_COLOR, "FIELD_NAME_COLOR");
This would bind the color parameter with the data (ie will extract the value of the color from the eld called FIELD_NAME_COLOR
260
int setGeomTransform(string value) int updateFromString(string snippet) Update MS_SUCCESS/MS_FAILURE. symbolObj a style from a string snippet. Returns
Constructor
new symbolObj(mapObj map, string symbolname)

int ms_newSymbolObj(mapObj map, string symbolname)
Creates a new symbol with default values in the symbolist. Note: Using the new constructor, the symbol is automatically returned. The old constructor returns the id of the new symbol. If a symbol with the same name exists, it (or its id) will be returned. To get a symbol object using the old constructor, you need to use a method on the map object:
$nId = ms_newSymbolObj($map, "symbol-test"); $oSymbol = $map->getSymbolObjectById($nId);
Members
Type int string int string string int int int string int double double int int Name antialias character lled font imagepath inmaple patternlength position name numpoints sizex sizey transparent transparentcolor Note
read-only If set to TRUE, the symbol will be saved inside the maple. read-only
read-only
Methods
void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. array getpatternarray() Returns an array containing the pattern. If there is no pattern, it returns an empty array. array getpointsarray() Returns an array containing the points of the symbol. Refer to setpoints to see how the array should be interpreted. If there are no points, it returns an empty array.
6.3. PHP MapScript
261
int set(string property_name, new_value) Set object property to a new value. int setimagepath(char lename) Loads a pixmap symbol specied by the lename. The le should be of either Gif or Png format. int setpattern(array int) Set the pattern MS_SUCCESS/MS_FAILURE. of the symbol (used for dash patterns). Returns
int setpoints(array double) Set the points of the symbol. Note that the values passed is an array containing the x and y values of the points. Returns MS_SUCCESS/MS_FAILURE. Example:
$array[0] = 1 # x value of the first point $array[1] = 0 # y values of the first point $array[2] = 1 # x value of the 2nd point ....
Example of usage
1. create a symbol to be used as a dash line
$nId = ms_newsymbolobj($gpoMap, "mydash"); $oSymbol = $gpoMap->getsymbolobjectbyid($nId); $oSymbol->set("filled", MS_TRUE); $oSymbol->set("sizex", 1); $oSymbol->set("sizey", 1); $oSymbol->set("inmapfile", MS_TRUE); $aPoints[0] = 1; $aPoints[1] = 1; $oSymbol->setpoints($aPoints); $aPattern[0] = 10; $aPattern[1] = 5; $aPattern[2] = 5; $aPattern[3] = 10; $oSymbol->setpattern($aPattern); $style->set("symbolname", "mydash");
2. Create a TrueType symbol

$nId = ms_newSymbolObj($gpoMap, "ttfSymbol"); $oSymbol = $gpoMap->getSymbolObjectById($nId); $oSymbol->set("type", MS_SYMBOL_TRUETYPE); $oSymbol->set("filled", true); $oSymbol->set("character", "D"); $oSymbol->set("font", "ttfFontName");
webObj
Constructor
Instances of webObj are always are always embedded inside the mapObj.
262
Members
Type string string string rectObj string string string string string string double string hashTableObj double string string string string Name browseformat empty error extent footer header imagepath imageurl legendformat log maxscaledenom maxtemplate metadata minscaledenom mintemplate queryformat template temppath Note read-only read-only read-only
Methods
void free() Free the object properties and break the internal references. Note that you have to unset the php variable to free totally the resources. int set(string property_name, new_value) Set object property to a new value. int updateFromString(string snippet) Update MS_SUCCESS/MS_FAILURE. a web object from a string snippet. Returns
6.3.8 Memory Management

Normally, you should not have to worry about the memory management because php has a garbage collector and will free resources for you. If you write only small scripts that dont do a lot of processing, its not worth to care about that. Everything will be freed at the end of the script. However, it may be useful to free resources during the execution if the script executes many tasks. To do so, youll have to call the free() method of the mapscript objects and unset the php variables. The purpose of the free methods is to break the circular references between an object and its properties to allow the zend engine to free the resources. Heres an example of a script that doesnt free things during the execution:
$map = new mapObj("mapfile.map"); $of = $map->outputformat; echo $map->extent->minx." - ".$map->extent->miny." - ".$map->extent->maxx. " - ".$map->extent->maxy."\n"; echo "Outputformat name: $of->name\n"; unset($of); unset($map); // Even if we unset the php variables, resources wont be freed // Resources will be only freed at the end of the script
and the same script that frees resources as soon as it can
6.3. PHP MapScript
263
$map = new mapObj("mapfile.map"); $of = $map->outputformat; echo $map->extent->minx." - ".$map->extent->miny." - ".$map->extent->maxx." - ".$map->extent->maxy."\ echo "Outputformat name: $of->name\n"; unset($of); $map->free(); // break the circular references // at this place, the outputformat ($of) and the rect object ($map->extent) resources are freed unset($map); // the map object is immediately freed after the unset (before the end of the script)
6.4 Python MapScript Appendix

Author Sean Gillies Revision $Revision: 12108 $ Date $Date: 2011-08-24 01:58:40 -0700 (Wed, 24 Aug 2011) $ Contents Python MapScript Appendix Introduction Classes Exception Handling
6.4.1 Introduction
The Python MapScript module contains some class extension methods that have not yet been implemented for other languages.
6.4.2 Classes
References to sections below will be added here as the documentation grows. imageObj The Python Imaging Library, http://www.pythonware.com/products/pil/, is an indispensible tool for image manipulation. The extensions to imageObj are all geared towards better integration of PIL in MapScript applications.
imageObj Methods
imageObj( PyObject arg1, PyObject arg2 [, PyObject arg3 ] ) [imageObj] Create a new instance which is either empty or read from a Python le-like object that refers to a GD format image. The constructor has 2 different modes. In the blank image mode, arg1 and arg2 should be the desired width and height in pixels, and the optional arg3 should be either an instance of outputFormatObj or a GD driver name as a shortcut to a format. In the image le mode, arg1 should be a lename or a Python le or le-like object. If the le-like object does not have a seek attribute (such as a urllib resource handle), then a GD driver name must be provided as arg2.
264
Heres an example of creating a 320 pixel wide by 240 pixel high JPEG using the constructors blank image mode:
image = mapscript.imageObj(320, 240, GD/JPEG)
In image le mode, interesting values of arg1 to try are instances of StringIO:

s = StringIO() pil_image.save(s) # Save an image manipulated with PIL ms_image = imageObj(s)
Or the le-like object returned from urlopen

url = urllib.urlopen(http://mapserver.gis.umn.edu/bugs/ant.jpg) ms_image = imageObj(url, GD/JPEG)
write( [ PyObject le ] ) [void] Write image data to a Python le-like object. Default is stdout. pointObj
pointObj Methods
__str__() [string] Return a string formatted like
{ x: %f , y: %f }
with the coordinate values substituted appropriately. Usage example:

>>> p = mapscript.pointObj(1, 1) >>> str(p) { x: 1.000000 , y: 1.000000 }
Note that the return value can be conveniently evald into a Python dictionary:
>>> p_dict = eval(str(p)) >>> p_dict[x] 1.000000
rectObj
rectObj Methods
__contains__( pointObj point ) [boolean] Returns True if point is inside the rectangle, otherwise returns False.
>>> r >>> p >>> p False >>> p True = mapscript.rectObj(0, 0, 1, 1) = mapscript.pointObj(2, 0) in r not in r # outside
__str__() [string] Return a string formatted like

{ minx: %f , miny: %f , maxx: %f , maxy: %f }
with the bounding values substituted appropriately. Usage example:
6.4. Python MapScript Appendix
265
>>> r = mapscript.rectObj(0, 0, 1, 1) >>> str(r) { minx: 0.000000 , miny: 0.000000 , maxx: 1.000000 , maxy: 1.000000 }
Note that the return value can be conveniently evald into a Python dictionary:
>>> r_dict = eval(str(r)) >>> r_dict[minx] 0.000000
6.4.3 Exception Handling

The Python MapScript module maps a few MapServer errors into Python exceptions. Attempting to load a non-existent maple raises an IOError, for example
>>> import mapscript >>> mapfile = /no/such/file.map >>> m = mapscript.mapObj(mapfile) Traceback (most recent call last): File "<stdin>", line 1, in ? File "/usr/lib/python2.3/site-packages/mapscript.py", line 799, in __init__ newobj = _mapscript.new_mapObj(*args) IOError: msLoadMap(): Unable to access file. (/no/such/file.map) >>>
The message of the error is written by msSetError and so is the same message that CGI mapserv users see in error logs.
6.5 Python MapScript Image Generation

Author Sean Gillies Revision $Revision: 8295 $ Date $Date: 2008-12-26 21:08:04 -0800 (Fri, 26 Dec 2008) $ Last Updated 2008/07/15 Table of Contents Python MapScript Image Generation Introduction Imagery Overview The imageObj Class Image Output Images and Symbols
6.5.1 Introduction
The MapScript HOWTO docs are intended to complement the API reference with examples of usage for specic subjects. All examples in this document refer to the maple and testing layers distributed with MapServer 4.2+ and found under mapserver/tests.
266
Pseudocode All examples will use a pseudocode that is consistent with the language independent API reference. Each line is a statement. For object attributes and methods we use the dot, ., operator. Creation and deletion of objects will be indicated by new and del keywords. Other than that, the pseudocode looks a lot like Python.
6.5.2 Imagery Overview

The most common use of MapServer and MapScript is to create map imagery using the built-in GD format drivers: GD/GIF, GD/PNG, GD/PNG24, and GD/JPEG. This imagery might be saved to a le on disk or be streamed directly to another device.
6.5.3 The imageObj Class

Imagery is represented in MapScript by the imageObj class. Please see the API Reference (MapScript.txt) for class attribute and method details. Creating imageObj from a mapObj The mapObj class has two methods that return instances of imageObj: draw, and prepareImage. The rst returns a full-edged map image just as one would obtain from the mapserv CGI program
test_map = MapScript.mapObj(tests/test.map) map_image = test_map.draw()
A properly sized and formatted blank image, without any layers, symbols, or labels, will be generated by prepareImage
blank_image = test_map.prepareImage()
Creating a new imageObj The imageObj class constructor creates new instances without need of a map
format = MapScript.outputFormatObj(GD/JPEG) image = MapScript.imageObj(300, 200, format) # 300 wide, 200 high JPEG
and can even initialize from a le on disk

# First three args are overriden by attributes of the disk image file disk_image = MapScript.imageObj(-1, -1, NULL, tests/test.png)
6.5.4 Image Output

Creating les on disk Imagery is saved to disk by using the save method. By accessing the extension attribute of an images format, the proper le extension can be used without making any assumptions
filename = test. + map_image.format.extension map_image.save(filename)
6.5. Python MapScript Image Generation
267
If the image is using a GDAL/GTiff-based format, a GeoTIFF le can be created on disk by adding a mapObj as a second optional argument to save
map_image.save(filename, test_map)
Direct Output An image can be dumped to an open lehandle using the write method. By default, the lehandle is stdout
# Send an image to a web browser print "Content-type: " + map_image.format.mimetype + "\n\n" map_image.write()
This method is not fully functional for all SWIG MapScript languages. See the API Reference (MapScript.txt) for details. The write method is new in 4.4.
6.5.5 Images and Symbols

The symbolObj::getImage() method will return an instance of imageObj for pixmap symbols
symbol = test_map.symbolset.getSymbolByName(home-png) image = symbol.getImage()
There is a symmetric setImage method which loads imagery into a symbol, allowing pixmap symbols to be created dynamically
new_symbol = MapScript.symbolObj(from_image) new_symbol.type = MapScript.MS_SYMBOL_PIXMAP new_symbol.setImage(image) index = test_map.symbolset.appendSymbol(new_symbol)
The get/setImage methods are new in MapServer 4.4.
6.6 Maple Manipulation

Author Sean Gillies Revision $Revision: 12501 $ Date $Date: 2011-08-28 02:51:27 -0700 (Sun, 28 Aug 2011) $ Contents Maple Manipulation Introduction Maple Overview The mapObj Class Children of mapObj Metadata
268
6.6.1 Introduction
The MapScript HowTo docs are intended to complement the API reference with examples of usage for specic subjects. All examples in this document refer to the maple and testing layers distributed with MapServer 4.2+ and found under mapserver/tests. Pseudocode All examples will use a pseudocode that is consistent with the language independent API reference. Each line is a statement. For object attributes and methods we use the dot, ., operator. Creation and deletion of objects will be indicated by new and del keywords. Other than that, the pseudocode looks a lot like Python.
6.6.2 Maple Overview

By Maple here, I mean all the elements that can occur in (nearly) arbitrary numbers within a MapScript mapObj: Layers, Classes, and Styles. MapServer 4.4 has greatly improved capability to manipulate these objects.
6.6.3 The mapObj Class

An instance of mapObj is a parent for zero to many layerObj children. New instances The maple path argument to the mapscript.mapObj constructor is now optional
empty_map = new mapscript.mapObj
generates a default mapObj with no layers. A mapObj is initialized from a maple on disk in the usual manner:
test_map = new mapscript.mapObj(tests/test.map)
Cloning An independent copy, less result and label caches, of a mapObj can be produced by the new mapObj.clone() method:
clone_map = test_map.clone()
Note: the Java MapScript module implements a cloneMap method to avoid conict with the clone method of Javas Object class. Saving A mapObj can be saved to disk using the save method:
clone_map.save(clone.map)
Frankly, the msSaveMap() function which is the foundation for mapObj::save is incomplete. Your mileage may vary.
6.6.4 Children of mapObj

There is a common parent/child object API for Layers, Classes, and Styles in MapServer 4.4. 6.6. Maple Manipulation 269
Referencing a Child References to Layer, Class, and Style children are obtained by getChild-like methods of their parent:
layer_i = test_map.getLayer(i) class_ij = layer_i.getClass(j) style_ijk = class_ij.getStyle(k)
These references are for convenience only. MapScript doesnt have any reference counting, and you are certain to run into trouble if you try to use these references after the parent mapObj has been deleted and freed from memory. Cloning a Child A completely independent Layer, Class, or Style can be created using the clone method of layerObj, classObj, and styleObj:
clone_layer = layer_i.clone()
This instance has no parent, and is self-owned. New Children Uninitialized instances of layerObj, classObj, or styleObj can be created with the new constructors:
new_layer = new mapscript.layerObj new_class = new mapscript.classObj new_style = new mapscript.styleObj
and are added to a parent object using insertChild-like methods of the parent which returns the index at which the child was inserted:
li = test_map.insertLayer(new_layer) ci = test_map.getLayer(li).insertClass(new_class) si = test_map.getLayer(li).getClass(ci).insertStyle(new_style)
The insert* methods create a completely new copy of the object and store it in the parent with all ownership taken on by the parent. see the API reference for more details. Backwards Compatibility The old style child object constructors with the parent object as a single argument:
new_layer = new mapscript.layerObj(test_map) new_class = new mapscript.classObj(new_layer) new_style = new mapscript.styleObj(new_class)
remain in MapServer 4.4. Removing Children Child objects can be removed with removeChild-like methods of parents, which return independent copies of the removed object:
270
# following from the insertion example ... # remove the inserted style, returns a copy of the original new_style removed_style = test_map.getLayer(li).getClass(ci).removeStyle(si) removed_class = test_map.getLayer(li).removeClass(ci) removed_layer = test_map.removeLayer(li)
6.6.5 Metadata
Map, Layer, and Class metadata are the other arbitrarily numbered elements (well, up to the built-in limit of 41) of a maple. New API In MapServer 4.4, the metadata attributes of mapObj.web, layerObj, and classObj are instances of hashTableObj, a class which functions like a limited dictionary
layer.metadata.set(wms_name, foo) name = layer.metadata.get(wms_name) # returns foo
You can iterate over all keys in a hashTableObj like

key = NULL while (1): key = layer.metadata.nextKey(key) if key == NULL: break value = layer.metadata.get(key) ...
See the API Reference (mapscript.txt) for more details. Backwards Compatibility for Metadata The old getMetaData and setMetaData methods of mapObj, layerObj, and classObj remain for use by older programs.
6.7 Querying
Author Sean Gillies Revision $Revision: 12501 $ Date $Date: 2011-08-28 02:51:27 -0700 (Sun, 28 Aug 2011) $ Contents Querying Introduction Querying Overview Attribute Queries Spatial Queries
6.7. Querying
271
6.7.1 Introduction
All examples in this document refer to the maple and testing layers distributed with MapServer 4.2+ and found under mapserver/tests. Pseudocode All examples will use a pseudocode that is consistent with the language independent API reference. Each line is a statement. For object attributes and methods we use the dot, ., operator. Creation and deletion of objects will be indicated by new and del keywords. Other than that, the pseudocode looks a lot like Python.
6.7.2 Querying Overview

The Query Result Set Map layers can be queried to select features using spatial query methods or the attribute query method. Ignoring for the moment whether we are executing a spatial or attribute query, results are obtained like so:
layer.query() results = layer.getResults() # not an actual method!
In the case of a failed query or query with zero results, getResults returns NULL. Result Set Members Individual members of the query results are obtained like:
... if results: for i in range(results.numresults): result = results.getResult(i) # continued
# iterate over results
This result object is a handle, of sorts, for a feature of the layer, having shapeindex and tileindex attributes that can be used as arguments to getFeature. Resulting Features The previous example code can now be extended to the case of obtaining all queried features:
layer.query() results = layer.getResults() if results: # open layer in preparation of reading shapes layer.open() for i in range(results.numresults): result = results.getResult(i) layer.getFeature(result.shapeindex, result.tileindex) ... # do something with this feature
272
# Close when done layer.close()
Backwards Compatibility Scripts using the 4.2 API can continue to access query result members through layer methods:
for i in range(layer.getNumResults()): result = layer.getResult(0)
but should adopt the new API for use in new work.
6.7.3 Attribute Queries

By Attributes queryByAttributes()
6.7.4 Spatial Queries

By Rectangle queryByRect() By Point queryByRect() By Shape queryByShape() By Selection queryByFeatures()
6.8 MapScript Variables

Author Howard Butler Contact hobu.inc at gmail.com Revision $Revision: 12501 $ Date $Date: 2011-08-28 02:51:27 -0700 (Sun, 28 Aug 2011) $
6.8. MapScript Variables
273
Contents MapScript Variables Version Logical Control - Boolean Values Logical Control - Status Values Map Units Layer Types Font Types Label Positions Label Size (Bitmap only) Shape Types Measured Shape Types Shapele Types Query Types File Types Querymap Styles Connection Types DB Connection Types Join Types Line Join Types (for rendering) Image Types Image Modes Symbol Types Return Codes Limiters Error Return Codes
6.8.1 Version
Name MS_VERSION Type character Value 5.2
6.8.2 Logical Control - Boolean Values

Name MS_TRUE MS_ON MS_YES MS_FALSE MS_OFF MS_NO Type integer integer integer integer integer integer Value 1 1 1 0 0 0
6.8.3 Logical Control - Status Values

Name MS_DEFAULT MS_EMBED MS_DELETE Type integer integer integer Value 2 3 4
274
6.8.4 Map Units

Name MS_DD MS_FEET MS_INCHES MS_METERS MS_MILES MS_NAUTICALMILES MS_PIXELS Type integer integer integer integer integer integer integer Value
6.8.5 Layer Types

Name MS_LAYER_POINT MS_LAYER_LINE MS_LAYER_POLYGON MS_LAYER_RASTER MS_LAYER_ANNOTATION MS_LAYER_QUERY MS_LAYER_CIRCLE MS_LAYER_TILEINDEX Type integer integer integer integer integer integer integer integer Value
6.8.6 Font Types

Name MS_TRUETYPE MS_BITMAP Type integer integer Value
6.8.7 Label Positions

Name MS_UL MS_LL MS_UR MS_LR MS_CL MS_CR MS_UC MS_LC MS_CC MS_AUTO Type integer integer integer integer integer integer integer integer integer integer Value
275
6.8.8 Label Size (Bitmap only)

Name MS_TINY MS_SMALL MS_MEDIUM MS_LARGE MS_GIANT Type integer integer integer integer integer Value
6.8.9 Shape Types

Name MS_SHAPE_POINT MS_SHAPE_LINE MS_SHAPE_POLYGON MS_SHAPE_NULL Type integer integer integer integer Value
6.8.10 Measured Shape Types

Name MS_SHP_POINTM MS_SHP_ARCM MS_SHP_POLYGONM MS_SHP_MULTIPOINTM Type integer integer integer integer Value 21 23 25 28
6.8.11 Shapele Types

Name MS_SHAPEFILE_POINT MS_SHAPEFILE_ARC MS_SHAPEFILE_POLYGON MS_SHAPEFILE_MULTIPOINT Type integer integer integer integer Value 1 3 5 8
6.8.12 Query Types

Name MS_SINGLE MS_MULTIPLE Type integer integer Value 0 1
6.8.13 File Types

Name MS_FILE_MAP MS_FILE_SYMBOL Type integer integer Value
276
6.8.14 Querymap Styles

Name MS_NORMAL MS_HILITE MS_SELECTED Type integer integer integer Value
6.8.15 Connection Types

Name MS_INLINE MS_SHAPEFILE MS_TILED_SHAPEFILE MS_SDE MS_OGR MS_POSTGIS MS_WMS MS_ORACLESPATIAL MS_WFS MS_GRATICULE MS_MYGIS MS_RASTER Type integer integer integer integer integer integer integer integer integer integer integer integer Value
6.8.16 DB Connection Types

Name MS_DB_XBASE MS_DB_CSV MS_DB_MYSQL MS_DB_ORACLE MS_DB_POSTGRES Type integer integer integer integer integer Value
6.8.17 Join Types

Name MS_JOIN_ONE_TO_ONE MS_JOIN_ONE_TO_MANY Type integer integer Value
6.8.18 Line Join Types (for rendering)

Name MS_CJC_NONE MS_CJC_BEVEL MS_CJC_BUTT MS_CJC_MITER MS_CJC_ROUND MS_CJC_SQUARE MS_CJC_TRIANGLE Type integer integer integer integer integer integer integer Value
277
6.8.19 Image Types

Name GD/GIF GD/PNG GD/PNG24 GD/JPEG GD/WBMP swf imagemap pdf GDAL/GTiff Type integer integer integer integer integer integer integer integer integer Value
6.8.20 Image Modes

Name MS_IMAGEMODE_PC256 MS_IMAGEMODE_RGB MS_IMAGEMODE_RGBA MS_IMAGEMODE_INT16 MS_IMAGEMODE_FLOAT32 MS_IMAGEMODE_BYTE MS_IMAGEMODE_NULL MS_NOOVERRIDE MS_GD_ALPHA Type integer integer integer integer integer integer integer integer integer Value
1000
6.8.21 Symbol Types

Name MS_SYMBOL_SIMPLE MS_SYMBOL_VECTOR MS_SYMBOL_ELLIPSE MS_SYMBOL_PIXMAP MS_SYMBOL_TRUETYPE Type integer integer integer integer integer Value
6.8.22 Return Codes

Name MS_SUCCESS MS_FAILURE MS_DONE Type integer integer integer Value
6.8.23 Limiters
Name MS_MAXSYMBOLS MS_MAXVECTORPOINTS MS_MAXSTYLELENGTH MS_IMAGECACHESIZE Type long long long long Value
278
6.8.24 Error Return Codes

Name MS_NOERR MS_IOERR MS_MEMERR MS_TYPEERR MS_SYMERR MS_REGEXERR MS_TTFERR MS_DBFERR MS_GDERR MS_IDENTERR MS_EOFERR MS_PROJERR MS_MISCERR MS_CGIERR MS_WEBERR MS_IMGERR MS_HASHERR MS_JOINERR MS_NOTFOUND MS_SHPERR MS_PARSEERR MS_SDEERR MS_OGRERR MS_QUERYERR MS_WMSERR MS_WMSCONNERR MS_ORACLESPATIALERR MS_WFSERR MS_WFSCONNERR MS_MAPCONTEXTERR MS_HTTPERR MS_CHILDERR MS_WCSERR MS_NUMERRORCODES MESSAGELENGTH ROUTINELENGTH Type long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long Value 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 33 33
279
280
CHAPTER 7
Data Input
7.1 Vector Data

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Author Tyler Mitchell Contact tmitchell at osgeo.org Last Updated 2011-07-18 This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license, visit: http://creativecommons.org/licenses/by-sa/2.0/ca/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. What is vector data? This quote from is a good description of what vector data is: Vector: An abstraction of the real world where positional data is represented in the form of coordinates. In vector data, the basic units of spatial information are points, lines and polygons. Each of these units is composed simply as a series of one or more coordinate points. For example, a line is a collection of related points, and a polygon is a collection of related lines. Vector images are dened mathematically as a series of points joined by lines. Vector-based drawings are resolution independent. This means that they appear at the maximum resolution of the output device, such as a printer or monitor. Each object is self-contained, with properties such as color, shape, outline, size, and position on the screen. From: http://www8.nos.noaa.gov/coris_glossary/index.aspx?letter=v The rest of this document is the data format guide. This guide is structured to show the fundamentals of each MapServer supported data format. Each section discusses one format, ranging from one to several pages in length. The sections typically start with a summary of the most important information about the format, followed by examples of le listings, connection methods, ogrinfo usage and MapServer map le syntax examples. Each section has been designed to stand alone, so you may notice that certain warnings and comments are repeated or redundant. This is intentional. Each format is presented in rough order of popular use, based on a survey of the MapServer community. The following formats are included:
281
7.1.1 Data Format Types

Each type of data is made up of a data source and (one or more) layers. These two denitions apply to MapServer and OGR. Data Source - a group of layers stored in a common repository. This may be a le that handles several layers within it, or a folder that has several les. Layer - a sub-set of a data source often containing information in one type of vector format (point, line, polygon). There are three types of data mapping and GIS data formats. Each type is handled differently. Below are the types and some example formats: File-based- Shapeles, Microstation Design Files (DGN), GeoTIFF images Directory-based - ESRI ArcInfo Coverages, US Census TIGER Database connections - PostGIS, ESRI ArcSDE, MySQL File-based Data File-based data consists of one or more les stored in any arbitrary folder. In many cases a single le is used (e.g. DGN) but ESRI Shapeles, for example, consist of at least 3 les each with a different lename extension: SHP, DBF, SHX. In this case all 3 les are required because they each perform a different task internally. Filenames usually serve as the data source name and contain layers that may or may not be obvious from the lename. In Shapeles, for example, there is one data source per shapele and one layer which has the same name as that of the le. Directory-based Data Directory-based data consists of one or more les stored in a particular way within a parent folder. In some cases (e.g. Coverages) they may also require additional folders in other locations in the le tree in order to be accessed. The directory itself may be the data source. Different les within the directory often represent the layers of data available. For example, ESRI ArcInfo Coverages consist of more than one le with an ADF le extension, within a folder. The PAL.ADF le represents the Polygon data. ARC.ADF holds the arc or line string data. The folder holds the data source and each ADF le is a layer. Database Connections Database Connections are very similar to le and directory-based structures in one respect: they provide geographic coordinate data for MapServer to interpret. That may be oversimplifying what is happening inside MapServer, but in essence all you need is access to the coordinates making up the vector datasets. Database connections provide a stream of coordinate data that is temporarily stored (e.g. in memory) and read by MapServer to create the map. Other attribute or tabular data may also be required, but the focus of this guide is coordinate data. One important distinction between databases must be made. The databases discuss here are spatial databases, those which can hold geographic data in its own data type. This is opposed to strictly tabular databases which cannot hold geographic coordinates in the same way. It is possible to store some very simple coordinate data in regular tables, but for anything but the most simple use a spatial database is required. There are spatial extensions to many databases (open source and commercial). One of the most robust is the PostGIS extension to the PostgreSQL database. This database not only allows the storage of geographic data, but also allows the manipulation of that data using SQL commands. The other open source database with spatial capabilities is MySQL.
282
Chapter 7. Data Input
Connections to databases usually consist of the following pieces of connection information: Host - Directions to the server or computer hosting the database. Database name - The name of the database you wish to access that is running on the host. User name / passwords - Access privileges are usually restricted by user. Note: Some databases (e.g. Oracle) use a name service identier that includes both the host and database names. Access to specic pieces of coordinate data usually require: Table/View name - The name of the table or view holding the coordinate data. Geographic column name - Where the geometry or coordinates are stored.
7.1.2 ArcInfo
ESRI ArcInfo Coverage Files are also known as simply as Coverages and less commonly as ADF les. File listing Coverages are made up of a set of les within a folder. The folder itself is the coverage name. The les roughly represent different layers, usually representing different types of topology or feature types.
> ls /data/coverage/brazil aat.adf arc.adf arx.adf bnd.adf lab.adf prj.adf tic.adf tol.adf
A folder with the name INFO is also part of the coverage. It sits at the same hierarchical level as the coverage folder itself. Therefore, to copy a coverage (using regular le system tools) the coverage folder and the INFO folder must both be copied. The INFO folder holds some catalogue information about the coverage.
> ls /data/coverage/info arc0000.dat arc0001.dat arc0000.nit arc0001.nit arc0002.dat arc0002.nit arc.dir
Data Access / Connection Method CONNECTIONTYPE OGR must be used. The ability to use coverages is not built into MapServer. The path to the coverage folder name is required. The layer name (feature type) is specied in the DATA parameter
OGRINFO Examples
The directory is the data source. Layers are found within the directory. Using ogrinfo on a coverage directory:
> ogrinfo /data/coverage/brazil -summary INFO: Open of brazil using driver AVCBin successful. 1: ARC (Line String) 2: CNT (Point) 3: LAB (Point) 4: PAL (Polygon)
Using ogrinfo to examine the structure of a layer:
7.1. Vector Data
283
> ogrinfo /data/coverage/brazil PAL -summary Had to open data source read-only. INFO: Open of brazil using driver AVCBin successful. Layer name: PAL Geometry: Polygon Feature Count: 1 Extent: (1272793.274958, 795381.617050) - (1287078.382785, 807302.747284) Layer SRS WKT: (unknown) ArcIds: IntegerList (0.0) AREA: Real (18.5) PERIMETER: Real (18.5) F_OPER#: Integer (5.0) F_OPER-ID: Integer (5.0) OPER: String (2.0) FCODE: String (10.0)
Map File Example:

LAYER NAME Brazil_bounds TYPE POLYGON STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "/data/coverage/brazil" DATA "PAL" CLASS NAME "Brazil Admin Areas" STYLE OUTLINECOLOR 153 102 0 SIZE 2 END END END
7.1.3 ArcSDE
Spatial Database Engine (SDE) is one of ESRIs products which enables spatial data to be stored, managed, and quickly retrieved from leading commercial database management systems like Oracle, Microsoft SQL Server, Sybase, IBM DB2, and Informix. Supported ArcSDE Operations Versioned queries (query geometry and attributes from a specied version) queryByAttributes (select geometry and attributes based on the values of an attribute) Limited join support for within-database tables</li> queryByRect (select geometry based on an extent) Projection on the y SDE for Coverages (a read-only type of SDE for coverage, shapele, and ArcStorm/ArcLibrarian repositories) SDE 8.1, 8.2, 8.3, 9.0, 9.1, and 9.2
284
Linux, Windows, and Solaris (platforms that have SDE C API support) Unsupported ArcSDE Operations queryByShape (pass in a shape with MapScript and use it for queries) Direct Connect (bypass SDE to connect directly to the database with the SDE C API) How to make a connection to SDE: Install the SDE C API client libraries for your platform (preferably matched to the server version you are using, ie 8.2 client -> 8.2 server, 8.3 client -> 8.3 server) Compile MapServer with SDE support MapServer Unix Compilation Howto for specic details) Dene a LAYER block in a MapFile that uses SDE as the CONNECTIONTYPE
LAYER NAME states TYPE POLYGON CONNECTION "sdemachine.iastate.edu,port:5151,sde,username,password" CONNECTIONTYPE SDE DATA "HOBU.STATES_LAYER,SHAPE,SDE.DEFAULT" FILTER "where MYCOLUMN is not NULL" PROCESSING "QUERYORDER=ATTRIBUTE" # <-- MapServer 4.10 and above # Within database one-to-one join support # MapServer 5.0 and above PROCESSING "JOINTABLE=SDE_MASTER.GEOSERVWRITE.JOINTABLE" # MapServer 5.0 and above CLASSITEM "SDE_MASTER.GEOSERVWRITE.JOINTABLE.VAL" # MapServer 5.0 and above FILTER "SDE_MASTER.GEOSERVWRITE.JOINTABLE.AQ_TAG=SDE_MASTER.GEOSERVWRITE.JOINTESTLAYER.AQ_TAG" # ObjectID column manipulation # MapServer 5.0 and above PROCESSING "OBJECTID=OBJECTID" TEMPLATE /where/the/template/file/is/located CLASS STYLE SYMBOL circle SIZE 3 COLOR -1 -1 -1 OUTLINECOLOR 0 0 0 END END END
CONNECTION - Order is important!

sdemachine.iastate.edu - The name of the machine you are connecting to. In some instances, this may need to be the IP address of the machine rather than the name if the server running MapServer is not congured to 7.1. Vector Data 285
cascade DNS lookups port:5151 - The port number of SDE. The port: is important as SDE expects you to dene the service in this slot, and it can be other names like sde:oracle (for direct connect) or esri_sde (for systems with port 5151 dened as esri_sde in /etc/services) sde - The database username that the SDE server is using to connect to your database. It is often only important for SDE setups that are connecting to Oracle (and even then, not so important). Just leave it as sde if you dont know what it should be. username - The username that will be connecting to SDE. This user must have been granted rights to select the layer that you will be specifying in the DATA directive. You can use ArcCatalog or the SDE command-line utilities to grant the appropriate rights to layers. password - Password of the user connecting to SDE. Case Sensitive.
DATA - Order is important!

HOBU.STATES_LAYER - The layer name you are querying. This the full name of the table in which the layer resides. If you are using Oracle or Microsoft SQL Server as the DB for SDE, the schema name must also be supplied. SHAPE - The column that contains the geometry. SDE technically allows for storage of multiple geometry types in the same layer, but in practice this isnt desirable. Also, expect to have problems if there are invalid or null geometries in the layer (or versions of the layer). SDE.DEFAULT - As of MapServer 4.2, you can query against a specic version of the layer. SDE supports multi-user editing with versions. If a layer has been Registered with the GeoDatabase and Registered as Versioned (ArcGIS terms), MapServer can query against specied versions of those edits. If not specied, SDE.DEFAULT will be used for all queries. Case Sensitive. Note: The version parameter is located in a different spot than MapServer 4.2, which had it on the CONNECTION string.
TEMPLATE
/where/the/template/le/is/located - A template directive must be specied (can point to a dummy le) in order for MapServer to be able to query attributes from SDE. If you are only going to be drawing layers, this directive is unnecessary and will slow down the query operations of SDE (especially for layers with lots of attribute columns).
PROCESSING
PROCESSING QUERYORDER=ATTRIBUTE - Allows you to force SDE to use the WHERE clause that was dened in your FILTER statement rst, without attempting to hit the spatial index. Only in very special cases will you want to do this. PROCESSING OBJECTID=OBJECTID - If you are having trouble with the SDE driver detecting your unique ID column, you can override it with this processing parameter. Doing so will also have a slight performance benet because it will save a couple of extra queries to the database. PROCESSING ATTRIBUTE_QUALIFIED=TRUE - User can set this option to always use fully qualied attribute names.
286
Within-database Join Support

MapServers SDE driver, as of MapServer 5.0, allows you to join a single attribute table that has no geometries to the layer that you are rendering. This feature allows you to use the data in the joined table much as you would in a composite query that was made with something like PostGIS or Oracle Spatial. That is, the columns in the right table of the join are available for CLASSITEM, LABELITEM and so on. The biggest constraint, however, is that fully qualied names must be used or it most likely will not work. The join support is activated through PROCESSING options. PROCESSING JOINTABLE=SDE_MASTER.GEOSERVWRITE.JOINTABLE - The JOINTABLE processing option tells the driver which table you are joining the current layer to. CLASSITEM SDE_MASTER.GEOSERVWRITE.JOINTABLE.VAL - A CLASSITEM or LABELITEM for a joined table using this mechanism must be fully qualied.
FILTER SDE_MASTER.GEOSERVWRITE.JOINTABLE.AQ_TAG=SDE_MASTER.GEOSERVWRITE.JOINTESTLA - An important part of the join is dening how the join is to be made. Use a FILTER to do so.
7.1.4 DGN
File listing Data are encapsulated in a single le, usually with the sufx .dgn.
0824t.dgn
Data Access / Connection Method Access is available in MapServer through OGR. The CONNECTIONTYPE OGR parameter must be used. The path to the dgn le is required, le extension is needed. All types of features in a DGN le are held in one layer of data. The layer is called elements and is the rst and only layer. The type of feature to be read from the DGN depends on the TYPE parameter in the map le. DGN les typically contain POINT, LINE, POLYGON and ANNOTATION feature types. DGN les contain styling information - how to color and present the data. This is used, optionally, by specifying the STYLEITEM AUTO parameter. Note: DGN les typically use white as a color for their features and therefore are not visible on maps with white backgrounds. OGRINFO Examples Using ogrinfo on a single DGN le:
> ogrinfo /data/dgn/0824t.dgn Had to open data source read-only. INFO: Open of 0842t.dgn using driver DGN successful. 1: elements
7.1. Vector Data
287
Note: No geometry/feature type for the layer is identied because it can be multiple types. DGN les are not really GIS data les. They evolved from drafting formats used by computer aided drafting/design (CADD) programs. They carry a few key attributes which are usually consistent across all DGN les. Most of the attributes relate to graphical styling of features for map presentation, such as ColorIndex, Style, etc. Spatial reference system information is not always encoded into DGN les. This can be a major problem when trying to adequately reference the DGN data in another mapping program. Measurement units can be a problem. In some cases the features could be located in kilometres or feet even though it is not obvious from the output of ogrinfo. Sometimes the only way to identify or correct a problem with units is to open the le in Microstation software. Using ogrinfo to examine the structure of the le/layer:
> ogrinfo -summary /data/dgn/0824t.dgn elements INFO: Open of 0824t.dgn using driver DGN successful. Layer name: elements Geometry: Unknown (any) Feature Count: 22685 Extent: (-513183.050000, 150292.930000) - (-224583.220000, 407463.360000) Layer SRS WKT: (unknown) Type: Integer (2.0) Level: Integer (2.0) GraphicGroup: Integer (4.0) ColorIndex: Integer (3.0) Weight: Integer (2.0) Style: Integer (1.0) EntityNum: Integer (8.0) MSLink: Integer (10.0) Text: String (0.0)
Map File Example:

LAYER NAME dgn TYPE LINE STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "dgn/0824t.dgn" STYLEITEM "AUTO" CLASS END END # Layer
7.1.5 ESRI File Geodatabase

ESRI File Geodatabases exist in a le folder and offer improved performance and size limitations. For more information see the ESRI description page. Note: Only le geodatabases created by AcrGIS 10.0 and above can be read by GDAL/MapServer.
288
File listing File geodatabases are made up of a set of les within a folder. The les are made up of geographic data, attribute data, index les, and lock les. A better description of the le contents can be found here. Data Access / Connection Method File geodatabase access is available through OGR. See the OGR driver page for specic driver information. The driver is available for GDAL >= 1.9.0. The CONNECTION parameter must be used to point to the name of the le folder, and the DATA parameter should be the name of the spatial table (or OGR layer).
CONNECTIONTYPE ogr CONNECTION "filegdb-folder" DATA "layername"
Note: The CONNECTION path is relative to the maple (SHAPEPATH is not used here). Full paths can also be used. OGRINFO Examples First you should make sure that your GDAL/OGR build contains the le geodatabase FileGDB driver, by using the formats command:
>ogrinfo --formats Supported Formats: ... "FileGDB" (read/write) "ESRI Shapefile" (read/write) "MapInfo File" (read/write) "UK .NTF" (readonly) "SDTS" (readonly) "TIGER" (read/write) ...
If you dont have the driver, see GDALs BuildHints page for compiling the driver. Once you have the FileGDB driver you are ready to try an ogrinfo command on your database to get a list of spatial tables. In the example below our folder is named us_states.gdb:
ogrinfo us_states.gdb INFO: Open of us_states.gdb using driver FileGDB successful. 1: statesp020 (Multi Polygon)
Now use ogrinfo to get information on the structure of the statesp020 table:
ogrinfo us_states.gdb statesp020 -summary INFO: Open of us_states.gdb using driver FileGDB successful. Layer name: statesp020 Geometry: Multi Polygon Feature Count: 2895 Extent: (-179.000000, 17.000000) - (179.000000, 71.000000) Layer SRS WKT: GEOGCS["GCS_North_American_1983",
7.1. Vector Data
289
DATUM["North_American_Datum_1983", SPHEROID["GRS_1980",6378137.0,298.257222101]], PRIMEM["Greenwich",0.0], UNIT["Degree",0.017453292519943295]] FID Column = OBJECTID Geometry Column = SHAPE AREA: Real (0.0) PERIMETER: Real (0.0) STATESP020: Real (0.0) STATE: String (0.0) STATE_FIPS: String (0.0)
Maple Example
LAYER NAME "fgdb_poly" TYPE POLYGON STATUS ON CONNECTIONTYPE OGR CONNECTION "../data/filegdb/us_states.gdb" DATA "statesp020" LABELITEM "STATE" CLASS NAME "US States" STYLE COLOR 120 120 120 OUTLINECOLOR 0 0 0 END LABEL COLOR 255 255 255 OUTLINECOLOR 0 0 0 END END END
7.1.6 ESRI Personal Geodatabase (MDB)

ESRI Personal Geodatabases are basically Microsoft Access les that contain spatial information. For more information see the ESRI description page. File listing Similar to other database formats, the mdb le consists of several tables. The geometry is held in a BLOB table column. Data Access / Connection Method Personal geodatabase access is available through OGR. See the OGR driver page for specic driver information. The driver is standard in any win32 build of GDAL/OGR version 1.3.2 or later. For Linux/Unix, MDBTools ODBC drivers can be used for this (with some difculty). OGR uses the names of spatial tables within the personal geodatabase (tables with a Shape column) as layers.
290
The CONNECTION parameter must include the mdb extension, and the DATA parameter should be the name of the spatial table (or OGR layer).
CONNECTIONTYPE ogr CONNECTION "pgeodatabase.mdb" DATA "layername"
OGRINFO Examples First you should make sure that your GDAL/OGR build contains the personal geodatabase PGeo driver, by using the formats command:
>ogrinfo --formats Loaded OGR Format Drivers: ... -> "ODBC" (read/write) -> "PGeo" (readonly) -> "PostgreSQL" (read/write) ...
If you dont have the driver, you might want to try the FWTools or MS4W packages, which include the driver. Once you have the PGeo driver you are ready to try an ogrinfo command on your database to get a list of spatial tables:
>ogrinfo test.mdb INFO: Open of test.mdb using driver PGeo successful. 1: counties
Now use ogrinfo to get information on the structure of the spatial table:
>ogrinfo test.mdb counties -summary INFO: Open of test.mdb using driver PGeo successful. Layer name: counties Geometry: Unknown (any) Feature Count: 67 Extent: (-87.634943, 24.543945) - (-80.031369, 31.000975) Layer SRS WKT: GEOGCS["GCS_WGS_1984", DATUM["WGS_1984", SPHEROID["WGS_1984",6378137.0,298.257223563]], PRIMEM["Greenwich",0.0], UNIT["Degree",0.0174532925199433]] OBJECTID_1: Integer (10.0) OBJECTID: Integer (10.0) NAME: String (32.0) STATE_NAME: String (25.0) STATE_FIPS: String (2.0) CNTY_FIPS: String (3.0) FIPS: String (5.0) ...
Note that you can also use an ODBC connection to access all of the tables in your geodatabase:
>ogrinfo PGeo:testDSN counties -summary INFO: Open of testDSN using driver PGeo successful.
7.1. Vector Data
291
1: counties 2: counties_Shape_Index ...
(where testDSN is the name of your System DSN) Maple Example
Direct Access to MDB

LAYER NAME my_geodatabase TYPE POLYGON CONNECTIONTYPE ogr CONNECTION "test.mdb" DATA "counties" STATUS ON CLASS NAME "counties" STYLE COLOR 255 255 120 END END END
Through an ODBC Connection

LAYER NAME my_geodatabase TYPE POLYGON CONNECTIONTYPE ogr CONNECTION "PGeo:testDSN" DATA "counties" STATUS ON CLASS NAME "counties" STYLE COLOR 255 255 120 END END END
7.1.7 ESRI Shapeles (SHP)

Also known as ESRI ArcView Shapeles or ESRI Shapeles. ESRI is the company that introduced this format. ArcView was the rst product to use shapeles. File listing Shapeles are made up of a minimum of three similarly named les, with different sufxes:
292
Countries_area.dbf Countries_area.shp Countries_area.shx
Data Access / Connection Method Shapele access is built directly into MapServer. It is also available through OGR, but direct access without OGR is recommended and discussed here. The path to the shapele is required. No le extension should be specied. Shapeles only hold one layer of data, therefore no distinction needs to be made. OGRINFO Examples The directory can serve as a data source. Each shapele in a directory serves as a layer. A shapele can also be a data source. In this case the layer has the same prex as the shapele. Using ogrinfo on a directory with multiple shapeles:
> ogrinfo /data/shapefiles/ INFO: Open of /data/shapefiles/ using driver ESRI Shapefile successful. 1: wpg_h2o (Line String) 2: wpg_roads (Line String) 3: wpg_roads_dis (Line String) 4: wpgrestaurants (Point)
Using ogrinfo on a single shapele:

> ogrinfo /data/shapefiles/Countries_area.shp Had to open data source read-only. INFO: Open of Countries_area.shp using driver ESRI Shapefile successful. 1: Countries_area (Polygon)
Using ogrinfo to examine the structure of the le/layer:

> ogrinfo -summary /data/shapefiles/Countries_area.shp Countries_area Had to open data source read-only. INFO: Open of Countries_area.shp using driver ESRI Shapefile successful. Layer name: Countries_area Geometry: Polygon Feature Count: 27458 Extent: (-180.000000, -90.000000) - (180.000000, 83.627419) Layer SRS WKT: (unknown) FAC_ID: Integer (5.0) TILE: Integer (3.0) ARCLIST: String (254.0) NAM: String (77.0) PERIMETER: Real (22.17) POLYGONCOU: Integer (6.0) NA2DESC: String (45.0)
7.1. Vector Data
293
Map File Example:

LAYER NAME my_shapefile TYPE POLYGON DATA countries_area STATUS OFF CLASS NAME "Countries" OUTLINECOLOR 0 0 0 END END
7.1.8 GML
Also known as Geographic Markup Language and GML/XML. GML is a text-based, XML format that can represent vector and attribute data. This is an Open Geospatial Consortium specication for data interchange. More information is available at http://www.opengeospatial.org/standards/gml File listing GML les are usually a single text le with a GML lename extension. Some may use XML as the lename extension:
coal_dep.gml
XML schema documents often accompany GML les that have been translated from some other format (e.g. using the ogr2ogr utility). GML uses sets of nested tags to dene attributes and geometry coordinates. Example of text in a GML le:
<gml:featureMember> <Coal_Deposits fid="1"> <UNKNOWN>0.000</UNKNOWN> <NA>0.000</NA> <ID>2</ID> <ID2>2</ID2> <MARK>7</MARK> <COALKEY>110</COALKEY> <COALKEY2>110</COALKEY2> <ogr:geometryProperty> <gml:Point> <gml:coordinates>78.531,50.694</gml:coordinates> </gml:Point> </ogr:geometryProperty> </Coal_Deposits> </gml:featureMember>
Data Access / Connection Method GML access is available in MapServer through OGR. More information on OGR GML support is available at http://www.gdal.org/ogr/drv_gml.html The CONNECTIONTYPE OGR parameter must be used. The path to the GML le is required, including le extension. There can be multiple layers in a GML le, including multiple feature types.
294
OGRINFO Examples Using ogrinfo on a single GML le:

> ogrinfo /data/gml/coal_dep.gml Had to open data source read-only. INFO: Open of coal_dep.gml using driver GML successful. 1: Coal_Deposits
Using ogrinfo to examine the structure of one layer:

> ogrinfo -summary /data/gml/coal_dep.gml Coal_Deposits Had to open data source read-only. INFO: Open of coal_dep.gml using driver GML successful. Layer name: Coal_Deposits Geometry: Unknown (any) Feature Count: 266 Extent: (23.293650, 37.986340) - (179.272550, 80.969670) Layer SRS WKT: (unknown) UNKNOWN: Real (0.0) NA: Real (0.0) ID: Integer (0.0) ID2: Integer (0.0) MARK: Integer (0.0) COALKEY: Integer (0.0) COALKEY2: Integer (0.0) LONG: Real (0.0) LAT: Real (0.0)
Map File Example:

LAYER NAME coal_deposits TYPE POINT STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "gml/coal_dep.gml" CLASS STYLE COLOR 0 0 0 SYMBOL circle SIZE 6 END END END
7.1.9 GPS Exchange Format (GPX)

GPX (the GPS Exchange Format) is a light-weight XML data format containing GPS data (waypoints, routes, and tracks). For more information see the ofcial GPX site.
7.1. Vector Data
295
File listing All waypoints, routes, and tracks are stored in a single .gpx le. Data Access / Connection Method GPX access is available through OGR. See the OGR driver page for specic driver information. A relative path to the .gpx le can be used in the maple LAYERs CONNECTION string. The feature type is specied in the DATA parameter the tracks feature type will usually be the track line the track_points feature type will usually be the points that make up the track line OGRINFO Examples First you should make sure that your GDAL/OGR build contains the GPX driver, by using the formats command:
>ogrinfo --formats Loaded OGR Format Drivers: ... -> "CSV" (read/write) -> "GML" (read/write) -> "GPX" (read/write) -> "KML" (read/write) ...
If you dont have the driver, you might want to try the FWTools or MS4W packages, which include the driver. Once you have the GPX driver you are ready to try an ogrinfo command on your le to get a list of feature types:
>ogrinfo test.gpx INFO: Open of test.gpx using driver GPX successful. 1: waypoints (Point) 2: routes (Line String) 3: tracks (Multi Line String) 4: route_points (Point) 5: track_points (Point)
Now use ogrinfo to get information on one of the feature types:

>ogrinfo test.gpx track_points -summary INFO: Open of test.gpx using driver GPX successful. Layer name: track_points Geometry: Point Feature Count: 661 Extent: (-66.694270, 47.985570) - (-66.675222, 47.990791) Layer SRS WKT: GEOGCS["WGS 84", DATUM["WGS_1984", SPHEROID["WGS 84",6378137,298.257223563, AUTHORITY["EPSG","7030"]], AUTHORITY["EPSG","6326"]], PRIMEM["Greenwich",0,
296
AUTHORITY["EPSG","8901"]], UNIT["degree",0.01745329251994328, AUTHORITY["EPSG","9122"]], AUTHORITY["EPSG","4326"]] track_fid: Integer (0.0) track_seg_id: Integer (0.0) track_seg_point_id: Integer (0.0) ele: Real (0.0) time: DateTime (0.0) magvar: Real (0.0) geoidheight: Real (0.0) name: String (0.0) cmt: String (0.0) desc: String (0.0) src: String (0.0) ...
Maple Example Since you have conrmed that OGR can read your GPX le, now you can create a MapServer layer:
LAYER NAME gpx TYPE POINT STATUS ON CONNECTIONTYPE OGR CONNECTION test.gpx DATA "track_points" CLASS NAME "gpx" STYLE SYMBOL circle COLOR 0 119 255 SIZE 2 END END END # layer
7.1.10 Inline
Inline features refer to coordinates entered directly into the map le. They are not a le or database format and do not require any DATA or CONNECTION parameters. Instead they use a FEATURE section to dene the coordinates. Inline features can be used to dene points, lines and polygons as if taken from an external le. This requires direct entry of coordinate pairs in the map le using a particular syntax. Data Access / Connection Method This is a native MapServer option that doesnt use any external libraries to support it.
7.1. Vector Data
297
Map File Example
Points
Each FEATURE..END section denes a feature. Multiple points can be dened in a FEATURE section. If multiple points are dened in the same layer, they will have the same CLASS settings, e.g. for colours and styles. Coordinates are entered in the units set in the layers projection. In this case it is assuming the map le projection is using decimal degrees.
LAYER NAME inline_stops TYPE POINT STATUS DEFAULT FEATURE POINTS 72.36 33.82 END TEXT "My House" END FEATURE POINTS 69.43 35.15 71.21 37.95 72.02 38.60 END TEXT "My Stores" END CLASS STYLE COLOR 0 0 250 SYMBOL circle SIZE 6 END END END
Lines
Lines are simply a list of points strung together, but the layer must be TYPE LINE instead of TYPE POINT.
LAYER NAME inline_track TYPE LINE STATUS DEFAULT MAXSCALE 10000000 FEATURE POINTS 72.36 33.82 70.85 34.32 69.43 35.15 70.82 36.08 70.90 37.05 71.21 37.95 END
298
END CLASS STYLE COLOR 255 10 0 SYMBOL circle SIZE 2 END END END
Polygons
Polygons are the same as the line example, just a list of points. They require the TYPE POLYGON parameter. Polygons also require the nal coordinate pair to be the same as the rst, making it a closed polygon.
7.1.11 KML - Keyhole Markup Language

Table of Contents KML - Keyhole Markup Language Links to KML-Related Information Data Access / Connection Method Example 1: Displaying a .KML le Example 2: Displaying a .KMZ le Keyhole Markup Language (KML) is an XML-based language for managing the display of 3D geospatial data. KML is a standard maintained by the Open Geospatial Consoritum (OGC). Links to KML-Related Information Googles KML Reference OGCs KML Specication KML Validator KML Validator (against OGC KML 2.2) Data Access / Connection Method KML access in MapServer is available through OGR. See the OGR driver page for specic driver information. Read support was initially added to GDAL/OGR version 1.5.0. A more complete KML reader was added to GDAL/OGR in version 1.8.0, through the libKML driver (including the ability to read multigeometry, and KMZ les). The CONNECTION parameter must include the kml or kmz extension, and the DATA parameter should be the name of the layer.
CONNECTIONTYPE OGR CONNECTION "filename.kml" DATA "layername"
7.1. Vector Data
299
Example 1: Displaying a .KML le
OGRINFO
First you should make sure that your GDAL/OGR build contains the KML driver, by using the formats command:
>ogrinfo --formats Loaded OGR Format Drivers: ... -> "GML" (read/write) -> "GPX" (read/write) -> "KML" (read/write) ...
If you dont have the driver, you might want to try the FWTools or MS4W packages, which include the driver. Once you have the KML driver you are ready to try an ogrinfo command on your le to get a list of available layers:
>ogrinfo myplaces.kml INFO: Open of myplaces.kml using driver KML successful. 1: Layer #0 (Point)
Now use ogrinfo to get information on the structure of the layer:

>ogrinfo fountains-hotel.kml "Layer #0" -summary Had to open data source read-only. INFO: Open of fountains-hotel.kml using driver KML successful. Layer name: Layer #0 Geometry: Point Feature Count: 1 Extent: (18.424930, -33.919627) - (18.424930, -33.919627) Layer SRS WKT: GEOGCS["WGS 84", DATUM["WGS_1984", SPHEROID["WGS 84",6378137,298.257223563, AUTHORITY["EPSG","7030"]], AUTHORITY["EPSG","6326"]], PRIMEM["Greenwich",0, AUTHORITY["EPSG","8901"]], UNIT["degree",0.01745329251994328, AUTHORITY["EPSG","9122"]], AUTHORITY["EPSG","4326"]] Name: String (0.0) Description: String (0.0)
Maple Example
LAYER NAME "kml_example" TYPE POINT STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "kml/fountains-hotel.kml" DATA "Layer #0"
300
LABELITEM "NAME" CLASS NAME "My Places" STYLE COLOR 250 0 0 OUTLINECOLOR 255 255 255 SYMBOL circle SIZE 6 END LABEL SIZE TINY COLOR 0 0 0 OUTLINECOLOR 255 255 255 POSITION AUTO END END END
Example 2: Displaying a .KMZ le
OGRINFO
First you should make sure that your GDAL/OGR build contains the LIBKML driver, by using the formats command:
>ogrinfo --formats Loaded OGR Format Drivers: ... -> "GML" (read/write) -> "GPX" (read/write) -> "LIBKML" (read/write) -> "KML" (read/write) ...
If you dont have the driver, you might want to try the FWTools or MS4W packages, which include the driver. Or you can follow the compiling notes for libKML and GDAL/OGR. Once you have the LIBKML driver you are ready to try an ogrinfo command on your le to get a list of available layers:
>ogrinfo Lunenburg_Municipality.kmz INFO: Open of Lunenburg_Municipality.kmz using driver LIBKML successful. 1: Lunenburg_Municipality
Now use ogrinfo to get information on the structure of the layer:

>ogrinfo Lunenburg_Municipality.kmz Lunenburg_Municipality -summary INFO: Open of Lunenburg_Municipality.kmz using driver LIBKML successful. Layer name: Lunenburg_Municipality Geometry: Unknown (any) Feature Count: 1 Extent: (-64.946433, 44.133207) - (-64.230281, 44.735125) Layer SRS WKT: GEOGCS["WGS 84",
7.1. Vector Data
301
DATUM["WGS_1984", SPHEROID["WGS 84",6378137,298.257223563, AUTHORITY["EPSG","7030"]], TOWGS84[0,0,0,0,0,0,0], AUTHORITY["EPSG","6326"]], PRIMEM["Greenwich",0, AUTHORITY["EPSG","8901"]], UNIT["degree",0.0174532925199433, AUTHORITY["EPSG","9108"]], AUTHORITY["EPSG","4326"]] Name: String (0.0) description: String (0.0) timestamp: DateTime (0.0) begin: DateTime (0.0) end: DateTime (0.0) altitudeMode: String (0.0) tessellate: Integer (0.0) extrude: Integer (0.0) visibility: Integer (0.0)
Maple Example
LAYER NAME "lunenburg" TYPE POLYGON STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "Lunenburg_Municipality.kmz" DATA "Lunenburg_Municipality" CLASS NAME "Lunenburg" STYLE COLOR 244 244 16 OUTLINECOLOR 199 199 199 END END END # layer
7.1.12 MapInfo
File listing The following les are also associated with .TAB les: .DAT, .ID, .MAP. An example is:
border.DAT border.ID border.MAP border.TAB
The term MID/MIF refers to les with .MID and .MIF extension. Data Access / Connection Method TAB and MID/MIF access is available in MapServer through OGR. 302 Chapter 7. Data Input
The CONNECTIONTYPE OGR parameter must be used. The path to the (*.tab or *.mif) le is required, and the le extension is needed. The path may be relative to the SHAPEPATH MapInfo les already contain styling information. This styling information can be used optionally by specifying the STYLEITEM AUTO parameter in the LAYER object of the map le. Note: If you use STYLEITEM AUTO you must have an empty class in the layer. OGRINFO Examples Using ogrinfo on a single TAB le
> ogrinfo elev5_poly.TAB Had to open data source read-only. INFO: Open of elev5_poly.TAB using driver MapInfo File successful. 1: elev5_poly (Polygon)
Using ogrinfo to examine the structure of the le/layer

> ogrinfo elev5_poly.TAB elev5_poly Had to open data source read-only. INFO: Open of elev5_poly.TAB using driver MapInfo File successful. Layer name: elev5_poly Geometry: Polygon Feature Count: 2236 Extent: (-141.000000, 60.000000) - (-124.403310, 69.300251) Layer SRS WKT: GEOGCS["unnamed", DATUM["MIF 0", SPHEROID["WGS 84 (MAPINFO Datum 0)",6378137.01,298.257223563], TOWGS84[0,0,0,0,0,0,0]], PRIMEM["Greenwich",0], UNIT["degree",0.0174532925199433]] AREA: Real (0.0) PERIMETER: Real (0.0) ELEV5_: Integer (0.0) ELEV5_ID: Integer (0.0) TYPE: Real (4.0) ELEV5: Real (4.0) ...
Map File Example

LAYER NAME Elevation_Poly_5 TYPE POLYGON STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "./hypso/elev5_poly.TAB" STYLEITEM "AUTO" CLASS NAME "Elevation Poly 5"
7.1. Vector Data
303
END END # Layer
7.1.13 MSSQL
Author Tamas Szekeres Contact szekerest at gmail.com Last Updated 2010-10-01 Contents MSSQL Introduction Creating spatial data tables in MSSQL 2008 Connecting to Spatial Data in MSSQL 2008 * Create MapServer Layer * Selecting the type of the geometry column * The expected location on the plugin dll * Using spatial indexes * Layer Processing Options Obtaining binaries containing the MSSQL plugin dll More Information
Introduction Microsoft SQL Server 2008+ supports storing spatial data by using the built in geometry/geography data types. MapServer supports a driver to access these tables containing spatial columns, which is compiled as a plugin (msplugin_mssql2008.dll). Creating spatial data tables in MSSQL 2008 There are several ways to create spatial data tables in MSSQL 2008. Having an existing data you can easily upload that to an MSSQL table by using the ogr2ogr commandline tool and the OGRs MSSQL Spatial driver Connecting to Spatial Data in MSSQL 2008 In order to connect to the MSSQL 2008 spatial database you should set up a valid connection string to the database like the following examples:
Server=.\MSSQLSERVER2008;Database=Maps;Integrated Security=true Server=55.55.55.55,1433;uid=a_user;pwd=a_password;database=a_database;Integrated Security=True
Server=55.55.55.55\SQLEXPRESS,1433;uid=a_user;pwd=a_password;database=a_database;Integrated Security=
304
Create MapServer Layer

Once the connection can be established to the server the layer can be congured to access MSSQL2008 as follows:
LAYER NAME "rivers_mssql_spatial" TYPE POLYGON STATUS DEFAULT CONNECTIONTYPE PLUGIN PLUGIN "msplugin_mssql2008.dll" CONNECTION "Server=.\MSSQLSERVER2008;Database=Maps;Integrated Security=true" DATA "ogr_geometry from rivers USING UNIQUE ogr_fid USING SRID=4326" ... END
The DATA parameter is used to perform the SQL select statement to access your table in MSSQL. The geometry column is required in the select statement; in the above example the ogr_geometry column is the geometry column in the rivers table. The table should also have an unique column (ogr_d) which is provided for random access to the features in the feature query operations. The DATA section should also contain the spatial reference id (SRID) of the features in the data table The SRID is used when specifying the search shapes during the intersect operations which should match with the SRID of the features otherwise no features are returned in a particular query. if you omit specifying the SRID value in the DATA section the diver will use SRID=0 when dening the search shapes.
Selecting the type of the geometry column

For the geometry columns MSSQL supports 2 data types: geometry and geography. By default the driver considers the type of the geometry column is geometry. In case if the type of the geometry column is geography we must specify the data type in the DATA section explicitly, like:
DATA "ogr_geometry(geography) from rivers USING UNIQUE ogr_fid USING SRID=4326"
The expected location on the plugin dll

On Windows platforms the DLLs needed by the program are searched for in the following order: 1. The directory from which the application loaded. 2. The current directory. 3. The system directory. Use the GetSystemDirectory function to get the path of this directory. 4. The 16-bit system directory. 5. The Windows directory. Use the GetWindowsDirectory function to get the path of this directory. 6. The directories that are listed in the PATH environment variable.
Using spatial indexes

In order to speed up the access to the features a spatial index should be created to the geometry column which could easily be done with the OGR MSSQL Spatial driver like:
7.1. Vector Data
305
ogrinfo -sql "create spatial index on rivers" "MSSQL:server=.\MSSQLSERVER2008;database=Maps;Integrate
In general we can safely rely on the query optimizer to select the most appropriate index in the sql query operations. In some cases - however - we should force the optimizer to use the spatial index by specifying the index hint in the DATA section like:
DATA "ogr_geometry from rivers using index ogr_geometry_sidx USING UNIQUE ogr_fid USING SRID=4326"
Layer Processing Options

We can control the behaviour of the MSSQL driver by using the following PROCESSING options: CLOSE_CONNECTION=DEFER - This is where you can enable connection pooling for certain layer types. Connection pooling will allow MapServer to share the handle to an open database or layer connection throughout a single map draw process. Obtaining binaries containing the MSSQL plugin dll Currently the following binary distributions contain msplugin_mssql2008.dll MapServer and GDAL binary and SDK packages MS4W distributions More Information OGR MSSQL Spatial driver page (describes the OGR MSSQL support) ogr2ogr application (describes the ogr2ogr commandline application) Vector Data (MapServer Vector Data Access Guide)
7.1.14 MySQL
Author David Fawcett Contact david.fawcett at moea.state.mn.us Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Last Updated 2010-07-29
306
Contents MySQL Introduction Connecting to Spatial Data in MySQL * Requirements * Verify MySQL Support in OGR Build * Test Connection with ogrinfo * Create MapServer Layer Connecting to non-Spatial Data in MySQL * Requirements * Create .ovf le * Test Connection with ogrinfo * Create MapServer Layer More Information
Introduction The following methods connect to MySQL through OGRs MySQL driver, thus avoiding the need to set up an ODBC connection. Connecting to Spatial Data in MySQL This section describes how to display a spatial MySQL table (meaning that the table has a column of type geometry) in MapServer. OGRs MySQL driver was expanded in OGR version 1.3.2 to support access to MySQL spatial tables.
Requirements
MapServer compiled with OGR support OGR/GDAL version 1.3.2 or more recent compiled with MySQL support
Verify MySQL Support in OGR Build

You can verify that your local build of OGR contains MySQL support by using the ogrinfo commandline utility, and making sure that MySQL is returned:
ogrinfo --formats Supported Formats: -> "ESRI Shapefile" (read/write) -> "MapInfo File" (read/write) ... -> "PostgreSQL" (read/write) -> "MySQL" (read/write) ...
Test Connection with ogrinfo

MySQL connection strings in OGR are in the following format:
7.1. Vector Data
307
MYSQL:database,host=yourhost,user=youruser,password=yourpass,tables=yourtable
Therefore an example ogrinfo command would be:

> ogrinfo MYSQL:test,user=root,password=mysql,port=3306
which should return a list of all of your tables in the test database:
INFO: Open of MYSQL:test,user=root,password=mysql,port=3306 using driver MySQL successful. 1: province (Polygon)
and you can return a summary of the MySQL spatial layer:

> ogrinfo MYSQL:test,user=root,password=mysql,port=3306 province -summary
INFO: Open of MYSQL:test,user=root,password=mysql,port=3306 using driver MySQL successful. Layer name: province Geometry: Polygon Feature Count: 48 Extent: (-13702.315770, 3973784.599548) - (1127752.921471, 4859616.714055) Layer SRS WKT: PROJCS["ED50_UTM_zone_30N", ... FID Column = OGR_FID Geometry Column = SHAPE id: Real (2.0) ...

LAYER NAME "spain_provinces_mysql_spatial" TYPE POLYGON STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "MySQL:test,user=root,password=mysql,port=3306" DATA "SELECT SHAPE,admin_name from province" LABELITEM "admin_name" CLASS NAME "Spain Provinces" STYLE COLOR 240 240 240 OUTLINECOLOR 199 199 199 END LABEL COLOR 0 0 0 FONT sans TYPE truetype SIZE 8 POSITION AUTO PARTIALS FALSE OUTLINECOLOR 255 255 255 END
308
END END # layer
The DATA parameter is used to perform the SQL select statement to access your table in MySQL. The geometry column is required in the select statement; in the above example the SHAPE column is the geometry column in the province table. Connecting to non-Spatial Data in MySQL This section describes how to display a non-spatial MySQL table (meaning the table does not have a column of type geometry) in MapServer. Support for this functionality is found in GDAL/OGR 1.2.6 and older on Windows and GDAL/OGR 1.3.2 on Linux.
Requirements
MySQL database containing a table with elds containing x and y coordinates .ovf le, a small xml le you will create MapServer compiled with OGR version supporting this functinality
Create .ovf le
Here is the .ovf le named aqidata.ovf
<OGRVRTDataSource> <OGRVRTLayer name="aqidata"> <SrcDataSource>MYSQL:aqiTest,user=uuuuu,password=ppppp,host=192.170.1.100,port=3306,tables=te <SrcSQL>SELECT areaID, x, y, sampleValue FROM testdata</SrcSQL> <GeometryType>wkbPoint</GeometryType> <GeometryField encoding="PointFromColumns" x="x" y="y"/> </OGRVRTLayer> </OGRVRTDataSource>
If you look at the connection string in <SrcDataSource> The MySQL database name is aqiTest testdata is the table containing the coordinate data host and port are for MySQL server Use the GeometryField element to tell OGR which elds store the x and y coordinate data. Mine are simply named x and y.
Test Connection with ogrinfo

# usr/local/bin/ogrinfo /maps/aqidata.ovf
ogrinfo returns
7.1. Vector Data
309
ERROR 4: Update access not supported for VRT datasources. Had to open data source read-only. INFO: Open of /maps/aqidata.ovf using driver VRT successful. 1: aqidata (Point)
Dont worry about the error, this is just telling you that it is a read-only driver. If it really bugs you, call ogrinfo with the -ro (read only) ag. To see the actual data
# usr/local/bin/ogrinfo /maps/aqidata.ovf -al

LAYER NAME "MyAqi" STATUS DEFAULT TYPE POINT CONNECTIONTYPE OGR CONNECTION "aqidata.ovf" DATA "aqidata" CLASS NAME "MyClass" STYLE SYMBOL circle SIZE 15 COLOR 0 255 0 END END END
DATA in the LAYER denition should be the same as the name attribute of the OGRVRTLayer element in the ovf le. For this to draw, you need to have a SYMBOLSET dened in your maple and have a symbol called circle in your symbols.sym le. More Information OGR (MapServer OGR document) Vector Data (MapServer Vector Data Access Guide) MySQL wiki page (describes the deprecated mygis support)
7.1.15 NTF
NTF les are mostly used by the United Kingdom Ordnance Survey (OS). For more on the Ordnance Survey, see their website at: http://www.ordnancesurvey.co.uk/oswebsite/ File listing NTF les have an NTF extension.
310
Data Access / Connection Method NTF access requires OGR. The path to the NTF le is required in the CONNECTION string. It may be relative to the SHAPEPATH setting in the map le or the full path. The DATA parameter is used to specify the layer to use OGRINFO Examples Using ogrinfo on an NTF le to retrieve layer names:
> ogrinfo llcontours.ntf ERROR 4: NTF Driver doesnt support update. Had to open data source read-only. INFO: Open of llcontours.ntf using driver UK .NTF successful. 1: LANDLINE_POINT (Point) 2: LANDLINE_LINE (Line String) 3: LANDLINE_NAME (Point) 4: FEATURE_CLASSES (None)
Using ogrinfo to examine the structure of an NTF layer:

> ogrinfo llcontours.ntf LANDLINE_LINE -summary ERROR 4: NTF Driver doesnt support update. Had to open data source read-only. INFO: Open of llcontours.ntf using driver UK .NTF successful. Layer name: LANDLINE_LINE Geometry: Line String Feature Count: 491 Extent: (279000.000000, 187000.000000) - (280000.000000, 188000.000000) Layer SRS WKT: PROJCS["OSGB 1936 / British National Grid", GEOGCS["OSGB 1936", DATUM["OSGB_1936", SPHEROID["Airy 1830",6377563.396,299.3249646, AUTHORITY["EPSG","7001"]], AUTHORITY["EPSG","6277"]], PRIMEM["Greenwich",0, AUTHORITY["EPSG","8901"]], UNIT["degree",0.0174532925199433], AUTHORITY["EPSG","4277"]], PROJECTION["Transverse_Mercator"], PARAMETER["latitude_of_origin",49], PARAMETER["central_meridian",-2], PARAMETER["scale_factor",0.999601272], PARAMETER["false_easting",400000], PARAMETER["false_northing",-100000], UNIT["metre",1, AUTHORITY["EPSG","9001"]], AUTHORITY["EPSG","27700"]] LINE_ID: Integer (6.0) FEAT_CODE: String (4.0) ...
7.1. Vector Data
311
Map File Example:

LAYER NAME ntf_uk TYPE LINE CONNECTIONTYPE OGR CONNECTION "./ntf/llcontours.ntf" DATA "LANDLINE_LINE" STATUS DEFAULT CLASS NAME "Contours" STYLE COLOR 0 150 200 END END END
7.1.16 OGR
Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Last Updated 2010-10-16 Table of Contents OGR Introduction What is OGR? Obtaining and Compiling MapServer with OGR Support Integrating OGR Support with MapServer Applications STYLEITEM AUTO - Rendering Layers Using Style Information from the OGR File Sample Sites Using OGR/MapServer FAQ / Common Problems
Introduction Starting with version 3.5, MapServer included the ability to access vector data sets in formats other than Shapele in their native format using the OGR library. The following document describes the process for implementing OGR support within MapServer applications. Note: Experimental OGR support was included in MapServer version 3.4 but this initial implementation had some limitations and is not covered in this document. This document assumes that you are already familiar with certain aspects of MapServer: MapServer application development and especially setting up .map les. Some compilation skills if you dont have ready access to a pre-compiled installation and need to compile your own copy of MapServer with OGR support. access to OGR utilities, such as ogrinfo, which are available in the FWTools and MS4W packages. Readers should also check out the Vector Data Access Guide, which has lots of examples of how to access specic vector formats.
312
What is OGR? The OGR Simple Features Library is a C++ open source library (and command-line tools) providing read (and sometimes write) access to a variety of vector le formats including ESRI Shapeles, and MapInfo mid/mif and TAB formats. OGR is actually part of the GDAL library, so you will notice that some references point to GDAL (such as the mailing list).
What Does OGR Add to MapServer?

The OGR Simple Features Library allows MapServer users to display several types of vector data les in their native formats. For example, MapInfo Mid/Mif and TAB data do not need to be converted to ESRI shapeles when using OGR support with MapServer.
What Data Formats are Supported?

See http://www.gdal.org/ogr/ogr_formats.html for the latest list of supported formats. At the date this document was written, the following formats were supported: ArcInfo Binary Coverages ArcInfo E00 Coverages Atlas BNA Comma Separated Value (.csv) DODS/OPeNDAP ESRI ArcSDE ESRI Personal GeoDatabase ESRI Shapeles FMEObjects Gateway Goconcept Export GeoJSON GeoRSS GML GMT GRASS GPX Informix DataBlade INGRES INTERLIS KML MapInfo les Memory
7.1. Vector Data
313
Microstation DGN les MySQL ODBC OGDI Vectors Oracle Spatial PostgreSQL SDTS SQLite UK.NTF (National Transfer Format) US Census TIGER/Line VRT - Virtual Datasource X-Plane/Flighgear aeronautical data Note: Some of the above formats (e.g. OGDI) have external dependencies and are not always included in the pre-compiled binary distributions of MapServer with OGR support.* Note: Some of the above formats are not well suited for random access by nature, thats the case of MapInfo MIF/MID les which is a TEXT format and will give very poor performance for a web application. On the other hand, some binary formats such as MapInfo TAB are better suited for random access and will give performance comparable to native shapele access in MapServer.*
How to Get More Information on the OGR Project

More information on the OGR Simple Features Project can be found at http://www.gdal.org/ogr/. The GDAL mailing list can be used for OGR related questions. Always search the list archives before sending new questions. The GDAL Wiki has lots of good information for users and developers. The #gdal IRC channel on irc.freenode.net might also be of help. For info on IRC see the MapServer IRC page. The main developer of the OGR library is Frank Warmerdam and the integration of OGR within MapServer was done by Daniel Morissette. Obtaining and Compiling MapServer with OGR Support Follow the instructions on the OGR page to compile/install OGR/GDAL. Obtain the MapServer source. For UNIX users, see the README.CONFIGURE le in the MapServer source, or see the UNIX Compilation and Installation. If GDAL/OGR is normally installed it should be sufcient to add with-ogr to the congure line before (re)building MapServer. Linux users might want to try FGS, a Linux installer for MapServer. For Windows users, it is recommended to look for a pre-compiled binary on the MapServer site (MS4W is recommended). If you want to compile your own then see the README.WIN32 le in the MapServer source.
314
Integrating OGR Support with MapServer Applications The only change that is needed to integrate OGR support with a MapServer application is with the .map le. The LAYERs DATA parameter is expanded to three parameters (CONNECTIONTYPE OGR, CONNECTION and DATA). The syntax for this differs depending on the type of data being used (the Vector Data Access Guide is an excellent resource for this). In OGR, a data source can be either a set of les that share a common basename (e.g. .shp/.shx/.dbf for ArcView Shapeles, or .tab/.map/.dat/.ind/.id for MapInfo TAB les) or a whole directory of les (e.g. TIGER). Lets call the former File-based data sources and the later Directory-based data sources. When accessing a lebased data source you specify the lename of one of the les in the set (e.g. roads.shp or roads.tab) and when accessing a directory-based data source you specify the directory name and OGR reads all the les in the directory as a single data source with potentially several layers (e.g. TIGER les). Some OGR drivers (e.g. SHP, TAB) can have dual behaviors, that is if theyre pointed to a single le then they behave as a le-based data source and if theyre pointed to a directory then they will behave as a directory-based data source and then every le in the directory becomes a new layer in the data source. See the OGR formats page for more info on the specic le format youre using. (Click on the format name for more specic driver info on that format)
Using OGR Data Sources in the Map File

The .map le LAYER denition for le-based sources is as follows:
LAYER ... CONNECTIONTYPE OGR CONNECTION "<datasource_name>" DATA "<layer_definition>" ... END
<datasource_name> is the name of the datasource to read from and is prexed by the CONNECTION keyword. The exact organization depends on the format driver in use. The format driver to use is automatically selected by OGR based on the nature of the string passed as the datasource, and/or the format of the le referenced by it. For le based datasources this is the name of the le, including the extension, using an absolute path, or a relative path. Relative paths are interpreted relative to the SHAPEPATH rst, if not found then we try again relative to the .map le location. Note: Before version 4.1 the SHAPEPATH was ignored for OGR datasources. For directory based datasources, such as TIGER/Line, or Arc/Info Binary Coverages this is the name of the directory containing the les. If the path is relative it is interpreted relative to the .map le. For virtual datasources such as database systems, and OGDI this is the service connection string and is generally not related to the lesystem. For instance, for Oracle Spatial this might be OCI:warmerda/[email protected]. <layer_denition> is the name, number or SQL denition of the layer to use from the datasource. It is indicated via the DATA keyword in the map le. Layer Name: The (case insenstive) layer name may be used to select a layer. Layer Number: The layer number (starting from 0 for the rst layer) may be used to select a layer. Generally the layer name is preferred to this since it is more self describing. Omitted: If no DATA keyword is provided, this is equivalent to selecting layer 0.
7.1. Vector Data
315
SQL SELECT: If an SQL SELECT statement is used, it is interpreted in a driver specic manner to try and generate a temporary pseudo-layer. For some formats this a restricted subset of SQL is interpreted within OGR. For RDBMS based drivers (such as PostGIS and Oracle) this is passed through to the underlying database. The OGRINFO utility can be used to nd out the list of layers and their names in a data source.
Examples of Layer Denitions Using OGR

Please see the Vector Data Access Guide for details and examples of each data format supported. Example 1. MapInfo TAB le
LAYER NAME "Builtup_Areas_tab" TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "data/tab/092b06_builtup_a.tab" STATUS ON CLASS ... END ... END
Example 2. Microstation DGN le using <layer_index> The entire DGN le is represented in OGR as one layer (see the DGN driver page for more details):
LAYER NAME "dgn" TYPE LINE CONNECTIONTYPE OGR CONNECTION "dgn/santabarbara02.dgn" DATA "0" STATUS ON STYLEITEM "AUTO" CLASS END END # Layer
Example 3. TIGER/Line le using <layer_name>

LAYER NAME "Roads_tig" TYPE line CONNECTIONTYPE OGR CONNECTION "full/path/to/tiger/TGR25001" DATA "CompleteChain" STATUS ON CLASS ... END END
Example 4. Directory of Shapeles using SQL JOIN

LAYER NAME "Parks_cov" TYPE POLYGON
316
CONNECTIONTYPE OGR CONNECTION "data/shppoly" DATA "SELECT eas_id, idlink.Name FROM poly LEFT JOIN idlink ON poly.eas_id = idlink.eas_id" STATUS ON CLASSITEM "idlink.Name" CLASS ... END END
How to Use OGRINFO

OGRINFO is part of the GDAL/OGR distribution (it is also included in FWTools and MS4W). It is an executable that can be used to obtain layer information about OGR supported les. The parameters are: ogrinfo [-ro] [-q] datasource_name [layer [layer...]] -ro opens the le as read only (optional) -q executes in quiet mode, only the layer idex line will be returned (optional) datasource_name is the lename including extension (eg. roads.tab); for TIGER/Line les, datasource_name is the directory containing the TIGER les (eg. ogrinfo TGR25001) Example 5. To get the list of layers in a le:
$ ogrinfo popplace.tab
Had to open data source read-only. INFO: Open of popplace.tab using driver MapInfo File successful. 1: popplace (Point)
which shows that there is one point layer in the popplace.tab le. Example 6. To get a dump of a specic layer, including eld names, projection, etc:
$ ogrinfo popplace.tab popplace Had to open data source read-only. INFO: Open of popplace.tab using driver MapInfo File successful. Layer name: popplace Geometry: Point Feature Count: 497 Layer SRS WKT: PROJCS["unnamed",GEOGCS["unnamed",DATUM["North ...snipped... AREA: Real (15.3) PERIMETER: Real (15.3) POPPLACE_: Real (11.0) POPPLACE_I: Real (15.0) NAME: String (50.0) OGRFeature(popplace):1 AREA (Real) = 0.000 PERIMETER (Real) = 0.000 POPPLACE_ (Real) = 1 POPPLACE_I (Real) = 1 NAME (String) = Port Hope Simpson POINT (2437287.249 1153656.751)
7.1. Vector Data
317
OGRFeature(popplace):2 AREA (Real) = 0.000 PERIMETER (Real) = 0.000 POPPLACE_ (Real) = 2 POPPLACE_I (Real) = 1 NAME (String) = Hopedale ... ...
Example 7. To get a list of layers in a TIGER/Line Directory:

$ ogrinfo TGR25001 Had to open data source read-only. INFO: Open of TGR25001 using driver TIGER successful. 1: CompleteChain (Line String) 2: AltName (None) 3: FeatureIds (None) 4: ZipCodes (None) 5: Landmarks (Point) 6: AreaLandmarks (None) 7: KeyFeatures (None) 8: Polygon (None) 9: EntityNames (Point) 10: IDHistory (None) 11: PolyChainLink (None) 12: PIP (Point) 13: TLIDRange (None) 14: ZipPlus4 (None)
The above example shows that there are 14 layers in the TGR25001 directory. Example 8. To get a summary of a specic TIGER layer, including only eld names, projection, and extent
$ ogrinfo TGR25001 Landmarks -summary Had to open data source read-only. INFO: Open of TGR25001 using driver TIGER successful. Layer name: Landmarks Geometry: Point Feature Count: 777 Extent: (-70.674324, 41.519817) - (-69.969211, 42.046868) Layer SRS WKT: GEOGCS["NAD83",DATUM["North_American_Datum_1983", SPHEROID["GRS 1980",6378137,298.257222101]],PRIMEM["Greenwich",0], UNIT["degree",0.0174532925199433]] MODULE: String (8.0) FILE: String (5.0) STATE: Integer (2.0) COUNTY: Integer (3.0) LAND: Integer (10.0) SOURCE: String (1.0) CFCC: String (3.0) LANAME: String (30.0)
318
Queries Through OGR Format

OGR layers can be queried the same way as regular shapeles in MapServer.
TILEINDEX with OGR

OGR layers can utilize tile indexes in a similar fashion to Shapele based layers. The TILEINDEX keyword should contain the connection string for the tile index le. The tile index le may be any supported OGR format, including shapeles. The TILEITEM keyword in the LAYER denition indicates what attribute from the tile index le should be used as the datasource location. If omitted, the default TILEITEM value is location. The value in the location eld should be a connection string the same as would have been used in the CONNECTION eld for OGR layers. The CONNECTION keyword is not needed (and will be ignored) for layers using the OGR connection type and having the TILEINDEX keyword. Tileindex les can be prepared in an external GIS, or using the OGR utility ogrtindex. Details can be found on the OGR Utilities Page. The following is a simple example of a point layer using a tile index.
LAYER NAME "ogr_points" TYPE POINT CONNECTIONTYPE OGR TILEINDEX "PIP_ogr_tiles.shp,0" STATUS ON CLASS NAME "points" STYLE SYMBOL "default-circle" COLOR 255 0 0 SIZE 6 END END END
OGR tileindex layers should support all normal query and attribute fetching mechanisms, including from MapScript; however, this has not been heavily tested as of April/2002. Please report problems via the MapServer Trac. If auto projection support is used for tileindexed OGR layers, the tileindex is read for the projection (not the component tiles). Problems may (or may not) be encountered if the component tiles have differing schemas (different sets of attributes).
Connection Pooling
For some OGR supported formats, connecting to the dataset is quite expensive in terms of CPU use and amount of disk IO. For instance, establishing access to an S-57 dataset results in a complete read into memory of the data les. Connection pooling control aims at reducing this overhead in situations where the same le is used for several different map layers. To ensure that an OGR supported dataset is only opened once per map render (instead of separately for each map LAYER referencing the dataset, use the CLOSE_CONNECTION PROCESSING option. The default value is for CLOSE_CONNECTION is NORMAL, but if set to DEFER the dataset will be kept open till the map render is complete. It will be reused by any other layers with using the same datasource. Example 9. Preserve S-57 connection for two layers
7.1. Vector Data
319
In this example, we are using the same dataset (NO410810.000) for two layers. To avoid re-reading the dataset, we mark the rst layer to defer closing the connection till layer. In the second (or last) layer we request NORMAL connection handling (though this could have been left out as normal handling is the default).
LAYER NAME "AdminAreas" TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "NO410810.000" DATA "ADMARE" PROCESSING "CLOSE_CONNECTION=DEFER" STATUS ON ... END LAYER NAME "Land Areas" TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "NO410810.000" DATA "LNDARE" PROCESSING "CLOSE_CONNECTION=NORMAL" STATUS ON ... END
1. The text of the CONNECTION keyword must match exactly between layers for the connection to be reused. 2. Some dataset connections are quite memory expensive, and keeping them open may result in increased memory use. 3. If all layers rendered for a particular connection defer closing the connection, it will remain open till MapServer terminates. For normal cgi or MapScript use this is likely OK. 4. This use of CLOSE_CONNECTION handling is unique to OGR layers, and may be changed at some point in the future as part of a broader implementation of connection pooling in MapServer. STYLEITEM AUTO - Rendering Layers Using Style Information from the OGR File Note: This feature is only supported with MapInfo TAB and Microstation DGN les at the moment, but eventually other formats that carry colors and styles at the shape-level may also be supported through OGR.* In MapServer, ArcView, and other shapele-based applications, colors and styles are usually dened at the layer level. This means that all the shapes in a given layer are usually rendered using the same color and styles. On the other hand, some formats supported by OGR such as MapInfo TAB do have color and style information attached to each shape. OGR adds support for the STYLEITEM AUTO layer parameter which allows you to request that the shapes in a layer be rendered using colors and styles coming from the data source instead of being driven by CLASSes as was traditionally done with MapServer.
How to Implement
In order to have a layer rendered using colours and styles coming from the OGR data source, your must do the following: Your layer denition must contain the STYLEITEM AUTO parameter.
320
Your layer denition needs to contain at least one CLASS (which may be empty) and optionally a CLASSITEM to match the expressions if your CLASS contains an expression. The empty CLASS in the layer will be updated dynamically at runtime to contain colours and styles coming from the data source for each shape.
Examples
Example 10. Layer Denition Using STYLEITEM AUTO without a CLASSITEM
LAYER NAME "test_dgn" STATUS ON TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "../data/dgn/test.dgn" # This enables use of colors and styles from the source file. STYLEITEM "AUTO" # Define an empty class that will be filled at runtime from the color and # styles read on each shape in the source file. CLASS END END # layer
Example 11. Layer Denition Using STYLEITEM AUTO with a CLASSITEM

LAYER NAME "Builtup_Areas_tab" TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "data/tab/092b06_builtup_a.tab" STATUS ON # This enables use of colors and styles from the source file. STYLEITEM "AUTO" # Define an empty class that will be filled at runtime from the color and # styles read on each shape in the source file. CLASSITEM "CATEGORY" CLASS EXPRESSION "1" END END
Please Note: CLASS EXPRESSIONs are still working, so it is still possible to query and classify layers that are using STYLEITEM AUTO. The only difference is that instead of using static class denitions, the colors and style will be read from the data le.
Important Notes
NOTE 1 Even though MapInfo and other OGR data sources may support layers with mixed geometry types (e.g. points, lines and polygons in the same le) this is not yet supported in MapServer. So you still have to dene a layer TYPE and make sure that all the shapes in the OGR data source
7.1. Vector Data
321
are compatible with that layer type, otherwise MapServer may produce an error about incompatible geometry types at runtime. NOTE 2 Due to the dynamic nature of this feature, it is not compatible with the labelcache, so the labelcache is automatically disabled for layers that make use of STYLEITEM AUTO. NOTE 3 When you use STYLEITEM AUTO, MapServer tries to match symbol names returned by OGR to names in your symbol le. For a quick solution, try using the following symbol le: http://demo.mapserver.org/ogr-demos/yk_demo/etc/symbols_mapinfo.txt The name of the symbols returned by OGR to MapServer depends on the le format. In the case of MapInfo les, it will be: For old-style symbols (default MapInfo 3.0 symbols numbered 32 to 67) the symbol name will be mapinfosym-## where ## is the symbol number, e.g. mapinfo-sym-32. For Font Symbols, the symbol name is also mapinfo-sym-## where ## is the symbol number in the font. In this case, the name of the font itself is ignored by MapServer. MapInfo also supports custom symbols (bitmap symbols)... Im not sure what you would get from OGR for this, but Im pretty sure that MapServer doesnt do anything useful with them. The OGRINFO utility can be used to nd out exactly which symbol names OGR will return to MapServer. Look at the Style string in the ogrinfo output for each shape that is read.
Mapping of OGR Style Info to the MapServer CLASS Members

Here is the list of style parameters that are currently supported from OGR data sources and how theyre mapped in MapServer: Line color The line colour is mapped to CLASS.COLOR Line thickness The line thickness is mapped to CLASS.STYLE.WIDTH. The default will be 1 pixel line (as it always is with MapServer). Polygon ll color Polygon ll color is mapped directly to CLASS.COLOR Note that at this time, transparent polygons are not supported (theyre always opaque). Polygon outline If a polygon has an outline color and thickness dened in the data source then the same rule as for line color and thickness above will apply, except that the outline color is mapped to CLASS.OUTLINECOLOR Point symbols Point symbol color is directly mapped to CLASS.COLOR. Point symbol size is directly mapped to CLASS.SIZE. If your symbolset contains a symbol called default-marker then this symbol will be used, otherwise the default will be CLASS.SYMBOL=0 (i.e. a 1 pixel dot) It is also possible (with a bit of work) to control which symbol gets used in rendering point symbols. OGR provides MapServer with symbol names, and if the symbol name returned by OGR to MapServer matches the name of one of the symbols in your symbolset then this symbol will be used. For MapInfo point symbols (numbered 32 to 67 in the MapInfo MIF spec), the name returned by OGR is mapinfo-sym-X where X should be replaced with the MapInfo symbol number (e.g. mapinfo-sym-35 is the star symbol). If the OGR symbol id is a web reference (http://.../mysymbol.png), the symbol will be downloaded and a new symbol entry will be created referring to it. Text labels The text string is mapped to CLASS.TEXT Text color is mapped to CLASS.LABEL.COLOR 322 Chapter 7. Data Input
Text background color is mapped to CLASS.LABEL.BACKGROUNDCOLOR Text height is mapped to CLASS.LABEL.SIZE Text angle is mapped to CLASS.LABEL.ANGLE Text font mapping follows the following rules: 1. If TTF fonts are supported: (a) If the native font name (e.g. Arial) is found in your fontset then this font will be used. The font styles bold and italic are supported as follows: Arial bold fontname maps to arial-bold. Arial italic fontname maps to arial-italic. Arial bold italic fontname maps to arial-bold-italic. If the styles are not available, arial will be used. (b) If 1a. failed and a font called default is present in your fontset then this default font will be used. 2. If TTF fonts are not supported or if all above cases failed, then BITMAP MEDIUM font will be used. Transparency If the color parameter from the OGR style contains an alpha value, the value will be used to set the OPACITY parameter in the STYLE object.
Accessing OGR STYLEITEMAUTO Label Styles Through MapScript

OGR STYLEITEMAUTO label styles can be accessed through MapScript, such as PHP/MapScripts getshape() or getvalue() methods, by setting the LAYERs PROCESSING parameter to GETSHAPE_STYLE_ITEMS=all. Therefore, the LAYER may contain:
LAYER ... PROCESSING "GETSHAPE_STYLE_ITEMS=all" ... END
The following label styles are supported:
7.1. Vector Data
323
Label Style
Description
OGR:LabelFont Comma-delimited list of fonts names OGR:LabelSize Numeric value with units OGR:LabelText Label text string OGR:LabelAngle Rotation angle (in degrees) OGR:LabelFColorForeground color OGR:LabelBColorBackground color OGR:LabelPlacement is the text drawn relative to the features geometry How OGR:LabelAnchorA value from 1 to 12 dening the labels position relative to the point to which it is attached. OGR:LabelDx X offset OGR:LabelDy Y offset OGR:LabelPerp Perpendicular offset OGR:LabelBold Bold text OGR:LabelItalic Italic text OGR:LabelUnderline Underlined text OGR:LabelPriorityNumeric value dening the order in which style parts should be drawn. OGR:LabelStrikeout Strike out text (gdal >= 1.4.0) OGR:LabelStretchStretch factor changes the width of all characters in the font by factor percent. (gdal >= 1.4.0) OGR:LabelAdjHorHorizontally adjacent text (gdal >= 1.4.0) OGR:LabelAdjVert ertically adjacent text (gdal >= 1.4.0) V OGR:LabelHColorShadow color (gdal >= 1.4.0) OGR:LabelOColorOutline color (gdal > 1.6.0)
MapServer Version Implemented 5.4 5.2.0 5.2.0 5.2.0 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4 5.4
Please see the OGR Feature Style Specication document for more details on those specic styles. Sample Sites Using OGR/MapServer The following sites use OGRs STYLEITEM AUTO feature: http://demo.mapserver.org/ogr-demos/yk_demo/demo_init.html http://demo.mapserver.org/ogr-demos/nd_demo/demo_init.html The following site uses OGR, as well as MapInfos Seamless Map Layers feature: http://demo.mapserver.org/ogr-demos/ro_demo/demo_init.html The following site uses OGR to display TIGER 2000 les: http://demo.mapserver.org/ogr-demos/tig_demo/demo_init.html FAQ / Common Problems Q What Does OGR Stand For? A Basically, OGR does not stand for anything. For a detailed explanation of how OGR was named, see GDALs FAQ at http://trac.osgeo.org/gdal/wiki/FAQ.
Q When using STYLEITEM AUTO, what should I have in my .sym symbols le?
324
A When you use STYLEITEM AUTO, MapServer tries to match symbol names returned by OGR to names in your symbol le. For a quick solution, try using the following symbol le: http://demo.mapserver.org/ogr-demos/yk_demo/etc/symbols_mapinfo.txt The name of the symbols returned by OGR to MapServer depends on the le format. In the case of MapInfo les, it will be: For old-style symbols (default MapInfo 3.0 symbols numbered 32 to 67) the symbol name will be mapinfo-sym-## where ## is the symbol number, e.g. mapinfo-sym-32. For Font Symbols, the symbol name is also mapinfo-sym-## where ## is the symbol number in the font. In this case, the name of the font itself is ignored by MapServer. MapInfo also supports custom symbols (bitmap symbols)... Im not sure what you would get from OGR for this, but Im pretty sure that MapServer doesnt do anything useful with them. The OGRINFO utility can be used to nd out exactly which symbol names OGR will return to MapServer. Look at the Style string in the ogrinfo output for each shape that is read.
7.1.17 Oracle Spatial

Author Bart van den Eijnden Last Updated 2005/12/12 Table of Contents Oracle Spatial What MapServer 5.2 with Oracle Spatial Binaries Installation Two options for using Oracle Spatial with MapServer Maple syntax for native Oracle Spatial support Using subselects in the DATA statement Additional keywords - [FUNCTION] Additional keywords - [VERSION] More information Example of a LAYER Maple syntax for OGR Oracle Spatial support Oracle Spatial is a spatial cartridge for the Oracle database. Remember that all Oracle databases come with Locator, which has less features than Oracle Spatial. The differences between Locator and Spatial can be found in the Oracle Spatial FAQ. You can also see the original OracleSpatial wiki page that this document was based on. What MapServer 5.2 with Oracle Spatial mode=map query modes: query, nquery, itemnquery MapScript query functions such as querybyattributes OGC:WMS: GetCapabilities, GetMap, GetFeatureInfo, DescribeLayer OGC:WFS, GetCapabilities, DescribeFeatureType, GetFeature 7.1. Vector Data 325
Binaries MapServer Windows plugins with Oracle spatial support can be downloaded from MS4W. But you need Oracle client software in the server on which you are running MapServer. Oracle client software can be obtained for development purposes from the Oracle website, but you need to register, which by the way is free. The most recent version is Oracle Database 10g Release 1 Client. The ORACLE TECHNOLOGY NETWORK DEVELOPMENT LICENSE AGREEMENT applies to this software. The instant client will be satisfactory, and you can download the instant client. Make sure though your MapServer is compiled against the same version as your Oracle client, for compiling you need a full client install, not just the instant client. Installation See Oracle Installation for more conguration and installation information for MapServers native Oracle support Note: If you receive error messages like Error: .. Its likely related to MapServer being unable access or locate the ORACLE_HOME. Two options for using Oracle Spatial with MapServer Oracle Spatial layers in MapServer can be used through 2 interfaces: The native built-in support through maporaclespatial.c OGR, but watch out: OGR is not compiled with Oracle Spatial support so it wont work without compiling in OCI (Oracle client) yourself. This requires both recompiling GDAL/OGR as well as recompiling MapServer itself against the new GDAL/OGR !!!! Maple syntax for native Oracle Spatial support The DATA statement for a LAYER of CONNECTIONTYPE oraclespatial can now have 4 options. This change is backwards compatible, i.e. the old ways of specifying DATA still work. The new options are an extension to the old DATA statements, as they needed to include identication of the primary key to be used for the query modes (UNIQUE). The following options are valid DATA statements:
"[geom_column] FROM [table]| [( SELECT [...] FROM [table]|[Spatial Operator] [WHERE condition] )] [USING [UNIQUE column] | [SRID #srid] | [FUNCTION] | [VERSION #version] ]"
Example 1
The most simple DATA statement, in this case you only need to dene one geometry column and one table. This option assumes you do not have an SRID dened.
326
LAYER ... CONNECTIONTYPE oraclespatial DATA "MYGEOMETRY FROM MYTABLE" ... END
Example 2
Its composed of the rst option plus the USING UNIQUE parameter. These new features are necessary when you want to use any query function. When it is used you must pass a numeric column type. This option assumes you do not have an SRID dened.
LAYER ... CONNECTIONTYPE oraclespatial DATA "MYGEOMETRY FROM MYTABLE USING UNIQUE MYTABLE_ID" ... END
Example 3
This option is an extension to the rst option. In this mode you must dene the USING SRID parameter when the SRID value in your data is different from NULL.
LAYER ... CONNECTIONTYPE oraclespatial DATA "MYGEOMETRY FROM MYTABLE USING SRID 90112" ... END
Example 4
This option is a combination of examples 2 and 3.
LAYER ... CONNECTIONTYPE oraclespatial DATA "MYGEOMETRY FROM MYTABLE USING UNIQUE MYTABLE_ID SRID 90112" ... END
Using subselects in the DATA statement It is possible to dene the source of the date as a subselect and not only as a table. As source of data, used in FROM token, you can dene any SQL, table, function, or operator that returns a SDO_GEOMETRY. For example:
DATA "[geom_column] FROM (SELECT [columns] FROM [table]|[Spatial function])"
If the LAYER denition contains a CLASSITEM, LABELITEM or FILTER, it is necessary that the elds used are returned by the query. When you dene CLASSITEM you can use an expression without any problems.
7.1. Vector Data
327
Additional keywords - [FUNCTION] You can add three keywords to the DATA statement for [FUNCTION] option that inuence the query which will be executed in Oracle:
USING FILTER
"[geom_column] FROM [table]|([Subselect]) USING FILTER"
Using this keyword triggers MapServer to use the Oracle Spatial SDO_FILTER operator. This operator executes only the Oracle Spatial primary lter over your query data. In the Oracle User guide they explain: The primary lter compares geometric approximations, it returns a superset of exact result. The primary lter therefore should be as efcient (that is, selective yet fast) as possible. This operator uses the spatial index, so you need to dene your spatial index correctly to retrieve an exact result. If the result of the query is not exact you can try the next option.
USING RELATE
"[geom_column] FROM [table]|([Subselect]) USING RELATE"
Using this keyword triggers MapServer to use the Oracle Spatial SDO_RELATE operator. This operator applies the primary and secondary Oracle Spatial lters. Its performance can be slightly slow but the result is extremely correct. You can use this mode when you want a perfect result or when you cant readjust the spatial index.
USING GEOMRELATE
"[geom_column] FROM [table]|([Subselect]) USING GEOMRELATE"
Using this keyword triggers MapServer to use the geometry function SDO_GEOM.RELATE, a function that searches the relations between geometries. SDO_GEOM.RELATE does not use the spatial index and your performance is more slow than operators but its very accurate. You can use this mode when you cant use the spatial index or when it doesnt exist.
USING NONE
"[geom_column] FROM [table]|([Subselect]) USING NONE"
Using this keyword triggers MapServer to dont use any geometry function or spatial operator. So, the internal SQL dont retrict, bases in the extent, the data from source. All the data from source will be returned for MapServer. The NONE token is very useful when the source of the data dont contains any spatial index. Its usually occur when the source is a function like SDO_BUFFER, SDO_XOR, SDO_INTERSECTION...... So this mode is recomended when you cant use the spatial index or when it doesnt exist. Additional keywords - [VERSION] You can dene what version of database you are using to improve the internal sql. This is very useful when using geodetic SRIDs and MapServer functions that retrieve the extent from data.
328
USING VERSION 8i
"[geom_column] FROM [table]|([Subselect]) USING VERSION 8i"
This indicates MapServer to use a internal SQL that its compatible with Oracle 8i version.
USING VERSION 9i
"[geom_column] FROM [table]|([Subselect]) USING VERSION 9i"
The second indicates MapServer to use 9i version, is recommended to use this parameter if you are using 9i version because the internal SQL will use specic spatial functions that is need to retrieve data correctly from 9i Oracle Spatial versions.
USING VERSION 10g

"[geom_column] FROM [table]|([Subselect]) USING VERSION 10g"
This indicates MapServer to use a internal SQL that its compatible with Oracle 10g version. More information You can dene any PROJECTION to your LAYER without problem, can be used for data with or without an SRID in Oracle. The native support for Oracle Spatial supports the defaults denition for SDO_GEOMETRY in database, the Oracle Spatial SDO package. Information about the primary and secondary Oracle Spatial lters can be found in the Oracle Spatial User Guide (the Query Model section). Information about the SDO_FILTER and SDO_RELATE operators can be found in the Spatial Operators section, and information about the SDO_GEOM.RELATE function can be found in the Geometry Function section of the Oracle Spatial User Guide. Example of a LAYER
LAYER NAME kwadranten TYPE POLYGON CONNECTIONTYPE oraclespatial CONNECTION "user/pwd" DATA "GEOMETRIE FROM KWADRANTEN USING SRID 90112" CLASS STYLE OUTLINECOLOR 0 0 0 COLOR 0 128 128 END END END
You can specify the SID for your database, the SID alias needs to be supplied in the tnsnames.ora le of the Oracle client, e.g. Example for tnsnames.ora:
7.1. Vector Data
329
MYDB = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = server_ip)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = DB1) ) )
So after this you can dene you layer connection as:

CONNECTION "user/pwd@MYDB"
Maple syntax for OGR Oracle Spatial support Syntax for your MAP le:
CONNECTION "OCI:user/pwd@service" CONNECTIONTYPE OGR DATA "Tablename"
Note: Make sure you set the wms_extent METADATA for the LAYER, as otherwise the Getcapabilities request takes a lot of time.
7.1.18 PostGIS/PostgreSQL
Table of Contents PostGIS/PostgreSQL PostGIS/PostgreSQL Data Access /Connection Method OGRINFO Examples Maple Example Support for SQL/MM Curves * Example#1: CircularString in MapServer * Example#2: CompoundCurve in MapServer * Example#3: CurvePolygon in MapServer * Example#4: MultiCurve in MapServer * Example#5: MultiSurface in MapServer * Using MapServer < 6.0
PostGIS/PostgreSQL PostGIS spatially enables the Open Source PostgreSQL database. The PostGIS wiki page may include additional information. Data Access /Connection Method PostGIS is supported directly by MapServer and must be compiled into MapServer to work.
330
The PostgreSQL client libraries (libpq.so or libpq.dll) must be present in the systems path environment for functionality to be present. The CONNECTIONTYPE parameter must be set to POSTGIS. The CONNECTION parameter is used to specify the parameters to connect to the database. CONNECTION parameters can be in any order. Most are optional. dbname is required. user is required. host defaults to localhost, port defaults to 5432 (the standard port for PostgreSQL). The DATA parameter is used to specify the data used to draw the map. The form of DATA is [geometry_column] from [table_name|sql_subquery] using unique [unique_key] using srid=[spatial_reference_id]. The using unique and using srid= clauses are optional when drawing features, but using them improves performance. If you want to make MapServer query calls to a PostGIS layer, your DATA parameter must include using unique. Omitting it will cause the query to fail. Here is a simple generic example:
CONNECTIONTYPE POSTGIS CONNECTION "host=yourhostname dbname=yourdatabasename user=yourdbusername password=yourdbpassword port=yourpgport" DATA "geometrycolumn from yourtablename"
This example shows specifying the unique key and srid in the DATA line:
CONNECTIONTYPE POSTGIS CONNECTION "dbname=yourdatabasename user=yourdbusername" DATA "the_geom from the_database using unique gid using srid=4326"
This example shows using a SQL subquery to perform a join inside the database and map the result in MapServer. Note the as subquery string in the statement everything between from and using is sent to the database for evaluation:
CONNECTIONTYPE POSTGIS CONNECTION "dbname=yourdatabasename user=yourdbusername" DATA "the_geom from (select g.gid, g.the_geom, a.attr1, a.attr2 from geotable g join attrtable a on g.gid = a.aid) as subquery using unique gid using srid=4326"
This example shows using a geometry function and database sort to limit the number of features and vertices returned to MapServer:
CONNECTIONTYPE POSTGIS CONNECTION "dbname=yourdatabasename user=yourdbusername" DATA "the_geom from (select g.gid, ST_Simplify(g.the_geom, 10.0) as the_geom from geotable g order by ST_Area(g.the_geom) desc limit 10) as subquery using unique gid using srid=4326"
This example shows the use of the !BOX! substitution string to over-ride the default inclusion of the map bounding box in the SQL. By default the spatial box clause is appended to the SQL in the DATA clause, but you can use !BOX! to insert it anywhere you like in the statement. In general, you wont need to use !BOX!, because the PostgreSQL planner will generate the optimal plan from the generated SQL, but in some cases (complex sub-queries) a better plan can be generated by placing the !BOX! closer to the middle of the query:
CONNECTIONTYPE POSTGIS CONNECTION "dbname=yourdatabasename user=yourdbusername" DATA "the_geom from (select g.gid, ST_Union(g.the_geom, 10.0) as the_geom from geotable g where ST_Intersects(g.geom,!BOX!)) as subquery using unique gid using srid=4326"
7.1. Vector Data
331
OGRINFO Examples OGRINFO can be used to read out metadata about PostGIS tables directly from the database. First you should make sure that your GDAL/OGR build contains the PostgreSQL driver, by using the formats command:
>ogrinfo --formats Loaded OGR Format Drivers: ... -> "PGeo" (readonly) -> "PostgreSQL" (read/write) -> "MySQL" (read/write) ...
If you dont have the driver, you might want to try the FWTools or MS4W packages, which include the driver. Once you have the driver you are ready to try an ogrinfo command on your database to get a list of spatial tables:
>ogrinfo PG:"host=127.0.0.1 user=postgres password=postgres dbname=canada port=5432" using driver PostgreSQL successful. 1: province (Multi Polygon)
>ogrinfo PG:"host=127.0.0.1 user=postgres password=postgres dbname=canada port=5432" province -summary INFO: Open of PG:host=127.0.0.1 user=postgres password=postgres dbname=canada using driver PostgreSQL successful. Layer name: province Geometry: Multi Polygon Feature Count: 1068 Extent: (-2340603.750000, -719746.062500) - (3009430.500000, 3836605.250000) Layer SRS WKT: (unknown) FID Column = gid Geometry Column = the_geom area: Real (0.0) island: String (30.0) island_e: String (30.0) island_f: String (30.0) name: String (30.0) ...
Maple Example
LAYER NAME "province" STATUS ON TYPE POLYGON CONNECTIONTYPE POSTGIS CONNECTION "host=127.0.0.1 port=5432 dbname=canada user=postgres password=postgres" DATA "the_geom from province" CLASS ... END END
332
For more info about PostGIS and MapServer see the PostGIS docs: http://postgis.org/documentation/ Support for SQL/MM Curves PostGIS is able to store circular interpolated curves, as part of the SQL Multimedia Applications Spatial specication (read about the SQL/MM specication). For more information about PostGIS support, see the SQL-MM Part 3 section in the PostGIS documentation, such as here. As of MapServer 6.0, the PostGIS features CircularString, CompoundCurve, CurvePolygon, MultiCurve, and MultiSurface can be drawn through MapServer directly.
Example#1: CircularString in MapServer

The following is the Well Known Text of the feature loading into PostGIS:
INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0), -1), 2);
An example MapServer layer might look like:

LAYER NAME "curves_poly" STATUS DEFAULT TYPE POLYGON CONNECTIONTYPE postgis CONNECTION "user=postgres password=postgres dbname=curves host=localhost port=5432" DATA "g from test using SRID=-1 using unique id" CLASS STYLE COLOR 128 128 128 ANTIALIAS true END END END
And testing with shp2img should produce a map image of:
Example#2: CompoundCurve in MapServer

INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText(COMPOUNDCURVE( CIRCULARSTRING(0 0, 1 1, 1 0),(1 0, 0 1)), -1), 3);
7.1. Vector Data
333

Example#3: CurvePolygon in MapServer

INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText(CURVEPOLYGON( CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0),(1 1, 3 3, 3 1, 1 1)), -1), 4);

334
Example#4: MultiCurve in MapServer

INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText(MULTICURVE((0 0, 5 5),CIRCULARSTRING(4 0, 4 4, 8 4)), -1), 6);

7.1. Vector Data
335
Example#5: MultiSurface in MapServer

INSERT INTO test ( g, id ) VALUES ( ST_GeomFromText(MULTISURFACE( CURVEPOLYGON(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0),(1 1, 3 3, 3 1, 1 1)),((10 10, 14 12, 11 10, 10 10),(11 11, 11.5 11, 11 11.5, 11 11))), -1), 7);

336
Using MapServer < 6.0

If you cannot upgrade to MapServer 6.0, then you can use the PostGIS function ST_CurveToLine() in your MapServer LAYER to draw the curves (note that this is much slower however):
LAYER NAME "curves_poly" STATUS DEFAULT TYPE POLYGON CONNECTIONTYPE postgis CONNECTION "user=postgres password=postgres dbname=curves host=localhost port=5432" DATA "wkb_geometry from (select c.id, ST_CurveToLine(c.g) as wkb_geometry from c) as subquery using unique id using SRID=-1" CLASS STYLE COLOR 128 128 128 ANTIALIAS true END END END
7.1. Vector Data
337
7.1.19 SDTS
This is a United States Geological Survey (USGS) format. SDTS has a raster and a vector format. The raster format is not supported in MapServer. Only the vector formats are supported, including VTP and DLG les. File listing SDTS les are often organized into state-sized pieces. For example, all of the state of Maryland (MD), U.S.A. Files are also available for multiple types of features including hydrography, transportation and administrative boundaries. This example uses transportation data, which consists of 35 separate les, each with the sufx DDF:
MDTRAHDR.DDF MDTRDQCG.DDF MDTRNA03.DDF MDTRAMTF.DDF MDTRDQHL.DDF MDTRNE03.DDF MDTRARDF.DDF MDTRDQLC.DDF MDTRNO01.DDF MDTRARDM.DDF MDTRDQPA.DDF MDTRNO02.DDF MDTRARRF.DDF MDTRFF01.DDF MDTRNO03.DDF MDTRBFPS.DDF MDTRIDEN.DDF MDTRPC01.DDF MDTRBMTA.DDF MDTRIREF.DDF MDTRPC02.DDF MDTRCATD.DDF MDTRLE01.DDF MDTRPC03.DDF MDTRCATS.DDF MDTRLE02.DDF MDTRSPDM.DDF MDTRCATX.DDF MDTRLE03.DDF MDTRSTAT.DDF MDTRDDSH.DDF MDTRNA01.DDF MDTRXREF.DDF MDTRDQAA.DDF MDTRNA02.DDF
Data Access / Connection Method SDTS access is available in MapServer through OGR. The CONNECTIONTYPE OGR parameter must be used. The path (which can be relative) to the catalog le (????CATD.DDF) is required, including le extension. There are multiple layers in the SDTS catalog, some of which are only attributes and have no geometries. The layer name is specied with the DATA parameter OGRINFO Examples Using ogrinfo on a catalog le (note that the rst 7 layers do not have geometries):
> ogrinfo /data/sdts/MD/MDTRCATD.DDF Had to open data source read-only. INFO: Open of MDTRCATD.DDF using driver SDTS successful. 1: ARDF (None) 2: ARRF (None) 3: AMTF (None) 4: ARDM (None) 5: BFPS (None) 6: BMTA (None) 7: AHDR (None) 8: NE03 (Point) 9: NA01 (Point) 10: NA02 (Point)
338
11: 12: 13: 14: 15: 16: 17: 18: 19: 20:
NA03 NO01 NO02 NO03 LE01 LE02 LE03 PC01 PC02 PC03
(Point) (Point) (Point) (Point) (Line String) (Line String) (Line String) (Polygon) (Polygon) (Polygon)
Using ogrinfo to examine the structure of the le/layer:

> ogrinfo /data/sdts/MD/MDTRCATD.DDF LE01 -summary Had to open data source read-only. INFO: Open of MDTRCATD.DDF using driver SDTS successful. Layer name: LE01 Geometry: Line String Feature Count: 780 Extent: (-80.000289, 36.999774) - (-74.999711, 40.000225) Layer SRS WKT: GEOGCS["NAD27", DATUM["North_American_Datum_1927", SPHEROID["Clarke 1866",6378206.4,294.978698213901]], PRIMEM["Greenwich",0], UNIT["degree",0.0174532925199433]] RCID: Integer (0.0) SNID: Integer (0.0) ENID: Integer (0.0) ENTITY_LABEL: String (7.0) ARBITRARY_EXT: String (1.0) RELATION_TO_GROUND: String (1.0) VERTICAL_RELATION: String (1.0) OPERATIONAL_STATUS: String (1.0) ACCESS_RESTRICTION: String (1.0) OLD_RAILROAD_GRADE: String (1.0) WITH_RAILROAD: String (1.0) COVERED: String (1.0) HISTORICAL: String (1.0) LIMITED_ACCESS: String (1.0) PHOTOREVISED: String (1.0) LANES: Integer (2.0) ROAD_WIDTH: Integer (3.0) BEST_ESTIMATE: String (1.0) ROUTE_NUMBER: String (7.0) ROUTE_TYPE: String (9.0)
Map File Example:

LAYER NAME sdts_maryland TYPE LINE CONNECTIONTYPE OGR CONNECTION "data/sdts/MD/MDTRCATD.DDF" DATA "LE01" STATUS DEFAULT CLASS
7.1. Vector Data
339
STYLE COLOR 0 0 0 END END END
7.1.20 S57
Also known as S57. The IHO S-57 format is a vector interchange format used for maritime charts. It was developed by the International Hydrographic Organisation (IHO). For more information about the IHO see: http://www.iho.shom.fr/ File listing Individual S57 data les have an extension of *.000. For example:
US1BS02M.000
Data Access / Connection Method S57 access in MapServer occurs through OGR, CONNECTIONTYPE OGR must be used. Specify a full path or a relative path from the SHAPEPATH to the .000 le for the CONNECTION Use the DATA parameter to specify the s57 layer name
Special Notes
The underlying OGR code requires two les from your GDAL/OGR installation when reading S57 data in MapServer : s57objectclasses.csv and s57attributes.csv. These les can be found in the /GDAL/data/ folder (unix: /usr/local/share/gdal windows: /ms4w/gdaldata). If you receive an error in MapServer such as:
msDrawMap(): Image handling error. Failed to draw layer named s57. msOGRFileOpen(): OGR error. xxx failed for OGR connection
you may have to point MapServer to these les using the CONFIG parameter in the main section of your map le:
CONFIG GDAL_DATA "C:\ms4w\gdaldata"
OGRINFO Examples Using ogrinfo on an S57 le to get the layer name:

> ogrinfo us1bs02m.000 ERROR 4: S57 Driver doesnt support update. Had to open data source read-only. INFO: Open of us1bs02m.000 using driver IHO S-57 (ENC) successful. 1: ADMARE (Polygon) 2: CBLSUB (Line String) 3: CTNARE 4: COALNE (Line String) 5: DEPARE 6: DEPCNT (Line String)
340
7: LNDARE 8: LNDELV 9: LNDRGN 10: LNDMRK 11: LIGHTS 12: OBSTRN 13: RDOSTA 14: SEAARE 15: SBDARE 16: SLCONS 17: SOUNDG 18: UWTROC 19: WATTUR 20: WRECKS 21: M_COVR 22: M_NPUB 23: M_NSYS 24: M_QUAL 25: C_ASSO
(Point) (Point)
(Multi Point) (Point)
(Polygon) (Polygon) (Polygon) (Polygon) (None)
Using ogrinfo to examine the structure of an S57 layer:

> ogrinfo us1bs02m.000 DEPARE -summary ERROR 4: S57 Driver doesnt support update. Had to open data source read-only. INFO: Open of us1bs02m.000 using driver IHO S-57 (ENC) successful. Layer name: DEPARE Geometry: Unknown (any) Feature Count: 297 Extent: (165.666667, 48.500000) - (180.000000, 60.750000) Layer SRS WKT: GEOGCS["WGS 84", DATUM["WGS_1984", SPHEROID["WGS 84",6378137,298.257223563]], PRIMEM["Greenwich",0], UNIT["degree",0.0174532925199433]] GRUP: Integer (3.0) OBJL: Integer (5.0) RVER: Integer (3.0) AGEN: Integer (2.0) FIDN: Integer (10.0) FIDS: Integer (5.0) LNAM: String (16.0) LNAM_REFS: StringList (16.0) DRVAL1: Real (0.0) DRVAL2: Real (0.0) QUASOU: String (0.0) SOUACC: Real (0.0) VERDAT: Integer (0.0) INFORM: String (0.0) NINFOM: String (0.0) NTXTDS: String (0.0) SCAMAX: Integer (0.0) SCAMIN: Integer (0.0) TXTDSC: String (0.0) RECDAT: String (0.0) RECIND: String (0.0)
7.1. Vector Data
341
...
Map File Example:

LAYER NAME s57 TYPE POLYGON STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "./s57/us1bs02m.000" DATA "DEPARE" CLASS STYLE COLOR 247 237 219 OUTLINECOLOR 120 120 120 END END END # Layer
7.1.21 SpatiaLite
SpatiaLite spatially enables the le-based SQLite database. For more information see the SpatiaLite description page. File listing Similar to other database formats, the .sqlite le consists of several tables. The geometry is held in a BLOB table column. Data Access / Connection Method Spatialite access is available through OGR. See the OGR driver page for specic driver information. The driver is available in GDAL/OGR version 1.7.0 or later. OGR uses the names of spatial tables within the SpatiaLite database (tables with a geometry column that are registered in the geometry_columns table) as layers. The CONNECTION parameter must include the sqlite extension, and the DATA parameter should be the name of the spatial table (or OGR layer).
CONNECTIONTYPE OGR CONNECTION "spatialite_db.sqlite" DATA "layername"
OGRINFO Examples First you should make sure that your GDAL/OGR build contains the spatialite SQLite driver, by using the formats command:
>ogrinfo --formats Loaded OGR Format Drivers: ... -> "GMT" (read/write) -> "SQLite" (read/write) -> "ODBC" (read/write) ...
342
If you dont have the driver, you might want to try the MS4W or OSGeo4W packages, which include the driver. Once you have conrmed that you have the SQLite driver you are ready to try an ogrinfo command on your database to get a list of spatial tables:
>ogrinfo counties.sqlite INFO: Open of counties.sqlite using driver SQLite successful. 1: mn_counties (Polygon)
>ogrinfo counties.sqlite county -summary INFO: Open of counties.sqlite using driver SQLite successful. Layer name: mn_counties Geometry: Polygon Feature Count: 87 Extent: (189783.560000, 4816309.330000) - (761653.524114, 5472346.500000) Layer SRS WKT: PROJCS["NAD83 / UTM zone 15N", GEOGCS["NAD83", DATUM["North_American_Datum_1983", SPHEROID["GRS 1980",6378137,298.257222101, AUTHORITY["EPSG","7019"]], TOWGS84[0,0,0,0,0,0,0], AUTHORITY["EPSG","6269"]], PRIMEM["Greenwich",0, AUTHORITY["EPSG","8901"]], UNIT["degree",0.0174532925199433, AUTHORITY["EPSG","9122"]], AUTHORITY["EPSG","4269"]], UNIT["metre",1, AUTHORITY["EPSG","9001"]], PROJECTION["Transverse_Mercator"], PARAMETER["latitude_of_origin",0], PARAMETER["central_meridian",-93], PARAMETER["scale_factor",0.9996], PARAMETER["false_easting",500000], PARAMETER["false_northing",0], AUTHORITY["EPSG","26915"], AXIS["Easting",EAST], AXIS["Northing",NORTH]] FID Column = PK_UID Geometry Column = Geometry AREA: Real (0.0) PERIMETER: Real (0.0) COUNTY_ID: Integer (0.0) FIPS: String (0.0) ...
7.1. Vector Data
343
Maple Example
Standard connection
LAYER NAME my_counties_layer TYPE POLYGON CONNECTIONTYPE ogr CONNECTION "counties.sqlite" DATA "mn_counties" STATUS ON CLASS NAME "mncounties" STYLE COLOR 255 255 120 END END END
Connection utilizing SQL syntax

LAYER NAME my_counties_layer TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "counties.sqlite" DATA "select geometry from mn_counties" STATUS ON CLASS NAME "mncounties" STYLE COLOR 255 255 120 END END END
Connection utilizing joined table for additional attributes

LAYER NAME my_counties_layer TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "counties.sqlite" DATA "SELECT mn.geometry, c.fips FROM mn_counties mn inner join county_data c on mn.county_id = c.county_id STATUS ON CLASS NAME "mncounties" STYLE COLOR 255 255 120 END END END
344
Standard Connection with a lter

LAYER NAME my_counties_layer TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "counties.sqlite" DATA "mn_counties" FILTER ([fips] = 27031) STATUS ON CLASS NAME "mncounties" STYLE COLOR 255 255 120 END END END
Filter utilizing SQL syntax

LAYER NAME my_counties_layer TYPE POLYGON CONNECTIONTYPE OGR CONNECTION "counties.sqlite" DATA "select geometry from mn_counties where fips = 27031" STATUS ON CLASS NAME "mncounties" STYLE COLOR 255 255 120 END END END
7.1.22 USGS TIGER

TIGER/Line les are created by the US Census Bureau and cover the entire US. They are often referred simply as TIGER les. For more information see: http://www.census.gov/geo/www/tiger/. File listing TIGER/Line les are text les and directory-based data sources. For example, one county folder TGR06059 contains several associated les:
TGR06059.RT1 TGR06059.RT6 TGR06059.RTC TGR06059.RTR TGR06059.RT2 TGR06059.RT7 TGR06059.RTH TGR06059.RTS TGR06059.RT4 TGR06059.RT8 TGR06059.RTI TGR06059.RTT TGR06059.RT5 TGR06059.RTA TGR06059.RTP TGR06059.RTZ
Data Access / Connection Method TIGER/Line access occurs through an OGR CONNECTION 7.1. Vector Data 345
The full path to the directory containing the associated les is required in the CONNECTION string. The feature type is specied in the DATA parameter
OGRINFO Examples
Using ogrinfo on a TIGER directory to retrieve feature types:
> ogrinfo TGR06059 (NOTE that this is a directory) ERROR 4: Tiger Driver doesnt support update. Had to open data source read-only. INFO: Open of TGR06059 using driver TIGER successful. 1: CompleteChain (Line String) 2: AltName (None) 3: FeatureIds (None) 4: ZipCodes (None) 5: Landmarks (Point) 6: AreaLandmarks (None) 7: Polygon (None) 8: PolygonCorrections (None) 9: EntityNames (Point) 10: PolygonEconomic (None) 11: IDHistory (None) 12: PolyChainLink (None) 13: PIP (Point) 14: TLIDRange (None) 15: ZeroCellID (None) 16: OverUnder (None) 17: ZipPlus4 (None)
Using ogrinfo to examine the structure of the TIGER feature type CompleteChain:
> ogrinfo TGR06059 CompleteChain -summary ERROR 4: Tiger Driver doesnt support update. Had to open data source read-only. INFO: Open of TGR06059 using driver TIGER successful. Layer name: CompleteChain Geometry: Line String Feature Count: 123700 Extent: (-118.125898, 33.333992) - (-117.412987, 33.947512) Layer SRS WKT: GEOGCS["NAD83", DATUM["North_American_Datum_1983", SPHEROID["GRS 1980",6378137,298.257222101]], PRIMEM["Greenwich",0], UNIT["degree",0.0174532925199433]] MODULE: String (8.0) TLID: Integer (10.0) SIDE1: Integer (1.0) SOURCE: String (1.0) FEDIRP: String (2.0) FENAME: String (30.0) FETYPE: String (4.0) FEDIRS: String (2.0) CFCC: String (3.0)
346
FRADDL: String (11.0) TOADDL: String (11.0) FRADDR: String (11.0) TOADDR: String (11.0) FRIADDL: String (1.0) TOIADDL: String (1.0) FRIADDR: String (1.0) TOIADDR: String (1.0) ZIPL: Integer (5.0)
Map File Example:

LAYER NAME Complete_Chain TYPE LINE STATUS DEFAULT CONNECTIONTYPE OGR CONNECTION "/path/to/data/tiger/TGR06059" DATA "CompleteChain" CLASS STYLE COLOR 153 102 0 END END END # Layer
7.1.23 Virtual Spatial Data

Table of Contents Virtual Spatial Data Types of Databases Types of Flat Files Steps for Display This is an OGR extension to MapServer. It allows you to connect to databases that do not explicitly hold spatial data, as well as at text les. Your data must have an X and a Y column, and the data may be accessed through an ODBC connection or a direct pointer to a text le. The original VirtualSpatialData wiki page may contain additional information. Types of Databases The VirtualSpatialData OGR extension has been tested with the following databases and should, in theory, support all ODBC data sources. Oracle MySQL SQL Server Access PostgreSQL
7.1. Vector Data
347
Types of Flat Files Comma, tab or custom delimited text/at les work with VirtualSpatialData. Steps for Display
1. Create the Datasource Name (DSN)

Specic notes about creating a DSN on Windows and Linux can be found by searching the MapServer reference documents site On some Windows systems you must create a SYSTEM DSN.
2. Test your Connection

Test your connection with ogrinfo. The syntax for this command is:
> ogrinfo ODBC:user/pass@DSN table
Windows users may not be required to specify a user/password, so the syntax would be:
> ogrinfo ODBC:@DSN table
Example: Accessing a comma separated text le through ODBC using ogrinfo The following is a snippet of the at text le coal_dep.txt containing lat/long points:
unknown,na,id,id2,mark,coalkey,coalkey2,long,lat 0.000,0.000,1,1,7,87,87,76.90238,51.07161 0.000,0.000,2,2,7,110,110,78.53851,50.69403 0.000,0.000,3,3,3,112,112,83.22586,71.24420 0.000,0.000,4,4,6,114,114,80.79896,73.41175
If the DSN name is Data_txt, the ogrinfo command to see a list of applicable les in the directory is:
> ogrinfo ODBC:jeff/test@Data_txt INFO: Open of ODBC:jeff/test@Data_txt using driver ODBC successful. 1: coal_dep.csv 2: coal_dep.txt 3: coal_dep_nf.txt 4: coal_dep_trim.txt 5: Copy of coal_dep.txt 6: deposit.csv 7: maruia.asc 8: oahuGISbathy.csv 9: oahuGISbathy.txt 10: on_pts.txt 11: on_pts_utm.txt 12: test.txt 13: utm_test.txt
Username and password may be optional, so the following may also be valid:
> ogrinfo ODBC:@Data_txt
Therefore, the command to see more information about one of the specic layers is:
348
> ogrinfo ODBC:@Data_txt coal_dep.txt INFO: Open of ODBC:@Data_txt using driver ODBC successful. Layer name: coal_dep.txt Geometry: Unknown (any) Feature Count: 266 Layer SRS WKT: (unknown) UNKNOWN: String (255.0) NA: String (255.0) ID: String (255.0) ID2: String (255.0) MARK: String (255.0) COALKEY: String (255.0) COALKEY2: String (255.0) LONG: String (255.0) LAT: String (255.0) OGRFeature(coal_dep.txt):0 UNKNOWN (String) = 0.000 ....
3. Create a Virtual Data File

This is a le with an ovf extension and looks like the following:
<OGRVRTDataSource> <OGRVRTLayer name="mylayer"> <SrcDataSource>ODBC:user/pass@DSN</SrcDataSource> <SrcLayer>tablename</SrcLayer> <GeometryType>wkbPoint</GeometryType> <LayerSRS>WGS84</LayerSRS> <GeometryField encoding="PointFromColumns" x="x" y="y"/> </OGRVRTLayer> </OGRVRTDataSource>
More information on ovf les can be found at: http://www.gdal.org/ogr/drv_vrt.html Example ovf le for coal_dep.txt:
<OGRVRTDataSource> <OGRVRTLayer name="coal-test"> <SrcDataSource>ODBC:Data_txt</SrcDataSource> <SrcLayer>coal_dep.txt</SrcLayer> <GeometryField encoding="PointFromColumns" x="Long" y="Lat"/> <GeometryType>wkbPoint</GeometryType> </OGRVRTLayer> </OGRVRTDataSource>
4. Test Virtual Data File with ogrinfo

Use ogrinfo to test your new ovf le, such as:
> ogrinfo coal.ovf coal-test ERROR 4: Update access not supported for VRT datasources. Had to open data source read-only.
7.1. Vector Data
349
INFO: Open of myfile.ovf using driver VRT successful. Layer name: coal_dep.txt Geometry: Unknown (any) Feature Count: 266 Layer SRS WKT: (unknown) UNKNOWN: String (255.0) NA: String (255.0) ID: String (255.0) ID2: String (255.0) MARK: String (255.0) ...
5. Maple Layer
Using an ovf le your layer may look like:
LAYER CONNECTION "coal.ovf" CONNECTIONTYPE OGR DATA "coal-test" METADATA "wms_srs" "4326" "wms_title" "coal-test" END NAME "coal-test" SIZEUNITS PIXELS STATUS ON TOLERANCE 0 TOLERANCEUNITS PIXELS TYPE POINT UNITS METERS CLASS STYLE COLOR 255 0 0 MAXSIZE 100 MINSIZE 1 SIZE 6 SYMBOL "star" END END END
Or you may specify the ovf contents inline such as:

LAYER CONNECTION "<OGRVRTDataSource> <OGRVRTLayer name=coal-test> <SrcDataSource>ODBC:@Data_txt</SrcDataSource> <SrcLayer>coal_dep.txt</SrcLayer> <GeometryField encoding=PointFromColumns x=Long y=Lat/> <GeometryType>wkbPoint</GeometryType> </OGRVRTLayer> </OGRVRTDataSource>" CONNECTIONTYPE OGR
350
DATA "coal-test" METADATA "wms_srs" "4326" "wms_title" "coal-test" END NAME "coal-test" SIZEUNITS PIXELS STATUS ON TOLERANCE 0 TOLERANCEUNITS PIXELS TYPE POINT UNITS METERS CLASS STYLE COLOR 255 0 0 MAXSIZE 100 MINSIZE 1 SIZE 6 SYMBOL "star" END END END
6. Test your Maple

The rst thing you should try is to use the shp2img utility:
shp2img -m mymapfile.map -o test.png
Once you successfully created a map image, then try your application. Note Windows users may come across a problem where shp2img works but their application throws an error similar to this:
Warning: [MapServer Error]: msOGRFileOpen(): Open failed for OGR connection coal.ovf. Unable to initialize ODBC connection to DSN for jeff/test@Data_txt, [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified in D:\ms4w\Apache\htdocs\quickmap.php on line 40
If that happens you should make sure you have created a System DSN.
7.1.24 WFS
WFS is an Open Geospatial Consortium (OGC) specication. For more information about the format itself, see: http://www.opengeospatial.org/standards/wfs WFS allows a client to retrieve geospatial data encoded in Geography Markup Language (GML) from multiple Web Feature Services. GML is built on the standard web language XML. WFS differs from the popular Web Map Service (WMS) specication in that WFS returns a subset of the data in valid GML format, not just a graphic image of data. Capabilities Requesting the capabilities using the GetCapabilities request to a WFS server returns an XML document showing what layers and projections are available, etc. Example of a WFS GetCapabilities URL:
7.1. Vector Data
351
http://demo.mapserver.org/cgi-bin/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities Example of the Resulting XML from GetCapabilties:

... <FeatureTypeList> <Operations> <Query/> </Operations> <FeatureType> <Name>continents</Name> <Title>World continents</Title> <SRS>EPSG:4326</SRS> <LatLongBoundingBox minx="-180" miny="-90" maxx="180" maxy="83.6274"/> </FeatureType> <FeatureType> <Name>cities</Name> <Title>World cities</Title> <SRS>EPSG:4326</SRS> <LatLongBoundingBox minx="-178.167" miny="-54.8" maxx="179.383" maxy="78.9333"/> </FeatureType> </FeatureTypeList> ...
Data Access / Connection Method WFS access is a core MapServer feature. MapServer currently supports WFS version 1.0.0 The CONNECTIONTYPE WFS parameter must be used. WFS layers can be requested through a layer in a map le, or you can request the GML directly through the browser with a GetFeature request. You can specify a specic layer with the TypeName request. In a map le the name/value pairs should be put into a METADATA object. You can limit the number of features returned in the GML by using the MaxFeatures option (e.g. &MAXFEATURES=100). Example of a WFS Request Directly Through the Browser: The following URL requests the GML for the layer continents. (see the GetCapabilities above for the possible layers available on this test server) . The URL is all one line, broken up here for readability (click here for a working link).
http://demo.mapserver.org/cgi-bin/wfs? SERVICE=WFS& VERSION=1.0.0& REQUEST=getfeature& TYPENAME=continents& MAXFEATURES=100
Map File Example

LAYER NAME "continents" TYPE POLYGON STATUS ON CONNECTION "http://demo.mapserver.org/cgi-bin/wfs?" CONNECTIONTYPE WFS METADATA "wfs_typename" "continents"
352
"wfs_version" "1.0.0" "wfs_connectiontimeout" "60" "wfs_maxfeatures" "10" END PROJECTION "init=epsg:4326" END CLASS NAME "Continents" STYLE COLOR 255 128 128 OUTLINECOLOR 96 96 96 END END END # Layer
7.2 Raster Data

Author Frank Warmerdam Contact warmerdam at pobox.com Revision $Revision: 12540 $ Date $Date: 2011-09-12 01:59:40 -0700 (Mon, 12 Sep 2011) $ Last Updated 2007/12/09 Table of Contents Raster Data Introduction How are rasters added to a Map le? Supported Formats Rasters and Tile Indexing Raster Warping 24bit RGB Rendering Special Processing Directives Raster Query Raster Display Performance Tips Preprocessing Rasters Georeference with World Files
7.2.1 Introduction
MapServer supports rendering a variety of raster le formats in maps. The following describes some of the supported formats, and what capabilities are supported with what formats. This document assumes that you are already familiar with setting up MapServer Maple, but does explain the raster specic aspects of maples.
7.2. Raster Data
353
7.2.2 How are rasters added to a Map le?

A simple raster layer declaration looks like this. The DATA le is interpreted relative to the SHAPEPATH, much like shapeles.
LAYER NAME "JacksonvilleNC_CIB" DATA "Jacksonville.tif" TYPE RASTER STATUS ON END
Though not shown rasters can have PROJECTION, METADATA, PROCESSING, MINSCALE, and MAXSCALE information. It cannot have labels, CONNECTION, CONNECTIONTYPE, or FEATURE information. Classifying Rasters Rasters can be classied in a manner similar to vectors, with a few exceptions. There is no need to specify a CLASSITEM. The raw pixel value itself ([pixel]) and, for paletted images, the red, green and blue color associated with that pixel value ([red], [green] and [blue]) are available for use in classications. When used in an evaluated expression the pixel, red, green and blue keywords must be in lower case.
LAYER NAME "JacksonvilleNC_CIB" DATA "Jacksonville.tif" TYPE RASTER STATUS ON CLASSITEM "[pixel]" # class using simple string comparison, equivelent to ([pixel] = 0) CLASS EXPRESSION "0" STYLE COLOR 0 0 0 END END # class using an EXPRESSION using only [pixel]. CLASS EXPRESSION ([pixel] >= 64 AND [pixel] < 128) STYLE COLOR 255 0 0 END END # class using the red/green/blue values from the palette CLASS NAME "near white" EXPRESSION ([red] > 200 AND [green] > 200 AND [blue] > 200) STYLE COLOR 0 255 0 END END # Class using a regular expression to capture only pixel values ending in 1 CLASS EXPRESSION /*1/ STYLE COLOR 0 0 255 END END END
354
As usual, CLASS denitions are evaluated in order from rst to last, and the rst to match is used. If a CLASS has a NAME attribute it may appear in a LEGEND. Only the COLOR, EXPRESSION and NAME parameters within a CLASS denition are utilized for raster classications. The other styling or control information is ignored. Raster classications always take place on only one raster band. It defaults to the rst band in the referenced le, but this can be altered with the BANDS PROCESSING directive. In particular this means that including even a single CLASS declaration in a raster layer will result in the raster layer being rendered using the one band classication rules instead of other rules that might have applied (such as 3 band RGB rendering).
Classifying Non-8bit Rasters

As of MapServer 4.4 support has been added for classifying non-8bit raster inputs. That is input rasters with values outside the range 0-255. Mostly this works transparently but there are a few caveats and options to provide explicit control. Classifying raster data in MapServer is accomplished by pre-classifying all expected input values and using that table of classication results to lookup each pixel as it is rendered. This is done because evaluating a pixel value against a series of CLASS denitions is relatively expensive to do for the hundreds of thousands of pixels in a typical rendered image. For simple 8bit inputs, only 256 input values need to be pre-classied. But for non-8bit inputs more values need to be classied. For 16bit integer inputs all 65536 possible input values are pre-classied. For oating point and other input data types, up to 65536 values are pre-classied based on the maximum expected range of input values. The PROCESSING directive can be used to override the range of values to be pre-classied, or the number of values (aka Buckets) in that range to classify. The SCALE=min,max PROCESSING directive controls the range. The SCALE_BUCKETS PROCESSING directive controls the number of buckets. In some cases rendering can be accelerated considerable by selecting a restricted range of input values and a reduced number of scaling values (buckets). The following example classies a oating raster, but only 4 values over the range -10 to 10 are classied. In particular, the values classied would be -7.5, -2.5, 2.5, and 7.5 (the middle of each quarter of the range). So those four value are classied, and one of the classication results is selected based on which value is closest to the pixel value being classied.
LAYER NAME grid1 TYPE raster STATUS default DATA data/float.tif PROCESSING "SCALE=-10,10" PROCESSING "SCALE_BUCKETS=4" CLASS NAME "red" EXPRESSION ([pixel] < -3) STYLE COLOR 255 0 0 END END CLASS NAME "green" EXPRESSION ([pixel] >= -3 and [pixel] < 3) STYLE COLOR 0 255 0 END END CLASS NAME "blue"
7.2. Raster Data
355
EXPRESSION ([pixel] >= 3) STYLE COLOR 0 0 255 END END END
7.2.3 Supported Formats

What raster formats are supported by MapServer is largely controlled by conguration time options. Some formats are considered to be built-in while the remainder are handled by the optional GDAL raster library. More information on GDAL can be found at http://www.gdal.org, including the supported formats list. Some of the advanced MapServer raster features, such as resampling, RGB color cube generation and automatic projection capture only work with raster formats used through GDAL. GDAL is normally built and installed separately from MapServer, and then enabled during the build of MapServer using the with-gdal conguration switch. To nd out what is built into a particular MapServer executable, use the -v ags to discover what build options are enabled. To nd out what GDAL formats are available, the gdalinfo formats command may be used. For example:
warmerda@gdal2200[124]% mapserv -v MapServer version 4.4.0-beta2 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=FASTCGI INPUT=EPPL7 INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE DEBUG=MSDEBUG warmerda@gdal2200[18]% gdalinfo --formats Supported Formats: GRASS (ro): GRASS Database Rasters (5.7+) GTiff (rw+): GeoTIFF NITF (rw+): National Imagery Transmission Format HFA (rw+): Erdas Imagine Images (.img) SAR_CEOS (ro): CEOS SAR Image ...
The following formats are potential builtins: TIFF/GeoTIFF If built with INPUT=TIFF MapServer will have builtin support for reading TIFF or GeoTIFF les. The builtin TIFF support has some limitations with regard to the organization of les that can be read (no tiled, 16bit, RGB, or odd color models). This driver supports world les, or simple builtin GeoTIFF coordinates for georeferencing. Full featured TIFF/GeoTIFF support is available through GDAL. Note that only GDAL supports tiled TIFF les and TIFF les with overviews. Tiled TIFF les with overviews pre-built are one of the highest performance ways of serving large raster images. GIF If GD is congured with GIF (OUTPUT=GIF) support, then MapServer will also be able to read GIF les for raster layers. The only way to georeference GIF les is with a world le. If GD is not congured with GIF support, it may still be available in GDAL. PNG If GD is congured with PNG (OUTPUT=PNG) support, then MapServer will also be able to read PNG les for raster layers. The only way to georeference PNG les is with a world le. If GD is not congured with PNG support, it may still be available in GDAL. JPEG If MapServer is built with JPEG (INPUT=JPEG) support then greyscale JPEG les may be rendered in raster layers. RGB les (the more common kind) will not be able to be displayed. Georeferencing is via world les. If MapServer is not built with native JPEG support, GDAL may still support the format. In this case RGB les are also supported (via the RGB color cube mechanism). Georeferencing is still via world le. 356 Chapter 7. Data Input
Erdas .LAN/.GIS If congured with INPUT=EPPL7 (the default) MapServer will support one band eight bit Erdas LAN/GIS les. The .trl le is read for a colormap, and if not found the layer is treated as greyscale. Georeferencing is read from the le. If MapServer is built with GDAL it is generally better to access all possible formats through GDAL rather than via the built-in drivers. The built-in drivers are less featureful, and not as well maintained.
7.2.4 Rasters and Tile Indexing

When handling very large raster layers it is often convenient, and higher performance to split the raster image into a number of smaller images. Each le is a tile of the larger raster mosaic available for display. The list of les forming a layer can be stored in a shapele with polygons representing the footprint of each le, and the name of the les. This is called a TILEINDEX and works similarly to the same feature in vector layers. The result can be represented in the Maple as one layer, but MapServer will rst scan the tile index, and ensure that only raster les overlapping the current display request will be opened. The following example shows a simple example. No DATA statement is required because MapServer will fetch the lename of the raster les from the Location attribute column in the hp2.dbf le for records associated with polygons in hp2.shp that intersect the current display region. The polygons in hp2.shp should be rectangles representing the footprint of the corresponding le. Note that the les do not have to be all the same size, the formats can vary and they can even overlap (later les will be drawn over earlier ones); however, they must all be in the same coordinate system (projection) as the layer.
LAYER NAME "hpool" STATUS ON TILEINDEX "hp2.shp" TILEITEM "Location" TYPE RASTER END
The lenames in the tileindex are searched for relative to the SHAPEPATH or map le, not relative to the tileindex. Great care should be taken when establishing the paths put into the tileindex to ensure they will evaluate properly in use. Often it is easiest to place the tileindex in the SHAPEPATH directory, and to create the tileindex with a path relative to the SHAPEPATH directory. When all else fails, absolute paths can be used in tileindex, but then they cannot be so easily moved from system to system. While there are many ways to produce TILEINDEX shapeles for use with this command, one option is the gdaltindex program, part of the GDAL utility suite. The gdaltindex program will automatically generate a tile index shapele from a list of GDAL supported raster les passed on the command line.
Usage: gdaltindex [-tileindex field_name] index_file [gdal_file]* % gdaltindex doq_index.shp doq/*.tif
Tile Index Notes The shapele (index_le) will be created if it doesnt already exist. The default tile index eld is location. Simple rectangular polygons are generated in the same coordinate system as the rasters. Raster lenames will be put in the le exactly as they are specied on the commandline. Many problems with tile indexes relate to how relative paths in the tile index are evaluated. They should be evaluated relative to the SHAPEPATH if one is set, otherwise relative to the tileindex le. When in doubt absolute paths may avoid path construction problems. 7.2. Raster Data 357
The gdaltindex program is built as part of GDAL. Prebuilt binaries for GDAL including the gdaltindex program can be downloaded as part of the OSGeo4W, FWTools and MS4W distributions. See Also: Tile Indexes
7.2.5 Raster Warping

MapServer is able to resample GDAL rasters on the y into new projections. Non-GDAL rasters may only be up or down sampled without any rotation or warping. Raster warping kicks in if the projection appears to be different for a raster layer than for the map being generated. Warped raster layers are signicantly more expensive to render than normal raster layers with rendering time being perhaps 2-4 times long than a normal layer. The projection and datum shifting transformation is computed only at selected points, and generally linearly interpolated along the scanlines (as long as the error appears to be less than 0.333 pixels. In addition to reprojecting rasters, the raster warping ability can also apply rotation to GDAL rasters with rotational coefcients in their georeferencing information. Currently rotational coefcients wont trigger raster warping unless the map and layer have valid (though matching is ne) projection denitions.
7.2.6 24bit RGB Rendering

Traditionally MapServer has been used to produce 8 bit pseudo-colored map displays generated from 8bit greyscale or pseudocolored raster data. However, if the raster le to be rendered is actually 24bit (a red, green and blue band) then additional considerations come into play. Currently rendering of 24bit imagery is only supported via the GDAL renderer. The built-in PNG, JPEG and other drivers do not support 24bit input images. If the output is still 8bit pseudo-colored (the IMAGEMODE is PC256 in the associated OUTPUTFORMAT declaration) then the full 24bit RGB colors for input pixels will be converted to a color in the colormap of the output image. By default a color cube is used. That is a xed set of 175 colors providing 5 levels of red, 7 levels of green and 5 levels of blue is used, plus an additional 32 greyscale color entries. Colors in the input raster are mapped to the closest color in this color cube on the y. This substantial degrades color quality, especially for smoothly changing images. It also lls up the colors table, limited to 256 colors, quite quickly. A variation on this approach is to dither the image during rendering. Dithering selects a color for a pixel in a manner that diffuses error over pixels. In an area all one color in the source image, a variety of output pixel colors would be selected such that the average of the pixels would more closely approximate the desired color. Dithering also takes advantage of all currently allocated colors, not just those in the color cube. Dithering requires GDAL 1.1.9 or later, and is enabled by providing the PROCESSING DITHER=YES option in the maple. Dithering is more CPU intensive than using a simple color cube, and should be avoided if possible in performance sensitive situations. The other new possibility for handling 24bit input imagery in MapServer 4.0 or later, is to produce 24bit output images. The default IMAGETYPE png24 or IMAGETYPE jpeg declaration may be used to produce a 24bit PNG output le, instead of the more common 8bit pseudo-colored PNG le. The OUTPUTFORMAT declaration provides for detailed control of the output format. The IMAGEMODE RGB and IMAGEMODE RGBA options produce 24bit and 32bit (24bit plus 8bit alpha/transparency) for supported formats.
7.2.7 Special Processing Directives

As of MapServer 4.0, the PROCESSING parameter was added to the LAYER of the Maple. It is primarily used to pass specialized raster processing options to the GDAL based raster renderer. The following processing options are supported in MapServer 4.0 and newer.
358
BANDS=red_or_grey[,green,blue[,alpha]] This directive allows a specic band or bands to be selected from a raster le. If one band is selected, it is treated as greyscale. If 3 are selected, they are treated as red, green and blue. If 4 are selected they are treated as red, green, blue and alpha (opacity). Example:
PROCESSING "BANDS=4,2,1"
COLOR_MATCH_THRESHOLD=n Alter the precision with which colors need to match an entry in the color table to use it when producing 8bit colormapped output (IMAGEMODE PC256). Normally colors from a raster colormap (or greyscale values) need to match exactly. This relaxes the requirement to being within the specied color distance. So a COLOR_MATCH_THRESHOLD of 3 would mean that an existing color entry within 3 (sum of difference in red, green and blue) would be used instead of creating a new colormap entry. Especially with greyscale raster layers, which would normally use all 256 color entries if available, this can be a good way to avoid stealing your whole colormap for a raster layer. Normally values in the range 2-6 will give good results. Example:
PROCESSING "COLOR_MATCH_THRESHOLD=3"
DITHER=YES This turns on error diffusion mode, used to convert 24bit images to 8bit with error diffusion to get better color results. Example:
PROCESSING "DITHER=YES"
LOAD_FULL_RES_IMAGE=YES/NO This option affects how image data is loaded for the resampler when reprojecting or otherwise going through complex resampling (as opposed to the fast default image decimation code path). This forces the source image to be loaded at full resolution if turned on (default is NO). This helps work around problems with default image resolution selection in when radical warping is being done. It can result in very slow processing if the source image is large. LOAD_WHOLE_IMAGE=YES/NO This option affects how image data is loaded for the resampler (as above). This option, if turned on, will cause the whole source image to be loaded and helps make up for problem identifying the area required, usually due to radical image reprojection near a dateline or projection horizon. The default is NO. Turning this on can dramatically affect rendering performance and memory requirements. LUT[_n]=<lut_spec> This directive (MapServer 4.9+) instructs the GDAL reader to apply a custom LUT (lookup table) to one or all color bands as a form of on the y color correction. If LUT is used, the LUT is applied to all color bands. If LUT_n is used it is applied to one color band (n is 1 for red, 2 for green, 3 for blue, 4 for alpha). The LUT can be specied inline in the form:
<lut_spec> = <in_value>:<out_value>[,<in_value>:<out_value>]*
This essentially establish particular input values which are mapped to particular output values. The list implicitly begins with 0:0, and 255:255. An actual 256 entry lookup table is created from this specication, linearly interpolating between the values. The in values must be in increasing order. The LUT specication may also be in a text le with the <lut_spec> being the lename. The le contents should be in the same syntax, and the le is searched relative to the maple. Example:
PROCESSING PROCESSING PROCESSING or PROCESSING "LUT_1=red.lut" "LUT_2=green.lut" "LUT_3=blue.lut" "LUT=100:30,160:128,210:200"
7.2. Raster Data
359
As a special case there is also support for GIMP format curve les. That is the text les written out by the Tools->Color->Curves tool. If this is specied as the lename then it will be internally converted into linear segments based on the curve control points. Note that this will not produce exactly the same results as the GIMP because linear interpolation is used between control points instead of curves as used in the GIMP. For a reasonable number of control points the results should be similar. Also note that GIMP color curve les include an overall value curve, and curves for red, green, blue and alpha. The value curve and the appropriate color curve will be composed internally to produce the nal LUT. Example:
PROCESSING "LUT=munich.crv"
OVERSAMPLE_RATIO=double Default is 2.5. PLE_RATIO. Example:

PROCESSING "OVERSAMPLE_RATIO=1.0"
Rendering time will increase with increasing OVERSAM-
RESAMPLE=NEAREST/AVERAGE/BILINEAR This option can be used to control the resampling kernel used sampling raster images. The default (and fastest) is NEAREST. AVERAGE will perform compute the average pixel value of all pixels in the region of the disk le being mapped to the output pixel (or possibly just a sampling of them). BILINEAR will compute a linear interpolation of the four pixels around the target location. This topic is discussed in more detail in MS RFC 4: MapServer Raster Resampling. Resampling options other than NEAREST result in use of the generalized warper and can dramatically slow down raster processing. Generally AVERAGE can be desirable for reducing noise in dramatically downsampled data, and can give something approximating antialiasing for black and white linework. BILINEAR can be helpful when oversampling data to give a smooth appearance. Example (chose one):
PROCESSING "RESAMPLE=NEAREST" PROCESSING "RESAMPLE=AVERAGE" PROCESSING "RESAMPLE=BILINEAR"
SCALE[_n]=AUTO or min,max This directive instructs the GDAL reader to pre-scale the incoming raster data. It is primarily used to scale 16bit or oating point data to the range 0-255, but can also be used to constrast stretch 8bit data. If an explicit min/max are provided then the input data is stretch (or squished) such that the minimum value maps to zero, and the maximum to 255. If AUTO is used instead, a min/max is automatically computed. To control the scaling of individual input bands, use the SCALE_1, SCALE_2 and SCALE_3 keywords (for red, green and blue) instead of SCALE which applies to all bands. Example:
PROCESSING or PROCESSING PROCESSING PROCESSING "SCALE=AUTO" "SCALE_1=409,1203" "SCALE_2=203,296" "SCALE_3=339,1004"
7.2.8 Raster Query

A new feature added in MapServer 4.4 is the ability to perform queries on rasters in a manner similar to queries against vector layers. Raster queries on raster layers return one point feature for each pixel matching the query. The point features will have attributes indicating the value of different bands at that pixel, the nal rendering color and the class name. The resulting feature can be directly access in MapScript, or processed through templates much like
360
normal vector query results. Only raster layers with a query TEMPLATE associated can be queried, even for the query methods that dont actually use the query template (much like vector data). Raster query supports QueryByPoint, QueryByRect, and QueryByShape. QueryByPoint supports single and multiple result queries. Other query operations such as QueryByIndex, QueryByIndexAdd, QueryByAttributes and QueryByFeature are not supported for raster layers. Raster layers do not support saving queries to disk, nor query maps. Raster queries return point features with some or all of the following attributes: x georeferenced X location of pixel. y georeferenced Y location of pixel. value_list a comma separated list of the values of all selected bands at the target pixel. value_n the value for the nth band in the selected list at this pixel (zero based). There is one value_n entry for each selected band. class Name of the class this pixel is a member of (classied layers only). red red component of the display color for this pixel. green green component of the display color for this pixel. blue blue component of the display color for this pixel. The red, green and blue attribute are intended to be the nal color the pixel would be rendered with, but in some subtle cases it can be wrong (ie. classied oating point results). The selected bands are normally the band that would be used to render the layer. For a pure query-only layer BANDS PROCESSING directive can be used to select more bands than could normally be used in a render operation. For instance for a 7 band landsat scene a PROCESSING BANDS=1,2,3,4,5,6,7 directive could be used to get query results for all seven bands in results to a query operation. Care should be taken to avoid providing a large query area (selecting alot of pixels) as each selected pixel requires over 100 bytes of memory for temporary caching. The RASTER_QUERY_MAX_RESULT PROCESSING item can be used to restrict the maximum number of query results that will be returned. The default is one million which would take on the order of 100MB of RAM. Query results can be returned as HTML via the normal substitution into query template HTML. Query results are also accessible via WMS GetFeatureInfo calls, and from MapScript. The following example shows executing a feature query from Python MapScript and fetching back the results:
map = mapscript.Map(rquery.map) layer = map.getLayer(0) pnt = mapscript.Point() pnt.x = 440780 pnt.y = 3751260 layer.queryByPoint( map, pnt, mapscript.MS_MULTIPLE, 180.0 ) layer.open() for i in range(1000): result = layer.getResult( i ) if result is None: break print (%d,%d) % (result.shapeindex, result.tileindex) s = layer.getShape( result.shapeindex, result.tileindex ) for i in range(layer.numitems): print %s: %s % (layer.getItem(i), s.getValue(i))
7.2. Raster Data
361
layer.close()
This following is a simple example query TEMPLATE le. The raster pixel attributes will be substituted in before the query result is returned to the user as HTML.
Pixel:<br> values=[value_list]<br> value_0=[value_0]<br> value_1=[value_1]<br> value_2=[value_2]<br> RGB = [red],[green],[blue]<p> Class = [class]<br>
Internally raster query results are essentially treated as a set of temporary features cached in RAM. Issuing a new query operation clears the existing query cache on the layer. The transitory in-memory representation of raster query results is also responsible for the inability to save raster query results since saved query results normally only contain the feature ids, not the entire features. Some addition information is available in the RasterQuery Wiki topic.
7.2.9 Raster Display Performance Tips

Build overview levels for large rasters to ensure only a reasonable amount of data needs to be touched to display an overview of a large layer. Overviews can be implemented as a group of raster layers at different resolutions, using MINSCALEDENOM, and MAXSCALEDENOM to control which layers are displayed at different resolutions. Another, perhaps easier way, is to build overviews for GDAL supported formats using the gdaladdo utility. When using tileindexes to manage many raster les as a single le, it is especially important to have an overview layer that kicks in at high scales to avoid having to open a large number of raster les to fulll the map request. Preprocess RGB images to eightbit with a colormap to reduce the amount of data that has to be read, and the amount of computation to do on the y. For large images use tiling to reduce the overhead for loading a view of a small area. This can be accomplished using the TILEINDEX mechanism of the maple, or by creating a tiled format le (ie. TIFF with GDAL). Ensure that the image is kept on disk in the most commonly requested projection to avoid on-the-y image warping which is fairly expensive. If you are getting debug output from MapServer in your web server log le, check to see if the message msResampleGDALToMap in effect appears. If so, the raster layer is being resampled. If you dont think it should be resampled carefully review your map le to ensure that the layer projection exactly matches the map projection or that the layer has no projection denition.
7.2.10 Preprocessing Rasters

The following operations use GDAL commandline utilities, some of which are python scripts. They are generally available on any GDAL installation with python support. Producing Tiled Datasets The TIFF and Erdas Imagine formats support internal tiling within les, and will generally give better display speed for local map requests from large images. To produce a GeoTIFF le in internally tiled format using the TILED=YES creation option with the gdal_translate utility:
362
gdal_translate -co TILED=YES original.tif tiled.tif
Erdas Imagine (HFA) les are always tiled, and can be larger than 4GB (the GeoTIFF limit). Use a command like the following to translate a raster to Imagine format:
gdal_translate -of HFA original.tif tiled.img
Reducing RGB to 8bit Rendering and returning 24bit images (especially as PNG) can be quite expensive in render/compress time and bandwidth. Pre-reducing raster data to 8bit can save disk space, processing time, and bandwidth. However, such a color reduction also implicitly reduces the quality of the resulting map. The color reduction can be done on the y by MapServer but this requires even more processing. A faster approach is to pre-reduce the colors of 24bit imagery to 8bit. This can be accomplished with the GDAL rgb2pct.py script like this:
rgb2pct.py original.tif 8bit.tif
By default images will be reduced to 256 colors but this can mean there are not enough colors to render other colors in the map. So it may be desired to reduce to even less colors:
rgb2pct.py -n 200 original.tif 8bit.tif
Downsampling to 8bit should be done before internal tiling and overview building. The rgb2pct.py script tries to compute an optimal color table for a given image, and then uses error diffusion during the 24bit to 8bit reduction. Other packages (such as ImageMagick or Photoshop) may have alternative color reduction algorithms that are more appropriate for some uses. Building Internal Overviews Most GDAL supported raster formats can have overviews pre-built using the gdaladdo utility. However, a few formats, such as JPEG2000, MrSID, and ECW already contain implicit overviews in the format themselves and will not generally benet from external overviews. For other formats (such as GeoTIFF, and Erdas Imagine format) use a command like the following to build overviews:
gdaladdo tile.tif 2 4 8 16 32 64 128
The above would build overviews at x2 through x128 decimation levels. By default it uses nearest neighbour downsampling. That is one of the pixels in the input downsampled area is selected for each output pixel. For some kinds of data averaging can give much smoother overview results, as might be generated with this command:
gdaladdo -r average tiled.tif 2 4 8 16 32 64 128
Note that overview building should be done after translating to a nal format. Overviews are lost in format conversions using gdal_translate. Also, nothing special needs to be done to make MapServer use GDAL generated overviews. They are automatically picked up by GDAL when mapserver requests a reduced resolution map. Building External Overviews When working with large collections of raster les using a MapServer tileindex, it is desirable to build reduced resolution overview layers that kick in at high scales (using MINSCALEDENOM / MAXSCALEDENOM to control which layer activates). Preparing the overviews can be a somewhat complex process. One approach is to use the gdal_merge.py script to downsample and mosaic all the images. For instance if we want to produce an overview of many 1meter ortho photos with 250 meter pixels we might do something like:
7.2. Raster Data
363
gdal_merge.py -o overview.tif -ps 250 250 ortho_*.tif
The gdal_merge.py utility suffers from a variety of issues, including no support for different resampling kernels. With GDAL 1.3.2 or later it should be able to accomplish something similar with the more exible gdalwarp utility:
gdalwarp -rc -tr 250 250 ortho_*.tif overview.tif
In some cases the easiest way of generating an overview is to let MapServer do it using the shp2img utility. For instance if the tileindex layer is called orthos we could do something like:
shp2img -m ortho.map -l orthos -o overview.png
Note that the overview will be generated with the extents and size in the .map le, so it may be necessary to temporarily adjust the map extents and size values to match the raster extents and the desired output size. Also, if using this method, dont leave large les in PNG (or GIF or JPEG) format as they are slow formats to extract subareas from.
7.2.11 Georeference with World Files

World les are a simple mechanism for associating georeferencing (world coordinates) information with raster les. ESRI was the rst company to propagate the use of world les, and they often used with TIFF instead of embedding georeferencing information in the le itself. The world le contents look like the following. The rst coefcient is the X pixel size. The second and third are rotational/shear coefcients (and should normally be 0.0). The fourth is the Y pixel size, normally negative indicating that Y decreases as you move down from the top left origin. The nal two values are the X and Y location of the center of the top left pixel. This example is for an image with a 2m x 2m pixel size, and a top left origin at (356800E, 5767999N):
2 0.0000000000 0.0000000000 -2 356800.00 5767999.00
The name of the world le is based on the le it relates to. For instance, the world le for aerial.tif might be aerial.tfw. Conventions vary for appropriate endings, but with MapServer the extension .wld is always OK for world les. Since the GDAL/OGR library is used for vector and raster access in MapServer, many more formats are supported, so please see the OGR (vector) and GDAL (raster) formats pages.
364
CHAPTER 8
Output Generation
8.1 AGG Rendering Specics

Author Thomas Bonfort Contact thomas.bonfort at gmail Revision $Revision: 8295 $ Date $Date: 2008-12-26 21:08:04 -0800 (Fri, 26 Dec 2008) $ Last Updated 2008/11/24 Table of Contents AGG Rendering Specics Introduction Setting the OutputFormat New Features Modied Behavior
8.1.1 Introduction
MapServer 5.0 released with a new rendering backend. This howto details the changes and new functionality that this adds to map creation. This howto assumes you already now the basics of maple syntax. If not, you should probably be reading the maple syntax.
8.1.2 Setting the OutputFormat

24 bit png (high quality, large le size):
OUTPUTFORMAT NAME AGG DRIVER AGG/PNG IMAGEMODE RGB END
365
24 bit png, transparent background:

OUTPUTFORMAT NAME AGGA DRIVER AGG/PNG IMAGEMODE RGBA END
24 bit jpeg (jpeg compression artifacts may appear, but smaller le size):
OUTPUTFORMAT NAME AGG_JPEG DRIVER AGG/JPEG IMAGEMODE RGB END
png output, with number of colors reduced with quantization.

OUTPUTFORMAT NAME AGG_Q DRIVER AGG/PNG IMAGEMODE RGB FORMATOPTION "QUANTIZE_FORCE=ON" FORMATOPTION "QUANTIZE_DITHER=OFF" FORMATOPTION "QUANTIZE_COLORS=256" END
8.1.3 New Features

All rendering is now done antialiased by default. All ANTIALIAS keywords are now ignored, as well as TRANSPARENCY ALPHA. Pixmaps and fonts are now all drawn respecting the images internal alpha channel (unless a backgroundcolor is specied). As with GD in ver. 4.10, using a SYMBOL of type ELLIPSE to draw thick lines isnt mandatory anymore. To draw a thick line just use:
STYLE WIDTH 5 COLOR 0 0 255 END
A line symbolizer has been added, that works with vector or pixmap symbols, to draw textured lines. This happens by default if a lines style is given a symbol of type vector or pixmap. To enable shield symbolization, i.e. a marker placed only on some points of the line, you must add a GAP parameter to your symbol denition. This GAP value is scaled w.r.t the styles SIZE parameter. Specify a positive gap value for symbols always facing north (optionally rotated by the ANGLE of the current style), or a negative value for symbols that should follow the line orientation
366
Chapter 8. Output Generation
This happens by default if a lines style is given a symbol of type vector or pixmap. To enable shield symbolization, i.e. a marker placed only on some points of the line, you must add a GAP parameter to your symbol denition. This GAP value is scaled w.r.t the styles SIZE parameter - specify a positive gap value for symbols always facing north (optionally rotated by the ANGLE of the current style), or a negative value for symbols that should follow the line orientation Pixmap and font symbols can now be rotated without loosing their transparency For POLYGON layers with no specic SYMBOL, the WIDTH keyword species the width of the outline, if an OUTLINECOLOR was specied. This is a shorthand that avoids having to create multiple styles for basic rendering, and will provide a marginal performance gain. Note that in this case, the width of the outline is /not/ scale dependent.
8.1.4 Modied Behavior

When specifying a SYMBOL for a polygon shape, the GAP parameter of the symbol is used as a separation between each rendered symbol. This works for symbols of type vector, pixmap and ellipse. For example a symbol dened by
SYMBOL NAME triangle TYPE VECTOR FILLED TRUE POINTS 0 1 .5 0 1 1 0 1 END GAP 1 END
that is rendered in a class where SIZE is 15 will be rendered like
layers of type CIRCLE support hatch type symbol lling the ENCODING keyword for labels is now enforced. If unset, MapServer will treat your label text byte-by-byte (resulting in corrupt special characters).
8.2 AntiAliasing with MapServer

Author Pericles Nacionales Contact naci0002 at umn.edu Revision $Revision: 11477 $ Date $Date: 2011-04-06 04:51:20 -0700 (Wed, 06 Apr 2011) $ Last Updated 2009/01/17
8.2. AntiAliasing with MapServer
367
Note: For quality antialiased output from mapserver, it is highly recommended to use the AGG rendering. This document applies only if you whish to stick to the GD rendering, or if you are using a version predating the 5.0 release of mapserver. Table of Contents AntiAliasing with MapServer What needs to be done
8.2.1 What needs to be done

1. Change (or add) IMAGETYPE keyword in MAP object to PNG24 (24-bit PNG output) or JPEG
MAP ... IMAGETYPE P N G 24 ... END
2. Add TRANSPARENCY to the LAYER object and set value to ALPHA

MAP ... IMAGETYPE P N G 24 ... LAYER ... TRANSPARENCY ALPHA ... END END
3. Add ANTIALIAS keyword to the STYLE object within the CLASS object within the LAYER and set value to TRUE
MAP ... IMAGETYPE P N G 24 ... LAYER ... TRANSPARENCY ALPHA ... CLASS ... STYLE ... ANTIALIAS TRUE ... END \.\.\. END # end class END # end layer END # end map
368
Note: Dont use the SYMBOL or the SIZE keywords within the CLASS object, instead use WIDTH to specify width of line or polygon outline. Dont use WIDTH unless you have to. If you must dene a SYMBOL, use symbol of type ELLIPSEit supports antialiasing. Heres an example of a real-world maple: Note: From Mapserver 6, symbol type CARTOLINE is no longer supported. You have to use AGG rendering and STYLE PATTERN to achieve dashed lines. Therefore, the following example does not work anymore.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
MAP NAME ms101 EXTENT -2198022.00 -2444920.25 2707932.00 1234545.25 SIZE 640 480 SHAPEPATH data SYMBOLSET symbols/symbols.txt IMAGETYPE P N G 24 PROJECTION "init=epsg:2163" END
# CONUS LAEA (US)
# The layer below will be rendered as 1-pixel wide, antialiased line # If youd like to change the line thickness add the WIDTH keyword # in the STYLE object with a value of 3 or greater. LAYER # begin antialiased country boundary (line) layer NAME country_line DATA shapefile/WorldCountryBorders TYPE LINE STATUS ON TRANSPARENCY ALPHA PROJECTION "init=epsg:4326" END CLASS NAME Country Boundary STYLE COLOR 96 96 96 ANTIALIAS TRUE END END END # end country boundary layer # The layer below shows one way to draw a polygon with antialiased outline LAYER # begin antialiased country boundary (polygon) layer NAME country_line DATA shapefile/Countries_area TYPE POLYGON STATUS ON TRANSPARENCY ALPHA PROJECTION "init=epsg:4326" END CLASS NAME Country Boundary
8.2. AntiAliasing with MapServer
369
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
STYLE COLOR 212 212 212 OUTLINECOLOR 96 96 96 WIDTH 3 ANTIALIAS TRUE END END END # end country boundary polygon layer # The layer below shows one way to draw a polygon with antialiased outline LAYER # begin antialiased state boundary (line) layer NAME state_line DATA shapefile/us_states TYPE LINE STATUS ON TRANSPARENCY ALPHA PROJECTION "init=epsg:4326" END CLASS NAME State Boundary STYLE COLOR 144 144 144 SYMBOL cartoline ANTIALIAS TRUE END END END # end state line layer END # end of map file
Heres how the cartoline symbol is dened: Note: From Mapserver 6, symbol type CARTOLINE is not available. You have to use AGG rendering and STYLE PATTERN to achieve dashed lines. Therefore, the following symbol can not be used anymore.
SYMBOL NAME cartoline TYPE CARTOLINE LINECAP "round" LINEJOIN "round" LINEJOINMAXSIZE 3 END
Note: The examples provided here are for illustrative purposes onlykeep your map le denitions simple. Antialiasing adds computing overhead on the server and could slow/degrade its performance. Dont use it unless you must and certainly dont use symbols with it unless you really have to.
8.3 Dynamic Charting

Author Thomas Bonfort Contact thomas.bonfort at gmail.com Revision $Revision: 12003 $ Date $Date: 2011-08-05 03:10:14 -0700 (Fri, 05 Aug 2011) $ 370 Chapter 8. Output Generation
Last Updated 2009/01/17 Table of Contents Dynamic Charting Setup Adding a Chart Layer to a Maple Pie Charts Bar Graphs Starting with version 5.0, MapServer included the ability to automatically draw pie or bar graphs whose values are taken and adjusted from attributes of a datasource. This document assumes that you are already familiar with MapServer application development and especially setting up Maple s. You can also check out the Vector Data Access Guide, which has lots of examples of how to access specic data sources.
8.3.1 Setup
Supported Renderers Dynamic charts are supported solely with the GD and AGG renderers. Attempting to add a chart layer with any other renderer (e.g. PDF or SWF) will result in an error. Rendering quality with the GD renderer is less than optimal, especially with small graphs, due to the lack of subpixel rendering functions. Output from AGG and GD Renderers MapServer AGG Rendering
MapServer GD Rendering
8.3.2 Adding a Chart Layer to a Maple

Layer Type A new type of layer has been added to the maple syntax. To specify a chart layer, use
8.3. Dynamic Charting
371
LAYER ... TYPE CHART ... END
No other specic keywords have been added in order to keep the number of different keywords to a minimum in the maple syntax, therefore all the chart specic conguration is determined by PROCESSING directives. Specifying the Size of each Chart The size of each chart is specied by the CHART_SIZE directive. If two values are given for this parameter, this will specify the width and height of each chart (this only applies for bar graphs). By default, the charts are 20x20 pixels.
LAYER TYPE CHART PROCESSING "CHART_SIZE=21" # specify size of the chart for pie or bar graphs #PROCESSING "CHART_SIZE=20 10" # specify width and height for bar graphs ... END
From version 5.2 and onwards, the diameter of a pie chart can be bound to an attribute,using the CHART_SIZE_RANGE PROCESSING attribute:
PROCESSING "CHART_SIZE_RANGE = itemname minsize maxsize minval maxval"
where: itemname is the name of the attribute that drives the chart size (e.g. total_sales) minsize and maxsize are the minimum and maximum chart size values in pixels (e.g. 10 100) minval and maxval are the minimum values of the attribute that correspond to chart sizes of minsize and maxsize (e.g. 10000 1000000). If the attribute value is smaller than minval then the chart size will be minsize pixels, and if the attribute value is larger than maxval, the chart size will be maxsize pixels. Specifying the Values to be Plotted Each value to be plotted (i.e. a slice in a pie chart, or a bar in a par graph) is specied in a CLASS of the chart layer. The value to be plotted is taken from the SIZE keyword from the rst STYLE block of the class. This is semantically a bit awkward, but keeps the number of different keywords to a minimum in the maple syntax. The value given to the SIZE keyword could of course be given a static value, but dynamic charting really only makes sense with attribute binding.
LAYER ... CLASS # include a NAME keyword if you want this class to be included # in the legend NAME "value 1" STYLE # specify which value from the data source will be used as the # value for the graph SIZE [ a t t r i b u t e ] ... END
372
END CLASS ... END ... END
At least 2 CLASS blocks must be specied before charting can occur (but you already knew this if you want your charts to convey at least some information ;) ). Specifying Style The styling of each value in the charts is specied by the usual MapServer syntax. Only one style per class is supported, any other STYLE block will be silently ignored. Only a subset of the styling keywords are supported:
STYLE SIZE [ a t t r i b u t e ] # specify the fill color COLOR r g b # if present will draw an outline around the corresponding bar or slice OUTLINECOLOR r g b #specify the width of the outline if OUTLINECOLOR is present (defaults to 1) WIDTH w # only for pie charts. a is the number of pixels the corresponding # slice will be offset relative to the center of the pie. This is useful # for emphasizing a specific value in each chart. b is required by the # mapfile parser but is ignored. OFFSET a b END
8.3.3 Pie Charts

This is the default type of chart that is rendered. This can also be specically set with a PROCESSING keyword in the layer attributes:
PROCESSING "CHART_TYPE=PIE"
For each shape in the layers datasource, the STYLE SIZE is used to set the relative size (value) of each pie slice, with the angles of the slices that are automatically computed so as to form a full pie. For example:
1 2 3 4 5 6 7 8 9 10 11 12 13
LAYER NAME "Ages" TYPE CHART CONNECTIONTYPE postgis CONNECTION "blabla" DATA "the_geom from demo" PROCESSING "CHART_TYPE=pie" PROCESSING "CHART_SIZE=30" STATUS ON CLASS NAME "Population Age 0-19" STYLE SIZE [ v 1006]
8.3. Dynamic Charting
373
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
COLOR 255 244 237 END END CLASS NAME "Population Age 20-39" STYLE SIZE [ v 1007] COLOR 255 217 191 END END CLASS NAME "Population Age 40-59" STYLE SIZE [ v 1008] COLOR 255 186 140 END END END
In the example above, if for a given shape we have v1006=1000, v1007=600 and v1008=400 then the actual pie slices for each class will be respectively 50%, 30% and 20% of the total pie size.
8.3.4 Bar Graphs

Bar graph drawing is set with a PROCESSING keyword in the layer attributes:
PROCESSING "CHART_TYPE=BAR"
For each shape in the layers datasource, the STYLE SIZE is used to set the relative size (value) of each bar in the graph. By default, the vertical axis of each bar graph is scaled for the values of the corresponding shape, and will always include the origin (=0). For example a shape whose STYLE SIZEs contains values {5,8,10,3} will be plotted on a graph whose vertical axis spans 0 to 10. a shape whose STYLE SIZEs contains values {-5,-8,-10,-3} will be plotted on a graph whose vertical axis spans -10 to 0. a shape whose STYLE SIZEs contains values {-5,-8,10,3} will be plotted on a graph whose vertical axis spans -8 to 10. Additional PROCESSING directives are used to optionally specify the bounds of vertical axes so that the graphs for all the shapes can be plotted with the same scale:
PROCESSING "CHART_BAR_MINVAL=val" PROCESSING "CHART_BAR_MAXVAL=val"
Values in the datasource that are above CHART_BAR_MAXVAL or below CHART_BAR_MINVAL will be clipped respectively to these values. If only one of these directives is included, the other will be automatically adjusted for each shape to include at least the origin, i.e. the graphs for all the shapes will be in the same scale only if all the values are of the same sign (positive or negative). Stacked bar Graphs Stacked bar graphs can be drawn using:
374
PROCESSING "CHART_TYPE=VBAR"
8.4 Flash Output

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Author Yewondwossen Assefa Contact assefa at dmsolutions.ca Revision $Revision: 12056 $ Date $Date: 2011-08-14 15:13:13 -0700 (Sun, 14 Aug 2011) $ Last Updated 2008/07/15 Table of Contents Flash Output Introduction Installing MapServer with Flash Support How to Output SWF Files from MapServer What is Currently Supported and Not Supported
8.4.1 Introduction
Since MapServer 4.0, MapServer can output Flash les, in SWF format (or Shockwave Flash Format). The following document outlines how to enable Flash output in MapServer. Note: SWF is no longer supported in version 6.0. Links to Flash-Related Information Open Source Flash Viewer Flash maps demo
8.4.2 Installing MapServer with Flash Support

To check that your mapserv executable includes Flash support, use the -v command-line switch and look for OUTPUT=SWF.
$ ./mapserv -v MapServer version 5.2.0-rc1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS SUPPORTS=GEOS SUPPORTS=RGBA_PNG INPUT=JPEG INPUT=POSTGIS INPUT=ORACLESPATIAL INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
8.4. Flash Output
375
Using Pre-compiled Binaries Windows users can use MS4W, which supports SWF output. Compiling MapServer with Flash Support The library chosen to output SWF les is the Ming library. Ming is a C library for generating SWF (Flash) format movies, and it contains a set of wrappers for using the library from C++ and popular scripting languages like PHP, Python, and Ruby.
Building on Windows
download the Ming library (the version currently supported is 0.2a) as of Ming 0.3 there was no makele for Windows available in the distribution yet, but you can download a MS VC++ makele (makele.vc) from here (contains makele and also libming.lib) copy makele.vc under the src directory (ming-0.2/src) execute:
nmake /f makefile.vc
at this point you should have a libming.lib that will be linked with MapServer edit the nmake.opt in your MapServer directory and uncomment the MING=-DUSE_MING_FLASH ag, and point MING_DIR to your Ming directory. build MapServer as usual
Building on Unix
Use the with-ming congure ag to enable MING support on Unix. with-ming=dir will try to nd the include les and library in the indicated directory.
Note: compiling MapServer 4.4.2 with flash support (mingbeta version 0.3) requires the -DMING_VERSION_03 option otherwise the make fails. This option should be included in the configure.in after -DUSE_MING_FLASH as below: MING ENABLED= "-DUSE_MING_FLASH -DMING_VERSION_03"
8.4.3 How to Output SWF Files from MapServer

SWF output is specied by using the OUTPUTFORMAT object. There are 2 possible output types: 1. A single movie containing the raster output for all the layers. To enable this, declare the following in the map le:
OUTPUTFORMAT NAME swf MIMETYPE "application/x-shockwave-flash" DRIVER swf IMAGEMODE PC256 FORMATOPTION "OUTPUT_MOVIE=SINGLE" END
376
2. A movie for every layer (vector movies for vector layers and raster movies for raster layers). To enable this, declare the following in the map le:
OUTPUTFORMAT NAME swf MIMETYPE "application/x-shockwave-flash" DRIVER swf IMAGEMODE PC256 FORMATOPTION "OUTPUT_MOVIE=MULTIPLE" END
Other OutputFormat Options FORMATOPTION FULL_RESOLUTION=FALSE The FULL_RESOLUTION applies only for vector layers. If set to FALSE, ltering will be applied to the vector elements. It results in a smaller SWF le. The default value is TRUE. FORMATOPTION LOAD_AUTOMATICALLY=OFF Setting this option to OFF will not load the SWF les for each layer. The default value is ON. Composition of the Resulting SWF Files Several SWF Files will be produced from a single map le: there will be one SWF le for each layer dened in the map le and one main SWF le containing critical information on the map le and the layers produced. The main SWF File will contain Action Script (AS) code that gives critical information on the map le and the SWF layers produced. Basically there will be an object called mapObj containing the height, width, extent, scale, number of layers, etc. Here is an example (in AS) of the contents of this main movie:
mapObj = new Object (); mapObj.name = "DEMO_SWF"; mapObj.width = 400; mapObj.height = 300; mapObj.extent = "-2594561.353333,3467361.353333,3467361.353333,3840000.000000"; ; mapObj.numlayers = 4; mapObj.layers = new Array (); function LayerObj (name, type, fullname, relativename) { this.name = name; this.type = type; this.fullname = fullname; this.relativename = relativename; } mapObj.layers[0] = new LayerObj ("park", "2", "c:/tmp/ms_tmp/102389536132841_layer_0.swf", "10 mapObj.layers[1] = new LayerObj ("popplace", "4", "c:/tmp/ms_tmp/102389536132841_layer_1.swf", mapObj.layers[2] = new LayerObj ("rail", "1", "c:/tmp/ms_tmp/102389536132841_layer_2.swf", "10 mapObj.layers[3] = new LayerObj ("road", "1", "c:/tmp/ms_tmp/102389536132841_layer_3.swf", "10
This example is produced based on a maple with two layers dened in it. We create a layer class object containing useful information on a layer. The parameters are: Name : the name found in the map le Type : the type of layer ( 0 = Point Layer; 1=Line; 2=Polygon; 3=Raster; 4=Annotation; 6=Circle) Fullname : Full name of the le with path included Relative name : Relative Name
8.4. Flash Output
377
For example you can use mapObj.layers[0].name to extract the name of the rst layer. Note: All map parameters from MapServer are not exported at this time. We should come up with a list of information of what we want to output. Note that this information can be used in a Flash application to load the SWF le, to build a legend, to build a scale bar, etc. SWF Files for each layer Each layer dened in the maple will have an associated SWF le created. The names of these SWF les are based on the name of the main le with an addition of layer_X at the end of the name (where X is the layer index). These SWF les will contain vector and raster data as well as some Action Script depending on the layer and some congurations in the map le. We will see these congurations in detail in the following section. Exporting Attributes Exporting attributes works on a layer basis (it is only available for Vector Layers). To be able to export attributes to the SWF les, you have to dene a metadata item called SWFDUMPATTRIBUTES in the layer section of the maple. Here is an example :
... LAYER NAME park METADATA "DESCRIPTION""Parks" "RESULT_FIELDS" "NAME_E YEAR_EST AREA_KMSQ" "SWFDUMPATTRIBUTES" "NAME_E,AREA_KMSQ " END TYPE POLYGON STATUS ON DATA park ...
In the above example, the values for the attributes NAME_E and AREA_KMSQ will be exported for each element in the layer. The resulting SWF File will have the values of these attributes (written in Action Script). Here is an example related to the above layer:
nAttributes= 2; Attributes = new Array(); Attributes[0] = "NAME_E"; Attributes[1] = "AREA_KMSQ"; Element = new Array (); Element[0] = new Array(); Element[0][0] = "Ellesmere Island National Park Reserve"; Element[0][1] = "1500"; Element[1][0] = " Aulavik National park"; Element[1][1] = "1500";
Events and Highlights Here is what is currently implemented concerning events (events here refer to mouse events happening on an element. The available events are MOUSEUP, MOUSEDOWN, MOUSEOVER, MOUSEOUT): Events are only available for layers that have dened attributes exported (using SWFDUMPATTRIBUTES). This is like dening that a certain layer is queryable.
378
When a mouse event happens on one of the elements, there is an Action Script call that is made: _root.ElementSelecetd(LayerId, ShapeId, Event) . The Flash application who wants to receive these events should dene the function ElementSelected and use the information received to do actions like retrieving the attribute values from the specic SWF for the specied shape and display it. In order to have highlighting, it has to be dened when the SWF is produced (basically highlighting means that the shape is redrawn using a different color). As of MapServer 5.0, highlighting is available on queryable layers by using the QueryMap object in the map le to extract the color and do a highlight when on MOUSEOVER. The current implementation will highlight all objects that are in a layer that uses SWFDUMPATTRIBUTES, using the COLOR set in the QueryMap object in the maple. Before MapServer 5.0, all objects that are in a layer that uses SWFDUMPATTRIBUTES are highlighted using a red color. Fonts Ming uses a special type of font called FDB les. It does not yet support Truetype fonts. Please refer to ming documentation on how to produce FDB les. Outputting Raster SWF for Vector Layers One mechanism would be to use the metadata for layer objects to dene a raster output for vector layers. We could use something like SWFOUTPUT RASTER. If this sounds desirable, please le an enhancement ticket with this request, specifying the Output-SWF component.
8.4.4 What is Currently Supported and Not Supported

1. Vector layers Layer Point (case MS_LAYER_POINT) : done msDrawMarkerSymbol msDrawLabel Layer line (case MS_LAYER_LINE) : done msDrawLineSymbol msDrawLabel Layer circle ( case MS_LAYER_CIRCLE) : not done (should be done easily but missing data for testing) omsCircleDrawLineSymbol omsCircleDrawShadeSymbol Layer annotation (case MS_LAYER_ANNOTATION): done omsDrawMarkerSymbol omsDrawLabel Layer Polygon (MS_SHAPE_POLYGON): done omsDrawShadeSymbol omsDrawLineSymbol omsDrawLabel
8.4. Flash Output
379
Vector Low Level functions omsDrawMarkerSymbol * case(MS_SYMBOL_TRUETYPE) : done * case(MS_SYMBOL_PIXMAP) : done * case(MS_SYMBOL_ELLIPSE) : done * case(MS_SYMBOL_VECTOR) : done omsDrawLineSymbol * case : simple line : done drawing with the symbols : not done omsDrawShadeSymbol * case : solid ll polygon : done * case : lled with symbols : cannot be implemented for now (tried to create a GD image to ll the shape but les created were huge) omsCircleDrawLineSymbol : not done omsCircleDrawShadeSymbol : not done omsDrawLabel : done omsDrawLabelCache : done obillboard (shadow for texts) : not done 2. Raster Layer msDrawRasterLayer: done 3. WMS Layer msDrawWMSLayer: done 4. Surround components (Legend, scalebar) : not supported
8.5 HTML Legends with MapServer

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Revision $Revision: 12496 $ Date $Date: 2011-08-28 00:04:51 -0700 (Sun, 28 Aug 2011) $ Last Updated 2006/01/09 Contents HTML Legends with MapServer Introduction Sample Site Using the HTML Legend
380
8.5.1 Introduction
The HTML legend is an alternative to the traditional GIF legend in MapServer. The following document describes the process for implementing an HTML legend in MapServer CGI applications (NOTE: MapServer version > 3.5 is required). This document assumes that you are already familiar with certain aspects of MapServer: Setting up MapServer maples and templates. Implementation Key components for generating HTML legends are 1) a template parameter in the legend object, 2) a CGI [legend] tag in the HTML le, and 3) an HTML legend template le. So that means that if the HTML page has the CGI [legend] parameter set, and the maple has a LEGEND object with its TEMPLATE set to a valid HTML legend le then an HTML legend will be returned. The following sections discuss these components. Legend Object of Maple The HTML legend is enabled by a new TEMPLATE parameter in the Legend Object of the maple. If TEMPLATE is set in the Legend Object, then the HTML legend template le is read and used to generate an HTML legend which will be inserted at the location of the [legend] tag in the main HTML template. Similar to other MapServer templates, the HTML legend template lename MUST end with an .html extension. Example 1. Sample Legend Object with the new TEMPLATE parameter
... # LEGEND object LEGEND STATUS ON KEYSIZE 18 12 # LABEL object LABEL TYPE BITMAP SIZE MEDIUM COLOR 0 0 89 END TEMPLATE "legend.html" END ...
### HTML template file
If TEMPLATE is not set, then the [legend] tag produces a regular image in a GIF/PNG image (the traditional behaviour). CGI [legend] tag The traditional CGI [legend] tag returns the URL of an image, so it is usually used inside an <IMG SRC=[legend]> tag in the HTML le. The new HTML [legend] tag returns a block of HTML, so when converting an existing application template from using a traditional image legend to the new HTML legend, you have to remove the IMG tag in the main application template. Also note that if legend mode is specied in the URL, then MapServer will return a gif containing the whole legend if no template is specied. See the CGI Reference doc for more information on CGI parameters. Example 2. [legend] tag in the main HTML template (with TEMPLATE set)
8.5. HTML Legends with MapServer
381
... <FONT SIZE=+1><B>Legend</B></FONT><BR><HR>[legend]<HR> ...
Example 3. [legend] tag in the main HTML template (with TEMPLATE not set)
... <FONT SIZE=+1><B>Legend</B></FONT><BR><HR><IMG SRC="[legend]"><HR> ...
HTML Legend Template File The HTML legend template le is a separate le that contains 0 or 1 of each of the following tags that dene blocks of HTML to use in building the legend:
[leg_group_html] ... [/leg_group_html] [leg_layer_html <OPTIONAL PARAMS>] ... [/leg_layer_html] [leg_class_html <OPTIONAL PARAMS>] ... [/leg_class_html]
Note Any text or HTML tags outside the [leg_*_html] tag pairs in the legend template le are ignored by the template parser. The following example shows what an HTML legend TEMPLATE le could look like: Example 4. An HTML legend TEMPLATE le
[leg_group_html] <tr> <td colspan=3 bgcolor=#cccccc><b>[leg_group_name]</b></td> </tr> [/leg_group_html] [leg_layer_html order_metadata=legend_order opt_flag=5] <tr> <td> <input type=checkbox name="map_[leg_layer_name]_status" value=1 [if name=layer_status oper=eq value=2]CHECKED[/if]> </td> <td colspan=2> <a href="[metadata name=href]">[metadata name=layer_title]</a> </td> </tr > [/leg_layer_html] [leg_class_html] <tr> <td width=15> </td> <td> <img src="[leg_icon width=20 height=10]" width=20 height=10> </td> <td> [leg_class_name] </td> </tr> [/leg_class_html]
Supported Tags for the TEMPLATE le:
382
HEADER block
Tag [leg_header_html]...[/leg_header_html] Description HTML block to use as the header of the legend.
FOOTER block
Tag [leg_footer_html]...[/leg_footer_html] Description HTML block to use as the footer of the legend. Example 5. HTML Legend File Using Header/Footer Blocks
[leg_header_html] <p><b>my header</b></p> [/leg_header_html] [leg_layer_html] ... [/leg_layer_html] [leg_footer_html] <p><b>my footer</b></p> [/leg_footer_html]
GROUP block
Tag [leg_group_html <OPTIONAL PARAMS>]...[/leg_group_html] Description HTML block to use for layer group headers if layers should be grouped in the legend. If not set then layers are not grouped in the legend. When the [leg_group_html] tag is used, then layers that dont belong to any group (i.e. LAYER GROUP not set in the maple) and their classes will not show up at all in the legend. The group list is decided by the order_metadata parameter, which is explained later. SUPPORTED PARAMETERS: Parameter opt_ag=<bit_mask> Description Control the groups display, by adding the following values (default is 15). The opt_ag is applied on all layers in the group. If at least one layer matches the ag, the group will show up in the legend. 1 If set, show group even if all layers in group are out of scale (default: hide groups out of scale). 2 If set, show group even if all layers in group have status OFF (default: hide groups with STATUS OFF). 4 If set, show group even if all layers in group are of type QUERY (default: hide group of TYPE QUERY) 8 If set, show group even if all layers in group are of type ANNOTATION (default: hide groups of TYPE ANNOTATION) e.g. opt_ag=12 (shown below) means show all layer types, including QUERY and ANNOTATION layers (4 + 8) 8.5. HTML Legends with MapServer 383
[leg_group_html opt_flag=12] ... [/leg_group_html]
SUPPORTED TAGS: Tag [leg_group_name] Description Returns the groups name. Tag [layer_status] Description Returns the status of the rst layer in the group. Tag [leg_icon width=<optional_width> height=<optional_height>] Description In the group context, the [leg_icon] tag returns the URL of a legend icon for the rst class in the rst layer thats part of this group. Tag [metadata name=<metadata_eld_to_display>] Description Returns specied metadata value from webs metadata. e.g. the group block below simply displays the name of the group in the legend:
[leg_group_html] <tr><td colspan=2><b>[leg_group_name]</b></td></tr> [/leg_group_html]
LAYER block
Tag [leg_layer_html <OPTIONAL PARAMS>] ... [/leg_layer_html] Description HTML block to use for layer header. If not set then no layer headers are displayed (could allow a legend with only classes in it). SUPPORTED PARAMETERS: Parameter order_metadata=<eld_to_order_by> Description Species that the value of the layer metadata <eld_to_order_by> controls the order and visibility of the layers in the legend. Layers with <eld_to_order_by> >= 0 are sorted in order of this value, with multiple layers with same value being accepted, in which case the map layer orderapplies between those layers. Layers with <eld_to_order_by> < 0 are always hidden in the legend. Parameter opt_ag=<bit_mask> Description Control the layer display process. Add the values below to acquire the desired options (default is 15): 1 If set, show layer even if out of scale (default: hide layers out of scale). 2 If set, show layer even if status is OFF (default: hide layers with STATUS OFF). 4 If set, show layer even if type is QUERY (default: hide layers of TYPE QUERY) 8 If set, show layer even if type is ANNOTATION (default: hide layers of TYPE ANNOTATION) e.g. opt_ag=14 (shown below) means do not show layers in the legend that are out of scale. 384 Chapter 8. Output Generation
[leg_layer_html opt_flag=14] ... [/leg_layer_html]
SUPPORTED TAGS: Tag [leg_layer_group] Description Returns the group name of the layer. This was added to MapServer v4.8. Tag [leg_layer_index] Description Returns the maple index value of the layer, which is useful for ordering. This was added to MapServer v4.8. Tag [leg_layer_maxscale] Description Returns the maximum scale set for the layer. This was added to MapServer v4.8. Tag [leg_layer_minscale] Description Returns the minimum scale set for the layer. This was added to MapServer v4.8. Tag [leg_layer_name] Description Returns the current LAYER NAME value. Tag [leg_icon width=<optional_width> height=<optional_height>] Description In the layer context, the [leg_icon] tag returns the URL of a legend icon for the rst class in this layer. Tag [metadata name=<metadata_eld_to_display>] Description Returns specied metadata value from this layers metadata and webs metadata. e.g. the layer block below simply displays an icon of the layers class and the layer name:
[leg_layer_html] <tr><td><img src=[leg_icon width=15 height=15]><b>[leg_layer_name]</b></td></tr> [/leg_layer_html]
CLASS block
Tag [leg_class_html <OPTIONAL PARAMS>] ... [/leg_class_html] Description HTML block to use for classes. If not set then no classes are displayed (could allow a legend with only layer headers in it). Note that classes with NULL (i.e. empty) NAMEs are not displayed. SUPPORTED PARAMETERS: Parameter opt_ag=<bit_mask> Description Control the layer (i.e. class) display process. Add the values below to acquire the desired options (default is 15). Note that using this parameter for the CLASS block has the same effect as using the opt_ag parameter in the LAYER block. 1 If set, show layer even if out of scale (default: hide layers out of scale). 2 If set, show layer even if status is OFF (default: hide layers with STATUS OFF). 4 If set, show layer even if type is QUERY (default: hide layers of TYPE QUERY)
8.5. HTML Legends with MapServer
385
8 If set, show layer even if type is ANNOTATION (default: hide layers of TYPE ANNOTATION) e.g. opt_ag=14 (shown below) means do not show classes in the legend that are out of scale.
[leg_class_html opt_flag=14] ... [/leg_class_html]
SUPPORTED TAGS: Tag [leg_class_index] Description Returns the maple index value of the class, which is useful for ordering and legend icon creation. This was added to MapServer v4.8. Tag [leg_class_maxscale] Description Returns the maximum scale set for the class. This was added to MapServer v4.8. Tag [leg_class_minscale] Description Returns the minimum scale set for the class. This was added to MapServer v4.8. Tag [leg_class_name] Description Returns the CLASS NAME value. Tag [leg_class_title] Description Returns the CLASS TITLE value. Tag [leg_layer_name] Description Returns the parent layer name. This was added to MapServer v4.8. Tag [leg_icon width=<optional_width> height=<optional_height>] Description In the layer context, the [leg_icon] tag returns the URL of a legend icon for the rst class in this layer. Tag [metadata name=<metadata_eld_to_display>] Description Returns specied metadata value from the metadata of the layer to which this class belongs and webs metadata. e.g. the class block below simply displays an icon of the layers class and the class name:
[leg_class_html] <tr><td><img src=[leg_icon width=15 height=15]><b>[leg_class_name]</b></td></tr> [/leg_class_html]
CONDITIONAL text
[if] tags can be used in any of the [leg_*_html] tags above to place conditional text. The syntax is:
[if name=<field_to_check> oper=<eq|neq|isset|isnull> value=<to_compare_with_field>] ... [/if]
Note: Nested IFs are supported. Parameter oper can be eq for equal, neq for not equal, isset (self-explanatory), or isnull (self-explanatory). The default value is equal.
386
Example 6. [if] tag can be used to maintain the state of a layer checkbox
[leg_layer_html order_metadata=legend_order opt_flag=5] <tr> <td> <input type=checkbox name="map_[leg_layer_name]_status" value=1 [if name=layer_status oper=eq value=2]CHECKED[/if] > </td> <td colspan=2> <a href="[metadata name=href]">[metadata name=layer_title]</a> </td> </tr > [/leg_layer_html]
The possible values that can be tested in an [if] tag depend on the context in which the [if] tag is used. At the moment, the number of values that can be tested is limited, but new values may be added as needed. Note that the order of the items in the following [if] contexts are listed by their order of precedence. The rule is always that special keywords have top priority (e.g. layer_status, etc.), followed by layer-level metadata, and ending with map-level metadata. The possible values that can be tested are as follows: In a [leg_group_html] context: [if name=layer_status value=...] ... [/if] value is the layer status of the rst layer that belongs to the group in integer format: 0=OFF, 1=ON, 2=DEFAULT [if name=layer_visible value=...] ... [/if] value is the visibility of the rst layer in the group: 0=NOT VISIBLE, 1=VISIBLE [if name=group_name value=...] ... [/if] [if name=any_layer_metadata value=...] ... [/if] Uses metadata value from the rst layer in the maple that belongs to that group [if name=any_web_metadata value=...] ... [/if] [if name=layer_queryable value=...] ... [/if] value is the queryability of the rst layer in the group: 0=NOT QUERYABLE, 1=QUERYABLE New in version 5.6. In a [leg_layer_html] context: [if name=layer_status value=...] ... [/if] value is the layers status in integer format: 0=OFF, 1=ON, 2=DEFAULT [if name=layer_type value=...] ... [/if] value is the layers type in integer format: 0=POINT, 1=LINE, 2=POLYGON, 3=RASTER, 4=ANNOTATION, 5=QUERY, 6=CIRCLE [if name=layer_name value=...] ... [/if] value is the layers name in string format [if name=layer_group value=...] ... [/if] value is the layers group name in string format [if name=layer_visible value=...] ... [/if] value is the visibility of the layer: 0=NOT VISIBLE, 1=VISIBLE 8.5. HTML Legends with MapServer 387
[if name=any_layer_metadata value=...] ... [/if] [if name=any_web_metadata value=...] ... [/if] [if name=layer_queryable value=...] ... [/if] value is the queryability of the layer: 0=NOT QUERYABLE, 1=QUERYABLE New in version 5.6. In a [leg_class_html] context: [if name=layer_status value=...] ... [/if] value is the status of the layer in which the class is located [if name=layer_type value=...] ... [/if] value is the layers type in integer format: 0=POINT, 1=LINE, 2=POLYGON, 3=RASTER, 4=ANNOTATION, 5=QUERY, 6=CIRCLE [if name=layer_name value=...] ... [/if] value is the layers name in string format [if name=layer_group value=...] ... [/if] value is the layers group name in string format [if name=layer_visible value=...] ... [/if] value is the visibility of the layer: 0=NOT VISIBLE, 1=VISIBLE [if name=class_name value=...] ... [/if] [if name=any_layer_metadata value=...] ... [/if] [if name=any_web_metadata value=...] ... [/if] [if name=layer_queryable value=...] ... [/if] value is the queryability of the layer: 0=NOT QUERYABLE, 1=QUERYABLE New in version 5.6.
8.5.2 Sample Site Using the HTML Legend

http://www2.dmsolutions.ca/msapps/itasca_legend/demo_init.html This demo is based on the MapServer Itasca demo and contains several variations of HTML Legends, some of which are listed below: HTML Legend 1 - displays classes only, similar to the traditional legends:
[leg_class_html opt_flag=15] <img src=[leg_icon]> [leg_class_name]<br> [/leg_class_html]
HTML Legend 2 - displays layer titles with HREF links and classes:
[leg_layer_html order_metadata=WMS_ORDER visibility_flag=15] <a href="[leg_layer_name]">[metadata name=WMS_TITLE]</a><BR> [/leg_layer_html] [leg_class_html visibility_flag=15] <img src=[leg_icon]> [leg_class_name]<br> [/leg_class_html]
HTML Legend 3 - displays layers by group, with checkboxes to turn layers on/off:
388
[leg_group_html] <tr><td colspan=2><b>[leg_group_name]</b></td></tr> [/leg_group_html] [leg_layer_html order_metadata=WMS_ORDER opt_flag=15] <tr> <td><input type=checkbox name=layer value=[leg_layer_name] [if name=layer_status value=1]CHECKED[/if]> [if name=layer_type value=4] <img src=[leg_icon width=22 height=18]> [/if] [if name=layer_type oper=neq value=4]<img src=[leg_icon]>[/if] </td> <td> <a href="[leg_layer_name]">[metadata name=WMS_TITLE]</a> </td> </tr> [/leg_layer_html]
8.6 HTML Imagemaps

Author David Fawcett Contact david.fawcett at gmail.com Last Updated 2008-10-08 Contents HTML Imagemaps Introduction Maple Layer Denition Templates Request URL Additional Notes More Information
8.6.1 Introduction
The shpxy method of creating imagemaps uses MapServer query functionality to build a html imagemap. Just like a regular MapServer query, you send a query request and MapServer uses the templates to build a block of html that it sends back to the browser. The rst example shows you how to build an imagemap based on a point layer. An example template for a polygon layer is also included. Components MapServer maple query template le query header template query footer template
8.6. HTML Imagemaps
389
8.6.2 Maple Layer Denition

Here is a simple maple for our example
MAP NAME "myMapFile STATUS ON SIZE 200 200 EXTENT 178784 4804000 772653 5483346 UNITS METERS STATUS ON SHAPEPATH "/web/maps/data" IMAGECOLOR 255 255 255 WEB IMAGEPATH "/web/maps/tmp/" IMAGEURL "/maps/tmp/" END QUERYMAP STATUS ON STYLE NORMAL END LAYER NAME "sites" STATUS DEFAULT TYPE point DATA aqiAreas TEMPLATE "bodytemplate.html" HEADER "imapheader.html" FOOTER "imapfooter.html" END END
You can see that we have a maple with one point layer, and that it contains references to three query templates.
8.6.3 Templates
In MapServer, the query header and footers get processed only once. The main query template, bodytemplate.html in this example, gets processed once for each record in the record set returned by the query. Point Layers Here is the query header, imapheader.html. It creates the opening tag for your html imagemap.
<map id="mymap" name="mymap">
Here is the query template, bodytemplate.html. It creates the body of the html imagemap.
<area shape="circle" coords="[shpxy precision=0 proj=image yf=",7" xf=","]" href="http://my.url/mypag
This template is used to create circular imagemap elements for a point layer. NAME is a eldname in the data source, the value for NAME for each individual record gets substituted as the template is processed. The href species the URL link if the element is clicked. Title and alt will display the value when an element is moused over.
390
The resulting html element looks like

<area shape="circle" coords="80,103,7" href="http://my.url/mypage.cfm?region=Northern" >
The key part here is

coords="[shpxy precision=0 proj=image xf="," yf=",7"]"
This is where MapServer will substitute the image coordinates for that query record. With Precision=0, the coordinates will be integers. You also see shpxy template formatting options xf and yf. xf=, tells MapServer to place a comma after the x coordinate. yf=,7 after the y coordinate. This is done to specify a radius of 7 pixels for the circle. More options can be found in the Template Reference. The query footer template simply adds the closing tag for the html imagemap
</map>
Polygon Layers Here is a query template for a polygon layer
<area shape="poly" coords="[shpxy precision=0 proj=image]" href="http://my.url/mypage.cfm?ID=[SITE_ID
8.6.4 Request URL

To get the imagemap, you need to send a GET or POST request to MapServer with several URL variables dened. The below URL tells MapServer where the maple is located, what layer we are querying, and that we are using nquery mode to return multiple results.
http://myurl/cgi-bin/mapserv?map=/web/maps/demoimap.map&qlayer=sites&mode=nquery&searchmap=true
8.6.5 Additional Notes

If you use separate map les to generate your imagemap and your map image, make sure that the EXTENT and SIZE specied in both maples are identical. If they are not, your features will not align properly.
8.6.6 More Information

Steve Limes SHPXY Example
8.7 OGR Output

Author Frank Warmerdam Contact warmerdam at pobox.com Last Updated 2011-11-15
8.7. OGR Output
391
Table of Contents OGR Output Introduction OUTPUTFORMAT Declarations LAYER Metadata MAP / WEB Metadata Geometry Types Supported Attribute Field Denitions Return Packaging Test Suite Example
8.7.1 Introduction
OGR output support was added to MapServer 6.0. It provides an output driver to produce feature style output suitable as a return result from WMS GetFeatureInfo or WFS GetFeature requests. OGR feature output depends on MapServer being built against the GDAL/OGR library. The OGR output driver should be enabled in MapServer 6.0 or newer when INPUT=OGR appears in the version string.
8.7.2 OUTPUTFORMAT Declarations

Details of OGR output formats allowed are controlled by an OUTPUTFORMAT declaration. The declarations dene the OGR format driver to be used, creation options specic to that driver, and more general instructions to MapServer on how to package multi-le results and whether to try and build the result on disk or in memory. Examples:
OUTPUTFORMAT NAME "CSV" DRIVER "OGR/CSV" MIMETYPE "text/csv" FORMATOPTION "LCO:GEOMETRY=AS_WKT" FORMATOPTION "STORAGE=memory" FORMATOPTION "FORM=simple" FORMATOPTION "FILENAME=result.csv" END OUTPUTFORMAT NAME "OGRGML" DRIVER "OGR/GML" FORMATOPTION "STORAGE=filesystem" FORMATOPTION "FORM=multipart" FORMATOPTION "FILENAME=result.gml" END OUTPUTFORMAT NAME "SHAPEZIP" DRIVER "OGR/ESRI Shapefile" FORMATOPTION "STORAGE=memory" FORMATOPTION "FORM=zip" FORMATOPTION "FILENAME=result.zip" END
392
The OGR format driver to be used is determined by the name appearing after OGR/ in the DRIVER argument. This name should match one of the formats listed as supported for the -f argument to ogr2ogr in the ogr2ogr usage message. The IMAGEMODE for OGR output is FEATURE, but this is implicit and does not need to be explicitly stated for OGR output driver declarations. The OGR renderer will support the following FORMATOPTION declarations: DSCO:* Anything prexed by DSCO: is used as a dataset creation option with the OGR driver. See the OGR web page for the particular format driver to see layer creation options available. LCO:* Anything prexed by LCO: is used as a layer creation option. See the OGR web page for the particular format driver to see layer creation options available.w FORM=simple/zip/multipart Indicates whether the result should be a simple single le (single), a mime multipart attachment (multipart) or a zip le (zip). zip is the default. STORAGE=memory/lesystem/stream Indicates where the datasource should be stored while being written. le is the default. If memory then it will be created in /vsimem/ - but this is only suitable for drivers supporting VSI*L which we cant easily determine automatically. If lesystem, then a directory for temporary les (specied using WEB TEMPPATH or MS_TEMPPATH) will be used for writing and reading back the le(s) to stream to the client. If stream then the datasource will be created with a name /vsistdout as an attempt to write directly to stdout. Only a few OGR drivers will work properly in this mode (ie. CSV, perhaps kml, gml). FILENAME=name Provides a name for the datasource created, default is result.dat.
8.7.3 LAYER Metadata

The OGR output driver utilizes several items from the LAYER level METADATA object. Some of these were originally intended for GML output or are primarily intended to support WFS. wfs_getfeature_formatlist (Optional) A comma delimited list of formats supported for WFS GetFeature responses. The OUTPUTFORMAT NAME values should be listed.
"wfs_getfeature_formatlist" "OGRGML,SHAPEZIP,CSV"
gml_include_items (Optional) A comma delimited list of items to include, or keyword all. You can enable full exposure by using the keyword all.
"gml_include_items" "all"
You can specify a list of attributes (elds) for partial exposure, such as:
"gml_include_items" "Name,ID"
The new default behaviour is to expose no attributes at all. gml_include_items (Optional) A comma delimited list of items to include, or keyword all. As of MapServer 4.6, you can control how many attributes (elds) you expose for your data layer with this metadata. The previous behaviour was simply to expose all attributes all of the time. You can enable full exposure by using the keyword all, such as:
8.7. OGR Output
393
The new default behaviour is to expose no attributes at all. gml_[item name]_alias (Optional) An alias for an attributes name. The resulting le will refer to this attribute by the alias. Here is an example:
"gml_province_alias" "prov"
gml_[item name]_type (Optional) Species ger|Real|Character|Date|Boolean.
the
type
of
the
attribute.
Valid
values
are
Inte-
gml_[item name]_width (Optional) Species the width of the indicated eld for formats where this is signicant, such as Shapeles. gml_[item name]_precision (Optional) Species the precision of the indicated eld for formats where this is significant, such as Shapeles. Precision is the number of decimal places, and is only needed for Real elds. gml_types (Optional) If this eld is auto then some input feature drivers (ie. OGR, and native shapeles) will automatically populate the type, width and precision metadata for the layer based on the source le.
"gml_types" "auto"
ows/wfs_geomtype (Optional) Set the geometry type of OGR layers created from this MapServer LAYER. One of Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection, Geometry, or None. Most are fairly obvious, but Geometry can be used to represent a mix of geometry types, and None is sometimes suitable for layers without geometry. Note that layers which are a mix of polygon and multipolygon would normally have to be described as Geometry.
"ows_geomtype" "Polygon"
8.7.4 MAP / WEB Metadata

wms_feature_info_mime_type In order for WMS GetFeatureInfo to allow selection of OGR output formats, the mime type associated with the OUTPUTFORMAT must be listed in this metadata item.
"wms_feature_info_mime_type" "text/csv"
8.7.5 Geometry Types Supported

In MapServer we have POINT, LINE and POLYGON layers which also allow for features with multiple points, lines or polygons. However, in the OGC Simple Feature geometry model used by OGR a point and multipoint layer are quite distinct. Likewise for a LineString and MultiLineString and Polygon an MultiPolygon layer type. To work around the mismatches between the MapServer and OGR geometry models, there is a mechanism to specify the geometry type to be used when exporting through OGR. This is the wfs/ows_geomtype metadata item on the layer. It may be one of one of Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection, Geometry, or None. If this item is not specied, then Point, LineString or Polygon will be used depending on the TYPE of the LAYER. In cases of mixed geometry types (ie. polygons and multipolygons) the geometry type should be set to Geometry which means any geometry type.
"ows_geomtype" "Geometry"
394
8.7.6 Attribute Field Denitions

For OGR output it is highly desirable to be able to create the output elds with the appropriate datatype, width and precision to reect the source feature denition. It is possible to set the gml_[item]_type, gml_[item]_width and gml_[item]_precision metadata on the layer to provide detailed eld denitions:
METADATA "gml_ID_type" "gml_ID_width" "gml_AREA_type" "gml_AREA_width" "gml_AREA_precision" "gml_NAME_type" "gml_NAME_width" ... "Integer" "8" "Real" "15" "6" "Character" "64"
However, doing this manually is tedious and error prone. For that reason some feature sources (at least OGR, Shapeles, POSTGIS and ORACLESPATIAL) support a mechanism to automatically populate this information from the source datastore. To accomplish this specify:
"gml_types" "auto"
If no effort is made to set type, width and precision information for attribute elds, they will all be treated as variable length character elds when writing through OGR.
8.7.7 Return Packaging

One of the challenges returning generalized feature formats is that many such formats consists of multiple les which must be returned in the result. There are three approaches taken to this based on the FORM FORMATOPTION in the OUTPUTFORMAT declaration. simple In this case a single result is returned. This is suitable for format drivers that produce a single le. The return result will have the mimetype listed in the OUTPUTFORMAT declaration. Note that if the OGR driver actually returns multiple les, only the primary one (the one with a name matching the lename passed into the OGR CreateDataSource call) will be returned. The return result will have a suggested lename based on the FILENAME FORMATOPTION. multipart In this case all the les produced are returned as a multipart mime result. In this case the MIMETYPE of the OUTPUTFORMAT is ignored. All component les are returned with a mime type of application/binary and the whole package is multipart/mixed. zip In this case all the les produced are bundled into one .zip le and this zip le is returned with a mimetype of application/zip. The OUTPUTFORMAT MIMETYPE is ignored. One caveat with zip results is that this option is only available if the GDAL/OGR version is 1.8 or newer (or a 1.8 development later than approximately Oct 15, 2010). Earlier versions of GDAL/OGR lacked the zipping capability needed.
8.7.8 Test Suite Example

The MSAutoTest test suite contains a test case for use of OGR Output from WFS. The maple is at: http://svn.osgeo.org/mapserver/trunk/msautotest/wxs/wfs_ogr.map
8.7. OGR Output
395
The comments at the start of the le have a variety of sample requests that can be run against the map, as long as [MAPFILE] is replaced with the maple name. They requests should be run against mapserv sitting in the msautotest/wxs directory.
8.8 PDF Output

Author Yewondwossen Assefa Contact yassefa at dmsolutions.ca Revision $Revision: 12056 $ Date $Date: 2011-08-14 15:13:13 -0700 (Sun, 14 Aug 2011) $ Last Updated 2006/01/12 Table of Contents PDF Output Introduction What is currently supported and not supported Implementing PDF Output PHP/MapScript and PDF Output
8.8.1 Introduction
PDF output support was added to MapServer 3.7. Previous versions of MapServer had support for pdf output using a utility program (shp2pdf) to output a pdf le given a MapServer maple. The difference in this new version is that the output to PDF can now be directly specied in the maple using the IMAGETYPE or the OUTPUTFORMAT parameters in the maple. Additionally, raster layers are now supported for pdf output. Note: From version 6.0, PDF output is supported through Cairo. This is not reected in the current documentation.
8.8.2 What is currently supported and not supported

1. Vector Layers Layer Point: supported Layer Line: supported Layer Polygon: supported Layer Circle : not supported Layer Annotation: supported Note: Note: Dashed lines are supported with PDFlib version 6 or greater. Note: Polygons lled with symbols are not supported. 2. Raster Layers Raster layers are supported. Note that at this point all raster layers are transformed to jpeg format before being written to the PDF le.
396
3. WMS Layers Not yet supported 4. Surround components Legend, scalebar are not supported. 5. Fonts Standard PostScript fonts are supported. For use of other fonts (such as truetype), see the pdib documentation for use of UPR description les (some notes on it are here).
8.8.3 Implementing PDF Output

Note that the following instructions were developed for MapServer 3.7 and pdib 4.0.3, but the general steps should be similar for recent versions of both. Build the PDF Library In order to have access to the PDF support in MapServer, you should download and build the PDF library from http://www.pdib.com/products/pdib/. Please follow the instructions on the PDFLib site to build on your specic platforms. Here are some quick notes on how to build on windows: download and extract the source code from http://www.pdib.com/products/pdib/ open the project PDFlib.dsw in MS Visual C++ build the project pdib_dll after a sucessful build, you should have a pdib.lib and pdblib.dll under the pdib directory copy the pdib.dll under your system directory (ex : c:/winnt/system32) the pdib.lib will be used while building mapserver with the PDF support Build MapServer with PDF support Windows platform Edit the makele.vc and uncomment the following lines (make sure that the paths are adapted to your installation):
PDF_LIB=../pdflib-4.0.3/pdflib/pdflib.lib PDF_INC=-I../pdflib-4.0.3/pdflib PDF=-DUSE_PDF
See the Windows Compilation document for general MapServer compile instructions. Unix platforms Add with-pdf to your congure command line before compiling. See the Unix Compilation document for general MapServer compile instructions.
8.8. PDF Output
397
Maple denition The IMAGETYPE parameter in the Maple should be set to pdf in order to output to PDF:
NAME pdf-test STATUS ON ... IMAGETYPE pdf .. WEB ... END LAYER ... END END
You can also specify the output using the OUTPUTFORMAT tag (this tag was introduced in mapserver 3.7) :
OUTPUTFORMAT NAME pdf MIMETYPE "application/x-pdf" DRIVER pdf FORMATOPTION "OUTPUT_TYPE=RASTER" ##not mandatory END
If the OUTPUT_TYPE=RASTER all the layers will be rendered as rasters. Note that when WMS layers are included in the maple, this option should be set since there is a problem with transparency and wms layers. See the OUTPUTFORMAT object in the Maple reference for parameter explanations. Testing The easiest way to test your pdf output maple is with the MapServer shp2img utility. Windows users can nd this utility in MS4W, as well as FWTools. You simply pass a maple to the executable and a name for the output pdf, and a pdf le is generated:
shp2img -m gmap_pdf.map -o test.pdf
Possible Errors
PDFlib I/O error: Resource configuration file pdflib.upr not found
This is related to fonts. If you remove the LABEL object from your maple you will see this error go away. The pdf error is described here. Basically, until this issue is xed, if you want to use a font other than the included standard PostScript fonts in pdf output (such as truetype fonts), consult the PDFlib documentation.
8.8.4 PHP/MapScript and PDF Output

MapServer can render to PDF directly, another option is to render to a PNG and insert that into a PDF document. This is not the only way to create a PDF document of course. You will need to have support for PDFLib compiled into your PHP install.
398
This example shows the key parts of the process, you will need to furnish parts of the script yourself (depending on your app) and repeat the process for each map element that you want to include. Refer to the PHP/MapScript Reference wherever necessary. How does it work? In brief, we will pass parameters required to render a map to a PHP script that will: create a PDF document render a PNG view at a suitably higher resolution insert the PNG buffer it and send it to the user Create the PDF document Here is an example similiar to the one given on the PHP website to create a new PDF document:
$my_pdf = pdf_new(); ...
Get this stage and section 4.5 working before you try inserting MapServer elements. Render PNG views at a suitable resolution Work back from the assumption that you will need no more than 300 dpi on your page for your map to look presentable. For an A4 map, I am using 150 dpi for an 8 x 8 main map, which is 1200 x 1200 pixels.
$map->set(width,1200); $map->set(height,1200);
Of course, our map will not be very useful unless it is zoomed in to the extent our user requested, and the layers they selected are switched on. Maintain arrays in your application that record:
- The current extent (say $ext[]) - Layer status (say $layer[])
Open your map le and pass these back through to set the map le into the state the user is expecting, something like:
$map->setextent($ext[0], $ext[1], $ext[2], $ext[3]); while($layer[]) { $layer=$map->getLayer($n); if($layer[$n]==1) { $layer->set(status,1); } else { $layer->set(status,0); } }
Now you will need to save a rendered view to a PNG le.

$img = $map->draw(); $url = $img->saveWebImage(MS_PNG, 0, 0, 0);
Use the same method for all your map elements, such as drawReferenceMap?(), drawScaleBar?() and drawLegend(). 8.8. PDF Output 399
Insert the PNG elements into your PDF document This is really easy, use the pdf_open_image_le() function to import the map elements into your PDF document:
$element = pdf_open_image_file($my_pdf, "png", "$webroot/$url"); pdf_place_image($my_pdf, $element, $xpos, $ypos); pdf_close_image($my_pdf, $element);
Repeat as needed for any map elements you created. Buffer the PDF and send it to the user Assuming we have been creating the document $my_pdf, when we are done, we merely buffer it and send it to the user using echo():
<?php .... pdf_close($my_pdf); $data = pdf_get_buffer($my_pdf); header(Content-type: application/pdf); header(Content-disposition: inline; filename=my_pdf.pdf); header(Content-length: . strlen($data) ); echo $data; ?>
Gotcha: remember that you cannot send headers if you have at any stage outputed text to the browser. Additional stuff to try Rendering everything as PNG can look ugly, so I step through the key and extract labels so I can render them using PDFs text functions. This can be done for other map element, such as map titles, layer descriptions, or anything else that can be read from the maple.
8.9 SVG
Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Revision $Revision: 12056 $ Date $Date: 2011-08-14 15:13:13 -0700 (Sun, 14 Aug 2011) $ Last Updated 2005/12/13
400
Table of Contents SVG Introduction Feature Types and SVG Support Status Testing your SVG Output goSVG
8.9.1 Introduction
SVG (or Scalable Vector Graphics) is a standardized XML language for describing 2D graphics via vector graphics, text and raster graphics. As of version 4.5, MapServer can output SVG v1.1 maps. The following documentation is based on the World Wide Web Consortiums (W3C) Scalable Vector Graphics (SVG) 1.1 Specication. This document assumes that you are already familiar with certain aspects of MapServer: MapServer application development and setting up map les. Note: From version 6.0, SVG output is supported through Cairo. This is not reected in the current documentation. Links to SVG-Related Information SVG 1.1 specication SVG Discussion Paper G-XML Project Page SVG Tiny Prole MapFile Reference Doc
8.9.2 Feature Types and SVG Support Status

Annotation Layers Annotation layers are supported (see the Text Features section below for details). Circle Layers Circle layers are not yet supported. Line Layers The following items describe how line layers are handled by MapServer for SVG output: Lines are converted to SVG polyline elements. The STYLE objects WIDTH parameter is used for SYMBOL 0 for line thickness. The STYLE objects SIZE parameter is used for other symbols for line thickness. All lines are drawn without symbols - only line thickness changes.
8.9. SVG
401
If a style uses a symbol and this symbol has a dashed style, it will be transformed into an SVG stroke-dasharray element. Point Layers The following items describe how point layers are handled by MapServer for SVG output: VECTOR, ELLIPSE, and TRUETYPE symbols are supported. PIXMAP symbols are not currently supported. Labels attached with the symbols are supported (see the Text Features section below for details). Polygon Layers The following items describe how polygon layers are handled by MapServer for SVG output: Polygons are converted to SVG polygon elements. The STYLEs COLOR is used for the ll. The STYLEs OUTLINECOLOR is used for the stroke. SVG patterns are not currently supported. Raster Layers The following items describe how raster layers are handled by MapServer for SVG output: Temporary image is created through the GD library, and GD functions are used to draw the layer. You must have at least PNG or JPEG support compiled in MapServer. You must have the WEB objects IMAGEPATH and IMAGEURL set properly in your maple. Text Features The following items describe how text features are handled by MapServer for SVG output: Text is converted to SVG text element. Only TRUETYPE fonts are supported. Supports labels with ENCODING (output as UTF-8 hexadecimal values). The FONT name used in MapServer is parsed to form the SVG font-family, font-style, and font-weight. WMS Layers WMS layers are not yet supported. Setting up a Maple for SVG Output You must have valid IMAGEPATH and IMAGEURL parameters set in the WEB object of the maple. To be able to output a valid SVG le, the user needs to dene an OUTPUTFORMAT object in the map le and set the IMAGETYPE parameter to svg. Here is an example:
402
MAP ... IMAGETYPE svg ... OUTPUTFORMAT NAME svg MIMETYPE "image/svg+xml" DRIVER svg FORMATOPTION "COMPRESSED_OUTPUT=TRUE" FORMATOPTION "FULL_RESOLUTION=TRUE" END ... WEB IMAGEPATH "/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" END ... LAYER ... END END
Note: If FORMATOPTION COMPRESSED_OUTPUT=TRUE is set MapServer will produce a compressed SVG le (svgz). By default this option is FALSE. Note that to be able to create compressed output, MapServer must be built with the compile ag USE_ZLIB. If FORMATOPTION FULL_RESOLUTION=TRUE is set MapServer will not eliminate duplicate points and collinear lines when outputting SVG. By default this option is set to FALSE.
8.9.3 Testing your SVG Output

The easiest way to test your SVG maple is to use MapServer CGI. For example, you might enter the following URL in a browser:
http://127.0.0.1/cgi-bin/mapserv.exe?map=my/path/to/my-svg.map&mode=map&layers=layer1 layer2
You can also use PHP/MapScript to test your SVG maple. Your php le might look like the following:
<?php dl("php_mapscript_45.dll"); $oMap = ms_newmapObj("my/path/to/my-svg.map"); $img = $oMap->draw(); header("Content-type: image/svg+xml"); $url = $img->saveImage(""); ?>
An SVG le should be created in your IMAGEPATH directory. If you open the SVG le in a text editor you can see that it is an XML le. Below is a sample SVG le of a point layer with labels:
8.9. SVG
403
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-flat.dtd <svg version="1.1" width="400" height="300" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://ww
 <ellipse cx="252" cy="130" rx="3" ry="3" fill="#000000" /> <ellipse cx="37" cy="227" rx="3" ry="3" fill="#000000" /> <ellipse cx="127" cy="239" rx="3" ry="3" fill="#000000" /> <ellipse cx="255" cy="282" rx="3" ry="3" fill="#000000" /> <polygon fill="#000000" stroke-width="1" points=" 267,263 270,263 271,260 272,263 275,263 273,265 <ellipse cx="288" cy="247" rx="3" ry="3" fill="#000000" /> <ellipse cx="313" cy="243" rx="3" ry="3" fill="#000000" /> <ellipse cx="328" cy="233" rx="3" ry="3" fill="#000000" /> <ellipse cx="331" cy="245" rx="3" ry="3" fill="#000000" /> <ellipse cx="366" cy="196" rx="3" ry="3" fill="#000000" /> <ellipse cx="161" cy="246" rx="3" ry="3" fill="#000000" /> <ellipse cx="92" cy="208" rx="3" ry="3" fill="#000000" /> <ellipse cx="40" cy="125" rx="3" ry="3" fill="#000000" /> <ellipse cx="108" cy="146" rx="3" ry="3" fill="#000000" /> <text x="40" y="143" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="43" y="121" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="34" y="205" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="164" y="258" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="316" y="190" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="334" y="258" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="249" y="230" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="241" y="242" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="223" y="260" font-family="fritqat-italic" font-size="8pt" fill="#ff0000" stroke="#ffffff" <text x="210" y="279" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="82" y="234" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="40" y="223" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="214" y="125" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke </svg>
You can now view the SVG le in a supported browser (see the ofcial list of SVG implementations for possible SVG viewers). The Adobe Viewer plugin is very popular.
8.9.4 goSVG
goSVG is now supported as a vector output format in MapServer 4.5 (and later). Denition This denition of goSVG was obtained from here. goSVG is short for G-XML over SVG and g-contents over SVG. This is a subset for mobiles specied within the G-XML (a Japanese Spatial Information Format which is an XML based protocol with the ability to describe, communicate and exchange Spatial Information and Electric Maps), and is a Spatial Information Exchanging format that determines the method to expand spatial information and connect to the backend system(G-XML standard mark format). goSVG is an expanded SVG Tiny prole (a Mobile prole of SVG 1.1. suited for cellular phones) that adds functions that are useful for Spatial Information Services (SVG Map Service). Support for Specic goSVG Elements Name space extension: supported 404 Chapter 8. Output Generation
Content Area Denition (bounding box): supported Geographic Coordinate System: supported Map Request Protocol: supported Setting up a Maple for goSVG Output
Requirements
A valid MapServer Maple. Valid IMAGEPATH and IMAGEURL parameters set in the WEB object of the maple. A PROJECTION object dened beneath the MAP object, using an EPSG code. For example:
MAP ... WEB IMAGEPATH "/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" END ... PROJECTION "init=epsg:42304" END ... LAYER ... END END
Setting the OUTPUTFORMAT

To be able to output a valid goSVG le, you must dene an OUTPUTFORMAT object in the maple and set the IMAGETYPE to svg. Here is an example:
MAP ... IMAGETYPE svg ... OUTPUTFORMAT NAME svg MIMETYPE "image/svg+xml" DRIVER svg FORMATOPTION "GOSVG=TRUE" FORMATOPTION "GOSVG_ZoomInTH=20" FORMATOPTION "GOSVG_ZoomOutTH=40" FORMATOPTION "GOSVG_ScrollTH=60" END ... WEB IMAGEPATH "/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" END ... PROJECTION
8.9. SVG
405
"init=epsg:42304" END ... LAYER ... END END
Specic FORMATOPTIONs Related to goSVG

GOSVG should be set to TRUE. The default is false. GOSVG_ZoomInTH controls the zoomin threshold when outputting the Map Request Protocol. If it is not dened the default value is set to 70. GOSVG_ZoomOutTH controls the zoomout threshold when outputting the Map R equest Protocol. If it is not dened the default value is set to 100. GOSVG_ScrollTH controls the scrolling threshold when outputting the Map Request Protocol. If it is not dened the default value is set to 10. Testing your goSVG Output Refer to the section Testing your SVG Output to generate and test your goSVG output. goSVG can be read by regular SVG viewers (they will just ignore the goSVG headers). Sample goSVG File Produced by MapServer Below is a sample goSVG le of a point layer with labels:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-flat.dtd <svg version="1.1" width="400" height="300" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://ww <title>DEMO</title> <metadata> <rdf:RDF xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:crs = "http://www.ogc.org/crs" xmlns:svg="http://wwww.w3.org/2000/svg"> <rdf:Description> <crs:CoordinateReferenceSystem svg:transform="matrix(0.000066,0.000000,0.000000,-0.000066,171.243002, rdf:resource="http://www.opengis.net/gml/srs/epsg.xml#42304"/> </rdf:Description> </rdf:RDF> <au:lbs protocol="maprequest"> <au:zoomin th="20" xlink:href="."/> <au:zoomout th="40" xlink:href="."/> <au:scroll th="60" xlink:href="."/> </au:lbs> </metadata>  <ellipse cx="252" cy="130" rx="3" ry="3" fill="#000000" /> <ellipse cx="37" cy="227" rx="3" ry="3" fill="#000000" /> <ellipse cx="127" cy="239" rx="3" ry="3" fill="#000000" /> <ellipse cx="255" cy="282" rx="3" ry="3" fill="#000000" /> <polygon fill="#000000" stroke-width="1" points=" 267,263 270,263 271,260 272,263 275,263 273,265
406
<ellipse cx="288" cy="247" rx="3" ry="3" fill="#000000" /> <ellipse cx="313" cy="243" rx="3" ry="3" fill="#000000" /> <ellipse cx="328" cy="233" rx="3" ry="3" fill="#000000" /> <ellipse cx="331" cy="245" rx="3" ry="3" fill="#000000" /> <ellipse cx="366" cy="196" rx="3" ry="3" fill="#000000" /> <ellipse cx="161" cy="246" rx="3" ry="3" fill="#000000" /> <ellipse cx="92" cy="208" rx="3" ry="3" fill="#000000" /> <ellipse cx="40" cy="125" rx="3" ry="3" fill="#000000" /> <ellipse cx="108" cy="146" rx="3" ry="3" fill="#000000" /> <text x="40" y="143" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="43" y="121" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="34" y="205" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="164" y="258" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="316" y="190" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="334" y="258" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="249" y="230" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="241" y="242" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="223" y="260" font-family="fritqat-italic" font-size="8pt" fill="#ff0000" stroke="#ffffff" <text x="210" y="279" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke <text x="82" y="234" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="40" y="223" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke<text x="214" y="125" font-family="fritqat" font-size="8pt" fill="#000000" stroke="#ffffff" stroke </svg>
8.10 Tile Mode

Author Paul Ramsey Contact pramsey at cleverelephant.ca Revision $Revision: 9817 $ Date $Date: 2010-02-20 11:35:53 -0800 (Sat, 20 Feb 2010) $ Last Updated 2008/04/30 Table of Contents Tile Mode Introduction Conguration Utilization
8.10.1 Introduction
MapServer can feed tile-based map clients directly using the CGI tile mode. Tile-based map clients work by dividing the map of the world up into a discrete number of zoom levels, each partitioned into a number of identically sized tiles. Instead of accessing a map by requesting a bounding box, a tile client builds a map by accessing individual tiles.
8.10. Tile Mode
407
8.10.2 Conguration
Tile requests are handled by the mapserv CGI program. In order to return tiles in the correct projection, MapServer must be built with the use-proj option turned on. You can check if your version of mapserv has projection support by running it with the -v option and looking for SUPPORTS=PROJ. Example 1. On Unix:
$ ./mapserv -v MapServer version 4.6.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE DEBUG=MSDEBUG
Example 2. On Windows:
C:\apache\cgi-bin> mapserv -v MapServer version 4.6.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE DEBUG=MSDEBUG
MapServer requires that each LAYER in your map le have a valid PROJECTION block to support reprojection. Because the tile mode uses reprojection, you will have to ensure each LAYER has a valid PROJECTION block. Conguration checklist: MapServer compiled with PROJ support Map le with a PROJECTION dened for every LAYER As of MapServer 6.0, there are two extra parameters available for conguring tile mode. tile_map_edge_buffer renders the tile into a buffered rendering frame, then clips out the nal tile. This will reduce edge effects when large symbols or wide lines are drawn. Recommended value: the size of the largest symbol or line width in your map le. tile_metatile_level renders the into into a xed metatile, then clips out the nal tile. This will reduce label repetition, at the expense of much higher rendering cost. Recommended value: 1 if you are doing labelling of large features in your layer. 0 otherwise. If you use both tile_map_edge_buffer and tile_metatile_level at the same time, the buffer will be applied at the meta-tile level.
8.10.3 Utilization
The MapServer tile support adds three new directives to the CGI interface: mode=tile tells the server to generate tiles based on the other tile mode parameters tilemode=gmap tells the server use the Google Maps tile scheme for the tiles tile=x+y+z tells the server what tile you want to retrieve, using the Google Maps tile addressing system tilemode=ve tells the server use the Virtual Earth tile naming scheme for the tiles tile=10231 tells the server what tile you want to retrieve, using the Virtual Earth tile addressing system
408
About Spherical Mercator Spherical Mercator (also called web mercator by some) is a world projection. All the major tile-based map interfaces (Google Maps, Microsoft Virtual Earth, Yahoo Maps, OpenLayers) use the spherical mercator system to address tiles. A spherical mercator set of tiles has the following properties: The map has been reprojected to mercator using a spherical mercator algorithm There is one tile in the top zoom level, zoom level zero Each successive zoom level (z) has 2^z tiles along each axis Tiles are 256x256 in size Google Maps and Virtual Earth both use spherical mercator as their underlying tile projection, but use different formats to address the individual tiles. Google Maps uses an x, y, zoom format. The zoom indicates which level to pull tiles from, and the x and y indicate while tile in that zoom level to pull. Virtual Earth uses a single string to address each tile. The top zoom level in Virtual Earth has four tiles (equivalent to Googles zoom level 1). The top left tile in the Virtual Earth top zoom level is addessed as 0, top right as 1, bottom left as 2 and bottom right as 3. Each tile the next level is addressed by rst referencing the top level tile that contains it, then its address relative to that tile. So the top left tile in the second zoom level is 00 and the bottom right one is 33. See the Virtual Earth site for more details: http://msdn.microsoft.com/en-us/library/bb545006.aspx Using Google Maps The Google Maps API includes support for using alternative tile sets as overlays, or as alternate base maps. Here is an example of an GTileLayerOverlay
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <title>Google/MapServer Tile Example</title> <script src="http://maps.google.com/maps?file=api&v=2&key=[YOUR KEY HERE]" type="text/javascript"></script> <script type="text/javascript"> function load() { if (GBrowserIsCompatible()) { var urlTemplate = http://localhost/cgi-bin/mapserv?; urlTemplate += map=/var/map.map&; urlTemplate += layers=layer1 layer2&; urlTemplate += mode=tile&; urlTemplate += tilemode=gmap&; urlTemplate += tile={X}+{Y}+{Z}; var myLayer = new GTileLayer(null,0,18,{ tileUrlTemplate:urlTemplate, isPng:true, opacity:1.0 }); var map = new GMap2(document.getElementById("map")); map.addControl(new GLargeMapControl()); map.addControl(new GMapTypeControl()); map.setCenter(new GLatLng(35.35, -80.55), 15); map.addOverlay(new GTileLayerOverlay(myLayer));
8.10. Tile Mode
409
29 30 31 32 33 34 35 36 37
} } </script> </head> <body onload="load()" onunload="GUnload()"> <div id="map" style="width: 500px; height: 500px"></div> </body> </html>
Note the format of the tileUrlTemplate: a valid URL, with {X}, {Y} and {Z} substitution tokens that Google Maps will replace with the tile coordinates and zoom level on the y to retrieve tiles from your server. You can also use a MapServer tile layer as an alternate base map:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <title>Google/MapServer Tile Example</title> <script src="http://maps.google.com/maps?file=api&v=2&key=[YOUR KEY HERE]" type="text/javascript"></script> <script type="text/javascript"> function load() { if (GBrowserIsCompatible()) { var urlTemplate = http://localhost/cgi-bin/mapserv?; urlTemplate += map=/var/map.map&; urlTemplate += layers=layer1 layer2&; urlTemplate += mode=tile&; urlTemplate += tilemode=gmap&; urlTemplate += tile={X}+{Y}+{Z}; var myLayer = new GTileLayer(null,0,18,{ tileUrlTemplate:urlTemplate, isPng:true, opacity:0.3 }); var map = new GMap2(document.getElementById("map")); map.addControl(new GLargeMapControl()); map.addControl(new GMapTypeControl()); map.setCenter(new GLatLng(35.35, -80.55), 15); var myMapType = new GMapType([myLayer], new GMercatorProjection(18), MapServer); map.addMapType(myMapType); } } </script> </head> <body onload="load()" onunload="GUnload()"> <div id="map" style="width: 500px; height: 500px"></div> </body> </html>
The only change from the previous example is that we dont create a GTileLayerOverlay, we create a GMapType, and use addMapType(), instead of addOverlay().
410
Using Virtual Earth The Virtual Earth API also includes support for using alternative tile sets as overlays, or as alternate base maps. Here is an example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-stri <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <title>Virtual Earth Example</title> <script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.1">< <script type="text/javascript"> var map = null; function OnLoadMap () { map = new VEMap("myMap"); map.LoadMap(); var url url url url url url = "http://localhost/cgi-bin/mapserv?"; += "map=/var/map.map&"; += "mode=tile&"; += "layers=layer1 layer2&"; += "tilemode=ve&"; += "tile=%4";
var tileSourceSpec = new VETileSourceSpecification( "myLayer", url ); tileSourceSpec.Opacity = 0.3; map.AddTileLayer(tileSourceSpec, true); } </script> </head> <body onload="OnLoadMap();"> <div id="myMap" style="position:relative; width:500px; height:500px;"></div> </body> </html>
8.11 Template-Driven Output

Author Chris Hodgson Contact chodgson at refractions.net Last Updated 2011-04-13 Table of Contents Template-Driven Output Introduction OUTPUTFORMAT Declarations Template Substitution Tags Examples
8.11. Template-Driven Output
411
8.11.1 Introduction
RFC 36 added support for dening template-driven OUTPUTFORMATs for use with feature queries, including WMS GetFeatureInfo and WFS GetFeature. This allows for custom text-oriented output such as GeoJSON, KML, or XML. The templates are essentially the same as with the standard MapServer query Templating, however there are some additional tags to allow for template denition in a single le instead of the standard header/template/footer. Note: There are other, simpler, ways to output some of these formats using MapServer. However, template-driven output provides maximal exibility and customization of the output, at the cost of additional complexity and conguration.
8.11.2 OUTPUTFORMAT Declarations

Details of template-driven output formats are controlled by an OUTPUTFORMAT declaration. The declarations dene the template le to be used, as well as other standard OUTPUTFORMAT options. Examples:
OUTPUTFORMAT NAME "kayml" DRIVER "TEMPLATE" MIMETYPE "application/vnd.google-earth.kml+xml" FORMATOPTION "FILE=myTemplate.kml" FORMATOPTION "ATTACHMENT=queryResults.kml" END OUTPUTFORMAT NAME "geojson" DRIVER "TEMPLATE" FORMATOPTION "FILE=myTemplate.json" END OUTPUTFORMAT NAME "customxml" DRIVER "TEMPLATE" FORMATOPTION "FILE=myTemplate.xml" END
The template le to be used is determined by the FILE=... FORMATOPTION. The template lename is relative to the maples path. As is standard with MapServer template les, the le must containt the magic string mapserver template in the rst line of the le, usually within a comment, but this line is not output to the client. Note that both the MIMETYPE and FORMATOPTION ATTACHMENT=... parameters are very useful for controlling how a web browser handles the output le.
8.11.3 Template Substitution Tags

These tags only work in query result templates, and their purpose is primarily to simplify the templating to a single le for custom ouput formats. [include src=otherTemplate.txt] Includes another template le; the path to the template le is relative to the maple path. Attributes: src: The le to be included.
412
[resultset layer=layername]...[/resultset] Denes the location of the results for a given layer. Attributes: layer: The layer to be used nodata: (optional) A string to return if no results are returned. [feature]...[/feature] Denes the loop around the features returned for a given layer. Attributes: limit: (optional) Species the maximum number of features to output for this layer. trimlast: (optional) Species a string to be trimmed off of the end of the nal feature that is output. This is intended to allow for trailing record delimiters to be removed. See the examples below. [join name=join1]...[/join] denes the loop around the features join from another layer. See Also: Templating
8.11.4 Examples
This example shows how to emulate the old 3-le system using the new system, to compare the usage:
 [include src="templates/header.html"] [resultset layer=lakes] ... old layer HEADER stuff goes here, if a layer has no results this block disappears... [feature] ...repeat this block for each feature in the result set... [join name=join1] ...repeat this block for each joined row... [/join] [/feature] ...old layer FOOTER stuff goes here... [/resultset] [resulset layer=streams] ... old layer HEADER stuff goes here, if a layer has no results this block disappears... [feature] ...repeat this block for each feature in the result set... [/feature] ...old layer FOOTER stuff goes here... [/resultset] [include src="templates/footer.html"]
A specic GML3 example:

 <?xml version="1.0" encoding="ISO-8859-1"?> [resultset layer=mums] <MapServerUserMeetings xmlns="http://localhost/ms_ogc_workshop" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:gml="http://www.opengis.net/gml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://localhost/ms_ogc_workshop ./mums.xsd"> <gml:description>This is a GML document which provides locations of all MapServer User Meeting that have taken place</gml:description>
413
<gml:name>MapServer User Meetings</gml:name> <gml:boundedBy> <gml:Envelope> <gml:coordinates>-93.093055556,44.944444444 -75.7,45.4166667</gml:coordinates> </gml:Envelope> </gml:boundedBy> [feature] <gml:featureMember> <Meeting> <gml:description>[desc]</gml:description> <gml:name>[name]</gml:name> <gml:location> <gml:Point srsName="http://www.opengis.net/gml/srs/epsg.xml#4326"> <gml:pos>[x] [y]</gml:pos> </gml:Point> </gml:location> <year>[year]</year> <venue>[venue]</venue> <website>[url]</website> </Meeting> </gml:featureMember> [/feature] <dateCreated>2007-08-13T17:17:32Z</dateCreated> </MapServerUserMeetings> [resultset]
A GeoJSON example:
// mapserver template [resultset layer=mums] { "type": "FeatureCollection", "features": [ [feature trimlast=","] { "type": "Feature", "id": "[id]", "geometry": { "type": "PointLineString", "coordinates": [ { "type": "Point", "coordinates": [[x], [y]] } ] }, "properties": { "description": "[description]", "venue": "[venue]", "year": "[year]" } }, [/feature] ] } [/resultset]
A more complicated KML example. Note the use of [shpxy] to support multipolygons with holes, and also that a point placemark is included with each feature using [shplabel]: 414 Chapter 8. Output Generation
 <?xml version="1.0" encoding="UTF-8"?> <kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom"> <Document> <Style id="parks_highlight"> <IconStyle> <scale>1.4</scale> <Icon> <href>http://maps.google.com/mapfiles/kml/shapes/parks.png</href> </Icon> <hotSpot x="0.5" y="0" xunits="fraction" yunits="fraction"/> </IconStyle> <LineStyle> <color>ffff5500</color> <width>4.2</width> </LineStyle> <PolyStyle> <color>aaaaaaaa</color> </PolyStyle> <BalloonStyle> <text> <![CDATA[ <p ALIGN="center"><b>$[name]</b></p> $[description] ]]> </text> </BalloonStyle> </Style> <Style id="parks_normal"> <IconStyle> <scale>1.2</scale> <Icon> <href>http://maps.google.com/mapfiles/kml/shapes/parks.png</href> </Icon> <hotSpot x="0.5" y="0" xunits="fraction" yunits="fraction"/> </IconStyle> <LineStyle> <color>ffff5500</color> <width>4.2</width> </LineStyle> <PolyStyle> <color>ff7fff55</color> </PolyStyle> <BalloonStyle> <text> <![CDATA[ <p ALIGN="center"><b>$[name]</b></p> $[description] ]]> </text> </BalloonStyle> </Style> <StyleMap id="parks_map"> <Pair> <key>normal</key>
415
<styleUrl>#parks_normal</styleUrl> </Pair> <Pair> <key>highlight</key> <styleUrl>#parks_highlight</styleUrl> </Pair> </StyleMap> [resultset layer=parks] <Folder> <name>Parks</name> [feature trimlast="," limit=1] <Placemark> <name>[NAME]</name> <Snippet/> <description> <![CDATA[ <p>Year Established: [YEAR_ESTABLISHED]</p> <p>Area: [AREA_KILOMETERS_SQUARED] sq km</p> ]]> </description> <styleUrl>#parks_map</styleUrl> <ExtendedData> <Data name="Year Established">[YEAR_ESTABLISHED]</Data> <Data name="Area">[AREA_KILOMETERS_SQUARED]</Data> </ExtendedData> <MultiGeometry> <Point> <coordinates>[shplabel proj=epsg:4326 precision=10],0</coordinates> </Point> [shpxy ph="<Polygon><tessellate>1</tessellate>" pf="</Polygon>" xf="," xh=" " yh=" " yf=",0 " orh="<outerBoundaryIs><LinearRing><coordinates>" orf="</coordinates></LinearRing></outerBoundaryIs>" irh="<innerBoundaryIs><LinearRing><coordinates>" irf="</coordinates></LinearRing></innerBoundaryIs>" proj=epsg:4326 precision=10] </MultiGeometry> </Placemark> [/feature] </Folder> [/resultset] </Document> </kml>
8.12 Kml Output

Last Updated 2010/11/26 Authors Dvaid Kana (david.kana at gmail.com) Authors Thomas.Bonfort (thomas.bonfort at gmail.com) Authors Yewondwossen Assefa (yassefa at dmsolutions.ca) Authors Michael Smith (michael.smith at usace.army.mil) Version MapServer 6.0
416
Id $
8.12.1 Introduction
This purpose of this docuement is to describethe KML/KMZ output support in MapServer 6.0. The main goal of the KML driver is to generate KML output used mainly by Google Earth application.
8.12.2 General Functionnality

Kml support is provided by using a kml or kmz image type in the map le. Output can then be generated using MapServer cgi (example mode=map) or through a WMS request.
8.12.3 Output format

The default name of the output format is kml or kmz, and this name can be used to set the imagetype parameter in the map le. The format can also be dened in the map le:
OUTPUTFORMAT NAME kml DRIVER "KML" MIMETYPE "application/vnd.google-earth.kml+xml" IMAGEMODE RGB EXTENSION "kml" FORMATOPTION ATTACHMENT=gmap75.kml #name of kml file returned FORMATOPTION "maxfeaturestodraw=100" END OUTPUTFORMAT NAME kmz DRIVER "KMZ" MIMETYPE "application/vnd.google-earth.kmz" IMAGEMODE RGB EXTENSION "kmz" FORMATOPTION ATTACHMENT=gmap75.kmz #name of kmz file returned END
8.12.4 Build
On windows: there is a ag KML in nmake.opt On Linux: with-kml AGG driver is necessary for the kml driver To be able to get kmz support, MapServer needs to be build aginst GDAL 1.8
8.12.5 Limiting the number of features

The number of vector features drawn by default is set to 1000 per layer. To control the number of features, users can set:
8.12. Kml Output
417
layer level metadata that only applies to the layer: maxfeaturestodraw 100 map level metada that applies to all layers: maxfeaturestodraw 100 output format option that applies to all layers: FORMATOPTION maxfeaturestodraw=100
8.12.6 Map
In terms for Kml object, the MapServer KML output will produce a <Document> element to include all the layers that are part of the MapServer map le. Features supported for the Document are: Document element name visibility open address AdressDetails phoneNumber Snippet description AbstractView TimePrimitive styleURL StyleSelector Supported Yes No No No No No No No No No No Yes MapServer equivalence/Notes
Name in the map le Can be supported if needed. Default is 1 Can be supported if needed. Default is 0 Could be supported for example using ows_address if available
Could be supported using ows_contactvoicetelephone is available
Style element will be supported. All different styles from the layers will be stored here and referenced from the folders using a styleUrl.In addition to the Styles related to features, there is a ListStyle element added at the document level. This allows to control the way folders are presented.See Layers section (styleUrl) setting for more details.
Region Metadata ExtendedData
No No No
8.12.7 Layers
Each layer of the MapServer map le will be inside a Kml <Folder> element. Supported Folder elements are:
418
Sup- MapServer equivalence/Notes ported name Yes Name of the layer. If not available the name will be Layer concatenated with the layers index (Layer1) visibility Yes Always set to 1 open No Default is 0 atom:authoratom:linkaddressAddressDetailsphoneNumberSnippet No description No Could be supported using ows_description AbstarctView No TimePrimitive No styleUrl Yes The user can use the kml_folder_display layer or map level metedata to choose a setting. Possible values are check (default), radioFolder, checkOffOnly, checkHideChildren. RegionMetadataExtendedNo Data Each element in the Layer will be inside a Kml <Placemark> element. As described in the Kml reference : A Placemark is a Feature with associated Geometry. In Google Earth, a Placemark appears as a list item in the Places panel. A Placemark with a Point has an icon associated with it that marks a point on the Earth in the 3D viewer. (In the Google Earth 3D viewer, a Point Placemark is the only object you can click or roll over. Other Geometry objects do not have an icon in the 3D viewer. To give the user something to click in the 3D viewer, you would need to create a MultiGeometry object that contains both a Point and the other Geometry object.) For Polygon and Line layers, when a feature is associated with a label, a MultiGeometry element containing a point geometry and the geometry of the feature is created. The point feature will be located in the middle of the polygon or line
<Folder> <name>park</name> <visibility>1</visibility> <styleUrl>#LayerFolder_check</styleUrl> <Placemark> <name>Ellesmere Island National Park Reserve</name> <styleUrl>#style_line_ff787878_w4.0_polygon_ff00ffc8_label_ff0000ff</styleUrl> <MultiGeometry> <Polygon> <outerBoundaryIs> <LinearRing> <coordinates> ... <Point> <coordinates> -70.86810858,82.12291871 </coordinates> </Point> </MultiGeometry> </Placemark> </Folder>
Folder element
Supported Features in the Placemark element are: General notes on layers Labelcache is turned off on each layer Projection block should be set. If not set It will be assumed that the data is in lat/lon projection (a debug message will be sent to the user: Debug Message 1)
8.12. Kml Output
419
Possible to output vector layers as raster using metadata: KML_OUTPUTASRASTER true The user can use the KML_FOLDER_DSIPLAY layer or map level metedata to choose a setting. Possible values are check (default), radioFolder, checkOffOnly, checkHideChildren. The user can use metadata KML/OWS_DESCRIPTION or KML/OWS_INCLUDE_ITEMS to dene the description attached to each feature. If KML/OWS_DESCRIPTION are dened, the <description> tag of the Placemark will be used. If KML/OWS_INCLUDE_ITEMS, the <ExtendedData> tag will be used. The user can use the metadata KML_NAME_ITEM to indicate the eld name to be used a a name tag for each feature. The user can use metadata KML_ALTITUDEMODE to specify how altitude components in the <coordinates> element are interpreted. Possible values are: absolute, relativeToGround, clampToGround. http://code.google.com/apis/kml/documentation/kmlreference.html#altitudemode The user can use metedata KML_EXTRUDE to specify whether to connect the LinearRing to the ground. http://code.google.com/apis/kml/documentation/kmlreference.html#tessellate The user can use metedata KML_TESSELLATE to specify whether to allow the LinearRing to follow the terrain. http://code.google.com/apis/kml/documentation/kmlreference.html#extrude The user can specify an attribute to be used as the elevation value using a layer level metedata: kml_elevation_attribute <Name of attribute>. The value will be used as the z value when the coordinates are written. Point Layers Each layer will be inside a Folder element. Each feature will be represented by a Placemark. The Geometry element for a Point layer would be represented as a Point geometry element in Kml. Supported elements are: Line Layers Each layer will be inside a Folder element. Each feature in the layer would be represented by a Placemark. If a label is attached to the line, the Geometry element would be represented as a MultiGeometry that includes a LineString element and a Point element representing the position of the label. If no label is attached to a feature, the Geometry element will be a LineString. Polygon Layers Each layer will be inside a Folder element. Each feature will be represented by a Placemark. If a label is attached to the polygon, the Geometry element would be represented as a MultiGeometry that includes a Polygon element and a Point element representing the position of the label. Annotation Layers Not supported.
420
Raster Layers Each layer will be inside a Folder element. A GroundOverlay feature is created for the layer, that includes an href link to the raster image generated and LatLongBox for the extents (map extents). The href is generated using the imagepath and imageurl settings in the map le.
8.12.8 Styling
As described in Section 4, all different styles from the layers will be stored at the Document level and referenced from the folders using a styleUrl. Point Layers Point layers will be styled using the IconStyle styling element of kml. An image representing the symbol will be created and referenced from the IconStyle object. If a label is attached to the point, a LabelStyle element will also be used. The LabelStyle will have the color parameter set.
<Style id="style_label_ff0000ff_symbol_star_13.0_ff000000"> <IconStyle> <Icon> <href>>http://localhost/ms_tmp/4beab862_19bc_0.png</href> </Icon> </IconStyle> <LabelStyle> <color>ff0000ff</color> </LabelStyle> </Style>
Line Layers Line layers will be styled using the LineStyle styling element of kml. Color and width parameters of the LineStyle will be used. If a label is attached to the layer, a LabelStyle element will also be used. Polygon Layers Polygon layers will be styled using the PolyStyle styling element of kml. Color parameter of the PolyStyle will be used. If an outline is dened in the map le, an addition LineStyle will be used. If a label is attached to the layer, a LabelStyle element will also be used.
8.12.9 Attributes
As described in section on Layers, two ways of dening the description: kml/ows_description kml/ows_include_items
8.12. Kml Output
421
8.12.10 Coordinate system

The map level projection should be set to epsg:4326. If not set, the driver will automatically set it. Layers are expected to have projection block if their projection is different from epsg:4326.
8.12.11 Warning and Error Messages

When the projection of the map le is not set or is different from a a lat/lon projection, the driver automatically sets the projection to espg:4326. If the map is is debug mode, the following message is sent: KmlRenderer::checkProjection: Maple projection set to epsg:4326 If imagepath and imageurl are not set in the web object, the following message is sent in debug mode: KmlRenderer::startNewLayer: imagepath and imageurl should be set in the web object
422
CHAPTER 9
OGC Support and Conguration
Interoperability is increasingly becoming a focus point for organizations that distribute and share data over the Internet. The Open Geospatial Consortium (OGC) focuses on the development of publicly available geospatial web standards. MapServer supports numerous OGC standards, allowing users to publish and consume data and services in an application neutral implementation manner.
9.1 Mapserver OGC Specication support

Web Map Service (OGC:WMS) Server: 1.0.0, 1.0.7, 1.1.0, 1.1.1, 1.3.0 Client: 1.0.0, 1.0.7, 1.1.0, 1.1.1 Web Feature Service (OGC:WFS) 1.0.0, 1.1.0 Web Coverage Service (OGC:WCS) 1.0.0, 1.1.0, 2.0.0 Geography Markup Language (OGC:GML) 2.1.2, 3.1.0 Level 0 Prole Web Map Context Documents (OGC:WMC) 1.0.0, 1.1.0 Styled Layer Descriptor (OGC:SLD) 1.0.0 Filter Encoding Specication (OGC:FES) 1.0.0 Sensor Observation Service (OGC:SOS) 1.0.0 Observations and Measurements (OGC:OM) 1.0.0 SWE Common (OGC:SWE) 1.0.1 OWS Common (OGC:OWS) 1.0.0, 1.1.0
9.2 WMS Server

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Last Updated 2011-10-06
423
Table of Contents WMS Server Introduction Setting Up a WMS Server Using MapServer Changing the Online Resource URL WMS 1.3.0 Support Reference Section FAQ / Common Problems
9.2.1 Introduction
A WMS (or Web Map Server) allows for use of data from several different servers, and enables for the creation of a network of Map Servers from which clients can build customized maps. The following documentation is based on the Open Geospatial Consortiums (OGC) Web Map Server Interfaces Implementation Specication v1.1.1. MapServer v3.5 or more recent is required to implement WMS features. At the time this document was written, MapServer supports the following WMS versions: 1.0.0, 1.0.7, 1.1.0 (a.k.a. 1.0.8), 1.1.1 and 1.3.0 This document assumes that you are already familiar with certain aspects of MapServer: MapServer application development and setting up .map les. Familiarity with the WMS spec would be an asset. A link to the WMS specication document is included in the WMS-Related Information section below. Links to WMS-Related Information MapServer WMS Client Howto WMS 1.1.1 specication WMS 1.3.0 specication Open Geospatial Consortium (OGC) home page WMS-Dev mailing list and archive WMS Cookbook MapServer OGC Web Services Workshop package MapServer Styled Layer Descriptor (SLD) Howto MapServer WMS Time Support Howto How does a WMS Work WMS servers interact with their clients via the HTTP protocol. In most cases, a WMS server is a CGI program. This is also the case with MapServer. The WMS specication denes a number of request types, and for each of them a set of query parameters and associated behaviors. A WMS-compliant server MUST be able to handle at least the following 2 types of WMS requests: 1. GetCapabilities: return an XML document with metadata of the Web Map Servers information 2. GetMap: return an image of a map according to the users needs.
424
Chapter 9. OGC Support and Conguration
And support for the following types is optional: 1. GetFeatureInfo: return info about feature(s) at a query (mouse click) location. MapServer supports 3 types of responses to this request: text/plain output with attribute info. text/html output using MapServer query templates (see Templating) specied in the CLASS TEMPLATE parameter (the lename has to have an .html extension). The MIME type returned by the Class templates defaults to text/html and can be controlled using the metadata wms_feature_info_mime_type. application/vnd.ogc.gml, GML.1 or GML for GML features. 2. DescribeLayer: return an XML description of one or more map layers. To execute this: for vector layers: to have a valid return the user needs to setup wfs_onlineresource (or ows_onlineresource) metadata either at the map level or at the layer level (the layer level metadata is the one which is used if both are dened) for raster layers: the metadata is wcs_onlineresource with the same logic as above. 3. GetLegendGraphic: returns a legend image (icon) for the requested layer, with label(s). More information on this request can be found in the GetLegendGraphic section later in this doc. With respect to MapServer specically, it is the mapserv CGI program that knows how to handle WMS requests. So setting up a WMS server with MapServer involves installing the mapserv CGI program and a setting up a maple with appropriate metadata in it. This is covered in the rest of this document.
9.2.2 Setting Up a WMS Server Using MapServer

Install the Required Software WMS requests are handled by the mapserv CGI program. Not all versions of the mapserv program do include WMS support (it is included by default when you compile together with the PROJ library), so the rst step is to check that your mapserv executable includes WMS support. One way to verify this is to use the -v command-line switch and look for SUPPORTS=WMS_SERVER. (Unix users should refer to the Compiling on Unix document for any compiling instructions, and Windows users might want to use MS4W, which comes ready with WMS/WFS support) Example 1. On Unix:
$ ./mapserv -v MapServer version 4.6.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE DEBUG=MSDEBUG
C:\apache\cgi-bin> mapserv -v MapServer version 4.6.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE DEBUG=MSDEBUG
9.2. WMS Server
425
Setup a Maple For Your WMS Each instance of WMS server that you setup needs to have its own maple. It is just a regular MapServer maple in which some parameters and some metadata entries are mandatory. Most of the metadata is required in order to produce a valid GetCapabilites output. Here is the list of parameters and metadata items that usually optional with MapServer, but are required (or strongly recommended) for a WMS conguration: At the MAP level: Map NAME Map PROJECTION Map Metadata (in the WEB Object): wms_title wms_onlineresource wms_srs (unless PROJECTION object is dened using init=epsg:...) wms_enable_request And for each LAYER: Layer NAME Layer PROJECTION Layer METADATA wms_title wms_srs (optional since the layers inherit the maps SRS value) Layer STATUS Layers set to STATUS DEFAULT will always be sent to the client. Layers set to STATUS ON or STATUS OFF can be requested by the client. Layer TEMPLATE (required for GetFeatureInfo requests - see Templating) Lets go through each of these parameters in more detail: Map Name and wms_title: WMS Capabilities requires a Name and a Title tag for every layer. The Maps NAME and wms_title metadata will be used to set the root layers name and title in the GetCapabilities XML output. The root layer in the WMS context corresponds to the whole maple. Layer Name and wms_title metadata: Every individual layer needs its own unique name and title. Layer names are also used in GetMap and GetFeatureInfo requests to refer to layers that should be included in the map output and in the query. Layer names must start with a letter when setting up a WMS server (layer names should not start with a digit or have spaces in them). Map PROJECTION and wms_srs metadata: WMS servers have to advertise the projection in which they are able to serve data using EPSG projection codes (see http://www.epsg.org/ for more background on EPSG codes). Recent versions of the PROJ4 library come with a table of EPSG initialization codes and allow users to dene a projection like this:
426
(Note that epsg has to be in lowercase when used in the PROJ4 init directive.) If the MAP PROJECTION block is provided in the format init=epsg:xxxx then MapServer will also use this information to generate a <BoundingBox> tag for the top-level layer in the WMS capabilities document. BoundingBox is a mandatory element of WMS capabilities for WMS 1.3.0 (for WMS 1.1.0 it is optional, but it is good practice to allow MapServer to include it when possible). The above is sufcient for MapServer to recognize the EPSG code and include it in SRS tags in the capabilities output (wms_srs metadata is not required in this case). However, it is often impossible to nd an EPSG code to match the projection of your data. In those cases, the wms_srs metadata is used to list one or more EPSG codes that the data can be served in, and the PROJECTION object contains the real PROJ4 denition of the datas projection. Here is an example of a server whose data is in an Lambert Conformal Conic projection (42304). Its capabilities output will advertize EPSG:4269 and EPSG:4326 projections (lat/lon), but the PROJECTION object is set to the real projection that the data is in:
NAME "DEMO" ... WEB ... METADATA "wms_title" "wms_onlineresource" "wms_srs" END END PROJECTION "init=epsg:42304" END ... END
"WMS Demo Server" "http://my.host.com/cgi-bin/mapserv?map=wms.map&" "EPSG:4269 EPSG:4326"
In addition to EPSG:xxxx projections, a WMS server can advertize projections in the AUTO:xxxx namespace. AUTO projections 42001 to 42005 are internally supported by MapServer. However, AUTO projections are useful only with smart WMS clients, since the client needs to dene the projection parameters in the WMS requests to the server. For more information see Annex E of the WMS 1.1.1 specication and section 6.5.5.2 of the same document. See also the FAQ on AUTO projections at the end of this document. Layer PROJECTION and wms_srs metadata: By default layers inherit the SRS of their parent layer (the maps PROJECTION in the MapServer case). For this reason it is not necessary (but still strongly recommended) to provide PROJECTION and wms_srs for every layer. If a layer PROJECTION is not provided then the top-level map projecion will be assumed. Layer PROJECTION and wms_srs metadata are dened exactly the same way as the maps PROJECTION and wms_srs metadata. For vector layers, if a PROJECTION block is provided in the format init=epsg:xxxx then MapServer will also use this information to generate a <BoundingBox> tag for this layer in the WMS capabilities document. BoundingBox is a mandatory element of WMS capabilities for WMS 1.3.0 (for WMS 1.1.0 it is optional, but it is good practice to allow MapServer to include it when possible). wms_onlineresource metadata:
9.2. WMS Server
427
The wms_onlineresource metadata is set in the maps web object metadata and species the URL that should be used to access your server. This is required for the GetCapabilities output. If wms_onlineresource is not provided then MapServer will try to provide a default one using the script name and hostname, but you shouldnt count on that too much. It is strongly recommended that you provide the wms_onlineresource metadata. See section 6.2.2 of the WMS 1.1.1 specication for the whole story about the online resource URL. Basically, what you need is a complete HTTP URL including the http:// prex, hostname, script name, potentially a map= parameter, and and terminated by ? or &. Here is a valid online resource URL:
http://my.host.com/cgi-bin/mapserv?map=mywms.map&
By creating a wrapper script on the server it is possible to hide the map= parameter from the URL and then your servers online resource URL could be something like:
http://my.host.com/cgi-bin/mywms?
This is covered in more detail in the section More About the Online Resource URL below. wms_enable_request metadata: Specify which requests to enable. If not specied, no requests will be enabled! See the explanation below. Conguring for GetFeatureInfo Requests: You must set the layer TEMPLATE parameter for the layer to be queryable by GetFeatureInfo requests (see Templating). For requests of type text/html you should also set the layer HEADER and FOOTER parameters. As of MapServer 4.6 you must set the gml_* metadata for the layer attributes to be served (see the Layer Object metadata in the Reference Section later in this document). To include geometry, gml_geometries and gml_[name]_type has to be specied. Here are working examples of GetFeatureInfo requests: text/plain / text/html / gml (for gml, your browser might ask you to save the le, if so save it locally as a .gml le and view it in a text editor) Test Your WMS Server
Validate the Capabilities Metadata

OK, now that weve got a maple, we have to check the XML capabilities returned by our server to make sure nothing is missing. Using a web browser, access your servers online resource URL to which you add the parameters SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities to the end, e.g.
http://my.host.com/cgi-bin/mapserv?map=mywms.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities
Here is a working GetCapabilities request (note that the SERVICE parameter is required for all GetCapabilities requests): http://demo.mapserver.org/cgi-bin/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities This should return a document of MIME type application/vnd.ogc.wms_xml, so your browser is likely going to prompt you to save the le. Save it and open it in a text editor (Emacs, Notepad, etc.), and you will see the returned XML from the WMS server. If you get an error message in the XML output then take necessary actions. Common problems and solutions are listed in the FAQ at the end of this document.
428
If everything went well, you should have a complete XML capabilities document. Search it for the word WARNING... MapServer inserts XML comments starting with <!WARNING: in the XML output if it detects missing maple parameters or metadata items. If you notice any warning in your XML output then you have to x all of them before you can register your server with a WMS client, otherwise things are likely not going to work. Note that when a request happens, it is passed through WMS, WFS, and WCS in MapServer (in that order) until one of the services respond to it.
Test With a GetMap Request

OK, now that we know that our server can produce a valid XML GetCapabilities response we should test the GetMap request. MapServer only checks for a few of the required GetMap parameters, so both of the minimum MapServer parameters and a valid GetMap request will be explained below. The following is a list of the required GetMap parameters according to the WMS spec: VERSION=version: Request version REQUEST=GetMap: Request name LAYERS=layer_list: Comma-separated list of one or more map layers. Optional if SLD parameter is present. STYLES=style_list: Comma-separated list of one rendering style per requested layer. Optional if SLD parameter is present. Set STYLES= with an empty value to use default style(s). Named styles are also supported and are controlled by CLASS GROUP names in the maple. SRS=namespace:identier: Spatial Reference System. BBOX=minx,miny,maxx,maxy: Bounding box corners (lower left, upper right) in SRS units. WIDTH=output_width: Width in pixels of map picture. HEIGHT=output_height: Height in pixels of map picture. FORMAT=output_format: Output format of map. Note: WMS Servers only advertise supported formats that are part of the gd / gdal libraries. A valid example would therefore be:
http://my.host.com/cgi-bin/mapserv?map=mywms.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=prov
Here is a working valid request.
Test with a Real Client

If you have access to a WMS client, then register your new servers online resource with it and you should be off and running. If you dont have your own WMS client installed already, here are a few pointers: MapServer itself can be used as a WMS client, see the MapServer WMS Client Howto. Quantum GIS is a full GIS package which includes WMS client support. (recommended) OpenJUMP is a desktop GIS package which includes WMS client support. uDig is a desktop package that allows users to add WMS layers. Deegree provides a WMS client.
9.2. WMS Server
429
owsview Viewer Client Generator is an online application that allows users to add WMS layers. This list is not exhaustive, there are several Open Source or proprietary packages that offer WMS support and could be used to interact with your new MapServer WMS server instance. GetLegendGraphic Request This request returns a legend image (icon) for the specied layer. The request will draw an icon and a label for all classes dened on the layer. If the requested layername is a GROUP-name, all included layers will be returned in the legend-icon.
Requirements
The following are required in the WMS server maple to enable this request: a LEGEND object. a CLASS object for each layer. a NAME in the CLASS object. the STATUS of each LAYER must be set to ON.
Parameters
The following are valid parameters for this request: LAYER - (Required) Name of the WMS layer to return the legend image of. Note that this is the <Name> parameter of the Layer in the GetCapabilities. FORMAT - (Required) Format of the legend image (e.g. image/png). WIDTH - (Optional) Width of the legend image. Note that the Width parameter is only used when the Rule parameter is also used in the request. HEIGHT - (Optional) Height of the legend image. Note that the Height parameter is only used when the Rule parameter is also used in the request. SLD - (Optional) The URL to the SLD. Applies the SLD on the layer and the legend is drawn after the SLD is applied (using the classes speced by the SLD). Note here that you need to put a <Name>class1</Name> inside the Rule element so that a class name is created from the SLD and therefore a correct legend image. SLD_BODY - (Optional) The body (code) of the SLD, instead of specifying a URL (as in the SLD parameter). SLD_VERSION - (Optional) The SLD version. SCALE - (Optional) Specify a scale so that only layers that fall into that scale will have a legend. STYLE - (Optional) The style. RULE - (Optional) Specify the name of the CLASS to generate the legend image for (as opposed to generating an icon and label for ALL classes for the layer). Note: All rules that are used to draw the legend in normal CGI mode apply here. See the CGI Reference doc if necessary. The CLASS objects KEYIMAGE parameter can also be used to specify a legend image for a CLASS. See the MapFile Reference doc if necessary. Example Request An example request might look like:
430
http://127.0.0.1/cgi-bin/mapserv.exe?SERVICE=WMS&VERSION=1.1.1&layer=park& REQUEST=getlegendgraphic&FORMAT=image/png
9.2.3 Changing the Online Resource URL

As mentioned in the section Setup a Maple / wms_onlineresource metadata above, the following Online Resource URL is perfectly valid for a MapServer WMS according to section 6.2.2 or the WMS 1.1.1 specication:
http://my.host.com/cgi-bin/mapserv?map=mywms.map&
However, some people will argue that the above URL contains mandatory vendor-specic parameters and that this is illegal. First we would like to point that map=... is not considered a vendor-specic parameter in this case since it is part of the Online Resource URL which is dened as an opaque string terminated by ? or & (See WMS 1.1.1 section 6.2.2). But anyway, even if its valid, the above URL is still ugly. And you might want to use a nicer URL for your WMS Online Resource URL. Here are some suggestions: Apache ReWrite rules (using Apache mod_rewrite) One can use Apaches mod_rewrite to avoid specifying the map, or any other default parameter in the mapserver URL. This task consist of three steps, specifying the mod_rewrite module to be loaded, enabling the mod_rewrite module for the selected directories and at last to write a .htaccess le to do the rewriting. In the httpd.conf le, the mod_rewrite module is per default disabled. To enable it, remove the opening # in the line
#LoadModule rewrite_module modules/mod_rewrite.so
To be able to use the module, it must be enabled, using the directive AllowOverride. This can be done per server or per directory. If you just have one server, add an AllowOverride All line in the httpd.conf le (see the Apache documentation to be sure about the security implications of this). Per directory is the easiest way to make it work on virtual hosts. Within the <virtualHost> section of the httpd.conf insert:
<Directory myhtdocsdir> AllowOverride All </Directory>
Where myhtdocsdir is the directory dened as documentroot for the actual virtual server. When the directives are set to load and enable the mod_rewrite module, Apache has to be restarted. In a web-accessible directory make a .htaccess le like the following:
RewriteEngine on RewriteRule wmsmap?(.*) /cgi-bin/mapserv?map=/home/www/mapserverstuff/mymapfile.map&$1
The rewriteRule says: given a webpage starting with wmsmap, pick out the query parameters, make a new page request starting with /cgi-bin/mapserv?map=(. . . )? and add on whatever was the query parameters in the original page request. e.g, the URL wmsmap?mode=map will be rewritten as /cgi-bin/mapserv?map=/home/www/mapserverstuff/mymaple.map&mode=map If just the URL wmsmap is given (without any parameters) a page not found error will show up as that does not match the wmsmap? expression.
9.2. WMS Server
431
Apache environment variables - MS_MAPFILE A default maple can be specied using the MS_MAPFILE environment variable:
Alias /mywms /usr/lib/cgi-bin/mapserver <Location /mywms> SetHandler cgi-script Options ExecCGI SetEnv MS_MAPFILE /path/to/mymapfile.map </Location>
Apache SetEnvIf Another option is to use the setenvif feature of Apache: use symbolic links that all point to a same mapserv binary, and then for each symbolic link test the URL, and set the MAP environment accordingly. For Windows and Apache users the steps are as follows (this requires Apache 1.3 or newer): Copy mapserv.exe to a new name for your WMS, such as mywms.exe. In httpd.conf, add:
SetEnvIf Request_URI "/cgi-bin/mywms" MS_MAPFILE=/path/to/mymap.map
ASP script (IIS - Microsoft Windows) On IIS servers (Windows), you can use the following ASP script: Note: The script below, while functional, is intended only as an example of using ASP to lter MapServer requests. Using ASP in a production WMS server will likely require additional ASP especially in the area of error handling and setting timeouts.*
<% Server.ScriptTimeout = 360 Select Case Request.ServerVariables("REQUEST_METHOD") Case "GET" strRequest = Request.QueryString Case "POST" strRequest = Request.Form End Select
strURL = "http://myserver/cgi-bin/mapserv.exe?map=C:\Inetpub\wwwroot\workshop\itasca.map&" & strReq Dim objHTTP Set objHTTP = Server.CreateObject("MSXML2.ServerXMLHTTP") objHTTP.open "GET", strURL, false objHTTP.send "" Response.ContentType = objHTTP.getResponseHeader("content-type") Response.BinaryWrite objHTTP.responseBody Set objHTTP = Nothing %>
Mapscript wrapper Some OGC services (WFS, SOS) support both GET and POST requests. Here, you can use a minimal MapScript WxS wrapper. Heres a Python example: 432 Chapter 9. OGC Support and Conguration
#!/usr/bin/python import mapscript req = mapscript.OWSRequest() req.loadParams() map = mapscript.mapObj(/path/to/config.map) map.OWSDispatch(req)
Wrapper script (Unix) On Unix servers, you can setup a wrapper shell script that sets the MS_MAPFILE environment variable and then passes control to the mapserv executable... that results on a cleaner OnlineResource URL:
#! /bin/sh MS_MAPFILE=/path/to/demo.map export MS_MAPFILE /path/to/mapserv
Note: Using a /bin/sh wrapper script causes an overhead on system resources as two processes have to be spawned instead of one, and is therefore not recommended.
9.2.4 WMS 1.3.0 Support

MapServer 5.4 adds support for WMS 1.3.0. Although the general mechanism in Mapserver to support this new specication are the same, there are some notable upgrades. Major features related to the WMS 1.3.0 support Support WMS 1.3.0 basic operations: GetCapabilities, GetMap and GetFeatureInfo. Implement the Styled Layer Descriptor prole of the Web Map Service Implementation Specication. This specication extends the WMS 1.3.0 and allows to advertise styling capabilities (Styled Layer Descriptor (SLD) support). It also denes two addition operations GetLegendGraphic and DescribeLayer Implement the Symbology Encoding Implementation Specication, which is the new version of the SLD. Read support was added for Point, Line, Polygon, Raster symbolizers Upgrade the generation of SLD to version 1.1.0 (SLD generated through through the GetStyles operation or through MapScript) Coordinate Systems and Axis Orientation The most notable changes introduced in WMS 1.3.0 are the: the axis changes the introduction of new coordinate reference systems the use of CRS parameter (instead of SRS) The axis order in previous versions of the WMS specications was to always use easting (x or lon ) and northing (y or lat). WMS 1.3.0 species that, depending on the particular CRS, the x axis may or may not be oriented West-to-East, and the y axis may or may not be oriented South-to-North. The WMS portrayal operation shall account for axis order. This affects some of the EPSG codes that were commonly used such as ESPG:4326. MapServer 5.x makes sure that
9.2. WMS Server
433
coordinates passed to the server (as part of the GetMap BBOX parameter) as well as those advertised in the capabilities document reect the inverse axe orders for EPSG codes between 4000 and 5000. MapServer 6.0 and up holds a list of epsg codes with inverted axis order. It is currently based on EPSG database version 7.6. It is also possible to dene the axis order at build time for a specic ESPG code(see #3582). This allows for example to use the normal axis order for some of EPSG codes between 4000 and 5000. In addition, the WMS 1.3.0 denes a series of new coordinate system. These are the once that are currently supported in MapServer: CRS:84 (WGS 84 longitude-latitude) CRS:83 (NAD83 longitude-latitude) CRS:27 (NAD27 longitude-latitude) AUTO2:420001 (WGS 84 / Auto UTM ) AUTO2:420002 (WGS 84 / Auto Tr. Mercator) AUTO2:420003 (WGS 84 / Auto Orthographic) AUTO2:420004 (WGS 84 / Auto Equirectangular) AUTO2:420005 (WGS 84 / Auto Mollweide) Example of requests Users can use the CRS:84 coordinate system and order the BBOX coordinates as long/lat: ...&CRS=CRS:84&BBOX=-180.0,-90.0,180.0,90.0&... (example request) -
Users can also use the ESPG:4326 coordinates and use the axis odering of lat/long: - ...&EPSG:4326&BBOX=-90.0,180.0,90,180.0&... (example request) Other notable changes valid values for the EXCEPTIONS parameter in a GetMap request are XML, INIMAGE, BLANK valid value for the EXCEPTIONS parameter in a GetFeatureInfo request is XML LayerLimit is introduced, allowing a server to advertise and limit the number of layers a client is allowed to include in a GetMap request Some Missing features WMS 1.3.0 Post request should be an XML document containing the different operations and parameters. SLD documents containing elements form the Feature Encoding 1.1 specication could potentially use ESPG projections with some lters. It is not yet clear nor implemented if the axis ordering should be taken into account in these specic cases. OCG compliance tests As of version 5.4, MapServer passes all the basic and query tests of the OGC CITE test suite for WMS 1.3.0.
434
9.2.5 Reference Section

The following metadata are available in the setup of the maple: (Note that each of the metadata below can also be referred to as ows_* instead of wms_*. MapServer tries the wms_* metadata rst, and if not found it tries the corresponding ows_* name. Using this reduces the amount of duplication in maples that support multiple OGC interfaces since ows_* metadata can be used almost everywhere for common metadata items shared by multiple OGC interfaces.) Web Object Metadata ows_http_max_age Description: (Optional) an integer (in seconds) to specify how long a given map response should be considered new. Setting this directive allows for aware WMS clients to use this resulting HTTP header value as a means to optimize (and minimize) requests to a WMS Server. More info is available at http://www.mnot.net/cache_docs/#CACHE-CONTROL ows_updatesequence Description: (Optional) The updateSequence parameter can be used for maintaining the consistency of a client cache of the contents of a service metadata document. The parameter value can be an integer, a timestamp in [ISO 8601:2000] format, or any other number or string. ows_sld_enabled Description: (Optional) A value (true or false) which, when set to false, will ignore SLD and SLD_BODY parameters in order to disable remote styling of WMS layers. Also, SLD is not advertised in WMS Capabilities as a result ows_schemas_location Description: (Optional) (Note the name ows_schemas_location and not wms_... this is because all OGC Web Services (OWS) use the same metadata) Root of the web tree where the family of OGC WMS XMLSchema les are located. This must be a valid URL where the actual .xsd les are located if you want your WMS output to validate in a validating XML parser. Default is http://schemas.opengis.net. See http://ogc.dmsolutions.ca for an example of a valid schema tree. wms_abstract WMS TAG Name: Abstract (WMS1.1.1, sect. 7.1.4.2) Description: (Optional) A blurb of text providing more information about the WMS server. wms_accessconstraints WMS TAG Name: AccessConstraints (WMS1.1.1, sect. 7.1.4.2) Description: (Optional) Access constraints information. Use the reserved word none if there are no access constraints. wms_addresstype, wms_address, wms_city, wms_stateorprovince, wms_postcode, wms_country WMS TAG Name: ContactAddress and family (WMS1.1.1, sect. 7.1.4.2) Description: Optional contact address information. If provided then all six metadata items are required. wms_attribution_logourl_format Description: (Optional) The MIME type of the logo image. (e.g. image/png). Note that the other wms_attribution_logourl_* metadata must also be specied. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec.
9.2. WMS Server
435
wms_attribution_logourl_height Description: (Optional) Height of the logo image in pixels. Note that the other wms_attribution_logourl_* metadata must also be specied. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_logourl_href Description: (Optional) URL of the logo image. Note that the other wms_attribution_logourl_* metadata must also be specied. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_logourl_width Description: (Optional) Width of the logo image in pixels. Note that the other wms_attribution_logourl_* metadata must also be specied. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_onlineresource Description: (Optional) The data providers URL. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_title Description: (Optional) Human-readable string naming the data provider. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_bbox_extended: Description: (Optional) true or false. If true, bounding boxes are reported for all supported SRS / CRS in the capabilities document. If false, only the bounding box of the rst SRS / CRS is reported. Introduced in 6.0. wms_contactelectronicmailaddress WMS TAG Name: ContactElectronicMailAddress (WMS1.1.1, sect. 7.1.4.2) Description: Optional contact Email address. wms_contactfacsimiletelephone WMS TAG Name: ContactFacsimileTelephone (WMS1.1.1, sect. 7.1.4.2) Description: Optional contact facsimile telephone number. wms_contactperson, wms_contactorganization, wms_contactposition WMS TAG Name: ContactInformation, ContactPerson, ContactOrganization, ContactPosition (WMS1.1.1, sect. 7.1.4.2) Description: Optional contact information. If provided then all three metadata items are required. wms_contactvoicetelephone WMS TAG Name: ContactVoiceTelephone (WMS1.1.1, sect. 7.1.4.2) Description: Optional contact voice telephone number. wms_encoding WMS TAG Name: Encoding Description: Optional XML capabilities encoding type. The default is ISO-8859-1.
436
wms_enable_request (or ows_enable_request) Description: Space separated list of requests to enable. The default is none. The following requests can be enabled: GetCapabilities, GetMap, GetFeatureInfo and GetLegendGraphic. A ! in front of a request will disable the request. * enables all requests. Examples: To enable only GetMap and GetFeatureInfo:
"wms_enable_request" "GetMap GetFeatureInfo"
To enable all requests except GetFeatureInfo

"wms_enable_request" "* !GetFeatureInfo"
wms_feature_info_mime_type WMS TAG Name: Feature_info_mime_type Description: Used to specify an additional MIME type that can be used when responding to the GetFeature request. For example if you want to use the layers HTML template as a base for its response, you need to add WMS_FEATURE_INFO_MIME_TYPE text/html. Setting this will have the effect of advertizing text/html as one of the MIME types supported for a GetFeature request. You also need to make sure that the layer points to a valid html template (see Templating). The client can then call the server with INFO_FORMAT=text/html. If not specied, MapServer by default has text/plain and GML implemented. wms_fees WMS TAG Name: Fees (WMS1.1.1, sect. 7.1.4.2) Description: (Optional) Fees information. Use the reserved word none if there are no fees. wms_getcapabilities_version Description: (Optional) Default version to use for GetCapabilities requests that do not have a version parameter. If not set, the latest supported version will be returned. wms_getlegendgraphic_formatlist Description: (Optional) A comma-separated list of valid formats for a WMS GetLegendGraphic request. wms_getmap_formatlist Description: (Optional) A comma-separated list of valid formats for a WMS GetMap request. wms_keywordlist WMS TAG Name: KeywordList (WMS1.1.1, sect. 7.1.4.2) Description: (Optional) A comma-separated list of keywords or keyword phrases to help catalog searching. As of WMS 1.1.0 no controlled vocabulary has been dened. wms_onlineresource WMS TAG Name: OnlineResource (WMS1.1.1, sect. 6.2.2) Description: (Recommended) The URL that will be used to access this WMS server. This value is used in the GetCapabilities response. See Also: sections Setup a Maple / wms_onlineresource metadata and More About the Online Resource URL above.
9.2. WMS Server
437
wms_resx, wms_resy WMS TAG Name: BoundingBox (WMS1.1.1, sect. 6.5.6) Description: (Optional) Used in the BoundingBox tag to provide info about spatial resolution of the data, values are in map projection units. wms_service_onlineresource Description: (Optional) Top-level onlineresource URL. MapServer uses the onlineresource metadata (if provided) in the following order: 1. wms_service_onlineresource 2. ows_service_onlineresource 3. wms_onlineresource (or automatically generated URL, see the onlineresource section of this document) wms_srs WMS TAG Name: SRS (WMS1.1.1, sect. 6.5.5) Description: (Recommended) Contains a list of EPSG projection codes that should be advertized as being available for all layers in this server. The value can contain one or more EPSG:<code> pairs separated by spaces (e.g. EPSG:4269 EPSG:4326) This value should be upper case (EPSG:42304.....not epsg:42304) to avoid problems with case sensitive platforms. See Also: section Setup a Maple / Map PROJECTION and wms_srs metadata above. wms_timeformat Description: The time format to be used when a request is sent. (e.g. wms_timeformat %Y-%m-%d %H, %Y-%m-%d %H:%M). Please see the WMS Time Support Howto for more information. wms_title WMS TAG Name: Title (WMS1.1.1, sect. 7.1.4.1) Description: (Required) A human-readable name for this Layer. wms_rootlayer_title WMS TAG Name: Title (WMS1.1.1, sect. 7.1.4.1) Description: (Optional) Same as wms_title, applied to the root Layer element. If not set, then wms_title will be used. wms_rootlayer_abstract WMS TAG Name: Abstract (WMS1.1.1, sect. 7.1.4.2) Description: (Optional) Same as wms_abstract, applied to the root Layer element. If not set, then wms_abstract will be used. wms_rootlayer_keywordlist WMS TAG Name: KeywordList (WMS1.1.1, sect. 7.1.4.2) Description: (Optional) Same as wms_keywordlist, applied to the root Layer element. If not set, then wms_keywordlist will be used. wms_layerlimit WMS TAG Name: LayerLimit (WMS1.3.0, sect. 7.2.4.3) Description: (Optional) The maximum number of layers a WMS client can specify in a GetMap request. If not set, then no limit is imposed.
438
Layer Object Metadata gml_exclude_items Description: (Optional, applies only to GetFeatureInfo GML requests) A comma delimited list of items to exclude. As of MapServer 4.6, you can control how many attributes (elds) you expose for your data layer with metadata. The previous behaviour was simply to expose all attributes all of the time. The default is to expose no attributes at all. An example excluding a specic eld would be:
"gml_include_items" "all" "gml_exclude_items" "Phonenum"
gml_groups Description: (Optional, applies only to GetFeatureInfo GML requests) A comma delimited list of group names for the layer. gml_[group name]_group Description: (Optional, applies only to GetFeatureInfo GML requests) A comma delimited list of attributes in the group. Here is an example:
"gml_include_items" "all" "gml_groups" "display" "gml_display_group" "Name_e,Name_f"
gml_include_items Description: (Optional, applies only to GetFeatureInfo GML requests) A comma delimited list of items to include, or keyword all. As of MapServer 4.6, you can control how many attributes (elds) you expose for your data layer with this metadata. The previous behaviour was simply to expose all attributes all of the time. You can enable full exposure by using the keyword all, such as:
The new default behaviour is to expose no attributes at all. gml_[item name]_alias Description: (Optional, applies only to GetFeatureInfo GML requests) An alias for an attributes name. The served GML will refer to this attribute by the alias. Here is an example:
gml_[item name]_type Description: (Optional, applies only to GetFeatureInfo GML requests) Species the type of the attribute. Valid values are Integer|Real|Character|Date|Boolean. gml_xml_items Description: (Optional, applies only to GetFeatureInfo GML requests) A comma delimited list of items that should not be XML-encoded. gml_geometries Description: (Optional, applies only to GetFeatureInfo GML requests) Provides a name for geometry elements. The value is specied as a string to be used for geometry element names. By default, GML geometries are not written in GML GetFeatureInfo output, unless gml_geometries and gml_[name]_type are both set. By
9.2. WMS Server
439
default, only the bounding box is written. If gml_geometries is set to none, neither the bounding box nor the geometry are written. gml_[name]_type Description: (Optional, applies only to GetFeatureInfo GML requests) When employing gml_geometries, it is also necessary to specify the geometry type of the layer. This is accomplished by providing a value for gml_[name]_type, where [name] is the string value specied for gml_geometries, and a value which is one of: point multipoint line multiline polygon multipolygon wms_abstract Same as wms_abstract in the Web Object. wms_attribution_logourl_format Description: (Optional) The MIME type of the logo image. (e.g. image/png). Note that the other wms_attribution_logourl_* metadata must also be specied. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_logourl_height Description: (Optional) Height of the logo image in pixels. Note that the other wms_attribution_logourl_* metadata must also be specied. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_logourl_href Description: (Optional) URL of the logo image. Note that the other wms_attribution_logourl_* metadata must also be specied. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_logourl_width Description: (Optional) Width of the logo image in pixels. Note that the other wms_attribution_logourl_* metadata must also be specied. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_onlineresource Description: (Optional) The data providers URL. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec. wms_attribution_title Description: (Optional) Human-readable string naming the data provider. refer to section 7.1.4.5.11 of the WMS 1.1.1 spec.
440
wms_authorityurl_name, wms_authorityurl_href - Description: (Optional) AuthorityURL is used in tandem with Identier values to provide a means of linking identier information back to a web service. The wms_identier_authority should provide a string that matches a declared wms_authorityurl_name. Both wms_authorityurl_name and wms_authorityurl_href must be present for an AuthorityURL tag to be written to the capabilities. - refer to section 7.1.4.5.12 of the WMS 1.1.1 spec. wms_bbox_extended: Description: (Optional) true or false. If true, bounding boxes are reported for all supported SRS / CRS in the capabilities document. If false, only the bounding box of the rst SRS / CRS is reported. Introduced in 6.0. wms_identier_authority, wms_identier_value - Description: (Optional) Identier is used in tandem with AuthorityURL end points to provide a means of linking identier information back to a web service. The wms_identier_authority should provide a string that matches a declared wms_authorityurl_name. Both wms_identier_authority and wms_identier_value must be present for an Identier tag to be written to the capabilities. - refer to section 7.1.4.5.12 of the WMS 1.1.1 spec. wms_dataurl_format Description: (Optional) Non-standardized le format of the metadata. The layer metadata wms_dataurl_href must also be specied. refer to section 7.1.4.5.14 of the WMS 1.1.1 spec. wms_dataurl_href Description: (Optional) The URL to the layers metadata. The layer metadata wms_dataurl_format must also be specied. refer to section 7.1.4.5.14 of the WMS 1.1.1 spec. wms_enable_request (or ows_enable_request) Description: Space separated list of requests to enable. The default is none. The following requests can be enabled: GetCapabilities, GetMap, GetFeatureInfo and GetLegendGraphic. A ! in front of a request will disable the request. * enables all requests. Examples: To enable only GetMap and GetFeatureInfo:
"wms_enable_request" "GetMap GetFeatureInfo"
To enable all requests except GetFeatureInfo

"wms_enable_request" "* !GetFeatureInfo"
wms_extent WMS TAG Name: BoundingBox (WMS1.1.1, sect. 6.5.6) Description: (Optional) Used for the layers BoundingBox tag for cases where it is impossible (or very inefcient) for MapServer to probe the data source to gure its extents. The value for this metadata is minx miny maxx maxy separated by spaces, with the values in the layers projection units. If wms_extent is provided then it has priority and MapServer will NOT try to read the source les extents. For Rasters served through WMS, MapServer can now use the wms_extent metadata parameter to register the image. If a .wld le cannot be found, MapServer will then look for the wms_extent metadata parameter and use the extents of the image and the size of the image for georegistration. wms_getfeatureinfo_formatlist
9.2. WMS Server
441
Description: (Optional) Comma-separted list of formats that sould be valid for a GetFeatureInfo request. If dened, only these formats are advertised through in the Capabilities document. wms_getlegendgraphic_formatlist Description: (Optional) Comma-separted list of image formats that sould be valid for a GetLegendGraphic request. If dened, only these formats are advertised through in the Capabilities document. wms_getmap_formatlist Description: (Optional) Comma-separted list of image formats that sould be valid for a GetMap request. If dened, only these formats are advertised through in the Capabilities document. wms_group_abstract Description: (Optional) A blurb of text providing more information about the group. Only one layer for the group needs to contain wms_group_abstract, MapServer will nd and use the value. The value found for the rst layer in the group is used. So if multiple layers have wms_group_abstract set then only the rst value is used. wms_group_title WMS TAG Name: Group_title (WMS1.1.1, sect. 7.1.4.1) Description: (Optional) A human-readable name for the group that this layer belongs to. Only one layer for the group needs to contain wms_group_title, MapServer will nd and use the value. The value found for the rst layer in the group is used. So if multiple layers have wms_group_title set then only the rst value is used. wms_keywordlist Same as wms_keywordlist in the Web Object . wms_layer_group Description: (Optional) Can be used to assign a layer to a number of hierarchically nested groups. This grouped hierarchy will be expressed in the capabilities. WMS_LAYER_GROUP is different from the GROUP keyword in that it does not publish the name of the group in the capabilities, only the title. As a consequence the groups set with WMS_LAYER_GROUP can not be requested with a GetMap or GetFeatureInfo request (see section 7.1.4.5.2 of the WMS implementation specication version 1.1.1. (OGC 01-068r2)). Another difference is that GROUP does not support nested groups. The purpose of this metadata setting is to enable making a WMS client aware of layer grouping. All group names should be preceded by a forward slash (/). It is not allowed to use both the WMS_LAYER_GROUP setting and the GROUP keyword for a single layer.
LAYER NAME "mylayer" DATA "mylayer" TYPE LINE CLASS STYLE COLOR 100 100 255 END END METADATA "WMS_LAYER_GROUP" "/rootgroup/subgroup" END END
wms_metadataurl_format Description: (Optional) The le format MIME type of the metadata record (e.g. text/plain). The layer metadata wms_metadataurl_type and wms_metadataurl_href must also be specied. 442 Chapter 9. OGC Support and Conguration
refer to section 7.1.4.5.10 of the WMS 1.1.1 spec. wms_metadataurl_href Description: (Optional) The URL to the layers metadata. The layer metadata wms_metadataurl_format and wms_metadataurl_type must also be specied. refer to section 7.1.4.5.10 of the WMS 1.1.1 spec. wms_metadataurl_type Description: (Optional) The standard to which the metadata complies. Currently only two types are valid: TC211 which refers to [ISO 19115], and FGDC which refers to [FGDC-STD-001-1988]. The layer metadata wms_metadataurl_format and wms_metadataurl_href must also be specied. refer to section 7.1.4.5.10 of the WMS 1.1.1 spec. wms_opaque WMS TAG Name: Opaque (WMS1.1.1, sect. 7.1.4.6.3) Description: (Optional) Set this metadata to 1 to indicate that the layer represents an area-lling coverage of space (e.g. a bathymetry and elevation layer). This should be taken by the client as a hint that this layer should be placed at the bottom of the stack of layers. wms_srs Same as wms_srs in the Web Object . wms_style Description: (Optional) The LegendURL style name. Requires the following metadata: wms_style_<styles_name>_width, wms_style_<styles_name>_legendurl_height, wms_style_<styles_name>_legendurl_format, wms_style_<styles_name>_legendurl_href refer to section 7.1.4.5.4 of the WMS 1.1.1 spec. wms_style_<styles_name>_legendurl_height Description: (Optional) The height of the legend image in pixels. Requires the following metadata: wms_style_<styles_name>_width, wms_style, wms_style_<styles_name>_legendurl_format, wms_style_<styles_name>_legendurl_href. refer to section 7.1.4.5.4 of the WMS 1.1.1 spec. wms_style_<styles_name>_legendurl_href Description: (Optional) The URL to the layers legend. Requires the following metadata: wms_style_<styles_name>_width, wms_style_<styles_name>_legendurl_height, wms_style_<styles_name>_legendurl_format, wms_style. refer to section 7.1.4.5.4 of the WMS 1.1.1 spec. wms_style_<styles_name>_legendurl_format Description: (Optional) The le format MIME type of the legend image. Requires the following metadata: wms_style_<styles_name>_width, wms_style_<styles_name>_legendurl_height, wms_style, wms_style_<styles_name>_legendurl_href. refer to section 7.1.4.5.4 of the WMS 1.1.1 spec. wms_style_<styles_name>_legendurl_width Description: (Optional) The width of the legend image in pixels. Requires the following metadata: wms_style_<styles_name>_format, wms_style_<styles_name>_legendurl_height, wms_style, wms_style_<styles_name>_legendurl_href.
9.2. WMS Server
443
refer to section 7.1.4.5.4 of the WMS 1.1.1 spec. wms_timedefault Description: (Optional for Time Support) This value is used if it is dened and the Time value is missing in the request. Please see the WMS Time Support Howto for more information. wms_timeextent Description: (Mandatory for Time Support) This is used in the capabilities to return the valid time values for the layer. The value dened here should be a valid time range. Please see the WMS Time Support Howto for more information. wms_timeitem Description: (Mandatory for Time Support) This is the name of the eld in the DB that contains the time values. Please see the WMS Time Support Howto for more information. wms_title Same as wms_title in the Web Object. Vendor specic WMS parameters angle Angle (in degrees) to rotate the map. Note: The angle value is in degrees clockwise. Sample WMS Server Maple The following is a very basic WMS Server maple:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
MAP NAME "WMS-test" STATUS ON SIZE 400 300 SYMBOLSET ../ e t c / s y m b o l s . s y m EXTENT -2200000 -712631 3072800 3840000 UNITS METERS SHAPEPATH "../data" IMAGECOLOR 255 255 255 FONTSET ../ e t c / f o n t s . t x t WEB IMAGEPATH "/ms4w/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" METADATA "wms_title" "WMS Demo Server" ##required "wms_onlineresource" "http://yourpath/cgi-bin/mapserv.exe?" "wms_srs" "EPSG:42304 EPSG:42101 EPSG:4269 EPSG:4326" "wms_enable_request" "*" ##necessary END END PROJECTION "init=epsg:42304" END
##required ##recommended
##required
444
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
# # Start of layer definitions # LAYER NAME "park" METADATA "wms_title" "Parks" ##required END TYPE POLYGON STATUS OFF DATA p a r k PROJECTION "init=epsg:42304" ##recommended END CLASS NAME "Parks" STYLE COLOR 200 255 0 OUTLINECOLOR 120 120 120 END END END # Layer LAYER NAME p o p p l a c e METADATA "wms_title" "Cities" ##required END TYPE POINT STATUS ON DATA p o p p l a c e PROJECTION "init=epsg:42304" ##recommended END CLASS NAME "Cities" STYLE SYMBOL 2 SIZE 8 COLOR 0 0 0 END END END # Layer END # Map File
9.2.6 FAQ / Common Problems

Q How can I nd the EPSG code for my datas projection? A If you know the parameters of your datas projection, then you can browse the epsg le that comes with PROJ4 and look for a projection denition that matches your datas projection. Its a simple text le and the EPSG code is inside brackets (<...>) at the beginning of every line. The epsg le is usually located in /usr/local/share/proj/ on Unix systems and in C:/PROJ/ or C:/PROJ/NAD in Windows systems (depending on the installation). MS4W users will nd the epsg
9.2. WMS Server
445
le in /MS4W/proj/nad/.
Q My WMS server produces the error msProcessProjection(): no system list, errno: .. A Thats likely PROJ4 complaining that it cannot nd the epsg projection denition le. Make sure you have installed PROJ 4.4.3 or more recent and that the epsg le is installed at the right location. On Unix it should be under /usr/local/share/proj/, and on Windows PROJ looks for it under C:/PROJ/ or C:/PROJ/NAD (depending on the installation). You should also check the error documentation to see if your exact error is discussed. If you dont have the epsg le then you can get it as part of the PROJ4 distribution at http://trac.osgeo.org/proj/ or you can download it at http://www.maptools.org/dl/proj4-epsg.zip.
Q How do AUTO projections work? A When a WMS client calls a WMS server with an auto projection, it has to specify the SRS in the form: AUTO: proj_id,unit_id,lon0,lat0 where: proj_id is one of 42001, 42002, 42003, 42004, or 42005 (only ve auto projections are currently dened). unit_id is always 9001 for meters. (It is uncertain whether anyone supports any other units.) lon0 and lat0 are the coordinates to use as the origin for the projection. When using an AUTO projection in WMS GetCapabilities, you include only the AUTO:42003 string in your wms_srs metadata, you do not include the projection parameters. Those are added by the application (client) at runtime depending on the map view. For example:
NAME "DEMO" ... WEB ... METADATA "wms_title" "WMS Demo Server" "wms_onlineresource" "http://my.host.com/cgi-bin/mapserv?map=wms.map&" "wms_srs" "AUTO:42001 AUTO:42002" "wms_enable_request" "*" ##necessary END # METADATA END # WEB
The above server advertises the rst two auto projections.
9.3 WMS Client

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Last Updated 2010-10-01
446
Table of Contents WMS Client Introduction Compilation / Installation MapFile Conguration Limitations/TODO
9.3.1 Introduction
A WMS (or Web Map Server) allows for use of data from several different servers, and enables for the creation of a network of Map Servers from which clients can build customized maps. The following document contains information about using MapServers WMS connection type to include layers from remote WMS servers in MapServer applications. Mapserver supports the following WMS versions when acting as client: 1.0.0, 1.0.7, 1.1.0, 1.1.1 (see Mapserver OGC Specication support for an updated list). This document assumes that you are already familiar with certain aspects of MapServer: MapServer application development and setting up .map les. Familiarity with the WMS spec would be an asset. A link to the WMS specication document is included below. WMS-Related Information MapServer WMS Server HowTo WMS 1.1.1 specication MapServer OGC Web Services Workshop package
9.3.2 Compilation / Installation

The WMS connection type is enabled by the with-wmsclient congure switch. It requires PROJ4, GDAL and libcurl version 7.10.1 or more recent. Windows users who do not want to compile MapServer should use MS4W (which comes ready for WMS/WFS client and server use), or check for the availability of other Windows binaries with WMS support. For PROJ4 and GDAL installation, see the MapServer Compilation HowTo (Compiling on Unix / Compiling on Win32) For libcurl, make sure you have version 7.10.1 or more recent installed on your system. You can nd out your libcurl version using curl-cong version. (if your system came with an older version of libcurl preinstalled then you MUST uninstall it prior to installing the new version) Once the required libraries are installed, then congure MapServer using the with-wmsclient switch (plus all the other switches you used to use) and recompile. This will give you a new set of executables (and possibly php_mapscript.so if you requested it). See the MapServer Compilation HowTo (links above) for installation details. Check your MapServer executable To check that your mapserv executable includes WMS support, use the -v command-line switch and look for SUPPORTS=WMS_CLIENT. 9.3. WMS Client 447
Example 1. Mapserv Version Info on Unix:

$ ./mapserv -v MapServer version 5.2.0-rc1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS SUPPORTS=GEOS SUPPORTS=RGBA_PNG INPUT=JPEG INPUT=POSTGIS INPUT=ORACLESPATIAL INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
Example 2. Mapserv Version Info on Windows:

C:\ms4w\apache\cgi-bin> mapserv -v MapServer version 5.2.0-rc1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS SUPPORTS=GEOS SUPPORTS=RGBA_PNG INPUT=JPEG INPUT=POSTGIS INPUT=ORACLESPATIAL INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
Install Optional PROJ4 EPSG Codes (Note: installing these PROJ4 codes is optional, install only if you need them) Some Canadian WMS servers will use some non-standard projection codes not included in the default distribution (e.g. EPSG:42304, etc.). If you are planning to use MapServer to connect to Canadian WMS servers then you might want to download a custom Canadian epsg le with those codes, and unzip it in the /usr/local/share/proj directory (or /ms4w/proj/nad/ for MS4W users). Finally, ESRI WMS servers also come with their own series of non-standard codes. If you are planning to connect to ESRI WMS servers then you might want to get a custom epsg le that contains the canadian codes and the ESRI codes, allowing you to connect to any server. Download the custom ESRI epsg le and unzip it in /usr/local/share/proj (or /ms4w/proj/nad/ for MS4W users). Q But why not always install and distribute the proj4-epsg-with-42xxx-and-esri.zip le then since its more complete? A You should install only the epsg projection codes that you need, the epsg le with all ESRI codes in it is 20% larger than the default one, so it comes with extra overhead that you may not need. Also note that when creating WMS servers, in order to be really interoperable, only EPSG codes that are part of the standard EPSG list should be used. i.e. it is a bad idea for interoperability to use the custom canadian codes or the custom ESRI codes and we do not want to promote their use too much.
9.3.3 MapFile Conguration

Note: A PROJECTION must be set in the maple for the MAP unless you are sure that all your WMS layers support only a single projection which is the same as the PROJECTION of the map. The MAP PROJECTION can be set using init=epsg:xxxx codes or using regular PROJ4 parameters. Failure to set a MAP PROJECTION may result in blank maps coming from remote WMS servers (because of inconsistent BBOX+SRS combination being used in the WMS connection URL).
448
Storing Temporary Files Before version 6.0, and in version 6.0 when wms_cache_to_disk metadata is turned on, you have to set the IMAGEPATH value in the WEB object of your maple to point to a valid and writable directory. MapServer will use this directory to store temporary les downloaded from the remote servers. The temporary les are automatically deleted by MapServer so you wont notice them. Example 3. Setting IMAGEPATH Parameter in Maple
MAP ... WEB IMAGEPATH "/tmp/ms_tmp/" IMAGEURL ... END ... END
If you want to keep this temporary le for debugging purposes, you should add the following statement to the LAYER object of your maple:
LAYER .... DEBUG ON ... END
Adding a WMS Layer WMS layers are accessed via the WMS connection type in the Maple. Here is an example of a layer using this connection type:
LAYER NAME "country_bounds" TYPE RASTER STATUS ON CONNECTION "http://demo.mapserver.org/cgi-bin/wms?" CONNECTIONTYPE WMS METADATA "wms_srs" "EPSG:4326" "wms_name" "country_bounds" "wms_server_version" "1.1.1" "wms_format" "image/gif" END END
Required Layer Parameters and Metadata

CONNECTIONTYPE WMS CONNECTION - this is the remote servers online resource URL, just the base URL without any of the WMS parameters. The server version, image format, layer name, etc. will be provided via metadata, see below. Note: Note that if the CONNECTION parameter value is not set the the value of the wms_onlineresource metadata will be used. If both CONNECTION and wms_onlineresource are set then the wms_onlineresource metadata takes precedence.
9.3. WMS Client
449
wms_format metadata - the image format to use in GetMap requests. Note: If wms_formatlist is provided then wms_format is optional and MapServer will pick the rst supported format in wms_formatlist for use in GetMap requests. If both wms_format and wms_formatlist are provided then wms_format takes precedence. Also note that WMS Servers only advertize supported formats that are part of the GD/GDAL libraries. wms_name metadata - comma-separated list of layers to be fetched from the remote WMS server. This value is used to set the LAYERS and QUERY_LAYERS WMS URL parameters. wms_server_version metadata - the version of the WMS protocol supported by the remote WMS server and that will be used for issuing GetMap requests. wms_srs metadata - space-delimited list of EPSG projection codes supported by the remote server. You normally get this from the servers capabilities output. This value should be upper case (EPSG:4236.....not epsg:4236) to avoid problems with case sensitive platforms. The value is used to set the SRS WMS URL parameter.
Optional Layer Parameters and Metadata

MINSCALE, MAXSCALE - if the remote servers capabilities contains a ScaleHint value for this layer then you might want to set the MINSCALE and MAXSCALE in the LAYER object in the maple. This will allow MapServer to request the layer only at scales where it makes sense PROJECTION object - it is optional at this point. MapServer will create one internally if needed. Including one may allow MapServer to avoid looking up a denition in the PROJ.4 init les. wms_auth_username metadata - msEncrypt-style authorization string. Empty strings are also accepted.
METADATA "wms_auth_username" "foo" "wms_auth_password" "{FF88CFDAAE1A5E33}" END
wms_auth_type metadata - Authorization type. Supported types include: basic digest ntlm any (the underlying http library picks the best among the opotions supported by the remote server) anysafe (the underlying http library picks only safe methods among the options supported by the remote server)
METADATA "wms_auth_type" "ntlm" END
wms_connectiontimeout metadata - the maximum time to wait for a remote WMS layer to load, set in seconds (default is 30 seconds). This metadata can be added at the layer level so that it affects only that layer, or it can be added at the map level (in the web object) so that it affects all of the layers. Note that wms_connectiontimeout at the layer level has priority over the map level.
METADATA ... "wms_connectiontimeout" "60" ... END
450
wms_exceptions_format metadata - set the format for exceptions (as of MapServer 4.6). MapServer defaults to application/vnd.ogc.se_inimage (the exception will be in a picture format). You can check the GetCapabilities of the server to see what formats are available for exceptions. The application/vnd.ogc.se_inimage exception format is actually a non-required exception format in the WMS 1.1.1 spec, so there are servers out there which dont support this format. In that case you would use:
LAYER ... METADATA "wms_exceptions_format " a p p l i c a t i on/ v n d . o g c . s e _ x m l " END ... END
Which would return this xml exception in the MS_ERRORFILE:

Tue Jan 17 18:05:13 2006 - msDrawWMSLayerLow(): WMS server error. WMS GetMap request got XML exception for layer prov_bound: <?xml version=1.0 encoding="ISO-8859-1" standalone="no" ?><!DOCTYPE ServiceExceptionReport SYSTEM "http://schemas.opengis.net/wms/1.1.1/exception_1_1_1.dtd"> <ServiceExceptionReport version="1.1.1"><ServiceException code="LayerNotDefined"> msWMSLoadGetMapParams(): WMS server error. Invalid layer(s) given in the LAYERS parameter. </ServiceException> </ServiceExceptionReport>
wms_force_separate_request metadata - set this to 1 to force this WMS layer to be requested using its own separate GetMap request. By default MapServer will try to merge multiple adjacent WMS layers from the same server into a single multi-layer GetMap request to reduce the load on remote servers and improve response time. This metadata is used to bypass that behavior. wms_formatlist metadata - comma-separated list of image formats supported by the remote WMS server. Note that wms_formatlist is used only if wms_format is not set. If both wms_format and wms_formatlist are provided then wms_format takes precedence. wms_latlonboundingbox metadata - the bounding box of this layer in geographic coordinates in the format lon_min lat_min lon_max lat_max. If it is set then MapServer will request the layer only when the map view overlaps that bounding box. You normally get this from the servers capabilities output.
METADATA "wms_latlonboundingbox" "-124 48 -123 49" END
wms_proxy_auth_type metadata - the authorization type to use for a proxy connection. Supported types include: basic digest ntlm any (the underlying http library picks the best among the opotions supported by the remote server) anysafe (the underlying http library picks only safe methods among the options supported by the remote server)
METADATA "wms_proxy_auth_type" "ntlm" END
wms_proxy_host metadata - the hostname of the proxy to use, in dot-quad format, with an optional port component (e.g. 192.168.2.10:8080).
9.3. WMS Client
451
METADATA "wms_proxy_host" "192.168.2.10" END
wms_proxy_port metadata - the port to use for a proxy connection.

METADATA "wms_proxy_port" "8080" END
wms_proxy_type metadata - the type of the proxy connection. Valid values are http and socks5, which are case sensitive.
METADATA "wms_proxy_type" "http" END
wms_proxy_username metadata - msEncrypt-style string for a proxy connection. Empty strings are also accepted.
METADATA "wms_proxy_username" "foo" "wms_proxy_password" "{FF88CFDAAE1A5E33}" END
wms_sld_body metadata - can be used to specify an inline SLD document. wms_sld_url metadata - can be used to specify a link to an SLD document. wms_style metadata - name of style to use for the STYLES parameter in GetMap requests for this layer. wms_style_<stylename>_sld metadata URL of a SLD to use in GetMap requests. Replace <stylename> in the metadta name with the name of the style to which the SLD applies.
METADATA ... "wms_style" "wms_style_mystyle_sld" ... END
"mystyle" "http://my.host.com/mysld.xml"
For more information on SLDs in MapServer see the SLD HowTo document. wms_time metadata - value to use for the TIME parameter in GetMap requests for this layer. Please see the WMS Time HowTo for more information. wms_bgcolor metadata - species the color to be used as the background of the map. The general format of BGCOLOR is a hexadecimal encoding of an RGB value where two hexadecimal characters are used for each of Red, Green, and Blue color values. The values can range between 00 and FF for each (0 and 255, base 10). The format is 0xRRGGBB; either upper or lower case characters are allowed for RR, GG, and BB values. The 0x prex shall have a lower case x. wms_transparent metadata - species whether the map background is to be made transparent or not. TRANSPARENT can take on two values, TRUE or FALSE. If not specied, MapServer sets default to TRUE wms_cache_to_disk metadata - set this to 1 to force MapServer to write fetched images to disk. Writing to disk is necessary to take advantage of MapServers caching logic to avoid refetching WMS requests made previously. This feature is new to MapServer 6.0 - previously results were always written to disk. wms_nonsquare_ok metadata - set this to 0 to indicate that the remote WMS only supports requests for square pixels. In this case MapServer will be careful to only make square pixel requests even if it means
452
oversampling in one dimension compared to the resolution of image data required. This feature is new to MapServer 6.0. wms_extent metadata - If there is exactly one SRS supported by this layer (as listed in the wms_srs metadata), and if the wms_extent metadata item (or an extent specied via the EXTENT keyword) is set then MapServer will take care to only making requests within this area. This can short circuit requests completely outside the layer, reduce processing for layers that only partially overlap the target map area and avoid poor behaviors with reprojection in some areas. The contents of this metadata item should be of the form minx miny maxx maxy. This feature is new to MapServer 6.0. Note: Note that each of the above metadata can also be referred to as ows_* instead of wms_*. MapServer tries the wms_* metadata rst, and if not found it tries the corresponding ows_* name. Using this reduces the amount of duplication in maples that support multiple OGC interfaces since ows_* metadata can be used almost everywhere for common metadata items shared by multiple OGC interfaces.
Old CONNECTION parameter format from version 3.5 and 3.6 (deprecated)
In MapServer version 3.5 and 3.6, the CONNECTION parameter had to include at a minimum the VERSION, LAYERS, FORMAT and TRANSPARENT WMS parameters. This mode of operation is still supported but is deprecated and you are encouraged to use metadata items for those parameters as documented in the previous section above. Here is an example of a layer denition using this deprecated CONNECTION parameter format:
LAYER NAME "bathymetry_elevation" TYPE RASTER STATUS ON CONNECTIONTYPE WMS CONNECTION "http://demo.mapserver.org/cgi-bin/wms?VERSION=1.1.0&LAYERS=bluemarble&FORMAT=image/png" PROJECTION "init=epsg:4326" END END
9.3.4 Limitations/TODO
1. GetFeatureInfo is not fully supported since the output of getFeatureInfo is left to the discretion of the remote server. A method layer.getWMSFeatureInfoURL() has been added to MapScript for applications that want to access featureInfo results and handle them directly. 2. MapServer does not attempt to fetch the layers capabilities. Doing so at every map draw would be extremely inefcient. And caching that information does not belong in the core of MapServer. This is better done at the application level, in a script, and only the necessary information is passed to the MapServer core via the CONNECTION string and metadata.
9.4 WMS Time

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Revision $Revision: 12605 $ Date $Date: 2011-09-29 09:12:13 -0700 (Thu, 29 Sep 2011) $
9.4. WMS Time
453
Last Updated 2006/06/26 Table of Contents WMS Time Introduction Enabling Time Support in MapServer Future Additions Limitations and Known Bugs
9.4.1 Introduction
A WMS server can provide support to temporal requests. This is done by providing a TIME parameter with a time value in the request. MapServer 4.4 and above provides support to interpret the TIME parameter and transform the resulting values into appropriate requests. Links to WMS-Related Information MapServer WMS Server HowTo MapServer WMS Client HowTo WMS 1.1.1 specication MapServer OGC Web Services Workshop
9.4.2 Enabling Time Support in MapServer

Time Patterns WMS species that the basic format used for TIME requests is based on the ISO 8601:1988(E) extended format. MapServer supports a limited set of patterns that are dened in the ISO 8601 specications, as well as few other patterns that are useful but not compliant to ISO 8601. Here is a list of patterns currently supported: Table 1. Supported Time Patterns Time Patterns YYYYMMDD YYYY-MM-DDTHH:MM:SSZ YYYY-MM-DDTHH:MM:SS YYYY-MM-DD HH:MM:SS YYYY-MM-DDTHH:MM YYYY-MM-DD HH:MM YYYY-MM-DDTHH YYYY-MM-DD HH YYYY-MM-DD YYYY-MM YYYY THH:MM:SSZ THH:MM:SS Examples 20041012 2004-10-12T13:55:20Z 2004-10-12T13:55:20 2004-10-12 13:55:20 2004-10-12T13:55 2004-10-12 13:55 2004-10-12T13 2004-10-12 13 2004-10-12 2004-10 2004 T13:55:20Z T13:55:20
454
Setting Up a WMS Layer with Time Support To have a valid WMS layer with time support, the user has to dene the following metadata at the layer level: wms_timeextent: (Mandatory) this is used in the capabilities document to return the valid time values for the layer. The value dened here should be a valid time range. (more on this in Specifying Time Extents below) wms_timeitem: (Mandatory) this is the name of the eld in the DB that contains the time values. wms_timedefault: (Optional) this value is used if it is dened and the TIME value is missing in the request. It is also recommended to set a LAYER FILTER for the time layer to provide a default time also for non-WMS requests. If the time item is mytime, and the time format is YYYYMMDD the following layer lter could be used:
FILTER ([ m y t i m e ] = 2004-01-01 14:10:00)
Specifying Time Extents

Time Extents can be declared with the following syntax for the wms_timeextent metadata (see Annex C.3 in the WMS 1.1.1 specication document for a full description): 1. value - a single value. This is not directly supported in MapServer but there is an easy workwound by specifying the same value as min and max. 2. value1,value2,value3,... - a list of multiple values. 3. min/max/resolution - an interval dened by its lower and upper bounds and its resolution. This is supported in MapServer (note that the resolution is not supported however). 4. min1/max1/res1,min2/max2/res2,... - a list of multiple intervals.
Example WMS-Server Layer

LAYER NAME "earthquakes" METADATA "wms_title" "Earthquakes" "wms_timeextent" "2004-01-01/2004-02-01" "wms_timeitem" "TIME" "wms_timedefault" "2004-01-01 14:10:00" "wms_enable_request" "*" END TYPE POINT STATUS ON DATA "quakes" FILTER ([ T I M E ]=2004-01-01 14:10:00) CLASS .. END END
GetCapabilities Output If your layer is set up properly, requesting the capabilities on the server outputs a Dimension element. Here is an example of a GetCapabilities result for a layer congured for time support:
9.4. WMS Time
455
<Layer queryable="0" opaque="0" cascaded="0"> <Name>earthquakes</Name> <Title>Earthquakes</Title> <SRS>EPSG:4326</SRS> <LatLonBoundingBox minx="-131.02" miny="24.84" maxx="-66.59" maxy="48.39" /> <BoundingBox SRS="EPSG:4326" minx="-131.02" miny="24.84" maxx="-66.59" maxy="48.39" /> <Dimension name="time" units="ISO8601"/> <Extent name="time" default="2004-01-01 14:10:00" nearestValue="0">2004-01-01/2004-02-01</Extent> </Layer>
Supported Time Requests When sending a request with the TIME parameter, different types of time values can be specied. The following are supported by MapServer: single value: for example: ...&TIME=2004-10-12&... multiple values: for example: ...&TIME=2004-10-12, 2004-10-13, 2004-10-14&... single range value: for example: ...&TIME=2004-10-12/2004-10-13&... multiple range values: for example: ...&TIME=2004-10-12/2004-10-13, 2004-10-15/2004-10-16&... Interpreting Time Values When MapServer receives a request with a TIME parameter, it transforms the time requests into valid expressions that are assigned to the lter parameter on layers that are time-aware. Here are some examples of how different types of requests are treated (wms_timeitem is dened here as being time_eld): single value (2004-10-12) transforms to ([time_eld] eq 2004-10-12) multiple values (2004-10-12, 2004-10-13) transform to ([time_eld] eq 2004-10-12 OR [time_eld] eq 2004-10-13) single range : 2004-10-12/2004-10-13 transforms to (([time_eld] ge 2004-10-12) AND ([time_eld] le 2004-10-13)) multiple ranges (2004-10-12/2004-10-13, 2004-10-15/2004-10-16) transform to (([time_eld] ge 2004-1012 AND [time_eld] le 2004-10-13) OR ([time_eld] ge 2004-10-15 AND [time_eld] le 2004-1016)) As shown in the above examples, all elds and values are written inside back tics () - this is the general way of specifying time expressions inside MapServer. Exceptions to this rule: 1. When dealing with layers that are not Shapeles nor through OGR, the expression built has slightly different syntax. For example, the expression set in the lter for the rst example above would be ([time_eld] = 200410-12). 2. For PostGIS/PostgreSQL layers, the time expression built uses the date_trunc function available in PostgreSQL. For example, if the user passes a time value of 2004-10-12, the expression set in the lter is date_trunc(day, time_eld) = 2004-10-12. The use of the date_trunc function allows requests to use the concept of time resolution. In the example above, for a request of 2004-10-12, MapServer determines that the resolution is day by parsing the time string and the result gives all records matching the date 2004-10-12 regardless of the values set for Hours/Minutes/Seconds in the database. For more information on the date_trunc function, please refer to the PostgreSQL documentation.
456
Limiting the Time Formats to Use The user has the ability to dene the time format(s) to be used when a request is sent, in metadata at the WEB level. For example, the user can dene the following two formats:
"wms_timeformat" "YYYY-MM-DDTHH, YYYY-MM-DDTHH:MM"
Another example is for a WMS layer that is based on time data that contains precise time values taken every minute (e.g., 2004-10-12T13:55, 2004-10-12T13:56, 2004-10-12 T13:57, ...). Normally, a valid request on such a layer would require the time value to be as complete as the data underneath. By dening a set of patterns to use, MapServer introduces the notion of resolution to be used when doing a query. Using the example above, a request TIME= 200410-12T13:55 would be valid and a request TIME= 2004-10-12T13 would also be valid and would return all elements taken for that hour. Note that this functionality is only available on layers based on Shapeles and OGR. Example of WMS-T with PostGIS Tile Index for Raster Imagery This example currently requires latest 4.9 CVS build! Here is an example maple snippet for a raster WMS-T instance using a PostGIS tileindex. This example shows US Nexrad Base Reectivity running at Iowa State U at http://mesonet.agron.iastate.edu/cgi-bin/wms/nexrad/n0rt.cgi?SERVICE=WMS&request=GetCapabilities
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
# Tile Index LAYER STATUS ON NAME "time_idx" TYPE POLYGON DATA "the_geom from nexrad_n0r_tindex" METADATA "wms_title" "TIME INDEX" "wms_srs" "EPSG:4326" "wms_extent" "-126 24 -66 50" "wms_timeextent" "2003-08-01/2006-12-31/PT5M" "wms_timeitem" "datetime" #column in postgis table of type timestamp "wms_timedefault" "2006-06-23T03:10:00Z" "wms_enable_request" "*" END CONNECTION "dbname=postgis host=10.10.10.20" CONNECTIONTYPE postgis END # raster layer LAYER NAME "nexrad-n0r-wmst" TYPE RASTER STATUS ON DEBUG ON PROJECTION "init=epsg:4326" END METADATA "wms_title" "NEXRAD BASE REF WMS-T" "wms_srs" "EPSG:4326" "wms_extent" "-126 24 -66 50" "wms_timeextent" "2003-08-01/2006-12-31/PT5M" "wms_timeitem" "datetime" #datetime is a column in postgis table of type timestamp
9.4. WMS Time
457
35 36 37 38 39 40 41 42
"wms_timedefault" "2006-06-23T03:10:00Z" "wms_enable_request" "*" END OFFSITE 0 0 0 TILEITEM "filepath" #filepath is a column in postgis table with varchar of the filepath to each imag TILEINDEX "time_idx" FILTER ([ d a t e t i m e ] = "2006-06-23T03:10:00Z") END
You can nd more information on Time and tileindexes in the WCS documentation.
9.4.3 Future Additions

Support for a special time value: current.
9.4.4 Limitations and Known Bugs

Pattern YYYYMMDD does not work on Windows. (Bug#970)
9.5 Map Context

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Last Updated 2010-10-07 Contents Map Context Introduction Implementing a Web Map Context
9.5.1 Introduction
The term map context comes from the Open Geospatial Constortiums (OGC) Web Map Context Specication v1.0.0, which coincides with the OGC Web Map Server Specication (WMS) v1.1.1. A map context is a XML document that describes the appearance of layers from one or more WMS servers, and can be transferred between clients while maintaining startup views, the state of the view (and its layers), and storing additional layer information. Support for OGC Web Map Context was added to MapServer in version 3.7/4.0. This allows client applications to load and save a map conguration in a standard XML format. MapServer can read context documents of versions 0.1.2, 0.1.4, 0.1.7, 1.0.0, 1.1.0 and can export contents in versions 0.1.4, 0.1.7, 1.0.0, 1.1.0. Web Map Context 1.1.0 support was added to MapServer 4.10 This document assumes that you are already familiar with certain aspects of MapServer: MapServer application development and setting up maples. Familiarity with the WMS spec would be an asset. Please see the following section for links to associated sources.
458
Links to WMS / Map Context Related Information MapServer WMS Client HowTo Open Geospatial Consortium (OGC) home page WMS 1.1.1 specication Map Context 1.0.0 specication MapServer OGC Web Services Workshop
9.5.2 Implementing a Web Map Context

Special Build Considerations Map Context support requires PROJ4, GDAL/OGR and PHP support libraries. Build/install the above libraries on your system and then build MapServer with the with-wmsclient with-proj withogr with-gdal with-php congure options. Also make sure that your build uses the USE_WMS_LYR and USE_OGR ags. For more details on MapServer compilation see the appropriate HowTo: Unix / Windows Windows users can use MS4W, which is ready for Map Context use. Map Context Maple A map context document can ONLY contain WMS layers (e.g. CONNECTIONTYPE WMS). Please refer to the MapServer WMS Client HowTo for more information on declaring WMS layers.
MapFile Metadata
The following maple metadata are used by MapServer to handle map context information: (Note that some parameters have width, height, format, and href, and some only have format and href. This is because width and height are only used for images and parameters that do not have them are text or html. For consistency with the spec MapServer supports height and width for all parameters, but they should only be used for images)
Web Object Metadata

ows_schemas_location : Location of XML schema document. Default is http://schemas.opengis.net. See http://ogc.dmsolutions.ca for an example of a valid schema tree. wms_abstract : A blurb of text providing more information about the WMS server. wms_address : If provided must also then provide wms_addresstype, wms_city, wms_stateorprovince, wms_postcode, and wms_country) wms_addresstype : If provided must also then provide wms_address, wms_city, wms_stateorprovince, wms_postcode, and wms_country) wms_city : If provided must also then provide wms_address, wms_addresstype, wms_stateorprovince, wms_postcode, and wms_country) wms_contactelectronicmailaddress : contact Email address. wms_contactfacsimiletelephone : contact facsimile telephone number.
9.5. Map Context
459
wms_contactorganization : wms_contactperson : wms_contactposition : wms_contactvoicetelephone : contact voice telephone number. wms_context_d : the feature id of the context. Set to 0 when saving if not specied. wms_context_version : the version of the map context specication. wms_country : If provided must also then provide wms_address, wms_city, wms_stateorprovince, wms_postcode, and wms_addresstype. wms_descriptionurl_format : Format of the webpage which contains relevant information to the view. wms_descriptionurl_href : Reference to a webpage which contains relevant information to the view. wms_keywordlist : A comma-separated list of keywords or keyword phrases to help catalog searching. wms_logourl_width : Width of the context logo. wms_logourl_height : Height of the context logo. wms_logourl_format : Format of the context logo. wms_logourl_href : Location of the context logo. wms_postcode : If provided must also then provide wms_address, wms_city, wms_stateorprovince, wms_addresstype, and wms_country. wms_stateorprovince : If provided must also then provide wms_address, wms_city, wms_addresstype, wms_postcode, and wms_country. wms_title : (Required) A human-readable name for this Layer (this metadata does not exist beyond version 0.1.4)
Layer Object Metadata

wms_abstract : A blurb of text providing more information about the WMS server. wms_dataurl_href : Link to an online resource where data corresponding to the layer can be found. wms_dataurl_format : Format of the online resource where data corresponding to the layer can be found. wms_dimension : Current dimension used. New in version 4.10. wms_dimensionlist : List of available dimensions. New in version 4.10. wms_dimension_%s_default : Default dimension value. MapServer will check for wms_time and wms_timedefault metadata when this is not specied. %s = the name of the dimension. New in version 4.10. wms_dimension_%s_multiplevalues : Multiple dimension values. %s = the name of the dimension. New in version 4.10. wms_dimension_%s_nearestvalue : Nearest dimension value. The default value is 0. %s = the name of the dimension. New in version 4.10. wms_dimension_%s_units : Units for the dimension values. The default value is ISO8601. %s = the name of the dimension. New in version 4.10. wms_dimension_%s_unitsymbol : Symbol for dimension units. The default value is t. %s = the name of the dimension. New in version 4.10.
460
wms_dimension_%s_uservalue : User dimension value. MapServer will check for wms_time and wms_timedefault metadata when this is not specied. %s = the name of the dimension. New in version 4.10. wms_format : Current format used. wms_formatlist : List of available formats for this layer. wms_metadataurl_href : Link to an online resource where descriptive metadata of the corresponding layer can be found. wms_metadataurl_format : Format of the online resource where descriptive metadata of the corresponding layer can be found. wms_name : Name of the WMS layer on the server. wms_onlineresource : Required URL to access the server. wms_server_version : The version of the web map server specication. wms_server_title : The title of the web map server. wms_stylelist : Current style used. wms_style_%s_legendurl_width : Width of an image describing the style. %s = the name of the style. wms_style_%s_legendurl_height : Height of an image describing the style. %s = the name of the style. wms_style_%s_legendurl_format : Format of an image describing the style. %s = the name of the style. wms_style_%s_legendurl_href : Location of an image describing the style. %s = the name of the style. wms_style_%s_sld : URL to the SLD document of this style. %s = the name of the style. wms_style_%s_sld_body : SLD_BODY document of this style. %s = the name of the style. wms_style_%s_title : Title of the layer. %s = the name of the style. wms_title : (Required) A human-readable name for this Layer.
Sample Map Context Maple

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
MAP NAME "mapcontext" STATUS ON SIZE 400 300 SYMBOLSET "../etc/symbols.txt" EXTENT -180 -90 180 90 UNITS DD SHAPEPATH "../data" IMAGECOLOR 255 255 255 FONTSET "../etc/fonts.txt"
# # Start of web interface definition # WEB IMAGEPATH "/ms4w/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" METADATA "wms_abstract" "Demo for map context document. Blah blah..." "wms_title" "Map Context demo" #### REQUIRED
9.5. Map Context
461
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
END END PROJECTION "init=epsg:4326" END # # Start of layer definitions # LAYER NAME "country_bounds" TYPE RASTER STATUS ON CONNECTION "http://demo.mapserver.org/cgi-bin/wms?" CONNECTIONTYPE WMS METADATA "wms_title" "World Country Boundaries" #### REQUIRED "wms_onlineresource" "http://demo.mapserver.org/cgi-bin/wms?" #### REQUIRED "wms_srs" "EPSG:4326" "wms_name" "country_bounds" "wms_server_version" "1.1.1" "wms_format" "image/gif" "wms_dimensionlist" "time,width" "wms_dimension" "time" "wms_dimension_time_unitsymbol" "t" "wms_dimension_time_units" "ISO8601" "wms_dimension_time_uservalue" "1310" "wms_dimension_time_default" "1310" "wms_dimension_time_multiplevalues" "1310,1410" "wms_dimension_time_nearestvalue" "0" END END END # Map File
Testing Map Context Support 1. The rst thing to do is to save your maple using the saveMapContext function available from the PHP/MapScript library. An example script is shown below:
<?php if (!extension_loaded("MapScript")) dl(MODULE); $oMap = ms_newMapObj("mapcontext.map"); $oMap->saveMapContext("mapcontext_output.xml"); ?>
2. Scan the XML output to look for <! WARNING: ... > comments. Then make the necessary changes to x every warning that you encounter. At the end of this you should have a maple compatible with the Map Context specication. 3. Now you can load your new Map Context document into an application using the loadMapContext function from the PHP/MapScript library.
462
Sample Map Context Document The following is a sample Map Context document:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
<?xml version=1.0 encoding="ISO-8859-1" standalone="no" ?> <ViewContext version="1.1.0" id="mapcontext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance <General> <Window width="400" height="300"/>  <BoundingBox SRS="EPSG:4326" minx="-180.000000" miny="-90.000000" maxx="180.000000" maxy="90.  <Title>Map Context demo</Title> <Abstract>Demo for map context document. Blah blah...</Abstract> <ContactInformation> </ContactInformation> </General> <LayerList> <Layer queryable="0" hidden="0"> <Server service="OGC:WMS" version="1.1.1" title="World Country Boundaries"> <OnlineResource xlink:type="simple" xlink:href="http://demo.mapserver.org/cgi-bin/wms?"/> </Server> <Name>country_bounds</Name> <Title>World Country Boundaries</Title> <SRS>EPSG:4326</SRS> <FormatList> <Format current="1">image/gif</Format> </FormatList> <DimensionList> <Dimension name="time" units="ISO8601" unitSymbol="t" userValue="1310" default="1310" mul </DimensionList> </Layer> </LayerList> </ViewContext>
Map Context Support Through CGI MapServer CGI allows you to load a map context through the use of a CONTEXT parameter, and you can point this parameter to a locally stored context le or a context le accessible through a URL. For more information on MapServer CGI see the CGI Reference.
Support for Local Map Context Files

There is a new cgi parameter called CONTEXT that is used to specify a local context le. The user can then use MapServer to request a map using the following syntax:
http://localhost/mapserver.cgi?MODE=map&MAP=/path/to/mapfile.map&CONTEXT= /path/to/contextfile.xml&LAYERS=layer_name1 layers_name2
Note: All layers created from a context le have their status set to ON. To be able to display layers, the user needs to add the LAYERS argument in the URL.
Support for Context Files Accessed Through a URL

The syntax of using a web accessible context le would be similar to accessing a local context le:
9.5. Map Context
463
http://localhost/mapserver.cgi?MODE=map&MAP=/path/to/mapfile.map&CONTEXT= http://URL/path/to/contextfile.xml&LAYERS=layers_name1 layer_name2
Due to security concerns loading a le from a URL is disabled by default. To enable this functionality, the user needs to set a CONFIG parameter called CGI_CONTEXT_URL in the default maple that will allow this functionality. Here is an example of a map le with the CONFIG parameter:
# Start of map file NAME "map-context" STATUS ON SIZE 400 300 EXTENT -2200000 -712631 3072800 3840000 UNITS METERS IMAGECOLOR 255 255 255 IMAGETYPE png CONFIG "CGI_CONTEXT_URL" "1" ... WEB ... END LAYER ... END END
Default Maple
To smoothly run a MapServer CGI application with a Map Context, the application administrator needs to provide a default maple with at least the basic required parameters that will be used with the Context le. This default maple can contain as little information as the imagepath and imageurl or contain a list of layers. Information coming from the context (e.g.: layers, width, height, ...) would either be appended or will replace values found in the maple. Here is an example of a default map le containing the minimum required parameters:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
NAME "CGI-CONTEXT-DEMO" STATUS ON SIZE 400 300 EXTENT -2200000 -712631 3072800 3840000 UNITS METERS IMAGECOLOR 255 255 255 IMAGETYPE png # # Start of web interface definition # WEB MINSCALE 2000000 MAXSCALE 50000000 # # On Windows systems, /tmp and /tmp/ms_tmp/ should be created at the root # of the drive where the .MAP file resides. # IMAGEPATH "/ms4w/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" END END # Map File
464
Map Context Support Through WMS MapServer can also output your WMS layers as a Context document. MapServer extends the WMS standard by adding a request=GetContext operation that allows you to retrieve a context for a WMS-based maple with a call like:
http://localhost/mapserver.cgi?map=/path/to/mapfile.map&service=WMS& request=GetContext&version=1.1.0
The VERSION parameter controls the version of context document to return. GetContext is disabled by default because it could be considered a security issue: it could publicly expose the URLs of WMS layers used (cascaded) by a maple. To enable it, set the wms_getcontext_enabled web metadata to 1 in your WMS servers maple.
9.6 WFS Server

Author Jean-Franois Doyon Contact jdoyon at nrcan.gc.ca Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Revision $Revision: 12605 $ Date $Date: 2011-09-29 09:12:13 -0700 (Thu, 29 Sep 2011) $ Contents WFS Server Introduction Conguring your MapFile to Serve WFS layers Reference Section To-do Items and Known Limitations
9.6.1 Introduction
A WFS ( Web Feature Service ) publishes feature-level geospatial data to the web. This means that instead of returning an image, as MapServer has traditionally done, the client now obtains ne-grained information about specic geospatial features of the underlying data, at both the geometry AND attribute levels. As with other OGC specications, this interface uses XML over HTTP as its delivery mechanism, and, more precisely, GML (Geography Markup Language), which is a subset of XML. WFS-Related Information Here are some WFS related links (including a newly added OGC services workshop with MapServer). Since these are highly detailed technical specications, there is no need to read through them in their entirety to get a MapServer WFS up and running. It is still recommended however to read them over and get familiar with the basics of each of them, in order to understand how it all works: The OGC Web Feature Service Implementation Specication. The Geography Markup Language Implementation Specication. 9.6. WFS Server 465
MapServer OGC Web Services Workshop package. Working knowledge of MapServer is of course also required. Software Requirements In order to enable MapServer to serve WFS, it MUST be compiled against certain librairies: PROJ.4: The reprojection library. Version 4.4.3 or greater is required. GDAL/OGR: I/O support libraries. Version 1.1.8 or greater is required. Please see the MapServer UNIX Compilation and Installation HowTo for detailed instructions on compiling mapserver with support for these libraries and features. For Windows users, the MS4W installer comes ready to serve both WFS and WMS. Versions of GML Supported MapServer can output both GML2 and GML3. By default MapServer serves GML2. You can test this by adding an OUTPUTFORMAT parameter to a GetFeature request, such as: GML2 request output GML3 request output For a detailed discussion on the versions supported, see bug#884.
9.6.2 Conguring your MapFile to Serve WFS layers

Much as in the WMS support, WFS publishing is enabled by adding certain magic METADATA keyword/value pairs to a MapFile. MapServer will serve and include in its WFS capabilities only the layers that meet the following conditions: Data source is of vector type (Shapele, OGR, PostGIS, SDE, SDO, ...) LAYER NAME must be set. Layer names must start with a letter when setting up a WFS server (layer names should not start with a digit or have spaces in them). LAYER TYPE is one of: LINE, POINT, POLYGON The wfs_onlineresource metadata: The wfs_onlineresource metadata is set in the maps web object metadata and species the URL that should be used to access your server. This is required for the GetCapabilities output. If wfs_onlineresource is not provided then MapServer will try to provide a default one using the script name and hostname, but you shouldnt count on that too much. It is strongly recommended that you provide the wfs_onlineresource metadata. See section 12.3.3 of the WFS 1.0.0 specication for the whole story about the online resource URL. Basically, what you need is a complete HTTP URL including the http:// prex, hostname, script name, potentially a map= parameter, and and terminated by ? or &. Here is a valid online resource URL:
http://my.host.com/cgi-bin/mapserv?map=mywfs.map&
466
http://my.host.com/cgi-bin/mywfs?
This is covered in more detail in the More About the Online Resource URL section of the WMS Server document. The wfs_enable_request metadata (see below). Example WFS Server Maple The following is an example of a bare minimum WFS Server maple. Note the comments for the required parameters.
MAP NAME "WFS_server" STATUS ON SIZE 400 300 SYMBOLSET "../etc/symbols.txt" EXTENT -180 -90 180 90 UNITS DD SHAPEPATH "../data" IMAGECOLOR 255 255 255 FONTSET "../etc/fonts.txt"
# # Start of web interface definition # WEB IMAGEPATH "/ms4w/tmp/ms_tmp/" IMAGEURL "/ms_tmp/" METADATA "wfs_title" "WFS Demo Server for MapServer" ## REQUIRED "wfs_onlineresource" "http://demo.mapserver.org/cgi-bin/wfs?" ## Recommended "wfs_srs" "EPSG:4326 EPSG:4269 EPSG:3978 EPSG:3857" ## Recommended "wfs_abstract" "This text describes my WFS service." ## Recommended "wfs_enable_request" "*" # necessary END END PROJECTION "init=epsg:4326" END # # Start of layer definitions # ################## # World Continents ################## LAYER NAME "continents" METADATA "wfs_title" "World continents" ##REQUIRED "wfs_srs" "EPSG:4326" ## REQUIRED "gml_include_items" "all" ## Optional (serves all attributes for layer) "gml_featureid" "ID" ## REQUIRED "wfs_enable_request" "*" END
9.6. WFS Server
467
TYPE POLYGON STATUS ON DATA shapefile/countries_area PROJECTION "init=epsg:4326" END CLASS NAME World Continents STYLE COLOR 255 128 128 OUTLINECOLOR 96 96 96 END END END #layer END #mapfile
Rules for Handling SRS in MapServer WFS The OGC WFS 1.0 specication doesnt allow a layer (feature type) to be advertised in more than one SRS. Also, there is no default SRS that applies to all layers by default. However, it is possible to have every layer in a WFS server advertised in a different SRS. The OGC WFS 1.1 specication allows more than one SRS to be advertised, and one of the SRSs will be advertised as the default SRS (the default SRS will be the rst in the list specied in the METADATA wfs_srs / ows_srs). Here is how MapServer decides the SRS to advertise and use for each layer in your WFS: If a top-level map SRS is dened then this SRS is used and applies to all layers (feature types) in this WFS. In this case the SRS of individual layers is simply ignored even if it is set. If no top-level map SRS is dened, then each layer is advertised in its own SRS in the capabilities. Note: By SRS is dened, we mean either the presence of a PROJECTION object dened using an EPSG code, or of a wfs_srs / ows_srs metadata at this level. Note: At the map top-level the wfs_srs / ows_srs metadata value takes precedence over the contents of the PROJECTION block. At the layer level, if both the wfs_srs / ows_srs metadata and the PROJECTION object are set to different values, then the wfs_srs / ows_srs metadata denes the projection to use in advertising this layer (assuming there is no top-level map SRS), and the PROJECTION value is assumed to be the projection of the data. So this means that the data would be reprojected from the PROJECTION SRS to the one dened in the wfs_srs / ows_srs metadata before being served to WFS clients. Confusing? As a rule of thumb, simply set the wfs_srs / ows_srs at the map level (in web metadata) and never set the wfs_srs / ows_srs metadata at the layer level and things will work ne for most cases. Axis Orientation in WFS 1.1 The axis order in previous versions of the WFS specications was to always use easting (x or lon ) and northing (y or lat). WMS 1.1 species that, depending on the particular SRS, the x axis may or may not be oriented West-to-East, and the y axis may or may not be oriented South-to-North. The WFS portrayal operation shall account for axis order. This affects some of the EPSG codes that were commonly used such as ESPG:4326. The current implementation makes sure that coordinates returned to the server for the GetFeature request reect the inverse axis orders for EPSG codes between 4000 and 5000.
468
Test Your WFS Server
Validate the Capabilities Metadata

OK, now that weve got a maple, we have to check the XML capabilities returned by our server to make sure nothing is missing. Using a web browser, access your servers online resource URL to which you add the parameter REQUEST=GetCapabilities to the end, e.g. http://demo.mapserver.org/cgi-bin/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities If everything went well, you should have a complete XML capabilities document. Search it for the word WARNING... MapServer inserts XML comments starting with <!WARNING: in the XML output if it detects missing maple parameters or metadata items. If you notice any warning in your XML output then you have to x all of them before you can register your server with a WFS client, otherwise things are likely not going to work. Note: The SERVICE parameter is required for all WFS requests. When a request happens, it is passed through WMS, WFS, and WCS in MapServer (in that order) until one of the services respond to it.
Test With a GetFeature Request

OK, now that we know that our server can produce a valid XML GetCapabilities response we should test the GetFeature request. Simply adding SERVICE=WFS&VERSION=1.0.0&REQUEST=GetFeature&TYPENAME=yourlayername1,yourlayername2 to your servers URL should return the GML associated with those layers.
http://demo.mapserver.org/cgi-bin/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=getfeature&TYPENAME=continents&MAXF
Test with a Real Client

If you have access to a WFS client, then register your new servers online resource with it and you should be off and running. If you dont have your own WFS client installed already, here are a few pointers: MapServer itself can be used as a WFS client, see the WFS Client HowTo. Quantum GIS is a full GIS package which includes WFS client support. (recommended) Deegree provides a WFS client. uDig can add layers from WMS/WFS servers. The owsview Viewer Client Generator is an online application that allows users to validate WFS Capabilities XML (it does not allow you to view WFS data).
Support for GET and POST Requests

Starting from version 4.2 MapServer supports XML-encoded POST requests and GET requests. The default in MapServer is POST.
9.6. WFS Server
469
Support for Filter Encoding

Starting from version 4.2 MapServer supports Filter Encoding (FE) in WFS GetFeature requests. For more information on the server side of Filter Encoding see the Filter Encoding HowTo.
MapServer WFS Extensions

STARTINDEX In addition to the MAXFEATURES=n keyword, MapServer also supports a STARTINDEX=n keyword in WFS GetFeature requests. This can be used to skip some features in the result set and in combination with MAXFEATURES provides for the ability to use WFS GetFeature to page through results. Note that STARTINDEX=1 means start with the rst feature, skipping none. OUTPUTFORMAT Normally OUTPUTFORMAT should be GML2 for WFS 1.0 and either text/xml; subtype=gml/2.1.2 or text/xml; subtype=gml/3.1.1 for WFS 1.1. However as an extension to the specication, it is also possible to congure MapServer for a variety of other feature output formats. This is discussed in some detail in the OGR Output document.

The following metadata are available in the setup of the WFS Server maple: Note: Each of the metadata below can also be referred to as ows_* instead of wfs_*. MapServer tries the wfs_* metadata rst, and if not found it tries the corresponding ows_* name. Using this reduces the amount of duplication in maples that support multiple OGC interfaces since ows_* metadata can be used almost everywhere for common metadata items shared by multiple OGC interfaces. Web Object Metadata ows_schemas_location (Optional) (Note the name ows_schemas_location and not wfs/_... this is because all OGC Web Services (OWS) use the same metadata) Root of the web tree where the family of OGC WFS XMLSchema les are located. This must be a valid URL where the actual .xsd les are located if you want your WFS output to validate in a validating XML parser. Default is http://schemas.opengis.net. See http://ogc.dmsolutions.ca for an example of a valid schema tree. ows_updatesequence (Optional) The updateSequence parameter can be used for maintaining the consistency of a client cache of the contents of a service metadata document. The parameter value can be an integer, a timestamp in [ISO 8601:2000] format, or any other number or string. wfs_abstract (Optional) Descriptive narrative for more information about the server. WFS TAG Name: Abstract (WFS 1.0.0, sect. 12.3.3) wfs_accessconstraints (Optional) Text describing any access constraints imposed by the service provider on the WFS or data retrieved from this service. WFS TAG Name: Accessconstraints (WFS 1.0.0, sect. 12.3.3) wfs_encoding (Optional) XML encoding for all XML documents returned by the server. The default is ISO-8859-1. wfs_enable_request (or ows_enable_request) Space separated list of requests to enable. The default is none. The following requests can be enabled: GetCapabilities, GetFeature and DescribeFeatureType. A ! in front of a request will disable the request. * enables all requests. Examples: To enable only GetCapabilities and GetFeature:
470
"wfs_enable_request" "GetCapabilities GetFeature"
To enable all requests except GetCapabilities

"wfs_enable_request" "* !GetCapabilities"
wfs_feature_collection Replaces the default name of the feature-containing element (<msFeatureCollection>) with a user-dened value. wfs_fees (Optional) Any fees imposed by the service provider for usage of this service or for data retrieved from the WFS. WFS TAG Name: Fees (WFS 1.0.0, sect. 12.3.3) wfs_getcapabilities_version (Optional) Default version to use for GetCapabilities requests that do not have a version parameter. If not set, the latest supported version will be returned. wfs_keywordlist (Optional) List of words to aid catalog searching. WFS TAG Name: Keyword (WFS 1.0.0, sect. 12.3.3) wfs_maxfeatures (Optional) The number of elements to be returned by the WFS server. This has priority over the maxfeatures parameter passed by the user. If the not set the current behaviour is not changed. Sensible values are integers greater than 0. If 0 is specied, no features will be returned. wfs_namespace_prex (Optional) User dened namespace prex to be used in the response of a WFS GetFeature request. E.g. wfs_namespace_prex someprex. wfs_namespace_uri (Optional) User dened namespace URI to be used in the response of a WFS GetFeature request. e.g. wfs_namespace_uri http://somehost/someurl. wfs_onlineresource (Recommended) The URL prex for HTTP GET requests. WFS TAG Name: Onlineresource (WFS 1.0.0, sect. 12.3.3) wfs_service_onlineresource (Optional) Top-level onlineresource URL. MapServer uses the onlineresource metadata (if provided) in the following order: 1. wfs_service_onlineresource 2. ows_service_onlineresource 3. wfs_onlineresource (or automatically generated URL, see the onlineresource section of this document) wfs_srs (Recommended) The SRS to use for all layers in this server. (e.g. EPSG:4326) See the note about the SRS rules in WFS. wfs_title (Required) Human readable title to identify server. WFS TAG Name: Title (WFS 1.0.0, sect. 12.3.3) Layer Object gml_constants (Optional) A comma delimited list of constants. This option allows you to dene data that are not part of the underlying dataset and add them to the GML output. Many application schemas require constants of one form or another. To specify the value and type of the constants use gml_[item name]_value and gml_[item name]_type.
"gml_constants" "const1,const2" "gml_const1_type" "Character" "gml_const1_value" "abc" "gml_const2_type" "Integer" "gml_const2_value" "999"
9.6. WFS Server
471
gml_exclude_items (Optional) A comma delimited list of items to exclude. As of MapServer 4.6, you can control how many attributes (elds) you expose for your data layer with metadata. The previous behaviour was simply to expose all attributes all of the time. The default is to expose no attributes at all. An example excluding a specic eld would be:
"gml_include_items" "all" "gml_exclude_items" "Phonenum"
gml_featureid (Required for MapServer 4.10) Field to be used for the ID of the feature in the output GML. wfs_featureid or ows_featureid can be specied instead. gml_geometries Provides a name other than the default msGeometry for geometry elements. The value is specied as a string to be used for geometry element names. gml_[name]_occurances MapServer applies default values of 0 and 1, respectively, to the minOccurs and maxOccurs attributes of geometry elements, as can be seen in the preceding examples. To override these defaults, a value is assigned to a gml_[name]_occurances layer metadata item, where again [name] is the string value specied for gml_geometries, and the value is a comma-delimited pair containing the respective lower and upper bounds. gml_[name]_type When employing gml_geometries, it is also necessary to specify the geometry type of the layer. This is accomplished by providing a value for gml_[name]_type, where [name] is the string value specied for gml_geometries, and a value which is one of: point multipoint line multiline polygon multipolygon gml_groups (Optional) A comma delimited list of group names for the layer. gml_[group name]_group (Optional) A comma delimited list of attributes in the group. Here is an example:
"gml_include_items" "all" "gml_groups" "display" "gml_display_group" "Name_e,Name_f"
gml_include_items (Optional) A comma delimited list of items to include, or keyword all. As of MapServer 4.6, you can control how many attributes (elds) you expose for your data layer with this metadata. The previous behaviour was simply to expose all attributes all of the time. You can enable full exposure by using the keyword all, such as:
The new default behaviour is to expose no attributes at all. gml_[item name]_alias (Optional) An alias for an attributes name. The served GML will refer to this attribute by the alias. Here is an example:
472
gml_[item name]_precision (Optional) Species the precision of the indicated eld for formats where this is signicant, such as Shapeles. Precision is the number of decimal places, and is only needed for Real elds. Currently this is only used for OGR based output formats, not the WFS GML2/GML3 output. gml_[item name]_type (Optional) Species ger|Real|Character|Date|Boolean. the type of the attribute. Valid values are Inte-
gml_[item name]_value Used to specify values for gml_constants. gml_[item name]_width (Optional) Species the width of the indicated eld for formats where this is signicant, such as Shapeles. gml_types (Optional) If this eld is auto then some input feature drivers (ie. OGR, POSTGIS, ORACLESPATIAL and native shapeles) will automatically populate the type, width and precision metadata for the layer based on the source le. Currently this is only used for OGR based output formats, not the WFS GML2/GML3 output.
"gml_types" "auto"
gml_xml_items (Optional) A comma delimited list of items that should not be XML-encoded. wfs_abstract Same as wfs_abstract in the Web Object. wfs_extent (Optional) Used for the layers BoundingBox tag for cases where it is impossible (or very inefcient) for MapServer to probe the data source to gure its extents. The value for this metadata is minx miny maxx maxy separated by spaces, with the values in the layers projection units. If wfs_extent is provided then it has priority and MapServer will NOT try to read the source les extents. wfs_enable_request (or ows_enable_request) Space separated list of requests to enable. The default is none. The following requests can be enabled: GetCapabilities, GetFeature and DescribeFeatureType. A ! in front of a request will disable the request. * enables all requests. Examples: To enable only GetCapabilities and GetFeature:
"wfs_enable_request" "GetCapabilities GetFeature"

"wfs_enable_request" "* !GetCapabilities"
wfs_featureid (Required for MapServer 4.10) Field to be used for the ID of the feature in the output GML. gml_featureid or ows_featureid can be specied instead. wfs_getfeature_formatlist (Optional) Comma-separted list of formats that sould be valid for a GetFeature request. If dened, only these formats are advertised through in the Capabilities document. wfs_keywordlist Same as wfs_keywordlist in the Web Object. wfs_metadataurl_format (Optional) The le format of the metadata record. Valid values are XML, SGML, or HTML. The layer metadata wfs_metadataurl_type and wfs_metadataurl_href must also be specied. Refer to section 12.3.5 of the WFS 1.0.0 spec. wfs_metadataurl_href (Optional) The URL to the layers metadata. The layer metadata wfs_metadataurl_type and wfs_metadataurl_format must also be specied. Refer to section 12.3.5 of the WFS 1.0.0 spec. wfs_metadataurl_type (Optional) The standard to which the metadata complies. Currently only two types are valid: TC211 which refers to [ISO 19115], and FGDC which refers to [FGDC CSDGM]. The layer metadata wfs_metadataurl_format and wfs_metadataurl_href must also be specied. Refer to section 12.3.5 of the WFS 1.0.0 spec. wfs_srs If there is no SRS dened at the top-level in the maple then this SRS will be used to advertize this feature type (layer) in the capabilities. See the note about the SRS rules in WFS.
9.6. WFS Server
473
wfs_title Same as wfs_title in the Web Object.
9.6.4 To-do Items and Known Limitations

This is just a basic WFS (read-only): transaction requests are not supported and probably never will given the nature of MapServer. GeoServer or TinyOWS is recommended for those needing WFS-T support. WFS spec. seems to require that features of a given feature type must all be of the same geometry type (point, line, polygon). This works ne for shapeles, but some data source formats supported by MapServer allow mixed geometry types in a single layer and this goes against the WFS spec. Suggestions on how to handle this are welcome (send suggestions to the mapserver-dev mailing list.
9.7 WFS Client

Author Jean-Franois Doyon Contact jdoyon at nrcan.gc.ca Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Last Updated 2010-11-07 Contents WFS Client Introduction Setting up a WFS-client Maple TODO / Known Limitations
9.7.1 Introduction
MapServer can retrieve and display data from a WFS server. The following document explains how to display data from a WFS server using MapServer. A WFS ( Web Feature Service ) publishes feature-level geospatial data to the web. This means that it is possible to use this data as a data source to render a map. In effect, this is not unlike having a shapele accessible over the web, only its not a shapele, its XML-Encoded geospatial data (GML to be exact), including both geometry AND attribute information. WFS-Related Information Although in-depth understanding of WFS and GML is neither necessary nor required in order to implement a MapServer application that reads remote WFS data, it is recommended to at least get aquainted with the concepts and basic functionality of both. Here are the ofcial references (including a newly added OGC workshop with MapServer): OGC Web Feature Service Implementation Specication. Geography Markup Language Implementation Specication. MapServer OGC Web Services Workshop package.
474
Software Requirements In order to enable MapServer to serve WFS, it MUST be compiled against certain libraries: PROJ.4: The reprojection library. Version 4.4.3 or greater is required. GDAL/OGR: I/O support librairies. Version 1.1.8 or greater is required. LibCURL: Used to help MapServer act as an HTTP client. Version 7.10 or greater is required. Please see the MapServer UNIX Compilation and Installation HOWTO for detailed instructions on compiling mapserver with support for these librairies and features. For Windows users, look on the MapServer website to see if there are any binaries available that meet these requirements.
9.7.2 Setting up a WFS-client Maple

Storing Temporary Files You must set the IMAGEPATH parameter in your maple since MapServer uses this directory to store temporary les downloaded from the remote WFS server. Windows users must specify a full path for IMAGEPATH, such as: IMAGEPATH C:/tmp/ms_tmp/
MAP ... WEB IMAGEPATH "/tmp/ms_tmp/" IMAGEURL ... END ... END
WFS Layer A WFS layer is a regular maple layer, which can use CLASS objects, with expressions, etc. As of MapServer 4.4, the suggested method to dene a WFS Client layer is through the CONNECTION parameter and the layers METADATA. The necessary maple parameters are dened below: CONNECTIONTYPE: must be wfs CONNECTION: The URL to the WFS Server. e.g. http://demo.mapserver.org/cgi-bin/wfs? The path to the maple on the WFS server is required if it was required in the GetCapabilities request e.g. you would have to specify the MAP parameter in the CONNECTION for the following server: http://map.ns.ec.gc.ca/MapServer/mapserv.exe?MAP=/mapserver/services/envdat/cong.map &SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities METADATA: The LAYERs must contain a METADATA object with the following parameters: wfs_connectiontimeout (optional): The maximum time to wait for a remote WFS layer to load, set in seconds (default is 30 seconds). This metadata can be added at the layer level so that it affects only that layer, or it can be added at the map level (in the web object) so that it affects all of the layers. Note that wfs_connectiontimeout at the layer level has priority over the map level. wfs_lter: This can be included to include a lter encoding parameter in the getFeature request (see the Filter Encoding Howto for more information on ltering). The content of the wfs_lter is a valid lter encoding element.
9.7. WFS Client
475
... METADATA "wfs_filter" END ...
"<PropertyIsGreaterThan><PropertyName>POP_RANGE</PropertyName> < L i t e r a l >4</ L i t e r a l ></ P r o p e r t y I s G r e
wfs_latlongboundingbox (optional): The bounding box of this layer in geographic coordinates in the format lon_min lat_min lon_max lat_max. If it is set then MapServer will request the layer only when the map view overlaps that bounding box. You normally get this from the servers capabilities output. wfs_maxfeatures (optional): Limit the number of GML features to return. Sensible values are integers greater than 0. If 0 is specied, no features will be returned. wfs_request_method (optional): Can be set to GET to do a Get request to WFS servers that do not support Post requests. The default method in MapServer is Post.
... METADATA "wfs_filter" END ...
"GET"
wfs_typename (required): the <Name> of the layer found in the GetCapabilities. An example GetCapabilities request is: http://demo.mapserver.org/cgibin/wfs?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities wfs_version (required): WFS version, currently 1.0.0 Note: Each of the above metadata can also be referred to as ows_* instead of wfs_*. MapServer tries the wfs_* metadata rst, and if not found it tries the corresponding ows_* name. Using this reduces the amount of duplication in maples that support multiple OGC interfaces since ows_* metadata can be used almost everywhere for common metadata items shared by multiple OGC interfaces. Example WFS Layer
LAYER NAME "continents" TYPE POLYGON STATUS ON CONNECTION "http://demo.mapserver.org/cgi-bin/wfs?" CONNECTIONTYPE WFS METADATA "wfs_typename" "continents" "wfs_version" "1.0.0" "wfs_connectiontimeout" "60" "wfs_maxfeatures" "10" END PROJECTION "init=epsg:4326" END CLASS NAME "Continents" STYLE COLOR 255 128 128 OUTLINECOLOR 96 96 96 END END END # Layer
476
Connection - deprecated As of MapServer v4.4 the method of specifying all of the connection information in the CONNECTION parameter has beendeprecated. The preferred method is mentioned above. If the metadata is not provided, VERSION, SERVICE, and TYPENAME will be fetched from the CONNECTION, as shown below
CONNECTION "http://demo.mapserver.org/cgi-bin/wfs?SERVICE=WFS&VERSION=1.0.0&TYPENAME=continents"
9.7.3 TODO / Known Limitations

1. Temporary WFS (gml) les are written to the IMAGEPATH directory, but this could become a security concern since it makes the raw GML data downloadable by someone who could guess the gml lename. We should consider having a wfs_cache_dir metadata that, if it is set will dene a directory where temp les should be written. The default would still be to use the value of IMAGEPATH if wfs_tmpdir is not set.
9.8 WFS Filter Encoding

Author Jeff McKenna Contact jmckenna at gatewaygeomatics.com Author Yewondwossen Assefa Contact assefa at dmsolutions.ca Last Updated 2010-10-07 Table of Contents WFS Filter Encoding Introduction Currently Supported Features Get and Post Requests Use of Filter Encoding in MapServer Limitations Tests
9.8.1 Introduction
This document describes the procedures for taking advantage of the Filter Encoding (FE) support in WFS GetFeature requests, which was added to MapServer in version 4.2. This document assumes that you are already familiar with the following aspects of MapServer: MapServer application development and setting up .map les. Familiarity with the WFS specication would be an asset. Links to the MapServer WFS documents are included in the next section. Links to SLD-related Information Filter Encoding Implementation Specication.
9.8. WFS Filter Encoding
477
MapServer WFS Client Howto. MapServer WFS Server Howto. MapServer OGC Web Services Workshop. Open GIS Consortium (OGC) home page.
9.8.2 Currently Supported Features

The following table lists the currently supported features for FE. Table 1. Currently Supported Features Feature Set Spatial Capabilities Feature Equals Disjoint Touches Within Overlaps Crosses Intersects Contains DWithin BBOX Scalar Capabilities Logical Operators And Or Not Comparison Operators PropertyIsEqualTo (=) PropertyIsNotEqualTo (<>) PropertyIsLessThan (<) PropertyIsGreaterThan (>) PropertyIsLessThanOrEqualTo (<=) PropertyIsGreaterThanOrEqualTo (>=) PropertyIsLike PropertyIsBetween (range) Units of measure The following units of measure are supported: m or meters km or kilometers NM mi or miles in or inches ft or feet deg or dd px meters kilometers nauticalmiles miles inches feet degree pixels
478
9.8.3 Get and Post Requests

MapServer already has the capability to receive and parse Get requests and URL-encoded Post requests. The ability for MapServer to be able to receive Post requests with XML-encoded information sent in the body of the request has been added. Also, the ability to generate XML-encoded Post requests for WFS layers has been added. Both Get and Post request are now supported for all WFS requests: GetCapabilities GetFeatures DescribeFeatureType Supporting these WFS requests in Post was implemented to keep consistency between all supported WFS requests. When sending requests, the default request method used is Post. To change this behavior, we have introduced a layer level meta data, wfs_request_method, which can be set to GET.
9.8.4 Use of Filter Encoding in MapServer

This section describes how to use FE on both the server and client sides. Server Side To be able to use Filter Encoding, you need to create a valid WFS server using MapServer. Please refer to the WFS Server HOWTO for specics. There is nothing special that should be added to a WFS server for Filter Encoding, but you should note that, when requesting the capabilities of your WFS server, the document returned should contain the supported lters. Here is part of a Capabilities document (note the Filter_Capabilities section):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
<?xml version="1.0" encoding="ISO-8859-1"?> <WFS_Capabilities version="1.0.0" updateSequence="0" xmlns="http://www.opengis.net/wfs" xmlns:ogc  <html> <head>...</head> <body> ... </body> </html>
XML template example:

 <?xml version="1.0" encoding="UTF-8" ?> <rootElement> ... </rootElement>
GeoJSON template example:

// MapServer Template [resultset layer=foo] { "type": "FeatureCollection", "features": [ [feature trim=,] { "type": "Feature", "id": "[id]", "geometry": { "type": "PointLineString", "coordinates": [ { "type": "Point", "coordinates": [[x], [y]] } ] }, "properties": { "description": "[description]", "venue": "[venue]", "year": "[year]" } }, [/feature] ] } [/resultset]
768
MS_MAP_PATTERN Environment Variable The optional MS_MAP_PATTERN environment variable, set via mod_env or other web server equivalents, can be used to specify a Regular Expression that must be matched by all maple paths passed to the mapserv CGI. If MS_MAP_PATTERN is not set then any .map le can be loaded. Example, use Apaches SetEnv directive to restrict maples to the /opt/mapserver/ directory and subdirectories:
SetEnv MS_MAP_PATTERN "^/opt/mapserver/"
MS_MAP_NO_PATH Environment Variable The optional MS_MAP_NO_PATH environment variable can be set to any value via mod_env or other web server equivalents to forbid the use of explicit paths in the map=... URL parameter. Setting MS_MAP_NO_PATH to any value forces the use of the map=<env_variable_name> mechanism in mapserv CGI URLs. If this variable is not set then nothing changes and the mapserv CGI still accepts explicit le paths via the map=... URL parameter. Example, set set MS_MAP_NOPATH and some maple paths in Apaches httpd.conf:
SetEnv MS_MAP_NO_PATH "foo" SetEnv MY_MAPFILE "/opt/mapserver/map1/mymapfile.map"
... and then calls the mapserv CGI must use environment variables for the map=... parameter:
Backwards Compatibility Issues The MAP and SYMBOLSET keywords must be added to any maple and symbolset that did not contain them already. All MapServer templates must be updated to contain the MapServer Template magic string on the rst line. The new environment variables are optional and will have no impact on existing applications that dont use them. Files Impacted mapserver.h maptemplate.c mapserv.c Ticket Id Related security tickets: http://trac.osgeo.org/mapserver/ticket/2939 http://trac.osgeo.org/mapserver/ticket/2941 http://trac.osgeo.org/mapserver/ticket/2942 http://trac.osgeo.org/mapserver/ticket/2943 http://trac.osgeo.org/mapserver/ticket/2944
769
Voting History Adopted on 2009-03-26 with +1 from DanielM, TomK, PericlesN, JeffM, SteveW, AssefaY, SteveL and TamasS.
14.8.56 MS RFC 57: Labeling enhancements: ability to repeat labels along a line/multiline
Date 2009/06/26 Authors Alan Boudreault Contact aboudreault at mapgears.com Last Edited 2009/06/29 Status Adopted (2009/07/21) and Implemented. Version MapServer 6.0 Id $Id: ms-rfc-57.txt 12779 2011-11-16 16:31:27Z dmorissette $ Overview Currently, MapServer draws labels on the longest segment of a linear shape. Even if the shape is a long line or a multiline shape, only one label is drawn. In some cases, the map quality could be highly improved with more labels. This RFC proposes a mechanism to x this by adding the ability to add more labels along long lines or multiline shapes. There are two major enhancements that are proposed. See the Images section to visualize the current and new behaviors. Enhancement 1: Label all the lines in MultiLine shape At the moment, if youve got a MultiLine shape (i.e. a shapeObj with numlines > 1) then only the longest of the Lines is labelled. This is ne in most cases, but in some cases, we may want each individual Line in the MultiLine to get a label. Thats the rst proposed enhancement: make it possible to label all lines in a MultiLine shape. Enhancement 2: Ability to repeat labels along a line At the moment, the label is placed at the center of a line in the case of ANGLE FOLLOW, and at the center of the longest segment of a line in the case of ANGLE AUTO|constant. In the case of very long lines (roads), and especially when using metatiles to render a tile cache, we may want to repeat the label at some interval along the line. Thats the second enhancement: make it possible to repeat the label at a given interval along a line. Technical Solution The way to control this in the maple is to add a LABEL.REPEATDISTANCE parameter. By default this would be turned off and we would keep the current behavior. If REPEATDISTANCE is set to any value > 0 then the labels would be repeated on every line of a multiline shape (enhancement 1 above), and would be repeated multiple times along a given line at an interval of REPEATDISTANCE pixels (item 2 above). In all cases the MINDISTANCE value would still be handled by the label cache so that multiple labels ending up too close to each other for various reasons would be eliminated by the label cache. To achieve better visual effect, here is an outline of the algorithm that applies when REPEATDISTANCE is set:
770
1. Calculate the number of labels candidates (N) that can t in the length of the line. 2. Ensure that N is an odd number. If its even then subtract one to get an odd number. We want an odd number of label candidates along a given line so that there is always one candidate that falls at the center of the line and which will remain in case of collisions. With an even number of candidates, when collisions happen along a line, the remaining labels are usually shifted one way or the other along the line instead of being centered which does not look as good. 3. Calculate the offset between labels and the position of candidates along the line. 4. Insert labels candidates into the label cache in an order that will ensure that the label cache will eliminate the right labels in case of collisions (keep in mind that collisions are still possible since MINDISTANCE remains in effect). We want to give higher priority to the label candidate at the center of the line and lower priority to other candidates as they get further away from the center. Since the label cache order is last in rst out (LIFO), we start by inserting the labels candidates at the extremities of the line into the cache end end with the one at the center, giving it the highest priority. Usage example This example will repeat the labels every 80 pixels on each line of a multiline shape.
MAP ... LABEL REPEATDISTANCE 80 END ... END
Backwards Compatibility Issues There is no backwards compatibility issues. By default the LABEL.REPEATDISTANCE parameter is set to 0, so not applied. Files Impacted mapprimitive.c: Modify the labels placement algorithm maple.c, maplexer.l: new LABEL.REPEATDISTANCE maple keyword mapdraw.c: Modify the way how msPolylineLabel* calls are handled Ticket Id http://trac.osgeo.org/mapserver/ticket/3030 Images Since a picture is worth a thousand words: Repeat distance, visual explanation: http://trac.osgeo.org/mapserver/attachment/ticket/3030/repeat_label.gif Label placement algorithm: http://trac.osgeo.org/mapserver/attachment/ticket/3030/label_algorithm.gif Labels comparison: http://trac.osgeo.org/mapserver/attachment/ticket/3030/label-comparison.jpg
771
Shields comparison: http://trac.osgeo.org/mapserver/attachment/ticket/3030/shield-comparison.jpg Voting History Adopted on 2009/07/21 with +1 from SteveW, DanielM, SteveL, AssefaY, ThomasB and PericlesN.
14.8.57 MS RFC 58: Kml Output

Date 2009/03/01 Authors Dvaid Kana (david.kana at gmail.com) Authors Thomas.Bonfort (thomas.bonfort at gmail.com) Authors Yewondwossen Assefa (yassefa at dmsolutions.ca) Authors Michael Smith (michael.smith at usace.army.mil) Status Planning Version MapServer 6.0 Id $ Purpose This purpose of this RFC is to provide a KML output for MapServer 6.0. The initial work was done by David Kana during the 2009 Google Summer of Code. The main task of the project is the implementation of the KML driver for generating KML output used mainly by Google Earth application. Code for KML rendering is based on new renderer API described in MS RFC 54 First intention was to use original KML library libkml provided by Google but due to its complexity libxml2 already included in MapServer was selected for xml generating. General Functionnality The general idea is to provide an output format that can be set at the map level and allows to generate a kml or kmz output from a MapServer map le. Output can be generated using MapServer cgi (example mode=map) or through a WMS request. Output format The default name of the output format is kml, and this name can be used to set the imagetype parameter in the map le. The format can also be dened in the map le:
OUTPUTFORMAT NAME kml DRIVER "KML" MIMETYPE "application/vnd.google-earth.kml+xml" IMAGEMODE RGB EXTENSION "kml" FORMATOPTION ATTACHMENT=gmap75.kml #name of kml file returned END
772
kmz output will also be supported through the minizip library. Build On windows: there is a ag KML in nmake.opt On Linux: with-kml cairo and agg2 are for now necessary to build with. When agg2 will be nshed, we will drop the cairo link. Driver conguration options Map In terms for Kml object, the MapServer KML output will produce a <Document> element to include all the layers that are part of the MapServer map le. Features supported for the Document are: Document element name visibility open address AdressDetails phoneNumber Snippet description AbstractView TimePrimitive styleURL StyleSelector Supported Yes No No No No No No No No No No Yes MapServer equivalence/Notes
Name in the map le Can be supported if needed. Default is 1 Can be supported if needed. Default is 0 Could be supported for example using ows_address if available
Could be supported using ows_contactvoicetelephone is available
Style element will be supported. All different styles from the layers will be stored here and referenced from the folders using a styleUrl.In addition to the Styles related to features, there is a ListStyle element added at the document level. This allows to control the way folders are presented.See Layers section (styleUrl) setting for more details.
Region Metadata ExtendedData Layers
No No No
Each layer of the MapServer map le will be inside a Kml <Folder> element. Supported Folder elements are:
773
Sup- MapServer equivalence/Notes ported name Yes Name of the layer. If not available the name will be Layer concatenated with the layers index (Layer1) visibility Yes Always set to 1 open No Default is 0 atom:authoratom:linkaddressAddressDetailsphoneNumberSnippet No description No Could be supported using ows_description AbstarctView No TimePrimitive No styleUrl Yes The user can use the kml_folder_display layer or map level metedata to choose a setting. Possible values are check (default), radioFolder, checkOffOnly, checkHideChildren. RegionMetadataExtendedNo Data Each element in the Layer will be inside a Kml <Placemark> element. As described in the Kml reference : A Placemark is a Feature with associated Geometry. In Google Earth, a Placemark appears as a list item in the Places panel. A Placemark with a Point has an icon associated with it that marks a point on the Earth in the 3D viewer. (In the Google Earth 3D viewer, a Point Placemark is the only object you can click or roll over. Other Geometry objects do not have an icon in the 3D viewer. To give the user something to click in the 3D viewer, you would need to create a MultiGeometry object that contains both a Point and the other Geometry object.) For Polygon and Line layers, when a feature is associated with a label, a MultiGeometry element containing a point geometry and the geometry of the feature is created. The point feature will be located in the middle of the polygon or line
<Folder> <name>park</name> <visibility>1</visibility> <styleUrl>#LayerFolder_check</styleUrl> <Placemark> <name>Ellesmere Island National Park Reserve</name> <styleUrl>#style_line_ff787878_w4.0_polygon_ff00ffc8_label_ff0000ff</styleUrl> <MultiGeometry> <Polygon> <outerBoundaryIs> <LinearRing> <coordinates> ... <Point> <coordinates> -70.86810858,82.12291871 </coordinates> </Point> </MultiGeometry> </Placemark> </Folder>
Folder element
Supported Features in the Placemark element are:
774
Palcemark element name visibility open address AddessDetails phoneNumber Snippet description AbstractView TimePrimitive styleUrl StyleSelector Region Metadata Geometry
SupMapServer equivalence/Notes ported Yes No No No No No Label attached with the feature. If there is no label a default name is assigned using the layer name and the shape id (ex. park.1) Is is by default set to true
No Yes
This is a short description the feature. If needed It could be supported. This information is what appears in the description balloon when the user clicks on the feature. The <description> element supports plain text as well as a subset of HTML formatting elements.Two ways of dening the description:
No No Yes No No No Yes Refers to a Style dened in the Document
Depends on the layer type
General notes on layers

Labelcache is turned off on each layer Projection block should be set. If not set It will be assumed that the data is in lat/lon projection (a debug message will be sent to the user: Debug Message 1) Possible to output vector layers as raster using metadata: KML_OUTPUTASRASTER true The user can use the KML_FOLDER_DSIPLAY layer or map level metedata to choose a setting. Possible values are check (default), radioFolder, checkOffOnly, checkHideChildren. The user can use metedata KML_DESCRIPTION or KML_INCLUDE_ITEMS to dene the description attached to each feature. The user can use metedata KML_ALTITUDEMODE to specify how altitude components in the <coordinates> element are interpreted. Possible values are: absolute, relativeToGround, clampToGround. http://code.google.com/apis/kml/documentation/kmlreference.html#altitudemode The user can use metedata KML_EXTRUDE to specify whether to connect the LinearRing to the ground. http://code.google.com/apis/kml/documentation/kmlreference.html#tessellate The user can use metedata KML_TESSELLATE to specify whether to allow the LinearRing to follow the terrain. http://code.google.com/apis/kml/documentation/kmlreference.html#extrude
775
Point Layers
Each layer will be inside a Folder element. Each feature will be represented by a Placemark. The Geometry element for a Point layer would be represented as a Point geometry element in Kml. Supported elements are:
Line Layers
Each layer will be inside a Folder element. Each feature in the layer would be represented by a Placemark. If a label is attached to the line, the Geometry element would be represented as a MultiGeometry that includes a LineString element and a Point element representing the position of the label. If no label is attached to a feature, the Geometry element will be a LineString.
Polygon Layers
Each layer will be inside a Folder element. Each feature will be represented by a Placemark. If a label is attached to the polygon, the Geometry element would be represented as a MultiGeometry that includes a Polygon element and a Point element representing the position of the label.
Annotation Layers
Not supported yet.
Raster Layers
Each layer will be inside a Folder element. A GroundOverlay feature is created for the layer, that includes an href link to the raster image generated and LatLongBox for the extents (map extents). The href is generated using the imagepath and imageurl settings in the map le.
WMS Layers
Not supported yet. Styling As described in Section 4, all different styles from the layers will be stored at the Document level and referenced from the folders using a styleUrl.
776
Point Layers
Point layers will be styled using the IconStyle styling element of kml. An image representing the symbol will be created and referenced from the IconStyle object. If a label is attached to the point, a LabelStyle element will also be used. The LabelStyle will have the color parameter set.
<Style id="style_label_ff0000ff_symbol_star_13.0_ff000000"> <IconStyle> <Icon> <href>>http://localhost/ms_tmp/4beab862_19bc_0.png</href> </Icon> </IconStyle> <LabelStyle> <color>ff0000ff</color> </LabelStyle> </Style>
Line Layers
Line layers will be styled using the LineStyle styling element of kml. Color and width parameters of the LineStyle will be used. If a label is attached to the layer, a LabelStyle element will also be used.
Polygon Layers
Polygon layers will be styled using the PolyStyle styling element of kml. Color parameter of the PolyStyle will be used. If an outline is dened in the map le, an addition LineStyle will be used. If a label is attached to the layer, a LabelStyle element will also be used. Attributes As described in section on Layers, two ways of dening the description: kml_description kml_include_items Coordinate system The map level projection should be set to epsg:4326. If not set, the driver will automatically set it. Layers are expected to have projection block if their projection is different from epsg:4326. Warning and Error Messages When the projection of the map le is not set or is different from a a lat/lon projection, the driver automatically sets the projection to espg:4326. If the map is is debug mode, the following message is sent: KmlRenderer::checkProjection: Maple projection set to epsg:4326 If imagepath and imageurl are not set in the web object, the following message is sent in debug mode: KmlRenderer::startNewLayer: imagepath and imageurl should be set in the web object
777
Testing Development is done in mapserver svn (http://svn.osgeo.org/mapserver/trunk/mapserver/). http://svn.osgeo.org/mapserver/sandbox/davidK/ Documentation Comments from Review period instead of KML_DUMPATTRIBUTES we could possibly use the gml/ows_include_items error messages should be claried for the projection and exact wording should be put in the RFC clearly dene what control the user will have over KML styling (the description balloon, icon styles, and Google Earth TOC) Voting History Adopted 2010/04/08 on the condition that this RFC should be cleaned and upadted with more details. This allows to move the source code from the sand box to trunk with +1 from DanielM, SteveL, TamasS, AssefaY, TomK, JeffM with +0 from SteveW It was initially in
14.8.58 MS RFC 59: Add Variable Binding to Database Connection Types

Author Dan Ducky Little Contact danlittle at yahoo.com Last Edited 2010/02/20 Status Not Adopted Version MapServer 6.0 Id $Id: ms-rfc-59.txt 12779 2011-11-16 16:31:27Z dmorissette $ Purpose Both of the major databases used for spatial data storage with MapServer, PostgreSQL and Oracle, offer the ability to bind variables in SQL statements. The reason they provide variable binding is to prevent needing to resolve datatype issues in the SQL and it prevent SQL injection. Various MapServer applications take untrusted user input from the CGI request and insert it into an SQL statement. This leaves an open vector for SQL injection. This also causes some issues as SQL requires properly escaping strings and integers. Not having to know that ahead of time is useful. Implementation Details There is a need to be able to create the key-value pairings for the various databases in a exible format. For example, Oracle can use a named bind variable but PostgreSQL only accepts numbers. These are some examples of variable binding in PostgreSQL and Oralce to illustrate the differences: PostgreSQL
778
select count(*) from parcels where city_id = $1
Oracle
select count(*) from parcels where city_id = :city_id
Alternatively, Oracle Could Also be Written

select count(*) from parcels where city_id = :1
This need for exibility lends itself well to a hash object and it may be appropriate to create a new block in the LAYER object to support it. For example:
LAYER ... BINDVALS 1 END ... END LAYER ... BINDVALS city_id 1345 END ... END
1345
Backward Compatibility Issues The implementation would be completely optional and not provide any backward compatibility issues. Documentation The mainline documentation will need to add the description of the BINDVALS block and its functionality. Files Impacted maple.c maple.h mappostgis.c maporaclespatial.c mapserver.h maplexer.c maplexer.l
779
Comments from Review period Voting History
14.8.59 MS RFC 60: Labeling enhancement: ability to skip ANGLE FOLLOW labels with too much character overlap
Date 2009/06/26 Authors Daniel Morissette (dmorissette at mapgears.com) Authors Alan Boudreault (aboudreault at mapgears.com) Last Edited 2010-09-02 Status Adopted on 2010-09-23 Version MapServer 6.0 Id $Id: ms-rfc-60.txt 12779 2011-11-16 16:31:27Z dmorissette $ Overview At the moment, ANGLE FOLLOW labels on very sharp curved lines can result in labels on which some characters overlap, resulting in either bad looking or sometimes completely unreadable labels. This RFC proposes a mechanism to detect overlapping characters in ANGLE FOLLOW labels and simply skip the labels, leaving room for other/better labels to fall around the same spot, leading to better looking maps. In ticket #2221, several options were discussed to improve problematic ANGLE FOLLOW labels, including line smoothing, or increasing the spacing between the characters when overlaps are detected, those approaches may have potential but will be dealt with separately (i.e. in their own RFCs). This RFC deals specically with skipping bad labels with too much character overlap and ticket #3523 has been created for it. Background This issue was found as part of the FOSS4G 2010 Benchmarking exercise where one of the layers to render was contours with labels. Weve seen that MapServer did a poor job of labeling some contours with sharp curves using ANGLE FOLLOW, resulting in overlapping characters and unreadable labels. OTOH, we found that GeoServer for instance didnt have this type of problematic labels because it simply detected the overlapping chars and skipped those labels. This is the approach we propose to implement here. Here are two maps of the same area, the rst produced by MapServer with the bad labels and the second by GeoServer without the bad labels: http://trac.osgeo.org/mapserver/attachment/ticket/3523/mapserver-wms.png http://trac.osgeo.org/mapserver/attachment/ticket/3523/geoserver-wms.png Experiments We have found that it is of no use to test the character bboxes for overlap since most of them overlap in normal situations as we can see in the following images: http://trac.osgeo.org/mapserver/attachment/ticket/3523/mapserver-label-boxes.png
780
OTOH we found that we could compare the angles of consecutive characters within a given label and use that as a better indicator of possible overlap. In most cases, a overlap of more than 22.5 degrees is a good threshold to use to decide to skip a given label. The following image shows the same contours in which labels with character overlap larger than 22.5 degrees are skipped: http://trac.osgeo.org/mapserver/attachment/ticket/3523/mapserver-label-with-x.png Here is another example with a street map: http://trac.osgeo.org/mapserver/attachment/ticket/3523/maxoverlapangle-2.png Technical Solution A new MAXOVERLAPANGLE keyword will be added to the LABEL object, whose value is the angle threshold to use in ltering out ANGLE FOLLOW labels in which characters overlap (oating point value in degrees). This ltering will be enabled by default starting with MapServer 6.0. The default MAXOVERLAPANGLE value will be 22.5 degrees, which also matches the default in GeoServer. Users will be free to tune the value up or down depending on the type of data they are dealing with and their tolerance to bad overlap in labels. Setting MAXOVERLAPANGLE == 0 will completely disable ltering of labels based on this criteria, restoring the pre-6.0 behavior. Usage example This feature is enabled by default with a default value of 22.5 degrees, so no maple changes are required to enable it. This example will increase the MAXOVERLAPANGLE to 30 degrees, resulting in less labels being skipped:
MAP ... LABEL ANGLE FOLLOW ... MAXOVERLAPANGLE 30 END ... END
Keep in mind that this option can be combined with REPEATDISTANCE and MINDISTANCE to produce maps with even more labels. Here is an example:
MAP ... LABEL ANGLE FOLLOW ... MAXOVERLAPANGLE 22.5 REPEATDISTANCE 400 MINDISTANCE 100 END ... END
... and here is the resulting contour map with the above settings: http://trac.osgeo.org/mapserver/attachment/ticket/3523/mapserver-collisions-repeatdistance-400-min-100.png
781
Backwards Compatibility Issues This new feature will be enabled by default with a default MAXOVERLAPANGLE value of 22.5 degreees. Existing maples will work without any change, but may end up producing maps with less labels if they contain several bad labels with overlapping characters. It is always possible to come back to the old behavior (disabling ltering) using MAXOVERLAPANGLE 0 or to tune the value up or down to get better results. There is no other backwards compatibility issue. Files Impacted maple.c maple.h mapserver.h maplexer.c maplexer.l mapprimitive.c Ticket Id Main ticket: http://trac.osgeo.org/mapserver/attachment/ticket/3523 See also: http://trac.osgeo.org/mapserver/attachment/ticket/2221 Voting History Adopted on 2010-09-23 with +1 from DanielM, SteveL, FrankW, TomK, PericlesN, ThomasB, SteveW, HowardB, AssefaY, JeffM and TamasS.
14.8.60 MS RFC 61: Enhance MapServer Feature Style Support

Date 2010/09/11 Author Tamas Szekeres Contact szekerest at gmail.com Last Edited $Date: 2011-11-16 08:31:27 -0800 (Wed, 16 Nov 2011) $ Status Adopted (Implemented on 2010.09.29, Documentation added) Id $Id: ms-rfc-61.txt 12779 2011-11-16 16:31:27Z dmorissette $ Description: This RFC proposes a generic implementation for rendering the feature styles retrieved from the various data sources. In this regard we intend to enhance the existing STYLEITEM option which could now be specied for all layer types and not restricted to the OGR driver.
782
Background Currently only the OGR driver supports rendering the styles attached to a feature in the OGR data sources. Theoretically only a few data sources support storing the styles along with the features (like MapInfo, AutoCAD DXF, Microstation DGN), however those styles can easily be transferred to many other data sources as a separate attribute by using the ogr2ogr SQL option as follows:
ogr2ogr -sql "select *, OGR_STYLE from srclayer" "dstlayer" "srclayer"
As a result of the transfer, the OGR style string is added to the destination layer as a separate attribute. We could also rename this attribute during the transfer according to the following example:
ogr2ogr -sql "select *, OGR_STYLE as mystyleattribute from srclayer" "dstlayer" "srclayer"
Currently the style string transferred this way can only be rendered by the MapServer OGR driver, however it would be reasonable to implement such option for all layer types in MapServer. Proposed New Syntax This RFC wouldnt alter the current behaviour of STYLEITEM AUTO option, which causes the driver specic LayerGetAutoStyle vtable method to be called as before. If LayerGetAutoStyle is not implemented by a driver an error message is provided to the user STYLEITEM AUTO not supported for this data source. We will however add support for specifying the feature attribute containing the style string in the form: STYLEITEM mystyleattribute which will tell mapserver to initialize the style from the specied attribute in a generic way. Supported Style Representations We will implement support for either the current mapserver and OGR specic style representations. The mapserver style representation follows the syntax of the STYLE and CLASS entries in the maple format like the following sample:
"STYLE BACKGROUNDCOLOR 128 0 0 COLOR 0 0 208 END"
By specifying the entire CLASS instead of a single style allows to use further options (like setting expressions, label attributes, multiple styles) on a per feature basis. In addition to the mapserver style the OGR style string format will also be supported as described in the following documentation: http://www.gdal.org/ogr/ogr_feature_style.html The actual style format will be identifyed at run-time according to the rst characters of the style strings. This solution will allow to specify multiple style formats within the same layer. Implementation Details In order to implement this enhancement the following changes should be made in the MapServer codebase: 1. Modify msDrawVectorLayer (in mapdraw.cpp) to invoke a new method (msLayerGetFeatureStyle) when STYLEITEM is set for a particular layer. 2. Implement msLayerGetFeatureStyle in maplayer.c which will call either msUpdateStyleFromString, msUpdateClassFromString or the new method: msOGRUpdateStyleFromString according to the actual style format retrieved from the layer.
783
3. Modify msOGRLayerGetAutoStyle (in mapogr.cpp) and extract the bulk of the style initialization into a separate function (msOGRUpdateStyle). We will add a new function (msOGRUpdateStyleFromString) where the style manager will be initialized by using OGRStyleMgr::InitStyleString instead of OGRStyleMgr::InitFromFeature 4. Modify msLayerWhichItems in (maplayer.c) to retrieve the attribute containing the style string specied in the STYLEITEM parameter. By using STYLEITEM AUTO no additional attribute will be retrieved just as before. MapScript Issues Theres no need to modify the MapScript interface since the styleitem parameter has already been exposed. However this attribute will now support the name of the style attribute not only the AUTO value. Files affected To implement the solution the following les would require to be changed: mapserver.h => Add the declaration for msLayerGetFeatureStyle and msOGRUpdateStyleFromString mapogr.cpp => Add msOGRUpdateStyleFromString and msOGRUpdateStyle maplayer.c => Modify msLayerWhichItems and implement msLayerGetFeatureStyle mapdraw.c => Call msLayerGetFeatureStyle in addition to msLayerGetAutoStyle Backwards Compatibilty Issues Currently STYLEITEM AUTO has only been implemented in the OGR driver which overrides LayerGetAutoStyle with a custom implementation. This behaviour would continue to work as previously since the generic implementation would not affect those drivers which provide custom auto style implementation. When using the STYLEITEM mystyleattribute setting, we provide a generic implementation to set the style directly from the feature attribute and no driver specic function will be called. This option will work for all drivers in the same way. Further Considerations In the future we may provide support further style representations in addition to the mapserver and OGR style strings. Each new representation will require a proper (and fast) method to identify the format from the style string itself. Using the OGR style format will require the OGR driver to be compiled in. If we compile MapServer without OGR support and the STYLEITEM mystyleattribute option is used, those features may not be rendered correctly where the actual style format is OGR style string. Bug ID The ticket for RFC-61 (containing the implementation) can be found here. Bug 3544 Voting history +1 from SteveW, DanielM, SteveL, PericlesN, AssefaY, FrankW, ThomasB, HowardB and TamasS
784
14.8.61 MS RFC 62: Support Additional WFS GetFeature Output Formats

Date 2010/10/07 Author Frank Warmerdam Contact [email protected] Last Edited $Date: 2011-11-16 08:31:27 -0800 (Wed, 16 Nov 2011) $ Status Adopted Id $Id: ms-rfc-62.txt 12779 2011-11-16 16:31:27Z dmorissette $ Description: This RFC proposes to extend the ability of the WFS GetFeature request to support formats other than GML. Support for template query formatting (aka RFC 36) is introduced as well as support for output to OGR outputs. Control of output formats is managed via appropriate OUTPUTFORMAT declarations. WFS GetFeature Changes 1) If the WFS OUTPUTFORMAT value is not one of the existing supported values, then the set of outputFormatObjs for the map will be searched for one with a matching name or mime type and an image mode of MS_IMAGEMODE_FEATURE. 2) If the wfs_getfeature_formatlist metadata exists on the layer, it should be a comma delimited list of output formats permitted for this layer. Any other will not be selectable with the OUTPUTFORMAT parameter to GetFeature. The value in this parameter will be the NAME from the OUTPUTFORMAT declaration. As a fallback it may also exist on the map instead of the layer. 3) The existing GML2/GML3 generation support will be retained in essentially its current form within mapwfs.c, but its preamble and postx generation will be moved into separate functions to reduce the gml clutter in the main msWFSGetFeature() function. 4) If an outputFormatObj is being used instead of GML output, it will be generated by a call to msReturnTemplateQuery() which already supports output via the new template engine (RFC 36) as well as call outs for other renderers. WFS GetCapabilities Changes In WFS 1.1.0 mode the GetCapabilities document lists the set of formats allowed for the OUTPUTFORMAT parameter. As part of this development it will be extended to show all the legal output formats for all of the layers (based on wfs_getfeature_formatlist metadata). Note that in WFS 1.0.0 there is no mechanism to discover the format list on a per-layer basis, only the overall list. WFS 1.1.0 supports an overall list and a per-layer list. outputFormatObj A new image mode value will be added, MS_IMAGEMODE_FEATURE, intended to be approriate for formats that are feature oriented, and cannot be meaningfully seen as an image. RFC 36 style template output format declarations will now default to this imagemode. The WFS GetFeature() directive will only support output formats of this image mode. As well a new renderer value, MS_RENDER_WITH_OGR, will be added for OGR output.
785
OGR OUTPUTFORMAT Declarations The OGR renderer will support the following FORMATOPTION declarations: DSCO:* Anything prexed by DSCO: is used as a dataset creation option with the OGR driver. LCO:* Anything prexed by LCO: is used as a layer creation option. FORM=simple/zip/multipart Indicates whether the result should be a simple single le (single), a mime multipart attachment (multipart) or a zip le (zip). zip is the default. STORAGE=memory/lesystem/stream Indicates where the datasource should be stored while being written. le is the default. If memory then it will be created in /vsimem/ - but this is only suitable for drivers supporting VSI*L which we cant easily determine automatically. If le then a temporary directory will be created under the IMAGEPATH were the le(s) will be written and then read back to stream to the client. If stream then the datasource will be created with a name /vsistdout as an attempt to write directly to stdout. Only a few OGR drivers will work properly in this mode (ie. CSV, perhaps kml, gml). COMPRESSION=none/gzip Should gzip compression be applied as the result is returned? This is generally not suitable for use with FORM=zip which is already compressing the image. none is the default. GEOMTYPE=None/Unknown/Point/LineString/Polygon/GeometryCollection/MultiPoint/MultiLineString/MultiPolygon This sets the OGR geometry type of the output layer created. It defaults to Unknown. FILENAME=name Provides a name for the datasource created, default is result.dat. Examples:
OUTPUTFORMAT NAME "CSV" DRIVER "OGR/CSV" MIMETYPE "text/csv" FORMATOPTION "LCO:GEOMETRY=AS_WKT" FORMATOPTION "STORAGE=memory" FORMATOPTION "FORM=simple" FORMATOPTION "FILENAME=result.csv" END OUTPUTFORMAT NAME "OGRGML" DRIVER "OGR/GML" FORMATOPTION "STORAGE=filesystem" FORMATOPTION "FORM=multipart" FORMATOPTION "FILENAME=result.gml" END OUTPUTFORMAT NAME "SHAPEZIP" DRIVER "OGR/ESRI Shapefile" FORMATOPTION "STORAGE=memory" FORMATOPTION "FORM=zip" FORMATOPTION "FILENAME=result.zip" END
786
OGR Renderer Implementation The OGR Renderer will be implemented as the function msOGRWriteFromQuery() in the new le mapogroutput.c. It will create a new OGR datasource based on the information in the output format declaration. It will then create an output layer for each map layer with an active, non-empty query resultcache. Those resultcache shapes will be written. The gml_include_items and gml_exclude_items rules will be used to decide what attributes should be written to the output layers. The gml eld name aliasing mechanism will be supported for OGR output. The gml_[item]_type metadata will be supported for OGR output. The gml_[item]_width (new) metadata will be supported for OGR output. The gml_[item]_precision (new) metadata will be supported for OGR output. When gml_[item]_type metadata is not available then all elds will be created with a type of OFTString. Some features, such as zip output, will only be supported with GDAL/OGR 1.8. These features will be made conditional on the GDAL/OGR version. Geometry Types Supported In MapServer we have POINT, LINE and POLYGON layers which also allow for features with multiple points, lines or polygons. However, in the OGC Simple Feature geometry model used by OGR a point and multipoint layer are quite distinct. Likewise for a LineString and MultiLineString and Polygon an MultiPolygon layer type. When features written to a layer could be of distinct types like this the only way we can create the layer is as geometry type wkbUnknown - that is with no distinct geometry type. Some drivers, such as the OGR shapele driver will establish a specic geometry type based on the rst geometry encountered and discard with an error features of an unsupported geometry type. Some drivers support mixtures of geometry types. The GEOMTYPE FORMATOPTION make it possible to force creation of the layer with a particular geometry type. Attribute Field Denitions For OGR output it is highly desirable to be able to create the output elds with the appropriate datatype, width and precision to reect the source feature denition. In the past for GML output the gml_[item]_type metadata provided a mechanism for users to manually set the eld type in generated GML as there was no supported mechanism to automatically discovered. As a further step, for the OGR output mechanism it is planned to offer support for two new data items, gml_[item]_width and gml_[item]_precision which default the width and precision (number of decimal places) for elds. It is not immediately planned to utilize the eld width and precision information in the GML output though that may prove useful. The width and precision metadata will be parsed by msGMLGetItems() and added into the gmlItemObj structure. Values of 0 indicate a value is not known. gml_types auto Setting the eld type information for all elds in a layer is tedious and error prone. So as a further extension it is intended to support a mechanism to automatically discover eld type, width and precision for some data sources. This will be requested by setting the gml_types metadata item to a value of auto. This will be taken as a clue to
787
implementing layer types to set the various metadata items on the layer to dene the elds type, width and precision when the GetItems layer method is called. As part of the development effort for this RFC support for automatic eld denition discovered will be implemented for OGR, POSTGIS, ORACLE and SHAPEFILE layers. The maintainers of other feature sources can implement support if and when it is convenient. Use of CPL Services Support for WFS OGR output is dependent on USE_OGR being dened. But when available it implies that GDAL/OGR CPL (Common Portability Library) services are also available. These include the virtual le system interface (VSI*L) which provides services like in memory les. The /vsimem services will be used to avoid writing intermediate les to disk if STORAGE=memory, the default conguration. Note that the /vsimem/ service is already being used for WMS layers to avoid having to write images from remove WMS servers to disk, in WCS to avoid writing GDAL-written images to disk and in WMS when using GDAL based outputformats. So this isnt really new. As well, CPL includes support for gzip compression via the /vsigzip virtual lesystem handler. In the past GDAL has not had support for writing zip les; a feature that is very desirable as a mechanism for both compressing and grouping multi-le sets produced by many OGR drivers. As part of the development undertaken for this RFC it is intended that GDAL will be extended with a CPL API for writing zip les, or alternatively a /vsizip/ virtual le system mechanism to write les. Backwards Compatibilty Issues There are no apparent backward compatability issues with this proposal. Its effect is primarily in the situation where new OUTPUTFORMAT values are used in the WFS GetFeature directive. Security Implications There are no apparent security implications to this proposal. Further Considerations It should be noted that the DescribeFeatureType WFS operation will still only support GML formatted description for feature types. A prototype implementation has been developed (by Frank Warmerdam) and is working though it is not quite feature complete, and will need some renement before it can be committed. It is convenient to use the metadata and other structure originally intended to drive GML production but it does cause some confusion when gml metadata items are used to drive non-GML output. Outstanding Issues How do we alter msReturnTemplate() to support the WFS limit on number of features, and offset to the rst feature? What are the implications if queries in other circumstances than WFS GetFeature picking an OGR output format?
788
Testing The msautotest/wxs suite will be extended with a few tests of OGR output. This will likely revolve around producing text output formats so it will be easy to compare to previous results as we do with gml output. Some advanced features, such as zipped output may not be convenient to add regression testing for. Documentation Documentation updates willb be required in the following documents: WFS Server: extensive discussion of new gml items, and how OGR and templated output is invoked and controlled. MapFile Reference: Add information on OGR OUTPUTFORMAT declarations. Ideally we ought to document the new gml_types auto stuff in the document on how to write feature layer implementations, but the only document on this is RFC 3 which does not seem to dene what the functions are supposed to do for the most part. Ticket Id http://trac.osgeo.org/mapserver/ticket/3570 Voting history Adopted on 2010/10/13 with +1 from SteveW, SteveL, AssefaY and FrankW.
14.8.62 MS RFC 63: Built-in OpenLayers map viewer

Date 2010-09-25 Author Daniel Morissette (dmorissette at mapgears.com) Author Alan Boudreault (aboudreault at mapgears.com) Last Edited 2010-10-26 Status Adopted on 2010-10-29. Implementation complete. Version MapServer 6.0 Id $Id: ms-rfc-63.txt 12779 2011-11-16 16:31:27Z dmorissette $ Overview Users often request for a simple way to test maples. This RFC proposes a simple way to preview, test and navigate a maple with MapServer using a built-in OpenLayers based map viewer that will be triggered via the cgi. This is for testing/development purposes only and not for production or deploying full-featured sites. This will use the a built-in openlayers template. It will return a simple html viewer based on OpenLayers. Note that GeoServer already provides a similar functionnality and this is what this RFC was inspired from.
789
Implementation Details In order to implement this enhancement, the following changes should be made in the MapServer codebase: Add a built-in openlayers template. Some new template tags will be needed. These tags will be used to construct the mapserver cgi url. [mapserv_onlineresource] or [protocol] [host] [program] See ticket 3552 for more detail. The template will be triggered using one of the following ways: Using mode=browse&template=openlayers: The viewer will be initialized based on the maple defaults, and some of the traditional mapserv CGI params may also work (such as map size, layer selection, etc.) Using FORMAT=application/openlayers in a WMS GetMap request: The rest of the GetMap parameters would be used to congure the map to view (BBOX, WIDTH, HEIGHT, LAYERS, etc.) Both cases would call the same functions internally to produce a simple OpenLayers viewer with one singletile layer for the whole map with the selected layers. Heres the simple viewer html code that could be used:
<html> <head> <title>MapServer Simple Viewer</title> <script src="http://www.mapserver.org/lib/OpenLayers-ms60.js"></script> </head> <body> <div style="width:[mapwidth]; height:[mapheight]" id="map"></div> <script defer="defer" type="text/javascript"> var map = new OpenLayers.Map(map, {maxExtent: new OpenLayers.Bounds([minx],[miny],[maxx],[maxy]), maxResolution: [cellsize]} ); var mslayer = new OpenLayers.Layer.MapServer( "MapServer Layer", "[mapserv_onlineresource]", {layers: [layers]}, {singleTile: "true", ratio:1} ); map.addLayer(mslayer); map.zoomToMaxExtent(); </script> </body> </html>
OpenLayers Dependency Obviously, this functionnality needs the OpenLayers javascript library. A minimal build will be used and hosted on the MapServer website at http://www.mapserver.org/lib/OpenLayers-ms60.js. The ms60 sufx in the OpenLayersms60.js lename is so that we can increase the version number in the future if/when needed to match the requirements of future releases of MapServer.
790
Users will also be able to use their own OpenLayers library in one of two ways: Using a environment variable: by setting the environment variable MS_OPENLAYERS_JS_URL, MapServer will use that url rather than the default one. Using a CONFIG setting in the maple: by adding the cong variable MS_OPENLAYERS_JS_URL in a maple, MapServer will use that url rather than the default one. Files affected To determine... Further Considerations In the future, we may provide a mechanism to support multiple frameworks and ship generic templates with MapServer. Bug ID The ticket for RFC-63 (containing the implementation) can be found here. Ticket 3549 Ticket 3552 Voting history Adopted on 2010-10-29 with +1 from SteveL, DanielM, JeffK, AssefaY, TomK, TamasS, SteveW and PerryN.
14.8.63 MS RFC 64 - MapServer Expression Parser Overhaul

Date 2010/11/2 Author Steve Lime Contact sdlime at comcast.net Last Edited 2010-11-2 Status Draft Overview This is a draft RFC addressing 1) how the Bison/Yacc parser for logical expressions is implemented and 2) where in the MapServer code the parser can be used. This RFC could have broader impacts on query processing depending on additional changes at the driver level, specically the RDBMS ones. Those changes dont have to occur for this to be a useful addition. A principle motivation for this work is to support OGC lter expressions in a single pass in a driver-independent manner. All of the work detailed here is being prototyped in a sandbox, visit: http://svn.osgeo.org/mapserver/sandbox/sdlime/common-expressions/mapserver <http://svn.osgeo.org/mapserver/sandbox/sdlime/common-expressions/mapserver>
791
Existing Expression Parsing The existing logical expression handling in MapServer works like so: 1. duplicate expression string[[BR]] 2. substitute shape attributes into string (e.g. [name] => Anoka)[[BR]] 3. parse with yyparse() The parser internally calls yylex() for its tokens. Tokens are the smallest pieces of an expression. Advantages its simple and it works Disadvantages limited by substitution to strings, no complex types can be handled have to perform the substitution and tokenize the resulting string for every feature Proposed Technical Changes This RFC proposes a number of technical changes. The core change, however, involved updating the way logical expressions work. Additional features capitalize on this core change to bring additional capabilities to MapServer. Core Parser Update I propose moving to a setup where a logical expression is tokenized once (via our Flex-generated lexer) and then Bison/Yacc parser works through tokens (via a custom version of yylex() dened in mapparser.y) as necessary for each feature. This eliminates the substitution and tokenize steps currently necessary and opens up possibilities for supporting more complex objects in expressions. Basically wed hang a list of tokens off an expressionObj, populate it in msLayerWhichItems() and leverage the tokens as needed in the parser. The following new structs and enums are added to mapserver.h:
enum MS_TOKEN_LOGICAL_ENUM { MS_TOKEN_LOGICAL_AND=100, MS_TOKEN_LOGICAL_OR, MS_TOKEN_LOGICAL_NOT }; enum MS_TOKEN_LITERAL_ENUM { MS_TOKEN_LITERAL_NUMBER=110, MS_TOKEN_LITERAL_STRING, MS_TOKEN_LITERAL_T enum MS_TOKEN_COMPARISON_ENUM { MS_TOKEN_COMPARISON_EQ=120, MS_TOKEN_COMPARISON_NE, MS_TOKEN_COMPARISON_GT, MS_TOKEN_COMPARISON_LT, MS_TOKEN_COMPARISON_RE, MS_TOKEN_COMPARISON_IRE, MS_TOKEN_COMPARISON_IN, MS_TOKEN_COMPARISON_LIKE, MS_TOKEN_COMPARISON_INTERSECTS, MS_TOKEN_COMPARISON_DISJOINT, MS_TOKEN_COMPARISON_TOUCHES, MS_TOKEN MS_TOKEN_COMPARISON_BEYOND, MS_TOKEN_COMPARISON_DWITHIN }; enum MS_TOKEN_FUNCTION_ENUM { MS_TOKEN_FUNCTION_LENGTH=140, MS_TOKEN_FUNCTION_TOSTRING, MS_TOKEN_FUNC enum MS_TOKEN_BINDING_ENUM { MS_TOKEN_BINDING_DOUBLE=150, MS_TOKEN_BINDING_INTEGER, MS_TOKEN_BINDING_ typedef union { double dblval; int intval; char *strval; struct tm tmval; shapeObj *shpval; attributeBindingObj bindval; } tokenValueObj; typedef struct { int token; tokenValueObj tokenval; } tokenObj;
792
Some of these denitions hint at other features that will be detailed later. When we convert an expression string into a series of tokens we also store away the value associated with that token (if necessary). In many cases the token value is a literal (string or number), in other cases its a reference to a feature attribute. In the latter case we use the attributeBindingObj already in use by MapServer to encapsulate the information necessary to quickly access the correct data (typically an item index value). We always have had to make expression data available to the parser (and lexer) via temporary global variables. That would continue to be the case here, although different data are shared in this context. One thing to note is that once an expression is tokenized we no longer have to rely on the ex-generated lexer so, in theory, it should be easier to implement a thread-safe parser should we choose to do so. Extending the Yacc grammar to support spatial operators The mapserver.h denitions above allow for using shapeObjs within the Yacc grammar (we also dene a shapeObj as a new base token type within mapparser.y). There are two types of shape-related tokens: 1) a shape binding, that is, a reference to the geometry being evaluated and 2) shape literals, shapes described as WKT within the expression string. For example:
In the expression: EXPRESSION (fromText(POINT(500000 5000000)) Intersects [shape])
1) fromText(POINT(500000 5000000)) defines a shape literal (the WKT to shapeObj conversion is don 2) [shape] is a shape binding
We can use these tokens in the grammar to implement all of the MapServer supported (via GEOS) logical operators. Note that in the above example fromText() appears as a function operating on a string. This is handled as a special case when tokenizing the string since we only want to do this once. So we create a shape literal based on the enclosed WKT string at this time. Extending the grammar to support spatial functions By supporting the use of more complex objects we can support functions on those objects. We could write:
EXPRESSION (area([shape]) < 100000)
or rely on even more of the GEOS operators. (Note: only the area function is present in the sandbox.) To do this we need to somehow store a shapeObjs scope so that working copies can be freed as appropriate. I would propose adding a int scope to the shapeObj structure denition. Shapes created in the course of expression evaluation would be tagged as having limited scope while literals or bindings would be left alone and presumably destroyed later. This saves having to make copies of shapes which can be expensive. **Context Sensitive Parsing ** We could have done this all along but this would be an opportune time to implement context sensitive parser use. Presently we expect the parser to produce a true or false result, but certainly arent limited to that. The idea is to use the parser to compute values in other situations. Two places are working in the sandbox and are detailed below. Class TEXT Parameter Currently you can write:
CLASS ... TEXT ([area] acres) END
It looks as if the TEXT value is an expression (and it is stored as such) but its not evaluated as one. It would be very useful to treat this as a true expression. This would open up a world of formatting options for drivers that dont support it otherwise (e.g. shapeles). Ticket 2950 <http://trac.osgeo.org/mapserver/ticket/2950> is an example where this would come in handy. Within the sandbox Ive added toString, round and commify functions so that you can write:
793
TEXT (commify(toString([area]*0.000247105381,"%.2f")) + ac)
Which converts area from sq. meters to acres, truncates the result to two decimal places adds commas (213234.123455 => 213,234.12) for crowd pleasing display. To add this support, in addition to grammar changes, we add these declarations to mapserver.h:
enum MS_PARSE_RESULT_TYPE_ENUM { MS_PARSE_RESULT_BOOLEAN, MS_PARSE_RESULT_STRING, MS_PARSE_RESULT_SHA typedef union { int intval; char *strval; shapeObj *shpval; } parseResultObj;
Then in the grammar we set a parse result type and set the result accordingly. One side effect is that we have to dene a standard way to convert numbers to strings when in the string context and simply using %g as a format string for snprintf does wonders to output. Style GEOMTRANSFORM Within the sandbox Ive implemented GEOMTRANSFORMs as expressions as opposed to the original implementation. The parser has also been extended to support the GEOS buffer operator. So you can write:
STYLE GEOMTRANSFORM (buffer([shape], -3)) ... END
This does executes a buffer on the geometry before rendering (see test.buffer.png attachment). Because the GEOMTRANSFORM processing occurs this transformation happens after the feature is converted from map to image coordinates, but the effect is still valuable and the buffer value is given in pixels. In the future we might consider implementing a GEOMTRANSFORM at the layer level so that the transformation is available to all classes and/or styles (and consequently in query modes too). Expression Use Elsewhere Currently the logical expression syntax is also used with REQUIRES/LABELREQUIRES and with rasters. In the REQUIRES/LABELREQUIRES case the code would remain mostly as is wed still do the substitutions bases on layer status, then explicitly tokenize and parse. Since this done at most once per layer theres really no need to do anything more. Rasters present more of a challenge. Wed need to handle them as a special case when tokenizing an expression by dening pixel bindings and then pass a pixel to the parser when evaluating the expression. This should be much, much faster than the current method where each pixel value is converted to a string representation (and then back to a number), especially given the number of pixels often evaluated. Some interesting drawing effects are also possible if you could expose a pixel location to the GEOS operators. For example, one could create a mask showing only pixels within a particular geometry. Query Impact This is where things get interesting. Im proposing adding a new query, msQueryByFilter() that would work off an expression string (this is working in the sandbox). The expression string would still have to be accompanied by an extent parameter. Drivers like shapeles still need to rst apply a bounding box before applying a secondary lter. Other drivers could choose to combine the extent and expression string (more likely the tokens) if they so choose. msQueryByFilter() works much like msQueryByAttributes(). The layer API has been extended to include a prototype, msLayerSupportsCommonFilters(), that allows the driver to say if it could process this common expression format 794 Chapter 14. Development
natively somehow (e.g. via a FILTER and msLayerWhichShapes()/ msLayerNextShape()) or if the expression would need to be applied after msLayerNextShape() is called repeatedly. The shapele and tiled shapele drivers would work natively, as would any driver that uses msEvalExpression(). My hope is that the RDBMS drivers could somehow translate (via the tokens) an expression into their native SQL but if not, we would still be able to use those sources. Backwards Compatibility Issues Surprisingly few. The parser changes would all be transparent to the user. Truly handling TEXT expressions as expressions is a regression, albeit a positive one IMHO. I would also propose a few expression level changes especially around case-insensitive string and regex comparisons within logical expression. I think it makes more sense and is more user friendly to simply dene case-insensitive operators (e.g. EQ and IEQ for straight string equality, and ~ and ~* for regex (modeled after Postgres). The additional operators, functions and parsing contexts are new functionality. A great deal of code would be made obsolete if this were pursued. Much of the OWS lter evaluation would be handled by the msQueryByFilter() function and numerous associated enums, denes, etc... could go away. Grammar summary (bold means new): Logical operators: AND, OR, NOT Comparison operators: =, =*, !=, >, <, >=, <=, ~, ~*, in Spatial comparison operators: intersects, disjoint, touches, overlaps, crosses, within, contains, beyond, dwithin Functions: length, commify, round, tostring Spatial functions: fromtext, area, distance, buffer Security Issues While the bulk of the work is in the bowels of MapServer any change of this magnitude could have unintended consequences. In this case I think the largest risks are buffer overows associated with string operators in the parser and memory leaks. Care would need to be taken in developing a comprehensive set of test cases. Todos 1. The IN operator is in dire need of optimization. 2. All OGC lter operations need to be supported. Bounding box lters in particular have not been looked at. 3. Need LIKE operator code. (e.g. Dr. Dobbs, 9/08, Matching Wildcards: An Algorithm, pp. 37-39) 4. How to handle layer tolerances in msQueryByFilter()? 5. Best way to manage tokens: array, list, tree? Bison/Yacc needs array or list, but both Frank and Paul have referred to trees. (Update: the tokens are now managed as a linked list.) 6. Thread safety... 7. Parser error handling, any errors have basically always been silently ignored. Bug ID #3613
795
Voting history Passed on 12/1/2010 with a +1 from Steve L, Steve W, Perry, Assefa, Tamas.
14.8.64 MS RFC 65 - Single-pass Query Changes for 6.0

Date 2010/11/18 Author Steve Lime Contact sdlime at comcast.net Last Edited 2010-11-18 Status Draft Overview This is a proposal to straighten out issues introduced in 5.6 with the single-pass query support. We probably introduced more change than necessary in hindsight. This RFC represents a simplication of both the C and MapScript APIs. Single-pass query is really a misnomer. Pre-5.6 we would do an initial query (by point, bbox or whatever) to identify candidate shapes and then n small queries to retrieve each result. This was obviously very slow in some cases, particular with the RDBMS drivers. In 5.6 we switched things to basically hold a result set open post query and retain index values to the result set. We still make 2 passes through the results but this is much more efcient than before. Initially we stuck the result set id in the shapeindex attribute of a result (of type resultCacheMemberObj). This index was later used to retrive the feature. Long story short, at the NYC sprint we discovered that some drivers were doing things differently. For Oracle, the result set ID was being passed in the tileindex and the shapeindex contained the global shape id. This was a reasonable thing to do and the PostGIS driver was changed at the sprint to behave the same way. So, the shapeindex contains the overall record index and the tileindex contains the index relative to the query result set. This re-use of the tileindex takes advantage of a an attribute that otherwise would go unused and saves us from further complicating things. Layers that use tile indexes are always le-based and dont suffer (generally) from the performance problems what caused the changes in the rst place. Drivers that Implement msLayerResultsGetShape() Oracle Spatial as msOracleSpatialLayerResultGetShape() PostGIS as msPostGISLayerResultsGetShape() OGR as msOGRLayerResultGetShape() (is identical to msOGRLayerGetShape()) Proposed Techincal Changes Cleaning up the query result portion of the code. 1. Drop the layer API function msLayerResultsGetShape() in favor of msLayerGetShape(). 2. Edit the msLayerGetShape() for drivers that support the result set indexes (now passed as a tile index value) to look for the tile index and if present work of the existing result set. If not, then work of the global id. That is, merge msLayerResultsGetShape() and msLayerGetShape() into a new msLayerGetShape(). 3. Remove resultsGetShape() and getFeature() methods from MapScript.
796
4. Refactor getShape() MapScript method to a) return a shapeObj * like getFeature() does and to b) take a resultCacheMemberObj as input instead of the shape and tile indexes. That simplies the inferface and abstracts the indexes so that we have more exibility moving forward. We wouldnt necessarily have to change the driver implementations to take a resultCacheMemberObj at this point, that could be done later. The refactored getShape() signature would like so (in layer.i for SWIG):
%newobject getShape; shapeObj *getShape(resultCacheMemberObj *r)
Id also like to consider adding another query saving function to MapScript, something like saveQueryFeatures(). This function would write a pre-5.6 query le which consisted of a series of shape and tile indexes. We wouldnt write tile indexes for layers that werent tiled (e.g. layers that didnt have a TILEINDEX). This would restore some usefull funcitonallity that was removed with the 5.6 changes. 1. Add signatures to the two styles of query les (query parameters and query results). This will allow us to write a single loader function and improve security. 2. Add an optional ag to saveQuery() method in MapScript to save the actual query results (e.g. all the resultCacheMemberObjs) instead of just the query parameters. Post RFC a query action in MapScript would look like so:
... my $rect = new mapscript::rectObj(420000, 5120000, 582000, 5200000); $layer->queryByRect($map, $rect); # layer is left open after this operation for(my $i=0; $i<$layer->getNumResults(); $i++) { my $shape = $layer->getShape($layer->getResult($)); # much simpler ... } # save query $map->saveQuery(myquery.qy); # new style (query parameters) $map->saveQuery(myquery.qy, 1); # old style (query feature indexes)
The changes are relatively technically mild. The changes in MapScript are big in that scripts that process query results will need an update. In the end I think thats worth it and this will be more intuitive for users. Bug ID #3647 Voting history Passed with a +1 from Steve L., Tom, Jeff, Steve W., Perry.
14.8.65 MS RFC 66: Better handling of temporary les

Date 2011-01-12 Author Alan Boudreault (aboudreault at mapgears.com) Author Daniel Morissette (dmorissette at mapgears.com) Last Edited 2011-01-12 Status Adopted on 2011-01-17
797
Version MapServer 6.0 Overview At the moment, we write some temporary les in the web-accessible IMAGEPATH directory, this was a poor practice but still okay for some uses in the past (such as writing CONNECTIONTYPE WMS and WFS responses while we process them), but as our need for temporary les increase, we need to ensure that temp les are handled in a proper and safer way. This is a proposal for a better handling of the temporary les. The goal is to add the ability to congure the temporary path. Proposed Solution The les will still be written on the disk. The temporary path can be set by the two following ways: The environment variable MS_TEMPPATH. In the maple
WEB TEMPPATH "/tmp/" END
If the temporary path is not set, the function will try the standard path depending on the OS. /tmp/ for Linux/MAC and C:/temp for Windows. Most of the work will be to modify the msTmpFile function. Purposes of temporary les mapcontext.c: Load an OGC Web Map Context format from an URL mapgdal.c: msSaveImageGDAL() temporary le... memory support implemented mapkmlrenderer.cpp: Merging raster buffer Create icon images Create a zip le with the kml le in it. Using cpl zip api. mapogclter.c: Save maples after lter applied (debug only) mapogcsld.c: Save sld les. Save maples after SLD applied (debug only) Download the symbol referenced by the URL and create a pixmap mapogroutput.c: Create zip le (write from query) Create temporary directory (write from query) mapscript/php/image.c: Save web images mapwfslayer.c: Save gml les mapwmslayer.c: Save temporary request output les
798
Files affected maputil.c: The msTmpFile function. All les that call msTmpFile(). Future enhancement The default behavior could be changed to write the temporary les in memory. This will only be available if MapServer is built with gdal/cpl, which has a virtual io support. This is more efcient than writing les on disk. The virtual le system interface approach will be based on the RFC 62 CPL Services implementation, which already uses memory les. This will need the implementation of a few generic functions (or using msIO* functions) to open/read/write/close a le using the CPL functions when available. A memory le can only be handled by the CPL services. This enhamcement is not a part of the current RFC and will require another RFC. Bug ID The ticket for RFC-66 (containing the implementation) can be found here. Ticket 3354 References RFC 62 CPL Services Ticket 3570 Voting history Adopted on 2011-01-17 with +1 from SteveW, DanielM, FrankW, AssefaY, PericlesN
14.8.66 MS RFC 67: Enable/Disable Layers in OGC Web Services

Date 2011-02-01 Author Alan Boudreault (aboudreault at mapgears.com) Author Daniel Morissette (dmorissette at mapgears.com) Author Yewondwossen Assefa (yassefa at dmsolutions.ca) Last Edited 2011-02-10 Status Adopted on 2010-02-25 and implemented in MapServer 6.0 Version MapServer 6.0
799
Overview At the moment, it is not possible to hide/disable a layer in OGC Web Services. Everybody recognizes the need to be able to hide layers from a given maple from some or all OGC Web Service (OWS) requests. This is a proposal to add the ability to enable/disable layers in OGC Web Services in MapServer. There was also a discussion on this topic in the wiki at http://trac.osgeo.org/mapserver/wiki/HidingLayersInOGCWebServices Use Cases Here are some use cases to demonstrate the need of hiding layers: One needs the ability to hide tileindex layers to all OGC services In a WMS maple where multiple scale-dependent layers are in a common group, we want only the group to appear in GetCapabilities? and not the individual layers. However the layers should not be completely turned off since we want them to be visible in GetMap and queryable with GetFeatureInfo when the group is selected. This use case is common for WMS and may (or may not) apply to other OGC services. One may want to offer a given layer via WMS but not via WFS (or any combination of services). In other words, we need the ability to select in which OGC services a given layer is exposed. The copyright notice (i.e. layer with STATUS DEFAULT) shall not appear in the GetCapabilities output and shall not be queryable. Not about hiding a full layer, but setting the ability to say that one wants a certain layer to return the geometry as gml in a wms-getfeatureinfo-response (at this moment it is never returned) Handle wms_group_layers as real layers (relevant for INSPIRE), but move the rendering part into hidden layers in order to avoid redundant style congurations in the group layer and the sub layer. Proposed Solution The main concern was to minimalize users changes in their maples. It seems that the easier way to go would be to use metadata, as we already do currently for some ows settings. All OWS services will be disabled by default unless enabled at map or layer level. The OWS services can be enabled using the following metadata: ows_enable_request: Apply to all OGC Web Services wms_enable_request: Apply to Web Map Service (WMS) wfs_enable_request: Apply to Web Feature Service (WFS) sos_enable_request: Apply to Sensor Observation Service (SOS) wcs_enable_request: Apply to Web Coverage Service (WCS) The value of the metadata is a list of the requests to enable:
"GetMap GetFeature GetFeatureInfo"
The possible values are the request names for each service type as dened in the corresponding OGC specication. For convenience, there are also two special characters we can use in the requests list: *: Used alone, means all requests !: Placed before a request name, means disable this request !*: Means disable all requests 800 Chapter 14. Development
Examples: Fully enable WMS:

wms_enable_request "*"
Enable WMS, all requests except GetFeatureInfo:

wms_enable_request "* !GetFeatureInfo"
Enable WMS with only GetMap and GetFeatureInfo:

wms_enable_request "GetMap GetFeatureInfo"
Enable any/all OGC Web Service request types:

ows_enable_request "*"
Disable any/all OGC Web Service request types, mostly useful at the layer level to hide a specic layer:
ows_enable_request "!*"
Inheritance A particularity of the proposed solution is the inheritance of settings between the map and the layer level. The settings at the map level apply to all layers unless they are overriden at the layer level. Example: Fully enable WFS for all layers at the map level:
wfs_enable_request "*"
Disable WFS GetFeature request in a specic layer (All other requests will remain enabled):
wfs_enable_request "!GetFeature"
Implementation notes Dont forget to also update the list of supported operations in the GetCapabilities (e.g. dont write out GetFeatureInfo as an operation if wms_enable_request !GetFeatureInfo) Improved handling of wms_layer_group as real layers The current behavior of the wms_layer_group is to provide hierarchy of layers and expose it through the capabilities document. The parent layers do not conatin a <Name> tag, thus are not accessible through the GetMap and GetFeatureInfo requests. With an upgrade of wms_layer_group functionality to use Group parameter to indicate the level of the XPath expression that can be requested (refer to http://trac.osgeo.org/mapserver/ticket/1632), and the addition of the functionality discussed in this RFC, the user will have exibility to congure the map le to show/hide low level layers and to allow or not WMS requests at different levels of the tree hierarchy. This is especially important to be able to support the INSPIRE requirements. Note: This section of the RFC was not implemented and will be done as part of future INSPIRE related enhancements, likely in 6.2.
801
Backwards Compatibilty Issues All OWS services will be disabled by default. This implies that all users will have to modify their maples and add the following line to get their ogc services working as before. :: ows_enable_request * Tickets Main ticket: http://trac.osgeo.org/mapserver/ticket/3703 Related tickets: http://trac.osgeo.org/mapserver/ticket/337 : Need a way to prevent layers from being served via WMS http://trac.osgeo.org/mapserver/ticket/300 : Extend behavior of DUMP maple parameter for GML output http://trac.osgeo.org/mapserver/ticket/1952 : Tileindex Layer and WMS Get Capabilities http://trac.osgeo.org/mapserver/ticket/1632 : support for named group layers using wms_layer_group http://trac.osgeo.org/mapserver/ticket/3608 : INSPIRE related suport http://trac.osgeo.org/mapserver/ticket/3830 : DUMP keyword is made obsolete by RFC 67 Voting history Adopted on 2010-02-25 with +1 from FrankW, PericlesN SteveW, DanielM, AssefaY, JeffM, TamasS
14.8.67 MS RFC 68: Support for combining features from multiple layers
Date 2011/02/10 Author Tamas Szekeres Contact szekerest at gmail.com Last Edited $Date: 2011-11-16 08:31:27 -0800 (Wed, 16 Nov 2011) $ Status Adopted (Implemented on 2011-03-04) Version MapServer 6.0 Id $Id: ms-rfc-68.txt 12779 2011-11-16 16:31:27Z dmorissette $ Description: This RFC proposes an implementation for creating a new data provider (CONNECTIONTYPE=UNION) which provides an option to represent features from multiple layers in a single layer. 1. Overview Today, you can combine multiple les using a tileindex, but only if they have the same attributes, and description. In theory, it might be nice to be able to have multiple source layers that have similar attributes and to be able to combine them into a single layer (being called as union layer) using some compatible subset of the source column attributes so that the combined layer could be treated as a single layer. We could then use this single layer in the same way as any other layer when setting up the classes styles and labels. This layer could also provide the option to use features from multiple layers when conguring clustering support as per MS RFC 69.
802
2. The proposed solution This functionality will be implemented as a separate layer data provider (CONNECTIONTYPE=UNION). The union layer will use the CONNECTION parameter to dene the source layers in the maples as follows:
LAYER CONNECTIONTYPE UNION CONNECTION "layer1,layer2,layer3" # reference to the source layers NAME "union-layer" PROCESSING "ITEMS=itemname1,itemname2,itemname3" ... END LAYER CONNECTIONTYPE OGR NAME layer1 ... END LAYER CONNECTIONTYPE SHAPE NAME layer2 ... END LAYER CONNECTIONTYPE SHAPE NAME layer3 ... END
The new layer data provider will work in the following way: 1. In LayerOpen, it will open all of the source layers specied by the CONNECTION parameter 2. The LayerWhichShapes call will be delegated to the underlying layers and provide the rectangle for the area of interest 3. LayerNextShape will iterate through the layers and call LayerNextShape for the subsequent shapes. The layer index is assigned to the tileindex of the returned shapes. If we nish retrieving the shapes from one layer we start retrieving the features from the next source layer. 4. LayerGetShape will identify the layer based on the tile index and then call LayerGetShape of this layer The union layer and the source layers must have the same geometry type otherwise an error is generated in the LayerOpen call. 2.1 Handling the layer attributes (items) In general the source layers must provide those attributes which are required when rendering the union layer, however the underlying data may contain further attributes, which are not used when fetching the data from the original source. When all attributes are requested (in the query operations) then the union layer will provide only some aggegated attributes (like the layer name or the group name of the source layer the feature belongs to). The set of the items can manually be overridden (and further attributes can be exposed) by using the existing ITEMS processing option. At this stage of the development, the driver will expose the following additional attributes: 1. Combine:SourceLayerName - The name of the source layer the feature belongs to 2. Combine:SourceLayerGroup - The group of the source layer the feature belongs to
803
2.2 Projections It is suggested to use the same projection of the union layer and the source layers. The layer provider will however support transforming the feature positions between the source layers and the union layer. 2.3 Handling classes and styles We can dene the symbology and labelling of the union layers in the same way as any other layer by specifying the classes and styles. In addition we will also support the STYLEITEM AUTO option for the union layer, which is essential if we want to display the features in the same way as with the source layers. The source layers may also use the STYLEITEM AUTO setting if the underlying data source provides that. 2.4 Query processing The driver will create (and operate on) a copy of the source layers which will allow to keep the underlying layers open until the union layer is open. This will provide the single pass query to work in case if the source layer supports it. The queries on the union layer will anyway behave the same like with the other layers. 3. Implementation Details In order to implement this enhancement the following changes should be made in the MapServer codebase: 1. Modify the lexer to interpret the new connection type (UNION). 2. Implement mapunion.c containing the code of the union layer data source. 3.1 Files affected The following les will be modied/created by this RFC:
maplexer.l (maplexer.c) mapserver.h Makefile.vc Makefile.in mapunion.c (new)
3.2 MapScript Issues The connection type of this new layer will be exposed in the MapScript interface. No further impact is taken into account at the moment. 3.3 Backwards Compatibilty Issues This change provides a new functionality with no backwards compatibility issues being considered. 4. Bug ID The ticket for RFC-68 (containing implementation code) can be found here. Bug 3674
804
5. Voting history +1 from SteveW, DanielM, AssefaY, PericlesN, ThomasB, SteveL, TamasS
14.8.68 MS RFC 69: Support for clustering of features in point layers

Date 2011/02/19 Author Tamas Szekeres Contact szekerest at gmail.com Last Edited $Date: 2011-11-16 08:31:27 -0800 (Wed, 16 Nov 2011) $ Status Adopted (Implemented on 2011-03-04) Version MapServer 6.0 Id $Id: ms-rfc-69.txt 12779 2011-11-16 16:31:27Z dmorissette $ Description: This RFC proposes an implementation for clustering multiple features from a layer to single (aggregated) features based on their relative positions. 1. Overview In order to make the maps perspicuous at a given view, we may require to limit the number of the features rendered at neighbouring locations which would normally overlap each other. Currently theres no such mechanism in MapServer which would prevent from the symbols to overlap based on their relative locations. In a feasible solution we should provide rendering the isolated symbols as is, but create new (clustered) features for those symbols that would overlap in a particular scale. According to the example at http://trac.osgeo.org/mapserver/attachment/ticket/3700/cluster.png the number of the features forming the clusters are displayed in the labels for each clustered features. 3. The proposed soution This functionality will be implemented as a separate layer data provider (implemented in mapcluster.c) This provider will be used internally (being invoked in msLayerOpen). The clustering parameters can be specied for each layer type as follows:
LAYER TYPE POINT CONNECTIONTYPE OGR NAME cluster CLUSTER MAXDISTANCE 20 # in pixels REGION ellipse # can be rectangle or ellipse GROUP (expression) # we can define an expression to create separate groups for each value FILTER (expression) # we can define a logical expression to specify the grouping condition END ... END
We can also use multiple classes to display the clustered shapes. The referred example above use the following layer denition:
LAYER CLUSTER MAXDISTANCE 50
805
REGION "rectangle" END LABELITEM "Cluster:FeatureCount" CLASSITEM "zoomcode" CLASS TEMPLATE "query.html" STYLE SYMBOL "image4" END LABEL ... END EXPRESSION "Cluster:Empty" END CLASS TEMPLATE "query.html" STYLE SYMBOL "image1" END LABEL ... END EXPRESSION "5" END CLASS TEMPLATE "query.html" STYLE SYMBOL "image2" END LABEL ... END EXPRESSION "4" END CLASS TEMPLATE "query.html" STYLE COLOR 0 0 255 SYMBOL "image3" END LABEL ... END EXPRESSION "3" END ... END
3.1 The concept of the implementation In the proposed solution msLayerOpen will call the vtable method of the cluster layer provider instead of the original vtable method depending on the existence of the clustering options, something like:
if (layer->cluster.region) return msClusterLayerOpen(layer);
806
In msClusterLayerOpen the data provider will override the vtable functions so that the subsequent LayerWhichShapes/LayerNextShape/LayerClose (and some further) functions will be handled by this provider and not by the original data source. The clustering process itself will be handled in the LayerWhichShapes call. This is the only place where the features are retrieved from the original data source and then cached in the local clustering database (stored in layerinfo). The clustering process itself will be implemented in the following way: 1. For each feature we create a tentative cluster with some aggregate attributes (like the feature count, the average position and the variance) the features are added into a customized quadtree data structure which provides quick access when searching for the neighboring shapes 2. For each feature we will retrieve all the neighbouring shapes (that has already been retrieved earlier) within the specied distance (CLUSTERMAXDISTANCE) and search shape (CLUSTERREGION) by using a quadtree search. We will also inspect the lter and group conditions in each relations, In the related clusters we update the feature count (n) average positions (avg) and the variance (var) for each intersecting clusters by using the following recursive formula:
n = n + 1 avg(n) = avg(n-1) * (n-1) / n + x(n) / n var(n) = var(n-1) * (n-1) / n + pow2(x(n) - avg(n)) / (n-1)
3. In a second turn we evaluate the tentative clusters based on their feature count and the offset of the average position related to the initial position and the variance. The best ranking clusters will be identied by minimizing the position offset and the variance. The individual features (having rank=0) will be retrieved rst in this approach. 4. The best ranking clusters will be added to the nalization list (in layerinfo) and the nalized clusters (and the related features) will be removed from the quadtree as well. 5. Based on the nalized features we update the average position and the variance of the affected clusters which are still exist in the quadtree. 6. Repeat from #4 until we have features in the quadtree. In LayerNextShape the features are served from the nalization list which is preserved until the layer is open. In LayerClose the vtable of the layer will be restored to the original methods (by calling msInitializeVirtualTable) 3.2 Handling the feature attributes (items) The clustered layer itself will provide the following aggregate attributes: 1) Cluster:FeatureCount - count of the features in the clustered shape 1) Cluster:Group - The group value of the cluster (to which the group expression is evaluated) These attributes can be used to congure the labels of the features and can also be used in expressions. The clustered layer will also support to get further attributes from the original data source as referenced in the LAYER conguration. The ITEMS processing option can be used to specify additional attributes from the source layer according to the user preference. If we retrieve the original attributes then the layer provider will provide only those values which are equal for each shapes in the cluster. The other values are set to Cluster:Empty. In the future we may probably extend this by implementing aggregate functions to dene the attributes, like min([attributename]) or max([attributename]) 3.3 Handling classes and styles We can dene the symbology and labelling of the clustered layers in the same way as any other layer by specifying the classes and styles. STYLEITEM AUTO is not considered to be supported at this phase.
807
3.4 Query processing In the query operations the clustered features are retrieved as single shapes with the attribute set as specied in the ITEMS processing option. The clustered features are preserved until the layer is open, so the single pass query approach is provided by this driver. 4. Implementation Details In order to implement this enhancement the following changes should be made in the MapServer codebase: 1. Modify the lexer to contain the new keywords 2. Create a new struct (clusterObj) to contain the clustering parameters and implement the handlers (initCluster, loadCluster, freeCluster, writeCluster) in maple.c 2. Modify maplayer.c to invoke msClusterlayerOpen based on the existence of the clustering parameters, and make msLayerWhichItems aware of the group and lter expressions 3. Implement mapcluster.c containing the code of the cluster layer data provider 4.1 Files affected The following les will be modied/created by this RFC:
Makefile.vc Makefile.in maplayer.c (msLayerOpen and msLayerWhichItems) mapfile.c, mapfile.h(for handling clusterObj) mapcluster.c (the code of the new data provider) cluster.i (SWIG interface file to expose clusterObj) maplexer.l mapserver.h
4.2 MapScript Issues The new object (clusterObj) will be exposed to the mapscript interface. 4.3 Backwards Compatibilty Issues This change provides a new functionality with no backwards compatibility issues being considered. 5. Bug ID The ticket for RFC-69 (containing implementation code) can be found here. Bug 3700 6. Voting history +1 from SteveL, AssefaY, ThomasB and TamasS
808
14.8.69 MS RFC 70: Integration of TinyOWS in MapServer project

Date 2011/04/14 Author Olivier Courtin Contact olivier dot courtin at oslandia.com Last Edited $Date: 2011-11-16 08:31:27 -0800 (Wed, 16 Nov 2011) $ Status Adopted Version MapServer 6.2 Id $Id: ms-rfc-70.txt 12779 2011-11-16 16:31:27Z dmorissette $ Description: This RFC proposes a TinyOWS integration under MapServer Umbrella. 1. Overview TinyOWS is often used tiedly with MapServer to provide WFS-T functionnalities. The idea here is to bring to end user a more integrated solution through a single MapFile conguration le for both apps. And also to put TinyOWS under MapServer project umbrella, to increase again its usage. 2. The proposed solution 2.1 Keeping the cycle release independant MapServer and TinyOWS cycles releases are kept independant. 2.2 SVN On SVN, TinyOWS location should be: svn.osgeo.org/mapserver/trunk/tinyows svn.osgeo.org/mapserver/tags/tinyows-1.0.0 2.3 A common MapFile as cong le Aim is to be able to have for end user a single cong le, so a text MapFile. TinyOWS trunk already able to deal with MapFile to retrieve all its cong stuff, through a dedicaded MapFile lexer. The idea, in a quite near future, is to bring an LibMapFile API and so to allow others apps to use MapFile as a single cong le way. It will simplify the maintenace of such a parser, and avoid possibility to have distincts behaviours. This LibMapFile API, is out of the scope of this RFC. svn.osgeo.org/mapserver/branches/tinyows-1.0
809
2.4 Perspective: Packaged build system We could imagine from this RFC (and also with related mod_geocache integration), to provide an meta package with a single congure/make/make install, managing the build of MapServer, TinyOWS and mod_geocache at once. These meta package build system is also out ot the scope of this RFC. 3. Solution Details 3.0 Naming TinyOWS will be called: MapServer TinyOWS (To keep the previous quite known name, and to give it the MapServer prex) 3.1 Documentation Move TinyOWS trac Wiki documentation to RST syntax. Also need to enhance documentation to provide more examples and a comprehensive user manual, or at least something like and FAQ. Native English writers, and guys who are not (yet) familiar with the project are really appreciated on helping on this. 3.2 Licence TinyOWS already use MIT licence, as MapServer does. Copyright holders (Barbara Philippot and Olivier Courtin) should be kept on existing TinyOWS les. 3.3 Tickets TinyOWS use a Trac, but as only few tickets are still open, an efcient way is just to create them back in MapServer one. Should imply a new component in MapServer Trac, called: TinyOWS. 3.4 Developpers & PSC Olivier Courtin should entered in MapServer PSC and have commit access to MapServer trunk, and will keep (at least for a while) the lead in the TinyOWS development stuff. Others TinyOWS devs are already involved in MapServer project (Assefa, Alan). One aim is also to have more MapServer devs ready to look at the code, and committing patches. The MapServer PSC will become the ultimate decision autorithy for MapServer TinyOWS module. 3.5 SVN Import TinyOWS trunk and 1.0 (coming) branch should be imported in MapServer SVN. Previous commit history will be kept on the old TinyOWS SVN, for a while.
810
3.6 Code Convention We have to call astyle on the whole code, to make it MapServer compliant: astyle style=kr unpad=paren indent=spaces=2 3.7 Redirections tinyows.org domain could be redirected to the coming MapServer TinyOWS documentation pages. Mailings lists: tinyows-dev and tinyows-users should be stopped and news discussions should occurs to relevant mapserver ones. 3.8 Project Maturity If we compare to MapServer, TinyOWS is a far more younger project, with a really small dev team. So it imply that decision, and administrative part of the project must be kept lightweight, at least for a while. So RFC must be used only for big and majors changes, all the others common stuff, should be done only with simple Trac tickets, like: Correct/improve OGC standard compliancy, and interoperability Bug and security xes Minor feature enhancement Small code refactoring Unit tests policy ... 4. TinyOWS Code Review 4.1 Code Origin All C code was written from scratch by TinyOWS devs, so should not be a real problem. For XSD Schema coming from OGC, and OGC CITE Unit tests: Ofcial OGC LICENSE is descripted here: http://www.opengeospatial.org/ogc/document it allows public diffusion, but not to modify it. 4.2 Code Quality All code compile without any warning on commons Unix like platforms, with ags: -ansi -pedantic -Wall All OGC CITE Units tests are valgrinded, (no error, no memory leak), but its doesnt cover all the code branchs. Some units tests like Cunit could be helpfull in a future. 4.3 Security Audit No external security audit never been perform on the code. The main inherent risk is SQL Injection. Somes checks already have been done with automated tools like sqlmap, but will need to be improved to adjust to some WFS-T and FE peculiar uses cases. (No security hole ve been found on TinyOWS trunk with sqlmap) 14.8. Request for Comments 811
4.4 OGC WFS-T compliancy Implementation of WFS 1.0.0, WFS 1.1.0, FE 1.0.0 and FE 1.1.0. Basic and Transactional prole, SF-0. (No Xlink nor Lock prole implemented) TinyOWS trunk on OGC CITE unit test: WFS-T 1.1.0 (r4) : 559 Passed / 0 Failed WFS-T 1.0.0 (r3) : 398 Passed / 0 Failed 4.5 External Dependancies LibXML2 >= 2.6.20 (and libxml2 trunk http://tinyows.org/trac/wiki/LibxmlSchemaGmlBug) PostgreSQL >= 8.1.0 PostGIS >= 1.5.0 FastCGI is optional (but recommended) 4.6 MapFile notions not yet addressed Some Maple concepts are not yet present in TinyOWS: Only PostGIS CONNECTIONTYPE are handled TinyOWS dont pretend to support right now all the WFS parameters available in MapFile But on the other hand you should be able to congure every part of TinyOWS from MapFile Each CONNECTION string value in layers must be the same. MapFile PROJECTION content is not parsed, so use explicit wfs_srs MapFile LAYER/FILTER is not parsed. Defaults values are TinyOWS ones, even for common properties shared by both apps. TinyOWS dont use DATA element from MapFile, so you have to use tinyows_table (and tinyows_schema if needed) in each layer. If DUMP is not set to TRUE on a layer both Read and Write access are shutdown for these layer 4.7 Build system TinyOWS use like MapServer autoconf and Makele to build stuff. 4.8 Roadmap and vision General aim is to keep the application the faster alternative available for WFS-T, as compliant as possible to next OGC and INSPIRE standards, and of course robust. Mains future works area are (they will imply futures RFC, just here to notice them): Add new export formats (Shapele, KML...) Apache Module support More exhaustive unit tests policy (not only OGC ones) 812 Chapter 14. Development to avoid GML XSD Schema, see:
More consistent behaviour and conguration directives for both TinyOWS and MS. Oracle Spatial support Application Schema support WFS 2.0 and INSPIRE compliancy 5. Voting history Passed with +1s from Steve L., Steve W., Tamas, Dan, Howard, Assefa, Thomas and Tom on 8/19/2011.
14.8.70 MS RFC 71: Integration of Mod-Geocache in the MapServer project

Date 2011/05/20 Author Thomas Bonfort Contact tbonfort at terriscope dot fr Last Edited $Date: 2011-11-16 08:31:27 -0800 (Wed, 16 Nov 2011) $ Status Adopted Version MapServer 7.0 Id $Id: ms-rfc-71.txt 12779 2011-11-16 16:31:27Z dmorissette $ Description: This RFC proposes the integration of mod-geocache in the MapServer project. 1. Overview Mod-Geocache is a recent tile caching solution that runs in front of a WMS server either as an apache module or as a fastCGI executable. It can connect to any WMS compliant server, but given its source code language and the roots of its core developpers, it would make sense to integrate it tightly with the mapserver project, to ease conguration for end-users, and provide higher QA through a larger development team. 1.1 The need for a tile caching solution The usage patterns of web mapping have evolved in the past years and is more and more based around the pregeneration of image tiles rather than the direct creation of images from the source data. Current solutions for serving map tiles include TileCache, MapProxy, and GeoWebCache, all of which accomplish the task successfully but in a manner that does not integrate ideally with the MapServer project: They do not run native code, which incurs a minor performance overhead, and can be an inconvenience in the context of high performance data dissemination They do not share their conguration with the server they are proxying, as such requiring users to duplicate conguration variables and metadata. In the case of the python servers, they require an additional component to function (mod-python, mod-wsgi, or fastcgi wrapper) that is cumbersome to congure on non-mainstream platforms. The GIL is also a bottleneck for multi-threaded servers for the requests that require an access to native code (notably related to image format encoding and decoding). NIH ;) and as it can be written in C, why not use that directly?
813
1.2 The mod-geocache project Mod-geocache is a recent project (oct 2010), distributed under an apache license. It is written in plain C using a semi object-oriented architecture (heavy use of structure inheritance and function pointers). Being primarily aimed at being run as an apache module, it is very fast as it runs as native code inside the process treating the http requests (there is no overhead in cgi process creation or fastcgi ipc). Its list of features include: services WMS, WMTS, TMS, VirtualEarth/Bing and GoogleMaps requests ability to respond to untiled WMS requests by merging tiles from the cache or forwarding them to the wms source responds to WMS/WMTS GetFeatureInfo requests (forwarded to source service) KML superoverlay generation data provided by WMS backends (GDAL supported sources planned) experimental memcached cache congurable metatiling, with inter-process/inter-thread locking and synchronization to avoid overloading the source wms when the tiles are not seeded yet. on-the-y tile merging for combining multiple tiles into a single image image post-processing (recompression and quantization) when arriving from a backend interprets and produces cache control headers: Last-Modied, If-Modied-Since, Expires multithreaded seeding utility ability to add a custom watermark on stored tiles can produce a fastCGI executable for using with other webservers than apache congurable symbolic linking of blank tiles to gain disk storage congurable error reporting: plain http error code, textual message, or empty (blank) image ability to specify vendor params or dimensions to be forwarded to the WMS backend (and build a cache that takes these parameters into account) rule-based proxying of non-tile requests to (an)other server(s), e.g. for WFS, WFS-T, etc... 1.3 Integration Overview Mod-geocache will be modied to read its conguration from a supplied maple rather than its own xml le as is now. When used in conjunction with mapserver and tinyOWS, it will act as a proxy to these servers: if an incoming request corresponds to soemthing that can be served from cache it will act as a classic tile server, if not it will proxy the request to mapserver or tinyows (or any other OGC compliant server). 2. Governance 2.1 Finding a Name Mod-Geocache as a name is a poor choice, and should be changed during the integration with MapServer. The author has no predened idea as to what the solution should be named, ideas will be greatly appreciated.
814
2.2 Release Cycles Mod-geocache being a recent project, it is undergoing development at a pace that is incompatible with the MapServer release cycle. As such, the release cycle of mod-geocache will be at rst decoupled from the mapserver one: modgeocache releases will be produced any time there is a mapserver release, but also at a faster rate if needed. 2.3 Source Code Location The mod-geocache code will be located in a subdirectory of the mapserver repository, e.g. trunk/mapserver/modgeocache 2.4 RFCs and Decision Process In the early steps of the integration, development surrounding the core of mod-geocache unrelated to the MapServer project will be undertaken in a relaxed manner compared to the RFC based decision taking that prevails for MapServer. All non trivial changes to the mod-geocache core will be announced for discussion on the mapserver-dev mailing list, but will not undergo the rfc voting process unless there is a direct interaction with the actual mapserver functionality. Once the transitionning phase of the integration has been completed, the development on mod-geocache will follow the traditional RFC based decision taking. 2.5 Licence The apache licence of mod-geocache will be switched to the same licence as MapServer. 2.6 Tickets Mod-geocache is hosted on google-code and uses its integrated issue tracking system. The MapServer trac instance will be used, once a dedicated component for mod-geocache has been created. There are currently no open bugs to transition to the MapServer trac. The open feature enhancements will be manually migrated to the MapServer trac instance. 2.7 SVN Import Mod-geocache trunk will be imported in MapServer SVN. Previous commit history will be kept on the old google-code SVN, for a while. 3 A common MapFile as cong le 3.1 LibMaple API A LibMapFile API will be created out of the mapserver source tree, and will require some refactoring of header and source les. The MapServer API itself should not be changed as the refactoring will mostly concern moving some functions and declarations out into separate les.
815
3.2 Conguration Directives New keywords and/or metadata will have to be added to the mapserver parser. The exact syntax and the extent of the conguration keywords must be discussed as part of the commenting period of this RFC. The conguration directives being rather extensive, a tradeoff will have to be found between ease of syntax and similarity to actual mapserver keywords. 3.3 Documentation The mod-geocache documentation is rather sparse, and consists essentially of a commented conguration le. There will have to be an effort to add documentation to the main mapserver doc site, and to migrate the few wiki pages from the google-code hosting. 4. Code Review 4.1 Code Origin All C code was written from scratch by myself and Steve Woodbridge, so should not be a real problem. Image io functions based on libpng/libjpeg have been vastly inspired by the same functions in mapserver, and could be merged together in a second phase. 4.2 Code Quality Similar to MapServer. 4.3 Security Audit No external security audit has been performed on the code. Being run as an apache module that potentially receives untrusted data, security has always been a concern when writing the code, but Im no security expert. 4.4 External Dependancies libcurl (required) apr(required) / apr-util(optional) libpng (required) libjpeg (required) pcre (optional) OGR (for the seeder, optional) libcairo (optional, required for servicing GetMap requests built from cached tiles) FastCGI (optional) 4.5 Build system mod-geocache like MapServer uses autoconf (without automake) and Makeles to build stuff.
816
4.6 IP and Patent overview Patent review is left as an exercise for users coming from countries with a broken patent system ;) 5. Voting history Passed with +1s from Steve L., Steve W., Tamas, Dan, Howard, Assefa, Thomas and Tom on 8/19/2011.
14.8.71 MS RFC 72: Layer and Label-Level Geomtransforms

Date 2011/06/27 Author Steve Lime Contact sdlime at comcast.net Last Edited $Date: 2011-11-16 08:31:27 -0800 (Wed, 16 Nov 2011) $ Status Draft Version MapServer 6.2 Id $Id: ms-rfc-72.txt 12779 2011-11-16 16:31:27Z dmorissette $ 1. Overview MapServer 6.0 introduced the concept of geometry expressions within a styleObj-geomtransform. For example, one could write:
STYLE GEOMTRANSFORM (buffer([shape], -5) ... END
This would cause a buffer operation to be run on the shape before being rendered with a given style. This is useful for certain cartographic effects but is limited in a couple of ways: 1. it operates in pixel space (e.g. once a feature is converted from map to image coordinates) 2. the resulting shape can only be used with a single style so it is not efcient to, say, create a complex rendering of a buffered feature 3. it is not possible to query transformed features 4. the resulting shape cannot be used in any labeling operations 2. The proposed solution This RFC proposes to extend GEOMTRANSFORMS to both the layer and label contexts. Basically the same keyword and syntax would become valid in other objects. For a layer the tranformation would be applied to geometries as they are read from a datasource and before any drawing or query operations. As a result it would be much more efcient to perform complex rendering of a transformed shape. In addition the resulting shape would also be queryable in a consistent manner since the transformation would be independent of the map being drawn (e.g. scale, bounding box, etc...).
817
For a label the transformation would be applied ahead label point computation, in pixel coordinates much like the current style implementation. This will allow for effects like labeling the inside edge of a polygon or perhaps creating a curved labels within a polygon. These operations are computationaly intensive so users would need to understand the performance impact but as tiling becomes the norm this is less an issue. 3. Implementation Details For layers I propose adding a check to the functions msLayerGetShape() and msLayerNextShape() to conditionally apply the GEOMSTRANFORM before returning the shape. The resulting shape would contain all the attributes of the parent. (Note: one potential issue is that certain operations might affect the bounding box used to select candidate shapes via msLayerWhichShapes()). For labels the check and transformation would be applied within the msLayerDrawShape() function. Small changes to the logical expression grammar (mapparser.y) and expression tokenizer would need to be made. 3.1 Files affected The following les will be modied/created by this RFC:
mapfile.c (layer/label read/write) mapdraw.c (update msDrawShape()) maplayer.c (update msLayerGetShape(), msLayerNextShape(), msLayerWhichItems() and msLayerGetTokens()) maplexer.l (add additional GEOS operators, in trunk only buffer and difference are currently implemen mapparser.y (extend the grammar)
3.2 MapScript Issues These are just expressionObjs so functions to get/set them already exist. 3.3 Security Issues Care must be take to avoid memory leaks associated with the production of the transformed shapes. It would make sense to allow runtime substitution like is done with layer lters and class expressions. Simlarly, validation patterns would be required. 3.4 Backwards Compatibilty Issues This change provides a new functionality with no backwards compatibility issues being considered. 4. Bug ID None assigned. See related ticket #3871. 5. Voting history None
818
14.8.72 MS RFC 73: Improved SVG symbols support

Date 2011/05/19 Authors Zak James (zjames at dmsolutions.ca) Authors Yewondwossen Assefa (yassefa at dmsolutions.ca) Last Edited 2011/05/19 Status Proposed Version MapServer 6.2 Id $Id: ms-rfc-73.txt 12842 2011-12-04 13:55:35Z assefa $ Overview The SVG format offers several advantages over existing mapserver symbol types but existing support is limited. We propose the implementation of complete support using the libsvg-cairo library, part of the cairo project. Technical Solution All renderers will be extended with an added supports_svg ag, set to 0 for all but the cairo renderer. When an SVG symbol is requested, other renderers will trigger a call to msRenderSVGToPixmap which will parse the referenced svg le (using libsvg-cairo) and render the svg into the symbols pixmapbuffer using cairo. After this operation, normal pixmap symbol handling will be used. For the cairo renderer, the renderSVGSymbolCairo function will use libsvg-cairo to parse the symbol, but will then use the cairo api to render the symbol directly. Congure.in will be modied to detect the with-libsvg-cairo congure option and dene USE_LIBSVG_CAIRO. Existing Partial Implementation If this rfc is adopted the existing SVG symbol code (see http://trac.osgeo.org/mapserver/ticket/3343) would be superceeded and would be removed. The proposed implementation will reuse the existing changes to the parser but the approach for reading and rendering the symbols would be different. It will use an existing SVG parser which includes a more complete SVG implementation and will pass through the SVG instructions directly in the case of a cairo (pdf or postscript) outputformat to improve quality. Additionally, this version will pre-scale and rotate the SVG before rasterizing with agg to avoid bitmap artifacts. Usage example
SYMBOL NAME "svgsymbol" TYPE SVG IMAGE "/path/to/symbol.svg" END
... once dened, the symbol is used within the maple like any other.
819
Backwards Compatibility Issues There are no compatibility issues with existing maples. The SVG symbol type is already allowed within a SYMBOLSET. SVG Symbol support will be disabled by default. Enabling it will require installation of the libsvg-cairo library available from * http://cairographics.org/snapshots/libsvg-cairo-0.1.6.tar.gz Affected Files mapserver.h mapdraw.c mapdummyrenderer.c maprendering.c mapsymbol.c mapsymbol.h mapcairo.c mapagg.cpp congure.in Ticket Id http://trac.osgeo.org/mapserver/ticket/3671 Voting History +1 from DanielM, SteveW, ThomasB, SteveL, MichaelS, AssefaY
14.8.73 MS RFC 74: Includes from non-le connections (eg Databases)

Date 2011/07/29 Author Michael Smith, Daniel Morissette Contact michael.smith at usace.army.mil, dmorissette at mapgears.com Last Edited 09/17/2011 Status Draft Version MapServer 6.2 1. Overview MapServer 4.10 introduced the concept of INCLUDE les. When this directive is encountered parsing switches to the included le immediately. As a result the included le can be comprised of any valid maple syntax. For example, one could write:
INCLUDE myLayer.map
820
This would include the contents in the maple at runtime. It would be useful to extend this to allow INCLUDEs from database connections. This provides another mechanism for dynamic maples without requiring MapScript. 2. The proposed solution This RFC proposes to add a new DBINCLUDE maple item. This item would have a number of associated maple items including: CONNECTIONTYPE CONNECTION DATA INCLUDEITEM FILTER METADATA And be closed with an END keyword. Example
D B INCLUDE CONNECTIONTYPE oraclespatial CONNECTION "%uid%/%passwd%@tns_connection" DATA "MAPLAYER_TABLE_NAME" I N C L U D E I T E M "MAPLAYERS" FILTER "condition=%layer_variable%" METADATA "layer_variable_validation_pattern" "^condition1|condition2$" END END
The only new item, beside the DBINCLUDE keyword, is the INCLUDEITEM. It denes the attribute from which to to pull the layers denitions. It functions similarly to TILEITEM. Allowed CONNECTIONTYPEs would include OGR, POSTGIS, ORACLESPATIAL. An Example of the query would be select maplayers from maplayer_table_name where condition = condition1; The content of the MAPLAYERS content would be strings to include in the maple just and INCLUDE would do. One difference is that the query could return a resultset of strings to add, and would be equivalent to N INCLUDE statements. 2.5 Use Cases A common use case is providing a custom classed layer for an individual. Currently, this is very difcult to do without MapScript. For example, in a table one column would be username and the second column would be the layer class level text string. Table 14.2: Example Table user jeff daniel steve class CLASS Name Jeff Layer STYLE OUTLINECOLOR 255 0 0 SYMBOL 0 COLOR 0 0 255 END END CLASS Name Daniel Layer STYLE OUTLINECOLOR 122 180 200 SYMBOL 0 END END CLASS Name Steve Layer EXPRESSION type=brewery STYLE SYMBOL 0 COLOR 0 255 255 WIDTH 4 END END
Another common case is dynamically classifying a layer as the data changes. With SQL, a text string can be calculated on the y from the data itself, by looking at the DISTINCT values of a dataset to generate the classes that will be used to display that data.
821
3. Implementation Details 3.1 Files affected The following les will be modied/created by this RFC:
mapfile.c mapogr.c maplayer.c maplexer.l mapparser.y
3.2 MapScript Issues There should be no mapscript issues, this is really only useful for CGI 3.3 Security Issues The security issues should be the same as any existing database connection layer 3.4 Backwards Compatibility Issues This change provides a new functionality with no backwards compatibility issues being considered. 4. Bug ID None assigned. 5. Voting history None
14.8.74 MS RFC 75: INSPIRE view service support

Date 2011/07/01 Author Stefan Leopold (stefan.leopold at reex.at) Author Stephan Meissl (stephan.meissl at eox.at) Last Edited 2011/09/17 Status Proposed Version MapServer 6.2 Id $Id: ms-rfc-75.txt 12779 2011-11-16 16:31:27Z dmorissette $
822
1. Overview In order to achieve INSPIRE view service compliance, several enhancements need to be implemented in MapServer to support the specication : Activation of INSPIRE support (two scenarios) Multi-language support for certain capabilities elds Provision of INSPIRE specic metadata Style section for root layer and possibly existing group layers This RFC aggregates and extends the already provided ideas/solutions regarding INSPIRE view service support. 2. Activation of INSPIRE support INSPIRE specic metadata can either be referenced in an external INSPIRE service metadata document (scenario 1) or can be directly embedded in the capabilities document (scenario 2). MapServer needs to support both scenarios. As suggested in Ticket 3608, activation of the corresponding scenario for INSPIRE support takes place in the WEB.METADATA section of the maple through wms_inspire_capabilities. If activated, the corresponding INSPIRE namespace as well as appropriate validation warnings are generated in the capabilities document. Scenario 1 - activate INSPIRE support using a reference to external service metadata
WEB METADATA "wms_inspire_capabilities" "url" ... END END
Scenario 2 - activate INSPIRE support using embedded service metadata

WEB METADATA "wms_inspire_capabilities" "embed" ... END END
3. Multi-language support for certain capabilities elds
INSPIRE requires multi-language support and requests a list of all supported languages as well as the default language in the ca wms_title wms_abstract wms_rootlayer_title wms_rootlayer_abstract wms_group_title wms_group_abstract as well as language dependent reference data like DATA road_eng 14.8. Request for Comments 823
CONNECTION db_ger need to be provided in the requested language. If the language is not supported (or no language parameter is present), the default language has to be used. As suggested in Ticket 3608, all supported languages are specied as comma separated list (rst language is default) through wms_inspire_languages in the WEB.METADATA section of the maple. This language parameter is also added to the onlineresource in the GetCapabilites output.
WEB METADATA ... "wms_inspire_languages" "eng,ger" ... END END
#first default, values according ISO 639-
To address the second issue, different options regarding implementation were evaluated. For language specic metadata values, a key extension method is applied.
WEB METADATA ... "wms_title_eng" "myservicetitle" "wms_title_ger" "myservicetitleger" "wms_abstract" "mylayerabstract" "wms_abstract_ger" "mylayerabstractger" ... END END
#to test fallback
For language dependent reference data, a similar approach like the runtime-substitution feature of MapServer has been followed (only DATA and CONNECTION values with %language% are substituted).
... LAYER NAME TN.RoadTransportNetwork.RoadLink DATA "road_%language%" ... END ...
If the language is not supported (or no language parameter is present), the default language is substituted. 4. Provision of INSPIRE specic metadata Depending on the scenario, additional metadata information is required to support the specication. The INSPIRE related elds are provided below: Scenario 1 - INSPIRE related elds using referenced external service metadata
WEB METADATA "wms_inspire_capabilities" "url" "wms_inspire_languages" "eng,ger" #first default, values according ISO 639"wms_metadataurl_href" "http://INSPIRE.service/metadata" "wms_metadataurl_format" "application/vnd.ogc.csw.capabilities.response_xml" "wms_inspire_keyword" "infoMapAccessService" #value according "classification of spati "wms_title" "myservicetitle" "wms_abstract" "myabstract"
824
"wms_fees" "conditions unknown" "wms_accessconstraints" "None" "wms_contactorganization" "MapServer" "wms_contactposition" "owner" ... END END
#value either "no conditions apply"|defau #value according ISO 19115 (MD_Restrictio #responsible organisation #responsible organisation, value accordin
Scenario 2 - INSPIRE related elds using embedded service metadata

WEB METADATA "wms_inspire_capabilities" "embed" "wms_inspire_languages" "eng,ger" "wms_inspire_temporal_reference" "2011-09-19" "wms_inspire_mpoc_name" "mympocname" "wms_inspire_mpoc_email" "[email protected]" "wms_inspire_metadatadate" "2011-09-19" "wms_inspire_keyword" "infoMapAccessService" "wms_title" "myservicetitle" "wms_abstract" "myabstract" "wms_fees" "conditions unknown" "wms_accessconstraints" "None" "wms_contactorganization" "MapServer" "wms_contactposition" "owner" ... END END
#first default, values according ISO 639#date of last revision, value according Y #point of contact #point of contact #value according YYYY-MM-DD #value according "classification of spati
#value either "no conditions apply"|defau #value according ISO 19115 (MD_Restrictio #responsible organisation #responsible organisation, value accordin
Notes: several elds require certain values, these values are not validated by MapServer itself, instead a manual validation against the INSPIRE schemas or the WMS INSPIRE tester is recommended only one keyword through wms_inspire_keyword is supported, a possibly provided wms_keywordlist will be ignored as suggested in this document regarding scenario 2, <inspire_common:ResourceType> is always set to service and <inspire_common:SpatialDataServiceType> is always set to view, both values cant be altered through the maple conformity is always set to not evaluated, based on the latest INSPIRE Metadata Implementing Rules (page 7), a specication document, the specication date and a specication URI or URL need to be provided for degree conformant/not conformant, which is currently not implemented 5. Style section for root layer and possibly existing group layers For regular layers, the concept of GROUP and CLASSGROUP can be used to to set the layer style name to the according value. Additionally - as suggested in Ticket 3850 - the layer style titles can be overwritten through wms_style_<stylename>_title and the layer style legendURLs through wms_style_<stylename>_legendurl_* (width, height, format and href need to be provided).
... LAYER NAME TN.RoadTransportNetwork.RoadLink DATA "road" METADATA "wms_title_eng" "Transport networks: Road Link" "wms_title_ger" "Verkehrsnetze: Strassensegment"
825
... "wms_style_inspire_common:DEFAULT_title" "mylayerstyletitle" #style title "wms_style_inspire_common:DEFAULT_legendurl_width" "85" #override style legendu "wms_style_inspire_common:DEFAULT_legendurl_height" "40" "wms_style_inspire_common:DEFAULT_legendurl_format" "image/png" "wms_style_inspire_common:DEFAULT_legendurl_href" "http://path/to/onlineresource...roadlink" END ... END ... CLASSGROUP "inspire_common:DEFAULT" CLASSITEM "NAME_E" CLASS NAME "myclass1" GROUP "inspire_common:DEFAULT" EXPRESSION "Trans-Canada Highway" COLOR 255 0 0 END CLASS NAME "myclass2" GROUP "inspire_common:DEFAULT" COLOR 0 255 0 END ...
The following method is suggested to support (customizable) style sections in the root layer use wms_style_name in the WEB.METADATA section to add a style section to the root layer use wms_style_title to override the style title (optional) use wms_style_legendurl_* to override width, heigth, format and href of the legendURL (optional) and possibly existing group layers use wms_group_style_name in the rst corresponding LAYER.METADATA section to add a style section to the group layer use wms_group_style_title to override the style title (optional) use wms_group_style_legendurl_* to override width, heigth, format and href of the legendURL (optional)
...
WEB METADATA ... "wms_style_name" "inspire_common:DEFAULT" #style name "wms_style_title" "myroadarealayerstyletitle" #style title "wms_style_legendurl_width" "85" #override style legendu "wms_style_legendurl_height" "40" "wms_style_legendurl_format" "image/png" "wms_style_legendurl_href" "http://path/to/onlineresource...roadarea" END END LAYER NAME TN.RailTransportNetwork.RailwayLink GROUP TN.CommonTransportElements.TransportLink DATA "road" METADATA
826
"wms_group_title_eng" "Transport networks: Generic Transport Link" "wms_group_title_ger" "Verkehrsnetze: Generisches Verkehrssegment" "wms_group_abstract" "mygenerictransportlinklayerabstract" #to test fallback "wms_group_abstract_ger" "mygenerictransportlinklayerabstract" "wms_group_style_name" "inspire_common:DEFAULT" #style name "wms_group_style_title" "mygenerictransportlinklayerstyletitle" #style title "wms_group_style_legendurl_width" "85" #override style legendu "wms_group_style_legendurl_height" "40" "wms_group_style_legendurl_format" "image/png" "wms_group_style_legendurl_href" "http://path/to/onlineresource...generictransportlink" "wms_title_eng" "Transport networks: Railway Link" "wms_title_ger" "Verkehrsnetze: Eisenbahnverbindung" "wms_abstract" "myrailwaylinklayerabstract" #to test fallback "wms_abstract_ger" "myrailwaylinklayerabstractger" ... END ... END ...
Provided that ability, 3 levels of hierarchy can be achieved as done in the example maples.
TN.RoadTransportNetwork.RoadArea +--- TN.RoadTransportNetwork.RoadLink +--- TN.CommonTransportElements.TransportLink +--- TN.RailTransportNetwork.RailwayLink +--- TN.AirTransportNetwork.AirLink
6. Implementation details In order to implement this enhancement, the following changes need to be implemented in the MapServer codebase: 1. get language from request and validate it 2. detect if INSPIRE support is activated, if so add corresponding namespace 3. output extended capabilitities with language list and INSPIRE specic metadata (depending on scenario 1 or 2) 4. add language parameter to onlineresource in output 5. consider key extension based on language (e.g. wms_title_eng) when deriving metadata from the mapobject, use fallback with no extension (e.g. wms_title) 6. override style titles and legendURLs if specied in maple (e.g. wms_style_<stylename>_title) 7. add warnings for missing but mandatory INSPIRE specic metadata 6.1 Files affected The following les will be affected by this RFC:
mapows.c/mapows.h [N] [N] [N] [N] [N] [N] MS_DLL_EXPORT const char *msOWSLookupMetadataWithLanguage(.., const char *validated_language) MS_DLL_EXPORT char *msOWSGetOnlineResource2(.., const char *validated_language) MS_DLL_EXPORT char **msOWSGetInspireLanguageList(..) MS_DLL_EXPORT char *msOWSGetInspireLanguage(.., const char *requested_language) MS_DLL_EXPORT int msOWSPrintInspireCommonExtendedCapabilities(..) int msOWSPrintInspireCommonMetadata(..)
827
[N] [C] [N] [C] [N] [C] [C]
int int int int int int int
msOWSPrintInspireCommonLanguages(..) msOWSPrintEncodeMetadata(..) msOWSPrintEncodeMetadata2(.., const char *validated_language) msOWSPrintGroupMetadata(..) msOWSPrintGroupMetadata2(.., const char *validated_language) msOWSPrintMetadataList(..) msOWSPrintEncodeMetadataList(..)
mapwms.c [S] [S] [S] [S] [C] [C] [C] [C] [C] [C] int msDumpLayer(.., const char *validated_language) void msWMSPrintNestedGroups(.., const char *validated_language) int msWMSGetCapabilities(.., const char *requested_language) int msWMSGetMap(.., const char *requested_language) int msWMSLoadGetMapParams(..) int msWMSLoadGetMapParams(..) int msWMSDescribeLayer(..) int msWMSGetLegendGraphic(..) int msWMSGetStyles(..) int msWMSDispatch(..)
[C] function changed [N] new function [S] signature of function also changed 6.2 MapScript issues This change provides new functionality with no MapScript issues being considered. 6.3 Backwards compatibility issues This change provides new functionality with no backwards compatibility issues being considered. 7. Solution The code for this RFC can be found in the inspire_soc2011 sandbox. Incorporated tickets: Ticket 3608: INSPIRE related support Ticket 3850: allow to dene a title for styles and possibility to override autogenerated legendurl href Related (but currently not addressed) tickets: Ticket 1632: support for named group layers using wms_layer_group 8. Tests 2 example maples were created for testing purposes: maple INSPIRE scenario1 maple INSPIRE scenario2
828
The GetCapabilites responses with these maples validate against the INSPIRE schemas as well as the WMS INSPIRE tester without warnings/errors. 9. Voting history ...
14.8.75 MS RFC 76: Adding License Metadata to Output Images

Date 2011/06/22 Author Paul Ramsey Contact pramsey at opengeo.org Last Edited $Date: 2011-11-16 08:31:27 -0800 (Wed, 16 Nov 2011) $ Status Draft Version MapServer 6.2 Id $Id: ms-rfc-76.txt 12779 2011-11-16 16:31:27Z dmorissette $ Description: This RFC proposes allowing XML metadata information to be embedded in MapServer output images. The use case is for any organization producing maps that wishes to embed licensing and authorship information directly in the output images. 1. Overview XMP is the extensible metadata platform 1 which allows the embedding of metadata information across a wide range of document and image formats: PNG, GIF, JPEG, PDF, etc. XMP was originally developed by Adobe 2 and is supported across their product line. It is now being increasingly included in other standards for metadata embedding and supported by tools for viewing image information (e.g. exiftools). Creative Commons has standards for using XMP to embed commons licensing 3 in images and other document, including a specic Creative Commons schema. One of the challenges of advertising licensing and terms of use in WMS and other web mapping services is that the terms are usually advertised separately from the actual content. So a WMS service might specify terms in the Capabilities document, but the images themselves will be unmarked. Embedding license URLs inside the images themselves using a standard markup allows organizations to be unambiguous about the conditions attached to their content. The goal of this change is to allow users the option of embedding XMP metadata in their MapServer output using an open source XMP utility library. 2. Proposed Technical Change 2.1. Driver Support libexempi 4 provides a standard C interface for reading and writing XMP content from multiple image formats. One limitation of libexempi (and all other XMP libraries we investigated) is that it only works on existing les. That means that any image that is going to be tagged with metadata must be written to the disk rst. Fortunately the GDAL image
1 2 3 4
http://en.wikipedia.org/wiki/Extensible_Metadata_Platform http://www.adobe.com/products/xmp/overview.html http://wiki.creativecommons.org/XMP http://libopenraw.freedesktop.org/wiki/Exempi
829
driver already writes a temporary le to disk for every request, so we propose that XMP support be available only when using the GDAL output format driver. For example:
OUTPUTFORMAT NAME png DRIVER "GDAL/PNG" MIMETYPE "image/png" IMAGEMODE RGB EXTENSION "png" END
The XMP metadata embedding code will be called in msSaveImageGDAL just before the temporary le is streamed back to the client. 2.2. Map File Conguration Metadata information is written per-image, so will be stored in the METADATA block of the WEB object in the MAP le. The metadata key for each tag will have the form xmp_<namespace>_<tag>, so for example: xmp_dc_Title, for the Dublin Core title. Eight namespaces will be supported by default: meta which is the standard XMP tag set 5 cc which is the Creative Commons tag set 6 dc which is the Dublin Core tag set 7 rights which is the standard XMP Rights tag set 8 exif which is the EXIF tags set 9 tiff which is the TIFF tags set 10 crs which is the Photoshop Camera Raw Schema 11 photoshop which is the Photoshop tag set 12 Within those names spaces, users can specify any tag. The MapServer code will not check that the tags are valid for the namespace, that responsibility will fall to the user. Here are some examples of common tags within the default name spaces: xmp_rights_Marked (true or false) indicates whether the image is copyright (true) or public domain (false) xmp_rights_WebStatement (URL) link to a page that explains the terms and conditions under which the image is licensed xmp_rights_UsageTerms (text) a description of the terms and conditions under which the image is licensed. To save image space and ensure licensing is kept up to date, the web statement is preferred over the usage terms.
5 6 7 8 9 10 11 12
http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/XMP.html#xmp http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/XMP.html#cc http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/XMP.html#dc http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/XMP.html#xmpRights http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/XMP.html#exif http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/XMP.html#tiff http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/XMP.html#crs http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/XMP.html#photoshop
830
xmp_cc_License (URL) link to the creative commons license that applies to this image (e.g. http://creativecommons.org/licenses/by-sa/2.0/) xmp_cc_MorePermissions (URL) link to a page describing additional terms and conditions beyond the CC terms xmp_cc_AttributionURL (URL) link to a page of information about the author or organization that produced the content xmp_cc_AttributionName (text) name of the person or organization that produced the content xmp_dc_Title (text) title of the image xmp_dc_Rights (text) textual description of the license regime of the image Here is an example of setting tags using the default namespaces:
WEB METADATA "xmp_rights_Marked" "true" "xmp_cc_License" "http://creativecommons.org/licenses/by-sa/2.0/" "xmp_cc_AttributionURL" "http://www.landgate.wa.gov.au/corporate.nsf/web/About+Us" "xmp_cc_AttributionName" "Landgate (landgate.wa.gov.au)" END END
Users can also set up their own namespace and insert tags into it. The user must include a metadata key of the form xmp_<name>_namespace with a namespace URI as the value. Once the namespace is declared, other metadata keys of the usual form can be used to insert tags into the XMP. Here is an example of setting tags using a custom namespace:
WEB METADATA "xmp_lightroom_namespace" "http://ns.adobe.com/lightroom/1.0/" "xmp_lightroom_PrivateRTKInfo" "My Information Here" END END
2.3. Build Conguration XMP metadata support will require the presence of the libexempi library. The library must be requested or pointed to directly to using the with-exempi=[yes|no|path] conguration option in the ./congure script. If with-exempi is not used, XMP metadata support will not be enabled. 3. Implementation Details 3.1. Files Affected The following les will be modied for this RFC:
Makefile.in Makefile.vc mapgdal.c mapxmp.c configure.in configure
831
3.2. Bug ID The ticket for RFC 76 (containing proof-of-concept code) can be found here (Bug 3932). 3.3. Documentation Documentation for this feature will be added to the appropriate map le documentation (metadata keywords) and a separate howto document will be created explaining XMP metadata. 4. Enhancements The ability to use the XMP facility across output drivers would be desirable, but that requires intercepting the image before it is streamed to the user and writing it to disk to allow the exempi library to alter the metadata. For GDAL, the write-to-disk step is already part of the output sequence. Other drivers stream their output direct to stdout. 5. Voting history :: Steve Lime +1 Daniel Morissette +1 Frank Warmerdam +1 Assefa Yewondwossen Howard Butler +1 Steve Woodbridge +1 Perry Nacionales +1 Tom Kralidis +1 Jeff McKenna Umberto Nicoletti Tamas Szekeres +0 Thomas Bonfort +1 Olivier Courtin +1 Mike Smith
14.8.76 MS RFC 77: Support for Multiple Label Objects Within a Class
Date 2011/10/01 Author Steve Lime, Thomas Bonfort Contact sdlime at comcast.net, Last Edited $Date: 2011-12-15 06:04:35 -0800 (Thu, 15 Dec 2011) $ Status Draft Version MapServer 6.2 Id $Id: ms-rfc-77.txt 12900 2011-12-15 14:04:35Z sdlime $ 1. Overview This RFC proposes allowing for the denition of multiple label objects within a class. There are a number of use cases where this would be valuable. Adding text below a label with different styling, for example an alternate name shown in italics. Labeling roads with multiple shields and road numbers. Supporting complex meteorlogical rendering where many values are placed around a point.
832
Presently only very limited support for these use cases is available. Basically you have to draw layers multiple times and place each piece of text separately. This is inefcient and does not allow for group label collision avoidance. 2. Proposed Technical Change 2.1 Core Object Changes Class object would need to support multiple label objects in much the same way as the they support multiple styles. In fact, implementation would follow the styleObj pattern. A key requirement is that the extra labels be self-contained, that is, they need to allow for the denition of label text and conditional display within the labelObj. To do this we propose adding the following attributes to labelObjs: expression text These attributes behave just like their classObj equivalents. In addition a labelObj will be extended with several attributes that will be used to hold per-feature values in the context of the label cache. They are: labeltext (string to be drawn) labelpoly (bounding box shapeObj) A labels labeltext will be set according to the following order: label text (new for this RFC) class text layer labelitem shape text A NULL labeltext value means that label will not be rendered. The labelCacheMemberObj will also require change. First, it needs to support multiple labelObjs (see point and polygon discussion below) just like the styles attribute currently supported. A label counter will be added as well. Because the text to be drawn will be carried in a label the text attribute can be removed. 2.2 Label Rendering Changes 2.2.1 Point and Polygon Labels The labeling of point and polygon features is done based on a single computed label point. Multiple labels within a classObj will be applied to a label point as a group, that is, all label text must be placed successfully or the entire group will not be drawn. In this case a new function, msAddLabelGroup() is available to add all labels from a class to the label cache as a single element. The bounding shapes for a group of labels will be considered as one for collision avoidance computations. Positioning of the multiple labels will be done as always- relative to the label point using label->position and/or label->offset. In the case of a label group label priority will be taken from the rst label dened in a class. Scale thresholds will be taken into account when a labels labeltext value is assigned (outside of the cache population code). A label that is out of scale will set labeltext=NULL and will not be drawn although others in the group could be. Label cache collision functions will have to be updated to look a multiple labels, especially the code that looks for duplicate text (label->mindistance).
833
2.2.2 Line Labels Line labeling is another story. Lines often are used to derive curved text, repeating labels and sometimes both. In this case a single feature might contribute dozens of labels to the cache. It is impractical to handle these as we would a point or polygon with a single label point. A for more common use will be to label a line with multiple names or a combination of a name and a marker/text combination. So, for line labels the approach will be to simply use the existing cache faciliities but with an added loop to process multiple labels if available. It might be possible in the future to use the label grouping described above in certain instances but that is outside the scope of this work. 2.3 MapScript Class objects will need support for labels similar to what is in place for styles. Presently a classObj supports the following methods: getStyle, insertStyle, removeStyle, moveStyleUp and moveStyleDown. We propose adding label equivalents for the rst three (label order is not nearly as import as style order). It is not quite clear how classes label is dened/manipulated from within MapScript. In SWIG/MapScript labels are marked as immutable. Further work needs to be done to understand if this represents a regression. 3. Implementation Details 3.1. Files Affected Change lis limited primarly to: mapserver.h: core structure changes maple.c: read/write/initialize changes mapdraw.c: siginicant changes to msDrawShape() and msDrawLabelCache() maplabel.c: changes to msAddLabel() and addition of msAddLabelGroup() maplayer.c: changes to msLayerWhichItems() to account for label text and expressions maputil.c: changes to msBindLayerToShape() and msShapeGetAnnotation() Various other les see small changes with the change in classObj from one label to many. 3.2 Documentation Changes Documentation for classObj (labels 0 .. n) and labelObj (text and expression) will need update. MapScript documentation will need changes to document new methods and the change in object hierarchy between classes and labels. Maple XML le must be changed as well. A number of test cases will added to the MapServer regression test suiteall existing labeling tests should continue to be useful. 3.3 Bug ID #4127. Work is underway in a sandbox (http://svn.osgeo.org/mapserver/sandbox/sdlime/rfc-77/). 4. Backwards Compatibility At the maple level there are no issues, existing maples should run without any change. It is possible that this could introduce regressions within MapScript although the scope is not fully known. 834 Chapter 14. Development
4.1 Relationship to Other Outstanding Label Bugs #1355 - None, test is valid w/grouped labels too. #2866 - None. #2981 - None. #3009 - None. #3044 - This is already supported (ticket can be closed). #3335 - Styles are supported for each additional label. #3675 - This will be adressed by this RFC. Label content will be dened by the new TEXT attribute. 5. Enhancements Although beyond the scope of this work it seems that some interesting work related to the relative placement of grouped labels might be possible. For example, it could be useful to dene positions relative to the previous label instead of relative to a label point. 6. Voting history None
14.8.77 MS RFC 78: Vector Field Rendering (CONNECTIONTYPE UVRASTER)

Date 2011/11/04 Author Alan Boudreault Contact aboudreault at mapgears.com Last Edited $Date: 2011-11-25 12:59:20 -0800 (Fri, 25 Nov 2011) $ Status Draft Version MapServer 6.2 Id $Id: ms-rfc-78.txt 12806 2011-11-25 20:59:20Z aboudreault $ 1. Overview This is a proposal to add the ability to render vector eld layers in MapServer. Vector elds are used for instance in meteorology to store/display wind direction and magnitude. The source is two bands of raster data, one band represents the U component of the vector, and the 2nd band the V component. Using the u,v values at a given location we can compute a rotation and magnitude and use that to draw an arrow of a size proportional to the magnitude and pointing in the direction of the phenomenon (wind, current, etc.) For more details about vector elds, refer to: http://en.wikipedia.org/wiki/Vector_eld Visual example (rendered with MapServer):
835
2. The proposed solution This RFC proposes the addition of a new type of layer in MapServer: CONNECTIONTYPE UVRASTER. The new type is a hybrid layer, which has a raster data source as input and vector features as output. Initially, only the point representation of those vector features will be supported. Also, queries wont be supported in this phase. Since the data source is a raster, all raster processing options can be used (e.g. RESAMPLE). After a few tests, we determined that the best results (for all different zoom levels) for vector elds were when using RESAMPLE=AVERAGE and this will be set by default for UV layers unless another type of resampling is explicitly specied in the layer denition. To render a vector eld layer, we need to dene a layer in the maple with the following options: Set the layer TYPE to POINT. Set CONNECTIONTYPE to UVRASTER. Set the DATA to the raster le that contains u/v bands. Specify the 2 bands to use as u and v. Specify a class to render the point features. Optional PROCESSING settings: UV_SPACING: The spacing is simply the distance, in pixels, between arrows to be displayed in the vector eld. Default is 32. UV_SIZE_SCALE: The uv size scale is used to convert the vector lengths (magnitude) of the raster to pixels for a better rendering. Default is 1. The UVRASTER layer has 4 attribute bindings that can be used in the layer denition and/or class expressions: [u]: the raw u value [v]: the raw v value [uv_angle]: the vector angle [uv_length]: the vector length (scaled with the UV_SIZE_SCALE option value)
836
Example of a layer denition:

LAYER NAME "my_uv_layer" TYPE POINT STATUS DEFAULT CONNECTIONTYPE UVRASTER DATA /mnt/data/raster/grib/wind.grib2 PROCESSING "BANDS=1,2" PROCESSING "UV_SPACING=40" PROCESSING "UV_SIZE_SCALE=0.2" CLASS STYLE ANGLE [uv_angle] SYMBOL "arrow" SIZE [uv_length] COLOR 255 0 0 POSITION CC MINSIZE 5 END END
3. Implementation Details Internally, a UVRASTER layer will have its own renderer/driver code. Its a hybrid layer because it reads the raster source as a normal raster layer does, but all other functions behave like a vector layer. The layer can be drawn as a normal point layer using whichShape, GetShape etc. Basic internal draw process of a UVRASTER layer: 1. whichShape() is called: the raster data source is read using the internal GDAL functions, resample and all other raster options are applied and the u,v pixels result is stored in the internal layer structure. 2. getShape() is called: loop through the raster pixels and returns a shapeObj (Point) created with the pixel location. 3. MapServer draws its point feature as any other vector layer. 3.1 Files affected The following les will be modied/created by this RFC:
mapserver.h/mapfile.c (Connection type UVRASTER support in the mapfile) mapuvraster.c (new file for the UVRASTER renderer) maplayer.c (new layer type handling, virtual tables init etc.) maplexer.l (add additional UVRASTER keyword)
3.2 MapScript No issue for any MapScript bindings. The UVRASTER layer is handled/rendered internally as any other layer.. 3.4 Backwards Compatibilty Issues This change provides a new functionality with no backwards compatibility issues being considered.
837
4. Bug ID http://trac.osgeo.org/mapserver/ticket/4094 5. Voting history +1 from Jeff, Olivier, Assefa, Perry, FrankW, Daniel, Stephen, Michael, Thomas, Tom and Steve.
14.8.78 MS RFC 79: Layer Masking

Date 2011/11/30 Author Thomas Bonfort Author Alan Boudreault Contact tbonfort at terriscope.fr Contact aboudreault at mapgears.com Last Edited $Date: 2011-12-06 03:08:57 -0800 (Tue, 06 Dec 2011) $ Status Adopted Version MapServer 6.2 Id $Id: ms-rfc-79.txt 12849 2011-12-06 11:08:57Z tbonfort $ 1. Overview For some applications, it is desirable to mask out one or more layers so that only the features that intersect another set of features are rendered in the returned image. While it is relatively trivial to achieve this goal with sql joins if all the data is stored in postgis, the task becomes much more evolved or even impossible if the layer to be masked, or the layer to use as a mask, comes from a shapele or a raster datasource. A example use-case for this could be rendering meteo data for a given client, but only on the areas where the client has purchased the service. In this case, the meteo data should only be rendered on the areas covered by a set of polygons that represent the purchased areas. Another example use-case given an input DEM raster, could be to only render data where the elevation is comprised in a given range. To achieve these goals, the present RFC proposes the introduction of MASK layers, where only the features that intersect the given mask are rendered onto the nal image. 2. Proposed solution In order to work with all layer types, this RFC proposes to implement layer masking at the pixel level, with the addition of a single MASK maple keyword. The MASK keywords is placed at the layer level, and takes a single argument which is the name of another maple layer that should be used as a mask. The mechanism to achieve masking at rendering time is: Each layer that is used as a mask is rendered in its own temporary image. All the ltering and styling is done as usual, which implies that raster classication/ltering can be performed, as well as style-level geomtransforms, etc...
838
When a layer references a MASK, it is rendered in its own temporary image, in the same way that is done when OPACITY is set. As before, all kind of ltering/transformations can be performed on the masked layer The masked layer is blended onto the nal map image, but only for the pixels that have been set in the mask image. Example of MASK usage:
LAYER NAME "parcels" TYPE POLYGON STATUS OFF DATA "the_geom from parcels where clientid=%token%" CLASS STYLE COLOR 0 0 0 END END END LAYER NAME "meteo" STATUS ON TYPE RASTER DATA "raster.tif" MASK "parcels" END
3. Implementation Details The parser will have a MASK keyword added to it, expecting a string The layerObj will have two properties added to it: char* masklayer : the name of the layer that should be used as a mask imageObj* maskimage : for a layer that has been referenced as a mask by another layer, this will contain the pixels that should be used to determine where data can be rendered on the nal map image. This is to prevent the mask layer from being rendered multiple times if it is referenced by multiple layers. In msDrawLayer(), if the current layer references a MASK layer: a temp image is created and rendered into by another call to msDrawLayer() a temp image is created and rendered into following the same codepath as if layer->opacity has been set the second temporary images alpha channel is tampered with and set to 0 for all the pixels that havent been set in the rst temporary image. the second temporary image is blended into the nal map image, again following codepath as if layer>opacity has been set. 3.1 Files affected The following les will be modied/created by this RFC:
mapserver.h/mapfile.c/mapfile.h/maplexer.l/mapcopy.c: parser and new layerObj members mapdraw.c: implementation in msDrawLayer() maplabel.c: implementation for dropping labels from the labelcache if they dont intersect the mask layer in msAddLabel()
839
3.2 MapScript Getters and Setters will have to be added to programmatically add a MASK to a layerObj. No other issues are to be expected. 3.4 Backwards Compatibilty Issues This change provides a new functionality with no backwards compatibility issues being considered. 4. Limitations Querying: The masking is done at the pixel level, as such all operations that query the datasource will not mask out features. Vector renderers: masking operations will not be supported on the vector renderers (svg,pdf) Labelling: Labelling is usually performed after all layers have been rendered, in the labelcache phase. For layers that are referenced as a mask, the layers labelcache will be set to OFF, which results in all labels being directly added to the temporary mask image instead of being added to the labelcache. Of course, it is not recommended to add labels to a layer used as a mask (that is, unless someone nds a compelling use-case to do so) If the layer that is being masked has labels, these have the potential to be rendered outside the mask area if they go through the labelcache. To overcome this, there will be a test to ensure that the labelpoint is contained in the masked areas before adding it to the labelcache. Note that the label text itself might be rendered outside of the masked areas, but this should not be an issue. If the masked layer is set with LABELCACHE FALSE, the rendered labels will be ltered out automatically at the pixel level, although there will probably be truncated labels that can appear. 5. Error Handling There are no special cases to treat here aside from the classic ones (parsing errors, invalid layer referenced by MASK, invalid renderer selected) 6. Bug ID http://trac.osgeo.org/mapserver/ticket/4111 7. Voting history Passed with +1 from ThomasB, MichaelS, StephenW, AssefaY, FrankW, TamasS, DanielM, JeffMcK, TomK, OlivierC, SteveL
14.8.79 MS RFC 80: Font Fallback Support

Date 2011/12/07 Author Thomas fake Jakobi Author Thomas Bonfort Contact thomas at derfake.com
840
Contact tbonfort at terriscope.fr Last Edited $Date: 2011-12-12 01:37:28 -0800 (Mon, 12 Dec 2011) $ Status Passed Version MapServer 6.2 Id $Id: ms-rfc-80.txt 12882 2011-12-12 09:37:28Z tbonfort $ 1. Overview This RFC proposes allowing for the denition of fallback fonts for labels, to be used when a glyph is not available in the initial font. Presently, if a glyph is not available in the font of a label, the fonts error glyph is drawn (usually an empty box). This is problematic when rendering international data, as it may contain a wide range of unicode charachters. Up to now, this can only be xed using a (near-)complete unicode font. The free unifont contains all glyphs of the basic unicode set (~60.000), but does not look very pleasing as a default font. With fallback fonts, glyph lookup would try a set of fonts, in a given order, before accepting the error glyph. This way, a unicode font like unifont would only be used as last resort on a glyph-by-glyph basis. In the maple, a list of fonts would be given as a comma-separated string like font1,font2,font3, where each font is listed in the fonts.lst as usual. If only one font is specied, this functionality has no effect. The same fontlist support is availabe for attribute binding. 2. Proposed Technical Change 2.1 Core Object Changes The Label Style Object would need to support multiple fonts. The proposed implementation uses a hard limit to the number of fonts, to avoid overhead. The number of fonts can be changed using the MS_MAX_LABEL_FONTS dene, the suggested default is 5. 2.2 Label Rendering Changes The function pointer signature of GetTruetypeTextBBox needs to be changed to be able to recieve multiple fonts and their count. This requires a change to every renderer, as does the change of the labelStyleObj. Renderers supporting single-glyph operation like cairo and agg can use the font list passed in to implement the glyph fallback. Renderers operating on complete strings can use fonts[0] for no change in behavior. 2.3 MapScript The mapscript getters and setters are unchanged, but the semantics of the string passed to labelObj->setFont() is modied as it now expects a comma-separated list of fontset keys. 3. Implementation Details The proposed implementation adds font fallback support to the cairo and agg renderers. The labelObj is unchanged, but its char* font member semantics is changed to contain a comma separated list of fontset keys instead of a single fontset key. This ensures minimal backwards incompatibility for mapscript applications and datasource bindings. 14.8. Request for Comments 841
A new function msFontsetLookupFonts() is called before labelling renderer-specic functions are called, and maps the comma-separated labelObj->font into an array of full font lenames, by iterating through the labelObj->font keys and calling msFontsetLookup. The renderer-specic labelling function signatures are modied to take a list of font lenames instead of a single lename as is the case now. Renderers that do not (yet?) support multiple font fallbacks are slightly modied to use the rst entry of the font array, while the other renderers use some specic code to detect missing characters and use the fallback fonts when needed. 3.1. Files Affected maplabel.c: add msFontsetLookupFonts implementation that splits the input font on commas and looks up each font key in the fontset. call msFontsetLookupFonts before calling the renderer vtable boundingbox calculation functions. maprendering.c: call msFontsetLookupFonts to set list of fonts in labelStyleObj mapagg.cpp: glyph fallback implementation, agg specic mapcairo.c: glyph fallback implementation, cairo and freetype specic mapgd.c, mapkml.c, mapogl.cpp: use only the rst font of the given font list getTruetypeTextBBox function signature update mapserver.h: add msFontsetLookupFonts function and MS_MAX_LABEL_FONTS dene change labelStyleObj char* font to char* font[MS_MAX_LABEL_FONTS] mapsymbol.c: symbol font fallback adoptions maputil.c: only bind font from shape if its different mapdummyrenderer.c: getTruetypeTextBBox signature change 3.2 Bug ID http://trac.osgeo.org/mapserver/ticket/4114 4. Backwards compatibility issues None expected, unless existing fontset keys contained commas. Im not sure this was valid syntax anyways, and was denitely bad practice. 5. Error reporting The hard limit on the maximum number of fonts allowed is enforced in msFontsetLookupFonts() which will halt processing and return an error message stating that the maximum number of fonts is set to MS_MAX_LABEL_FONTS. The renderers themselves will report the usual error message if one of the referenced fonts could not be loaded (due to an inaccessible or corrupt ttf le).
842
6. Example Usage see msautotest entry http://trac.osgeo.org/mapserver/changeset/12863 7. Voting history Passed with +1 from ThomasB, SteveW, MichaelS, SteveL, PerryN, DanielM
14.9 Maple Editing

14.9.1 VIM Syntax
Author Andreas Hirner Contact andreas.hirner at dlr.de Author Schuyler Erle Contact schuyler at tridity.org Revision $Revision: 8369 $ Date $Date: 2008-12-31 12:21:15 -0800 (Wed, 31 Dec 2008) $ Last Updated 2006/5/5 Table of Contents VIM Syntax General remarks Installation Folding Closing Remarks
General remarks vi (vim) resides in: /usr/share/vim/current (vim_root). Syntax denitions are in vim_root/syntax/*.vim les. Linking le types to extensions is done in vim_root/ftdetect/*.vim. (The the star denotes the extension and would be replaced with map to dene highlighting of MapServer cong les). Installation The installation process requires two steps: 1. Copy the map.vim syntax le to the syntax directory Copy map.vim to the vim syntax directory (on Suse: /usr/share/vim/current/syntax) 2. Register the syntax le in the custom letype directory If absent, create a new directory called ftdetect in vim_root (on Suse Linux: /usr/share/vim/current). Create a new le called map.vim in ftdetect according to the example shown below:
14.9. Maple Editing
843
" MapServer config file au BufNewFile,BufRead *.map
setf map
Now restart vim and open a map le .... Folding
Introduction
Vim code folding can be an extremely handy way to simplify the task of editing complex MapServer maples inside the Vim editor. A Vim command le called map_fold.vim is attached to this document, which denes a folding mode for maples. This le also lives at http://iconocla.st/code/dot/map_fold.vim.
Installation
In Vim 6, you can copy map_fold.vim as-is to your $VIMROOT/ftplugin/ directory, and it should more or less work. To use locally, create a ~/.vim/ftplugin directory, copy map_fold.vim to it, and then add the following to your ~/.vimrc:
autocmd BufRead *.map set filetype=map
map_fold.vim is totally compatible with the map.vim syntax highlighter, and their combined use is even recommended.
Use
The Vim folding tutorial (at least the rst two or three sections) is highly recommended. The Vim folding reference may also be helpful.
Conclusion
Hope this helps! Please let me know if you nd it useful, or if you nd ways to improve it. Thanks! Closing Remarks The keywords are based on the TextPad Symbol Map_40.syn le contributed by Christopher Thorne, which can also be found on the MapServer utility page. I hope the le is somehow useful to anybody out there. If there are any questions or suggestions, please feel free to contact me.
14.10 External Links

Buildbot Developers Ohloh Release Plans (wiki)
844
CHAPTER 15
Download
15.1 Source
15.1.1 Current Release(s)
2011-07-12 mapserver-6.0.1.tar.gz Changelog
15.1.2 Development Releases

none available
15.1.3 Past Releases

2011-05-12 mapserver-6.0.0.tar.gz Changelog 2011-07-12 mapserver-5.6.7.tar.gz Changelog 2009-07-23 mapserver-5.4.2.tar.gz Changelog 2009-07-23 mapserver-5.2.3.tar.gz Changelog 2011-07-12 mapserver-4.10.7.tar.gz Changelog
15.1.4 Development Source

Current Trunk: http://svn.osgeo.org/mapserver/trunk/ Latest Release Branch: http://svn.osgeo.org/mapserver/branches/branch-6-0 Note: More information about MapServer development can be found at Development
15.2 Documentation
Note: If you plan on upgrading to the MapServer 6.0 release, be sure to review the MapServer Migration Guide. The entire documentation is available as a single PDF document. 845
15.2.1 Current Release

MapServer-Documentation.pdf
15.2.2 Previous Releases

MapServer-5.6-Documentation.pdf MapServer-5.4-Documentation.pdf
15.3 Binaries
15.3.1 Windows
MS4W MapServer for Windows from MapTools.org. If you are a beginner looking for a complete MapServer solution on the Windows platform, or an advanced user looking to avoid compiling your own, this is what youre looking for. MS4W is a complete Web Server/MapServer/MapScript package. MS4W includes several avors of MapScript (PHP, C#, Python, Java), and additional dlls for SDE and Oracle support. Several popular Web applications are also available for download, which are pre-congured for MS4W. OSGeo4W OSGeo4W is a binary distribution of a broad set of Open Source geospatial software for Win32 environments (Windows XP, Vista, etc). OSGeo4W includes GDAL/OGR, GRASS, MapServer, OpenEV, uDig, as well as many other packages (about 70 as of summer 2008). FWTools A collection of Open Source GIS tools provided by Frank Warmerdam. This goes beyond your basic web mapping tools and include many useful utilities for creating, manipulating, and serving geo-spatial data. New versions will probably not appear. Gisinternals A collection of binary packages that are compiled daily based on the MapServer and GDAL SVN (development and stable branches).
15.3.2 Linux
DebianGIS DebianGIS provides a number of packages including MapServer, PostGIS, GDAL, QGIS, and GEOS. It sometimes lags a little bit behind the absolute latest release, but DebianGIS provides a solid integration environment for a giant slug of Open Source GIS software. Enterprise Linux GIS The Enterprise Linux GIS (ELGIS) repository provides up to date packages of MapServer and related OSGeo tools for Enterprise Linux and derivatives, that is Red Hat Enterprise Linux (RHEL), CentOS and Scientic Linux. FGS The FGS Linux Installer is a self-extracting le that will install MapServer with PHP/MapScript and all of their dependencies on your Linux system. It provides a stand-alone environment with all the required software (incl. Apache and PHP) to run PHP/MapScript webmapping applications. The bundled version of Apache can be congured to run on any port so it will not interfere with previous installations of Apache or other web servers on your system. OpenSUSE The OpenSUSE Application:Geo repository provides stable Packages for MapServer and other OSGeo tools. Development versions are also made available for testing in other OBS before being migrated to the stable repository.
846
Chapter 15. Download
UbuntuGIS UbuntuGIS provides up to date packages of MapServer and related OSGeo tools for the last three releases of Ubuntu.
15.3.3 Mac OS X
Kyng Chaos William Kyngesburye provides excellent, up-to-date packages for Mac OS X. Most of the Open Source GIS stack is provided, including GEOS, GDAL, QGIS, and PostGIS.
15.4 Demo Application

Download MapServer 5.4.x Demo Download and unzip this le into your computer. Follow the directions in ReadMe.txt. You will most likely need to move the demo directory tree to an appropriate location in your httpd server. You will also need to edit some of the maple and template le parameters to reect the changes in your paths (directory locations).
15.4. Demo Application
847
848
Chapter 15. Download
CHAPTER 16
Environment Variables
A number of environment variables can be used to control MapServers behavior or specify the location of some resources. CURL_CA_BUNDLE Used to specify the location of the Certicate Authority (CA) bundle le to be used by Curl when using HTTPS connections in WMS/WFS client layers. Curl comes bundled with its own CA bundle by default, so this variable is not required unless you have an unusual installation:
export CURL_CA_BUNDLE=/path/to/ca-bundle.crt
New in version 5.4.1. MS_DEBUGLEVEL A default DEBUG level value can be set using the MS_DEBUGLEVEL environment variable in combination with the MS_ERRORFILE variable. When set, this value is used as the default debug level value for all map and layer objects as they are loaded by the maple parser. This option also sets the debug level for any msDebug() call located outside of the context of a map or layer object, for instance for debug statements relating to initialization before a map is loaded. If a DEBUG value is also specied in the maple in some map or layer objects then the local value (in the maple) takes precedence over the value of the environment variable. This option is mostly useful when tuning applications by enabling timing/debug output before the map is loaded, to capture the full process initialization and map loading time, for instance. New in version 5.0. See Also: MS RFC 28: Redesign of LOG/DEBUG output mechanisms MS_ENCRYPTION_KEY See Also: msencrypt New in version 4.10. MS_ERRORFILE The MS_ERRORFILE environment variable species the location of the logging/debug output, with possible values being either a le path on disk, or one of the following special values: stderr to send output to standard error. Under Apache stderr is the Apache error_log le. Under IIS stderr goes to stdout so its use is discouraged. With IIS it is recommended to do direct output to a le on disk instead. stdout to send output to standard output, combined with the rest of MapServers output.
849
windowsdebug to send output to the Windows OutputDebugString API, allowing the use of external programs like SysInternals debugview to display the debug output. It is possible to specify MS_ERRORFILE either as an environment variable or via a CONFIG directive inside a maple:
CONFIG "MS_ERRORFILE" "/tmp/mapserver.log"
or:
CONFIG "MS_ERRORFILE" "stderr"
If both the MS_ERRORFILE environment variable is set and a CONFIG MS_ERRORFILE is set, then the CONFIG directive takes precedence. If MS_ERRORFILE is not set, then error/debug logging is disabled. During parsing of a maple, error/debug logging may become available only after the MS_ERRORFILE directive has been parsed. See Also: MS RFC 28: Redesign of LOG/DEBUG output mechanisms MS_MAP_NO_PATH The MS_MAP_NO_PATH environment variable can be set to any value to forbid the use of explicit paths in the map=... URL parameter. Setting MS_MAP_NO_PATH to any value forces the use of the map=<env_variable_name> mechanism in mapserv CGI URLs. If this variable is not set then nothing changes and the mapserv CGI still accepts explicit le paths via the map=... URL parameter. Example, set set MS_MAP_NOPATH and some maple paths in Apaches httpd.conf:
SetEnv MS_MAP_NO_PATH "foo" SetEnv MY_MAPFILE "/opt/mapserver/map1/mymapfile.map"
and then calls the mapserv CGI must use environment variables for the map=... parameter:
New in version 5.4. See Also: MS RFC 56: Tighten control of access to maples and templates MS_MAPFILE The maple to use if the map=... URL parameter is not provided. It is also possible to use an environment variable name as the value of the map=... URL parameter. The value of this environment variable will be used as the maple path:
map=ENV_VAR
MS_MAPFILE_PATTERN MS_MAPFILE_PATTERN can be used to override the default regular expression which is used to validate maple lename extensions. The default value for this variable is:
MS_MAPFILE_PATTERN=\.map$
MS_MAP_PATTERN The MS_MAP_PATTERN environment variable can be used to specify a Regular Expression that must be matched by all maple paths passed to the mapserv CGI in the map=... URL parameter. If MS_MAP_PATTERN is not set then any .map le can be loaded. Example, use Apaches SetEnv? directive to restrict maples to the /opt/mapserver/ directory and subdirectories:
850
Chapter 16. Environment Variables
SetEnv MS_MAP_PATTERN "^/opt/mapserver/"
New in version 5.4. See Also: MS RFC 56: Tighten control of access to maples and templates MS_MODE Default value for the mode=... URL parameter. Setting mode=... in the URL takes precedence over the environment variable. MS_OPENLAYERS_JS_URL The URL to the OpenLayers javascript library (can be used when testing WMS services using imagetype application/openlayers), for instance:
http://openlayers.org/api/OpenLayers.js
MS_TEMPPATH Set the WEB TEMPPATH. New in version 6.0. MS_XMLMAPFILE_XSLT Used to enable XML Maple support. Points to the location of the XSLT to use for the XML->text maple conversion. See Also: XML Maple support PROJ_LIB The PROJ_LIB environment variable or CONFIG directive can be used to specify the directory where the PROJ.4 data les (including the epsg le) are located, if they are not in the default directory where PROJ.4 expects them. See Also: Setting the location of the epsg le in Errors.
851
852
Chapter 16. Environment Variables
CHAPTER 17
Glossary
AGG Anti-Grain Geometry A high quality graphics rendering engine that MapServer 5.0+ can use. It supports sub-pixel anti-aliasing, as well as many more features. CGI Wikipedia provides excellent coverage of CGI. EPSG EPSG codes are numeric codes associated with coordinate system denitions. For instance, EPSG:4326 is geographic WGS84, and EPSG:32611 is UTM zone 11 North, WGS84. The WMS protocol uses EPSG codes to describe coordinate systems. EPSG codes are published by the OGP Surveying and Positioning Committee. A list of PROJ.4 denitions corresponding to the EPSG codes can be found in the le /usr/local/share/proj/epsg. PROJECTION describes how to use these in your Maple. See Also: http://spatialreference.org for a listing of spatial references and an interface to search for spatial references. Filter Encoding Filter Encoding is an OGC standard which denes an XML encoding for lter expressions to allow for spatial and attribute querying. See Also: WFS Filter Encoding FreeType FreeType is a font engine that MapServer uses for accessing and rendering TrueType fonts. GD GD is a graphics library for dynamic generation of images. It was the rst graphics renderer that was available for MapServer, and it is required by MapServer to operate. GDAL GDAL (Geospatial Data Abstraction Library) is a multi-format raster reading and writing library. It is used as the primary mechanism for reading raster data in MapServer. It is hosted at http://www.gdal.org/ GEOS Geometry Engine Open Source is a C/C++ port of the Java Topology Suite. It is used for geometric algebra operations like determining if a polygon is contained in another polygon or determining the resultant intersection of two or more polygons. MapServer optionally uses GEOS for geometric algebra operations. GML Geography Markup Language is an OGC standard which denes an abstract model for geographic features See Also: WFS Server GPX GPS eXchange Format is an XML Schema for describing GPS data. OGR can be used to transform and render this data with MapServer. Map Scale A treatise of mapping scale can be found on about.com.
853
Maple Maple is the declarative language that MapServer uses to dene data connections, map styling, templating, and server directives. Its format is xml-like and hierarchical, with closing END tags, but the format is not xml. MapScript MapScript is an alternative the the CGI application of mapserv that allows you to program the MapServer object API in many languages. Mercator Wikipedia provides excellent coverage of the Mercator projection. OGC The Open Geospatial Consortium is a standards organization body in the GIS domain. MapServer supports numerous OGC standards. See Also: WMS Server and WMS Time and WMS Client and WFS Server and WFS Client and WCS Server and Map Context and SLD and WFS Filter Encoding and SOS Server OGR OGR is the vector data access portion of the GDAL library. It provides access to a multitude of data formats. See Also: OGR OM Observations and Measurements is an OGC standard which denes an abstract model for sensor based data. See Also: SOS Server OpenLayers OpenLayers is a JavaScript library for developing draggable, slippy map web applications. Proj.4 Proj4 is a library for projecting map data. It is used by MapServer and GDAL and a multitude of other Open Source GIS libraries. Projection A map projection is a mathematical transformation of the surface of a sphere (3D) onto a 2D plane. Due to the laws of the universe, each type of projection must make tradeoffs on how and what features it distorts. Raster A raster is a rectangular grid of pixels. Essentially an image. Rasters are supported in MapServer with a layer type of RASTER, and a variety of formats are supported including GeoTIFF, JPEG, and PNG. Shapele Shapeles are simple GIS vector les containing points, lines or areas. The format was designed and published by ESRI and is widely supported in the GIS world. It is effectively the native and highest performance format for MapServer. See Also: Wikipedia SLD SLD is an OGC standard which allows for custom symbolization for portrayal of data. See Also: SLD SOS SOS is an OGC standard which provides an API for managing deployed sensors and retrieving sensor and observation data. See Also: SOS Server Spherical Mercator Spherical Mercator is a term used to describe the PROJECTION used by many commercial API providers. SVG Scalable Vector Graphics is an XML format that MapServer can output. It is frequently used in browser and mobile devices. See Also:
854
Chapter 17. Glossary
SVG SWF Shockwave Flash format that MapServer can generate for output. See Also: Flash Output SWIG Simplied Wrapper Interface Generator is the library that MapServer uses for generating the language bindings for all languages other than C/C++ and PHP. MapScript describes these bindings. Tileindex A tileindex is a Shapele or other Vector data source that contains footprints of Raster data coverage. MapServer can use a tileindex to render a directory of raster data. The tileindex allows MapServer to only read the data that intersects the requested map extent, rather than reading all of the data. See Also: Tile Indexes Vector Geographic features described by geometries (point, line, polygon) on a (typically) cartesian plane. WCS WCS is an OGC standard that describes how to systematically produce structured Raster cartographic data from a service and return them to a client See Also: WCS Server and WCS Use Cases WFS WFS is an OGC standard that describes how to systematically produce structured Vector cartographic data from a service and return them to a client. See Also: WFS Server and WFS Client WMC Web Map Context is an OGC standard which allows for sharing of map views of WMS layers in multiple applications. See Also: Map Context WMS WMS is an OGC standard that describes how to systematically produce rendered map images from a service and return them to a client. See Also: WMS Server and WMS Client
855
856
Chapter 17. Glossary
CHAPTER 18
Errors
18.1 drawEPP(): EPPL7 support is not available

Error displayed when not using EPPL7 data. This is a confusing error for users who are not even trying to view EPPL7 layers (EPPL7 is a raster format). The full error displayed may appear as follows:
msDrawRaster(): Unrecognized or unsupported image format ... drawEPP(): EPPL7 support is not available.
18.1.1 Explanation
When MapServer tries to draw a layer, it will attempt to use all of the drivers it knows about, and the EPPL7 driver is the very last driver it will try. This means that if a layer fails to draw for any reason, you will see this error message. There are other possible instances when this error can appear however, here are a few: the server is returning either a ServiceException (which MapServer does not yet detect and parse into a reasonable error message) or it is returning an image in an unrecognized format ... for instance it is returning a GIF image and MapServer is not built to support GIF images. WMS servers often advertise multiple image formats but dont respect them in the getmap request.
18.2 loadLayer(): Unknown identier. Maximum number of classes reached

Error displayed when attempting to draw a layer with a large number of classes. This error states that MapServer has reached its limit for the maximum number of classes for the layer. This maximum can be modied in the MapServer source, and can then be re-compiled. map.h contains the default values, and below are the defaults for MapServer 4.10 and 4.8:
#define MS_MAXCLASSES 250 #define MS_MAXSTYLES 5 #define MS_MAXLAYERS 200
857
Note: This limitation was corrected in MapServer 5.0 and should no longer be a problem.
18.3 loadMapInternal(): Given map extent is invalid

When loading your maple or one of your layers, MapServer complains about an invalid extent. Beginning in MapServer 4.6, MapServer got more strict about LAYER and MAP extents. If minx is greater than maxx, or miny is greater than maxy, this error will be generated. Check your MAPs EXTENT, LAYERs EXTENT, or wms_extent setting to make sure this is not the case. MapServer always takes in extents in the form of:
EXTENT minx miny maxx maxy
18.3.1 How to get a les EXTENT values?

The easiest way to get a vector les EXTENT is to use the ogrinfo utility, that is part of the GDAL/OGR library (for raster les you would use the gdalinfo utility). Windows users can download the FWTools package, which includes all of the GDAL and OGR commandline utilities. MS4W also includes the utilities (in ms4w/tools/gdal-ogr-utils/ ). Linux users will probably already have the GDAL libraries, if not you can also use the FWTools package. For example, here is the results of the ogrinfo command on a shapele (notice the Extent line):
$ ogrinfo province.shp province -summary INFO: Open of province.shp using driver ESRI Shapefile successful. Layer name: province Geometry: Polygon Feature Count: 1071 Extent: (-2340603.750000, -719746.062500) - (3009430.500000, 3836605.250000) Layer SRS WKT: (unknown) AREA: Real (16.0) PERIMETER: Real (16.0) PROVINCE_: Real (16.0) PROVINCE_I: Real (16.0) STATUS: String (64.0) NAME: String (64.0) NAME_E: String (64.0) NAME_F: String (64.0) REG_CODE: Real (16.0) POLY_FEATU: Real (16.0) ISLAND: String (64.0) ISLAND_E: String (64.0) ISLAND_F: String (64.0) YYY: Real (16.0) SIZE: Real (16.0) ANGLE: Real (16.0)
Ogrinfo gives the les extent in the form of (minx, miny),(maxx, maxy), therefore the EXTENT in a maple would be:
EXTENT -2340603.750000 -719746.062500 3009430.500000 3836605.250000
Note: The EXTENT in a maple must be in the same units as the MAP -level PROJECTION.
858
Chapter 18. Errors
18.4 msGetLabelSize(): Requested font not found

Error displayed when attempting to display a specic font. This message tells you that MapServer cannot nd specied font.
Make sure that the font is properly referenced in the FONTSET lookup file.
See Also: FONTSET
18.5 msLoadFontset(): Error opening fontset

Error when attempting to display a label. This message tells you that MapServer cannot nd the FONTSET specied in the Maple.
The FONTSET path is relative to the mapfile location.
See Also: FONTSET
18.6 msLoadMap(): Failed to open map le

Error displayed when trying to display map image. The message tells you that MapServer cannot nd maple. Verify that you have specied the correct path to the maple. Linux/Unix users should make sure that the web user has access permissions to the maple path as well. The error message states where MapServer thinks the maple is:
[MapServer Error]: msLoadMap(): (D:/ms4w/apps/blah/blah.map) Failed to open map file D:/ms4w/apps/blah/blah.map
18.7 msProcessProjection(): no options found in init le

Error displayed when attempting to use a specic projection. The message tells you that the projection youre trying to use isnt dened in the epsg le. Open your epsg le in a text editor and search for your projection to make sure that it exists. On Windows, the default location of the epsg le is c:\proj\nad. MS4W users will nd the epsg le in \ms4w\proj\nad. See Also: PROJECTION and http://spatialreference.org
18.8 msProcessProjection(): No such le or directory

Error displayed when trying to refer to an epsg le.
18.4. msGetLabelSize(): Requested font not found
859
The message tells you that MapServer cannot nd the epsg le. On Windows, the default location of the epsg le is c:\proj\nad. MS4W users will nd the epsg le in \ms4w\proj\nad. Linux/Unix users should be careful to specify the correct case when referring to the epsg le, since lenames are case sensitive on Linux/Unix. init=epsg:4326 refers to the epsg lename, and therefore init=EPSG:4326 will not work because it will be looking for an EPSG le in uppercase.
18.8.1 Setting the location of the epsg le

There are a few options available if you need to set the epsg location: 1. Use a system variable (environment variable on windows) called PROJ_LIB and point it to your epsg directory. 2. Use the maple parameter CONFIG to force the location of the epsg le. This parameter is specied at the MAP level See Also: Maple
MAP ... CONFIG "PROJ_LIB" "C:/somedir/proj/nad/" ... END
3. Set an environment variable through your web server. Apache has a SetEnv directive that can set environment variables. Add something like the following to your Apache httpd.conf le:
SetEnv PROJ_LIB C:/somedir/proj/nad/
18.9 msProcessProjection(): Projection library error.major axis or radius = 0 not given

Error displayed when attempting to specify projection parameters. Since MapServer 4.0, you are required to specify the ellipsoid for the projection. Omitting this ellipsoid parameter in later MapServer versions will cause this error.
18.9.1 Valid Examples

4.0 and newer:
PROJECTION "proj=latlong" "ellps=WGS84" END
before MapServer 4.0:

PROJECTION "proj=latlong" END
860
Chapter 18. Errors
See Also: PROJECTION and http://spatialreference.org
18.10 msQueryByPoint: search returned no results

Why do I get the message msQueryByPoint(): Search returned no results. No matching record(s) found when I query a feature known to exists? The query feature requires a TEMPLATE object in the CLASS object of your LAYER denition. The value points to a html fragment using MapServer template syntax. Example MapFile fragment:
LAYER NAME "Parcel9" TYPE POLYGON STATUS OFF DATA "Parcels/area09_parcels" CLASS STYLE OUTLINECOLOR 128 128 128 COLOR 153 205 255 END TEMPLATE "templates/Parcels/area09_parcels.html" END HEADER "templates/Parcels/area09_parcels_header.html" FOOTER "templates/Parcels/area09_parcels_footer.html" END
Example Template:
<tr> <td>[lrn]</td> <td>[PIN]</td> </tr>
The [lrn] is a special keyword that indicates the resulting line number which starts at 1. [PIN] is the name of a feature attribute.
18.11 msReturnPage(): Web application error. Malformed template name

This error may occur when you are attempting to use a URL template for a query. The issue is that URL templates are only allowed for query modes that return only one result (e.g. query or itemquery) You can only use a URL template for a query in mode=query or mode=itemquery. If you try it with mode=nquery or mode=itemnquery, you will get the error:
Content-type: text/html msReturnPage(): Web application error. Malformed template name
See Also: MapServer CGI Controls
18.10. msQueryByPoint: search returned no results
861
18.12 msSaveImageGD(): Unable to access le

Error displayed when attempting to display map image. This error is displayed if MapServer cannot display the map image. There are several things to check: IMAGEPATH and IMAGEURL parameters in maple are valid In CGI mode, any IMAGEPATH and IMAGEURL variables set in the init pages are valid Linux/Unix users should verify that the web user has permissions to write to the IMAGEPATH
18.13 msWMSLoadGetMapParams(): WMS server error. Image Size out of range, WIDTH and HEIGHT must be between 1 and 2048 pixels
Error that is returned / displayed when a user has requested a map image (via WMS) that exceeds the maximum width or height that the service allows. To increase the maximum map width and height for the service, use the MAXSIZE parameter of the MAP object. Producing larger map images requires more processing power and more memory, so take care.
18.14 Unable to load dll (MapScript)

One of the dll-s could not be loaded that mapscript.dll depends on. You can get this problem on Windows and in most cases it can be dedicated to a missing or an unloadable shared library. The error message talks about mapscript.dll but surely one or more of the dll-s are missing that libmap.dll depends on. So rstly you might want to check for the dependencies of your libmap.dll in your application directory. You can use the Visual Studio Dependency Walker to accomplish this task. You can also use a le monitoring tool (like SysInternals lemon) to detect the dll-s that could not be loaded. I propose to store all of the dll-s required by your application in the application folder. If you can run the mapscript sample applications properly your compilation might be correct and all of the dlls are available.
18.14.1 C#-specic information

You may nd that the mapscript C# interface behaves differently for the desktop and the ASP.NET applications. Although you can run the drawmap sample correctly you may encounter the dll loading problem with the ASP.NET applications. When creating an ASP.NET project your application folder will be Inetpubwwwroot[YourApp]bin by default. The host process of the application will aspnet_wp.exe or w3wp.exe depending on your system. The application will run under a different security context than the interactive user (under the context of the ASPNET user by default). When placing the dll-s outside of your application directory you should consider that the PATH environment variable may differ between the interactive and the ASPNET user and/or you may not have enough permission to access a dll outside of your application folder.
862
Chapter 18. Errors
CHAPTER 19
FAQ
19.1 Where is the MapServer log le?

See MS RFC 28: Redesign of LOG/DEBUG output mechanisms
19.2 What books are available about MapServer?

Mapping Hacks by Schuyler Erle, Rich Gibson, and Jo Walsh is available from OReilly. Web Mapping Illustrated by Tyler Mitchell is available from OReilly. Introduces MapServer and many other related technologies including, GDAL/OGR, MapScript, PostGIS, map projections, etc. MapServer: Open Source GIS Development by Bill Kropla.
19.3 How do I compile MapServer for Windows?

See Compiling on Win32. Also, you can use the development libraries in OSGeo4W as a starting point instead of building all of the dependent libraries yourself.
19.4 What do MapServer version numbers mean?

MapServers version numbering scheme is very similar to Linuxs. For example, a MapServer version number of 4.2.5 can be decoded as such: 4: Major version number. MapServer releases a major version every two to three years. 2: Minor version number. Increments in minor version number almost always relate to additions in functionality. 5: Revision number. Revisions are bug xes only. No new functionality is provided in revisions. From a developers standpoint, MapServer version numbering scheme is also like Linux. Even minor version numbers (0..2..4..6) relate to release versions, and odd minor versions (1..3..5..7) correspond to developmental versions.
863
19.5 Is MapServer Thread-safe?

Q: Is MapServer thread-safe? A: Generally, no (but see the next question). Many components of MapServer use static or global data that could potentially be modied by another thread. Under heavy load these unlikely events become inevitable, and could result in sporadic errors. Q: Is it possible to safely use any of MapServer in a multi-threaded application? A: Some of it, yes, with care. Or with Python :) Programmers must either avoid using the unsafe components of MapServer or carefully place locks around them. Pythons global interpreter lock immunizes against MapServer threading problems; since no mapscript code ever releases the GIL all mapscript functions or methods are effectively atomic. Users of mapscript and Java, .NET, mod_perl, or mod_php do not have this extra layer of protection. A: Which components are to be avoided? Q: Below are lists of unsafe and unprotected components and unsafe but locked components. Unsafe: OGR layers: use unsafe CPL services Cartoline rendering: static data Imagemap output: static data SWF output: static data and use of unsafe msGetBasename() SVG output: static data WMS/WFS server: static data used for state of dispatcher Forcing a temporary le base (an obscure feature): static data MyGIS: some static data Unsafe, but locked: Map cong le loading: global parser Setting class and and layer lter expressions (global parser) Class expression evaluation (global parser) Setting map and layer projections (PROJ) Raster layer rendering and querying (GDAL) Database Connections (mappool.c) PostGIS support Oracle Spatial (use a single environment handle for connection) SDE support (global layer cache) Error handling (static repository of the error objects) WMS/WFS client connections: potential race condition in Curl initialization Plugin layers (static repository of the loaded dll-s) Rather coarse locks are in place for the above. Only a single thread can use the global parser at a time, and only one thread can access GDAL raster data at a time. Performance is exchanged for safety.
864
Chapter 19. FAQ
19.6 What does STATUS mean in a LAYER?

STATUS ON and STATUS OFF set the default status of the layer. If a map is requested, those layers will be ON/OFF unless otherwise specied via the layers parameter. This is particularly the case when using MapScript and MapServers built-in template mechanism, but is also useful as a hint when writing your own apps and setting up the initial map view. STATUS DEFAULT means that the layer is always on, even if not specied in the layers parameter. A layers status can be changed from DEFAULT to OFF in MapScript, but other than that, its always on. CGI turns everything off that is not STATUS DEFAULT off so all layers start from the same state (e.g. off) and must be explicitly requested to be drawn or query. That common state made (at least in my mind) implementations easier. I mean, if a layer lakes started ON the doing layer=lakes would turn it OFF. So I wanted to remove the ambiguity of a starting state.
19.7 How can I make my maps run faster?

There are a lot of different approaches to improving the performance of your maps, aside from the obvious and expensive step of buying faster hardware. Here are links to some individual howtos for various optimizations. Tuning your maple for performance Optimizing the performance of vector data sources Optimizing the performance of raster data sources Tileindexes for mosaicing and performance Some general tips for all cases: First and foremost is hardware. An extra GB of RAM will give your map performance increases beyond anything youre likely to achieve by tweaking your data. With the price of RAM these days, its cheap and easy to speed up every map with one inexpensive upgrade. Use the scientic method. Change one thing at a time, and see what effect it had. Try disabling all layers and enabling them one at a time until you discover which layer is being problematic. Use shp2img program to time your results. This runs from the command line and draws an image of your entire map. Since its run from the command line, it is immune to net lag and will give more consistent measurements that your web browser.
19.8 What does Polyline mean in MapServer?

Theres confusion over what POLYLINE means in MapServer and via ESRI. In MapServer POLYLINE simply means a linear representation of POLYGON data. With ESRI polyline means multi-line. Old versions of the Shapele techical description dont even refer to polyline shapeles, just line. So, ESRI polyline shapeles are just linework and can only be drawn and labeled as LINE layers. Those shapeles dont have feature closure enforced as polygon shapeles do which is why the distinction is so important. I suppose there is a better choice than POLYLINE but I dont know what it would be. Note: The only difference between POLYLINE and LINE layers is how they are labeled.
19.6. What does STATUS mean in a LAYER?
865
19.9 What is MapScript?

MapScript is the scripting interface to MapServer, usually generated by SWIG (except in the case of php). MapScript allows you to program with MapServers objects directly instead of interacting with MapServer through its CGI and Maple.
19.10 Does MapServer support reverse geocoding?

No. Reverse geocoding is an activity where you take a list of street features that you already have and generate postal addresses from them. This kind of spatial functionality is provided by proprietary packages such as the ESRI suite of tools, as well as services such as those provided by GDT. MapServer is for map rendering, and it does not provide for advanced spatial operations such as this.
19.11 Does MapServer support geocoding?

No. Geocoding is an activity where you take a list of addresses and generate lat/lon points for them. This kind of spatial functionality is provided by proprietary packages such as the ESRI suite of tools, as well as services such as those provided by GDT. MapServer is for map rendering, and it does not provide for advanced spatial operations such as this. If you are using MapScript, there is a free geocder available through XMLRPC and SOAP at http://geocoder.us . You could hook you application up to use this service to provide lat/lon pairs for addresses, and then use MapServer to display those points.
19.12 How do I set line width in my maps?

You must set the symbol for the LAYER to be circle and then you can set the symbol SIZE to be the width you want. A circle symbol can be dened as
SYMBOL NAME circle TYPE ELLIPSE FILLED TRUE POINTS 1 1 END END
19.13 Why do my JPEG input images look crappy via MapServer?

The default output format for MapServer is 8bit pseudo-colored PNG or GIF. Inherently there will be some color degredation in converting a 24bit image (16 million colors) image into 8bit (256 colors). But in order to ensure fast rendering MapServer uses quite a simple method to do the transformation, converting pixels to the nearest color in a 175 color colorcube. This will usually result in blotchy color in a fairly smoothly varying image. Solutions include: 866 Chapter 19. FAQ
Select 24bit output. This might be as easy as IMAGETYPE JPEG in your MAP section. Enable dithering (PROCESSING DITHER=YES) to produce a better color appearance. Preprocess your image to 8bit before using it in MapServer with an external application like the GDAL rgb2pct.py script. For more information review the Raster Data.
19.14 Which image format should I use?

Although MapScript can generate the map in any desired image format it sufcient to only consider the three most prevalent ones: JPEG, PNG, and GIF. JPEG is an image format that uses a lossy compression algorithm to reduce an images le size and is mostly used when loss of detail through compression is either not noticeable or negligible, as in most photos. Maps on the other hand mainly consist of ne lines and areas solidly lled in one colour, which is something JPEG is not known for displaying very well. In addition, maps, unless they include some aerial or satellite imagery, generally only use very few different colours. JPEG with its 24bit colour depth capable of displaying around 16.7 million colours is simple not suitable for this purpose. GIF and PNG however use an indexed colour palette which can be optimized for any number (up to 256) of colours which makes them the perfect solution for icons, logos, charts or maps. The following comparison (generated le sizes only; not le generation duration) will therefore only include these two le formats: Table 19.1: GIF vs. PNG vs. PNG24 Generated Map File Sizes Vector Data only Vector Data & Satellite Image coloured Vector Data & Satellite Image monochrome GIF 59kb 156kb 142kb PNG 26kb 182kb 134kb PNG24 69kb 573kb 492kb
(results based on an average 630x396 map with various colours, symbols, labels/annotations etc.) Although GIF shows a quantitative as well as qualitative advantage over PNG when generating maps that contain full coloured remote sensing imagery, PNG is the clear quantitative winner in terms of generated le sizes for maps with or without additional monochrome imagery and should therefore been the preferred image format. If the mapping application however can also display fullcolour aerial or satellite imagery, the output le format can be changed dynamically to either GIF or even PNG24 to achieve the highest possible image quality.
19.15 Why doesnt PIL (Python Imaging Library) open my PNGs?

PIL does not support interlaced PNGs at this time (no timetable on when it actually will either). To be able to read PNGs in PIL, they must not be interlaced. Modify your OUTPUTFORMAT with a FORMATOPTION like so:
OUTPUTFORMAT NAME png DRIVER "GD/PNG" MIMETYPE "image/png" IMAGEMODE RGB EXTENSION "png" FORMATOPTION "INTERLACE=OFF" END
19.14. Which image format should I use?
867
19.16 Why do my symbols look poor in JPEG output?

When I render my symbols to an 8bit output (PNG, GIF) they look ne, but in 24bit jpeg output they look very blocky and gross. In order to render some classes of symbols properly in 24bit output, such as symbols from true type fonts, it is necessary to force rendering to occur in RGBA. This can be accomplished by including the TRANSPARENCY ALPHA line in the layer denition. Dont use this unnecessarily as there is a performance penalty. This problem also affects PNG24 output or any RGB output format. 8bit (PC256) or RGBA output types are already ok.
19.17 How do I add a copyright notice on the corner of my map?

You can use an inline feature, with the FEATURE object, to make a point on your map. Use the TEXT parameter of the FEATURE object for the actual text of the notice, and a LABEL object to style the notice.
19.17.1 Example Layer

LAYER NAME "copyright" STATUS ON TYPE annotation TRANSFORM ll #set the image origin to be lower left FEATURE POINTS 60 -10 #set the offset from lower left position in pixels END TEXT " xyz company 2006" #this is your displaying text END CLASS LABEL #defines the font, colors etc. of the text FONT "sans" TYPE TRUETYPE SIZE 8 BUFFER 1 COLOR 0 0 0 BACKGROUNDCOLOR 255 255 255 FORCE TRUE END END UNITS PIXELS #sets the units for the feature object END
868
Chapter 19. FAQ
19.17.2 Result
19.18 How do I have a polygon that has both a ll and an outline with a width?
How do I have a polygon that has both a ll and an outline with a width? Whenever I put both a color (ll) and an outlinecolor with a width on a polygon within a single STYLE, the outline width isnt respected. For historical reasons, width has two meanings within the context of lling polygons and stroke widths for the outline. If a polygon is lled, then the width denes the width of the symbol inside the lled polygon. In this event, the outline width is disregarded, and it is always set to 1. To acheive the effect of both a ll and an outline width, you need to use two styles in your class.
STYLE # solid fill COLOR 255 0 0 END STYLE # thick outline (could use a circle symbol with size too) OUTLINECOLOR 0 0 0 WIDTH 3 ANTIALIAS TRUE END
19.18. How do I have a polygon that has both a ll and an outline with a width?
869
19.19 How can I create simple antialiased line features?

The easiest way to produce antialiased lines is to: use a 24-bit output image type (IMAGEMODE RGB (or RGBA)) set TRANSPARENCY ALPHA in the layer using antialiased lines set ANTIALIAS TRUE in the STYLE element of the CLASS with antialiased lines The following maple snippets enable antialiased county borders:
... IMAGETYPE "png24" ... OUTPUTFORMAT NAME "png24" DRIVER "GD/PNG" MIMETYPE "image/png" IMAGEMODE RGB EXTENSION "png" END ... LAYER NAME "counties" TYPE line STATUS default DATA "bdry_counln2" TRANSPARENCY alpha SYMBOLSCALE 5000000 CLASS STYLE WIDTH 3 COLOR 1 1 1 ANTIALIAS true END END END ...
Note: The bdry_counln2 shapele referenced in the counties layer is a line shapele. A polygon shapele could be substituted with roughly the same results, though owing to the nature of shapeles each border would be rendered twice and the resulting output line would likely appear to be slightly thicker. Alternatively, one could use a polygon shapele, set TYPE to POLYGON, and use OUTLINECOLOR in place of COLOR in the STYLE element. Note: You can tweak the combination of STYLE->WIDTH and SYMBOLSCALE to modify line widths in your output images. See Also: Cartoline symbols can be used to achieve fancier effects.
19.20 Which OGC Specications does MapServer support?

See: OGCSUPPORT
870
Chapter 19. FAQ
19.21 Why does my requested WMS layer not align correctly?

Requesting a layer from some ArcIMS WMS connectors results in a map with misalgned data (the aspect ratio of the pixels looks wrong). Some ArcIMS sites are not set up to stretch the returned image to t the requested envelope by default. This results in a map with data layers that overlay well in the center of the map, but not towards the edges. This can be solved by adding reaspect=false to the request (by tacking it on to the connection string). For example, if your maple is in a projection other than EPSG:4326, the following layer will not render correctly:
LAYER NAME "hillshade" TYPE RASTER STATUS OFF TRANSPARENCY 70 CONNECTIONTYPE WMS CONNECTION "http://gisdata.usgs.net:80/servlet19/com.esri.wms.Esrimap/USGS_WMS_NED?" PROJECTION "init=epsg:4326" END METADATA "wms_srs" "EPSG:4326" "wms_title" "US_NED_Shaded_Relief" "wms_name" "US_NED_Shaded_Relief" "wms_server_version" "1.1.1" "wms_format" "image/png" END END
Adding reaspect=false to the connection string solves the problem:
LAYER NAME "hillshade" TYPE RASTER STATUS OFF TRANSPARENCY 70 CONNECTIONTYPE WMS CONNECTION "http://gisdata.usgs.net:80/servlet19/com.esri.wms.Esrimap/USGS_WMS_NED?reaspect=false PROJECTION "init=epsg:4326" END METADATA "wms_srs" "EPSG:4326" "wms_title" "US_NED_Shaded_Relief" "wms_name" "US_NED_Shaded_Relief" "wms_server_version" "1.1.1" "wms_format" "image/png" END END
19.22 When I do a GetCapabilities, why does my browser want to download mapserv.exe/mapserv?

A beginner question here... Im new to MS and to Apache. Ive got MS4W up and running with the Itasca demo. Now I want to enable it as a WMS server. mapserv -v at the command line tells me it supports WMS_SERVER. When I
19.21. Why does my requested WMS layer not align correctly?
871
point my browser to it, my browser just wants to download mapserv.exe! What am I missing? Here is the URL Im using to issue a GetCapabilities WMS request: http://localhost/cgibin/mapserv.exe?map=../htdocs/itasca/demo.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities The OGC:WMS 1.1.0 and 1.1.1 specications (which are both supported by MapServer) state that, for GetCapabilities responses, the OGC:WMS server returns a specic MIME type (i.e. application/vnd.ogc.xml (see subclause 6.5.3 of OGC:WMS 1.1.1. A MIME type is passed from the web server to the client (in your case, a web browser), from which a client can decide how to process it. Example 1: if using a web browser, if a web server returns an HTTP Header of Content-type:image/png, then the web browser will know that this is a PNG image and display it accordingly. Example 2: if using a web browser, if a web server returns an HTTP Header of Content-type:text/html, then the web browser will know that this is an HTML page and display it accordingly (i.e. tables, divs, etc.) Basically, what is happening is that the OGC:WMS is returning, in the headers of the HTTP response, a MIME type which your web browser does not understand, which usually prompts a dialog box on whether to open or download the content (i.e. Content-type:application/vnd.ogc.wms_xml). You could congure your web browser to handle the application/vnd.ogc.wms_xml MIME type a certain way (i.e. open in Notepad, etc.).
19.23 Why do my WMS GetMap requests return exception using MapServer 5.0?
Before upgrading to MapServer 5.0, I was able to do quick GetMap tests in the form of: http://wms.example.com/wms?service=WMS&version=1.1.1&request=GetMap&layers=foo Now when I try the same test, MapServer WMS returns an XML document saying something about missing required parameters. Whats going on here? This was a major change for WMS Server support in MapServer 5.0. MapServer WMS Server GetMap requests now require the following additional parameters: srs bbox width height format styles Note: These parameters were always required in all versions of the WMS specication, but MapServer previously had not required them in a client request (even though most OGC WMS clients would issue them anyway to be consistent with the WMS spec). The request below now constitutes a valid GetMap request:
http://wms.example.com/wms?service=WMS&version=1.1.1&request=GetMap&layers=foo&srs=EPSG:4326&bbox=-18
Which is consistent with the WMS specication. More information on these parameters can be found in the WMS Server and the OGC WMS 1.1.1 specication 872 Chapter 19. FAQ
For more detailed information, see ticket 1088 Warning: STYLES, though a required WMS parameter, is now optional again in MapServer. For more detailed information, see ticket 2427
19.24 Using MapServer 6.0, why dont my layers show up in GetCapabilities responses or are not found anymore?
MapServer 6.0 introduces the option of hiding layers against OGC Web Service requests. OGC Web Services can provide powerful access to your geospatial data. It was decided to disable layer level request access as a default. See MS RFC 67: Enable/Disable Layers in OGC Web Services provides a full explanation of the changes and implications. To enable pre-6.0 behaviour, you can add the following to the WEB objects METADATA section in your maple:
"ows_enable_request" "*"
This will enable access of all layers to all OGC Web Service requests.
19.25 Where do I nd my EPSG code?

There is a text le epsg in your PROJ4 installation (e.g. /usr/local/share/proj/epsg) which contain the EPSG information used by PROJ4. In Windows, this is often located in C:\proj\nad or is found with an environment variable called PROJ_LIB. http://spatialreference.org allows you to search for EPSG codes. You can also have a look at: http://ocean.csl.co.uk More information to EPSG: http://www.epsg.org More information to PROJ4: http://trac.osgeo.org/proj
19.26 How can I reproject my data using ogr2ogr?

With ogr2ogr of course! ogr2ogr is a powerful utility that will transform the projections of your shapeles when passed the appropriate parameters. In my case, I was using MapServer to serve data in RI State Plane Feet. In order to do so, the data had to rst be converted to meters. Here is the command I used:
ogr2ogr -t_srs EPSG:32130 output.shp input.shp
Since my data already had a projection dened, I did not need to explicitly state a source projection. This command uses the EPSG denition for NAD83 Rhode Island (32130) and performs the feet to meters conversion. Now say my data wasnt already projected? Heres how we deal with that:
ogr2ogr -s_srs "+proj=tmerc +lat_0=41.08333333333334 +lon_0=-71.5 +k=0.999994 +x_0=100000 +y_0=0 +ell
Lets examine what is going on here: The -s_srs parameter explicitly denes a projection for the data. The parameters used here were taken out of the EPSG denition (in this case, 32130) in the epsg le(see the projection FAQ for more details on locating EPSG denitions). The entry for RI in the epsg le is as follows:
19.24. Using MapServer 6.0, why dont my layers show up in GetCapabilities responses or are not 873 found anymore?
# NAD83 / Rhode Island <32130> +proj=tmerc +lat_0=41.08333333333334 +lon_0=-71.5 +k=0.999994 +x_0=100000 +y_0=0 +ellps=GRS80
You can see how the denition in the initial command is formulated. Notice that the +units=m parameter has been changed to +to_meter=0.3408. This is important for the conversion. Where did the value of 0.3408 come from you ask? From the EPSG le! It has many goodies buried in it so by simply running grep to_meter epsg you can refresh your memory if you need to. The next parameter in the command is -t_srs EPSG:32130. This command tells ogr2ogr to transform the data to the EPSG code of 32130. After this is declared, all you need to do is declare a le name for your new shape le and to set which le is being used as the input (note: make sure you dont confuse the order of these two). Hit enter, bombs away, and enjoy your new data in meters!
19.27 How can I help improve the documentation on this site?

New documentation material and corrections to existing documentation are denitely very welcome. These contributions are handled through the same issue tracker used to track software bugs and enhancements. Follow the directions for submitting bugs at: http://www.mapserver.org/development/bugs.html. When creating a ticket, in the Component eld, select MapServer Documentation. If our ticket pertains to a specic web page, please include the URL to that page. If you have tips or examples that dont really t the denition of documentation, a good place to put them is the MapServer wiki at: http://trac.osgeo.org/mapserver/wiki
19.28 Whats with MapServers logo?

The MapServer logo illustrates the conuence of the Minnesota and Mississippi rivers, quite near to the home of the St. Paul Campus of the University of Minnesota, which was the birthplace of MapServer.
874
Chapter 19. FAQ
CHAPTER 20
License
Copyright (c) 1996-2008 Regents of the University of Minnesota. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation les (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies of this Software or works derived from this Software. THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
875
876
Chapter 20. License
CHAPTER 21
Credits
Major funding for development of MapServer has been provided by NASA through cooperative agreements with the University of Minnesota, Department of Forest Resources. Additional enhancements have been made by the State of Minnesota, Department of Natural Resources and the Land Management Information Center. MapServer and MapScript have been developed by Stephen Lime. Raster access module developed by Pete Olson and Stephen Lime. PHP/MapScript module was developed by DM Solutions and is maintained by MapGears. Portions copyright (c) 1998 State of Minnesota, Land Management Information Center.
877
878
Chapter 21. Credits
Bibliography
[FW1] Frank Warmerdam on the mapserver-dev: Message-Id: <[email protected]> Date: Wed, 17 Aug 2005 22:31:09 -0400 Subject: Re: Mapserver Plug-in Infastructure: RFC and PATCH
879
880
Bibliography
Index
Symbols
.NET Compilation, MapScript, 53 24bit Raster, 358 8bit Raster, 363
A
AGG, 853 Aggregate functions Cluster, 117 ALIGN LABEL, 141 SCALEBAR, 163 and Expressions, 127 ANGLE LABEL, 141 MAP, 154 STYLE, 163 angle WMS Vendor specic parameters, 444 ANTIALIAS LABEL, 142 STYLE, 164 SYMBOL, 168 Apache MS_MAPFILE, 431 ReWriteRule, 431 SetEnvIf, 432 Apache variables, 581 API MapScript, 192 area Expressions, 131 Area symbols, 87
Arithmetic expressions Expressions, 128 Arithmetic operations Expressions, 130 ASP script IIS, 432 Assymetrical line styling, 87 Attributes Expressions, 124 AUTO LAYER STYLEITEM, 151
B
BACKGROUNDCOLOR CLASS, 113 SCALEBAR, 163 STYLE, 164 BANDS LAYER PROCESSING, 358 beyond Expressions, 129 BLOCKXSIZE OUTPUTFORMAT FORMATOPTION, 159 BLOCKYSIZE OUTPUTFORMAT FORMATOPTION, 159 blue, 354 Raster query, 361 Boolean values MapScript Variables, 274 browse CGI mode, 578 BROWSEFORMAT WEB, 188 BUFFER CLUSTER, 116 LABEL, 142 buffer CGI, 577 881
Expressions, 131 Build MapScript PHP, 49
C
Cartographical symbols, 69 CGI, 59, 853 buffer, 577 context, 577 icon, 577 id, 577 img, 578 imgbox, 578 imgext, 578 imgshape, 578 imgsize, 578 imgxy, 578 layer, 578 layers, 578 map, 578 mapext, 578 mapshape, 578 mapsize, 578 mapxy, 578 maxx, 578 maxy, 578 minx, 578 miny, 578 mode, 578 mode browse, 578 mode coordinate, 579 mode featurenquery, 578 mode featurequery, 579 mode indexquery, 579 mode itemfeaturenquery, 579 mode itemfeaturequery, 579 mode itemnquery, 579 mode itemquery, 579 mode legend, 579 mode legendicon, 579 mode map, 579 mode nquery, 579 mode query, 579 mode reference, 579 mode scalebar, 579 mode zoomin, 579 mode zoomout, 579 qformat, 579 qitem, 579 qlayer, 579 qstring, 579 queryle, 579 ref, 580 refxy, 580 882
savequery, 580 scaledenom, 580 searchmap, 580 shapeindex, 580 slayer, 580 tileindex, 580 zoom, 580 zoomdir, 580 zoomsize, 580 CGI_CONTEXT_URL MAP CONFIG, 154 Change URL, 431 Change map le parameters, 580 CLASS, 113 BACKGROUNDCOLOR, 113 COLOR, 113 DEBUG, 113 EXPRESSION, 113 GROUP, 113 KEYIMAGE, 114 LABEL, 114 LAYER, 145 MAXSCALEDENOM, 114 MAXSIZE, 114 MINSCALEDENOM, 114 MINSIZE, 114 NAME, 114 OUTLINECOLOR, 114 OVERLAYBACKGROUNDCOLOR, 115 OVERLAYCOLOR, 115 OVERLAYMAXSIZE, 115 OVERLAYMINSIZE, 115 OVERLAYOUTLINECOLOR, 115 OVERLAYSIZE, 115 OVERLAYSYMBOL, 115 SIZE, 114 STATUS, 114 STYLE, 114 SYMBOL, 114 TEMPLATE, 115 TEXT, 115 VALIDATION, 115 class Raster query, 361 Classes MapScript, 195 MapScript PHP, 231 MapScript Python, 264 CLASSGROUP LAYER, 146 CLASSITEM EXPRESSION, 125 LAYER, 146
Index
classObj MapScript, 195 MapScript PHP, 231 Cloning MapScript Layer, 270 MapScript Maple, 269 CLOSE_CONNECTION LAYER PROCESSING, 150 CLUSTER, 115 BUFFER, 116 FILTER, 116 GROUP, 116 LAYER, 146 MAXDISTANCE, 116 REGION, 116 Cluster, 115 Aggregate functions, 117 Feature attributes, 117 FeatureCount, 117 Group, 117 clusterObj MapScript PHP, 233 COLOR CLASS, 113 LABEL, 142 QUERYMAP, 162 REFERENCE, 162 SCALEBAR, 163 STYLE, 164 COLOR_MATCH_THRESHOLD LAYER PROCESSING, 359 colorObj MapScript, 197 MapScript PHP, 233 Combining symbols, 76 commify Expressions, 130 Compilation MapScript .NET, 53 Win32, 40 COMPRESS OUTPUTFORMAT FORMATOPTION, 159 COMPRESSION OUTPUTFORMAT FORMATOPTION, 159 CONFIG CGI_CONTEXT_URL, MAP, 154 MAP, 154 MS_ENCRYPTION_KEY, MAP, 154 MS_ERRORFILE, MAP, 154 MS_NONSQUARE, MAP, 154 ON_MISSING_DATA, MAP, 154 PROJ_LIB, MAP, 155 CONNECTION JOIN, 137
LAYER, 146 Connection types MapScript Variables, 277 CONNECTIONTYPE JOIN, 137 LAYER, 146 Constants MapScript PHP, 230 contains Expressions, 129 context CGI, 577 coordinate CGI mode, 579 CP1252 ENCODING, 123 crosses Expressions, 129 CURL_CA_BUNDLE Environment variables, 849
D
DATA LAYER, 146 DATAPATTERN MAP, 155 DB connection types MapScript Variables, 277 DEBUG CLASS, 113 LAYER, 146 MAP, 155 DEFRESOLUTIONx MAP, 156 difference Expressions, 131 disjoint Expressions, 129 DITHER LAYER PROCESSING, 359 Download MapScript PHP, 48 drawEPP(): EPPL7 support is not available Error, 857 DRIVER OUTPUTFORMAT, 159 DUMP LAYER, 147 dwithin Expressions, 129
E
Element support SLD, 486 883
Index
Ellipse symbols, 70 EMPTY WEB, 188 ENCODING CP1252, 123 EUC-JP, 123 ISO-8859-1, 123 ISO-8859-2, 123 LABEL, 121, 142 Shift-JIS, 123 TIS-620, 123 UTF-8, 123 Environment variable MS_TEMPPATH, 189 Environment variables, 847 CURL_CA_BUNDLE, 849 MS_DEBUGLEVEL, 849 MS_ENCRYPTION_KEY, 849 MS_ERRORFILE, 849 MS_MAP_NO_PATH, 850 MS_MAP_PATTERN, 850 MS_MAPFILE, 850 MS_MAPFILE_PATTERN, 850 MS_MODE, 851 MS_OPENLAYERS_JS_URL, 851 MS_TEMPPATH, 851 MS_XMLMAPFILE_XSLT, 851 PROJ_LIB, 851 EPSG, 853 eq Expressions, 127129, 131 Erdas, 357 ERROR WEB, 188 Error drawEPP(): EPPL7 support is not available, 857 loadLayer(): Unknown identier. Maximum number of classes reached, 857 loadMapInternal(): Given map extent is invalid, 858 msGetLabelSize(): Requested font not found, 858 msLoadFontset(): Error opening fontset, 859 msLoadMap(): Failed to open map le, 859 msProcessProjection(): no options found in init le, 859 msProcessProjection(): No such le or directory, 859 msProcessProjection(): Projection library error.major axis or radius = 0 not given, 860 msQueryByPoint: search returned no results, 861 msReturnPage(): Web application error. Malformed template name, 861 msSaveImageGD(): Unable to access le, 861 msWMSLoadGetMapParams(): WMS server error, 862 Unable to load dll, 862
Error return codes MapScript Variables, 278 errorObj MapScript, 197 MapScript PHP, 234 Errors, 855 EUC-JP ENCODING, 123 Exception handling MapScript Python, 266 EXPRESSION CLASS, 113 CLASSITEM, 125 Expression types, 125 Expressions, 123 and, 127 area, 131 Arithmetic expressions, 128 Arithmetic operations, 130 Attributes, 124 beyond, 129 buffer, 131 commify, 130 contains, 129 crosses, 129 difference, 131 disjoint, 129 dwithin, 129 eq, 127129, 131 fromtext, 131 ge, 128, 132 gt, 128, 132 in, 128 intersects, 129 le, 128, 132 length, 130 Logical expressions, 127 lt, 128, 132 Mapserver expressions, 127 ne, 127, 132 not, 127 or, 127 overlaps, 129 Regular expression comparison, 125 round, 130 Spatial expressions, 129 Spatial functions, 130 String comparison, 125 String expressions, 127 String functions, 130 String operations, 129 Temporal expressions, 131 tostring, 130 touches, 129
884
Index
within, 129 EXTENSION OUTPUTFORMAT, 159 EXTENT LAYER, 147 MAP, 156 REFERENCE, 162 External overviews Raster, 363
F
FEATURE, 132 ITEMS, 132 LAYER, 147 POINTS, 132 TEXT, 132 WKT, 132 Feature attributes Cluster, 117 FeatureCount Cluster, 117 featurenquery CGI mode, 578 featurequery CGI mode, 579 File format FONTSET, 133 File types MapScript Variables, 276 FILTER CLUSTER, 116 LAYER, 147 Run-time substitution, 583 Filter Encoding, 853 Filter encoding Limitations, WFS, 481 OGC conformance tests, WFS, 482 Supported features, WFS, 478 Units of measure, WFS, 478 WFS, 477 FILTERITEM LAYER, 148 FONT LABEL, 142 Font types MapScript Variables, 275 FONTSET, 132 File format, 133 fontsetObj MapScript, 198 FOOTER JOIN, 137 LAYER, 148 WEB, 188 Index
FORCE LABEL, 143 FORMATOPTION BLOCKXSIZE, OUTPUTFORMAT, 159 BLOCKYSIZE, OUTPUTFORMAT, 159 COMPRESS, OUTPUTFORMAT, 159 COMPRESSION, OUTPUTFORMAT, 159 GAMMA, OUTPUTFORMAT, 159 INTERLACE, OUTPUTFORMAT, 159 INTERLEAVE, OUTPUTFORMAT, 159 NULLVALUE, OUTPUTFORMAT, 159 OUTPUTFORMAT, 159 PALETTE, OUTPUTFORMAT, 160 PALETTE_FORCE, OUTPUTFORMAT, 160 QUALITY, OUTPUTFORMAT, 159 QUANTIZE_COLORS, OUTPUTFORMAT, 160 QUANTIZE_FORCE, OUTPUTFORMAT, 159 TILED, OUTPUTFORMAT, 159 FreeType, 853 FROM JOIN, 137 fromtext Expressions, 131 Functions MapScript, 194 MapScript PHP, 231
G
GAMMA OUTPUTFORMAT FORMATOPTION, 159 GAP, 78 STYLE, 164 GD, 853 GDAL, 853 ge Expressions, 128, 132 Geographical reference systems, 160 GEOMTRANSFORM STYLE, 165 Georeferencing Raster, 364 GEOS, 853 GeoTIFF, 356 GetLegendGraphic WMS, 430 GetMap WMS, 429 GETSHAPE_STYLE_ITEMS LAYER PROCESSING, 150 GIF, 356 GML, 853 WFS Server, 466 GPX, 853 green, 354 885
Raster query, 361 GRID, 134 LABELFORMAT, 134 LAYER, 148 MAXARCS, 134 MAXINTERVAL, 134 MAXSUBDIVIDE, 134 MINARCS, 134 MININTERVAL, 134 MINSUBDIVIDE, 134 gridObj MapScript PHP, 234 GROUP CLASS, 113 CLUSTER, 116 LAYER, 148 Group Cluster, 117 gt Expressions, 128, 132
H
hashTableObj MapScript, 198 MapScript PHP, 235 Hatch polygon ll, 88 HEADER JOIN, 137 LAYER, 148 WEB, 188 https connections, 526
I
icon CGI, 577 id CGI, 577 IIS, 59 ASP script, 432 IMAGE REFERENCE, 162 Image modes MapScript Variables, 278 Image types MapScript Variables, 277 IMAGECOLOR LEGEND, 153 MAP, 156 SCALEBAR, 163 IMAGEMODE OUTPUTFORMAT, 160 imageObj MapScript, 198 MapScript PHP, 236 886
MapScript Python, 264 IMAGEPATH WEB, 188 IMAGETYPE MAP, 156 IMAGEURL WEB, 188 img CGI, 578 imgbox CGI, 578 imgext CGI, 578 imgshape CGI, 578 imgsize CGI, 578 imgxy CGI, 578 in Expressions, 128 INCLUDE MAP, 135 Include, 135 indexquery CGI mode, 579 Installation, 31 MapScript PHP, 49 Oracle, 61 Unix, 33 Win32, 40 intarray MapScript, 199 INTERLACE OUTPUTFORMAT FORMATOPTION, 159 INTERLEAVE OUTPUTFORMAT FORMATOPTION, 159 Internal overviews Raster, 363 International characters, 119 intersects Expressions, 129 INTERVALS SCALEBAR, 163 Introduction MapScript, 191 ISO-8859-1 ENCODING, 123 ISO-8859-2 ENCODING, 123 itemfeaturenquery CGI mode, 579 itemfeaturequery CGI mode, 579
Index
itemnquery CGI mode, 579 itemquery CGI mode, 579 ITEMS FEATURE, 132 LAYER PROCESSING, 150
J
JOIN, 136 CONNECTION, 137 CONNECTIONTYPE, 137 FOOTER, 137 FROM, 137 HEADER, 137 LAYER, 136, 148 NAME, 137 Supported formats, 136 TABLE, 137 TEMPLATE, 137 TO, 137 TYPE, 137 Join types MapScript Variables, 277 JPEG, 356
K
KEYIMAGE CLASS, 114 KEYSIZE LEGEND, 153 KEYSPACING LEGEND, 153
L
LABEL, 141 ALIGN, 141 ANGLE, 141 ANTIALIAS, 142 BUFFER, 142 CLASS, 114 COLOR, 142 ENCODING, 121, 142 FONT, 142 FORCE, 143 LEGEND, 153 MAXLENGTH, 143 MAXOVERLAPANGLE, 143 MAXSIZE, 143 MINDISTANCE, 143 MINFEATURESIZE, 143 MINSIZE, 143 OFFSET, 143 OUTLINECOLOR, 143 Index
OUTLINEWIDTH, 144 PARTIALS, 144 POSITION, 144 PRIORITY, 144 REPEATDISTANCE, 144 SCALEBAR, 163 SHADOWCOLOR, 144 SHADOWSIZE, 144 SIZE, 144 STYLE, 145 TYPE, 145 WRAP, 145 Label positions MapScript Variables, 275 Label size MapScript Variables, 275 LABEL_NO_CLIP LAYER PROCESSING, 150 LABELCACHE LAYER, 148 labelCacheMemberObj MapScript, 200 labelcacheMemberObj MapScript PHP, 236 labelCacheObj MapScript, 200 labelcacheObj MapScript PHP, 237 LABELFORMAT GRID, 134 LABELITEM LAYER, 148 LABELMAXSCALEDENOM LAYER, 148 LABELMINSCALEDENOM LAYER, 148 labelObj MapScript, 201 MapScript PHP, 237 LABELREQUIRES LAYER, 148 LAYER, 145 CLASS, 145 CLASSGROUP, 146 CLASSITEM, 146 CLUSTER, 146 CONNECTION, 146 CONNECTIONTYPE, 146 DATA, 146 DEBUG, 146 DUMP, 147 EXTENT, 147 FEATURE, 147 FILTER, 147
887
FILTERITEM, 148 FOOTER, 148 GRID, 148 GROUP, 148 HEADER, 148 JOIN, 136, 148 LABELCACHE, 148 LABELITEM, 148 LABELMAXSCALEDENOM, 148 LABELMINSCALEDENOM, 148 LABELREQUIRES, 148 MAP, 156 MAXFEATURES, 149 MAXGEOWIDTH, 149 MAXSCALEDENOM, 149 METADATA, 149 METADATA, SOS, 523 METADATA, WCS, 507 METADATA, WFS, 471 METADATA, WFS Client, 475 METADATA, WMS, 438 METADATA, WMS Client, 449 MINGEOWIDTH, 149 MINSCALEDENOM, 149 NAME, 149 OFFSITE, 150 OPACITY, 150 PLUGIN, 150 POSTLABELCACHE, 150 PROCESSING, 150 PROCESSING BANDS, 358 PROCESSING CLOSE_CONNECTION, 150 PROCESSING COLOR_MATCH_THRESHOLD, 359 PROCESSING DITHER, 359 PROCESSING GETSHAPE_STYLE_ITEMS, 150 PROCESSING ITEMS, 150 PROCESSING LABEL_NO_CLIP, 150 PROCESSING LOAD_FULL_RES_IMAGE, 359 PROCESSING LOAD_WHOLE_IMAGE, 359 PROCESSING LUT[_n], 359 PROCESSING OVERSAMPLE_RATIO, 360 PROCESSING raster options, 150 PROCESSING RESAMPLE, 360 PROCESSING SCALE, 360 PROJECTION, 151 REQUIRES, 151 SIZEUNITS, 151 STATUS, 151 STYLEITEM, 151 STYLEITEM AUTO, 151 SYMBOLSCALEDENOM, 151 TEMPLATE, 152 TILEINDEX, 152
TILEITEM, 152 TOLERANCE, 152 TOLERANCEUNITS, 152 TRANSFORM, 152 TYPE, 152 UNITS, 153 VALIDATION, 153 Layer Cloning, MapScript, 270 layer CGI, 578 Layer types MapScript Variables, 275 layerObj MapScript, 203 MapScript PHP, 239 layers CGI, 578 le Expressions, 128, 132 LEGEND, 153 IMAGECOLOR, 153 KEYSIZE, 153 KEYSPACING, 153 LABEL, 153 MAP, 156 OUTLINECOLOR, 153 POSITION, 153 POSTLABELCACHE, 153 STATUS, 153 TEMPLATE, 154 TRANSPARENT, 154 legend CGI mode, 579 LEGENDFORMAT WEB, 188 legendicon CGI mode, 579 legendObj MapScript, 208 MapScript PHP, 243 length Expressions, 130 libexslt, 189 libiconv, 120 libxslt, 189 Limitations WFS Filter encoding, 481 Limiters MapScript Variables, 278 Line join types MapScript Variables, 277 Line symbol overlay, 78 Line symbols, 76
888
Index
LINECAP STATUS, 157 STYLE, 85, 165 SYMBOLSET, 157 LINEJOIN TEMPLATEPATTERN, 157 STYLE, 85, 165 UNITS, 157 LINEJOINMAXSIZE WEB, 157 STYLE, 85, 165 map lineObj CGI, 578 MapScript, 209 CGI mode, 579 MapScript PHP, 244 Map projections, 160 LOAD_FULL_RES_IMAGE Map Scale, 853 LAYER PROCESSING, 359 mapext LOAD_WHOLE_IMAGE CGI, 578 LAYER PROCESSING, 359 Maple, 853 loadLayer(): Unknown identier. Maximum number of Cloning, MapScript, 269 classes reached MapScript, 268 Error, 857 Saving, MapScript, 269 loadMapInternal(): Given map extent is invalid SOS Server, 517 Error, 858 WCS Server, 495 Logical expressions WFS Client, 475 Expressions, 127 WFS Server, 466 lt WMS Client, 448 Expressions, 128, 132 WMS Server, 425 LUT[_n] mapObj LAYER PROCESSING, 359 MapScript, 209, 269 MapScript PHP, 245 M MapScript, 854 .NET Compilation, 53 MAP, 154 API, 192 ANGLE, 154 Classes, 195 CONFIG, 154 classObj, 195 CONFIG CGI_CONTEXT_URL, 154 colorObj, 197 CONFIG MS_ENCRYPTION_KEY, 154 errorObj, 197 CONFIG MS_ERRORFILE, 154 fontsetObj, 198 CONFIG MS_NONSQUARE, 154 Functions, 194 CONFIG ON_MISSING_DATA, 154 hashTableObj, 198 CONFIG PROJ_LIB, 155 imageObj, 198 DATAPATTERN, 155 intarray, 199 DEBUG, 155 Introduction, 191 DEFRESOLUTIONx, 156 labelCacheMemberObj, 200 EXTENT, 156 labelCacheObj, 200 IMAGECOLOR, 156 labelObj, 201 IMAGETYPE, 156 Layer Cloning, 270 INCLUDE, 135 layerObj, 203 LAYER, 156 legendObj, 208 LEGEND, 156 lineObj, 209 MAXSIZE, 156 Maple, 268 NAME, 156 Maple Cloning, 269 PROJECTION, 156 Maple Saving, 269 QUERYMAP, 156 mapObj, 209, 269 REFERENCE, 156 markerCacheMemberObj, 215 RESOLUTION, 156 outputFormatObj, 215 SCALEBAR, 157 OWSRequest, 216 SCALEDENOM, 157 PHP, 47, 229 SHAPEPATH, 157 PHP Build, 49 SIZE, 157 Index 889
PHP Classes, 231 PHP classObj, 231 PHP clusterObj, 233 PHP colorObj, 233 PHP Constants, 230 PHP Download, 48 PHP errorObj, 234 PHP Functions, 231 PHP gridObj, 234 PHP hashTableObj, 235 PHP imageObj, 236 PHP Installation, 49 PHP labelcacheMemberObj, 236 PHP labelcacheObj, 237 PHP labelObj, 237 PHP layerObj, 239 PHP legendObj, 243 PHP lineObj, 244 PHP mapObj, 245 PHP outputformatObj, 250 PHP OwsrequestObj, 251 PHP pointObj, 252 PHP projectionObj, 253 PHP querymapObj, 253 PHP rectObj, 254 PHP referenceMapObj, 254 PHP resultObj, 255 PHP scalebarObj, 255 PHP Setup, 48 PHP shapeleObj, 256 PHP shapeObj, 257 PHP styleObj, 259 PHP symbolObj, 261 PHP webObj, 262 pointObj, 217 projectionObj, 218 Python, 264 Python Classes, 264 Python Exception handling, 266 Python imageObj, 264 Python pointObj, 265 Python rectObj, 265 Querying, 271 rectObj, 219 referenceMapObj, 219 resultCacheMemberObj, 220 resultCacheObj, 220 scalebarObj, 221 shapeleObj, 221 shapeObj, 222 styleObj, 224 symbolObj, 225 symbolSetObj, 227 Variables, 273
Variables Boolean values, 274 Variables Connection types, 277 Variables DB connection types, 277 Variables Error return codes, 278 Variables File types, 276 Variables Font types, 275 Variables Image modes, 278 Variables Image types, 277 Variables Join types, 277 Variables Label positions, 275 Variables Label size, 275 Variables Layer types, 275 Variables Limiters, 278 Variables Line join types, 277 Variables Measured shape types, 276 Variables Query types, 276 Variables Querymap styles, 276 Variables Return codes, 278 Variables Shape types, 276 Variables Shapele types, 276 Variables Status values, 274 Variables Symbol types, 278 Variables Units, 274 webObj, 227 Mapscript Wrapper, 432 Mapscript wrappers WxS Services, 528 Mapserver expressions Expressions, 127 mapshape CGI, 578 mapsize CGI, 578 mapxy CGI, 578 MARKER REFERENCE, 162 markerCacheMemberObj MapScript, 215 MARKERSIZE REFERENCE, 162 MAXARCS GRID, 134 MAXBOXSIZE REFERENCE, 162 MAXDISTANCE CLUSTER, 116 MAXFEATURES LAYER, 149 MAXGEOWIDTH LAYER, 149 MAXINTERVAL GRID, 134
890
Index
MAXLENGTH LABEL, 143 MAXOVERLAPANGLE LABEL, 143 MAXSCALEDENOM CLASS, 114 LAYER, 149 WEB, 188 MAXSIZE CLASS, 114 LABEL, 143 MAP, 156 STYLE, 165 MAXSUBDIVIDE GRID, 134 MAXTEMPLATE WEB, 188 MAXWIDTH STYLE, 165 maxx CGI, 578 maxy CGI, 578 Measured shape types MapScript Variables, 276 Mercator, 854 METADATA LAYER, 149 SOS LAYER, 523 SOS WEB, 521 WCS LAYER, 507 WCS WEB, 505 WEB, 188 WFS Client LAYER, 475 WFS LAYER, 471 WFS WEB, 470 WMS Client LAYER, 449 WMS LAYER, 438 WMS WEB, 435 Metadata SOS, 521 WCS, 505 WFS, 470 WMS, 434 MIMETYPE OUTPUTFORMAT, 160 MINARCS GRID, 134 MINBOXSIZE REFERENCE, 162 MINDISTANCE LABEL, 143 MINFEATURESIZE LABEL, 143
MINGEOWIDTH LAYER, 149 MININTERVAL GRID, 134 MINSCALEDENOM CLASS, 114 LAYER, 149 WEB, 188 MINSIZE CLASS, 114 LABEL, 143 STYLE, 165 MINSUBDIVIDE GRID, 134 MINTEMPLATE WEB, 189 MINWIDTH STYLE, 165 minx CGI, 578 miny CGI, 578 mode browse, CGI, 578 CGI, 578 coordinate, CGI, 579 featurenquery, CGI, 578 featurequery, CGI, 579 indexquery, CGI, 579 itemfeaturenquery, CGI, 579 itemfeaturequery, CGI, 579 itemnquery, CGI, 579 itemquery, CGI, 579 legend, CGI, 579 legendicon, CGI, 579 map, CGI, 579 nquery, CGI, 579 query, CGI, 579 reference, CGI, 579 scalebar, CGI, 579 zoomin, CGI, 579 zoomout, CGI, 579 MS_DEBUGLEVEL Environment variables, 849 MS_ENCRYPTION_KEY Environment variables, 849 MAP CONFIG, 154 MS_ERRORFILE Environment variables, 849 MAP CONFIG, 154 MS_MAP_NO_PATH Environment variables, 850 MS_MAP_PATTERN Environment variables, 850
Index
891
MS_MAPFILE Apache, 431 Environment variables, 850 MS_MAPFILE_PATTERN Environment variables, 850 MS_MODE Environment variables, 851 MS_NONSQUARE MAP CONFIG, 154 MS_OPENLAYERS_JS_URL Environment variables, 851 MS_TEMPPATH Environment variable, 189 Environment variables, 851 MS_XMLMAPFILE_XSLT, 190 Environment variables, 851 msGetLabelSize(): Requested font not found Error, 858 msLoadFontset(): Error opening fontset Error, 859 msLoadMap(): Failed to open map le Error, 859 msProcessProjection(): no options found in init le Error, 859 msProcessProjection(): No such le or directory Error, 859 msProcessProjection(): Projection library error.major axis or radius = 0 not given Error, 860 msQueryByPoint: search returned no results Error, 861 msReturnPage(): Web application error. Malformed template name Error, 861 msSaveImageGD(): Unable to access le Error, 861 msWMSLoadGetMapParams(): WMS server error Error, 862
O
OFFSET LABEL, 143 STYLE, 85, 165 OFFSITE LAYER, 150 OGC, 854 OGC conformance tests WFS Filter encoding, 482 OGC Support, 423 OGR, 854 OM, 854 ON_MISSING_DATA MAP CONFIG, 154 OPACITY LAYER, 150 STYLE, 166 OpenLayers, 854 or Expressions, 127 Oracle, 325 Installation, 61 OUTLINECOLOR CLASS, 114 LABEL, 143 LEGEND, 153 REFERENCE, 162 SCALEBAR, 163 STYLE, 166 OUTLINEWIDTH LABEL, 144 Output formats WCS Server, 496 OUTPUTFORMAT, 157 DRIVER, 159 EXTENSION, 159 FORMATOPTION, 159 FORMATOPTION BLOCKXSIZE, 159 FORMATOPTION BLOCKYSIZE, 159 FORMATOPTION COMPRESS, 159 FORMATOPTION COMPRESSION, 159 FORMATOPTION GAMMA, 159 FORMATOPTION INTERLACE, 159 FORMATOPTION INTERLEAVE, 159 FORMATOPTION NULLVALUE, 159 FORMATOPTION PALETTE, 160 FORMATOPTION PALETTE_FORCE, 160 FORMATOPTION QUALITY, 159 FORMATOPTION QUANTIZE_COLORS, 160 FORMATOPTION QUANTIZE_FORCE, 159 FORMATOPTION TILED, 159 IMAGEMODE, 160 MIMETYPE, 160 NAME, 160 Index
N
NAME CLASS, 114 JOIN, 137 LAYER, 149 MAP, 156 OUTPUTFORMAT, 160 ne Expressions, 127, 132 not Expressions, 127 nquery CGI mode, 579 NULLVALUE OUTPUTFORMAT FORMATOPTION, 159 892
Template-driven output, 412 TRANSPARENT, 160 outputFormatObj MapScript, 215 outputformatObj MapScript PHP, 250 overlaps Expressions, 129 OVERLAYBACKGROUNDCOLOR CLASS, 115 OVERLAYCOLOR CLASS, 115 OVERLAYMAXSIZE CLASS, 115 OVERLAYMINSIZE CLASS, 115 OVERLAYOUTLINECOLOR CLASS, 115 OVERLAYSIZE CLASS, 115 OVERLAYSYMBOL CLASS, 115 OVERSAMPLE_RATIO LAYER PROCESSING, 360 OWSRequest MapScript, 216 OwsrequestObj MapScript PHP, 251
P
PALETTE OUTPUTFORMAT FORMATOPTION, 160 PALETTE_FORCE OUTPUTFORMAT FORMATOPTION, 160 PARTIALS LABEL, 144 PATTERN, 78 STYLE, 166 Performance tips Raster, 362 PHP Build, MapScript, 49 Classes, MapScript, 231 classObj, MapScript, 231 clusterObj, MapScript, 233 colorObj, MapScript, 233 Constants, MapScript, 230 Download, MapScript, 48 errorObj, MapScript, 234 Functions, MapScript, 231 gridObj, MapScript, 234 hashTableObj, MapScript, 235 imageObj, MapScript, 236 Installation, MapScript, 49 Index
labelcacheMemberObj, MapScript, 236 labelcacheObj, MapScript, 237 labelObj, MapScript, 237 layerObj, MapScript, 239 legendObj, MapScript, 243 lineObj, MapScript, 244 mapObj, MapScript, 245 MapScript, 47, 229 outputformatObj, MapScript, 250 OwsrequestObj, MapScript, 251 pointObj, MapScript, 252 projectionObj, MapScript, 253 querymapObj, MapScript, 253 rectObj, MapScript, 254 referenceMapObj, MapScript, 254 resultObj, MapScript, 255 scalebarObj, MapScript, 255 Setup, MapScript, 48 shapeleObj, MapScript, 256 shapeObj, MapScript, 257 styleObj, MapScript, 259 Support, 48 symbolObj, MapScript, 261 webObj, MapScript, 262 php, 59 pixel, 354 Pixmap polygon ll, 89 Pixmap symbols, 72 PLUGIN LAYER, 150 PNG, 356 Point symbols, 70 pointObj MapScript, 217 MapScript PHP, 252 MapScript Python, 265 POINTS FEATURE, 132 Polygon outlines, 103 POSITION LABEL, 144 LEGEND, 153 SCALEBAR, 163 POSTLABELCACHE LAYER, 150 LEGEND, 153 SCALEBAR, 163 Preprocessing Raster, 362 PRIORITY LABEL, 144 PROCESSING, 150 BANDS, LAYER, 358 CLOSE_CONNECTION, LAYER, 150
893
COLOR_MATCH_THRESHOLD, LAYER, 359 DITHER, LAYER, 359 GETSHAPE_STYLE_ITEMS, LAYER, 150 ITEMS, LAYER, 150 LABEL_NO_CLIP, LAYER, 150 LAYER, 150 LOAD_FULL_RES_IMAGE, LAYER, 359 LOAD_WHOLE_IMAGE, LAYER, 359 LUT[_n], LAYER, 359 OVERSAMPLE_RATIO, LAYER, 360 raster options, LAYER, 150 RESAMPLE, LAYER, 360 SCALE, LAYER, 360 Processing directives Raster, 358 Proj.4, 854 PROJ_LIB Environment variables, 851 MAP CONFIG, 155 PROJECTION, 160 LAYER, 151 MAP, 156 Projection, 854 projectionObj MapScript, 218 MapScript PHP, 253 Python Classes, MapScript, 264 Exception handling, MapScript, 266 imageObj, MapScript, 264 MapScript, 264 pointObj, MapScript, 265 rectObj, MapScript, 265
MapScript Variables, 276 queryle CGI, 579 QUERYFORMAT WEB, 189 Querying MapScript, 271 QUERYMAP, 162 COLOR, 162 MAP, 156 SIZE, 162 STATUS, 162 STYLE, 162 Querymap styles MapScript Variables, 276 querymapObj MapScript PHP, 253 Quotes escaping, 124
R
Raster, 854 24bit, 358 8bit, 363 External overviews, 363 Georeferencing, 364 Internal overviews, 363 Performance tips, 362 Preprocessing, 362 Processing directives, 358 Query, 360 Tile indexing, 357 Tiled datasets, 362 Warping, 358 World les, 364 Raster classication, 354 Raster data, 353 Raster formats, 356 Raster options, 150 raster options LAYER PROCESSING, 150 Raster query blue, 361 class, 361 green, 361 red, 361 value_list, 361 value_n, 361 x, 361 y, 361 rectObj MapScript, 219 MapScript PHP, 254 MapScript Python, 265 red, 354 Index
Q
qformat CGI, 579 qitem CGI, 579 qlayer CGI, 579 qstring CGI, 579 QUALITY OUTPUTFORMAT FORMATOPTION, 159 QUANTIZE_COLORS OUTPUTFORMAT FORMATOPTION, 160 QUANTIZE_FORCE OUTPUTFORMAT FORMATOPTION, 159 Query Raster, 360 query CGI mode, 579 Query types 894
Raster query, 361 ref CGI, 580 REFERENCE, 162 COLOR, 162 EXTENT, 162 IMAGE, 162 MAP, 156 MARKER, 162 MARKERSIZE, 162 MAXBOXSIZE, 162 MINBOXSIZE, 162 OUTLINECOLOR, 162 SIZE, 163 STATUS, 163 reference CGI mode, 579 referenceMapObj MapScript, 219 MapScript PHP, 254 refxy CGI, 580 REGION CLUSTER, 116 Regular expression comparison Expressions, 125 Regular expressions, 125 REPEATDISTANCE LABEL, 144 REQUIRES LAYER, 151 RESAMPLE LAYER PROCESSING, 360 RESOLUTION MAP, 156 resultCacheMemberObj MapScript, 220 resultCacheObj MapScript, 220 resultObj MapScript PHP, 255 Return codes MapScript Variables, 278 ReWriteRule Apache, 431 ROSA-Applet controls, 582 round Expressions, 130 Run-time substitution, 582 FILTER, 583 Supported parameters, 583
S
savequery Index
CGI, 580 Saving MapScript Maple, 269 SCALE LAYER PROCESSING, 360 SCALEBAR, 163 ALIGN, 163 BACKGROUNDCOLOR, 163 COLOR, 163 IMAGECOLOR, 163 INTERVALS, 163 LABEL, 163 MAP, 157 OUTLINECOLOR, 163 POSITION, 163 POSTLABELCACHE, 163 SIZE, 163 STATUS, 163 STYLE, 163 UNITS, 163 scalebar CGI mode, 579 scalebarObj MapScript, 221 MapScript PHP, 255 SCALEDENOM MAP, 157 scaledenom CGI, 580 Scaling of symbols, 70 searchmap CGI, 580 SetEnvIf Apache, 432 Setup MapScript PHP, 48 WMS Server, 425 SHADOWCOLOR LABEL, 144 SHADOWSIZE LABEL, 144 Shape types MapScript Variables, 276 Shapele, 854 Shapele types MapScript Variables, 276 shapeleObj MapScript, 221 MapScript PHP, 256 shapeindex CGI, 580 shapeObj MapScript, 222 MapScript PHP, 257
895
SHAPEPATH MAP, 157 Shift-JIS ENCODING, 123 simple: CGI controls, 577 SIZE CLASS, 114 LABEL, 144 MAP, 157 QUERYMAP, 162 REFERENCE, 163 SCALEBAR, 163 STYLE, 166 SIZEUNITS LAYER, 151 slayer CGI, 580 SLD, 484, 854 Element support, 486 SOS, 854 LAYER METADATA, 523 Metadata, 521 WEB METADATA, 521 SOS Server, 515 Maple, 517 Spatial expressions Expressions, 129 Spatial functions Expressions, 130 SpatialLite, 342 Special options, 150 Spherical Mercator, 854 SRS WFS Server, 468 Stacked symbols, 115 STATUS CLASS, 114 LAYER, 151 LEGEND, 153 MAP, 157 QUERYMAP, 162 REFERENCE, 163 SCALEBAR, 163 Status values MapScript Variables, 274 String comparison Expressions, 125 String expressions Expressions, 127 String functions Expressions, 130 String operations Expressions, 129 String quotation, 124
STYLE, 163 ANGLE, 163 ANTIALIAS, 164 BACKGROUNDCOLOR, 164 CLASS, 114 COLOR, 164 GAP, 164 GEOMTRANSFORM, 165 LABEL, 145 LINECAP, 85, 165 LINEJOIN, 85, 165 LINEJOINMAXSIZE, 85, 165 MAXSIZE, 165 MAXWIDTH, 165 MINSIZE, 165 MINWIDTH, 165 OFFSET, 85, 165 OPACITY, 166 OUTLINECOLOR, 166 PATTERN, 166 QUERYMAP, 162 SCALEBAR, 163 SIZE, 166 SYMBOL, 167 STYLEITEM AUTO, LAYER, 151 LAYER, 151 styleObj MapScript, 224 MapScript PHP, 259 Support PHP, 48 Supported features WFS Filter encoding, 478 Supported formats JOIN, 136 Supported parameters Run-time substitution, 583 SVG, 854 SWF, 855 SWIG, 855 SYMBOL, 168 ANTIALIAS, 168 CLASS, 114 STYLE, 167 Symbol center, 108 Symbol construction, 65 Symbol scaling, 68 Symbol specication, 68 Symbol types MapScript Variables, 278 symbolObj MapScript, 225 MapScript PHP, 261
896
Index
Symbology examples, 169 SYMBOLSCALEDENOM LAYER, 151 SYMBOLSET MAP, 157 symbolSetObj MapScript, 227
T
TABLE JOIN, 137 TEMPLATE CLASS, 115 JOIN, 137 LAYER, 152 LEGEND, 154 WEB, 189 Template substitution tags Template-driven output, 412 Template-driven output, 411 OUTPUTFORMAT, 412 Template substitution tags, 412 TEMPLATEPATTERN MAP, 157 Templating, 173 Temporal expressions Expressions, 131 TEMPPATH WEB, 189 TEXT CLASS, 115 FEATURE, 132 TIFF, 356 Tile indexing Raster, 357 TILED OUTPUTFORMAT FORMATOPTION, 159 Tiled datasets Raster, 362 TILEINDEX LAYER, 152 Tileindex, 855 tileindex CGI, 580 TILEITEM LAYER, 152 Time requests WMS Server, 453 TIS-620 ENCODING, 123 TO JOIN, 137 TOLERANCE LAYER, 152 Index
TOLERANCEUNITS LAYER, 152 tostring Expressions, 130 touches Expressions, 129 TRANSFORM LAYER, 152 TRANSPARENT LEGEND, 154 OUTPUTFORMAT, 160 Truetype symbols, 71 TYPE JOIN, 137 LABEL, 145 LAYER, 152
U
Unable to load dll Error, 862 Union layer, 183 UNITS LAYER, 153 MAP, 157 SCALEBAR, 163 Units MapScript Variables, 274 Units of measure WFS Filter encoding, 478 Unix Installation, 33 Wrapper script, 433 URL Change, 431 Use cases WCS, 510 UTF-8 ENCODING, 123
V
VALIDATION, 584 CLASS, 115 LAYER, 153 WEB, 189 value_list Raster query, 361 value_n Raster query, 361 Variable substitution, 187 Variables Boolean values, MapScript, 274 Connection types, MapScript, 277 DB connection types, MapScript, 277 Error return codes, MapScript, 278 897
File types, MapScript, 276 Font types, MapScript, 275 Image modes, MapScript, 278 Image types, MapScript, 277 Join types, MapScript, 277 Label positions, MapScript, 275 Label size, MapScript, 275 Layer types, MapScript, 275 Limiters, MapScript, 278 Line join types, MapScript, 277 MapScript, 273 Measured shape types, MapScript, 276 Query types, MapScript, 276 Querymap styles, MapScript, 276 Return codes, MapScript, 278 Shape types, MapScript, 276 Shapele types, MapScript, 276 Status values, MapScript, 274 Symbol types, MapScript, 278 Units, MapScript, 274 Vector, 855 Vector polygon ll, 92 Vector symbols, 70 Vendor specic parameters angle, WMS, 444 WMS, 444
W
Warping Raster, 358 WCS, 855 LAYER METADATA, 507 Metadata, 505 Use cases, 510 WEB METADATA, 505 WCS 1.1.0, 498 WCS 2.0, 500 WCS Server, 493 Maple, 495 Output formats, 496 WEB, 187 BROWSEFORMAT, 188 EMPTY, 188 ERROR, 188 FOOTER, 188 HEADER, 188 IMAGEPATH, 188 IMAGEURL, 188 LEGENDFORMAT, 188 MAP, 157 MAXSCALEDENOM, 188 MAXTEMPLATE, 188 METADATA, 188 METADATA, SOS, 521 898
METADATA, WCS, 505 METADATA, WFS, 470 METADATA, WMS, 435 MINSCALEDENOM, 188 MINTEMPLATE, 189 QUERYFORMAT, 189 TEMPLATE, 189 TEMPPATH, 189 VALIDATION, 189 Web map context WMS, 458 webObj MapScript, 227 MapScript PHP, 262 WFS, 855 Filter encoding, 477 Filter encoding Limitations, 481 Filter encoding OGC conformance tests, 482 Filter encoding Supported features, 478 Filter encoding Units of measure, 478 LAYER METADATA, 471 Metadata, 470 WEB METADATA, 470 WFS Client, 474 LAYER METADATA, 475 Maple, 475 WFS Server, 465 GML, 466 Maple, 466 SRS, 468 Win32 Compilation, 40 Installation, 40 within Expressions, 129 WKT FEATURE, 132 WMC, 855 WMS, 855 GetLegendGraphic, 430 GetMap, 429 LAYER METADATA, 438 Metadata, 434 Vendor specic parameters, 444 Vendor specic parameters angle, 444 Web map context, 458 WEB METADATA, 435 WMS 1.3.0, 433 WMS Client, 446 LAYER METADATA, 449 Maple, 448 WMS Server, 423 Maple, 425 Setup, 425
Index
Time requests, 453 World les Raster, 364 WRAP LABEL, 145 Wrapper Mapscript, 432 Wrapper script Unix, 433 WxS Services Mapscript wrappers, 528
X
x Raster query, 361 XML Maple support, 189
Y
y Raster query, 361
Z
zoom CGI, 580 zoomdir CGI, 580 zoomin CGI mode, 579 zoomout CGI mode, 579 zoomsize CGI, 580
Index
899

Map Server

Uploaded by

Copyright:

Available Formats

Map Server

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Map Server

Uploaded by

Copyright:

Available Formats

MapServer Documentation

The MapServer Team

December 16, 2011

14.4 14.5 14.6 14.7 14.8 14.9 14.10

19.20 19.21 19.22 19.23 19.24 19.25 19.26 19.27 19.28

20 License 21 Credits Bibliography Index

MapServer Documentation, Release 6.0.1

Note: The entire documentation is also available as a single PDF document

and ePub document

MapServer Documentation, Release 6.0.1

MapServer Documentation, Release 6.0.1

2.1 MapServer Overview

MapServer Documentation, Release 6.0.1

2.2 Anatomy of a MapServer Application

Chapter 2. An Introduction to MapServer

MapServer Documentation, Release 6.0.1

Figure 2.1: The basic architecture of MapServer applications.

2.2. Anatomy of a MapServer Application

MapServer Documentation, Release 6.0.1

2.3 Installation and Requirements

Chapter 2. An Introduction to MapServer

MapServer Documentation, Release 6.0.1

2.3. Installation and Requirements

MapServer Documentation, Release 6.0.1

Chapter 2. An Introduction to MapServer

MapServer Documentation, Release 6.0.1

2.3. Installation and Requirements

MapServer Documentation, Release 6.0.1

8. Verify that MapServer is working

Chapter 2. An Introduction to MapServer

MapServer Documentation, Release 6.0.1

2.3.2 Hardware Requirements

2.3.3 Software Requirements

2.3. Installation and Requirements

MapServer Documentation, Release 6.0.1

2.4 Introduction to the Maple

Chapter 2. An Introduction to MapServer

MapServer Documentation, Release 6.0.1

2.4.1 MAP Object

2.4. Introduction to the Maple

MapServer Documentation, Release 6.0.1

2.4.2 LAYER Object

See Also: Vector Data

2.4.3 CLASS and STYLE Objects

Chapter 2. An Introduction to MapServer

MapServer Documentation, Release 6.0.1

Figure 2.3: Rendered Bluemarble image with vector boundaries

where symbols.txt might contain:

and the maple would contain:

2.4. Introduction to the Maple

MapServer Documentation, Release 6.0.1

Figure 2.4: Rendered Bluemarble image with styled roads

Chapter 2. An Introduction to MapServer

MapServer Documentation, Release 6.0.1

2.4. Introduction to the Maple

MapServer Documentation, Release 6.0.1

2.4.6 CLASS Expressions

Chapter 2. An Introduction to MapServer

MapServer Documentation, Release 6.0.1

therefore the main maple would contain: