Navigation and Bearings

/**
 * Calculate great circle bearing between two points
 * @param origin - Starting point coordinate
 * @param dest - Destination point coordinate
 * @returns Bearing in degrees (0-360), where 0° is North
 */
function getGreatCircleBearing(
  origin: GeolibInputCoordinates, 
  dest: GeolibInputCoordinates
): number;

import { getGreatCircleBearing } from "geolib";

// Calculate bearing from Berlin to Paris
const berlin = { latitude: 52.5200, longitude: 13.4050 };
const paris = { latitude: 48.8566, longitude: 2.3522 };

const bearing = getGreatCircleBearing(berlin, paris);
console.log(bearing); // e.g., 243.7 (degrees, SW direction)

// Calculate bearing for navigation
const start = { lat: 51.515, lng: 7.453 };
const destination = { lat: 51.520, lng: 7.460 };
const navBearing = getGreatCircleBearing(start, destination);
console.log(`Head ${navBearing.toFixed(1)}° from start`);

/**
 * Calculate rhumb line bearing between two points
 * @param origin - Starting point coordinate
 * @param dest - Destination point coordinate
 * @returns Bearing in degrees (0-360), where 0° is North
 */
function getRhumbLineBearing(
  origin: GeolibInputCoordinates, 
  dest: GeolibInputCoordinates
): number;

import { getRhumbLineBearing } from "geolib";

// Calculate rhumb line bearing (constant compass heading)
const start = { latitude: 51.515, longitude: 7.453 };
const end = { latitude: 51.520, longitude: 7.460 };

const rhumbBearing = getRhumbLineBearing(start, end);
console.log(rhumbBearing); // Constant compass bearing

/**
 * Convert bearing to 16-point compass direction
 * @param origin - Starting point coordinate
 * @param dest - Destination point coordinate
 * @param bearingFn - Optional custom bearing function (default: getRhumbLineBearing)
 * @returns Compass direction string (N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW)
 */
function getCompassDirection(
  origin: GeolibInputCoordinates, 
  dest: GeolibInputCoordinates,
  bearingFn?: (
    origin: GeolibInputCoordinates, 
    dest: GeolibInputCoordinates
  ) => number
): string;

import { getCompassDirection, getGreatCircleBearing } from "geolib";

// Get compass direction
const from = { latitude: 51.515, longitude: 7.453 };
const to = { latitude: 51.520, longitude: 7.460 };

const direction = getCompassDirection(from, to);
console.log(direction); // e.g., "NNE" (North-Northeast)

// Using great circle bearing instead of rhumb line
const gcDirection = getCompassDirection(from, to, getGreatCircleBearing);
console.log(gcDirection); // Direction using great circle bearing

// Navigation instructions
console.log(`Head ${direction} towards destination`);

/**
 * Convert bearing to 8-point compass direction
 * @param origin - Starting point coordinate
 * @param dest - Destination point coordinate
 * @returns Rough compass direction (N, NE, E, SE, S, SW, W, NW)
 */
function getRoughCompassDirection(
  origin: GeolibInputCoordinates, 
  dest: GeolibInputCoordinates
): string;

import { getRoughCompassDirection } from "geolib";

// Get simplified compass direction
const from = { latitude: 51.515, longitude: 7.453 };
const to = { latitude: 51.520, longitude: 7.460 };

const roughDirection = getRoughCompassDirection(from, to);
console.log(roughDirection); // e.g., "NE" (Northeast)

// Simple navigation guidance
console.log(`Go ${roughDirection}`);

/**
 * Compute destination point from start point, distance, and bearing
 * @param start - Starting point coordinate
 * @param distance - Distance to travel in meters
 * @param bearing - Bearing in degrees (0° = North)
 * @param radius - Earth radius in meters (default: 6371000)
 * @returns Destination point coordinates
 */
function computeDestinationPoint(
  start: GeolibInputCoordinates, 
  distance: number, 
  bearing: number, 
  radius?: number
): { latitude: number; longitude: number };

import { computeDestinationPoint } from "geolib";

// Find point 1km north of current location
const currentLocation = { latitude: 51.515, longitude: 7.453 };
const distance = 1000; // 1km in meters
const bearing = 0; // 0° = North

const destination = computeDestinationPoint(currentLocation, distance, bearing);
console.log(destination); // { latitude: 51.524, longitude: 7.453 }

// Find point 500m northeast
const neDestination = computeDestinationPoint(
  currentLocation, 
  500,    // 500 meters
  45      // 45° = Northeast
);
console.log(neDestination);

// Create waypoints along a route
const waypoints = [];
const startPoint = { latitude: 51.515, longitude: 7.453 };
const stepDistance = 100; // 100m between waypoints
const routeBearing = 90; // East

for (let i = 1; i <= 10; i++) {
  const waypoint = computeDestinationPoint(
    startPoint, 
    stepDistance * i, 
    routeBearing
  );
  waypoints.push(waypoint);
}
console.log(waypoints); // 10 waypoints, 100m apart, heading east

/**
 * Calculate speed between two timestamped coordinates
 * @param start - Starting coordinate with timestamp
 * @param end - Ending coordinate with timestamp
 * @param distanceFn - Optional distance function (default: getDistance)
 * @returns Speed in meters per second
 */
function getSpeed(
  start: GeolibInputCoordinatesWithTime, 
  end: GeolibInputCoordinatesWithTime, 
  distanceFn?: (
    from: GeolibInputCoordinates, 
    to: GeolibInputCoordinates
  ) => number
): number;

interface GeolibInputCoordinatesWithTime extends GeolibInputCoordinates {
  time: number; // Unix timestamp in milliseconds
}

import { getSpeed, convertSpeed } from "geolib";

// Calculate vehicle speed
const start = {
  latitude: 51.515,
  longitude: 7.453,
  time: Date.now()
};

// After 10 seconds of travel
const end = {
  latitude: 51.516,
  longitude: 7.454,
  time: Date.now() + 10000 // 10 seconds later
};

const speedMps = getSpeed(start, end);
console.log(speedMps); // Speed in meters per second

// Convert to km/h
const speedKmh = convertSpeed(speedMps, "kmh");
console.log(`Speed: ${speedKmh.toFixed(1)} km/h`);