= !MapGuide RFC 177 - Mapbox Vector Tile (MVT) support =

This page contains a change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.

== Status ==

||RFC Template Version||(1.0)||
||Submission Date||24 Sep 2019||
||Last Modified||||
||Author||Jackie Ng||
||RFC Status||implemented||
||Implementation Status||implemented||
||Proposed Milestone||4.0||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||Jackie,Reno,Martin,Gordon||
||+0||||
||-0||||
||-1||||
||no vote|| ||

== Overview ==

This RFC proposes to add support for the rendering and storage/retrieval of Mapbox Vector Tiles

== Motivation ==

Vector tiles are a way to deliver geographic data in small chunks to a browser or other client application. 

Vector tiles are similar to raster tiles, but instead of raster images, the data returned is a vector representation of the features in the tile.

Vector tiles relieves the burden of rendering/stylization on the MapGuide Server as stylization is now a responsibility of client mapping applications, allowing for 
much richer and interactive user/application experiences as in this case, the MapGuide Server only has to focus on the encoding and delivery of vector tiles.

Some factors that had delayed support for vector tiles in MapGuide include:

 1. The lack of consensus around a "standard" for vector tiles. Over time, it is clear that [https://docs.mapbox.com/vector-tiles/reference/ Mapbox Vector Tiles] is now the clear de-facto standard for vector tiles.
 2. The eco-system of suitable MVT encoding libraries in C++ demanding a C++11 compliant compiler at a bare minium in order to consume said libraries.
 
With the recent change to adopt C++11 in [wiki:MapGuideRfc172 MapGuide RFC 172], we now have the opportunity to finally add vector tiles support in MapGuide.

== Proposed Solution ==

This RFC will implement support for Mapbox Vector Tiles by re-using the [https://github.com/OSGeo/gdal/blob/master/gdal/ogr/ogrsf_frmts/mvt/mvt_tile.h MVT tile encoder] from the MVT driver in GDAL/OGR.

A new API will be added to MgRenderingService for the rendering of MVT tiles.

{{{
class MG_MAPGUIDE_API MgRenderingService : public MgService
{
PUBLISHED_API:
    /////////////////////////////////////////////////////////////////
    /// \brief
    /// Returns the specified MVT (Mapbox Vector 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 tile image.
    ///
    /// \since 4.0
    virtual MgByteReader* RenderTileMVT(
        MgMap* map,
        CREFSTRING baseMapLayerGroupName,
        INT32 x,
        INT32 y,
        INT32 z,
        INT32 dpi) = 0;
};
}}}

The mime type of the vector tile content will be `application/vnd.mapbox-vector-tile`, defined in a new `MgMimeType::Mvt` constant.

The server-side implementation of this API taps into a new `MVTRenderer` in the Renderers project. The `MVTRenderer` is basically the adapter between the Rendering/Stylization engine and MVT tile encoder.

We will leverage the tile set definition infrastructure introduced in [wiki:MapGuideRfc140 MapGuide RFC 140] to add support for MVT tiles.

MVT tile geometry will always be in web mercator (`EPSG:3857`) coordinates. Thus all vector data will be reprojected to `WGS84.PseudoMercator` when rendering MVT tiles and will incur the usual re-projection overheads for data not already in `WGS84.PseudoMercator`

Support for MVT tiles is exposed through the new {{{TileFormat}}} of {{{MVT}}} in the existing {{{XYZ}}} tile provider. 

Retrieval of MVT 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 {{{MVT}}}

Features that span multiple MVT tile boundaries will be clipped at the tile boundaries.

For the `GetDefaultTileSizeX` and `GetDefaultTileSizeY` APIs, it will return `4096` for MVT tile sets (ie. The default MVT tile size is `4096x4096`)

None of our existing viewer offerings will be updated to take advantage of Mapbox Vector Tiles. It is expected the main adopters of this feature when implemented are custom map viewers.

This implementation resides in the [http://trac.osgeo.org/mapguide/browser/sandbox/jng/mvt_alt mvt_alt 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 {{{MVT}}} can only be used on versions of MapGuide on/since the introduction of this RFC.

== Test Plan ==

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

== Funding / Resources ==

Community