Status: actively developed. The core workflow (search → download → preprocess → run a model → assess) is tested, but not everything is equally mature. Project status lists what is partial, optional or deliberately unimplemented, so you know before you rely on it.

Why PyGeoVision

Applying AI to satellite imagery usually means gluing together a data-download library, a preprocessing pipeline, a modelling framework and a pile of custom code. PyGeoVision puts those steps behind one package, so there are fewer joins in the chain for things to quietly break.

• One search/download interface across 22 providers (Sentinel, Landsat, Planet, Maxar, Copernicus, USGS and more) through PyGeoFetch, with credentials stored once in the system keyring.
• Models that run inside the package — segmentation, detection, change detection, classification and foundation-model embeddings — with no separate AI-platform account.
• 40 pipelines from a bounding box to a finished output — 33 run out of the box, 7 run a model you trained.
• A training stack with fine-tuning, geospatial losses and tiled inference for full scenes.
• Object-based image analysis — segmentation, object features, rule/fuzzy/supervised classification and object-level accuracy.
• A CLI and a Python API that cover the same ground.

It is aimed at geospatial researchers who want satellite data and AI in one import, ML practitioners who would rather not hand-roll provider APIs, and teams who need scriptable, schedulable workflows.

✨ Features

📦 Installation

pip install pygeovision                     # core: data search/download + band-math inference
pip install "pygeovision[geo]"              # rasterio, geopandas, rioxarray, ...
pip install "pygeovision[train]"            # PyTorch, timm, segmentation-models-pytorch, albumentations, ...
pip install "pygeovision[foundation]"       # transformers, scikit-learn, umap, faiss (foundation models)
pip install "pygeovision[obia]"             # scikit-image, scikit-learn, rasterio, geopandas (OBIA)
pip install "pygeovision[report]"           # map, vector layers and PDF/Word/Excel reports for every pipeline run
pip install "pygeovision[all]"              # everything except cloud/edge

Other extras: vlm (CLIP), labeling, xai, monitoring, advanced, geo3d, viz, edge (ONNX Runtime), cloud (AWS/Azure/GCP SDKs), dev (tests and linters).

Requirements: Python 3.10+. PyTorch is only needed for training and deep-model inference; search, download, NDWI/NDVI segmentation and the OBIA module work without it.

⚡ Quick start

Search, download, prepare and classify one scene:

import pygeovision as pgv

client = pgv.PyGeoVision()

results = client.search(bbox=(38.6, 8.9, 38.95, 9.15),
                        date_range=("2024-01-01", "2024-04-30"),
                        cloud_cover_max=15)
scene = client.download(results[:1], output_dir="./data",
                        bands=["B02", "B03", "B04", "B08", "B11", "B12"])[0]

ready = client.prepare_for_ai(scene.path, model_type="foundation",
                              output_path="./data/ready.tif")
client.classification.land_cover(ready["output_path"], output_path="./land_cover.tif")

Segmentation, detection and change detection follow the same pattern:

client.segmentation.buildings("scene.tif", output_path="buildings.tif")
client.detection.ships("port.tif", output_path="ships.tif")
client.change.detect("2020.tif", "2024.tif", output_path="change.tif")

client.validator checks rasters and can auto-fix common problems before they reach a model.

🖥️ Command line

Everything above is also available from the shell:

pygeovision data search --bbox -74.1 40.6 -73.7 40.9 --date 2024-06 --satellite sentinel-2
pygeovision data download --bbox -74.1 40.6 -73.7 40.9 --date 2024-06 --output ./data/

pygeovision ai segment buildings --input scene.tif --output buildings.tif
pygeovision ai change --before 2020.tif --after 2024.tif --output change.tif

pygeovision channel list
pygeovision channel building_footprints --bbox -0.15 51.47 -0.10 51.52 --date 2024-06

pygeovision status    # what is installed and working
pygeovision doctor    # diagnose a broken setup

pygeovision --help shows the full tree: data, ai, channel, pipeline (YAML workflows), models, zoo, label, explain, monitor, edge, cloud, vlm, timeseries, validate, preprocess, indices, postprocess, benchmark, datasets, infer and obia.

CLI_TESTING_GUIDE.md has a runnable example for every command, including all 40 pipelines, and says which ones need network access, credentials or your own trained weights. python tools/verify_cli_guide.py runs the offline examples on synthetic data.

🛰️ End-to-end pipelines

The catalogue holds 40 pipelines, all runnable from Python (client.pipeline(name, ...)) and from the CLI (pygeovision channel <name>). pygeovision channel list shows each one and its kind:

• 33 run out of the box. Each is a documented index, terrain product, published reference map or published vector dataset, computed on valid pixels only (cloud- and shadow-masked pixels are nodata, never a class).
• 7 need a model you trained (solar_detection, crop_monitoring, road_extraction, disaster_assessment, deforestation, urban_growth, landslide_detection). PyGeoVision ships no weights for them; without checkpoint= they refuse to run, before downloading any imagery. (building_footprints also takes a checkpoint, but by default it returns Microsoft, Google or OpenStreetMap footprints and needs none.)

Every run also leaves a presentation-ready deliverables folder (needs pip install "pygeovision[report]"):

