Inspection functions

Inspection functions read properties out of a cell without converting it to geometry. All are pure bit operations or table lookups, and none require the coordinate system.

isValidCell

Tests whether a value is a well-formed Terra cell. Checks the mode, reserved fields, resolution range, base cell existence, and that digits beyond the cell's resolution hold the unused marker 7.

Validate anything that arrives from outside your system — user input, a file, another service. A 64-bit value is not a Terra cell merely by being 64 bits.

C

int isValidCell(TerraIndex cell);

Returns non-zero if valid.

Python

terra.is_valid_cell(cell)
# Returns: bool

terra.is_valid_cell("t10830cd1943ffff8")   # True
terra.is_valid_cell("t0000000000000000")   # False — mode is not a cell

JavaScript

terra.isValidCell(cell)   // boolean

SQL

SELECT terra_is_valid_cell('t10830cd1943ffff8');  -- true

-- Screen a column before indexing on it
SELECT count(*) FROM imported WHERE NOT terra_is_valid_cell(cell);

getResolution

Returns the resolution of a cell, 0–14. A four-bit field read, valid on any well-formed cell.

C

int getResolution(TerraIndex cell);

Python

terra.get_resolution("t10830cd1943ffff8")   # 8

SQL

-- Confirm a table holds a single resolution
SELECT DISTINCT terra_get_resolution(cell) FROM parcels;

getBaseCellNumber

Returns the base cell a cell descends from, 0–127. Useful for coarse partitioning: every cell sharing a base cell occupies one contiguous region of the country.

Python

terra.get_base_cell_number("t10830cd1943ffff8")   # 24

SQL

-- Partition a large table by base cell
CREATE TABLE parcels PARTITION BY LIST (terra_get_base_cell_number(cell));

cellArea

Returns the area of a cell. Because the projection is equal-area, this depends only on the resolution — every cell at a given resolution has identical area anywhere in the extent.

Python

terra.cell_area(cell, unit="ha")     # 1.0     at Res 8
terra.cell_area(cell, unit="m2")     # 10000.0
terra.cell_area(cell, unit="km2")    # 0.01

SQL

-- Total area of a cell set, exactly
SELECT count(*) * terra_cell_area(min(cell), 'ha') AS hectares FROM coverage;

Since area is constant per resolution, counting cells is measuring area. A set of 2,401 Res 8 cells is exactly 2,401 hectares, with no summation over geometry.

isPentagon

Always returns false. Provided so that code ported from grid systems that require pentagon handling compiles and runs unchanged.

Terra is a regional projected grid and tiles with hexagons alone. Every Terra cell has exactly six neighbours, at every resolution, without exception. New code should not branch on this function.

Next

• Hierarchy — moving between resolutions
• Error handling — what invalid cells look like

---

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