Docs / Core / Geodesy

Geodesy on the globe (Spherical)

Distance, heading, area and interpolation, with the same names and the same results on all three platforms. Nothing depends on a map SDK utility, so swapping providers never changes a number — and the SDK own hit testing and great-circle rendering use exactly these functions.

ELLIPSOID

WGS84

SEMI-MAJOR

6,378,137 m

FLATTENING

1 / 298.257…

UNIT

metres / degrees

View demoPolygon Geodesic · React ↗

Platform

01 · The basics

The everyday functions live under Spherical. Distances come back in metres, headings in degrees clockwise from true north, areas in square metres. Inputs are plain coordinates — no projection or zoom involved.

Function

Description

computeDistanceBetween

Distance between two points, in metres.

computeHeading

Heading from one point to another (−180…180°).

computeOffset

The point a given distance and heading away — used to build circles and rings.

computeOffsetOrigin

Solves the origin back from a destination, distance and heading.

computeLength

Total length along a list of points, in metres — route distances.

computeArea / computeSignedArea

Area enclosed by a closed ring, in square metres; the signed variant also tells you the winding.

interpolate

Interpolates between two points along the great circle.

Planar.interpolate

Interpolates linearly in lat/lng (a method of the straight-line Planar model), taking the short side across the date line.

com.mapconductor.core.spherical

val meters = Spherical.computeDistanceBetween(from, to)
val heading = Spherical.computeHeading(from, to)

// 円の外周マーカーを8方向に置く
val ring = (0 until 8).map { i ->
    Spherical.computeOffset(center, 3_000.0, i * 45.0)
}

val routeMeters = Spherical.computeLength(routePoints)
val areaSqMeters = Spherical.computeArea(polygonPoints)

MapConductorCore · spherical

let meters = Spherical.computeDistanceBetween(from: from, to: to)
let heading = Spherical.computeHeading(from: from, to: to)

let ring = (0..<8).map { i in
    Spherical.computeOffset(origin: center, distance: 3_000.0, heading: Double(i) * 45.0)
}

let routeMeters = Spherical.computeLength(routePoints)

@mapconductor/js-sdk-core

import { computeDistanceBetween, computeOffset, computeLength } from '@mapconductor/js-sdk-core';

const meters = computeDistanceBetween(from, to);

// 中心から 3km、45度きざみのリング
const ring = Array.from({ length: 8 }, (_, i) =>
  computeOffset({ origin: center, distance: 3000, heading: i * 45 }));

const routeMeters = computeLength(routePoints);

02 · Sphere and ellipsoid

Two levels of accuracy are available: a spherical model treating the Earth as a perfect sphere, and a geodesic model on the WGS84 ellipsoid.

Both use WGS84 constants (equatorial radius 6,378,137 m, flattening 1/298.257223563). The same constants and formulas on all three platforms mean identical inputs give identical outputs.

Spherical

Spherical — fast and accurate enough

Haversine distance plus spherical trigonometry for headings and interpolation. Up to a few hundred kilometres the error is negligible in practice, and it is cheap to compute.

For: distance readouts · headings · rings · areas · hit testing

WGS84Geodesic

Ellipsoidal — true geodesics

Computes on WGS84 geodesics via an iterative (Vincenty-family) solution. It exposes the same method set as Spherical, so you can swap Spherical (globe) for WGS84Geodesic (WGS84) without changing call sites. Area is computed on the ellipsoid (authalic sphere).

For: long-haul routes · precise distance, heading and area

FALLBACK

Falls back to the sphere when iteration fails

The iterative solution may not converge for near-antipodal pairs. It then falls back to the spherical result, so you never get 0 or NaN and never need error handling at the call site.

03 · Bridging to the screen

These convert screen-based amounts — a fingertip, a 16 px margin — into geographic distance. Zoom and latitude are part of the conversion, so the feel stays the same wherever you are and however far you are zoomed in.

calculateMetersPerPixel

Metres per pixel at a given zoom and latitude.

expandBounds

Grows a bounding box outwards by metres — handy for fetching slightly more than the viewport.

Figure · how hit testing uses these

The configured fingertip size (logical units) is turned into screen pixels.

calculateMetersPerPixel converts that into a tolerance in metres for the current zoom and latitude.

That tolerance is used to test the distance to lines and shapes in geographic coordinates.

Because of this, lines stay equally easy to tap at any zoom, and the result is identical on every provider.

04 · For lines and shapes

These make polyline and polygon rendering and hit testing identical across providers. They are the very functions the SDK uses internally.

Function

Description

WGS84Geodesic.createInterpolatePoints

Densifies a path along the geodesic — the point list handed to engines that cannot draw curves.

Planar.createInterpolatePoints

Densifies along straight lat/lng lines instead. Same name, different namespace.

WGS84Geodesic.pointOnLineOrNull

Returns the closest point on a geodesic segment within a tolerance — hit testing for curves.

Planar.pointOnLineOrNull

Tests whether a point is within a tolerance of a straight segment.

splitByMeridian

Splits a path that crosses 180° at the boundary. A top-level function, not part of a namespace.

closestPointOnSegment

Finds the closest point on a segment; also top-level.

createInterpolatePoints and pointOnLineOrNull exist under both WGS84Geodesic and Planar with identical names, so swapping the namespace is all it takes to move between the geodesic and straight-line models.

CONSISTENCY

Identical inputs, identical results

The Kotlin, Swift and TypeScript implementations share formulas and constants, so distances and areas never disagree between platforms.

PUBLIC API

Yours to use as well

The core computation functions are not internal-only — use them directly for route distances, radius maths or your own hit testing. Every function listed on this page is present on all three platforms.