Configuration

Calculon resolves configuration from three levels with increasing priority:

Hardcoded defaults < Config file < CLI arguments

CLI arguments

calculon [OPTIONS]

Options:
  -t, --tile-dir <TILE_DIR>      Path to the tile directory (required)
  -b, --bind <BIND>              Address to bind (default: 0.0.0.0:8002)
      --cache-size <CACHE_SIZE>  LRU tile cache size (default: 200)
  -c, --config <CONFIG>          Path to config file (default: calculon.toml in CWD)

Config file

Calculon looks for calculon.toml in the current working directory by default. Use --config to specify a different path.

tile_dir = "/data/valhalla/tiles"
bind = "0.0.0.0:8002"
cache_size = 200

[costing.auto]
use_highways = 0.5
use_tolls = 0.5
top_speed = 140

[costing.bicycle]
cycling_speed = 20.0
use_roads = 0.5

[costing.pedestrian]
walking_speed = 5.1

Values in [costing.*] sections set server-wide defaults that apply to every request unless overridden by per-request costing_options.

Auto (driving) options

Option	Range	Default	Description
`use_highways`	0.0 - 1.0	0.5	Highway preference (0 = avoid, 1 = prefer)
`use_tolls`	0.0 - 1.0	0.5	Toll road preference (0 = avoid, 1 = prefer)
`use_distance`	0.0 - 1.0	0.0	Distance vs time trade-off (0 = fastest, 1 = shortest)
`top_speed`	10 - 252	140	Maximum speed in kph
`toll_booth_cost`	0+	15.0	Seconds added at toll booths
`destination_only_penalty`	0+	600.0	Penalty for destination-only edges (seconds)
`maneuver_penalty`	0+	5.0	Penalty for name-inconsistent turns (seconds)
`signal_penalty`	0+	0.5	Traffic signal penalty (seconds)
`surface_factor`	0.0 - 1.0	0.5	Surface quality impact on cost
`service_penalty`	0+	75.0	Penalty for service roads (seconds)
`shortest`	bool	false	Pure distance-based routing

Bicycle options

Option	Range	Default	Description
`cycling_speed`	5 - 60	18.0	Base cycling speed in kph
`use_roads`	0.0 - 1.0	0.25	Road preference (0 = avoid roads, 1 = prefer)
`use_hills`	0.0 - 1.0	0.25	Hill preference (0 = avoid, 1 = prefer)
`avoid_bad_surfaces`	0.0 - 1.0	0.25	Bad surface avoidance penalty
`use_living_streets`	0.0 - 1.0	0.5	Living street preference
`maneuver_penalty`	0+	5.0	Penalty for name-inconsistent turns (seconds)
`gate_penalty`	0+	300.0	Penalty for passing through a gate (seconds)
`shortest`	bool	false	Pure distance-based routing

Pedestrian options

Option	Range	Default	Description
`walking_speed`	0.5 - 25	5.1	Base walking speed in kph
`walkway_factor`	0.1+	1.0	Cost factor for walkways (lower = prefer)
`sidewalk_factor`	0.1+	1.0	Cost factor when sidewalk present (lower = prefer)
`alley_factor`	0.1+	2.0	Cost factor for alleys (higher = avoid)
`driveway_factor`	0.1+	5.0	Cost factor for driveways (higher = avoid)
`step_penalty`	0+	30.0	Penalty for steps (seconds)
`use_hills`	0.0 - 1.0	0.5	Hill preference (0 = avoid, 1 = prefer)
`max_hiking_difficulty`	0 - 6	1	Maximum SAC hiking scale
`use_lit`	0.0 - 1.0	0.0	Preference for lit roads (0 = don't care)
`use_living_streets`	0.0 - 1.0	0.6	Living street preference
`maneuver_penalty`	0+	5.0	Penalty for name-inconsistent turns (seconds)
`shortest`	bool	false	Pure distance-based routing

Option merge

Options are merged in order: hardcoded defaults < config file < per-request costing_options.

Config filePer-request override

[costing.auto]
use_highways = 0.8
use_tolls = 0.2

{
  "locations": [...],
  "costing": "auto",
  "costing_options": {
    "auto": {
      "use_highways": 0.3
    }
  }
}

In this example, use_highways is 0.3 (request wins), use_tolls is 0.2 (config wins over hardcoded 0.5), and all other options use hardcoded defaults.