GeoMath.h File Reference

#include <math.h>
#include <float.h>

Include dependency graph for GeoMath.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	M_PI   3.14159265358979323846

Functions
static bool	geoCoordinatesValid (double lat, double lng)
	Validates a GPS coordinate pair before it is allowed to touch timing state.
static double	geoHaversine (double lat1, double lon1, double lat2, double lon2)
static double	geoHaversine3D (double prevLat, double prevLng, double prevAlt, double currentLat, double currentLng, double currentAlt)
static bool	geoInsideLineThreshold (double thresholdMeters, double driverLat, double driverLon, double crossingPointALat, double crossingPointALon, double crossingPointBLat, double crossingPointBLon)
	Hypotenuse-based crossing-zone membership test.
static bool	geoIsFinite (double v)
	Checks a value is a real, finite number (not NaN, not +/-infinity).
static double	geoPointLineSegmentDistance (double pointX, double pointY, double startX, double startY, double endX, double endY)
	Shortest distance from a point to a line segment, in meters.
static int	geoPointOnSideOfLine (double driverLat, double driverLng, double pointALat, double pointALng, double pointBLat, double pointBLng)
	Determines which side of an (infinite) line a point is on.

Variables
static constexpr double	GEOMATH_KMH_TO_MPH = 1.0 / GEOMATH_MPH_TO_KMH
static constexpr double	GEOMATH_KNOTS_TO_KMH = 1.852
static constexpr double	GEOMATH_METERS_TO_FEET = 1.0 / 0.3048
static constexpr double	GEOMATH_MPH_TO_KMH = 1.609344
static const double	GEOMATH_RADIUS_EARTH = 6371.0 * 1000

Macro Definition Documentation

M_PI

#define M_PI   3.14159265358979323846

Geographic math utilities shared across DovesLapTimer, WaypointLapTimer, and CourseDetector.

These are static inline functions so any class can include this header without needing a separate .cpp or an instance of DovesLapTimer.

DovesLapTimer retains its own haversine()/haversine3D() public methods as thin wrappers for backward compatibility.

Function Documentation

geoCoordinatesValid()

static bool geoCoordinatesValid ( double  lat, double  lng  )

inlinestatic

Validates a GPS coordinate pair before it is allowed to touch timing state.

Rejects NaN/infinity (routine output from NMEA parsers during fix loss), out-of-range latitudes/longitudes, and the exact (0, 0) "null island" fix that parsers emit while the receiver has no solution. A single such fix would otherwise permanently poison odometers and distance tracking.

Parameters

lat	Latitude in decimal degrees.
lng	Longitude in decimal degrees.

Returns

True if the pair is a plausible real-world coordinate.

geoHaversine()

static double geoHaversine ( double  lat1, double  lon1, double  lat2, double  lon2  )

inlinestatic

geoHaversine3D()

static double geoHaversine3D ( double  prevLat, double  prevLng, double  prevAlt, double  currentLat, double  currentLng, double  currentAlt  )

inlinestatic

geoInsideLineThreshold()

static bool geoInsideLineThreshold ( double  thresholdMeters, double  driverLat, double  driverLon, double  crossingPointALat, double  crossingPointALon, double  crossingPointBLat, double  crossingPointBLon  )

inlinestatic

Hypotenuse-based crossing-zone membership test.

Forms a right triangle from the line's width and thresholdMeters; the hypotenuse is the effective proximity bound measured from the driver to EACH line endpoint. See DETECTION.md for why this beats a plain distance-to-line check. Extracted from DovesLapTimer::insideLineThreshold (which delegates here with its configured threshold).

geoIsFinite()

static bool geoIsFinite ( double  v )

inlinestatic

Checks a value is a real, finite number (not NaN, not +/-infinity).

Implemented without isnan()/isinf() because their availability as unqualified names differs between Arduino cores and host <cmath>.

Parameters

v	Value to check.

Returns

True if v is finite, false for NaN or infinity.

geoPointLineSegmentDistance()

static double geoPointLineSegmentDistance ( double  pointX, double  pointY, double  startX, double  startY, double  endX, double  endY  )

inlinestatic

Shortest distance from a point to a line segment, in meters.

Inputs are decimal-degree coordinates; the projection onto the segment happens in degree space, but every return path measures the final distance via haversine, so the result is in meters. Extracted from DovesLapTimer::pointLineSegmentDistance (which delegates here).

geoPointOnSideOfLine()

static int geoPointOnSideOfLine ( double  driverLat, double  driverLng, double  pointALat, double  pointALng, double  pointBLat, double  pointBLng  )

inlinestatic

Determines which side of an (infinite) line a point is on.

Cross-product sign test in degree space. Extracted from DovesLapTimer::pointOnSideOfLine so CrossingEngine and SprintTimer can share it without a timer instance; the member method delegates here.

Returns

1 / -1 for the two sides, 0 if exactly on the line (matches CROSSING_LINE_SIDE_B / _A / _EXACT).

Variable Documentation

GEOMATH_KMH_TO_MPH

constexpr double GEOMATH_KMH_TO_MPH = 1.0 / GEOMATH_MPH_TO_KMH

staticconstexpr

GEOMATH_KNOTS_TO_KMH

constexpr double GEOMATH_KNOTS_TO_KMH = 1.852

staticconstexpr

GEOMATH_METERS_TO_FEET

constexpr double GEOMATH_METERS_TO_FEET = 1.0 / 0.3048

staticconstexpr

GEOMATH_MPH_TO_KMH

constexpr double GEOMATH_MPH_TO_KMH = 1.609344

staticconstexpr

GEOMATH_RADIUS_EARTH

const double GEOMATH_RADIUS_EARTH = 6371.0 * 1000

static