A quick primer on geodesy concepts
Coordinates are hard. If they were easy, you wouldn’t have needed to find this library. The below is intended as a quick guide to the basic concepts involved in geodesy (the science of measuring the Earth’s shape) intended to allow you to more fully understand the terminology used within the library. It is not necessary to read or memorise this documentation section to use the library, it’s just here for educational purposes.
What is a coordinate?
A coordinate (or set of coordinates) is a reference to a particular point on the Earth, or in the near vicinity of it (e.g. the location of an aeroplane flying from A to B can still be identified by coordinates). Points are identified by a set of distances (and direction) from a known starting point. A simple example would be a pirate map saying that the buried treasure is 200 paces south-east of the old palm tree. Modern mapping doesn’t measure distances from random trees, but the principle is the same - pick a starting point and measure out distance(s) in the specified direction(s).
But how can someone find that starting point to start counting from? How does a treasure hunter find the right palm tree (or even the right town?). You could measure out as a set of distances from a different tree, but that leads to circularity very quickly. The answer is to special-case the starting point and to define it differently in terms of the physical characteristics of the Earth. Pirate maps have pictures of coves and other local landmarks for this purpose, serious mapping uses science.
Technically, a datum is a set of described measurements to be performed on the Earth. The results of the measurements give the known starting point. Sometimes, when repeating what in theory are the same measurements different results are obtained - this can be because of simple error, or can also be because newer measurements are able to use more precise measuring techniques. Where this occurs, each set of measurements is termed a new realisation of the same datum.
Most datums have only ever had 1 realisation made, and therefore the word datum usually refers to the results rather than the method.
There are two types of datum: geodetic and vertical. The next few sections relate to the geodetic kind, vertical datums are covered further below.
Before dividing the world into latitudes and longitudes or whatever other system is used, the first thing that needs to be agreed on is the shape and size of the planet. Otherwise, my latitude/longitude grid1 and your latitude/longitude grid won’t match up.
Although the Earth is normally pictured as spherical, it is actually very slightly wider at the equator than between the north and south poles making it more elliptical in nature. A 3D ellipse is called an ellipsoid. The Earth is not a perfect ellipsoid, it’s more lumpy and bumpy than that but for the purposes of actually being able to perform any calculations at all, slight distortions from reality are usually accepted.
However, historically there has not been a unified view of what those distortions should be. Nowadays, many (most?) coordinates are generated by devices making use of GPS and other such similar global satellite systems. By their very nature, needing to work worldwide, a great deal of effort was made to pick an ellipsoid that minimised distortions on a global basis. Even with that effort, new measurements and refinements from improving satellite technologies resulted in evolution of the scientific consensus on the dimensions of the true “best-fit” ellipsoid several times and therefore different mapping systems make use of different ellipsoids.
Before satellite positioning though, mapping was usually done by surveying and on a much more regional basis. It was therefore commonplace for such mapping to purposefully make use of an ellipsoid that was a closer match to the actual Earth surface in the area of interest, with the greater resulting mismatch from reality in parts of the globe that weren’t going to feature on the map being perfectly acceptable.
Thus, one of the most common reasons for needing to convert coordinates is that the source system and target system are based on entirely different ellipsoids.
Since we live in a 3D world, for full accuracy it is necessary to use 3 axes to describe the distance and direction of our point of interest from the known starting point (which I’ll call the origin going forward). For simplicity, we’ll ignore height for now and assume all points are at surface level. Thus, 2 axes are needed. Keeping in line with the philosophy of using physical attributes of the Earth to define things, a consistent practice of using North-South and East-West for these axes has been used since the time of the Ancient Greeks.
For measurements along the north-south axis, the easiest thing to do is to define 0 to be the halfway point between the two poles. Thus, in a latitude/longitude based system 0° latitude is the line around the equator. All geodetic datums use this definition.
There is no East Pole or West Pole, so unfortunately the same type of physical definition cannot be used to pick where to place the east-west axis. There are actually an infinite number of possible choices, the decision is essentially arbitrary. Because of this, the choice of where to draw the 0 line must be recorded as part of the datum definition. The chosen location is called the Prime Meridian.
The Ancient Greeks picked the westernmost point of the known world to be their Prime Meridian, which came with the helpful property for them that all longitudes were positive numbers. As map-making became more scientific in nature in the 18th century, many countries started using meridians that passed through their capital cities - e.g. French maps used Paris, German maps used Berlin. This was probably at least partially for reasons of national pride but also since longitude was more difficult to determine in those days, having the known 0 reference point inside the territory will have had practical benefits to those doing the measuring.
Eventually, international agreement was reached to standardise on a single meridian worldwide, that choice being the one passing through the Royal Observatory, Greenwich.
From the above, you may have realised that the origin point for north-south measurements (the equator), and the origin point for east-west (typically Greenwich) can be several thousand miles away from each other on completely different continents. This seems very complicated compared to the pirate map. Wouldn’t it be simpler to simply pick the Royal Observatory as (0,0) and measure everything from that single point?
The answer is that to measure distances in the way pirate maps do it requires either direct access to the origin point to measure out directly from (it had better be close!) or a network of other points with known coordinates that you can measure indirectly from. In fact, surveying makes heavy use of this very principle even today. However, it is not always practicable to find such points with known coordinates to measure from - for instance in remote areas, or for ships at sea.
With the right equipment and training, it is however possible to make standalone measurements of latitude and longitude from anywhere on the planet. This is useful.
Height is a concept that intuitively sounds very simple, but gets complicated very quickly (there is a section below that expands on this). For now however, remember that the ellipsoidal model of the Earth is just an approximation, which means this imaginary ellipsoid sometimes passes underneath “true” ground level, and sometimes passes above it. Thus, although “height” above or below the ellipsoid can theoretically be calculated and used to accurately place a point within a 3D space, it is of very limited practical use on the ground since the ellipsoid cannot actually be seen.
Coordinate reference systems (CRSs)
A Coordinate Reference System, is the combination of a Datum and a Coordinate System which is the particular set of axes being used to measure distances on.
It is very important to know the set of axes being used, because otherwise numbers are very prone to misintepretation -
42.0669, 11.8128 would be near Rome if the order is (latitude, longitude), but near Djibouti if the
order is (longitude, latitude). That’s assuming the measurement is in decimal degrees, and not some other unit such as
Most map projections use metres, but some use feet. Many use Eastings and Northings, but some are Northings and Eastings. Some are Southings and Westings. Some are just X and Y, but some use X to mean East and others use it to mean North. Some write the X coordinate first, some write the Y coordinate first. Just about every permutation of meaning and order exists.
When taking in coordinates from an external system, always, always, always check the unit, and the order of a numbers if they are not already clearly labelled.
Geographic coordinates are those that use latitude/longitude (and optionally ellipsoid height).
Longitudes are not of constant width, each degree covers a significantly wider area near the equator than near the poles. This means any calculations involving them involves a lot of trigonometry. For this reason, coordinates are sometimes expressed as 3 distances (3 axes…) from the centre of the Earth instead, with the axes angled so as to respect the datum definition (one runs through the poles, one runs through the line of prime meridian). GPS signals use this system, although the result is usually converted to latitude and longitude for display.
The 3D model describing the shape of the Earth is great from a scientific point of view, but comes with severe drawbacks for everyday use. A pirate has not, and never will, carry around a pocket globe. It’s just not practicable.
Like all humans, they prefer flat, foldable (portable!) maps.
Apart from portability, one of the other main benefits of flat maps is that unlike latitudes and longitudes, map grids have a fixed scale which makes measuring distances between points in everyday units such as metres nice and easy.
Unfortunately, there is no method of drawing out what is inherently a 3D shape onto a 2D surface whilst retaining full fidelity. There are ways of maintaining accuracy of shape, but they involve distorting size. There are also ways to maintain accurate size, but that involves some distortion of shape. Many mapmaking techniques aim for a compromise between the two. Usually, the technique (called a projection) is chosen so that distortions are only noticeable at very large scale e.g. maps that try to show entire countries at once. A well-produced map of e.g. a single town will not show such effects.
Complicating things further, some projection methods work really well for tall, skinny areas (think Italy) but work much less well on a more square-like areas (think France) so there are many methods in use worldwide.
All projected coordinate systems are based upon an existing geographic or geocentric system, and therefore have a datum and ellipsoid inside their formal definitions.
Because ellipsoidal heights are impractical to measure from the ground, it is common practice to ignore them completely and measure heights using a completely different system (you might have heard of a height being referred to as “above sea level”). A vertical coordinate system is by its nature 1 dimensional.
A compound coordinate, is simply the combination of a 2D geographic or projected coordinate and 1D vertical coordinate. Such a system is called 2D+1D to distinguish it from an actual 3D system such as a geocentric coordinate or a geographic coordinate that includes an ellipsoid height.
What is a height? In everyday usage, a height would be described as a distance above (or potentially below) a reference point. Easy. There are just 2 problems with that definition:
As discussed previously, defining something in terms of a real, physical point can produce difficulty in making measurements since it is not possible to determine the coordinates of your current location without having the known coordinates of a different point within sight
We also covered that a coordinate is a distance and direction from another point. As it turns out, “above” can be a complicated concept.
Before satellite positioning existed the first problem was ignored by mapmakers (or rather the practical difficulties were accepted as necessary). Heights were measured off a fixed point because there simply wasn’t an alternative. In the UK mainland the basis for zero height is mean sea level at Newlyn in Cornwall as read off the tide gauge a hundred years ago and a marker was placed to use as physical reference. For Northern Ireland, using a reference point in Cornwall is physically impossible and thus a different sea-level based reference point was established in Belfast.
Other islands around the UK coast also have their own 0m markers, and countries worldwide all use similar systems, for instance the US and Canada use a system based upon the water in the Great Lakes and France has historically measured heights from a spot near Marseille.
In 2015, the primary marker for the American Samoa Vertical Datum on the island of Tutuila was destroyed in an earthquake. Other secondary markers with derived/calculated heights were present on the island, but the earthquake meant that they had moved too much to be considered reliable indicators of their claimed position and therefore could not safely be used to back-calculate where the original 0m height line was.
As a result, the US was forced to declare the datum as obsolete and today when height information is needed fresh surveys have to be made based on a new 0m origin marker that has no relation to the previous origin.
Despite all being based on sea level, the 0m Newlyn marker, the 0m Belfast marker, the 0m Marseille marker and any/all other markers in different countries have absolutely nothing in common with each other and are not interchangeable. They were created at different dates, and even if they had all been created on the same day, sea levels at different points on the globe are not equal.
Which way up?
The other problem is the “direction” of height. In order to work out the relative height of an arbitrary point compared to the reference marker a surveyor needs to know what direction to make their measurements.
Intuitively we think of the ground as a flat surface, and height is simply the direction perpendicular to the ground. This works perfectly well for everyday usage such as a pirate burying treasure “6 feet below the ground”.
However, if we introduce the concept of a hill to that mental model it starts to become ambiguous. If one person is standing at the bottom of a hill, and another person is standing on it…are they at the same height (actual ground level) or is one of them higher than the other?
Additionally, as any pirate who has every tried to look over the horizon from the crow’s nest has figured out, the Earth is not, in fact, flat. It’s possible to have a mountain (“higher”) located “below” the horizon.
The actual, scientific answer to that conundrum is that “down” is the direction of gravity (i.e. towards the centre of the Earth), and “up” is the same axis just going the other way. That is, every point on the Earth measures “height” in a slightly different direction from every other point. That’s not as bad as it initially sounds for a surveyor though because they can use a spirit level to determine what direction that is. It’s fiddly and requires a lot of care but is doable, and a spirit level is part of every surveyors toolkit.
The results of those measurements reveal that the Earth’s gravity does not actually point at the centre of the Earth. At first glance that seems it must be wrong, but if you think back to how the Earth isn’t actually a perfect ellipsoid, and nor is the landmass on it equally distributed it starts to makes sense. The line of 0m height that is produced by keeping the spirit level level, is therefore not ellipsoidal but it also does not follow the contours of the Earth’s physical surface. It is it’s own unique imaginary shape (yes, another one) and is called the local geoid.
Confusingly, “geoid height” refers to the distance between the geoid and the ellipsoid. The distance between the geoid and what you’re measuring is called orthometric height.
For most of a landmass, this does mean that just as an “ellipsoid height” is not related to anything the eye can see, neither are geoid based heights other than at that single primary marker point.
Although countries worldwide have tended to settle on using bodies of water to set their 0 height points, this is an arbitrary choice. It makes most of the country have positive height numbers which has practical benefits, but scientifically they could have chosen literally any point in the country to be 0 and done their spirit levelling from there instead. There are an infinite number of potential 0 heights that could have been picked with their corresponding geoids (before choosing sea level at Newlyn, UK mainland heights were actually measured from a church in Liverpool).
In the last few decades it has become possible to measure gravity from space. Not needing a stable surface and spirit level means that measuring a geoid does not need to stop at the coast anymore, but can continue over oceans too. That means that it is now possible for heights to actually be comparable and interoperable between different landmasses. This global geoid is defined as the geoid that most closely aligns with global mean sea level.
This means the global geoid doesn’t go through a single prone-to-destruction marker point and no country gets bragging rights to having the definition be based on their land, but it does involve measuring the entire ocean instead which obviously presents some practical difficulties.
Most national mapping therefore continue to use a local geoid, because it allows them to restrict the necessary survey work to within their own territory.
- In summary, coordinates can measure heights in any of the following ways:
a by-product of a 3-axis based geocentric coordinate system
the distance from the imaginary ellipsoid, in the direction away from the centre of the ellipsoid
the distance from an imaginary local geoid referenced to local mean sea level, in the opposite direction to gravity
the distance from an imaginary global geoid referenced to global mean sea level, in the opposite direction to gravity
with absolutely none of them being referenced to actual physical ground characteristics at all.
This means if you’re just trying to locate points on the Earth surface, it is probably better to use coordinates without a height rather than specify a zero height as that almost certainly doesn’t mean what you intend it to.
And if you are trying to reference a height compared to local surface level (“the treasure is 6 feet below ground”, “that building is 100 metres tall”) specify that information separately to the coordinates.
The Earth is not a static environment. Melting glaciers cause sea levels to change. Earthquakes cause land to suddenly shift in sudden (and often catastrophic) ways. And continental drift causes continents to slowly, but continuously change position. It is therefore important for high accuracy to record when the measurements were made. This date portion of a coordinate is called an epoch.
An operator of 2 oil platforms located near each other wanted to install a bridge between them. The first platform was installed in the 1990s, the second was installed in the 2010s. Both platforms had accurate locations recorded at time of installation, and so the corresponding distance and angle between them were calculated and a bridge was pre-fabricated on-shore and brought to sea.
It didn’t fit. The calculated gap between them was wrong because the coordinates of the two platforms were taken 20 years apart. This mistake cost millions to fix.
Geodesy tends to use decimal years for epochs, e.g. 2000.40, or 2021.00. For ease of use PHPCoord deviates from this
and accepts dates in standard PHP
DateTimeImmutable format instead.
If, like most people you don’t have dates for your coordinates, you can also use
null or leave blank entirely.
The oil and gas industry relies very heavily upon precision surveying - accurate information as to location is of critical importance to them, not just on a day-to-day “is this drill positioned where we think it is?” basis but also for legal and regulatory purposes such as obtaining the necessary licenses. Given that almost every country in the world has its own coordinate system(s) and also that oil and gas fields do not stop at national boundaries, the ability to convert between them is a frequent necessity.
For that reason, one of their trade associations, the International Association of Oil & Gas Producers (IOGP) maintains a database of coordinate system definitions and how to transform between them for use by their members known as the EPSG Geodetic Parameter Dataset. They also generously make it available at no charge to non-members.
This dataset (maintained since 1985, public since 1993) is so useful that it has become a de-facto standard, and it is incorporated into many, many GIS applications. The usage of “EPSG codes” to reference specific coordinate systems has actually become so standardised that IOGP accepts submissions for new ones that have absolutely no relevance to their own members.
- Example EPSG codes you may have seen include:
EPSG:4326 for WGS84 (GPS)
EPSG:4269 for NAD83 (North America)
EPSG:4258 for ETRS89 (Europe)
PHPCoord also makes use of the EPSG dataset although for the most part tries to make it an implementation detail rather than something that users should be aware of. It is possible to use EPSG codes directly if you know them (e.g. taking in data from an external system), but it’s not necessary to know the relevant code to use the software.
Technically called a graticule, but nobody knows that word