UTFGrid Output

Author

Francois Desjarlais

Contact

fdesjarlais1 at gmail.com

Last Updated

2020-07-23

Introduction

UTFGrid is an output format that was added in MapServer version 7. This howto assumes that you have basic knowledge of the mapfile syntax (see Mapfile).

Functionality

UTFGrid output will allow more interaction with maps by allowing data to be exposed via an invisible UTF-8 character grid.

See also

MS RFC 93: UTF Grid Support

Build

  • Iconv is required.

  • AGG is required.

Setting the OutputFormat

Adding the following to the mapfile will allow mapserver to use generate UTFGrid output. For this example, the output generated will be a grid with each pixel corresponding to a 4x4 pixels square in the original image. Also, it will not allow duplicates which means different shapes with the same IDs will be considered as a single shape.

OUTPUTFORMAT
  NAME "utfgrid"
  DRIVER UTFGRID
  MIMETYPE "application/json"
  EXTENSION "json"
  FORMATOPTION "UTFRESOLUTION=4"
  FORMATOPTION "DUPLICATES=false"
END

If no FORMATOPTION is set, default values will be used. Default values are: 4 for UTFRESOLUTION and true for DUPLICATES.

Exposing Feature Properties

Two LAYER parameters are used to choose which data to expose. To use them, add these to your LAYER in the mapfile.

UTFITEM   "id"
UTFDATA   "{\"id\":\"[id]\",\"name\":\"[name]\"}"

The items can be used separately. If UTFITEM is not set, a sequence number (based on the rendering order) will be used as the grid ID. If UTFDATA is not set, no data beyond the UTFITEM will be exposed.

Note

UTFGrids can be set on multiple layers, but only one UTFGrid can be rendered at a time. If you wish to add multiples UTFGrids, with for example OpenLayers, you need to add a new layer for each of them.

Note

Due to upcoming changes in text rendering the UTFGrid driver doesn’t support Truetype symbol rendering.