satellite-tiler 0.4.0
A Python library for accessing open-source satellite imagery from AWS with AI agent CLI
Requires Python: >=3
Keywords: satellite, imagery, tiles, landsat, sentinel, cbers, geospatial, remote-sensing

# satellite-tiler

A Python library for accessing open-source satellite imagery from AWS with an AI-powered CLI for natural language analysis.

[![PyPI](https://img.shields.io/pypi/v/satellite-tiler.svg)](https://pypi.org/project/satellite-tiler/)
[![Python](https://img.shields.io/pypi/pyversions/satellite-tiler.svg)](https://pypi.org/project/satellite-tiler/)

## Features

- **Multi-platform support**: Landsat 8/9, Sentinel-2, CBERS-4
- **AI-powered CLI**: Natural language queries powered by Claude Opus 4.5
- **Urban analysis tools**: Heat islands, vegetation health, land classification, change detection
- **Agent-ready tools**: JSON-serializable outputs for AI frameworks (Strands, LangChain)
- **Discovery-first workflow**: Find what's available before fetching
- **Real COG access**: Efficient HTTP range requests to Cloud-Optimized GeoTIFFs
- **AWS Lambda compatible**: Works with IAM roles, no credential files needed

## Installation

```bash
pip install satellite-tiler
```

This installs everything including the `satellite-agent` CLI.

## Quick Start - CLI

```bash
# Start interactive session
satellite-agent

# Single query
satellite-agent -q "Find heat islands in Dubai"

# Set a default location
satellite-agent -l "25.27,55.30" -q "Analyze vegetation health"

# List available tools
satellite-agent --list-tools
```

## Example Queries

- "What satellite data is available for Brisbane?"
- "Find heat islands in Abu Dhabi and suggest cooling strategies"
- "Analyze vegetation health in Central Park, New York"
- "Compare land use changes in Singapore between 2020 and 2024"
- "What's the flood risk in this area?"

---

## Python API

```python
from satellite_tiler import discover, list_scenes, get_tile, SatellitePlatform
from satellite_tiler.tiles import set_scene_asset_urls

# 1. Discover available missions at a location
missions = discover(lat=-27.47, lon=153.02)
print(f"Available: {[m.platform.value for m in missions]}")

# 2. List recent scenes with low cloud cover
scenes = list_scenes(
    lat=-27.47, lon=153.02,
    platform=SatellitePlatform.SENTINEL2,
    max_cloud_cover=20,
    limit=5
)

# 3. Fetch a tile
scene = scenes[0]
set_scene_asset_urls(scene.scene_id, scene.asset_urls)

result = get_tile(
    scene_id=scene.scene_id,
    lat=-27.47,
    lon=153.02,
    zoom=12,
    bands=["B04", "B03", "B02"]  # RGB
)

# 4. Save as PNG
from satellite_tiler.encoding import encode
with open("tile.png", "wb") as f:
    f.write(encode(result.data, format="png"))
```

---

## Urban Analysis Tools

The `urban_tools` module provides specialized analysis functions:

## Heat Island Detection

Requires Landsat imagery (has thermal bands).

```python
from satellite_tiler.urban_tools import analyze_urban_heat

result = analyze_urban_heat(
    scene_id="LC08_...",
    lat=25.27,
    lon=55.30,
    zoom=12
)
# Returns:
# {
#     "temperature_stats": {"min_c": 20.1, "max_c": 35.6, "mean_c": 25.5},
#     "heat_islands": [...],
#     "heat_island_coverage_percent": 28.3,
#     "recommendations": ["Consider urban greening initiatives..."]
# }
```

## Vegetation Health (NDVI)

```python
from satellite_tiler.urban_tools import analyze_vegetation_health

result = analyze_vegetation_health(
    scene_id="S2B_...",
    lat=-27.47,
    lon=153.02,
    zoom=12
)
# Returns:
# {
#     "ndvi_stats": {"min": -0.2, "max": 0.8, "mean": 0.45},
#     "class_percentages": {"dense_vegetation": 35.2, "moderate_vegetation": 28.1, ...},
#     "health_assessment": "Good"
# }
```

## Land Use Classification

```python
from satellite_tiler.urban_tools import classify_land_use

result = classify_land_use(
    scene_id="S2B_...",
    lat=-27.47,
    lon=153.02,
    zoom=12
)
# Returns:
# {
#     "class_percentages": {"urban": 45.2, "vegetation": 30.1, "water": 5.3, ...},
#     "dominant_class": "urban"
# }
```

## Change Detection

```python
from satellite_tiler.urban_tools import detect_changes

result = detect_changes(
    scene_id_before="S2B_..._2024",
    scene_id_after="S2B_..._2025",
    lat=-27.47,
    lon=153.02,
    change_type="vegetation"  # or "urban"
)
```

## Additional Analysis Tools

- `calculate_spectral_index` - NDVI, NDBI, NDWI, MNDWI, EVI, SAVI
- `analyze_flood_risk_tool` - Flood vulnerability assessment
- `analyze_air_quality_tool` - Air quality proxies from satellite data
- `analyze_green_infrastructure_tool` - Green space analysis
- `analyze_water_bodies_tool` - Water body monitoring
- `detect_buildings_tool` - Built-up area detection
- `analyze_environmental_justice_tool` - Environmental burden indicators
- `get_heat_recommendations` - Cooling intervention suggestions

---

## AI Agent Integration

satellite-tiler is designed for use with AI agent frameworks like AWS Strands Agents, LangChain, and others.

## AWS Strands Agents

```python
from strands import Agent
from satellite_tiler.tools import get_strands_tools
from satellite_tiler.urban_tools import get_geospatial_strands_tools

# Create agent with all satellite tools
agent = Agent(
    system_prompt="You are a satellite imagery analyst.",
    tools=get_strands_tools() + get_geospatial_strands_tools()
)

# Agent can now use satellite tools
response = agent("Find heat islands in Dubai and suggest cooling strategies")
```

## Core Agent Tools

```python
from satellite_tiler.tools import (
    discover_satellite_data,    # Find available missions
    list_satellite_scenes,      # List scenes with filters
    get_satellite_tile,         # Fetch imagery (saves to file)
    get_scene_info,             # Get metadata
    analyze_tile_quality,       # Validate data quality
)
```

## LangChain Integration

```python
from langchain.tools import StructuredTool
from satellite_tiler.tools import discover_satellite_data, list_satellite_scenes

tools = [
    StructuredTool.from_function(
        func=discover_satellite_data,
        name="discover_satellite_data",
        description="Discover available satellite missions at a location"
    ),
    StructuredTool.from_function(
        func=list_satellite_scenes,
        name="list_satellite_scenes", 
        description="List available satellite scenes for a mission"
    ),
]
```

---

## AWS Credentials

This library requires AWS credentials for accessing satellite data (Landsat uses requester-pays buckets).

```bash
# Option 1: Environment variables
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret

# Option 2: AWS credentials file (~/.aws/credentials)

# Option 3: IAM role (automatic on Lambda/EC2)
```

---

## Band Reference

## Landsat 8/9

| Band | Name | Wavelength | Resolution |
|------|------|------------|------------|
| B2 | Blue | 0.45-0.51μm | 30m |
| B3 | Green | 0.53-0.59μm | 30m |
| B4 | Red | 0.64-0.67μm | 30m |
| B5 | NIR | 0.85-0.88μm | 30m |
| B6 | SWIR 1 | 1.57-1.65μm | 30m |
| B7 | SWIR 2 | 2.11-2.29μm | 30m |
| B10 | Thermal | 10.6-11.2μm | 100m |

**Common combinations:**
- True color: `["B4", "B3", "B2"]`
- False color (vegetation): `["B5", "B4", "B3"]`
- Thermal/Heat: `["B10"]`

## Sentinel-2

| Band | Name | Wavelength | Resolution |
|------|------|------------|------------|
| B02 | Blue | 0.46-0.52μm | 10m |
| B03 | Green | 0.54-0.58μm | 10m |
| B04 | Red | 0.65-0.68μm | 10m |
| B08 | NIR | 0.78-0.90μm | 10m |
| B11 | SWIR 1 | 1.57-1.66μm | 20m |
| B12 | SWIR 2 | 2.10-2.28μm | 20m |

**Common combinations:**
- True color: `["B04", "B03", "B02"]`
- False color (vegetation): `["B08", "B04", "B03"]`

**Note:** Sentinel-2 does NOT have thermal bands. Use Landsat for heat analysis.

---

## License

MIT License