Directed edge functions

A directed edge is the boundary between two adjacent cells, with a direction — from an origin cell to a destination cell. Because every Terra cell has exactly six neighbours at every resolution, every cell has exactly six outgoing directed edges, with no exceptions to handle.

Directed edges exist so that movement between cells can itself be an identifier. Flow, traffic, pipe segments, migration, and transfer are properties of a movement rather than of a place, and a directed edge gives that movement a 64-bit key of its own — one that joins and aggregates the same way a cell does.

An edge is encoded as a Terra index with the edge mode set and the direction recorded alongside the origin cell. The pair (A→B) and (B→A) are different edges with different identifiers.

cellsToDirectedEdge

Returns the directed edge from one cell to an adjacent one. Fails with E_RES_MISMATCH if the cells differ in resolution, and E_DIR_EDGE_INVALID if they are not neighbours.

C

TerraError cellsToDirectedEdge(TerraIndex origin, TerraIndex destination,
                               TerraIndex *out);

Python

terra.cells_to_directed_edge(origin, destination)

edge = terra.cells_to_directed_edge(a, b)
reverse = terra.cells_to_directed_edge(b, a)
# edge != reverse — direction is part of the identity

SQL

-- Key a flow measurement by the movement rather than the location
SELECT terra_cells_to_directed_edge(from_cell, to_cell) AS edge, volume
FROM movements;

isValidDirectedEdge

Tests whether a value is a well-formed directed edge. Validate anything arriving from outside your system, as with cells.

getDirectedEdgeOrigin / getDirectedEdgeDestination

Return the origin and destination cells of an edge.

terra.get_directed_edge_origin(edge)
terra.get_directed_edge_destination(edge)

directedEdgeToCells

Returns both endpoints at once, origin first. Cheaper than two separate calls when you need both.

origin, destination = terra.directed_edge_to_cells(edge)

originToDirectedEdges

Returns all six directed edges leaving a cell. Always exactly six.

Python

edges = terra.origin_to_directed_edges(cell)
len(edges)   # 6, always

SQL

-- Build an adjacency table for a cell set
SELECT cell, unnest(terra_origin_to_directed_edges(cell)) AS edge
FROM service_area;

directedEdgeToBoundary

Returns the geometry of the shared edge — the two vertices of the boundary segment between the cells, not the cells themselves.

Use this to draw the edge rather than the regions it separates: a barrier, a pipe run, a border segment, or a flow arrow anchored on the actual shared boundary.

terra.directed_edge_to_boundary(edge)
# Returns: list[tuple[float, float]] — two vertices

Worked pattern: aggregating flow

Directed edges aggregate like cells. Keyed by edge, a set of movement records reduces to a flow network with no geometry involved:

SELECT terra_cells_to_directed_edge(from_cell, to_cell) AS edge,
       sum(volume)                                      AS total
FROM movements
GROUP BY 1
ORDER BY total DESC
LIMIT 20;

Because origin and destination are recoverable from the edge, the result can be rendered directly without re-joining to the source table.

Next

• Traversal — gridDisk, gridRing, and grid distance
• Vertexes — the points where three cells meet

---

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