Skip to main content

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.3.0
import import georoutelib

Requires Python 3.12+.

Immutable-by-design: RouteLine and GeoRoute follow 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 of RoutePoint. 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. Provides from_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.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for georoutelib 0.3.0
File Actions
georoutelib-0.3.0-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for georoutelib-0.3.0-cp312-cp312-win_amd64.whl
georoutelib-0.3.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.3.0-cp312-cp312-manylinux_2_28_x86_64.whl
georoutelib-0.3.0-cp312-cp312-manylinux_2_28_aarch64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ ARM64 Details for georoutelib-0.3.0-cp312-cp312-manylinux_2_28_aarch64.whl
georoutelib-0.3.0-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl CPython 3.12 CPython 3.12 macOS 11.0+ ARM64, macOS 10.12+ universal2 (ARM64, x86-64), macOS 10.12+ x86-64 Details for georoutelib-0.3.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.3.0-cp312-cp312-win_amd64.whl

Download URL georoutelib-0.3.0-cp312-cp312-win_amd64.whl
Size 1.9 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
e2bd888e64ea85a7e24dfe1f9bb949b09d8de9710e9d5d3634fb6650cac37af5
BLAKE2b-256 checksum
How to use checksums
1f8c05c039ca8bccaa7acef3c251a18658df648b7daebb0b0d7a32c8e71b7a30
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.3.0-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL georoutelib-0.3.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
a3d0028dbff028f1117e063efa7cec45a75a26fd41d8abd1e8f8f124cb97bd22
BLAKE2b-256 checksum
How to use checksums
673689833fd69bc234507d1f13351241a0ef99314eae4e08aca1ec0c9eba804a
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.3.0-cp312-cp312-manylinux_2_28_aarch64.whl

Download URL georoutelib-0.3.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
1fe4b0f79df2b0c28be4c6271610f64d3481bef89c08be89e58d4475ce15bf1e
BLAKE2b-256 checksum
How to use checksums
ca9b09f9fea7e1857ce4c22a3b209bd7a3ffa68f61d99be06bb2ee37868f6a49
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.3.0-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

Download URL georoutelib-0.3.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
075fec010d85efb557d364bce883e3b133f673d71c38bb465644780500b7ed00
BLAKE2b-256 checksum
How to use checksums
ba707a8ce9cd6940cf8d0fdf4e88e4f706ddd1a31eeb237b57e4484623695b1e
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.3.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page