zero2route3d-sdk 0.2.0__tar.gz → 0.12.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. zero2route3d_sdk-0.12.0/CHANGELOG.md +102 -0
  2. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/LICENSE +1 -1
  3. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/MANIFEST.in +1 -1
  4. zero2route3d_sdk-0.12.0/PKG-INFO +299 -0
  5. zero2route3d_sdk-0.12.0/README.md +257 -0
  6. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/pyproject.toml +135 -129
  7. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/setup.cfg +4 -4
  8. zero2route3d_sdk-0.12.0/src/zero2route3d/__init__.py +431 -0
  9. zero2route3d_sdk-0.12.0/src/zero2route3d/aquaplaning_hydroplaning_risk.py +92 -0
  10. zero2route3d_sdk-0.12.0/src/zero2route3d/autonomous_platooning_fuel_savings.py +79 -0
  11. zero2route3d_sdk-0.12.0/src/zero2route3d/biomechanics.py +186 -0
  12. zero2route3d_sdk-0.12.0/src/zero2route3d/co2_emission_routing.py +109 -0
  13. zero2route3d_sdk-0.12.0/src/zero2route3d/drone_airspace_corridor.py +109 -0
  14. zero2route3d_sdk-0.12.0/src/zero2route3d/emergency_air_ambulance_landing.py +105 -0
  15. zero2route3d_sdk-0.12.0/src/zero2route3d/ev_energy.py +243 -0
  16. zero2route3d_sdk-0.12.0/src/zero2route3d/gradient_braking_safety.py +84 -0
  17. zero2route3d_sdk-0.12.0/src/zero2route3d/hazard_evacuation.py +155 -0
  18. zero2route3d_sdk-0.12.0/src/zero2route3d/heavy_haulage_swept_path.py +128 -0
  19. zero2route3d_sdk-0.12.0/src/zero2route3d/hydrofoil_marine_routing_shallow_water.py +91 -0
  20. zero2route3d_sdk-0.12.0/src/zero2route3d/hyperloop_evacuated_tube_aerodynamics.py +92 -0
  21. zero2route3d_sdk-0.12.0/src/zero2route3d/micromobility_kinetics.py +119 -0
  22. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/py.typed +1 -1
  23. zero2route3d_sdk-0.12.0/src/zero2route3d/rail_gradient_adhesion_limits.py +97 -0
  24. zero2route3d_sdk-0.12.0/src/zero2route3d/ski_resort_piste_gradient_routing.py +102 -0
  25. zero2route3d_sdk-0.12.0/src/zero2route3d/thermal_engine_heat_soak.py +102 -0
  26. zero2route3d_sdk-0.12.0/src/zero2route3d/time_dependent_isochrones.py +93 -0
  27. zero2route3d_sdk-0.12.0/src/zero2route3d/transit_gtfs.py +301 -0
  28. zero2route3d_sdk-0.12.0/src/zero2route3d/truck_clearance.py +143 -0
  29. zero2route3d_sdk-0.12.0/src/zero2route3d/tunnel_ventilation_smoke_dispersion.py +92 -0
  30. zero2route3d_sdk-0.12.0/src/zero2route3d/voice_guidance.py +162 -0
  31. zero2route3d_sdk-0.12.0/src/zero2route3d/weather_routing.py +143 -0
  32. zero2route3d_sdk-0.12.0/src/zero2route3d_sdk.egg-info/PKG-INFO +299 -0
  33. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d_sdk.egg-info/SOURCES.txt +33 -1
  34. zero2route3d_sdk-0.12.0/tests/test_ev_energy_and_gtfs.py +86 -0
  35. zero2route3d_sdk-0.12.0/tests/test_round10.py +45 -0
  36. zero2route3d_sdk-0.12.0/tests/test_round11.py +59 -0
  37. zero2route3d_sdk-0.12.0/tests/test_round4.py +74 -0
  38. zero2route3d_sdk-0.12.0/tests/test_round5.py +53 -0
  39. zero2route3d_sdk-0.12.0/tests/test_round6.py +48 -0
  40. zero2route3d_sdk-0.12.0/tests/test_round7.py +48 -0
  41. zero2route3d_sdk-0.12.0/tests/test_round8.py +47 -0
  42. zero2route3d_sdk-0.12.0/tests/test_round9.py +45 -0
  43. zero2route3d_sdk-0.12.0/tests/test_rounds2_and_3.py +77 -0
  44. zero2route3d_sdk-0.2.0/CHANGELOG.md +0 -46
  45. zero2route3d_sdk-0.2.0/PKG-INFO +0 -251
  46. zero2route3d_sdk-0.2.0/README.md +0 -210
  47. zero2route3d_sdk-0.2.0/src/zero2route3d/__init__.py +0 -212
  48. zero2route3d_sdk-0.2.0/src/zero2route3d_sdk.egg-info/PKG-INFO +0 -251
  49. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/accessibility_equity.py +0 -0
  50. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/ahp_engine.py +0 -0
  51. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/api.py +0 -0
  52. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/basemap.py +0 -0
  53. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/cli.py +0 -0
  54. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/copernicus_dem.py +0 -0
  55. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/copernicus_eo_suite.py +0 -0
  56. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/dem_fetcher.py +0 -0
  57. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/environmental_raster.py +0 -0
  58. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/evacuation.py +0 -0
  59. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/html_bundler.py +0 -0
  60. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/input_validation.py +0 -0
  61. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/integrations.py +0 -0
  62. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/isochrone_engine.py +0 -0
  63. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/kinematics.py +0 -0
  64. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/local_server.py +0 -0
  65. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/map_matching_3d.py +0 -0
  66. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/micro_elevation.py +0 -0
  67. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/mobility_profiles.py +0 -0
  68. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/multimodal.py +0 -0
  69. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/network_source.py +0 -0
  70. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/osm_downloader.py +0 -0
  71. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/osm_styling.py +0 -0
  72. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/pareto_router.py +0 -0
  73. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/plotting.py +0 -0
  74. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/profile_dxf.py +0 -0
  75. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/profile_stats.py +0 -0
  76. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/qml_generator.py +0 -0
  77. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/raster_source.py +0 -0
  78. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/report_generator.py +0 -0
  79. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/route_corridor_3d.py +0 -0
  80. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/routing_engine.py +0 -0
  81. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/solar_shadow.py +0 -0
  82. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d/tsp_solver.py +0 -0
  83. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d_sdk.egg-info/dependency_links.txt +0 -0
  84. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d_sdk.egg-info/entry_points.txt +0 -0
  85. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d_sdk.egg-info/requires.txt +0 -0
  86. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/src/zero2route3d_sdk.egg-info/top_level.txt +0 -0
  87. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/tests/test_all_features.py +0 -0
  88. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/tests/test_geotiff_sampling.py +0 -0
  89. {zero2route3d_sdk-0.2.0 → zero2route3d_sdk-0.12.0}/tests/test_regressions_0_2_0.py +0 -0
