Grid traversal functions

Grid traversal allows finding cells in the vicinity of an origin cell, and determining how to move across the grid from one cell to another.

gridDisk

Returns all cells within grid distance k of the origin cell — a filled hexagonal disk. Output order is not guaranteed.

The number of cells returned is 1 + 6 + 12 + ... + 6k = 3k² + 3k + 1.

C

TerraError gridDisk(TerraIndex origin, int k, TerraIndex *out);

Returns 0 (E_SUCCESS) on success. Allocate maxGridDiskSize(k) elements for out.

Python

terra.grid_disk(origin, k)
# Returns: list[str] — cell TIS values

# All cells within 2 rings of a Riyadh cell (19 cells)
disk = terra.grid_disk("t10830cd1943ffff8", 2)
print(len(disk))  # 19

# All Res 8 (1 ha) cells within 500 m of a point
# Res 8 hex width ≈ 107 m, so k=5 covers ~535 m radius
cell = terra.latlon_to_cell(24.6877, 46.7219, 8)
nearby = terra.grid_disk(cell, 5)
print(len(nearby))  # 91

JavaScript

terra.gridDisk(origin, k)
// Returns: string[]

const disk = terra.gridDisk("t10830cd1943ffff8", 2);
// 19 cells

SQL

terra_grid_disk(origin, k)
-- Returns: text[]

-- Count all cells within 3 rings of a logistics hub
SELECT array_length(
    terra_grid_disk('t10830cd1943ffff8', 3), 1
) AS cell_count;
-- 37

-- Join delivery orders to nearby cells
SELECT o.order_id, o.terra_cell
FROM orders o
WHERE o.terra_cell = ANY(
    terra_grid_disk('t10830cd1943ffff8', 5)
);

Go

disk, err := terra.GridDisk("t10830cd1943ffff8", 2)
// disk: []string — 19 cells

DuckDB

terra_grid_disk(origin, k)

SELECT unnest(terra_grid_disk('t10830cd1943ffff8', 2)) AS cell;

Shell

$ terra gridDisk -k 2 -c t10830cd1943ffff8
["t10830cd1943ffff8", "t1858a2e400000000", ...]

gridRing

Returns only the cells at exactly grid distance k from the origin — the hollow ring. Returns 6k cells for k > 0, and 1 cell for k = 0.

C

TerraError gridRing(TerraIndex origin, int k, TerraIndex *out);

Returns 0 (E_SUCCESS) on success.

Python

terra.grid_ring(origin, k)
# Returns: list[str]

ring1 = terra.grid_ring("t10830cd1943ffff8", 1)
print(len(ring1))  # 6 — the 6 direct neighbours

JavaScript

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

SQL

terra_grid_ring(origin, k)

SELECT terra_grid_ring('t10830cd1943ffff8', 1);

Shell

$ terra gridRing -k 1 -c t10830cd1943ffff8
["t1858a2e400000000", "t1858a2f000000000", ...]

gridDistance

Returns the minimum number of cell hops between two cells at the same resolution.

C

TerraError gridDistance(TerraIndex origin, TerraIndex dest, int64_t *distance);

Returns 0 (E_SUCCESS) on success. Returns an error if cells are at different resolutions.

Python

terra.grid_distance(origin, dest)
# Returns: int

cell_a = terra.latlon_to_cell(24.6877, 46.7219, 8)  # Riyadh
cell_b = terra.latlon_to_cell(24.7136, 46.6753, 8)  # ~5 km away
dist = terra.grid_distance(cell_a, cell_b)
print(dist)  # approx 50 hops at Res 8 (each hop ~107 m)

JavaScript

const dist = terra.gridDistance(cell_a, cell_b);

SQL

terra_grid_distance(origin, dest)
-- Returns: bigint

SELECT terra_grid_distance(
    terra_latlon_to_cell(24.6877, 46.7219, 8),
    terra_latlon_to_cell(24.7136, 46.6753, 8)
);

Shell

$ terra gridDistance -o t10830cd1943ffff8 -d t1858b1a400000000
47

gridPathCells

Returns a minimal-length contiguous path of cells between two cells (inclusive of both endpoints). Path length equals gridDistance(start, end) + 1.

C

TerraError gridPathCells(TerraIndex start, TerraIndex end, TerraIndex *out);

Returns 0 (E_SUCCESS) on success.

Python

terra.grid_path_cells(start, end)
# Returns: list[str]

start = terra.latlon_to_cell(24.6877, 46.7219, 8)
end   = terra.latlon_to_cell(24.7003, 46.7401, 8)
path  = terra.grid_path_cells(start, end)
print(len(path))  # gridDistance + 1

JavaScript

const path = terra.gridPathCells(start, end);

SQL

terra_grid_path_cells(start, end)
-- Returns: text[]

Shell

$ terra gridPathCells -o t10830cd1943ffff8 -d t1858a3c400000000
["t10830cd1943ffff8", "t1858a30400000000", ..., "t1858a3c400000000"]

areNeighborCells

Returns true if two cells share an edge (grid distance = 1).

Python

terra.are_neighbor_cells(cell_a, cell_b)
# Returns: bool

neighbors = terra.grid_ring("t10830cd1943ffff8", 1)
print(terra.are_neighbor_cells("t10830cd1943ffff8", neighbors[0]))
# True

JavaScript

terra.areNeighborCells(cell_a, cell_b)  // boolean

SQL

terra_are_neighbor_cells(cell_a, cell_b)
-- Returns: boolean

---

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