MAPPER

Multimodal Accessibility and Place Profiling Engine for Regions.
Open-data pipeline that turns OSM, GTFS, and census inputs into multimodal, H3-aligned accessibility fields.

Builds mode-specific travel-time graphs, harmonizes 130+ opportunity layers, runs network KDE to produce continuous accessibility fields, and exports them on a national H3 grid — ready for digital twins, GIS, and GeoAI workflows.

---

Why MAPPER

• Scalable and reproducible — tested at country scale (Germany), runs on a single workstation for city regions.
• Multimodal by default — walk, bike, drive, and walk+transit with real GTFS timetables; each mode produces its own output columns.
• Harmonized opportunity layers — OSM POI, Sentinel-2 land-cover proxies, and workplace/census attributes in a single schema.
• H3-native output — every result lands on a uniform hexagonal grid for direct use with DT/GeoAI stacks.
• Native C++ core — RoutingKit-backed NKDE with OpenMP parallelism; Python handles config, orchestration, and I/O.

---

Installation

Requirements

• Linux (Ubuntu 22.04+) or macOS — macOS supported but untested
• GCC ≥ 11, CMake ≥ 3.16
• Miniforge or Miniconda

1 — Install conda (if needed)

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh -b -p ~/miniforge3
~/miniforge3/bin/conda init

2 — Clone and bootstrap

mapper.sh creates the mapper conda environment, installs Python dependencies, and builds the C++ libraries in one step:

git clone https://github.com/tillzacher/gravity_framework.git
cd gravity_framework
bash mapper.sh --no-launch

--no-launch builds everything without starting the TUI. Run it once after cloning and again after pulling breaking changes.

---

Quickstart — Hamburg

The included configs/mapper_config.example.py targets Hamburg and runs out of the box.

# 1. Fetch OSM + GTFS data for Hamburg
bash mapper.sh fetch -c configs/mapper_config.example.py

# 2. Run the pipeline
bash mapper.sh -c configs/mapper_config.example.py

Results land in results/<run-id>/cells.parquet alongside a JSON metadata file.

---

Input Data

OSM (always required)

MAPPER downloads OSM network and POI data automatically from Geofabrik when you run bash mapper.sh fetch -c .... The REGION key in your config must be the exact Geofabrik path slug for your area — copy it from the URL structure on the Geofabrik downloads page.

https://download.geofabrik.de/europe/germany/hamburg.html
                               ↑ slug: "europe/germany/hamburg"

https://download.geofabrik.de/europe/france.html
                               ↑ slug: "europe/france"

Data is cached under data/<REGION>/ and reused on subsequent runs.

GTFS (required for transit modes only)

Transit modes (transit, walk_transit, walk_transit_bus, walk_transit_rail) require a GTFS schedule file. OSM-only modes (walk, bike, drive) work without one.

Germany — the fetch command downloads the GTFS feed automatically:

bash mapper.sh fetch -c configs/mapper_config.example.py

All other countries — download a GTFS zip for your region and place it at:

data/<REGION>/gtfs.zip

For example, for "REGION": "europe/france", the file must be at:

data/europe/france/gtfs.zip

If your GTFS file is somewhere else, point GTFS_PATH at it in your config:

"GTFS_PATH": "/path/to/my_feed.zip",

GTFS feeds are available from transit agencies directly, or from aggregators such as Mobility Database and transit.land.

---

Terminal UI

Launch the interactive TUI:

bash mapper.sh

Or directly from the activated environment:

conda activate mapper
python main.py

Navigation

Key	Action
b	Previous tab (Home / Runs / Results)
n	Next tab
Tab	Cycle forward through panes within the active tab
Shift+Tab	Cycle backward through panes
↑ / ↓	Move within a table or log
← / →	Cycle between buttons when a button row is focused
Enter	Activate the focused widget / button
q	Quit

The Home tab lets you pick a config and launch a run. The Runs tab shows run history, live logs, and control buttons. The Results tab lets you inspect output columns and generate plots.

---

CLI

All TUI operations are also available from the command line via mapper (after conda activate mapper) or bash mapper.sh:

# Fetch input data
bash mapper.sh fetch -c configs/my_region.py

# Run the pipeline headlessly
bash mapper.sh -c configs/my_region.py

# Force a clean rebuild (ignore caches)
bash mapper.sh -c configs/my_region.py --force-rebuild

Pass --dry-run to fetch to see what would be downloaded without downloading it.

---

Adding a New Region

1 — Copy the example config

cp configs/mapper_config.example.py configs/my_city.py

2 — Edit the five key fields

CONFIG = {
    # Geofabrik path slug — must match exactly (see Input Data section above)
    "REGION": "europe/germany/berlin",

    # Transport modes — transit modes require a GTFS file (see Input Data)
    "MODES": ["walk", "walk_transit"],

    # OSM POI categories to use as accessibility targets
    "AMENITIES": ["hospital", "school", "supermarket"],

    # Travel-time cutoff in seconds (1800 = 30 min)
    "CUTOFF": 1800,
}

3 — Fetch and run

bash mapper.sh fetch -c configs/my_city.py
bash mapper.sh -c configs/my_city.py

All configs live under configs/. The full list of available keys and their defaults is in docs/configuration.md.

---

C++ Libraries

The native RoutingKit NKDE and graph libraries are built automatically by mapper.sh --no-launch. To rebuild manually:

# Full rebuild (deps + all targets + smoke tests)
bash source/infra/bootstrap_cpp_worker.sh

# Individual targets
bash source/cpp/build.sh graph     # libgraph.so     — OSM/GTFS parser
bash source/cpp/build.sh nkde      # libroutingkit.so — RoutingKit NKDE + hex sampler
bash source/cpp/build.sh extended  # libgraph_ext.so  — preprocessing
bash source/cpp/build.sh pipeline  # run_pipeline_cpp — native orchestrator

Artifacts land in source/cpp/.build/. Compatibility symlinks under source/modules/ are refreshed automatically.

---

Documentation

File	Contents
docs/configuration.md	Full config key reference with defaults
docs/architecture.md	Pipeline stages, C++ ↔ Python boundaries
docs/deployment.md	Detailed install, HPC, and container setup
docs/troubleshooting.md	Common issues and fixes

---

License

Apache License 2.0 — see LICENSE.