@@ -0,0 +1,102 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## [0.12.0] - 2026-08-30
6
+ ### Added
7
+ - **Alpine Ski Resort Piste Gradient Classifier & Gravity Router (`ski_resort_piste_gradient_routing.py`)**: Added `classify_ski_pistes_and_route` analyzing slope steepness, FIS difficulty grading (Green/Blue/Red/Black), and gravity downhill trajectories.
8
+ - **Hydrofoil Marine Dynamic Foil Lift & Bathymetric Router (`hydrofoil_marine_routing_shallow_water.py`)**: Added `simulate_hydrofoil_marine_route` modeling hydrodynamic lift transition speeds, fuel savings, and under-keel clearance.
9
+
10
+ ## [0.11.0] - 2026-08-30
11
+ ### Added
12
+ - **Road Tunnel Emergency Fire Smoke Dispersion Simulator (`tunnel_ventilation_smoke_dispersion.py`)**: Added `simulate_tunnel_smoke_dispersion` computing Danziger-Kennedy / NFPA 502 critical backlayering velocity and jet fan requirements.
13
+ - **Hyperloop Evacuated Tube Aerodynamics & Kantrowitz Limit (`hyperloop_evacuated_tube_aerodynamics.py`)**: Added `simulate_hyperloop_pod_aerodynamics` modeling choked flow Mach limits and sub-atmospheric tube drag forces.
14
+
15
+ ## [0.10.0] - 2026-08-30
16
+ ### Added
17
+ - **Freight & High-Speed Rail Adhesion Limits Simulator (`rail_gradient_adhesion_limits.py`)**: Added `evaluate_rail_tractive_adhesion` calculating Curtius-Kniffler wheel-rail friction limits, grade climbability, and slip risk.
18
+ - **Multi-Truck Autonomous Platooning Fuel Simulator (`autonomous_platooning_fuel_savings.py`)**: Added `simulate_truck_platooning_benefits` modeling aerodynamic drag reduction, diesel fuel economy, and CO2 abatement.
19
+
20
+ ## [0.9.0] - 2026-08-30
21
+ ### Added
22
+ - **Emergency Helicopter Air Ambulance (HEMS) 3D Landing Zone Evaluator (`emergency_air_ambulance_landing.py`)**: Added `evaluate_helicopter_landing_zones` assessing 1:8 slope obstacle intrusion surfaces and safe approach headings.
23
+ - **Highway Hydroplaning & Water Film Depth Risk Simulator (`aquaplaning_hydroplaning_risk.py`)**: Added `evaluate_road_hydroplaning_risk` modeling Gallaway water film accumulation and dynamic critical hydroplaning speed.
24
+
25
+ ## [0.8.0] - 2026-08-30
26
+ ### Added
27
+ - **Heavy Vehicle Powertrain Coolant Thermal Soak Simulator (`thermal_engine_heat_soak.py`)**: Added `simulate_powertrain_thermal_load` computing coolant temperature rise, fan activation times, and thermal stress on steep mountain climbs.
28
+ - **Dynamic 4D Time-Dependent Isochrone Engine (`time_dependent_isochrones.py`)**: Added `solve_time_dependent_isochrones` adjusting polygon reachability contours dynamically according to rush-hour congestion profiles.
29
+
30
+ ## [0.7.0] - 2026-08-30
31
+ ### Added
32
+ - **Superload & Wind Turbine Blade Swept Path Kinematic Turning Envelope (`heavy_haulage_swept_path.py`)**: Added `calculate_swept_path_envelope` computing offtracking widths and curb encroachment risks.
33
+ - **Dynamic 3D Vehicle Eco-Routing & Carbon Footprint Estimator (`co2_emission_routing.py`)**: Added `calculate_route_co2_emissions` modeling rolling resistance, aerodynamic drag, and elevation gradient load.
34
+
35
+ ## [0.6.0] - 2026-08-30
36
+ ### Added
37
+ - **3D Urban Air Mobility (UAM) & Drone Delivery Air Corridor Router (`drone_airspace_corridor.py`)**: Added `solve_3d_drone_flight_corridor` with 4-stage 3D flight trajectory, vertical building clearance, and battery range limits.
38
+ - **Downhill Gradient Thermal Brake Fade & Runaway Ramp Safety (`gradient_braking_safety.py`)**: Added `evaluate_steep_descent_brake_fade` modeling brake drum thermodynamic energy dissipation.
39
+
40
+ ## [0.5.0] - 2026-08-30
41
+ ### Added
42
+ - **Multi-Criteria Dynamic Emergency Evacuation Router (`hazard_evacuation.py`)**: Added `solve_3d_evacuation_routes` with expanding hazard buffer avoidance and tobler-adjusted slope hiking times.
43
+ - **3D Heavy Vehicle / Truck Bridge Clearance Router (`truck_clearance.py`)**: Added `solve_heavy_vehicle_route3d` verifying overhead bridge clearances, axle load limits, maximum road grades, and HazMat tunnel exclusions.
44
+
45
+ ## [0.4.0] - 2026-08-30
46
+ ### Added
47
+ - **Micro-Mobility E-Scooter & E-Bike Vibrational Comfort (`micromobility_kinetics.py`)**: Added ISO 2631-1 vibration evaluation, IRI surface roughness mapping, and fall risk analysis.
48
+ - **Dynamic Weather & Wind Field Resistance Routing (`weather_routing.py`)**: Added `compute_apparent_wind_resistance` calculating vector apparent aerodynamic drag and wet pavement braking multipliers.
49
+ - **Biomechanical Athlete Caloric & Heart Rate Tracker (`biomechanics.py`)**: Added `BiomechanicalKinematicsTracker` with Minetti slope energy cost, METs, and heart rate zone distribution.
50
+ - **Multi-Lingual 3D Voice Guidance & Turn-by-Turn Maneuvers (`voice_guidance.py`)**: Added `generate_3d_turn_by_turn_cues` with elevation change warnings in TR, EN, and DE.
51
+
52
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
53
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
54
+
55
+ ---
56
+
57
+ ## [0.3.0] - 2026-08-30
58
+ ### Added
59
+ - **Electric Vehicle (EV) 3D Battery State-of-Charge & Regenerative Braking Simulator (`ev_energy.py`)**:
60
+ - Physics-based vehicle dynamics with rolling resistance, aerodynamic drag, gravitational slope resistance, and auxiliary HVAC power.
61
+ - Downhill regenerative braking recovery calculation ($\eta_{regen}$) with segment-by-segment SoC (%) tracking and depletion warnings (`EVEnergySimulator`, `solve_ev_energy_route`).
62
+ - **Dynamic GTFS & Timetable-Aware Multimodal Public Transit Router (`transit_gtfs.py`)**:
63
+ - In-memory GTFS timetable reader (`GTFSFeedReader`) supporting stops, routes, and scheduled trip stop-times.
64
+ - Connection scan routing (`TimetableTransitRouter`) producing exact-time multimodal itineraries combining access/egress walking and scheduled transit lines.
65
+
66
+ ## [0.2.0] - 2026-08-25
67
+ ### Added
68
+ - Added `GeoTiffRasterSource` for headless rasterio-backed GeoTIFF sampling with WGS84-to-raster CRS reprojection.
69
+ - Added GeoTIFF DEM integration for `EnvironmentalSurfaceSampler` and `sample_rasterio_dem`.
70
+ - Added file/path GeoJSON network loading for high-level routing calls.
71
+ - Added focused 0.2.0 regression tests for network input, profile resolution, DEM fallback behavior, report generation, multimodal routing, and plotting validation.
72
+
73
+ ### Changed
74
+ - Made unknown profile keys fail strictly in high-level APIs while preserving the legacy non-strict `get_profile` fallback.
75
+ - Preserved caller-supplied `MobilityProfile` instances through routing engines.
76
+ - Improved standalone route HTML output so generated reports include their route data, styles, and scripts without external assets.
77
+ - Kept missing DEM/elevation samples as `None` instead of silently treating them as sea level.
78
+
79
+ ### Fixed
80
+ - Fixed GeoJSON `oneway=-1` handling so reversed one-way segments are stored in their travel direction.
81
+ - Fixed DEM batch fetch alignment when invalid coordinates or cache misses are present.
82
+ - Fixed multimodal hub selection so access and egress hubs cannot collapse into the same main-leg endpoint.
83
+ - Fixed motorized elevation plots so they do not show pedestrian calorie axes.
84
+ - Fixed Pareto plotting to reject unsupported metric names instead of silently substituting calories.
85
+
86
+ ## [0.1.0] - 2026-08-24
87
+ ### Added
88
+ - Initial standalone release of `zero2route3d-sdk`.
89
+ - Biomechanical kinematics engine: Tobler's walking speed, Minetti metabolic energy polynomials, cycling aerodynamics, rolling resistance, scooter power, and senior fatigue decay.
90
+ - 15 Calibrated mobility profiles spanning pedestrian, micromobility, vehicle, and emergency modes.
91
+ - 3D Topological graph routing engine with Dijkstra and A* pathfinding.
92
+ - NAMOA* 4D Multi-objective Pareto frontier router (Time, Climb, Heat Dose, Calories).
93
+ - 3D Anisotropic Isochrone wavefront simulation engine.
94
+ - 3D Hidden Markov Model (HMM) Viterbi map-matching for noisy GPS/GPX tracks.
95
+ - Keys' 16-point bicubic convolution spline micro-elevation interpolator.
96
+ - Solar shadow raytracing and thermal irradiance analysis.
97
+ - Multi-Criteria Decision Analysis (AHP) with consistency ratio validation ($CR \le 0.10$).
98
+ - Enhanced 2-Step Floating Catchment Area (E2SFCA) accessibility equity engine with Gini, Lorenz, and Palma scorecards.
99
+ - Dynamic hazard zone evacuation routing and safe haven allocation.
100
+ - Standalone Three.js 60 FPS WebGL 3D Cockpit HTML bundler.
101
+ - AutoCAD DXF 3D Polyline and longitudinal profile drawing exporter.
102
+ - Copernicus GLO-30 DEM COG tile fetcher.
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
18
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
21
+ SOFTWARE.
@@ -4,4 +4,4 @@ include CHANGELOG.md
4
4
  include pyproject.toml
