Skip to content

Commit d20a6fe

Browse files
emmanuelmathotemmanuelmathot
committed
Enhance documentation and setup instructions in README and CONTRIBUTING files; add .gitignore and pyproject.toml for project configuration and dependency management.
1 parent a6c07d1 commit d20a6fe

File tree

4 files changed

+305
-13
lines changed

4 files changed

+305
-13
lines changed

‎.gitignore‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
MANIFEST
23+
24+
# Virtual environments
25+
.venv/
26+
.env
27+
venv/
28+
ENV/
29+
env/
30+
31+
# uv
32+
.uv/
33+
34+
# Jupyter
35+
.ipynb_checkpoints/
36+
*.ipynb_checkpoints
37+
38+
# IDE
39+
.vscode/
40+
.idea/
41+
*.swp
42+
*.swo
43+
*~
44+
45+
# OS
46+
.DS_Store
47+
.DS_Store?
48+
._*
49+
.Spotlight-V100
50+
.Trashes
51+
ehthumbs.db
52+
Thumbs.db
53+
54+
# Testing
55+
.pytest_cache/
56+
.coverage
57+
htmlcov/
58+
.tox/
59+
60+
# Documentation
61+
site/
62+
63+
# Temporary files
64+
*.tmp
65+
*.temp
66+
*.log
67+
68+
# OpenEO specific
69+
.openeo/
70+
auth_*.json

‎CONTRIBUTING.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,95 @@
22

33
Thank you for your interest in contributing to the Sentinel Hub evalscript to openEO conversion project! This guide will help you understand our conversion process and standards so your contributions can be integrated smoothly.
44

