إنتقل إلى المحتوى الرئيسي

Core library overview

terra-core is the C implementation of the Terra grid. Every binding wraps it, so behaviour is identical across languages by construction rather than by agreement.

Design principles​

Arithmetic, not lookup. Indexing, traversal, and hierarchy operations are computed from the cell identifier. There is no spatial index, no geometry table, and no network dependency. Cost scales with the target resolution, not with dataset size.

No allocation in the core. Functions that return multiple results write into caller-allocated buffers, sized by the corresponding sizing helper. The core never allocates on the caller's behalf, so it can be used in constrained and embedded contexts.

Errors as return values. Every fallible function returns a TerraError; results are written through out-parameters. No global error state, so the library is thread-safe without coordination.

Deterministic and portable. The same inputs produce the same outputs on any platform. No floating-point dependence in identity operations — index arithmetic is integer throughout, and floating point appears only in projection and geometry.

Layered structure​

The library is layered, and each layer depends only on those below it:

Index layer — packing and unpacking the 64-bit identifier: mode, resolution, base cell, and child digits. Pure bit manipulation. Parent, child, and validity operations live here and touch no geometry at all.

Lattice layer — hexagonal lattice arithmetic in integer coordinates: neighbours, rings, grid distance, and the digit-to-offset mapping. Still integer, still no projection.

Projection layer — Lambert Azimuthal Equal Area forward and inverse transforms about 24°N 45°E, and the KSA-GRF17 ellipsoid parameters. The only place floating point is essential.

Geometry layer — cell centres, boundaries, vertexes, and region operations. Combines the lattice and projection layers.

Encoding layer — the Terra Grid Code: Base32 packing and the Luhn mod 32 check character.

The layering matters practically: a binding that only needs identity and hierarchy operations does not pull in the projection or geometry code, which is what keeps the WebAssembly build small.

Core types​

TerraIndex — an unsigned 64-bit integer holding a cell, a directed edge, or a vertex. The mode field distinguishes them.

TerraError — an enumerated result code. See Error handling.

TerraLatLng — a geographic coordinate in radians, on KSA-GRF17.

TerraCellBoundary — a fixed-capacity array of boundary vertices with a count.

Coordinates are held in radians internally. The conversion helpers exist because most callers work in degrees, but the core does not convert on every call.

Thread safety​

All functions are re-entrant and free of global mutable state. Multiple threads may call any function concurrently, provided they do not share an output buffer.

Testing and conformance​

The library is validated by round-trip properties — coordinate to cell to coordinate, cell to parent to child, index to string to index — and by the invariants the grid guarantees: exactly six neighbours at every resolution, exactly seven children per parent, ring sizes of exactly 6k, and resolution-constant cell area.

These invariants form the conformance suite any binding or independent implementation must pass. See Creating bindings.

Next​

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