Skip to content

Commit 5002499

Browse files
santillandsantilland
authored
Merge pull request #11 from eodash/processdef
feat: preview action and initial process doc page
2 parents 04f1a64 + dbbf2f8 commit 5002499

File tree

8 files changed

+308
-0
lines changed

8 files changed

+308
-0
lines changed

‎.github/workflows/deploy_docs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,5 @@ jobs:
2020
with:
2121
folder: ./.vitepress/dist/
2222
branch: gh-pages
23+
clean-exclude: pr-preview
24+
force: false

‎.github/workflows/preview.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# .github/workflows/preview.yml
2+
# This is a basic workflow takes care of building and deploying
3+
# client when creating merge request
4+
5+
name: Deploy PR previews
6+
7+
on:
8+
pull_request_target:
9+
branches:
10+
- main
11+
types:
12+
- opened
13+
- reopened
14+
- synchronize
15+
- closed
16+
# do not allow running multiple of pipelines for this PR in parallel
17+
concurrency: preview-${{ github.ref }}
18+
19+
jobs:
20+
deploy-preview:
21+
runs-on: ubuntu-22.04
22+
permissions:
23+
contents: write
24+
pages: write
25+
pull-requests: write
26+
steps:
27+
- uses: actions/setup-node@v4
28+
with:
29+
node-version: 20
30+
-
31+
uses: actions/checkout@v4
32+
with:
33+
submodules: 'true'
34+
ref: ${{ github.event.pull_request.head.ref }}
35+
repository: ${{ github.event.pull_request.head.repo.full_name }}
36+
- if: github.event.action != 'closed'
37+
run: |
38+
npm install
39+
npm run build -- --base /pr-preview/pr-${{ github.event.number }}/
40+
- name: Deploy preview
41+
uses: rossjrw/pr-preview-action@v1
42+
with:
43+
source-dir: .vitepress/dist/

‎.vitepress/config.mjs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,13 @@ export default defineConfig({
4040
{ text: 'Data configuration', link: '/data' },
4141
{ text: 'Styling', link: '/styling' },
4242
{ text: 'Storytelling', link: '/storytelling' },
43+
{
44+
text: 'Processing / API integration',
45+
link: '/processing',
46+
items: [
47+
{ text: 'Input definition', link: '/processing_inputs' },
48+
]
49+
},
4350
]
4451
}
4552
],

‎assets/process_definition.jpg‎

101 KB
Loading

‎assets/processing_results.jpg‎

63.8 KB
Loading

‎assets/vega_examples.jpg‎

66.6 KB
Loading

