Geo::H...ansform(3pm)

✨ Geo::HelmertTransform — the manual, but make it make sense ✨

okay bestie so this is Geo::HelmertTransform(3pm), a Perl module that does Helmert transformations between coordinates, and it is genuinely so much less scary than the name suggests, i promise 🫶

---

💖 VERSION 💖

1.14 — that's the one, that's the version, no cap.

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste energy:

use Geo::HelmertTransform;

my ($lat, $lon, $h) = ...; # from OS map
my $airy1830 = Geo::HelmertTransform::datum('Airy1830');
my $wgs84 = Geo::HelmertTransform::datum('WGS84');

($lat, $lon, $h)
    = Geo::HelmertTransform::convert_datum($airy1830, $wgs84,
                                            $lat, $lon, $h);

literally that's it. you grab a datum, you grab another datum, you hand it your coords, it hands them back in the new datum. iconic behavior honestly 💅

---

🦋 DESCRIPTION 🦋

so the whole point of this module: it transforms geographical coordinates between different datums.

here's the lore. we usually describe geographical points as polar coordinates — latitude, longitude and altitude — referenced to a "datum ellipsoid", which is basically a shape we use to approximate the Earth's geoid. and the way that the latitude, longitude and altitude of one single physical point change depending on which datum ellipsoid you're using? yeah. not it. because unfortunately a bunch of ellipsoids are in everyday use, so you constantly have to transform geographical coordinates between different datum ellipsoids. it's giving "why is there more than one, bestie" 😭

two different datum ellipsoids can differ in where their centers are, or in their shape — and there might even be an angle between their equatorial planes, or between the meridians that longitude gets measured relative to. the Helmert Transform, which this module implements, is a linear transformation of coordinates between pairs of datum ellipsoids, in the limit of small angles of deviation between them.

translation: it's the small-angle approximation version, bestie. don't come at it with huge deviations.

---

🎀 CONVENTIONS 🎀

• Latitude is in degrees, positive-north.
• Longitude is in degrees, positive-east.
• Heights (ellipsoid) and cartesian coordinates are in meters.

that's it, that's the whole section, but you needed it, i promise 🙈

---

🌈 FUNCTIONS 🌈

rad_to_deg RADIANS

converts RADIANS to degrees. little conversion moment, very demure 🎀

deg_to_rad DEGREES

converts DEGREES to radians. the other direction, as the name strongly implies.

geo_to_xyz DATUM LAT LON H

give it the geographical coordinates (LAT, LON, H) in the given DATUM and it returns the Cartesian (X, Y, Z) coordinates for them. 🧚

xyz_to_geo DATUM X Y Z

the reverse glow-up: returns the geographical (LAT, LON, H) coordinates for the Cartesian coordinates (X, Y, Z) in the given DATUM. heads up — this is an iterative procedure. it's not doing one clean solve, it's looping its way there, and you should know that going in.

convert_datum D1 D2 LAT LON H

the main character of this whole module honestly 👑 give it geographical coordinates (LAT, LON, H) in datum D1 and it returns the corresponding coordinates in datum D2. caveat bestie: this assumes that the transformations are small, and it always converts via WGS84 — like, it doesn't go direct, it routes through WGS84 every single time. iykyk.

datum NAME

returns the datum of the given NAME. currently implemented are these three and only these three:

• Airy1830 — the 1830 Airy ellipsoid, which the British Ordnance Survey's National Grid is referenced to.
• Airy1830Modified — the modified 1830 Airy ellipsoid, which the Irish Grid is referenced to (as used by Ordnance Survey Ireland and Ordnance Survey Northern Ireland). also known as the Ireland 1975 datum. two names, one ellipsoid, we love a rebrand 💖
• WGS84 — the global datum used for GPS. the famous one. the celebrity.

---

🔥 SEE ALSO 🔥

• A guide to coordinate systems in Great Britain, http://www.gps.gov.uk/guidecontents.asp
• Making maps compatible with GPS, http://www.osni.gov.uk/downloads/Making%20maps%20GPS%20compatible.pdf

go read them, they're the receipts for everything above 📚

---

💜 AUTHOR AND COPYRIGHT 💜

Written by Chris Lightfoot, team@mysociety.org 💌

Copyright (c) UK Citizens Online Democracy.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. so go off, remix it, slay responsibly ✨

---

ngl the license here is the chillest one possible and we stan that for it 🌸

and that's a wrap bestie — perl v5.36.0, dated 2022-11-20, and this whole thing was Geo::HelmertTransform(3pm). take care of your datums, drink water, and remember: always converting via WGS84 💅🦋