moos-map 1.0.1__py3-none-any.whl

moos_map/__init__.py

@@ -0,0 +1,3 @@
+"""MOOS-IvP background map builder."""
+
+__version__ = "1.0.1"

moos_map/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

moos_map/acquisition.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import sqlite3
+import threading
+import time
+from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from io import BytesIO
+from typing import Callable, Protocol
+
+import httpx
+from PIL import Image, UnidentifiedImageError
+
+from . import __version__
+from .cache import TileCache
+from .errors import FetchError
+from .models import TileRange
+from .sources import MapSource
+
+
+ProgressCallback = Callable[[int, int, int, int], None]
+
+
+class TileProvider(Protocol):
+    cache_hits: int
+    downloaded_tiles: int
+
+    def fetch(self, zoom: int, x: int, y: int, *, force: bool = False) -> bytes: ...
+
+    def close(self) -> None: ...
+
+
+def validate_tile_bytes(data: bytes, tile_size: int, description: str) -> None:
+    if not data:
+        raise FetchError(f"Empty tile response for {description}")
+    try:
+        with Image.open(BytesIO(data)) as image:
+            image.load()
+            if image.size != (tile_size, tile_size):
+                raise FetchError(
+                    f"Unexpected tile dimensions for {description}: "
+                    f"{image.width}x{image.height}, expected {tile_size}x{tile_size}"
+                )
+    except (UnidentifiedImageError, OSError) as exc:
+        raise FetchError(
+            f"Response was not a readable image for {description}"
+        ) from exc
+
+
+class HttpTileProvider:
+    RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+
+    def __init__(
+        self,
+        source: MapSource,
+        *,
+        cache: TileCache | None = None,
+        timeout_seconds: float = 20.0,
+        retries: int = 3,
+    ) -> None:
+        self.source = source
+        self.cache = cache or TileCache(source)
+        self.retries = retries
+        self.cache_hits = 0
+        self.downloaded_tiles = 0
+        self._stats_lock = threading.Lock()
+        self._client = httpx.Client(
+            timeout=httpx.Timeout(timeout_seconds),
+            follow_redirects=True,
+            headers={
+                "User-Agent": f"moos-map/{__version__} (+local MOOS-IvP map builder)",
+                "Accept": "image/*",
+            },
+            limits=httpx.Limits(max_connections=8, max_keepalive_connections=8),
+        )
+
+    def fetch(self, zoom: int, x: int, y: int, *, force: bool = False) -> bytes:
+        description = f"{self.source.id} z={zoom} x={x} y={y}"
+        if not force:
+            cached = self.cache.read(zoom, x, y)
+            if cached is not None:
+                try:
+                    validate_tile_bytes(cached, self.source.tile_size, description)
+                except FetchError:
+                    self.cache.path_for(zoom, x, y).unlink(missing_ok=True)
+                else:
+                    with self._stats_lock:
+                        self.cache_hits += 1
+                    return cached
+
+        url = self.source.tile_url(zoom, x, y)
+        last_error: Exception | None = None
+        for attempt in range(self.retries + 1):
+            try:
+                response = self._client.get(url)
+                if response.status_code == 200:
+                    data = response.content
+                    if len(data) > 10 * 1024 * 1024:
+                        raise FetchError(
+                            f"Tile response exceeded 10 MB for {description}"
+                        )
+                    validate_tile_bytes(data, self.source.tile_size, description)
+                    self.cache.write(zoom, x, y, data)
+                    with self._stats_lock:
+                        self.downloaded_tiles += 1
+                    return data
+
+                message = f"HTTP {response.status_code} fetching {description}"
+                if response.status_code not in self.RETRYABLE_STATUS_CODES:
+                    raise FetchError(message)
+
+                retry_after = response.headers.get("Retry-After", "")
+                try:
+                    delay = min(float(retry_after), 10.0)
+                except ValueError:
+                    delay = min(0.5 * (2**attempt), 8.0)
+                last_error = FetchError(message)
+            except (httpx.HTTPError, FetchError) as exc:
+                last_error = exc
+                if isinstance(exc, FetchError) and "HTTP " in str(exc):
+                    status_text = str(exc).split("HTTP ", 1)[1].split(" ", 1)[0]
+                    if (
+                        status_text.isdigit()
+                        and int(status_text) not in self.RETRYABLE_STATUS_CODES
+                    ):
+                        raise
+                delay = min(0.5 * (2**attempt), 8.0)
+
+            if attempt < self.retries:
+                time.sleep(delay)
+
+        raise FetchError(
+            f"Failed after {self.retries + 1} attempts: {description}"
+        ) from last_error
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class MBTilesProvider:
+    def __init__(self, source: MapSource) -> None:
+        if not source.mbtiles_path:
+            raise FetchError("MBTiles source has no archive path")
+        self.source = source
+        self.path = source.mbtiles_path
+        self.cache_hits = 0
+        self.downloaded_tiles = 0
+        self._lock = threading.Lock()
+        try:
+            self._connection = sqlite3.connect(self.path, check_same_thread=False)
+            self._connection.execute("SELECT 1 FROM tiles LIMIT 1")
+        except sqlite3.Error as exc:
+            raise FetchError(f"Invalid MBTiles archive: {self.path}") from exc
+
+    def fetch(self, zoom: int, x: int, y: int, *, force: bool = False) -> bytes:
+        del force
+        tms_y = (1 << zoom) - 1 - y
+        with self._lock:
+            row = self._connection.execute(
+                "SELECT tile_data FROM tiles "
+                "WHERE zoom_level=? AND tile_column=? AND tile_row=?",
+                (zoom, x, tms_y),
+            ).fetchone()
+        if row is None:
+            raise FetchError(
+                f"Tile is absent from {self.path.name}: z={zoom} x={x} y={y}"
+            )
+        data = bytes(row[0])
+        validate_tile_bytes(
+            data, self.source.tile_size, f"{self.path.name} z={zoom} x={x} y={y}"
+        )
+        with self._lock:
+            self.cache_hits += 1
+        return data
+
+    def close(self) -> None:
+        self._connection.close()
+
+
+def create_provider(source: MapSource) -> TileProvider:
+    if source.kind == "xyz":
+        return HttpTileProvider(source)
+    if source.kind == "mbtiles":
+        return MBTilesProvider(source)
+    raise FetchError(f"Unsupported source kind: {source.kind}")
+
+
+def fetch_tile_range(
+    provider: TileProvider,
+    tiles: TileRange,
+    *,
+    force: bool = False,
+    workers: int = 4,
+    progress: ProgressCallback | None = None,
+) -> dict[tuple[int, int], bytes]:
+    coordinates = list(tiles.coordinates())
+    results: dict[tuple[int, int], bytes] = {}
+    completed = 0
+
+    with ThreadPoolExecutor(max_workers=max(1, min(workers, 16))) as executor:
+        futures: dict[Future[bytes], tuple[int, int]] = {
+            executor.submit(provider.fetch, tiles.zoom, x, y, force=force): (x, y)
+            for x, y in coordinates
+        }
+        try:
+            for future in as_completed(futures):
+                x, y = futures[future]
+                results[(x, y)] = future.result()
+                completed += 1
+                if progress:
+                    progress(completed, len(coordinates), x, y)
+        except Exception:
+            for future in futures:
+                future.cancel()
+            raise
+
+    return results

