bboxkit 0.1.0__py3-none-any.whl

bboxkit/cli.py

@@ -0,0 +1,311 @@
+"""Command-line interface: ``bboxkit convert|info|area|tiles|split|buffer|reproject|geocode``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import warnings
+from typing import Any, Callable, Dict, List, Optional, Sequence, TextIO
+
+from ._version import __version__
+from .bbox import BBox
+from .formats import FORMAT_ALIASES, FORMATS, format_bbox
+from .parsing import PARSERS, parse
+
+_UNITS = {"m": 1.0, "km": 1000.0, "mi": 1609.344, "ft": 0.3048, "nmi": 1852.0}
+
+
+def parse_distance(text: str) -> float:
+    """``"1km"``, ``"500 m"``, ``"2mi"``, ``"250"`` (metres) to metres."""
+    m = re.fullmatch(r"\s*([-+]?\d+(?:\.\d*)?|[-+]?\.\d+)\s*([a-zA-Z]*)\s*", text)
+    if not m:
+        raise ValueError(f"cannot read distance {text!r}; try 500m or 1.5km")
+    unit = m.group(2).lower() or "m"
+    if unit not in _UNITS:
+        raise ValueError(f"unknown distance unit {unit!r}; use one of {', '.join(_UNITS)}")
+    return float(m.group(1)) * _UNITS[unit]
+
+
+def _grid_spec(text: str) -> List[int]:
+    m = re.fullmatch(r"\s*(\d+)\s*[xX*,]\s*(\d+)\s*", text)
+    if not m:
+        raise ValueError(f"cannot read grid {text!r}; use e.g. 3x2 (columns x rows)")
+    return [int(m.group(1)), int(m.group(2))]
+
+
+def _load(args: argparse.Namespace) -> BBox:
+    text = " ".join(args.bbox).strip()
+    if text == "-":
+        text = sys.stdin.read().strip()
+    return parse(text, fmt=args.source_format, order=args.order, crs=args.crs)
+
+
+def _out(box: BBox, fmt: str, precision: Optional[int]) -> str:
+    kwargs: Dict[str, Any] = {}
+    if precision is not None and fmt in (
+        "wsen",
+        "swne",
+        "bboxfinder",
+        "overpass",
+        "wkt",
+        "envelope",
+        "postgis",
+        "gdal-te",
+        "gdal-projwin",
+        "bbox",
+        "csv",
+        "latlon",
+        "gdal",
+        "te",
+        "projwin",
+    ):
+        kwargs["precision"] = precision
+    return format_bbox(box, fmt, **kwargs)
+
+
+def _cmd_convert(args: argparse.Namespace, out: TextIO) -> None:
+    box = _load(args)
+    if args.to == "all":
+        for name in FORMATS:
+            try:
+                value = _out(box, name, args.precision)
+            except (ValueError, ImportError) as exc:
+                value = f"(n/a: {exc})"
+            out.write(f"{name:<13} {value}\n")
+        return
+    out.write(_out(box, args.to, args.precision) + "\n")
+
+
+def _cmd_info(args: argparse.Namespace, out: TextIO) -> None:
+    box = _load(args)
+    lon, lat = box.center
+    info: Dict[str, Any] = {
+        "bbox": list(box.bounds),
+        "crs": box.crs,
+        "crosses_antimeridian": box.crosses_antimeridian,
+        "width": box.width,
+        "height": box.height,
+        "center": [lon, lat],
+        "area_km2": box.area_km2(),
+    }
+    if box.is_geographic:
+        info["width_m"] = box.width_m
+        info["height_m"] = box.height_m
+    out.write(json.dumps(info, indent=2) + "\n")
+
+
+def _cmd_area(args: argparse.Namespace, out: TextIO) -> None:
+    area = _load(args).area_km2()
+    out.write(f"{area:.{args.digits}f}\n")
+
+
+def _cmd_tiles(args: argparse.Namespace, out: TextIO) -> None:
+    box = _load(args)
+    if args.count:
+        out.write(f"{box.tile_count(args.zoom)}\n")
+        return
+    for t in box.tiles(args.zoom, max_tiles=args.max):
+        if args.format == "quadkey":
+            out.write(t.quadkey + "\n")
+        elif args.format == "wsen":
+            out.write(BBox(*t.bounds).to_wsen() + "\n")
+        else:
+            out.write(f"{t}\n")
+
+
+def _write_boxes(boxes: Sequence[BBox], fmt: str, precision: Optional[int], out: TextIO) -> None:
+    if fmt == "geojson":
+        fc = {
+            "type": "FeatureCollection",
+            "features": [
+                b.to_geojson(feature=True, properties={"id": i}) for i, b in enumerate(boxes)
+            ],
+        }
+        out.write(json.dumps(fc) + "\n")
+        return
+    for b in boxes:
+        out.write(_out(b, fmt, precision) + "\n")
+
+
+def _cmd_split(args: argparse.Namespace, out: TextIO) -> None:
+    box = _load(args)
+    if args.grid:
+        nx, ny = _grid_spec(args.grid)
+        cells = box.grid(nx, ny)
+    else:
+        cy = parse_distance(args.cell_y) if args.cell_y else None
+        cells = box.split(parse_distance(args.cell), cy, max_cells=args.max)
+    _write_boxes(cells, args.to, args.precision, out)
+
+
+def _cmd_buffer(args: argparse.Namespace, out: TextIO) -> None:
+    box = _load(args).buffer(parse_distance(args.distance))
+    out.write(_out(box, args.to, args.precision) + "\n")
+
+
+def _cmd_reproject(args: argparse.Namespace, out: TextIO) -> None:
+    box = _load(args)
+    if args.target.lower() == "utm":
+        res = box.to_utm()
+    else:
+        res = box.to_crs(args.target, densify=args.densify)
+    text = _out(res, args.to, args.precision)
+    out.write(f"{text}\n" if args.quiet else f"{text}  ({res.crs})\n")
+
+
+def _cmd_geocode(args: argparse.Namespace, out: TextIO) -> None:
+    from .nominatim import geocode_bbox
+
+    box = geocode_bbox(
+        " ".join(args.query),
+        user_agent=args.user_agent,
+        email=args.email,
+        timeout=args.timeout,
+        base_url=args.server,
+    )
+    out.write(_out(box, args.to, args.precision) + "\n")
+
+
+def _cmd_formats(args: argparse.Namespace, out: TextIO) -> None:
+    out.write("Output formats (--to):\n")
+    for name, desc in FORMATS.items():
+        out.write(f"  {name:<13} {desc}\n")
+    out.write("Aliases: " + ", ".join(f"{a}={b}" for a, b in FORMAT_ALIASES.items()) + "\n")
+    out.write("Input formats (--from; detected automatically when omitted):\n")
+    out.write("  " + ", ".join(sorted(PARSERS)) + ", wsen, swne\n")
+
+
+def _format_choice(text: str) -> str:
+    key = text.lower().replace("_", "-")
+    if key != "all" and key not in FORMATS and key not in FORMAT_ALIASES:
+        raise argparse.ArgumentTypeError(f"unknown format {text!r} (see 'bboxkit formats')")
+    return key
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bboxkit",
+        description="Parse, convert and operate on bounding boxes.",
+        epilog="Boxes starting with '-' (e.g. -122.5,37.7,...) work as they are.",
+    )
+    parser.add_argument("--version", action="version", version=f"bboxkit {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.required = True
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("bbox", nargs="+", help="bounding box in any format ('-' reads stdin)")
+    common.add_argument(
+        "--from",
+        dest="source_format",
+        metavar="FMT",
+        help="input format, e.g. wsen, swne, wkt, tile (default: detect)",
+    )
+    common.add_argument(
+        "--order",
+        choices=["wsen", "swne"],
+        help="order of four plain numbers (default: guess, with a warning)",
+    )
+    common.add_argument("--crs", help="CRS of the input coordinates (default EPSG:4326)")
+    common.add_argument("--precision", type=int, metavar="N", help="decimal places in the output")
+
+    def add(
+        name: str,
+        func: Callable[[argparse.Namespace, TextIO], None],
+        help_: str,
+        with_bbox: bool = True,
+    ) -> argparse.ArgumentParser:
+        p = sub.add_parser(
+            name, parents=[common] if with_bbox else [], help=help_, description=help_
+        )
+        p.set_defaults(func=func)
+        return p
+
+    p = add("convert", _cmd_convert, "convert a box to another format")
+    p.add_argument(
+        "--to", type=_format_choice, default="wsen", help="output format, or 'all' (default wsen)"
+    )
+
+    add("info", _cmd_info, "print size, centre and area as JSON")
+
+    p = add("area", _cmd_area, "area in square kilometres (ellipsoidal)")
+    p.add_argument("--digits", type=int, default=3, help="decimals to print (default 3)")
+
+    p = add("tiles", _cmd_tiles, "list XYZ tiles covering the box")
+    p.add_argument("--zoom", "-z", type=int, required=True)
+    p.add_argument("--format", choices=["zxy", "quadkey", "wsen"], default="zxy")
+    p.add_argument("--count", action="store_true", help="only print the number of tiles")
+    p.add_argument("--max", type=int, default=100_000, help="refuse more tiles (default 100000)")
+
+    p = add("split", _cmd_split, "split into cells of a given size or an n x m grid")
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument("--cell", help="cell size, e.g. 1km or 500m")
+    g.add_argument("--grid", help="columns x rows, e.g. 4x3")
+    p.add_argument("--cell-y", help="cell height if different from --cell")
+    p.add_argument("--to", type=_format_choice, default="wsen")
+    p.add_argument("--max", type=int, default=100_000, help="refuse more cells (default 100000)")
+
+    p = add("buffer", _cmd_buffer, "grow (or shrink) the box by a distance")
+    p.add_argument("--distance", "-d", required=True, help="e.g. 500m, 2km, -100m")
+    p.add_argument("--to", type=_format_choice, default="wsen")
+
+    p = add("reproject", _cmd_reproject, "reproject to EPSG:3857, UTM or (with pyproj) any CRS")
+    p.add_argument(
+        "--to-crs",
+        dest="target",
+        required=True,
+        help="target CRS, e.g. EPSG:3857, EPSG:32635 or 'utm' for the local zone",
+    )
+    p.add_argument("--densify", type=int, default=21)
+    p.add_argument("--to", type=_format_choice, default="wsen")
+    p.add_argument("--quiet", "-q", action="store_true", help="do not print the CRS")
+
+    p = add(
+        "geocode",
+        _cmd_geocode,
+        "look up a place name on Nominatim (network; usage policy applies)",
+        with_bbox=False,
+    )
+    p.add_argument("query", nargs="+", help="place name")
+    p.add_argument("--to", type=_format_choice, default="wsen")
+    p.add_argument("--precision", type=int, metavar="N")
+    p.add_argument("--user-agent", help="identify your application (recommended)")
+    p.add_argument("--email", help="contact address sent to Nominatim")
+    p.add_argument("--timeout", type=float, default=10.0)
+    p.add_argument("--server", default="https://nominatim.openstreetmap.org/search")
+
+    add("formats", _cmd_formats, "list supported formats", with_bbox=False)
+    return parser
+
+
+_DASH_VALUE = re.compile(r"^-(?:\d|\.\d|te\s|projwin\s|spat\s)")
+
+
+def _protect(argv: Sequence[str]) -> List[str]:
+    """Keep argparse from mistaking '-122.5,37.7,...' or '-te 1 2 3 4' for options."""
+    return [
+        f" {a}" if _DASH_VALUE.match(a) and (" " in a or "," in a or ";" in a) else a for a in argv
+    ]
+
+
+def main(argv: Optional[Sequence[str]] = None, out: Optional[TextIO] = None) -> int:
+    """Entry point; returns the process exit code."""
+    stream = out if out is not None else sys.stdout
+    args = build_parser().parse_args(_protect(sys.argv[1:] if argv is None else argv))
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        try:
+            args.func(args, stream)
+        except (ValueError, TypeError, LookupError, ImportError, OSError) as exc:
+            for w in caught:
+                sys.stderr.write(f"bboxkit: warning: {w.message}\n")
+            sys.stderr.write(f"bboxkit: error: {exc}\n")
+            return 2
+    for w in caught:
+        sys.stderr.write(f"bboxkit: warning: {w.message}\n")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

bboxkit/crs.py

@@ -0,0 +1,380 @@
+"""Coordinate reference systems: names, Web Mercator and UTM, optional pyproj.
+
+Built in (no dependencies):
+
+* geographic WGS 84 (``EPSG:4326``, also written ``OGC:CRS84``, ``WGS84``),
+* Web Mercator (``EPSG:3857`` and its historical aliases),
+* UTM on WGS 84 (``EPSG:32601``-``32660`` north, ``EPSG:32701``-``32760`` south)
+  using the 6th-order Krueger series (nanometre-level accuracy within a zone).
+
+Any other CRS is handed to :mod:`pyproj` when it is installed
+(``pip install bboxkit[pyproj]``).
+"""
+
+from __future__ import annotations
+
+import functools
+import math
+import re
+from typing import Any, Callable, List, Optional, Tuple, Union
+
+from ._geo import MERCATOR_MAX_LAT, WGS84_A, WGS84_E, WGS84_N
+
+__all__ = [
+    "WGS84",
+    "WEB_MERCATOR",
+    "normalize_crs",
+    "is_geographic",
+    "is_builtin",
+    "utm_zone",
+    "utm_crs",
+    "utm_zone_of_crs",
+    "lonlat_to_mercator",
+    "mercator_to_lonlat",
+    "lonlat_to_utm",
+    "utm_to_lonlat",
+    "transform_point",
+]
+
+WGS84 = "EPSG:4326"
+WEB_MERCATOR = "EPSG:3857"
+
+CRSLike = Union[str, int]
+
+_ALIASES = {
+    "WGS84": WGS84,
+    "WGS 84": WGS84,
+    "CRS84": WGS84,
+    "OGC:CRS84": WGS84,
+    "EPSG:4326": WGS84,
+    "EPSG:3857": WEB_MERCATOR,
+    "EPSG:900913": WEB_MERCATOR,
+    "EPSG:3785": WEB_MERCATOR,
+    "EPSG:102100": WEB_MERCATOR,
+    "EPSG:102113": WEB_MERCATOR,
+    "ESRI:102100": WEB_MERCATOR,
+    "ESRI:102113": WEB_MERCATOR,
+}
+
+# Geographic (lon/lat degree) CRSs recognised without pyproj. Only EPSG:4326
+# can be transformed without pyproj; the others are known to use degrees, so
+# bounding boxes in them get latitude checks and antimeridian semantics.
+_GEOGRAPHIC = {
+    WGS84,
+    "EPSG:4258",  # ETRS89
+    "EPSG:4269",  # NAD83
+    "EPSG:4283",  # GDA94
+    "EPSG:7844",  # GDA2020
+    "EPSG:4167",  # NZGD2000
+    "EPSG:4490",  # CGCS2000
+    "EPSG:4612",  # JGD2000
+    "EPSG:6668",  # JGD2011
+    "EPSG:4674",  # SIRGAS 2000
+    "EPSG:4019",  # GRS 1980 unknown datum
+}
+
+_URN = re.compile(r"^urn:ogc:def:crs:(EPSG|OGC):[^:]*:(\w+)$", re.IGNORECASE)
+_HTTP = re.compile(r"^https?://www\.opengis\.net/def/crs/(EPSG|OGC)/[^/]+/(\w+)$", re.IGNORECASE)
+_AUTH = re.compile(r"^(EPSG|ESRI|OGC)\s*:{1,2}\s*(\w+)$", re.IGNORECASE)
+
+
+def normalize_crs(crs: CRSLike) -> str:
+    """Return a canonical ``AUTHORITY:CODE`` string for common CRS spellings.
+
+    ``4326``, ``"epsg:4326"``, ``"urn:ogc:def:crs:EPSG::4326"``,
+    ``"http://www.opengis.net/def/crs/OGC/1.3/CRS84"`` and ``"WGS84"`` all map to
+    ``"EPSG:4326"`` (bounding boxes in this package are always x/lon first, so
+    CRS84 and EPSG:4326 are the same thing here). Unknown strings such as
+    PROJ or WKT definitions are returned stripped but otherwise unchanged.
+    """
+    if isinstance(crs, bool):
+        raise TypeError("crs must be a string or an integer EPSG code")
+    if isinstance(crs, int):
+        text = f"EPSG:{crs}"
+    elif isinstance(crs, str):
+        text = crs.strip()
+        if not text:
+            raise ValueError("crs must not be empty")
+    else:
+        raise TypeError("crs must be a string or an integer EPSG code")
+    for pattern in (_URN, _HTTP, _AUTH):
+        m = pattern.match(text)
+        if m:
+            text = f"{m.group(1).upper()}:{m.group(2).upper()}"
+            break
+    else:
+        if text.isdigit():
+            text = f"EPSG:{text}"
+    return _ALIASES.get(text.upper(), _ALIASES.get(text, text))
+
+
+@functools.lru_cache(maxsize=256)
+def _pyproj_is_geographic(crs: str) -> bool:
+    try:
+        from pyproj import CRS
+    except ImportError:
+        return False
+    try:
+        return bool(CRS.from_user_input(crs).is_geographic)
+    except Exception:  # noqa: BLE001 - any parse failure means "not geographic"
+        return False
+
+
+def is_geographic(crs: CRSLike) -> bool:
+    """True if coordinates in ``crs`` are longitude/latitude degrees."""
+    c = normalize_crs(crs)
+    if c in _GEOGRAPHIC:
+        return True
+    if c == WEB_MERCATOR or utm_zone_of_crs(c) is not None:
+        return False
+    return _pyproj_is_geographic(c)
+
+
+def is_builtin(crs: CRSLike) -> bool:
+    """True if ``crs`` can be transformed without pyproj."""
+    c = normalize_crs(crs)
+    return c in (WGS84, WEB_MERCATOR) or utm_zone_of_crs(c) is not None
+
+
+# --------------------------------------------------------------------------
+# UTM zones
+# --------------------------------------------------------------------------
+
+
+def utm_zone(lon: float, lat: float) -> int:
+    """UTM zone number for a point, with the Norway and Svalbard exceptions."""
+    if not -180.0 <= lon <= 180.0:
+        lon = (lon + 180.0) % 360.0 - 180.0
+    zone = int((lon + 180.0) // 6.0) % 60 + 1
+    if 56.0 <= lat < 64.0 and 3.0 <= lon < 12.0:
+        return 32
+    if 72.0 <= lat <= 84.0 and 0.0 <= lon < 42.0:
+        if lon < 9.0:
+            return 31
+        if lon < 21.0:
+            return 33
+        if lon < 33.0:
+            return 35
+        return 37
+    return zone
+
+
+def utm_crs(zone: int, south: bool = False) -> str:
+    """EPSG code string of a WGS 84 / UTM zone."""
+    if not 1 <= zone <= 60:
+        raise ValueError(f"UTM zone must be 1..60, got {zone}")
+    return f"EPSG:{32700 + zone if south else 32600 + zone}"
+
+
+def utm_zone_of_crs(crs: str) -> Optional[Tuple[int, bool]]:
+    """``(zone, south)`` if ``crs`` is a WGS 84 or ETRS89 UTM CRS, else None."""
+    m = re.match(r"^EPSG:(\d+)$", crs)
+    if not m:
+        return None
+    code = int(m.group(1))
+    if 32601 <= code <= 32660:
+        return (code - 32600, False)
+    if 32701 <= code <= 32760:
+        return (code - 32700, True)
+    if 25828 <= code <= 25838:  # ETRS89 / UTM 28N-38N, identical to WGS 84 at this level
+        return (code - 25800, False)
+    return None
+
+
+# --------------------------------------------------------------------------
+# Web Mercator
+# --------------------------------------------------------------------------
+
+
+def lonlat_to_mercator(lon: float, lat: float) -> Tuple[float, float]:
+    """Project to EPSG:3857 metres. Latitude is clamped to +-85.0511 degrees.
+
+    Longitudes are not wrapped, so values beyond +-180 give x beyond the
+    usual +-20037508.34 m, which keeps antimeridian-crossing boxes contiguous.
+    """
+    lat = max(-MERCATOR_MAX_LAT, min(MERCATOR_MAX_LAT, lat))
+    x = WGS84_A * math.radians(lon)
+    y = WGS84_A * math.log(math.tan(math.pi / 4.0 + math.radians(lat) / 2.0))
+    return (x, y)
+
+
+def mercator_to_lonlat(x: float, y: float) -> Tuple[float, float]:
+    """Inverse of :func:`lonlat_to_mercator` (longitude is not wrapped)."""
+    lon = math.degrees(x / WGS84_A)
+    lat = math.degrees(2.0 * math.atan(math.exp(y / WGS84_A)) - math.pi / 2.0)
+    return (lon, lat)
+
+
+# --------------------------------------------------------------------------
+# Transverse Mercator (Krueger series, Karney 2011) for UTM
+# --------------------------------------------------------------------------
+
+_K0 = 0.9996
+_n = WGS84_N
+_A = WGS84_A / (1.0 + _n) * (1.0 + _n**2 / 4.0 + _n**4 / 64.0 + _n**6 / 256.0)
+_ALPHA = (
+    _n / 2 - 2 * _n**2 / 3 + 5 * _n**3 / 16 + 41 * _n**4 / 180 - 127 * _n**5 / 288
+    + 7891 * _n**6 / 37800,
+    13 * _n**2 / 48 - 3 * _n**3 / 5 + 557 * _n**4 / 1440 + 281 * _n**5 / 630
+    - 1983433 * _n**6 / 1935360,
+    61 * _n**3 / 240 - 103 * _n**4 / 140 + 15061 * _n**5 / 26880 + 167603 * _n**6 / 181440,
+    49561 * _n**4 / 161280 - 179 * _n**5 / 168 + 6601661 * _n**6 / 7257600,
+    34729 * _n**5 / 80640 - 3418889 * _n**6 / 1995840,
+    212378941 * _n**6 / 319334400,
+)  # fmt: skip
+_BETA = (
+    _n / 2 - 2 * _n**2 / 3 + 37 * _n**3 / 96 - _n**4 / 360 - 81 * _n**5 / 512
+    + 96199 * _n**6 / 604800,
+    _n**2 / 48 + _n**3 / 15 - 437 * _n**4 / 1440 + 46 * _n**5 / 105 - 1118711 * _n**6 / 3870720,
+    17 * _n**3 / 480 - 37 * _n**4 / 840 - 209 * _n**5 / 4480 + 5569 * _n**6 / 90720,
+    4397 * _n**4 / 161280 - 11 * _n**5 / 504 - 830251 * _n**6 / 7257600,
+    4583 * _n**5 / 161280 - 108847 * _n**6 / 3991680,
+    20648693 * _n**6 / 638668800,
+)  # fmt: skip
+
+
+def _tm_forward(dlon: float, lat: float) -> Tuple[float, float]:
+    """Transverse Mercator x, y (unscaled by k0) for a longitude offset."""
+    phi = math.radians(lat)
+    lam = math.radians(dlon)
+    if abs(lat) >= 90.0:
+        tau_p = math.copysign(math.inf, lat)
+    else:
+        tau = math.tan(phi)
+        sigma = math.sinh(WGS84_E * math.atanh(WGS84_E * tau / math.sqrt(1.0 + tau * tau)))
+        tau_p = tau * math.sqrt(1.0 + sigma * sigma) - sigma * math.sqrt(1.0 + tau * tau)
+    cos_lam = math.cos(lam)
+    if math.isinf(tau_p):
+        xi_p = math.copysign(math.pi / 2.0, tau_p)
+        eta_p = 0.0
+    else:
+        xi_p = math.atan2(tau_p, cos_lam)
+        eta_p = math.asinh(math.sin(lam) / math.sqrt(tau_p * tau_p + cos_lam * cos_lam))
+    xi = xi_p
+    eta = eta_p
+    for j, a in enumerate(_ALPHA, start=1):
+        xi += a * math.sin(2 * j * xi_p) * math.cosh(2 * j * eta_p)
+        eta += a * math.cos(2 * j * xi_p) * math.sinh(2 * j * eta_p)
+    return (_A * eta, _A * xi)
+
+
+def _tm_inverse(x: float, y: float) -> Tuple[float, float]:
+    """Inverse of :func:`_tm_forward`: returns (longitude offset, latitude)."""
+    eta = x / _A
+    xi = y / _A
+    xi_p = xi
+    eta_p = eta
+    for j, b in enumerate(_BETA, start=1):
+        xi_p -= b * math.sin(2 * j * xi) * math.cosh(2 * j * eta)
+        eta_p -= b * math.cos(2 * j * xi) * math.sinh(2 * j * eta)
+    sinh_eta = math.sinh(eta_p)
+    sin_xi = math.sin(xi_p)
+    cos_xi = math.cos(xi_p)
+    denom = math.sqrt(sinh_eta * sinh_eta + cos_xi * cos_xi)
+    if denom == 0.0:
+        return (0.0, math.copysign(90.0, sin_xi))
+    tau_p = sin_xi / denom
+    tau = tau_p
+    e2 = WGS84_E * WGS84_E
+    for _ in range(20):
+        sigma = math.sinh(WGS84_E * math.atanh(WGS84_E * tau / math.sqrt(1.0 + tau * tau)))
+        tau_i = tau * math.sqrt(1.0 + sigma * sigma) - sigma * math.sqrt(1.0 + tau * tau)
+        d_tau = (
+            (tau_p - tau_i)
+            / math.sqrt(1.0 + tau_i * tau_i)
+            * (1.0 + (1.0 - e2) * tau * tau)
+            / ((1.0 - e2) * math.sqrt(1.0 + tau * tau))
+        )
+        tau += d_tau
+        if abs(d_tau) < 1e-14:
+            break
+    lat = math.degrees(math.atan(tau))
+    dlon = math.degrees(math.atan2(sinh_eta, cos_xi))
+    return (dlon, lat)
+
+
+def _central_meridian(zone: int) -> float:
+    return zone * 6.0 - 183.0
+
+
+def lonlat_to_utm(lon: float, lat: float, zone: int, south: bool) -> Tuple[float, float]:
+    """WGS 84 lon/lat to UTM easting/northing in the given zone."""
+    dlon = (lon - _central_meridian(zone) + 180.0) % 360.0 - 180.0
+    x, y = _tm_forward(dlon, lat)
+    return (500000.0 + _K0 * x, _K0 * y + (10000000.0 if south else 0.0))
+
+
+def utm_to_lonlat(easting: float, northing: float, zone: int, south: bool) -> Tuple[float, float]:
+    """UTM easting/northing to lon/lat. Longitude is CM + offset (not wrapped)."""
+    x = (easting - 500000.0) / _K0
+    y = (northing - (10000000.0 if south else 0.0)) / _K0
+    dlon, lat = _tm_inverse(x, y)
+    return (_central_meridian(zone) + dlon, lat)
+
+
+# --------------------------------------------------------------------------
+# Point transforms between built-in CRSs
+# --------------------------------------------------------------------------
+
+Point = Tuple[float, float]
+
+
+def _to_lonlat_fn(crs: str) -> Callable[[float, float], Point]:
+    if crs == WGS84:
+        return lambda x, y: (x, y)
+    if crs == WEB_MERCATOR:
+        return mercator_to_lonlat
+    utm = utm_zone_of_crs(crs)
+    if utm is not None:
+        zone, south = utm
+        return lambda x, y: utm_to_lonlat(x, y, zone, south)
+    raise ValueError(f"{crs} is not a built-in CRS")
+
+
+def _from_lonlat_fn(crs: str) -> Callable[[float, float], Point]:
+    if crs == WGS84:
+        return lambda x, y: (x, y)
+    if crs == WEB_MERCATOR:
+        return lonlat_to_mercator
+    utm = utm_zone_of_crs(crs)
+    if utm is not None:
+        zone, south = utm
+        return lambda x, y: lonlat_to_utm(x, y, zone, south)
+    raise ValueError(f"{crs} is not a built-in CRS")
+
+
+def transform_point(x: float, y: float, src: CRSLike, dst: CRSLike) -> Point:
+    """Transform one point between CRSs (built-in, else pyproj)."""
+    s, d = normalize_crs(src), normalize_crs(dst)
+    if s == d:
+        return (x, y)
+    if is_builtin(s) and is_builtin(d):
+        lon, lat = _to_lonlat_fn(s)(x, y)
+        return _from_lonlat_fn(d)(lon, lat)
+    t = _pyproj_transformer(s, d)
+    tx, ty = t.transform(x, y)
+    return (float(tx), float(ty))
+
+
+def transform_points(points: List[Point], src: str, dst: str) -> List[Point]:
+    """Transform many points between two built-in CRSs via lon/lat."""
+    to_ll = _to_lonlat_fn(src)
+    from_ll = _from_lonlat_fn(dst)
+    return [from_ll(*to_ll(x, y)) for x, y in points]
+
+
+def require_pyproj() -> Any:
+    """Import pyproj or raise an ImportError with installation advice."""
+    try:
+        import pyproj
+    except ImportError as exc:  # pragma: no cover - exercised only without pyproj
+        raise ImportError(
+            "this CRS needs pyproj; install it with: pip install bboxkit[pyproj]"
+        ) from exc
+    return pyproj
+
+
+@functools.lru_cache(maxsize=64)
+def _pyproj_transformer(src: str, dst: str) -> Any:
+    pyproj = require_pyproj()
+    return pyproj.Transformer.from_crs(src, dst, always_xy=True)