whatcrs 0.1.0__py3-none-any.whl

whatcrs/__init__.py

@@ -0,0 +1,41 @@
+"""whatcrs - "What CRS is this?"
+
+Guess the coordinate reference system of mystery coordinates and rank
+candidate EPSG codes with explanations::
+
+    >>> import whatcrs
+    >>> best = whatcrs.guess_crs([(440000, 4474000)], hint="Spain")[0]
+    >>> best.epsg
+    25830
+
+Works offline with a bundled set of ~900 widely used CRSs and pure-Python
+inverse projections; installs with ``pyproj`` widen the search to every EPSG
+projected CRS.
+"""
+
+from __future__ import annotations
+
+from .core import Candidate, describe_coordinates, fix_swapped_axes, guess_crs, to_lonlat
+from .crs_db import CRSRecord, builtin_records, pyproj_available
+from .readers import PointSource, read_points, read_text
+from .regions import Region, country_at, parse_hint
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Candidate",
+    "CRSRecord",
+    "PointSource",
+    "Region",
+    "__version__",
+    "builtin_records",
+    "country_at",
+    "describe_coordinates",
+    "fix_swapped_axes",
+    "guess_crs",
+    "parse_hint",
+    "pyproj_available",
+    "read_points",
+    "read_text",
+    "to_lonlat",
+]

whatcrs/__main__.py

@@ -0,0 +1,3 @@
+from whatcrs.cli import main
+
+raise SystemExit(main())

whatcrs/cli.py

