geodesy for Tessel

A Tessel library

Geodesy for Tessel apps.

Exact distances, azimuths and areas on the ellipsoid by Karney's algorithms. Map projections and datum shifts that agree with PROJ to the nanometre for all 5230 EPSG projected systems it has, the Philippine PRS92 and Luzon 1911 zones among them. PROJ strings and .prj files, grid-to-ground factors, degrees as text and MGRS.

tessel add geodesy

MIT licence · Tessel 0.10 or later · no dependencies

Manila to Los Angeles on a Web Mercator map: the geodesic (11 759 km) arcs north, the rhumb line (12 363 km) is straight

What it does

The pictures are drawn with the chart library by the examples that come with geodesy.

The geodesic and the rhumb line from Manila to Los Angeles on a Mercator map

Geodesics and rhumb lines

The shortest path between any two points, antipodes included, with its azimuths, points along it and the area under it: Karney's algorithms, good to 15 nm. Rhumb lines hold one compass course.

let r = geodesy.inverse(14.5995, 120.9842, 10.3157, 123.8854)
print(r.distance)                    // 569218.2057… m (Manila to Cebu)
let (s, azimuth) = geodesy.rhumb(14.5995, 120.9842, 34.0522, -118.2437)
Grid scale factor at 14.6°N across UTM zones 50 to 52 and PRS92 zones I to V

Grid to ground

The scale factor and meridian convergence of any projected system at a point, as PROJ's get_factors: for reducing measured distances to the grid. PRS92's 2° zones stay within 0.0001 of true scale.

let zone3 = geodesy.epsg(3123) ?? geodesy.wgs84Crs()
let (k, _, convergence) = zone3.gridFactors(121.5, 14.6)

EPSG codes, PROJ strings and .prj files

578 geographic and 5230 projected EPSG systems, with the shift to WGS84 that PROJ itself picks. Or read a PROJ string, or the WKT in a shapefile's .prj (GDAL's, Esri's or WKT2): an Esri .prj with no shift finds its datum's by name.

let c = try geodesy.crs("EPSG:3123")
let d = try geodesy.fromProj("+proj=utm +zone=51 +datum=WGS84")
let e = try geodesy.fromWkt(readFile("lots.prj") ?? "")
let (x, y) = geodesy.transform(500000.0, 1600000.0, from: c, to: d)
writeFile(path: "out.prj", text: c.wkt())

Areas, degrees and MGRS

The area of a lot from GPS corners, positive counterclockwise. Degrees read the ways people write them and written back with rounding that carries. MGRS both ways, polar areas included.

let (area, perimeter) = geodesy.polygonArea(lats, lons)
let pos = try geodesy.readLatLon("14°35'58.2\"N 120°59'03.1\"E")
print(geodesy.formatLatLon(14.5995, 120.9842))   // 14°35'58.20"N 120°59'03.12"E
print(geodesy.toMGRS(14.5995, 120.9842))         // 51PTS8284814992

In a program

Latitudes and longitudes in degrees, lengths in metres, and points as (x, y): easting and northing, or longitude and latitude, whatever order EPSG lists the axes in.

From GPS to a Philippine grid

WGS84 to PRS92 zone 3 through EPSG's datum shift, the grid factors there, and the position as text.

import geodesy

fn main() {
    let wgs = geodesy.wgs84Crs()
    let zone3 = geodesy.epsg(3123) ?? wgs          // PRS92 / Philippines zone 3
    let (e, n) = geodesy.transform(120.97695, 14.58285, from: wgs, to: zone3)
    print("{e} {n}")                             // 497369.807 1612820.042

    let (lon, lat) = zone3.toLonLat(e, n)
    let (k, _, convergence) = zone3.gridFactors(lon, lat)
    print("k = {k}, convergence {convergence}°") // k = 0.99995009, -0.0061°

    print(geodesy.formatLatLon(14.58285, 120.97695))
    print(geodesy.toMGRS(14.58285, 120.97695))   // 51PTS8205113157
}

A lot from its corners

The area and perimeter of a polygon of geodesics, and the distance and bearing of each side, for a survey report.

import geodesy

