geomind-ai 1.0.0__py3-none-any.whl

geomind/tools/geocoding.py

@@ -0,0 +1,108 @@
+"""
+Geocoding tools for converting place names to coordinates.
+
+Uses OpenStreetMap's Nominatim service via geopy.
+"""
+
+from typing import Optional
+from geopy.geocoders import Nominatim
+from geopy.extra.rate_limiter import RateLimiter
+
+from ..config import GEOCODER_USER_AGENT, DEFAULT_BUFFER_KM
+
+
+def geocode_location(place_name: str) -> dict:
+    """
+    Convert a place name to geographic coordinates.
+
+    Args:
+        place_name: Name of the location (e.g., "New York", "Paris, France")
+
+    Returns:
+        Dictionary with latitude, longitude, and full address
+
+    Example:
+        >>> geocode_location("Central Park, New York")
+        {'latitude': 40.7828, 'longitude': -73.9653, 'address': '...'}
+    """
+    geolocator = Nominatim(user_agent=GEOCODER_USER_AGENT, timeout=10)
+    geocode = RateLimiter(geolocator.geocode, min_delay_seconds=1)
+
+    location = geocode(place_name)
+
+    if location is None:
+        return {
+            "success": False,
+            "error": f"Could not find location: {place_name}",
+            "latitude": None,
+            "longitude": None,
+            "address": None,
+        }
+
+    return {
+        "success": True,
+        "latitude": location.latitude,
+        "longitude": location.longitude,
+        "address": location.address,
+    }
+
+
+def get_bbox_from_location(place_name: str, buffer_km: Optional[float] = None) -> dict:
+    """
+    Convert a place name to a bounding box suitable for STAC queries.
+
+    Creates a square bounding box centered on the location with the
+    specified buffer distance.
+
+    Args:
+        place_name: Name of the location (e.g., "San Francisco")
+        buffer_km: Buffer distance in kilometers (default: 10km)
+
+    Returns:
+        Dictionary with bbox [min_lon, min_lat, max_lon, max_lat] and center point
+
+    Example:
+        >>> get_bbox_from_location("London", buffer_km=5)
+        {'bbox': [-0.17, 51.46, -0.08, 51.55], 'center': {...}}
+    """
+    if buffer_km is None:
+        buffer_km = DEFAULT_BUFFER_KM
+
+    # Get coordinates
+    location_result = geocode_location(place_name)
+
+    if not location_result["success"]:
+        return {
+            "success": False,
+            "error": location_result["error"],
+            "bbox": None,
+        }
+
+    lat = location_result["latitude"]
+    lon = location_result["longitude"]
+
+    # Calculate approximate degree offset
+    # 1 degree latitude ≈ 111 km
+    # 1 degree longitude ≈ 111 * cos(latitude) km
+    import math
+
+    lat_offset = buffer_km / 111.0
+    lon_offset = buffer_km / (111.0 * math.cos(math.radians(lat)))
+
+    bbox = [
+        lon - lon_offset,  # min_lon (west)
+        lat - lat_offset,  # min_lat (south)
+        lon + lon_offset,  # max_lon (east)
+        lat + lat_offset,  # max_lat (north)
+    ]
+
+    return {
+        "success": True,
+        "bbox": bbox,
+        "center": {
+            "latitude": lat,
+            "longitude": lon,
+        },
+        "address": location_result["address"],
+        "buffer_km": buffer_km,
+    }

geomind/tools/processing.py