5+
## Getting Started
6+
7+
### Development Environment Setup
8+
9+
Before you begin converting evalscripts, set up your development environment properly:
10+
11+
#### Prerequisites
12+
13+
- Python 3.11 or later
14+
- [uv](https://docs.astral.sh/uv/) for dependency management
15+
- Git for version control
16+
- Access to an openEO backend for testing
17+
18+
#### Environment Setup
19+
20+
1. **Install uv** if you haven't already:
21+
```bash
22+
# On macOS and Linux
23+
curl -LsSf https://astral.sh/uv/install.sh | sh
24+
25+
# On Windows
26+
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
27+
```
28+
29+
2. **Fork and clone the repository**:
30+
```bash
31+
git clone https://github.com/your-username/openeo-udp.git
32+
cd openeo-udp
33+
```
34+
35+
3. **Set up the development environment**:
36+
```bash
37+
# Create virtual environment and install all dependencies
38+
uv sync
39+
40+
# Install development dependencies (for linting, testing)
41+
uv sync --group dev
42+
43+
# Install as Jupyter kernel for notebook development
44+
uv run python -m ipykernel install --user --name openeo-udp-dev --display-name "openEO UDP (Dev)"
45+
```
46+
47+
#### Jupyter Kernel Management
48+
49+
After installation, you should have the "openEO UDP (Dev)" kernel available in Jupyter. When creating or opening notebooks:
50+
51+
- Ensure you select the correct kernel
52+
- Verify the kernel has access to all required packages
53+
- Test the openEO connection in the first cell
54+
55+
### Working with the Development Environment
56+
57+
- **Starting Jupyter**: Use `uv run jupyter lab` or `uv run jupyter notebook`
58+
- **Running tests**: Use `uv run pytest`
59+
- **Code formatting**: Use `uv run black .`
60+
- **Linting**: Use `uv run ruff check .`
61+
- **Installing new packages**: Use `uv add package-name`
62+
- **Running any Python script**: Use `uv run python script.py`
63+
64+
#### Verifying Your Environment
65+
66+
Before starting development, verify your environment is set up correctly:
67+
68+
1. **Test Python and package availability**:
69+
```bash
70+
uv run python -c "
71+
import openeo
72+
import matplotlib.pyplot as plt
73+
import numpy as np
74+
from PIL import Image
75+
print('All packages imported successfully!')
76+
"
77+
```
78+
79+
2. **Test openEO connection** (optional, requires backend access):
80+
```bash
81+
uv run python -c "
82+
import openeo
83+
connection = openeo.connect('https://openeo.ds.io/')
84+
print('OpenEO connection successful!')
85+
"
86+
```
87+
88+
3. **Check Jupyter kernel**:
89+
- Launch Jupyter: `uv run jupyter lab`
90+
- Create a new notebook
91+
- Ensure "openEO UDP (Dev)" kernel is available and selected
92+
- Run the import test from step 1
93+
594
## Understanding the Conversion Process
695

796
Converting a Sentinel Hub evalscript to an openEO User-Defined Process involves more than simple translation. You need to understand both what the algorithm does scientifically and how to express that logic using openEO's process graph structure.

‎README.md‎

Lines changed: 41 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -88,31 +88,59 @@ Each notebook concludes with proper attribution to the original evalscript autho
8888
To run these notebooks, you need:
8989

9090
- Python 3.11 or later
91-
- Jupyter Notebook or JupyterLab
91+
- [uv](https://docs.astral.sh/uv/) for fast and reliable dependency management
9292
- Access to an openEO backend (we recommend https://openeo.ds.io/ for testing)
9393
- Basic understanding of remote sensing concepts and Python programming
9494

95-
### Installation
96-
97-
Clone the repository and install the required dependencies:
98-
99-
```bash
100-
git clone https://github.com/developmentseed/openeo-udp.git
101-
cd openeo-udp
102-
pip install -r requirements.txt
103-
```
95+
### Environment Setup
10496

105-
The requirements file includes the openEO Python client library, visualization tools like matplotlib and Pillow, and any specialized processing libraries needed for specific algorithms.
97+
This project uses [uv](https://docs.astral.sh/uv/) for fast and reliable dependency management.
98+
99+
1. **Install uv** if you haven't already:
100+
```bash
101+
# On macOS and Linux
102+
curl -LsSf https://astral.sh/uv/install.sh | sh
103+
104+
# On Windows
105+
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
106+
```
107+
108+
2. **Clone the repository and set up the environment**:
109+
```bash
110+
git clone https://github.com/developmentseed/openeo-udp.git
111+
cd openeo-udp
112+
113+
# Create virtual environment and install all dependencies
114+
uv sync
115+
```
116+
117+
3. **Install as Jupyter kernel** (recommended for running notebooks):
118+
```bash
119+
# Install the environment as a Jupyter kernel
120+
uv run python -m ipykernel install --user --name openeo-udp --display-name "openEO UDP"
121+
```
122+
123+
The environment includes the openEO Python client library, visualization tools like matplotlib and Pillow, Jupyter, and all other dependencies needed to run the notebooks.
106124

107125
### Running a Notebook
108126

109127
Start Jupyter and open any notebook. For example, the [NDCI cyanobacteria notebook](notebooks/sentinel/sentinel-2/marine_and_water_bodies/ndci_cyanobacteria.ipynb):
110128

111129
```bash
112-
jupyter notebook notebooks/sentinel/sentinel-2/marine_and_water_bodies/ndci_cyanobacteria.ipynb
130+
# Start Jupyter using uv
131+
uv run jupyter lab
132+
133+
# Or start Jupyter Notebook
134+
uv run jupyter notebook
113135
```
114136

115-
Execute the cells sequentially to see the conversion process, validate results, and export the UDP definition. 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.
137+
When creating or opening a notebook:
138+
139+
1. Make sure the "openEO UDP" kernel is selected (if you installed it as a kernel)
140+
2. Open the [NDCI cyanobacteria notebook](notebooks/sentinel/sentinel-2/marine_and_water_bodies/ndci_cyanobacteria.ipynb)
141+
3. Execute the cells sequentially to see the conversion process, validate results, and export the UDP definition
142+
143+
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.
116144

117145
## Using the Exported UDPs
118146

‎pyproject.toml‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
[build-system]
2+
requires = ["setuptools>=45", "wheel"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "openeo-udp"
7+
description = "openEO User-Defined Processes converted from Sentinel Hub evalscripts"
8+
readme = "README.md"
9+
license = {text = "Apache-2.0"}
10+
authors = [
11+
{name = "Development Seed", email = "[email protected]"},
12+
]
13+
classifiers = [
14+
"Development Status :: 4 - Beta",
15+
"Intended Audience :: Science/Research",
16+
"License :: OSI Approved :: Apache Software License",
17+
"Operating System :: OS Independent",
18+
"Programming Language :: Python :: 3",
19+
"Programming Language :: Python :: 3.11",
20+
"Programming Language :: Python :: 3.12",
21+
"Topic :: Scientific/Engineering :: GIS",
22+
]
23+
requires-python = ">=3.11"
24+
dependencies = [
25+
"openeo>=0.24.0",
26+
"matplotlib>=3.7.0",
27+
"Pillow>=10.0.0",
28+
"numpy>=1.24.0",
29+
"jupyter>=1.0.0",
30+
"ipykernel>=6.25.0",
31+
"requests>=2.28.0",
32+
]
33+
34+
[project.optional-dependencies]
35+
dev = [
36+
"pytest>=7.0.0",
37+
"pytest-cov>=4.0.0",
38+
"black>=23.0.0",
39+
"ruff>=0.0.290",
40+
"pre-commit>=3.0.0",
41+
]
42+
docs = [
43+
"mkdocs>=1.5.0",
44+
"mkdocs-material>=9.0.0",
45+
"mkdocstrings[python]>=0.23.0",
46+
]
47+
48+
[project.urls]
49+
Homepage = "https://github.com/developmentseed/openeo-udp"
50+
Documentation = "https://github.com/developmentseed/openeo-udp"
51+
Repository = "https://github.com/developmentseed/openeo-udp"
52+
"Bug Tracker" = "https://github.com/developmentseed/openeo-udp/issues"
53+
54+
[tool.setuptools.packages.find]
55+
where = ["src"]
56+
57+
[tool.setuptools.package-dir]
58+
"" = "src"
59+
60+
[tool.black]
61+
line-length = 88
62+
target-version = ['py311']
63+
include = '\.pyi?$'
64+
extend-exclude = '''
65+
/(
66+
# directories
67+
\.eggs
68+
| \.git
69+
| \.hg
70+
| \.mypy_cache
71+
| \.tox
72+
| \.venv
73+
| _build
74+
| buck-out
75+
| build
76+
| dist
77+
)/
78+
'''
79+
80+
[tool.ruff]
81+
target-version = "py311"
82+
line-length = 88
83+
select = [
84+
"E", # pycodestyle errors
85+
"W", # pycodestyle warnings
86+
"F", # pyflakes
87+
"I", # isort
88+
"C", # flake8-comprehensions
89+
"B", # flake8-bugbear
90+
]
91+
ignore = [
92+
"E501", # line too long, handled by black
93+
"B008", # do not perform function calls in argument defaults
94+
"C901", # too complex
95+
]
96+
97+
[tool.pytest.ini_options]
98+
testpaths = ["tests"]
99+
python_files = ["test_*.py"]
100+
python_functions = ["test_*"]
101+
addopts = "-v --tb=short --strict-markers"
102+
markers = [
103+
"slow: marks tests as slow (deselect with '-m \"not slow\"')",
104+
"integration: marks tests as integration tests",
105+
]

0 commit comments

Comments
 (0)