terrain and wmts interfaces display listing and provide README file

mapproxy/debian/bionic/control

@@ -17,4 +17,4 @@ m4_define({{{VAR_BuildDepends}}},{{{debhelper (>= 11), libboost1.65-all-dev
     , libprocps-dev (>= 3.3.12)
     , libmagic-dev (>= 5.32)
     , libicu-dev (>= 60.2-3ubuntu3)
-    , gawk}}})m4_dnl
+    , gawk, pandoc}}})m4_dnl

mapproxy/debian/stretch/control

@@ -16,4 +16,4 @@ m4_define({{{VAR_BuildDepends}}},{{{debhelper (>= 9.20150101+deb8u2), libboost1.
     , protobuf-compiler
     , libprocps-dev (>= 3.3.9)
     , libmagic-dev (>= 5.25)
-    , gawk}}})m4_dnl
+    , gawk, pandoc}}})m4_dnl

mapproxy/debian/wheezy/control

@@ -11,4 +11,4 @@ m4_define({{{VAR_BuildDepends}}},{{{debhelper (>= 7.0.50~), libboost-all-dev (>=
     , libblas-dev (>= 1.2.20110419-5), libcrypto++-dev (>= 5.6)
     , libgdal-dev (>= 2.0), libproj-dev (>= 4.9)
     , libmysql++-dev (>= 3.0.9-1+b1), libopenmesh-dev (>= 2.3.1-2)
-    , libgeographiclib-dev (>= 1.21-1)}}})m4_dnl
+    , libgeographiclib-dev (>= 1.21-1), pandoc}}})m4_dnl

mapproxy/src/mapproxy/CMakeLists.txt

