osmforge 1.1.2__tar.gz

osmforge-1.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Freeman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

osmforge-1.1.2/PKG-INFO

@@ -0,0 +1,374 @@
+Metadata-Version: 2.1
+Name: osmforge
+Version: 1.1.2
+Summary: Self-hosted OpenStreetMap stack and Python client for spatial analysis
+Home-page: https://github.com/Tom3man/osm-forge
+License: MIT
+Keywords: osm,openstreetmap,gis,geospatial,postgis,propagation
+Author: Tom Freeman
+Author-email: tomrfreeman3@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Dist: geopandas (>=1.1.1,<2.0.0)
+Requires-Dist: platformdirs (>=4.0,<5.0)
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Requires-Dist: shapely (>=2.1.2,<3.0.0)
+Project-URL: Documentation, https://tom3man.github.io/osm-forge/
+Project-URL: Repository, https://github.com/Tom3man/osm-forge
+Description-Content-Type: text/markdown
+
+# OSMForge
+
+A self-hosted OpenStreetMap stack that downloads regional OSM extracts, ingests
+them into a local PostGIS database, and serves a GeoJSON API optimised for
+spatial analysis — particularly **radio-frequency propagation modelling**.
+
+Public OSM APIs (Overpass, Nominatim) have strict rate limits and aren't suited
+to bulk or repeated spatial queries. OSMForge gives you unlimited local access
+to the same data.
+
+---
+
+## Contents
+
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Quick start](#quick-start)
+- [Adding regions](#adding-regions)
+- [Makefile reference](#makefile-reference)
+- [API reference](#api-reference)
+- [Python client](#python-client)
+- [Data layers](#data-layers)
+
+---
+
+## Architecture
+
+```
+Geofabrik  ──download──▶  *.osm.pbf
+                               │
+                          osm2pgsql (Lua flex)
+                               │
+                        osm schema (raw)
+                    osm_points / osm_lines / osm_polygons
+                               │
+                          make layers  (SQL)
+                               │
+                         app schema (classified)
+              osm_buildings / osm_roads / osm_water /
+              osm_vegetation / osm_landuse /
+              osm_structures / osm_terrain
+                               │
+                          FastAPI  :8000
+                               │
+                        osmforge.client
+```
+
+The `osm` schema holds raw data exactly as loaded by osm2pgsql.
+The `app` schema holds pre-classified, indexed tables ready for querying.
+
+---
+
+## Prerequisites
+
+| Tool | Version | Notes |
+|---|---|---|
+| Docker + Compose v2 | latest | `docker compose version` |
+| osm2pgsql | ≥ 1.9 | `osm2pgsql --version` |
+| Python | ≥ 3.12 | |
+| Poetry | ≥ 1.8 | `pip install poetry` |
+
+Install Python dependencies:
+
+```bash
+poetry install
+```
+
+---
+
+## Quick start
+
+### 1 — Start the database
+
+```bash
+make up
+```
+
+This starts a PostGIS 17 container on `localhost:5432` and the FastAPI container
+on `localhost:8000`. On first run Docker will pull the images.
+
+### 2 — Download an OSM extract
+
+Extracts come from [Geofabrik](https://download.geofabrik.de). Pass the full
+path from the Geofabrik URL:
+
+```bash
+make download REGION=europe/united-kingdom/england/isle-of-wight
+```
+
+The file lands in `osmforge/data/` and is skipped on subsequent runs unless you
+pass `FORCE=--force`.
+
+### 3 — Ingest + build layers
+
+```bash
+make ingest    # load every *.osm.pbf in osmforge/data/ into osm.*
+make layers    # build classified app.* tables
+```
+
+Or in one step:
+
+```bash
+make rebuild
+```
+
+### 4 — Query the API
+
+```bash
+curl "http://localhost:8000/propagation/bbox?min_lon=-1.35&min_lat=50.65&max_lon=-1.1&max_lat=50.78"
+```
+
+---
+
+## Adding regions
+
+Download as many regions as you like before ingesting — `make ingest` loads
+everything in `osmforge/data/` in a single pass.
+
+```bash
+# individual counties
+make download REGION=europe/united-kingdom/england/west-midlands
+make download REGION=europe/united-kingdom/england/staffordshire
+make download REGION=europe/united-kingdom/england/warwickshire
+
+# then ingest them all together
+make rebuild
+```
+
+To see what Geofabrik has available, browse:
+- England: https://download.geofabrik.de/europe/united-kingdom/england.html
+- Full index: https://download.geofabrik.de
+
+---
+
+## Makefile reference
+
+| Command | Description |
+|---|---|
+| `make up` | Start PostGIS + API containers |
+| `make down` | Stop containers (data volume preserved) |
+| `make download REGION=<path>` | Download a PBF from Geofabrik |
+| `make ingest` | Load all PBFs in `osmforge/data/` via osm2pgsql |
+| `make layers` | Build `app.*` tables from raw `osm.*` data |
+| `make rebuild` | `ingest` + `layers` in one step |
+| `make rebuild-api` | Rebuild the API Docker image after code changes |
+| `make clean` | Destroy containers **and** data volume (full reset) |
+| `make interface` | Open a psql shell to the database |
+| `make help` | List all targets |
+
+---
+
+## API reference
+
+The API runs at `http://localhost:8000`. Interactive docs at
+`http://localhost:8000/docs`.
+
+---
+
+### `GET /health`
+
+```
+200 {"status": "ok"}
+```
+
+---
+
+### `GET /propagation/bbox`
+
+Return classified OSM features within a bounding box.
+
+**Query parameters**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `min_lon` | float | ✓ | West edge (WGS-84) |
+| `min_lat` | float | ✓ | South edge |
+| `max_lon` | float | ✓ | East edge |
+| `max_lat` | float | ✓ | North edge |
+| `layers` | string (repeat) | | Subset of layers (default: all) |
+| `limit` | int | | Max features returned |
+
+**Example**
+
+```
+GET /propagation/bbox?min_lon=-1.35&min_lat=50.65&max_lon=-1.1&max_lat=50.78&layers=buildings&layers=terrain
+```
+
+**Response** — GeoJSON FeatureCollection. Each feature's `properties`:
+
+```json
+{
+  "osm_id": 123456,
+  "name": "St Mary's Church",
+  "layer": "buildings",
+  "feature_class": "church",
+  "height_m": 18.0,
+  "levels": "3",
+  "material": "stone"
+}
+```
+
+---
+
+### `POST /propagation/geometry`
+
+Return classified OSM features intersecting an arbitrary polygon or
+multipolygon. Useful when you already have a coverage or study-area polygon.
+
+**Request body**
+
+```json
+{
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [[[<lon>, <lat>], ...]]
+  },
+  "layers": ["buildings", "vegetation", "terrain"],
+  "limit": 5000
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `geometry` | GeoJSON geometry | ✓ | Polygon or MultiPolygon, WGS-84 |
+| `layers` | array of strings | | Subset of layers (default: all) |
+| `limit` | int | | Max features returned |
+
+---
+
+### `GET /features/bbox`
+
+Return **raw** OSM features (all tags) within a bounding box. Useful for
+exploration; use `/propagation/bbox` for modelling workflows.
+
+**Query parameters** — same bbox params as above, plus optional `limit`.
+
+---
+
+## Python client
+
+Install the package then import the client:
+
+```python
+from osmforge.client import OSMClient
+
+client = OSMClient()  # default: http://localhost:8000
+# or: OSMClient("http://my-server:8000")
+```
+
+All methods return a `geopandas.GeoDataFrame` (CRS EPSG:4326).
+
+---
+
+### `client.propagation_bbox`
+
+```python
+gdf = client.propagation_bbox(
+    min_lon=-1.35,
+    min_lat=50.65,
+    max_lon=-1.1,
+    max_lat=50.78,
+)
+```
+
+Filter to specific layers:
+
+```python
+gdf = client.propagation_bbox(
+    min_lon=-1.35, min_lat=50.65,
+    max_lon=-1.1,  max_lat=50.78,
+    layers=["buildings", "terrain"],
+    limit=10000,
+)
+```
+
+---
+
+### `client.propagation_geometry`
+
+Accepts a GeoJSON dict **or** a Shapely geometry:
+
+```python
+from shapely.geometry import Polygon
+
+area = Polygon([
+    (-1.35, 50.65), (-1.1, 50.65),
+    (-1.1, 50.78),  (-1.35, 50.78),
+    (-1.35, 50.65),
+])
+
+gdf = client.propagation_geometry(area)
+
+# with options
+gdf = client.propagation_geometry(
+    area,
+    layers=["buildings", "vegetation", "terrain"],
+    limit=50000,
+)
+```
+
+---
+
+### `client.features_bbox`
+
+```python
+gdf = client.features_bbox(
+    min_lon=-1.35,
+    min_lat=50.65,
+    max_lon=-1.1,
+    max_lat=50.78,
+)
+# gdf.columns → geometry, osm_id, name, source_layer, tags
+```
+
+---
+
+## Data layers
+
+| Layer | Source OSM tags | Key properties |
+|---|---|---|
+| `buildings` | `building=*` | `building_type`, `height_m`, `levels`, `material` |
+| `roads` | `highway=*`, `railway=*` | `transport_class` (major / secondary / local / rail / …) |
+| `water` | `natural=water`, `waterway=*`, `landuse=reservoir` | `water_class` |
+| `vegetation` | `landuse=forest`, `natural=wood/scrub/heath/grassland`, `leisure=park` | `vegetation_class` |
+| `landuse` | `landuse=*` | `landuse_class` (residential / industrial / agricultural / …) |
+| `structures` | `man_made=mast/tower`, `power=tower/line`, bridges, embankments | `structure_class` |
+| `terrain` | `natural=cliff/ridge/coastline/peak/saddle`, barriers, chimneys | `terrain_class`, `height_m` |
+
+### Height estimation
+
+`height_m` on buildings is derived from OSM tags in order of preference:
+
+1. `height=*` (metres, if numeric)
+2. `building:levels=*` × 3 m per floor
+3. `NULL` if neither is tagged
+
+### Terrain classes
+
+| `terrain_class` | Geometry | Propagation relevance |
+|---|---|---|
+| `cliff` | line | Hard diffraction edge |
+| `ridge` | line | Diffraction / shadowing |
+| `coastline` | line | Land/sea boundary — sea has near-zero attenuation |
+| `barrier_wall` | line | Urban canyon obstruction |
+| `embankment` / `cutting` | line | Signal blocking |
+| `peak` / `saddle` | point | Elevation proxy |
+| `chimney` / `storage_tank` | point | Tall point obstacles |
+| `communications_tower` | point | Co-channel interference sources |
+

osmforge-1.1.2/README.md

@@ -0,0 +1,348 @@
+# OSMForge
+
+A self-hosted OpenStreetMap stack that downloads regional OSM extracts, ingests
+them into a local PostGIS database, and serves a GeoJSON API optimised for
+spatial analysis — particularly **radio-frequency propagation modelling**.
+
+Public OSM APIs (Overpass, Nominatim) have strict rate limits and aren't suited
+to bulk or repeated spatial queries. OSMForge gives you unlimited local access
+to the same data.
+
+---
+
+## Contents
+
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Quick start](#quick-start)
+- [Adding regions](#adding-regions)
+- [Makefile reference](#makefile-reference)
+- [API reference](#api-reference)
+- [Python client](#python-client)
+- [Data layers](#data-layers)
+
+---
+
+## Architecture
+
+```
+Geofabrik  ──download──▶  *.osm.pbf
+                               │
+                          osm2pgsql (Lua flex)
+                               │
+                        osm schema (raw)
+                    osm_points / osm_lines / osm_polygons
+                               │
+                          make layers  (SQL)
+                               │
+                         app schema (classified)
+              osm_buildings / osm_roads / osm_water /
+              osm_vegetation / osm_landuse /
+              osm_structures / osm_terrain
+                               │
+                          FastAPI  :8000
+                               │
+                        osmforge.client
+```
+
+The `osm` schema holds raw data exactly as loaded by osm2pgsql.
+The `app` schema holds pre-classified, indexed tables ready for querying.
+
+---
+
+## Prerequisites
+
+| Tool | Version | Notes |
+|---|---|---|
+| Docker + Compose v2 | latest | `docker compose version` |
+| osm2pgsql | ≥ 1.9 | `osm2pgsql --version` |
+| Python | ≥ 3.12 | |
+| Poetry | ≥ 1.8 | `pip install poetry` |
+
+Install Python dependencies:
+
+```bash
+poetry install
+```
+
+---
+
+## Quick start
+
+### 1 — Start the database
+
+```bash
+make up
+```
+
+This starts a PostGIS 17 container on `localhost:5432` and the FastAPI container
+on `localhost:8000`. On first run Docker will pull the images.
+
+### 2 — Download an OSM extract
+
+Extracts come from [Geofabrik](https://download.geofabrik.de). Pass the full
+path from the Geofabrik URL:
+
+```bash
+make download REGION=europe/united-kingdom/england/isle-of-wight
+```
+
+The file lands in `osmforge/data/` and is skipped on subsequent runs unless you
+pass `FORCE=--force`.
+
+### 3 — Ingest + build layers
+
+```bash
+make ingest    # load every *.osm.pbf in osmforge/data/ into osm.*
+make layers    # build classified app.* tables
+```
+
+Or in one step:
+
+```bash
+make rebuild
+```
+
+### 4 — Query the API
+
+```bash
+curl "http://localhost:8000/propagation/bbox?min_lon=-1.35&min_lat=50.65&max_lon=-1.1&max_lat=50.78"
+```
+
+---
+
+## Adding regions
+
+Download as many regions as you like before ingesting — `make ingest` loads
+everything in `osmforge/data/` in a single pass.
+
+```bash
+# individual counties
+make download REGION=europe/united-kingdom/england/west-midlands
+make download REGION=europe/united-kingdom/england/staffordshire
+make download REGION=europe/united-kingdom/england/warwickshire
+
+# then ingest them all together
+make rebuild
+```
+
+To see what Geofabrik has available, browse:
+- England: https://download.geofabrik.de/europe/united-kingdom/england.html
+- Full index: https://download.geofabrik.de
+
+---
+
+## Makefile reference
+
+| Command | Description |
+|---|---|
+| `make up` | Start PostGIS + API containers |
+| `make down` | Stop containers (data volume preserved) |
+| `make download REGION=<path>` | Download a PBF from Geofabrik |
+| `make ingest` | Load all PBFs in `osmforge/data/` via osm2pgsql |
+| `make layers` | Build `app.*` tables from raw `osm.*` data |
+| `make rebuild` | `ingest` + `layers` in one step |
+| `make rebuild-api` | Rebuild the API Docker image after code changes |
+| `make clean` | Destroy containers **and** data volume (full reset) |
+| `make interface` | Open a psql shell to the database |
+| `make help` | List all targets |
+
+---
+
+## API reference
+
+The API runs at `http://localhost:8000`. Interactive docs at
+`http://localhost:8000/docs`.
+
+---
+
+### `GET /health`
+
+```
+200 {"status": "ok"}
+```
+
+---
+
+### `GET /propagation/bbox`
+
+Return classified OSM features within a bounding box.
+
+**Query parameters**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `min_lon` | float | ✓ | West edge (WGS-84) |
+| `min_lat` | float | ✓ | South edge |
+| `max_lon` | float | ✓ | East edge |
+| `max_lat` | float | ✓ | North edge |
+| `layers` | string (repeat) | | Subset of layers (default: all) |
+| `limit` | int | | Max features returned |
+
+**Example**
+
+```
+GET /propagation/bbox?min_lon=-1.35&min_lat=50.65&max_lon=-1.1&max_lat=50.78&layers=buildings&layers=terrain
+```
+
+**Response** — GeoJSON FeatureCollection. Each feature's `properties`:
+
+```json
+{
+  "osm_id": 123456,
+  "name": "St Mary's Church",
+  "layer": "buildings",
+  "feature_class": "church",
+  "height_m": 18.0,
+  "levels": "3",
+  "material": "stone"
+}
+```
+
+---
+
+### `POST /propagation/geometry`
+
+Return classified OSM features intersecting an arbitrary polygon or
+multipolygon. Useful when you already have a coverage or study-area polygon.
+
+**Request body**
+
+```json
+{
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [[[<lon>, <lat>], ...]]
+  },
+  "layers": ["buildings", "vegetation", "terrain"],
+  "limit": 5000
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `geometry` | GeoJSON geometry | ✓ | Polygon or MultiPolygon, WGS-84 |
+| `layers` | array of strings | | Subset of layers (default: all) |
+| `limit` | int | | Max features returned |
+
+---
+
+### `GET /features/bbox`
+
+Return **raw** OSM features (all tags) within a bounding box. Useful for
+exploration; use `/propagation/bbox` for modelling workflows.
+
+**Query parameters** — same bbox params as above, plus optional `limit`.
+
+---
+
+## Python client
+
+Install the package then import the client:
+
+```python
+from osmforge.client import OSMClient
+
+client = OSMClient()  # default: http://localhost:8000
+# or: OSMClient("http://my-server:8000")
+```
+
+All methods return a `geopandas.GeoDataFrame` (CRS EPSG:4326).
+
+---
+
+### `client.propagation_bbox`
+
+```python
+gdf = client.propagation_bbox(
+    min_lon=-1.35,
+    min_lat=50.65,
+    max_lon=-1.1,
+    max_lat=50.78,
+)
+```
+
+Filter to specific layers:
+
+```python
+gdf = client.propagation_bbox(
+    min_lon=-1.35, min_lat=50.65,
+    max_lon=-1.1,  max_lat=50.78,
+    layers=["buildings", "terrain"],
+    limit=10000,
+)
+```
+
+---
+
+### `client.propagation_geometry`
+
+Accepts a GeoJSON dict **or** a Shapely geometry:
+
+```python
+from shapely.geometry import Polygon
+
+area = Polygon([
+    (-1.35, 50.65), (-1.1, 50.65),
+    (-1.1, 50.78),  (-1.35, 50.78),
+    (-1.35, 50.65),
+])
+
+gdf = client.propagation_geometry(area)
+
+# with options
+gdf = client.propagation_geometry(
+    area,
+    layers=["buildings", "vegetation", "terrain"],
+    limit=50000,
+)
+```
+
+---
+
+### `client.features_bbox`
+
+```python
+gdf = client.features_bbox(
+    min_lon=-1.35,
+    min_lat=50.65,
+    max_lon=-1.1,
+    max_lat=50.78,
+)
+# gdf.columns → geometry, osm_id, name, source_layer, tags
+```
+
+---
+
+## Data layers
+
+| Layer | Source OSM tags | Key properties |
+|---|---|---|
+| `buildings` | `building=*` | `building_type`, `height_m`, `levels`, `material` |
+| `roads` | `highway=*`, `railway=*` | `transport_class` (major / secondary / local / rail / …) |
+| `water` | `natural=water`, `waterway=*`, `landuse=reservoir` | `water_class` |
+| `vegetation` | `landuse=forest`, `natural=wood/scrub/heath/grassland`, `leisure=park` | `vegetation_class` |
+| `landuse` | `landuse=*` | `landuse_class` (residential / industrial / agricultural / …) |
+| `structures` | `man_made=mast/tower`, `power=tower/line`, bridges, embankments | `structure_class` |
+| `terrain` | `natural=cliff/ridge/coastline/peak/saddle`, barriers, chimneys | `terrain_class`, `height_m` |
+
+### Height estimation
+
+`height_m` on buildings is derived from OSM tags in order of preference:
+
+1. `height=*` (metres, if numeric)
+2. `building:levels=*` × 3 m per floor
+3. `NULL` if neither is tagged
+
+### Terrain classes
+
+| `terrain_class` | Geometry | Propagation relevance |
+|---|---|---|
+| `cliff` | line | Hard diffraction edge |
+| `ridge` | line | Diffraction / shadowing |
+| `coastline` | line | Land/sea boundary — sea has near-zero attenuation |
+| `barrier_wall` | line | Urban canyon obstruction |
+| `embankment` / `cutting` | line | Signal blocking |
+| `peak` / `saddle` | point | Elevation proxy |
+| `chimney` / `storage_tank` | point | Tall point obstacles |
+| `communications_tower` | point | Co-channel interference sources |

osmforge-1.1.2/osmforge/__init__.py

@@ -0,0 +1,4 @@
+from .client import OSMClient, ALL_LAYERS
+from .download import get_data_dir
+
+__all__ = ["OSMClient", "ALL_LAYERS", "get_data_dir"]

osmforge-1.1.2/osmforge/client.py

@@ -0,0 +1,154 @@
+"""
+Thin Python client for the local OSM API.
+
+Usage:
+    from osmforge.client import OSMClient
+
+    client = OSMClient()  # defaults to http://localhost:8000
+
+    # By bounding box
+    gdf = client.propagation_bbox(min_lon=-1.6, min_lat=50.55, max_lon=-1.0, max_lat=50.85)
+
+    # By arbitrary polygon / multipolygon (shapely or GeoJSON dict)
+    gdf = client.propagation_geometry(my_polygon)
+
+    # Filter to specific layers
+    gdf = client.propagation_geometry(my_polygon, layers=["buildings", "terrain"])
+
+    # Raw OSM tags (no classification)
+    gdf = client.features_bbox(min_lon=-1.6, min_lat=50.55, max_lon=-1.0, max_lat=50.85)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+import geopandas as gpd
+import requests
+
+try:
+    from shapely.geometry import mapping
+    from shapely.geometry.base import BaseGeometry
+    _SHAPELY = True
+except ImportError:
+    _SHAPELY = False
+
+_GeoJSON = Dict[str, Any]
+_Geometry = Union[_GeoJSON, "BaseGeometry"]
+
+ALL_LAYERS = [
+    "buildings", "roads", "water",
+    "vegetation", "landuse", "structures", "terrain",
+]
+
+
+def _to_geojson(geometry: _Geometry) -> _GeoJSON:
+    if isinstance(geometry, dict):
+        return geometry
+    if _SHAPELY and isinstance(geometry, BaseGeometry):
+        return mapping(geometry)
+    raise TypeError(
+        f"geometry must be a GeoJSON dict or a Shapely geometry, got {type(geometry)}"
+    )
+
+
+class OSMClient:
+    def __init__(self, base_url: str = "http://localhost:8000"):
+        self.base_url = base_url.rstrip("/")
+
+    def _get(self, path: str, params: dict) -> dict:
+        r = requests.get(f"{self.base_url}{path}", params=params, timeout=120)
+        r.raise_for_status()
+        return r.json()
+
+    def _post(self, path: str, body: dict) -> dict:
+        r = requests.post(f"{self.base_url}{path}", json=body, timeout=120)
+        r.raise_for_status()
+        return r.json()
+
+    @staticmethod
+    def _to_gdf(fc: dict) -> gpd.GeoDataFrame:
+        features = fc.get("features", [])
+        if not features:
+            return gpd.GeoDataFrame()
+        return gpd.GeoDataFrame.from_features(features, crs="EPSG:4326")
+
+    # ------------------------------------------------------------------
+    # Public methods
+    # ------------------------------------------------------------------
+
+    def propagation_bbox(
+        self,
+        min_lon: float,
+        min_lat: float,
+        max_lon: float,
+        max_lat: float,
+        layers: Optional[List[str]] = None,
+        limit: Optional[int] = None,
+    ) -> gpd.GeoDataFrame:
+        """
+        Return propagation-classified features within a bounding box.
+
+        Parameters
+        ----------
+        min_lon, min_lat, max_lon, max_lat : float
+            Bounding box in WGS-84 degrees.
+        layers : list of str, optional
+            Subset of ALL_LAYERS to include. Defaults to all.
+        limit : int, optional
+            Maximum number of features to return.
+        """
+        params: dict = {
+            "min_lon": min_lon, "min_lat": min_lat,
+            "max_lon": max_lon, "max_lat": max_lat,
+        }
+        for layer in (layers or ALL_LAYERS):
+            params.setdefault("layers", [])
+            params["layers"].append(layer)
+        if limit is not None:
+            params["limit"] = limit
+        return self._to_gdf(self._get("/propagation/bbox", params))
+
+    def propagation_geometry(
+        self,
+        geometry: _Geometry,
+        layers: Optional[List[str]] = None,
+        limit: Optional[int] = None,
+    ) -> gpd.GeoDataFrame:
+        """
+        Return propagation-classified features intersecting a polygon or multipolygon.
+
+        Parameters
+        ----------
+        geometry : GeoJSON dict or Shapely geometry
+            The area of interest (Polygon or MultiPolygon).
+        layers : list of str, optional
+            Subset of ALL_LAYERS to include. Defaults to all.
+        limit : int, optional
+            Maximum number of features to return.
+        """
+        body: dict = {"geometry": _to_geojson(geometry), "layers": layers or ALL_LAYERS}
+        if limit is not None:
+            body["limit"] = limit
+        return self._to_gdf(self._post("/propagation/geometry", body))
+
+    def features_bbox(
+        self,
+        min_lon: float,
+        min_lat: float,
+        max_lon: float,
+        max_lat: float,
+        limit: Optional[int] = None,
+    ) -> gpd.GeoDataFrame:
+        """
+        Return raw OSM features (all tags) within a bounding box.
+
+        Useful for exploration; use propagation_bbox for modelling.
+        """
+        params: dict = {
+            "min_lon": min_lon, "min_lat": min_lat,
+            "max_lon": max_lon, "max_lat": max_lat,
+        }
+        if limit is not None:
+            params["limit"] = limit
+        return self._to_gdf(self._get("/features/bbox", params))

osmforge-1.1.2/osmforge/docker-compose.yaml

@@ -0,0 +1,32 @@
+services:
+  db:
+    image: postgis/postgis:17-3.6-alpine
+    container_name: osm-postgis
+    environment:
+      POSTGRES_DB: osm
+      POSTGRES_USER: osm
+      POSTGRES_PASSWORD: osm
+    ports:
+      - "5432:5432"
+    volumes:
+      - osm_pgdata:/var/lib/postgresql/data
+      - ./db/init:/docker-entrypoint-initdb.d
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U osm -d osm"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  api:
+    build: ./fastapi
+    container_name: osm-api
+    environment:
+      DATABASE_URL: postgresql+psycopg://osm:osm@db:5432/osm
+    ports:
+      - "8000:8000"
+    depends_on:
+      db:
+        condition: service_healthy
+
+volumes:
+  osm_pgdata:

osmforge-1.1.2/osmforge/download.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Download OSM PBF extracts from Geofabrik.
+
+Usage:
+    python3 osmforge/download.py <region-path> [region-path ...]
+    python3 osmforge/download.py --force <region-path>
+
+Examples:
+    python3 osmforge/download.py europe/united-kingdom/england/isle-of-wight
+    python3 osmforge/download.py europe/united-kingdom/england/greater-london
+    python3 osmforge/download.py europe/united-kingdom/england/west-midlands \
+                                  europe/united-kingdom/england/staffordshire
+
+Or via make:
+    make download REGION=europe/united-kingdom/england/isle-of-wight
+    make download REGION="europe/united-kingdom/england/west-midlands europe/united-kingdom/england/staffordshire"
+"""
+
+import os
+import sys
+import time
+from pathlib import Path
+
+import requests
+from platformdirs import user_data_dir
+
+BASE_URL = "https://download.geofabrik.de"
+INTER_FILE_DELAY = 2  # seconds between downloads
+
+
+def get_data_dir() -> Path:
+    """
+    Resolve the directory where PBF files are stored.
+
+    Priority:
+      1. OSMFORGE_DATA_DIR environment variable
+      2. OS user-data directory (~/.local/share/osmforge on Linux,
+         ~/Library/Application Support/osmforge on macOS, etc.)
+    """
+    env = os.environ.get("OSMFORGE_DATA_DIR")
+    path = Path(env) if env else Path(user_data_dir("osmforge"))
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def dest_path(region_path: str, data_dir: Path) -> Path:
+    leaf = region_path.rstrip("/").split("/")[-1]
+    return data_dir / f"{leaf}-latest.osm.pbf"
+
+
+def download(region_path: str, force: bool = False) -> Path:
+    data_dir = get_data_dir()
+    url = f"{BASE_URL}/{region_path}-latest.osm.pbf"
+    dest = dest_path(region_path, data_dir)
+
+    if dest.exists() and not force:
+        size_mb = dest.stat().st_size / 1_048_576
+        print(f"  [skip] {dest.name} already exists ({size_mb:.1f} MB)")
+        return dest
+
+    print(f"  -> {url}")
+    print(f"  saving to {dest}")
+
+    tmp = dest.with_suffix(".part")
+    try:
+        with requests.get(url, stream=True, timeout=60) as r:
+            r.raise_for_status()
+            total = int(r.headers.get("content-length", 0))
+            downloaded = 0
+            with tmp.open("wb") as f:
+                for chunk in r.iter_content(chunk_size=1 << 20):
+                    f.write(chunk)
+                    downloaded += len(chunk)
+                    if total:
+                        pct = downloaded / total * 100
+                        mb = downloaded / 1_048_576
+                        print(
+                            f"\r    {mb:6.1f} / {total/1_048_576:.1f} MB"
+                            f"  ({pct:.0f}%)",
+                            end="",
+                            flush=True,
+                        )
+        print()
+        tmp.rename(dest)
+        print(f"  saved -> {dest.name}")
+    except Exception:
+        tmp.unlink(missing_ok=True)
+        raise
+
+    return dest
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    force = "--force" in args
+    regions = [a for a in args if not a.startswith("--")]
+
+    if not regions:
+        print(__doc__)
+        sys.exit(1)
+
+    print(f"Queued {len(regions)} region(s):\n")
+    for i, region in enumerate(regions):
+        print(f"[{i + 1}/{len(regions)}] {region}")
+        download(region, force=force)
+        if i < len(regions) - 1:
+            time.sleep(INTER_FILE_DELAY)
+
+    print("\nDone.")
+
+
+if __name__ == "__main__":
+    main()

osmforge-1.1.2/pyproject.toml

@@ -0,0 +1,84 @@
+[tool.poetry]
+name = "osmforge"
+version = "1.1.2"
+description = "Self-hosted OpenStreetMap stack and Python client for spatial analysis"
+authors = ["Tom Freeman <tomrfreeman3@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/Tom3man/osm-forge"
+repository = "https://github.com/Tom3man/osm-forge"
+documentation = "https://tom3man.github.io/osm-forge/"
+keywords = ["osm", "openstreetmap", "gis", "geospatial", "postgis", "propagation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: GIS",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+
+# Only ship the client-side modules; the server stack lives in the repo only.
+packages = [{include = "osmforge"}]
+exclude = [
+    "osmforge/db",
+    "osmforge/fastapi",
+    "osmforge/osm2pgsql",
+    "osmforge/data",
+]
+
+
+[tool.poetry.dependencies]
+# Runtime — installed when users `pip install osmforge`
+python     = "^3.12"
+requests   = "^2.32.5"
+geopandas  = "^1.1.1"
+shapely    = "^2.1.2"
+platformdirs = "^4.0"
+
+
+[tool.poetry.group.dev.dependencies]
+# Server stack + notebook tooling — not published to PyPI
+fastapi    = "^0.121.0"
+uvicorn    = "^0.38.0"
+psycopg    = {extras = ["binary"], version = "^3.0"}
+click      = "^8.3.0"
+ipykernel  = "^7.2.0"
+matplotlib = "^3.10.8"
+# Quality tooling
+ruff       = "^0.9"
+mypy       = "^1.11"
+pytest     = "^8.0"
+
+
+[tool.poetry.group.docs.dependencies]
+mkdocs             = "^1.6"
+mkdocs-material    = "^9.5"
+mkdocstrings       = {extras = ["python"], version = "^0.27"}
+
+
+[tool.poetry.scripts]
+osmforge-download = "osmforge.download:main"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+strict = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]