georoutelib
Maritime route calculation: waypoints → route geometry → along-route analysis and editing. Built in Rust with PyO3, exposed as a Python native extension.
| PyPI | georoutelib 0.2.0 |
|---|---|
| import | import georoutelib |
Requires Python 3.12+.
Immutable-by-design:
RouteLineandGeoRoutefollow Rust's functional paradigm — all mutation methods (merge_point,deduplicate,simplify,remove_point, …) return a new instance. The original object is never modified in place.# ✅ Correct: re-assign to capture the result route = route.deduplicate().simplify() route = route.merge_point(new_point) # ❌ Wrong: original object unchanged, result discarded route.deduplicate() # silently does nothing useful
Install
pip install georoutelib
Development:
uv sync --extra dev
env -u CONDA_PREFIX maturin develop
.venv/bin/pytest
Package layout (Rust)
src/
├── lib.rs # PyO3 module entry; logging init
├── eca/ # ECAProcessor — GeoJSON zones × route distance
│ ├── mod.rs # HTTP cache (30-min TTL), singleton instances
│ ├── compute.rs # Polygon intersection math
│ └── geom.rs # Segment–polygon geometry helpers
└── route/
├── geo_calc.rs # GeoCalc: static geodesic utilities
├── geo_calc_core.rs # Core algorithms (LonLat, dateline split, simplify, …)
├── geo_route.rs # GeoRoute: multi-segment route object
├── route_line.rs # RouteLine: flat point-sequence operations
├── route_point.rs # RoutePoint data model + make_route_point_simple()
├── measures.rs # Haversine / rhumb distance & bearing
├── coord.rs # Rounding, constants (NM_TO_KM, EPS_ZERO, DATELINE_EPS)
└── py_convert.rs # Python ↔ Rust data conversion
Units
| Quantity | Unit |
|---|---|
| Distance | nautical miles (nm) |
| Speed | knots (kts) |
| Bearing | degrees (0–360°) |
| Time | hours (h) or Unix timestamp (s) |
Quick start
Create points and measure distance
from georoutelib import RoutePoint, GeoCalc
a = RoutePoint(lon=-50.9, lat=12.6)
b = RoutePoint(lon=-52.3, lat=12.9)
rhumb_nm = GeoCalc.distance(a, b, rhumb=True)
gc_nm = GeoCalc.distance(a, b, rhumb=False)
bearing_deg = GeoCalc.bearing(a, b, rhumb=True)
print(f"Rhumb: {rhumb_nm:.1f} nm GC: {gc_nm:.1f} nm Brng: {bearing_deg:.1f}°")
Destination from bearing & distance
from georoutelib import RoutePoint, GeoCalc
start = RoutePoint(lon=116.4, lat=39.9) # Beijing
dest = GeoCalc.destination(start, bearing=45.0, dist_nm=100.0, rhumb=False)
print(f"Destination: ({dest.lon:.2f}, {dest.lat:.2f})")
Build a route from waypoints (great-circle interpolation)
from georoutelib import RoutePoint, GeoRoute
points = [
RoutePoint(lon=103.8, lat=1.2, is_great_circle=True),
RoutePoint(lon=104.5, lat=1.5, is_great_circle=True),
RoutePoint(lon=105.0, lat=2.0), # rhumb leg (default)
]
route = GeoRoute.from_points(points, spacing=200.0)
print(f"Segments: {len(route.segments)}") # split at ±180° if crossed
print(f"Total: {route.total_distance():.1f} nm")
Flat route operations (chainable)
from georoutelib import RouteLine, RoutePoint
points = [
RoutePoint(lon=0, lat=0),
RoutePoint(lon=1, lat=1),
RoutePoint(lon=2, lat=0),
]
line = RouteLine(points).deduplicate().simplify()
total_nm = line.total_distance()
center_pt = line.center() # RoutePoint
bbox = line.bbox() # [min_lon, min_lat, max_lon, max_lat]
segments = line.to_multi_line() # List[List[Tuple]]
print(f"Distance={total_nm:.1f}nm Center=({center_pt.lon:.2f},{center_pt.lat:.2f})")
Advance along a route (vessel tracking)
from georoutelib import RoutePoint, GeoRoute
route = GeoRoute.from_points(points, spacing=200.0)
current = RoutePoint(lon=104.0, lat=1.3, custom_speed=14.0)
result = route.advance_along(current, dist=50.0)
next_pos = result["point"] # RoutePoint at +50 nm ahead
remaining = result["remaining"] # untraveled segments (GeoRoute segments format)
traveled = result["traveled"] # List[RoutePoint] passed en route
print(f"Next waypoint: ({next_pos.lon:.3f}, {next_pos.lat:.3f})")
Minimum distance from a point to a route
result = route.min_distance_to(RoutePoint(lon=104.2, lat=1.4))
# {"min_dist": float, "seg_index": int, "min_index": int}
print(f"Cross-track error: {result['min_dist']:.2f} nm")
More scenarios
Simplify routes (reduce point count)
Three strategies available via GeoCalc static methods:
from georoutelib import RoutePoint, RouteLine, GeoCalc
points = [RoutePoint(lon=i * 0.5, lat=(i % 10) * 0.1) for i in range(50)]
line = RouteLine(points)
# Angle-based: remove points where turn angle > min_angle (default 170°)
simple = line.simplify()
# Turn-based: combine distance threshold + angle threshold
simple = GeoCalc.simplify_by_turn(line.points, min_distance=0.5, min_angle=175.0)
# Collinearity-based: drop mid-points on near-straight legs
simple = GeoCalc.simplify_by_collinearity(
line.points, min_distance=1.0, min_angle=180.0, warn=True,
)
Dateline handling (crossing ±180°)
Routes that cross the antimeridian are automatically split into separate segments.
Both RouteLine.to_multi_line() and GeoRoute.from_points() handle this internally:
from georoutelib import RouteLine, RoutePoint, GeoCalc
# A route crossing the Pacific dateline
points = [
RoutePoint(lon=179.0, lat=20.0),
RoutePoint(lon=-179.0, lat=22.0), # crosses ±180°
RoutePoint(lon=-175.0, lat=25.0),
]
line = RouteLine(points)
segments = line.to_multi_line(rhumb=True)
# Returns [[...], [...]] — two segments on each side of the date line
print(f"Split into {len(segments)} segment(s)")
# Manual split via GeoCalc:
segments = GeoCalc.split_at_dateline(line.points, rhumb=False)
Convert between GeoRoute ↔ RouteLine
from georoutelib import RoutePoint, GeoRoute, RouteLine
route = GeoRoute.from_points(my_points, spacing=200.0)
# GeoRoute → RouteLine (flatten all segments into one list)
line = route.to_line()
# RouteLine → coordinate array
coords = line.to_multi_line() # List[List[(lon, lat)]]
Slice a route between two waypoints
from georoutelib import RoutePoint, GeoRoute
start_wp = RoutePoint(lon=104.0, lat=1.3)
end_wp = RoutePoint(lon=104.8, lat=1.7)
# Get sub-route as coordinates
sub_segments = route.slice_route(start_wp, end_wp)
# Or get as flat RouteLine
sub_line = route.slice_line(start_wp, end_wp)
Find nearest point on route
from georoutelib import RoutePoint, GeoRoute
off_route = RoutePoint(lon=104.3, lat=1.55)
nearest = route.nearest_point(off_route)
# nearest: RoutePoint — closest point on any segment
Fill waypoint distances along a route
from georoutelib import RoutePoint, GeoRoute
waypoints = [RoutePoint(lon=103.8+i*0.3, lat=1.2+i*0.15) for i in range(5)]
# Populate distance_from_previous / distance_from_start on each WP
route.fill_point_distances(waypoints)
for wp in waypoints:
print(f"WP ({wp.lon:.1f}, {wp.lat:.1f}): "
f"d_prev={wp.distance_from_previous:.1f}nm "
f"d_start={wp.distance_from_start:.1f}nm")
Compress dense great-circle points back to reference waypoints
from georoutelib import RoutePoint, GeoRoute
dense = route.to_points(min_distance_nm=0.1) # hundreds of interpolated points
ref_points = [ # your original waypoints
RoutePoint(lon=103.8, lat=1.2),
RoutePoint(lon=105.0, lat=2.0),
]
compressed = route.compress_points(ref_points, min_distance_nm=1.0)
# Returns simplified list preserving reference waypoints
Time-based queries (DR / dead reckoning)
When RoutePoint.position_time (Unix timestamp) is populated:
from georoutelib import RoutePoint, RouteLine
pts = []
for i, t in enumerate([1700000000, 1700003600, 1700007200, 1700010800]):
pts.append(RoutePoint(lon=120 + i * 0.5, lat=25 + i * 0.1, position_time=t))
line = RouteLine(pts)
# Interpolate position at a given timestamp
pos = line.position_at(1700005000) # Option[RoutePoint]
# Reverse lookup: time when vessel passes a location
ts = line.time_at(target_point) # Option[float] — Unix ts
# Nearest point by temporal window
pt = line.nearest_point_by_time(ts=1700006000, step_hours=2.0)
# Remaining points from a given position
ahead = line.remaining_points_from(some_point)
prev = line.prev_point_at(some_point)
Cross-track distance (how far off-course?)
from georoutelib import RoutePoint, GeoCalc
p = RoutePoint(lon=104.2, lat=1.4) # vessel position
a = RoutePoint(lon=104.0, lat=1.3) # leg start
b = RoutePoint(lon=104.5, lat=1.6) # leg end
xtd = GeoCalc.cross_track_distance(p, a, b) # perpendicular offset in nm
foot = GeoCalc.closest_point_on_segment(p, a, b)
# foot: {"lon", "lat", "inline"} — projection onto segment
Remaining route from current position
from georoutelib import RoutePoint, GeoRoute
current = RoutePoint(lon=104.1, lat=1.35)
remaining = route.remaining_route(current)
# remaining: GeoRoute-style segments from current position to destination
Reverse a route
reversed_line = line.reverse() # returns new RouteLine, points in opposite order
Append / prepend / remove points
All return new instances:
from georoutelib import RoutePoint, RouteLine, GeoRoute
# Add points
line = line.append_point(RoutePoint(lon=3.0, lat=0.5))
route = route.append_point(RoutePoint(lon=106.0, lat=2.5))
route = route.prepend_point(RoutePoint(lon=102.0, lat=0.8))
# Remove by value
line = line.remove_point(target_point, precision=6)
route = route.remove_point(target_point)
# Merge (project onto nearest segment)
route = route.merge_point(target_point)
route = route.merge_points([p1, p2, p3])
Round coordinates
from georoutelib import round_lon, round_lat
rounded_lon = round_lon(120.123456789, precision=6) # 120.123457
rounded_lat = round_lat(35.987654321, precision=6) # 35.987654
Architecture
RoutePoint
↓
GeoCalc ← bearing / distance / interpolate / dateline split / simplify
↓
RouteLine ← flat List[RoutePoint], chainable edits, DR / time queries
↕
GeoRoute ← List[List[List[float]]], dateline-safe storage, along-route ops
↓
ECAProcessor ← emission control area intersect distances (GeoJSON polygons)
RoutePoint: single waypoint with optional metadata (speed,bearing,position_time,utc,is_important,is_pilot_station,custom_speed,hours_from_prev,suspend_hours, …).GeoCalc: stateless geodesic math utility class (all@staticmethod). Covers haversine/rhumb distance & bearing, destination projection, cross-track distance, great-circle interpolation, dateline splitting, and three simplification algorithms.RouteLine: flat, undivided sequence ofRoutePoint. Chainable immutable API (deduplicate(),simplify(),reverse(),merge_point()etc.). Supports dead-reckoning (position_at(),time_at()) and time-windowed queries.GeoRoute: multi-segment coordinate store, auto-split at the antimeridian. Providesfrom_points()(with great-circle spacing interpolation),advance_along(),min_distance_to(),remaining_route(),slice_route(),fill_point_distances(),compress_points().ECAProcessor: loads Emission Control Area polygons from GeoJSON URL or dict; computes intersect distances against routes. Includes HTTP response cache (30-min TTL).
ECA (Emission Control Area)
from georoutelib import ECAProcessor
# Load from URL (auto-cached for 30 minutes)
processor = ECAProcessor("https://example.com/eca-zones.geojson")
# Or load offline / test with raw GeoJSON dict
processor = ECAProcessor.from_geojson(url="test", data=my_geojson_dict)
# Calculate ECA intersects
results = processor.calculate_eca_intersects([
[120.0, 30.0],
[122.0, 31.0],
])
for item in results:
print(f"ECA '{item['eca']}': {item['distance']:.1f} nm")
for wp in item["waypoints"]:
print(f" WP ({wp.lon:.2f}, {wp.lat:.2f})")
# Clear HTTP cache (e.g., between tests)
ECAProcessor.clear_cache()
Accepts GeoRoute, list[RoutePoint], or raw coordinate segments as input.
Optional geojson_loader property overrides HTTP fetch (useful for testing):
processor.geojson_loader = lambda: load_my_geojson()
Logging
The library uses log + env_logger internally.
Logging is initialized automatically on module import (first import wins; subsequent calls are no-ops).
Control log level via environment variable:
# Default: warn (only warnings and errors)
RUST_LOG=warn python my_script.py
# Debug everything (module loading, HTTP requests, cache hits/misses, dateline splits)
RUST_LOG=debug python my_script.py
# Silence entirely
RUST_LOG=off python my_script.py
Log output goes to stderr by default. In Python you can also redirect:
import logging
import os
os.environ["RUST_LOG"] = "info"
import georoutelib # logging init happens here
Constants exported to Python
| Constant | Value | Description |
|---|---|---|
NM_TO_KM |
1.852 |
Nautical mile → kilometer conversion |
EPS_ZERO |
~1e-9 |
Floating-point equality tolerance |
DATELINE_EPS |
~0.01 |
Longitude tolerance for dateline detection (~180°) |
Native dependencies
| Crate | Role |
|---|---|
pyo3 0.22 |
Python bindings / extension module |
geo 0.29 |
Rhumb / haversine measures; ECA polygon predicates |
geojson 0.24 |
Parse ECA FeatureCollection |
geographiclib-rs 0.2 |
High-precision geodesic calculations |
serde_json 1 |
JSON serialization |
ureq 2.10 |
Minimal HTTP client for ECA GeoJSON fetch |
log 0.4 |
Logging facade |
env_logger 0.11 |
Log output initialization |
Publish
uv sync --extra dev
maturin build --release -o dist
ls dist/
# georoutelib-0.2.0-cp312-cp312-*.whl
Upload to PyPI:
uv publish dist/*.whl
License
MIT — see LICENSE.
Metadata
Release files for georoutelib 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| georoutelib-0.2.0-cp312-cp312-win_amd64.whl | CPython 3.12 | CPython 3.12 | Windows x86-64 | Details for georoutelib-0.2.0-cp312-cp312-win_amd64.whl |
| georoutelib-0.2.0-cp312-cp312-manylinux_2_28_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.28+ x86-64 | Details for georoutelib-0.2.0-cp312-cp312-manylinux_2_28_x86_64.whl |
| georoutelib-0.2.0-cp312-cp312-manylinux_2_28_aarch64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.28+ ARM64 | Details for georoutelib-0.2.0-cp312-cp312-manylinux_2_28_aarch64.whl |
| georoutelib-0.2.0-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl | CPython 3.12 | CPython 3.12 | macOS 10.12+ x86-64, macOS 11.0+ ARM64, macOS 10.12+ universal2 (ARM64, x86-64) | Details for georoutelib-0.2.0-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
Total release size: 9.3 MB
Release files / georoutelib-0.2.0-cp312-cp312-win_amd64.whl
| Download URL | georoutelib-0.2.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
cfccf341045e48be88e8df6a7da69ede29e403a1d992632c69668b9a1b87aaaa
|
|
BLAKE2b-256 checksum How to use checksums |
0e0e9103262d9bab0632ab97a61bfc6063acde8e87dc7ec91b146963a7aa7431
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / georoutelib-0.2.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | georoutelib-0.2.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
d97e8d99d3df48129b488c2e19a8110831206f429391de79fa60f0a988fe7daa
|
|
BLAKE2b-256 checksum How to use checksums |
a0f40cea7e480462e086091989e99899cbc5f588d67392a8352e92b29167416a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / georoutelib-0.2.0-cp312-cp312-manylinux_2_28_aarch64.whl
| Download URL | georoutelib-0.2.0-cp312-cp312-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
d9a74b63c503cee76b502eff6190f285769ab7dea78e95efbd6c20b8a431ba7d
|
|
BLAKE2b-256 checksum How to use checksums |
06bd648e5f387d64a25cb826b542b1fce5d77b6ebe3a44379c140f5ed3155db3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / georoutelib-0.2.0-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
| Download URL | georoutelib-0.2.0-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.12 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
2d90482dceb99ca6e6a754d8122e396dc01cdd99f71bb2104c457a4b1a2aa204
|
|
BLAKE2b-256 checksum How to use checksums |
351bf101044f9cd6cb35a23fb875effbd84441337cb7070b5cc8f2583e2971ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for georoutelib 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.