Changes between Initial Version and Version 1 of MapGuideRfc173

Timestamp:

Jun 11, 2019, 7:47:42 AM (5 years ago)

Author:

jng

Comment:

--

MapGuideRfc173

@@ +1 @@
+
+= !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 [wiki:MapGuideRfcs RFCs] page.
+
+== Status ==
+
+||RFC Template Version||(1.0)||
+||Submission Date||12 Jun 2019||
+||Last Modified||||
+||Author||Jackie Ng||
+||RFC Status||draft||
+||Implementation Status||pending||
+||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](https://openlayers.org/en/latest/examples/xyz-retina.html) 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.
+
+=== 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
+
+== 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