@@ -0,0 +1,349 @@
+"""
+Image processing tools for Sentinel-2 data.
+
+Handles loading Zarr data, applying corrections, and creating visualizations.
+"""
+
+from typing import Optional, List
+from pathlib import Path
+import numpy as np
+
+from ..config import (
+    REFLECTANCE_SCALE,
+    REFLECTANCE_OFFSET,
+    OUTPUT_DIR,
+)
+
+
+def _apply_scale_offset(
+    data: np.ndarray,
+    scale: float = REFLECTANCE_SCALE,
+    offset: float = REFLECTANCE_OFFSET,
+    nodata: int = 0,
+) -> np.ndarray:
+    """
+    Apply scale and offset to convert DN to surface reflectance.
+
+    Formula: reflectance = (DN * scale) + offset
+
+    Args:
+        data: Raw digital number values
+        scale: Scale factor (default: 0.0001)
+        offset: Offset value (default: -0.1)
+        nodata: NoData value to mask (default: 0)
+
+    Returns:
+        Surface reflectance values
+    """
+    # Create mask for nodata
+    mask = data == nodata
+
+    # Apply transformation
+    result = (data.astype(np.float32) * scale) + offset
+
+    # Set nodata pixels to NaN
+    result[mask] = np.nan
+
+    return result
+
+
+def _normalize_for_display(
+    data: np.ndarray,
+    percentile_low: float = 2,
+    percentile_high: float = 98,
+) -> np.ndarray:
+    """
+    Normalize data to 0-1 range for display using percentile stretch.
+
+    Args:
+        data: Input array
+        percentile_low: Lower percentile for clipping
+        percentile_high: Upper percentile for clipping
+
+    Returns:
+        Normalized array in 0-1 range
+    """
+    # Get valid (non-NaN) values
+    valid = data[~np.isnan(data)]
+
+    if len(valid) == 0:
+        return np.zeros_like(data)
+
+    # Calculate percentiles
+    low = np.percentile(valid, percentile_low)
+    high = np.percentile(valid, percentile_high)
+
+    # Normalize
+    if high > low:
+        result = (data - low) / (high - low)
+    else:
+        result = np.zeros_like(data)
+
+    # Clip to 0-1
+    result = np.clip(result, 0, 1)
+
+    # Set NaN to 0 for display
+    result = np.nan_to_num(result, nan=0)
+
+    return result
+
+
+def create_rgb_composite(
+    zarr_url: str,
+    output_path: Optional[str] = None,
+    subset_size: Optional[int] = 1000,
+) -> dict:
+    """
+    Create an RGB composite image from Sentinel-2 10m bands.
+
+    Uses B04 (Red), B03 (Green), B02 (Blue) bands.
+
+    Args:
+        zarr_url: URL to the SR_10m Zarr asset
+        output_path: Optional path to save the image
+        subset_size: Size to subset the image (for faster processing)
+
+    Returns:
+        Dictionary with path to saved image and metadata
+    """
+    try:
+        import matplotlib.pyplot as plt
+        import zarr
+
+        # Open the Zarr store
+        # The SR_10m asset contains b02, b03, b04, b08
+        store = zarr.open(zarr_url, mode="r")
+
+        # Read the bands
+        # Note: Band names are lowercase in the Zarr structure
+        red = np.array(store["b04"])
+        green = np.array(store["b03"])
+        blue = np.array(store["b02"])
+
+        # Subset if requested (for faster processing)
+        if subset_size and red.shape[0] > subset_size:
+            # Take center subset
+            h, w = red.shape
+            start_h = (h - subset_size) // 2
+            start_w = (w - subset_size) // 2
+            red = red[start_h : start_h + subset_size, start_w : start_w + subset_size]
+            green = green[
+                start_h : start_h + subset_size, start_w : start_w + subset_size
+            ]
+            blue = blue[
+                start_h : start_h + subset_size, start_w : start_w + subset_size
+            ]
+
+        # Apply scale and offset
+        red = _apply_scale_offset(red)
+        green = _apply_scale_offset(green)
+        blue = _apply_scale_offset(blue)
+
+        # Normalize for display
+        red = _normalize_for_display(red)
+        green = _normalize_for_display(green)
+        blue = _normalize_for_display(blue)
+
+        # Stack into RGB
+        rgb = np.dstack([red, green, blue])
+
+        # Generate output path
+        if output_path is None:
+            output_path = OUTPUT_DIR / f"rgb_composite_{np.random.randint(10000)}.png"
+        else:
+            output_path = Path(output_path)
+
+        # Create figure
+        fig, ax = plt.subplots(figsize=(10, 10))
+        ax.imshow(rgb)
+        ax.set_title("Sentinel-2 RGB Composite (B4/B3/B2)")
+        ax.axis("off")
+
+        # Save
+        plt.savefig(output_path, dpi=150, bbox_inches="tight", pad_inches=0.1)
+        plt.close(fig)
+
+        return {
+            "success": True,
+            "output_path": str(output_path),
+            "image_size": rgb.shape[:2],
+            "bands_used": ["B04 (Red)", "B03 (Green)", "B02 (Blue)"],
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+def calculate_ndvi(
+    zarr_url: str,
+    output_path: Optional[str] = None,
+    subset_size: Optional[int] = 1000,
+) -> dict:
+    """
+    Calculate NDVI (Normalized Difference Vegetation Index) from Sentinel-2 data.
+
+    NDVI = (NIR - Red) / (NIR + Red)
+    Uses B08 (NIR) and B04 (Red) bands.
+
+    Args:
+        zarr_url: URL to the SR_10m Zarr asset
+        output_path: Optional path to save the NDVI image
+        subset_size: Size to subset the image
+
+    Returns:
+        Dictionary with NDVI statistics and output path
+    """
+    try:
+        import zarr
+        import matplotlib.pyplot as plt
+        from matplotlib.colors import LinearSegmentedColormap
+
+        # Open the Zarr store
+        store = zarr.open(zarr_url, mode="r")
+
+        # Read the bands
+        nir = np.array(store["b08"])  # NIR
+        red = np.array(store["b04"])  # Red
+
+        # Subset if requested
+        if subset_size and nir.shape[0] > subset_size:
+            h, w = nir.shape
+            start_h = (h - subset_size) // 2
+            start_w = (w - subset_size) // 2
+            nir = nir[start_h : start_h + subset_size, start_w : start_w + subset_size]
+            red = red[start_h : start_h + subset_size, start_w : start_w + subset_size]
+
+        # Apply scale and offset
+        nir = _apply_scale_offset(nir)
+        red = _apply_scale_offset(red)
+
+        # Calculate NDVI
+        # Avoid division by zero
+        denominator = nir + red
+        denominator[denominator == 0] = np.nan
+
+        ndvi = (nir - red) / denominator
+
+        # NDVI statistics
+        valid_ndvi = ndvi[~np.isnan(ndvi)]
+        stats = {
+            "min": float(np.min(valid_ndvi)) if len(valid_ndvi) > 0 else None,
+            "max": float(np.max(valid_ndvi)) if len(valid_ndvi) > 0 else None,
+            "mean": float(np.mean(valid_ndvi)) if len(valid_ndvi) > 0 else None,
+            "std": float(np.std(valid_ndvi)) if len(valid_ndvi) > 0 else None,
+        }
+
+        # Generate output path
+        if output_path is None:
+            output_path = OUTPUT_DIR / f"ndvi_{np.random.randint(10000)}.png"
+        else:
+            output_path = Path(output_path)
+
+        # Create NDVI colormap (brown -> yellow -> green)
+        colors = ["#8B4513", "#D2691E", "#FFD700", "#ADFF2F", "#228B22", "#006400"]
+        ndvi_cmap = LinearSegmentedColormap.from_list("ndvi", colors)
+
+        # Create figure
+        fig, ax = plt.subplots(figsize=(10, 10))
+        im = ax.imshow(ndvi, cmap=ndvi_cmap, vmin=-1, vmax=1)
+        ax.set_title("NDVI - Normalized Difference Vegetation Index")
+        ax.axis("off")
+
+        # Add colorbar
+        cbar = plt.colorbar(im, ax=ax, shrink=0.8)
+        cbar.set_label("NDVI")
+
+        # Save
+        plt.savefig(output_path, dpi=150, bbox_inches="tight", pad_inches=0.1)
+        plt.close(fig)
+
+        return {
+            "success": True,
+            "output_path": str(output_path),
+            "statistics": stats,
+            "interpretation": _interpret_ndvi(stats["mean"]) if stats["mean"] else None,
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+def _interpret_ndvi(mean_ndvi: float) -> str:
+    """Provide interpretation of mean NDVI value."""
+    if mean_ndvi < 0:
+        return "Water or bare surfaces dominant"
+    elif mean_ndvi < 0.1:
+        return "Bare soil or built-up areas"
+    elif mean_ndvi < 0.2:
+        return "Sparse vegetation or stressed plants"
+    elif mean_ndvi < 0.4:
+        return "Moderate vegetation"
+    elif mean_ndvi < 0.6:
+        return "Dense vegetation"
+    else:
+        return "Very dense/healthy vegetation"
+
+
+def get_band_statistics(
+    zarr_url: str,
+    bands: Optional[List[str]] = None,
+) -> dict:
+    """
+    Get statistics for specified bands from a Sentinel-2 Zarr asset.
+
+    Args:
+        zarr_url: URL to the Zarr asset (e.g., SR_10m)
+        bands: List of band names (default: all available)
+
+    Returns:
+        Dictionary with statistics for each band
+    """
+    try:
+        import zarr
+
+        store = zarr.open(zarr_url, mode="r")
+
+        # Get available bands if not specified
+        if bands is None:
+            bands = [key for key in store.keys() if key.startswith("b")]
+
+        results = {}
+
+        for band in bands:
+            if band not in store:
+                results[band] = {"error": "Band not found"}
+                continue
+
+            data = np.array(store[band])
+
+            # Apply scale/offset
+            data = _apply_scale_offset(data)
+            valid = data[~np.isnan(data)]
+
+            if len(valid) > 0:
+                results[band] = {
+                    "min": float(np.min(valid)),
+                    "max": float(np.max(valid)),
+                    "mean": float(np.mean(valid)),
+                    "std": float(np.std(valid)),
+                    "shape": data.shape,
+                }
+            else:
+                results[band] = {"error": "No valid data"}
+
+        return {
+            "success": True,
+            "band_statistics": results,
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }

geomind/tools/stac_search.py

@@ -0,0 +1,231 @@
+"""
+STAC API search tools for querying Sentinel-2 imagery.
+
+Uses the EOPF STAC API at https://stac.core.eopf.eodc.eu
+"""
+
+from typing import Optional, List
+from datetime import datetime, timedelta
+from pystac_client import Client
+
+from ..config import (
+    STAC_API_URL,
+    STAC_COLLECTION,
+    DEFAULT_MAX_CLOUD_COVER,
+    DEFAULT_MAX_ITEMS,
+)
+
+
+def _get_stac_client() -> Client:
+    """Get a STAC API client instance."""
+    return Client.open(STAC_API_URL)
+
+
+def _format_item(item) -> dict:
+    """Format a STAC item into a simplified dictionary."""
+    props = item.properties
+
+    return {
+        "id": item.id,
+        "datetime": props.get("datetime"),
+        "cloud_cover": props.get("eo:cloud_cover"),
+        "platform": props.get("platform"),
+        "bbox": item.bbox,
+        "geometry": item.geometry,
+        "assets": {
+            key: {
+                "title": asset.title,
+                "href": asset.href,
+                "type": asset.media_type,
+            }
+            for key, asset in item.assets.items()
+            if key in ["SR_10m", "SR_20m", "SR_60m", "TCI_10m", "product"]
+        },
+        "stac_url": f"{STAC_API_URL}/collections/{STAC_COLLECTION}/items/{item.id}",
+    }
+
+
+def search_imagery(
+    bbox: Optional[List[float]] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    max_cloud_cover: Optional[float] = None,
+    max_items: Optional[int] = None,
+) -> dict:
+    """
+    Search for Sentinel-2 L2A imagery in the EOPF STAC catalog.
+
+    Args:
+        bbox: Bounding box [min_lon, min_lat, max_lon, max_lat]
+        start_date: Start date in YYYY-MM-DD format
+        end_date: End date in YYYY-MM-DD format
+        max_cloud_cover: Maximum cloud cover percentage (0-100)
+        max_items: Maximum number of items to return
+
+    Returns:
+        Dictionary with search results including items found
+
+    Example:
+        >>> search_imagery(
+        ...     bbox=[-74.0, 40.7, -73.9, 40.8],
+        ...     start_date="2024-12-01",
+        ...     end_date="2024-12-20",
+        ...     max_cloud_cover=20
+        ... )
+    """
+    if max_cloud_cover is None:
+        max_cloud_cover = DEFAULT_MAX_CLOUD_COVER
+    if max_items is None:
+        max_items = DEFAULT_MAX_ITEMS
+
+    # Build datetime string
+    datetime_str = None
+    if start_date or end_date:
+        start = start_date or "2015-01-01"
+        end = end_date or datetime.now().strftime("%Y-%m-%d")
+        datetime_str = f"{start}/{end}"
+
+    try:
+        client = _get_stac_client()
+
+        # Build search parameters
+        search_params = {
+            "collections": [STAC_COLLECTION],
+            "max_items": max_items,
+        }
+
+        if bbox:
+            search_params["bbox"] = bbox
+
+        if datetime_str:
+            search_params["datetime"] = datetime_str
+
+        # Execute search
+        search = client.search(**search_params)
+        items = list(search.items())
+
+        # Filter by cloud cover (post-filter since API may not support query param)
+        filtered_items = [
+            item
+            for item in items
+            if item.properties.get("eo:cloud_cover", 100) <= max_cloud_cover
+        ]
+
+        # Sort by date (newest first)
+        filtered_items.sort(
+            key=lambda x: x.properties.get("datetime", ""), reverse=True
+        )
+
+        # Format results
+        formatted_items = [_format_item(item) for item in filtered_items]
+
+        return {
+            "success": True,
+            "total_found": len(items),
+            "filtered_count": len(filtered_items),
+            "items": formatted_items,
+            "search_params": {
+                "bbox": bbox,
+                "datetime": datetime_str,
+                "max_cloud_cover": max_cloud_cover,
+            },
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "items": [],
+        }
+
+
+def get_item_details(item_id: str) -> dict:
+    """
+    Get detailed information about a specific STAC item.
+
+    Args:
+        item_id: The STAC item ID (e.g., "S2B_MSIL2A_20251218T110359_...")
+
+    Returns:
+        Dictionary with full item details including all assets
+    """
+    try:
+        # Get the item
+        item_url = f"{STAC_API_URL}/collections/{STAC_COLLECTION}/items/{item_id}"
+
+        import requests
+
+        response = requests.get(item_url)
+        response.raise_for_status()
+        item_data = response.json()
+
+        return {
+            "success": True,
+            "item": item_data,
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+def list_recent_imagery(
+    location_name: Optional[str] = None,
+    days: int = 7,
+    max_cloud_cover: Optional[float] = None,
+    max_items: Optional[int] = None,
+) -> dict:
+    """
+    List recent Sentinel-2 imagery, optionally for a specific location.
+
+    This is a convenience function that combines geocoding and search.
+
+    Args:
+        location_name: Optional place name to search around
+        days: Number of days to look back (default: 7)
+        max_cloud_cover: Maximum cloud cover percentage
+        max_items: Maximum items to return
+
+    Returns:
+        Dictionary with recent imagery items
+    """
+    from .geocoding import get_bbox_from_location
+
+    # Calculate date range
+    end_date = datetime.now()
+    start_date = end_date - timedelta(days=days)
+
+    # Get bbox if location provided
+    bbox = None
+    location_info = None
+
+    if location_name:
+        bbox_result = get_bbox_from_location(location_name)
+        if bbox_result["success"]:
+            bbox = bbox_result["bbox"]
+            location_info = {
+                "name": location_name,
+                "center": bbox_result["center"],
+                "address": bbox_result["address"],
+            }
+        else:
+            return {
+                "success": False,
+                "error": f"Could not geocode location: {location_name}",
+            }
+
+    # Search for imagery
+    result = search_imagery(
+        bbox=bbox,
+        start_date=start_date.strftime("%Y-%m-%d"),
+        end_date=end_date.strftime("%Y-%m-%d"),
+        max_cloud_cover=max_cloud_cover,
+        max_items=max_items,
+    )
+
+    if location_info:
+        result["location"] = location_info
+
+    return result