Presented at FOSS4G 2014 in Portland, Oregon. Advanced tips on using MapServer (http://www.mapserver.org). Video of the presentation is available at: http://vimeo.com/106867779

1. MapServer #ProTips
FOSS4G Portland 09/11/14
MapServer for Power Users
A collection of tips to streamline your mapping workflow

2. #Protip: Use OGR Output format for
generating GeoJSON
FOSS4G Portland 09/11/14

3. WFS OGR Outputformat - GeoJSON
FOSS4G Portland 09/11/14
OUTPUTFORMAT
NAME "geojson"
DRIVER "OGR/GEOJSON"
MIMETYPE "application/json; subtype=geojson"
FORMATOPTION "STORAGE=stream"
FORMATOPTION "FORM=SIMPLE"
END
Just add: &request=getFeature&typename=myLayer&outputformat=geojson
Example: WFS Call - Returns XML WFS - Returns GeoJSON

4. #Protip: Simplify mapfiles with
SCALETOKEN
FOSS4G Portland 09/11/14

5. FOSS4G Portland 09/11/14
SCALETOKENs
Reduce Mapfile Clutter - Example: US HUC Codes - 6 layers -> 1 layer
LABELITEM "HUCCODE"
SCALETOKEN
NAME "%table%"
VALUES
"0" "HUC12 as HUCCODE, shape from USDA.WBDHU12"
"100000" "HUC10 as HUCCODE, shape from USDA.WBDHU10"
"700000" "HUC8 as HUCCODE, shape from USDA.WBDHU8"
"1500000" "HUC6 as HUCCODE, shape from USDA.WBDHU6"
"3000000" "HUC4 as HUCCODE, shape from USDA.WBDHU4"
"8000000" "HUC2 as HUCCODE, shape from USDA.WBDHU2"
END
END
DATA "SHAPE from (select %table%) using SRID 4326"

6. #Protip: Discover performance issues,
problems, etc with DEBUG
FOSS4G Portland 09/11/14

7. FOSS4G Portland 09/11/14
DEBUGGING - Part 1
● set DEBUG level at MAP and/or LAYER level
● can see GDAL/OGR debug info with CPL_DEBUGMAP
...
CONFIG "CPL_DEBUG" "ON"
...
LAYER
...
END
END
● use shp2img command line utility with
‘-all_debug” switch maximum debug info

8. FOSS4G Portland 09/11/14
DEBUGGING - Part 2
● can execute problem query at the command line (and avoid using Apache/Web server)
mapserv -nh “QUERY_STRING=”
● http://www.mapserver.org/optimization/debugging.html

9. #Protip: Preview layers immediately
with built in viewer
FOSS4G Portland 09/11/14

10. Using Native OpenLayers Viewer
(part1)
● added in MapServer 6.0
● quickly view map output using JS/’slippy’ interface
● required parameters for CGI request:
FOSS4G Portland 09/11/14
&MODE=map&TEMPLATE=OpenLayers
&LAYERS=all

11. Using Native OpenLayers Viewer
(part2)
● Notes:
o Points to remote OpenLayers.lib ‘out-of-the-box’ (version 2.10)
§ http://www.mapserver.org/lib/OpenLayers-ms60.js
FOSS4G Portland 09/11/14
o Can use own OL/template

12. FOSS4G Portland 09/11/14
Using Native OpenLayers Viewer (demo)

13. #Protip: Simply your mapfile (and your
life) with INCLUDEs
FOSS4G Portland 09/11/14

14. FOSS4G Portland 09/11/14
MapFile INCLUDEs
● Used anytime you want to reuse something or make a change in one place to affect many
places
● Key places: LAYERs, connection strings, metadata, settings, paths, debug info
● Can be nested
● File can be given any extension (.lay, .inc)

15. FOSS4G Portland 09/11/14
INCLUDE Ideas:
● Empty INCLUDE for every level (makes easy to add something to every layer)
● For databases, CONNECTION info and PROCESSING "CLOSE_CONNECTION=DEFER"
● Standard LAYER METADATA
● Standard WEB METADATA / OUTPUTFORMATs
● Projection blocks: INCLUDE "latlon.inc"
● Standard Label style blocks
● (Mike) use includes for data layers by category, INCLUDE "include/dam_water_levels.inc",
which includes 12 layers about Dams

16. FOSS4G Portland 09/11/14
Example Mapfile with Includes
MAP
NAME mymap
INCLUDE "include/paths.inc"
INCLUDE "include/outputformats.inc"
INCLUDE "include/web.inc"
#LAYERS
INCLUDE "include/base_layers.inc"
INCLUDE "include/mid_layers.inc"
INCLUDE "include/top_layers.inc"
END#map

17. #Protip: Make your maps more colorful
with COLORRANGE
FOSS4G Portland 09/11/14

