Quick Start

This page shows you how to get started with the functions in Terra that convert points to cell identifiers, and from cell identifiers back to geometry. These are the core indexing functions used in most Terra applications.

The examples below use the coordinates of Masmak Fortress in Riyadh (24.6877°N, 46.7219°E) at resolution 8 — the 1-hectare national base standard.

Follow along using your preferred language binding.

Convert a coordinate to a cell

Find which Terra cell contains a given latitude and longitude:

Python

import terra

lat = 24.6877
lng = 46.7219
res = 8  # 1-hectare base resolution

cell = terra.latlon_to_cell(lat, lng, res)
print(cell)
# "t10830cd1943ffff8"

JavaScript

import * as terra from 'terra-sa';

const lat = 24.6877;
const lng = 46.7219;
const res = 8;

const cell = terra.latLngToCell(lat, lng, res);
console.log(cell);
// "t10830cd1943ffff8"

SQL

SELECT terra_latlon_to_cell(24.6877, 46.7219, 8) AS cell;
-- "t10830cd1943ffff8"

Shell

$ terra latLngToCell --lat 24.6877 --lng 46.7219 -r 8
"t10830cd1943ffff8"

The result is the Terra Index String (TIS) of the hexagonal cell containing this point. Every point within the bounds of this cell shares the same identifier.

Get the cell centre

Retrieve the geographic centre of a Terra cell:

Python

cell = "t10830cd1943ffff8"
center = terra.cell_to_center(cell)
print(center)
# (24.6880, 46.7221)

JavaScript

const cell = "t10830cd1943ffff8";
const center = terra.cellToCenter(cell);
console.log(center);
// [24.6880, 46.7221]

SQL

SELECT terra_cell_to_center('t10830cd1943ffff8');

Shell

$ terra cellToCenter -c t10830cd1943ffff8
[24.6880, 46.7221]

Note that the centre returned is the centroid of the hexagonal cell in the LAEA projection, reprojected to WGS84. It will differ slightly from the original input coordinates, because the cell contains a region rather than a single point.

Get the cell boundary

Retrieve the six vertices of a Terra hexagon:

Python

cell = "t10830cd1943ffff8"
boundary = terra.cell_to_boundary(cell)
print(boundary)
# [(24.6935, 46.7177), (24.6963, 46.7253), (24.6908, 46.7328),
#  (24.6825, 46.7326), (24.6797, 46.7250), (24.6852, 46.7176)]

JavaScript

const cell = "t10830cd1943ffff8";
const boundary = terra.cellToBoundary(cell);
// Returns array of [lat, lng] pairs for the 6 hexagon vertices

SQL

-- Returns a PostGIS geometry (POLYGON)
SELECT terra_cell_to_boundary_wkb('t10830cd1943ffff8');

Shell

$ terra cellToBoundary -c t10830cd1943ffff8
[[24.6935,46.7177],[24.6963,46.7253],[24.6908,46.7328],[24.6825,46.7326],[24.6797,46.7250],[24.6852,46.7176]]

Get the human-readable Terra Grid Code

Every Terra cell at Res 8 has a short human-readable address — the Terra Grid Code (TGC):

Python

cell = "t10830cd1943ffff8"
code = terra.cell_to_saudi_code(cell)
print(code)
# "T08-0C6D351E"

JavaScript

const code = terra.cellToSaudiCode("t10830cd1943ffff8");
console.log(code);
// "T08-0C6D351E"

SQL

SELECT terra_cell_to_saudi_code('t10830cd1943ffff8');
-- "T08-0C6D351E"

The TGC format is T[RES]-[POSITION]. T08 indicates resolution 8 (1 ha). The 6-character position code encodes the geometric location with no reference to any administrative boundary.

Get the parent cell

Move up one level in the hierarchy to get the Res 7 block (7 ha) containing this cell:

Python

cell = "t10830cd1943ffff8"
parent = terra.cell_to_parent(cell, 7)
print(parent)
# "t1858a2f000000000"  (Res 7 — 7 ha block)

JavaScript

const parent = terra.cellToParent("t10830cd1943ffff8", 7);

SQL

SELECT terra_cell_to_parent('t10830cd1943ffff8', 7);

Find neighbouring cells

Get all cells within 1 ring of the origin (the 6 adjacent hexagons):

Python

cell = "t10830cd1943ffff8"
ring = terra.grid_ring(cell, k=1)
print(len(ring))  # 6 neighbours

JavaScript

const ring = terra.gridRing("t10830cd1943ffff8", 1);
// 6 adjacent cells

SQL

SELECT terra_grid_ring('t10830cd1943ffff8', 1);

---

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