https://github.com/kalfasyan/vresto
Satellite product browser
https://github.com/kalfasyan/vresto
cdse copernicus-products nicegui remote-sensing satellite-imagery sentinel-2 webapp
Last synced: about 1 month ago
JSON representation
Satellite product browser
- Host: GitHub
- URL: https://github.com/kalfasyan/vresto
- Owner: kalfasyan
- License: cc-by-4.0
- Created: 2025-12-06T08:40:53.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-04-21T20:32:08.000Z (about 2 months ago)
- Last Synced: 2026-04-21T21:31:13.264Z (about 2 months ago)
- Topics: cdse, copernicus-products, nicegui, remote-sensing, satellite-imagery, sentinel-2, webapp
- Language: Python
- Homepage:
- Size: 242 MB
- Stars: 27
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Security: SECURITY.md
Awesome Lists containing this project
README
# vresto
**An elegant Python interface for discovering and retrieving Copernicus Sentinel data.**
[](https://badge.fury.io/py/vresto)
[](https://pepy.tech/projects/vresto)
[](https://github.com/kalfasyan/vresto/actions/workflows/tests.yml)
[](https://kalfasyan.github.io/vresto/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/gitleaks/gitleaks)
---
## Demo
*(wait a few seconds for it to load)*
## Features
- 🗺️ **Interactive Map Interface** - Visually search and filter satellite products
- 🛰️ **High-Resolution Tile Server** - Instantly visualize full-resolution product bands on the map (via `localtileserver`)
- 🔍 **Smart Search** - Filter by location, date range, cloud cover, and product type
- 📦 **Granular Download Management** - Advanced Band-Resolution matrix for precise data selection and de-duplicated downloads
- 🔌 **Dual Backend Support** - Flexible discovery via **OData** or **STAC** APIs
- 🐍 **Professional API** - Clean Python API for programmatic access
- 🔐 **Secure** - Handle S3 credentials safely with static key support
- ⚡ **Efficient** - Batch operations and smart caching
## ⚡ Quick Start with Docker 🐳
The fastest way to run `vresto` is by using Docker Compose 🚢
You only need Docker and Docker Compose installed on your machine. If you don't have them yet, you can find installation instructions on the [Docker website](https://docs.docker.com/get-docker/) and [Docker Compose documentation](https://docs.docker.com/compose/install/).
**Note:** You need Copernicus credentials to use vresto. Get free access at https://dataspace.copernicus.eu/
Start `vresto` in just a few steps:
1. **Clone the repository and go to its main directory**
```bash
git clone https://github.com/kalfasyan/vresto.git && cd vresto
```
2. **Start the application with one command**
```bash
make docker-up
```
ℹ️ **That's it!** The app will start and you can add credentials later via the UI, or provide them now:
**Option A: Add credentials now** (Recommended if you have them)
- Create a `.env` file from the committed template:
```bash
cp .env.example .env
# Edit .env with your credentials
```
- Then run one of these commands:
```bash
make docker-up
```
or:
```bash
docker compose up -d
```
- `.env` is ignored by git; do not commit secrets.
- Optional `.env` variables: `COPERNICUS_S3_ACCESS_KEY`, `COPERNICUS_S3_SECRET_KEY`, `COPERNICUS_S3_ENDPOINT`, `VRESTO_BASE_TILE_PORT` (default: 8611)
**Option B: Add credentials later** (via the app Settings menu)
- Just run `make docker-up` without credentials (use `make docker-rebuild` if you just cloned the repo and want a rebuild)
- The app will start at http://localhost:8610 (tile server traffic is mapped via `VRESTO_BASE_TILE_PORT`)
- Click the **☰ menu button** in the top-left corner to open the Settings drawer
- Add your Copernicus credentials through the Settings menu anytime
- S3 credentials are optional—without them you'll get temporary credentials with usage limits (see [Setup Guide](docs/getting-started/setup.md) for details)
✅ **Done!** 🎉
Your vresto dashboard is now running at:
🌐 [http://localhost:8610](http://localhost:8610)
**Note:** If you pulled recent changes and a feature isn't available, rebuild the Docker image:
```bash
docker compose up -d --build
```
🚀 Essential Docker & Docker Compose Commands
```bash
# Start the app in background (Docker Compose)
make docker-up
```
```bash
# View logs (Docker Compose)
make docker-logs
```
```bash
# Stop and remove services (Docker Compose)
make docker-down
```
```bash
# Rebuild and start (Docker Compose)
make docker-rebuild
```
```bash
# Run the container directly (plain Docker)
docker run -d -p 8610:8610 \
--name vresto-dashboard \
vresto:latest
```
```bash
# View logs (plain Docker)
docker logs -f vresto-dashboard
```
```bash
# Stop and remove the container (plain Docker)
docker stop vresto-dashboard && docker rm vresto-dashboard
```
## Quick Start
**Note:** You need Copernicus credentials to use vresto. Get free access at https://dataspace.copernicus.eu/
### Installation
**From PyPI (recommended for users):**
```bash
pip install vresto
```
**For development:**
```bash
git clone https://github.com/kalfasyan/vresto.git
cd vresto
uv sync
```
### Configuration
Configure your credentials (see [Setup Guide](docs/getting-started/setup.md) for details):
```bash
export COPERNICUS_USERNAME="your_email@example.com"
export COPERNICUS_PASSWORD="your_password"
```
Or run the interactive setup helper which writes a `.env` in the project root:
```bash
python scripts/setup_credentials.py
```
### Launch the App
Simply run:
```bash
vresto
```
Opens at http://localhost:8610 (the tile server runs on a random port handled internally)
**Alternative methods:**
```bash
# Using make
make app
# Or directly with Python
python src/vresto/ui/app.py
```
**Command-Line Interface (CLI):**
Quick searches and downloads from the terminal:
```bash
# 🔍 Search for products
vresto-cli search-name "S2A_MSIL2A_20200612" --max-results 5
# 📸 Download quicklook (preview image)
vresto-cli download-quicklook "S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018" --output ./quicklooks
# 📋 Download metadata
vresto-cli download-metadata "S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018" --output ./metadata
# 🎨 Download specific bands
vresto-cli download-bands "S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018" "B04,B03,B02" --resolution 10 --output ./data
```
For complete CLI documentation, see the [CLI Guide](docs/user-guide/cli.md).
**API usage:**
Get started with just a few lines of Python:
```python
from vresto.api import CatalogSearch, CopernicusConfig
from vresto.products import ProductsManager
# Initialize
config = CopernicusConfig()
catalog = CatalogSearch(config=config)
manager = ProductsManager(config=config)
# 🔍 Search for a product by name
products = catalog.search_products_by_name("S2A_MSIL2A", max_results=5)
# 📸 Download quicklook and metadata
for product in products:
quicklook = manager.get_quicklook(product)
metadata = manager.get_metadata(product)
if quicklook:
quicklook.save_to_file(f"{product.name}.jpg")
# 🎨 Download specific bands for analysis/visualization
manager.download_product_bands(
product=products[0].name,
bands=["B04", "B03", "B02"], # Red, Green, Blue
resolution=10,
dest_dir="./data",
)
```
For more examples, see the [examples/](examples/) directory and [API Guide](docs/user-guide/api.md).
For detailed setup and usage, see the documentation below.
## Documentation
📖 **[Full Documentation](https://kalfasyan.github.io/vresto/)** - Hosted on GitHub Pages
- **[Setup Guide](https://kalfasyan.github.io/vresto/getting-started/setup/)** ⭐ **Start here** - Installation, credentials setup, and configuration
- [API Guide](https://kalfasyan.github.io/vresto/user-guide/api/) - Programmatic usage examples and reference
- [AWS CLI Guide](https://kalfasyan.github.io/vresto/advanced/aws-cli/) - Direct S3 access with AWS CLI
- [Contributing](CONTRIBUTING.md) - Development setup
## Requirements
- Python 3.11+
- `uv` package manager (optional but recommended)
## License
See [LICENSE.txt](LICENSE.txt)