Skip to content

Commit 4ff3044

Browse files
VTvitoVTvito
committed
docs: add GitHub repo setup guide and release notes template
1 parent 2699b72 commit 4ff3044

2 files changed

Lines changed: 398 additions & 0 deletions

File tree

‎GITHUB_REPO_SETUP.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# GitHub Repository Setup
2+
3+
Copy and paste these settings into your GitHub repository.
4+
5+
## Repository Description
6+
7+
```
8+
Python client for Copernicus Data Space Ecosystem (CDSE) - Modern replacement for sentinelsat with support for Sentinel-1/2/3/5P data
9+
```
10+
11+
## Website URL
12+
13+
```
14+
https://vtvito.github.io/cdse-client/
15+
```
16+
17+
## Topics (GitHub Tags)
18+
19+
Add these topics to your repository (Settings → General → Topics):
20+
21+
```
22+
copernicus
23+
sentinel
24+
satellite-imagery
25+
earth-observation
26+
remote-sensing
27+
sentinel-2
28+
sentinel-1
29+
cdse
30+
stac
31+
geospatial
32+
python
33+
eo-data
34+
earth-engine
35+
satellite-data
36+
copernicus-data
37+
sentinelsat
38+
data-download
39+
gis
40+
geospatial-analysis
41+
open-data
42+
```
43+
44+
## Social Media Description
45+
46+
**For Twitter/X, LinkedIn, etc.:**
47+
48+
🛰️ Just released cdse-client v0.3.0 - A modern Python library for downloading Copernicus Sentinel satellite data!
49+
50+
✨ Features:
51+
• Drop-in replacement for sentinelsat
52+
• Support for Sentinel-1/2/3/5P
53+
• STAC API search
54+
• Async downloads
55+
• Processing utilities (NDVI, crop, stack)
56+
• CLI tools
57+
58+
🔗 https://github.com/VTvito/cdse-client
59+
📦 pip install cdse-client
60+
61+
#Python #RemoteSensing #EarthObservation #Copernicus #GIS
62+
63+
---
64+
65+
## README Badge Suggestions
66+
67+
Add these badges to the top of your README.md (after the existing badges):
68+
69+
```markdown
70+
[![Downloads](https://static.pepy.tech/badge/cdse-client)](https://pepy.tech/project/cdse-client)
71+
[![Downloads/Month](https://static.pepy.tech/badge/cdse-client/month)](https://pepy.tech/project/cdse-client)
72+
[![GitHub stars](https://img.shields.io/github/stars/VTvito/cdse-client?style=social)](https://github.com/VTvito/cdse-client/stargazers)
73+
[![Documentation Status](https://readthedocs.org/projects/cdse-client/badge/?version=latest)](https://cdse-client.readthedocs.io/en/latest/?badge=latest)
74+
```
75+
76+
---
77+
78+
## How to Set These Up
79+
80+
### 1. Repository Description & Website
81+
1. Go to https://github.com/VTvito/cdse-client
82+
2. Click **Settings** (gear icon at top right of the repo page)
83+
3. Under **General** → **Description**, paste the description
84+
4. Under **Website**, paste: `https://vtvito.github.io/cdse-client/`
85+
5. Click **Save changes**
86+
87+
### 2. Topics
88+
1. On the main repository page, click **Add topics** (next to About)
89+
2. Copy the topics list above and paste them one by one
90+
3. Press Enter after each topic
91+
92+
### 3. Enable GitHub Pages
93+
1. Go to **Settings** → **Pages**
94+
2. Under **Source**, select **GitHub Actions**
95+
3. Save
96+
97+
### 4. Enable Discussions (Optional but Recommended)
98+
1. Go to **Settings** → **General**
99+
2. Scroll to **Features**
100+
3. Check ✅ **Discussions**
101+
4. This allows users to ask questions and share use cases
102+
103+
---
104+
105+
## Marketing Checklist
106+
107+
- [ ] Post on Twitter/X with hashtags
108+
- [ ] Post on LinkedIn (tag Copernicus, ESA)
109+
- [ ] Submit to:
110+
- [ ] [PyPI Trending](https://pypi.org/project/cdse-client/)
111+
- [ ] [awesome-python](https://github.com/vinta/awesome-python) (create PR)
112+
- [ ] [awesome-geospatial](https://github.com/sacridini/Awesome-Geospatial) (create PR)
113+
- [ ] [awesome-earthobservation-code](https://github.com/acgeospatial/awesome-earthobservation-code)
114+
- [ ] Reddit r/Python, r/gis, r/eo
115+
- [ ] Write blog post or tutorial
116+
- [ ] Create YouTube demo video
117+
- [ ] Add example notebooks to repository
118+
119+
---
120+
121+
## SEO Keywords for PyPI
122+
123+
Already in pyproject.toml, but here's the full list for reference:
124+
125+
```python
126+
keywords = [
127+
"copernicus",
128+
"sentinel",
129+
"satellite",
130+
"remote-sensing",
131+
"earth-observation",
132+
"CDSE",
133+
"STAC",
134+
"sentinelsat"
135+
]
136+
```
137+
138+
---
139+
140+
## GitHub Release Notes Template (for v0.3.0)
141+
142+
```markdown
143+
# 🚀 cdse-client v0.3.0
144+
145+
First production release of cdse-client - a modern Python client for Copernicus Data Space Ecosystem.
146+
147+
## 🎯 Overview
148+
149+
`cdse-client` is a drop-in replacement for the deprecated `sentinelsat` library, providing access to Sentinel-1/2/3/5P satellite data through the new CDSE infrastructure.
150+
151+
## ✨ Features
152+
153+
- **Search & Download**: STAC API search with flexible filters (bbox, date, cloud cover, etc.)
154+
- **Collections**: Support for Sentinel-1 GRD, Sentinel-2 L1C/L2A, Sentinel-3 OLCI/SLSTR, Sentinel-5P L2
155+
- **Export Formats**: DataFrame, GeoJSON, GeoDataFrame (sentinelsat compatible)
156+
- **Processing**: Band extraction, cropping, stacking, NDVI calculation, preview generation
157+
- **Async Support**: High-performance concurrent downloads with aiohttp
158+
- **CLI Tools**: Command-line interface for search and download operations
159+
- **Geocoding**: Search by city name with built-in bbox lookup
160+
- **Type Safety**: Full type hints and py.typed marker
161+
162+
## 📦 Installation
163+
164+
```bash
165+
pip install cdse-client # Core functionality
166+
pip install cdse-client[all] # Everything included
167+
```
168+
169+
## 🔧 Quick Start
170+
171+
```python
172+
from cdse import CDSEClient
173+
174+
client = CDSEClient(client_id="...", client_secret="...")
175+
176+
# Search Sentinel-2 data
177+
products = client.search(
178+
bbox=[9.0, 45.0, 9.5, 45.5],
179+
start_date="2024-01-01",
180+
end_date="2024-01-31",
181+
collection="sentinel-2-l2a",
182+
cloud_cover_max=20
183+
)
184+
185+
# Download
186+
for product in products:
187+
client.download(product)
188+
```
189+
190+
## 📚 Documentation
191+
192+
- **Docs**: https://vtvito.github.io/cdse-client/
193+
- **PyPI**: https://pypi.org/project/cdse-client/
194+
- **GitHub**: https://github.com/VTvito/cdse-client
195+
196+
## 🙏 Acknowledgments
197+
198+
This library provides unofficial client access to:
199+
- Copernicus Data Space Ecosystem (CDSE)
200+
- European Space Agency (ESA) data
201+
- European Commission Copernicus Programme
202+
203+
Data is provided under free, full, and open data policy.
204+
205+
## 📄 License
206+
207+
MIT License - See [LICENSE](LICENSE)
208+
209+
---
210+
211+
**Full Changelog**: https://github.com/VTvito/cdse-client/compare/v0.1.0...v0.3.0
212+
```
213+
214+
---
215+
216+
## Example Use Cases for README/Docs
217+
218+
Add these examples to show practical applications:
219+
220+
### 🌾 Agriculture Monitoring
221+
```python
222+
# Monitor crop health with NDVI
223+
from cdse import CDSEClient
224+
from cdse.processing import calculate_ndvi, crop_and_stack
225+
226+
client = CDSEClient()
227+
products = client.search_by_city("Mantova, Italia", collection="sentinel-2-l2a")
228+
229+
for product in products[:1]:
230+
client.download(product)
231+
# Extract and process bands
232+
result = crop_and_stack(
233+
product.name + ".zip",
234+
bbox=[...],
235+
bands=["B08", "B04"] # NIR and Red
236+
)
237+
ndvi = calculate_ndvi(nir_path="B08.tif", red_path="B04.tif")
238+
```
239+
240+
### 🌊 Water Body Detection
241+
```python
242+
# Track water bodies over time
243+
products = client.search(
244+
bbox=[12.0, 45.0, 13.0, 46.0],
245+
collection="sentinel-2-l2a",
246+
start_date="2023-01-01",
247+
end_date="2023-12-31"
248+
)
249+
```
250+
251+
### 🏙️ Urban Growth Analysis
252+
```python
253+
# Monitor urban expansion
254+
products = client.search_by_city(
255+
"Milano, Italia",
256+
collection="sentinel-2-l2a",
257+
buffer_km=20
258+
)
259+
260+
df = client.to_dataframe(products)
261+
df.sort_values('datetime').to_csv('milano_imagery.csv')
262+
```
263+

‎RELEASE_NOTES_v0.3.0.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# 🚀 cdse-client v0.3.0
2+
3+
First production release of **cdse-client** - a modern Python client for Copernicus Data Space Ecosystem.
4+
5+
## 🎯 Overview
6+
7+
`cdse-client` is a drop-in replacement for the deprecated `sentinelsat` library, providing access to Sentinel-1/2/3/5P satellite data through the new CDSE infrastructure.
8+
9+
## ✨ Features
10+
11+
### Core Functionality
12+
- 🔍 **STAC API Search**: Flexible search with bbox, date range, cloud cover, and more
13+
- 📥 **Smart Downloads**: Automatic retry, checksum verification, quicklook support
14+
- 🗂️ **Multiple Collections**: Sentinel-1 GRD, Sentinel-2 L1C/L2A, Sentinel-3 OLCI/SLSTR, Sentinel-5P L2
15+
- 📊 **Export Formats**: DataFrame, GeoJSON, GeoDataFrame (sentinelsat compatible)
16+
17+
### Processing Tools
18+
- 🛠️ **Band Extraction**: Extract specific bands from .SAFE or .zip files
19+
- ✂️ **Cropping & Stacking**: Crop to AOI and stack bands into multi-band GeoTIFF
20+
- 🌱 **NDVI Calculation**: Built-in vegetation index calculation
21+
- 🖼️ **Preview Generation**: Create RGB previews with Jupyter notebook support
22+
23+
### Advanced Features
24+
- ⚡ **Async Downloads**: High-performance concurrent downloads with `aiohttp`
25+
- 💻 **CLI Interface**: Command-line tools for search and download
26+
- 🗺️ **Geocoding**: Search by city name with automatic bbox lookup
27+
- 🔒 **Type Safety**: Full type hints with `py.typed` marker
28+
29+
## 📦 Installation
30+
31+
```bash
32+
# Core functionality
33+
pip install cdse-client
34+
35+
# With all extras (recommended)
36+
pip install cdse-client[all]
37+
38+
# Specific extras
39+
pip install cdse-client[geo] # + shapely, geopandas, geopy
40+
pip install cdse-client[processing] # + rasterio, numpy, matplotlib
41+
pip install cdse-client[async] # + aiohttp, aiofiles
42+
pip install cdse-client[dataframe] # + pandas
43+
```
44+
45+
## 🚦 Quick Start
46+
47+
```python
48+
from cdse import CDSEClient
49+
50+
# Initialize with OAuth2 credentials
51+
client = CDSEClient(
52+
client_id="your-client-id",
53+
client_secret="your-client-secret"
54+
)
55+
56+
# Search Sentinel-2 data over Milan
57+
products = client.search(
58+
bbox=[9.0, 45.0, 9.5, 45.5],
59+
start_date="2024-01-01",
60+
end_date="2024-01-31",
61+
collection="sentinel-2-l2a",
62+
cloud_cover_max=20,
63+
limit=5
64+
)
65+
66+
# Download products
67+
for product in products:
68+
path = client.download(product)
69+
print(f"Downloaded: {path}")
70+
```
71+
72+
## 📖 Documentation
73+
74+
- **Documentation**: https://vtvito.github.io/cdse-client/
75+
- **PyPI Package**: https://pypi.org/project/cdse-client/
76+
- **Source Code**: https://github.com/VTvito/cdse-client
77+
78+
## 🆕 What's New in v0.3.0
79+
80+
### New Modules
81+
- ✅ `cdse.processing` - Band extraction, cropping, stacking, NDVI, previews
82+
- ✅ `cdse.async_client` - High-performance async downloads
83+
- ✅ `cdse.converters` - DataFrame, GeoJSON, GeoDataFrame export
84+
- ✅ `cdse.geocoding` - City-based bbox lookup
85+
- ✅ `cdse.geometry` - GeoJSON/WKT utilities
86+
87+
### CLI Improvements
88+
- ✅ `cdse search` - Search products from command line
89+
- ✅ `cdse download` - Download by name/UUID with quicklook support
90+
- ✅ `cdse collections` - List available collections
91+
92+
### Quality & Documentation
93+
- ✅ Full test suite (135+ tests, 46% coverage)
94+
- ✅ Complete MkDocs documentation
95+
- ✅ Type hints with `py.typed` marker
96+
- ✅ CI/CD with GitHub Actions
97+
- ✅ Security policy and contributing guidelines
98+
99+
## 🔄 Migration from sentinelsat
100+
101+
| sentinelsat | cdse-client |
102+
|-------------|-------------|
103+
| `SentinelAPI(user, password)` | `CDSEClient(client_id, client_secret)` |
104+
| `api.query(...)` | `client.search(...)` |
105+
| `api.download(uuid)` | `client.download(product)` |
106+
| `api.to_dataframe(...)` | `client.to_dataframe(...)` |
107+
| `api.to_geojson(...)` | `client.to_geojson(...)` |
108+
109+
See [Migration Guide](https://vtvito.github.io/cdse-client/migration/) for details.
110+
111+
## 🛡️ Requirements
112+
113+
- Python ≥ 3.9
114+
- OAuth2 credentials from [Copernicus Data Space](https://dataspace.copernicus.eu/)
115+
116+
## 🙏 Acknowledgments
117+
118+
This is an **unofficial** client library. The Copernicus Data Space Ecosystem and Sentinel data are provided by:
119+
- European Space Agency (ESA)
120+
- European Commission
121+
- Copernicus Programme
122+
123+
Sentinel data is available under a **free, full, and open** data policy for any use, including commercial. See [Sentinel Data Legal Notice](https://sentinels.copernicus.eu/documents/247904/690755/Sentinel_Data_Legal_Notice).
124+
125+
## 📄 License
126+
127+
MIT License - See [LICENSE](https://github.com/VTvito/cdse-client/blob/main/LICENSE)
128+
129+
## 🤝 Contributing
130+
131+
Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/VTvito/cdse-client/blob/main/CONTRIBUTING.md)
132+
133+
---
134+
135+
**Full Changelog**: https://github.com/VTvito/cdse-client/commits/main

0 commit comments

Comments
 (0)