zero2route3d-sdk 0.2.0__py3-none-any.whl

zero2route3d/__init__.py

@@ -0,0 +1,212 @@
+"""02Route 3D SDK — Multi-Criteria 3D Kinematic & Spatial Mobility Analytics Library."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+__author__ = "Yusuf Eminoğlu"
+__email__ = "yusufeminoglu@gmail.com"
+
+from .accessibility_equity import (
+    AccessibilityEquityEngine,
+    EquityScorecardResult,
+    SupplyFacility,
+    ZoneAccessibilityRecord,
+)
+from .ahp_engine import AHPEngine, AHPResult
+from .api import (
+    match_gps_track_3d,
+    solve_3d_isochrones,
+    solve_3d_route,
+    solve_4d_pareto_frontier,
+)
+from .basemap import add_osm_basemap
+from .copernicus_dem import CopernicusDemError, CopernicusDemTileSource
+from .dem_fetcher import NODATA, GlobalDemFetcher
+from .environmental_raster import EnvironmentalSurfaceSampler, MCDAWeights
+from .evacuation import EvacuationPlan, EvacuationRouter, HazardZone
+from .html_bundler import StandaloneHtmlBundler
+from .integrations import (
+    from_geodataframe,
+    sample_rasterio_dem,
+    to_geodataframe,
+    to_networkx_digraph,
+    to_shapely_linestring,
+)
+from .isochrone_engine import IsochroneBand, IsochroneEngine3D, IsochroneResult
+from .kinematics import (
+    aerodynamic_drag_power,
+    cycling_energy_cost,
+    cyclist_speed,
+    haversine_distance_2d,
+    haversine_distance_3d,
+    minetti_energy_cost,
+    rolling_resistance_force,
+    scooter_speed,
+    senior_fatigue_decay,
+    solar_irradiance_aspect_factor,
+    tobler_walking_speed,
+    universal_thermal_comfort_utci,
+    vehicle_free_flow_speed,
+)
+from .map_matching_3d import (
+    GPXPoint,
+    HMMMapMatcher3D,
+    MapMatching3DResult,
+    MatchedTrackPoint3D,
+)
+from .micro_elevation import (
+    BicubicSurfaceInterpolator,
+    IDWSurfaceInterpolator,
+    MicroElevationEngine,
+    SurfaceGradient3D,
+)
+from .mobility_profiles import (
+    PROFILE_CATEGORIES,
+    PROFILES,
+    MobilityProfile,
+    UnknownProfileError,
+    get_profile,
+    get_profile_color,
+    list_profile_keys,
+    list_profile_keys_for_group,
+    load_custom_profile_json,
+    resolve_profile,
+    save_custom_profile_json,
+)
+from .multimodal import MultiModalJourney, MultiModalLeg, MultiModalRouter
+from .network_source import NetworkSourceError, NetworkSourceManager, RoadSegment
+from .osm_downloader import OsmBuilding, OsmDataFetcher
+from .pareto_router import (
+    ParetoCostVector,
+    ParetoFrontierResult,
+    ParetoMultiObjectiveRouter,
+    ParetoRouteSolution,
+)
+from .plotting import (
+    plot_elevation_profile,
+    plot_lorenz_equity_curve,
+    plot_pareto_frontier_2d,
+)
+from .profile_dxf import export_route_to_dxf_3d
+from .profile_stats import (
+    CueInstruction,
+    RouteStatistics,
+    compute_route_statistics,
+    densify_3d_linestring,
+    generate_cue_sheet,
+    smooth_elevation_series,
+)
+from .qml_generator import generate_route_qml_style
+from .raster_source import GeoTiffRasterSource, RasterSourceError
+from .report_generator import generate_analytical_report_html
+from .route_corridor_3d import filter_buildings_in_corridor
+from .routing_engine import RouteResult3D, RoutingEngine3D, Waypoint
+from .solar_shadow import (
+    ShadeExposureReport,
+    SolarPosition,
+    calculate_solar_position,
+    compute_shade_exposure_along_route,
+)
+from .tsp_solver import solve_tsp_order
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__email__",
+    "AccessibilityEquityEngine",
+    "EquityScorecardResult",
+    "SupplyFacility",
+    "ZoneAccessibilityRecord",
+    "AHPEngine",
+    "AHPResult",
+    "add_osm_basemap",
+    "solve_3d_route",
+    "solve_3d_isochrones",
+    "solve_4d_pareto_frontier",
+    "match_gps_track_3d",
+    "to_geodataframe",
+    "from_geodataframe",
+    "to_networkx_digraph",
+    "to_shapely_linestring",
+    "sample_rasterio_dem",
+    "plot_elevation_profile",
+    "plot_pareto_frontier_2d",
+    "plot_lorenz_equity_curve",
+    "CopernicusDemError",
+    "CopernicusDemTileSource",
+    "GlobalDemFetcher",
+    "GeoTiffRasterSource",
+    "RasterSourceError",
+    "NODATA",
+    "EnvironmentalSurfaceSampler",
+    "MCDAWeights",
+    "EvacuationPlan",
+    "EvacuationRouter",
+    "HazardZone",
+    "StandaloneHtmlBundler",
+    "IsochroneBand",
+    "IsochroneEngine3D",
+    "IsochroneResult",
+    "GPXPoint",
+    "HMMMapMatcher3D",
+    "MapMatching3DResult",
+    "MatchedTrackPoint3D",
+    "BicubicSurfaceInterpolator",
+    "IDWSurfaceInterpolator",
+    "MicroElevationEngine",
+    "SurfaceGradient3D",
+    "MultiModalJourney",
+    "MultiModalLeg",
+    "MultiModalRouter",
+    "ParetoCostVector",
+    "ParetoFrontierResult",
+    "ParetoMultiObjectiveRouter",
+    "ParetoRouteSolution",
+    "export_route_to_dxf_3d",
+    "generate_analytical_report_html",
+    "generate_route_qml_style",
+    "calculate_solar_position",
+    "compute_shade_exposure_along_route",
+    "ShadeExposureReport",
+    "SolarPosition",
+    "aerodynamic_drag_power",
+    "cyclist_speed",
+    "haversine_distance_2d",
+    "haversine_distance_3d",
+    "cycling_energy_cost",
+    "minetti_energy_cost",
+    "rolling_resistance_force",
+    "scooter_speed",
+    "senior_fatigue_decay",
+    "solar_irradiance_aspect_factor",
+    "tobler_walking_speed",
+    "universal_thermal_comfort_utci",
+    "vehicle_free_flow_speed",
+    "PROFILES",
+    "PROFILE_CATEGORIES",
+    "MobilityProfile",
+    "UnknownProfileError",
+    "get_profile",
+    "get_profile_color",
+    "list_profile_keys",
+    "list_profile_keys_for_group",
+    "resolve_profile",
+    "load_custom_profile_json",
+    "save_custom_profile_json",
+    "NetworkSourceManager",
+    "NetworkSourceError",
+    "RoadSegment",
+    "OsmBuilding",
+    "OsmDataFetcher",
+    "filter_buildings_in_corridor",
+    "CueInstruction",
+    "RouteStatistics",
+    "compute_route_statistics",
+    "densify_3d_linestring",
+    "generate_cue_sheet",
+    "smooth_elevation_series",
+    "RouteResult3D",
+    "RoutingEngine3D",
+    "Waypoint",
+    "solve_tsp_order",
+]

zero2route3d/accessibility_equity.py

@@ -0,0 +1,214 @@
+"""Urban Mobility Accessibility Equity Scorecard Engine.
+
+Implements:
+1. Enhanced Two-Step Floating Catchment Area (E2SFCA) with continuous Gaussian decay.
+2. Spatial Gini Coefficient & Lorenz Curve generation for accessibility justice.
+3. Theil Index entropy decomposition for spatial disparities.
+4. Automated equity classification (Transit Deserts, Vulnerable, Oasis).
+
+Author: Yusuf Eminoglu
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+
+@dataclass
+class ZoneAccessibilityRecord:
+    """Individual zone demographic and computed spatial accessibility indicators."""
+
+    zone_id: str
+    name: str
+    lon: float
+    lat: float
+    population: float
+    accessibility_score: float = 0.0
+    equity_tier: str = "Undetermined"
+    percentile_rank: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "zone_id": self.zone_id,
+            "name": self.name,
+            "lon": self.lon,
+            "lat": self.lat,
+            "population": self.population,
+            "accessibility_score": round(self.accessibility_score, 4),
+            "equity_tier": self.equity_tier,
+            "percentile_rank": round(self.percentile_rank, 1),
+        }
+
+
+@dataclass
+class SupplyFacility:
+    """Public service destination / facility (e.g. hospital, metro station, school)."""
+
+    facility_id: str
+    name: str
+    lon: float
+    lat: float
+    capacity: float
+
+
+@dataclass
+class EquityScorecardResult:
+    """Comprehensive Spatial Equity & Transport Justice Analytical Report."""
+
+    gini_coefficient: float
+    palma_ratio: float  # Top 10% / Bottom 40% accessibility ratio
+    theil_index: float
+    mean_accessibility: float
+    median_accessibility: float
+    lorenz_curve: List[Dict[str, float]]
+    zones: List[ZoneAccessibilityRecord]
+    tier_distribution: Dict[str, int] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "gini_coefficient": round(self.gini_coefficient, 4),
+            "palma_ratio": round(self.palma_ratio, 2),
+            "theil_index": round(self.theil_index, 4),
+            "mean_accessibility": round(self.mean_accessibility, 4),
+            "median_accessibility": round(self.median_accessibility, 4),
+            "tier_distribution": self.tier_distribution,
+            "lorenz_curve": self.lorenz_curve,
+            "zone_count": len(self.zones),
+        }
+
+
+class AccessibilityEquityEngine:
+    """Spatial accessibility computation and distributional justice scorecard."""
+
+    def __init__(self, catchment_radius_m: float = 1500.0) -> None:
+        self.catchment_radius_m = catchment_radius_m
+
+    def gaussian_decay(self, distance_m: float) -> float:
+        """Continuous Gaussian distance friction function."""
+        if distance_m > self.catchment_radius_m:
+            return 0.0
+        d_0 = self.catchment_radius_m
+        numerator = math.exp(-0.5 * ((distance_m / d_0) ** 2)) - math.exp(-0.5)
+        denominator = 1.0 - math.exp(-0.5)
+        return max(0.0, numerator / denominator)
+
+    def compute_e2sfca(
+        self,
+        demand_zones: Sequence[ZoneAccessibilityRecord],
+        supply_facilities: Sequence[SupplyFacility],
+        distance_func: Optional[Callable[[Tuple[float, float], Tuple[float, float]], float]] = None,
+    ) -> EquityScorecardResult:
+        """Execute Enhanced Two-Step Floating Catchment Area (E2SFCA) algorithm."""
+        from .kinematics import haversine_distance_2d
+
+        dist_fn = distance_func or (lambda p1, p2: haversine_distance_2d(p1, p2))
+        zones_list = [
+            ZoneAccessibilityRecord(
+                zone_id=z.zone_id,
+                name=z.name,
+                lon=z.lon,
+                lat=z.lat,
+                population=z.population,
+            )
+            for z in demand_zones
+        ]
+
+        # Step 1: Compute Provider-to-Population Ratio (R_j)
+        facility_ratios: Dict[str, float] = {}
+        for fac in supply_facilities:
+            weighted_demand = 0.0
+            for z in zones_list:
+                d = dist_fn((fac.lon, fac.lat), (z.lon, z.lat))
+                if d <= self.catchment_radius_m:
+                    w = self.gaussian_decay(d)
+                    weighted_demand += z.population * w
+
+            if weighted_demand > 0:
+                facility_ratios[fac.facility_id] = fac.capacity / weighted_demand
+            else:
+                facility_ratios[fac.facility_id] = 0.0
+
+        # Step 2: Compute Accessibility Score (A_i) for each Demand Zone
+        for z in zones_list:
+            acc_score = 0.0
+            for fac in supply_facilities:
+                d = dist_fn((z.lon, z.lat), (fac.lon, fac.lat))
+                if d <= self.catchment_radius_m:
+                    w = self.gaussian_decay(d)
+                    acc_score += facility_ratios[fac.facility_id] * w
+            z.accessibility_score = acc_score
+
+        # Step 3: Equity Diagnostics (Gini, Lorenz Curve, Theil Index)
+        sorted_zones = sorted(zones_list, key=lambda x: x.accessibility_score)
+        total_pop = sum(z.population for z in sorted_zones) or 1.0
+        total_acc_weighted = sum(z.population * z.accessibility_score for z in sorted_zones) or 1.0
+
+        cum_pop = 0.0
+        cum_acc = 0.0
+        lorenz_points: List[Dict[str, float]] = [{"pop_share": 0.0, "acc_share": 0.0}]
+        gini_sum = 0.0
+        prev_p = 0.0
+        prev_a = 0.0
+
+        for idx, z in enumerate(sorted_zones):
+            z.percentile_rank = (idx + 1) / len(sorted_zones) * 100.0
+            cum_pop += z.population
+            cum_acc += z.population * z.accessibility_score
+
+            p_curr = cum_pop / total_pop
+            a_curr = cum_acc / total_acc_weighted
+
+            gini_sum += (p_curr - prev_p) * (a_curr + prev_a)
+            prev_p = p_curr
+            prev_a = a_curr
+
+            if idx % max(1, len(sorted_zones) // 20) == 0 or idx == len(sorted_zones) - 1:
+                lorenz_points.append({"pop_share": round(p_curr, 4), "acc_share": round(a_curr, 4)})
+
+        gini = max(0.0, min(1.0, 1.0 - gini_sum))
+
+        # Theil Index
+        mean_acc = total_acc_weighted / total_pop
+        theil = 0.0
+        for z in sorted_zones:
+            if z.accessibility_score > 0 and mean_acc > 0:
+                ratio = z.accessibility_score / mean_acc
+                theil += (z.population / total_pop) * ratio * math.log(ratio)
+        theil = max(0.0, theil)
+
+        # Palma Ratio
+        bottom_40_acc = sum(
+            z.accessibility_score * z.population for z in sorted_zones if z.percentile_rank <= 40.0
+        )
+        top_10_acc = sum(
+            z.accessibility_score * z.population for z in sorted_zones if z.percentile_rank >= 90.0
+        )
+        palma = (top_10_acc / max(0.001, bottom_40_acc)) if bottom_40_acc > 0 else 1.0
+
+        # Tier Categorization
+        tier_counts = {"Transit Desert": 0, "Underserved": 0, "Adequate": 0, "Mobility Oasis": 0}
+        median_acc = sorted_zones[len(sorted_zones) // 2].accessibility_score
+
+        for z in sorted_zones:
+            if z.accessibility_score <= 0.0001:
+                z.equity_tier = "Transit Desert"
+            elif z.accessibility_score < median_acc * 0.5:
+                z.equity_tier = "Underserved"
+            elif z.accessibility_score < median_acc * 1.5:
+                z.equity_tier = "Adequate"
+            else:
+                z.equity_tier = "Mobility Oasis"
+            tier_counts[z.equity_tier] += 1
+
+        return EquityScorecardResult(
+            gini_coefficient=gini,
+            palma_ratio=palma,
+            theil_index=theil,
+            mean_accessibility=mean_acc,
+            median_accessibility=median_acc,
+            lorenz_curve=lorenz_points,
+            zones=sorted_zones,
+            tier_distribution=tier_counts,
+        )

zero2route3d/ahp_engine.py

@@ -0,0 +1,117 @@
+"""Analytic Hierarchy Process (AHP) multi-criteria decision engine.
+
+Provides pairwise comparison matrix construction, principal eigenvector weight
+calculation, and Saaty consistency ratio (CR < 0.10) validation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Sequence
+
+# Saaty Random Consistency Index (RI) table for matrix sizes 1..10
+RANDOM_INDEX: Dict[int, float] = {
+    1: 0.00,
+    2: 0.00,
+    3: 0.58,
+    4: 0.90,
+    5: 1.12,
+    6: 1.24,
+    7: 1.32,
+    8: 1.41,
+    9: 1.45,
+    10: 1.49,
+}
+
+
+@dataclass
+class AHPResult:
+    """Output of AHP analysis with weights, consistency metrics, and status."""
+
+    criteria: List[str]
+    weights: Dict[str, float]
+    lambda_max: float
+    consistency_index: float
+    consistency_ratio: float
+    is_consistent: bool
+    status_message: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "criteria": self.criteria,
+            "weights": {k: round(v, 4) for k, v in self.weights.items()},
+            "lambda_max": round(self.lambda_max, 4),
+            "consistency_index": round(self.consistency_index, 4),
+            "consistency_ratio": round(self.consistency_ratio, 4),
+            "is_consistent": self.is_consistent,
+            "status_message": self.status_message,
+        }
+
+
+class AHPEngine:
+    """Solves AHP pairwise comparison matrices for multi-criteria routing weights."""
+
+    def __init__(self, criteria: Sequence[str]) -> None:
+        self.criteria = list(criteria)
+        self.n = len(self.criteria)
+        self.matrix: List[List[float]] = [[1.0] * self.n for _ in range(self.n)]
+
+    def set_pairwise_comparison(self, criterion_a: str, criterion_b: str, value: float) -> None:
+        """Set pairwise importance of criterion A relative to B (1/9 to 9 scale)."""
+        if criterion_a not in self.criteria or criterion_b not in self.criteria:
+            return
+        i = self.criteria.index(criterion_a)
+        j = self.criteria.index(criterion_b)
+        val = max(1.0 / 9.0, min(9.0, float(value)))
+        self.matrix[i][j] = val
+        self.matrix[j][i] = 1.0 / val
+
+    def calculate(self) -> AHPResult:
+        """Compute principal eigenvector weights and consistency ratio."""
+        if self.n == 0:
+            return AHPResult([], {}, 0.0, 0.0, 0.0, True, "Empty criteria.")
+        if self.n == 1:
+            return AHPResult(
+                self.criteria, {self.criteria[0]: 1.0}, 1.0, 0.0, 0.0, True, "Single criterion."
+            )
+
+        # 1. Normalize columns
+        col_sums = [sum(self.matrix[row][col] for row in range(self.n)) for col in range(self.n)]
+        norm_matrix = [
+            [self.matrix[row][col] / max(1e-9, col_sums[col]) for col in range(self.n)]
+            for row in range(self.n)
+        ]
+
+        # 2. Row averages (eigenvector weights)
+        weights_list = [sum(norm_matrix[row]) / self.n for row in range(self.n)]
+        weights = {self.criteria[i]: weights_list[i] for i in range(self.n)}
+
+        # 3. Maximum Eigenvalue (lambda_max)
+        weighted_sum_vector = [
+            sum(self.matrix[row][col] * weights_list[col] for col in range(self.n))
+            for row in range(self.n)
+        ]
+        ratios = [weighted_sum_vector[i] / max(1e-9, weights_list[i]) for i in range(self.n)]
+        lambda_max = sum(ratios) / self.n
+
+        # 4. Consistency Index (CI) and Consistency Ratio (CR)
+        ci = (lambda_max - self.n) / max(1, self.n - 1)
+        ri = RANDOM_INDEX.get(self.n, 1.49)
+        cr = (ci / ri) if ri > 0 else 0.0
+
+        is_consistent = cr <= 0.10 or self.n <= 2
+        msg = (
+            f"Consistent (CR = {cr:.3f} <= 0.10)"
+            if is_consistent
+            else f"Inconsistent (CR = {cr:.3f} > 0.10); consider revising pairwise judgements."
+        )
+
+        return AHPResult(
+            criteria=self.criteria,
+            weights=weights,
+            lambda_max=lambda_max,
+            consistency_index=ci,
+            consistency_ratio=cr,
+            is_consistent=is_consistent,
+            status_message=msg,
+        )