GeoAI SDK

Run Azure AI Foundry geospatial models at scale on satellite imagery

What is GeoAI SDK?

GeoAI SDK makes it simple to run geospatial AI models on satellite imagery. Point to your data source, define your area of interest, and let the SDK handle everything else - from data discovery and validation to concurrent processing and result publishing.

Built for Planetary Computer and Azure AI Foundry, with automatic optimization for model endpoints and concurrent request handling.

⚡ Quick Start

import geoai
from azure.identity import DefaultAzureCredential

# 1. Configure your workflow
input_source = geoai.Input(collection="naip")  # Planetary Computer

constraint = geoai.Constraint(
    bbox=[-122.5, 37.5, -122.0, 38.0],  # San Francisco
    datetime="2024-01-01/2024-12-31"
)

output = geoai.Output(
    geocatalog_uri="https://your-geocatalog.com/",
    collection_name="sf-detections",
    credential=DefaultAzureCredential(),
    storage_url="https://youraccount.blob.core.windows.net",
    blob_container="results"
)

# 2. Run object detection
model = geoai.models.EOOS(
    endpoint="https://your-model.inference.ml.azure.com/score",
    credential="your-api-key",
    num_instances=3,           # Optimize for your deployment
    concurrent_per_instance=10  # Max concurrent requests per instance
)

result = await model.run(
    input=input_source,
    constraint=constraint,
    params={"chip_size": 1024, "stride": 800, "threshold": 0.5},
    output=output
)

print(f"✅ Detected {result.detection_count} objects")
print(f"📊 Processed {result.total_chips} chips")
print(f"🔗 View: {result.geocatalog_url}")

That’s it! The SDK handles STAC search, chipping, preprocessing, inference, merging, and publishing.

---

✨ Why GeoAI SDK?

No Infrastructure Management

• ✅ Single machine processing with optimized concurrency

• ✅ Automatic parallelization across model instances

• ✅ Smart resource utilization based on your endpoint configuration

Intelligent Workflow

• 🔍 Discover - Find available models and check compatibility

• 📊 Estimate - Preview job scope before running (chip count, data availability)

• ✅ Validate - Automatic input validation and error checking

• 🚀 Execute - Fully automated 7-step workflow

Key Capabilities

• 🌍 Multi-AOI Support - Process hundreds of locations in one call

• ⚡ Concurrent Processing - 5-30× speedup with configurable parallelism

• 🔄 Result Merging - Automatic NMS for overlapping detections

• 📤 GeoCatalog Integration - Direct STAC item publishing with extent management

---

� Prerequisites

Before using the SDK, you’ll need to set up the following Azure resources:

1. Deploy AI Model in Azure AI Foundry

Deploy an EOOS or MARS model endpoint to run inference:

• Browse models in Azure AI Foundry Model Catalog:

  • EOOS Object Detection

  • MARS Map Generation

