Dokumentation · Geospatial API
Eine Python-Bibliothek für den Gebrauch durch Agenten.
Die Geospatial API ist eine Entwicklung des Instituts für holistische Technologieforschung GmbH im Forschungsvorhaben zu tokeneffizientem Geoprocessing mit Fehlertoleranz für KI-Agenten. Sie ist nicht Teil der SpatialAgents, lässt sich aber in sie integrieren; im Testaufbau der Benchmarks war sie eingebunden. Diese Seite beschreibt sie.
Zweck
Ein Aufruf statt eines Skripts.
Die Bibliothek fasst Beschaffung, Verarbeitung und Ausgabe von Geodaten in einer Aufrufform zusammen. Wer sie nutzt, beschreibt das Ziel und nicht den Weg dorthin: Vegetationsindex statt Bandarithmetik, Hangneigung statt Nachbarschaftsfenster.
- Deklarativ
- Ein benannter Aufruf ersetzt die Schrittfolge aus Einlesen, Rechnen und Schreiben.
- Verkettbar
- Mehrstufige Abläufe stehen als ein Ausdruck; Zwischenergebnisse bleiben im Speicher.
- Erst zählen
- Zu jedem Download gibt es einen Zähl- und einen Suchaufruf, der die Menge vorab nennt.
- Fehler mit Ausweg
- Eine abgewiesene Eingabe nennt den gültigen Wertebereich und den Aufruf, der stattdessen passt.
Zugang
Forschung des Instituts, Einsatz über die GBD.
Das Institut forscht und entwickelt; Bibliotheken und Plugins stellt es nicht direkt bereit. Wer die Geospatial API mit SpatialAgents einsetzen möchte, wendet sich an die Geoinformatikbüro Dassau GmbH (GBD); sie übernimmt Projekte, Einrichtung, Schulung und Betreuung.
Objekte
Raster, Vektor, Zeitreihe.
Jede Beschaffung liefert eines von drei Objekten zurück. Sie tragen die Daten nicht im Speicher, sondern verweisen auf die Dateien und lesen erst beim Zugriff.
| Objekt | Eigenschaften |
|---|---|
GeospatialRaster | Mehrere Kacheln erscheinen als ein Raster, auch bei unterschiedlichem Bezugssystem und unterschiedlicher Auflösung. Bänder werden über ihren Namen angesprochen, nicht über eine laufende Nummer. |
GeospatialVector | Objektdaten mit verketteten Operationen; die Attributtabelle bleibt zugänglich. |
RasterCollection | Zeitreihe aus Rastern, mit Filtern, Aggregaten und Iteration über die Zeitachse. |
Accessor-Muster
Fachgebiet als Namensraum.
Die Verarbeitung hängt am Objekt, geordnet nach Fachgebiet: spectral für Indizes aus Satellitenbändern, terrain für Ableitungen aus Höhenmodellen, cluster für Punktverdichtung. Der Namensraum sagt, welche Frage beantwortet wird.
ndvi = scene.spectral.ndvi()
slope = dem.terrain.slope()
gruppen = cafes.cluster.dbscan(eps=200, min_samples=3)Mehrstufige Abläufe stehen als ein Ausdruck. Die Kette hält das Zwischenergebnis fest und gibt es am Ende frei:
vegetationsmaske = (scene.pipe
.ndvi()
.focal_median(3)
.threshold(0.5)
.result)Zählen, suchen, laden
Die Menge kennen, bevor sie kommt.
Sieben Kategorien von Objektdaten aus OpenStreetMap — Einrichtungen, Tourismus, Geschäfte, Naturflächen, Straßen, Gewässer und ein allgemeiner Punktaufruf — haben je drei Aufrufe: zählen, suchen, laden.
anzahl = osm.count_amenity("restaurant", place="Basel")
treffer = osm.search_amenity("restaurant", place="Basel")
if treffer.count < 1000:
daten = osm.download_amenity("restaurant", place="Basel")Der Zählaufruf gibt eine Zahl zurück, der Suchaufruf Zahl und Umgebungsangaben, der Ladeaufruf die Daten. Wer zuerst zählt, lädt kein Stadtgebiet herunter, um festzustellen, dass darin zwölf Objekte liegen.
Datenquellen
Neun Quellen, zwei davon mit Schlüssel.
Alle neun Quellen sind öffentlich erreichbar und brauchen keine eigene Infrastruktur. Ein Zugangsschlüssel ist nur für zwei von ihnen nötig: NASA FIRMS gibt ihn kostenfrei aus, Tavily setzt einen voraus.
| Gegenstand | Quelle | Schlüssel |
|---|---|---|
| Objektdaten | OpenStreetMap | nein |
| Satellitenbilder und Höhenmodelle | Microsoft Planetary Computer | nein |
| Wetter | Open-Meteo | nein |
| Feuerherde | NASA FIRMS | ja |
| Deutsche Wetterstationen | Bright Sky, Daten des Deutschen Wetterdienstes | nein |
| Bodeneigenschaften | ISRIC SoilGrids | nein |
| Europäische Statistik | Eurostat | nein |
| Klimaprojektionen | ReKliEs-De, CORDEX, CMIP6 | nein |
| Websuche | Tavily | ja |
Der Planetary Computer trägt unter anderem Sentinel-2 mit 10 bis 60 Metern, Landsat mit 30 Metern, das Copernicus-Höhenmodell mit 30 oder 90 Metern und die Landbedeckung von ESA WorldCover mit 10 Metern. Über die Kachelgrenzen hinweg entsteht daraus ein Raster.
Algorithmen
Dreizehn Kategorien, über hundert Verfahren.
Die Zahlen stammen aus der Übersicht der Bibliothek, Abschnitt Algorithmenkatalog. Wo ein Pluszeichen steht, nennt die Quelle eine Untergrenze.
| Kategorie | Verfahren | Beispiele |
|---|---|---|
| Gelände | 27 | Hangneigung, Exposition, Schummerung, Krümmung, Geländeformen, Erosionsfaktor |
| Hydrologie | 18+ | Fließrichtung, Einzugsgebiete, Gewässerordnung, Höhe über Vorflut, Versickerung |
| Klima und Wärmebelastung | 17 | Hitzeindex, Feuchtkugeltemperatur, Wärmeinsel, Trockenheitsindex, Frost |
| Sichtbarkeit | 11 | Sichtfeld, Himmelsanteil, Sonneneinstrahlung, Horizontwinkel, Funkstrecke |
| Spektralindizes | 6 | Vegetation, Wasser, Bebauung, bodenkorrigierte Vegetation, freie Bandarithmetik |
| Gefahrenindizes | 6 | Sturzflut, Erosion, Grundwasserneubildung, Bau- und Agrareignung |
| Waldbrand | 4 | Ausbreitungsmodell, kanadischer Feuerwetterindex und dessen Komponenten |
| Vektoranalyse | 14+ | Gebäudehöhe, Landschaftsmaße, Erreichbarkeit, Standortoptimierung |
| Räumliche Statistik | 3 | Häufungsanalyse, räumliche Autokorrelation, Punktmusteranalyse |
| Interpolation | 3 | Distanzgewichtung, Kriging, Voronoi-Zerlegung |
| Netzwerke | 4 | Zentralität, Erreichbarkeitszonen, Versorgungsgebiete, Wegsuche |
| Fensterstatistik | 9 | Mittel, Median, Streuung, Extremwerte, Kantenfilter, Perzentil |
| Weitere | — | Veränderungsvergleich, Umklassifizierung, kostengünstigster Weg, Trendanalyse |
Fehlermeldungen
Die Meldung nennt den nächsten Schritt.
Eine Fehlermeldung, die nur das Scheitern feststellt, kostet einen Rateversuch. Die Meldungen der Bibliothek nennen deshalb den Istzustand, die zulässigen Werte und den Aufruf, der zum Ziel führt.
AttributeError: 'OSMApi' has no method 'download_cafes()'.
Hint: Use download_amenity('cafe', place=...)Die zweite Zeile nennt den Aufruf, der das Gewünschte leistet. Ebenso bei einer Bereichsangabe: Die Prüfung läuft vor der Rechnung und benennt die erwartete Reihenfolge.
ValueError: BBox validation failed:
west (7.61) > east (7.57). The format is (west, south, east, north).
Did you swap min/max longitude?Einordnung
Neben GDAL und QGIS-Processing, nicht an deren Stelle.
GDAL bleibt der Weg für Formatumwandlung, Umprojektion und Kachelung; QGIS-Processing bleibt der Weg für die Algorithmen, die in QGIS ohnehin vorliegen. Die Bibliothek setzt darüber an, wo eine Fachfrage sonst zehn Einzelschritte bräuchte.
- GDAL
- Formate, Bezugssysteme, Mosaike. Die Bibliothek nutzt denselben Unterbau und liest über dessen Kachelindex.
- QGIS-Processing
- Der Werkzeugkasten von QGIS, aufrufbar über die Kommandozeile und als Liste über die Bridge lesbar.
- Geospatial API
- Fachfragen in einem Aufruf: Gefahrenindizes, Geländeableitungen, Erreichbarkeit, Zeitreihen.
- Ergebnisweg
- Was die Bibliothek schreibt, ist eine gewöhnliche Datei und wird über die Bridge in QGIS geladen.