The standalone Geospatial AI
platform — satellite to insight

import pygeovision as pgv
from pygeovision.models import get_model
from pygeovision.models.foundation.dinov3 import DINOv3Backbone
from pygeovision.models.foundation.prithvi import PrithviTasks
from pygeovision.inference.tiled import TiledInference
from pygeovision.training.trainer import GeoTrainer

client = pgv.PyGeoVision()
print(client)
# PyGeoVision(v2.0.0 | models=119 | datasets=503 | pygeofetch=optional | geoai=optional)

# ── 1. Own model registry — 119 architectures ────────────────────────────
model = get_model("segformer-b2", num_classes=5, in_channels=6, pretrained=True)

# ── 2. Tiled inference — own stack, no GeoAI ─────────────────────────────
inf    = TiledInference(model, chip_size=512, overlap=64, blend_mode="gaussian")
result = inf.infer("large_scene.tif", "prediction.tif")
# → {n_chips: 24, duration_seconds: 1.1, chips_per_second: 44.7}

# ── 3. DINOv3 — own foundation stack ─────────────────────────────────────
backbone   = DINOv3Backbone("dinov3_vitl16_sat")   # SAT-493M pre-training
embeddings = backbone.extract_embeddings("scene.tif")    # (1, 1024)
features   = backbone.extract_features("scene.tif")      # (H_p, W_p, 1024)
attention  = backbone.get_attention_maps("scene.tif")     # saliency map

# ── 4. Prithvi-EO-2.0 — own foundation stack ─────────────────────────────
tasks      = PrithviTasks("prithvi_eo_2_0")
land_cover = tasks.land_cover("scene.tif", source="sentinel2")
crop_map   = tasks.crop_mapping("scene.tif", source="sentinel2")
flood      = tasks.flood_detection("scene.tif", source="sentinel2")

# ── 5. Auto-label without any manual annotation ──────────────────────────
ms    = client.labeling.microsoft_buildings(bbox=(-0.15,51.47,-0.10,51.52))
fused = client.labeling.pipeline(bbox=(-0.15,51.47,-0.10,51.52),
    sources=[{"type":"microsoft_buildings","weight":1.5},{"type":"osm","weight":1.0}])

# ── 6. GeoTrainer — own training pipeline ────────────────────────────────
from pygeovision.losses.segmentation import GeospatialMixedLoss
from pygeovision.training.callbacks import EarlyStopping, ModelCheckpoint
loss    = GeospatialMixedLoss(weights={"combo":0.5,"boundary":0.3,"ohem":0.2})
trainer = GeoTrainer(model=model, task="segmentation", num_classes=5, epochs=100,
                      learning_rate=6e-5, mixed_precision="bf16", loss_fn=loss)

# ── 7. Serve as REST API ────────────────────────────────────────────────
from pygeovision.serving import InferenceServer
server = InferenceServer(auth_keys={"prod":"SECRET"})
server.register("seg_v1", "model.onnx", task="segmentation", num_classes=5)
server.serve(host="0.0.0.0", port=8080)

# ── 8. Optional: PyGeoFetch satellite data ───────────────────────────────
# pip install pygeofetch
results   = client.search(bbox=(-0.15,51.47,-0.10,51.52),
    date_range=("2024-06-01","2024-06-30"), providers=["planetary_computer"])
downloads = client.download(results[:1], post_process=["cog"])

# ── 9. Optional: GeoAI plugin ────────────────────────────────────────────
# pip install "pygeovision[geoai]"
# ga = client.geoai   # lazy-loads geoai-py on first access
# ga.detect.grounded("aerial.tif", "swimming pools")  # GroundedSAM

from pygeovision.models.foundation.dinov3 import (
    DINOv3Backbone, get_transform, finetune_dinov3, CHMv2Model,
    WEB_MEAN, WEB_STD,     # ImageNet — for LVD-1689M web pre-trained
    SAT_MEAN, SAT_STD,     # Satellite — for SAT-493M pre-trained ← DIFFERENT
)

# get_transform() auto-selects correct stats for the model name
transform = get_transform("dinov3_vitl16_sat")   # satellite stats
transform = get_transform("dinov3_vitl16")        # ImageNet stats

backbone = DINOv3Backbone("dinov3_vitl16_sat")   # 300M, 1024-dim, SAT-493M

# Feature extraction
embeddings = backbone.extract_embeddings("scene.tif")     # (1, 1024) — global CLS
features   = backbone.extract_features("scene.tif")       # (H_p, W_p, 1024) — spatial
attention  = backbone.get_attention_maps("scene.tif")      # saliency map

