zero2route3d-sdk 0.2.0__py3-none-any.whl

zero2route3d/input_validation.py

@@ -0,0 +1,100 @@
+"""Small, dependency-free validation helpers shared by routing workflows."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Iterable, List, Optional, Sequence, Tuple
+
+
+def finite_number(value: Any, default: float = 0.0) -> float:
+    """Return a finite float or a safe default."""
+    try:
+        number = float(value)
+    except (TypeError, ValueError, OverflowError):
+        return default
+    return number if math.isfinite(number) else default
+
+
+def normalize_bbox(
+    bbox: Sequence[Any],
+    minimum_span: float = 0.005,
+) -> Tuple[float, float, float, float]:
+    """Validate and normalize ``(min_lon, min_lat, max_lon, max_lat)``."""
+    if not bbox or len(bbox) < 4:
+        raise ValueError("A bounding box needs four coordinates.")
+    values = [finite_number(value, float("nan")) for value in bbox[:4]]
+    if not all(math.isfinite(value) for value in values):
+        raise ValueError("The bounding box contains invalid coordinates.")
+    min_lon, min_lat, max_lon, max_lat = values
+    if not (-180.0 <= min_lon <= 180.0 and -180.0 <= max_lon <= 180.0):
+        raise ValueError("Longitude must be between -180 and 180 degrees.")
+    if not (-90.0 <= min_lat <= 90.0 and -90.0 <= max_lat <= 90.0):
+        raise ValueError("Latitude must be between -90 and 90 degrees.")
+    if min_lon > max_lon:
+        min_lon, max_lon = max_lon, min_lon
+    if min_lat > max_lat:
+        min_lat, max_lat = max_lat, min_lat
+    span = max(0.0001, finite_number(minimum_span, 0.005))
+    if max_lon - min_lon < span:
+        center = (min_lon + max_lon) / 2.0
+        min_lon, max_lon = center - span / 2.0, center + span / 2.0
+    if max_lat - min_lat < span:
+        center = (min_lat + max_lat) / 2.0
+        min_lat, max_lat = center - span / 2.0, center + span / 2.0
+    return min_lon, min_lat, max_lon, max_lat
+
+
+def normalize_time_intervals(
+    intervals: Iterable[Any],
+    max_intervals: int = 12,
+    max_minutes: float = 24.0 * 60.0,
+) -> List[float]:
+    """Return sorted, unique, positive time cutoffs within a safe bound."""
+    cleaned = {
+        round(value, 3)
+        for raw in intervals
+        for value in [finite_number(raw, -1.0)]
+        if 0.0 < value <= max_minutes
+    }
+    return sorted(cleaned)[: max(1, int(max_intervals))]
+
+
+def validate_waypoint_coordinates(waypoints: Sequence[Any]) -> Optional[str]:
+    """Validate waypoint count and WGS84 coordinate ranges."""
+    if not waypoints:
+        return "At least two waypoints are required."
+    if len(waypoints) > 500:
+        return "A route can contain at most 500 waypoints."
+    for index, waypoint in enumerate(waypoints, start=1):
+        lon = finite_number(getattr(waypoint, "lon", float("nan")), float("nan"))
+        lat = finite_number(getattr(waypoint, "lat", float("nan")), float("nan"))
+        if not (math.isfinite(lon) and math.isfinite(lat)):
+            return f"Waypoint {index} has invalid coordinates."
+        if not (-180.0 <= lon <= 180.0 and -90.0 <= lat <= 90.0):
+            return f"Waypoint {index} is outside the WGS84 coordinate range."
+    return None
+
+
+def deduplicate_adjacent_coordinates(
+    coords: Sequence[Sequence[float]],
+    tolerance_m: float = 0.05,
+) -> List[Tuple[float, float, float]]:
+    """Remove consecutive coordinates that represent the same map position."""
+    from .kinematics import haversine_distance_2d
+
+    result: List[Tuple[float, float, float]] = []
+    tolerance = max(0.0, finite_number(tolerance_m, 0.05))
+    for coord in coords:
+        if not coord or len(coord) < 2:
+            continue
+        lon = finite_number(coord[0], float("nan"))
+        lat = finite_number(coord[1], float("nan"))
+        if not (math.isfinite(lon) and math.isfinite(lat)):
+            continue
+        z = finite_number(coord[2], 0.0) if len(coord) > 2 else 0.0
+        point = (lon, lat, z)
+        if not result or haversine_distance_2d(result[-1], point) > tolerance:
+            result.append(point)
+        elif abs(z - result[-1][2]) > 0.01:
+            result[-1] = point
+    return result

zero2route3d/integrations.py

@@ -0,0 +1,260 @@
+"""Geospatial ecosystem integrations: GeoPandas, Shapely, NetworkX, and Rasterio.
+
+Allows seamless conversion between 02Route 3D objects and standard Python GIS libraries.
+All dependencies are lazily loaded with graceful fallbacks.
+"""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+from .kinematics import haversine_distance_2d
+from .network_source import RoadSegment
+from .raster_source import GeoTiffRasterSource
+
+
+def to_shapely_linestring(coordinates_3d: Sequence[Sequence[float]]) -> Any:
+    """Convert 3D coordinate sequence to a shapely.geometry.LineString (Z-aware)."""
+    try:
+        import shapely.geometry
+
+        return shapely.geometry.LineString([c[:3] for c in coordinates_3d])
+    except ImportError as exc:
+        raise ImportError(
+            "shapely is required for geometric conversion. Install via 'pip install shapely'."
+        ) from exc
+
+
+def from_geodataframe(
+    gdf: Any,
+    id_column: Optional[str] = None,
+    highway_column: Optional[str] = "highway",
+    surface_column: Optional[str] = "surface",
+    oneway_column: Optional[str] = "oneway",
+) -> List[RoadSegment]:
+    """Extract 02Route 3D RoadSegment objects from a geopandas.GeoDataFrame of LineStrings."""
+    try:
+        import geopandas as gpd
+    except ImportError as exc:
+        raise ImportError("geopandas is required. Install via 'pip install geopandas'.") from exc
+
+    if not isinstance(gdf, gpd.GeoDataFrame):
+        raise TypeError("Expected geopandas.GeoDataFrame instance.")
+
+    segments: List[RoadSegment] = []
+
+    for _idx, row in gdf.iterrows():
+        geom = row.geometry
+        if geom is None or geom.is_empty:
+            continue
+
+        lines = (
+            [geom]
+            if geom.geom_type == "LineString"
+            else (geom.geoms if geom.geom_type == "MultiLineString" else [])
+        )
+        for line in lines:
+            coords = list(line.coords)
+            if len(coords) < 2:
+                continue
+
+            highway_val = (
+                str(row.get(highway_column, "residential"))
+                if highway_column in row
+                else "residential"
+            )
+            surface_val = (
+                str(row.get(surface_column, "asphalt")) if surface_column in row else "asphalt"
+            )
+            oneway_raw = row.get(oneway_column, False) if oneway_column in row else False
+            oneway_tag = str(oneway_raw).strip().lower()
+            # oneway=-1 means one-way *against* the digitisation order. Treating it
+            # as a plain one-way stores the segment pointing the wrong way, so the
+            # router sends traffic the wrong direction down it.
+            reversed_oneway = oneway_tag in ("-1", "reverse")
+            is_oneway = bool(
+                oneway_raw is True or oneway_tag in ("yes", "true", "1") or reversed_oneway
+            )
+            is_steps = "step" in highway_val.lower()
+
+            for i in range(len(coords) - 1):
+                p1_raw = coords[i]
+                p2_raw = coords[i + 1]
+
+                p1: Tuple[float, float, float] = (
+                    float(p1_raw[0]),
+                    float(p1_raw[1]),
+                    float(p1_raw[2]) if len(p1_raw) > 2 and math.isfinite(p1_raw[2]) else 0.0,
+                )
+                p2: Tuple[float, float, float] = (
+                    float(p2_raw[0]),
+                    float(p2_raw[1]),
+                    float(p2_raw[2]) if len(p2_raw) > 2 and math.isfinite(p2_raw[2]) else 0.0,
+                )
+
+                length_m = haversine_distance_2d(p1, p2)
+
+                seg = RoadSegment(
+                    p1=p2 if reversed_oneway else p1,
+                    p2=p1 if reversed_oneway else p2,
+                    length_m=length_m,
+                    highway_type=highway_val,
+                    surface=surface_val,
+                    is_oneway=is_oneway,
+                    is_steps=is_steps,
+                )
+                segments.append(seg)
+
+    return segments
+
+
+def to_geodataframe(
+    items: Union[List[RoadSegment], Any],
+    crs: str = "EPSG:4326",
+) -> Any:
+    """Convert RoadSegment list or RouteResult3D into a geopandas.GeoDataFrame with 3D LineStrings."""
+    try:
+        import geopandas as gpd
+        import shapely.geometry
+    except ImportError as exc:
+        raise ImportError("geopandas and shapely are required for GeoDataFrame creation.") from exc
+
+    records: List[Dict[str, Any]] = []
+
+    # Check if input is RouteResult3D
+    if hasattr(items, "coordinates_3d") and hasattr(items, "statistics"):
+        coords = items.coordinates_3d
+        if len(coords) >= 2:
+            geom = shapely.geometry.LineString(coords)
+            records.append(
+                {
+                    "geometry": geom,
+                    "distance_m": items.statistics.total_distance_m,
+                    "duration_min": items.statistics.total_duration_min,
+                    "climb_m": items.statistics.elevation_gain_m,
+                    "descent_m": items.statistics.elevation_loss_m,
+                    "max_slope_pct": items.statistics.max_slope_pct,
+                    "profile": getattr(
+                        getattr(items, "profile", None),
+                        "name",
+                        getattr(items, "profile_name", "3D Route"),
+                    ),
+                }
+            )
+    elif isinstance(items, list):
+        for seg in items:
+            if isinstance(seg, RoadSegment):
+                geom = shapely.geometry.LineString([seg.p1, seg.p2])
+                records.append(
+                    {
+                        "geometry": geom,
+                        "length_m": seg.length_m,
+                        "highway_type": seg.highway_type,
+                        "surface": seg.surface,
+                        "is_oneway": seg.is_oneway,
+                        "is_steps": seg.is_steps,
+                    }
+                )
+
+    if not records:
+        # GeoDataFrame([]) has no geometry column, so every downstream .geometry
+        # access raises instead of yielding an empty result set.
+        return gpd.GeoDataFrame({"geometry": []}, geometry="geometry", crs=crs)
+
+    return gpd.GeoDataFrame(records, geometry="geometry", crs=crs)
+
+
+def to_networkx_digraph(engine_or_segments: Any) -> Any:
+    """Convert 02Route 3D graph or segment list into a networkx.DiGraph with kinematic edge weights."""
+    try:
+        import networkx as nx
+    except ImportError as exc:
+        raise ImportError("networkx is required. Install via 'pip install networkx'.") from exc
+
+    g = nx.DiGraph()
+
+    if hasattr(engine_or_segments, "nodes") and hasattr(engine_or_segments, "adj"):
+        for node_id, coord in engine_or_segments.nodes.items():
+            g.add_node(
+                node_id, lon=coord[0], lat=coord[1], elevation_m=coord[2] if len(coord) > 2 else 0.0
+            )
+
+        for u, neighbors in engine_or_segments.adj.items():
+            for v, length_m, slope_pct, meta in neighbors:
+                g.add_edge(
+                    u,
+                    v,
+                    length_m=length_m,
+                    slope_pct=slope_pct,
+                    highway_type=meta.get("highway_type", "residential"),
+                    surface=meta.get("surface", "asphalt"),
+                    is_steps=meta.get("is_steps", False),
+                )
+    elif isinstance(engine_or_segments, list):
+        for seg in engine_or_segments:
+            if isinstance(seg, RoadSegment):
+                n1 = f"n_{round(seg.p1[0], 5)}_{round(seg.p1[1], 5)}"
+                n2 = f"n_{round(seg.p2[0], 5)}_{round(seg.p2[1], 5)}"
+                g.add_node(
+                    n1,
+                    lon=seg.p1[0],
+                    lat=seg.p1[1],
+                    elevation_m=seg.p1[2] if len(seg.p1) > 2 else 0.0,
+                )
+                g.add_node(
+                    n2,
+                    lon=seg.p2[0],
+                    lat=seg.p2[1],
+                    elevation_m=seg.p2[2] if len(seg.p2) > 2 else 0.0,
+                )
+                slope = (
+                    ((seg.p2[2] - seg.p1[2]) / seg.length_m) * 100.0
+                    if seg.length_m > 0 and len(seg.p1) > 2 and len(seg.p2) > 2
+                    else 0.0
+                )
+
+                g.add_edge(
+                    n1,
+                    n2,
+                    length_m=seg.length_m,
+                    slope_pct=slope,
+                    highway_type=seg.highway_type,
+                    surface=seg.surface,
+                    is_steps=seg.is_steps,
+                )
+                if not seg.is_oneway:
+                    g.add_edge(
+                        n2,
+                        n1,
+                        length_m=seg.length_m,
+                        slope_pct=-slope,
+                        highway_type=seg.highway_type,
+                        surface=seg.surface,
+                        is_steps=seg.is_steps,
+                    )
+
+    return g
+
+
+def sample_rasterio_dem(
+    tif_path: Union[str, Path],
+    coords: Sequence[Tuple[float, float]],
+    band: int = 1,
+) -> List[Optional[float]]:
+    """Sample elevations from a GeoTIFF at WGS84 (lon, lat) coordinates.
+
+    Coordinates are reprojected into the raster's own CRS first, so a UTM or
+    national-grid DEM works without the caller converting anything -- previously
+    every sample of such a raster silently fell outside the grid.
+
+    NoData and out-of-coverage points come back as None rather than 0.0, which is
+    a real elevation and must not stand in for missing data. All points are read
+    in a single pass.
+    """
+    source = GeoTiffRasterSource(tif_path, band=band)
+    try:
+        return source.sample_many(coords)
+    finally:
+        source.close()

zero2route3d/isochrone_engine.py

@@ -0,0 +1,220 @@
+"""3D Network-based Isochrone and Accessibility Catchment Engine."""
+
+from __future__ import annotations
+
+import heapq
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Sequence, Tuple, Union
+
+from .input_validation import normalize_time_intervals
+from .mobility_profiles import MobilityProfile, resolve_profile
+from .routing_engine import RoutingEngine3D, Waypoint
+
+_EARTH_RADIUS_M = 6371000.0
+
+
+def convex_hull_2d(points: Sequence[Tuple[float, float]]) -> List[Tuple[float, float]]:
+    """Monotone-chain convex hull of (lon, lat) points, counter-clockwise, no repeat.
+
+    Dependency-free so isochrone geometry does not require shapely.
+    """
+    unique = sorted({(float(x), float(y)) for x, y in points})
+    if len(unique) < 3:
+        return unique
+
+    def cross(o: Tuple[float, float], a: Tuple[float, float], b: Tuple[float, float]) -> float:
+        return (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
+
+    lower: List[Tuple[float, float]] = []
+    for pt in unique:
+        while len(lower) >= 2 and cross(lower[-2], lower[-1], pt) <= 0:
+            lower.pop()
+        lower.append(pt)
+
+    upper: List[Tuple[float, float]] = []
+    for pt in reversed(unique):
+        while len(upper) >= 2 and cross(upper[-2], upper[-1], pt) <= 0:
+            upper.pop()
+        upper.append(pt)
+
+    return lower[:-1] + upper[:-1]
+
+
+def _ring_area_m2(ring: Sequence[Tuple[float, float]]) -> float:
+    """Shoelace area of a lon/lat ring, on a local equirectangular projection."""
+    if len(ring) < 3:
+        return 0.0
+    mean_lat_rad = math.radians(sum(lat for _lon, lat in ring) / len(ring))
+    scale_x = _EARTH_RADIUS_M * math.cos(mean_lat_rad) * math.pi / 180.0
+    scale_y = _EARTH_RADIUS_M * math.pi / 180.0
+
+    total = 0.0
+    for (lon1, lat1), (lon2, lat2) in zip(ring, list(ring[1:]) + [ring[0]]):
+        total += (lon1 * scale_x) * (lat2 * scale_y) - (lon2 * scale_x) * (lat1 * scale_y)
+    return abs(total) * 0.5
+
+
+@dataclass
+class IsochroneBand:
+    """Individual time contour band (e.g. 0-5 min, 5-10 min)."""
+
+    time_cutoff_min: float
+    reachable_node_count: int
+    approx_area_ha: float
+    #: Convex hull of the reachable nodes, counter-clockwise, first point not repeated.
+    boundary_points: List[Tuple[float, float]] = field(default_factory=list)
+
+    @property
+    def area_sqkm(self) -> float:
+        """Catchment area in square kilometres."""
+        return self.approx_area_ha / 100.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "time_cutoff_min": self.time_cutoff_min,
+            "reachable_node_count": self.reachable_node_count,
+            "approx_area_ha": round(self.approx_area_ha, 2),
+            "area_sqkm": round(self.area_sqkm, 4),
+            "boundary_points_count": len(self.boundary_points),
+        }
+
+    def to_geojson_feature(self) -> Dict[str, Any]:
+        """Convex-hull catchment as a GeoJSON Polygon Feature (empty geometry if degenerate)."""
+        ring = list(self.boundary_points)
+        geometry: Any = None
+        if len(ring) >= 3:
+            closed = ring + [ring[0]]
+            geometry = {
+                "type": "Polygon",
+                "coordinates": [[[round(lon, 6), round(lat, 6)] for lon, lat in closed]],
+            }
+        return {"type": "Feature", "geometry": geometry, "properties": self.to_dict()}
+
+
+@dataclass
+class IsochroneResult:
+    """Complete multi-tier 3D accessibility service area result."""
+
+    origin: Waypoint
+    profile: MobilityProfile
+    bands: List[IsochroneBand]
+    total_reachable_nodes: int
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "origin": {"lon": self.origin.lon, "lat": self.origin.lat, "name": self.origin.name},
+            "profile_name": self.profile.name,
+            "total_reachable_nodes": self.total_reachable_nodes,
+            "bands": [b.to_dict() for b in self.bands],
+        }
+
+    def to_geojson(self) -> Dict[str, Any]:
+        """All catchment bands as one GeoJSON FeatureCollection, widest band first.
+
+        Ordering matters for rendering: drawing the widest polygon first lets the
+        tighter bands paint on top of it instead of being hidden underneath.
+        """
+        ordered = sorted(self.bands, key=lambda b: b.time_cutoff_min, reverse=True)
+        return {
+            "type": "FeatureCollection",
+            "properties": {
+                "origin": {"lon": self.origin.lon, "lat": self.origin.lat},
+                "profile_key": self.profile.key,
+                "profile_name": self.profile.name,
+                "total_reachable_nodes": self.total_reachable_nodes,
+            },
+            "features": [band.to_geojson_feature() for band in ordered],
+        }
+
+
+class IsochroneEngine3D:
+    """Generates 3D multi-interval travel-time catchment zones from a topological graph."""
+
+    def __init__(self, routing_engine: RoutingEngine3D) -> None:
+        self.engine = routing_engine
+
+    def compute_isochrones(
+        self,
+        origin: Waypoint,
+        profile_key: Union[str, MobilityProfile] = "adult",
+        time_intervals_min: Sequence[float] = (5.0, 10.0, 15.0, 20.0, 30.0),
+    ) -> IsochroneResult:
+        """Propagate Dijkstra wavefront along 3D graph up to maximum time interval."""
+        profile = resolve_profile(profile_key)
+        intervals_min = normalize_time_intervals(time_intervals_min)
+        if not intervals_min:
+            return IsochroneResult(origin, profile, [], 0)
+        start_node = self.engine.find_nearest_node((origin.lon, origin.lat))
+
+        if start_node is None or not self.engine.nodes:
+            return IsochroneResult(origin, profile, [], 0)
+
+        max_cutoff_s = max(intervals_min) * 60.0
+        sorted_intervals_s = [t * 60.0 for t in intervals_min]
+
+        # Dijkstra queue: (travel_time_seconds, node_id)
+        pq: List[Tuple[float, int]] = [(0.0, start_node)]
+        min_times: Dict[int, float] = {start_node: 0.0}
+        visited = set()
+
+        while pq:
+            t_curr, u = heapq.heappop(pq)
+            if u in visited:
+                continue
+            visited.add(u)
+
+            if t_curr > max_cutoff_s:
+                continue
+
+            for v, seg_len, slope_pct, meta in self.engine.adj.get(u, []):
+                if v in visited:
+                    continue
+
+                cost = profile.calculate_edge_resistance(
+                    length_m=seg_len,
+                    slope_pct=slope_pct,
+                    is_steps=meta.get("is_steps", False),
+                    hierarchy_rank=meta.get("hierarchy", 4),
+                )
+                if not math.isfinite(cost):
+                    continue
+
+                seg_time_s = profile.travel_time_seconds(
+                    seg_len,
+                    slope_pct=slope_pct,
+                    hierarchy_rank=meta.get("hierarchy", 4),
+                )
+                tentative_t = t_curr + seg_time_s
+
+                if tentative_t < min_times.get(v, float("inf")) and tentative_t <= max_cutoff_s:
+                    min_times[v] = tentative_t
+                    heapq.heappush(pq, (tentative_t, v))
+
+        bands: List[IsochroneBand] = []
+        for cutoff_s in sorted_intervals_s:
+            cutoff_min = cutoff_s / 60.0
+            nodes_in_band = [nid for nid, t in min_times.items() if t <= cutoff_s]
+            pts = [(self.engine.nodes[nid][0], self.engine.nodes[nid][1]) for nid in nodes_in_band]
+
+            # A real convex hull of the reachable nodes, and its real area. The
+            # previous version stored the first 50 nodes in dictionary order and
+            # called them a boundary, then reported pi*r^2 times a fudge factor.
+            hull = convex_hull_2d(pts)
+            area_ha = _ring_area_m2(hull) / 10000.0
+
+            bands.append(
+                IsochroneBand(
+                    time_cutoff_min=cutoff_min,
+                    reachable_node_count=len(nodes_in_band),
+                    approx_area_ha=area_ha,
+                    boundary_points=hull,
+                )
+            )
+
+        return IsochroneResult(
+            origin=origin,
+            profile=profile,
+            bands=bands,
+            total_reachable_nodes=len(min_times),
+        )