From ceac9919794174d7862b791c57692b35a354c49b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?V=C3=A1clav=20Bla=C5=BEek?= <vaclav.blazek@gmail.com>
Date: Fri, 26 May 2017 11:10:58 +0200
Subject: [PATCH] Update resources.md

---
 docs/resources.md | 73 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 3 deletions(-)

diff --git a/docs/resources.md b/docs/resources.md
index 0aa02f6..98f6e10 100644
--- a/docs/resources.md
+++ b/docs/resources.md
@@ -93,16 +93,83 @@ definition = {
 
 ## Surface drivers
 
+### Commpon surdace driver configuration options
+
+All surface drivers support these (optional) options:
+```javascript
+    Optional String geoidGrid           // name of Proj.4's geoid grid file (e.g. `egm96_15.gtx`).
+    Optional Double nominalTexelSize    // nominal resolution (meter/pixel);
+                                        // reported by mapproxy-calipers
+    Optional Int mergeBottomLod         // Reported in generated tileset.conf, speeds up merge
+                                        // with other surfaces
+    Optional Object/Array introspection // Introspection info used when using mapConfig.json served
+                                        // by mapproxy. See below.
+```
+
+Introspection is extending configuration for mapproxy served `mapConfig.json` (only when browsing is enabled).
+
+```javascript
+introspection = {
+    Optional Array position;   // VTS position in JSON/python format
+    Optional Object/Array tms  // bound layer(s) mapped on the surface, see below 
+}
+```
+
+TMS in the above introspection is one or more TMS resource identifiers:
+```javascript
+tms = [
+    {
+        String group           // group part of TMS resource identifier
+        Strting id             // ID part of TMS resource identifier
+    }
+    ...
+]
+```
+
+If there is just one TMS resource used in the introspection then the enclosing array is optional.
+
 ### surface-spheroid
 
 This driver generates meshed surface for reference frame's spheroid. If geoid grid is provided the resulting body
 is in fact a geoid.
 
+If a `textureLayerId` entry is present this ID is written into generated meshes as a default bound layer to use
+if nothing else is mapped on the surface. Otherwise surface is completely texture less.
+
+```javascript
+definition = {
+    Optional Int textureLayerId  // numeric bound layer ID
+}
+```
+
+### surface-dem
+
+This driver generates meshed surface from supplied GDAL raster DEM/DSM/DTM dataset.
+
+Since GDAL raster formats are
+unable to safely store vertical SRS component and thus it cannot tell whether data are in ellipsoidal or orthometric
+verical datum. Therefore by default data are treated as data above ellipsoid (i.e. ellipsoidal vertical datum). By providing
+a `geoidGrid` configuration option we can specify geoid grid for orthormetric vertical datum, i.e. to tell that the heights
+store in the GDAL dataset are relative to given geoid.
+
+Please be aware that due to such limitations the GDAL dataset's vertical system must be compatible with reference frame's
+vertical system to use geoid support. I.e. either they share the same ellipsoid or the input data are in some
+local system that approximates the geoid at given place. One working example is data in Krovak's projection that can
+be reinterpreted as heights above WGS84+EGM96.
+
+If a `textureLayerId` entry is present this ID is written into generated meshes as a default bound layer to use
+if nothing else is mapped on the surface. Otherwise surface is completely texture less.
+
+All `surface-dem` input datasets are registered in internal map od available DEM's under its `group-id` identifier
+and can be referenced from various `geodata`resources for 2D features heightcofing. See meore in `geodata` resources
+documentation. Optionially, input dataset can be registered in this map under an alias.
+
 ```javascript
 definition = {
-    Optional String geoidGrid    // Name of Proj.4's geoid grid file (e.g. `egm96_15.gtx`).
-    Optional Int textureLayerId  // Numeric bound layer ID. If present this ID is written into generated meshes
-                                 // as a default bound layer to use if nothing else is mapped on the surface.
+    String dataset                    // path to complex dataset
+    Optional String mask              // optional mask, generated by mapproxy-rf-mask tool
+    Optional Int textureLayerId       // numeric bound layer ID
+    Optional String heightcodingAlias // dataset is registered under given alias
 }
 ```