GeoPakTile 2.1.0__py3-none-any.whl

geopaktile/__init__.py

@@ -0,0 +1,8 @@
+from geopaktile.geopaktile import GeoPakTile as GeoPakTile
+from geopaktile.gpkg_to_cog import gpkg_tiles_to_cog as gpkg_tiles_to_cog
+from geopaktile.xml_parser import get_tile_matrix_set as get_tile_matrix_set
+from geopaktile.xml_parser import parse_capabilities as parse_capabilities
+
+
+def main():
+    print("Command line usage has not been implemented.")

geopaktile/__main__.py

@@ -0,0 +1,4 @@
+from geopaktile import main
+
+if __name__ == "__main__":
+    main()

geopaktile/geopaktile.py

@@ -0,0 +1,463 @@
+import re
+import sqlite3
+import sys
+from collections.abc import Iterable
+from os import PathLike
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+from typing import ClassVar, Literal
+
+import numpy as np
+from morecantile.models import TileMatrixSet
+from pyproj import CRS
+
+_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class GeoPakTile:
+    DEFAULT_PRAGMAS: ClassVar[dict[str, str]] = {
+        "synchronous": "NORMAL",
+        "journal_mode": "WAL",
+        "locking_mode": "EXCLUSIVE",
+    }
+
+    def __init__(
+        self,
+        filepath: str | PathLike,
+        tms: TileMatrixSet = None,
+        table_name: str = "tiles",
+        mode: Literal["ro", "rw", "rwc"] = "ro",
+        pragmas: dict[str, str] | None = None,
+    ):
+        """Create and or write tiles to a geopackage XYZ tile layer.
+
+        A tile matrix set is required in order to get the correct co-ordinates for the tiles and data extents.
+        These are provided by the `morecantile` library, or can be parsed from a WMTS capabilities document using the
+        `pygeopkgxyz.xml_parser.parse_tile_matrix_set` function.
+
+        Args:
+            filepath (str | PathLike): where the geopackage is or should be created
+            tms (TileMatrixSet): Describes the tile coordinates and data extent
+            table_name (str, optional): The name of the tile table/layer. Defaults to "tiles".
+            mode (Literal[ro, rw, rwc], optional): Sqlite3 connection modes. ro = read only, rw is
+                read-write, rwc is read, write or create. Defaults to 'ro' for safety.
+            pragmas (dict[str, str], optional): PRAGMA overrides/additions applied
+                on top of DEFAULT_PRAGMAS after connecting. Pass e.g.
+                {"synchronous": "FULL"} to override a default, or add new keys
+                for pragmas not set by default. Defaults to None (no changes).
+        """
+
+        self.filepath = Path(filepath)
+        self.tms = tms
+        self.table_name = table_name
+
+        self._validate_table_name()
+
+        if mode not in ("ro", "rw", "rwc"):
+            raise ValueError("Mode must be ro, rw or rwc")
+
+        if mode in ["ro", "rw"] and not self.filepath.exists():
+            raise FileNotFoundError("geopackage not found")
+
+        if mode in ["rw", "rwc"] and self.tms is None:
+            raise ValueError(
+                "A TileMatrixSet is required to create or write to a geopackage."
+            )
+
+        self._mode = mode
+        file_string = f"{self.filepath.absolute().as_uri()}?mode={mode}"
+        self._conn = sqlite3.connect(file_string, uri=True)
+        self._cursor = self._conn.cursor()
+        self._apply_pragmas(pragmas)
+
+        # initialize tables if needed and in create mode
+        if mode == "rwc":
+            self._create_tables()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def close(self) -> None:
+        """Close the connection, leaving a single self-contained .gpkg file."""
+        if self._conn is None:
+            return
+        try:
+            if self._mode != "ro":
+                self._conn.commit()
+                 # Default journal mode, prevents WAL file from being left behind and creation by future read operations
+                self._conn.execute("PRAGMA journal_mode=DELETE")
+        finally:
+            self._cursor.close()
+            self._conn.close()
+            self._conn = None
+
+    def has_tile(self, z: int, x: int, y: int):
+        """Check if a tile is present, using the zxy coordinates"""
+
+        self._cursor.execute(
+            f"SELECT EXISTS (SELECT 1 FROM {self.table_name} "
+            "where zoom_level=? and tile_column=? and tile_row=? LIMIT 1)",
+            (z, x, y),
+        )
+
+        row = self._cursor.fetchone()
+        return row[0] == 1
+
+    def has_tiles(self, zxys: list[tuple[int, int, int]] | np.ndarray) -> np.ndarray:
+        """Check many tiles efficiently."""
+
+        requested = np.asarray(zxys, dtype=np.uint64)
+
+        self._cursor.execute(
+            f"SELECT zoom_level, tile_column, tile_row FROM {self.table_name}"
+        )
+        rows = self._cursor.fetchall()
+        existing = (
+            np.array(rows, dtype=np.uint64)
+            if rows
+            else np.empty((0, 3), dtype=np.uint64)
+        )
+
+        # Combine z, x, y into a single array using bit shifting
+        # [ 8 bits unused ][ 8 bits z ][ 28 bits x ][ 28 bits y ]
+        def pack(arr: np.ndarray) -> np.ndarray:
+            z, x, y = arr[:, 0], arr[:, 1], arr[:, 2]
+            return (z << np.uint64(56)) | (x << np.uint64(28)) | y
+
+        req_keys = pack(requested)
+        exist_keys = pack(existing)
+
+        return np.isin(req_keys, exist_keys, assume_unique=False)
+
+    def add_tiles(
+        self,
+        tiles: Iterable[tuple[int, int, int, bytes]],
+        batch_size: int = 1000,
+    ) -> None:
+        """Add tiles to the geopackage
+
+        Args:
+            tiles (Iterable[tuple[int, int, int, bytes]]): List of tiles - [z, x, y, image data in bytes]
+            batch_size (int, optional): Add images in batches for speed. Defaults to 1000.
+        """
+
+        insert_sql = f"""
+            INSERT OR IGNORE INTO "{self.table_name}"
+            (
+                zoom_level,
+                tile_column,
+                tile_row,
+                tile_data
+            )
+            VALUES (?, ?, ?, ?)
+        """
+
+        zs = {t[0] for t in tiles}
+        for z in zs:
+            self._ensure_zoom_level(z)
+
+        batch = []
+        for z, x, y, tile_bytes in tiles:
+            z = int(z)
+            x = int(x)
+            y = int(y)
+
+            if self.has_tile(z, x, y):
+                continue
+
+            batch.append((z, x, y, sqlite3.Binary(tile_bytes)))
+            if len(batch) >= batch_size:
+                self._cursor.executemany(insert_sql, batch)
+                self._conn.commit()
+                batch.clear()
+
+        if batch:
+            self._cursor.executemany(insert_sql, batch)
+            self._conn.commit()
+
+    # Pragmas that need write access; skipped for read-only connections.
+    _WRITE_PRAGMAS: ClassVar[frozenset[str]] = frozenset({"journal_mode", "synchronous"})
+
+    def _apply_pragmas(self, overrides: dict[str, str] | None) -> None:
+        merged = {**self.DEFAULT_PRAGMAS, **(overrides or {})}
+        for name, value in merged.items():
+            if self._mode == "ro" and name in self._WRITE_PRAGMAS:
+                # skip pragmas that require write access when in read-only mode
+                continue
+            if not str(value).replace("_", "").isalnum():
+                # Ensure malicious values aren't parsed.
+                # Passes: "WAL", "NORMAL", "OFF", "EXCLUSIVE", "1000" (a plausible wal_autocheckpoint value)
+                # Blocked: "WAL; DROP TABLE tiles;--", "OFF' OR '1'='1", anything with spaces, quotes, or punctuation
+                raise ValueError(f"Unsafe PRAGMA value for {name!r}: {value!r}")
+            self._cursor.execute(f"PRAGMA {name}={value}")
+
+    def _create_tables(self):
+        """Create the tables for a valid geopackage XYZ layer"""
+
+        self._cursor.execute("PRAGMA application_id = 1196437808")
+        self._cursor.execute("PRAGMA user_version = 10400")
+
+        self._cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS gpkg_spatial_ref_sys (
+                srs_name TEXT NOT NULL,
+                srs_id INTEGER NOT NULL PRIMARY KEY,
+                organization TEXT NOT NULL,
+                organization_coordsys_id INTEGER NOT NULL,
+                definition TEXT NOT NULL,
+                description TEXT
+            )
+            """
+        )
+
+        self._cursor.execute(
+            """
+            INSERT OR IGNORE INTO gpkg_spatial_ref_sys
+            VALUES
+            (
+                'Undefined Cartesian SRS',
+                -1,
+                'NONE',
+                -1,
+                'undefined',
+                'undefined Cartesian coordinate reference system'
+            )
+            """
+        )
+
+        self._cursor.execute(
+            """
+            INSERT OR IGNORE INTO gpkg_spatial_ref_sys
+            VALUES
+            (
+                'Undefined Geographic SRS',
+                0,
+                'NONE',
+                0,
+                'undefined',
+                'undefined geographic coordinate reference system'
+            )
+            """
+        )
+
+        epsg = self.tms.crs.to_epsg()
+        if epsg is None:
+            raise ValueError(
+                f"TileMatrixSet CRS {self.tms.crs} does not have an EPSG code."
+            )
+        crs = CRS.from_epsg(epsg)
+        srs_name = crs.name
+        definition = crs.to_wkt()
+
+        self._cursor.execute(
+            """
+            INSERT OR IGNORE INTO gpkg_spatial_ref_sys
+            (
+                srs_name,
+                srs_id,
+                organization,
+                organization_coordsys_id,
+                definition,
+                description
+            )
+            VALUES (?, ?, 'EPSG', ?, ?, ?)
+            """,
+            (
+                srs_name,
+                epsg,
+                epsg,
+                definition,
+                srs_name,
+            ),
+        )
+
+        self._cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS gpkg_contents (
+                table_name TEXT NOT NULL PRIMARY KEY,
+                data_type TEXT NOT NULL,
+                identifier TEXT UNIQUE,
+                description TEXT DEFAULT '',
+                last_change DATETIME NOT NULL DEFAULT
+                    (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+                min_x DOUBLE,
+                min_y DOUBLE,
+                max_x DOUBLE,
+                max_y DOUBLE,
+                srs_id INTEGER,
+                CONSTRAINT fk_gc_r_srs_id
+                    FOREIGN KEY (srs_id)
+                    REFERENCES gpkg_spatial_ref_sys(srs_id)
+            )
+            """
+        )
+
+        self._cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS gpkg_tile_matrix_set (
+                table_name TEXT NOT NULL PRIMARY KEY,
+                srs_id INTEGER NOT NULL,
+                min_x DOUBLE NOT NULL,
+                min_y DOUBLE NOT NULL,
+                max_x DOUBLE NOT NULL,
+                max_y DOUBLE NOT NULL,
+                CONSTRAINT fk_gtms_table_name
+                    FOREIGN KEY (table_name)
+                    REFERENCES gpkg_contents(table_name),
+                CONSTRAINT fk_gtms_srs
+                    FOREIGN KEY (srs_id)
+                    REFERENCES gpkg_spatial_ref_sys(srs_id)
+            )
+            """
+        )
+
+        self._cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS gpkg_tile_matrix (
+                table_name TEXT NOT NULL,
+                zoom_level INTEGER NOT NULL,
+                matrix_width INTEGER NOT NULL,
+                matrix_height INTEGER NOT NULL,
+                tile_width INTEGER NOT NULL,
+                tile_height INTEGER NOT NULL,
+                pixel_x_size DOUBLE NOT NULL,
+                pixel_y_size DOUBLE NOT NULL,
+                CONSTRAINT pk_ttm PRIMARY KEY (table_name, zoom_level),
+                CONSTRAINT fk_tmm_table_name
+                    FOREIGN KEY (table_name)
+                    REFERENCES gpkg_contents(table_name)
+            )
+            """
+        )
+
+        self._cursor.execute(
+            f"""
+            CREATE TABLE IF NOT EXISTS "{self.table_name}" (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                zoom_level INTEGER NOT NULL,
+                tile_column INTEGER NOT NULL,
+                tile_row INTEGER NOT NULL,
+                tile_data BLOB NOT NULL,
+                UNIQUE (zoom_level, tile_column, tile_row)
+            )
+            """
+        )
+
+        self._cursor.execute(
+            f"""
+            CREATE INDEX IF NOT EXISTS "{self.table_name}_zxy_idx"
+            ON "{self.table_name}" (zoom_level, tile_column, tile_row)
+            """
+        )
+
+        bb = self.tms.xy_bbox
+
+        self._cursor.execute(
+            """
+            INSERT OR REPLACE INTO gpkg_contents
+            (
+                table_name,
+                data_type,
+                identifier,
+                description,
+                min_x,
+                min_y,
+                max_x,
+                max_y,
+                srs_id
+            )
+            VALUES (?, 'tiles', ?, '', ?, ?, ?, ?, ?)
+            """,
+            (
+                self.table_name,
+                self.table_name,
+                bb.left,
+                bb.bottom,
+                bb.right,
+                bb.top,
+                epsg,
+            ),
+        )
+
+        self._cursor.execute(
+            """
+            INSERT OR REPLACE INTO gpkg_tile_matrix_set
+            (
+                table_name,
+                srs_id,
+                min_x,
+                min_y,
+                max_x,
+                max_y
+            )
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            (
+                self.table_name,
+                epsg,
+                bb.left,
+                bb.bottom,
+                bb.right,
+                bb.top,
+            ),
+        )
+
+        self._conn.commit()
+
+    def _ensure_zoom_level(
+        self,
+        z: int,
+    ) -> None:
+        """
+        Add one gpkg_tile_matrix row for a zoom level.
+        """
+
+        tm = self.tms.matrix(z)
+        self._cursor.execute(
+            """
+            INSERT OR IGNORE INTO gpkg_tile_matrix
+            (
+                table_name,
+                zoom_level,
+                matrix_width,
+                matrix_height,
+                tile_width,
+                tile_height,
+                pixel_x_size,
+                pixel_y_size
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                self.table_name,
+                z,
+                tm.matrixWidth,
+                tm.matrixHeight,
+                tm.tileWidth,
+                tm.tileHeight,
+                tm.cellSize,
+                tm.cellSize,
+            ),
+        )
+
+    def _validate_table_name(self) -> None:
+        """Ensure table_name is safe to interpolate into SQL and spec-compliant."""
+        if not _IDENTIFIER_RE.match(self.table_name):
+            raise ValueError(
+                f"Invalid table_name {self.table_name!r}: must match "
+                f"[A-Za-z_][A-Za-z0-9_]* (letters, digits, underscore only, "
+                f"not starting with a digit)."
+            )
+        if self.table_name.lower().startswith("gpkg_"):
+            raise ValueError(
+                f"Invalid table_name {self.table_name!r}: the 'gpkg_' prefix is "
+                f"reserved by the GeoPackage spec."
+            )