# Canopy height — DINOv3 CHMv2 (1m global, GEDI calibrated)
chm    = CHMv2Model()
result = chm.predict_canopy_height("sentinel2.tif")  # mean_m, max_m, coverage_pct
biomass= chm.estimate_biomass("sentinel2.tif")         # t DM/ha

# Fine-tuning (task: "segmentation" | "classification")
result = finetune_dinov3(
    model_name="dinov3_vitl16_sat", dataset=my_dataset,
    task="segmentation", num_classes=7, epochs=50,
    learning_rate=1e-5,          # low LR for SAT pre-trained
    mixed_precision=True,         # BF16 — critical for ViT-L
)

from pygeovision.models.foundation.prithvi import (
    Prithvi, PrithviTasks, PrithviMultiTemporal,
    map_bands, normalise_hls, finetune_prithvi,
)

# HLS band order: Blue(B02) Green(B03) Red(B04) NIR(B08) SWIR1(B11) SWIR2(B12)
data_hls  = map_bands(data, source="sentinel2")   # remaps S2 → HLS order
data_norm = normalise_hls(data_hls)               # divides by HLS_SCALE_FACTOR=10000.0

# Task predictions (all auto-apply map_bands + normalise internally)
tasks      = PrithviTasks("prithvi_eo_2_0")
land_cover = tasks.land_cover("sentinel2.tif", source="sentinel2")       # 9 classes
crops      = tasks.crop_mapping("sentinel2.tif", source="sentinel2")     # 10 crops
flood      = tasks.flood_detection("sentinel2.tif", source="sentinel2")  # binary
defor      = tasks.deforestation_detection("sentinel2.tif", source="sentinel2")

# Multi-temporal (4 frames simultaneously — key strength of Prithvi)
mt = PrithviMultiTemporal("prithvi_eo_2_0")
mt.process_time_series(images, dates=dates, source="sentinel2")

# Fine-tuning
result = finetune_prithvi(
    model_name="prithvi_eo_2_0", task="land_cover", num_classes=9,
    epochs=50, learning_rate=5e-5, batch_size=8,  # memory-limited for 600M
    mixed_precision=True,
)

from pygeovision.models import get_model
from pygeovision.training.trainer import GeoTrainer
from pygeovision.training.callbacks import EarlyStopping, ModelCheckpoint
from pygeovision.losses.segmentation import GeospatialMixedLoss
from pygeovision.training.data import GeoSegDataset
from torch.utils.data import DataLoader

model = get_model("segformer-b2", num_classes=5, in_channels=6, pretrained=True)
loss  = GeospatialMixedLoss(weights={"combo":0.40,"boundary":0.40,"ohem":0.20})

trainer = GeoTrainer(
    model           = model,
    task            = "segmentation",
    num_classes     = 5,
    epochs          = 100,
    learning_rate   = 6e-5,         # low LR for transformer fine-tuning
    weight_decay    = 0.01,
    mixed_precision = "bf16",        # BF16 recommended for A100/H100
    loss_fn         = loss,
    callbacks       = [
        EarlyStopping(monitor="val_iou", patience=15, mode="max"),
        ModelCheckpoint("./checkpoints/", monitor="val_iou", save_top_k=3),
    ],
)
train_dl = DataLoader(GeoSegDataset("./chips/train/","./labels/train/"), batch_size=8)
val_dl   = DataLoader(GeoSegDataset("./chips/val/",  "./labels/val/"),   batch_size=8)
history  = trainer.fit(train_dl, val_dl)
print(f"Best val_iou: {history['best_metrics']['val_iou']:.4f}")

from pygeovision.advanced.vlm.clip_geo      import CLIPGeo
from pygeovision.advanced.vlm.moondream_geo import MoondreamGeo

# ── RemoteCLIP (RS5M — 5M remote sensing image-text pairs) ───────────────
clip = CLIPGeo(model_name="remoteclip-l14")

# Zero-shot classification (no fine-tuning needed)
probs = clip.classify("scene.tif", [
    "dense urban area", "tropical rainforest",
    "agricultural cropland", "flooded wetland",
])

# Build FAISS index over large satellite archive (one-time)
clip.build_index("./archive/", "geo_index.faiss")

# Text-to-image retrieval
results = clip.search("flooded agricultural fields near river", top_k=10)
similar = clip.search_by_image("query.tif", top_k=5)

# ── Moondream 2 (1.87B VLM) ──────────────────────────────────────────────
moon    = MoondreamGeo()
caption = moon.caption("scene.tif")
answer  = moon.vqa("scene.tif", "How many buildings are visible?")
change  = moon.describe_change("before.tif", "after.tif")

