MapGuide RFC 173 - Tile Service Enhancements (Round 3)

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	12 Jun 2019
Last Modified
Author	Jackie Ng
RFC Status	implemented
Implementation Status	complete
Proposed Milestone	4.0
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

This RFC proposes to build on top of the Tile Service Enhancements introduced in MapGuide Open Source 3.0 with RFC 140 and improved upon in this dev cycle with RFC 170

Motivation

RFC 140 introduced the concept of a tile set as a resource (TileSetDefinition) and support for XYZ tile sets.

RFC 170 incoprorated meta-tiling support (RFC90) by retrofitting the implementation on top of the Tile Set Definition infrastructure.

At this point, there are still several feature gaps and loose ends that this RFC will address.

Proposed Solution

This RFC will enhance our tile services with the following:

"Retina"/HiDPI tile support for XYZ tiles

A new RetinaScale tile set property is now available for XYZ tile sets which will render XYZ tiles at (256 * RetinaScale) x (256 * RetinaScale) pixels.

A supporting viewer can consume such tiles as regular XYZ tiles but with an appropriate scaling property (OpenLayers for example, ​can consume retina tiles via a tilePixelRatio property)

Removing tile set restriction from CREATERUNTIMEMAP

Until now, CREATERUNTIMEMAP (and its underlying MgMap.Create()) throws an exception when passing a XYZ tile set resource id or passing a resource id of a Map Definition that links to a XYZ tile set.

For this RFC, we will remove this restriction.

The reason for the removal is that when a client viewer wants to consume a CREATERUNTIMEMAP response, if it links to an XYZ tile set then the "finite scale list" is already well-defined and does not require server-side computation.

For such a map, CREATERUNTIMEMAP will produce an empty scale list.

To illustrate how such a response (with restrictions removed) can be consumed, a new OpenLayers demo is included that can load any Map Definition or (image-based) Tile Set Definition.

New MgMap APIs

New methods have been added to MgMap to describe this new information:

class MG_MAPGUIDE_API MgMap : public MgMapBase
{
PUBLISHED_API:
    ...

    //////////////////////////////////////////////////////////////////
    /// \brief
    /// Returns the provider name of the referenced tile set definition
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// string GetTileSetProvider();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// String GetTileSetProvider();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// string GetTileSetProvider();
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \since 4.0
    ///
    /// \return
    /// Returns the tile set provider name. Or an empty string if this map does not reference a tile set
    STRING GetTileSetProvider();

    //////////////////////////////////////////////////////////////////
    /// \brief
    /// Returns the tile pixel ratio for retina tiles. This is only
    /// applicable for XYZ tiles.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// int GetTilePixelRatio();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// int GetTilePixelRatio();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// int GetTilePixelRatio();
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \since 4.0
    ///
    /// \return
    /// Returns the tile pixel ratio for retina tiles
    INT32 GetTilePixelRatio();

    //////////////////////////////////////////////////////////////////
    /// \brief
    /// Returns the tile content format for the tile set definition
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// string GetTileFormat();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// String GetTileFormat();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// string GetTileFormat();
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \since 4.0
    ///
    /// \return
    /// Returns the tile content format
    STRING GetTileFormat();

    ...
};

New RuntimeMap XML schema

A new RuntimeMap-4.0.0.xsd schema will be introduced that models the changes introduced in this RFC.

What's changed from the 3.0.0 schema:

• MapDefinition is now optional
  • When CREATERUNTIMEMAP is created from a tile set, this element will not be specified
• A new TileFormat element that defines the tile content format of the linked tile set. This is a convenience property to avoid the consuming application from having to fetch the tile set resource separately to get this information.
• A new TilePixelRatio element that defines the retina scale (defaults to 1 if not specified in the tile set). This is a convenience property to avoid the consuming application from having to fetch the tile set resource separately to get this information.

A copy of this schema is attached below

Implementation Status

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

Implications

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

Although we have lifted the XYZ tile set restriction at the API level, we will still throw an exception from the AJAX viewer when loading a map from a XYZ tile set resource or from a map definition that links to a XYZ tile set as the AJAX viewer is not set up to consume XYZ tiles.

Test Plan

Add new CREATERUNTIMEMAP test cases to exercise creating runtime maps against XYZ tile sets and Map Definitions that link to XYZ tile sets and verify the new information is included in the response.

Funding / Resources

Community