From 3ec61f623b405f2ff1135c257b20568b4a134cc7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Stephan=20Mei=C3=9Fl?= <stephan.meissl@eox.at>
Date: Tue, 10 Mar 2020 13:37:06 +0100
Subject: [PATCH] Further work closing viewing and downloading chapters for
now.
---
documentation/usage-guide/downloading.rst | 28 +++++--
documentation/usage-guide/viewing.rst | 89 ++++++++++++++++++++---
2 files changed, 100 insertions(+), 17 deletions(-)
diff --git a/documentation/usage-guide/downloading.rst b/documentation/usage-guide/downloading.rst
index f3332f9d..972d7de9 100644
--- a/documentation/usage-guide/downloading.rst
+++ b/documentation/usage-guide/downloading.rst
@@ -3,13 +3,31 @@
Downloading
===========
+The download interface is implemented following the `Web Coverage Service (WCS)
+<https://www.ogc.org/standards/wcs>`_ as well as the `Download Service for Earth
+Observation Products Best Practice (DSEO)
+<https://portal.opengeospatial.org/files/?artifact_id=55210>`_ standards.
-`Web Coverage Service (WCS) <https://www.ogc.org/standards/wcs>`_
-`Download Service for Earth Observation Products Best Practice <https://portal.opengeospatial.org/files/?artifact_id=55210>`_
+These interfaces support both, the simple download of entire products via DSEO
+as well as flexible customized downloads via WCS. Both services can be accessed
+at the path ``/ows?``.
-TODO
- WCS
- DSEO
+The WCS offers the following customizations in order to optimize downloads and
+minimize unnecessarily used bandwidth:
+
+* `Earth Observation Application Profile (EO-WCS)
+ <http://docs.opengeospatial.org/is/10-140r2/10-140r2.html>`_
+* Meaningful default configuration
+* Spatial subset to retrieve only the geographic area of interest
+* Range subset to retrieve only the band(s) of interest
+* Scaling to required resolution
+* Format selection
+* Interpolation selection if needed
+* Projection selection
+
+Note that the download size in WCS is restricted in order to not block the
+service. Clients are advised to download bigger coverages in junks and but them
+together afterwards.
The final chapter :ref:`sample_requests` holds a list of sample requests against
the various services described in this usage guide.
diff --git a/documentation/usage-guide/viewing.rst b/documentation/usage-guide/viewing.rst
index 32181447..59ce8856 100644
--- a/documentation/usage-guide/viewing.rst
+++ b/documentation/usage-guide/viewing.rst
@@ -5,12 +5,15 @@ Viewing
The viewing interface is implemented following the `Web Map Tile Service (WMTS)
<https://www.ogc.org/standards/wmts>`_ as well as the `Web Map Service (WMS)
-<https://www.ogc.org/standards/wms>`_ . Both services are implemented by a wide
-range of client software which makes it as simple as possible to integrate the
-viewing service as needed.
+<https://www.ogc.org/standards/wms>`_ standards. Both services are implemented
+by a wide range of client software which makes it as simple as possible to
+integrate the viewing service as needed.
Service endpoints optimized for performance as well as for flexibility are
-provided alongside each other.
+provided alongside each other. Concrete example URLs demonstrating the
+capabilities of the various endpoints are provided in the chapter
+:ref:`sample_requests`.
+
Performance optimized service
-----------------------------
@@ -22,7 +25,8 @@ This endpoint offers access to predefined visualizations via WMTS and WMS. The
GetTile as well as GetMap requests are answered from image tiles cached on
object storage when possible. :numref:`fig_wmts_tiles` below shows the three
predefined visualizations, true color, false color, and NDVI of the same image
-tile.
+tile and :numref:`fig_wmts_masked` the unmasked and masked versions using the
+validity mask of one tile.
.. _fig_wmts_tiles:
.. figure:: images/wmts_tiles.*
@@ -30,6 +34,35 @@ tile.
*WMTS Tiles - True color, false color, and NDVI*
+.. _fig_wmts_masked:
+.. figure:: images/wmts_masked.*
+ :alt: WMTS Tiles - Unmasked and masked
+
+ *WMTS Tiles - Unmasked and masked*
+
+The operator might configure additional layers besides the default ones. These
+layers can offer a specific customization described below as performance
+optimized variant.
+
+For example for the VHR Image 2018 dataset not only the three default layers for
+True Color, False Color, and NDVI are configured but also the Masked Validity
+one as shown in the figures above.
+
+In addition the VHR Image 2018 dataset contains level 1 and 3 products. Thus
+individual layers aggregating each level individually are added making the total
+of offered layers twelve.
+
+Finally two layers are configured offering a quick true color visualization of
+the entire level 3 datasets without support of the time dimension both unmasked
+as well as masked. The masked layer is shown in
+:numref:`fig_webclient_fulllayer` below.
+
+.. _fig_webclient_fulllayer:
+.. figure:: images/webclient_start.*
+ :alt: Web Client - Full coverage layer
+
+ *Web Client - Full coverage layer*
+
Image tiles not yet present in the cache are stored upon first hit for
consecutive requests. This is the so-called on-demand caching. The operator
might decide for optimal performance, even for the first request, to pre-seed
@@ -49,8 +82,6 @@ as they are cached without the need of any reprocessing. WMS responses are
generated on-the-fly from image tiles and might thus need some reprocessing to
stitch together and scale image tiles.
-TODO: full layers
-
More sophisticated reprocessing like reprojection or custom color adjustments
are not offered at this endpoint.
@@ -65,8 +96,8 @@ This endpoint offers the following customizations via WMS:
* Access to individual products via ID (``cql=identifier='ID'``)
* Access to entire collections/datasets supporting ``time`` parameter
* Various layers as defined by the `Earth Observation Application Profile of WMS
- <https://portal.opengeospatial.org/files/?artifact_id=30912>`_ like one
- showing outlines of products (``__outlines``)
+ (EO-WMS) <https://portal.opengeospatial.org/files/?artifact_id=30912>`_ like
+ one showing outlines of products (``__outlines``)
* Additional useful layers like one showing both, products and outlines,
correctly rendering topology of outlines (``__outlined``) or one showing a
validity mask (``__validity``) or applied validity mask
@@ -82,16 +113,31 @@ This endpoint offers the following customizations via WMS:
All these customization parameters can of course be combined as needed.
+Please see the chapter :ref:`sample_requests` for detailed examples of all
+supported parameters.
+
Loading in QGIS
---------------
+Any of the above described layers can be loaded in client software supporting
+either the WMTS or WMS standard like for example `QGIS <https://qgis.org>`_.
+
+Open the Data Source Manager as shown in :numref:`fig_wms_qgis1` and create a
+new WMS/WMTS Connection using the URL to the layer of interest.
+When using parameters like for example ``cql=identifier='ID'`` to view one
+individual product make sure to tick the "Ignore GetMap/GetTile URI reported in
+capabilities" as these parameters are overwritten otherwise.
.. _fig_wms_qgis1:
.. figure:: images/wms_qgis1.*
- :alt: WMS loading in QGIS
+ :alt: QGIS - Create WMS/WMTS Connection
- *WMS loading in QGIS*
+ *QGIS - Create WMS/WMTS Connection*
+
+The next step is to retrieve the capabilities of the created WMS/WMTS Connection
+using the Connect button. Selected layers from the list are added using the Add
+button as shown in :numref:`fig_wms_qgis2`.
.. _fig_wms_qgis2:
.. figure:: images/wms_qgis2.*
@@ -99,4 +145,23 @@ Loading in QGIS
*WMS loading in QGIS*
-Continue reading about the provided :ref:`downloading` services.
+The TimeManager plugin offers a convenient way to navigate through the time
+dimension as shown in :numref:`fig_wms_qgis3`.
+
+.. _fig_wms_qgis3:
+.. figure:: images/wms_qgis3.*
+ :alt: WMS loading in QGIS
+
+ *WMS loading in QGIS*
+
+.. only:: builder_html
+
+ It even allows exporting an animation as shown in :numref:`fig_wms_qgis4` below.
+
+ .. _fig_wms_qgis4:
+ .. figure:: images/wmts_animation.gif
+ :alt: WMS loading in QGIS
+
+ *WMS loading in QGIS*
+
+Continue reading to learn about the provided :ref:`downloading` services.
--
GitLab