Skip to main content

How Terra works

Terra turns a position on the ground into an integer. This page explains the four design decisions that make that integer useful: the choice of hexagons, the projection the grid is laid on, the way resolutions nest, and the algorithm that maps a coordinate to a cell.

Why hexagons​

A grid system has to pick a shape that tiles the plane without gaps. Three regular polygons can do it: triangles, squares, and hexagons. Terra uses hexagons, for three reasons that matter in practice.

Every neighbour is equidistant. A hexagon has six neighbours, and the centre of each sits the same distance away. A square has eight neighbours at two different distances — the four edge-sharing ones are closer than the four corner-sharing ones. Any calculation involving adjacency, travel cost, spread, or diffusion has to correct for that discrepancy on a square grid. On a hexagonal grid there is nothing to correct.

There is no corner ambiguity. Four squares meet at every corner of a square grid, so a point landing exactly on a corner has four equally valid containers. Hexagons meet three at a time along edges only, which makes containment tests cleaner and removes a whole category of edge case from spatial joins.

Hexagons approximate a circle. Most real phenomena — a signal footprint, a service radius, a plume, a catchment — are closer to round than to square. A hexagon is the tiling shape with the lowest perimeter-to-area ratio, so it wastes the least area when used to approximate these.

The cost is that hexagons cannot be perfectly subdivided into smaller hexagons. Terra addresses this in the hierarchy section below.

The projection​

Terra is a regional system. It covers Saudi Arabia and a buffer extending across the GCC, not the whole planet, and that constraint buys two significant simplifications.

Terra projects the region onto a plane using Lambert Azimuthal Equal Area (LAEA), centred on 24°N, 45°E — roughly the geographic middle of the Kingdom. The grid is then laid out on that flat plane.

Every cell has the same area. LAEA preserves area exactly. A Res 8 cell in Tabuk, in the Empty Quarter, and on the Gulf coast each cover precisely 1 hectare. Counting cells is therefore equivalent to measuring ground, with no latitude correction and no per-cell area lookup. A density computed as events per cell is directly comparable across the whole country.

There are no pentagons. Global grid systems wrap a sphere, which no arrangement of hexagons alone can do — a global hexagonal grid must include a small number of pentagon cells, and those pentagons are a permanent source of special-case code. Terra covers a bounded region on a plane, so it tiles with hexagons alone. Every Terra cell has exactly six neighbours, everywhere, without exception.

Distortion in an LAEA projection grows with distance from the centre point. At the edges of the Terra coverage area, shape and distance are slightly distorted — but area, the property the grid depends on, remains exact everywhere by construction.

The resolution hierarchy​

Terra has 15 resolution levels, Res 0 through Res 14, related by aperture 7: each finer level divides area by 7.

StepFactor
Area÷ 7
Edge length÷ √7 ≈ 2.6458
Rotation≈ 19.1° per level

Starting from a Res 0 cell of ~57,648 km², eight levels of division give exactly 1 hectare at Res 8 — the national base standard. Six more levels reach ~0.09 m² at Res 14.

Each cell has seven children: one centred on the parent, six around it. This is where the child digits in the 64-bit index come from — each digit, 0 through 6, records which child was taken at that level.

Nesting is approximate​

This matters enough to state precisely, because it is easy to overstate.

Seven child hexagons have exactly the same total area as their parent, but they cannot be arranged to tile it exactly. The child grid is rotated about 19.1° relative to the parent, so children near the parent's boundary extend slightly into the neighbouring parent, and are slightly clipped in return.

What remains exact. The index hierarchy is a clean partition. Every cell has exactly one ancestor at each coarser resolution, determined by arithmetic on the child digits:

  • Rolling counts up from a fine resolution to a coarse one loses nothing and counts nothing twice. Each fine cell contributes to exactly one coarse cell.
  • Cell counts are exact: a Res 4 cell has exactly 7⁴ = 2,401 Res 8 descendants.
  • Total area is exact: those 2,401 descendants cover exactly 2,401 hectares, because the projection is equal-area.

What is approximate. Only the geometry, and specifically only near boundaries:

  • The drawn parent hexagon is not the same patch of ground as the union of its children. Both have identical area; their footprints differ slightly at the edges.
  • Consequently, indexing a point directly at Res 4 and indexing it at Res 8 then taking the parent can disagree for points close to a cell boundary.

In practice. If you need an authoritative assignment at a coarse resolution — cadastral, statistical, or anything with legal weight — index the point directly at that resolution. It costs the same as indexing at any other resolution and it is exact. Use rollup for dashboards, densities, and heat maps, where the boundary effect is immaterial and the partition property is what matters.

This is an inherent property of aperture-7 hexagonal hierarchies, not a limitation of this implementation. The alternative — perfectly nested squares — costs you equidistant neighbours and corner-free containment, which is a worse trade for the work Terra is built for.

From coordinate to cell​

terra_latlng_to_cell() performs five steps, all arithmetic and none requiring a lookup table, a network call, or a spatial index.

  1. Datum — the input coordinate is interpreted on KSA-GRF17 (EPSG:9333). Coordinates on another datum are transformed first; see SANSRS Integration.
  2. Project — LAEA transform to planar x/y in metres from the 24°N 45°E origin.
  3. Base cell — determine which of the ~80 Res 0 cells contains the point.
  4. Descend — for each level down to the target resolution, determine which of the seven children contains the point and record the digit.
  5. Pack — assemble mode, resolution, base cell, and digits into the 64-bit integer.

The work is proportional to the target resolution, not to the size of any dataset. Indexing a point at Res 8 costs the same whether the database holds one row or ten billion.

The reverse, terra_cell_to_latlng(), unpacks the digits, walks back up to planar coordinates, and applies the inverse projection.

What you get​

The integer that comes out is the whole point. Because location has become an ordinary 64-bit key:

  • Datasets that share nothing geometrically — cadastral parcels, delivery telemetry, sensor readings, utility runs — join on equality rather than on a spatial predicate.
  • Standard database indexes work. No spatial extension is required to filter, group, or count by location.
  • Cells sort meaningfully: the digit layout means cells that are near each other in space tend to be near each other in sort order, which makes range scans and partitioning effective.

The two string forms of that integer — the developer-facing TIS and the human-facing TGC — are covered in Terra index structure.

Next​

The Terra System is designed and developed by Tec Solution KSA.