bboxkit 0.1.0__py3-none-any.whl

bboxkit/parsing.py

@@ -0,0 +1,722 @@
+"""Parse bounding boxes from strings, URLs, GeoJSON, WKT, tiles and grid codes."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import sys
+import warnings
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple
+from urllib.parse import parse_qs, urlsplit
+
+from . import geohash as _geohash
+from . import mgrs as _mgrs
+from . import pluscode as _pluscode
+from . import tiles as _tiles
+from ._geo import MERCATOR_MAX_LAT, Arc, component_arc, covering_arc, lon_arc, snap_arc_edges
+from .bbox import BBox
+from .crs import WGS84, CRSLike, is_geographic, normalize_crs
+
+__all__ = [
+    "AmbiguousOrderWarning",
+    "parse",
+    "parse_numbers",
+    "parse_bboxfinder",
+    "parse_overpass",
+    "parse_osm_url",
+    "parse_wkt",
+    "parse_geojson",
+    "parse_gdal",
+    "parse_leaflet",
+    "parse_mapbox",
+    "parse_tile",
+    "parse_quadkey",
+    "parse_geohash",
+    "parse_pluscode",
+    "parse_mgrs",
+    "parse_postgis",
+    "PARSERS",
+]
+
+Viewport = Tuple[int, int]
+
+
+_PKG_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+def _warn(message: str) -> None:
+    """Warn with the location of the first caller outside bboxkit."""
+    level = 1
+    frame = sys._getframe(0)
+    while frame is not None and os.path.abspath(frame.f_code.co_filename).startswith(_PKG_DIR):
+        frame = frame.f_back  # type: ignore[assignment]
+        level += 1
+    warnings.warn(message, AmbiguousOrderWarning, stacklevel=level)
+
+
+class AmbiguousOrderWarning(UserWarning):
+    """Four numbers could be read both as W,S,E,N and as S,W,N,E.
+
+    Pass ``order="wsen"`` or ``order="swne"`` to state the order explicitly
+    (and silence the warning).
+    """
+
+
+_NUM = r"[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?"
+_NUM_RE = re.compile(_NUM)
+_NUMS_ONLY = re.compile(rf"^\s*{_NUM}(?:\s*[,;\s]\s*{_NUM})*\s*$")
+_CRS_TAIL = re.compile(
+    r"^(?P<body>.*?)[\s,;]+(?P<crs>(?:EPSG|ESRI|OGC|CRS84|urn:ogc|https?://www\.opengis)\S*)\s*$",
+    re.IGNORECASE,
+)
+_WKT_RE = re.compile(
+    r"^\s*(?:SRID=(?P<srid>\d+)\s*;)?\s*(?P<kind>POINT|LINESTRING|POLYGON|MULTIPOINT|"
+    r"MULTILINESTRING|MULTIPOLYGON|GEOMETRYCOLLECTION|ENVELOPE|BOX3D|BOX2D|BOX)\b",
+    re.IGNORECASE,
+)
+_OVERPASS_RE = re.compile(
+    rf"^\s*(?:\[\s*bbox\s*:\s*(?P<a>{_NUM}(?:\s*,\s*{_NUM}){{3}})\s*\]\s*;?"
+    rf"|\(\s*(?P<b>{_NUM}(?:\s*,\s*{_NUM}){{3}})\s*\))\s*$",
+    re.IGNORECASE,
+)
+_TILE_RE = re.compile(r"^\s*(?:tile:)?(\d{1,2})/(\d+)/(\d+)(?:@\dx)?(?:\.\w+)?\s*$", re.IGNORECASE)
+_TILE_URL_RE = re.compile(r"/(\d{1,2})/(\d+)/(\d+)(?:@\dx)?(?:\.\w+)?(?:\?.*)?$")
+_PLUS_RE = re.compile(r"^\s*[23456789CFGHJMPQRVWX0]{2,8}\+[23456789CFGHJMPQRVWX]*\s*$", re.I)
+_QUADKEY_RE = re.compile(r"^[0-3]{1,30}$")
+_GEOHASH_RE = re.compile(r"^[0-9b-hjkmnp-z]{1,22}$")
+_GDAL_RE = re.compile(r"(?:^|\s)-(?:te|projwin|spat)\s")
+_POSTGIS_RE = re.compile(r"^\s*(?:ST_)?MakeEnvelope\s*\((?P<args>[^)]*)\)\s*;?\s*$", re.I)
+
+
+# --------------------------------------------------------------------------
+# Plain numbers and the W,S,E,N / S,W,N,E question
+# --------------------------------------------------------------------------
+
+
+def _plausible(w: float, s: float, e: float, n: float, unwrapped: bool) -> bool:
+    lon_ok = -180.0 <= w <= 180.0 and (-180.0 <= e <= 180.0 or (unwrapped and w <= e <= w + 360.0))
+    return lon_ok and -90.0 <= s <= n <= 90.0
+
+
+def _build(w: float, s: float, e: float, n: float, crs: str, unwrapped: bool = False) -> BBox:
+    if unwrapped and e > 180.0 and w <= e:
+        return BBox.wrap(w, s, e, n, crs=crs)
+    return BBox(w, s, e, n, crs=crs)
+
+
+def _from_four(
+    vals: Sequence[float],
+    order: Optional[str],
+    crs: str,
+    default: str = "wsen",
+    unwrapped: bool = False,
+) -> BBox:
+    if len(vals) != 4:
+        raise ValueError(f"expected 4 numbers, got {len(vals)}")
+    a, b, c, d = (float(v) for v in vals)
+    readings = {"wsen": (a, b, c, d), "swne": (b, a, d, c)}
+    if order is not None:
+        key = order.lower().replace(",", "").replace(" ", "")
+        if key not in readings:
+            raise ValueError("order must be 'wsen' or 'swne'")
+        return _build(*readings[key], crs=crs, unwrapped=unwrapped)
+    if not is_geographic(crs):
+        return _build(*readings["wsen"], crs=crs)
+
+    def score(key: str) -> Tuple[bool, bool]:
+        w, s, e, n = readings[key]
+        ok = _plausible(w, s, e, n, unwrapped)
+        return (ok, ok and w <= e)
+
+    other = "swne" if default == "wsen" else "wsen"
+    s_def, s_oth = score(default), score(other)
+    chosen = other if s_oth > s_def else default
+    loser = other if chosen == default else default
+    ambiguous = score(loser)[0] and readings["wsen"] != readings["swne"]
+    if ambiguous:
+        names = {"wsen": "west,south,east,north", "swne": "south,west,north,east"}
+        _warn(
+            f"{a:g},{b:g},{c:g},{d:g} is ambiguous; read as {names[chosen]}. "
+            f"Pass order='{chosen}' or order='{loser}' to be explicit."
+        )
+    return _build(*readings[chosen], crs=crs, unwrapped=unwrapped)
+
+
+def _numbers(text: str) -> List[float]:
+    return [float(x) for x in _NUM_RE.findall(text)]
+
+
+def parse_numbers(text: Any, order: Optional[str] = None, crs: CRSLike = WGS84) -> BBox:
+    """Four numbers as text (``"29,40.9,29.2,41.1"``) or a sequence.
+
+    Without ``order`` the reading that gives a valid, non-crossing box wins;
+    W,S,E,N is assumed when both orders are valid, with an
+    :class:`AmbiguousOrderWarning`.
+    """
+    c = normalize_crs(crs)
+    if isinstance(text, str):
+        m = _CRS_TAIL.match(text)
+        if m:
+            text, c = m.group("body"), normalize_crs(m.group("crs"))
+        vals = _numbers(text)
+    else:
+        vals = [float(v) for v in text]
+    return _from_four(vals, order, c)
+
+
+# --------------------------------------------------------------------------
+# Web formats
+# --------------------------------------------------------------------------
+
+
+def parse_bboxfinder(text: str) -> BBox:
+    """bboxfinder.com URL; its fragment is ``#south,west,north,east``."""
+    frag = urlsplit(text.strip()).fragment or text
+    return _from_four(_numbers(frag), "swne", WGS84)
+
+
+def parse_overpass(text: str) -> BBox:
+    """Overpass QL ``(s,w,n,e)`` filter or ``[bbox:s,w,n,e]`` setting."""
+    m = _OVERPASS_RE.match(text)
+    if not m:
+        raise ValueError(f"{text!r} is not an Overpass bbox")
+    return _from_four(_numbers(m.group("a") or m.group("b")), "swne", WGS84)
+
+
+def _map_view_bbox(zoom: float, lat: float, lon: float, viewport: Viewport) -> BBox:
+    vw, vh = viewport
+    if vw <= 0 or vh <= 0:
+        raise ValueError("viewport must be positive")
+    scale = 256.0 * 2.0**zoom
+    dx = vw / 2.0 / scale * 360.0
+    lat_c = max(-MERCATOR_MAX_LAT, min(MERCATOR_MAX_LAT, lat))
+    yc = (1.0 - math.asinh(math.tan(math.radians(lat_c))) / math.pi) / 2.0
+    half = vh / 2.0 / scale
+    y_top, y_bot = max(0.0, yc - half), min(1.0, yc + half)
+
+    def lat_of(y: float) -> float:
+        return math.degrees(math.atan(math.sinh(math.pi * (1.0 - 2.0 * y))))
+
+    return BBox.wrap(lon - dx, lat_of(y_bot), lon + dx, lat_of(y_top))
+
+
+def parse_osm_url(text: str, viewport: Viewport = (1024, 768)) -> BBox:
+    """OpenStreetMap-style URL.
+
+    Understands ``bbox=W,S,E,N`` (OSM API, many WFS/REST services),
+    ``minlon=&minlat=&maxlon=&maxlat=`` and ``map=zoom/lat/lon`` in the query
+    or fragment; a ``map=`` view is turned into the area a ``viewport``
+    (pixels, default 1024 x 768) shows at that zoom.
+    """
+    parts = urlsplit(text.strip())
+    params: Dict[str, List[str]] = {}
+    for chunk in (parts.query, parts.fragment):
+        for k, v in parse_qs(chunk).items():
+            params.setdefault(k.lower(), v)
+    if "bbox" in params:
+        return _from_four(_numbers(params["bbox"][0]), "wsen", WGS84)
+    keys = ("minlon", "minlat", "maxlon", "maxlat")
+    if all(k in params for k in keys):
+        w, s, e, n = (float(params[k][0]) for k in keys)
+        return BBox(w, s, e, n)
+    if "map" in params:
+        nums = _numbers(params["map"][0])
+        if len(nums) >= 3:
+            return _map_view_bbox(nums[0], nums[1], nums[2], viewport)
+    raise ValueError(f"no bbox=, minlon/minlat/maxlon/maxlat or map= found in {text!r}")
+
+
+def _pairs(value: Any) -> List[float]:
+    if isinstance(value, str):
+        value = json.loads(value)
+    if (
+        isinstance(value, (list, tuple))
+        and len(value) == 2
+        and all(isinstance(p, (list, tuple)) and len(p) == 2 for p in value)
+    ):
+        return [float(value[0][0]), float(value[0][1]), float(value[1][0]), float(value[1][1])]
+    raise ValueError("expected a pair of pairs like [[a, b], [c, d]]")
+
+
+def parse_leaflet(value: Any) -> BBox:
+    """Leaflet / Google ``[[south, west], [north, east]]`` (east may exceed 180)."""
+    return _from_four(_pairs(value), "swne", WGS84, unwrapped=True)
+
+
+def parse_mapbox(value: Any) -> BBox:
+    """Mapbox / MapLibre ``[[west, south], [east, north]]`` (east may exceed 180)."""
+    return _from_four(_pairs(value), "wsen", WGS84, unwrapped=True)
+
+
+def parse_gdal(text: str, crs: Optional[CRSLike] = None) -> BBox:
+    """GDAL/OGR arguments: ``-te xmin ymin xmax ymax``, ``-projwin ulx uly lrx lry``
+    or ``-spat xmin ymin xmax ymax``, optionally with ``-te_srs`` / ``-projwin_srs``
+    / ``-spat_srs`` (``-t_srs`` is used for ``-te`` when no ``-te_srs`` is given).
+    A whole command line works too.
+    """
+    tokens = text.split()
+    found: Optional[Tuple[str, List[float]]] = None
+    srs: Dict[str, str] = {}
+    for i, tok in enumerate(tokens):
+        key = tok.lower()
+        if key in ("-te", "-projwin", "-spat") and found is None:
+            nums = tokens[i + 1 : i + 5]
+            if len(nums) < 4:
+                raise ValueError(f"{tok} needs four numbers")
+            found = (key, [float(x) for x in nums])
+        elif key in ("-te_srs", "-projwin_srs", "-spat_srs", "-t_srs") and i + 1 < len(tokens):
+            srs[key] = tokens[i + 1].strip("'\"")
+    if found is None:
+        raise ValueError("no -te, -projwin or -spat option found")
+    key, v = found
+    src = srs.get(key + "_srs") or (srs.get("-t_srs") if key == "-te" else None)
+    c = normalize_crs(src) if src else normalize_crs(crs if crs is not None else WGS84)
+    if key == "-projwin":
+        return BBox(v[0], v[3], v[2], v[1], crs=c)
+    return BBox(v[0], v[1], v[2], v[3], crs=c)
+
+
+def parse_postgis(text: str, crs: Optional[CRSLike] = None) -> BBox:
+    """PostGIS ``ST_MakeEnvelope(xmin, ymin, xmax, ymax[, srid])``."""
+    m = _POSTGIS_RE.match(text)
+    if not m:
+        raise ValueError(f"{text!r} is not an ST_MakeEnvelope call")
+    nums = _numbers(m.group("args"))
+    if len(nums) not in (4, 5):
+        raise ValueError("ST_MakeEnvelope needs 4 numbers and an optional SRID")
+    c: CRSLike = crs if crs is not None else WGS84
+    if len(nums) == 5 and int(nums[4]) > 0:
+        c = int(nums[4])
+    return BBox(nums[0], nums[1], nums[2], nums[3], crs=c)
+
+
+# --------------------------------------------------------------------------
+# Geometry: GeoJSON and WKT
+# --------------------------------------------------------------------------
+
+
+class _Extent:
+    """Accumulates longitude arcs and latitudes of geometry components."""
+
+    def __init__(self, geographic: bool) -> None:
+        self.geographic = geographic
+        self.arcs: List[Arc] = []
+        self.xs: List[float] = []
+        self.ys: List[float] = []
+
+    def add_component(self, coords: Sequence[Sequence[float]]) -> None:
+        if any(len(p) < 2 for p in coords):
+            raise ValueError("every position needs at least two coordinates")
+        pts = [(float(p[0]), float(p[1])) for p in coords]
+        if not pts:
+            return
+        xs = [p[0] for p in pts]
+        self.ys.extend(p[1] for p in pts)
+        self.xs.extend(xs)
+        if self.geographic:
+            self.arcs.append(component_arc(xs))
+
+    def add_bbox(self, w: float, s: float, e: float, n: float) -> None:
+        self.ys.extend((s, n))
+        self.xs.extend((w, e))
+        if self.geographic:
+            self.arcs.append(lon_arc(w, e))
+
+    def result(self, crs: str) -> BBox:
+        if not self.ys:
+            raise ValueError("geometry is empty")
+        s, n = min(self.ys), max(self.ys)
+        if not self.geographic:
+            return BBox(min(self.xs), s, max(self.xs), n, crs=crs)
+        w, e = snap_arc_edges(covering_arc(self.arcs), self.xs, self.xs)
+        return BBox(w, s, e, n, crs=crs)
+
+
+def _geojson_bbox(value: Sequence[Any]) -> Tuple[float, float, float, float]:
+    vals = [float(v) for v in value]
+    if len(vals) == 4:
+        return (vals[0], vals[1], vals[2], vals[3])
+    if len(vals) == 6:
+        return (vals[0], vals[1], vals[3], vals[4])
+    raise ValueError(f"a GeoJSON bbox has 4 or 6 numbers, got {len(vals)}")
+
+
+def _collect_geojson(obj: Any, ext: _Extent) -> None:
+    if not isinstance(obj, Mapping):
+        raise ValueError("GeoJSON objects must be JSON objects")
+    if obj.get("bbox") is not None:
+        ext.add_bbox(*_geojson_bbox(obj["bbox"]))
+        return
+    kind = obj.get("type")
+    coords = obj.get("coordinates")
+    if kind == "FeatureCollection":
+        for feat in obj.get("features") or []:
+            _collect_geojson(feat, ext)
+    elif kind == "Feature":
+        if obj.get("geometry") is not None:
+            _collect_geojson(obj["geometry"], ext)
+    elif kind == "GeometryCollection":
+        for geom in obj.get("geometries") or []:
+            _collect_geojson(geom, ext)
+    elif kind == "Point":
+        if coords:
+            ext.add_component([coords])
+    elif kind == "MultiPoint":
+        for p in coords or []:
+            ext.add_component([p])
+    elif kind == "LineString":
+        ext.add_component(coords or [])
+    elif kind == "MultiLineString":
+        for line in coords or []:
+            ext.add_component(line)
+    elif kind == "Polygon":
+        if coords:
+            ext.add_component(coords[0])
+    elif kind == "MultiPolygon":
+        for poly in coords or []:
+            if poly:
+                ext.add_component(poly[0])
+    else:
+        raise ValueError(f"unsupported GeoJSON type {kind!r}")
+
+
+def parse_geojson(obj: Any, crs: Optional[CRSLike] = None) -> BBox:
+    """Bounding box of any GeoJSON object (text or parsed).
+
+    A ``bbox`` member is used as is (``west > east`` crosses the antimeridian).
+    Otherwise the box is computed from the coordinates: a line or ring whose
+    consecutive vertices are more than 180 degrees apart crosses the
+    antimeridian, and separate parts are combined with the smallest covering
+    longitude range (RFC 7946, section 5.2).
+    """
+    if isinstance(obj, str):
+        obj = json.loads(obj)
+    c = normalize_crs(crs) if crs is not None else WGS84
+    ext = _Extent(is_geographic(c))
+    _collect_geojson(obj, ext)
+    return ext.result(c)
+
+
+def _wkt_points(group: str) -> List[Tuple[float, float]]:
+    pts = []
+    for chunk in group.split(","):
+        nums = _numbers(chunk)
+        if len(nums) < 2:
+            raise ValueError(f"bad WKT coordinate {chunk.strip()!r}")
+        pts.append((nums[0], nums[1]))
+    return pts
+
+
+def parse_wkt(text: str, crs: Optional[CRSLike] = None) -> BBox:
+    """Bounding box of WKT/EWKT, ``ENVELOPE(minx, maxx, maxy, miny)`` or ``BOX(...)``.
+
+    ``SRID=xxxx;`` sets the CRS. Antimeridian handling follows
+    :func:`parse_geojson`.
+    """
+    m = _WKT_RE.match(text)
+    if not m:
+        raise ValueError(f"{text[:40]!r} is not WKT")
+    kind = m.group("kind").upper()
+    c = normalize_crs(int(m.group("srid"))) if m.group("srid") else normalize_crs(crs or WGS84)
+    body = text[m.end() :]
+    if re.search(r"\bEMPTY\b", body, re.IGNORECASE):
+        raise ValueError("geometry is empty")
+    if kind == "ENVELOPE":
+        nums = _numbers(body)
+        if len(nums) != 4:
+            raise ValueError("ENVELOPE needs 4 numbers: minX, maxX, maxY, minY")
+        return BBox(nums[0], nums[3], nums[1], nums[2], crs=c)
+    if kind.startswith("BOX"):
+        groups = re.findall(r"\(([^()]*)\)", body)
+        if len(groups) != 1:
+            raise ValueError("BOX needs one coordinate list")
+        pts = _wkt_points(groups[0])
+        if len(pts) != 2:
+            raise ValueError("BOX needs two corners")
+        return BBox(pts[0][0], pts[0][1], pts[1][0], pts[1][1], crs=c)
+    ext = _Extent(is_geographic(c))
+    groups = re.findall(r"\(([^()]*)\)", body)
+    if not groups:
+        raise ValueError("no coordinates found in WKT")
+    if kind == "MULTIPOINT":
+        for g in groups:
+            for p in _wkt_points(g):
+                ext.add_component([p])
+    else:
+        for g in groups:
+            ext.add_component(_wkt_points(g))
+    return ext.result(c)
+
+
+# --------------------------------------------------------------------------
+# Grid cells
+# --------------------------------------------------------------------------
+
+
+def parse_tile(text: Any) -> BBox:
+    """XYZ tile ``"z/x/y"`` (also a tile URL, or a ``(x, y, z)`` Tile)."""
+    if isinstance(text, _tiles.Tile):
+        return BBox(*text.bounds)
+    if not isinstance(text, str):
+        raise TypeError("expected 'z/x/y' text or a Tile")
+    m = _TILE_RE.match(text) or _TILE_URL_RE.search(text.strip())
+    if not m:
+        raise ValueError(f"{text!r} is not a z/x/y tile")
+    z, x, y = int(m.group(1)), int(m.group(2)), int(m.group(3))
+    return BBox(*_tiles.tile_bounds(x, y, z))
+
+
+def parse_quadkey(text: str) -> BBox:
+    """Bing Maps quadkey (digits 0-3)."""
+    t = _tiles.quadkey_to_tile(_strip_prefix(text))
+    return BBox(*t.bounds)
+
+
+def parse_geohash(text: str) -> BBox:
+    """Geohash cell."""
+    return BBox(*_geohash.decode_bounds(_strip_prefix(text)))
+
+
+def parse_pluscode(text: str) -> BBox:
+    """Full Open Location Code (Plus Code) area, e.g. ``"8FVC9G8F+6W"``."""
+    return BBox(*_pluscode.decode_bounds(_strip_prefix(text)))
+
+
+def parse_mgrs(text: str) -> BBox:
+    """MGRS grid square, e.g. ``"35TPF"`` (100 km) or ``"35TPF6654"`` (1 km)."""
+    return BBox(*_mgrs.square_bounds(_strip_prefix(text)))
+
+
+def _strip_prefix(text: str) -> str:
+    t = text.strip()
+    head, sep, tail = t.partition(":")
+    return tail.strip() if sep and head.lower() in _PREFIXES else t
+
+
+# --------------------------------------------------------------------------
+# Dictionaries
+# --------------------------------------------------------------------------
+
+
+def _lower_keys(obj: Mapping[str, Any]) -> Dict[str, Any]:
+    return {str(k).lower(): v for k, v in obj.items()}
+
+
+def _latlng(obj: Any) -> Tuple[float, float]:
+    d = _lower_keys(obj)
+    lat = d.get("lat", d.get("latitude"))
+    lng = d.get("lng", d.get("lon", d.get("longitude")))
+    if lat is None or lng is None:
+        raise ValueError("expected an object with lat and lng")
+    return (float(lng), float(lat))
+
+
+def _arcgis_crs(sr: Any) -> Optional[CRSLike]:
+    if isinstance(sr, Mapping):
+        wkid = sr.get("latestWkid") or sr.get("wkid")
+        if wkid:
+            return int(wkid)
+    return None
+
+
+def parse_mapping(
+    obj: Mapping[str, Any], order: Optional[str] = None, crs: Optional[CRSLike] = None
+) -> BBox:
+    """Dictionaries: GeoJSON, STAC, Nominatim results, ArcGIS extents,
+    Leaflet ``{_southWest, _northEast}``, Google ``{south, west, north, east}`` /
+    ``{southwest, northeast}`` and ``{minx, miny, maxx, maxy}``-style keys."""
+    d = _lower_keys(obj)
+    c = crs if crs is not None else WGS84
+    if "boundingbox" in d:  # Nominatim: [south, north, west, east] as strings
+        s, n, w, e = (float(v) for v in d["boundingbox"])
+        return BBox(w, s, e, n)
+    if "extent" in d and isinstance(d["extent"], Mapping):  # STAC collection
+        spatial = d["extent"].get("spatial", {})
+        boxes = spatial.get("bbox") if isinstance(spatial, Mapping) else None
+        if boxes:
+            return BBox(*_geojson_bbox(boxes[0]))
+    if "type" in d or "bbox" in d or "coordinates" in d:
+        return parse_geojson(obj, crs=crs)
+    for keys in (
+        ("west", "south", "east", "north"),
+        ("minx", "miny", "maxx", "maxy"),
+        ("xmin", "ymin", "xmax", "ymax"),
+        ("minlon", "minlat", "maxlon", "maxlat"),
+        ("min_lon", "min_lat", "max_lon", "max_lat"),
+        ("left", "bottom", "right", "top"),
+    ):
+        if all(k in d for k in keys):
+            sr = _arcgis_crs(d.get("spatialreference"))
+            w, s, e, n = (float(d[k]) for k in keys)
+            return BBox(w, s, e, n, crs=sr if sr is not None else c)
+    for sw, ne in (("_southwest", "_northeast"), ("southwest", "northeast"), ("sw", "ne")):
+        if sw in d and ne in d:
+            w, s = _latlng(d[sw])
+            e, n = _latlng(d[ne])
+            return _build(w, s, e, n, normalize_crs(c), unwrapped=True)
+    raise ValueError(f"unrecognised bbox mapping with keys {sorted(d)}")
+
+
+# --------------------------------------------------------------------------
+# Dispatch
+# --------------------------------------------------------------------------
+
+
+def _from_json_value(
+    value: Any, order: Optional[str], crs: Optional[CRSLike], pair_default: str
+) -> BBox:
+    if isinstance(value, Mapping):
+        return parse_mapping(value, order=order, crs=crs)
+    if isinstance(value, (list, tuple)):
+        if len(value) == 2 and all(isinstance(p, (list, tuple)) for p in value):
+            vals = _pairs(value)
+            c = normalize_crs(crs if crs is not None else WGS84)
+            return _from_four(vals, order, c, default=pair_default, unwrapped=True)
+        if len(value) == 6 and order is None:
+            return BBox(*_geojson_bbox(value), crs=crs if crs is not None else WGS84)
+        return parse_numbers(value, order=order, crs=crs if crs is not None else WGS84)
+    raise ValueError(f"cannot read a bbox from {type(value).__name__}")
+
+
+def _parse_text(
+    text: str, order: Optional[str], crs: Optional[CRSLike], viewport: Viewport
+) -> BBox:
+    t = text.strip()
+    if not t:
+        raise ValueError("empty bbox text")
+    head, sep, tail = t.partition(":")
+    if sep and head.lower() in _PREFIXES and not tail.startswith("//"):
+        return parse(tail.strip(), fmt=head.lower(), order=order, crs=crs, viewport=viewport)
+    if t[0] in "[{":
+        try:
+            value = json.loads(t)
+        except ValueError:
+            value = None
+        if value is not None:
+            return _from_json_value(value, order, crs, pair_default="swne")
+    low = t.lower()
+    if "bboxfinder.com" in low:
+        return parse_bboxfinder(t)
+    if _OVERPASS_RE.match(t):
+        return parse_overpass(t)
+    if _GDAL_RE.search(" " + t):
+        return parse_gdal(t, crs=crs)
+    if _POSTGIS_RE.match(t):
+        return parse_postgis(t, crs=crs)
+    if _WKT_RE.match(t):
+        return parse_wkt(t, crs=crs)
+    if re.match(r"^[a-z][a-z0-9+.-]*://", low) or low.startswith(("www.", "?", "#")):
+        if re.search(r"(?:[?#&]|^)(?:bbox|minlon|map)=", low):
+            return parse_osm_url(t, viewport=viewport)
+        if _TILE_URL_RE.search(t):
+            return parse_tile(t)
+        raise ValueError(f"no bounding box found in URL {t!r}")
+    if _TILE_RE.match(t):
+        return parse_tile(t)
+    if _PLUS_RE.match(t):
+        return parse_pluscode(t)
+    if _mgrs._PATTERN.match(t):
+        return parse_mgrs(t)
+    if (_NUMS_ONLY.match(t) and len(_NUM_RE.findall(t)) > 1) or _CRS_TAIL.match(t):
+        return parse_numbers(t, order=order, crs=crs if crs is not None else WGS84)
+    if _QUADKEY_RE.match(t):
+        return parse_quadkey(t)
+    if _GEOHASH_RE.match(t):
+        return parse_geohash(t)
+    raise ValueError(
+        f"could not recognise {t[:60]!r} as a bounding box. Place names need an explicit "
+        "lookup: bboxkit.nominatim.geocode_bbox(...)"
+    )
+
+
+def parse(
+    value: Any,
+    *,
+    fmt: Optional[str] = None,
+    order: Optional[str] = None,
+    crs: Optional[CRSLike] = None,
+    viewport: Viewport = (1024, 768),
+) -> BBox:
+    """Parse a bounding box from (almost) anything.
+
+    Accepts a :class:`BBox`, a string in any supported format (detected
+    automatically unless ``fmt`` names one of :data:`PARSERS`), a GeoJSON-like
+    or other bbox dictionary, an object with ``__geo_interface__``, a Shapely
+    or GeoPandas object (``.bounds`` / ``.total_bounds``), a :class:`Tile`, or
+    a sequence of four numbers. Never touches the network.
+
+    ``order`` (``"wsen"`` or ``"swne"``) settles four-number inputs; without it
+    the order is guessed and an :class:`AmbiguousOrderWarning` is emitted when
+    the guess could be wrong.
+    """
+    if isinstance(value, BBox):
+        return value if crs is None else value.to_crs(crs)
+    if isinstance(value, bytes):
+        value = value.decode("utf-8")
+    if fmt is not None:
+        name = fmt.lower().replace("_", "-")
+        if name in ("wsen", "swne") and order is None:
+            order = name
+        key = _PREFIXES.get(name, name)
+        if key not in PARSERS:
+            raise ValueError(f"unknown format {fmt!r}; choose from {', '.join(sorted(PARSERS))}")
+        if key == "numbers":
+            return parse_numbers(value, order=order, crs=crs if crs is not None else WGS84)
+        if key in ("osm",):
+            return parse_osm_url(value, viewport=viewport)
+        if key in ("wkt", "geojson", "gdal", "postgis"):
+            return PARSERS[key](value, crs=crs)
+        return PARSERS[key](value)
+    if isinstance(value, str):
+        return _parse_text(value, order, crs, viewport)
+    if isinstance(value, _tiles.Tile):
+        return parse_tile(value)
+    for attr in ("total_bounds", "bounds"):
+        bounds = getattr(value, attr, None)
+        if bounds is not None and not callable(bounds):
+            vals = [float(v) for v in bounds]
+            if len(vals) == 4 and all(math.isfinite(v) for v in vals):
+                return BBox(
+                    vals[0], vals[1], vals[2], vals[3], crs=crs if crs is not None else WGS84
+                )
+    geo = getattr(value, "__geo_interface__", None)
+    if isinstance(geo, Mapping):
+        return parse_geojson(geo, crs=crs)
+    return _from_json_value(value, order, crs, pair_default="swne")
+
+
+PARSERS: Dict[str, Callable[..., BBox]] = {
+    "numbers": parse_numbers,
+    "bboxfinder": parse_bboxfinder,
+    "overpass": parse_overpass,
+    "osm": parse_osm_url,
+    "wkt": parse_wkt,
+    "geojson": parse_geojson,
+    "gdal": parse_gdal,
+    "postgis": parse_postgis,
+    "leaflet": parse_leaflet,
+    "mapbox": parse_mapbox,
+    "tile": parse_tile,
+    "quadkey": parse_quadkey,
+    "geohash": parse_geohash,
+    "pluscode": parse_pluscode,
+    "mgrs": parse_mgrs,
+}
+"""Explicit parsers by format name (the ``fmt=`` argument of :func:`parse`)."""
+
+_PREFIXES: Dict[str, str] = {name: name for name in PARSERS}
+_PREFIXES.update(
+    {
+        "wsen": "numbers",
+        "swne": "numbers",
+        "xyz": "tile",
+        "plus": "pluscode",
+        "olc": "pluscode",
+        "gdal-te": "gdal",
+        "gdal-projwin": "gdal",
+        "envelope": "wkt",
+        "osm-url": "osm",
+    }
+)