app.coordinates_utils module#

Geodesic utilities for great-circle calculations on a spherical Earth model.

This module implements the classic “destination point” formula to derive a new latitude/longitude from a start point, a great-circle distance in kilometers, and a bearing measured clockwise from geographic north.

Warnings#

  • The underlying spherical approximation is sufficient for short distances and most grid seeding use cases. For long-haul routes or high-latitude travel, consider ellipsoidal solutions (e.g., Vincenty) to reduce error.

See Also#

app.coordinates_manager

Seeds surrounding points using this computation.

app.coordinates_setup

Validates inputs and orchestrates seeding/listing.

Notes#

  • Primary role: compute destination coordinates using spherical trigonometry and provide small helpers for input validation and longitude normalization.

  • Key dependencies: standard library math and a stable mean Earth radius constant; consumed by app.coordinates_manager and app.coordinates_setup.

  • Invariants: latitude must be within [-90, 90] and longitude within [-180, 180]. Distances are non-negative kilometers. Longitudes are normalized to [-180, 180].

Examples#

>>> # Move ~1 km to the north from (0, 0)
>>> lat, lon = calculate_destination_point(0.0, 0.0, 1.0, 0.0)
>>> isinstance(lat, float) and isinstance(lon, float)
True