Merge pull request #136 from ESA-APEx/geospatialexplorerguide

Geospatialexplorerguide

Author: JanssenBrm

_quarto.yml

@@ -75,6 +75,10 @@ website:
             text: Linking APEx STAC catalogue with an openEO service
           - href: guides/file_formats.qmd
             text: File format recommendations
+          - href: guides/geospatial_explorer_config_guide.md
+            text: Configuring the Geospatial Explorer
+          - href: guides/geospatial_explorer_guide.md
+            text: Using the Geospatial Explorer
           - href: guides/project_portal/index.qmd
             contents:
               - auto: guides/project_portal/tutorials/*.qmd

guides/geospatial_explorer_config_guide.qmd

@@ -0,0 +1,216 @@
+---
+title: Configuring the APEx Geospatial Explorer
+---
+The [APEx Geospatial Explorer](../instantiation/geospatial_explorer.md) is a versatile web application designed to visualize
+and interact with geospatial data. It leverages the OpenLayers library to provide a rich set of features for exploring spatial
+datasets. The application is highly configurable, allowing users to tailor its functionality and appearance to meet specific
+project requirements. This document outlines the configuration options for the APEx Geospatial Explorer, detailing the structure
+and properties of the configuration schema.
+
+## Configuration Schema
+
+The service configuration will be based on a schema that provides administrators with the expected structure and
+contents of the configuration. Taking this approach enables:
+
+* Automated and dynamic instantiation of the service with differing functionality.
+* Configuration validation.
+* Definition of a “contract” for easier documentation of features and their configuration.
+
+The sections below briefly outline the structure of the configuration schema and provide a preliminary description of
+each field/property within. The schema currently consists of four top-level fields and all properties are written in
+camel case.
+
+### Layout - `layout`
+
+An object with properties that modify the elements that the application will render. These properties and elements
+relate specifically to non-geospatial layout components, like navigation and footer.
+
+Currently supported properties:
+
+#### Navigation - `navigation`
+
+An object which supports two properties:
+
+* `logo`: A URL string that points to a logo image asset.
+* `title`: A string to be used as a title for the application.
+
+### Interface Groups - `interfaceGroups`
+
+An optional array of strings to be used as names/keys. This is currently used to configure the grouping of layer UI
+elements, such as the layer cards. This will be expanded in later versions.
+
+### Exclusivity Sets - `exclusivitySets`
+
+An optional array of strings to be used as names/keys. This is currently not in use but is a placeholder for future
+work.
+
+### Sources - `sources`
+
+An array of objects. Each object outlines a particular data source to be configured for display within the application,
+with properties detailing both the geospatial and user interface configuration.
+
+Currently supported properties within a source object are:
+
+#### Name - `name`
+
+A string that is used to identify layers in both the user interface and OpenLayers state
+
+#### Is Active - `isActive`
+
+A boolean. Determines if a layer is currently shown on the map. Setting this to true will show the layer on the map when
+the application loads.
+
+#### Time Frame - `timeframe`
+
+A string that is required to render and control time series layers. It should have a value of either `Days`, `Months`, `Years`.
+This will determine the behavior of the UI for layer groups with time series data configured.
+
+* Days: This will allow the selection of every available date within the configure data sources.
+* Months: This will only allow a user to select a the year and the month for the configured sources.
+* Years: This will allow only a single year to be selected for the dataset.
+
+For the best user experience it's essential to set this correctly for the series of datasets in use.
+
+#### Base Layer - `isBaseLayer`
+
+Optional boolean that determines if the layer should be treated as a base layer. Base layer groups are always active and
+cannot be toggled.
+
+#### Swipe Layer - `isSwipeLayer`
+
+Optional boolean that determines if the layer should be treated as a swipe layers. Swipe layer groups are configured much
+like any other layer group however the individual sources need to be configured with an additional position property with
+a value of either `left` or `right`.
+
+#### Layout - `layout`
+
+An object to determine which interface elements are rendered for the layer. Supports two properties:
+
+##### Layer Card - `layerCard`
+
+An object that will determine if a layer card should be rendered for this layer and what other interface elements should
+be rendered within the card. This is currently the main way to interact with a layer within the application. The layer
+card can show a toggle for the layer, a selection of buttons or controls for the layer, legends and attribution text.
+This currently supports the following properties:
+
+* `toggleable`: A boolean that determines if a toggle switch to enable/disable the layer should be rendered.
+* `controls`: An optional object that configures which buttons to render in the layer card for interaction with
+  the layer. This object can contain:
+  * `zoomToCenter`: A boolean that renders a button that will zoom the map to the extent of the layer.
+  * `opacitySlider`: A boolean that renders a button to open or close the opacity slider control for the layer.
+  * `download`: A URL string that will render a link to the given URL. Used for signposting users to the source data or website.
+* `legend`: An optional object that can be configured to show static or dynamic legend elements within the layer card
+  when active. Contains a `type` property that has a string value of: `swatch`, `image`, `gradient`. Also requires a `url`
+  property with a string value
+  if the type is `image`.
+
+##### Interface Group - `interfaceGroup`
+
+An optional string that is used to identify which interface group this layer belongs to.
+
+#### Metadata - `meta`
+
+An object that contains information describing the data source. This is generally used for information that would be used
+in multiple places across the application such as: units used to describe data values, the minimum and maximum value for
+use in UI/Visualisation calculations, attribution etc.
+
+This currently supports the following properties:
+
+* `attribution`: An optional object to render some text or a link for use with attribution of layer datasets.
+* `min`: An integer for the lower limit to use for data values when calculating UI elements such as legends, statistics,\
+colour ramps.
+* `max`: An integer for the upper limit to use for data values when calculating UI elements such as legends, statistics,\
+colour ramps.
+* `units`: An optional string that describes the units of any values derived from the data. Used in legends and statistics\
+panels.
+* `description`: An optional string that describes the dataset.
+* `startColor`: A string describing a valid hex or RGB/A colour value. This is used to render colour ramps and legends.
+* `categories`: An array of objects that contains a `label` (string) property, a `color` (string) property and a `value`\
+(integer) property. Describes classifications within datasets such as land usage. Used to create swatch legends and statistics
+ visualisation.
+
+#### Data - `data`
+
+An array of objects that configures the data to be displayed in the layer. If the length is more than one a layer group
+will be created and all sources will be treated as one layer.
+
+Each object currently supports the following properties:
+
+* `url`: A required URL string that points to the dataset's publicly available resource.
+* `format`: A required string that identifies what kind of dataset is requested. This can be one of the following: `wms`,
+`wmts`, `cog`, `xyz`, `wfs`, `flatgeobuf`, `stac` or `geojson`.
+* `layers`: Only required for sources of format: `wms` and `wmts`. A string that describes the layer to be requested from
+  the external service.
+* `typeName`: Only required for sources of format: `wfs`. A string that describes the type to be requested from the
+  external service.
+* `zIndex`: Optional integer that determines rendering order within the map. It can be used to override the default
+  rendering of Open Layers.
+* `exclusivitySet`: Optional string used to identify a group of other layers that should be disabled when this layer is
+  enabled. They must share the same string.
+* `projection`: Optional EPSG code string that describes the projection of the dataset to Open Layers. If the projection
+  is supported (and doesn't match the map's configured projection), it will attempt to reproject the data.
+* `style`: Open Layers style object that is passed through to the library to modify the rendering of the layer within
+  the map.
+* `normalise`: Only required for sources of format: `cog`. Boolean that configures the map to normalise the raster pixel
+  values to between 0 and 1. False by default.
+* `level`: A required integer for sources of type `statistical`. Ideally starting at 0, this integer describes the hierarchy
+of statistical sources. Higher integers should represent more complex and granular vector datasets. Used to provide the
+ statistics feature UI and maintain performance for large vector datasets.
+* `position`: A string of either `left` or `right` that is only required for swipe layer groups. This determines which side
+of the swipe control the date will be visualised on.
+* `timestamps`: An optional array of Unix timestamps or ISO8601 date strings. This allows the configuration of time series
+visualisation within the layer group. If multiple timestamps exist within the layer group and the timeframe property is
+ set a datepicker/stepper control will be rendered to cycle which layer is visible.
+
+## Example Configurations
+
+Numerous example configurations can be found in the
+[APEx Geospatial Explorer Configurations](https://github.com/ESA-APEx/apex_geospatial_explorer_configs) repository on GitHub.
+
+```{python}
+#| echo: false
+from IPython.display import display, HTML
+import requests
+
+examples_api_url = "https://api.github.com/repos/ESA-APEx/apex_geospatial_explorer_configs/contents/examples"
+example_base_url = "https://raw.githubusercontent.com/ESA-APEx/apex_geospatial_explorer_configs/main/examples/"
+example_gh_base_url = (
+    "https://github.com/ESA-APEx/apex_geospatial_explorer_configs/tree/main/examples/"
+)
+response = requests.get(examples_api_url)
+examples = response.json()
+cards = []
+for example in examples:
+    result_url = example_base_url + example["name"] + "/result.png"
+    example_url = example_gh_base_url + example["name"]
+
+    config_url = example_base_url + example["name"] + "/config.json"
+    config_response = requests.get(config_url)
+    config = config_response.json()
+    title = config["layout"]["navigation"]["title"]
+
+    card = f"""
+    <a href='{example_url}'>
+      <div class='card' style='width: 300px'">
+        <p class='card-img-top'>
+          <img src='{result_url}' class='thumbnail-image card-img' height='150'/>
+        </p>
+        <div class='card-body pot-contents'>
+          <h5 class='card-title listing-title'>{title}</h5>
+        </div>
+      </div>
+    </a>
+      """
+    cards.append(card)
+
+# Join the cards and return the result
+
+card_container = f"""
+<div style='display: flex; flex-wrap: wrap; gap: 1rem;'>
+  {''.join(cards)}
+</div></a>
+"""
+
+display(HTML(card_container))
+
+```

guides/geospatial_explorer_guide.md

@@ -0,0 +1,102 @@
+---
+title: Using the Geospatial Explorer
+---
+
+The [**APEx Geospatial Explorer**](../instantiation/geospatial_explorer.md) is a web map application with a configurable
+user interface that can be used to showcase the results of ESA projects as interactive maps, tables and charts.  This user
+guide provides some general user guidance for a number of supported features.
+
+:::{.callout-note}
+Users should be aware that the configuration of any specific Geospatial Explorer page will determine
+what is available on a case by case basis.  Examples of instantiated versions of the Geospatial Explorer are
+listed [here](../instantiation/geospatial_explorer.md#examples) on the project overview page.
+:::
+
+## Navigating around the map
+
+There are a number of options for navigating around the map:
+
+:::{.callout-tip}
+
+## You can
+
+* Use the "+" and "-" icons on the map to zoom in and out
+* Double click on the map to zoom in
+* Hold "shift" and double click on the map to zoom out
+* Hold "shift" and draw a rectangle on the map to zoom to a specific area
+of interest
+* Click and drag on the map to pan *Hold "alt", "shift" then click and drag on the map to rotate*
+* Click on the arrow in the top right to reset the map to north up
+:::
+
+A **scale bar** of your map view is visible in the bottom left of the map, and the **latitude** and **longitude**
+of your current cursor location at the bottom right.
+
+## Layer groups and layers
+
+The left hand panel of the Geospatial Explorer is used to add data to the map.  Typically data is organised into
+**layer groups**.
+
+![Layer groups](./images/geospatialexplorer/groups.jpg)
+
+Clicking on a specific layer group expands the layers within that group and displays a brief description of what
+that layer comprises.
+
+![Expanded layer groups](./images/geospatialexplorer/expanded.jpg)
+
+To add the data on to the map, use the toggle button. Once a layer is toggled on the layer panel will expand to
+show you more information about the layer - for example, a legend to help you interpret the map.  If it has been
+configured you may also see an attribution link, which may link you out to a project page or metadata record about
+the layer.  The example below has been linked to the **World Cover** website.
+
+![Layer displayed with legend and attribution statement](./images/geospatialexplorer/toggled-on.jpg)
+
+In some cases, according to how the explorer has been configured **switching one layer on may switch others off**.
+These *mutually exclusive* groups are often set up when it only makes sense to show one layer at a time, because
+viewing one layer would completely obscure another layer in the group.
+
+## Layer opacity
+
+In some circumstances a layer may have been configured to include an **opacity** control.  This gives you a slider
+that allows you to change the level of opacity to make the layer partially transparent, allowing you to view other
+map layers (such as background mapping) beneath the layer.
+
+![Opacity slider](./images/geospatialexplorer/opacity.jpg)
+
+## Layer "info" box
+
+For some layers (such as the **European Top Soil Layers** in the [SEF Food
+Demo](https://explorer.sef-food.apex.esa.int/)) clicking on the map drops a marker and displays an "info" box of
+the *latitude, longitude* and *data value* at the marker location, allowing you to display the precise value of
+the data at that point.
+
+![Layer info box](./images/geospatialexplorer/infobox.jpg)
+
+## Split screen view
+
+The Geospatial Explorer also allows different layers to be compared in a **split screen** view.  In the current
+release of the explorer, these comparison layers are defined in the configuration for a given explorer, but in
+a future release it will be possible for you to choose your own pair of layers to view in a split screen mode.
+When you are in a split screen mode, the slider at the bottom of the map allows you to "swipe" from left to right
+to compare the two layers with one another.
+
+![Split screen view](./images/geospatialexplorer/splitscreen.jpg)
+
+## Statistics
+
+Statistical data can also be displayed in the Geospatial Explorer as tables, charts and graphs.  These statistics are
+*pre-computed* for performance reasons, to specific boundary areas.  These could be administrative (e.g. national,
+regional or local boundaries) or natural (e.g. river basins).  The statistics that are available will depend on
+what the administrator of the Geospatial Explorer has defined for you.
+
+![Statistics](./images/geospatialexplorer/statistics.jpg)
+
+To access these, simply *click on a polygon* to display the statistics panel and then select from the table,
+bar or pie chart options.
+
+In some cases, there may be a hierarchy of boundaries available, allowing users to *"drill down"* from national
+to regional to local levels.  Each time a boundary is selected, the set of available boundaries at the next tier
+down are displayed.
+
+You will also notice that the statistics panel then contains a *"breadcrumb"* view of the boundaries.  You can
+navigate back up through your hierarchy by clicking on elements within the breadcrumb view.