from pygeovision.monitoring.drift   import DriftDetector
from pygeovision.monitoring.tracker import ModelPerformanceTracker
from pygeovision.monitoring.alerts  import AlertManager

# Drift detection — PSI (Population Stability Index)
detector = DriftDetector(method="psi", threshold_warn=0.1, threshold_critical=0.2)
detector.fit(reference_images)
report  = detector.check(new_images)
# PSI < 0.10: no drift  |  0.10–0.20: warning  |  > 0.20: retrain

# Performance tracking
tracker = ModelPerformanceTracker(metrics=["val_iou","val_f1","throughput_fps"])
tracker.log(epoch=50, metrics={"val_iou":0.843,"val_f1":0.887,"throughput_fps":118})
trend   = tracker.trend("val_iou")   # direction, slope

# Alerts — Slack / email / webhook
alerts = AlertManager(channels={"slack":{"webhook_url":"https://..."}})
alerts.add_rule("iou_drop",  "val_iou",      "less_than",    0.78, "critical")
alerts.add_rule("drift",     "psi_score",    "greater_than", 0.10, "warning")
alerts.add_rule("throughput","fps",           "less_than",    80,   "warning")
alerts.check({"val_iou":0.72})   # fires critical alert

from pygeovision.serving import InferenceServer

server = InferenceServer(
    auth_keys   = {"prod":"SECRET_KEY", "dev":"DEV_KEY"},
    max_workers = 4,
    enable_cors = True,
)
server.register("seg_v1", "model.onnx",    task="segmentation",       num_classes=5)
server.register("chg_v1", "change.onnx",   task="change_detection")
server.register("det_v1", "detector.onnx", task="detection")
server.serve(host="0.0.0.0", port=8080)

# CLI equivalent
# pygeovision serve start --model model.onnx --port 8080 --auth-key SECRET

# Install the optional GeoAI plugin
# pip install "pygeovision[geoai]"  or  pip install geoai-py

ga = client.geoai   # lazy-loads geoai-py only on first attribute access
ga.is_available     # True / False
ga.version          # '0.39.x'

# ── What GeoAI adds beyond PyGeoVision's own stack ─────────────────────

# Tessera pre-computed satellite embeddings (large-scale)
ga.tessera.available_years(bbox=(-74.1,40.6,-73.7,40.9))
ga.tessera.download(bbox=..., output_dir="./tessera/")

# GroundedSAM — DINO + SAM for natural language object detection
ga.detect.grounded("aerial.tif", "swimming pools in backyards")
ga.detect.grounded("aerial.tif", "solar panels on rooftops")

# Leafmap interactive visualisation (Jupyter)
m = ga.map.leafmap()
ga.map.view_raster("prediction.tif")
ga.map.view_vector("buildings.geojson")

# Moondream sliding-window caption over large scene
results = ga.caption.sliding_window("large_scene.tif",
    prompt="Describe the dominant land use.", tile_size=512)

# ── PyGeoVision own equivalents (no GeoAI needed) ────────────────────
# Buildings   → get_model("segformer-b2") + TiledInference
# Change det  → get_model("changeformer")
# DINOv3      → DINOv3Backbone("dinov3_vitl16_sat")
# Prithvi     → PrithviTasks("prithvi_eo_2_0")
# CLIP        → CLIPGeo("remoteclip-l14")
# Moondream   → MoondreamGeo()

# GeoAI plugin segmentation extras (requires pip install "pygeovision[geoai]")
ga.segment.buildings("s2.tif", output_vector="buildings.geojson")  # BuildingFootprintExtractor
ga.segment.solar_panels("aerial.tif", output_vector="solar.geojson")
ga.segment.agriculture_fields("s2.tif", output_vector="fields.geojson")
ga.segment.water("s2.tif", band_order="sentinel2")
ga.segment.with_sam("aerial.tif", output_path="masks.tif")
ga.segment.from_hub("scene.tif", "giswqs/building-footprint-usa")  # HF Hub

ga.detect.cars("aerial.tif",    output_path="cars.geojson")
ga.detect.ships("port.tif",     output_path="ships.geojson")
ga.detect.parking("lot.tif",    output_path="spots.geojson")
ga.detect.grounded("aerial.tif","swimming pools",output_path="pools.geojson")  # GroundedSAM
ga.detect.rfdetr("scene.tif",   output_path="det.geojson")
ga.detect.multiclass("scene.tif","nwpu_model.pth",output_path="det.geojson")

# Tessera pre-computed embeddings
embeddings = ga.embed.patch("sentinel2.tif", chip_size=64)   # (N, 512)
ga.embed.cluster(embeddings, n_clusters=10)
score = ga.embed.similarity(emb_a, emb_b)   # 0.85
ga.embed.visualize(embeddings, method="umap")

