tilearray 0.1.0__py3-none-any.whl

tilearray/service/xyz.py

@@ -0,0 +1,145 @@
+"""XYZ (slippy map) tile service implementation."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable
+from typing import Any
+
+from ..types import CRS, BoundingBox, Format, ServiceTypeEnum, TileRequest
+from .base import BaseService, TileGeometry, register_service
+
+
+@register_service(ServiceTypeEnum.XYZ)
+class XYZService(BaseService):
+    """Client for XYZ / slippy-map tile endpoints."""
+
+    inferred_grid_shape: tuple[int, int] | None = None
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        zoom: int,
+        tile_size: int = 256,
+        output_format: Format | None = Format.PNG,
+        crs: CRS | None = CRS.EPSG_4326,
+        **config: Any,
+    ) -> None:
+        super().__init__(base_url, zoom=zoom, tile_size=tile_size, **config)
+        if zoom < 0:
+            raise ValueError("zoom must be non-negative")
+        if tile_size <= 0:
+            raise ValueError("tile_size must be positive")
+        self.url_template = base_url
+        self.zoom = zoom
+        self.tile_size = tile_size
+        self.output_format = output_format or Format.PNG
+        self.native_crs = crs or CRS.EPSG_4326
+
+    @classmethod
+    def from_url(cls, url: str, **config: Any) -> XYZService:
+        zoom = config.get("zoom")
+        if zoom is None:
+            raise ValueError("XYZ services require a zoom level")
+        return cls(url, **config)
+
+    def plan_tiles(
+        self,
+        bbox: BoundingBox,
+        chunk_size: tuple[int, int],
+        **options: object,
+    ) -> Iterable[TileGeometry]:
+        zoom_value = options.get("zoom", self.zoom)
+        tile_size_value = options.get("tile_size", self.tile_size)
+        zoom = int(zoom_value) if isinstance(zoom_value, (int, str)) else self.zoom
+        tile_size = (
+            int(tile_size_value)
+            if isinstance(tile_size_value, (int, str))
+            else self.tile_size
+        )
+        target_crs = options.get("crs", self.native_crs)
+        if not isinstance(target_crs, CRS):
+            target_crs = self.native_crs
+
+        working_bbox = bbox if bbox.crs == CRS.EPSG_4326 else bbox.to_crs(CRS.EPSG_4326)
+        x_min, y_min, x_max, y_max = _tile_range_for_bbox(working_bbox, zoom)
+
+        rows = y_max - y_min + 1
+        cols = x_max - x_min + 1
+        self.inferred_grid_shape = (rows, cols)
+
+        for tile_y in range(y_min, y_max + 1):
+            for tile_x in range(x_min, x_max + 1):
+                tile_bbox = _tile_bounds(tile_x, tile_y, zoom, target_crs)
+                yield TileGeometry(
+                    bbox=tile_bbox,
+                    width=tile_size,
+                    height=tile_size,
+                    crs=target_crs,
+                    tile_x=tile_x,
+                    tile_y=tile_y,
+                    zoom=zoom,
+                )
+
+    def build_tile_request(self, tile: TileGeometry, **options: Any) -> TileRequest:
+        tile_x = _require_tile_index(tile.tile_x, options.get("x"))
+        tile_y = _require_tile_index(tile.tile_y, options.get("y"))
+        zoom = int(
+            options.get("zoom", tile.zoom if tile.zoom is not None else self.zoom)
+        )
+
+        url = self.url_template.format(x=tile_x, y=tile_y, z=zoom)
+        fmt = options.get("output_format") or self.output_format
+        if isinstance(fmt, str):
+            fmt = Format(fmt)
+
+        passthrough = {
+            key: value for key, value in options.items() if key != "output_format"
+        }
+        return self.compose_tile_request(
+            tile,
+            url=url,
+            output_format=fmt,
+            **passthrough,
+        )
+
+
+def _require_tile_index(tile_index: int | None, override: int | None) -> int:
+    value = override if override is not None else tile_index
+    if value is None:
+        raise ValueError("XYZ tile indices are required")
+    return int(value)
+
+
+def _tile_range_for_bbox(bbox: BoundingBox, zoom: int) -> tuple[int, int, int, int]:
+    x_min = _lon_to_tile_x(bbox.min_x, zoom)
+    x_max = _lon_to_tile_x(bbox.max_x, zoom)
+    y_min = _lat_to_tile_y(bbox.max_y, zoom)
+    y_max = _lat_to_tile_y(bbox.min_y, zoom)
+    return x_min, y_min, x_max, y_max
+
+
+def _lon_to_tile_x(lon: float, zoom: int) -> int:
+    scale = 2**zoom
+    return int(math.floor((lon + 180.0) / 360.0 * scale))
+
+
+def _lat_to_tile_y(lat: float, zoom: int) -> int:
+    scale = 2**zoom
+    lat_rad = math.radians(lat)
+    return int(
+        math.floor((1.0 - math.asinh(math.tan(lat_rad)) / math.pi) / 2.0 * scale)
+    )
+
+
+def _tile_bounds(x: int, y: int, zoom: int, crs: CRS) -> BoundingBox:
+    scale = 2**zoom
+    min_x = x / scale * 360.0 - 180.0
+    max_x = (x + 1) / scale * 360.0 - 180.0
+    max_y = math.degrees(math.atan(math.sinh(math.pi * (1 - 2 * y / scale))))
+    min_y = math.degrees(math.atan(math.sinh(math.pi * (1 - 2 * (y + 1) / scale))))
+    bbox = BoundingBox(
+        min_x=min_x, min_y=min_y, max_x=max_x, max_y=max_y, crs=CRS.EPSG_4326
+    )
+    return bbox if crs == CRS.EPSG_4326 else bbox.to_crs(crs)

tilearray/tiles.py

@@ -0,0 +1,142 @@
+"""
+Generic tile fetching functionality for geospatial services.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from pathlib import Path
+
+import numpy as np
+
+from .fetch import (
+    FetchPolicy,
+    FetchProgress,
+    TileFetcher,
+    fetch_tile_with_policy,
+    get_fetcher,
+)
+from .types import BoundingBox, TileRequest, TileResponse
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "FetchPolicy",
+    "TileFetcher",
+    "create_tile_grid",
+    "fetch_tile",
+    "get_fetcher",
+    "save_tile",
+]
+
+
+def fetch_tile(
+    request: TileRequest,
+    *,
+    policy: FetchPolicy | None = None,
+    fetcher: TileFetcher | None = None,
+    progress: FetchProgress | None = None,
+) -> TileResponse:
+    """
+    Fetch a tile from any geospatial service.
+
+    Args:
+        request: Tile request parameters
+        policy: Optional fetch policy (concurrency, retries, rate limits)
+        fetcher: Optional explicit fetcher instance
+
+    Returns:
+        Tile response with data or error information
+    """
+    if fetcher is not None:
+        return fetcher.fetch(request, progress=progress)
+    return fetch_tile_with_policy(request, policy, progress=progress)
+
+
+def save_tile(tile_response: TileResponse, output_path: str | Path) -> bool:
+    """
+    Save tile data to file.
+
+    Args:
+        tile_response: Response from tile request
+        output_path: Path to save the tile
+
+    Returns:
+        True if successful, False otherwise
+    """
+    if not tile_response.success:
+        logger.error(f"Cannot save failed tile: {tile_response.error_message}")
+        return False
+
+    try:
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(output_path, "wb") as f:
+            f.write(tile_response.data)
+
+        logger.debug(f"Saved tile to {output_path}")
+        return True
+
+    except Exception as e:
+        logger.error(f"Failed to save tile to {output_path}: {e}")
+        return False
+
+
+def create_tile_grid(
+    bbox: BoundingBox,
+    tile_size: tuple[int, int],
+    origin: tuple[float, float],
+    resolution: tuple[float, float],
+) -> np.ndarray:
+    """
+    Create a grid of tiles covering the bounding box with the given tile size, origin and resolution.
+
+    Tiles are aligned to a fixed grid anchored at ``origin``. Each tile spans
+    ``tile_size`` pixels at the given ground resolution. When the bounding box
+    is not grid-aligned, the returned tiles extend beyond the bbox so their
+    union fully covers it.
+
+    Args:
+        bbox: Overall bounding box
+        tile_size: Size of each tile in pixels as ``(width, height)``
+        origin: Origin of the grid in the given CRS as ``(x, y)``
+        resolution: Ground resolution as ``(x, y)`` units per pixel
+
+    Returns:
+        ``float64`` array with shape ``(n_rows, n_cols, 4)`` where the last
+        dimension stores ``(min_x, min_y, max_x, max_y)`` for each tile.
+        Rows increase with ``y`` (bottom row first).
+    """
+    tile_width, tile_height = tile_size
+    res_x, res_y = resolution
+    if tile_width <= 0 or tile_height <= 0:
+        raise ValueError("tile_size dimensions must be positive")
+    if res_x <= 0 or res_y <= 0:
+        raise ValueError("resolution values must be positive")
+
+    origin_x, origin_y = origin
+    tile_width_units = tile_width * res_x
+    tile_height_units = tile_height * res_y
+
+    col_min = math.floor((bbox.min_x - origin_x) / tile_width_units)
+    col_max = math.ceil((bbox.max_x - origin_x) / tile_width_units) - 1
+    row_min = math.floor((bbox.min_y - origin_y) / tile_height_units)
+    row_max = math.ceil((bbox.max_y - origin_y) / tile_height_units) - 1
+
+    n_cols = col_max - col_min + 1
+    n_rows = row_max - row_min + 1
+    if n_cols <= 0 or n_rows <= 0:
+        return np.empty((0, 0, 4), dtype=np.float64)
+
+    grid = np.empty((n_rows, n_cols, 4), dtype=np.float64)
+    for row_index, row in enumerate(range(row_min, row_max + 1)):
+        min_y = origin_y + row * tile_height_units
+        max_y = min_y + tile_height_units
+        for col_index, col in enumerate(range(col_min, col_max + 1)):
+            min_x = origin_x + col * tile_width_units
+            max_x = min_x + tile_width_units
+            grid[row_index, col_index] = (min_x, min_y, max_x, max_y)
+
+    return grid