geopaktile/gpkg_to_cog.py

@@ -0,0 +1,508 @@
+"""Convert a GeoPackage tile pyramid layer to a Cloud Optimized GeoTIFF.
+
+The highest selected zoom level becomes the full-resolution image and each
+lower zoom level becomes an overview, so the COG keeps the GeoPackage's own
+scales rather than GDAL resampling new overviews.
+
+Requires: numpy, pillow, rasterio (with GDAL >= 3.1 for the COG driver)
+
+How it works:
+    1. The output extent is snapped to the pixel grid of a coarse zoom level
+       so that the finer levels line up with it exactly.
+    2. Each zoom level whose pixel grid lines up with that extent is
+       mosaicked, unresampled, into a temporary GeoTIFF.
+    3. With resample_unaligned=True, coarser levels whose grid doesn't line
+       up are cropped from their own tiles and resampled onto the extent,
+       down to overviews 1 pixel across. A warning lists those levels.
+    4. A VRT lists the base level plus the overview levels as explicit
+       <Overview> elements, and GDAL's COG driver copies it with
+       OVERVIEWS=FORCE_USE_EXISTING.
+"""
+
+from __future__ import annotations
+
+import io
+import math
+import sqlite3
+import tempfile
+import warnings
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+import numpy as np
+import rasterio
+import rasterio.shutil
+from PIL import Image
+from rasterio.crs import CRS
+from rasterio.enums import Resampling
+from rasterio.transform import Affine, from_origin
+from rasterio.warp import reproject, transform_bounds
+from rasterio.windows import Window
+
+SUPPORTED_BANDS = {"RGBA": 4, "RGB": 3}
+COLOR_INTERP = ["Red", "Green", "Blue", "Alpha"]
+_EPS = 1e-6
+_PIXEL_TOL = 1e-3  # how close to a whole pixel counts as "aligned"
+
+
+@dataclass(frozen=True)
+class _Level:
+    zoom: int
+    matrix_width: int
+    matrix_height: int
+    tile_width: int
+    tile_height: int
+    px: float  # pixel width in CRS units
+    py: float  # pixel height in CRS units
+
+
+@dataclass(frozen=True)
+class _Plan:
+    level: _Level
+    width: int
+    height: int
+    col_off: int  # used only when not resampled
+    row_off: int
+    resampled: bool
+
+
+def _quote_ident(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def _is_whole(value: float) -> bool:
+    return abs(value - round(value)) < _PIXEL_TOL
+
+
+def _as_int(value: float, what: str) -> int:
+    """Round to int, warning if the value wasn't (nearly) integral."""
+    if not _is_whole(value):
+        warnings.warn(
+            f"{what} is {value:.4f} pixels, not a whole number; rounding. "
+            "Zoom levels may not be exact multiples of each other.",
+            stacklevel=3,
+        )
+    return round(value)
+
+
+def gpkg_tiles_to_cog(
+    gpkg_path: str | Path,
+    cog_path: str | Path,
+    table: str | None = None,
+    *,
+    bbox: Sequence[float] | None = None,
+    bbox_crs: str | CRS | None = None,
+    min_zoom: int | None = None,
+    max_zoom: int | None = None,
+    resample_unaligned: bool = False,
+    resampling: str = "bilinear",
+    bands: str = "RGBA",
+    compress: str = "DEFLATE",
+    blocksize: int | None = None,
+    overwrite: bool = False,
+) -> Path:
+    """Convert a GeoPackage tile layer to a COG, using zoom levels as overviews.
+
+    Args:
+        gpkg_path: Path to the .gpkg file.
+        cog_path: Output GeoTIFF path.
+        table: Tile table name. Optional if the GeoPackage has exactly one.
+        bbox: (min_x, min_y, max_x, max_y) to clip to. Defaults to the extent
+            of the tiles present at max_zoom.
+        bbox_crs: CRS of bbox (e.g. "EPSG:4326"). Defaults to the layer's CRS.
+        min_zoom: Coarsest zoom level to include. Without resample_unaligned,
+            the extent is snapped to this level's pixel grid, which can
+            enlarge it a lot; with resample_unaligned it only limits which
+            levels are included. Defaults to as many levels as possible.
+        max_zoom: Zoom level used for full resolution. Defaults to the
+            highest zoom level that has tiles.
+        resample_unaligned: Also include coarser levels whose pixel grid
+            doesn't line up with the output extent, by resampling them onto
+            it. Emits a warning naming the resampled levels.
+        resampling: Resampling method for those levels: a rasterio
+            Resampling name such as "nearest", "bilinear", "cubic", "average".
+        bands: "RGBA" (missing tiles become transparent) or "RGB" (missing
+            tiles become black; required for JPEG compression).
+        compress: COG compression, e.g. "DEFLATE", "ZSTD", "LZW", "WEBP", "JPEG".
+        blocksize: COG internal tile size. Defaults to the GeoPackage tile width.
+        overwrite: Replace an existing output file.
+
+    Returns:
+        Path to the written COG.
+    """
+    if bands not in SUPPORTED_BANDS:
+        raise ValueError(f"bands must be one of {sorted(SUPPORTED_BANDS)}")
+    if compress.upper() == "JPEG" and bands != "RGB":
+        raise ValueError('JPEG compression requires bands="RGB"')
+    try:
+        resampling_method = Resampling[resampling]
+    except KeyError:
+        raise ValueError(f"Unknown resampling method {resampling!r}") from None
+    n_bands = SUPPORTED_BANDS[bands]
+
+    cog_path = Path(cog_path)
+    if cog_path.exists() and not overwrite:
+        raise FileExistsError(f"{cog_path} exists; pass overwrite=True")
+
+    uri = Path(gpkg_path).resolve().as_uri() + "?mode=ro"
+    con = sqlite3.connect(uri, uri=True)
+    try:
+        # --- Tile table, tile matrix set and CRS ----------------------------
+        tables = [
+            r[0]
+            for r in con.execute(
+                "SELECT table_name FROM gpkg_contents WHERE data_type = 'tiles'"
+            )
+        ]
+        if table is None:
+            if len(tables) != 1:
+                raise ValueError(f"Specify table=; tile tables found: {tables}")
+            table = tables[0]
+        elif table not in tables:
+            raise ValueError(f"{table!r} is not a tile table; found: {tables}")
+        qtable = _quote_ident(table)
+
+        srs_id, tms_min_x, tms_min_y, tms_max_x, tms_max_y = con.execute(
+            "SELECT srs_id, min_x, min_y, max_x, max_y "
+            "FROM gpkg_tile_matrix_set WHERE table_name = ?",
+            (table,),
+        ).fetchone()
+        org, org_id, wkt = con.execute(
+            "SELECT organization, organization_coordsys_id, definition "
+            "FROM gpkg_spatial_ref_sys WHERE srs_id = ?",
+            (srs_id,),
+        ).fetchone()
+        if org and org.upper() == "EPSG":
+            crs = CRS.from_epsg(int(org_id))
+        else:
+            crs = CRS.from_wkt(wkt)
+
+        # --- Zoom levels that actually contain tiles ------------------------
+        present = {
+            z for (z,) in con.execute(f"SELECT DISTINCT zoom_level FROM {qtable}")
+        }
+        levels = {
+            row[0]: _Level(*row)
+            for row in con.execute(
+                "SELECT zoom_level, matrix_width, matrix_height, tile_width, "
+                "tile_height, pixel_x_size, pixel_y_size "
+                "FROM gpkg_tile_matrix WHERE table_name = ? ORDER BY zoom_level",
+                (table,),
+            )
+            if row[0] in present
+        }
+        if not levels:
+            raise ValueError(f"Table {table!r} contains no tiles")
+
+        if max_zoom is None:
+            max_zoom = max(levels)
+        if max_zoom not in levels:
+            raise ValueError(f"max_zoom {max_zoom} has no tiles; have {sorted(levels)}")
+        base = levels[max_zoom]
+
+        # Finest to coarsest.
+        candidates = sorted(
+            (z for z in levels
+             if z <= max_zoom and (min_zoom is None or z >= min_zoom)),
+            reverse=True,
+        )
+        if not candidates or candidates[0] != max_zoom:
+            raise ValueError("min_zoom must not be greater than max_zoom")
+
+        # --- Requested extent, in the layer's CRS ---------------------------
+        if bbox is None:
+            cmin, cmax, rmin, rmax = con.execute(
+                f"SELECT MIN(tile_column), MAX(tile_column), MIN(tile_row), "
+                f"MAX(tile_row) FROM {qtable} WHERE zoom_level = ?",
+                (max_zoom,),
+            ).fetchone()
+            bx0 = tms_min_x + cmin * base.tile_width * base.px
+            bx1 = tms_min_x + (cmax + 1) * base.tile_width * base.px
+            by1 = tms_max_y - rmin * base.tile_height * base.py
+            by0 = tms_max_y - (rmax + 1) * base.tile_height * base.py
+        else:
+            bx0, by0, bx1, by1 = bbox
+            if bbox_crs is not None and CRS.from_user_input(bbox_crs) != crs:
+                bx0, by0, bx1, by1 = transform_bounds(
+                    bbox_crs, crs, bx0, by0, bx1, by1, densify_pts=21
+                )
+        bx0, by0 = max(bx0, tms_min_x), max(by0, tms_min_y)
+        bx1, by1 = min(bx1, tms_max_x), min(by1, tms_max_y)
+        if bx0 >= bx1 or by0 >= by1:
+            raise ValueError("bbox does not overlap the tile matrix set")
+
+        # --- Level whose pixel grid the extent is snapped to ----------------
+        if min_zoom is not None and not resample_unaligned:
+            snap_zoom = candidates[-1]
+        else:
+            # Coarsest level at which the extent is still about one tile,
+            # which keeps the snapping to a small fraction of the extent.
+            snap_zoom = max_zoom
+            for z in candidates:
+                lv = levels[z]
+                snap_zoom = z
+                if (bx1 - bx0) / lv.px <= lv.tile_width * (1 + _EPS) and (
+                    by1 - by0
+                ) / lv.py <= lv.tile_height * (1 + _EPS):
+                    break
+        snap = levels[snap_zoom]
+        x0 = tms_min_x + math.floor((bx0 - tms_min_x) / snap.px + _EPS) * snap.px
+        x1 = tms_min_x + math.ceil((bx1 - tms_min_x) / snap.px - _EPS) * snap.px
+        y1 = tms_max_y - math.floor((tms_max_y - by1) / snap.py + _EPS) * snap.py
+        y0 = tms_max_y - math.ceil((tms_max_y - by0) / snap.py - _EPS) * snap.py
+
+        # --- Decide how each level is produced ------------------------------
+        plan: list[_Plan] = []
+        for z in candidates:
+            lv = levels[z]
+            fcol = (x0 - tms_min_x) / lv.px
+            frow = (tms_max_y - y1) / lv.py
+            fwidth = (x1 - x0) / lv.px
+            fheight = (y1 - y0) / lv.py
+
+            if z >= snap_zoom:
+                # Aligned by construction (barring non-doubling pyramids).
+                width = _as_int(fwidth, f"z{z} width")
+                height = _as_int(fheight, f"z{z} height")
+                col_off = _as_int(fcol, f"z{z} column offset")
+                row_off = _as_int(frow, f"z{z} row offset")
+                aligned = True
+            else:
+                width, height = round(fwidth), round(fheight)
+                col_off, row_off = round(fcol), round(frow)
+                aligned = all(_is_whole(v) for v in (fcol, frow, fwidth, fheight))
+
+            if width < 1 or height < 1:
+                break  # smaller than a pixel: no useful overview
+            if plan and width >= plan[-1].width and height >= plan[-1].height:
+                continue  # overviews must get smaller
+            if not aligned and not resample_unaligned:
+                break
+            plan.append(_Plan(lv, width, height, col_off, row_off, not aligned))
+
+        resampled = [p.level.zoom for p in plan if p.resampled]
+        if resampled:
+            warnings.warn(
+                f"Zoom levels {resampled} don't line up with the output extent "
+                f"and were resampled ({resampling}) rather than copied.",
+                stacklevel=2,
+            )
+
+        if blocksize is None:
+            blocksize = base.tile_width
+
+        with tempfile.TemporaryDirectory(prefix="gpkg2cog_") as tmp:
+            tmpdir = Path(tmp)
+            level_files: list[Path] = []
+
+            for p in plan:
+                lv = p.level
+                path = tmpdir / f"z{lv.zoom}.tif"
+                if p.resampled:
+                    _resample_level(
+                        con, qtable, lv, path, crs, tmpdir,
+                        (tms_min_x, tms_max_y), (x0, y0, x1, y1),
+                        p.width, p.height, bands, n_bands, resampling_method,
+                    )
+                else:
+                    _mosaic_level(
+                        con, qtable, lv, path, crs,
+                        p.col_off, p.row_off, p.width, p.height,
+                        from_origin(x0, y1, lv.px, lv.py), bands, n_bands,
+                    )
+                level_files.append(path)
+
+            vrt_path = tmpdir / "pyramid.vrt"
+            vrt_path.write_text(
+                _pyramid_vrt(
+                    level_files, plan[0].width, plan[0].height, crs,
+                    (x0, base.px, 0, y1, 0, -base.py), n_bands,
+                )
+            )
+
+            options = {
+                "COMPRESS": compress,
+                "BLOCKSIZE": blocksize,
+                "OVERVIEWS": "FORCE_USE_EXISTING",
+                "BIGTIFF": "IF_SAFER",
+            }
+            if compress.upper() in {"DEFLATE", "ZSTD", "LZW"}:
+                options["PREDICTOR"] = "YES"
+            if cog_path.exists():
+                cog_path.unlink()
+            rasterio.shutil.copy(str(vrt_path), str(cog_path), driver="COG", **options)
+    finally:
+        con.close()
+
+    return cog_path
+
+
+def _profile(
+    width: int, height: int, n_bands: int, crs: CRS, transform: Affine, bands: str
+) -> dict:
+    profile = {
+        "driver": "GTiff",
+        "width": width,
+        "height": height,
+        "count": n_bands,
+        "dtype": "uint8",
+        "crs": crs,
+        "transform": transform,
+        "tiled": True,
+        "blockxsize": 256,
+        "blockysize": 256,
+        "compress": "DEFLATE",
+        "sparse_ok": True,  # leave missing tiles unwritten
+        "bigtiff": "IF_SAFER",
+    }
+    if bands == "RGBA":
+        profile["photometric"] = "RGB"
+        profile["alpha"] = "UNASSOCIATED"
+    return profile
+
+
+def _mosaic_level(
+    con: sqlite3.Connection,
+    qtable: str,
+    lv: _Level,
+    path: Path,
+    crs: CRS,
+    col_off: int,
+    row_off: int,
+    width: int,
+    height: int,
+    transform: Affine,
+    bands: str,
+    n_bands: int,
+) -> None:
+    """Copy one zoom level's pixels inside a pixel window into a GeoTIFF."""
+    tw, th = lv.tile_width, lv.tile_height
+    first_col, last_col = col_off // tw, (col_off + width - 1) // tw
+    first_row, last_row = row_off // th, (row_off + height - 1) // th
+
+    with rasterio.open(
+        path, "w", **_profile(width, height, n_bands, crs, transform, bands)
+    ) as dst:
+        rows = con.execute(
+            f"SELECT tile_column, tile_row, tile_data FROM {qtable} "
+            "WHERE zoom_level = ? AND tile_column BETWEEN ? AND ? "
+            "AND tile_row BETWEEN ? AND ?",
+            (lv.zoom, first_col, last_col, first_row, last_row),
+        )
+        for col, row, blob in rows:
+            with Image.open(io.BytesIO(blob)) as img:
+                if img.size != (tw, th):
+                    raise ValueError(
+                        f"Tile z={lv.zoom} col={col} row={row} is {img.size}, "
+                        f"expected {(tw, th)}"
+                    )
+                pixels = np.asarray(img.convert(bands))
+
+            # Tile position relative to the output window, then clip to it.
+            tx, ty = col * tw - col_off, row * th - row_off
+            dx0, dy0 = max(tx, 0), max(ty, 0)
+            dx1, dy1 = min(tx + tw, width), min(ty + th, height)
+            if dx0 >= dx1 or dy0 >= dy1:
+                continue
+            block = pixels[dy0 - ty : dy1 - ty, dx0 - tx : dx1 - tx]
+            dst.write(
+                np.moveaxis(block, -1, 0),
+                window=Window(dx0, dy0, dx1 - dx0, dy1 - dy0),
+            )
+
+
+def _resample_level(
+    con: sqlite3.Connection,
+    qtable: str,
+    lv: _Level,
+    path: Path,
+    crs: CRS,
+    tmpdir: Path,
+    origin: tuple[float, float],
+    extent: tuple[float, float, float, float],
+    width: int,
+    height: int,
+    bands: str,
+    n_bands: int,
+    resampling: Resampling,
+) -> None:
+    """Crop a level on its own grid, then resample it onto the output extent.
+
+    Only used for levels coarser than the snap level, where the extent is
+    about one tile or less, so the arrays involved are small.
+    """
+    tms_min_x, tms_max_y = origin
+    x0, y0, x1, y1 = extent
+
+    # Native-grid window covering the extent, plus a 1-pixel margin so
+    # interpolating methods have neighbours at the edges.
+    c_lo = max(math.floor((x0 - tms_min_x) / lv.px) - 1, 0)
+    c_hi = min(math.ceil((x1 - tms_min_x) / lv.px) + 1, lv.matrix_width * lv.tile_width)
+    r_lo = max(math.floor((tms_max_y - y1) / lv.py) - 1, 0)
+    r_hi = min(math.ceil((tms_max_y - y0) / lv.py) + 1, lv.matrix_height * lv.tile_height)
+
+    native_path = tmpdir / f"z{lv.zoom}_native.tif"
+    native_transform = from_origin(
+        tms_min_x + c_lo * lv.px, tms_max_y - r_lo * lv.py, lv.px, lv.py
+    )
+    _mosaic_level(
+        con, qtable, lv, native_path, crs,
+        c_lo, r_lo, c_hi - c_lo, r_hi - r_lo, native_transform, bands, n_bands,
+    )
+    with rasterio.open(native_path) as src:
+        source = src.read()
+
+    dst_transform = from_origin(x0, y1, (x1 - x0) / width, (y1 - y0) / height)
+    out = np.zeros((n_bands, height, width), dtype="uint8")
+    reproject(
+        source,
+        out,
+        src_transform=native_transform,
+        src_crs=crs,
+        dst_transform=dst_transform,
+        dst_crs=crs,
+        resampling=resampling,
+    )
+    with rasterio.open(
+        path, "w", **_profile(width, height, n_bands, crs, dst_transform, bands)
+    ) as dst:
+        dst.write(out)
+
+
+def _pyramid_vrt(
+    level_files: list[Path],
+    width: int,
+    height: int,
+    crs: CRS,
+    geotransform: tuple[float, ...],
+    n_bands: int,
+) -> str:
+    """VRT whose bands read the first file and expose the rest as overviews."""
+    base_path, overviews = level_files[0], level_files[1:]
+    gt = ", ".join(repr(v) for v in geotransform)
+    parts = [
+        f'<VRTDataset rasterXSize="{width}" rasterYSize="{height}">',
+        f"  <SRS>{escape(crs.to_wkt())}</SRS>",
+        f"  <GeoTransform>{gt}</GeoTransform>",
+    ]
+    for b in range(1, n_bands + 1):
+        parts += [
+            f'  <VRTRasterBand dataType="Byte" band="{b}">',
+            f"    <ColorInterp>{COLOR_INTERP[b - 1]}</ColorInterp>",
+            "    <SimpleSource>",
+            f'      <SourceFilename relativeToVRT="0">{escape(str(base_path))}</SourceFilename>',
+            f"      <SourceBand>{b}</SourceBand>",
+            "    </SimpleSource>",
+        ]
+        for ov_path in overviews:
+            parts += [
+                "    <Overview>",
+                f'      <SourceFilename relativeToVRT="0">{escape(str(ov_path))}</SourceFilename>',
+                f"      <SourceBand>{b}</SourceBand>",
+                "    </Overview>",
+            ]
+        parts.append("  </VRTRasterBand>")
+    parts.append("</VRTDataset>")
+    return "\n".join(parts)

geopaktile/xml_parser.py

@@ -0,0 +1,191 @@
+"""Parse OGC WMTS GetCapabilities XML into TileMatrix / TileMatrixSet models."""
+
+from __future__ import annotations
+
+import re
+from xml.etree import ElementTree as ET
+
+import pyproj
+from morecantile.models import CRS, TileMatrix, TileMatrixSet, TMSBoundingBox
+from morecantile.utils import meters_per_unit
+
+NS = {
+    "wmts": "http://www.opengis.net/wmts/1.0",
+    "ows": "http://www.opengis.net/ows/1.1",
+}
+
+# Matches the EPSG code out of any of the common ways a CRS URN/URI is
+# written in WMTS capabilities, e.g.:
+#   "urn:ogc:def:crs:EPSG::27700"
+#   "urn:ogc:def:crs:EPSG:6.3:27700"
+#   "urn:ogc:def:crs:EPSG:6.18:3:3857"   (multiple version/codespace segments)
+#   "EPSG:27700"
+#   "http://www.opengis.net/def/crs/EPSG/0/27700"
+# The middle segment is repeated (*, not ?) since some URN authorities
+# chain more than one version/codespace token before the actual code.
+_EPSG_RE = re.compile(r"EPSG[:/]+(?:[\w.]+[:/]+)*(\d+)\s*$", re.IGNORECASE)
+
+# CRS84 ("urn:ogc:def:crs:OGC:1.3:CRS84") is WGS84 with (lon, lat) axis
+# order
+_CRS84_RE = re.compile(r"\bCRS84\b", re.IGNORECASE)
+
+
+def _parse_crs(crs_text: str) -> str:
+    """Parse a SupportedCRS string into a CRS string pyproj/morecantile accept.
+
+    Returns "OGC:CRS84" for CRS84 and "EPSG:<code>" otherwise.
+    """
+    crs_text = crs_text.strip()
+    if _CRS84_RE.search(crs_text):
+        return "OGC:CRS84"
+
+    match = _EPSG_RE.search(crs_text)
+    if not match:
+        raise ValueError(f"Could not parse EPSG code from SupportedCRS: {crs_text!r}")
+    return f"EPSG:{int(match.group(1))}"
+
+
+def _text(elem: ET.Element, path: str, ns: dict[str, str] = NS) -> str:
+    found = elem.find(path, ns)
+    if found is None or found.text is None:
+        raise ValueError(f"Missing required element {path!r} in {elem.tag}")
+    return found.text.strip()
+
+
+def _text_any_ns(elem: ET.Element, local_name: str) -> str:
+    """Look up a WMTS-namespaced child, tolerating servers that omit the
+    default xmlns declaration and emit bare (no-namespace) element names."""
+    found = elem.find(f"wmts:{local_name}", NS)
+    if found is None:
+        found = elem.find(local_name)
+    if found is None or found.text is None:
+        raise ValueError(f"Missing required element {local_name!r} in {elem.tag}")
+    return found.text.strip()
+
+
+def _parse_tile_matrix(elem: ET.Element, fallback_zoom: int, meters_per_crs_unit: float) -> TileMatrix:
+    """Parse a single <TileMatrix> element.
+
+    The WMTS spec doesn't require ows:Identifier to be an integer zoom
+    level, just a unique label. morecantile requires an integer id, so we
+    try the identifier first and fall back to the element's position in the
+    (already document-ordered) TileMatrixSet.
+
+    pointOfOrigin is kept in the order written in the capabilities (the
+    CRS axis order); TileMatrixSet handles any lat/lon inversion itself.
+    """
+    raw_id = _text(elem, "ows:Identifier")
+    try:
+        zoom_level = int(raw_id)
+    except ValueError:
+        zoom_level = fallback_zoom
+
+    first, second = _text_any_ns(elem, "TopLeftCorner").split()
+    scale_denominator = float(_text_any_ns(elem, "ScaleDenominator"))
+
+    return TileMatrix(
+        id=str(zoom_level),
+        scaleDenominator=scale_denominator,
+        cellSize=scale_denominator * 0.28e-3 / meters_per_crs_unit,
+        cornerOfOrigin="topLeft",
+        pointOfOrigin=(float(first), float(second)),
+        tileWidth=int(_text_any_ns(elem, "TileWidth")),
+        tileHeight=int(_text_any_ns(elem, "TileHeight")),
+        matrixWidth=int(_text_any_ns(elem, "MatrixWidth")),
+        matrixHeight=int(_text_any_ns(elem, "MatrixHeight")),
+    )
+
+
+def _parse_bounding_box(elem: ET.Element) -> TMSBoundingBox | None:
+    """Parse an optional ows:BoundingBox (coordinates in CRS axis order)."""
+    bbox = elem.find("ows:BoundingBox", NS)
+    if bbox is None:
+        return None
+    lower = tuple(float(v) for v in _text(bbox, "ows:LowerCorner").split())
+    upper = tuple(float(v) for v in _text(bbox, "ows:UpperCorner").split())
+    return TMSBoundingBox(lowerLeft=lower, upperRight=upper)  # type: ignore morecantile uses NumType = int | float
+
+
+def parse_tile_matrix_set(elem: ET.Element, swap_xy: bool | None = None) -> TileMatrixSet:
+    """Parse a single <TileMatrixSet> element (found under <Contents>).
+
+    Parameters
+    ----------
+    swap_xy : bool | None
+        Whether TopLeftCorner/BoundingBox coordinates are written as
+        (lat, lon) instead of (lon, lat) / (x, y). If None (default),
+        morecantile infers this from the CRS's axis order (e.g. True for
+        EPSG:4326, False for CRS84). WMTS servers are inconsistent about
+        this in practice, so if your parsed bounds look implausible, try
+        passing the opposite explicitly; this sets the TileMatrixSet's
+        orderedAxes.
+    """
+    identifier = _text(elem, "ows:Identifier")
+    crs_str = _parse_crs(_text(elem, "ows:SupportedCRS"))
+    mpu = meters_per_unit(pyproj.CRS.from_user_input(crs_str))
+
+    tile_matrix_elems = elem.findall("wmts:TileMatrix", NS) or elem.findall("TileMatrix")
+    if not tile_matrix_elems:
+        raise ValueError(f"TileMatrixSet {identifier!r} has no TileMatrix levels")
+
+    tile_matrices = [
+        _parse_tile_matrix(tm_elem, fallback_zoom=i, meters_per_crs_unit=mpu)
+        for i, tm_elem in enumerate(tile_matrix_elems)
+    ]
+    tile_matrices.sort(key=lambda tm: int(tm.id))
+
+    ordered_axes = None if swap_xy is None else (["Y", "X"] if swap_xy else ["X", "Y"])
+
+    return TileMatrixSet(
+        # morecantile restricts ids to [\w\d_-]; keep the original as title.
+        id=re.sub(r"[^\w\-]", "_", identifier),
+        title=identifier,
+        crs=CRS(crs_str),
+        orderedAxes=ordered_axes,
+        boundingBox=_parse_bounding_box(elem),
+        tileMatrices=tile_matrices,
+    )
+
+
+def parse_capabilities(xml_source: str | bytes, swap_xy: bool | None = None) -> list[TileMatrixSet]:
+    """Parse a full WMTS GetCapabilities document into its TileMatrixSets.
+
+    Parameters
+    ----------
+    xml_source : str | bytes
+        The raw GetCapabilities XML, as returned by the WMTS endpoint.
+    swap_xy : bool | None
+        See parse_tile_matrix_set. Applied to every TileMatrixSet found;
+        pass None (default) to auto-detect per-set based on CRS.
+
+    Returns
+    -------
+    list[TileMatrixSet]
+        One entry per <TileMatrixSet> found under <Contents>. A capabilities
+        document commonly advertises several (e.g. one per CRS, or several
+        resolutions of the same CRS) even if you only care about one.
+    """
+    root = ET.fromstring(xml_source)
+    contents = root.find("wmts:Contents", NS)
+    if contents is None:
+        raise ValueError("GetCapabilities document has no <Contents> element")
+
+    tms_elems = contents.findall("wmts:TileMatrixSet", NS)
+    return [parse_tile_matrix_set(elem, swap_xy=swap_xy) for elem in tms_elems]
+
+
+def get_tile_matrix_set(
+    xml_source: str | bytes, identifier: str, swap_xy: bool | None = None
+) -> TileMatrixSet:
+    """Convenience wrapper: parse and return one named TileMatrixSet.
+
+    Raises KeyError if no TileMatrixSet with that identifier is present,
+    listing what was actually found so mismatches (e.g. guessing "2km"
+    when the service calls it "2km_epsg4326") are easy to debug.
+    """
+    all_sets = parse_capabilities(xml_source, swap_xy=swap_xy)
+    for tms in all_sets:
+        if identifier in (tms.id, tms.title):
+            return tms
+    available = [tms.title or tms.id for tms in all_sets]
+    raise KeyError(f"No TileMatrixSet {identifier!r} found. Available: {available}")

geopaktile-2.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: GeoPakTile
+Version: 2.1.0
+Summary: Create a Geopackage XYZ Tile layer.
+Keywords: GIS,Geopackage,Tiles,XYZ,gpkg
+Author: apwebber
+Author-email: apwebber <39490780+apwebber@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: typing-extensions>=4.0 ; python_full_version < '3.11'
+Requires-Dist: morecantile>=6.2.0
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: requests>=2.34.2
+Requires-Dist: pillow>=12.3.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/apwebber/GeoPakTile
+Project-URL: Documentation, https://github.com/apwebber/GeoPakTile
+Project-URL: Repository, https://github.com/apwebber/GeoPakTile.git
+Project-URL: Issues, https://github.com/apwebber/GeoPakTile/issues
+Description-Content-Type: text/markdown
+
+# GeoPakTile
+
+For writing geopackage XYZ raster tile layers, with support for using arbitrary grid systems, and for converting them to Cloud Optimized GeoTIFFs (COGs).
+
+Geopackage XYZ files can use any tile grid system, this is often defined by a server's GetCapabilities response where a TileMatrixSet defines the data co-ordinate system, the extent, the number of rows and columns in each zoom lever, and the corner co-ordinates for each zoom level. This package contains a tool for parsing the GetCapabilities XML into a [morecantile](https://github.com/developmentseed/morecantile) `TileMatrixSet`, and then for writing tiles to a new or existing geopackage.
+
+## Examples
+
+Write tiles to a new geopackage using web mercator (similar to mbtiles), where tiles is a list of (z, x, y, bytes). `tms` is a morecantile `TileMatrixSet` - the standard web mercator can be obtained with `morecantile.tms.get('WebMercatorQuad')`
+
+```python
+from geopaktile import GeoPakTile
+
+# Here, a list of tiles are read from a local path, the bytes and co-ordinates are stored as tuples in a list:
+# You might get these tiles from a tile server or anywhere else. Adjust accordingly.
+
+tiles = [
+    (z, x, y, path.read_bytes()),
+    (z2, x2, y2, path2.read_bytes()),
+    (z3, x3, y3, path3.read_bytes()),
+    ...
+]
+
+with GeoPakTile(test_gpkg, tms=morecantile.tms.get('WebMercatorQuad'), mode='rwc') as gpkg:
+    gpkg.add_tiles(tiles)
+```
+
+Open a geopackage in read only mode and see if it contains certain tiles. A TileMatrixSet isn't required for read-only mode.
+
+```python
+from geopaktile import GeoPakTile
+
+with GeoPakTile(test_gpkg, mode='ro') as gpkg:
+    assert gpkg.has_tile(z, x, y)
+    result = gpkg.has_tiles([(z, x, y), (z1, x1, y1)])
+```
+
+
+Parse a GetCapabilties xml to provide the TileMatrixSet for writing a geopackage:
+
+```python
+from geopaktile import parse_capabilities
+
+tms_set = parse_capabilities(xml)
+tms = tms_set[0] # you'll need to know which one you want, or use:
+
+tms = get_tile_matrix_set(xml, identifier = '1km') # an identifier that you know is defined in the xml
+```
+
+
+Convert a geopackage tile layer to a Cloud Optimized GeoTIFF. The highest zoom level becomes the full resolution image, and the lower zoom levels become the COG's overviews:
+
+```python
+from geopaktile import gpkg_tiles_to_cog
+
+gpkg_tiles_to_cog("tiles.gpkg", "tiles.tif")
+
+# Clip to a bounding box, given here in longitude/latitude
+gpkg_tiles_to_cog(
+    "tiles.gpkg",
+    "clipped.tif",
+    bbox=(-0.1, 51.45, 0.05, 51.52),
+    bbox_crs="EPSG:4326",
+)
+```
+
+### TileMatrixSet models
+
+Tile Matrix definitions use the [morecantile](https://github.com/developmentseed/morecantile) package (`morecantile.TileMatrixSet`, `TileMatrix`, etc.) so any morecantile TileMatrixSet (built-in or custom-loaded) can be passed to `GeoPakTile`. The XML parser returns morecantile `TileMatrixSet` objects.
+
+### XML Parser
+
+The xml parser has been tested on NASA GetCapabilties XML and some others, if you come across any that doesn't work then please raise an issue or fix and pull request.
+
+### Converting to COG
+
+`gpkg_tiles_to_cog` copies each zoom level's own pixels into the COG as an overview, rather than letting GDAL resample new overviews from the full resolution image, so every overview keeps the scale of the zoom level it came from. It works with any tile grid where each zoom level halves the pixel size of the one below, such as `WebMercatorQuad` and most grids from GetCapabilities documents.
+
+The output extent defaults to the tiles present at the highest zoom level, or can be set with `bbox` (in the layer's CRS, or in `bbox_crs` if given). The extent is expanded slightly so that it lines up with whole pixels at the zoom levels used as overviews.
+
+A zoom level can only be copied directly if its pixel grid lines up with the output extent. For small extents, the coarsest zoom levels often don't line up, and are left out by default. Pass `resample_unaligned=True` to include them by resampling them onto the extent, down to an overview 1 pixel across. A warning lists any zoom levels that were resampled. The method is set with `resampling` (`"bilinear"` by default; any [rasterio Resampling](https://rasterio.readthedocs.io/en/stable/api/rasterio.enums.html#rasterio.enums.Resampling) name such as `"nearest"` or `"average"` works).
+
+Other options:
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `table` | the only tile table | Tile table to convert, needed if the geopackage has more than one. |
+| `min_zoom`, `max_zoom` | all zoom levels with tiles | Zoom levels to include. `max_zoom` sets the full resolution. Without `resample_unaligned`, setting `min_zoom` expands the extent to line up with that zoom level's pixels, which can make the output much larger. |
+| `bands` | `"RGBA"` | `"RGBA"` makes missing tiles transparent. `"RGB"` makes them black, and is required for JPEG compression. |
+| `compress` | `"DEFLATE"` | Any GDAL COG compression, such as `"ZSTD"`, `"LZW"`, `"WEBP"` or `"JPEG"`. |
+| `blocksize` | the geopackage tile width | Internal tile size of the COG. |
+| `overwrite` | `False` | Replace an existing output file. |
+
+COG conversion requires [rasterio](https://rasterio.readthedocs.io/), which includes GDAL's COG driver in its wheels.

geopaktile-2.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+geopaktile/__init__.py,sha256=LOPsKscNgO2NqDz0SE8nDReAf6svu1md0PI4tNn8OPE,363
+geopaktile/__main__.py,sha256=MD118vcJhpneDLGbjmErx-_ug1lrjRsZzlmOj0LG8bY,69
+geopaktile/geopaktile.py,sha256=exSygyA-jhLOSii0ea95S7WLiwR1SVQOi64H7yKzNew,15404
+geopaktile/gpkg_to_cog.py,sha256=qXrhaaKYnlrUQR4Ja0EwU48fli1iHhCQMWn0tqlU-JY,19558
+geopaktile/xml_parser.py,sha256=eNEbJtHo885F5cQmAKPBOci7fz7f4E7D1z_jvTOCPKo,7791
+geopaktile-2.1.0.dist-info/licenses/LICENSE.md,sha256=l_OJCOs5Hli7ri30MKfXMFO58k8juM3sT1aTvR3fRBM,1085
+geopaktile-2.1.0.dist-info/WHEEL,sha256=M4DeIjVCA49okfALADZoWX5JOGwnmHb-JOpQHtI-1c0,80
+geopaktile-2.1.0.dist-info/entry_points.txt,sha256=cNf1TFW8KuDXF6Mmi424dwlTm2pq5NLg-sntV37tePs,48
+geopaktile-2.1.0.dist-info/METADATA,sha256=G5_CKyb8DBiWRGgjUxm0sRDbtGAX9qnHA7MZopqO_Sk,6441
+geopaktile-2.1.0.dist-info/RECORD,,

geopaktile-2.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.2
+Root-Is-Purelib: true
+Tag: py3-none-any

geopaktile-2.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+geopaktile = geopaktile:main
+

geopaktile-2.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alex Webber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.