18. FOSS4G Portland 09/11/14
COLORRANGE
● RFC 6 / RFC 108 / ‘easter egg’
● display a range of colors for a range of values
● useful for display of DEMs
● No Legend Output
STYLE
COLORRANGE 0 0 0 255 255 0 #black to yellow
DATARANGE 0 to 2000
RANGEITEM “[pixel]”
END

19. FOSS4G Portland 09/11/14
Multiple COLORRANGEs (7.0)
OPACITY 60
CLASS
STYLE
COLORRANGE "#0000ff00" "#0000ffff"
DATARANGE 0 32
END
STYLE
COLORRANGE "#0000ffff" "#ff0000ff"
DATARANGE 32 255
END
END

20. #Protip: Reduce problems by following
simple naming guidelines
FOSS4G Portland 09/11/14

21. FOSS4G Portland 09/11/14
Naming Conventions
● Avoid, whenever possible, using LAYER NAMEs with spaces, special characters, numbers at the
beginning, or uppercase. LAYER NAMEs are Case Sensitive. Never use colons (:), they will be
treated as namespace characters in the OGC output
● The issue is not MapServer, but often painful challenges ‘downstream’ (URLs, OGC Specs,
WMS/OWS, other applications, …)
● For Oracle, use all uppercase Column Names in the database (Oracle standard), can't start
with numbers, max 30 characters.
● For PostgreSQL, can’t start with numbers, use lowercase, max 63 characters.

22. #Protip: Combine multiple point
features into a CLUSTER
FOSS4G Portland 09/11/14

23. FOSS4G Portland 09/11/14
CLUSTERing Points
● Requires MapServer 6.0 or later
● Only for POINT layers
● Based on relative distance in pixels
● Query all clustered features with
PROCESSING "CLUSTER_GET_ALL_SHAPES"

24. #Protip: Combine TILEINDEXes across
multiple projections
FOSS4G Portland 09/11/14

25. FOSS4G Portland 09/11/14
TILEINDEXes with SRS Support
● Requires GDALTINDEX from 1.11 or later, MapServer 6.4 or later
● call GDALTINDEX with -src_srs_name to add SRS field to index and -t_srs output projection
gdaltindex -t_srs epsg:3857 -src_srs_name SRS ti.shp imagery/naip/*.jp2
● Also make sure to add a spatial index to the TILEINDEX
o use OGR or SHPTREE to add Shapefile spatial index
● However, TILEINDEXes don't have to be shapefiles, can be other formats
● If path to TILEINDEX is not absolute, it will be affected by SHAPEPATH
● Only for RASTERS

26. FOSS4G Portland 09/11/14
TILEINDEXes with SRS Support
LAYER
name naip16
TYPE raster
PROJECTION
"init=epsg:32616"
END
group "naip"
TILEINDEX "tileindexes/zones/ti_zone16.shp"
TILEITEM "PATH"
STATUS OFF
FILTERITEM "PROGRAM"
FILTER "NAIP"
METADATA
"ows_name" "naip16"
...
END
PROCESSING "OVERSAMPLE_RATIO=1.0"
END
LAYER
name naip17
TYPE raster
PROJECTION
"init=epsg:32617"
END
group "naip"
TILEINDEX "tileindexes/zones/ti_zone17.shp"
TILEITEM "PATH"
...
16 total layers
LAYER
name naip
TYPE raster
PROJECTION
"init=epsg:3857"
END
TILEINDEX "tileindexes/naip.shp"
TILEITEM "PATH"
TILESRS "SRS"
STATUS OFF
FILTERITEM "PROGRAM"
FILTER "NAIP"
METADATA
"ows_name" "naip"
...
END
PROCESSING "OVERSAMPLE_RATIO=1.0"
END

27. #Protip: Increase performance by
setting layer extents
FOSS4G Portland 09/11/14

28. FOSS4G Portland 09/11/14
“ows_extent” METADATA
● set it to avoid MapServer calculating the extents of your data layer on each request
● Sometimes solves problems for certain formats (OracleSpatial layer through OWS request)

29. #Protip: Catch errors quicker and
easier with syntax highlighting
FOSS4G Portland 09/11/14

30. FOSS4G Portland 09/11/14
Syntax Highlighting - Editor
Sublime 2 - https://github.com/richardsuematsu/sublime-text-2-mapserver
UltraEdit - http://www.ultraedit.com/files/wf/mapserver.uew
Notepad++ - https://github.com/AstunTechnology/MapserverSyntaxHighlighting
VIM - http://mapserver.org/development/editing/vim.html
Emacs - https://github.com/AxxL/mapserver-emacs-mode
Textpad - http://www.textpad.com/add-ons/files/syntax/map_40.zip
● Code folding is very useful to find missings/extra ENDs in mapfiles
● Comment block macros are also very useful for mapfiles

31. FOSS4G Portland 09/11/14
Thank you for using MapServer!
@mapserving @michael_smith