# Cloud masking
ga.cloud.predict("sentinel2.tif", output_path="cloud.tif")
stats = ga.cloud.statistics("cloud.tif")   # {"cloud_cover": 0.08}

# Super-resolution (ESRGAN ×4)
ga.sr.enhance("landsat.tif", output_path="enhanced.tif", scale_factor=4)

# Utilities
ga.utils.raster_to_vector("pred.tif","polygons.geojson")
ga.utils.smooth_vector("buildings.geojson","smooth.geojson")
metrics = ga.utils.segmentation_metrics(pred, target)   # mIoU, F1, accuracy
ga.utils.get_device()   # 'cuda' | 'mps' | 'cpu'

# System
pygeovision status
pygeovision doctor

# Own model registry (119 architectures)
pygeovision models list
pygeovision models list --task foundation
pygeovision models list --task segmentation --pretrained-only
pygeovision models info prithvi_eo_2_0
pygeovision models info dinov3_vitl16_sat

# Own inference stack (no satellite credentials needed)
pygeovision ai infer \
  --input large_scene.tif --model segformer-b2 \
  --output prediction.tif --num-classes 5 \
  --tile-size 512 --overlap 64 --precision bf16

# Foundation models (own stack)
pygeovision ai foundation dinov3 \
  --input scene.tif --model dinov3_vitl16_sat \
  --output embeddings.npy

pygeovision ai foundation prithvi \
  --input sentinel2.tif --task land_cover --output lc.tif

# Auto-labeling
pygeovision ai label ms-buildings \
  --bbox "-0.15,51.47,-0.10,51.52" --output labels.tif

# Training
pygeovision ai train segmentation \
  --data ./chips/ --output model.pth \
  --model segformer-b2 --num-classes 5 \
  --epochs 100 --precision bf16

# Serving
pygeovision serve start \
  --model model.onnx --port 8080 --auth-key SECRET
pygeovision serve status
pygeovision serve stop

# E2E pipelines
pygeovision pipeline building_footprints \
  --bbox "-0.15,51.47,-0.10,51.52" \
  --date 2024-06 --output ./results/

pygeovision pipeline change_detection \
  --bbox "-74.1,40.6,-73.7,40.9" \
  --date-before 2020-01 --date-after 2024-01

# Optional: PyGeoFetch satellite data
pygeovision data search \
  --bbox "-74.1,40.6,-73.7,40.9" \
  --date 2024-06 --providers planetary_computer \
  --cloud-max 10 --output results.geojson

pygeovision data download \
  --from-search results.geojson \
  --output ./data/ --parallel 4 \
  --post-process reproject:EPSG:32618,cog

tests/                          580 passing  |  2 skipped  |  0 failing
├── test_core.py                Core config, exceptions, engine init
├── test_data_layer.py          SatelliteFetcher, SearchResult, 22 providers
├── test_geoai_integration.py   GeoAI plugin subsystems (mocked, optional)
├── test_foundation_models.py   DINOv3 + Prithvi (own stack, mocked weights)
├── test_dinov3.py              DINOv3 backbone, transforms, CHMv2
├── test_prithvi.py             Prithvi tasks, band mapping, multi-temporal
├── test_edge_cloud.py          ONNX, Jetson, AWS, Azure, GCP
├── test_advanced.py            Few-shot, AutoML, VLM, timeseries
├── test_monitoring.py          Drift, tracker, alerts
├── test_serving.py             FastAPI endpoints, WebSocket, JWT auth
├── test_training.py            GeoTrainer, losses, metrics, callbacks
├── test_inference.py           TiledInference, ensemble, postprocessing
├── test_labeling.py            All 7 labelers + quality + fusion
├── test_models.py              Model registry, loader, 119 architectures
├── test_datasets.py            Dataset registry, loader, 503 datasets
├── test_pipelines.py           All 10 end-to-end pipelines
├── test_explainability.py      GradCAM, attention maps, uncertainty
├── test_cli.py                 All 15 CLI command groups
├── test_pointcloud.py          PointNet++, RandLA-Net, KPConv
└── conftest.py                 Shared fixtures, mock providers

pip install -e ".[dev]"
pytest tests/ -q                                       # all 580
pytest tests/test_foundation_models.py -v              # own foundation stack
pytest tests/test_models.py -v                         # 119-model registry
pytest tests/test_geoai_integration.py -v              # optional GeoAI plugin
pytest tests/ --cov=pygeovision --cov-report=html      # coverage report