zero2route3d-sdk

1. Installation & Quickstart

zero2route3d-sdk is available on PyPI. It has zero obligatory C-extension build requirements and functions seamlessly across Windows, Linux, and macOS:

# Standard installation (NumPy, SciPy)
pip install zero2route3d-sdk

# With full geospatial integration suite (GeoPandas, Shapely, Rasterio, NetworkX, Matplotlib)
pip install "zero2route3d-sdk[geo]"

One-Line High-Level 3D Routing

import zero2route3d as zr3d

# Solve optimal 3D path with barrier-free ADA wheelchair constraints
route = zr3d.solve_3d_route(
    origin=(27.11, 38.41),
    destination=(27.14, 38.44),
    network="city_streets.geojson",
    profile="wheelchair"
)

print(f"Total Distance: {route.statistics.total_distance_km:.2f} km")
print(f"Total Duration: {route.statistics.total_duration_min:.1f} min")
print(f"Cumulative Climb: +{route.statistics.elevation_gain_m:.1f} m")
print(f"Metabolic Energy: {route.statistics.total_energy_kcal:.0f} kcal")

# Generate standalone Three.js WebGL 3D Interactive Cockpit
route.to_html("interactive_cockpit.html")

Command Line Interface (CLI)

# List all 15 calibrated mobility profiles
zero2route3d profiles

# Run headless 3D route calculation from terminal
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

# Compute 3D travel time isochrone contours
zero2route3d isochrone --center 27.12,38.42 --intervals 5,10,15 --network streets.geojson --profile adult --out-geojson isochrones.geojson

2. Biomechanical Kinematics & Metabolic Energy

Unlike traditional 2D routing engines (such as standard OSRM or pgRouting) that treat the earth as a flat plane, zero2route3d-sdk embeds physiological human movement mechanics directly into the edge relaxation cost function.

Tobler's Hiking Function (1993)

Waldo Tobler's empirical formula determines walking speed $W$ (in $km/h$) as an exponential function of terrain slope $s = \frac{dz}{dx}$ (vertical rise over horizontal run):

Maximum walking velocity ($6.0 \text{ km/h}$) is achieved on a gentle downhill gradient of $-5.0\%$. Ascents and steep descents exponentially reduce walking velocity to maintain human postural stability.

Minetti Metabolic Energy Cost (2002)

Minetti et al. (2002) formulated a 5th-order polynomial governing the mechanical energy cost of human locomotion $C_w(s)$ in Joules per kilogram per meter ($J / (kg \cdot m)$):

Total metabolic calorie expenditure $E_{total}$ along path $P = \{e_1, e_2, \dots, e_k\}$ is calculated by integrating over segment lengths $\ell_i$ and body mass $M$:

Cycling Aerodynamic & Rolling Drag Dynamics

For micromobility profiles (commuter bikes, cargo bikes, e-scooters), resistive forces are governed by physical equations of motion:

Where $\rho = 1.225 \text{ kg/m}^3$ (air density), $C_d A$ is the effective frontal drag area ($0.35 \text{ m}^2$ for road bikes, $0.60 \text{ m}^2$ for upright cargo bikes), and $C_{rr}$ is the tire rolling resistance coefficient ($0.004 - 0.008$).

Universal Thermal Comfort Index (UTCI) & Shade Factor

Solar radiation and thermal stress amplify travel fatigue. The effective environmental impedance weight $w_{thermal}$ modifies link traversal cost based on shade fraction $f_{shade}$ and sun elevation angle $\theta_{sun}$:

3. 15 Calibrated Mobility Profiles Master Catalog

The SDK ships with 15 pre-configured, peer-reviewed physiological profiles catering to universal accessibility, active travel, and emergency logistics:

4. Multi-Objective 4D Pareto Optimization (NAMOA*)

In real-world urban routing, single-objective Dijkstra is insufficient: the fastest route may force a cyclist up a punishing 18% hill, while the flattest route may triple the travel time. NAMOA* (Node-Attribute Multiobjective A*) identifies the exact set of non-dominated Pareto solutions $\mathcal{P}^*$ across 4 distinct cost dimensions:

import zero2route3d as zr3d

pareto_result = zr3d.solve_4d_pareto_frontier(
    origin=(27.11, 38.41),
    destination=(27.14, 38.44),
    network="streets.geojson",
    profile="commuter_bike"
)

