georoutelib 0.1.0

Maritime route geometry: GeoRoute, RouteLine, GeoCalc (Rust core)

georoutelib

Maritime route calculation: waypoints → route geometry → along-route analysis and editing.

PyPI	georoutelib 0.1.0
import	georoutelib

Requires Python 3.12+.

Shared references: RouteLine and GeoRoute do not copy the list you pass in. Edits (merge_point, remove_point, deduplicate, simplify, …) mutate that same list in place. To keep the original data, pass a copy: RouteLine(points.copy()) or copy.deepcopy(segments).

Install

pip install georoutelib

Development:

uv sync --extra dev
uv run pytest

Package layout

src/georoutelib/
├── __init__.py          # public exports + __version__
├── route_point.py       # RoutePoint, round_lon/lat, COORD_PRECISION
├── geo_calc.py          # GeoCalc — bearing, distance, interpolation, ±180° split
├── route_line.py        # RouteLine — flat RoutePoint polyline
└── geo_route.py         # GeoRoute — GeoMultiLine storage (cross-dateline)

Units

Quantity	Unit
Distance	nautical miles (nm)
Speed	knots (kts)
Bearing	degrees (0–360°)
Time	hours (h) or timestamp (Unix 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 = GeoCalc.bearing(a, b, rhumb=True)

Build a route from points

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),
]

route = GeoRoute.from_points(points, spacing=200.0)
print(route.segments)  # GeoRoute: List[List[List[float]]], split at ±180° if needed

Flat route operations

from georoutelib import RouteLine, RoutePoint

points = [RoutePoint(lon=0, lat=0), RoutePoint(lon=1, lat=1), RoutePoint(lon=2, lat=0)]
route = RouteLine(points).deduplicate().simplify()

total_nm = route.total_distance()
center = route.center()
bbox = route.bbox()  # [minLon, minLat, maxLon, maxLat]
segments = route.to_multi_line()

Advance along a route

from georoutelib import RoutePoint, GeoRoute

route = GeoRoute.from_points(points, spacing=200.0)
current = RoutePoint(lon=104.0, lat=1.3)
result = route.advance_along(current, dist=50.0)
next_pos = result["point"]
remaining = result["remaining"]   # segments ahead
traveled = result["traveled"]     # points already passed

Minimum distance to route

result = route.min_distance_to(RoutePoint(lon=104.2, lat=1.4))
# {"min_dist": float, "seg_index": int, "min_index": int}

Architecture

RoutePoint
    ↓
GeoCalc          ← bearing / distance / interpolate / dateline split
    ↓
RouteLine     ← flat List[RoutePoint], chainable edits, DR
    ↕
GeoRoute         ← List[List[List[float]]], dateline-safe storage, along-route ops

• RouteLine: flat, undivided RoutePoint list (not a GeoRoute sub-segment); position_at / time_at, point queries.
• GeoRoute: raw multi-segment coordinates split at the antimeridian; from_points, advance_along, min_distance_to, remaining_route, fill_point_distances.
• GeoCalc: geodesic math via pyturf + shapely (rhumb vs great-circle selectable).

Planning API reference (Chinese): docs/route-planning.md.

Dependencies

Package	Role
pyturf	Rhumb / great-circle bearing, distance, destination, line intersect, center/bbox
shapely	Great-circle polyline × dateline intersection

Publish

Build wheel from source (maturin，仅 wheel，无 sdist 源码包):

uv sync --extra dev
maturin build --release -o dist
ls dist/
# georoutelib-0.1.0-cp312-cp312-*.whl

Upload to PyPI:

uv publish dist/*

License

MIT — see LICENSE.