openverto 0.1.1__tar.gz

openverto-0.1.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.3
+Name: openverto
+Version: 0.1.1
+Summary: Python CLI and library for the official IGM Verto Online coordinate transforms between Italian reference systems
+Keywords: igm,verto,coordinate,epsg,crs,italy,rdn2008,gauss-boaga,open-data
+Author: Andrea Borruso
+Author-email: Andrea Borruso <aborruso@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: typer>=0.24.1
+Requires-Dist: rich>=14.0.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/ondata/openverto
+Project-URL: Issues, https://github.com/ondata/openverto/issues
+Description-Content-Type: text/markdown
+
+# openverto
+
+> Tool sperimentale — aiutaci a testarlo [aprendo issue](https://github.com/ondata/openverto/issues) o inviando feedback.
+
+CLI e libreria Python per il servizio ufficiale **IGM Verto Online**: trasforma coordinate tra tutti i sistemi di riferimento italiani (Roma40, ED50, IGM95, ETRS89, RDN2008) **senza installare le griglie NTv2**, appoggiandosi al servizio autorevole dell'Istituto Geografico Militare.
+
+Pensato per essere **orchestrato da agenti AI**: output `--json`/`--jsonl`/`--csv`, non interattivo, pipeable, read-only. L'intelligenza sugli EPSG (`inspect`, `detect`, `targets`) è completamente **offline**.
+
+## Installazione
+
+Come strumento CLI (consigliato):
+
+```bash
+uv tool install openverto
+```
+
+Come libreria:
+
+```bash
+uv add openverto    # oppure: pip install openverto
+```
+
+## Avvio rapido (CLI)
+
+```bash
+# i 20 sistemi di riferimento supportati (cache offline dopo la prima volta)
+openverto systems
+
+# converti una coordinata Roma40 -> RDN2008 (lon lat)
+openverto convert --from 4265 --to 6706 12.4924 41.8902
+
+# asse, fuso e false easting prima di una conversione proiettata
+openverto inspect 3003
+
+# converti un CSV di punti Gauss-Boaga (colonne est/nord) in RDN2008/TM32
+openverto batch catasto.csv --from 3003 --to 6707 --e-col est --n-col nord --out out.csv
+
+# riproietta le geometrie di un GeoJSON
+openverto geojson aree.geojson --from 4230 --to 6706 --out out.geojson
+```
+
+## Formati di output
+
+Globale, con `-o/--output`:
+
+```bash
+openverto systems                 # tabella (default in terminale)
+openverto -o json systems         # JSON
+openverto -o jsonl convert ...    # JSON Lines: un oggetto compatto per riga (ideale per coordinate)
+openverto -o csv convert ...      # CSV
+```
+
+`jsonl` è il formato più adatto allo streaming di coordinate verso `jq` o pipeline.
+
+## Comandi
+
+| Comando | Descrizione |
+|---|---|
+| `systems` | Elenco dei sistemi di riferimento supportati (EPSG + descrizione) |
+| `convert` | Converte una o più coordinate (`e n`, o `e,n` da stdin) |
+| `batch` | Converte un CSV in CSV o GeoJSON (auto-chunk a 32000, `--skip-invalid`) |
+| `geojson` | Riproietta le geometrie di un file GeoJSON |
+| `inspect` | Famiglia datum, ordine assi, unità, fuso, false easting di un EPSG |
+| `detect` | Indovina il sistema di origine di una coordinata dalla sua magnitudine |
+| `targets` | Destinazioni di conversione valide per un EPSG (datum diverso) |
+| `roundtrip` | Converte A→B→A e riporta l'errore residuo del datum |
+| `cache` | Ispeziona o svuota la cache offline |
+| `doctor` | Verifica la connettività al servizio |
+
+### Funzioni distintive
+
+- **`roundtrip`** — certifica che una catena di datum sia lossless entro tolleranza prima di pubblicare dati.
+- **`detect`** — recupera l'EPSG reale di un dataset etichettato vagamente ("UTM", "Gauss-Boaga").
+- **`inspect` / `targets`** — disambigua sistemi simili (3003 vs 3004) ed evita destinazioni con lo stesso datum (rifiutate dal servizio).
+- **cache offline** — replay riproducibile delle conversioni in CI o pipeline offline.
+
+## Uso come libreria
+
+```python
+import openverto as ov
+
+# elenco sistemi
+ov.systems()                          # [{"epsg": 4265, "descrizione": "Monte Mario"}, ...]
+
+# conversione (e=est/lon, n=nord/lat); auto-chunk + cache
+ov.convert([(12.4924, 41.8902)], 4265, 6706)
+# -> [(12.4921961827, 41.8908506304)]
+
+# intelligenza offline (nessuna chiamata di rete)
+ov.inspect(3003)
+ov.targets(3003)
+ov.detect(2300000, 4640000)           # {"kind": "projected", "candidate_epsg": [3004], ...}
+
+# salta le coordinate fuori griglia isolandole per bisezione
+results, skipped = ov.convert_skipping(coords, 3003, 6707)
+
+# errore residuo di una catena di datum
+ov.roundtrip([(1500000, 4640000)], 3003, 6707)
+```
+
+## Autenticazione
+
+Nessuna. Il servizio è libero e gratuito; i campi `utente`/`chiave` richiesti dall'API sono segnaposto, riempiti automaticamente.
+
+## Note tecniche
+
+- Le coordinate geografiche sono **sempre in gradi sessadecimali**.
+- Le conversioni **tra sistemi con lo stesso datum** non sono ammesse dal servizio (vedi `targets`).
+- Il servizio accetta al massimo **32000 coordinate** per richiesta; `batch` esegue automaticamente il chunking.
+- La griglia IGM copre l'Italia e i mari circostanti: coordinate fuori copertura vengono rifiutate (usa `detect`/`inspect` per controllare assi e EPSG).
+
+## Crediti
+
+Servizio dati: [IGM Verto Online](https://igmi.esercito.difesa.it/), Istituto Geografico Militare.
+
+## Licenza
+
+MIT.

openverto-0.1.1/README.md

@@ -0,0 +1,118 @@
+# openverto
+
+> Tool sperimentale — aiutaci a testarlo [aprendo issue](https://github.com/ondata/openverto/issues) o inviando feedback.
+
+CLI e libreria Python per il servizio ufficiale **IGM Verto Online**: trasforma coordinate tra tutti i sistemi di riferimento italiani (Roma40, ED50, IGM95, ETRS89, RDN2008) **senza installare le griglie NTv2**, appoggiandosi al servizio autorevole dell'Istituto Geografico Militare.
+
+Pensato per essere **orchestrato da agenti AI**: output `--json`/`--jsonl`/`--csv`, non interattivo, pipeable, read-only. L'intelligenza sugli EPSG (`inspect`, `detect`, `targets`) è completamente **offline**.
+
+## Installazione
+
+Come strumento CLI (consigliato):
+
+```bash
+uv tool install openverto
+```
+
+Come libreria:
+
+```bash
+uv add openverto    # oppure: pip install openverto
+```
+
+## Avvio rapido (CLI)
+
+```bash
+# i 20 sistemi di riferimento supportati (cache offline dopo la prima volta)
+openverto systems
+
+# converti una coordinata Roma40 -> RDN2008 (lon lat)
+openverto convert --from 4265 --to 6706 12.4924 41.8902
+
+# asse, fuso e false easting prima di una conversione proiettata
+openverto inspect 3003
+
+# converti un CSV di punti Gauss-Boaga (colonne est/nord) in RDN2008/TM32
+openverto batch catasto.csv --from 3003 --to 6707 --e-col est --n-col nord --out out.csv
+
+# riproietta le geometrie di un GeoJSON
+openverto geojson aree.geojson --from 4230 --to 6706 --out out.geojson
+```
+
+## Formati di output
+
+Globale, con `-o/--output`:
+
+```bash
+openverto systems                 # tabella (default in terminale)
+openverto -o json systems         # JSON
+openverto -o jsonl convert ...    # JSON Lines: un oggetto compatto per riga (ideale per coordinate)
+openverto -o csv convert ...      # CSV
+```
+
+`jsonl` è il formato più adatto allo streaming di coordinate verso `jq` o pipeline.
+
+## Comandi
+
+| Comando | Descrizione |
+|---|---|
+| `systems` | Elenco dei sistemi di riferimento supportati (EPSG + descrizione) |
+| `convert` | Converte una o più coordinate (`e n`, o `e,n` da stdin) |
+| `batch` | Converte un CSV in CSV o GeoJSON (auto-chunk a 32000, `--skip-invalid`) |
+| `geojson` | Riproietta le geometrie di un file GeoJSON |
+| `inspect` | Famiglia datum, ordine assi, unità, fuso, false easting di un EPSG |
+| `detect` | Indovina il sistema di origine di una coordinata dalla sua magnitudine |
+| `targets` | Destinazioni di conversione valide per un EPSG (datum diverso) |
+| `roundtrip` | Converte A→B→A e riporta l'errore residuo del datum |
+| `cache` | Ispeziona o svuota la cache offline |
+| `doctor` | Verifica la connettività al servizio |
+
+### Funzioni distintive
+
+- **`roundtrip`** — certifica che una catena di datum sia lossless entro tolleranza prima di pubblicare dati.
+- **`detect`** — recupera l'EPSG reale di un dataset etichettato vagamente ("UTM", "Gauss-Boaga").
+- **`inspect` / `targets`** — disambigua sistemi simili (3003 vs 3004) ed evita destinazioni con lo stesso datum (rifiutate dal servizio).
+- **cache offline** — replay riproducibile delle conversioni in CI o pipeline offline.
+
+## Uso come libreria
+
+```python
+import openverto as ov
+
+# elenco sistemi
+ov.systems()                          # [{"epsg": 4265, "descrizione": "Monte Mario"}, ...]
+
+# conversione (e=est/lon, n=nord/lat); auto-chunk + cache
+ov.convert([(12.4924, 41.8902)], 4265, 6706)
+# -> [(12.4921961827, 41.8908506304)]
+
+# intelligenza offline (nessuna chiamata di rete)
+ov.inspect(3003)
+ov.targets(3003)
+ov.detect(2300000, 4640000)           # {"kind": "projected", "candidate_epsg": [3004], ...}
+
+# salta le coordinate fuori griglia isolandole per bisezione
+results, skipped = ov.convert_skipping(coords, 3003, 6707)
+
+# errore residuo di una catena di datum
+ov.roundtrip([(1500000, 4640000)], 3003, 6707)
+```
+
+## Autenticazione
+
+Nessuna. Il servizio è libero e gratuito; i campi `utente`/`chiave` richiesti dall'API sono segnaposto, riempiti automaticamente.
+
+## Note tecniche
+
+- Le coordinate geografiche sono **sempre in gradi sessadecimali**.
+- Le conversioni **tra sistemi con lo stesso datum** non sono ammesse dal servizio (vedi `targets`).
+- Il servizio accetta al massimo **32000 coordinate** per richiesta; `batch` esegue automaticamente il chunking.
+- La griglia IGM copre l'Italia e i mari circostanti: coordinate fuori copertura vengono rifiutate (usa `detect`/`inspect` per controllare assi e EPSG).
+
+## Crediti
+
+Servizio dati: [IGM Verto Online](https://igmi.esercito.difesa.it/), Istituto Geografico Militare.
+
+## Licenza
+
+MIT.

openverto-0.1.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "openverto"
+version = "0.1.1"
+description = "Python CLI and library for the official IGM Verto Online coordinate transforms between Italian reference systems"
+readme = "README.md"
+authors = [
+    { name = "Andrea Borruso", email = "aborruso@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.12"
+keywords = ["igm", "verto", "coordinate", "epsg", "crs", "italy", "rdn2008", "gauss-boaga", "open-data"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "typer>=0.24.1",
+    "rich>=14.0.0",
+    "platformdirs>=4.0.0",
+]
+
+[project.scripts]
+openverto = "openverto:main"
+
+[project.urls]
+Homepage = "https://github.com/ondata/openverto"
+Issues = "https://github.com/ondata/openverto/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.11", "twine>=5", "build>=1"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Skip the live (network) tests by default; run them with: pytest -m live
+addopts = "-m 'not live'"
+markers = ["live: tests that hit the live IGM Verto Online service"]
+
+[tool.ruff.lint]
+ignore = ["E402"]
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"

openverto-0.1.1/src/openverto/__init__.py

@@ -0,0 +1,55 @@
+"""openverto — Python CLI and library for the IGM Verto Online coordinate service.
+
+Convert coordinates between every Italian reference system (Roma40, ED50,
+IGM95, ETRS89, RDN2008) via the official IGM service, with zero grid-file
+setup. Offline EPSG intelligence (``inspect``, ``targets``, ``detect``) needs
+no network.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("openverto")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+from .base import (
+    MAX_COORD,
+    VertoError,
+    get_extra_headers,
+    set_base_url,
+    set_extra_headers,
+    set_timeout,
+)
+from .transform import convert, convert_skipping, inspect, roundtrip, targets
+from .detect import detect
+from .geo import reproject_geojson
+from .systems import info, system_by_epsg, systems
+
+__all__ = [
+    "systems",
+    "system_by_epsg",
+    "info",
+    "convert",
+    "convert_skipping",
+    "inspect",
+    "targets",
+    "roundtrip",
+    "detect",
+    "reproject_geojson",
+    "set_timeout",
+    "set_base_url",
+    "set_extra_headers",
+    "get_extra_headers",
+    "VertoError",
+    "MAX_COORD",
+    "__version__",
+    "main",
+]
+
+
+def main() -> None:
+    """CLI entrypoint (lazy import so the library has no CLI-only deps cost)."""
+    from .cli import app
+
+    app()

openverto-0.1.1/src/openverto/base.py

@@ -0,0 +1,124 @@
+"""HTTP layer for the IGM Verto Online service.
+
+The service is a single POST endpoint discriminated by the body field
+``richiesta``: ``"info"`` lists the supported reference systems, ``"conversione"``
+transforms an array of ``{e, n}`` coordinates between two EPSG codes. The
+``utente``/``chiave`` fields are mandatory but ignored by the service (they are
+NOT authentication); we send fixed placeholders.
+
+Service-level errors are returned inside an HTTP 200 body as
+``{"stato": "errore", "dove": ..., "messaggio": ...}`` and surface as
+:class:`VertoError`.
+"""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+
+#: Default endpoint (relative path ``/volapi`` is already included).
+DEFAULT_BASE_URL = "https://igmi.esercito.difesa.it/porta-magna/wps/volapi"
+
+#: Maximum number of coordinates accepted per ``conversione`` request.
+MAX_COORD = 32000
+
+_USER_AGENT = "openverto"
+
+# Module-level configuration (mutable via the setters below).
+_base_url = DEFAULT_BASE_URL
+_timeout = 30.0
+_extra_headers: dict[str, str] = {}
+
+
+def set_base_url(url: str) -> None:
+    """Override the service endpoint (useful for tests or a mirror)."""
+    global _base_url
+    _base_url = url
+
+
+def get_base_url() -> str:
+    return _base_url
+
+
+def set_timeout(seconds: float) -> None:
+    """Set the per-request timeout in seconds."""
+    global _timeout
+    _timeout = float(seconds)
+
+
+def get_timeout() -> float:
+    return _timeout
+
+
+def set_extra_headers(headers: dict[str, str]) -> None:
+    """Replace the static extra HTTP headers sent with every request."""
+    global _extra_headers
+    _extra_headers = dict(headers)
+
+
+def get_extra_headers() -> dict[str, str]:
+    return dict(_extra_headers)
+
+
+class VertoError(Exception):
+    """A service-level error reported by Verto Online (``stato: errore``).
+
+    The most common case is an out-of-grid coordinate, signalled by
+    ``dove == "Proj"`` (the underlying PROJ transform rejecting a coordinate
+    outside the IGM grid coverage).
+    """
+
+    def __init__(self, messaggio: str, dove: str = ""):
+        self.messaggio = messaggio
+        self.dove = dove
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        if self.dove:
+            return f"verto service error ({self.dove}): {self.messaggio}"
+        return f"verto service error: {self.messaggio}"
+
+    @property
+    def outside_grid(self) -> bool:
+        """Whether this is the 'coordinate outside the IGM grid coverage' case."""
+        if self.dove.strip().lower() == "proj":
+            return True
+        m = (self.messaggio or "").lower()
+        return "outside grid" in m or "griglia" in m
+
+
+def post(body: dict, *, retries: int = 2) -> dict:
+    """POST a request body to the Verto endpoint and return the parsed JSON.
+
+    Retries transient network/5xx errors with a short backoff. Raises
+    :class:`httpx.HTTPError` on a non-recoverable transport error and
+    :class:`ValueError` on an unparseable body. Service-level ``stato: errore``
+    bodies are returned as-is for the caller to interpret.
+    """
+    headers = {"Content-Type": "application/json", "User-Agent": _USER_AGENT}
+    headers.update(_extra_headers)
+    last_exc: Exception | None = None
+    for attempt in range(retries + 1):
+        try:
+            with httpx.Client(timeout=_timeout) as client:
+                resp = client.post(_base_url, json=body, headers=headers)
+            if resp.status_code >= 500 and attempt < retries:
+                last_exc = httpx.HTTPStatusError(
+                    f"server error {resp.status_code}", request=resp.request, response=resp
+                )
+                time.sleep(0.5 * (attempt + 1))
+                continue
+            resp.raise_for_status()
+            try:
+                return resp.json()
+            except ValueError as exc:
+                raise ValueError(f"invalid JSON from Verto service: {exc}") from exc
+        except (httpx.TransportError, httpx.HTTPStatusError) as exc:
+            last_exc = exc
+            if attempt < retries:
+                time.sleep(0.5 * (attempt + 1))
+                continue
+            raise
+    # Unreachable, but keeps type-checkers happy.
+    raise last_exc if last_exc else RuntimeError("post failed")

openverto-0.1.1/src/openverto/cache.py

@@ -0,0 +1,126 @@
+"""Offline write-through cache for systems and conversion results.
+
+Cached results let pipelines replay the same conversions offline and keep CI
+runs reproducible without hitting the live service. Files live under the user
+cache directory (``platformdirs``); set ``OPENVERTO_CACHE_DIR`` to override.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from platformdirs import user_cache_dir
+
+# Conversion cache keys round e/n to this many decimals so float jitter on the
+# input does not prevent a hit. 6 decimals is ~0.1 mm at the equator — finer
+# than the service's own precision.
+_KEY_DECIMALS = 6
+
+
+def cache_dir() -> Path:
+    """Return the cache directory, honouring ``OPENVERTO_CACHE_DIR``."""
+    override = os.environ.get("OPENVERTO_CACHE_DIR")
+    d = Path(override) if override else Path(user_cache_dir("openverto"))
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _systems_file() -> Path:
+    return cache_dir() / "systems.json"
+
+
+def _conv_file() -> Path:
+    return cache_dir() / "conversions.json"
+
+
+def load_systems() -> list[dict]:
+    """Return the cached systems list, or ``[]`` on miss/corruption."""
+    f = _systems_file()
+    try:
+        return json.loads(f.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return []
+
+
+def save_systems(systems: list[dict]) -> None:
+    try:
+        _systems_file().write_text(
+            json.dumps(systems, ensure_ascii=False), encoding="utf-8"
+        )
+    except OSError:
+        pass
+
+
+def _conv_key(in_epsg: int, out_epsg: int, e: float, n: float) -> str:
+    return f"{in_epsg}:{out_epsg}:{round(e, _KEY_DECIMALS)}:{round(n, _KEY_DECIMALS)}"
+
+
+class ConvCache:
+    """A write-through cache of conversion results, persisted as JSON."""
+
+    def __init__(self, data: dict[str, list[float]] | None = None):
+        self._data: dict[str, list[float]] = data or {}
+        self._dirty = False
+
+    @classmethod
+    def load(cls) -> "ConvCache":
+        try:
+            raw = json.loads(_conv_file().read_text(encoding="utf-8"))
+            if isinstance(raw, dict):
+                return cls(raw)
+        except (OSError, ValueError):
+            pass
+        return cls()
+
+    def get(self, in_epsg: int, out_epsg: int, e: float, n: float) -> tuple[float, float] | None:
+        v = self._data.get(_conv_key(in_epsg, out_epsg, e, n))
+        if v and len(v) == 2:
+            return (v[0], v[1])
+        return None
+
+    def put(self, in_epsg: int, out_epsg: int, e: float, n: float, result: tuple[float, float]) -> None:
+        self._data[_conv_key(in_epsg, out_epsg, e, n)] = [result[0], result[1]]
+        self._dirty = True
+
+    def save(self) -> None:
+        if not self._dirty:
+            return
+        try:
+            _conv_file().write_text(
+                json.dumps(self._data, ensure_ascii=False), encoding="utf-8"
+            )
+            self._dirty = False
+        except OSError:
+            pass
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+
+def stats() -> dict:
+    """Return cache statistics for the ``cache --stats`` command."""
+    conv = _conv_file()
+    syst = _systems_file()
+    return {
+        "cache_dir": str(cache_dir()),
+        "systems_cached": len(load_systems()),
+        "conversions_cached": len(ConvCache.load()),
+        "conversions_file": str(conv) if conv.exists() else None,
+        "size_bytes": (conv.stat().st_size if conv.exists() else 0)
+        + (syst.stat().st_size if syst.exists() else 0),
+    }
+
+
+def clear() -> list[str]:
+    """Delete cache files. Returns the paths removed."""
+    removed = []
+    for f in (_conv_file(), _systems_file()):
+        if f.exists():
+            try:
+                f.unlink()
+                removed.append(str(f))
+            except OSError:
+                pass
+    return removed