gispulse 2.2.0__tar.gz → 2.2.2__tar.gz

{gispulse-2.2.0/src/gispulse.egg-info → gispulse-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gispulse
-Version: 2.2.0
+Version: 2.2.2
 Summary: Modular geospatial engine with business rules, triggers, and dual operating modes (DuckDB/PostGIS)
 Author-email: ImagoData <contact@imagodata.com>
 License-Expression: AGPL-3.0-or-later

{gispulse-2.2.0 → gispulse-2.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gispulse"
-version = "2.2.0"
+version = "2.2.2"
 description = "Modular geospatial engine with business rules, triggers, and dual operating modes (DuckDB/PostGIS)"
 license = "AGPL-3.0-or-later"
 requires-python = ">=3.10"

gispulse-2.2.2/src/gispulse/capabilities/vector/snap_points.py

@@ -0,0 +1,259 @@
+"""Snap points to a line network with stable edge ids (capability B).
+
+Where ``line_locate_point`` returns only a measure plus a *positional*
+``ref_index``, this capability returns everything needed to attach an event
+to a routable edge:
+
+* ``edge_id``         — the matched line's id (from ``ref_id_col``), stable
+  across runs (not a row position);
+* ``measure``         — distance along the matched line, in meters, from its
+  start (in ``[0, line_length]``); null when unsnapped;
+* ``offset_distance`` — perpendicular distance from the point to its nearest
+  line (always reported, snapped or not);
+* ``snapped``         — ``True`` when ``offset_distance <= max_distance_m``
+  (or ``max_distance_m is None``), ``False`` otherwise;
+* ``geometry``        — for snapped rows, the **projected** point on the
+  nearest line; for unsnapped rows the original point is kept.
+
+A point beyond ``max_distance_m`` is reported with ``snapped=False``,
+``edge_id``/``measure`` null and its original geometry — only
+``offset_distance`` records how far its nearest line lies, so the consumer
+can decide what to do. A null/empty input geometry has no nearest line and
+stays ``edge_id=None``, ``snapped=False`` with its geometry untouched.
+
+Candidate lines are found through a :class:`~gispulse.core.spatial_index.SpatialIndex`
+(STRtree, no O(n·m) scan); each point projects directly onto its segment.
+Ties — several lines exactly equidistant from one point — break
+deterministically on the smallest ``edge_id`` so the same inputs always
+produce the same outputs.
+
+All metric quantities (``measure``, ``offset_distance``, ``max_distance_m``)
+are computed in ``crs_meters`` (a projected CRS); inputs in another CRS are
+reprojected in and the result is reprojected back to the points' original
+CRS. ``crs_meters`` must be a metric/projected CRS — never feed it degrees.
+
+This capability is deliberately **generic**: it carries no business notion
+(site, fibre edge, river reach…). Accidents on a road network, meters on a
+utility line and discharges on a watercourse are all the same operation —
+project points onto identified lines — and none is special-cased here.
+"""
+
+from __future__ import annotations
+
+import geopandas as gpd
+import numpy as np
+
+from gispulse.capabilities.base import Capability
+from gispulse.capabilities.registry import register
+from gispulse.core.spatial_index import SpatialIndex
+
+# How many nearest lines to inspect per point when breaking ties. Genuine
+# geometric ties (several lines exactly equidistant from one point) are rare;
+# 8 candidates is ample headroom while keeping each lookup O(k·log n) — far
+# cheaper (and bounded) than a radius query whose buffer could match the whole
+# network for a far-off point.
+_TIE_CANDIDATES = 8
+# Distances within this many CRS units (meters) are treated as equal for the
+# purpose of tie-breaking on edge_id.
+_TIE_TOL_M = 1e-9
+
+
+def _id_sort_key(value: object) -> "tuple[int, object]":
+    """Deterministic, total ordering key for tie-breaking on edge ids.
+
+    Real ids in a single ``ref_id_col`` are homogeneous (all ints or all
+    strings), where this reduces to natural order. The two-level key only
+    guards the pathological mixed-type column so ``min`` never raises and the
+    outcome stays reproducible.
+    """
+    if isinstance(value, bool):  # bool is an int subclass — keep it on the str side
+        return (1, str(value))
+    if isinstance(value, (int, float)):
+        return (0, value)
+    return (1, str(value))
+
+
+@register
+class SnapPointsToLinesCapability(Capability):
+    """Projects points onto a line network, tagging each with its edge id."""
+
+    name = "snap_points_to_lines"
+    description = (
+        "Snaps each point to the nearest line, adding edge_id (from "
+        "ref_id_col), measure, offset_distance and a snapped flag; geometry "
+        "becomes the projected point on the nearest line."
+    )
+
+    def execute(
+        self,
+        gdf: gpd.GeoDataFrame,
+        ref_gdf: gpd.GeoDataFrame | None = None,
+        ref_id_col: str | None = None,
+        max_distance_m: float | None = None,
+        crs_meters: str = "EPSG:3857",
+        edge_id_col: str = "edge_id",
+        measure_col: str = "measure",
+        offset_col: str = "offset_distance",
+        snapped_col: str = "snapped",
+        **_,
+    ) -> gpd.GeoDataFrame:
+        """Project each point onto its nearest reference line.
+
+        Args:
+            gdf:            Input points (non-points use their centroid). All
+                            input columns are preserved on the output.
+            ref_gdf:        Reference line layer (injected via ``ref_layer``).
+            ref_id_col:     Column on ``ref_gdf`` providing the stable
+                            ``edge_id``. **Required** — its absence raises a
+                            clear ``ValueError`` rather than silently falling
+                            back to a positional index.
+            max_distance_m: Snap threshold in meters. A point whose nearest
+                            line is farther than this is left unsnapped:
+                            ``snapped=False``, ``edge_id``/``measure`` null
+                            and the original geometry kept, with only
+                            ``offset_distance`` reporting the true nearest
+                            distance. ``None`` snaps every point to its
+                            nearest line.
+            crs_meters:     Metric (projected) CRS used for all distances.
+            edge_id_col:    Output column for the matched edge id.
+            measure_col:    Output column for the along-line measure (m).
+            offset_col:     Output column for the perpendicular offset (m).
+            snapped_col:    Output boolean column.
+
+        Returns:
+            Copy of ``gdf`` (input columns intact) with the four columns added
+            and ``geometry`` replaced by the projected point, in the input CRS.
+
+        Raises:
+            ValueError: if ``ref_gdf`` is missing/empty, or if ``ref_id_col``
+                is not a column of ``ref_gdf``.
+        """
+        if ref_gdf is None or ref_gdf.empty:
+            raise ValueError(
+                "snap_points_to_lines requires a non-empty reference line layer "
+                "(ref_gdf). Pass the lines to project the points onto."
+            )
+        if ref_id_col is None or ref_id_col not in ref_gdf.columns:
+            raise ValueError(
+                "snap_points_to_lines: ref_id_col="
+                f"{ref_id_col!r} is not a column of ref_gdf "
+                f"(available columns: {list(ref_gdf.columns)}). "
+                "Pass ref_id_col=<the stable id column on your lines> so every "
+                "snapped point can carry a durable edge_id."
+            )
+
+        original_crs = gdf.crs
+        left = gdf.to_crs(crs_meters) if original_crs is not None else gdf.copy()
+        right = (
+            ref_gdf.to_crs(crs_meters)
+            if ref_gdf.crs is not None and str(ref_gdf.crs) != str(crs_meters)
+            else ref_gdf.copy()
+        )
+        right = right.reset_index(drop=True)
+
+        line_geoms = list(right.geometry)
+        ref_ids = list(right[ref_id_col])
+        index = SpatialIndex(line_geoms)
+
+        n = len(left)
+        edge_ids: list[object] = [None] * n
+        measures = np.full(n, np.nan, dtype=float)
+        offsets = np.full(n, np.nan, dtype=float)
+        snapped = np.zeros(n, dtype=bool)
+        new_geoms = list(left.geometry)
+
+        for row_i, geom in enumerate(left.geometry):
+            if geom is None or geom.is_empty:
+                continue
+            pt = geom if geom.geom_type == "Point" else geom.centroid
+
+            pos = self._nearest_line(index, line_geoms, ref_ids, pt)
+            if pos is None:  # ref layer had no usable geometry
+                continue
+            line = line_geoms[pos]
+            offset = line.distance(pt)
+            offsets[row_i] = float(offset)  # nearest distance is always reported
+            if max_distance_m is not None and offset > max_distance_m:
+                # Beyond the threshold: leave edge_id/measure null and the
+                # original geometry in place (snapped stays False).
+                continue
+            measure = line.project(pt)
+            measures[row_i] = float(measure)
+            edge_ids[row_i] = ref_ids[pos]
+            new_geoms[row_i] = line.interpolate(measure)
+            snapped[row_i] = True
+
+        out = left.copy()
+        out[edge_id_col] = edge_ids
+        out[measure_col] = measures
+        out[offset_col] = offsets
+        out[snapped_col] = snapped
+        out = out.set_geometry(
+            gpd.GeoSeries(new_geoms, index=out.index, crs=crs_meters)
+        )
+        if original_crs is not None:
+            out = out.to_crs(original_crs)
+        return out.reset_index(drop=True)
+
+    @staticmethod
+    def _nearest_line(
+        index: SpatialIndex,
+        line_geoms: list,
+        ref_ids: list,
+        pt,
+    ) -> "int | None":
+        """Position of the nearest line to ``pt``, ties broken by smallest id.
+
+        Inspects the ``_TIE_CANDIDATES`` nearest lines (O(k·log n)), keeps
+        those within ``_TIE_TOL_M`` of the minimum distance, and returns the
+        one with the smallest ``edge_id`` — a stable, deterministic choice.
+        """
+        near = index.nearest(pt, k=min(_TIE_CANDIDATES, len(line_geoms)))
+        if not near:
+            return None
+        dists = {pos: line_geoms[pos].distance(pt) for pos in near}
+        best_dist = min(dists.values())
+        tied = [pos for pos, d in dists.items() if d <= best_dist + _TIE_TOL_M]
+        return min(tied, key=lambda pos: _id_sort_key(ref_ids[pos]))
+
+    def get_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "ref_layer": {
+                    "type": "string",
+                    "description": "Reference line layer to snap onto.",
+                },
+                "ref_id_col": {
+                    "type": "string",
+                    "description": (
+                        "Required. Column on the lines providing the stable "
+                        "edge_id; its absence raises a ValueError."
+                    ),
+                },
+                "max_distance_m": {
+                    "type": ["number", "null"],
+                    "description": (
+                        "Snap threshold (m). Beyond it, snapped=False with "
+                        "edge_id/measure null and the original geometry kept "
+                        "(only offset_distance reported). None snaps every "
+                        "point to its nearest line."
+                    ),
+                },
+                "crs_meters": {"type": "string", "default": "EPSG:3857"},
+                "edge_id_col": {"type": "string", "default": "edge_id"},
+                "measure_col": {"type": "string", "default": "measure"},
+                "offset_col": {"type": "string", "default": "offset_distance"},
+                "snapped_col": {"type": "string", "default": "snapped"},
+            },
+            # ``ref_id_col`` is genuinely required and is not plumbing, so it
+            # can validate early. ``ref_layer`` must NOT appear in ``required``:
+            # it is pipeline plumbing (resolved to ``ref_gdf`` and stripped
+            # before schema validation), so requiring it would fail every v2
+            # call before the capability runs. The runtime still raises a clear
+            # ValueError when ``ref_gdf`` itself is missing.
+            "required": ["ref_id_col"],
+        }
+
+
+__all__ = ["SnapPointsToLinesCapability"]