fn main() {
    let lats: [Float] = [14.58285, 14.58285, 14.58375, 14.58375]
    let lons: [Float] = [120.97695, 120.97788, 120.97788, 120.97695]
    let (area, perimeter) = geodesy.polygonArea(lats, lons)
    print("{area} m², {perimeter} m")            // 9979.24 m², 399.59 m
    for k in 0..lats.count {
        let j = (k + 1) % lats.count
        let r = geodesy.inverse(lats[k], lons[k], lats[j], lons[j])
        print("{k + 1}–{j + 1}: {r.distance} m at {r.azimuth1}°")
    }
}

Projections and datums

ProjectionEPSG systems
Transverse Mercator (Krüger's series, exact to nanometres), UTM, UPSMost national and state grids, the PRS92 and Luzon 1911 zones
Lambert conformal conic: 1SP, 2SP, variant BState planes, Lambert-93, national grids
Mercator, Web MercatorEPSG:3857 and web maps
Albers equal-area, Lambert azimuthal equal-areaContinental and statistical maps
Stereographic: polar, oblique, equatorial; oblique on the Gauss spherePolar maps, the Netherlands, Romania, New Brunswick
Cassini–Soldner (and EPSG's hyperbolic variant), equidistant cylindricalOld cadastral grids
Hotine oblique Mercator (variants A and B, two-point), Swiss oblique Mercator, LabordeMalaysia and Borneo RSO, Michigan, Switzerland, Madagascar
Krovak (both orientations), American polyconic, Colombia urban, New Zealand Map GridCzechia and Slovakia, Brazil, Colombian cities, New Zealand
Azimuthal equidistant (and Guam's), cylindrical equal-area, Equal EarthPacific islands, EASE-Grid, world maps

Datum shifts are 7-parameter Helmert transformations through WGS84, the one PROJ picks for each datum from the EPSG database (418 of 578), with PROJ's own ellipsoids and prime meridians.

Checked against GeographicLib and PROJ

Python programs ask GeographicLib, PROJ (through pyproj), SciPy and the mgrs package for the answers to thousands of cases, and geodesy has to agree with every one.

142,230checks in the library's tests, all passing
5,230EPSG projected systems, every one checked forward and back
0.1 µmthe largest difference from PROJ in any projection
0.13 sfor 100,000 transforms with a datum shift

Reference

On the ellipsoid

FunctionGives
inverse(lat1, lon1, lat2, lon2, on:), distance(…)The shortest path: distance, azimuths at each end, arc, reduced length, scales, area to the equator.
direct(lat, lon, azimuth:, distance:)The point that far along a geodesic.
line(lat, lon, azimuth:), lineBetween(…)A line: position(distance), points(n).
polygonArea(lats, lons), trackLength(lats, lons)Area and perimeter of a polygon; length of a track.
rhumb(…), rhumbDirect(…), rhumbPoints(…)Rhumb lines.
wgs84(), ellipsoid(a:, f:), ellipsoidNamed(name)Ellipsoids: WGS84, your own, or PROJ's 46.

Coordinate systems

Function or methodGives
epsg(code), crs(text), fromProj(text), fromWkt(text)A Crs from an EPSG code, a PROJ string or WKT.
utm(zone:, south:), utmFor(lat, lon), utmZone(lat, lon), wgs84Crs()WGS84 systems.
transform(x, y, from:, to:), transformAll(…)Points from one system to another.
c.toWGS84(x, y), c.fromWGS84(lon, lat), c.toLonLat, c.fromLonLatTo and from latitude and longitude.
c.gridFactors(lon, lat)Meridian and parallel scale, and convergence.
c.proj(), c.wkt(), epsgCodes(search:)Writing systems out, and finding codes by name.

Text

FunctionGives
readAngle(text), readLatLon(text)Degrees and positions from text.
formatAngle(degrees, style:, decimals:, hemispheres:), formatLatLon(lat, lon, …)Degrees as text: DMS, DM or decimal.
toMGRS(lat, lon, precision:), fromMGRS(text, center:)MGRS references.

The geodesic algorithms are C. F. F. Karney's (GeographicLib, MIT). The EPSG data are from the EPSG Geodetic Parameter Dataset (© IOGP), as PROJ ships it.