moos_map/cache.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import tempfile
+from pathlib import Path
+
+from .sources import MapSource
+
+
+def default_cache_dir() -> Path:
+    root = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return root / "moos-map" / "tiles"
+
+
+def source_cache_namespace(source: MapSource) -> str:
+    identity = source.url_template or str(source.mbtiles_path or source.id)
+    digest = hashlib.sha256(identity.encode("utf-8")).hexdigest()[:12]
+    safe_id = re.sub(r"[^A-Za-z0-9_.-]+", "-", source.id)
+    return f"{safe_id}-{digest}"
+
+
+class TileCache:
+    def __init__(self, source: MapSource, root: Path | None = None) -> None:
+        self.root = (root or default_cache_dir()).expanduser()
+        self.namespace = source_cache_namespace(source)
+
+    def path_for(self, zoom: int, x: int, y: int) -> Path:
+        return self.root / self.namespace / str(zoom) / str(x) / f"{y}.tile"
+
+    def read(self, zoom: int, x: int, y: int) -> bytes | None:
+        path = self.path_for(zoom, x, y)
+        try:
+            return path.read_bytes()
+        except FileNotFoundError:
+            return None
+
+    def write(self, zoom: int, x: int, y: int, data: bytes) -> Path:
+        path = self.path_for(zoom, x, y)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+        temp_path = Path(temp_name)
+        try:
+            with os.fdopen(handle, "wb") as stream:
+                stream.write(data)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temp_path, path)
+        finally:
+            temp_path.unlink(missing_ok=True)
+        return path