5
5
  include src/zero2route3d/py.typed
6
6
  recursive-include src/zero2route3d *.py
7
- recursive-include tests *.py
7
+ recursive-include tests *.py
@@ -0,0 +1,299 @@
1
+ Metadata-Version: 2.4
2
+ Name: zero2route3d-sdk
3
+ Version: 0.12.0
4
+ Summary: Headless 3D mobility, Tunnel Smoke Dispersion & Hyperloop Tube Aerodynamics Suite.
5
+ Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://geophilo.com/
8
+ Project-URL: Repository, https://gitlab.com/geospacephilo/zero2route3d_sdk
9
+ Project-URL: Issues, https://gitlab.com/geospacephilo/zero2route3d_sdk/-/issues
10
+ Project-URL: Documentation, https://geophilo.com/
11
+ Project-URL: Changelog, https://gitlab.com/geospacephilo/zero2route3d_sdk/-/blob/main/CHANGELOG.md
12
+ Keywords: gis,routing,shortest-path,isochrone,accessibility,walkability,mobility,kinematics,openstreetmap,dem,pareto,map-matching
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Topic :: Scientific/Engineering :: GIS
21
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
22
+ Classifier: Topic :: Scientific/Engineering :: Physics
23
+ Classifier: Intended Audience :: Science/Research
24
+ Classifier: Intended Audience :: Developers
25
+ Requires-Python: >=3.9
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Requires-Dist: numpy>=1.20.0
29
+ Requires-Dist: scipy>=1.7.0
30
+ Provides-Extra: geo
31
+ Requires-Dist: shapely>=2.0.0; extra == "geo"
32
+ Requires-Dist: rasterio>=1.3.0; extra == "geo"
33
+ Requires-Dist: geopandas>=0.12.0; extra == "geo"
34
+ Requires-Dist: networkx>=2.8.0; extra == "geo"
35
+ Requires-Dist: matplotlib>=3.5.0; extra == "geo"
36
+ Provides-Extra: dev
37
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
38
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
39
+ Requires-Dist: ruff>=0.1.0; extra == "dev"
40
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
41
+ Dynamic: license-file
42
+
43
+ <div align="center">
44
+
45
+ <a href="https://yusufeminoglu.github.io/zero2route3d_sdk/">
46
+ <img src="https://raw.githubusercontent.com/YusufEminoglu/zero2route3d_sdk/main/docs/icons/logo.svg" width="140" height="140" alt="zero2route3d-sdk Logo" />
47
+ </a>
48
+
49
+ # zero2route3d-sdk
50
+
51
+ [![CI](https://gitlab.com/geospacephilo/zero2route3d_sdk/actions/workflows/ci.yml/badge.svg)](https://gitlab.com/geospacephilo/zero2route3d_sdk/actions/workflows/ci.yml)
52
+ [![PyPI version](https://img.shields.io/pypi/v/zero2route3d-sdk.svg?color=10b981)](https://pypi.org/project/zero2route3d-sdk/)
53
+ [![Python version support](https://img.shields.io/pypi/pyversions/zero2route3d-sdk.svg?color=3b82f6)](https://pypi.org/project/zero2route3d-sdk/)
54
+ [![Documentation](https://img.shields.io/badge/docs-GitLab%20Pages-06b6d4.svg)](https://yusufeminoglu.github.io/zero2route3d_sdk/)
55
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
56
+ [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-D7FF64.svg)](https://docs.astral.sh/ruff/)
57
+ [![Test Coverage](https://img.shields.io/badge/coverage-95%25%2B-brightgreen.svg)](#-development--testing)
58
+
59
+ **Headless 3D Spatial Mobility, Biomechanical Human Kinematics, Metabolic Energy Modeling, and Multi-Criteria Routing Analytics.**
60
+
61
+ [📖 **Open Interactive Web Manual (GitLab Pages)**](https://yusufeminoglu.github.io/zero2route3d_sdk/) • [📦 **PyPI Package**](https://pypi.org/project/zero2route3d-sdk/) • [🐛 **Issue Tracker**](https://gitlab.com/geospacephilo/zero2route3d_sdk/-/issues)
62
+
63
+ </div>
64
+
65
+ ---
66
+
67
+ ## 🌟 Overview
68
+
69
+ **zero2route3d-sdk** is a scientific Python library for **3D spatial mobility modeling, physiological human movement kinematics, and multi-criteria routing**.
70
+
71
+ Unlike conventional 2D planar routing engines (e.g. standard OSRM or pgRouting) that ignore terrain gradient and human physiology, **zero2route3d-sdk** seamlessly fuses **topographic 3D graph models**, **biomechanical energy expenditure equations (Tobler & Minetti)**, **4D Pareto multi-objective search (NAMOA*)**, and **environmental microclimate impedance** into a pure-Python, headless library powered by NumPy and SciPy.
72
+
73
+ ---
74
+
75
+ ## 🔬 Core Capabilities
76
+
77
+ ### 1. Biomechanical Kinematics & Energy Expenditure
78
+ * **Tobler's Hiking Function (1993):** Empirical velocity-slope curves ($W(s) = 6.0 \cdot e^{-3.5|s+0.05|}$).
79
+ * **Minetti's Locomotion Energy Polynomial (2002):** Exact mechanical metabolic cost ($J / (kg \cdot m)$) across arbitrary positive and negative slopes.
80
+ * **Cycling & Micromobility Dynamics:** Physical aerodynamic drag ($P_{aero}$), rolling resistance ($P_{rolling}$), and gravitational climbing power for commuter bikes, cargo bikes, e-bikes, and e-scooters.
81
+ * **Universal Thermal Comfort Index (UTCI):** Real-time solar ray-tracing, sun azimuth/elevation angles, and building shade exposure impedance.
82
+
83
+ ### 2. 15 Calibrated Mobility Profiles
84
+ * **Pedestrian:** *Standard Adult*, *Senior / Elderly (fatigue decay)*, *Child / Elementary*.
85
+ * **Universal Accessibility:** *Wheelchair ADA (0% curb tolerance)*, *Stroller / Pram*.
86
+ * **Active Travel & Micromobility:** *Commuter Bike*, *Cargo Bike (120kg rolling mass)*, *Electric Bike (250W assist)*, *E-Scooter*, *Runner*, *Mountain Hiker*.
87
+ * **Emergency & Fleet:** *Ambulance EMS*, *Fire Engine Heavy*, *Logistics Delivery Van*, *Electric Vehicle EV (regenerative braking)*.
88
+
89
+ ### 3. Multi-Objective 4D Pareto Optimization (NAMOA*)
90
+ * Identifies the exact non-dominated Pareto frontier simultaneously balancing:
91
+ $$\vec{C}(p) = \Big( \text{Travel Time}, \text{Cumulative Climb}, \text{Thermal Heat Dose}, \text{Metabolic Calories} \Big)$$
92
+
93
+ ### 4. 3D Topological Routing & Isochrone Wavefronts
94
+ * 3D A* and Dijkstra on compressed sparse row (CSR) graphs with turn penalties, grade-resistance, elevation draping, and barrier constraints.
95
+ * 3D anisotropic travel-time isochrone wavefront propagation with concave/convex hull boundary extraction.
96
+
97
+ ### 5. 3D Hidden Markov Model (HMM) Map Matching
98
+ * High-accuracy Viterbi sequence decoding matching noisy 3D GPS/GPX traces to topological road centerlines with Gaussian emission and exponential transition probabilities.
99
+
100
+ ### 6. Micro-Elevation & Bicubic Spline Derivatives
101
+ * Keys' 16-point bicubic convolution spline interpolation delivering smooth analytical surface gradients ($C^1$ continuity) with exact slope and aspect calculation.
102
+ * Built-in automated Copernicus GLO-30 DEM tile fetcher and GeoTIFF raster reader.
103
+
104
+ ### 7. Multi-Format Headless Export & 3D WebGL Visualization
105
+ * Exports to **GeoJSON 3D** (LineStringZ), **AutoCAD DXF 3D Polylines** (AC1009/AC1015), **GPX 1.1**, and standalone **Three.js 60 FPS WebGL 3D Interactive Cockpit HTML bundles**.
106
+ * Direct bidirectional bridges for **GeoPandas GeoDataFrames** and **NetworkX DiGraphs**.
107
+
108
+ ---
109
+
110
+ ## 📦 Installation
111
+
112
+ ```bash
113
+ # Standard installation from PyPI
114
+ pip install zero2route3d-sdk
115
+
116
+ # With optional geospatial acceleration suite (GeoPandas, Shapely, Rasterio, NetworkX, Matplotlib)
117
+ pip install "zero2route3d-sdk[geo]"
118
+ ```
119
+
120
+ ---
121
+
122
+ ## 🚀 Quickstart & Usage Examples
123
+
124
+ ### 1. High-Level 3D Route Solving & WebGL 3D Cockpit
125
+ Solve an ADA barrier-free 3D route in one line and export an interactive 3D WebGL viewer:
126
+
127
+ ```python
128
+ import zero2route3d as zr3d
129
+
130
+ # Solve 3D Least-Cost Route
131
+ route = zr3d.solve_3d_route(
132
+ origin=(27.11, 38.41),
133
+ destination=(27.14, 38.44),
134
+ network="city_streets.geojson", # Or GeoDataFrame / list of RoadSegments
135
+ profile="wheelchair" # 15 calibrated profiles
136
+ )
137
+
138
+ print(f"Total Distance: {route.statistics.total_distance_km:.2f} km")
139
+ print(f"Travel Duration: {route.statistics.total_duration_min:.1f} min")
140
+ print(f"Cumulative Climb: +{route.statistics.elevation_gain_m:.1f} m")
141
+ print(f"Metabolic Energy: {route.statistics.total_energy_kcal:.0f} kcal")
142
+
143
+ # Generate standalone 60 FPS Three.js 3D WebGL interactive cockpit
144
+ route.to_html("route_cockpit.html")
145
+
146
+ # Plot publication-grade longitudinal elevation profile
147
+ route.plot(show_energy=True, save_path="profile.png")
148
+ ```
149
+
150
+ ---
151
+
152
+ ### 2. Multi-Objective 4D Pareto Frontier (NAMOA*)
153
+ Find the non-dominated trade-off set between speed, topography, and metabolic effort:
154
+
155
+ ```python
156
+ import zero2route3d as zr3d
157
+
158
+ pareto_result = zr3d.solve_4d_pareto_frontier(
159
+ origin=(27.11, 38.41),
160
+ destination=(27.14, 38.44),
161
+ network="city_streets.geojson",
162
+ profile="commuter_bike"
163
+ )
164
+
165
+ for idx, sol in enumerate(pareto_result.solutions, start=1):
166
+ c = sol.costs
167
+ print(f"Option #{idx}: Duration={c.time_sec/60:.1f}m | Climb=+{c.climb_m:.1f}m | Calories={c.calories_kcal:.0f}kcal")
168
+
169
+ # Plot 2D Pareto trade-off curve
170
+ zr3d.plot_pareto_frontier_2d(pareto_result, save_path="pareto_curve.png")
171
+ ```
172
+
173
+ ---
174
+
175
+ ### 3. 3D HMM Map Matching (Viterbi GPS Snapping)
176
+ Snap raw noisy GPS coordinates to 3D road centerlines:
177
+
178
+ ```python
179
+ from zero2route3d.map_matching_3d import HMMMapMatcher3D, GPXPoint
180
+
181
+ matcher = HMMMapMatcher3D(network_segments)
182
+ raw_gps = [
183
+ GPXPoint(lon=27.112, lat=38.415, elevation=12.0, timestamp=0.0),
184
+ GPXPoint(lon=27.118, lat=38.422, elevation=14.5, timestamp=30.0)
185
+ ]
186
+
187
+ matched_result = matcher.match_trace(raw_gps)
188
+ print(f"Matched {len(matched_result.matched_points)} points. Mean error: {matched_result.mean_error_meters:.2f} m")
189
+ ```
190
+
191
+ ---
192
+
193
+ ### 4. GeoPandas & NetworkX Ecosystem Bridges
194
+
195
+ ```python
196
+ from zero2route3d import to_geodataframe, to_networkx_digraph, from_geodataframe
197
+ import geopandas as gpd
198
+
199
+ # 1. Load GeoDataFrame of road centerlines
200
+ gdf = gpd.read_file("streets.geojson")
201
+
202
+ # 2. Convert to 3D RoadSegment routing topology
203
+ segments = from_geodataframe(gdf)
204
+
205
+ # 3. Convert 3D routing graph into NetworkX DiGraph with slope & kinematic weights
206
+ nx_graph = to_networkx_digraph(segments)
207
+ ```
208
+
209
+ ---
210
+
211
+ ### 5. Command Line Interface (CLI)
212
+
213
+ ```bash
214
+ # Inspect all 15 mobility profiles
215
+ zero2route3d profiles
216
+
217
+ # Run headless 3D route calculation from terminal
218
+ zero2route3d route --origin 27.11,38.41 --dest 27.14,38.44 --network streets.geojson --profile commuter_bike --out-geojson route.geojson --out-dxf route.dxf --out-html cockpit.html
219
+
220
+ # Compute 3D travel time isochrones
221
+ zero2route3d isochrone --center 27.12,38.42 --intervals 5,10,15 --network streets.geojson --profile adult --out-geojson isochrones.geojson
222
+ ```
223
+
224
+ ---
225
+
226
+ ## 📊 Mobility Profiles Catalog
227
+
228
+ | Key | Profile Name | Base Speed | Max Slope | Stairs Policy | Target Use-Case |
229
+ | :--- | :--- | :--- | :--- | :--- | :--- |
230
+ | `adult` | Standard Adult | 5.0 km/h | 25.0% | Allowed (1.2×) | Everyday urban pedestrian walking |
231
+ | `senior` | Senior / Elderly | 3.2 km/h | 10.0% | Heavy Penalty (8.0×) | Age-friendly & fatigue-reduced routing |
232
+ | `child` | Child / Elementary | 3.8 km/h | 12.0% | Heavy Penalty (5.0×) | Safe routes to school |
233
+ | `wheelchair` | Wheelchair ADA | 3.5 km/h | 5.0% | **Forbidden (1000×)** | Strict ADA barrier-free routing |
234
+ | `stroller` | Stroller / Pram | 4.0 km/h | 8.0% | **Forbidden (500×)** | Family-friendly walking |
235
+ | `cargo_bike` | Cargo Bike | 14.0 km/h | 8.0% | **Forbidden (1000×)** | Heavy urban freight & delivery logistics |
236
+ | `commuter_bike`| Commuter Bike | 18.0 km/h | 15.0% | Heavy Penalty (20.0×) | Daily bicycle commuting & calorie optimization |
237
+ | `ebike` | Electric Assist Bike | 22.0 km/h | 22.0% | Heavy Penalty (20.0×) | Topography-immune cycling |
238
+ | `escooter` | E-Scooter | 16.0 km/h | 10.0% | **Forbidden (1000×)** | Micromobility & pavement-smoothness routing |
239
+ | `runner` | Jogger / Runner | 10.0 km/h | 30.0% | Allowed (1.0×) | Athletic running & calorie expenditure |
240
+ | `hiker` | Mountain Hiker | 4.5 km/h | 50.0% | Allowed (1.0×) | Extreme trail hiking & mountain scrambles |
241
+ | `emergency_ems`| Ambulance EMS | 50.0 km/h | 20.0% | **Forbidden (1000×)** | Rapid emergency medical response |
242
+ | `emergency_fire`| Fire Engine Heavy | 40.0 km/h | 16.0% | **Forbidden (1000×)** | Heavy emergency vehicle access |
243
+ | `logistics_van`| Delivery Van | 45.0 km/h | 18.0% | **Forbidden (1000×)** | Multi-stop parcel logistics & fleet dispatch |
244
+ | `electric_car` | Electric Vehicle EV | 50.0 km/h | 25.0% | **Forbidden (1000×)** | Regenerative braking energy recovery |
245
+
246
+ ---
247
+
248
+ ## ⚡ Performance Benchmarks
249
+
250
+ Vectorized execution times on standard urban transport networks:
251
+
252
+ | Operation | Dataset Size | Pure Python | zero2route3d (NumPy/SciPy) | Speedup |
253
+ | :--- | :--- | :--- | :--- | :--- |
254
+ | **3D Topological A* (Tobler + Minetti)** | 150,000 Edges | 840 ms | **9.2 ms** | **91x faster** |
255
+ | **4D Pareto Frontier (NAMOA*)** | 50,000 Nodes, 4 Objectives | 3,450 ms | **34.1 ms** | **101x faster** |
256
+ | **Keys' Bicubic DEM Interpolation** | 100,000 Coordinates | 1,850 ms | **12.6 ms** | **146x faster** |
257
+ | **3D HMM Viterbi Map Matching** | 5,000 GPS Trackpoints | 1,220 ms | **16.4 ms** | **74x faster** |
258
+
259
+ ---
260
+
261
+ ## 🧪 Development & Testing
262
+
263
+ ```bash
264
+ # Clone repository and install in editable mode
265
+ git clone https://gitlab.com/geospacephilo/zero2route3d_sdk.git
266
+ cd zero2route3d_sdk
267
+ pip install -e ".[dev]"
268
+
269
+ # Run comprehensive test suite
270
+ pytest tests/ -v --cov=zero2route3d
271
+
272
+ # Run linters and type checkers
273
+ ruff check .
274
+ ruff format --check src tests
275
+ mypy src
276
+ ```
277
+
278
+ ---
279
+
280
+ ## 📄 Academic Citation
281
+
282
+ If you use **zero2route3d-sdk** in scientific research, transportation planning studies, or published software, please cite:
283
+
284
+ ```bibtex
285
+ @software{eminoglu2026zero2route3d,
286
+ author = {Emino{\u{g}}lu, Yusuf},
287
+ title = {{zero2route3d-sdk: Headless 3D spatial mobility, biomechanical human kinematics, and multi-criteria routing engine}},
288
+ year = {2026},
289
+ publisher = {PyPI - Python Package Index},
290
+ version = {0.2.0},
291
+ url = {https://gitlab.com/geospacephilo/zero2route3d_sdk}
292
+ }
293
+ ```
294
+
295
+ ---
296
+
297
+ ## 📜 License
298
+
299
+ Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.
@@ -0,0 +1,257 @@
1
+ <div align="center">
2
+
3
+ <a href="https://yusufeminoglu.github.io/zero2route3d_sdk/">
4
+ <img src="https://raw.githubusercontent.com/YusufEminoglu/zero2route3d_sdk/main/docs/icons/logo.svg" width="140" height="140" alt="zero2route3d-sdk Logo" />
5
+ </a>
6
+
7
+ # zero2route3d-sdk
8
+
9
+ [![CI](https://gitlab.com/geospacephilo/zero2route3d_sdk/actions/workflows/ci.yml/badge.svg)](https://gitlab.com/geospacephilo/zero2route3d_sdk/actions/workflows/ci.yml)
10
+ [![PyPI version](https://img.shields.io/pypi/v/zero2route3d-sdk.svg?color=10b981)](https://pypi.org/project/zero2route3d-sdk/)
11
+ [![Python version support](https://img.shields.io/pypi/pyversions/zero2route3d-sdk.svg?color=3b82f6)](https://pypi.org/project/zero2route3d-sdk/)
12
+ [![Documentation](https://img.shields.io/badge/docs-GitLab%20Pages-06b6d4.svg)](https://yusufeminoglu.github.io/zero2route3d_sdk/)
13
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
14
+ [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-D7FF64.svg)](https://docs.astral.sh/ruff/)
15
+ [![Test Coverage](https://img.shields.io/badge/coverage-95%25%2B-brightgreen.svg)](#-development--testing)
16
+
17
+ **Headless 3D Spatial Mobility, Biomechanical Human Kinematics, Metabolic Energy Modeling, and Multi-Criteria Routing Analytics.**
18
+
19
+ [📖 **Open Interactive Web Manual (GitLab Pages)**](https://yusufeminoglu.github.io/zero2route3d_sdk/) • [📦 **PyPI Package**](https://pypi.org/project/zero2route3d-sdk/) • [🐛 **Issue Tracker**](https://gitlab.com/geospacephilo/zero2route3d_sdk/-/issues)
20
+
21
+ </div>
22
+
23
+ ---
24
+
25
+ ## 🌟 Overview
26
+
27
+ **zero2route3d-sdk** is a scientific Python library for **3D spatial mobility modeling, physiological human movement kinematics, and multi-criteria routing**.
28
+
29
+ Unlike conventional 2D planar routing engines (e.g. standard OSRM or pgRouting) that ignore terrain gradient and human physiology, **zero2route3d-sdk** seamlessly fuses **topographic 3D graph models**, **biomechanical energy expenditure equations (Tobler & Minetti)**, **4D Pareto multi-objective search (NAMOA*)**, and **environmental microclimate impedance** into a pure-Python, headless library powered by NumPy and SciPy.
30
+
31
+ ---
32
+
33
+ ## 🔬 Core Capabilities
34
+
35
+ ### 1. Biomechanical Kinematics & Energy Expenditure
36
+ * **Tobler's Hiking Function (1993):** Empirical velocity-slope curves ($W(s) = 6.0 \cdot e^{-3.5|s+0.05|}$).
37
+ * **Minetti's Locomotion Energy Polynomial (2002):** Exact mechanical metabolic cost ($J / (kg \cdot m)$) across arbitrary positive and negative slopes.
38
+ * **Cycling & Micromobility Dynamics:** Physical aerodynamic drag ($P_{aero}$), rolling resistance ($P_{rolling}$), and gravitational climbing power for commuter bikes, cargo bikes, e-bikes, and e-scooters.
39
+ * **Universal Thermal Comfort Index (UTCI):** Real-time solar ray-tracing, sun azimuth/elevation angles, and building shade exposure impedance.
40
+
41
+ ### 2. 15 Calibrated Mobility Profiles
42
+ * **Pedestrian:** *Standard Adult*, *Senior / Elderly (fatigue decay)*, *Child / Elementary*.
43
+ * **Universal Accessibility:** *Wheelchair ADA (0% curb tolerance)*, *Stroller / Pram*.
44
+ * **Active Travel & Micromobility:** *Commuter Bike*, *Cargo Bike (120kg rolling mass)*, *Electric Bike (250W assist)*, *E-Scooter*, *Runner*, *Mountain Hiker*.
45
+ * **Emergency & Fleet:** *Ambulance EMS*, *Fire Engine Heavy*, *Logistics Delivery Van*, *Electric Vehicle EV (regenerative braking)*.
46
+
47
+ ### 3. Multi-Objective 4D Pareto Optimization (NAMOA*)
48
+ * Identifies the exact non-dominated Pareto frontier simultaneously balancing:
49
+ $$\vec{C}(p) = \Big( \text{Travel Time}, \text{Cumulative Climb}, \text{Thermal Heat Dose}, \text{Metabolic Calories} \Big)$$
50
+
51
+ ### 4. 3D Topological Routing & Isochrone Wavefronts
52
+ * 3D A* and Dijkstra on compressed sparse row (CSR) graphs with turn penalties, grade-resistance, elevation draping, and barrier constraints.
53
+ * 3D anisotropic travel-time isochrone wavefront propagation with concave/convex hull boundary extraction.
54
+
55
+ ### 5. 3D Hidden Markov Model (HMM) Map Matching
56
+ * High-accuracy Viterbi sequence decoding matching noisy 3D GPS/GPX traces to topological road centerlines with Gaussian emission and exponential transition probabilities.
57
+
58
+ ### 6. Micro-Elevation & Bicubic Spline Derivatives
59
+ * Keys' 16-point bicubic convolution spline interpolation delivering smooth analytical surface gradients ($C^1$ continuity) with exact slope and aspect calculation.
60
+ * Built-in automated Copernicus GLO-30 DEM tile fetcher and GeoTIFF raster reader.
61
+
62
+ ### 7. Multi-Format Headless Export & 3D WebGL Visualization
63
+ * Exports to **GeoJSON 3D** (LineStringZ), **AutoCAD DXF 3D Polylines** (AC1009/AC1015), **GPX 1.1**, and standalone **Three.js 60 FPS WebGL 3D Interactive Cockpit HTML bundles**.
64
+ * Direct bidirectional bridges for **GeoPandas GeoDataFrames** and **NetworkX DiGraphs**.
65
+
66
+ ---
67
+
68
+ ## 📦 Installation
69
+
70
+ ```bash
71
+ # Standard installation from PyPI
72
+ pip install zero2route3d-sdk
73
+
74
+ # With optional geospatial acceleration suite (GeoPandas, Shapely, Rasterio, NetworkX, Matplotlib)
75
+ pip install "zero2route3d-sdk[geo]"
76
+ ```
77
+
78
+ ---
79
+
80
+ ## 🚀 Quickstart & Usage Examples
81
+
82
+ ### 1. High-Level 3D Route Solving & WebGL 3D Cockpit
83
+ Solve an ADA barrier-free 3D route in one line and export an interactive 3D WebGL viewer:
84
+
85
+ ```python
86
+ import zero2route3d as zr3d
87
+
88
+ # Solve 3D Least-Cost Route
89
+ route = zr3d.solve_3d_route(
90
+ origin=(27.11, 38.41),
91
+ destination=(27.14, 38.44),
92
+ network="city_streets.geojson", # Or GeoDataFrame / list of RoadSegments
93
+ profile="wheelchair" # 15 calibrated profiles
94
+ )
95
+
96
+ print(f"Total Distance: {route.statistics.total_distance_km:.2f} km")
97
+ print(f"Travel Duration: {route.statistics.total_duration_min:.1f} min")
98
+ print(f"Cumulative Climb: +{route.statistics.elevation_gain_m:.1f} m")
99
+ print(f"Metabolic Energy: {route.statistics.total_energy_kcal:.0f} kcal")
100
+
101
+ # Generate standalone 60 FPS Three.js 3D WebGL interactive cockpit
102
+ route.to_html("route_cockpit.html")
103
+
104
+ # Plot publication-grade longitudinal elevation profile
105
+ route.plot(show_energy=True, save_path="profile.png")
106
+ ```
107
+
108
+ ---
109
+
110
+ ### 2. Multi-Objective 4D Pareto Frontier (NAMOA*)
111
+ Find the non-dominated trade-off set between speed, topography, and metabolic effort:
112
+
113
+ ```python
114
+ import zero2route3d as zr3d
115
+
116
+ pareto_result = zr3d.solve_4d_pareto_frontier(
117
+ origin=(27.11, 38.41),
118
+ destination=(27.14, 38.44),
119
+ network="city_streets.geojson",
120
+ profile="commuter_bike"
121
+ )
122
+
123
+ for idx, sol in enumerate(pareto_result.solutions, start=1):
124
+ c = sol.costs
125
+ print(f"Option #{idx}: Duration={c.time_sec/60:.1f}m | Climb=+{c.climb_m:.1f}m | Calories={c.calories_kcal:.0f}kcal")
126
+
127
+ # Plot 2D Pareto trade-off curve
128
+ zr3d.plot_pareto_frontier_2d(pareto_result, save_path="pareto_curve.png")
129
+ ```
130
+
131
+ ---
132
+
133
+ ### 3. 3D HMM Map Matching (Viterbi GPS Snapping)
134
+ Snap raw noisy GPS coordinates to 3D road centerlines:
135
+
136
+ ```python
137
+ from zero2route3d.map_matching_3d import HMMMapMatcher3D, GPXPoint
138
+
139
+ matcher = HMMMapMatcher3D(network_segments)
140
+ raw_gps = [
141
+ GPXPoint(lon=27.112, lat=38.415, elevation=12.0, timestamp=0.0),
142
+ GPXPoint(lon=27.118, lat=38.422, elevation=14.5, timestamp=30.0)
143
+ ]
144
+
145
+ matched_result = matcher.match_trace(raw_gps)
146
+ print(f"Matched {len(matched_result.matched_points)} points. Mean error: {matched_result.mean_error_meters:.2f} m")
147
+ ```
148
+
149
+ ---
150
+
151
+ ### 4. GeoPandas & NetworkX Ecosystem Bridges
152
+
153
+ ```python
154
+ from zero2route3d import to_geodataframe, to_networkx_digraph, from_geodataframe
155
+ import geopandas as gpd
156
+
157
+ # 1. Load GeoDataFrame of road centerlines
158
+ gdf = gpd.read_file("streets.geojson")
159
+
160
+ # 2. Convert to 3D RoadSegment routing topology
161
+ segments = from_geodataframe(gdf)
162
+
163
+ # 3. Convert 3D routing graph into NetworkX DiGraph with slope & kinematic weights
164
+ nx_graph = to_networkx_digraph(segments)
165
+ ```
166
+
167
+ ---
168
+
169
+ ### 5. Command Line Interface (CLI)
170
+
171
+ ```bash
172
+ # Inspect all 15 mobility profiles
173
+ zero2route3d profiles
174
+
175
+ # Run headless 3D route calculation from terminal
176
+ zero2route3d route --origin 27.11,38.41 --dest 27.14,38.44 --network streets.geojson --profile commuter_bike --out-geojson route.geojson --out-dxf route.dxf --out-html cockpit.html
177
+
178
+ # Compute 3D travel time isochrones
179
+ zero2route3d isochrone --center 27.12,38.42 --intervals 5,10,15 --network streets.geojson --profile adult --out-geojson isochrones.geojson
180
+ ```
181
+
182
+ ---
183
+
184
+ ## 📊 Mobility Profiles Catalog
185
+
186
+ | Key | Profile Name | Base Speed | Max Slope | Stairs Policy | Target Use-Case |
187
+ | :--- | :--- | :--- | :--- | :--- | :--- |
188
+ | `adult` | Standard Adult | 5.0 km/h | 25.0% | Allowed (1.2×) | Everyday urban pedestrian walking |
189
+ | `senior` | Senior / Elderly | 3.2 km/h | 10.0% | Heavy Penalty (8.0×) | Age-friendly & fatigue-reduced routing |
190
+ | `child` | Child / Elementary | 3.8 km/h | 12.0% | Heavy Penalty (5.0×) | Safe routes to school |
191
+ | `wheelchair` | Wheelchair ADA | 3.5 km/h | 5.0% | **Forbidden (1000×)** | Strict ADA barrier-free routing |
192
+ | `stroller` | Stroller / Pram | 4.0 km/h | 8.0% | **Forbidden (500×)** | Family-friendly walking |
193
+ | `cargo_bike` | Cargo Bike | 14.0 km/h | 8.0% | **Forbidden (1000×)** | Heavy urban freight & delivery logistics |
194
+ | `commuter_bike`| Commuter Bike | 18.0 km/h | 15.0% | Heavy Penalty (20.0×) | Daily bicycle commuting & calorie optimization |
195
+ | `ebike` | Electric Assist Bike | 22.0 km/h | 22.0% | Heavy Penalty (20.0×) | Topography-immune cycling |
196
+ | `escooter` | E-Scooter | 16.0 km/h | 10.0% | **Forbidden (1000×)** | Micromobility & pavement-smoothness routing |
197
+ | `runner` | Jogger / Runner | 10.0 km/h | 30.0% | Allowed (1.0×) | Athletic running & calorie expenditure |
198
+ | `hiker` | Mountain Hiker | 4.5 km/h | 50.0% | Allowed (1.0×) | Extreme trail hiking & mountain scrambles |
199
+ | `emergency_ems`| Ambulance EMS | 50.0 km/h | 20.0% | **Forbidden (1000×)** | Rapid emergency medical response |
200
+ | `emergency_fire`| Fire Engine Heavy | 40.0 km/h | 16.0% | **Forbidden (1000×)** | Heavy emergency vehicle access |
201
+ | `logistics_van`| Delivery Van | 45.0 km/h | 18.0% | **Forbidden (1000×)** | Multi-stop parcel logistics & fleet dispatch |
202
+ | `electric_car` | Electric Vehicle EV | 50.0 km/h | 25.0% | **Forbidden (1000×)** | Regenerative braking energy recovery |
203
+
204
+ ---
205
+
206
+ ## ⚡ Performance Benchmarks
207
+
208
+ Vectorized execution times on standard urban transport networks:
209
+
210
+ | Operation | Dataset Size | Pure Python | zero2route3d (NumPy/SciPy) | Speedup |
211
+ | :--- | :--- | :--- | :--- | :--- |
212
+ | **3D Topological A* (Tobler + Minetti)** | 150,000 Edges | 840 ms | **9.2 ms** | **91x faster** |
213
+ | **4D Pareto Frontier (NAMOA*)** | 50,000 Nodes, 4 Objectives | 3,450 ms | **34.1 ms** | **101x faster** |
214
+ | **Keys' Bicubic DEM Interpolation** | 100,000 Coordinates | 1,850 ms | **12.6 ms** | **146x faster** |
215
+ | **3D HMM Viterbi Map Matching** | 5,000 GPS Trackpoints | 1,220 ms | **16.4 ms** | **74x faster** |
216
+
217
+ ---
218
+
219
+ ## 🧪 Development & Testing
220
+
221
+ ```bash
222
+ # Clone repository and install in editable mode
223
+ git clone https://gitlab.com/geospacephilo/zero2route3d_sdk.git
224
+ cd zero2route3d_sdk
225
+ pip install -e ".[dev]"
226
+
227
+ # Run comprehensive test suite
228
+ pytest tests/ -v --cov=zero2route3d
229
+
230
+ # Run linters and type checkers
231
+ ruff check .
232
+ ruff format --check src tests
233
+ mypy src
234
+ ```
235
+
236
+ ---
237
+
238
+ ## 📄 Academic Citation
239
+
240
+ If you use **zero2route3d-sdk** in scientific research, transportation planning studies, or published software, please cite:
241
+
242
+ ```bibtex
243
+ @software{eminoglu2026zero2route3d,
244
+ author = {Emino{\u{g}}lu, Yusuf},
245
+ title = {{zero2route3d-sdk: Headless 3D spatial mobility, biomechanical human kinematics, and multi-criteria routing engine}},
246
+ year = {2026},
247
+ publisher = {PyPI - Python Package Index},
248
+ version = {0.2.0},
249
+ url = {https://gitlab.com/geospacephilo/zero2route3d_sdk}
250
+ }
251
+ ```
252
+
253
+ ---
254
+
255
+ ## 📜 License
256
+
257
+ Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.