zero2route3d-sdk 0.2.0__py3-none-any.whl
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.
- zero2route3d/__init__.py +212 -0
- zero2route3d/accessibility_equity.py +214 -0
- zero2route3d/ahp_engine.py +117 -0
- zero2route3d/api.py +244 -0
- zero2route3d/basemap.py +44 -0
- zero2route3d/cli.py +251 -0
- zero2route3d/copernicus_dem.py +76 -0
- zero2route3d/copernicus_eo_suite.py +443 -0
- zero2route3d/dem_fetcher.py +223 -0
- zero2route3d/environmental_raster.py +411 -0
- zero2route3d/evacuation.py +121 -0
- zero2route3d/html_bundler.py +603 -0
- zero2route3d/input_validation.py +100 -0
- zero2route3d/integrations.py +260 -0
- zero2route3d/isochrone_engine.py +220 -0
- zero2route3d/kinematics.py +383 -0
- zero2route3d/local_server.py +116 -0
- zero2route3d/map_matching_3d.py +374 -0
- zero2route3d/micro_elevation.py +264 -0
- zero2route3d/mobility_profiles.py +517 -0
- zero2route3d/multimodal.py +172 -0
- zero2route3d/network_source.py +512 -0
- zero2route3d/osm_downloader.py +328 -0
- zero2route3d/osm_styling.py +351 -0
- zero2route3d/pareto_router.py +331 -0
- zero2route3d/plotting.py +292 -0
- zero2route3d/profile_dxf.py +231 -0
- zero2route3d/profile_stats.py +648 -0
- zero2route3d/py.typed +1 -0
- zero2route3d/qml_generator.py +189 -0
- zero2route3d/raster_source.py +206 -0
- zero2route3d/report_generator.py +154 -0
- zero2route3d/route_corridor_3d.py +479 -0
- zero2route3d/routing_engine.py +747 -0
- zero2route3d/solar_shadow.py +157 -0
- zero2route3d/tsp_solver.py +78 -0
- zero2route3d_sdk-0.2.0.dist-info/METADATA +251 -0
- zero2route3d_sdk-0.2.0.dist-info/RECORD +42 -0
- zero2route3d_sdk-0.2.0.dist-info/WHEEL +5 -0
- zero2route3d_sdk-0.2.0.dist-info/entry_points.txt +2 -0
- zero2route3d_sdk-0.2.0.dist-info/licenses/LICENSE +21 -0
- zero2route3d_sdk-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
"""Solar position, dynamic shadow casting, and shade exposure along 3D route."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import math
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from typing import Any, Dict, Sequence, Tuple
|
|
8
|
+
|
|
9
|
+
from .kinematics import haversine_distance_2d
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
@dataclass
|
|
13
|
+
class SolarPosition:
|
|
14
|
+
"""Calculated solar azimuth and elevation angles."""
|
|
15
|
+
|
|
16
|
+
solar_hour: float # 0.0 to 24.0 (e.g. 14.5 = 14:30)
|
|
17
|
+
azimuth_deg: float # 0=North, 90=East, 180=South, 270=West
|
|
18
|
+
elevation_deg: float # 0=Horizon, 90=Zenith
|
|
19
|
+
direct_irradiance_w_m2: float
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass
|
|
23
|
+
class ShadeExposureReport:
|
|
24
|
+
"""Detailed solar exposure metrics along a 3D path."""
|
|
25
|
+
|
|
26
|
+
solar_position: SolarPosition
|
|
27
|
+
direct_sun_pct: float
|
|
28
|
+
shaded_pct: float
|
|
29
|
+
total_solar_exposure_kwh: float
|
|
30
|
+
comfort_category: str # 'Cool & Shaded', 'Balanced', 'Intense Sun'
|
|
31
|
+
|
|
32
|
+
def to_dict(self) -> Dict[str, Any]:
|
|
33
|
+
return {
|
|
34
|
+
"solar_hour": self.solar_position.solar_hour,
|
|
35
|
+
"azimuth_deg": round(self.solar_position.azimuth_deg, 1),
|
|
36
|
+
"elevation_deg": round(self.solar_position.elevation_deg, 1),
|
|
37
|
+
"direct_sun_pct": round(self.direct_sun_pct, 1),
|
|
38
|
+
"shaded_pct": round(self.shaded_pct, 1),
|
|
39
|
+
"total_solar_exposure_kwh": round(self.total_solar_exposure_kwh, 2),
|
|
40
|
+
"comfort_category": self.comfort_category,
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def calculate_solar_position(
|
|
45
|
+
lat_deg: float,
|
|
46
|
+
solar_hour: float = 13.0,
|
|
47
|
+
day_of_year: int = 172, # Summer solstice ~ June 21
|
|
48
|
+
) -> SolarPosition:
|
|
49
|
+
"""Compute solar azimuth and elevation angle based on latitude and hour of day."""
|
|
50
|
+
# Solar declination angle
|
|
51
|
+
declination_deg = 23.45 * math.sin(math.radians((360.0 / 365.0) * (284 + day_of_year)))
|
|
52
|
+
dec_rad = math.radians(declination_deg)
|
|
53
|
+
lat_rad = math.radians(lat_deg)
|
|
54
|
+
|
|
55
|
+
# Hour angle (15 deg per hour from solar noon at 12:00)
|
|
56
|
+
hour_angle_deg = (solar_hour - 12.0) * 15.0
|
|
57
|
+
h_rad = math.radians(hour_angle_deg)
|
|
58
|
+
|
|
59
|
+
# Solar elevation angle
|
|
60
|
+
sin_el = math.sin(lat_rad) * math.sin(dec_rad) + math.cos(lat_rad) * math.cos(
|
|
61
|
+
dec_rad
|
|
62
|
+
) * math.cos(h_rad)
|
|
63
|
+
sin_el = max(-1.0, min(1.0, sin_el))
|
|
64
|
+
elevation_rad = math.asin(sin_el)
|
|
65
|
+
elevation_deg = math.degrees(elevation_rad)
|
|
66
|
+
|
|
67
|
+
# Solar azimuth angle
|
|
68
|
+
if elevation_deg > 0:
|
|
69
|
+
cos_az = (math.sin(dec_rad) - math.sin(lat_rad) * math.sin(elevation_rad)) / max(
|
|
70
|
+
0.001, math.cos(lat_rad) * math.cos(elevation_rad)
|
|
71
|
+
)
|
|
72
|
+
cos_az = max(-1.0, min(1.0, cos_az))
|
|
73
|
+
azimuth_rad = math.acos(cos_az)
|
|
74
|
+
azimuth_deg = math.degrees(azimuth_rad)
|
|
75
|
+
if hour_angle_deg > 0:
|
|
76
|
+
azimuth_deg = 360.0 - azimuth_deg
|
|
77
|
+
else:
|
|
78
|
+
elevation_deg = 0.0
|
|
79
|
+
azimuth_deg = 180.0
|
|
80
|
+
|
|
81
|
+
# Solar direct beam irradiance model
|
|
82
|
+
irradiance = 1000.0 * math.sin(math.radians(elevation_deg)) if elevation_deg > 0 else 0.0
|
|
83
|
+
|
|
84
|
+
return SolarPosition(
|
|
85
|
+
solar_hour=solar_hour,
|
|
86
|
+
azimuth_deg=azimuth_deg,
|
|
87
|
+
elevation_deg=elevation_deg,
|
|
88
|
+
direct_irradiance_w_m2=max(0.0, irradiance),
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def compute_shade_exposure_along_route(
|
|
93
|
+
coords_3d: Sequence[Tuple[float, float, float]],
|
|
94
|
+
solar_hour: float = 14.0,
|
|
95
|
+
building_density_factor: float = 0.6,
|
|
96
|
+
) -> ShadeExposureReport:
|
|
97
|
+
"""Analyze the proportion of shade vs direct sun along a 3D path at a given time of day."""
|
|
98
|
+
if not coords_3d:
|
|
99
|
+
sun = calculate_solar_position(38.4, solar_hour)
|
|
100
|
+
return ShadeExposureReport(sun, 0.0, 100.0, 0.0, "Shaded")
|
|
101
|
+
|
|
102
|
+
mean_lat = sum(c[1] for c in coords_3d) / len(coords_3d)
|
|
103
|
+
sun = calculate_solar_position(mean_lat, solar_hour=solar_hour)
|
|
104
|
+
|
|
105
|
+
if sun.elevation_deg <= 0:
|
|
106
|
+
return ShadeExposureReport(sun, 0.0, 100.0, 0.0, "Night / Twilight")
|
|
107
|
+
|
|
108
|
+
sun_rad = math.radians(sun.azimuth_deg)
|
|
109
|
+
sun_el_rad = math.radians(sun.elevation_deg)
|
|
110
|
+
sun_shadow_len_factor = 1.0 / max(0.1, math.tan(sun_el_rad))
|
|
111
|
+
|
|
112
|
+
sunlit_length = 0.0
|
|
113
|
+
shaded_length = 0.0
|
|
114
|
+
|
|
115
|
+
for i in range(len(coords_3d) - 1):
|
|
116
|
+
p1 = coords_3d[i]
|
|
117
|
+
p2 = coords_3d[i + 1]
|
|
118
|
+
seg_len = haversine_distance_2d(p1, p2)
|
|
119
|
+
|
|
120
|
+
# Orientation angle of street segment
|
|
121
|
+
dx = (p2[0] - p1[0]) * math.cos(math.radians((p1[1] + p2[1]) * 0.5))
|
|
122
|
+
dy = p2[1] - p1[1]
|
|
123
|
+
street_bearing = math.atan2(dx, dy)
|
|
124
|
+
|
|
125
|
+
# Angle between sun ray and street orientation
|
|
126
|
+
angle_diff = abs(street_bearing - sun_rad) % (math.pi / 2.0)
|
|
127
|
+
canyon_shading_prob = (
|
|
128
|
+
math.sin(angle_diff) * building_density_factor * min(1.0, sun_shadow_len_factor * 0.35)
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
if canyon_shading_prob > 0.45:
|
|
132
|
+
shaded_length += seg_len
|
|
133
|
+
else:
|
|
134
|
+
sunlit_length += seg_len
|
|
135
|
+
|
|
136
|
+
tot = sunlit_length + shaded_length
|
|
137
|
+
sun_pct = (sunlit_length / tot * 100.0) if tot > 0 else 50.0
|
|
138
|
+
shade_pct = (shaded_length / tot * 100.0) if tot > 0 else 50.0
|
|
139
|
+
|
|
140
|
+
# Solar kWh exposure (assuming standard walking pace ~ 12 min/km)
|
|
141
|
+
hours_exposure = (tot / 1000.0) * 0.20
|
|
142
|
+
kwh = (sun.direct_irradiance_w_m2 * (sun_pct / 100.0) * hours_exposure) / 1000.0
|
|
143
|
+
|
|
144
|
+
if shade_pct > 65.0:
|
|
145
|
+
category = "Cool & Shaded (High Comfort)"
|
|
146
|
+
elif shade_pct > 35.0:
|
|
147
|
+
category = "Balanced Sun & Shade"
|
|
148
|
+
else:
|
|
149
|
+
category = "Intense Sun (High Thermal Strain)"
|
|
150
|
+
|
|
151
|
+
return ShadeExposureReport(
|
|
152
|
+
solar_position=sun,
|
|
153
|
+
direct_sun_pct=sun_pct,
|
|
154
|
+
shaded_pct=shade_pct,
|
|
155
|
+
total_solar_exposure_kwh=kwh,
|
|
156
|
+
comfort_category=category,
|
|
157
|
+
)
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"""Traveling Salesperson Problem (TSP) multi-stop tour optimizer.
|
|
2
|
+
|
|
3
|
+
Provides Nearest Neighbour heuristic + 2-Opt local search optimization to reorder
|
|
4
|
+
intermediate waypoints for minimal total 3D distance and elevation climb.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from typing import List, Sequence, Tuple
|
|
10
|
+
|
|
11
|
+
from .kinematics import haversine_distance_3d
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def solve_tsp_order(
|
|
15
|
+
waypoints: Sequence[Tuple[float, float, float]],
|
|
16
|
+
fix_start: bool = True,
|
|
17
|
+
fix_end: bool = True,
|
|
18
|
+
max_iterations: int = 200,
|
|
19
|
+
) -> List[int]:
|
|
20
|
+
"""Return indices of waypoints ordered for minimum total path length using 2-Opt.
|
|
21
|
+
|
|
22
|
+
Args:
|
|
23
|
+
waypoints: List of (lon, lat, ele) tuples.
|
|
24
|
+
fix_start: If True, index 0 remains the first point.
|
|
25
|
+
fix_end: If True, index N-1 remains the final destination.
|
|
26
|
+
"""
|
|
27
|
+
n = len(waypoints)
|
|
28
|
+
if n <= 3:
|
|
29
|
+
return list(range(n))
|
|
30
|
+
|
|
31
|
+
# Initial order via Nearest-Neighbour
|
|
32
|
+
unvisited = set(range(1, n - 1 if fix_end else n))
|
|
33
|
+
current = 0 if fix_start else 0
|
|
34
|
+
route = [current]
|
|
35
|
+
|
|
36
|
+
while unvisited:
|
|
37
|
+
nearest = min(
|
|
38
|
+
unvisited,
|
|
39
|
+
key=lambda idx: haversine_distance_3d(waypoints[current], waypoints[idx]),
|
|
40
|
+
)
|
|
41
|
+
route.append(nearest)
|
|
42
|
+
unvisited.remove(nearest)
|
|
43
|
+
current = nearest
|
|
44
|
+
|
|
45
|
+
if fix_end:
|
|
46
|
+
route.append(n - 1)
|
|
47
|
+
|
|
48
|
+
def total_distance(r: List[int]) -> float:
|
|
49
|
+
return sum(
|
|
50
|
+
haversine_distance_3d(waypoints[r[i]], waypoints[r[i + 1]]) for i in range(len(r) - 1)
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
# 2-Opt Local Search
|
|
54
|
+
best_route = list(route)
|
|
55
|
+
best_dist = total_distance(best_route)
|
|
56
|
+
improved = True
|
|
57
|
+
iters = 0
|
|
58
|
+
|
|
59
|
+
start_idx = 1 if fix_start else 0
|
|
60
|
+
end_idx = n - 2 if fix_end else n - 1
|
|
61
|
+
|
|
62
|
+
while improved and iters < max_iterations:
|
|
63
|
+
improved = False
|
|
64
|
+
iters += 1
|
|
65
|
+
for i in range(start_idx, end_idx):
|
|
66
|
+
for j in range(i + 1, end_idx + 1):
|
|
67
|
+
# 2-opt swap: reverse slice between i and j
|
|
68
|
+
new_route = best_route[:i] + best_route[i : j + 1][::-1] + best_route[j + 1 :]
|
|
69
|
+
new_dist = total_distance(new_route)
|
|
70
|
+
if new_dist < best_dist - 0.01:
|
|
71
|
+
best_route = new_route
|
|
72
|
+
best_dist = new_dist
|
|
73
|
+
improved = True
|
|
74
|
+
break
|
|
75
|
+
if improved:
|
|
76
|
+
break
|
|
77
|
+
|
|
78
|
+
return best_route
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: zero2route3d-sdk
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Headless 3D spatial mobility, biomechanical human kinematics, and multi-criteria routing engine.
|
|
5
|
+
Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/YusufEminoglu/zero2route3d_sdk
|
|
8
|
+
Project-URL: Repository, https://github.com/YusufEminoglu/zero2route3d_sdk
|
|
9
|
+
Project-URL: Issues, https://github.com/YusufEminoglu/zero2route3d_sdk/issues
|
|
10
|
+
Project-URL: Documentation, https://yusufeminoglu.github.io/zero2route3d/
|
|
11
|
+
Keywords: gis,routing,shortest-path,isochrone,accessibility,walkability,mobility,kinematics,openstreetmap,dem,pareto,map-matching
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
22
|
+
Classifier: Intended Audience :: Science/Research
|
|
23
|
+
Classifier: Intended Audience :: Developers
|
|
24
|
+
Requires-Python: >=3.9
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: numpy>=1.20.0
|
|
28
|
+
Requires-Dist: scipy>=1.7.0
|
|
29
|
+
Provides-Extra: geo
|
|
30
|
+
Requires-Dist: shapely>=2.0.0; extra == "geo"
|
|
31
|
+
Requires-Dist: rasterio>=1.3.0; extra == "geo"
|
|
32
|
+
Requires-Dist: geopandas>=0.12.0; extra == "geo"
|
|
33
|
+
Requires-Dist: networkx>=2.8.0; extra == "geo"
|
|
34
|
+
Requires-Dist: matplotlib>=3.5.0; extra == "geo"
|
|
35
|
+
Provides-Extra: dev
|
|
36
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
37
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
38
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
39
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
|
|
42
|
+
# zero2route3d-sdk
|
|
43
|
+
|
|
44
|
+
[](https://github.com/YusufEminoglu/zero2route3d_sdk/actions/workflows/ci.yml)
|
|
45
|
+
[](https://pypi.org/project/zero2route3d-sdk/)
|
|
46
|
+
[](https://pypi.org/project/zero2route3d-sdk/)
|
|
47
|
+
[](LICENSE)
|
|
48
|
+
[](https://docs.astral.sh/ruff/)
|
|
49
|
+
|
|
50
|
+
**zero2route3d-sdk** is a Python library for **3D spatial mobility modeling, biomechanical human kinematics, and multi-criteria routing analytics**.
|
|
51
|
+
|
|
52
|
+
Built for urban planners, mobility researchers, and geospatial developers, it brings physiological human movement equations, terrain-aware 3D graph algorithms, and environmental microclimate impedance surfaces together into a pure-Python, headless package powered by NumPy and SciPy.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 🌟 Key Capabilities
|
|
57
|
+
|
|
58
|
+
1. **Biomechanical Kinematics & Energy Modeling:**
|
|
59
|
+
- Empirical slope-speed curves via **Tobler's hiking function** ($W(s) = 6.0 \cdot e^{-3.5|s+0.05|}$).
|
|
60
|
+
- Exact metabolic energy expenditure via **Minetti's 5th-order polynomial equations** ($J / (kg \cdot m)$).
|
|
61
|
+
- Aerodynamic drag, rolling resistance, and mechanical efficiency for commuter bikes, cargo bikes, and e-scooters.
|
|
62
|
+
- Universal Thermal Comfort Index (**UTCI**) and solar irradiance aspect factors.
|
|
63
|
+
|
|
64
|
+
2. **15 Calibrated Mobility Profiles:**
|
|
65
|
+
- Pedestrian (*Adult, Senior, Child*).
|
|
66
|
+
- Universal accessibility (*Wheelchair ADA, Stroller*).
|
|
67
|
+
- Micromobility (*Commuter Bike, Cargo Bike, E-Bike, E-Scooter, Runner, Hiker*).
|
|
68
|
+
- Vehicles & Emergency (*Emergency EMS, Fire Truck, Logistics Van, Electric Car*).
|
|
69
|
+
|
|
70
|
+
3. **Multi-Objective 4D Pareto Optimization (NAMOA*):**
|
|
71
|
+
- Finds non-dominated Pareto frontiers balancing **Travel Time, Cumulative Climb, Thermal Heat Dose, and Metabolic Calories**.
|
|
72
|
+
|
|
73
|
+
4. **3D Topological Routing & Isochrones:**
|
|
74
|
+
- 3D graph construction with elevation draping, turn penalties, and barrier avoidance.
|
|
75
|
+
- Anisotropic 3D isochrone wavefront propagation.
|
|
76
|
+
|
|
77
|
+
5. **3D Hidden Markov Model (HMM) Map Matching:**
|
|
78
|
+
- Robust Viterbi decoding matching noisy GPS/GPX tracks to 3D networks.
|
|
79
|
+
|
|
80
|
+
6. **Micro-Elevation & Solar Ray-Tracing:**
|
|
81
|
+
- Keys' 16-point bicubic convolution spline interpolation with analytical $\mathcal{C}^1$ slope/aspect derivatives.
|
|
82
|
+
- Solar position calculation (azimuth/elevation) and building shadow casting.
|
|
83
|
+
|
|
84
|
+
7. **Spatial Justice & Evacuation:**
|
|
85
|
+
- Enhanced 2-Step Floating Catchment Area (**E2SFCA**) healthcare/amenity accessibility.
|
|
86
|
+
- Gini coefficients, Lorenz curves, and Palma spatial equity ratios.
|
|
87
|
+
- Dynamic hazard zone evacuation routing and safe haven allocation.
|
|
88
|
+
|
|
89
|
+
8. **Headless & Multi-Format I/O:**
|
|
90
|
+
- Runs everywhere: Jupyter Notebooks, FastAPI/Flask backends, Docker containers, CLI scripts.
|
|
91
|
+
- Exports to GeoJSON 3D, GPX 1.1, AutoCAD DXF (AC1009/AC1015) 3D Polylines, and standalone Three.js 60 FPS WebGL 3D Cockpit HTML bundles.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## 📦 Installation
|
|
96
|
+
|
|
97
|
+
Install the core library from PyPI:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
pip install zero2route3d-sdk
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Or install with optional geospatial acceleration libraries:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
pip install "zero2route3d-sdk[geo]"
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## 🚀 Quickstart
|
|
112
|
+
|
|
113
|
+
### 1. High-Level One-Line Routing & Isochrones
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
import zero2route3d as zr3d
|
|
117
|
+
|
|
118
|
+
# Solve 3D Least-Cost Route in 1 line
|
|
119
|
+
route = zr3d.solve_3d_route(
|
|
120
|
+
origin=(27.11, 38.41),
|
|
121
|
+
destination=(27.14, 38.44),
|
|
122
|
+
network="izmir_network.geojson", # Or GeoDataFrame / list of RoadSegments
|
|
123
|
+
profile="wheelchair" # 15 calibrated profiles
|
|
124
|
+
)
|
|
125
|
+
|
|
126
|
+
print(f"Distance: {route.statistics.total_distance_km:.2f} km")
|
|
127
|
+
print(f"Duration: {route.statistics.total_duration_min:.1f} min")
|
|
128
|
+
print(f"Climb: +{route.statistics.elevation_gain_m:.1f} m")
|
|
129
|
+
|
|
130
|
+
# Save or display interactive 3D WebGL Cockpit
|
|
131
|
+
route.to_html("route_viewer.html")
|
|
132
|
+
|
|
133
|
+
# Plot publication-grade elevation & metabolic energy profile with Matplotlib
|
|
134
|
+
route.plot(show_energy=True, save_path="profile.png")
|
|
135
|
+
|
|
136
|
+
# Convert to 3D LineStringZ GeoDataFrame for GIS workflows
|
|
137
|
+
gdf = route.to_geodataframe()
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### 2. Multi-Objective 4D Pareto Frontier (NAMOA*)
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
import zero2route3d as zr3d
|
|
144
|
+
|
|
145
|
+
pareto_result = zr3d.solve_4d_pareto_frontier(
|
|
146
|
+
origin=(27.11, 38.41),
|
|
147
|
+
destination=(27.14, 38.44),
|
|
148
|
+
network="izmir_network.geojson",
|
|
149
|
+
profile="commuter_bike"
|
|
150
|
+
)
|
|
151
|
+
|
|
152
|
+
for idx, sol in enumerate(pareto_result.solutions, start=1):
|
|
153
|
+
print(f"Solution #{idx}: Time={sol.costs.time_sec/60:.1f}m, Climb={sol.costs.climb_m:.1f}m, Calories={sol.costs.calories_kcal:.0f}kcal")
|
|
154
|
+
|
|
155
|
+
# Plot 2D Pareto trade-off curve
|
|
156
|
+
zr3d.plot_pareto_frontier_2d(pareto_result, save_path="pareto_curve.png")
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### 3. GeoPandas & NetworkX Ecosystem Bridges
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
from zero2route3d import to_geodataframe, to_networkx_digraph, from_geodataframe
|
|
163
|
+
import geopandas as gpd
|
|
164
|
+
|
|
165
|
+
# Load standard GeoDataFrame of road centerlines
|
|
166
|
+
gdf = gpd.read_file("streets.geojson")
|
|
167
|
+
|
|
168
|
+
# Convert GeoDataFrame into 3D RoadSegment graph
|
|
169
|
+
segments = from_geodataframe(gdf)
|
|
170
|
+
|
|
171
|
+
# Convert 3D routing graph into NetworkX DiGraph with slope & kinematic weights
|
|
172
|
+
nx_digraph = to_networkx_digraph(segments)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### 4. Command Line Interface (CLI)
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
# Inspect all 15 mobility profiles
|
|
179
|
+
zero2route3d profiles
|
|
180
|
+
|
|
181
|
+
# Run headless 3D route calculation from terminal
|
|
182
|
+
zero2route3d route --origin 27.11,38.41 --dest 27.14,38.44 --network streets.geojson --profile wheelchair --out-geojson route.geojson --out-dxf route.dxf --out-html viewer.html
|
|
183
|
+
|
|
184
|
+
# Compute 3D travel time isochrone bands
|
|
185
|
+
zero2route3d isochrone --center 27.12,38.42 --intervals 5,10,15 --network streets.geojson --out-geojson isochrones.geojson
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## 📚 Mobility Profiles Catalog
|
|
191
|
+
|
|
192
|
+
| Key | Profile Name | Base Speed | Max Slope | Stairs Policy | Target Use-Case |
|
|
193
|
+
| :--- | :--- | :--- | :--- | :--- | :--- |
|
|
194
|
+
| `adult` | Standard Adult | 5.0 km/h | 25.0% | Allowed (1.2×) | Everyday urban walking |
|
|
195
|
+
| `senior` | Senior / Elderly | 3.2 km/h | 10.0% | Heavy Penalty (8.0×) | Age-friendly routing |
|
|
196
|
+
| `child` | Child / Elementary | 3.8 km/h | 12.0% | Heavy Penalty (5.0×) | Safe routes to school |
|
|
197
|
+
| `wheelchair` | Wheelchair ADA | 3.5 km/h | 5.0% | **Forbidden** (1000×) | Barrier-free ADA routing |
|
|
198
|
+
| `stroller` | Stroller / Pram | 4.0 km/h | 8.0% | **Forbidden** (500×) | Family-friendly walking |
|
|
199
|
+
| `cargo_bike` | Cargo Bike | 14.0 km/h | 8.0% | **Forbidden** (1000×) | Urban freight & logistics |
|
|
200
|
+
| `commuter_bike`| Commuter Bike | 18.0 km/h | 15.0% | Heavy Penalty (20.0×) | Daily bicycle commuting |
|
|
201
|
+
| `ebike` | Electric Assist Bike| 22.0 km/h | 22.0% | Heavy Penalty (20.0×) | Topography-immune cycling |
|
|
202
|
+
| `escooter` | E-Scooter | 16.0 km/h | 10.0% | **Forbidden** (1000×) | First/last-mile micromobility |
|
|
203
|
+
| `runner` | Jogger / Runner | 10.0 km/h | 30.0% | Allowed (1.0×) | Fitness & athletic routing |
|
|
204
|
+
| `hiker` | Mountain Hiker | 4.5 km/h | 50.0% | Allowed (1.0×) | Trail & topographic hiking |
|
|
205
|
+
| `emergency_ems`| Ambulance EMS | 50.0 km/h | 20.0% | **Forbidden** (1000×) | Rapid emergency response |
|
|
206
|
+
| `emergency_fire`| Fire Engine Heavy | 40.0 km/h | 16.0% | **Forbidden** (1000×) | Heavy emergency vehicles |
|
|
207
|
+
| `logistics_van`| Delivery Van | 45.0 km/h | 18.0% | **Forbidden** (1000×) | Courier & parcel delivery |
|
|
208
|
+
| `electric_car` | Electric EV | 50.0 km/h | 25.0% | **Forbidden** (1000×) | Regenerative braking routing |
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## 🧪 Development & Testing
|
|
213
|
+
|
|
214
|
+
Clone the repository and install in editable mode:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
git clone https://github.com/YusufEminoglu/zero2route3d_sdk.git
|
|
218
|
+
cd zero2route3d_sdk
|
|
219
|
+
pip install -e ".[dev]"
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Run test suite with coverage:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
pytest tests/ -v --cov=zero2route3d
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Run linter and type checker:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
ruff check .
|
|
232
|
+
ruff format --check src tests
|
|
233
|
+
mypy src
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## 📄 License & Citation
|
|
239
|
+
|
|
240
|
+
Distributed under the **MIT License**. See `LICENSE` for details.
|
|
241
|
+
|
|
242
|
+
If you use this library in scientific research, please cite:
|
|
243
|
+
|
|
244
|
+
```bibtex
|
|
245
|
+
@software{eminoglu2026zero2route3d,
|
|
246
|
+
author = {Eminoğlu, Yusuf},
|
|
247
|
+
title = {zero2route3d-sdk: Headless 3D spatial mobility, biomechanical human kinematics, and multi-criteria routing engine},
|
|
248
|
+
year = {2026},
|
|
249
|
+
url = {https://github.com/YusufEminoglu/zero2route3d_sdk}
|
|
250
|
+
}
|
|
251
|
+
```
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
zero2route3d/__init__.py,sha256=HCGsnE1K0OS7N1e5qUeUGSJU21yGbt68VOqeyx2Zp5w,5843
|
|
2
|
+
zero2route3d/accessibility_equity.py,sha256=QwjCO8gkScFzr76ORQ3voMP_WR-yS8md9eTDgpL0fF0,7906
|
|
3
|
+
zero2route3d/ahp_engine.py,sha256=TagUW2urzrZPHROZR9vq5rKyjjx43Nx8_uY2UCrwHuc,4103
|
|
4
|
+
zero2route3d/api.py,sha256=bdE4DQKXGRM6c3MNp54Yv1Y5gFniWVZXpqtuYkg1Gvk,10169
|
|
5
|
+
zero2route3d/basemap.py,sha256=LKTUm_npAWn2QYNQuUPDTwtoXs51PJcXIjlCUvnm_k0,1866
|
|
6
|
+
zero2route3d/cli.py,sha256=BYrCDo7TcAoS9MRLmg1kn-6ZcBknwPpjU-o3rTAr6Yk,8978
|
|
7
|
+
zero2route3d/copernicus_dem.py,sha256=b5TtVBwGuiepMGinvdkyto7Heoz9IS7NbJxLIMnlJMY,3233
|
|
8
|
+
zero2route3d/copernicus_eo_suite.py,sha256=vIGRqFN0q_C0Kgu41pR_wVdLs3qhRyhS7MEe5Kwm5b0,16326
|
|
9
|
+
zero2route3d/dem_fetcher.py,sha256=onsisnDOiJbY7S5hCV6oodnT93_BXecD50YSY4_jimE,9228
|
|
10
|
+
zero2route3d/environmental_raster.py,sha256=pPiugLJsDjT3NjjAnDJOgetu_NSHtq95thyrHVg7HHo,16502
|
|
11
|
+
zero2route3d/evacuation.py,sha256=cU4mwsIbSjaeNI43Hu8zWBVMgJdT8J-VOF_IwjkWnU8,4454
|
|
12
|
+
zero2route3d/html_bundler.py,sha256=zN1ICLlUFy-BCtjOGK5zhzBV4FJaJyMtPtOqHcLFqY4,24058
|
|
13
|
+
zero2route3d/input_validation.py,sha256=yYYIQFhsiVXMF89QCqDQ_2LGo8WE7H59kVatek17CBQ,4064
|
|
14
|
+
zero2route3d/integrations.py,sha256=z7radatP7ZXDryN9lbj5qF7eoQb-MTvPjm6GHc2sugk,9856
|
|
15
|
+
zero2route3d/isochrone_engine.py,sha256=kU9ICt6cOZdO2PXKP6RzGA_6O7F7ljQemWNqQ3GHlc4,8245
|
|
16
|
+
zero2route3d/kinematics.py,sha256=b-zcCfwa_bgIxfTU64tNr462PNWV8Sh_ldz6t8scrtE,14537
|
|
17
|
+
zero2route3d/local_server.py,sha256=GlEG9-inbEDBcxxLSWW3zUbGBVY3gIfAgcnKdff8dnU,3891
|
|
18
|
+
zero2route3d/map_matching_3d.py,sha256=q5wLNHtWXTUNfBhX4-LPNdkP5MfTuLrL95Z-RAEuhGE,13633
|
|
19
|
+
zero2route3d/micro_elevation.py,sha256=NB7bazbOMU_6ltFjfnwXbxtlE1i-Cw4Rl707ihQgZ9M,9945
|
|
20
|
+
zero2route3d/mobility_profiles.py,sha256=A8AlrfILpWJONA60YkgJRjFeXyvkEtWXsvM55s6qQfE,19045
|
|
21
|
+
zero2route3d/multimodal.py,sha256=Rq-SCgRWP--hKxPcljQfRXR1QNFFypAJpr4TsDLN76Q,6291
|
|
22
|
+
zero2route3d/network_source.py,sha256=i499dB901LyLVRRLu4kHffdrVQ_nF8FcpeeSpjuHSlY,21791
|
|
23
|
+
zero2route3d/osm_downloader.py,sha256=54MSo9mA4eJrTDYEZEdRaCPYuMzk8ccgdwi2q2DtcoM,14648
|
|
24
|
+
zero2route3d/osm_styling.py,sha256=9IjKRTRRaN64SfWp7M9_eyzFxOSlQZ1lZ0ZS-1xnazc,12181
|
|
25
|
+
zero2route3d/pareto_router.py,sha256=Ldwlt8DtXzp1P6bjXrl8FffP7_K_OjFjPyOqntcld-4,12543
|
|
26
|
+
zero2route3d/plotting.py,sha256=DEgf8jqSBQ6nyPpdqjWk9mGkfKJLMphgvnLqz9uI4I0,10037
|
|
27
|
+
zero2route3d/profile_dxf.py,sha256=uSrpD_CFLgUx_c5qsbhyYq3OGCBvXm0kNu7nk2mzYgM,5317
|
|
28
|
+
zero2route3d/profile_stats.py,sha256=loSXmrWzP0ASdDUulYdfKXYi830QGWp3USJvZ8aZmQo,23352
|
|
29
|
+
zero2route3d/py.typed,sha256=0kx-6opwbvx37KaHPZ0rlYb8XJtMZZCO_GnYLkepmyI,40
|
|
30
|
+
zero2route3d/qml_generator.py,sha256=BHF3FyLQJqlz8gk_jkp3Gcl6NOYycWhqCDj4biENqlE,7446
|
|
31
|
+
zero2route3d/raster_source.py,sha256=TvJMbbNDWlDtAJu6YosBsBi97Aw-hFGGF00sHOpwIO4,7715
|
|
32
|
+
zero2route3d/report_generator.py,sha256=NjZg3FW7ebYG67MywvMni216KNnQLrxf5WgChdDNCVY,7425
|
|
33
|
+
zero2route3d/route_corridor_3d.py,sha256=JUjXaSwTRDT5YhGgWnSDrPGSWozCD9sJ_BOKMaHETOc,19613
|
|
34
|
+
zero2route3d/routing_engine.py,sha256=YpzQcQRujreEX7M1-bteFKgVygScL04LWm8-moTLApg,31392
|
|
35
|
+
zero2route3d/solar_shadow.py,sha256=CbjJjQoahDWIZ5eitwdgoTOHEGhXnV1lqAZK-GOpixI,5457
|
|
36
|
+
zero2route3d/tsp_solver.py,sha256=nINau2IcIobpNYWcmMSH7RGB_R-dyrNwqMNK5jZEpJE,2383
|
|
37
|
+
zero2route3d_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=Z9meOk3opsRgHOqC5mA4B8NjZoU5WU1Kqhn82FL4ICs,1072
|
|
38
|
+
zero2route3d_sdk-0.2.0.dist-info/METADATA,sha256=thp-WSAw4EWDCudkFCi96-zF5V8OA2ABEta-y53TEBc,10264
|
|
39
|
+
zero2route3d_sdk-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
|
|
40
|
+
zero2route3d_sdk-0.2.0.dist-info/entry_points.txt,sha256=gj18VrhRnQ8z3y4uehnXcD0Mx2IGCYDz7W1nLKiCmZo,55
|
|
41
|
+
zero2route3d_sdk-0.2.0.dist-info/top_level.txt,sha256=CjD09-SmzBJnTORwTdEbHpVs_cZCjZcBLeRUbijFtYU,13
|
|
42
|
+
zero2route3d_sdk-0.2.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Yusuf Eminoğlu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
zero2route3d
|