bboxkit 0.1.0__py3-none-any.whl

bboxkit/bbox.py

@@ -0,0 +1,1029 @@
+"""The :class:`BBox` value type."""
+
+from __future__ import annotations
+
+import functools
+import math
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+)
+
+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,
+    arc_to_lons,
+    covering_arc,
+    lon_arc,
+    meridian_distance,
+    metres_to_dlat,
+    metres_to_dlon,
+    parallel_radius,
+    rectangle_area_m2,
+    snap_arc_edges,
+    unwrapped_to_lons,
+    wrap_delta,
+    wrap_lon,
+)
+from .crs import (
+    WEB_MERCATOR,
+    WGS84,
+    CRSLike,
+    _from_lonlat_fn,
+    _pyproj_transformer,
+    _to_lonlat_fn,
+    is_builtin,
+    is_geographic,
+    lonlat_to_mercator,
+    mercator_to_lonlat,
+    normalize_crs,
+    utm_crs,
+    utm_zone,
+)
+from .tiles import Tile
+
+__all__ = ["BBox", "union_all", "Number"]
+
+Number = Union[int, float]
+PointLike = Sequence[float]
+
+_EPS = 1e-12
+#: Upper bound on the number of boxes or tiles a single call may create.
+DEFAULT_MAX_ITEMS = 1_000_000
+
+
+@functools.lru_cache(maxsize=512)
+def _crs_info(crs: CRSLike) -> Tuple[str, bool]:
+    c = normalize_crs(crs)
+    return (c, is_geographic(c))
+
+
+def _num(value: float, precision: Optional[int] = None) -> str:
+    """Compact, exact (round-trippable) decimal text for a coordinate."""
+    if precision is not None:
+        value = round(value, precision)
+    if value == 0:
+        return "0"
+    text = repr(float(value))
+    if "e" in text or "E" in text:
+        text = f"{value:.17f}".rstrip("0").rstrip(".")
+    if text.endswith(".0"):
+        text = text[:-2]
+    return text
+
+
+def _coerce(name: str, value: Any) -> float:
+    if isinstance(value, (str, bytes, bool)) or value is None:
+        raise TypeError(f"{name} must be a number, got {value!r}")
+    try:
+        f = float(value)
+    except (TypeError, ValueError) as exc:
+        raise TypeError(f"{name} must be a number, got {value!r}") from exc
+    if not math.isfinite(f):
+        raise ValueError(f"{name} must be finite, got {value!r}")
+    return f + 0.0  # turns -0.0 into 0.0
+
+
+class BBox:
+    """An immutable, hashable bounding box ``(west, south, east, north, crs)``.
+
+    For geographic CRSs (longitude/latitude degrees, ``EPSG:4326`` by default)
+    ``west > east`` means the box crosses the antimeridian, exactly as in
+    RFC 7946. ``BBox(-180, s, 180, n)`` spans every longitude. Coordinates are
+    validated on construction and the object cannot be modified afterwards;
+    use :meth:`replace` to derive a new box.
+
+    ``==`` and ``hash`` are exact (so boxes work as dict keys and in sets);
+    use :meth:`equals` for a tolerance-based comparison.
+    """
+
+    __slots__ = ("west", "south", "east", "north", "crs", "_geographic")
+
+    west: float
+    south: float
+    east: float
+    north: float
+    crs: str
+    _geographic: bool
+
+    def __init__(
+        self,
+        west: Number,
+        south: Number,
+        east: Number,
+        north: Number,
+        crs: CRSLike = WGS84,
+    ) -> None:
+        c, geographic = _crs_info(crs)
+        w = _coerce("west", west)
+        s = _coerce("south", south)
+        e = _coerce("east", east)
+        n = _coerce("north", north)
+        if s > n:
+            raise ValueError(f"south ({s}) is greater than north ({n}); check the coordinate order")
+        if geographic:
+            if not (-90.0 <= s <= 90.0 and -90.0 <= n <= 90.0):
+                raise ValueError(f"latitudes must be within [-90, 90], got south={s}, north={n}")
+            if not (-180.0 <= w <= 180.0 and -180.0 <= e <= 180.0):
+                raise ValueError(
+                    f"longitudes must be within [-180, 180], got west={w}, east={e}"
+                    " (use BBox.wrap() for unwrapped longitudes)"
+                )
+            # Canonical spelling of the antimeridian edges.
+            if w == 180.0 and e < 180.0:
+                w = -180.0
+            if e == -180.0 and w > -180.0:
+                e = 180.0
+        elif w > e:
+            raise ValueError(
+                f"west ({w}) is greater than east ({e}); only geographic boxes may cross"
+                " the antimeridian"
+            )
+        for name, value in (
+            ("west", w),
+            ("south", s),
+            ("east", e),
+            ("north", n),
+            ("crs", c),
+            ("_geographic", geographic),
+        ):
+            object.__setattr__(self, name, value)
+
+    # ------------------------------------------------------------------
+    # Value-type plumbing
+    # ------------------------------------------------------------------
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError("BBox is immutable; use replace()")
+
+    def __delattr__(self, name: str) -> None:
+        raise AttributeError("BBox is immutable")
+
+    def __reduce__(self) -> Tuple[Any, Tuple[Any, ...]]:
+        return (BBox, (self.west, self.south, self.east, self.north, self.crs))
+
+    def _key(self) -> Tuple[float, float, float, float, str]:
+        return (self.west, self.south, self.east, self.north, self.crs)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, BBox):
+            return NotImplemented
+        return self._key() == other._key()
+
+    def __hash__(self) -> int:
+        return hash(self._key())
+
+    def __repr__(self) -> str:
+        suffix = "" if self.crs == WGS84 else f", crs={self.crs!r}"
+        return f"BBox({self.west!r}, {self.south!r}, {self.east!r}, {self.north!r}{suffix})"
+
+    def __str__(self) -> str:
+        return self.to_string()
+
+    def __iter__(self) -> Iterator[float]:
+        """Iterate ``west, south, east, north`` (so ``w, s, e, n = box`` works)."""
+        return iter((self.west, self.south, self.east, self.north))
+
+    def __round__(self, ndigits: Optional[int] = None) -> BBox:
+        return self.round(ndigits)
+
+    @property
+    def __geo_interface__(self) -> Dict[str, Any]:
+        """GeoJSON geometry, so ``shapely.geometry.shape(box)`` just works."""
+        return self.to_geojson()
+
+    def replace(self, **changes: Any) -> BBox:
+        """Return a copy with some of ``west/south/east/north/crs`` replaced."""
+        values: Dict[str, Any] = {
+            "west": self.west,
+            "south": self.south,
+            "east": self.east,
+            "north": self.north,
+            "crs": self.crs,
+        }
+        unknown = set(changes) - set(values)
+        if unknown:
+            raise TypeError(f"unknown field(s): {', '.join(sorted(unknown))}")
+        values.update(changes)
+        return BBox(**values)
+
+    def equals(self, other: BBox, tol: float = 1e-9) -> bool:
+        """Equality within ``tol`` (CRS units); longitudes compare modulo 360."""
+        if not isinstance(other, BBox):
+            return False
+        if self.crs != other.crs:
+            return False
+        if abs(self.south - other.south) > tol or abs(self.north - other.north) > tol:
+            return False
+        if self._geographic:
+            if self.is_full_longitude and other.is_full_longitude:
+                return True
+            return (
+                abs(self.width - other.width) <= 2 * tol
+                and abs(wrap_delta(self.west - other.west)) <= tol
+                and abs(wrap_delta(self.east - other.east)) <= tol
+            )
+        return abs(self.west - other.west) <= tol and abs(self.east - other.east) <= tol
+
+    # ------------------------------------------------------------------
+    # Construction helpers
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def parse(cls, value: Any, **kwargs: Any) -> BBox:
+        """Parse any supported representation; see :func:`bboxkit.parse`."""
+        from .parsing import parse
+
+        return parse(value, **kwargs)
+
+    @classmethod
+    def from_bounds(cls, bounds: Sequence[Number], crs: CRSLike = WGS84) -> BBox:
+        """From a ``(minx, miny, maxx, maxy)`` tuple, e.g. Shapely ``geom.bounds``."""
+        if len(bounds) != 4:
+            raise ValueError(f"expected 4 numbers, got {len(bounds)}")
+        return cls(bounds[0], bounds[1], bounds[2], bounds[3], crs=crs)
+
+    @classmethod
+    def wrap(
+        cls, west: Number, south: Number, east: Number, north: Number, crs: CRSLike = WGS84
+    ) -> BBox:
+        """Build a geographic box from unwrapped longitudes (e.g. ``170 .. 190``).
+
+        ``east - west >= 360`` gives the full longitude range; otherwise both
+        longitudes are wrapped into [-180, 180], which may produce a box that
+        crosses the antimeridian.
+        """
+        w, e = float(west), float(east)
+        if e < w:
+            raise ValueError("wrap() expects west <= east in unwrapped longitudes")
+        lo, hi = unwrapped_to_lons(w, e)
+        return cls(lo, south, hi, north, crs=crs)
+
+    @classmethod
+    def world(cls) -> BBox:
+        """The whole globe, ``(-180, -90, 180, 90)``."""
+        return cls(-180.0, -90.0, 180.0, 90.0)
+
+    @classmethod
+    def from_point(cls, lon: Number, lat: Number, crs: CRSLike = WGS84) -> BBox:
+        """A zero-size box at a point; combine with :meth:`buffer`."""
+        return cls(lon, lat, lon, lat, crs=crs)
+
+    # ------------------------------------------------------------------
+    # Basic properties
+    # ------------------------------------------------------------------
+
+    @property
+    def is_geographic(self) -> bool:
+        return self._geographic
+
+    @property
+    def crosses_antimeridian(self) -> bool:
+        return self._geographic and self.west > self.east
+
+    @property
+    def is_full_longitude(self) -> bool:
+        return self._geographic and self.west == -180.0 and self.east == 180.0
+
+    @property
+    def bounds(self) -> Tuple[float, float, float, float]:
+        """``(west, south, east, north)`` as a plain tuple."""
+        return (self.west, self.south, self.east, self.north)
+
+    @property
+    def width(self) -> float:
+        """East-west extent in CRS units (degrees across the antimeridian if needed)."""
+        if self._geographic:
+            return self._arc()[1]
+        return self.east - self.west
+
+    @property
+    def height(self) -> float:
+        return self.north - self.south
+
+    @property
+    def center(self) -> Tuple[float, float]:
+        """Midpoint ``(x, y)``; the longitude midpoint follows the antimeridian."""
+        if self._geographic:
+            start, width = self._arc()
+            mid = start + width / 2.0
+            lon = mid if mid <= 180.0 else mid - 360.0
+            return (lon, (self.south + self.north) / 2.0)
+        return ((self.west + self.east) / 2.0, (self.south + self.north) / 2.0)
+
+    @property
+    def width_m(self) -> float:
+        """Ground width along the central parallel, in metres (CRS units if projected)."""
+        if self._geographic:
+            return parallel_radius(self.center[1]) * math.radians(self.width)
+        return self.width
+
+    @property
+    def height_m(self) -> float:
+        """Ground height along a meridian, in metres (CRS units if projected)."""
+        if self._geographic:
+            return meridian_distance(self.north) - meridian_distance(self.south)
+        return self.height
+
+    def _arc(self) -> Arc:
+        return lon_arc(self.west, self.east)
+
+    def _same_crs(self, other: BBox) -> None:
+        if not isinstance(other, BBox):
+            raise TypeError(f"expected a BBox, got {type(other).__name__}")
+        if other.crs != self.crs:
+            raise ValueError(
+                f"CRS mismatch: {self.crs} vs {other.crs}; convert one with to_crs() first"
+            )
+
+    def _from_lon_arc(self, arc: Arc, south: float, north: float) -> BBox:
+        w, e = arc_to_lons(arc)
+        return BBox(w, south, e, north, crs=self.crs)
+
+    def parts(self) -> Tuple[BBox, ...]:
+        """Split at the antimeridian: one box, or two if it crosses."""
+        if not self.crosses_antimeridian:
+            return (self,)
+        return (
+            BBox(self.west, self.south, 180.0, self.north, crs=self.crs),
+            BBox(-180.0, self.south, self.east, self.north, crs=self.crs),
+        )
+
+    split_antimeridian = parts
+
+    # ------------------------------------------------------------------
+    # Predicates and set operations
+    # ------------------------------------------------------------------
+
+    def contains(self, other: Union[BBox, PointLike]) -> bool:
+        """True if ``other`` (a box or an ``(x, y)`` point) lies inside, edges included."""
+        if not isinstance(other, BBox):
+            x, y = float(other[0]), float(other[1])
+            if not self.south - _EPS <= y <= self.north + _EPS:
+                return False
+            if self._geographic:
+                start, width = self._arc()
+                return (x - start) % 360.0 <= width + _EPS or width >= 360.0
+            return self.west - _EPS <= x <= self.east + _EPS
+        self._same_crs(other)
+        if other.south < self.south - _EPS or other.north > self.north + _EPS:
+            return False
+        if not self._geographic:
+            return self.west - _EPS <= other.west and other.east <= self.east + _EPS
+        s_start, s_width = self._arc()
+        o_start, o_width = other._arc()
+        if s_width >= 360.0:
+            return True
+        if o_width > s_width + _EPS:
+            return False
+        offset = (o_start - s_start) % 360.0
+        if offset > 360.0 - _EPS:
+            offset = 0.0
+        return offset + o_width <= s_width + 1e-9
+
+    def __contains__(self, item: Union[BBox, PointLike]) -> bool:
+        return self.contains(item)
+
+    def intersects(self, other: BBox) -> bool:
+        """True if the boxes share at least one point (touching counts)."""
+        self._same_crs(other)
+        if other.south > self.north or other.north < self.south:
+            return False
+        if not self._geographic:
+            return other.west <= self.east and other.east >= self.west
+        return bool(self._lon_overlaps(other))
+
+    def _lon_overlaps(self, other: BBox) -> List[Tuple[float, float]]:
+        s_start, s_width = self._arc()
+        o_start, o_width = other._arc()
+        if s_width >= 360.0:
+            return [(o_start, o_start + o_width)]
+        if o_width >= 360.0:
+            return [(s_start, s_start + s_width)]
+        lo_s, hi_s = s_start, s_start + s_width
+        out: List[Tuple[float, float]] = []
+        for k in (-1, 0, 1):
+            lo_o = o_start + 360.0 * k
+            hi_o = lo_o + o_width
+            lo, hi = max(lo_s, lo_o), min(hi_s, hi_o)
+            if lo <= hi and (lo, hi) not in out:
+                out.append((lo, hi))
+        return out
+
+    def intersection_parts(self, other: BBox) -> List[BBox]:
+        """All pieces of the intersection (two when wide boxes overlap at both ends)."""
+        self._same_crs(other)
+        s, n = max(self.south, other.south), min(self.north, other.north)
+        if s > n:
+            return []
+        if not self._geographic:
+            w, e = max(self.west, other.west), min(self.east, other.east)
+            return [BBox(w, s, e, n, crs=self.crs)] if w <= e else []
+        return [
+            self._from_lon_arc((wrap_lon(lo), hi - lo), s, n)
+            for lo, hi in self._lon_overlaps(other)
+        ]
+
+    def intersection(self, other: BBox) -> Optional[BBox]:
+        """The common box, or ``None`` if the boxes do not meet.
+
+        Raises ``ValueError`` in the rare case where the overlap is two separate
+        pieces (see :meth:`intersection_parts`).
+        """
+        pieces = self.intersection_parts(other)
+        if not pieces:
+            return None
+        if len(pieces) > 1:
+            raise ValueError(
+                "the intersection consists of two separate boxes; use intersection_parts()"
+            )
+        return pieces[0]
+
+    def __and__(self, other: BBox) -> Optional[BBox]:
+        return self.intersection(other)
+
+    def union(self, *others: BBox) -> BBox:
+        """Smallest box containing this box and ``others`` (antimeridian-aware)."""
+        return union_all((self,) + others)
+
+    def __or__(self, other: BBox) -> BBox:
+        return self.union(other)
+
+    # ------------------------------------------------------------------
+    # Measurements and transformations
+    # ------------------------------------------------------------------
+
+    def area_km2(self) -> float:
+        """Area in square kilometres.
+
+        Geographic boxes use the exact area of a lat/lon rectangle on the WGS 84
+        ellipsoid. Web Mercator boxes are converted to lon/lat first. Other
+        projected boxes return ``width * height / 1e6`` in CRS units (metres for
+        UTM, i.e. grid area).
+        """
+        if self._geographic:
+            return rectangle_area_m2(self.width, self.south, self.north) / 1e6
+        if self.crs == WEB_MERCATOR:
+            return self.to_crs(WGS84).area_km2()
+        return self.width * self.height / 1e6
+
+    def buffer(self, distance: float) -> BBox:
+        """Grow (or shrink, if negative) the box by ``distance`` metres on every side.
+
+        Geographic boxes use the local radii of curvature of WGS 84 so that every
+        point within ``distance`` of the box ends up inside it; the longitude
+        margin is taken at the most poleward latitude. Boxes reaching a pole get
+        the full longitude range. Projected boxes are buffered in CRS units.
+        """
+        d = float(distance)
+        if not math.isfinite(d):
+            raise ValueError("distance must be finite")
+        if not self._geographic:
+            w, s, e, n = self.west - d, self.south - d, self.east + d, self.north + d
+            if w > e or s > n:
+                raise ValueError("negative buffer collapses the box")
+            return BBox(w, s, e, n, crs=self.crs)
+        if d >= 0:
+            s = max(-90.0, self.south - metres_to_dlat(d, self.south))
+            n = min(90.0, self.north + metres_to_dlat(d, self.north))
+            pole_lat = max(abs(s), abs(n))
+            if pole_lat >= 90.0 - 1e-9 or self.is_full_longitude:
+                return BBox(-180.0, s, 180.0, n, crs=self.crs)
+            dlon = metres_to_dlon(d, pole_lat)
+            start, width = self._arc()
+            if width + 2 * dlon >= 360.0:
+                return BBox(-180.0, s, 180.0, n, crs=self.crs)
+            return self._from_lon_arc((wrap_lon(start - dlon), width + 2 * dlon), s, n)
+        m = -d
+        s = self.south + metres_to_dlat(m, self.south)
+        n = self.north - metres_to_dlat(m, self.north)
+        if s > n:
+            raise ValueError("negative buffer collapses the box")
+        equator_lat = 0.0 if s <= 0.0 <= n else min(abs(s), abs(n))
+        dlon = metres_to_dlon(m, equator_lat)
+        start, width = self._arc()
+        if 2 * dlon > width:
+            raise ValueError("negative buffer collapses the box")
+        return self._from_lon_arc((wrap_lon(start + dlon), width - 2 * dlon), s, n)
+
+    def round(self, ndigits: Optional[int] = None) -> BBox:
+        """Round every coordinate (``round(box, 4)`` works too)."""
+        vals = [float(round(v, ndigits)) for v in self]
+        return BBox(vals[0], vals[1], vals[2], vals[3], crs=self.crs)
+
+    def snap(self, step: float, outward: bool = True) -> BBox:
+        """Snap the edges to multiples of ``step`` (outward keeps the box covered)."""
+        if not step > 0:
+            raise ValueError("step must be positive")
+        lo_fn: Callable[[float], float]
+        hi_fn: Callable[[float], float]
+        if outward:
+
+            def lo_fn(v: float) -> float:
+                return math.floor(v / step + 1e-9) * step
+
+            def hi_fn(v: float) -> float:
+                return math.ceil(v / step - 1e-9) * step
+        else:
+
+            def lo_fn(v: float) -> float:
+                return round(v / step) * step
+
+            hi_fn = lo_fn
+
+        def clean(v: float) -> float:
+            return float(round(v, 12))
+
+        s, n = clean(lo_fn(self.south)), clean(hi_fn(self.north))
+        if not self._geographic:
+            return BBox(clean(lo_fn(self.west)), s, clean(hi_fn(self.east)), n, crs=self.crs)
+        s, n = max(-90.0, s), min(90.0, n)
+        if s > n:
+            s = n = clean(lo_fn((self.south + self.north) / 2.0))
+        start, width = self._arc()
+        lo, hi = clean(lo_fn(start)), clean(hi_fn(start + width))
+        if hi < lo:
+            hi = lo
+        w, e = (clean(v) for v in unwrapped_to_lons(lo, hi))
+        return BBox(max(-180.0, w), s, min(180.0, e), n, crs=self.crs)
+
+    def expand_to_aspect(self, ratio: float, mode: str = "mercator") -> BBox:
+        """Grow the box (never shrink) about its centre to ``width / height == ratio``.
+
+        ``mode`` picks the space the ratio is measured in: ``"mercator"`` (what a
+        web map shows), ``"ground"`` (metres on the ground) or ``"degrees"``.
+        Projected boxes always use CRS units.
+        """
+        if not ratio > 0 or not math.isfinite(ratio):
+            raise ValueError("ratio must be a positive number")
+        if not self._geographic:
+            w, s, e, n = _expand(self.west, self.south, self.east, self.north, ratio)
+            return BBox(w, s, e, n, crs=self.crs)
+        start, width = self._arc()
+        if mode == "degrees":
+            w, s, e, n = _expand(start, self.south, start + width, self.north, ratio)
+            return BBox.wrap(w, max(-90.0, s), e, min(90.0, n), crs=self.crs)
+        if mode == "mercator":
+            x0, y0 = lonlat_to_mercator(start, self.south)
+            x1, y1 = lonlat_to_mercator(start + width, self.north)
+            mx0, my0, mx1, my1 = _expand(x0, y0, x1, y1, ratio)
+            w, s = mercator_to_lonlat(mx0, my0)
+            e, n = mercator_to_lonlat(mx1, my1)
+            # Latitudes beyond the Mercator limit are kept, never cut.
+            s, n = min(s, self.south), max(n, self.north)
+            return BBox.wrap(w, s, e, n, crs=self.crs)
+        if mode == "ground":
+            w_m, h_m = self.width_m, self.height_m
+            if h_m <= 0 and w_m <= 0:
+                return self
+            if h_m <= 0 or w_m / h_m > ratio:
+                grow = (w_m / ratio - h_m) / 2.0
+                s = max(-90.0, self.south - metres_to_dlat(grow, self.south))
+                n = min(90.0, self.north + metres_to_dlat(grow, self.north))
+                return BBox(self.west, s, self.east, n, crs=self.crs)
+            grow_deg = metres_to_dlon((h_m * ratio - w_m) / 2.0, self.center[1])
+            return BBox.wrap(
+                start - grow_deg, self.south, start + width + grow_deg, self.north, crs=self.crs
+            )
+        raise ValueError("mode must be 'mercator', 'ground' or 'degrees'")
+
+    # ------------------------------------------------------------------
+    # Grids and tiles
+    # ------------------------------------------------------------------
+
+    def grid(self, nx: int, ny: int) -> List[BBox]:
+        """Split into ``nx`` columns by ``ny`` rows.
+
+        Cells are returned row by row from the north-west corner, like map
+        tiles. Cells may cross the antimeridian when the box does.
+        """
+        if int(nx) != nx or int(ny) != ny or nx < 1 or ny < 1:
+            raise ValueError("nx and ny must be positive integers")
+        nx, ny = int(nx), int(ny)
+        if nx * ny > DEFAULT_MAX_ITEMS:
+            raise ValueError(f"grid of {nx * ny} cells exceeds {DEFAULT_MAX_ITEMS}")
+        start = self._arc()[0] if self._geographic else self.west
+        return self._cells(start, self.width / nx, nx, self.height / ny, ny, even=True)
+
+    def _cells(
+        self, x0: float, dx: float, nx: int, dy: float, ny: int, even: bool = False
+    ) -> List[BBox]:
+        x_end = x0 + self.width
+        east_u = self._unwrapped_east() if self._geographic else self.east
+
+        def x_at(i: int) -> float:
+            if even:  # interpolate between the exact edges: 29 .. 29.2 halves at 29.1
+                return (self.west * (nx - i) + east_u * i) / nx
+            return min(x_end, x0 + i * dx)
+
+        def y_at(j: int) -> float:
+            if even:
+                return (self.north * (ny - j) + self.south * j) / ny
+            return max(self.south, self.north - j * dy)
+
+        # Column edges; the outer ones are the box's own (exact) edges.
+        edges = [self.west]
+        for i in range(1, nx):
+            x = x_at(i)
+            edges.append(x - 360.0 if self._geographic and x > 180.0 else x)
+        edges.append(self.east)
+        rows = [self.north] + [y_at(j) for j in range(1, ny)] + [self.south]
+        out: List[BBox] = []
+        for j in range(ny):
+            n, s = rows[j], rows[j + 1]
+            for i in range(nx):
+                w, e = edges[i], edges[i + 1]
+                if self._geographic and e == -180.0 and i + 1 < nx:
+                    e = 180.0  # an inner edge on the antimeridian closes the cell at +180
+                out.append(BBox(w, s, e, n, crs=self.crs))
+        return out
+
+    def split(
+        self,
+        cell: float,
+        cell_y: Optional[float] = None,
+        max_cells: int = DEFAULT_MAX_ITEMS,
+    ) -> List[BBox]:
+        """Split into cells of ``cell`` x ``cell_y`` metres (square if ``cell_y`` is None).
+
+        Geographic boxes get a regular lon/lat grid whose cells measure the
+        requested size at the box's central latitude. The last column and row
+        are clipped to the box. Order is row by row from the north-west.
+        Projected boxes use CRS units.
+        """
+        cx = float(cell)
+        cy = cx if cell_y is None else float(cell_y)
+        if not (cx > 0 and cy > 0):
+            raise ValueError("cell size must be positive")
+        if self._geographic:
+            lat = self.center[1]
+            dx = metres_to_dlon(cx, lat)
+            dy = metres_to_dlat(cy, lat)
+        else:
+            dx, dy = cx, cy
+        nx = max(1, math.ceil(self.width / dx - 1e-9)) if self.width > 0 else 1
+        ny = max(1, math.ceil(self.height / dy - 1e-9)) if self.height > 0 else 1
+        if nx * ny > max_cells:
+            raise ValueError(f"split would create {nx * ny} cells (max_cells={max_cells})")
+        start = self._arc()[0] if self._geographic else self.west
+        return self._cells(start, dx, nx, dy, ny)
+
+    def _wgs84(self) -> BBox:
+        return self if self.crs == WGS84 else self.to_crs(WGS84)
+
+    def tile_count(self, zoom: int) -> int:
+        """Number of XYZ tiles at ``zoom`` overlapping the box."""
+        b = self._wgs84()
+        return sum(
+            (x1 - x0 + 1) * (y1 - y0 + 1)
+            for x0, x1, y0, y1 in _tiles.tile_ranges(b.west, b.south, b.east, b.north, zoom)
+        )
+
+    def tiles(self, zoom: int, max_tiles: int = DEFAULT_MAX_ITEMS) -> List[Tile]:
+        """XYZ tiles at ``zoom`` overlapping the box (latitudes clamped to +-85.05)."""
+        count = self.tile_count(zoom)
+        if count > max_tiles:
+            raise ValueError(f"{count} tiles at zoom {zoom} exceed max_tiles={max_tiles}")
+        b = self._wgs84()
+        return list(_tiles.tiles_covering(b.west, b.south, b.east, b.north, zoom))
+
+    def iter_tiles(self, zoom: int) -> Iterator[Tile]:
+        """Lazily yield the tiles of :meth:`tiles` without a size limit."""
+        b = self._wgs84()
+        return _tiles.tiles_covering(b.west, b.south, b.east, b.north, zoom)
+
+    # ------------------------------------------------------------------
+    # Reprojection
+    # ------------------------------------------------------------------
+
+    def _edge_points(self, densify: int) -> List[Tuple[float, float]]:
+        steps = max(1, int(densify) + 1)
+        x0 = self._arc()[0] if self._geographic else self.west
+        x1 = x0 + self.width
+        pts: List[Tuple[float, float]] = []
+        for i in range(steps + 1):
+            t = i / steps
+            x = x0 + (x1 - x0) * t
+            y = self.south + (self.north - self.south) * t
+            pts.extend(((x, self.south), (x, self.north), (x0, y), (x1, y)))
+        return pts
+
+    def to_crs(self, crs: CRSLike, densify: int = 21) -> BBox:
+        """Reproject by transforming ``densify`` points along every edge.
+
+        WGS 84, Web Mercator and UTM are built in; any other CRS needs pyproj.
+        A box crossing the antimeridian keeps contiguous x values in Web
+        Mercator (east may exceed 20037508.34 m) and becomes a crossing box
+        again when converted back to longitude/latitude.
+        """
+        dst = normalize_crs(crs)
+        if dst == self.crs:
+            return self
+        if not (is_builtin(self.crs) and is_builtin(dst)):
+            t = _pyproj_transformer(self.crs, dst)
+            w, s, e, n = t.transform_bounds(
+                self.west, self.south, self.east, self.north, densify_pts=densify
+            )
+            if _crs_info(dst)[1]:
+                return BBox(max(-180.0, w), max(-90.0, s), min(180.0, e), min(90.0, n), crs=dst)
+            return BBox(w, s, e, n, crs=dst)
+        to_ll = _to_lonlat_fn(self.crs)
+        lonlat = [to_ll(x, y) for x, y in self._edge_points(densify)]
+        if dst == WGS84:
+            lons = [p[0] for p in lonlat]
+            lats = [p[1] for p in lonlat]
+            w, e = unwrapped_to_lons(min(lons), max(lons))
+            return BBox(w, max(-90.0, min(lats)), e, min(90.0, max(lats)), crs=dst)
+        from_ll = _from_lonlat_fn(dst)
+        xy = [from_ll(lon, lat) for lon, lat in lonlat]
+        xs = [p[0] for p in xy]
+        ys = [p[1] for p in xy]
+        return BBox(min(xs), min(ys), max(xs), max(ys), crs=dst)
+
+    def to_utm(self, zone: Optional[int] = None, south: Optional[bool] = None) -> BBox:
+        """Reproject to WGS 84 / UTM (zone and hemisphere default to the centre's)."""
+        b = self._wgs84()
+        lon, lat = b.center
+        z = utm_zone(lon, lat) if zone is None else zone
+        hemi_south = (lat < 0) if south is None else south
+        return self.to_crs(utm_crs(z, hemi_south))
+
+    # ------------------------------------------------------------------
+    # Formatting
+    # ------------------------------------------------------------------
+
+    def to_tuple(self) -> Tuple[float, float, float, float]:
+        """``(west, south, east, north)``."""
+        return self.bounds
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "west": self.west,
+            "south": self.south,
+            "east": self.east,
+            "north": self.north,
+            "crs": self.crs,
+        }
+
+    def to_string(
+        self, order: str = "wsen", sep: str = ",", precision: Optional[int] = None
+    ) -> str:
+        """Four numbers in ``order`` (``"wsen"`` or ``"swne"``)."""
+        key = order.lower()
+        if key not in ("wsen", "swne"):
+            raise ValueError("order must be 'wsen' or 'swne'")
+        vals = self.bounds if key == "wsen" else (self.south, self.west, self.north, self.east)
+        return sep.join(_num(v, precision) for v in vals)
+
+    def to_wsen(self, precision: Optional[int] = None) -> str:
+        """``"west,south,east,north"`` (GeoJSON, OSM API, Shapely, STAC order)."""
+        return self.to_string("wsen", precision=precision)
+
+    def to_swne(self, precision: Optional[int] = None) -> str:
+        """``"south,west,north,east"`` (Overpass, Leaflet, bboxfinder URL order)."""
+        return self.to_string("swne", precision=precision)
+
+    def to_bboxfinder(self, precision: Optional[int] = None) -> str:
+        """bboxfinder.com link (its URL fragment is ``south,west,north,east``)."""
+        return "http://bboxfinder.com/#" + self._wgs84().to_swne(precision)
+
+    def to_overpass(self, setting: bool = False, precision: Optional[int] = None) -> str:
+        """Overpass QL bbox filter ``(s,w,n,e)`` or global ``[bbox:s,w,n,e]`` setting."""
+        text = self._wgs84().to_swne(precision)
+        return f"[bbox:{text}]" if setting else f"({text})"
+
+    def to_osm_url(self, viewport: Tuple[int, int] = (1024, 768)) -> str:
+        """openstreetmap.org link whose ``#map=zoom/lat/lon`` view fits the box."""
+        b = self._wgs84()
+        vw, vh = viewport
+        if vw <= 0 or vh <= 0:
+            raise ValueError("viewport must be positive")
+        start, width = b._arc()
+        x0, y0 = lonlat_to_mercator(start, b.south)
+        x1, y1 = lonlat_to_mercator(start + width, b.north)
+        world = 2 * math.pi * 6378137.0
+        frac_w = max((x1 - x0) / world, 1e-12)
+        frac_h = max((y1 - y0) / world, 1e-12)
+        zoom = math.floor(math.log2(min(vw / (256 * frac_w), vh / (256 * frac_h))))
+        zoom = max(0, min(19, zoom))
+        lon, _ = mercator_to_lonlat((x0 + x1) / 2.0, 0.0)
+        _, lat = mercator_to_lonlat(0.0, (y0 + y1) / 2.0)
+        lon = wrap_lon(lon) if lon >= 180.0 else lon
+        return f"https://www.openstreetmap.org/#map={zoom}/{lat:.5f}/{lon:.5f}"
+
+    def _ring(self, w: float, e: float, precision: Optional[int]) -> str:
+        s, n = self.south, self.north
+        pts = ((w, s), (e, s), (e, n), (w, n), (w, s))
+        return "(" + ", ".join(f"{_num(x, precision)} {_num(y, precision)}" for x, y in pts) + ")"
+
+    def to_wkt(self, precision: Optional[int] = None) -> str:
+        """WKT ``POLYGON`` (``MULTIPOLYGON`` split at the antimeridian if crossing)."""
+        parts = self.parts()
+        if len(parts) == 1:
+            return f"POLYGON ({self._ring(self.west, self.east, precision)})"
+        rings = ", ".join(f"({p._ring(p.west, p.east, precision)})" for p in parts)
+        return f"MULTIPOLYGON ({rings})"
+
+    def to_wkt_envelope(self, precision: Optional[int] = None) -> str:
+        """CQL / Solr ``ENVELOPE(minX, maxX, maxY, minY)``."""
+        p = precision
+        return (
+            f"ENVELOPE({_num(self.west, p)}, {_num(self.east, p)}, "
+            f"{_num(self.north, p)}, {_num(self.south, p)})"
+        )
+
+    def _require_plain(self, what: str) -> None:
+        if self.crosses_antimeridian:
+            raise ValueError(f"{what} cannot express an antimeridian-crossing box; use parts()")
+
+    def _epsg(self) -> Optional[int]:
+        if self.crs.startswith("EPSG:") and self.crs[5:].isdigit():
+            return int(self.crs[5:])
+        return None
+
+    def to_postgis(self, precision: Optional[int] = None) -> str:
+        """PostGIS ``ST_MakeEnvelope(xmin, ymin, xmax, ymax, srid)``."""
+        self._require_plain("ST_MakeEnvelope")
+        srid = self._epsg()
+        nums = ", ".join(_num(v, precision) for v in self)
+        return f"ST_MakeEnvelope({nums}, {srid if srid is not None else 0})"
+
+    def to_geojson(
+        self, feature: bool = False, properties: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """GeoJSON geometry (or Feature) with an RFC 7946 ``bbox`` member.
+
+        Crossing boxes become a ``MultiPolygon`` split at the antimeridian, as
+        RFC 7946 section 3.1.9 recommends; the ``bbox`` keeps ``west > east``.
+        Non-WGS 84 boxes are reprojected first (GeoJSON is always WGS 84).
+        """
+        b = self._wgs84()
+
+        def ring(p: BBox) -> List[List[float]]:
+            w, s, e, n = p.bounds
+            return [[w, s], [e, s], [e, n], [w, n], [w, s]]
+
+        parts = b.parts()
+        geom: Dict[str, Any]
+        if len(parts) == 1:
+            geom = {"type": "Polygon", "coordinates": [ring(b)]}
+        else:
+            geom = {"type": "MultiPolygon", "coordinates": [[ring(p)] for p in parts]}
+        geom["bbox"] = list(b.bounds)
+        if not feature:
+            return geom
+        bbox = geom.pop("bbox")
+        return {
+            "type": "Feature",
+            "bbox": bbox,
+            "properties": dict(properties or {}),
+            "geometry": geom,
+        }
+
+    def to_shapely_bounds(self) -> Tuple[float, float, float, float]:
+        """``(minx, miny, maxx, maxy)`` as Shapely's ``geom.bounds`` returns it."""
+        self._require_plain("a Shapely bounds tuple")
+        return self.bounds
+
+    def to_gdal_te(self, with_srs: bool = False, precision: Optional[int] = None) -> str:
+        """gdalwarp ``-te xmin ymin xmax ymax`` (optionally with ``-te_srs``)."""
+        self._require_plain("gdalwarp -te")
+        text = "-te " + " ".join(_num(v, precision) for v in self)
+        return text + f" -te_srs {self.crs}" if with_srs else text
+
+    def to_gdal_projwin(self, with_srs: bool = False, precision: Optional[int] = None) -> str:
+        """gdal_translate ``-projwin ulx uly lrx lry`` (optionally with ``-projwin_srs``)."""
+        self._require_plain("gdal_translate -projwin")
+        vals = (self.west, self.north, self.east, self.south)
+        text = "-projwin " + " ".join(_num(v, precision) for v in vals)
+        return text + f" -projwin_srs {self.crs}" if with_srs else text
+
+    def _unwrapped_east(self) -> float:
+        return self.east + 360.0 if self.crosses_antimeridian else self.east
+
+    def to_leaflet(self) -> List[List[float]]:
+        """Leaflet ``LatLngBounds`` array ``[[south, west], [north, east]]``.
+
+        Crossing boxes use ``east + 360`` so the map shows one contiguous box.
+        """
+        b = self._wgs84()
+        return [[b.south, b.west], [b.north, b._unwrapped_east()]]
+
+    def to_mapbox(self) -> List[List[float]]:
+        """Mapbox / MapLibre ``LngLatBounds`` array ``[[west, south], [east, north]]``."""
+        b = self._wgs84()
+        return [[b.west, b.south], [b._unwrapped_east(), b.north]]
+
+    def _deepest(self, levels: Iterable[Any], cell_of: Callable[[Any], BBox]) -> Any:
+        best = None
+        for level in levels:
+            cell = cell_of(level)
+            if not cell.contains(self):
+                break
+            best = level
+        return best
+
+    def to_tile(self, max_zoom: int = _tiles.MAX_ZOOM) -> Tile:
+        """Deepest XYZ tile containing the whole box (latitudes clamped to +-85.05)."""
+        b = self._wgs84()
+        clamped = b.replace(
+            south=max(-MERCATOR_MAX_LAT, min(MERCATOR_MAX_LAT, b.south)),
+            north=max(-MERCATOR_MAX_LAT, min(MERCATOR_MAX_LAT, b.north)),
+        )
+        lon, lat = clamped.center
+
+        def cell(z: int) -> BBox:
+            return BBox(*_tiles.lonlat_to_tile(lon, lat, z).bounds)
+
+        z = clamped._deepest(range(max_zoom + 1), cell)
+        if z is None:  # only if latitudes reach the clamp exactly; z0 is the world
+            z = 0
+        return _tiles.lonlat_to_tile(lon, lat, z)
+
+    def to_quadkey(self, max_zoom: int = _tiles.MAX_ZOOM) -> str:
+        """Quadkey of :meth:`to_tile` (``""`` when only the zoom-0 tile fits)."""
+        return self.to_tile(max_zoom).quadkey
+
+    def to_geohash(self, max_precision: int = _geohash.MAX_PRECISION) -> str:
+        """Longest geohash whose cell contains the whole box."""
+        b = self._wgs84()
+        lon, lat = b.center
+        p = b._deepest(
+            range(1, max_precision + 1),
+            lambda k: BBox(*_geohash.decode_bounds(_geohash.encode(lon, lat, k))),
+        )
+        if p is None:
+            raise ValueError(
+                "the box is larger than any geohash cell (straddles a 45 x 45 deg cell edge)"
+            )
+        return _geohash.encode(lon, lat, p)
+
+    def to_pluscode(self) -> str:
+        """Longest Plus Code whose area contains the whole box."""
+        b = self._wgs84()
+        lon, lat = b.center
+        length = b._deepest(
+            _pluscode.VALID_LENGTHS,
+            lambda k: BBox(*_pluscode.decode_bounds(_pluscode.encode(lon, lat, k))),
+        )
+        if length is None:
+            raise ValueError("the box is larger than any Plus Code area (20 x 20 deg)")
+        return _pluscode.encode(lon, lat, length)
+
+    def to_mgrs(self) -> str:
+        """Finest MGRS square (100 km down to 1 m) containing the whole box."""
+        b = self._wgs84()
+        lon, lat = b.center
+        p = b._deepest(range(0, 6), lambda k: BBox(*_mgrs.square_bounds(_mgrs.encode(lon, lat, k))))
+        if p is None:
+            raise ValueError("the box does not fit in a single MGRS 100 km square")
+        return _mgrs.encode(lon, lat, p)
+
+    def format(self, fmt: str, **kwargs: Any) -> str:
+        """Format by name (see :data:`bboxkit.FORMATS`); lists and dicts become JSON."""
+        from .formats import format_bbox
+
+        return format_bbox(self, fmt, **kwargs)
+
+
+def union_all(boxes: Iterable[BBox]) -> BBox:
+    """Smallest box containing every box (RFC 7946 minimal-longitude-gap rule)."""
+    items = list(boxes)
+    if not items:
+        raise ValueError("union_all() needs at least one box")
+    first = items[0]
+    for b in items[1:]:
+        first._same_crs(b)
+    s = min(b.south for b in items)
+    n = max(b.north for b in items)
+    if not first.is_geographic:
+        return BBox(min(b.west for b in items), s, max(b.east for b in items), n, crs=first.crs)
+    arc = covering_arc(b._arc() for b in items)
+    w, e = snap_arc_edges(arc, [b.west for b in items], [b.east for b in items])
+    return BBox(w, s, e, n, crs=first.crs)
+
+
+def _expand(
+    w: float, s: float, e: float, n: float, ratio: float
+) -> Tuple[float, float, float, float]:
+    """Grow ``(w, s, e, n)`` about its centre to ``width / height == ratio``."""
+    width, height = e - w, n - s
+    if height == 0 and width == 0:
+        return (w, s, e, n)
+    if height == 0 or width / height > ratio:
+        grow = (width / ratio - height) / 2.0
+        return (w, s - grow, e, n + grow)
+    grow = (height * ratio - width) / 2.0
+    return (w - grow, s, e + grow, n)