Skip to main content

Vertex functions

A vertex is a corner of a cell. In a hexagonal grid exactly three cells meet at each vertex, and Terra gives that shared point its own identifier — so the same corner has the same identity regardless of which of the three cells you approached it from.

This is worth having because hexagons meet three at a time rather than four. A point falling on a corner has three candidate containers rather than four, and giving the corner an identity removes the ambiguity from any code that has to reason about it.

Each cell has six vertexes. Because each is shared by three cells, a large cell set has approximately twice as many vertexes as cells, not six times.

cellToVertex​

Returns one vertex of a cell by index, 0–5. Vertex numbering is fixed and consistent, so vertex n of a cell is always the same corner.

terra.cell_to_vertex(cell, 0)

The identifier returned is shared: the same corner reached from any of its three cells yields the same value.

cellToVertexes​

Returns all six vertexes of a cell, in order.

vertexes = terra.cell_to_vertexes(cell)
len(vertexes)   # 6

Order matches the vertex order of cellToBoundary, so the two can be zipped: vertex identifiers alongside their coordinates.

vertexToLatLng​

Returns the position of a vertex.

lat, lon = terra.vertex_to_latlng(vertex)

Since the vertex identifier is shared between the three cells meeting there, this position is identical however it was derived — which is what makes vertexes usable as join keys.

isValidVertex​

Tests whether a value is a well-formed vertex identifier.

Worked pattern: deduplicating a mesh​

Rendering a large cell set naively emits six vertices per cell, most of them duplicated three times. Keyed by vertex identifier, the duplication disappears:

positions = {}
for cell in cells:
    for v in terra.cell_to_vertexes(cell):
        if v not in positions:
            positions[v] = terra.vertex_to_latlng(v)

For a large contiguous set this reduces the vertex count by roughly two thirds, and — because the key is exact rather than a coordinate comparison — it avoids the floating-point tolerance problems that come with deduplicating by position.

Worked pattern: corner-adjacent cells​

Cells sharing only a corner are not neighbours, since a neighbour shares an edge. Where corner contact matters — contiguity rules, percolation, connectivity analysis — vertexes give it directly:

def corner_touching(cell):
    out = set()
    for v in terra.cell_to_vertexes(cell):
        out.update(terra.vertex_to_cells(v))
    out.discard(cell)
    return out

Next​

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