Foundations / Spatial on Ometeotl, an abstract decision meta-model

BoundingBox

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/bounding_box.py

Local role: Pure-Python, frozen-dataclass implementation of the Geometry protocol. The only concrete geometry at the foundations layer — makes the spatial module fully usable without any adapter.

Big-picture role: Used as the geometry type G for GeometricSpace[BoundingBox], SpatialExtent[BoundingBox], and SpatialMap[BoundingBox] when no adapter is installed. Adapter-backed geometry types must expose a .bounds property that returns a BoundingBox, enabling fallback comparisons.

Fields

min_x: float — left boundary
min_y: float — bottom boundary
max_x: float — right boundary
max_y: float — top boundary

Raises ValueError on construction if min_x > max_x or min_y > max_y.

Coordinate2D / Coordinate3D / GeoCoordinate / GridCell

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/coordinates.py

Local role: Pure immutable value types for expressing positions. No geometry logic — arithmetic, distance, and projection belong to Geometry implementations.

Coordinate2D

Frozen dataclass. A position in a flat 2-D Cartesian or projected plane.

Fields:

x: float
y: float

Coordinate3D

Frozen dataclass. A position in a 3-D Cartesian space.

Fields:

x: float
y: float
z: float

GeoCoordinate

Frozen dataclass. A geographic position in the GeoJSON longitude/latitude convention.

Fields:

CoordinateKind / CoordinateSystem / Predefined Singletons

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/coordinate_system.py

Local role: Vocabulary for describing coordinate frames attached to geometries and spatial extents.

CoordinateKind

str, Enum. Nature of a coordinate system. Inherits from str so values serialise to their string form without a custom JSON encoder.

Values:

CARTESIAN = "cartesian"
GEOGRAPHIC = "geographic"
GRID = "grid"
CUSTOM = "custom"

CoordinateSystem

Frozen dataclass. Describes the coordinate frame used by a geometry or extent.

Fields:

name: str — human-readable identifier (e.g. "wgs84")
kind: CoordinateKind — broad category
unit: str — native unit of measure ("meter", "degree", "cell")
srid: Optional[int] = None — EPSG code for geographic/projected systems

Methods:

derive_space_relations

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/relation_derivation.py

Local role: Bridge function from the spatial foundations layer back to ometeotl_core. Compares geometries pairwise and populates a SpaceRelationGraph with the resulting topological relations.

Big-picture role: Closes the loop from concrete geometry back to the abstract core model. The caller passes GeometricSpace objects (which carry both space.id and geometry) and receives a SpaceRelationGraph ready for use in world-level reasoning.

Signature

def derive_space_relations(
 spaces: Iterable[GeometricSpace],
 *,
 skip_abstract: bool = True,
 adjacency_tolerance: float = 0.0,
 derive_containment: bool = True,
 derive_intersection: bool = True,
 derive_adjacency: bool = True,
) -> SpaceRelationGraph:

Algorithm

For each unordered pair (A, B) the function checks in priority order:

GeometricSpace

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/geometric_space.py

Local role: Frozen generic dataclass that composes a core Space with a concrete geometry. The primary user-facing type for spatial spaces in the foundations layer.

Big-picture role: GeometricSpace[G] answers both ontological questions (kind, is_abstract, dimensions) and spatial questions (geometry) through a single object, without touching the Space dataclass directly. It is the input type for derive_space_relations().

Design principle: composition over inheritance — GeometricSpace wraps Space rather than subclassing it. This avoids dataclass + Generic[G] inheritance pitfalls and keeps ometeotl_core untouched.

Geometry Protocol

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/geometry.py

Local role: Structural Protocol (PEP 544) that all geometry implementations must satisfy. Decorated with @runtime_checkable so isinstance(obj, Geometry) guards work at runtime.

Big-picture role: The contract between the spatial foundations layer and adapter backends. BoundingBox satisfies it at the foundations layer; the Shapely adapter will wrap shapely.geometry.* objects in a thin class that also satisfies it.

Protocol members

Properties:

area -> float — area in the native units of the coordinate system; 0 for point/line geometries
centroid -> Coordinate2D — geometric centroid as a 2-D coordinate
bounds -> BoundingBox — axis-aligned bounding box of the geometry

Methods:

SpatialBackend Protocol

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/spatial_backend.py