‎processing.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Processing / API integration
2+
3+
The eodash ecosystem allows integration of nearly limitless custom endpoints and APIs to further enrich the information that can be provided to the user.
4+
5+
Typical use cases are fetching time series or statistics for an area that can be either selected from already existing features on the map or allow the user to create a custom geometry that will be passed to the endpoint.
6+
7+
The three main configuration blocks can be seen in the figure below. They are basically definition of:
8+
9+
* **Input**: what inputs are required for the call
10+
* **Process call**: where is the endpoint and how will the inputs be passed
11+
* **Output**: how should the result be presented to the user
12+
13+
This means that in principle the whole definition can be done with two json files and the references in the STAC collection definition.
14+
15+
![processing diagram](./assets/process_definition.jpg)
16+
17+
## Input
18+
19+
The inputs needed for the endpoint to be queried can be configured through a **eodash:jsonform** definition. A url to this file needs to be included in the root of the STAC collection definition or configured in the eodash_catalog collection definition.
20+
21+
This in principle allows a broad spectrum of input fields as well as even custom widgets for helping the user select correct values. The component used in eodash to render the form is the [eox-jsonform](https://eox-a.github.io/EOxElements/?path=/docs/elements-eox-jsonform--docs) from the EOxElements. Which is in turn based on the [json-editor](https://github.com/json-editor/json-editor) software.
22+
23+
A typical json-form configuration file could look like this:
24+
25+
```json
26+
{
27+
"type": "object",
28+
"properties": {
29+
"feature_id": {
30+
"type": "string",
31+
"title": "Select feature on the map",
32+
"format": "feature",
33+
"options": {
34+
"drawtools": {
35+
"for": "eox-map#main",
36+
"layerId": "collection_layer_id"
37+
},
38+
"featureProperty": "id",
39+
"type": "string"
40+
}
41+
}
42+
},
43+
"options": {
44+
"execute": true
45+
}
46+
}
47+
```
48+
49+
This configuration allows the user to click on a feature on the map, and the endpoint will only need the `id` of that feature as a string.
50+
51+
The drawtool widget integrations is very customizable, allowing custom point/bbox/area selection and other options, a more in depth explanation and further examples can be found in the [Input definition](/processing_inputs) section.
52+
53+
## Process call
54+
55+
Once the inputs have been configured it is possible to define how they should be applied into the request.
56+
The usual RESTful interfaces allow to send a GET request to retrieve the relevant information. For example this could be a typical endpoint:
57+
58+
```
59+
https://greatapi.com/v1/feature/timeseries/austria
60+
```
61+
62+
By using templating language it is possible to utilize the properties that have been defined in the inputs. For example we can use the `feature_id` in the GET request. The definition in the eodash_catalog collection would be:
63+
64+
```yaml
65+
Process:
66+
Name: "timeseries",
67+
JsonForm: "https://url.to/jsonform.json"
68+
VegaDefinition: "https://url.to/vega_chart.json"
69+
EndPoints:
70+
- Identifier: "timeseries"
71+
Url: "https://greatapi.com/v1/feature/timeseries/{{feature_id}}"
72+
Type: "application/json"
73+
Method: "GET"
74+
```
75+
76+
or directly in STAC collection as service link:
77+
78+
```json
79+
{
80+
"rel": "service",
81+
"href": "https://greatapi.com/v1/feature/timeseries/{{feature_id}}",
82+
"type": "application/json",
83+
"id": "timeseries",
84+
"method": "GET"
85+
},
86+
```
87+
88+
## Output
89+
90+
The request to the endpoint will then return some data. eodash foresees two types of outputs:
91+
92+
* tabular or similar
93+
* or georeferenced data
94+
95+
### Chart data
96+
97+
For tabular data it is possible to specify a VEGA Chart definition. [Vega](https://vega.github.io/vega/) is a well established Visualization Grammar. Through this a completely custom visualization of the data can be configured for the user.
98+
99+
Here is a screenshot of just a few examples (https://vega.github.io/vega/examples/) showing what is possible with VEGA definitions:
100+
101+
![vega examples](./assets/vega_examples.jpg)
102+
103+
An example definition could look like this, it can be tried out directly in the [online editor](https://vega.github.io/editor/) as well:
104+
105+
```json
106+
{
107+
"$schema": "https://vega.github.io/schema/vega-lite/v5.json",
108+
"data": {
109+
"values": [
110+
{ "x": 1, "y": 3 },
111+
{ "x": 2, "y": 5 },
112+
{ "x": 3, "y": 2 }
113+
]
114+
},
115+
"mark": "point",
116+
"encoding": {
117+
"x": { "field": "x", "type": "quantitative" },
118+
"y": { "field": "y", "type": "quantitative" }
119+
}
120+
}
121+
```
122+
The main change that is needed is to remove the **data** content and only leave a name property inside, e.g.:
123+
```json
124+
{
125+
"$schema": "https://vega.github.io/schema/vega-lite/v5.json",
126+
"data": {
127+
"name": "timeseries"
128+
},
129+
...
130+
}
131+
```
132+
The data section will be filled by eodash.
133+
134+
### Georeferenced data
135+
136+
For georeferenced data such as Cloud optimized **Geotiffs (COGs), GeoJSON or FlatGeobuf** an **eodash:style** definition file can be specified.
137+
More information on the style definition can be found under [Styling](/styling).
138+
139+
It is also possible to specify multiple endpoints, for example, one that provides a timeseries and another that provides a GeoJSON with some location data, this can be seen in the following image:
140+
141+
![multi endpoints screenshot](./assets/processing_results.jpg)
142+

‎processing_inputs.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Input definition
2+
3+
In this section we go over some examples giving further explanations and we collect some typical use cases which can help as handy sources to get you started in the definition.
4+
5+
## Inital example
6+
7+
```json
8+
{
9+
"type": "object",
10+
"properties": {
11+
"feature_id": {
12+
"type": "string",
13+
"title": "Select feature on the map",
14+
"format": "feature",
15+
"options": {
16+
"drawtools": {
17+
"for": "eox-map#main",
18+
"layerId": "collection_layer_id"
19+
},
20+
"featureProperty": "id",
21+
"type": "string"
22+
}
23+
}
24+
},
25+
"options": {
26+
"execute": true
27+
}
28+
}
29+
```
30+
31+
This first example shows the use of the [eox-drawtools](https://eox-a.github.io/EOxElements/?path=/docs/elements-eox-drawtools--docs) widget logic integrated for geometry or feature selection on the eodash map. Which is helpful in handling of features and geometry input information that allows an intuitive selection for the end-user.
32+
33+
Going through the properties object, the key to be used for the property is defined `feature_id`. In the object then the type and title can be configured.
34+
35+
The format defines what handler/widget will be used, in this case the custom `feature` format is used. This allows to define some special options for the drawtools widget.
36+
37+
The first is which EOxElement map should be used. In eodash this should always be `eox-map#main`, the layerId of the collection that has the features that should be used for selection can be specified.
38+
The `featureProperty` is the identifier of the property that should be extracted from the feature, in this case the id. Then the type of the property can be specified, which in this case is a string.
39+
40+
The additional execute options at the end, is intended for endpoint calls that are not expensive and can be queried as soon as a selection has been done (e.g.) on the map. If this is not set, the user will need to click on the execute button when he is ready with the input configuration.
41+
42+
## Formats
43+
44+
Depending on what geo-information you needs to be passed to the endpoint/process there are a various helper formats that can be utilized:
45+
46+
* Feature(s)
47+
* Bbox(es)
48+
* Point(s)
49+
* Polygon(s)
50+
51+
For geo-formats it is also possible to specify which projection the coordinates should be retrieved in.
52+
53+
54+
### Multiselection
55+
56+
All formats have a plural variant, this means that the form value will return an array which can be utilized for things like comparing data from multiple features. In the definition presented below, if feature is used in the EndPoint definition it will trigger a request for every feature id that is in the selection array, will merge the data in an object and pass it along to the vega chart, so it can be used for rendering.
57+
58+
```json
59+
{
60+
"options": {
61+
"execute": true
62+
},
63+
"type": "object",
64+
"properties": {
65+
"feature": {
66+
"type": "array",
67+
"title": "Select administrative areas on map to compare",
68+
"options": {
69+
"drawtools": {
70+
"for": "eox-map#main",
71+
"layerId": "collection_layer_id",
72+
"featureNameKey": "name",
73+
"featureStyles" :{
74+
"click": {
75+
"fill-color": "rgba(51, 153, 204,0.5)",
76+
"stroke-color": "#3399CC",
77+
"stroke-width": 2.5
78+
}
79+
}
80+
},
81+
"type": "string",
82+
"featureProperty": "id"
83+
},
84+
"format": "features"
85+
}
86+
}
87+
}
88+
```
89+
90+
## Other examples
91+
92+
Other typical property types:
93+
94+
```json
95+
"exampleproperty": {
96+
"title": "Dropdown selection",
97+
"type": "string",
98+
"enum": [
99+
"key1",
100+
"key2",
101+
"key3"
102+
],
103+
"options": {
104+
"enum_titles": [
105+
"First option",
106+
"Second option",
107+
"Third option"
108+
]
109+
},
110+
"default": "key1"
111+
}
112+
```
113+
114+

0 commit comments

Comments
 (0)