Coordinate systems
Terra converts a position through four representations. Understanding which one an operation works in explains why some operations are exact and others are not.
The four representations
| Representation | Form | Exact? |
|---|---|---|
| Geographic | latitude, longitude on KSA-GRF17 | continuous |
| Projected | x, y in metres, LAEA about 24°N 45°E | continuous, area-exact |
| Lattice | integer hexagonal coordinates at a resolution | exact |
| Index | 64-bit cell identifier | exact |
Conversions run in both directions. The geographic-to-projected step involves floating point; the lattice and index steps are integer and exactly reversible.
Geographic
Latitude and longitude on KSA-GRF17 (EPSG:9333), GRS 1980 ellipsoid. The core works in radians; the public API accepts degrees and converts.
Terra performs no datum transformation. A coordinate on another datum produces a wrong cell with no error raised. See SANSRS integration.
Projected
Lambert Azimuthal Equal Area, centred 24°N, 45°E, in metres from that origin.
LAEA preserves area exactly. That single property is why cell area is constant across the country, why counting cells measures ground, and why no latitude correction appears anywhere in the library.
What LAEA does not preserve is shape and distance, and the distortion grows with distance from the centre. Near the edges of the extent a cell is slightly non-equilateral, and its edge lengths differ slightly from the nominal figure. Derive cell vertices from the projection, not from a centroid and a fixed radius — the fixed-radius approximation drifts visibly at the extent edges.
Lattice
Integer coordinates on the hexagonal lattice at a given resolution. Neighbours, rings, grid distance, and path finding are computed here.
Working in integers is what makes traversal exact and free of floating-point tolerance problems. Two cells are neighbours or they are not; grid distance is a whole number of steps; a ring at radius k contains exactly 6k cells.
Each resolution has its own lattice, related to the next by the aperture-7 relationship: √7 in linear scale and approximately 19.1° in rotation.
Index
The 64-bit identifier. Conversion between lattice coordinates and the index is the digit encoding — each child digit records which of seven children was taken at that level.
Index and lattice are exactly equivalent. Everything in the hierarchy API operates here, in pure bit arithmetic, with no geometry involved.
Which conversions are exact
| Conversion | Exact? |
|---|---|
| Index ↔ lattice | exactly reversible |
| Lattice ↔ projected | exact within a resolution |
| Projected ↔ geographic | floating point; area-exact, shape-approximate |
| Geographic → cell → geographic | returns the cell centre, not the original point |
The last is not a defect. Indexing is deliberately lossy: it maps a continuous position onto a
discrete cell. cellToLatLng returns the centre of the cell containing the original point, and the
displacement is bounded by the cell size at that resolution. This is what makes Terra an index
rather than a coordinate encoding.
The 19.1° rotation
Successive resolutions are rotated relative to one another by
asin(√3 / (2√7)) ≈ 19.1066°, a consequence of aperture-7 subdivision on a triangular lattice.
The rotation is constant and applies at every level. It is why parent and child hexagons do not tile one another exactly, and therefore why nesting is geometrically approximate while counts and areas remain exact — see How Terra works.
Next
- Algorithms — how the conversions are computed
- Core library overview — the layering
The Terra System is designed and developed by Tec Solution KSA.