Local role: runtime_checkable Protocol defining the adapter factory interface. An adapter backend implements this protocol to expose library-backed geometry construction and spatial indexing to the rest of the system.

Big-picture role: The foundations layer itself does not provide a concrete backend — BoundingBox is the pure-Python fallback geometry. The Shapely adapter (ometeotl_adapters/spatial_shapely/) will implement this protocol using shapely.geometry.* factories.

Protocol members

make_point(coord: Coordinate2D) -> Geometry — create a point geometry from a 2-D coordinate
make_point_3d(coord: Coordinate3D) -> Geometry — create a point geometry from a 3-D coordinate
make_polygon(exterior: List[Coordinate2D]) -> Geometry — create a simple polygon from an exterior ring; backends close the ring internally if needed
make_buffer(geom: Geometry, distance: float) -> Geometry — return geom expanded by distance (in native units of the geometry’s coordinate system)
make_bounding_box(min_x, min_y, max_x, max_y) -> Geometry — create a rectangular geometry from explicit AABB coordinates; may return a BoundingBox or a library-specific rectangle
make_index() -> SpatialIndex — create an empty spatial index backed by this adapter

Design notes

Typed coordinate arguments (Coordinate2D, Coordinate3D) rather than variadic *coords prevent arity bugs and preserve type-checker information.
Construction operations (buffer, union) are on SpatialBackend, not on the Geometry protocol — geometry objects are value objects; the backend is the factory.

Example (illustrative — implementation lives in the adapter layer):

SpatialExtent

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/spatial_extent.py

Local role: Frozen generic dataclass recording where a non-space object (actor, resource, etc.) is located within a named coordinate frame.

Big-picture role: Distinct from GeometricSpace:

GeometricSpace describes what shape a space IS.
SpatialExtent describes where an object IS within a space.

SpatialMap[G] maps ObjectId → SpatialExtent[G] to track actor and resource positions.

Type parameter

G — the concrete geometry type (e.g. BoundingBox). Must satisfy the Geometry protocol.

Fields

space_id: ObjectId — loose reference (by ID string) to the GeometricSpace that defines the coordinate frame; keeps SpatialExtent lightweight with no hard dependency on the space collection
geometry: G — the object’s footprint or position
coordinate_system: CoordinateSystem = CARTESIAN_2D — coordinate frame of geometry
metadata: JsonMap = {} — arbitrary key/value annotations

Frozen — mutations create a new SpatialExtent.

SpatialIndex Protocol

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/spatial_index.py

Local role: runtime_checkable Protocol for spatially indexed object lookup. Defines the contract that adapter-backed index implementations (e.g. rtree) must satisfy.

Big-picture role: The foundations layer does not ship a concrete SpatialIndex implementation. SpatialMap uses a linear O(n) scan that is correct for all inputs. Adapter subclasses of SpatialMap override ids_containing_point and ids_intersecting with a SpatialIndex-backed implementation.

Protocol members

insert(object_id: ObjectId, bounds: BoundingBox) -> None — register object_id with its axis-aligned bounding box
remove(object_id: ObjectId) -> None — remove object_id from the index; no-op if not present
query(bounds: BoundingBox) -> List[ObjectId] — return IDs of all objects whose bounds intersect bounds
query_point(point: Coordinate2D) -> List[ObjectId] — return IDs of all objects whose bounds contain point; provided as first-class because point-in-box is the most common lookup and adapters can implement it more efficiently than query(BoundingBox.from_point(point))

Design notes

No update() method — callers use remove then insert to move an entry.
All operations are keyed by ObjectId (string alias).
The index stores bounding boxes only, not full geometry objects.

Example (illustrative — no concrete implementation in foundations):

SpatialMap

Mon, 01 Jan 0001 00:00:00 +0000

Source:

src/ometeotl_foundations/spatial/spatial_map.py

Local role: Mutable generic container mapping ObjectId → SpatialExtent[G]. Concrete class — not a Protocol.

Big-picture role: Tracks spatial positions for actors, resources, or any other objects within a coordinate frame. The default implementation scans all extents linearly for spatial queries; adapter subclasses override the query methods with a SpatialIndex-backed implementation for O(log n) performance.

Type parameter

G — bound to Geometry. The concrete geometry type stored in all extents within this map.