Hierarchy functions

Terra cells form a strict hierarchy across 15 resolution levels. Each cell at resolution n has exactly one parent at resolution n-1 and exactly 7 children at resolution n+1 (aperture-7). These functions navigate that hierarchy.

cellToParent

Returns the ancestor of a cell at the specified (coarser) resolution.

C

TerraError cellToParent(TerraIndex cell, int parentRes, TerraIndex *parent);

Returns 0 (E_SUCCESS) on success. Returns an error if parentRes is finer than the cell's current resolution.

Python

terra.cell_to_parent(cell, res)
# Returns: str (TIS of parent cell)

cell = terra.latlon_to_cell(24.6877, 46.7219, 8)  # Res 8 — 1 ha

parent_7 = terra.cell_to_parent(cell, 7)   # Res 7 — 7 ha block
parent_5 = terra.cell_to_parent(cell, 5)   # Res 5 — 3.43 km² district
parent_3 = terra.cell_to_parent(cell, 3)   # Res 3 — 168 km² province

# Aggregate delivery data by Res 5 district
import pandas as pd
df = pd.read_csv("deliveries.csv")
df["district"] = df["terra_cell"].apply(
    lambda c: terra.cell_to_parent(c, 5)
)
print(df.groupby("district")["value"].sum())

JavaScript

terra.cellToParent(cell, parentRes)
// Returns: string (TIS)

const block  = terra.cellToParent(cell, 7);  // 7 ha block
const zone   = terra.cellToParent(cell, 6);  // 49 ha zone
const sector = terra.cellToParent(cell, 4);  // 24 km² sector

SQL

terra_cell_to_parent(cell, parent_res)
-- Returns: text (TIS)

-- Aggregate parcel data by Res 5 district
SELECT
    terra_cell_to_parent(terra_cell, 5) AS district,
    COUNT(*) AS parcel_count,
    SUM(area_sqm) AS total_area
FROM cadastral_parcels
GROUP BY 1
ORDER BY 2 DESC;

Go

parent, err := terra.CellToParent(cell, 7)

DuckDB

terra_cell_to_parent(cell, parent_res)

-- Aggregate via DuckDB on a Parquet file
SELECT
    terra_cell_to_parent(terra_cell, 6) AS zone,
    COUNT(*) AS events
FROM read_parquet('sensor_events.parquet')
GROUP BY 1;

Shell

$ terra cellToParent -c t10830cd1943ffff8 -r 7
"t1858a2f000000000"

cellToChildren

Returns all cells at the specified (finer) resolution that are contained by the given cell. A cell at resolution n has exactly 7 children at resolution n+1, 49 at n+2, and 7^k at n+k.

C

TerraError cellToChildren(TerraIndex cell, int childRes, TerraIndex *children);

Allocate cellToChildrenSize(cell, childRes) elements for children. Returns 0 (E_SUCCESS) on success.

Python

terra.cell_to_children(cell, res)
# Returns: list[str]

block = terra.latlon_to_cell(24.6877, 46.7219, 7)  # Res 7 — 7 ha

children_8 = terra.cell_to_children(block, 8)   # 7 × 1 ha cells
print(len(children_8))  # 7

children_9 = terra.cell_to_children(block, 9)   # 49 cells (7²)
print(len(children_9))  # 49

JavaScript

const children = terra.cellToChildren(block, 8);
// 7 Res-8 cells

SQL

terra_cell_to_children(cell, child_res)
-- Returns: text[]

-- Expand a Res 5 district into all its Res 8 (1 ha) cells
SELECT unnest(
    terra_cell_to_children('t1858a00000000000', 8)
) AS base_cell;

Go

children, err := terra.CellToChildren(block, 8)
// len(children) == 7

Shell

$ terra cellToChildren -c t1858a2f000000000 -r 8
["t10830cd1943ffff8", "t1858a2f000000001", ...]
# 7 cells

cellToCenterChild

Returns only the centre child — the single child at the finer resolution whose centre is closest to the parent's centre. This is child digit 0.

Python

terra.cell_to_center_child(cell, res)
# Returns: str

center_child = terra.cell_to_center_child("t1858a2f000000000", 8)

JavaScript

const centerChild = terra.cellToCenterChild(cell, 8);

SQL

terra_cell_to_center_child(cell, child_res)

compactCells

Takes a set of cells and replaces groups of 7 sibling cells that share a parent with that parent cell. Recursively compacts until no further simplification is possible.

Compaction dramatically reduces the size of large cell sets. A filled disk of radius k at Res 8 collapses to a compact representation where most of the interior is represented by coarser cells.

C

TerraError compactCells(const TerraIndex *cellSet, TerraIndex *compactedSet,
                        const int64_t numCells);

Returns 0 (E_SUCCESS) on success.

Python

terra.compact_cells(cell_list)
# Returns: list[str] — mixed resolutions

# Polyfill Riyadh and compact
import json
with open("riyadh.geojson") as f:
    polygon = json.load(f)

cells = terra.polygon_to_cells(polygon, 8)
print(len(cells))           # ~120,000 cells

compact = terra.compact_cells(cells)
print(len(compact))         # ~8,000 cells — same coverage, fewer records

JavaScript

const compact = terra.compactCells(cells);

SQL

terra_compact_cells(cell_array)
-- Returns: text[]

Shell

$ terra compactCells < cells.txt

uncompactCells

Expands a compact cell set back to a uniform resolution. Inverse of compactCells.

C

TerraError uncompactCells(const TerraIndex *compactedSet, const int64_t numCompacted,
                          TerraIndex *cellSet, const int64_t maxCells,
                          const int res);

Returns 0 (E_SUCCESS) on success.

Python

terra.uncompact_cells(compact_list, res)
# Returns: list[str] — all at target resolution

# Restore compact representation to Res 8 base cells
cells = terra.uncompact_cells(compact, 8)

JavaScript

const cells = terra.uncompactCells(compact, 8);

SQL

terra_uncompact_cells(compact_array, target_res)
-- Returns: text[]

Shell

$ terra uncompactCells -r 8 < compact.txt

---

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