Region functions

Region functions bridge Terra cells and ordinary polygon geometry — filling a polygon with cells, and turning a set of cells back into a boundary.

polygonToCells

Returns the cells covering a polygon at a given resolution.

Containment mode is the argument that matters most. The two modes answer different questions and give different results near the boundary:

Mode	Includes a cell when	Use for
centroid (default)	its centre falls inside the polygon	partitioning, minimum-area rules, anything where each cell belongs to exactly one region
overlap	any part of it intersects the polygon	coverage, service areas, anything that must not miss ground

centroid produces a clean partition — adjacent regions never claim the same cell. overlap guarantees full coverage but double-counts cells straddling a shared boundary. Choosing the wrong one is the most common source of totals that fail to reconcile.

C

TerraError polygonToCells(const TerraGeoPolygon *poly, int res,
                          uint32_t flags, TerraIndex *out);

Size out with maxPolygonToCellsSize() before calling.

Python

terra.polygon_to_cells(polygon, res, mode="centroid")
# Returns: list[str]

district = {"type": "Polygon", "coordinates": [[...]]}
cells = terra.polygon_to_cells(district, 8)
print(f"{len(cells)} hectares")        # cell count is the area in ha

# Coverage rather than partition
cells = terra.polygon_to_cells(district, 8, mode="overlap")

JavaScript

terra.polygonToCells(polygon, res, { mode: 'centroid' });  // string[]

SQL

SELECT terra_polygon_to_cells(geom, 8) FROM districts WHERE id = 42;

-- Area of a district in hectares, without touching geometry again
SELECT id, array_length(terra_polygon_to_cells(geom, 8), 1) AS hectares
FROM districts;

Choose the resolution against the polygon, not the map. Filling a national boundary at Res 11 produces billions of cells. Fill coarse, then refine only where needed.

polygonToCellsPartial

Like polygonToCells in overlap mode, but returns each cell with the fraction of it lying inside the polygon.

This is the function for boundaries that cut through cells — coastlines, national borders, administrative limits. It lets a cell be assessed on its inside portion while being excluded from totals that require whole cells.

Python

terra.polygon_to_cells_partial(polygon, res)
# Returns: list[tuple[str, float]] — (cell, coverage 0.0-1.0)

for cell, coverage in terra.polygon_to_cells_partial(coastal, 8):
    if coverage == 1.0:
        whole.append(cell)
    else:
        partial.append((cell, coverage))

# Land area, counting partial cells proportionally
area_ha = sum(cov for _, cov in terra.polygon_to_cells_partial(coastal, 8))

SQL

SELECT cell, coverage
FROM terra_polygon_to_cells_partial(
       (SELECT geom FROM regions WHERE id = 7), 8)
WHERE coverage < 1.0;

A coverage of 1.0 means wholly inside. Values below 1.0 identify exactly the cells that need a policy decision about inclusion — and let that decision be made downstream rather than being baked into the cell set.

cellsToMultiPolygon

Returns the outline of a set of cells as a polygon, dissolving shared interior edges. Disjoint groups produce separate polygons; enclosed gaps become holes.

Python

terra.cells_to_multi_polygon(cells)
# Returns: GeoJSON MultiPolygon

outline = terra.cells_to_multi_polygon(service_area)

SQL

SELECT terra_cells_to_multi_polygon(array_agg(cell))
FROM coverage WHERE operator_id = 3;

Use this for display and export. For analysis, keep working with the cell set — it is cheaper and does not lose the resolution information.

cellsToGeoJson

Serialises a set of cells as a GeoJSON FeatureCollection, one feature per cell, each carrying its TIS and TGC as properties.

Convenient for handing cells to a mapping tool. Note the size: a GeoJSON feature per cell is far larger than the cells themselves, so for anything above a few thousand cells, send the cell identifiers and derive geometry at the other end.

Next

• Hierarchy — compactCells reduces a large cell set before export
• Indexing — cellToBoundary for individual cells

---

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