This repository follows SPEC.md. The first implementation pass creates the full service skeleton, pure RF/math kernels, and Copernicus DEM sampling. Integrations that require PostGIS data, pycraf, ITM/P.1812, landcover/canopy rasters, or external viewshed binaries are exposed through stable interfaces and return explicit "not implemented" responses until the corresponding data pipeline is connected.

Layout

api/ - FastAPI service, core calculations, service orchestration, tests.
scripts/ - data bootstrap/import entry points.
data/ - mounted data volume for DEM, landcover, and canopy rasters.
docker-compose.yml - local stack with API, worker, Redis, PostGIS, optional tiler.

Quick Start

cp .env.example .env
docker compose up --build api redis postgis

The API is served at http://localhost:8000, with OpenAPI docs at /docs.

DEM Bootstrap

Download Copernicus DEM GLO-30 COG tiles for Saint Petersburg and Leningrad Oblast:

python scripts/bootstrap_dem.py --bbox 27.3,58.4,35.8,61.4 --output-dir data/dem
docker compose restart api worker

The API samples all .tif/.tiff files under DEM_PATH recursively. In Docker, the default DEM_PATH=/data/dem points to the mounted ./data/dem directory.

Buildings Bootstrap

Download an OSM PBF extract and import building polygons into PostGIS:

mkdir -p data/osm
wget -O data/osm/northwestern-fed-district-latest.osm.pbf \
  https://download.geofabrik.de/russia/northwestern-fed-district-latest.osm.pbf
sh scripts/load_buildings.sh data/osm/northwestern-fed-district-latest.osm.pbf
docker compose restart api worker

The import writes a buildings table with geom, height_m, levels, building_type, and source. Heights come from height, then building:levels * 3.0, then an estimated default by building type.

Check the API:

curl -s -X POST http://localhost:8000/api/v1/buildings/query \
  -H 'Content-Type: application/json' \
  -d '{"bbox":[30.30,59.93,30.33,59.95]}' | jq '.features | length'

For local Python development:

cd api
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest
python -m ruff check .