{"id":34930256,"url":"https://github.com/kalfasyan/vresto","last_synced_at":"2026-04-25T18:01:27.031Z","repository":{"id":330881459,"uuid":"1111087192","full_name":"kalfasyan/vresto","owner":"kalfasyan","description":"Satellite product browser","archived":false,"fork":false,"pushed_at":"2026-04-21T20:32:08.000Z","size":254219,"stargazers_count":27,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T21:31:13.264Z","etag":null,"topics":["cdse","copernicus-products","nicegui","remote-sensing","satellite-imagery","sentinel-2","webapp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kalfasyan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-06T08:40:53.000Z","updated_at":"2026-04-20T05:29:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kalfasyan/vresto","commit_stats":null,"previous_names":["kalfasyan/vresto"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/kalfasyan/vresto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kalfasyan%2Fvresto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kalfasyan%2Fvresto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kalfasyan%2Fvresto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kalfasyan%2Fvresto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kalfasyan","download_url":"https://codeload.github.com/kalfasyan/vresto/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kalfasyan%2Fvresto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32271243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdse","copernicus-products","nicegui","remote-sensing","satellite-imagery","sentinel-2","webapp"],"created_at":"2025-12-26T15:34:01.874Z","updated_at":"2026-04-25T18:01:27.025Z","avatar_url":"https://github.com/kalfasyan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/vresto_logo.jpg\" alt=\"vresto logo\" width=\"320\" /\u003e\n  \n  # vresto\n  \n  **An elegant Python interface for discovering and retrieving Copernicus Sentinel data.**\n  \n  [![PyPI version](https://badge.fury.io/py/vresto.svg)](https://badge.fury.io/py/vresto)\n  [![PyPI Downloads](https://static.pepy.tech/personalized-badge/vresto?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=BLACK\u0026right_color=GREEN\u0026left_text=downloads)](https://pepy.tech/projects/vresto)\n  [![Tests](https://github.com/kalfasyan/vresto/actions/workflows/tests.yml/badge.svg)](https://github.com/kalfasyan/vresto/actions/workflows/tests.yml)\n  [![Docs - MkDocs](https://img.shields.io/badge/docs-mkdocs-blue)](https://kalfasyan.github.io/vresto/)\n  [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n  [![Gitleaks](https://img.shields.io/badge/secret%20scanning-gitleaks-blue)](https://github.com/gitleaks/gitleaks)\n\u003c/div\u003e\n\n---\n\n## Demo  \n*(wait a few seconds for it to load)*\n\n![vresto Demo](docs/assets/vresto_demo.gif)\n\n## Features\n\n- 🗺️ **Interactive Map Interface** - Visually search and filter satellite products\n- 🛰️ **High-Resolution Tile Server** - Instantly visualize full-resolution product bands on the map (via `localtileserver`)\n- 🔍 **Smart Search** - Filter by location, date range, cloud cover, and product type\n- 📦 **Granular Download Management** - Advanced Band-Resolution matrix for precise data selection and de-duplicated downloads\n- 🔌 **Dual Backend Support** - Flexible discovery via **OData** or **STAC** APIs\n- 🐍 **Professional API** - Clean Python API for programmatic access\n- 🔐 **Secure** - Handle S3 credentials safely with static key support\n- ⚡ **Efficient** - Batch operations and smart caching\n\n## ⚡ Quick Start with Docker 🐳\n\nThe fastest way to run `vresto` is by using Docker Compose 🚢\n\nYou 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/).\n\n**Note:** You need Copernicus credentials to use vresto. Get free access at https://dataspace.copernicus.eu/\n\nStart `vresto` in just a few steps:\n\n1. **Clone the repository and go to its main directory**\n    ```bash\n    git clone https://github.com/kalfasyan/vresto.git \u0026\u0026 cd vresto\n    ```\n\n2. **Start the application with one command**\n    ```bash\n    make docker-up\n    ```\n    \n    ℹ️ **That's it!** The app will start and you can add credentials later via the UI, or provide them now:\n    \n    **Option A: Add credentials now** (Recommended if you have them)\n    - Create a `.env` file from the committed template:\n      ```bash\n      cp .env.example .env\n      # Edit .env with your credentials\n      ```\n    - Then run one of these commands:\n      ```bash\n      make docker-up\n      ```\n      or:\n      ```bash\n      docker compose up -d\n      ```\n    - `.env` is ignored by git; do not commit secrets.\n    - Optional `.env` variables: `COPERNICUS_S3_ACCESS_KEY`, `COPERNICUS_S3_SECRET_KEY`, `COPERNICUS_S3_ENDPOINT`, `VRESTO_BASE_TILE_PORT` (default: 8611)\n    \n    **Option B: Add credentials later** (via the app Settings menu)\n    - Just run `make docker-up` without credentials (use `make docker-rebuild` if you just cloned the repo and want a rebuild)\n    - The app will start at http://localhost:8610 (tile server traffic is mapped via `VRESTO_BASE_TILE_PORT`)\n    - Click the **☰ menu button** in the top-left corner to open the Settings drawer\n    - Add your Copernicus credentials through the Settings menu anytime\n    - S3 credentials are optional—without them you'll get temporary credentials with usage limits (see [Setup Guide](docs/getting-started/setup.md) for details)\n\n✅ **Done!** 🎉\n\nYour vresto dashboard is now running at:  \n🌐 [http://localhost:8610](http://localhost:8610)\n\n**Note:** If you pulled recent changes and a feature isn't available, rebuild the Docker image:\n```bash\ndocker compose up -d --build\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🚀 Essential Docker \u0026 Docker Compose Commands\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Start the app in background (Docker Compose)\nmake docker-up\n```\n\n```bash\n# View logs (Docker Compose)\nmake docker-logs\n```\n\n```bash\n# Stop and remove services (Docker Compose)\nmake docker-down\n```\n\n```bash\n# Rebuild and start (Docker Compose)\nmake docker-rebuild\n```\n\n```bash\n# Run the container directly (plain Docker)\ndocker run -d -p 8610:8610 \\\n  --name vresto-dashboard \\\n  vresto:latest\n```\n\n```bash\n# View logs (plain Docker)\ndocker logs -f vresto-dashboard\n```\n\n```bash\n# Stop and remove the container (plain Docker)\ndocker stop vresto-dashboard \u0026\u0026 docker rm vresto-dashboard\n```\n\u003c/details\u003e\n\n## Quick Start\n\n**Note:** You need Copernicus credentials to use vresto. Get free access at https://dataspace.copernicus.eu/\n\n\n### Installation\n\n**From PyPI (recommended for users):**\n```bash\npip install vresto\n```\n\n**For development:**\n```bash\ngit clone https://github.com/kalfasyan/vresto.git\ncd vresto\nuv sync\n```\n\n### Configuration\n\nConfigure your credentials (see [Setup Guide](docs/getting-started/setup.md) for details):\n```bash\nexport COPERNICUS_USERNAME=\"your_email@example.com\"\nexport COPERNICUS_PASSWORD=\"your_password\"\n```\n\nOr run the interactive setup helper which writes a `.env` in the project root:\n```bash\npython scripts/setup_credentials.py\n```\n\n### Launch the App\n\nSimply run:\n```bash\nvresto\n```\n\nOpens at http://localhost:8610 (the tile server runs on a random port handled internally)\n\n**Alternative methods:**\n```bash\n# Using make\nmake app\n\n# Or directly with Python\npython src/vresto/ui/app.py\n```\n\n**Command-Line Interface (CLI):**\n\nQuick searches and downloads from the terminal:\n\n```bash\n# 🔍 Search for products\nvresto-cli search-name \"S2A_MSIL2A_20200612\" --max-results 5\n\n# 📸 Download quicklook (preview image)\nvresto-cli download-quicklook \"S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018\" --output ./quicklooks\n\n# 📋 Download metadata\nvresto-cli download-metadata \"S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018\" --output ./metadata\n\n# 🎨 Download specific bands\nvresto-cli download-bands \"S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018\" \"B04,B03,B02\" --resolution 10 --output ./data\n```\n\nFor complete CLI documentation, see the [CLI Guide](docs/user-guide/cli.md).\n\n**API usage:**\n\nGet started with just a few lines of Python:\n\n```python\nfrom vresto.api import CatalogSearch, CopernicusConfig\nfrom vresto.products import ProductsManager\n\n# Initialize\nconfig = CopernicusConfig()\ncatalog = CatalogSearch(config=config)\nmanager = ProductsManager(config=config)\n\n# 🔍 Search for a product by name\nproducts = catalog.search_products_by_name(\"S2A_MSIL2A\", max_results=5)\n\n# 📸 Download quicklook and metadata\nfor product in products:\n    quicklook = manager.get_quicklook(product)\n    metadata = manager.get_metadata(product)\n    if quicklook:\n        quicklook.save_to_file(f\"{product.name}.jpg\")\n\n# 🎨 Download specific bands for analysis/visualization\nmanager.download_product_bands(\n    product=products[0].name,\n    bands=[\"B04\", \"B03\", \"B02\"],  # Red, Green, Blue\n    resolution=10,\n    dest_dir=\"./data\",\n)\n```\n\nFor more examples, see the [examples/](examples/) directory and [API Guide](docs/user-guide/api.md).\n\nFor detailed setup and usage, see the documentation below.\n\n## Documentation\n\n📖 **[Full Documentation](https://kalfasyan.github.io/vresto/)** - Hosted on GitHub Pages\n\n- **[Setup Guide](https://kalfasyan.github.io/vresto/getting-started/setup/)** ⭐ **Start here** - Installation, credentials setup, and configuration\n- [API Guide](https://kalfasyan.github.io/vresto/user-guide/api/) - Programmatic usage examples and reference\n- [AWS CLI Guide](https://kalfasyan.github.io/vresto/advanced/aws-cli/) - Direct S3 access with AWS CLI\n- [Contributing](CONTRIBUTING.md) - Development setup\n\n## Requirements\n\n- Python 3.11+\n- `uv` package manager (optional but recommended)\n\n## License\n\nSee [LICENSE.txt](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkalfasyan%2Fvresto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkalfasyan%2Fvresto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkalfasyan%2Fvresto/lists"}