gispulse 1.2.0__py3-none-any.whl

capabilities/__init__.py

@@ -0,0 +1,380 @@
+"""GISPulse capabilities — spatial operations registry."""
+
+# Auto-import capability modules so they register themselves.
+# vector et postgis_sql n'ont aucune dépendance optionnelle.
+import capabilities.vector  # noqa: F401
+import capabilities.postgis_sql  # noqa: F401
+
+# validation : dépend uniquement de geopandas/shapely (déjà obligatoires)
+import capabilities.validation  # noqa: F401
+
+# Network & polygon topology repair — pure shapely, no optional deps.
+import capabilities.network_topology  # noqa: F401
+import capabilities.polygon_topology  # noqa: F401
+
+# Spatial statistics + density — require numpy/scipy/sklearn (always installed).
+import capabilities.spatial_stats  # noqa: F401
+import capabilities.density  # noqa: F401
+
+# Classification / choropleth — pure numpy core; mapclassify optional.
+import capabilities.classification  # noqa: F401
+
+# Schema / attribute manipulation — pure pandas, no optional deps.
+import capabilities.schema  # noqa: F401
+
+# Selection / row-level ops — pure pandas, no optional deps.
+import capabilities.selection  # noqa: F401
+
+# Overlay (intersection / union / erase) — pure geopandas.
+import capabilities.overlay  # noqa: F401
+
+# Geometry transforms — pure shapely.
+import capabilities.transforms  # noqa: F401
+
+# Temporal — pure pandas.
+import capabilities.temporal  # noqa: F401
+
+# Pointcloud — three pure-pandas capabilities + one optional laspy loader.
+# The module imports laspy lazily inside execute(), so this top-level import is
+# always safe; pointcloud_load_las raises RuntimeError if laspy is missing.
+import capabilities.pointcloud  # noqa: F401
+
+from capabilities.base import Capability
+from capabilities.registry import REGISTRY, get, list_all, register
+from capabilities.postgis_sql import PostGISSQLCapability
+from capabilities.classification import (
+    BivariateChoroplethCapability,
+    ChoroplethCapability,
+    ClassifyCapability,
+    ClassifyCategoricalCapability,
+    ContinuousRampCapability,
+    GraduatedSizeCapability,
+    HeadTailBreaksCapability,
+    NormalizeCapability,
+    build_graduated_style_def,
+    build_legend,
+)
+from capabilities.vector import (
+    AlphaShapeCapability,
+    AreaLengthCapability,
+    AssignProjectionCapability,
+    BoundaryCapability,
+    BufferCapability,
+    CalculateCapability,
+    CentroidCapability,
+    ChaikinSmoothCapability,
+    ClassifyByRingCapability,
+    ClipCapability,
+    ConcaveHullCapability,
+    ConvexHullCapability,
+    DelaunayTriangulationCapability,
+    DensifyVerticesCapability,
+    DissolveCapability,
+    EnvelopeCapability,
+    ExtractHolesCapability,
+    ExtractSegmentsCapability,
+    ExtractVerticesCapability,
+    FilterCapability,
+    ForceGeometryTypeCapability,
+    IntersectsCapability,
+    LineLocatePointCapability,
+    LineMergeCapability,
+    LineSubstringCapability,
+    MakeValidCapability,
+    MergeLayersCapability,
+    MinBoundingCircleCapability,
+    MultipartToSinglepartsCapability,
+    NearestNeighborCapability,
+    OffsetCurveCapability,
+    OrientedBBoxCapability,
+    PolygonizeCapability,
+    ReprojectCapability,
+    SimplifyCapability,
+    SinglepartsToMultipartCapability,
+    SnapToGridCapability,
+    SpatialAggregateCapability,
+    SpatialJoinCapability,
+    SymmetricDifferenceCapability,
+    UnionCapability,
+    VectorDiffCapability,
+    VoronoiPolygonsCapability,
+)
+from capabilities.schema import (
+    AddFieldCapability,
+    AttributeJoinCapability,
+    CaseWhenCapability,
+    CastFieldCapability,
+    CoalesceFieldsCapability,
+    DropFieldCapability,
+    LookupTableCapability,
+    PivotCapability,
+    RenameFieldCapability,
+    SelectColumnsCapability,
+    UnpivotCapability,
+)
+from capabilities.selection import (
+    DeduplicateCapability,
+    RandomSampleCapability,
+    SortCapability,
+    TopNCapability,
+)
+from capabilities.overlay import (
+    EraseCapability,
+    OverlayIntersectionCapability,
+    OverlayUnionCapability,
+)
+from capabilities.transforms import (
+    AddMCapability,
+    AddZCapability,
+    AffineTransformCapability,
+    DropMCapability,
+    DropZCapability,
+    ReverseLinesCapability,
+    SwapXYCapability,
+)
+from capabilities.temporal import (
+    TemporalFilterCapability,
+    TemporalJoinCapability,
+)
+from capabilities.pointcloud import (
+    PointcloudFilterClassificationCapability,
+    PointcloudGridSummaryCapability,
+    PointcloudLoadLasCapability,
+    PointcloudZonalHeightCapability,
+)
+from capabilities.spatial_stats import (
+    GetisOrdGStarCapability,
+    MoransICapability,
+    SpatialWeightsCapability,
+)
+from capabilities.density import (
+    GridCreateCapability,
+    HexGridCreateCapability,
+    KDEHeatmapCapability,
+)
+from capabilities.network_topology import (
+    ExtendDanglesCapability,
+    NodeLinesCapability,
+    RemoveDuplicateEdgesCapability,
+    RemovePseudoNodesCapability,
+    SnapEndpointsCapability,
+)
+from capabilities.polygon_topology import (
+    FixGapsCapability,
+    FixOverlapsCapability,
+    RemoveSliversCapability,
+    SnapBordersCapability,
+)
+
+# Clustering depends on scikit-learn (optional).
+try:
+    import capabilities.clustering  # noqa: F401
+    from capabilities.clustering import (
+        DBSCANClusterCapability,
+        HDBSCANClusterCapability,
+        KMeansClusterCapability,
+    )
+
+    _CLUSTERING_AVAILABLE = True
+except ImportError:
+    _CLUSTERING_AVAILABLE = False
+    DBSCANClusterCapability = None  # type: ignore[assignment, misc]
+    HDBSCANClusterCapability = None  # type: ignore[assignment, misc]
+    KMeansClusterCapability = None  # type: ignore[assignment, misc]
+from capabilities.validation import (
+    AttributeValidationCapability,
+    CompletenessCheckCapability,
+    DuplicateGeometryCapability,
+    TopologyCheckCapability,
+)
+
+# raster : dépend de rasterio / rasterstats (optionnels)
+try:
+    import capabilities.raster  # noqa: F401
+    from capabilities.raster import (
+        ChangeDetectionCapability,
+        NdviCapability,
+        RasterClipCapability,
+        RasterMergeCapability,
+        RasterReprojectCapability,
+        ZonalStatsCapability,
+    )
+
+    _RASTER_AVAILABLE = True
+except ImportError:
+    _RASTER_AVAILABLE = False
+    ChangeDetectionCapability = None  # type: ignore[assignment, misc]
+    ZonalStatsCapability = None  # type: ignore[assignment, misc]
+    RasterClipCapability = None  # type: ignore[assignment, misc]
+    NdviCapability = None  # type: ignore[assignment, misc]
+    RasterReprojectCapability = None  # type: ignore[assignment, misc]
+    RasterMergeCapability = None  # type: ignore[assignment, misc]
+
+# network : dépend de networkx (optionnel)
+try:
+    import capabilities.network  # noqa: F401
+    from capabilities.network import (
+        ConnectivityCheckCapability,
+        IsochroneCapability,
+        MinimumSpanningTreeCapability,
+        NetworkAllocationCapability,
+        ODMatrixCapability,
+        ShortestPathCapability,
+    )
+
+    _NETWORK_AVAILABLE = True
+except ImportError:
+    _NETWORK_AVAILABLE = False
+    IsochroneCapability = None  # type: ignore[assignment, misc]
+    ShortestPathCapability = None  # type: ignore[assignment, misc]
+    NetworkAllocationCapability = None  # type: ignore[assignment, misc]
+    ConnectivityCheckCapability = None  # type: ignore[assignment, misc]
+    ODMatrixCapability = None  # type: ignore[assignment, misc]
+    MinimumSpanningTreeCapability = None  # type: ignore[assignment, misc]
+
+__all__ = [
+    "Capability",
+    "REGISTRY",
+    "get",
+    "list_all",
+    "register",
+    # classification / choropleth
+    "BivariateChoroplethCapability",
+    "ChoroplethCapability",
+    "ClassifyCapability",
+    "ClassifyCategoricalCapability",
+    "ContinuousRampCapability",
+    "GraduatedSizeCapability",
+    "HeadTailBreaksCapability",
+    "NormalizeCapability",
+    "build_graduated_style_def",
+    "build_legend",
+    # vector
+    "AlphaShapeCapability",
+    "AreaLengthCapability",
+    "AssignProjectionCapability",
+    "BoundaryCapability",
+    "BufferCapability",
+    "CalculateCapability",
+    "CentroidCapability",
+    "ChaikinSmoothCapability",
+    "ClassifyByRingCapability",
+    "ClipCapability",
+    "ConcaveHullCapability",
+    "ConvexHullCapability",
+    "DelaunayTriangulationCapability",
+    "DensifyVerticesCapability",
+    "DissolveCapability",
+    "EnvelopeCapability",
+    "ExtractHolesCapability",
+    "ExtractSegmentsCapability",
+    "ExtractVerticesCapability",
+    "FilterCapability",
+    "ForceGeometryTypeCapability",
+    "IntersectsCapability",
+    "LineLocatePointCapability",
+    "LineMergeCapability",
+    "LineSubstringCapability",
+    "MakeValidCapability",
+    "MergeLayersCapability",
+    "MinBoundingCircleCapability",
+    "MultipartToSinglepartsCapability",
+    "NearestNeighborCapability",
+    "OffsetCurveCapability",
+    "OrientedBBoxCapability",
+    "PolygonizeCapability",
+    "ReprojectCapability",
+    "SimplifyCapability",
+    "SinglepartsToMultipartCapability",
+    "SnapToGridCapability",
+    "SpatialAggregateCapability",
+    "SpatialJoinCapability",
+    "SymmetricDifferenceCapability",
+    "UnionCapability",
+    "VectorDiffCapability",
+    "VoronoiPolygonsCapability",
+    # schema / attribute manipulation
+    "AddFieldCapability",
+    "AttributeJoinCapability",
+    "CaseWhenCapability",
+    "CastFieldCapability",
+    "CoalesceFieldsCapability",
+    "DropFieldCapability",
+    "LookupTableCapability",
+    "PivotCapability",
+    "RenameFieldCapability",
+    "SelectColumnsCapability",
+    "UnpivotCapability",
+    # selection / row-level
+    "DeduplicateCapability",
+    "RandomSampleCapability",
+    "SortCapability",
+    "TopNCapability",
+    # overlay
+    "EraseCapability",
+    "OverlayIntersectionCapability",
+    "OverlayUnionCapability",
+    # geometry transforms
+    "AddMCapability",
+    "AddZCapability",
+    "AffineTransformCapability",
+    "DropMCapability",
+    "DropZCapability",
+    "ReverseLinesCapability",
+    "SwapXYCapability",
+    # temporal
+    "TemporalFilterCapability",
+    "TemporalJoinCapability",
+    # pointcloud (load_las requires laspy; others are pure pandas/shapely)
+    "PointcloudFilterClassificationCapability",
+    "PointcloudGridSummaryCapability",
+    "PointcloudLoadLasCapability",
+    "PointcloudZonalHeightCapability",
+    # spatial statistics
+    "GetisOrdGStarCapability",
+    "MoransICapability",
+    "SpatialWeightsCapability",
+    # density & tessellation
+    "GridCreateCapability",
+    "HexGridCreateCapability",
+    "KDEHeatmapCapability",
+    # network topology
+    "ExtendDanglesCapability",
+    "NodeLinesCapability",
+    "RemoveDuplicateEdgesCapability",
+    "RemovePseudoNodesCapability",
+    "SnapEndpointsCapability",
+    # polygon topology
+    "FixGapsCapability",
+    "FixOverlapsCapability",
+    "RemoveSliversCapability",
+    "SnapBordersCapability",
+    # clustering (None si non disponible)
+    "DBSCANClusterCapability",
+    "HDBSCANClusterCapability",
+    "KMeansClusterCapability",
+    "_CLUSTERING_AVAILABLE",
+    # validation (Community — toujours disponible)
+    "TopologyCheckCapability",
+    "DuplicateGeometryCapability",
+    "AttributeValidationCapability",
+    "CompletenessCheckCapability",
+    # raster (None si non disponible)
+    "ZonalStatsCapability",
+    "ChangeDetectionCapability",
+    "RasterClipCapability",
+    "NdviCapability",
+    "RasterReprojectCapability",
+    "RasterMergeCapability",
+    "_RASTER_AVAILABLE",
+    # network (None si non disponible)
+    "ShortestPathCapability",
+    "IsochroneCapability",
+    "NetworkAllocationCapability",
+    "ConnectivityCheckCapability",
+    "ODMatrixCapability",
+    "MinimumSpanningTreeCapability",
+    "_NETWORK_AVAILABLE",
+    # postgis
+    "PostGISSQLCapability",
+]

