Pipeline: OSM PBF → stitched road polylines → sliding-window turning-function descriptors (translation/rotation/scale invariant) → FAISS index. Query: same descriptor on the drawn curve → ANN search → banded-DTW re-rank → matches on a Leaflet map.

Setup#

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt          # serving only
.venv\Scripts\pip install -r requirements-build.txt    # + rebuilding the index

Memory footprint#

The server mmaps the geometry (coords.npy) and metadata, so resident RAM stays ~1.6GB for the full-US index (10.5M descriptors) instead of ~3GB. The FAISS index itself is loaded resident (default IVF inverted lists aren't mmap-able). Fits a 4GB machine. An existing .npz-format index can be migrated in place without rebuilding: python scripts/shrink_index.py index/us.

Build an index#

Download any extract from https://download.geofabrik.de/, then:

.venv\Scripts\python.exe -m pipeline.build_index data\west-virginia-latest.osm.pbf --out index\wv

Run#

$env:ROADSKETCH_INDEX = "index\wv"   # optional, this is the default
.venv\Scripts\python.exe server\app.py
# → http://localhost:8899

Layout#

pipeline/geometry.py — projection + arc-length resampling
pipeline/descriptors.py — turning-function descriptors, window sweep
pipeline/extract.py — PBF parsing + way stitching
pipeline/build_index.py — offline index build CLI
server/matching.py — ANN search + DTW re-rank
server/app.py — FastAPI app (API + static frontend)
web/ — draw pad + Leaflet UI

Tuning knobs#

descriptors.SCALES — window lengths swept along each road
descriptors.MIN_TOTAL_TURN — curviness floor (higher = smaller index, fewer boring matches)
extract.HIGHWAY_KEEP — road classes included

Configure Feed