• Obtain your endpoint URL (e.g., https://your-model.eastus.inference.ml.azure.com/score)

• Get your API key or configure Azure AD authentication

2. Azure Storage Account

Required for storing imagery and STAC item assets:

• Create an Azure Storage Account

• Create a blob container (e.g., sdk-results)

• Note your storage URL (e.g., https://youraccount.blob.core.windows.net)

3. GeoCatalog

Required for publishing results as STAC items:

• Set up a GeoCatalog instance or use an existing one

• Note your GeoCatalog URI (collections are auto-created)

4. Azure RBAC Roles

Assign the following roles for Azure AD authentication (recommended):

Resource	Required Role	Purpose
Storage Account	Storage Blob Data Contributor	Upload chips and assets
Storage Account	Storage Blob Delegator	Generate SAS tokens with Azure AD
GeoCatalog	Write access to collection	Publish STAC items
Model Endpoint (Azure ML)	AzureML Data Scientist	Call inference endpoint
Model Endpoint (AI Foundry)	Azure AI Developer or Cognitive Services User	Call inference endpoint

Assign roles using Azure CLI:

# Storage roles
az role assignment create --assignee user@contoso.com \
  --role "Storage Blob Data Contributor" \
  --scope /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}

# Model endpoint role (Azure ML example)
az role assignment create --assignee user@contoso.com \
  --role "AzureML Data Scientist" \
  --scope /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.MachineLearningServices/workspaces/{workspace}

5. Environment Variables (Optional)

For convenience, you can set environment variables instead of using Azure AD:

# Storage account key (alternative to Azure AD)
export STORAGE_ACCOUNT_KEY="your-key-here"

# Model API keys (alternative to Azure AD)
export EOOS_API_KEY="your-eoos-key"
export MARS_API_KEY="your-mars-key"

# SDK logging level
export GEOAI_LOG_LEVEL="INFO"  # or DEBUG for detailed logs

For example notebooks: Copy .env.example to .env (in the same directory as the notebooks) and edit with your values. The notebooks will automatically load it.

---

🛠️ Installation

From wheel (download from GitHub Release):

pip install geoai_sdk-0.1.0-py3-none-any.whl

From cloned repo:

pip install tools/geoai-sdk/

For running example notebooks, install with the examples extra:

# From wheel
pip install "geoai_sdk-0.1.0-py3-none-any.whl[examples]"

# From cloned repo
pip install "tools/geoai-sdk[examples]"

For development (includes pytest, linting tools):

pip install "tools/geoai-sdk[dev]"

Requirements:

• Python 3.9+

• Azure credentials (for GeoCatalog publishing)

• Model endpoint (Azure AI Foundry deployment)

---

🎯 How It Works

Automated Workflow Steps

When you call model.run(), the SDK automatically:

1. 🔒 Validation - Verifies input/output configuration, checks model compatibility

2. 🔲 Chip Creation - Divides AOI into processing tiles with configurable size/stride

3. 🔍 STAC Search - Finds matching imagery items with spatial/temporal filtering

4. 📥 Image Fetching - Downloads and preprocesses imagery with multi-tile merging

5. 🤖 Model Inference - Runs predictions with concurrent request batching

6. 🔄 Result Merging - Combines detections with NMS and spatial deduplication

7. 📤 GeoCatalog Publishing - Uploads results as STAC items with imagery assets

---

📚 Key Features

1. Model Discovery

# List all models
models = geoai.models.list()

# Check collection support
collections = geoai.models.EOOS.get_supported_collections()  # ['naip']

2. Validation

Validate before running (optional - auto-runs in estimate/run):

validation = await model.validate_input(
    input=input_source,
    constraint=constraint,
    params={"chip_size": 1024}
)

if not validation.is_valid:
    for error in validation.errors:
        print(f"❌ {error}")

3. Estimation

Preview job scope (includes validation):

estimate = await model.estimate(input_source, constraint, params)

print(f"Chips: {estimate.estimated_chips}")
print(f"STAC items: {estimate.stac_items_found}")

# Per-AOI breakdown for multi-AOI
for aoi in estimate.aoi_estimates:
    print(f"{aoi['aoi_id']}: {aoi['estimated_chips']} chips")

4. Multi-AOI Processing

import geopandas as gpd

gdf = gpd.read_parquet("buildings.parquet")

constraint = geoai.Constraint(
    aois=gdf,
    datetime="2024-01-01/2024-12-31"
)

result = await model.run(input_source, constraint, params, output)
print(f"Processed {result.total_aois} AOIs")

5. Advanced STAC Control

import pystac_client

client = pystac_client.Client.open("https://planetarycomputer.microsoft.com/api/stac/v1")
search = client.search(
    collections=["naip"],
    bbox=[-122.5, 37.5, -122.0, 38.0],
    datetime="2024-01-01/2024-12-31",
    sortby=[{"field": "properties.datetime", "direction": "desc"}],
    limit=10
)

constraint = geoai.Constraint(bbox=[-122.5, 37.5, -122.0, 38.0], stac_search=search)

---

📖 Examples

Object Detection (EOOS)

Detect objects in high-resolution satellite imagery:

import geoai
from azure.identity import DefaultAzureCredential

# Configure input from Planetary Computer
input_source = geoai.Input(collection="naip")

# Define area and time
constraint = geoai.Constraint(
    bbox=[-118.42, 33.938, -118.40, 33.946],  # LAX
    datetime="2020-01-01/2023-12-31"
)

# Configure output
output = geoai.Output(
    geocatalog_uri="https://your-geocatalog.com/",
    collection_name="lax-detections",
    credential=DefaultAzureCredential(),
    storage_url="https://youraccount.blob.core.windows.net",
    blob_container="results"
)

# Run detection
model = geoai.models.EOOS(
    endpoint="https://eoos.inference.ml.azure.com/score",
    credential="your-api-key"
)

result = await model.run(
    input=input_source,
    constraint=constraint,
    params={"chip_size": 1024, "stride": 800, "threshold": 0.5},
    output=output
)

print(f"Detected {result.detection_count} objects")

Building/Road/Railway/Water Detection (MARS)

Extract buildings, roads, railways, and water bodies:

import geoai

# Same input/constraint setup...

# Run MARS
model = geoai.models.MARS(
    endpoint="https://mars.inference.ml.azure.com/score",
    credential="your-api-key"
)

result = await model.run(
    input=input_source,
    constraint=constraint,
    params={
        "chip_size": 1024,
        "stride": 800,
        # Optional: filter specific features.
        # Available: Building, Road, Railway, Water
        # Building and Water are polygons; Road and Railway are lines.
        # "categories": ["Building", "Water"]
    },
    output=output
)

print(f"Detected {result.detection_count} features")

Render a basemap PNG (/map:render)

MARS can rasterize extracted GeoJSON features plus imagery into a styled cartographic basemap PNG via the /map:render endpoint. The render URL is derived automatically from the scoring endpoint.

# Render straight from run() output (georeferenced GeoJSON FeatureCollection)
png_bytes = await model.render_map(
    image="chip.tif",                    # GeoTIFF bytes or path
    geojson=result.merged_results,       # FeatureCollection dict / list / JSON / path
    coordinate_space="geographic",       # "geographic" for run output, "pixel" for raw /score output
    theme="streets",                     # default | dark | standard_oil | streets
    color_map={"Water": "#1a6fb0"},      # optional palette override
)

from pathlib import Path
Path("basemap.png").write_bytes(png_bytes)

print("Supported themes:", model.render_themes)

---

🎓 Learn More

• 📓 Example Notebooks - Interactive Jupyter notebooks with full workflows

  • EOOS Object Detection

  • MARS Map Generation

• 📖 Documentation - Detailed guides and API reference

---

🌟 Supported Models

Model	Task	Collections	Resolution
EOOS	Object Detection	NAIP	0.6m
MARS	Building/Road/Railway/Water Detection + Map Render	NAIP	0.6m

---

🤝 Support

• Homepage: https://aka.ms/geoaisdk

• Documentation: Full Docs

• Repository: GitHub

• Issues: GitHub Issues

---