Metadata-Version: 2.4
Name: pygeovision
Version: 0.1.1
Summary: World-class Geospatial AI Platform — pygeofetch + geoai + PyGeoVision
Author: PyGeoVision Contributors
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
           Copyright 2024 PyGeoVision Contributors
        
           Licensed under the Apache License, Version 2.0 (the "License");
           you may not use this file except in compliance with the License.
           You may obtain a copy of the License at
        
               http://www.apache.org/licenses/LICENSE-2.0
        
           Unless required by applicable law or agreed to in writing, software
           distributed under the License is distributed on an "AS IS" BASIS,
           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
           See the License for the specific language governing permissions and
           limitations under the License.
        
Project-URL: Homepage, https://github.com/pygeovision/pygeovision
Project-URL: Documentation, https://docs.pygeovision.ai
Project-URL: Repository, https://github.com/pygeovision/pygeovision
Keywords: geospatial,satellite,remote-sensing,deep-learning,computer-vision,GIS,earth-observation,AI,pygeofetch,geoai,sentinel,landsat
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygeofetch>=0.1.1
Requires-Dist: pystac>=1.9
Requires-Dist: pystac-client>=0.7
Requires-Dist: planetary-computer>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: shapely>=2.0
Requires-Dist: pyproj>=3.6
Requires-Dist: boto3>=1.34
Requires-Dist: tenacity>=8.2
Requires-Dist: pydantic>=2.0
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28
Requires-Dist: numpy>=1.24
Requires-Dist: rich>=13.0
Requires-Dist: tqdm>=4.66
Provides-Extra: geoai
Requires-Dist: geoai-py>=0.39.0; extra == "geoai"
Provides-Extra: extra
Requires-Dist: geoai-py[extra]; extra == "extra"
Provides-Extra: geo
Requires-Dist: rasterio>=1.3; extra == "geo"
Requires-Dist: geopandas>=1.0; extra == "geo"
Requires-Dist: rioxarray>=0.15; extra == "geo"
Requires-Dist: pyogrio>=0.7; extra == "geo"
Provides-Extra: ai
Requires-Dist: torch>=2.0; extra == "ai"
Requires-Dist: torchvision>=0.15; extra == "ai"
Requires-Dist: timm>=0.9; extra == "ai"
Requires-Dist: transformers>=4.30; extra == "ai"
Requires-Dist: segmentation-models-pytorch>=0.3; extra == "ai"
Requires-Dist: albumentations>=1.3; extra == "ai"
Requires-Dist: scikit-learn>=1.3; extra == "ai"
Requires-Dist: Pillow>=9.0; extra == "ai"
Requires-Dist: rasterio>=1.3; extra == "ai"
Requires-Dist: pyproj>=3.5; extra == "ai"
Requires-Dist: shapely>=2.0; extra == "ai"
Provides-Extra: labelers
Requires-Dist: pygeovision[geo]; extra == "labelers"
Requires-Dist: requests>=2.28; extra == "labelers"
Provides-Extra: foundation
Requires-Dist: pygeovision[ai]; extra == "foundation"
Requires-Dist: open-clip-torch>=2.20; extra == "foundation"
Requires-Dist: huggingface-hub>=0.18; extra == "foundation"
Provides-Extra: mlflow
Requires-Dist: mlflow>=2.8; extra == "mlflow"
Provides-Extra: wandb
Requires-Dist: wandb>=0.16; extra == "wandb"
Provides-Extra: labelstudio
Requires-Dist: label-studio-sdk>=0.8; extra == "labelstudio"
Provides-Extra: onnx
Requires-Dist: onnx>=1.14; extra == "onnx"
Requires-Dist: onnxruntime>=1.16; extra == "onnx"
Provides-Extra: all
Requires-Dist: pygeovision[extra,foundation,geo,geoai,labelstudio,mlflow,onnx,wandb]; extra == "all"
Provides-Extra: dev
Requires-Dist: pygeovision[all]; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: ipython>=8.0; extra == "dev"
Requires-Dist: jupyter>=1.0; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: responses>=0.25; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="https://appiahkubis14.github.io/portfolio/logo/samuel_logo_dark.svg" alt="PyGeoVision Logo" width="200"/>

# PyGeoVision

