openeo-portable 0.2.0rc1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. openeo_portable-0.2.0rc1/LICENSE +21 -0
  2. openeo_portable-0.2.0rc1/LICENSING.md +79 -0
  3. openeo_portable-0.2.0rc1/PACKAGE.md +133 -0
  4. openeo_portable-0.2.0rc1/PKG-INFO +163 -0
  5. openeo_portable-0.2.0rc1/README.md +280 -0
  6. openeo_portable-0.2.0rc1/openeo_portable/__init__.py +14 -0
  7. openeo_portable-0.2.0rc1/openeo_portable/collections.py +211 -0
  8. openeo_portable-0.2.0rc1/openeo_portable/endpoints/__init__.py +97 -0
  9. openeo_portable-0.2.0rc1/openeo_portable/endpoints/copernicus_dataspace.py +119 -0
  10. openeo_portable-0.2.0rc1/openeo_portable/endpoints/ds_development.py +105 -0
  11. openeo_portable-0.2.0rc1/openeo_portable/endpoints/eopf_explorer.py +79 -0
  12. openeo_portable-0.2.0rc1/openeo_portable/endpoints/localhost_dev.py +66 -0
  13. openeo_portable-0.2.0rc1/openeo_portable/parameter_manager.py +502 -0
  14. openeo_portable-0.2.0rc1/openeo_portable/params/__init__.py +4 -0
  15. openeo_portable-0.2.0rc1/openeo_portable/params/agriculture_growth_stage.params.py +213 -0
  16. openeo_portable-0.2.0rc1/openeo_portable/params/apa_aquatic_plants_algae.params.py +187 -0
  17. openeo_portable-0.2.0rc1/openeo_portable/params/atmospheric_resistant_vegetation_index.params.py +66 -0
  18. openeo_portable-0.2.0rc1/openeo_portable/params/bais2_burned_area.params.py +136 -0
  19. openeo_portable-0.2.0rc1/openeo_portable/params/barren_soil.params.py +118 -0
  20. openeo_portable-0.2.0rc1/openeo_portable/params/cab_chlorophyll_content.params.py +164 -0
  21. openeo_portable-0.2.0rc1/openeo_portable/params/cloudless_mosaic.params.py +96 -0
  22. openeo_portable-0.2.0rc1/openeo_portable/params/cohen_braaten_yang_cloud_detection.params.py +150 -0
  23. openeo_portable-0.2.0rc1/openeo_portable/params/enhanced_vegetation_index.params.py +102 -0
  24. openeo_portable-0.2.0rc1/openeo_portable/params/fapar.params.py +175 -0
  25. openeo_portable-0.2.0rc1/openeo_portable/params/fire_boundary.params.py +128 -0
  26. openeo_portable-0.2.0rc1/openeo_portable/params/flood_detection.params.py +241 -0
  27. openeo_portable-0.2.0rc1/openeo_portable/params/flood_mapping.params.py +205 -0
  28. openeo_portable-0.2.0rc1/openeo_portable/params/hollstein_cloud_detection.params.py +132 -0
  29. openeo_portable-0.2.0rc1/openeo_portable/params/kernel_ndvi.params.py +68 -0
  30. openeo_portable-0.2.0rc1/openeo_portable/params/land_surface_temperature.params.py +182 -0
  31. openeo_portable-0.2.0rc1/openeo_portable/params/lava_visualization.params.py +67 -0
  32. openeo_portable-0.2.0rc1/openeo_portable/params/leaf_area_index.params.py +166 -0
  33. openeo_portable-0.2.0rc1/openeo_portable/params/mago_water_quality.params.py +154 -0
  34. openeo_portable-0.2.0rc1/openeo_portable/params/monthly_composite.params.py +170 -0
  35. openeo_portable-0.2.0rc1/openeo_portable/params/multitemporal_burnt_area.params.py +172 -0
  36. openeo_portable-0.2.0rc1/openeo_portable/params/ndci_cyanobacteria.params.py +224 -0
  37. openeo_portable-0.2.0rc1/openeo_portable/params/ndsi.params.py +117 -0
  38. openeo_portable-0.2.0rc1/openeo_portable/params/ndvi_anomaly_detection.params.py +250 -0
  39. openeo_portable-0.2.0rc1/openeo_portable/params/oil_spill_index.params.py +88 -0
  40. openeo_portable-0.2.0rc1/openeo_portable/params/olci_under_s5.params.py +174 -0
  41. openeo_portable-0.2.0rc1/openeo_portable/params/plant-senescence-reflectance-index.params.py +65 -0
  42. openeo_portable-0.2.0rc1/openeo_portable/params/s2_s1_forest_fire_progression.params.py +240 -0
  43. openeo_portable-0.2.0rc1/openeo_portable/params/sand_oriented_land_cover_classification.params.py +141 -0
  44. openeo_portable-0.2.0rc1/openeo_portable/params/ship_detection.params.py +201 -0
  45. openeo_portable-0.2.0rc1/openeo_portable/params/snow_classifier.params.py +95 -0
  46. openeo_portable-0.2.0rc1/openeo_portable/params/swbm.params.py +154 -0
  47. openeo_portable-0.2.0rc1/openeo_portable/params/urban_areas.params.py +121 -0
  48. openeo_portable-0.2.0rc1/openeo_portable/params/urban_s1_s2.params.py +165 -0
  49. openeo_portable-0.2.0rc1/openeo_portable/params/vegetation_condition_index.params.py +120 -0
  50. openeo_portable-0.2.0rc1/openeo_portable/params/wildfire_visualization.params.py +158 -0
  51. openeo_portable-0.2.0rc1/openeo_portable/validators.py +373 -0
  52. openeo_portable-0.2.0rc1/openeo_portable/widgets.py +191 -0
  53. openeo_portable-0.2.0rc1/openeo_portable.egg-info/PKG-INFO +163 -0
  54. openeo_portable-0.2.0rc1/openeo_portable.egg-info/SOURCES.txt +59 -0
  55. openeo_portable-0.2.0rc1/openeo_portable.egg-info/dependency_links.txt +1 -0
  56. openeo_portable-0.2.0rc1/openeo_portable.egg-info/requires.txt +8 -0
  57. openeo_portable-0.2.0rc1/openeo_portable.egg-info/top_level.txt +1 -0
  58. openeo_portable-0.2.0rc1/pyproject.toml +126 -0
  59. openeo_portable-0.2.0rc1/setup.cfg +4 -0
  60. openeo_portable-0.2.0rc1/tests/test_packaged_params.py +128 -0
  61. openeo_portable-0.2.0rc1/tests/test_parameter_management.py +743 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Development Seed
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,79 @@
1
+ # Licensing
2
+
3
+ This repository uses a mixed-licensing approach.
4
+
5
+ ## Default license (repo-level)
6
+
7
+ Unless stated otherwise in a file header, all original work in this repository is
8
+ licensed under the **MIT License** (see `LICENSE`).
9
+
10
+ ## Converted Sentinel Hub evalscripts
11
+
12
+ Files that are converted from Sentinel Hub Custom Scripts **must retain the
13
+ original license**. The Sentinel Hub Custom Scripts are published under
14
+ **CC-BY-SA-4.0**, so converted files are also **CC-BY-SA-4.0**.
15
+
16
+ The full CC-BY-SA-4.0 license text is at
17
+ <https://creativecommons.org/licenses/by-sa/4.0/legalcode>
18
+ ([summary](https://creativecommons.org/licenses/by-sa/4.0/)).
19
+
20
+ To keep this clear and non-viral, every converted file must include an explicit
21
+ header that states:
22
+
23
+ - The origin (converted from Sentinel Hub)
24
+ - The license that applies to that file (CC-BY-SA-4.0)
25
+ - A link to the original evalscript
26
+
27
+ This makes it clear that CC-BY-SA-4.0 applies only to those converted files, not
28
+ to the rest of the repository.
29
+
30
+ ## Required header template
31
+
32
+ Use the following template at the top of each converted file.
33
+
34
+ ### Jupyter notebook (first markdown cell)
35
+
36
+ ```
37
+ ## License
38
+
39
+ This notebook is a conversion of a Sentinel Hub evalscript and is licensed under
40
+ **CC-BY-SA-4.0**.
41
+
42
+ Original evalscript: <link>
43
+ Source: Sentinel Hub Custom Scripts (CC-BY-SA-4.0)
44
+ Conversion: Development Seed (openEO-UDP project)
45
+ ```
46
+
47
+ ### Code file (file header comment)
48
+
49
+ ```
50
+ # License: CC-BY-SA-4.0
51
+ # Origin: Converted from Sentinel Hub evalscript
52
+ # Original evalscript: <link>
53
+ # Source: Sentinel Hub Custom Scripts (CC-BY-SA-4.0)
54
+ # Conversion: Development Seed (openEO-UDP project)
55
+ ```
56
+
57
+ ## Current CC-BY-SA-4.0 files
58
+
59
+ ### Parameter files
60
+
61
+ Every parameter file in `openeo_portable/params/` (`*.params.py`) is converted
62
+ from a Sentinel Hub evalscript and is **CC-BY-SA-4.0**. Each one carries the
63
+ header above with a link to its original evalscript.
64
+ `tests/test_packaged_params.py` fails if a parameter file is missing the header.
65
+
66
+ ### Notebooks
67
+
68
+ - `notebooks/sentinel/sentinel-2/fire_and_disaster_monitoring/bais2_burned_area.ipynb`
69
+ - `notebooks/sentinel/sentinel-2/marine_and_water_bodies/ndci_cyanobacteria.ipynb`
70
+ - `notebooks/sentinel/sentinel-2/advanced_spectral_processing/cab_chlorophyll_content.ipynb`
71
+ - `notebooks/sentinel/sentinel-2/advanced_spectral_processing/ndvi_anomaly_detection.ipynb`
72
+ - `notebooks/sentinel/sentinel-3/land_surface_temperature.ipynb`
73
+ - `notebooks/sentinel/sentinel-3/olci_under_s5.ipynb`
74
+
75
+ ## Python package
76
+
77
+ The `openeo-portable` package on PyPI is licensed `MIT AND CC-BY-SA-4.0`: its
78
+ code is MIT, and its parameter files are CC-BY-SA-4.0. The package ships both
79
+ `LICENSE` and this file.
@@ -0,0 +1,133 @@
1
+ # openeo-portable
2
+
3
+ Parameter and backend management for portable openEO notebooks and User-Defined Processes (UDPs).
4
+
5
+ `openeo-portable` lets you write an openEO workflow once and run it on several openEO backends and study areas, without editing the code. It provides:
6
+
7
+ - **Parameter sets.** Each algorithm has a `.params.py` file with named sets of locations, dates and settings (for example `venice_lagoon`). The parameter files for the [openeo-udp notebooks](https://github.com/developmentseed/openeo-udp) ship with the package.
8
+ - **Endpoint mapping.** Collection IDs, band names and dimension names differ between backends. The package rewrites them for the backend you connect to, so the same process graph works on each one.
9
+ - **Interactive selection.** Dropdown widgets in Jupyter for choosing a parameter set and a backend.
10
+ - **Parameter resolution.** Turns `Parameter` references into concrete values, so a graph that will later be exported as a UDP can also run synchronously.
11
+
12
+ ## Installation
13
+
14
+ ```bash
15
+ pip install openeo-portable
16
+ ```
17
+
18
+ To run the openeo-udp notebooks, install the `notebooks` extra as well. It adds matplotlib, NumPy, Pillow and rioxarray:
19
+
20
+ ```bash
21
+ pip install "openeo-portable[notebooks]"
22
+ ```
23
+
24
+ Requires Python 3.11 or later.
25
+
26
+ ## Quick start
27
+
28
+ ```python
29
+ from openeo_portable import ParameterManager
30
+
31
+ # Load a parameter file that ships with the package
32
+ param_manager = ParameterManager("apa_aquatic_plants_algae.params.py")
33
+
34
+ # Show the parameter sets and endpoints you can choose from
35
+ param_manager.print_options("Aquatic plants and algae")
36
+
37
+ # Option 1: choose with dropdown widgets (in Jupyter)
38
+ selection_widget = param_manager.interactive_parameter_selection()
39
+ connection, current_params = selection_widget()
40
+
41
+ # Option 2: choose in code (in scripts)
42
+ connection, current_params = param_manager.quick_connect(
43
+ param_set="venice_lagoon",
44
+ endpoint="eopf_explorer",
45
+ )
46
+ ```
47
+
48
+ `current_params` holds the parameters mapped for the chosen backend. Use them to build a parameterised graph, then resolve it before running it synchronously:
49
+
50
+ ```python
51
+ cube = connection.load_collection(
52
+ current_params["collection"].default,
53
+ bands=current_params["bands"].default,
54
+ spatial_extent=current_params["bounding_box"],
55
+ temporal_extent=current_params["time"],
56
+ properties={"eo:cloud_cover": lambda x: x <= current_params["cloud_cover"]},
57
+ )
58
+
59
+ # Some backends store reflectance as scaled integers (0-10000), others as 0-1
60
+ # floats. Dividing by reflectance_scale gives 0-1 reflectance on every backend.
61
+ cube = cube / current_params["reflectance_scale"]
62
+
63
+ # Backends name the time dimension differently ("t" or "time"), so take the
64
+ # name from current_params instead of hard-coding it
65
+ cube = cube.reduce_dimension(
66
+ dimension=current_params["time_dimension"], reducer="first"
67
+ )
68
+
69
+ # Resolve parameter references before running synchronously, because the
70
+ # /result endpoint rejects unresolved ones
71
+ param_manager.resolve(cube, current_params).download("preview.nc")
72
+ ```
73
+
74
+ `reflectance_scale` and `time_dimension` come from the endpoint mapping, which adds them to `current_params` for the chosen backend. It also adds `bands_dimension`, the name of the band dimension, for processes such as `apply_dimension`. Reading these values from `current_params` instead of hard-coding them keeps the graph backend-agnostic.
75
+
76
+ ## Supported endpoints
77
+
78
+ | Endpoint | Backend |
79
+ | --- | --- |
80
+ | `eopf_explorer` | EOPF Sentinel Zarr Samples Explorer |
81
+ | `copernicus_dataspace` | Copernicus Data Space Ecosystem |
82
+ | `ds_development` | Development Seed development instance |
83
+ | `localhost_dev` | A local openEO backend for development |
84
+
85
+ ```python
86
+ from openeo_portable.endpoints import list_available_endpoints
87
+
88
+ list_available_endpoints()
89
+ ```
90
+
91
+ ## Parameter files
92
+
93
+ Parameter files for the openeo-udp algorithms ship in `openeo_portable.params`. A bare file name such as `ParameterManager("urban_areas.params.py")` loads the packaged file. To list them:
94
+
95
+ ```python
96
+ from openeo_portable import list_parameter_files
97
+
98
+ list_parameter_files()
99
+ ```
100
+
101
+ ### Using your own parameter file
102
+
103
+ You can override a packaged parameter file without changing the package. Put a file with the same name in your working directory, and `ParameterManager` loads it instead of the packaged one. The easiest start is a copy of the packaged file:
104
+
105
+ ```python
106
+ import shutil
107
+ from importlib.resources import files
108
+
109
+ shutil.copy(files("openeo_portable.params") / "urban_areas.params.py", "urban_areas.params.py")
110
+ ```
111
+
112
+ Edit the copy, for example to add a parameter set for your own area and dates. `print_options()` shows which file was loaded and warns when a local file overrides the packaged one. Delete or rename the local file to go back to the packaged version.
113
+
114
+ You can also give your file a different name and pass its path, for example `ParameterManager("my_urban_areas.params.py")`.
115
+
116
+ ## Documentation
117
+
118
+ - [Parameter management guide](https://github.com/developmentseed/openeo-udp/blob/main/docs/parameter-management.md): parameter file format, endpoint mapping, the full `ParameterManager` API, and how to add a new endpoint.
119
+ - [openeo-udp notebooks](https://github.com/developmentseed/openeo-udp): the notebooks that use this package to build UDPs for the [APEx Algorithm Catalogue](https://algorithm-catalogue.apex.esa.int/).
120
+ - [Contributing](https://github.com/developmentseed/openeo-udp/blob/main/CONTRIBUTING.md)
121
+
122
+ ## License
123
+
124
+ `MIT AND CC-BY-SA-4.0`:
125
+
126
+ - The package code is MIT ([LICENSE](https://github.com/developmentseed/openeo-udp/blob/main/LICENSE)).
127
+ - The parameter files in `openeo_portable/params/` are converted from [Sentinel Hub custom scripts](https://custom-scripts.sentinel-hub.com/) and are [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/). Each file's header links to its original evalscript.
128
+
129
+ See [LICENSING.md](https://github.com/developmentseed/openeo-udp/blob/main/LICENSING.md) for details.
130
+
131
+ ## Acknowledgments
132
+
133
+ Developed by [Development Seed](https://developmentseed.org/) as part of the [APEx](https://apex.esa.int/) project, funded by the European Space Agency.
@@ -0,0 +1,163 @@
1
+ Metadata-Version: 2.4
2
+ Name: openeo-portable
3
+ Version: 0.2.0rc1
4
+ Summary: Parameter and backend management for porting openEO notebooks and User-Defined Processes across backends with different collection and band names
5
+ Author-email: Emmanuel Mathot <emmanuel@developmentseed.org>, Firza Riany <firza@developmentseed.org>
6
+ License-Expression: MIT AND CC-BY-SA-4.0
7
+ Project-URL: Homepage, https://github.com/developmentseed/openeo-udp
8
+ Project-URL: Documentation, https://github.com/developmentseed/openeo-udp
9
+ Project-URL: Repository, https://github.com/developmentseed/openeo-udp
10
+ Project-URL: Bug Tracker, https://github.com/developmentseed/openeo-udp/issues
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Topic :: Scientific/Engineering :: GIS
18
+ Requires-Python: >=3.11
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ License-File: LICENSING.md
22
+ Requires-Dist: openeo>=0.24.0
23
+ Requires-Dist: ipywidgets>=8.0.0
24
+ Provides-Extra: notebooks
25
+ Requires-Dist: matplotlib>=3.7.0; extra == "notebooks"
26
+ Requires-Dist: numpy>=1.24.0; extra == "notebooks"
27
+ Requires-Dist: Pillow>=10.0.0; extra == "notebooks"
28
+ Requires-Dist: rioxarray>=0.19.0; extra == "notebooks"
29
+ Dynamic: license-file
30
+
31
+ # openeo-portable
32
+
33
+ Parameter and backend management for portable openEO notebooks and User-Defined Processes (UDPs).
34
+
35
+ `openeo-portable` lets you write an openEO workflow once and run it on several openEO backends and study areas, without editing the code. It provides:
36
+
37
+ - **Parameter sets.** Each algorithm has a `.params.py` file with named sets of locations, dates and settings (for example `venice_lagoon`). The parameter files for the [openeo-udp notebooks](https://github.com/developmentseed/openeo-udp) ship with the package.
38
+ - **Endpoint mapping.** Collection IDs, band names and dimension names differ between backends. The package rewrites them for the backend you connect to, so the same process graph works on each one.
39
+ - **Interactive selection.** Dropdown widgets in Jupyter for choosing a parameter set and a backend.
40
+ - **Parameter resolution.** Turns `Parameter` references into concrete values, so a graph that will later be exported as a UDP can also run synchronously.
41
+
42
+ ## Installation
43
+
44
+ ```bash
45
+ pip install openeo-portable
46
+ ```
47
+
48
+ To run the openeo-udp notebooks, install the `notebooks` extra as well. It adds matplotlib, NumPy, Pillow and rioxarray:
49
+
50
+ ```bash
51
+ pip install "openeo-portable[notebooks]"
52
+ ```
53
+
54
+ Requires Python 3.11 or later.
55
+
56
+ ## Quick start
57
+
58
+ ```python
59
+ from openeo_portable import ParameterManager
60
+
61
+ # Load a parameter file that ships with the package
62
+ param_manager = ParameterManager("apa_aquatic_plants_algae.params.py")
63
+
64
+ # Show the parameter sets and endpoints you can choose from
65
+ param_manager.print_options("Aquatic plants and algae")
66
+
67
+ # Option 1: choose with dropdown widgets (in Jupyter)
68
+ selection_widget = param_manager.interactive_parameter_selection()
69
+ connection, current_params = selection_widget()
70
+
71
+ # Option 2: choose in code (in scripts)
72
+ connection, current_params = param_manager.quick_connect(
73
+ param_set="venice_lagoon",
74
+ endpoint="eopf_explorer",
75
+ )
76
+ ```
77
+
78
+ `current_params` holds the parameters mapped for the chosen backend. Use them to build a parameterised graph, then resolve it before running it synchronously:
79
+
80
+ ```python
81
+ cube = connection.load_collection(
82
+ current_params["collection"].default,
83
+ bands=current_params["bands"].default,
84
+ spatial_extent=current_params["bounding_box"],
85
+ temporal_extent=current_params["time"],
86
+ properties={"eo:cloud_cover": lambda x: x <= current_params["cloud_cover"]},
87
+ )
88
+
89
+ # Some backends store reflectance as scaled integers (0-10000), others as 0-1
90
+ # floats. Dividing by reflectance_scale gives 0-1 reflectance on every backend.
91
+ cube = cube / current_params["reflectance_scale"]
92
+
93
+ # Backends name the time dimension differently ("t" or "time"), so take the
94
+ # name from current_params instead of hard-coding it
95
+ cube = cube.reduce_dimension(
96
+ dimension=current_params["time_dimension"], reducer="first"
97
+ )
98
+
99
+ # Resolve parameter references before running synchronously, because the
100
+ # /result endpoint rejects unresolved ones
101
+ param_manager.resolve(cube, current_params).download("preview.nc")
102
+ ```
103
+
104
+ `reflectance_scale` and `time_dimension` come from the endpoint mapping, which adds them to `current_params` for the chosen backend. It also adds `bands_dimension`, the name of the band dimension, for processes such as `apply_dimension`. Reading these values from `current_params` instead of hard-coding them keeps the graph backend-agnostic.
105
+
106
+ ## Supported endpoints
107
+
108
+ | Endpoint | Backend |
109
+ | --- | --- |
110
+ | `eopf_explorer` | EOPF Sentinel Zarr Samples Explorer |
111
+ | `copernicus_dataspace` | Copernicus Data Space Ecosystem |
112
+ | `ds_development` | Development Seed development instance |
113
+ | `localhost_dev` | A local openEO backend for development |
114
+
115
+ ```python
116
+ from openeo_portable.endpoints import list_available_endpoints
117
+
118
+ list_available_endpoints()
119
+ ```
120
+
121
+ ## Parameter files
122
+
123
+ Parameter files for the openeo-udp algorithms ship in `openeo_portable.params`. A bare file name such as `ParameterManager("urban_areas.params.py")` loads the packaged file. To list them:
124
+
125
+ ```python
126
+ from openeo_portable import list_parameter_files
127
+
128
+ list_parameter_files()
129
+ ```
130
+
131
+ ### Using your own parameter file
132
+
133
+ You can override a packaged parameter file without changing the package. Put a file with the same name in your working directory, and `ParameterManager` loads it instead of the packaged one. The easiest start is a copy of the packaged file:
134
+
135
+ ```python
136
+ import shutil
137
+ from importlib.resources import files
138
+
139
+ shutil.copy(files("openeo_portable.params") / "urban_areas.params.py", "urban_areas.params.py")
140
+ ```
141
+
142
+ Edit the copy, for example to add a parameter set for your own area and dates. `print_options()` shows which file was loaded and warns when a local file overrides the packaged one. Delete or rename the local file to go back to the packaged version.
143
+
144
+ You can also give your file a different name and pass its path, for example `ParameterManager("my_urban_areas.params.py")`.
145
+
146
+ ## Documentation
147
+
148
+ - [Parameter management guide](https://github.com/developmentseed/openeo-udp/blob/main/docs/parameter-management.md): parameter file format, endpoint mapping, the full `ParameterManager` API, and how to add a new endpoint.
149
+ - [openeo-udp notebooks](https://github.com/developmentseed/openeo-udp): the notebooks that use this package to build UDPs for the [APEx Algorithm Catalogue](https://algorithm-catalogue.apex.esa.int/).
150
+ - [Contributing](https://github.com/developmentseed/openeo-udp/blob/main/CONTRIBUTING.md)
151
+
152
+ ## License
153
+
154
+ `MIT AND CC-BY-SA-4.0`:
155
+
156
+ - The package code is MIT ([LICENSE](https://github.com/developmentseed/openeo-udp/blob/main/LICENSE)).
157
+ - The parameter files in `openeo_portable/params/` are converted from [Sentinel Hub custom scripts](https://custom-scripts.sentinel-hub.com/) and are [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/). Each file's header links to its original evalscript.
158
+
159
+ See [LICENSING.md](https://github.com/developmentseed/openeo-udp/blob/main/LICENSING.md) for details.
160
+
161
+ ## Acknowledgments
162
+
163
+ Developed by [Development Seed](https://developmentseed.org/) as part of the [APEx](https://apex.esa.int/) project, funded by the European Space Agency.
@@ -0,0 +1,280 @@
1
+ # openEO User-Defined Processes
2
+
3
+ This repository contains Jupyter notebooks that creates openEO User-Defined Processes (UDPs), initially from Sentinel Hub evalscripts. Each notebook documents the purpose of the UDP, validates the results, and exports the final process graph for integration with the openEO ecosystem.
4
+
5
+ The notebooks use [`openeo-portable`](PACKAGE.md), a Python package in this repository that manages parameter sets and maps them to different openEO backends. See [PACKAGE.md](PACKAGE.md) for its documentation.
6
+
7
+ ## Project Context
8
+
9
+ This work is part of the [APEx (Application Propagation Environments)](https://apex.esa.int/) project for the European Space Agency. The goal is to convert the extensive library of [Sentinel Hub custom evalscripts](https://custom-scripts.sentinel-hub.com/) into interoperable openEO process graphs that can run on any openEO-compliant backend while maintaining synchronous visualization capabilities.
10
+
11
+ For more information about the project:
12
+
13
+ - [APEx Algorithm Catalogue](https://algorithm-catalogue.apex.esa.int/)
14
+
15
+ ## Repository Structure
16
+
17
+ The repository is organized by category and sensor type following the structure of the original evalscripts:
18
+
19
+ ```console
20
+ notebooks/
21
+ ├── sentinel/
22
+ │ ├── sentinel-2/
23
+ │ │ ├── remote_sensing_indices/
24
+ │ │ │ ├── ndvi_enhanced.ipynb
25
+ │ │ │ └── ...
26
+ │ │ ├── marine_and_water_bodies/
27
+ │ │ │ ├── ndci_cyanobacteria.ipynb
28
+ │ │ │ └── ...
29
+ │ │ ├── cloud_detection/
30
+ │ │ │ ├── cohen_braaten_yang_cloud_detection.ipynb
31
+ │ │ │ └── ...
32
+ │ │ └── fire/
33
+ │ │ ├── bais2_burned_area.ipynb
34
+ │ │ └── ...
35
+ │ ├── sentinel-1/
36
+ │ └── ...
37
+ ├── multi-sensor/
38
+ │ └── ...
39
+ └── README.md (this file)
40
+ ```
41
+
42
+ ## Notebook Structure
43
+
44
+ Each conversion notebook follows a consistent structure to ensure clarity and reproducibility. Using the [NDCI cyanobacteria detection example](notebooks/sentinel/sentinel-2/marine_and_water_bodies/ndci_cyanobacteria.ipynb) as a reference, a typical notebook contains:
45
+
46
+ ### Introduction and Context
47
+
48
+ The notebook begins with a clear explanation of what the algorithm does, its scientific basis, and its practical applications. For instance, the NDCI notebook explains how the Normalized Difference Chlorophyll Index uses Sentinel-2's red and red-edge bands to estimate chlorophyll-a concentrations in water bodies, which is particularly valuable for detecting cyanobacteria blooms.
49
+
50
+ ### Scientific Background
51
+
52
+ This section provides the mathematical foundation and methodology behind the algorithm. The NDCI notebook describes the spectral signatures of chlorophyll, the specific wavelengths used (Band 5 at 705 nm and Band 4 at 665 nm), and the empirically-derived calibration model that converts NDVI values to chlorophyll-a concentrations.
53
+
54
+ ### Environment Setup
55
+
56
+ The notebook then establishes the technical environment by importing necessary libraries, connecting to the openEO backend, and configuring any required parameters. This includes libraries for data processing (openEO), visualization (matplotlib), and any specialized processing functions.
57
+
58
+ **Parameter Management System** for flexible backend connections and parameter handling:
59
+
60
+ ```python
61
+ # Initialize parameter manager with algorithm-specific parameters
62
+ param_manager = ParameterManager('algorithm_name.params.py')
63
+
64
+ # Display available options
65
+ param_manager.print_options("Algorithm name")
66
+
67
+ # Interactive approach - user selects via dropdowns
68
+ selection_widget = param_manager.interactive_parameter_selection()
69
+ connection, current_params = selection_widget()
70
+
71
+ # Alternative: Programmatic approach - direct connection
72
+ connection, current_params = param_manager.quick_connect(
73
+ param_set='venice_lagoon',
74
+ endpoint='eopf_explorer'
75
+ )
76
+
77
+ # Build a parameterised graph: algorithm-intrinsic values inline, runtime
78
+ # knobs (AOI, TOI, cloud cover) as Parameter refs so the same graph can
79
+ # later be exported as a UDP.
80
+ s2cube = connection.load_collection(
81
+ current_params["collection"].default,
82
+ bands=current_params["bands"].default,
83
+ spatial_extent=current_params["bounding_box"],
84
+ temporal_extent=current_params["time"],
85
+ properties={
86
+ "eo:cloud_cover": lambda x: x <= current_params["cloud_cover"],
87
+ },
88
+ )
89
+
90
+ # Resolve parameters before synchronous execution (the synchronous /result
91
+ # endpoint rejects unresolved from_parameter refs).
92
+ param_manager.resolve(s2cube, current_params).download("preview.nc")
93
+ ```
94
+
95
+ Each endpoint mapper also injects three backend-intrinsic values — `reflectance_scale`, `bands_dimension`, `time_dimension` — into `current_params`, so notebook UDPs stay fully backend-agnostic. This approach allows notebooks to work seamlessly with different OpenEO backends and parameter sets without code modifications.
96
+
97
+ ### Data Loading and Exploration
98
+
99
+ This section demonstrates how to load the initial dataset, define the spatial extent, select appropriate bands, and perform initial exploration of the data. The NDCI example shows how to extract multiple Sentinel-2 bands needed for both the main index and supporting calculations.
100
+
101
+ ### Intermediate Calculations
102
+
103
+ If the algorithm requires preparatory steps, these are documented separately with their own explanations. The NDCI notebook includes the Floating Algae Index (FAI) calculation as an intermediate step for detecting surface algal blooms before computing the main chlorophyll index.
104
+
105
+ ### Main Algorithm Implementation
106
+
107
+ This is the core of the notebook, where the primary algorithm is implemented using openEO processes. The implementation is broken down into understandable steps with clear variable names and comments explaining the logic. For NDCI, this includes water body identification, the NDCI calculation itself, and the conversion to chlorophyll-a concentrations.
108
+
109
+ ### Visualization and Color Mapping
110
+
111
+ Many algorithms require custom visualization schemes to make their results interpretable. The NDCI notebook demonstrates how to create discrete color scales representing different water quality classifications, from oligotrophic (clear water) through eutrophic to bloom conditions.
112
+
113
+ ### Process Graph Export
114
+
115
+ A critical section where the final openEO process graph is captured in a variable that can be serialized to JSON format. This export becomes the formal UDP definition that can be registered with openEO backends and consumed by various clients.
116
+
117
+ ### Validation and Results
118
+
119
+ The notebook executes the process graph and displays results for visual validation. This often includes comparisons with natural color imagery to help verify that the algorithm is working correctly. The NDCI example shows both the chlorophyll-a map and a side-by-side comparison with true color imagery.
120
+
121
+ ### Documentation and Attribution
122
+
123
+ Each notebook concludes with proper attribution to the original evalscript authors, citations for the scientific methodology, references to relevant publications, and acknowledgment of data sources used in the conversion.
124
+
125
+ ## Getting Started
126
+
127
+ ### Prerequisites
128
+
129
+ To run these notebooks, you need:
130
+
131
+ - Python 3.11 or later
132
+ - [uv](https://docs.astral.sh/uv/) for fast and reliable dependency management
133
+ - Access to an openEO backend (we recommend https://openeo.ds.io/ for testing)
134
+ - Basic understanding of remote sensing concepts and Python programming
135
+
136
+ ### Parameter Management System
137
+
138
+ The notebooks get their locations, dates and backend connections from the [`openeo-portable`](PACKAGE.md) package, so you can switch study area or openEO backend without editing code. The package's [README](PACKAGE.md) covers installation and usage, and the [parameter management guide](docs/parameter-management.md) has the full reference.
139
+
140
+ ### Environment Setup
141
+
142
+ This project uses [uv](https://docs.astral.sh/uv/) for fast and reliable dependency management.
143
+
144
+ 1. **Install uv** if you haven't already:
145
+
146
+ ```bash
147
+ # On macOS and Linux
148
+ curl -LsSf https://astral.sh/uv/install.sh | sh
149
+
150
+ # On Windows
151
+ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
152
+ ```
153
+
154
+ 2. **Clone the repository and set up the environment**:
155
+
156
+ ```bash
157
+ git clone https://github.com/developmentseed/openeo-udp.git
158
+ cd openeo-udp
159
+
160
+ # Create virtual environment and install all dependencies
161
+ uv sync
162
+ ```
163
+
164
+ 3. **Install as Jupyter kernel** (recommended for running notebooks):
165
+
166
+ ```bash
167
+ # Install the environment as a Jupyter kernel
168
+ uv run python -m ipykernel install --user --name openeo-udp --display-name "openEO UDP"
169
+ ```
170
+
171
+ The environment includes the openEO Python client library, visualization tools like matplotlib and Pillow, Jupyter, and all other dependencies needed to run the notebooks.
172
+
173
+ ### Running a Notebook
174
+
175
+ Start Jupyter and open any notebook. For example, the [APA Aquatic Plants and Algae notebook](notebooks/sentinel/sentinel-2/marine_and_water_bodies/apa_aquatic_plants_algae.ipynb):
176
+
177
+ ```bash
178
+ # Start Jupyter using uv
179
+ uv run jupyter lab
180
+
181
+ # Or start Jupyter Notebook
182
+ uv run jupyter notebook
183
+ ```
184
+
185
+ When creating or opening a notebook:
186
+
187
+ 1. Make sure the "openEO UDP" kernel is selected (if you installed it as a kernel)
188
+ 2. Open a notebook like [APA Aquatic Plants and Algae](notebooks/sentinel/sentinel-2/marine_and_water_bodies/apa_aquatic_plants_algae.ipynb)
189
+ 3. Execute the cells sequentially to see the conversion process, validate results, and export the UDP definition
190
+
191
+ **Parameter Management Integration:**
192
+ Each notebook has a parameter file (`.params.py`) that defines multiple locations and configurations. The parameter files ship with `openeo-portable` in [`openeo_portable/params/`](openeo_portable/params/), except for the self-contained machine-learning notebooks, which keep theirs in their own folder. You can:
193
+
194
+ - Use interactive widgets to select parameters and endpoints via dropdowns
195
+ - Switch between locations (Venice Lagoon, Lake Victoria, etc.) without editing code
196
+ - Connect to different OpenEO backends with automatic parameter mapping
197
+ - Run the same algorithm on different areas by simply changing parameter sets
198
+
199
+ To add your own area or dates, override a packaged parameter file with a local copy next to the notebook. See [Using your own parameter file](PACKAGE.md#using-your-own-parameter-file).
200
+
201
+ Most notebooks are designed to run completely from top to bottom without modification, though you may want to adjust spatial extents or temporal ranges to explore different areas.
202
+
203
+ ## Using the Exported UDPs
204
+
205
+ Once a notebook has been executed and validated, the resulting UDP can be used in several ways:
206
+
207
+ ### Direct Integration with openEO Backends
208
+
209
+ The exported JSON process graph can be registered as a UDP on openEO backends that support user-defined processes. This makes the algorithm available through standard openEO clients in Python, R, and JavaScript.
210
+
211
+ ### APEx Algorithm Catalogue
212
+
213
+ Validated UDPs are published to the APEx Algorithm Catalogue, making them discoverable and accessible to the broader Earth observation community through a standardized interface.
214
+
215
+ ### Synchronous Visualization Services
216
+
217
+ The converted algorithms can be consumed through web map tile services (XYZ endpoints) for real-time visualization in web mapping applications, maintaining the interactive nature of the original evalscripts.
218
+
219
+ ## Contributing
220
+
221
+ We welcome contributions from the community! Whether you are converting additional evalscripts, improving existing conversions, or fixing bugs, your help makes this resource more valuable for everyone.
222
+
223
+ Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute to this project, including the conversion process, coding standards, testing requirements, and pull request procedures.
224
+
225
+ The [NDCI cyanobacteria notebook](notebooks/sentinel/sentinel-2/marine_and_water_bodies/ndci_cyanobacteria.ipynb) serves as a comprehensive reference implementation demonstrating best practices for conversion, documentation, and validation.
226
+
227
+ ## Publication Documentation
228
+
229
+ Guidance for preparing and publishing UDP documentation is available in [docs/publication.md](docs/publication.md).
230
+
231
+ ## Original Evalscripts
232
+
233
+ All algorithms in this repository are converted from Sentinel Hub's community-contributed evalscripts. The original scripts can be found at:
234
+
235
+ - [Sentinel Hub Custom Scripts Repository](https://custom-scripts.sentinel-hub.com/)
236
+ - [Custom Scripts GitHub](https://github.com/sentinel-hub/custom-scripts)
237
+
238
+ Each notebook includes specific attribution to the original script authors and links to the source evalscripts.
239
+
240
+ ## Related Resources
241
+
242
+ ### openEO Ecosystem
243
+
244
+ - [openEO API Specification](https://openeo.org/)
245
+ - [openEO Processes Documentation](https://processes.openeo.org/)
246
+ - [openEO Python Client](https://github.com/Open-EO/openeo-python-client)
247
+
248
+ ### Sentinel Hub Documentation
249
+
250
+ - [Evalscript Documentation](https://docs.sentinel-hub.com/api/latest/evalscript/)
251
+ - [Custom Script Tutorial](https://docs.sentinel-hub.com/api/latest/evalscript/)
252
+
253
+ ### Project Infrastructure
254
+
255
+ - [openEO by TiTiler](https://github.com/sentinel-hub/titiler-openeo)
256
+ - [Demo Instance](https://openeo.ds.io/)
257
+
258
+ ## License
259
+
260
+ This project is licensed under the MIT License by default, with CC-BY-SA-4.0 applied to converted Sentinel Hub evalscripts. See [`LICENSING.md`](./LICENSING.md) for details.
261
+
262
+ ## Acknowledgments
263
+
264
+ This work is funded by the European Space Agency through the APEx project. We are grateful to:
265
+
266
+ - The Sentinel Hub team at Sinergise for creating the original evalscript infrastructure
267
+ - The openEO community for developing the interoperable processing standards
268
+ - All the scientists and developers who contributed the original evalscripts
269
+ - VITO, EODC, and other openEO backend providers for their collaboration
270
+
271
+ ## Contact and Support
272
+
273
+ For questions, issues, or suggestions:
274
+
275
+ - Open an issue in this repository
276
+ - Contact the Development Seed team through the project issue tracker
277
+
278
+ ---
279
+
280
+ **Note**: This repository is under active development as part of the evalscript conversion project. Some notebooks may be in draft form, and new conversions are added regularly as the project progresses.