Skip to main content

Miscellaneous functions

Constants, unit conversions, and the sizing helpers needed when allocating output buffers in C.

Grid constants​

FunctionReturns
resCount()15 — the number of resolutions, Res 0–14
baseCellCount()The number of base cells
maxResolution()14
baseResolution()8 — the national 1-hectare standard
terra.res_count()          # 15
terra.base_resolution()    # 8

baseResolution() exists so applications can refer to the national standard by name rather than hard-coding 8. Use it — it documents intent, and it reads correctly to anyone auditing the code.

Area and length by resolution​

terra.get_hexagon_area_avg(res, unit="ha")      # 1.0 at Res 8
terra.get_hexagon_edge_length_avg(res, unit="m")
terra.get_num_cells(res)                        # total cells at this resolution

Because the projection is equal-area, area is exact rather than average — every cell at a given resolution covers identical ground. Edge length varies slightly with distance from the projection centre, so that figure is a true average.

The Avg naming is retained for compatibility with code written against grid libraries where both figures vary.

Unit conversions​

terra.degs_to_rads(deg)
terra.rads_to_degs(rad)
terra.great_circle_distance(a, b, unit="m")

great_circle_distance measures between two coordinates on the ellipsoid. It is metric distance, distinct from gridDistance, which counts steps between cells.

Sizing helpers​

Only needed in C, where output arrays are caller-allocated. Bindings in other languages size their own results.

FunctionSizes the output of
maxGridDiskSize(k)gridDisk — returns 3k² + 3k + 1
maxPolygonToCellsSize(poly, res, flags)polygonToCells
cellToChildrenSize(cell, childRes)cellToChildren — returns 7ⁿ
uncompactCellsSize(cells, res)uncompactCells
int n = maxGridDiskSize(3);              /* 37 */
TerraIndex *out = calloc(n, sizeof(TerraIndex));
gridDisk(origin, 3, out);

These return upper bounds. gridDisk fills every slot, but polygonToCells may leave trailing entries zeroed — check each before use.

String conversion​

terra.int_to_string(cell)    # -> "t10830cd1943ffff8"
terra.string_to_int(s)       # -> int

In JavaScript, prefer strings. Every Terra index exceeds Number.MAX_SAFE_INTEGER, so a cell stored in a Number is silently corrupted. Use the string form, or BigInt where arithmetic is required.

// wrong — loses precision
const cell = Number("0x10830cd1943ffff8");

// correct
const cell = "t10830cd1943ffff8";          // string form
const raw  = BigInt("0x10830cd1943ffff8"); // when arithmetic is needed

Version​

terra.version()          # library version
terra.grid_version()     # e.g. "terra-v1.0-ksa-grf17"

gridVersion() identifies the grid instance, not the library build. Embed it in derived artefacts — tiles, caches, exported datasets — so that a regeneration of the grid can invalidate them cleanly. Two datasets carrying different grid versions must not be joined on cell identity without checking what changed between them.

Next​

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