<out>/deliverables/<pipeline>_report.pdf | .docx | .xlsx   cover, key figures, map, tables, method, limitations, references
<out>/deliverables/maps/*.png                              map (scale bar, north arrow, legend with areas) and charts
<out>/deliverables/vectors/<pipeline>.gpkg                 GeoPackage: aoi + classified polygons + per-class summary
<out>/deliverables/vectors/geojson/ | shapefile/ | kml/    the same layers in other formats
<out>/run_summary.json                                     machine-readable statistics

Areas in the report are measured on the output rasters on the WGS84 ellipsoid and agree with the statistics the pipeline prints. Choose formats with --report-formats pdf,docx,xlsx and --vector-formats gpkg,geojson,shapefile,kml, switch off with --no-report (or PYGEOVISION_REPORT=0), and rebuild from a finished run with pygeovision report <out>. In Python: client.pipeline("flood_mapping", ..., report_formats=["pdf"]) and result.deliverables.

The other 21 of the original 49 stay removed because they could not produce a correct result (untrained networks, placeholder indices, invented constants). Each removal has a documented reason: see removed pipelines.

client.pipeline("wildfire_severity", bbox=bbox, output_dir="out", date_before="2018-10", date_after="2018-12")
client.pipeline("building_footprints", bbox=bbox, output_dir="out", date="2024-06",
                checkpoint="runs/buildings/checkpoints/best.pth")

🧠 Models and training

• 77 registered architectures (pygeovision models list): SegFormer, Mask2Former, DETR/RT-DETR, ChangeFormer, ViT, SAM, CLIP, DINOv2, Prithvi, DOFA and more, plus a 14-model native hub (U-Net, DeepLabV3+, FCOS, RetinaNet, Siamese U-Net, …). 63 registry entries build real models; 14 are explicit placeholders that raise a clear error — see Choosing a model.
• Fine-tuning: start from a checkpoint, freeze the backbone, and train with geospatially aware augmentation; detection training reports real mAP.
• Losses: Dice, Focal, Tversky, Boundary-aware, Lovász, Combo and a geospatial mixed loss; GIoU/DIoU/CIoU/SIoU for boxes.
• Scale: mixed precision, gradient accumulation and distributed multi-GPU training.
• Tiled inference: Gaussian-blended tiles so a model trained on small chips runs on a full scene; ONNX export; ensembling and prediction validation.

🧩 Object-based image analysis (OBIA)

Analyse imagery as objects instead of pixels: segment, describe, classify, assess.

from pygeovision import obia

scene = obia.make_demo_scene()                       # synthetic scene with known truth (offline)
seg   = obia.segment(scene.raster, "multires", scale=20)
feats = obia.extract_features(seg.labels, scene.raster,
                              extra_layers=obia.spectral_layers(scene.raster))
rules = obia.RuleBasedClassifier([("water", "mean_ndwi > 0.3"),
                                  ("bare_field", "mean_ndvi <= 0.55"),
                                  ("cropland", "mean_ndvi > 0.55")])
result = rules.classify(feats)

It includes six segmentation methods (including Baatz & Schäpe-style region merging with a scale parameter — not a clone of eCognition), spectral/shape/GLCM-texture/context features, rule-based, fuzzy and supervised classifiers, and object-level accuracy and segmentation-quality metrics. Try it with pygeovision obia demo ./obia_demo, work through the tutorial scripts in examples/obia/, and see docs/obia for the guide and its limitations.

📌 Project status

Things worth knowing before you build on it:

• Five of the 79 registry entries are placeholders (dinov3_segmentor, changestar-r18, satlas-pretrain, chatearthnet, lisat-7b): they are discoverable but deliberately raise NotImplementedError instead of silently building a different architecture. The other 74 build real networks; pretrained loads need network access (and, for gated repos such as DINOv3, an accepted licence) and raise ModelLoadError rather than falling back to random weights unless you pass allow_random_init=True.
• Everything in the deep-learning layer was verified offline - synthetic rasters, randomly initialised tiny models and stand-ins - never with pretrained weights, a GPU or real scenes. Treat first runs on your data as validation runs.
• YOLO detection needs ultralytics, which is not installed by any extra: pip install ultralytics.
• Pipelines were tested on synthetic rasters with known answers, not on live imagery. Optical pipelines are still limited by clouds, haze and shadow; pick dates in the same season.
• client.detection.ships/cars use a general-purpose (COCO) detector that is not suited to 10 m pixels.
• Inference commands run your own trained network. infer predict|batch, ai infer, ai segment|detect custom and the changeformer|bit|dsamnet methods of ai change require --checkpoint; the registry holds architectures, not trained weights. For change maps from a bounding box use pygeovision channel change_detection.
• Some features download model weights on first use (for example ImageNet or Hugging Face weights); fully offline environments need them cached beforehand.
• Removed from earlier versions: the inference server, enterprise/RBAC layer, SAR/InSAR processing and the planner agent are not part of the package. See the roadmap for the history and the direct replacements.

🧪 Testing

pip install "pygeovision[dev,train,geo,obia]"
pytest tests/

With the full stack installed, the offline suite (tests/test_live.py excluded) runs about 1,300 tests, all of which pass without network access, GPU or pretrained weights. To exercise every CLI command and all 40 pipelines by hand, follow CLI_TESTING_GUIDE.md.

📋 Documentation

Full documentation is at https://pygeovision.readthedocs.io/en/latest/. To build it locally:

pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html

🤝 Contributing

Contributions are welcome — see docs/contributing.md to get started.

📄 License

PyGeoVision is free and open-source software, released under the MIT License.

Acknowledgements

The satellite data layer is built on pygeofetch, a universal satellite data pipeline that handles search, download, authentication, caching and pipeline orchestration. The modelling, training, labeling and OBIA layers are implemented inside PyGeoVision itself.