bboxkit 0.1.0__py3-none-any.whl

bboxkit/__init__.py

@@ -0,0 +1,31 @@
+"""bboxkit: parse, convert and operate on bounding boxes, with zero dependencies.
+
+>>> from bboxkit import BBox, parse
+>>> box = parse("29.0,40.9,29.2,41.1", order="wsen")
+>>> box.to_overpass()
+'(40.9,29,41.1,29.2)'
+"""
+
+from ._version import __version__
+from .bbox import BBox, union_all
+from .crs import WEB_MERCATOR, WGS84, normalize_crs, utm_crs, utm_zone
+from .formats import FORMATS, format_bbox
+from .parsing import PARSERS, AmbiguousOrderWarning, parse
+from .tiles import Tile
+
+__all__ = [
+    "__version__",
+    "BBox",
+    "Tile",
+    "parse",
+    "union_all",
+    "format_bbox",
+    "FORMATS",
+    "PARSERS",
+    "AmbiguousOrderWarning",
+    "WGS84",
+    "WEB_MERCATOR",
+    "normalize_crs",
+    "utm_zone",
+    "utm_crs",
+]

bboxkit/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m bboxkit``."""
+
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

bboxkit/_geo.py

@@ -0,0 +1,222 @@
+"""Ellipsoid constants, longitude arcs and closed-form geodesy on WGS 84.
+
+Everything here works on plain floats so the rest of the package can stay
+free of third-party dependencies.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Iterable, List, Sequence, Tuple
+
+# WGS 84 ellipsoid.
+WGS84_A = 6378137.0
+WGS84_F = 1.0 / 298.257223563
+WGS84_B = WGS84_A * (1.0 - WGS84_F)
+WGS84_E2 = WGS84_F * (2.0 - WGS84_F)
+WGS84_E = math.sqrt(WGS84_E2)
+#: Third flattening n = f / (2 - f), used by the Krueger series.
+WGS84_N = WGS84_F / (2.0 - WGS84_F)
+
+#: Latitude limit of the square Web Mercator world (EPSG:3857 / XYZ tiles).
+MERCATOR_MAX_LAT = math.degrees(math.atan(math.sinh(math.pi)))
+
+Arc = Tuple[float, float]
+"""A longitude arc as ``(start, width)``: start in [-180, 180), width in [0, 360]."""
+
+
+def wrap_lon(lon: float) -> float:
+    """Wrap a longitude into [-180, 180)."""
+    wrapped = (lon + 180.0) % 360.0 - 180.0
+    # ``%`` can return 360.0 - tiny for tiny negative inputs.
+    return -180.0 if wrapped >= 180.0 else wrapped
+
+
+def wrap_delta(delta: float) -> float:
+    """Wrap a longitude difference into (-180, 180]."""
+    d = (delta + 180.0) % 360.0 - 180.0
+    return 180.0 if d == -180.0 and delta > 0 else d
+
+
+def lon_arc(west: float, east: float) -> Arc:
+    """Return the eastward arc from ``west`` to ``east`` (crossing allowed)."""
+    if west == -180.0 and east == 180.0:
+        return (-180.0, 360.0)
+    width = east - west if west <= east else east - west + 360.0
+    return (wrap_lon(west), width)
+
+
+def arc_to_lons(arc: Arc) -> Tuple[float, float]:
+    """Convert an arc back to a ``(west, east)`` pair (``west > east`` if crossing)."""
+    start, width = arc
+    if width >= 360.0:
+        return (-180.0, 180.0)
+    east = start + width
+    if east > 180.0:
+        east -= 360.0
+    return (start, east)
+
+
+def unwrapped_to_lons(lo: float, hi: float) -> Tuple[float, float]:
+    """Turn an unwrapped longitude range (values may exceed +-180) into west/east."""
+    if hi - lo >= 360.0:
+        return (-180.0, 180.0)
+    return arc_to_lons((wrap_lon(lo), hi - lo))
+
+
+def covering_arc(arcs: Iterable[Arc]) -> Arc:
+    """Smallest longitude arc that covers every arc in ``arcs``.
+
+    This is the complement of the largest longitude gap, the rule RFC 7946
+    section 5.2 uses for features straddling the antimeridian. On a tie the
+    arc that does not cross the antimeridian wins.
+    """
+    segs = sorted(((s + 180.0) % 360.0, w) for s, w in arcs)
+    if not segs:
+        raise ValueError("no longitudes to cover")
+    if any(w >= 360.0 for _, w in segs):
+        return (-180.0, 360.0)
+    merged: List[List[float]] = []
+    for s, w in segs:
+        e = s + w
+        if merged and s <= merged[-1][1]:
+            merged[-1][1] = max(merged[-1][1], e)
+        else:
+            merged.append([s, e])
+    # Segments running past 360 may swallow segments at the start.
+    while len(merged) > 1 and merged[-1][1] >= merged[0][0] + 360.0:
+        merged[-1][1] = max(merged[-1][1], merged[0][1] + 360.0)
+        merged.pop(0)
+    if len(merged) == 1:
+        s, e = merged[0]
+        if e - s >= 360.0:
+            return (-180.0, 360.0)
+        return (wrap_lon(s - 180.0), e - s)
+    best: Tuple[float, int, float, float] = (-1.0, 0, 0.0, 0.0)
+    count = len(merged)
+    for i in range(count):
+        gap_start = merged[i][1]
+        nxt = merged[(i + 1) % count][0] + (360.0 if i == count - 1 else 0.0)
+        gap = nxt - gap_start
+        # The covering arc runs from the end of the gap round to its start.
+        start = nxt
+        width = 360.0 - gap
+        lon_start = wrap_lon(start - 180.0)
+        non_crossing = 1 if lon_start + width <= 180.0 else 0
+        cand = (gap, non_crossing, lon_start, width)
+        if cand[:2] > best[:2]:
+            best = cand
+    return (best[2], best[3])
+
+
+def snap_arc_edges(
+    arc: Arc, wests: Iterable[float], easts: Iterable[float], tol: float = 1e-9
+) -> Tuple[float, float]:
+    """``(west, east)`` of ``arc``, snapped to the exact input longitudes it came from.
+
+    ``start + width`` can differ from the original east edge by a rounding
+    error; picking the matching input value keeps results exact.
+    """
+    west, east = arc_to_lons(arc)
+    if arc[1] >= 360.0:
+        return (west, east)
+    for x in wests:
+        if abs(wrap_delta(x - west)) <= tol:
+            west = -180.0 if x == 180.0 else x
+            break
+    for x in easts:
+        if abs(wrap_delta(x - east)) <= tol:
+            east = 180.0 if x == -180.0 else wrap_lon(x) if x > 180.0 else x
+            break
+    if west == 180.0:
+        west = -180.0
+    return (max(-180.0, min(180.0, west)), max(-180.0, min(180.0, east)))
+
+
+def component_arc(lons: Sequence[float]) -> Arc:
+    """Longitude arc of a connected line or ring.
+
+    Consecutive vertices more than 180 degrees apart are joined across the
+    antimeridian (the shorter way round), as RFC 7946 prescribes.
+    """
+    if not lons:
+        raise ValueError("empty coordinate sequence")
+    if any(abs(b - a) > 180.0 for a, b in zip(lons, lons[1:])):
+        unwrapped = [lons[0]]
+        for a, b in zip(lons, lons[1:]):
+            unwrapped.append(unwrapped[-1] + wrap_delta(b - a))
+        lo, hi = min(unwrapped), max(unwrapped)
+        if hi - lo >= 360.0:
+            return (-180.0, 360.0)
+        return (wrap_lon(lo), hi - lo)
+    lo, hi = min(lons), max(lons)
+    return lon_arc(lo, hi)
+
+
+# --------------------------------------------------------------------------
+# Radii, meridian arc and area
+# --------------------------------------------------------------------------
+
+
+def meridional_radius(lat: float) -> float:
+    """Radius of curvature in the meridian, M(phi), in metres."""
+    s = math.sin(math.radians(lat))
+    return WGS84_A * (1.0 - WGS84_E2) / math.pow(1.0 - WGS84_E2 * s * s, 1.5)
+
+
+def prime_vertical_radius(lat: float) -> float:
+    """Radius of curvature in the prime vertical, N(phi), in metres."""
+    s = math.sin(math.radians(lat))
+    return WGS84_A / math.sqrt(1.0 - WGS84_E2 * s * s)
+
+
+def parallel_radius(lat: float) -> float:
+    """Radius of the parallel circle at ``lat`` (N cos phi), in metres."""
+    return prime_vertical_radius(lat) * math.cos(math.radians(lat))
+
+
+def meridian_distance(lat: float) -> float:
+    """Distance along the meridian from the equator to ``lat`` in metres.
+
+    Helmert's series in the third flattening; accurate to well below a
+    millimetre on WGS 84.
+    """
+    n = WGS84_N
+    phi = math.radians(lat)
+    a0 = WGS84_A / (1.0 + n) * (1.0 + n**2 / 4.0 + n**4 / 64.0)
+    return a0 * (
+        phi
+        - (1.5 * n - 9.0 / 16.0 * n**3) * math.sin(2 * phi)
+        + (15.0 / 16.0 * n**2 - 15.0 / 32.0 * n**4) * math.sin(4 * phi)
+        - 35.0 / 48.0 * n**3 * math.sin(6 * phi)
+        + 315.0 / 512.0 * n**4 * math.sin(8 * phi)
+    )
+
+
+def _authalic_q(lat: float) -> float:
+    s = math.sin(math.radians(lat))
+    es = WGS84_E * s
+    return s / (1.0 - es * es) + math.log((1.0 + es) / (1.0 - es)) / (2.0 * WGS84_E)
+
+
+def rectangle_area_m2(width_deg: float, south: float, north: float) -> float:
+    """Exact ellipsoidal area of a lat/lon rectangle bounded by parallels.
+
+    ``A = (b^2 / 2) * dlambda * (q(north) - q(south))`` with the authalic
+    function q. The east/west edges are meridians and the north/south edges
+    are parallels, exactly like the region a bounding box describes.
+    """
+    return 0.5 * WGS84_B**2 * math.radians(width_deg) * (_authalic_q(north) - _authalic_q(south))
+
+
+def metres_to_dlat(metres: float, lat: float) -> float:
+    """Latitude span (degrees) of ``metres`` along the meridian near ``lat``."""
+    return math.degrees(metres / meridional_radius(lat))
+
+
+def metres_to_dlon(metres: float, lat: float) -> float:
+    """Longitude span (degrees) of ``metres`` along the parallel at ``lat``."""
+    r = parallel_radius(lat)
+    if r <= 1e-6:
+        return 360.0
+    return math.degrees(metres / r)

bboxkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"