earthforge-raster 0.1.0__tar.gz

earthforge_raster-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude
+.claude/

earthforge_raster-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: earthforge-raster
+Version: 0.1.0
+Summary: EarthForge raster operations: COG info, validation, conversion, preview
+License-Expression: GPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: earthforge-core>=0.1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: rasterio>=1.3
+Description-Content-Type: text/markdown
+
+# earthforge-raster
+
+COG and GeoTIFF operations for EarthForge: info, validation, conversion, preview.
+
+See the [main README](../../README.md) for project documentation.

earthforge_raster-0.1.0/README.md

@@ -0,0 +1,5 @@
+# earthforge-raster
+
+COG and GeoTIFF operations for EarthForge: info, validation, conversion, preview.
+
+See the [main README](../../README.md) for project documentation.

earthforge_raster-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "earthforge-raster"
+version = "0.1.0"
+description = "EarthForge raster operations: COG info, validation, conversion, preview"
+readme = "README.md"
+license = "GPL-3.0-or-later"
+requires-python = ">=3.11"
+dependencies = [
+    "earthforge-core>=0.1.0",
+    "rasterio>=1.3",
+    "numpy>=1.24",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/earthforge"]

earthforge_raster-0.1.0/src/earthforge/raster/__init__.py

@@ -0,0 +1,7 @@
+"""EarthForge raster operations — COG info, validation, conversion, and preview.
+
+This package provides async-first APIs for working with Cloud Optimized GeoTIFFs
+and other raster formats. All I/O goes through ``earthforge.core`` wrappers.
+"""
+
+__version__ = "0.1.0"

earthforge_raster-0.1.0/src/earthforge/raster/convert.py

@@ -0,0 +1,261 @@
+"""GeoTIFF to Cloud-Optimized GeoTIFF (COG) conversion.
+
+Converts plain GeoTIFF files into COG format by applying tiling, compression,
+and overview generation. Uses GDAL's COG driver (via rasterio) for spec-
+compliant output with proper IFD ordering.
+
+Usage::
+
+    from earthforge.raster.convert import convert_to_cog
+
+    result = await convert_to_cog("input.tif", output="output.tif")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from functools import partial
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from earthforge.raster.errors import RasterError
+
+
+class CogConvertResult(BaseModel):
+    """Structured result from a COG conversion.
+
+    Attributes:
+        source: Input file path.
+        output: Output COG file path.
+        width: Raster width in pixels.
+        height: Raster height in pixels.
+        band_count: Number of bands.
+        dtype: Data type of the output.
+        crs: CRS identifier string.
+        compression: Compression codec used.
+        blocksize: Tile size used.
+        overview_levels: Overview decimation levels generated.
+        overview_resampling: Resampling method used for overviews.
+        file_size_bytes: Output file size in bytes.
+    """
+
+    source: str = Field(title="Source")
+    output: str = Field(title="Output")
+    width: int = Field(title="Width")
+    height: int = Field(title="Height")
+    band_count: int = Field(title="Bands")
+    dtype: str = Field(title="Data Type")
+    crs: str | None = Field(default=None, title="CRS")
+    compression: str = Field(title="Compression")
+    blocksize: int = Field(title="Block Size")
+    overview_levels: list[int] = Field(title="Overview Levels")
+    overview_resampling: str = Field(title="Overview Resampling")
+    file_size_bytes: int | None = Field(default=None, title="Size (bytes)")
+
+
+def _compute_overview_levels(width: int, height: int, blocksize: int = 512) -> list[int]:
+    """Compute appropriate overview levels for a raster.
+
+    Generates powers-of-2 overview levels until the smallest overview
+    dimension is roughly one tile or smaller.
+
+    Parameters:
+        width: Raster width in pixels.
+        height: Raster height in pixels.
+        blocksize: Tile size (default: 512).
+
+    Returns:
+        List of overview decimation factors (e.g. ``[2, 4, 8, 16]``).
+    """
+    levels: list[int] = []
+    factor = 2
+    min_dim = min(width, height)
+    while min_dim // factor >= blocksize // 2:
+        levels.append(factor)
+        factor *= 2
+    # Always include at least one level if the raster is large enough
+    if not levels and min_dim > blocksize:
+        levels.append(2)
+    return levels
+
+
+def _convert_to_cog_sync(
+    source: str,
+    *,
+    output: str | None = None,
+    compression: str = "deflate",
+    blocksize: int = 512,
+    resampling: str = "average",
+    overview_levels: list[int] | None = None,
+) -> CogConvertResult:
+    """Convert a GeoTIFF to COG synchronously.
+
+    Parameters:
+        source: Path to the input GeoTIFF.
+        output: Output COG path. If ``None``, appends ``_cog`` to the stem.
+        compression: Compression codec (``"deflate"``, ``"lzw"``, ``"zstd"``).
+        blocksize: Tile size in pixels (default: 512).
+        resampling: Resampling method for overviews (default: ``"average"``).
+        overview_levels: Explicit overview levels. If ``None``, auto-computed.
+
+    Returns:
+        Structured conversion result.
+
+    Raises:
+        RasterError: If the conversion fails.
+    """
+    try:
+        import rasterio
+    except ImportError as exc:
+        raise RasterError(
+            "rasterio is required for COG conversion: pip install earthforge[raster]"
+        ) from exc
+
+    # Read source metadata
+    try:
+        src_ds = rasterio.open(source)
+    except Exception as exc:
+        raise RasterError(f"Failed to open '{source}': {exc}") from exc
+
+    with src_ds:
+        width = src_ds.width
+        height = src_ds.height
+        band_count = src_ds.count
+        dtype = str(src_ds.dtypes[0])
+        crs_str = str(src_ds.crs) if src_ds.crs else None
+
+    # Compute overview levels
+    if overview_levels is None:
+        overview_levels = _compute_overview_levels(width, height, blocksize)
+
+    # Determine output path
+    if output is None:
+        src_path = Path(source)
+        output = str(src_path.with_stem(f"{src_path.stem}_cog"))
+
+    # Use GDAL's COG driver for spec-compliant output (handles tiling, IFD
+    # ordering, and overview generation in a single pass)
+    try:
+        from osgeo import gdal
+
+        gdal.UseExceptions()
+
+        compression_map = {
+            "deflate": "DEFLATE",
+            "lzw": "LZW",
+            "zstd": "ZSTD",
+            "lzma": "LZMA",
+            "none": "NONE",
+        }
+        gdal_compress = compression_map.get(compression.lower(), compression.upper())
+
+        resampling_map = {
+            "nearest": "NEAREST",
+            "bilinear": "BILINEAR",
+            "cubic": "CUBIC",
+            "average": "AVERAGE",
+            "lanczos": "LANCZOS",
+        }
+        gdal_resamp = resampling_map.get(resampling.lower(), "NEAREST")
+
+        # PREDICTOR=2 (horizontal differencing) improves DEFLATE/LZW compression
+        # by 30-40% for integer/byte imagery — standard COG best practice.
+        # Only applies to lossless codecs; skipped for NONE/ZSTD to avoid
+        # GDAL warnings on unsupported codec+predictor combinations.
+        predictor_codecs = {"DEFLATE", "LZW", "LZMA"}
+        creation_options = [
+            f"COMPRESS={gdal_compress}",
+            f"BLOCKSIZE={blocksize}",
+            f"OVERVIEW_RESAMPLING={gdal_resamp}",
+        ]
+        if gdal_compress in predictor_codecs:
+            creation_options.append("PREDICTOR=2")
+
+        translate_options = gdal.TranslateOptions(
+            format="COG",
+            creationOptions=creation_options,
+        )
+
+        result_ds = gdal.Translate(output, source, options=translate_options)
+        if result_ds is None:
+            raise RasterError("GDAL Translate returned None")
+        result_ds = None  # Close / flush
+
+    except ImportError as exc:
+        raise RasterError(
+            "GDAL is required for COG conversion: install GDAL Python bindings"
+        ) from exc
+    except RasterError:
+        raise
+    except Exception as exc:
+        raise RasterError(f"COG conversion failed: {exc}") from exc
+
+    # Read actual overview levels from the output
+    with rasterio.open(output) as out_ds:
+        overview_levels = out_ds.overviews(1) if out_ds.count > 0 else []
+
+    # Get output file size
+    file_size: int | None = None
+    try:
+        file_size = Path(output).stat().st_size
+    except OSError:
+        pass
+
+    return CogConvertResult(
+        source=source,
+        output=output,
+        width=width,
+        height=height,
+        band_count=band_count,
+        dtype=dtype,
+        crs=crs_str,
+        compression=compression,
+        blocksize=blocksize,
+        overview_levels=overview_levels,
+        overview_resampling=resampling,
+        file_size_bytes=file_size,
+    )
+
+
+async def convert_to_cog(
+    source: str,
+    *,
+    output: str | None = None,
+    compression: str = "deflate",
+    blocksize: int = 512,
+    resampling: str = "average",
+    overview_levels: list[int] | None = None,
+) -> CogConvertResult:
+    """Convert a GeoTIFF to Cloud-Optimized GeoTIFF (COG).
+
+    Applies tiling, compression, and overview generation. The output follows
+    the COG specification with proper IFD ordering (overviews after main image).
+
+    Parameters:
+        source: Path to the input GeoTIFF.
+        output: Output COG path. If ``None``, appends ``_cog`` to the stem.
+        compression: Compression codec (default: ``"deflate"``).
+        blocksize: Tile size in pixels (default: 512).
+        resampling: Resampling for overviews (default: ``"nearest"``).
+        overview_levels: Explicit overview levels. ``None`` auto-computes.
+
+    Returns:
+        Structured conversion result.
+
+    Raises:
+        RasterError: If the conversion fails.
+    """
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(
+        None,
+        partial(
+            _convert_to_cog_sync,
+            source,
+            output=output,
+            compression=compression,
+            blocksize=blocksize,
+            resampling=resampling,
+            overview_levels=overview_levels,
+        ),
+    )

earthforge_raster-0.1.0/src/earthforge/raster/errors.py

@@ -0,0 +1,29 @@
+"""Raster-specific error types."""
+
+from __future__ import annotations
+
+from earthforge.core.errors import EarthForgeError
+
+
+class RasterError(EarthForgeError):
+    """Base exception for raster operations.
+
+    Parameters:
+        message: Human-readable description.
+        exit_code: CLI exit code (defaults to ``10``).
+    """
+
+    def __init__(self, message: str, *, exit_code: int = 10) -> None:
+        super().__init__(message, exit_code=exit_code)
+
+
+class CogValidationError(RasterError):
+    """Raised when a file fails COG compliance checks.
+
+    Parameters:
+        message: Human-readable description of the validation failure.
+        exit_code: CLI exit code (defaults to ``11``).
+    """
+
+    def __init__(self, message: str, *, exit_code: int = 11) -> None:
+        super().__init__(message, exit_code=exit_code)

earthforge_raster-0.1.0/src/earthforge/raster/info.py

@@ -0,0 +1,214 @@
+"""Raster file inspection — COG and GeoTIFF metadata extraction.
+
+Reads raster metadata (dimensions, CRS, bands, data types, tiling, overviews)
+without loading pixel data. For remote files, rasterio uses GDAL's virtual
+filesystem (vsicurl) which issues HTTP range requests automatically.
+
+Usage::
+
+    from earthforge.raster.info import inspect_raster, inspect_raster_sync
+
+    info = await inspect_raster("/path/to/file.tif")
+    print(info.width, info.height, info.crs)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from functools import partial
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from earthforge.raster.errors import RasterError
+
+logger = logging.getLogger(__name__)
+
+
+class BandInfo(BaseModel):
+    """Metadata for a single raster band.
+
+    Attributes:
+        index: 1-based band index.
+        dtype: Data type (e.g. ``"uint8"``, ``"float32"``).
+        nodata: NoData value, or ``None`` if not set.
+        description: Band description, or empty string.
+    """
+
+    index: int = Field(title="Band")
+    dtype: str = Field(title="Data Type")
+    nodata: float | int | None = Field(default=None, title="NoData")
+    description: str = Field(default="", title="Description")
+
+
+class RasterInfo(BaseModel):
+    """Structured metadata for a raster file.
+
+    Attributes:
+        source: The file path or URL that was inspected.
+        driver: GDAL driver name (e.g. ``"GTiff"``).
+        width: Raster width in pixels.
+        height: Raster height in pixels.
+        crs: Coordinate reference system as a string (e.g. ``"EPSG:4326"``).
+        bounds: Bounding box as ``[west, south, east, north]``.
+        transform: Affine transform as a 6-element list.
+        band_count: Number of bands.
+        bands: Per-band metadata.
+        tile_width: Tile width in pixels, or ``None`` if untiled (strip layout).
+        tile_height: Tile height in pixels, or ``None`` if untiled.
+        is_tiled: Whether the raster uses tiled layout.
+        overview_count: Number of overview levels.
+        overview_levels: List of overview decimation factors.
+        compression: Compression method (e.g. ``"deflate"``, ``"lzw"``), or ``None``.
+        interleave: Pixel interleaving (``"band"``, ``"pixel"``), or ``None``.
+    """
+
+    source: str = Field(title="Source")
+    driver: str = Field(title="Driver")
+    width: int = Field(title="Width (px)")
+    height: int = Field(title="Height (px)")
+    crs: str | None = Field(default=None, title="CRS")
+    bounds: list[float] = Field(default_factory=list, title="Bounds")
+    transform: list[float] = Field(default_factory=list, title="Transform")
+    band_count: int = Field(title="Bands")
+    bands: list[BandInfo] = Field(default_factory=list, title="Band Info")
+    tile_width: int | None = Field(default=None, title="Tile Width")
+    tile_height: int | None = Field(default=None, title="Tile Height")
+    is_tiled: bool = Field(default=False, title="Tiled")
+    overview_count: int = Field(default=0, title="Overviews")
+    overview_levels: list[int] = Field(default_factory=list, title="Overview Levels")
+    compression: str | None = Field(default=None, title="Compression")
+    interleave: str | None = Field(default=None, title="Interleave")
+
+
+def _read_raster_info(source: str) -> RasterInfo:
+    """Synchronous implementation that reads raster metadata via rasterio.
+
+    Parameters:
+        source: Local file path or URL (rasterio handles vsicurl for URLs).
+
+    Returns:
+        Structured raster metadata.
+
+    Raises:
+        RasterError: If the file cannot be opened or read.
+    """
+    try:
+        import rasterio
+    except ImportError as exc:
+        raise RasterError(
+            "rasterio is required for raster operations. "
+            "Install it with: pip install earthforge[raster]"
+        ) from exc
+
+    try:
+        with rasterio.open(source) as ds:
+            # Basic dimensions
+            width = ds.width
+            height = ds.height
+            driver = ds.driver
+            band_count = ds.count
+
+            # CRS
+            crs_str: str | None = None
+            if ds.crs is not None:
+                crs_str = str(ds.crs)
+
+            # Bounds as [west, south, east, north]
+            b = ds.bounds
+            bounds = [b.left, b.bottom, b.right, b.top]
+
+            # Affine transform
+            t = ds.transform
+            transform = [t.a, t.b, t.c, t.d, t.e, t.f]
+
+            # Per-band info
+            bands: list[BandInfo] = []
+            for i in range(1, band_count + 1):
+                nodata_val = ds.nodata
+                desc = ds.descriptions[i - 1] or ""
+                bands.append(
+                    BandInfo(
+                        index=i,
+                        dtype=str(ds.dtypes[i - 1]),
+                        nodata=nodata_val,
+                        description=desc,
+                    )
+                )
+
+            # Tiling info from the first IFD
+            profile: dict[str, Any] = ds.profile
+            blockxsize = profile.get("blockxsize", 0)
+            blockysize = profile.get("blockysize", 0)
+            tiled = profile.get("tiled", False)
+            tile_w: int | None = blockxsize if tiled else None
+            tile_h: int | None = blockysize if tiled else None
+
+            # Overviews (from band 1)
+            overviews = ds.overviews(1) if band_count > 0 else []
+
+            # Compression and interleave
+            compression = profile.get("compress")
+            if compression:
+                compression = str(compression).lower()
+            interleave = profile.get("interleave")
+            if interleave:
+                interleave = str(interleave).lower()
+
+    except RasterError:
+        raise
+    except Exception as exc:
+        raise RasterError(f"Failed to read raster metadata from {source!r}: {exc}") from exc
+
+    return RasterInfo(
+        source=source,
+        driver=driver,
+        width=width,
+        height=height,
+        crs=crs_str,
+        bounds=bounds,
+        transform=transform,
+        band_count=band_count,
+        bands=bands,
+        tile_width=tile_w,
+        tile_height=tile_h,
+        is_tiled=tiled,
+        overview_count=len(overviews),
+        overview_levels=overviews,
+        compression=compression,
+        interleave=interleave,
+    )
+
+
+async def inspect_raster(source: str) -> RasterInfo:
+    """Inspect a raster file and return structured metadata.
+
+    Runs rasterio in a thread executor since GDAL I/O is blocking.
+
+    Parameters:
+        source: Local file path or URL.
+
+    Returns:
+        Structured raster metadata.
+
+    Raises:
+        RasterError: If the file cannot be opened or read.
+    """
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, partial(_read_raster_info, source))
+
+
+def inspect_raster_sync(source: str) -> RasterInfo:
+    """Synchronous convenience wrapper for :func:`inspect_raster`.
+
+    Parameters:
+        source: Local file path or URL.
+
+    Returns:
+        Structured raster metadata.
+
+    Raises:
+        RasterError: If the file cannot be opened or read.
+    """
+    return _read_raster_info(source)