bboxkit 0.1.0__py3-none-any.whl

bboxkit/formats.py

@@ -0,0 +1,86 @@
+"""Format a :class:`~bboxkit.BBox` by name."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Dict
+
+from .bbox import BBox
+
+__all__ = ["FORMATS", "FORMAT_ALIASES", "format_bbox"]
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, separators=(",", ":"))
+
+
+_Formatter = Callable[..., str]
+
+FORMATS: Dict[str, str] = {
+    "wsen": "west,south,east,north (GeoJSON, Shapely, OSM API, STAC)",
+    "swne": "south,west,north,east (lat-first)",
+    "bboxfinder": "bboxfinder.com link",
+    "overpass": "Overpass QL (s,w,n,e) filter",
+    "osm": "openstreetmap.org #map=zoom/lat/lon link that fits the box",
+    "wkt": "WKT POLYGON (MULTIPOLYGON when crossing the antimeridian)",
+    "envelope": "CQL/Solr ENVELOPE(minX, maxX, maxY, minY)",
+    "postgis": "PostGIS ST_MakeEnvelope(xmin, ymin, xmax, ymax, srid)",
+    "geojson": "GeoJSON Polygon/MultiPolygon with bbox member",
+    "shapely": "Shapely bounds tuple (minx, miny, maxx, maxy)",
+    "gdal-te": "gdalwarp -te xmin ymin xmax ymax",
+    "gdal-projwin": "gdal_translate -projwin ulx uly lrx lry",
+    "leaflet": "Leaflet [[south, west], [north, east]]",
+    "mapbox": "Mapbox/MapLibre [[west, south], [east, north]]",
+    "tile": "deepest XYZ tile z/x/y containing the box",
+    "quadkey": "Bing quadkey of that tile",
+    "geohash": "longest geohash containing the box",
+    "pluscode": "longest Plus Code containing the box",
+    "mgrs": "finest MGRS square containing the box",
+    "json": "JSON object {west, south, east, north, crs}",
+}
+"""Format names accepted by :meth:`BBox.format` and ``bboxkit convert --to``."""
+
+FORMAT_ALIASES: Dict[str, str] = {
+    "bbox": "wsen",
+    "csv": "wsen",
+    "latlon": "swne",
+    "gdal": "gdal-te",
+    "te": "gdal-te",
+    "projwin": "gdal-projwin",
+    "xyz": "tile",
+    "plus": "pluscode",
+    "olc": "pluscode",
+    "bounds": "shapely",
+}
+
+_FORMATTERS: Dict[str, _Formatter] = {
+    "wsen": lambda b, **kw: b.to_wsen(**kw),
+    "swne": lambda b, **kw: b.to_swne(**kw),
+    "bboxfinder": lambda b, **kw: b.to_bboxfinder(**kw),
+    "overpass": lambda b, **kw: b.to_overpass(**kw),
+    "osm": lambda b, **kw: b.to_osm_url(**kw),
+    "wkt": lambda b, **kw: b.to_wkt(**kw),
+    "envelope": lambda b, **kw: b.to_wkt_envelope(**kw),
+    "postgis": lambda b, **kw: b.to_postgis(**kw),
+    "geojson": lambda b, **kw: _json(b.to_geojson(**kw)),
+    "shapely": lambda b: _json(list(b.to_shapely_bounds())),
+    "gdal-te": lambda b, **kw: b.to_gdal_te(**kw),
+    "gdal-projwin": lambda b, **kw: b.to_gdal_projwin(**kw),
+    "leaflet": lambda b: _json(b.to_leaflet()),
+    "mapbox": lambda b: _json(b.to_mapbox()),
+    "tile": lambda b, **kw: str(b.to_tile(**kw)),
+    "quadkey": lambda b, **kw: b.to_quadkey(**kw),
+    "geohash": lambda b, **kw: b.to_geohash(**kw),
+    "pluscode": lambda b: b.to_pluscode(),
+    "mgrs": lambda b: b.to_mgrs(),
+    "json": lambda b: _json(b.to_dict()),
+}
+
+
+def format_bbox(bbox: BBox, fmt: str, **kwargs: Any) -> str:
+    """Render ``bbox`` in the format called ``fmt`` (see :data:`FORMATS`)."""
+    key = fmt.lower().replace("_", "-")
+    key = FORMAT_ALIASES.get(key, key)
+    if key not in _FORMATTERS:
+        raise ValueError(f"unknown format {fmt!r}; choose from {', '.join(FORMATS)}")
+    return _FORMATTERS[key](bbox, **kwargs)

bboxkit/geohash.py

@@ -0,0 +1,83 @@
+"""Geohash cells (Gustavo Niemeyer's base-32 interleaved lon/lat code)."""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+
+__all__ = ["BASE32", "decode_bounds", "encode", "MAX_PRECISION"]
+
+BASE32 = "0123456789bcdefghjkmnpqrstuvwxyz"
+_INDEX = {c: i for i, c in enumerate(BASE32)}
+
+#: 12 characters is about 3.7 cm x 1.9 cm, well past float-precision GPS.
+MAX_PRECISION = 12
+
+
+def decode_bounds(geohash: str) -> Tuple[float, float, float, float]:
+    """``(west, south, east, north)`` of a geohash cell."""
+    gh = geohash.strip().lower()
+    if not gh:
+        raise ValueError("empty geohash")
+    if len(gh) > 22:
+        raise ValueError("geohash is too long")
+    lon_lo, lon_hi = -180.0, 180.0
+    lat_lo, lat_hi = -90.0, 90.0
+    even = True
+    for ch in gh:
+        if ch not in _INDEX:
+            raise ValueError(f"invalid geohash character {ch!r} in {geohash!r}")
+        bits = _INDEX[ch]
+        for shift in range(4, -1, -1):
+            bit = (bits >> shift) & 1
+            if even:
+                mid = (lon_lo + lon_hi) / 2.0
+                if bit:
+                    lon_lo = mid
+                else:
+                    lon_hi = mid
+            else:
+                mid = (lat_lo + lat_hi) / 2.0
+                if bit:
+                    lat_lo = mid
+                else:
+                    lat_hi = mid
+            even = not even
+    return (lon_lo, lat_lo, lon_hi, lat_hi)
+
+
+def encode(lon: float, lat: float, precision: int = 9) -> str:
+    """Geohash of a point with ``precision`` characters."""
+    if not 1 <= precision <= 22:
+        raise ValueError("precision must be 1..22")
+    if not (-180.0 <= lon <= 180.0 and -90.0 <= lat <= 90.0):
+        raise ValueError(f"point ({lon}, {lat}) is outside lon/lat range")
+    lon_lo, lon_hi = -180.0, 180.0
+    lat_lo, lat_hi = -90.0, 90.0
+    out: List[str] = []
+    even = True
+    bits = 0
+    nbits = 0
+    while len(out) < precision:
+        if even:
+            mid = (lon_lo + lon_hi) / 2.0
+            if lon >= mid:
+                bits = (bits << 1) | 1
+                lon_lo = mid
+            else:
+                bits <<= 1
+                lon_hi = mid
+        else:
+            mid = (lat_lo + lat_hi) / 2.0
+            if lat >= mid:
+                bits = (bits << 1) | 1
+                lat_lo = mid
+            else:
+                bits <<= 1
+                lat_hi = mid
+        even = not even
+        nbits += 1
+        if nbits == 5:
+            out.append(BASE32[bits])
+            bits = 0
+            nbits = 0
+    return "".join(out)

bboxkit/mgrs.py

@@ -0,0 +1,136 @@
+"""MGRS grid squares (UTM part, latitudes 80 S to 84 N) on WGS 84.
+
+Polar UPS squares (bands A, B, Y, Z) are not supported.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Tuple
+
+from ._geo import wrap_lon
+from .crs import lonlat_to_utm, utm_to_lonlat, utm_zone
+
+__all__ = ["parse", "square_bounds", "encode", "band_letter"]
+
+_BANDS = "CDEFGHJKLMNPQRSTUVWX"
+_COL_SETS = ("ABCDEFGH", "JKLMNPQR", "STUVWXYZ")
+_ROWS = "ABCDEFGHJKLMNPQRSTUV"
+_PATTERN = re.compile(
+    r"^\s*(\d{1,2})\s*([C-HJ-NP-X])\s*([A-HJ-NP-Z])([A-HJ-NP-V])\s*(\d*)\s*(\d*)\s*$"
+)
+
+
+def band_letter(lat: float) -> str:
+    """MGRS latitude band letter (C..X) for -80 <= lat <= 84."""
+    if not -80.0 <= lat <= 84.0:
+        raise ValueError("MGRS/UTM covers latitudes 80 S to 84 N only")
+    return _BANDS[min(int((lat + 80.0) // 8.0), len(_BANDS) - 1)]
+
+
+def _band_lat_range(band: str) -> Tuple[float, float]:
+    i = _BANDS.index(band)
+    south = -80.0 + 8.0 * i
+    return (south, 84.0 if band == "X" else south + 8.0)
+
+
+def _zone_lon_range(zone: int, band: str) -> Tuple[float, float]:
+    west = zone * 6.0 - 186.0
+    east = west + 6.0
+    if band == "V" and zone == 31:
+        east = 3.0
+    elif band == "V" and zone == 32:
+        west = 3.0
+    elif band == "X" and zone in (31, 33, 35, 37):
+        west, east = {31: (0.0, 9.0), 33: (9.0, 21.0), 35: (21.0, 33.0), 37: (33.0, 42.0)}[zone]
+    elif band == "X" and zone in (32, 34, 36):
+        raise ValueError(f"MGRS zone {zone}X does not exist")
+    return (west, east)
+
+
+def parse(text: str) -> Tuple[int, str, float, float, float]:
+    """Split an MGRS reference into ``(zone, band, easting, northing, size_m)``."""
+    m = _PATTERN.match(text.upper())
+    if not m:
+        raise ValueError(f"{text!r} is not an MGRS reference")
+    zone = int(m.group(1))
+    band, col, row = m.group(2), m.group(3), m.group(4)
+    digits = m.group(5) + m.group(6)
+    if not 1 <= zone <= 60:
+        raise ValueError(f"MGRS zone must be 1..60, got {zone}")
+    if len(digits) % 2 or len(digits) > 10:
+        raise ValueError(f"{text!r}: easting/northing digits must be an even count up to 10")
+    col_set = _COL_SETS[(zone - 1) % 3]
+    if col not in col_set:
+        raise ValueError(f"column letter {col!r} is not used in zone {zone}")
+    precision = len(digits) // 2
+    size = 10.0 ** (5 - precision)
+    e_off = float(digits[:precision]) * size if precision else 0.0
+    n_off = float(digits[precision:]) * size if precision else 0.0
+    easting = (col_set.index(col) + 1) * 100000.0 + e_off
+    row_offset = 5 if zone % 2 == 0 else 0
+    row_n = ((_ROWS.index(row) - row_offset) % 20) * 100000.0 + n_off
+    # Resolve the 2,000 km northing ambiguity with the latitude band.
+    band_south, _ = _band_lat_range(band)
+    south = band_south < 0
+    lon_w, lon_e = _zone_lon_range(zone, band)
+    band_n = min(lonlat_to_utm(lon, band_south, zone, south)[1] for lon in (lon_w, lon_e))
+    band_n = min(band_n, lonlat_to_utm(zone * 6.0 - 183.0, band_south, zone, south)[1])
+    band_n = math.floor(band_n / 100000.0) * 100000.0
+    northing = row_n
+    while northing + size <= band_n:
+        northing += 2000000.0
+    return (zone, band, easting, northing, size)
+
+
+def square_bounds(text: str, densify: int = 16) -> Tuple[float, float, float, float]:
+    """``(west, south, east, north)`` of an MGRS square, clipped to its zone and band."""
+    zone, band, easting, northing, size = parse(text)
+    south = _band_lat_range(band)[0] < 0
+    lons = []
+    lats = []
+    steps = max(1, densify)
+    for i in range(steps + 1):
+        t = i / steps
+        for e, n in (
+            (easting + t * size, northing),
+            (easting + t * size, northing + size),
+            (easting, northing + t * size),
+            (easting + size, northing + t * size),
+        ):
+            lon, lat = utm_to_lonlat(e, n, zone, south)
+            lons.append(lon)
+            lats.append(lat)
+    zw, ze = _zone_lon_range(zone, band)
+    bs, bn = _band_lat_range(band)
+    west, east = max(min(lons), zw), min(max(lons), ze)
+    s, n = max(min(lats), bs), min(max(lats), bn)
+    if west >= east or s >= n:
+        raise ValueError(f"MGRS square {text!r} lies outside its zone and band")
+    w = wrap_lon(west) if west < -180.0 else west
+    e = wrap_lon(east) if east > 180.0 else east
+    return (w, s, e, n)
+
+
+def encode(lon: float, lat: float, precision: int = 5) -> str:
+    """MGRS reference of a point; ``precision`` digits per axis (0 = 100 km)."""
+    if not 0 <= precision <= 5:
+        raise ValueError("MGRS precision must be 0..5")
+    band = band_letter(lat)
+    zone = utm_zone(lon, lat)
+    south = lat < 0
+    easting, northing = lonlat_to_utm(lon, lat, zone, south)
+    col_set = _COL_SETS[(zone - 1) % 3]
+    col_i = int(easting // 100000.0) - 1
+    if not 0 <= col_i < len(col_set):
+        raise ValueError("point is outside the UTM zone's easting range")
+    row_offset = 5 if zone % 2 == 0 else 0
+    row_i = (int(northing // 100000.0) + row_offset) % 20
+    ref = f"{zone:02d}{band}{col_set[col_i]}{_ROWS[row_i]}"
+    if precision:
+        size = 10.0 ** (5 - precision)
+        e = int((easting % 100000.0) // size)
+        n = int((northing % 100000.0) // size)
+        ref += f"{e:0{precision}d}{n:0{precision}d}"
+    return ref

bboxkit/nominatim.py

@@ -0,0 +1,113 @@
+"""Optional place-name lookup through a Nominatim server.
+
+Nothing in bboxkit talks to the network unless you call this module
+explicitly. The public server at nominatim.openstreetmap.org has a usage
+policy (https://operations.osmfoundation.org/policies/nominatim/) that this
+client follows:
+
+* at most one request per second (enforced per process),
+* an identifying ``User-Agent`` (set your own, ideally with a contact),
+* results are cached in memory so repeated queries are not re-sent,
+* no bulk geocoding: use your own Nominatim instance for that (``base_url``).
+
+Results are (c) OpenStreetMap contributors, ODbL 1.0.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from ._version import __version__
+from .bbox import BBox
+
+__all__ = ["NOMINATIM_URL", "DEFAULT_USER_AGENT", "search", "geocode_bbox", "clear_cache"]
+
+NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
+DEFAULT_USER_AGENT = f"bboxkit/{__version__} (+https://github.com/YusufEminoglu/bboxkit_sdk)"
+MIN_INTERVAL_S = 1.0
+_CACHE_SIZE = 256
+
+_lock = threading.Lock()
+_last_request = 0.0
+_cache: OrderedDict[Tuple[Any, ...], List[Dict[str, Any]]] = OrderedDict()
+
+
+def clear_cache() -> None:
+    """Forget cached lookups."""
+    with _lock:
+        _cache.clear()
+
+
+def _throttle() -> None:
+    global _last_request
+    wait = _last_request + MIN_INTERVAL_S - time.monotonic()
+    if wait > 0:
+        time.sleep(wait)
+    _last_request = time.monotonic()
+
+
+def search(
+    query: str,
+    *,
+    limit: int = 1,
+    user_agent: Optional[str] = None,
+    email: Optional[str] = None,
+    timeout: float = 10.0,
+    base_url: str = NOMINATIM_URL,
+    accept_language: Optional[str] = None,
+    country_codes: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Run a Nominatim free-text search and return the decoded JSON results."""
+    q = query.strip()
+    if not q:
+        raise ValueError("empty query")
+    if not 1 <= limit <= 40:
+        raise ValueError("limit must be 1..40")
+    if timeout <= 0:
+        raise ValueError("timeout must be positive")
+    params: Dict[str, str] = {"q": q, "format": "jsonv2", "limit": str(limit)}
+    if email:
+        params["email"] = email
+    if accept_language:
+        params["accept-language"] = accept_language
+    if country_codes:
+        params["countrycodes"] = country_codes
+    key = (base_url, tuple(sorted(params.items())))
+    with _lock:
+        if key in _cache:
+            _cache.move_to_end(key)
+            return list(_cache[key])
+        _throttle()
+        url = f"{base_url}?{urlencode(params)}"
+        req = Request(
+            url,
+            headers={"User-Agent": user_agent or DEFAULT_USER_AGENT, "Accept": "application/json"},
+        )
+        with urlopen(req, timeout=timeout) as resp:  # noqa: S310 - https URL built above
+            data = json.loads(resp.read().decode("utf-8"))
+        if not isinstance(data, list):
+            raise ValueError("unexpected Nominatim response")
+        _cache[key] = data
+        while len(_cache) > _CACHE_SIZE:
+            _cache.popitem(last=False)
+        return list(data)
+
+
+def geocode_bbox(query: str, **kwargs: Any) -> BBox:
+    """Bounding box of the best Nominatim match for a place name.
+
+    Keyword arguments are passed to :func:`search`. Raises ``LookupError``
+    when nothing matches.
+    """
+    kwargs.setdefault("limit", 1)
+    results = search(query, **kwargs)
+    if not results:
+        raise LookupError(f"no Nominatim result for {query!r}")
+    s, n, w, e = (float(v) for v in results[0]["boundingbox"])
+    return BBox(w, s, e, n)