@@ -0,0 +1,192 @@
+"""Command line interface: ``whatcrs``.
+
+Examples::
+
+    whatcrs 512345 4182345
+    whatcrs 512345 4182345 --hint Spain
+    whatcrs data.csv --x lon --y lat --hint "Spain"
+    whatcrs shapes.geojson --json
+    whatcrs "POINT (2600000 1200000)"
+    cat points.csv | whatcrs -
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence, TextIO
+
+from . import __version__
+from .core import Candidate, describe_coordinates, guess_crs
+from .crs_db import pyproj_available
+from .readers import PointSource, read_points, read_text
+
+_NUMBER = re.compile(r"^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="whatcrs",
+        description=(
+            "What CRS is this? Guess the coordinate reference system of mystery coordinates "
+            "and rank candidate EPSG codes with explanations."
+        ),
+        epilog=(
+            "INPUT is either numbers (x y [x y ...], also 'x,y'), a CSV/GeoJSON/WKT file, "
+            "a WKT string, or '-' for standard input."
+        ),
+    )
+    p.add_argument("input", nargs="+", metavar="INPUT", help="coordinates, a file, WKT or '-'")
+    p.add_argument("--hint", help='where the data should be, e.g. "Spain", "Texas", "Europe"')
+    p.add_argument(
+        "--bbox",
+        help="expected area as west,south,east,north in degrees (use --bbox=-10,35,5,44 "
+        "when the first value is negative)",
+    )
+    p.add_argument("--units", help="known linear unit: m, ft or deg")
+    p.add_argument(
+        "--x", dest="xcol", help="CSV column with the first coordinate (name or 0-based index)"
+    )
+    p.add_argument("--y", dest="ycol", help="CSV column with the second coordinate")
+    p.add_argument("--delimiter", help="CSV delimiter (default: sniffed)")
+    p.add_argument(
+        "--format", dest="fmt", choices=["csv", "tsv", "geojson", "wkt"], help="input format"
+    )
+    p.add_argument("--top", type=int, default=5, help="number of candidates to show (default 5)")
+    p.add_argument("--json", action="store_true", help="print JSON")
+    p.add_argument(
+        "--no-pyproj",
+        action="store_true",
+        help="use only the bundled CRS subset even if pyproj is installed",
+    )
+    p.add_argument("--no-swap", action="store_true", help="do not consider swapped axes")
+    p.add_argument("--version", action="version", version=f"whatcrs {__version__}")
+    return p
+
+
+def _parse_numbers(tokens: Sequence[str]) -> Optional[List[float]]:
+    values: List[float] = []
+    for tok in tokens:
+        for part in re.split(r"[,;\s]+", tok.strip()):
+            if not part:
+                continue
+            if not _NUMBER.match(part):
+                return None
+            values.append(float(part))
+    return values
+
+
+def _load(args: argparse.Namespace) -> PointSource:
+    tokens: List[str] = args.input
+    numbers = _parse_numbers(tokens)
+    if numbers is not None:
+        if len(numbers) < 2 or len(numbers) % 2:
+            raise ValueError("give coordinates as pairs: x y [x y ...]")
+        pts = [(numbers[i], numbers[i + 1]) for i in range(0, len(numbers), 2)]
+        return PointSource(pts, "arguments")
+    if len(tokens) != 1:
+        raise ValueError("give either numbers, or a single file / WKT string / '-'")
+    tok = tokens[0]
+    if tok == "-":
+        return read_text(
+            sys.stdin.read(), args.fmt, x=args.xcol, y=args.ycol, delimiter=args.delimiter
+        )
+    path = Path(tok)
+    if path.is_file():
+        return read_points(path, x=args.xcol, y=args.ycol, delimiter=args.delimiter, fmt=args.fmt)
+    if re.match(r"^\s*(SRID\s*=\s*\d+\s*;\s*)?[A-Za-z]+\s*(Z|M|ZM)?\s*\(", tok):
+        return read_text(tok, "wkt")
+    raise ValueError(f"not a number list, an existing file or WKT: {tok!r}")
+
+
+def _hemi(lon: float, lat: float) -> str:
+    return f"{abs(lat):.5f}°{'N' if lat >= 0 else 'S'} {abs(lon):.5f}°{'E' if lon >= 0 else 'W'}"
+
+
+def _print_text(src: PointSource, cands: List[Candidate], out: TextIO, hint: Optional[str]) -> None:
+    n = len(src.points)
+    x0, y0 = src.points[0]
+    fields = f" (x={src.x_field}, y={src.y_field})" if src.x_field else ""
+    out.write(
+        f"whatcrs {__version__}: {n} point{'s' if n != 1 else ''} from {src.format}{fields}\n"
+    )
+    out.write(f"first point: {x0:.10g}, {y0:.10g}\n")
+    for note in src.notes:
+        out.write(f"note: {note}\n")
+    for note in describe_coordinates(src.points):
+        out.write(f"pattern: {note}\n")
+    if src.declared_crs:
+        out.write(f"declared in file: {src.declared_crs}\n")
+    if hint:
+        out.write(f"hint: {hint}\n")
+    if not cands:
+        out.write("\nNo candidate CRS fits these coordinates.\n")
+        return
+    out.write("\n")
+    for i, c in enumerate(cands, 1):
+        swap = "  [axes swapped]" if c.swapped else ""
+        out.write(f"{i}. {c.code}  {c.name}  - confidence {c.confidence:.0%}{swap}\n")
+        where = f" ({c.country})" if c.country else " (at sea)"
+        out.write(f"   centre: {_hemi(*c.centroid)}{where}\n")
+        label = "WGS 84" if c.wgs84 else "lon/lat"
+        sample = "; ".join(f"{lon:.5f}, {lat:.5f}" for lon, lat in c.sample_lonlat[:3])
+        out.write(f"   {label}: {sample}\n")
+        for r in c.reasons:
+            out.write(f"   - {r}\n")
+    if src.declared_crs and src.declared_crs.startswith("EPSG:"):
+        best = cands[0].code
+        verdict = "agrees with" if best == src.declared_crs else "differs from"
+        out.write(f"\nBest guess {best} {verdict} the declared {src.declared_crs}.\n")
+    if not pyproj_available():
+        out.write("\n(bundled CRS subset; `pip install whatcrs[pyproj]` searches all EPSG codes)\n")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(errors="replace")
+            except (ValueError, OSError):  # pragma: no cover - exotic streams
+                pass
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        src = _load(args)
+        bbox = None
+        if args.bbox:
+            bbox = [float(v) for v in re.split(r"[,\s]+", args.bbox.strip()) if v]
+        cands = guess_crs(
+            src.points,
+            args.hint,
+            bbox=bbox,
+            units=args.units,
+            top=max(1, args.top),
+            use_pyproj=False if args.no_pyproj else None,
+            allow_swapped=not args.no_swap,
+        )
+    except (ValueError, KeyError, OSError) as exc:
+        parser.exit(2, f"whatcrs: error: {exc}\n")
+    if args.json:
+        payload = {
+            "version": __version__,
+            "n_points": len(src.points),
+            "format": src.format,
+            "x_field": src.x_field,
+            "y_field": src.y_field,
+            "declared_crs": src.declared_crs,
+            "hint": args.hint,
+            "pattern": describe_coordinates(src.points),
+            "candidates": [c.to_dict() for c in cands],
+        }
+        sys.stdout.write(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
+    else:
+        _print_text(src, cands, sys.stdout, args.hint)
+    return 0 if cands else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())