{gispulse-2.2.0 → gispulse-2.2.2}/src/gispulse/persistence/datamart.py

@@ -19,8 +19,14 @@ from the ``GISPULSE_DATAMARTS`` environment variable (a JSON object), e.g.::
 
     GISPULSE_DATAMARTS='{
       "referentiel": {"location": "s3://bucket/marts/referentiel"},
-      "local": {"location": "/data/marts/local", "table_pattern": "{table}.parquet"}
+      "local": {"location": "/data/marts/local", "table_pattern": "{table}.parquet"},
+      "warehouse": {"location": "/data/marts/warehouse.duckdb", "kind": "duckdb"}
     }'
+
+A ``kind: "duckdb"`` mart points :attr:`Datamart.location` at a single
+DuckDB database file; ``datamart://warehouse/<table>`` then reads the table
+of that name from inside the file (attached read-only, bbox push-down still
+applies via an ``ST_Intersects`` predicate on a ``geom`` column).
 """
 
 from __future__ import annotations
@@ -42,17 +48,33 @@ DATAMARTS_ENV = "GISPULSE_DATAMARTS"
 DATAMART_SCHEME = "datamart"
 
 
+#: Supported datamart backends.
+DATAMART_KINDS = ("parquet", "duckdb")
+
+
 @dataclass(frozen=True)
 class Datamart:
     """Declaration of one curated table store.
 
