Custom DEPOT Map Tools written in Python

Valid as of v5.1.1

DISCLAIMER

• This is a wrapper for depot.
• BUILT FOR GERMANY, PLEASE MAKE SURE THAT OSM BUILDING TAGGING AND YOUR O/D MATRIX IS PRECISE!

Setting up .env file

# CITY_CODE, CITY_NAME, MAP_DESCRIPTION and MAP_CREATOR all have to change
# per city/map - everything below that already has a working default baked
# into the scripts, and only needs uncommenting/editing if your setup
# actually differs.

# 3-DIGIT CITY CODE
CITY_CODE = "FRA"

# --- Required for config.json (written automatically at the end of every
# run_demand_pipeline.py / rerun_enrichment.py run - no separate script) ---
CITY_NAME = "Frankfurt"
# {CITY_NAME} and {POPULATION_ROUNDED} are replaced with CITY_NAME above and
# the real population (summed from demand_data.json) rounded to the nearest
# 50,000, formatted with dots (e.g. 1.750.000).
MAP_DESCRIPTION = "Bring the subway to {CITY_NAME}! Over {POPULATION_ROUNDED} commuters want to go to their workplace and it's your job to get them there!"
MAP_CREATOR = "MergedEyes"

# Only needed for publish.py / release_maptools.py.
GITHUB_TOKEN = "<Github_Token_Classic>"

# --- Optional overrides (defaults shown) ---
# OSMPBF = "germany-latest.osm.pbf"
# CSV = "QZM_1X1KM.csv"
# RAW_BASE_DIR = "raw_map_files"
# OUTPUT_DIR = "Map_ZIPs"
# OSRM_URL = "http://localhost:5000"

# Hub (demand point) size dials - independent for residential (commuter-
# origin) hubs vs. job hubs. 1 = original tuning for that side. Set to 4 for
# hubs roughly 4x smaller and ~4x more numerous on that side; 0.5 for ~2x
# bigger/fewer. Real-world commuter totals never change, only how finely
# they're split across points. Lower JOB_SIZE_RATIO if jobs are spread
# across too many small destinations to design a profitable line around -
# this consolidates jobs into fewer, bigger hubs without touching
# residential granularity.
# RES_SIZE_RATIO = "1"
# JOB_SIZE_RATIO = "1"

• The bounding box is no longer set in .env - it's looked up automatically per city and saved to raw_map_files/CITY_CODE/CITY_CODE_MAP_DATA.json. The first time you run a script for a city with no saved bbox yet, it'll prompt you to paste one in (e.g. copied from boundingbox.klokantech.com).
• Some city codes can be found here.

Usage

Generating a map

This is handled by build.py, a thin wrapper around depot's own depot.maps.MapGen class - see depot's own examples/maps (HEL.py/LAXM.py) for further MapGen configuration options and depot's README for the full MapGen parameter/method reference.

python build.py

Generating demand data

This is handled by run_demand_pipeline.py, wrapping two composable pipeline stages exposed by generate_demand_qzm_local.py behind a small DemandGen class (demand_gen, already constructed for CITY_CODE at the bottom of the file) - the same build.py/MapGen-style shape, just for demand instead of map geometry.

Job hubs and residential hubs are consolidated independently and never merge into each other - RES_SIZE_RATIO/JOB_SIZE_RATIO in .env (see above) control each side's hub size/count on its own. If commuters end up spread across too many small, scattered job destinations to plan a profitable line around, lower JOB_SIZE_RATIO to fold jobs into fewer, bigger hubs without changing residential granularity at all.

DemandGen inputs

DemandGen methods

Both methods also rebuild config.json afterward (via config_utils.py) from CITY_NAME/MAP_DESCRIPTION/MAP_CREATOR in .env plus the population summed fresh from demand_data.json - there's no separate config-generation step or script to run by hand. run_all must complete at least once for a given city before run_enrich_only has a base checkpoint to enrich.

python run_demand_pipeline.py                # DemandGen.run_all()
python rerun_enrichment.py                    # DemandGen.run_enrich_only()

Running the scripts

Precautions

1. Install depot.
2. Run "pip install -r requirements.txt"
3. Download a .osm.pbf file you want to use to extract the mapdata from Geofabrik.
4. Get your commuters data in the INSPIRE-Grid format. Germany

Running the scripts

5. Get your initial map data with depot, running build.py (Check examples directory within depot (HEL.py/LAXM.py))
6. Set CITY_NAME/MAP_DESCRIPTION/MAP_CREATOR in .env (see Setting up .env file above) - required before this next step, since it now also writes config.json for you. Prepare the data, running run_demand_pipeline.py
7. Set correct coordinates for airport points, opening Google Maps and entering the correct cords into ./raw_map_files/CITY_CODE/custom_hubs.json, running open_maps.py
8. Generate the demand data, running run_demand_pipeline.py again. config.json is regenerated automatically at the end of this run too, with the final population - no separate config step needed. Reference for the full config.json schema: official documentation.
9. Run "ship.py none", to create the ZIP file. (none: No version change, major: Bumb major version, minor: Bump minor version, patch: Bump patch version inside config.json)
10. Import your ZIP into Railyard (locally) and test your map ingame.
11. (Optional) Make changes to the map, demand configuration, description, etc. Run build.py (only if you change the initial map/city), run_demand_pipeline.py, ship.py <none/major/minor/patch> again.
    • If you only changed something in the enrichment stage - RES_SIZE_RATIO/JOB_SIZE_RATIO or CITY_NAME/MAP_DESCRIPTION/MAP_CREATOR in .env, or hand-edited a special-demand JSON file - you don't need the full run_demand_pipeline.py run again. Run rerun_enrichment.py instead (see DemandGen methods above), which skips the much slower OSM parsing / airport snapping / base OSRM routing steps and still regenerates config.json:

      python rerun_enrichment.py
      

12. Publish your map to Github manually, OR:
13. Edit the parameters of publish.py and automatically publish your map to your Github-Repo, also generating a update.json for the SubwayBuilderModded Registry for your map automatically.

Scripts overview

Everything above walks through running these in order. Here's what each one actually does, for reference.

Scripts you run directly

Supporting modules

These aren't run directly - run_demand_pipeline.py and generate_demand_qzm_local.py import them.