print(f"Discovered {len(pareto_result.solutions)} non-dominated Pareto routes:")
for i, sol in enumerate(pareto_result.solutions, start=1):
    c = sol.costs
    print(f"  Option #{i}: Duration={c.time_sec/60:.1f}m | Climb=+{c.climb_m:.1f}m | Calories={c.calories_kcal:.0f}kcal")

5. 3D Hidden Markov Model (HMM) Map Matching

Matches raw, noisy GPS tracks (including elevation errors) to 3D road networks using the Viterbi Dynamic Programming Algorithm with Gaussian emission probabilities and exponential transition probabilities (Newson & Krumm, 2009):

from zero2route3d.map_matching_3d import HMMMapMatcher3D, GPXPoint

matcher = HMMMapMatcher3D(network_segments)
raw_gps_points = [GPXPoint(lon=27.112, lat=38.415, elevation=12.0, timestamp=0.0), ...]

result = matcher.match_trace(raw_gps_points)
print(f"Matched {len(result.matched_points)} points to 3D network with mean error: {result.mean_error_meters:.2f} m")

6. Keys' Bicubic Convolution Micro-Elevation Engine

Standard bilinear raster interpolation produces discontinuous, stepped derivatives ($C^0$), leading to erratic slope spikes. zero2route3d implements Keys' 16-point Bicubic Convolution Spline ($C^1$ continuity), providing smooth analytical surface gradients:

from zero2route3d.micro_elevation import BicubicSurfaceInterpolator
import numpy as np

# 4x4 DEM elevation kernel
dem_patch = np.array([
    [10.0, 11.2, 12.5, 14.0],
    [10.5, 12.0, 13.8, 15.5],
    [11.0, 13.1, 15.2, 17.1],
    [11.8, 14.2, 16.8, 19.0]
])

interpolator = BicubicSurfaceInterpolator(dem_patch)
elev, slope_deg, aspect_deg = interpolator.sample_with_derivatives(x=1.5, y=1.5)
print(f"Elevation: {elev:.2f} m | Slope: {slope_deg:.2f}° | Aspect: {aspect_deg:.1f}°")

7. Standalone Three.js 3D WebGL Cockpit & DXF Export

Routes can be directly exported into self-contained, single-file HTML bundles featuring a 60 FPS Three.js WebGL 3D cockpit with animated avatars, pitch/roll terrain tracking, and interactive camera orbits:

# Export to AutoCAD DXF 3D Polyline (AC1009/AC1015)
from zero2route3d.profile_dxf import export_route_to_dxf_3d

export_route_to_dxf_3d(route, output_path="3d_route_engineering.dxf")

# Export to Interactive 3D WebGL Cockpit
route.to_html("interactive_cockpit.html")

8. Performance & Benchmarking

zero2route3d is vectorized via NumPy contiguous arrays and SciPy CSR matrices:

9. Academic Bibliography & Citation

If you utilize zero2route3d in academic research, planning studies, or transportation models, please cite:

@software{eminoglu2026zero2route3d,
  author = {Emino{\u{g}}lu, Yusuf},
  title = {{zero2route3d-sdk: Headless 3D spatial mobility, biomechanical human kinematics, and multi-criteria routing engine}},
  year = {2026},
  publisher = {PyPI - Python Package Index},
  version = {0.2.0},
  url = {https://gitlab.com/geospacephilo/zero2route3d_sdk}
}

Key Foundational Literature

• Tobler, W. (1993). Three presentations on geographical analysis and modeling. National Center for Geographic Information and Analysis, Technical Report 93-1.
• Minetti, A. E., Moia, C., Roi, G. S., Susta, D., & Ferretti, G. (2002). Energy cost of walking and running at extreme uphill and downhill slopes. Journal of Applied Physiology, 93(3), 1039–1046.
• Newson, P., & Krumm, J. (2009). Hidden Markov map matching through noise and sparseness. ACM SIGSPATIAL GIS, 336–343.
• Keys, R. (1981). Cubic convolution interpolation for digital image processing. IEEE Transactions on Acoustics, Speech, and Signal Processing, 29(6), 1153–1160.
• Mandow, L., & De La Cruz, J. L. (2005). A new approach to multiobjective A* search. IJCAI, 218–223.