capabilities/base.py

@@ -0,0 +1,106 @@
+"""
+Base class for all GISPulse capabilities.
+
+Each capability encapsulates a single, reusable spatial operation.
+Concrete implementations live in capabilities/vector.py (and future
+capabilities/raster.py, capabilities/network.py, etc.).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+import geopandas as gpd
+
+if TYPE_CHECKING:
+    from capabilities.strategy import ExecutionContext, ExecutionStrategy
+
+from core.logging import get_logger
+
+log = get_logger(__name__)
+
+
+class Capability(ABC):
+    """Abstract base for all GISPulse spatial capabilities.
+
+    Subclasses must declare:
+    - ``name``        : unique snake_case identifier used in the registry.
+    - ``description`` : human-readable one-liner for Studio/API.
+
+    And implement:
+    - ``execute()``   : the spatial operation itself.
+    - ``get_schema()`` (optional): JSON Schema of accepted **params.
+
+    Optionally, subclasses can populate ``_strategies`` with
+    :class:`ExecutionStrategy` instances to enable backend-aware
+    dispatching via ``execute_with_context()``.
+    """
+
+    name: str
+    description: str
+    # Subclasses override with a list of strategies; empty tuple prevents
+    # accidental mutation of the shared class-level default.
+    _strategies: list[ExecutionStrategy] | tuple[()] = ()
+
+    @abstractmethod
+    def execute(self, gdf: gpd.GeoDataFrame, **params) -> gpd.GeoDataFrame:
+        """Run the capability on a GeoDataFrame.
+
+        Args:
+            gdf:    Input GeoDataFrame (never mutated in-place).
+            **params: Capability-specific keyword arguments.
+
+        Returns:
+            New GeoDataFrame with the operation applied.
+        """
+        ...
+
+    def execute_with_context(
+        self, gdf: gpd.GeoDataFrame, ctx: ExecutionContext,
+    ) -> gpd.GeoDataFrame:
+        """Run the capability using the best available execution strategy.
+
+        Selects the highest-priority strategy that can execute in the
+        given context.  Falls back to the plain ``execute()`` method
+        (Python/GeoPandas) if no strategy is eligible or none are declared.
+
+        Args:
+            gdf: Input GeoDataFrame (never mutated in-place).
+            ctx: Runtime execution context with engine info and params.
+
+        Returns:
+            New GeoDataFrame with the operation applied.
+        """
+        from capabilities.strategy import select_strategy
+
+        if self._strategies:
+            strategy = select_strategy(self._strategies, ctx)
+            if strategy is not None:
+                log.info(
+                    "strategy_selected",
+                    capability=self.name,
+                    strategy=strategy.mode.value,
+                    priority=strategy.priority,
+                )
+                return strategy.execute(gdf, ctx)
+            log.debug(
+                "no_eligible_strategy",
+                capability=self.name,
+                fallback="python",
+            )
+
+        # Fallback: plain execute() with params from context
+        return self.execute(gdf, **ctx.params)
+
+    def get_schema(self) -> dict:
+        """Return the JSON Schema for this capability's **params.
+
+        Used by GISPulse Studio to build dynamic forms.
+        Subclasses should override this to expose their parameters.
+
+        Returns:
+            JSON Schema dict (``{"type": "object", "properties": {...}}``)
+            or an empty dict when no parameters are needed.
+        """
+        return {}