moos_map/cli.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+from . import __version__
+from .errors import MoosMapError
+from .models import Bounds, MapRequest, Origin
+from .service import build_map, plan_map
+from .sources import list_sources
+from .verification import verify_bundle
+
+
+def _json_print(value: Any) -> None:
+    print(json.dumps(value, indent=2, sort_keys=True))
+
+
+def _add_machine_output(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--json", action="store_true", help="Emit machine-readable JSON"
+    )
+
+
+def _add_map_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--corners",
+        nargs=4,
+        type=float,
+        metavar=("LAT1", "LON1", "LAT2", "LON2"),
+        required=True,
+        help=(
+            "Two diagonally opposite WGS84 corners as latitude/longitude pairs; "
+            "either corner order is accepted"
+        ),
+    )
+    parser.add_argument(
+        "--origin",
+        nargs=2,
+        type=float,
+        metavar=("LAT", "LON"),
+        help="MOOS LatOrigin and LongOrigin (default: map center)",
+    )
+    parser.add_argument(
+        "--zoom", type=int, default=17, help="XYZ zoom level (default: 17)"
+    )
+    parser.add_argument(
+        "--source",
+        default="esri-world-imagery",
+        help="Built-in source ID (default: esri-world-imagery)",
+    )
+    source_group = parser.add_mutually_exclusive_group()
+    source_group.add_argument(
+        "--url-template",
+        help="Custom XYZ URL containing {z}, {x}, and {y}",
+    )
+    source_group.add_argument(
+        "--mbtiles",
+        type=Path,
+        help="Read tiles from a local MBTiles archive",
+    )
+    parser.add_argument(
+        "--accept-source-terms",
+        action="store_true",
+        help="Confirm that a custom source permits static/offline export",
+    )
+    parser.add_argument("--max-tiles", type=int, default=1024)
+    parser.add_argument("--max-pixels", type=int, default=67_108_864)
+
+
+def _request_from_args(args: argparse.Namespace) -> MapRequest:
+    latitude_1, longitude_1, latitude_2, longitude_2 = args.corners
+    bounds = Bounds(
+        west=min(longitude_1, longitude_2),
+        south=min(latitude_1, latitude_2),
+        east=max(longitude_1, longitude_2),
+        north=max(latitude_1, latitude_2),
+    )
+    if args.origin is None:
+        origin = Origin(
+            latitude=(bounds.south + bounds.north) / 2,
+            longitude=(bounds.west + bounds.east) / 2,
+        )
+    else:
+        latitude, longitude = args.origin
+        origin = Origin(latitude=latitude, longitude=longitude)
+    return MapRequest(
+        bounds=bounds,
+        origin=origin,
+        zoom=args.zoom,
+        source_id=args.source,
+        name=getattr(args, "name", "moos_map"),
+        output_dir=getattr(args, "output_dir", Path.home() / "moos-maps"),
+        emit_moos=getattr(args, "emit_moos", True),
+        force=getattr(args, "force", False),
+        overwrite=getattr(args, "overwrite", True),
+        refresh_tiles=getattr(args, "refresh_tiles", False),
+        custom_url_template=args.url_template,
+        accept_custom_source_terms=args.accept_source_terms,
+        mbtiles_path=args.mbtiles,
+        max_tiles=args.max_tiles,
+        max_pixels=args.max_pixels,
+    )
+
+
+def _format_file_size(size_bytes: int, *, precise: bool = False) -> str:
+    if size_bytes < 1_000:
+        return f"{size_bytes:,} bytes"
+    if size_bytes < 1_000_000:
+        return f"{size_bytes / 1_000:.{1 if precise else 0}f} KB"
+    return f"{size_bytes / 1_000_000:.{2 if precise else 1}f} MB"
+
+
+def _print_plan_human(
+    plan: dict[str, Any], *, actual_tiff_size_bytes: int | None = None
+) -> None:
+    source = plan["source"]
+    tiles = plan["tiles"]
+    actual = plan["actual_bounds"]
+    origin = plan["origin"]
+    print(f"Source: {source['name']} ({source['id']})")
+    print(
+        f"Source tiles: {tiles['count']} "
+        f"({tiles['columns']} x {tiles['rows']}), zoom {tiles['zoom']}"
+    )
+    print(f"TIFF dimensions: {plan['pixel_width']} x {plan['pixel_height']} pixels")
+    if actual_tiff_size_bytes is None:
+        print(
+            "Estimated TIFF size: "
+            f"~{_format_file_size(plan['estimated_tiff_size_bytes'])} "
+            "before content-dependent LZW compression"
+        )
+    else:
+        print(
+            "TIFF file size: "
+            f"{_format_file_size(actual_tiff_size_bytes, precise=True)} "
+            f"({actual_tiff_size_bytes:,} bytes)"
+        )
+    print(
+        "Exact bounds: "
+        f"W {actual['west']:.10f}, S {actual['south']:.10f}, "
+        f"E {actual['east']:.10f}, N {actual['north']:.10f}"
+    )
+    print(
+        "Mission origin: "
+        f"LatOrigin {origin['latitude']:.10f}, "
+        f"LongOrigin {origin['longitude']:.10f}"
+    )
+    print(
+        "Ground area: "
+        f"{plan['approximate_ground_width_m']:.1f} x "
+        f"{plan['approximate_ground_height_m']:.1f} m"
+    )
+    print(f"Source resolution: {plan['approximate_meters_per_pixel']:.3f} m/pixel")
+    print(
+        "Display alignment: "
+        f"{plan['estimated_max_requested_area_position_error_m']:.1f} m model max "
+        "(theoretical, not measured)"
+    )
+    print("Output crop: exact requested bounds")
+    for warning in plan["warnings"]:
+        print(f"Warning: {warning}", file=sys.stderr)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="moos-map",
+        description="Build exact-crop TIFF background maps for MOOS-IvP",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    sources_parser = subparsers.add_parser("sources", help="List available map sources")
+    _add_machine_output(sources_parser)
+
+    plan_parser = subparsers.add_parser(
+        "plan", help="Plan an export without downloading"
+    )
+    _add_map_arguments(plan_parser)
+    _add_machine_output(plan_parser)
+
+    build_command = subparsers.add_parser("build", help="Download and build a MOOS map")
+    _add_map_arguments(build_command)
+    build_command.add_argument(
+        "--name", required=True, help="Output basename without suffix"
+    )
+    build_command.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path.home() / "moos-maps",
+        help="Output directory (default: ~/moos-maps)",
+    )
+    build_command.add_argument(
+        "--no-moos",
+        dest="emit_moos",
+        action="store_false",
+        default=True,
+        help="Do not write the default .moos mission snippet",
+    )
+    build_command.add_argument(
+        "--emit-moos",
+        dest="emit_moos",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
+    build_command.add_argument(
+        "--no-overwrite",
+        dest="overwrite",
+        action="store_false",
+        default=True,
+        help="Refuse to replace existing output files with the same map name",
+    )
+    build_command.add_argument(
+        "--overwrite",
+        dest="overwrite",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
+    build_command.add_argument(
+        "--refresh-tiles",
+        action="store_true",
+        help="Redownload source tiles instead of reusing the local cache",
+    )
+    build_command.add_argument(
+        "--force",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
+    _add_machine_output(build_command)
+
+    verify_parser = subparsers.add_parser("verify", help="Verify a TIFF/.info bundle")
+    verify_parser.add_argument("tiff", type=Path)
+    _add_machine_output(verify_parser)
+
+    ui_parser = subparsers.add_parser("ui", help="Launch the local browser UI")
+    ui_parser.add_argument(
+        "--host", default="127.0.0.1", help="Local bind address (default: 127.0.0.1)"
+    )
+    ui_parser.add_argument("--port", type=int, default=8765, help="Port (default: 8765)")
+    ui_parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Start the server without opening a browser window",
+    )
+
+    return parser
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.command == "sources":
+        sources = [source.as_dict() for source in list_sources()]
+        if args.json:
+            _json_print({"sources": sources})
+        else:
+            print("Sources:")
+            for source in sources:
+                capability = "export" if source["export_allowed"] else "preview only"
+                print(
+                    f"{source['id']:<16} {capability:<12} "
+                    f"zoom {source['min_zoom']}-{source['max_zoom']}  {source['name']}"
+                )
+                if source["note"]:
+                    print(f"  {source['note']}")
+        return 0
+
+    if args.command == "plan":
+        plan = plan_map(_request_from_args(args)).as_dict()
+        if args.json:
+            _json_print(plan)
+        else:
+            _print_plan_human(plan)
+        return 0
+
+    if args.command == "build":
+        request = _request_from_args(args)
+
+        def progress(completed: int, total: int, x: int, y: int) -> None:
+            print(
+                f"Fetched {completed}/{total} tiles (latest x={x}, y={y})",
+                file=sys.stderr,
+            )
+
+        result = build_map(request, progress=progress)
+        payload = result.as_dict()
+        if args.json:
+            _json_print(payload)
+        else:
+            _print_plan_human(
+                payload["plan"],
+                actual_tiff_size_bytes=payload["verification"]["details"][
+                    "file_size_bytes"
+                ],
+            )
+            print(f"TIFF: {payload['tiff_path']}")
+            print(f"Info: {payload['info_path']}")
+            if payload["moos_path"]:
+                print(f"MOOS snippet: {payload['moos_path']}")
+            print(
+                f"Tiles downloaded: {payload['downloaded_tiles']}; "
+                f"cache hits: {payload['cache_hits']}"
+            )
+        return 0
+
+    if args.command == "verify":
+        report = verify_bundle(args.tiff)
+        payload = report.as_dict()
+        if args.json:
+            _json_print(payload)
+        else:
+            print("PASS" if report.ok else "FAIL")
+            print(f"TIFF: {report.tiff_path}")
+            print(f"Info: {report.info_path}")
+            if "pixel_width" in report.details:
+                print(
+                    "Image: "
+                    f"{report.details['pixel_width']} x "
+                    f"{report.details['pixel_height']} pixels, "
+                    f"{report.details['mode']} {report.details['format']}"
+                )
+                size_bytes = report.details["file_size_bytes"]
+                print(
+                    "TIFF file size: "
+                    f"{_format_file_size(size_bytes, precise=True)} "
+                    f"({size_bytes:,} bytes)"
+                )
+            for warning in report.warnings:
+                print(f"Warning: {warning}")
+            for error in report.errors:
+                print(f"Error: {error}", file=sys.stderr)
+        return 0 if report.ok else 1
+
+    if args.command == "ui":
+        from .web import run_ui
+
+        run_ui(host=args.host, port=args.port, open_browser=not args.no_browser)
+        return 0
+
+    raise AssertionError(f"Unhandled command: {args.command}")
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        raise SystemExit(run(args))
+    except MoosMapError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc

moos_map/errors.py

@@ -0,0 +1,14 @@
+class MoosMapError(Exception):
+    """Base exception for expected, user-facing failures."""
+
+
+class ValidationError(MoosMapError):
+    """Input or output failed validation."""
+
+
+class SourcePolicyError(MoosMapError):
+    """The selected provider does not permit this operation."""
+
+
+class FetchError(MoosMapError):
+    """A source tile could not be acquired or decoded."""