tilearray/types.py

@@ -0,0 +1,235 @@
+"""
+Generic type definitions and models for tile-based geospatial data processing.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel, Field, model_validator
+from pyproj import Transformer
+
+
+class CRS(str, Enum):
+    """Common Coordinate Reference Systems."""
+
+    EPSG_4326 = "EPSG:4326"
+    EPSG_3857 = "EPSG:3857"
+    EPSG_32633 = "EPSG:32633"
+    EPSG_27700 = "EPSG:27700"
+
+    @classmethod
+    def from_string(cls, crs: str) -> "CRS":
+        """Create CRS from string."""
+        if crs.startswith("EPSG:"):
+            return cls(crs)
+        raise ValueError(
+            f"Invalid CRS format: {crs}. Expected string, integer, or CRS enum"
+        )
+
+    @classmethod
+    def from_integer(cls, crs: int) -> "CRS":
+        """Create CRS from integer."""
+        return cls(f"EPSG:{crs}")
+
+    @classmethod
+    def from_epsg(cls, crs: Union[str, int]) -> "CRS":
+        """
+        Create CRS from EPSG code.
+
+        Args:
+            crs: EPSG code as string or integer
+             - string: "EPSG:4326"
+             - integer: 4326
+
+        Returns:
+            CRS enum
+        """
+        return cls.from_string(crs) if isinstance(crs, str) else cls.from_integer(crs)
+
+
+class Format(str, Enum):
+    """Supported output formats."""
+
+    GEOTIFF = "image/tiff"
+    PNG = "image/png"
+    JPEG = "image/jpeg"
+
+
+BBoxTuple = tuple[float, float, float, float]
+
+
+class BoundingBox(BaseModel):
+    """Bounding box representation."""
+
+    min_x: float = Field(..., description="Minimum X coordinate")
+    min_y: float = Field(..., description="Minimum Y coordinate")
+    max_x: float = Field(..., description="Maximum X coordinate")
+    max_y: float = Field(..., description="Maximum Y coordinate")
+    crs: CRS = Field(default=CRS.EPSG_4326, description="Coordinate Reference System")
+
+    @model_validator(mode="after")
+    def validate_coordinates(self) -> "BoundingBox":
+        """Validate that min coordinates are less than max coordinates."""
+        if self.min_x >= self.max_x:
+            raise ValueError("min_x must be less than max_x")
+        if self.min_y >= self.max_y:
+            raise ValueError("min_y must be less than max_y")
+        return self
+
+    @classmethod
+    def from_tuple(
+        cls,
+        bbox: BBoxTuple,
+        crs: Union[CRS, str, int] = CRS.EPSG_4326,
+    ) -> "BoundingBox":
+        """Create BoundingBox from tuple."""
+
+        if isinstance(crs, CRS):
+            target_crs = crs
+        elif isinstance(crs, str):
+            crs_upper = crs.upper()
+            if crs_upper.startswith("EPSG:"):
+                target_crs = CRS.from_string(crs_upper)
+            else:
+                target_crs = CRS.from_integer(int(crs))
+        else:
+            target_crs = CRS.from_integer(crs)
+
+        return cls(
+            min_x=bbox[0], min_y=bbox[1], max_x=bbox[2], max_y=bbox[3], crs=target_crs
+        )
+
+    def intersects(self, other: "BoundingBox") -> bool:
+        """Check if this bounding box intersects with another."""
+        return (
+            self.min_x < other.max_x
+            and self.max_x > other.min_x
+            and self.min_y < other.max_y
+            and self.max_y > other.min_y
+        )
+
+    def to_crs(self, crs: CRS) -> "BoundingBox":
+        """Transform the bounding box to a new CRS."""
+        transformer = Transformer.from_crs(self.crs.value, crs.value, always_xy=True)
+        xmin, ymin = transformer.transform(self.min_x, self.min_y)
+        xmax, ymax = transformer.transform(self.max_x, self.max_y)
+        return BoundingBox(min_x=xmin, min_y=ymin, max_x=xmax, max_y=ymax, crs=crs)
+
+
+class SpatialExtent(BaseModel):
+    """Spatial extent information."""
+
+    bbox: BoundingBox
+    dimensions: Optional[dict[str, Any]] = Field(
+        None, description="Optional dimension details"
+    )
+
+
+class TemporalExtent(BaseModel):
+    """Temporal extent information."""
+
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+
+    @model_validator(mode="after")
+    def validate_temporal_order(self) -> "TemporalExtent":
+        """Validate that end_time is after start_time."""
+        if self.end_time and self.start_time and self.end_time < self.start_time:
+            raise ValueError("end_time must be after start_time")
+        return self
+
+
+class CoverageDescription(BaseModel):
+    """Coverage description from WCS GetCapabilities."""
+
+    identifier: str = Field(..., description="Coverage identifier")
+    title: Optional[str] = None
+    abstract: Optional[str] = None
+    keywords: list[str] = Field(default_factory=list)
+    supported_crs: list[CRS] = Field(default_factory=list)
+    supported_formats: list[Format] = Field(default_factory=list)
+    spatial_extent: Optional[SpatialExtent] = None
+    temporal_extent: Optional[TemporalExtent] = None
+    native_crs: Optional[CRS] = Field(
+        None, description="Native CRS from DescribeCoverage envelope srsName"
+    )
+    axis_labels: dict[str, tuple[str, str]] = Field(
+        default_factory=dict,
+        description="Subsetting axis labels keyed by normalized CRS (e.g. EPSG:3857)",
+    )
+    native_format: Optional[Format] = Field(
+        None, description="Preferred output format from DescribeCoverage nativeFormat"
+    )
+
+
+class ServiceCapabilities(BaseModel):
+    """WCS Service Capabilities."""
+
+    service_title: str
+    service_abstract: Optional[str] = None
+    service_keywords: list[str] = Field(default_factory=list)
+    service_provider: Optional[str] = None
+    service_contact: Optional[str] = None
+    service_url: str
+    version: str = Field(default="2.0.1")
+    supported_versions: list[str] = Field(default_factory=lambda: ["2.0.1", "2.0.0"])
+    supported_operations: list[str] = Field(
+        default_factory=lambda: ["GetCapabilities", "DescribeCoverage", "GetCoverage"]
+    )
+    supported_formats: list[Format] = Field(default_factory=list)
+    supported_crs: list[CRS] = Field(default_factory=list)
+    coverages: list[CoverageDescription] = Field(default_factory=list)
+
+
+class TileRequest(BaseModel):
+    """Generic tile request parameters."""
+
+    url: str
+    params: dict[str, Any]
+    headers: Optional[dict[str, str]] = None
+    timeout: int = 30
+    retries: int = 3
+    output_format: Optional[Format] = None
+    crs: Optional[CRS] = None
+    bbox: Optional[BoundingBox] = None
+    width: Optional[int] = None
+    height: Optional[int] = None
+
+
+class TileResponse(BaseModel):
+    """Response from tile request."""
+
+    data: bytes
+    content_type: str
+    status_code: int
+    headers: dict[str, str]
+    url: str
+    success: bool
+    error_message: Optional[str] = None
+
+
+class WCSResponse(BaseModel):
+    """Represents a WCS response, either successful data or an error."""
+
+    success: bool = Field(
+        ..., description="True if the request was successful, False otherwise"
+    )
+    data: Optional[Any] = Field(
+        None, description="The response data (e.g., image bytes, NetCDF data)"
+    )
+    error_message: Optional[str] = Field(
+        None, description="Error message if the request failed"
+    )
+    status_code: Optional[int] = Field(
+        None, description="HTTP status code of the response"
+    )
+
+
+class ServiceTypeEnum(str, Enum):
+    """Service types."""
+
+    WCS = "WCS"
+    WMS = "WMS"
+    WMTS = "WMTS"
+    XYZ = "XYZ"