bboxkit 0.1.0__py3-none-any.whl

bboxkit/pluscode.py

@@ -0,0 +1,125 @@
+"""Open Location Code ("Plus Code") areas, implemented with exact integers."""
+
+from __future__ import annotations
+
+import math
+from typing import List, Tuple
+
+__all__ = ["ALPHABET", "VALID_LENGTHS", "decode_bounds", "encode"]
+
+ALPHABET = "23456789CFGHJMPQRVWX"
+_INDEX = {c: i for i, c in enumerate(ALPHABET)}
+_SEP = "+"
+_SEP_POS = 8
+_PAD = "0"
+_PAIRS = 5
+_GRID = 5
+_ROWS = 5
+_COLS = 4
+# Integer units: 1/25,000,000 degree of latitude, 1/8,192,000 degree of longitude.
+_LAT_UNITS = 8000 * _ROWS**_GRID
+_LNG_UNITS = 8000 * _COLS**_GRID
+
+#: Code lengths (digits, excluding '+' and padding) that describe an area.
+VALID_LENGTHS = (2, 4, 6, 8, 10, 11, 12, 13, 14, 15)
+
+
+def _place_values(length: int) -> List[Tuple[int, int]]:
+    """Latitude/longitude place value (integer units) of each digit position."""
+    places: List[Tuple[int, int]] = []
+    for k in range(_PAIRS):
+        lat = 20 ** (_PAIRS - 1 - k) * _ROWS**_GRID
+        lng = 20 ** (_PAIRS - 1 - k) * _COLS**_GRID
+        places.append((lat, lng))
+        places.append((lat, lng))
+    for j in range(_GRID):
+        places.append((_ROWS ** (_GRID - 1 - j), _COLS ** (_GRID - 1 - j)))
+    return places[:length]
+
+
+def _digits_of(code: str) -> str:
+    text = code.strip().upper()
+    if text.count(_SEP) != 1:
+        raise ValueError(f"{code!r} is not a Plus Code (needs exactly one '+')")
+    head, tail = text.split(_SEP)
+    if len(head) < _SEP_POS:
+        raise ValueError(
+            f"{code!r} is a short Plus Code; recover the full code with a reference location first"
+        )
+    if len(head) != _SEP_POS:
+        raise ValueError(f"{code!r}: '+' must follow the 8th character")
+    if _PAD in head:
+        stripped = head.rstrip(_PAD)
+        if _PAD in stripped or len(stripped) % 2 or tail or not stripped:
+            raise ValueError(f"{code!r} has invalid '0' padding")
+        head = stripped
+    if len(tail) == 1:
+        raise ValueError(f"{code!r}: a single digit after '+' is not allowed")
+    digits = head + tail
+    if len(digits) > _PAIRS * 2 + _GRID:
+        raise ValueError(f"{code!r} is longer than 15 digits")
+    for ch in digits:
+        if ch not in _INDEX:
+            raise ValueError(f"invalid Plus Code character {ch!r} in {code!r}")
+    if _INDEX[digits[0]] > 8 or _INDEX[digits[1]] > 17:
+        raise ValueError(f"{code!r} lies outside the globe")
+    return digits
+
+
+def decode_bounds(code: str) -> Tuple[float, float, float, float]:
+    """``(west, south, east, north)`` of a full Plus Code's area."""
+    digits = _digits_of(code)
+    places = _place_values(len(digits))
+    lat = lng = 0
+    for i, ch in enumerate(digits):
+        idx = _INDEX[ch]
+        lat_place, lng_place = places[i]
+        if i < _PAIRS * 2:
+            if i % 2 == 0:
+                lat += idx * lat_place
+            else:
+                lng += idx * lng_place
+        else:
+            lat += (idx // _COLS) * lat_place
+            lng += (idx % _COLS) * lng_place
+    lat_size, lng_size = places[-1]
+    # Subtract in integers first so each edge is a single correctly rounded division.
+    south = (lat - 90 * _LAT_UNITS) / _LAT_UNITS
+    west = (lng - 180 * _LNG_UNITS) / _LNG_UNITS
+    north = min(90.0, (lat + lat_size - 90 * _LAT_UNITS) / _LAT_UNITS)
+    east = min(180.0, (lng + lng_size - 180 * _LNG_UNITS) / _LNG_UNITS)
+    return (west, south, east, north)
+
+
+def encode(lon: float, lat: float, length: int = 10) -> str:
+    """Full Plus Code of a point with ``length`` digits (2, 4, 6, 8, 10 or 11-15)."""
+    if length not in VALID_LENGTHS:
+        raise ValueError(f"Plus Code length must be one of {VALID_LENGTHS}")
+    lat = max(-90.0, min(90.0, lat))
+    lon = (lon + 180.0) % 360.0 - 180.0
+    lat_val = int(math.floor(round((lat + 90.0) * _LAT_UNITS, 6)))
+    lng_val = int(math.floor(round((lon + 180.0) * _LNG_UNITS, 6)))
+    lat_val = min(lat_val, 180 * _LAT_UNITS - 1)  # the north pole belongs to the top row
+    lng_val %= 360 * _LNG_UNITS
+    places = _place_values(_PAIRS * 2 + _GRID)
+    out = []
+    for i in range(length):
+        lat_place, lng_place = places[i]
+        if i < _PAIRS * 2:
+            if i % 2 == 0:
+                d = lat_val // lat_place
+                lat_val -= d * lat_place
+            else:
+                d = lng_val // lng_place
+                lng_val -= d * lng_place
+            out.append(ALPHABET[d])
+        else:
+            row = lat_val // lat_place
+            col = lng_val // lng_place
+            lat_val -= row * lat_place
+            lng_val -= col * lng_place
+            out.append(ALPHABET[row * _COLS + col])
+    digits = "".join(out)
+    if length < _SEP_POS:
+        return digits + _PAD * (_SEP_POS - length) + _SEP
+    return digits[:_SEP_POS] + _SEP + digits[_SEP_POS:]

bboxkit/tiles.py

@@ -0,0 +1,148 @@
+"""XYZ (slippy map) tiles and Bing quadkeys on the Web Mercator grid."""
+
+from __future__ import annotations
+
+import math
+from typing import Iterator, List, NamedTuple, Tuple
+
+from ._geo import MERCATOR_MAX_LAT
+
+__all__ = [
+    "Tile",
+    "MAX_ZOOM",
+    "tile_bounds",
+    "lonlat_to_tile",
+    "tile_to_quadkey",
+    "quadkey_to_tile",
+    "tile_ranges",
+    "tiles_covering",
+]
+
+#: Deepest zoom level accepted (quadkeys and integers stay exact up to here).
+MAX_ZOOM = 30
+
+
+class Tile(NamedTuple):
+    """An XYZ tile: ``x`` grows eastwards, ``y`` southwards, ``z`` is the zoom."""
+
+    x: int
+    y: int
+    z: int
+
+    def __str__(self) -> str:
+        return f"{self.z}/{self.x}/{self.y}"
+
+    @property
+    def quadkey(self) -> str:
+        return tile_to_quadkey(self.x, self.y, self.z)
+
+    @property
+    def bounds(self) -> Tuple[float, float, float, float]:
+        """``(west, south, east, north)`` in degrees."""
+        return tile_bounds(self.x, self.y, self.z)
+
+
+def _check(x: int, y: int, z: int) -> None:
+    if not 0 <= z <= MAX_ZOOM:
+        raise ValueError(f"zoom must be 0..{MAX_ZOOM}, got {z}")
+    n = 1 << z
+    if not (0 <= x < n and 0 <= y < n):
+        raise ValueError(f"tile {z}/{x}/{y} is outside the 2^{z} x 2^{z} grid")
+
+
+def _lat_of_y(y: float, n: int) -> float:
+    return math.degrees(math.atan(math.sinh(math.pi * (1.0 - 2.0 * y / n))))
+
+
+def tile_bounds(x: int, y: int, z: int) -> Tuple[float, float, float, float]:
+    """``(west, south, east, north)`` of tile ``z/x/y`` in degrees."""
+    _check(x, y, z)
+    n = 1 << z
+    return (
+        x / n * 360.0 - 180.0,
+        _lat_of_y(y + 1, n),
+        (x + 1) / n * 360.0 - 180.0,
+        _lat_of_y(y, n),
+    )
+
+
+def _frac_x(lon: float, z: int) -> float:
+    return (lon + 180.0) / 360.0 * (1 << z)
+
+
+def _frac_y(lat: float, z: int) -> float:
+    lat = max(-MERCATOR_MAX_LAT, min(MERCATOR_MAX_LAT, lat))
+    phi = math.radians(lat)
+    return (1.0 - math.asinh(math.tan(phi)) / math.pi) / 2.0 * (1 << z)
+
+
+def lonlat_to_tile(lon: float, lat: float, z: int) -> Tile:
+    """Tile containing a point (latitude is clamped to the Mercator limit)."""
+    n = 1 << z
+    x = min(n - 1, max(0, int(math.floor(_frac_x(lon, z)))))
+    y = min(n - 1, max(0, int(math.floor(_frac_y(lat, z)))))
+    _check(x, y, z)
+    return Tile(x, y, z)
+
+
+def tile_to_quadkey(x: int, y: int, z: int) -> str:
+    """Bing Maps quadkey of a tile (``""`` for zoom 0)."""
+    _check(x, y, z)
+    digits = []
+    for i in range(z, 0, -1):
+        mask = 1 << (i - 1)
+        digit = (1 if x & mask else 0) + (2 if y & mask else 0)
+        digits.append(str(digit))
+    return "".join(digits)
+
+
+def quadkey_to_tile(quadkey: str) -> Tile:
+    """Tile of a quadkey string made of the digits 0-3."""
+    if len(quadkey) > MAX_ZOOM:
+        raise ValueError(f"quadkey longer than {MAX_ZOOM} digits")
+    x = y = 0
+    for ch in quadkey:
+        if ch not in "0123":
+            raise ValueError(f"invalid quadkey digit {ch!r} in {quadkey!r}")
+        d = int(ch)
+        x = (x << 1) | (d & 1)
+        y = (y << 1) | (d >> 1)
+    return Tile(x, y, len(quadkey))
+
+
+def _index_range(lo: float, hi: float, n: int) -> Tuple[int, int]:
+    """Indices of cells [i, i+1) overlapping [lo, hi], edges excluded."""
+    first = int(math.floor(lo))
+    last = int(math.ceil(hi)) - 1
+    if last < first:  # degenerate (zero-width) range
+        last = first
+    return (max(0, min(n - 1, first)), max(0, min(n - 1, last)))
+
+
+def tile_ranges(
+    west: float, south: float, east: float, north: float, z: int
+) -> List[Tuple[int, int, int, int]]:
+    """``(x_min, x_max, y_min, y_max)`` ranges of tiles covering a box.
+
+    An antimeridian-crossing box (``west > east``) yields two ranges.
+    """
+    if not 0 <= z <= MAX_ZOOM:
+        raise ValueError(f"zoom must be 0..{MAX_ZOOM}, got {z}")
+    n = 1 << z
+    y0, y1 = _index_range(_frac_y(north, z), _frac_y(south, z), n)
+    lon_parts = [(west, east)] if west <= east else [(west, 180.0), (-180.0, east)]
+    out = []
+    for w, e in lon_parts:
+        x0, x1 = _index_range(_frac_x(w, z), _frac_x(e, z), n)
+        out.append((x0, x1, y0, y1))
+    if len(out) == 2 and out[1][1] >= out[0][0]:  # the two halves overlap: whole row
+        out = [(0, n - 1, y0, y1)]
+    return out
+
+
+def tiles_covering(west: float, south: float, east: float, north: float, z: int) -> Iterator[Tile]:
+    """Yield every tile at zoom ``z`` that overlaps the box, row by row."""
+    for x0, x1, y0, y1 in tile_ranges(west, south, east, north, z):
+        for y in range(y0, y1 + 1):
+            for x in range(x0, x1 + 1):
+                yield Tile(x, y, z)

bboxkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: bboxkit
+Version: 0.1.0
+Summary: Zero-dependency bounding boxes: parse and format every bbox convention (WKT, GeoJSON, Overpass, GDAL, tiles, geohash, Plus Codes, MGRS), antimeridian-aware geometry, ellipsoidal area and reprojection.
+Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YusufEminoglu/bboxkit_sdk
+Project-URL: Repository, https://github.com/YusufEminoglu/bboxkit_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/bboxkit_sdk/issues
+Project-URL: Changelog, https://github.com/YusufEminoglu/bboxkit_sdk/blob/main/CHANGELOG.md
+Keywords: bbox,bounding-box,gis,geojson,wkt,overpass,openstreetmap,gdal,xyz-tiles,quadkey,geohash,plus-codes,mgrs,utm,web-mercator,antimeridian
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pyproj
+Requires-Dist: pyproj>=3.4; extra == "pyproj"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# bboxkit
+
+**Bounding boxes, without the guesswork.** Parse a bbox from whatever tool handed it to you,
+convert it to whatever the next tool wants, and do correct geometry on it, including boxes
+that cross the antimeridian. Pure Python, zero dependencies, fully typed.
+
+```bash
+pip install bboxkit            # zero dependencies
+pip install "bboxkit[pyproj]"  # optional: reproject to any CRS
+```
+
+```python
+>>> from bboxkit import BBox, parse
+>>> box = parse("29.0,40.9,29.2,41.1", order="wsen")   # Istanbul
+>>> box.to_overpass()
+'(40.9,29,41.1,29.2)'
+>>> box.to_gdal_te()
+'-te 29 40.9 29.2 41.1'
+>>> round(box.area_km2(), 3)                          # exact on the WGS 84 ellipsoid
+373.741
+```
+
+Every tool agrees that a bounding box has four numbers. Almost nothing else is agreed:
+GeoJSON and Shapely write `west,south,east,north`, Overpass and Leaflet write
+`south,west,north,east`, `gdal_translate -projwin` wants `west,north,east,south`, Nominatim
+returns `[south, north, west, east]` as strings, and a box around Fiji has `west > east`.
+bboxkit is a small, dependency-free value type that knows all of these conventions, so other
+packages can depend on it instead of re-implementing (and re-debugging) them.
+
+## Supported formats
+
+| Format | Example | Parse | Format |
+| --- | --- | --- | --- |
+| W,S,E,N (GeoJSON, Shapely, OSM API, STAC) | `29,40.9,29.2,41.1` | `parse(s, order="wsen")` | `to_wsen()` |
+| S,W,N,E (lat-first) | `40.9,29,41.1,29.2` | `parse(s, order="swne")` | `to_swne()` |
+| bboxfinder.com | `http://bboxfinder.com/#40.9,29,41.1,29.2` | auto | `to_bboxfinder()` |
+| Overpass QL | `(40.9,29,41.1,29.2)`, `[bbox:40.9,29,41.1,29.2]` | auto | `to_overpass()` |
+| OSM URL | `...?bbox=W,S,E,N`, `?minlon=...`, `#map=14/41.0/29.0` | auto (`viewport=`) | `to_osm_url()` |
+| WKT / EWKT | `POLYGON ((...))`, `SRID=3857;MULTIPOINT(...)`, any geometry | auto | `to_wkt()` |
+| ENVELOPE (CQL, Solr) | `ENVELOPE(29, 29.2, 41.1, 40.9)` | auto | `to_wkt_envelope()` |
+| PostGIS | `ST_MakeEnvelope(29, 40.9, 29.2, 41.1, 4326)`, `BOX(29 40.9,29.2 41.1)` | auto | `to_postgis()` |
+| GeoJSON | `bbox` member, or computed from any geometry / Feature / FeatureCollection | auto | `to_geojson()` |
+| Shapely / GeoPandas | `geom.bounds`, `gdf.total_bounds`, `__geo_interface__` | `parse(obj)` | `to_shapely_bounds()` |
+| GDAL / OGR | `-te 29 40.9 29.2 41.1`, `-projwin 29 41.1 29.2 40.9`, `-spat ...`, `-te_srs` | auto | `to_gdal_te()`, `to_gdal_projwin()` |
+| Leaflet / Google | `[[40.9, 29], [41.1, 29.2]]` | `parse_leaflet()` | `to_leaflet()` |
+| Mapbox / MapLibre | `[[29, 40.9], [29.2, 41.1]]` | `parse_mapbox()` | `to_mapbox()` |
+| XYZ tile | `14/9375/6142`, `https://tile.../14/9375/6142.png` | auto | `to_tile()` |
+| Quadkey (Bing) | `1202102332221212` | auto | `to_quadkey()` |
+| Geohash | `sxk9` | auto | `to_geohash()` |
+| Plus Code (OLC) | `8FVC9G8F+6W` | auto | `to_pluscode()` |
+| MGRS square | `35TPF`, `31U DQ 48251 11932` | auto | `to_mgrs()` |
+| Dictionaries | Nominatim result, ArcGIS extent (`wkid`), STAC collection, Leaflet `_southWest`, Google `southwest`, `{minx, ...}` | `parse(d)` | `to_dict()` |
+| Place name | `"Istanbul"` | `nominatim.geocode_bbox()` (opt-in, network) | |
+
+For cell formats (tile, quadkey, geohash, Plus Code, MGRS) parsing gives the cell's box and
+formatting gives the **smallest cell that contains the whole box**.
+
+Not included, on purpose: H3 (needs the icosahedral projection, i.e. the `h3` library) and
+the polar UPS part of MGRS.
+
+## One-liners
+
+```python
+from bboxkit import BBox, parse, union_all
+
+parse("http://bboxfinder.com/#40.9,29,41.1,29.2")         # BBox(29.0, 40.9, 29.2, 41.1)
+parse("[bbox:40.9,29,41.1,29.2]")                          # Overpass setting
+parse("gdalwarp -t_srs EPSG:32635 -te 500000 4500000 510000 4510000 in.tif out.tif")
+parse("https://www.openstreetmap.org/#map=14/41.0082/28.9784", viewport=(1920, 1080))
+parse("SRID=3857;POLYGON((0 0, 10 0, 10 10, 0 0))")       # crs='EPSG:3857'
+parse({"type": "Feature", "geometry": {"type": "LineString", "coordinates": [[179, 0], [-179, 1]]}})
+parse({"boundingbox": ["40.9", "41.1", "29.0", "29.2"]})   # a Nominatim result
+parse(shapely_polygon)                                      # uses .bounds
+parse("14/9375/6142"); parse("sxk9"); parse("8FVC9G8F+6W"); parse("35TPF")
+
+box = BBox(29.0, 40.9, 29.2, 41.1)
+box.to_wkt()               # 'POLYGON ((29 40.9, 29.2 40.9, 29.2 41.1, 29 41.1, 29 40.9))'
+box.to_geojson()           # {'type': 'Polygon', 'coordinates': [...], 'bbox': [...]}
+box.to_leaflet()           # [[40.9, 29.0], [41.1, 29.2]]
+box.to_gdal_projwin()      # '-projwin 29 41.1 29.2 40.9'
+box.to_osm_url()           # 'https://www.openstreetmap.org/#map=11/41.00008/29.10000'
+box.format("postgis")      # 'ST_MakeEnvelope(29, 40.9, 29.2, 41.1, 4326)'
+box.to_geohash(), box.to_tile(), box.to_mgrs()   # ('sxk', Tile(x=2, y=1, z=2), '35TPF')
+
+box.area_km2()             # 373.741450485826  (exact for a lat/lon rectangle on WGS 84)
+box.center                 # (29.1, 41.0)
+box.width_m, box.height_m  # (16827.0..., 22210.7...)
+box.buffer(500)            # grown by 500 m on every side
+box.buffer(-500)           # shrunk by 500 m
+box.contains((29.1, 41.0)); box.intersects(other); box & other; box | other
+box.grid(4, 3)             # 12 cells, row by row from the north-west
+box.split(1000)            # ~1 km x 1 km cells
+box.tiles(14)              # [Tile(x=9511, y=6136, z=14), ...]
+box.tile_count(14)         # 130
+box.expand_to_aspect(16 / 9)            # fit a 16:9 web map (Mercator), never shrinks
+BBox(29.03, 40.91, 29.17, 41.08).snap(0.1)   # BBox(29.0, 40.9, 29.2, 41.1)
+round(box, 2)
+box.to_crs("EPSG:3857")    # built in
+box.to_utm()               # built in: EPSG:32635 for Istanbul
+box.to_crs("EPSG:3035")    # any CRS with the [pyproj] extra
+w, s, e, n = box           # unpacks like a tuple
+```
+
+## The antimeridian
+
+For longitude/latitude boxes, `west > east` means the box crosses the 180th meridian, exactly
+as in RFC 7946:
+
+```python
+>>> fiji = BBox(177, -20, -178, -16)
+>>> fiji.crosses_antimeridian, fiji.width, fiji.center
+(True, 5.0, (179.5, -18.0))
+>>> fiji.contains((-179.5, -18))
+True
+>>> fiji.parts()
+(BBox(177.0, -20.0, 180.0, -16.0), BBox(-180.0, -20.0, -178.0, -16.0))
+>>> BBox(170, 0, 175, 1) | BBox(-175, 0, -170, 1)
+BBox(170.0, 0.0, -170.0, 1.0)
+>>> fiji.to_geojson()["type"]            # split into two parts, as RFC 7946 recommends
+'MultiPolygon'
+>>> fiji.to_leaflet()                    # one contiguous box on a web map
+[[-20.0, 177.0], [-16.0, 182.0]]
+```
+
+- `union()` / `union_all()` and bounding boxes computed from GeoJSON or WKT use the smallest
+  longitude range that covers everything (the complement of the largest gap), so the RFC 7946
+  Fiji example gives `[177, -20, -178, -16]`, not `[-178, -20, 177, -16]`.
+- A line or ring whose consecutive vertices are more than 180 degrees apart is read as crossing
+  the antimeridian (the shorter way round).
+- `intersection()` returns `None`, one box, or raises if the overlap is two separate pieces
+  (wide boxes overlapping at both ends); `intersection_parts()` always returns the list.
+- Formats that cannot express a crossing box (`-te`, `-projwin`, `ST_MakeEnvelope`, Shapely
+  bounds) raise a `ValueError` that points to `parts()`.
+- In Web Mercator a crossing box keeps contiguous x values (east beyond 20037508.34 m) and
+  converts back to a crossing box.
+
+## W,S,E,N or S,W,N,E?
+
+Four bare numbers are ambiguous. bboxkit reads them as `west,south,east,north` unless only the
+lat-first reading is valid, and emits an `AmbiguousOrderWarning` whenever both readings are
+possible. Say what you mean to make the warning go away:
+
+```python
+parse("40.9,29,41.1,29.2", order="swne")
+parse("swne:40.9,29,41.1,29.2")
+parse(text, fmt="leaflet")
+```
+
+## Area, buffers and grids
+
+- `area_km2()` uses the closed-form area of a region bounded by two meridians and two parallels
+  on the WGS 84 ellipsoid (via the authalic latitude function). It matches a densely densified
+  `pyproj.Geod` polygon to ~1e-11. 1 x 1 degree at the equator is 12308.4639 km2, at 60 N
+  6123.1409 km2; the whole globe is 510065621.724 km2.
+- `buffer(m)` uses the local radii of curvature; the longitude margin is taken at the most
+  poleward latitude, so every point within `m` metres of the box is inside the result. Boxes
+  that reach a pole get the full longitude range.
+- `split(cell_m)` builds a regular lon/lat grid whose cells measure `cell_m` at the box's central
+  latitude; `grid(nx, ny)` splits evenly. Both work across the antimeridian.
+- Projected boxes (UTM, any metric CRS) do all of this in CRS units.
+
+## Reprojection
+
+`to_crs()` transforms densified edges (21 points per edge by default) and takes the extent.
+WGS 84, Web Mercator (`EPSG:3857` and its aliases 900913, 3785, 102100) and WGS 84 / UTM
+(`EPSG:326xx`, `EPSG:327xx`, ETRS89 `EPSG:258xx`) are built in; UTM uses the 6th-order Krueger
+series (agrees with PROJ to nanometres). Anything else goes to pyproj when it is installed.
+`to_utm()` picks the zone of the centre, including the Norway and Svalbard exceptions.
+
+## Command line
+
+```bash
+$ bboxkit convert "29.0,40.9,29.2,41.1" --to overpass
+bboxkit: warning: 29,40.9,29.2,41.1 is ambiguous; read as west,south,east,north. ...
+(40.9,29,41.1,29.2)
+$ bboxkit convert "29.0,40.9,29.2,41.1" --order wsen --to all
+$ bboxkit convert "http://bboxfinder.com/#40.9,29,41.1,29.2" --to gdal-projwin
+$ bboxkit area "29.0,40.9,29.2,41.1" --order wsen
+373.741
+$ bboxkit tiles "29.0,40.9,29.2,41.1" --order wsen --zoom 14 --count
+130
+$ bboxkit tiles "29.0,40.9,29.2,41.1" --order wsen --zoom 14 --format quadkey
+$ bboxkit split "29.0,40.9,29.2,41.1" --order wsen --cell 1km --to geojson > grid.geojson
+$ bboxkit split "29.0,40.9,29.2,41.1" --order wsen --grid 4x3
+$ bboxkit buffer "POINT(29 41)" --distance 2km --to wkt
+$ bboxkit reproject "29.0,40.9,29.2,41.1" --order wsen --to-crs utm
+$ bboxkit info "177,-20,-178,-16" --order wsen
+$ bboxkit geocode "Kadikoy, Istanbul" --user-agent "my-app/1.0 (me@example.org)"
+$ bboxkit formats
+```
+
+Boxes that start with a minus sign (`-122.5,37.7,-122.3,37.8`, `-te 1 2 3 4`) work as they are;
+`-` reads the box from standard input.
+
+## Place names (optional, network)
+
+`parse()` never touches the network. Place lookup is a separate, explicit call:
+
+```python
+from bboxkit.nominatim import geocode_bbox
+
+geocode_bbox("Kadikoy, Istanbul", user_agent="my-app/1.0 (me@example.org)", timeout=10)
+```
+
+It follows the [Nominatim usage policy](https://operations.osmfoundation.org/policies/nominatim/):
+at most one request per second per process, an identifying User-Agent (please set your own),
+results cached in memory, and a `base_url=` for your own Nominatim instance when you need
+more than occasional lookups. Results are (c) OpenStreetMap contributors, ODbL.
+
+## Design
+
+- `BBox` is immutable, hashable, picklable and slotted. `==` and `hash` are exact so boxes can
+  be dict keys; `equals(other, tol=1e-9)` compares with a tolerance (longitudes modulo 360).
+- Validation on construction: finite numbers, `south <= north`, latitudes and longitudes in
+  range for geographic CRSs, `west <= east` for projected ones. `BBox.wrap()` accepts unwrapped
+  longitudes such as `170 .. 190`.
+- CRS strings are normalised (`4326`, `"epsg:4326"`, URNs, OGC URLs, `CRS84` all become
+  `"EPSG:4326"`).
+- Cell lookups (`to_geohash()`, `to_pluscode()`, ...) use exact integer arithmetic where the
+  format allows it, so round trips are stable.
+
+## Development
+
+```bash
+pip install -e ".[dev,pyproj]"
+pytest --cov=bboxkit
+ruff check . && ruff format --check src tests
+mypy --strict src
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Yusuf Eminoğlu.

bboxkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+bboxkit/__init__.py,sha256=52gVQpRXoDDcjiTNPXkZ-ycbw4tycV6KF-Djc35ElKk,736
+bboxkit/__main__.py,sha256=jnD5WmxMTKyGlvrBEWHxyesWykTYEBlGx_uTonn9mT8,129
+bboxkit/_geo.py,sha256=hmHxx_zNlegxxz9pgz7A6fv_eB7sq6jud46tTRU59tw,7966
+bboxkit/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+bboxkit/bbox.py,sha256=beML5HcakSYPeD_EpfeCUA2KDIE8Z0bWI3MzDXG1Okg,41500
+bboxkit/cli.py,sha256=ki05YBrXakaF3egXqCkZnz81l8A--DKrcp7C6vh4ZPU,11359
+bboxkit/crs.py,sha256=xDzpauNuQFyM4Ncvd8Wsugy3FadkOANqBCc7O4br_xo,13285
+bboxkit/formats.py,sha256=P9jBXJWRbWg5EnGBd81QSfDnyCNeUKCUfyzC_AqGbHg,3300
+bboxkit/geohash.py,sha256=3AglvokcXzc8apVMRhGdyUP0TU9ufmrjFxaOg79dI6c,2564
+bboxkit/mgrs.py,sha256=CYyuujNwjI5ktYSd_vBdezPs79GTfR6UOURRsn8mbDQ,5305
+bboxkit/nominatim.py,sha256=hQ2WwTZYzni20ch3QNlVrdoEMsVc4LHiciKqc4Lt7nI,3755
+bboxkit/parsing.py,sha256=YUwaLs9bhwNtB12URHRlNFOGPnbL-RnSOPFao58GcA0,27069
+bboxkit/pluscode.py,sha256=eVGEk9hVQ6MP49DDtkvTq0V4--sJvQxyROxREw3F7w8,4742
+bboxkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bboxkit/tiles.py,sha256=ZPcbAvNxTKI34xdNAOYXuHrlFXU5pSgVt6YSuQwhRSw,4632
+bboxkit-0.1.0.dist-info/licenses/LICENSE,sha256=Z9meOk3opsRgHOqC5mA4B8NjZoU5WU1Kqhn82FL4ICs,1072
+bboxkit-0.1.0.dist-info/METADATA,sha256=bJgR1beD5aX_MTMPhCAUkCy7MCtBJiFMOpJ49elODJQ,13569
+bboxkit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+bboxkit-0.1.0.dist-info/entry_points.txt,sha256=Fqc8gaNEQXsNXh3hoO43k01ksKesqnhVWeIH_9Smts0,45
+bboxkit-0.1.0.dist-info/top_level.txt,sha256=HdhzcKSSFOcJdYZd599gtW2s0mDllpI2HN_b6BSS5zU,8
+bboxkit-0.1.0.dist-info/RECORD,,

bboxkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bboxkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bboxkit = bboxkit.cli:main

bboxkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bboxkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bboxkit