Geospatial Explorer
This section outlines the requirements for the interoperability of the APEx Geospatial Explorer services. These requirements must be met to ensure the correct configuration and operation of a dashboard and its instantiation.
A technical challenge of the Geospatial Explorer service being provided by APEx is that it is to be instantiated on demand, with functional requirements potentially varying amongst each service.The geospatial explorer makes ue of a well-defined configuration schema, provided in the form of JSON, that outlines the interactive features and data sources to be used.
This approach allows APEx to define and update the schema required in the interoperability guidelines, which will then enables requesters of the service to configure the Geospatial Explorer on an individual project level with minimal external intervention.
The schema is versioned as it will change throughout the APEx project as the functional capabilities of the Geospatial Explorer matures. This does allow for improvements and extra features to be easily added to the application, and best practices shall be followed to avoid any breaking changes between versions.
Requirements
Table 1 outlines the requirements for configuring an instance of the Geospatial Explorer application.
| ID | Requirement | Description |
|---|---|---|
| EXPLORER-REQ-01 | Configuration of the Geospatial Explorer shall adhere to the provided JSON schema. | The application is configured through a hosted JSON object which is fetched when the client-side application loads. For the application to correctly render, a valid configuration JSON that follows the outlined schema must be provided pre-instantiation. During early development the schema will be subject to change and provided with limited validation. |
| EXPLORER-REQ-02 | Raster sources defined within the config shall be provided as either: | The use of these formats ensures that raster data can be visualized using widely recognized and well-established standards. |
| EXPLORER-REQ-03 | Vector sources defined within the config shall be provided as either: | The use of these formats ensures that vector data can be visualized using widely recognized and well-established standards. |
| EXPLORER-REQ-04 | All external sources shall be publicly available. | Currently the application does not support fetching sources from hosts that require authentication. |
| EXPLORER-REQ-05 | All external sources shall be available utilising the HTTPS protocol. | It is best practice to utilise HTTPS where possible. Whilst not as of yet blocked specifically, non-secure resources may not function correctly. |
| EXPLORER-REQ-06 | Web service endpoints for data must be configured to allow cross-origin requests from the domain hosting the Geospatial Explorer. | This includes setting the Access-Control-Allow-Origin header to explicitly permit the origin of the requesting front end or using a dynamic or wildcard origin setting if appropriate. Additionally, the web service must handle preflight (OPTIONS) requests correctly, including the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers, to support the HTTP methods and headers used by the front end. |
| EXPLORER-REQ-07 | All datasets shall be projected to CRS EPSG:3857 (Web Mercator); EPSG:4326 (WGS84) or EPSG:3035 (ETRS89-extended / LAEA Europe) | Other projections may work but will not be explicitly supported in the initial versions of the application. Support for these projections will be considered and reviewed on a case-by-case basis and will be subject to support by the PROJ4JS library [8]. |
| EXPLORER-REQ-08 |
Legends should be configured by providing:
|
This guideline ensures that the legend is fully compatible with the visualisation library used in the Geospatial Explorer. |
| EXPLORER-REQ-09 | Statistical datasets should be configured by providing public URLs to either: GeoJSON [4] or FlatGeobuf [7] | The statistics feature is complex due to the architecture and requirements of the Geospatial Explorer. One or more files containing vector features that describe an area and the relevant statistics for the area can be added to the configuration of an explorer instance. |
(*) The XYZ approach refers to a de facto API standard for URL structuring (Z = zoom level, X and Y = grid references). While there is no dedicated specification for XYZ, it is widely used (e.g., OpenStreetMap).
Format Specification & Guidelines
Cloud Optimized GeoTiff (COG)
When generating Cloud Optimised GeoTiffs, it is recommended to use the GoogleMapsCompatible tiling scheme—typically 256x256 pixel tiles aligned to a global grid—and to store the image in the Web Mercator projection (EPSG:3857). The BitsPerSample field must accurately reflect the data format. Overviews are essential for performance and should be generated using downsampling by factors of two until the image dimensions are the size of a tile or smaller. These overviews should also be tiled and placed after the main image data to conform with the COG specification. An example command line invocation using GDAL would be:
gdal_translate <src> <dest> -of COG -co TILING_SCHEME=GoogleMapsCompatibleStatistics (Vector Layers)
The statistics feature expects vector layers that are provided in a format that can be parsed to a feature collection following the GeoJSON specification. Currently tested and supported formats are GeoJSON[4] and FlatGeobuf[7]. FlatGeobuf[7] should be used where the statistical data is a large size as this allows for streaming of the relevant features without having to download the full dataset, increasing performance.
Statistics should be contained within the properties entry of each feature. Each feature must contain the following properties:
id- A short unique id string.name- A description label for the feature to be shown to users.level- An integer that describes the features geographical hierarchy. This should be contiguous with parent and child features.children- A string based comma separated list containing theidof all child features.
Datasets that have classifications (such as land use) should have key:value entires consisting of ‘name’:‘value’ and an entry with a key of ‘classifications’ with a value consisting of a string based comma separated list containing all the keys for the classifications and a ‘total’ key with the sum of all other values. This will allow for correctly rendering bar charts and pie charts.
{
Bare / sparse vegetation: 3349.349614217657,
Built-up: 18474.280639104116
Cropland: 155067.6934300016
Grassland: 140178.79417018566
Herbaceous wetland: 1612.828666906516
Mangroves: 479.46053523623897
Moss and lichen: 499.40601429089236
Permanent water bodies: 8969.837211370474
Shrubland: 7342.96093361589
Snow and ice: 495.7695064816955
Tree cover: 301783.0035618253
Unknown: 1.7258467103820294
total: 638255.1101299465
classifications: "Tree cover,Shrubland,Grassland,Cropland,Built-up,Bare / sparse vegetation,Snow and ice,
Permanent water bodies,Herbaceous wetland,Mangroves,Moss and lichen,Unknown"
}
Datasets that do not have classifications (such as a raster showing soil organic carbon) should contain a selection of the following entries:
- mean
- min
- max
These values will be rendered as a table.
{
mean: 437.94353402030356
min: 60
max: 4410
}