@@ -179,6 +179,9 @@ file_to_cpp(mapproxy_CESIUM_SOURCES
 file_to_cpp(mapproxy_CESIUM_SOURCES
   cesium::melowntech_png
   cesium/melown-technologies-logo-28.png)
+pandoc_to_cpp(mapproxy_CESIUM_SOURCES
+  cesium::README_md
+  cesium/README.md)
 
 set(mapproxy_OL_SOURCES
   ol.hpp ol.cpp
@@ -189,6 +192,9 @@ file_to_cpp(mapproxy_OL_SOURCES
 file_to_cpp(mapproxy_OL_SOURCES
   ol::ol_js
   ol/ol.js)
+pandoc_to_cpp(mapproxy_OL_SOURCES
+  ol::README_md
+  ol/README.md)
 
 add_executable(mapproxy
   ${mapproxy_SOURCES}

mapproxy/src/mapproxy/cesium.cpp

@@ -29,12 +29,13 @@
 #include "cesium/cesium.html.hpp"
 #include "cesium/cesium.js.hpp"
 #include "cesium/melown-technologies-logo-28.png.hpp"
+#include "cesium/README.md.html.hpp"
 
 namespace cesium {
 
 const vtslibs::storage::SupportFile::Files supportFiles =
 {
-    { "index.html"
+    { "browser.html"
       , {
             cesium_html
             , sizeof(cesium_html)
@@ -55,6 +56,13 @@ const vtslibs::storage::SupportFile::Files supportFiles =
             , melowntech_png_attr_lastModified
             , "image/png"
         }
+    }, { "README"
+      , {
+            README_md
+            , sizeof(README_md)
+            , README_md_attr_lastModified
+            , "text/html; charset=utf-8"
+        }
     }
 };
 

mapproxy/src/mapproxy/cesium/README.md

@@ -0,0 +1,23 @@
+# VTS Mapproxy resource Cesium Terrain Provider interface
+
+## Generail info
+
+Cesium Terrain Proviver interface allowd VTS surface resource to be used in any
+Cesium application as a terrain provider.
+
+For every terrain-enabled reference frame mapproxy provides a
+[layer.json](layer.json) file containing layer description and
+appropriateterrain files.
+
+If the original dataset doesn't cover whole Earth the undefined height is
+replaced with zero height.
+
+There's an [interactive browser](browser.html) provided by mapproxy for testing
+and evaluation.
+
+You can the use the [URL of this directory[(.) to add this resource as a terrain
+provider to your Cesium application.
+
+    var terrainProvider = new Cesium.CesiumTerrainProvider({
+        url: "path-to-this-resource"
+    });

mapproxy/src/mapproxy/fileinfo.cpp

@@ -53,6 +53,8 @@ namespace constants {
     const std::string DebugConfig("debug.json");
     const std::string Self("");
     const std::string Index("index.html");
+    const std::string Browser("browser.html");
+    const std::string README("README");
     const std::string Dems("dems.html");
     const std::string Geo("geo");
     const std::string Style("style.json");
@@ -570,7 +572,10 @@ TerrainFileInfo::TerrainFileInfo(const FileInfo &fi)
         LOG(debug) << "Browser enabled, checking browser files.";
 
         auto path(fi.filename);
-        if (constants::Self == path) { path = constants::Index; }
+        if ((constants::Self == path) || (constants::Index == path)) {
+            type = Type::listing;
+            return;
+        }
 
         // support files
         auto fsupport(cesium::supportFiles.find(path));
@@ -611,21 +616,31 @@ Sink::FileInfo TerrainFileInfo::sinkFileInfo(std::time_t lastModified) const
         return Sink::FileInfo(constants::applicationJson, lastModified)
             .setFileClass(FileClass::config);
 
+    case Type::listing:
     case Type::unknown:
         return {};
     }
 
     return {};
 }
 
+const Sink::Listing TerrainFileInfo::listing {
+    { constants::Browser }
+    , { constants::LayerJson }
+    , { constants::README }
+};
+
 WmtsFileInfo::WmtsFileInfo(const FileInfo &fi)
     : fileInfo(fi), type(Type::unknown), support()
 {
     if (fi.flags & FileFlags::browserEnabled) {
         LOG(debug) << "Browser enabled, checking browser files.";
 
         auto path(fi.filename);
-        if (constants::Self == path) { path = constants::Index; }
+        if ((constants::Self == path) || (constants::Index == path)) {
+            type = Type::listing;
+            return;
+        }
 
         // support files
         auto fsupport(ol::supportFiles.find(path));
@@ -657,14 +672,18 @@ Sink::FileInfo WmtsFileInfo::sinkFileInfo(std::time_t lastModified) const
         return Sink::FileInfo(constants::textXml, lastModified)
             .setFileClass(FileClass::config);
 
+    case Type::listing:
     case Type::unknown:
         return {};
     }
 
     return {};
 }
 
-const std::string& WmtsFileInfo::capabilitesName()
-{
-    return constants::WmtsCapabilities;
-}
+const std::string WmtsFileInfo::capabilitesName = constants::WmtsCapabilities;
+
+const Sink::Listing WmtsFileInfo::listing {
+    { constants::Browser }
+    , { constants::WmtsCapabilities }
+    , { constants::README }
+};

mapproxy/src/mapproxy/fileinfo.hpp

@@ -227,7 +227,7 @@ struct TerrainFileInfo {
     FileInfo fileInfo;
 
     enum class Type {
-        unknown, tile, definition, support, cesiumConf
+        unknown, tile, definition, support, cesiumConf, listing
     };
 
     /** File type.
@@ -241,6 +241,8 @@ struct TerrainFileInfo {
     /** Valid only when type == Type::support
      */
     const vs::SupportFile *support;
+
+    static const Sink::Listing listing;
 };
 
 /** Parsed TMS file information.
@@ -254,7 +256,7 @@ struct WmtsFileInfo {
      */
     FileInfo fileInfo;
 
-    enum class Type { unknown, capabilities, support };
+    enum class Type { unknown, capabilities, support, listing };
 
     /** File type.
      */
@@ -264,7 +266,9 @@ struct WmtsFileInfo {
      */
     const vs::SupportFile *support;
 
-    static const std::string& capabilitesName();
+    static const std::string capabilitesName;
+
+    static const Sink::Listing listing;
 };
 
 #endif // mapproxy_fileinfo_hpp_included_

mapproxy/src/mapproxy/generator/surface.cpp

@@ -580,6 +580,10 @@ ::terrainInterface(const FileInfo &fileInfo, Sink &sink) const
         cesiumConf(sink, fi, tms);
         break;
 
+    case TerrainFileInfo::Type::listing:
+        sink.listing(fi.listing);
+        break;
+
     default:
         sink.error(utility::makeError<InternalError>
                     ("Not implemented yet."));

mapproxy/src/mapproxy/generator/tms-raster-base.cpp

@@ -125,13 +125,13 @@ wmts::WmtsResources TmsRasterBase::wmtsResources(const WmtsFileInfo &fileInfo)
         layer.rootPath =
             prependRoot(std::string(), resource(), resdiff);
 
-        resources.capabilitiesUrl = "./" + fileInfo.capabilitesName();
+        resources.capabilitiesUrl = "./" + fileInfo.capabilitesName;
     } else {
         layer.rootPath = *config().externalUrl
             + prependRoot(std::string(), resource()
                           , ResourceRoot::Depth::referenceFrame);
         resources.capabilitiesUrl =
-            layer.rootPath + "/" + fileInfo.capabilitesName();
+            layer.rootPath + "/" + fileInfo.capabilitesName;
     }
 
     return resources;
@@ -140,8 +140,6 @@ wmts::WmtsResources TmsRasterBase::wmtsResources(const WmtsFileInfo &fileInfo)
 Generator::Task TmsRasterBase
 ::wmtsInterface(const FileInfo &fileInfo, Sink &sink) const
 {
-    const auto &wmts(getWmts());
-
     WmtsFileInfo fi(fileInfo);
 
     switch (fi.type) {
@@ -157,14 +155,16 @@ ::wmtsInterface(const FileInfo &fileInfo, Sink &sink) const
         supportFile(*fi.support, sink, fi.sinkFileInfo());
         break;
 
+    case WmtsFileInfo::Type::listing:
+        sink.listing(fi.listing);
+        break;
+
     default:
         sink.error(utility::makeError<InternalError>
                     ("Not implemented yet."));
     }
 
     return {};
-
-    (void) wmts;
 }
 
 } // namespace generator

mapproxy/src/mapproxy/ol.cpp

@@ -28,12 +28,13 @@
 
 #include "ol/ol.html.hpp"
 #include "ol/ol.js.hpp"
+#include "ol/README.md.html.hpp"
 
 namespace ol {
 
 const vtslibs::storage::SupportFile::Files supportFiles =
 {
-    { "index.html"
+    { "browser.html"
       , {
             ol_html
             , sizeof(ol_html)
@@ -47,6 +48,13 @@ const vtslibs::storage::SupportFile::Files supportFiles =
             , ol_js_attr_lastModified
             , "application/javascript; charset=utf-8"
         }
+    }, { "README"
+      , {
+            README_md
+            , sizeof(README_md)
+            , README_md_attr_lastModified
+            , "text/html; charset=utf-8"
+        }
     }
 };
 

mapproxy/src/mapproxy/ol/README.md

@@ -0,0 +1,50 @@
+# VTS Mapproxy resource WMTS interface
+
+## Generail info
+
+WMTS interface allowd VTS raster resource to be used in WMTS enabled WWW clients
+or GIS tool.
+
+For every WMTS-enabled reference frame mapproxy provides a
+[WMTSCapabilities.xml](WMTSCapabilities.xml) file containing single layer for
+this particular resource.
+
+There's an [interactive browser](browser.html) provided by mapproxy for testing
+and evaluation.
+
+You can the use the [URL of this directory[(.)in tools like
+[GDAL](https://www.gdal.org/) or [QGIS](https://qgis.org/en/site/).
+
+## Examples
+
+### GDAL
+
+* GDAL: warp whole dataset into a TIF file 1024 px wide with aspect ratio kept
+
+         # gdalwarp wmts:http://.../WMTSCapabilities.xml output.tif -ts 1024 0 -r cubic
+
+     (please notice the `wmts:` URL prefix)
+
+### QGIS
+In QGIS desktop application:
+
+* Open the "Add Layer(s) from a WM(T)S Server" dialog:
+    * either via menu: `Layer` -> `Add Layer` -> `Add WMT/WMTS Layer...`
+    * or by keyboard shortcut: `Ctrl+Shift+W`
+* Click the `New` button to add new server connection
+    * Choose name for new server in tha `Name` field
+    * Paste the use [WMTSCapabilities.xml URL](WMTSCapabilities.xml) in the `URL` field
+    * Click OK to save the connection
+* New server connection should become selected in the drop-down list
+* Click the `Connect` button
+* Select the only layer available
+* Click the `Add` butto
+
+---
+
+*Nota bene*: If you want to use WMTS interface outside of introspection browser
+you have to have properly configured the `http.externalUrl` mapproxy
+configuration options. For example:
+
+    [http]
+    externalUrl = http://myserver.mydomain.com/mapproxy/root