+    Two backends are supported, selected by :attr:`kind`:
+
+    * ``"parquet"`` (default) — *location* is a directory / ``s3://`` /
+      ``https://`` prefix holding **one file per table**; the file is
+      addressed by joining *location* with *table_pattern* and read as an
+      ordinary source (DuckDB-scannable, bbox push-down applies).
+    * ``"duckdb"`` — *location* is the path to a **single DuckDB database
+      file** (``.duckdb``); a table is a relation *inside* that file, read by
+      attaching the database read-only and selecting the table.
+
     Args:
         name:          Logical mart name used in ``datamart://<name>/…``.
-        location:      Base location of the tables — a directory path or
-                       an ``s3://`` / ``https://`` prefix. Joined with
-                       ``table_pattern`` to address a single table.
-        table_pattern: Filename pattern for a table, ``{table}`` being the
-                       table name. Defaults to ``"{table}.parquet"``.
+        location:      Base location: a directory / ``s3://`` / ``https://``
+                       prefix (``parquet``), or the path to a ``.duckdb``
+                       file (``duckdb``).
+        table_pattern: Filename pattern for a ``parquet`` table, ``{table}``
+                       being the table name. Defaults to ``"{table}.parquet"``.
+                       Ignored for ``duckdb`` marts.
+        kind:          Backend, ``"parquet"`` (default) or ``"duckdb"``.
         crs:           Optional CRS to force on tables that declare none.
         metadata:      Free-form descriptive metadata.
     """
@@ -60,13 +82,31 @@ class Datamart:
     name: str
     location: str
     table_pattern: str = "{table}.parquet"
+    kind: str = "parquet"
     crs: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
 
+    def __post_init__(self) -> None:
+        if self.kind not in DATAMART_KINDS:
+            raise ValueError(
+                f"datamart '{self.name}': unknown kind {self.kind!r} "
+                f"(expected one of {DATAMART_KINDS})"
+            )
+
     def uri_for(self, table: str) -> str:
-        """Return the concrete source URI for *table* in this mart."""
+        """Return the concrete source URI for *table* (``parquet`` marts).
+
+        Raises:
+            ValueError: for a ``duckdb`` mart — a table there is not a file
+                URI; resolve it via the loader's DuckDB-table path instead.
+        """
         if not table:
             raise ValueError(f"datamart '{self.name}': empty table name")
+        if self.kind != "parquet":
+            raise ValueError(
+                f"datamart '{self.name}': uri_for is only valid for parquet "
+                f"marts, not kind={self.kind!r}"
+            )
         filename = self.table_pattern.format(table=table)
         base = self.location.rstrip("/")
         return f"{base}/{filename}"
@@ -141,13 +181,19 @@ class DatamartRegistry:
                 if not isinstance(spec, dict) or "location" not in spec:
                     log.warning("datamart_env_bad_decl", name=name)
                     continue
-                self._marts[name] = Datamart(
-                    name=name,
-                    location=str(spec["location"]),
-                    table_pattern=str(spec.get("table_pattern", "{table}.parquet")),
-                    crs=spec.get("crs"),
-                    metadata=dict(spec.get("metadata") or {}),
-                )
+                try:
+                    self._marts[name] = Datamart(
+                        name=name,
+                        location=str(spec["location"]),
+                        table_pattern=str(
+                            spec.get("table_pattern", "{table}.parquet")
+                        ),
+                        kind=str(spec.get("kind", "parquet")),
+                        crs=spec.get("crs"),
+                        metadata=dict(spec.get("metadata") or {}),
+                    )
+                except ValueError as exc:
+                    log.warning("datamart_env_bad_decl", name=name, error=str(exc))
 
 
 def parse_datamart_uri(uri: str) -> tuple[str, str]:
@@ -177,6 +223,7 @@ DATAMARTS = DatamartRegistry()
 __all__ = [
     "DATAMARTS",
     "DATAMARTS_ENV",
+    "DATAMART_KINDS",
     "DATAMART_SCHEME",
     "Datamart",
     "DatamartRegistry",

{gispulse-2.2.0 → gispulse-2.2.2}/src/gispulse/persistence/loader.py

@@ -119,12 +119,30 @@ class LazyDataset:
         return _scan_to_gdf(self.scan_sql, crs=self.crs, bbox=bbox)
 
 
+@dataclass(frozen=True)
+class _DuckDBTableRef:
+    """Reference to a table living inside a single DuckDB database file.
+
+    Produced by :func:`resolve_source` for a ``duckdb``-kind datamart
+    (``datamart://<mart>/<table>`` where the mart's location is a
+    ``.duckdb`` file). Unlike a Parquet table it is not a file URI the
+    loader can hand to ``read_vector`` / a remote-table scan, so the loader
+    reads it via :func:`_duckdb_table_to_gdf` (attach read-only, select).
+    """
+
+    db_path: str
+    table: str
+    crs: str | None = None
+
+
 # ---------------------------------------------------------------------------
 # Source resolution
 # ---------------------------------------------------------------------------
 
 
-def resolve_source(source: "str | Path | AccessSpec | dict[str, Any]") -> "Path | AccessSpec":
+def resolve_source(
+    source: "str | Path | AccessSpec | dict[str, Any]",
+) -> "Path | AccessSpec | _DuckDBTableRef":
     """Resolve a user-supplied source into a local path or an access spec.
 
     Accepted forms:
@@ -162,12 +180,19 @@ def resolve_source(source: "str | Path | AccessSpec | dict[str, Any]") -> "Path
     scheme = head.lower()
 
     # Datamart indirection: resolve datamart://<mart>/<table> to its
-    # concrete source URI, then resolve that recursively.
+    # concrete source. A "parquet" mart yields a file URI resolved
+    # recursively; a "duckdb" mart yields a table reference inside a
+    # database file, read via _duckdb_table_to_gdf.
     if scheme == DATAMART_SCHEME:
         from gispulse.persistence.datamart import DATAMARTS, parse_datamart_uri
 
-        mart, table = parse_datamart_uri(raw)
-        return resolve_source(DATAMARTS.resolve(mart, table))
+        mart_name, table = parse_datamart_uri(raw)
+        mart = DATAMARTS.get(mart_name)
+        if mart.kind == "duckdb":
+            if not table:
+                raise ValueError(f"datamart '{mart_name}': empty table name")
+            return _DuckDBTableRef(db_path=mart.location, table=table, crs=mart.crs)
+        return resolve_source(mart.uri_for(table))
 
     # GeoNode: geonode://<instance>/<dataset> reads via the instance's
     # GeoServer WFS endpoint (reuses the OGC fetcher).
@@ -330,6 +355,52 @@ def _scan_to_gdf(
     return gdf
 
 
+def _duckdb_table_to_gdf(
+    db_path: str, table: str, *, crs: str | None, bbox: BBox | None
+) -> gpd.GeoDataFrame:
+    """Read a table from a DuckDB database file into a GeoDataFrame.
+
+    Attaches *db_path* **read-only** (so concurrent readers don't contend on
+    a write lock) onto an ephemeral in-memory session, then selects *table*.
+    When *bbox* is given an ``ST_Intersects`` envelope predicate is pushed
+    into the query against a ``geom`` column (matching the convention of
+    :func:`_scan_to_gdf`).
+    """
+    from gispulse.persistence.duckdb_engine import DuckDBSession
+
+    # ATTACH cannot be wrapped in the SELECT sub-query DuckDBSession.sql
+    # builds, so run it separately on the connection, then SELECT the table
+    # — that SELECT *is* wrappable, so geometry/CRS decoding still works.
+    db_lit = db_path.replace("'", "''")
+    rel = f"_mart.{_quote_ident(table)}"
+    query = f"SELECT * FROM {rel}"
+    if bbox is not None:
+        minx, miny, maxx, maxy = bbox
+        query = (
+            f"SELECT * FROM {rel} "
+            f"WHERE ST_Intersects(geom, ST_MakeEnvelope("
+            f"{minx}, {miny}, {maxx}, {maxy}))"
+        )
+
+    session = DuckDBSession()
+    session.open()
+    try:
+        session.conn.execute(f"ATTACH '{db_lit}' AS _mart (READ_ONLY)")
+        gdf = session.sql(query)
+    finally:
+        session.close()
+
+    if crs and gdf.crs is None:
+        gdf = gdf.set_crs(crs)
+    return gdf
+
+
+def _quote_ident(identifier: str) -> str:
+    """Quote a SQL identifier (double-quote, doubling embedded quotes)."""
+    escaped = identifier.replace('"', '""')
+    return f'"{escaped}"'
+
+
 # ---------------------------------------------------------------------------
 # Public entry point
 # ---------------------------------------------------------------------------
@@ -380,6 +451,15 @@ def load(
 
     resolved = resolve_source(source)
 
+    # --- DuckDB-file datamart table ---------------------------------------
+    if isinstance(resolved, _DuckDBTableRef):
+        if lazy:
+            log.debug("loader_lazy_ignored_for_duckdb_table", table=resolved.table)
+        gdf = _duckdb_table_to_gdf(
+            resolved.db_path, resolved.table, crs=crs or resolved.crs, bbox=bbox
+        )
+        return gdf
+
     # --- Local file path ---------------------------------------------------
     if isinstance(resolved, Path):
         if lazy:

{gispulse-2.2.0 → gispulse-2.2.2/src/gispulse.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gispulse
-Version: 2.2.0
+Version: 2.2.2
 Summary: Modular geospatial engine with business rules, triggers, and dual operating modes (DuckDB/PostGIS)
 Author-email: ImagoData <contact@imagodata.com>
 License-Expression: AGPL-3.0-or-later