[![image](https://img.shields.io/pypi/v/pygeovision.svg)](https://pypi.python.org/pypi/pygeovision)
[![image](https://img.shields.io/pypi/l/pygeovision.svg)](https://pypi.python.org/pypi/pygeovision)
[![image](https://img.shields.io/pypi/pyversions/pygeovision.svg)](https://pypi.python.org/pypi/pygeovision)
[![Tests](https://img.shields.io/badge/Tests-208_passing-22c55e?style=flat-square&logo=pytest&logoColor=white)](https://appiahkubis14.github.io/pygeovision-docs/)
[![PyGeoFetch](https://img.shields.io/badge/PyGeoFetch-22_providers-f59e0b?style=flat-square)](https://appiahkubis14.github.io/pygeofetch-docs/)
[![GeoAI](https://img.shields.io/badge/GeoAI-24_subsystems-a855f7?style=flat-square)](https://opengeoai.org)
[![DOI](https://img.shields.io/badge/DOI-10.21105%2Fjoss.09605-blue)](https://doi.org/10.21105/joss.09605)

**A production-ready Python platform unifying satellite data acquisition and geospatial AI —  
bridging [PyGeoFetch](https://appiahkubis14.github.io/pygeofetch-docs/) (22+ providers) and [GeoAI](https://opengeoai.org) (full AI stack) in one coherent API.**

</div>

---

## 📖 Introduction

PyGeoVision is a **world-class geospatial AI platform** that brings together two exceptional open-source packages under a single, unified API. It delegates all satellite data operations to [PyGeoFetch](https://github.com/appiahkubis14/PyGeoFetch) — providing access to 22+ providers including Sentinel, Landsat, Planet, Maxar, Copernicus, USGS, and more — and all AI operations to [GeoAI](https://opengeoai.org), exposing its full 24-subsystem stack covering segmentation, detection, classification, change detection, SAM, foundation models, embeddings, cloud masking, super-resolution, and ONNX export.

PyGeoVision's design principle is **integration, not reimplementation**. It is the bridge layer that makes PyGeoFetch and GeoAI work seamlessly together, adding 10 end-to-end pipelines, a full CLI, experiment tracking, distributed training, automated labeling, and YAML pipeline orchestration on top.

The package provides six core capabilities:

1. Authenticated search and download of satellite imagery from 22+ providers with caching, parallel downloads, and post-processing chains.
2. End-to-end pipelines that wire PyGeoFetch data directly into GeoAI inference with a single function call.
3. A complete AI training stack with 14 model architectures, 6 specialist losses, and distributed GPU support.
4. Automated dataset labeling from 7 sources including OSM, Microsoft, Google, ESA WorldCover, SAM, and foundation models.
5. A full CLI (`pygeovision`) covering data, AI, pipelines, and model management.
6. YAML pipeline orchestration for scheduled, repeatable geospatial workflows.

---

## 📝 Statement of Need

Applying AI to geospatial data requires navigating fragmented ecosystems — separate tools for data acquisition, preprocessing, model training, and inference — leading to steep learning curves, brittle pipelines, and reproducibility challenges. Existing packages like TorchGeo and TerraTorch provide excellent foundational tools but leave the data acquisition layer largely unsolved. PyGeoFetch addresses data acquisition comprehensively, and GeoAI addresses the AI layer comprehensively, but combining them into production workflows requires significant integration work.

PyGeoVision fills this gap by providing a unified, high-level interface that:

- Gives **geospatial researchers** a single import to go from satellite search to AI inference.
- Gives **AI practitioners** streamlined access to 22 satellite data providers without managing APIs, authentication, and file formats manually.
- Gives **organizations** a production-ready platform with CLI tooling, YAML pipelines, scheduling, and experiment tracking.

With 10 built-in end-to-end pipelines covering building footprints, change detection, land cover, water bodies, solar detection, crop monitoring, disaster assessment, deforestation, urban growth, and carbon estimation, PyGeoVision dramatically reduces the time from raw satellite imagery to actionable geospatial intelligence.

---

## Citations

If you find PyGeoVision useful in your research, please consider citing the following works:

```bibtex
@article{Wu2026geoai,
  author  = {Wu, Qiusheng},
  title   = {GeoAI: A Python package for integrating artificial intelligence with geospatial data analysis and visualization},
  journal = {Journal of Open Source Software},
  year    = {2026},
  volume  = {11},
  number  = {118},
  pages   = {9605},
  doi     = {10.21105/joss.09605}
}
```

---

## 🚀 Key Features

### 🛰️ Satellite Data — 22 Providers via PyGeoFetch
- Unified search and download across Sentinel, Landsat, Planet, Maxar, Airbus, USGS, Copernicus, NASA, JAXA, and more
- Secure credential management via system keyring (API keys, OAuth2, user/password)
- Parallel downloads with checksum verification, resume support, and bandwidth throttling
- Post-processing chains: unzip → reproject → compress → NDVI/NDWI → Cloud Optimized GeoTIFF
- YAML pipeline orchestration with cron scheduling

### 🤖 AI Inference — 24 Subsystems via GeoAI
- Segmentation: buildings, solar panels, agriculture fields, water bodies, custom models
- Detection: cars, ships, parking spots, natural-language grounded detection (GroundedSAM), RF-DETR
- Classification: scene classification, CLIP zero-shot land cover, batch inference
- Change detection: ChangeSTAR bi-temporal change detection
- Foundation models: NASA Prithvi, SAM, DINOv3, Tessera satellite embeddings
- Cloud masking, super-resolution (ESRGAN), ONNX export, canopy height estimation

### ⚙️ End-to-End Pipelines (10)
| Pipeline | Description |
|----------|-------------|
| `building_footprints` | Sentinel-2 / NAIP → GeoAI BuildingFootprintExtractor → GeoJSON |
| `change_detection` | Bi-temporal Sentinel-2 → ChangeSTAR → change mask |
| `land_cover` | Sentinel-2 → SegFormer / ESA WorldCover → classification map |
| `water_bodies` | Sentinel-2 → NDWI segmentation → water polygons |
| `solar_detection` | NAIP / Sentinel-2 → SolarPanelDetector → GeoJSON |
| `crop_monitoring` | Seasonal Sentinel-2 stack → crop type map |
| `disaster_assessment` | Post-event imagery → Siamese-UNet → damage assessment |
| `deforestation` | Bi-temporal Landsat/S2 → ChangeFormer → forest loss mask |
| `urban_growth` | Bi-temporal Landsat → Siamese-UNet → urban expansion map |
| `carbon_estimation` | Sentinel-2 NDVI → AGB formula → carbon stock estimate |

### 🧠 Own AI Training Stack
- 14 model architectures: U-Net, SegFormer, DeepLabV3+, FCOS, RetinaNet, ViT, ChangeFormer, ESRGAN, and more
- GeoTrainer with 6 specialist losses (Dice, Focal, Tversky, Unified Focal, Weighted CE, Change Detection)
- Distributed multi-GPU training, mixed precision, gradient accumulation
- TiledInference with Gaussian blending for large-scene inference
- ExperimentTracker and DriftDetector for production monitoring

### 🏷️ Automated Labeling (7 Sources)
OpenStreetMap · Microsoft Global Buildings · Google Open Buildings · ESA WorldCover · Google Dynamic World · SAM auto-labeling · Foundation model labeling

---

## 📦 Installation

```bash
# Core
pip install pygeovision

# + Full GeoAI stack (PyTorch, transformers, SMP, torchgeo, timm)
pip install "pygeovision[geoai]"

# + Raster/vector processing (rasterio, geopandas, rioxarray)
pip install "pygeovision[geo]"

# + Everything
pip install "pygeovision[all]"
```

**Requirements:** Python 3.10+ · `pip install pygeofetch` · `pip install geoai-py`

---

## ⚡ Quick Start

```python
import pygeovision as pgv

client = pgv.PyGeoVision()

# Search satellite imagery
results = client.search(
    bbox=(-0.15, 51.47, -0.10, 51.52),
    date_range=("2024-06-01", "2024-06-30"),
    providers=["planetary_computer"],
    collections=["sentinel-2-l2a"],
    cloud_cover_max=10,
)

# Download with post-processing
downloads = client.download(results[:3], output_dir="./data/", post_process=["unzip", "cog"])

# AI inference
client.geoai.segment.buildings(
    downloads[0].path,
    output_vector="buildings.geojson",
)

# Or run an end-to-end pipeline in one call
result = client.pipeline(
    "building_footprints",
    bbox=(-0.15, 51.47, -0.10, 51.52),
    date="2024-06",
    output_dir="./results/",
)
print(result.stats)  # {"buildings_detected": 1847, "coverage_pct": 0.312}
```

---

## 📋 Documentation

Comprehensive documentation is available at **https://appiahkubis14.github.io/pygeovision-docs/**, including:

- Full API reference
- Tutorials and example notebooks
- Pipeline configuration guides
- Contributing guide

---

## 🤝 Contributing

Contributions of all kinds are welcome. See our [contributing guide](CONTRIBUTING.md) for ways to get started.

---

## 📄 License

PyGeoVision is free and open source software, licensed under the [Apache 2.0 License](LICENSE).

---

## Acknowledgements

PyGeoVision is built on top of two exceptional open-source projects:

- **[PyGeoFetch](https://appiahkubis14.github.io/pygeofetch-docs/)** — Universal satellite data pipeline. PyGeoVision delegates all data search, download, authentication, caching, and pipeline orchestration to PyGeoFetch.

- **[GeoAI](https://opengeoai.org)** — Artificial Intelligence for Geospatial Data by [Qiusheng Wu](https://github.com/giswqs) and contributors. PyGeoVision wraps GeoAI for all AI inference, training, and model management. Published in [JOSS 2026](https://doi.org/10.21105/joss.09605).
