MapGuide RFC 159 - UTFGrid support

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	6 Jun 2017
Last Modified	16 Jun 2017
Author	Jackie Ng
RFC Status	implemented
Implementation Status	completed
Proposed Milestone	3.3
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1	Jackie,Gordon,Crispin
+0	Haris
-0
-1
no vote

Overview

This RFC proposes to add support for the rendering and storage/retrieval of UTFGrid tiles

Motivation

UTFGrid is a compact JSON-based specification for storing rasterized interaction data and nicely complements XYZ map tiles.

Where XYZ tiles provide the visuals, UTFGrid provides the tooltip interaction data. Combined together, you can have powerful interactive tiled maps that require no sessions or server roundtrips for tooltip data as they can be queried locally from the UTFGrid tile.

For a more in-depth overview of UTFGrid see: ​https://www.mapbox.com/blog/how-interactivity-works-utfgrid/

Proposed Solution

This RFC will implement version 1.3 of the UTFGrid specification.

Add a new API to MgRenderingService for the rendering of UTFGrid tiles.

class MG_MAPGUIDE_API MgRenderingService : public MgService
{
PUBLISHED_API:
    /////////////////////////////////////////////////////////////////
    /// \brief
    /// Returns the specified UTFGrid tile for the given map. Tile structure is
    /// based on the XYZ tiling scheme used by Google Maps, OpenStreetMap, and
    /// others
    ///
    /// \param map
    /// Input
    /// map object containing current state of map.
    /// \param baseMapLayerGroupName
    /// Input
    /// Specifies the name of the baseMapLayerGroup for which to render the tile.
    /// \param x
    /// Input
    /// Specifies the row index of the tile to return.
    /// \param y
    /// Input
    /// Specifies the column index of the tile to return.
    /// \param z
    /// Input
    /// Specifies the zoom level of the tile to return.
    /// \param dpi
    /// Input
    /// Specifies the dpi of the tile to return.
    /// \param tileImageFormat
    /// Input
    /// Specifies the image format of the tile to return.
    ///
    /// \return
    /// A byte reader containing the rendered UTFGrid tile.
    ///
    /// \since 3.3
    virtual MgByteReader* RenderTileUTFGrid(
        MgMap* map,
        CREFSTRING baseMapLayerGroupName,
        INT32 x,
        INT32 y,
        INT32 z,
        INT32 dpi) = 0;
};

The server-side implementation of this API taps into a new UTFGrid renderer in the Renderers project. The UTFGrid renderer uses the existing AntiGrain Geometry (AGG) library to render "pixels" of UTF characters.

To avoid unnecessary reinventing of the wheel, our UTFGrid renderer implementation re-uses MapServer's ​implementation of the low-level AGG pixel primitives needed to render UTF character "pixels"

We will leverage the infrastructure introduced in RFC 140 to add support for UTFGrid tiles.

Support for UTFGrid tiles is exposed through the new TileFormat of UTFGRID in the existing XYZ tile provider.

Retrieval of UTFGrid tiles is achieved through the existing GETTILEIMAGE mapagent operation version 1.2.0, with the MAPDEFINITION parameter pointing to a Tile Set Definition resource configured:

• With the XYZ tile provider
• With the TileFormat of UTFGRID

For this RFC, UTFGrid rendering takes the following into consideration:

• It only looks at layers in the Tile Set that have a tooltip and/or URL defined in their Layer Definition
• Tooltip and Hyperlink content for features in these matching layers are rendered out as the following properties:
  • MG_TOOLTIP: The tooltip content for the feature
  • MG_URL: The associated hyperlink for the feature

Thus, if you have a Tile Set configured with a TileFormat of UTFGRID, but have no layers that have tooltips or hyperlinks defined in their respective Layer Definitions, the UTFGrid tiles rendered and retrieved from such a Tile Set Definition will be blank.

This implementation resides in the ​utfgrid sandbox. Upon adoption of this RFC, it will be merged into trunk.

Implications

A Tile Set Definition using the XYZ provider and a TileFormat of UTFGRID can only be used on versions of MapGuide on/since the introduction of this RFC.

Test Plan

Add unit tests for rendering UTFGrids, compare with image-based XYZ tiles at the same X/Y/Z coordinates for "visual" verification of UTFGrid content.

Funding / Resources

Community