suaveplan/packages/geospatial/geo/geo/src/bearing/bearing.md

(no submodules)

Purpose

The bearing module computes initial bearings, destination points, and midpoints on an ellipsoid. These are the fundamental navigation primitives for routing, waypoint generation, and boundary interpolation.

Features

• bearing(from, to) — initial compass bearing in degrees (0–360)
• destination(start, bearingDeg, distanceM, ellipsoid) — computes the point reached after travelling a given distance on a given bearing
• midpoint(a, b) — geographic midpoint between two coordinates

Usage

Basic Example

import { bearing } from "@suaveplan/geo";

const brg = bearing(
    { latitude: 51.5, longitude: -0.1 },
    { latitude: 48.9, longitude: 2.3 }
);

Advanced Example

import { defineEllipsoid, destination, bearing } from "@suaveplan/geo";

const wgs84 = defineEllipsoid(6_378_137, 6_356_752.314245);
const start = { latitude: 51.5, longitude: -0.1 };
const end = destination(start, 90, 100_000, wgs84);
const back = bearing(end, start); // ~270

API Reference

bearing(from, to): number

Returns initial bearing in degrees clockwise from north.

destination(start, bearingDeg, distanceM, ellipsoid): SphericalCoord

Returns the coordinate reached after travelling distanceM metres on bearingDeg.

midpoint(a, b): SphericalCoord

Returns the geographic midpoint.

Implementation Notes

Destination uses the spherical law of cosines with the ellipsoid's semi-major axis as radius. For high-precision geodesic destinations, consumers should iterate bearing + vincentyDistance.