LogicLayer Geoservice

High-performance, in-process geospatial analysis engine for LogicLayer and Tesseract OLAP.

This project provides a set of functions and classes to analyze geospatial data (Shapefiles, GeoParquet, GeoJSON) and calculate relationships such as neighbors, parents, children, and intersections. It is designed to work as a standalone library for analytical engines like Tesseract OLAP, or as a LogicLayer module to provide a REST API.

Architecture

The project is built around a schema-driven GeoEngine that utilizes DuckDB and its Spatial extension for geospatial processing.

• Schema-Driven: All geographic levels and their hierarchies are defined in a YAML/JSON configuration file.
• In-Process: No external database (like PostGIS) is required. DuckDB handles spatial indexing and joins in-memory or via local files.
• Lazy Loading: Geometries are only loaded into memory when a specific level is first queried, optimizing startup time and resource usage.
• CRS Independent: The engine performs spatial operations assuming all input files share the same Coordinate Reference System.

Development Setup

This project uses uv for dependency management.

Prerequisites

• Python 3.10 or higher.
• uv installed on your system.

Nix Development Shell

If you use the Nix package manager, you can start a development environment with all dependencies (Python, uv, ruff, etc.) pre-installed:

nix develop

Installation

Clone the repository and install the development dependencies:

git clone https://github.com/Datawheel/logiclayer-geoservice.git
cd logiclayer-geoservice
uv sync

Running Tests

We use pytest for testing. The tests include unit tests for the engine and integration tests for the LogicLayer module.

uv run pytest

Internal Usage

The GeoEngine class can be used directly within other Python projects (e.g., Tesseract OLAP) to resolve geospatial filters:

from logiclayer_geoservice import GeoEngine, load_schema

schema = load_schema("path/to/schema.yaml")
engine = GeoEngine(schema)

# Find all municipality IDs within a specific state
municipality_ids = engine.get_relations(
    level_id="state",
    target_level_id="municipality",
    geo_id="ST01",
    mode="children"
)

License

© 2024 Datawheel, LLC.