PlanX

How to Use This Manual

This manual is the definitive academic reference for every algorithm in PlanX — Urban Analytics Studio (v4.10.1). It is written for urban planners, spatial analysts, researchers, and students who need to understand not just what a tool produces, but why the method works, how to configure it correctly, and what the results mean in a real planning context.

Structure of each algorithm entry

Every one of the 69 algorithms is documented to an identical eight-section template:

1. Overview — what problem it solves and how, in one page
2. Theoretical Background — the academic lineage, key contributors, assumptions
3. Mathematical Formulation — every equation with term-by-term explanation
4. Input Data Requirements — what data you need, where to get it, how to prepare it
5. Parameters — every dialog tab, every input, with recommendations per scenario
6. Output Description — every output field, its meaning, units, and typical ranges
7. Symbolic Representation — how to style the results in QGIS for publication
8. Interpretation Guide — how to read the results, common pitfalls, planning actions

Academic references

Each algorithm section concludes with a curated list of academic references — the foundational papers, textbooks, and technical reports that underpin the method. Where a DOI exists, it is provided as a clickable link to the published version. Conference proceedings, institutional reports, and older monographs that do not assign DOIs are cited with full bibliographic detail and, where available, a stable institutional URL. All references have been selected to support both theoretical understanding and applied planning practice.

Typographic conventions

• monospace — parameter names, field names, code identifiers
• bold — key concepts on first introduction
• italic — journal names, book titles, emphasis
• Math is rendered with MathJax: $E = mc^2$ for inline, $$E = mc^2 \tag{1}$$ for display

Introduction to PlanX

PlanX — Urban Analytics Studio is a comprehensive geospatial analysis platform delivered as a QGIS Processing provider. Its 69 algorithms span the full urban-planning workflow: from understanding the existing city (network analysis, morphology, microclimate) through diagnosing problems (equity, accessibility, walkability) to designing and evaluating interventions (optimization, growth simulation, scenario comparison).

Architecture

PlanX follows a strict three-layer architecture:

1. Algorithm layer (algorithms/alg_*.py) — thin QGIS Processing wrappers that define parameters, validate inputs, and format outputs. They contain no analytical logic.
2. Engine layer (engine/*.py) — pure NumPy/SciPy modules that implement every method. They contain no QGIS imports and can be tested, profiled, and reasoned about independently.
3. Plugin shell (planx.py, provider.py, studio_dock.py) — the QGIS integration surface: menus, docks, the tool browser, and the dashboard.

This separation means the mathematics described in this manual corresponds directly to the NumPy implementation in engine/ — what you read here is what runs.

The 19 tool groups

Design principles

• No external solvers. Every method runs inside the plugin using only NumPy (and optionally SciPy for sparse-matrix acceleration, with an identical pure-Python fallback). No web services, no licensed libraries, no cloud dependencies.
• Deterministic. Given the same inputs and version, every algorithm produces identical outputs. Random seeds are fixed; tie-breaking is lexicographic.
• Screening, not compliance. The environmental modules (noise, air quality, solar) are professional screening tools — they use the standard engineering formulas but are not a substitute for detailed environmental impact assessment by a licensed professional.

1. Network Analysis

The Network Analysis group provides the foundational graph infrastructure for the entire PlanX platform. Streets are modelled as an undirected primal graph where junctions are nodes and street segments are edges weighted by length (or a user-specified cost field). On this graph, the group builds the six classic transport-network queries: preparation (topological cleaning and node assignment), origin–destination cost matrices and routes, service areas (isochrones), nearest-facility allocation, and link criticality screening.

All six tools share a single Dijkstra engine (engine/paths.py) that uses scipy.sparse.csgraph when available and a pure-Python heapq kernel otherwise, with identical results asserted by unit tests. The engine tracks predecessor nodes and edge identifiers through the shortest-path tree, enabling full route-geometry reconstruction — not just costs.

Prepare Network

Processing ID: planx:preparenetwork

Overview

Converts raw street centreline layers into a topologically clean, routable network graph. This is the mandatory first step before any other network tool in PlanX: it snaps endpoints, assigns node IDs, computes edge lengths, and builds the adjacency structure that every downstream algorithm consumes. Without this preparation, crossing lines that appear connected visually will be treated as separate, unconnected edges — producing broken routes and nonsensical isochrones.

Theoretical Background

Academic lineage

Transport network analysis inherits from graph theory, whose formal foundations were laid by Leonhard Euler in 1736 with the Koenigsberg bridge problem — the first demonstration that the geometry of connection, not the geometry of distance, governs whether a network can be traversed. The modern computational treatment begins with Dijkstra's shortest-path algorithm (Dijkstra, 1959), which introduced the priority-queue relaxation paradigm that remains the backbone of every routing engine six decades later. In the GIS domain, network preparation was systematised through the 1990s and early 2000s as transportation agencies digitised their road inventories: the key contributions are the planar enforcement rules of early GIS topology engines (ARC/INFO, circa 1982), the generalised network data model of Goodchild (1998), and Curtin's (2007) comprehensive review that codified the distinction between geometric line layers and topological networks.

More recently, the explosion of OpenStreetMap (founded 2004) as a global road dataset made network preparation a routine prerequisite rather than a specialist task — but also introduced new challenges: OSM contributors draw crossing roads that do not share a node, double-digitised carriageways, and dangling stubs. The field has converged on a standard pipeline: (1) snap endpoints within a tolerance, (2) split lines at mutual intersections, (3) build an adjacency structure. This is the pipeline implemented in PlanX, and it is functionally equivalent to the v.clean tool in GRASS GIS, the pgRouting topology builder, and NetworkX's from_edgelist — but runs in pure NumPy with an R-tree spatial index so that no external network library is required.

Key assumptions

• Planarity. The algorithm assumes that street segments form a planar or near-planar graph. Overpasses, tunnels, and grade-separated intersections create false crossings that must be resolved before preparation — the tool cannot distinguish a genuine intersection from a bridge crossing on the basis of geometry alone. A level or layer attribute should be used to split the input beforehand if grade separation matters for routing.
• Projected CRS. Edge lengths are computed as Euclidean distances in map units. A geographic CRS (latitude–longitude degrees) will produce edge lengths in decimal degrees, which are meaningless for any distance-based analysis. Use a local UTM zone or an equal-area projection.
• Tolerance sensitivity. The snapping tolerance $\varepsilon$ is the most consequential parameter. Too small: crossing lines that appear connected visually remain disconnected in the graph. Too large: distinct intersections collapse into a single junction, creating false adjacency. A value of 0.5–1.0 metre works well for urban street-centreline data at 1:1,000–1:10,000 scale. For OSM data in dense urban cores, start at 1.0 m and inspect the result before proceeding.
• Undirected graph. The network is built as an undirected graph — all edges can be traversed in both directions. For one-way streets, filter the edge set after preparation and remove the forbidden direction from the adjacency list.
• No turn penalties. The primal graph representation does not model turn costs at intersections; a junction is a single node where all incident edges meet. If turn penalties matter (e.g. banned left turns, signalised intersection delays), use a line graph (dual graph) representation instead — this is precisely what the Space Syntax tool does with its segment angular analysis.

When to use vs. when NOT to use

Use Prepare Network when: you have a raw street-centreline layer and intend to run any downstream network analysis (shortest paths, catchments, centrality). The tool is mandatory before OD Cost Matrix, OD Routes, Service Areas, Nearest Facility, Link Criticality, Network Centrality, and Space Syntax. In practice, Prepare Network should be the first step in every PlanX project that involves the street grid.

Do NOT use when: (a) the input is already a verified topological network (e.g. a pgRouting export, a previous Prepare Network output with intact node_a/node_b fields); (b) the analysis does not involve routing — building metrics, solar radiation, and demographic analysis do not need a prepared network graph; (c) the input contains grade-separated crossings that geometry alone cannot resolve, and you lack a level attribute to split on — in this case, manually split the input at the known bridge/underpass locations first.

Mathematical Formulation

Given a set of $m$ polylines $\{P_1, \ldots, P_m\}$ where each polyline is a sequence of coordinate pairs $P_i = \{(x_1, y_1), \ldots, (x_{k_i}, y_{k_i})\}$, the algorithm constructs a primal graph $G = (V, E)$ through the following sequence of operations.

Node set $V$ — snapping and deduplication. The raw endpoints of every polyline segment form a multiset of coordinate pairs. Two endpoints $p, q$ are snapped together when their Euclidean distance falls within the tolerance $\varepsilon$. The implementation uses an R-tree spatial index: for each unprocessed endpoint $p$, a bounding-box query of radius $\varepsilon$ retrieves nearby endpoints; all within tolerance are merged to their centroid. Formally:

where $\varepsilon$ is the snapping tolerance (default: 1.0 map unit). This step transforms $O(m^2)$ naive pairwise checking into $O(m \log m)$ spatial-index lookups. Nodes are assigned consecutive integer IDs $0, 1, \ldots, n-1$ after deduplication.

Edge set $E$ — splitting at mutual intersections. For every pair of segments that intersect at a point $p_{int}$ not already a node, both segments are split at $p_{int}$, and $p_{int}$ is added to $V$. This ensures that the resulting graph is planarised: every edge intersection corresponds to a node. Each edge $e = (u, v)$ carries a weight equal to either its geometric length or a user-specified cost field value:

where $\ell_e$ is the Euclidean length of the segment in map units, computed as the sum of distances between consecutive vertices along the polyline:

When a cost field $f_{\text{cost}}(e)$ is provided (e.g. travel time in seconds), the edge weight becomes that field's value. This is critical for time-based routing: a short but slow street (e.g. a pedestrian lane with stairs) can carry a higher cost than a longer but faster one. The cost must be additive — a sum over segments, not an average or a rate. Speed fields (km/h) must be converted to travel time (length/speed) before use.

Adjacency — CSR representation. The graph is stored as a compressed sparse row (CSR) tuple $(indptr, indices, data)$ where:

• $indptr[i]$ marks the start of the adjacency list for node $i$
• $indices[j]$ is the destination node of the $j$-th adjacency entry
• $data[j]$ is the weight (cost) of the edge at position $j$

Because the graph is undirected, each edge $(u, v)$ produces two adjacency entries: $(u \rightarrow v)$ and $(v \rightarrow u)$, both with the same weight. The CSR format is directly consumable by SciPy's csgraph.dijkstra for the C-accelerated fast path, and by PlanX's pure-Python heapq Dijkstra kernel for the fallback — both producing numerically identical results.

Edge multiplicity. If two segments share the same endpoint pair $(u, v)$ (parallel edges, e.g. dual carriageways digitised as separate lines), both are retained as separate adjacency entries. The Dijkstra kernels correctly handle parallel edges: during relaxation, each entry is considered independently, and the one yielding the lower cumulative cost wins. The predecessor-tracking variant (shortest_path_tree) records which specific edge was traversed, enabling correct route reconstruction even with parallel edges — a capability that distinguishes it from simpler CSR Dijkstra implementations.

Complexity. With $m$ input polylines producing $n$ nodes and $e$ edges after splitting, the preparation runs in $O(m \log m + e)$ time dominated by the R-tree spatial-index construction and the intersection tests. For a typical urban network of 10,000 street segments, preparation completes in under 5 seconds on commodity hardware.

Input Data Requirements

Where to obtain: OpenStreetMap (via QuickOSM, Overpass Turbo, or the OSM Downloader plugin), municipal GIS portals, national mapping agencies. For OSM, download the highway key with values motorway, trunk, primary, secondary, tertiary, residential, living_street, pedestrian, footway, cycleway, path.

Preprocessing: Remove duplicate geometries, fix invalid geometries (Fix Geometries tool), ensure lines are not multipart (use Multipart to Singleparts). Dead-end stubs are fine; the graph handles degree-1 nodes naturally.

Parameters

Output Description

Symbolic Representation

Style the output as a thin line (0.3 mm) in dark grey. Nodes (junctions) can be visualised by extracting the unique endpoints and styling as small circles (1 mm). Colour-code by node_a if you need to trace connectivity. The prepared network is an intermediate product — its visual quality matters less than its topological correctness.

Interpretation Guide

Verifying preparation quality

The prepared network is an intermediate product — its visual quality matters less than its topological correctness. Three diagnostic checks should be performed before proceeding to downstream analyses:

1. Node degree histogram. In a typical urban grid, most junctions have degree 3 (T-intersection) or degree 4 (cross-intersection). Degree-2 nodes represent polyline vertices that were not split — they are interior points along a segment, not true intersections. Degree-1 nodes are dead-ends (cul-de-sac terminations or network-edge stubs). A histogram heavy on degree-1 nodes with no cul-de-sac geography suggests undersnapping — endpoints that should have merged but did not. A histogram with degree 5+ nodes suggests oversnapping — distinct intersections collapsed into one.
2. Service area quick test. Run a single Service Areas analysis with a 500 m break on one centrally located facility. The resulting catchment should form a contiguous, roughly isotropic blob with no gaps or spikes. Gaps indicate disconnected segments within the buffer; spikes along a single street indicate the only connected corridor. If the catchment resembles a starburst along one road but ignores large adjacent areas, the snapping tolerance was too low — crossing streets look connected visually but are not in the graph.
3. Edge count sanity check. The number of edges in the output should equal the number of input segments plus the number of intersection splits. If it grows by more than 10–15%, the input probably had many false crossings (unresolved grade separations); if it shrinks, duplicate geometries were present in the input.

Cost field selection

The choice between geometric length and a custom cost field is the single most important decision at the preparation stage, because it carries through to every downstream analysis. Length-based routing answers the question "how far is it on the map?" Time-based routing answers "how long does it take?" — and in urban environments with heterogeneous street types, the two can diverge dramatically:

• Walkability studies: use the time_fwd_min field from Walking Slope Comfort as the cost field. This accounts for slope-induced speed differences, so uphill walks are priced honestly and downhill walks get the speed bonus they confer in reality.
• Vehicular analysis: use a travel-time field computed from posted speed limits. A 500 m motorway segment at 100 km/h costs 0.3 min; the same length on a 30 km/h residential street costs 1.0 min — a factor of three difference that geometric-length routing cannot capture.
• Transit access: use walking time to a stop, not Euclidean distance. A bus stop 200 m away as the crow flies but 600 m by the footpath network is effectively three times farther than it appears.

Common misinterpretations

• "The network is ready because the lines look connected." Visual inspection of a line layer tells you nothing about topological connectivity. Two lines that cross on screen but lack a shared node are not connected in the graph — Dijkstra will route around them, producing routes that jump nonsensically. This is the most frequent cause of "buggy" network analysis results in GIS, and Prepare Network exists precisely to eliminate it.
• "Larger tolerance = more robust." A snapping tolerance larger than about half the minimum block length will merge distinct intersections. In dense urban cores where blocks are 50–80 m wide, a tolerance of 25 m or more can collapse the entire neighbourhood's junctions into a single super-node, making the graph useless. Always start with the smallest plausible tolerance (0.5–1.0 m for urban data) and increase only if inspection reveals unsnapped crossings.
• "Cost = speed." The cost field must be additive — it accumulates along a path as a sum. Speed (km/h) is not additive: the average of two segment speeds is not the sum. If your data contains a speed field, precompute cost = length / speed in the attribute table and use that precomputed field.

Cross-references

The prepared network's node_a, node_b, and cost fields are consumed by every downstream tool in Group 1 (Network Analysis) and Group 2 (Centrality & Space Syntax). The CSR graph built during preparation is serialised internally and reused across sessions when the input layer's file path and modification timestamp match — this cache avoids repeated preparation of the same network. For slope-aware or speed-aware routing, compute the cost field in a preprocessing step (Walking Slope Comfort or an external field calculator) and pass it to Prepare Network as COST_FIELD.

Academic References

Curtin, K.M. (2007). "Network Analysis in Geographic Information Science: Review, Assessment, and Projections." Cartography and Geographic Information Science, 34(2), 103–111. DOI: 10.1559/152304007781002163

Dijkstra, E.W. (1959). "A Note on Two Problems in Connexion with Graphs." Numerische Mathematik, 1(1), 269–271. DOI: 10.1007/BF01386390

Barabasi, A.-L. & Albert, R. (1999). "Emergence of Scaling in Random Networks." Science, 286(5439), 509–512. DOI: 10.1126/science.286.5439.509

Rodrigue, J.-P., Comtois, C. & Slack, B. (2017). The Geography of Transport Systems. 4th ed., Routledge. textbook, no DOI assigned] Available at: transportgeography.org

2. Centrality & Space Syntax

This group quantifies the structural position of every street segment within the network — how central or peripheral it is, how much through-movement it attracts, and how easily it can be reached. The two tools are complementary: Network Centrality works on the primal graph with metric (Euclidean/length) costs, computing the four canonical centrality measures — closeness, betweenness, straightness, and eigenvector. Space Syntax works on the segment dual graph with angular costs (turn degree ÷ 90), computing the Hillier space-syntax measures of angular integration (to-movement potential) and angular choice (through-movement potential), including the size-normalised NACH and NAIN indices.

Taken together, these two tools provide the configurational diagnosis of a street network — the single most influential analysis in the PlanX suite for master-plan evaluation, because street configuration, once built, persists for centuries.

Network Centrality

Processing ID: planx:networkcentrality

Overview

Computes four classic graph-centrality indices for every node in a prepared street network: closeness (how near a node is to all others), betweenness (how many shortest paths pass through a node), straightness (how direct routes from a node are, comparing Euclidean to network distance), and eigenvector centrality (how connected a node is to other well-connected nodes, via power iteration). Each measure can be computed at multiple metric radii to separate local from global structure.

The tool uses Brandes' (2001) $O(nm + n^2 \log n)$ algorithm for betweenness with radius limiting and optional source sampling for large networks. Closeness follows the Wasserman–Faust normalisation so that values are comparable across networks of different sizes.

Theoretical Background

Academic lineage

Centrality is one of the oldest and most studied concepts in network science. Its modern form traces to Alex Bavelas (1948), who first formalised the mathematical properties of group structures at MIT's Group Networks Laboratory under Kurt Lewin, showing that the position of a person within a communication network determined their influence and efficiency. Linton Freeman (1977) unified the proliferating measures into a coherent framework, establishing that three distinct structural properties — degree (activity), closeness (efficiency of access), and betweenness (control over flows) — capture fundamentally different dimensions of being "central." Phillip Bonacich (1972) introduced the eigenvector formulation: a node's centrality is proportional to the sum of its neighbours' centralities, capturing the recursive notion that being connected to a central node is more valuable than being connected to a peripheral one.

In urban studies, centrality measures translate directly into spatial quantities with economic meaning. Porta, Crucitti & Latora (2006a, 2006b) were the first to apply the full set of centrality indices to street networks at city scale under the label Multiple Centrality Assessment (MCA). Their landmark finding: self-organised (historically grown) cities exhibit scale-free centrality distributions similar to those found in biological and social networks, while planned cities do not — the planning act truncates the power-law tail. Sevtsuk & Mekonnen (2012) operationalised this as a GIS toolbox (Urban Network Analysis for ArcGIS), adding building-level weighting, so that two neighbouring buildings on the same street segment receive different reach scores if one has more residents. The PlanX implementation follows the same primal-graph, metric-cost paradigm but runs entirely within QGIS using the embedded Dijkstra and Brandes kernels.

Key assumptions

• Shortest-path behaviour. All four measures assume that movement, interaction, or influence follows shortest (least-cost) paths. This is a reasonable first approximation for vehicular and pedestrian movement in uncontested street networks, but it systematically underestimates centrality on streets that people use despite not being on the shortest path — scenic routes, historic streets, and shopping high streets that people deliberately detour to visit.
• Node-level aggregation. Centrality is computed at graph nodes (junctions), not at edges (segments). This means the result is a point layer, not a line layer. For segment-level analysis (e.g. "which street segments are most central?"), use Space Syntax, which operates on the segment dual graph.
• Undirected graph. The graph is treated as undirected — centrality does not distinguish inbound from outbound movement. For directional centrality (e.g. morning-peak inbound betweenness), the graph must be constructed with directed edges, which PlanX's primal graph does not currently support.
• Radius sensitivity. Radius choice is the most consequential parameter. A small radius (400 m) reveals neighbourhood centres; a large radius (5000+ m) reveals the metropolitan structural core. Running only the global radius ("n") conflates all scales and can mask a clear neighbourhood centre behind a weak global score.
• Sample approximation. When SAMPLE < 1.0, betweenness is estimated from a random subset of source nodes and scaled proportionally. The estimate is unbiased (expected value equals the exact value) but has variance proportional to $1/\sqrt{k}$ where $k$ is the number of sampled sources. At 10% sampling, betweenness rank-order correlations are typically $r > 0.95$ with the exact values — sufficient for mapping and ranking, but insufficient for precise numerical thresholds.

When to use vs. when NOT to use

Use Network Centrality when: you need a multi-dimensional diagnosis of the network's structural organisation (not the demand-weighted consequences — use Link Criticality for that); when comparing the spatial structure of different cities or different neighbourhoods within a city; when identifying candidate locations for new services (high closeness nodes), new transit corridors (high betweenness edges), or bypasses (high betweenness nodes that are also bottlenecks).

Do NOT use when: (a) you need segment-level (not node-level) centrality — use Space Syntax; (b) you need demand-weighted criticality — use Link Criticality; (c) the network is very small (under 100 nodes) and the ranking is driven by edge effects rather than structure — buffer your study area with at least one neighbourhood's worth of extra network; (d) you need directed (in/out) centrality for transport planning — the undirected primal graph does not distinguish directions.

Mathematical Formulation

Closeness (Wasserman–Faust):

where $d(i,j)$ is the shortest-path distance, $V_r(i)$ is the set of nodes reachable from $i$ within radius $r$, and $N_r(i) = |V_r(i)|$. The first factor is the Wasserman–Faust correction for partial reachability; the second is the raw closeness (inverse mean distance).

Betweenness (Brandes, 2001):

where $\sigma_{st}$ is the number of shortest paths from $s$ to $t$, and $\sigma_{st}(v)$ is the number of those paths that pass through $v$.

Straightness:

Eigenvector centrality:

where $\lambda$ is the largest eigenvalue of the adjacency matrix $A + I$, and $\mathcal{N}(i)$ is the set of neighbours of node $i$. The power iteration converges when $\|x^{(k+1)} - x^{(k)}\|_\infty < 10^{-6}$.

Input Data Requirements

Parameters

Output Description

(One set per radius; suffix is the radius label, e.g. closeness_800, betweenness_n.)

Symbolic Representation

Map betweenness with a graduated renderer using a sequential multi-hue ramp (Viridis or Inferno) in natural-breaks classification (5–7 classes). Closeness benefits from the same treatment. Straightness works well with a diverging ramp (RdYlGn) centred at the median. Eigenvector centrality is best visualised with quantile classification (5 classes) to expose the rank structure — the top quintile marks the spatial core. Always set the minimum symbol size to 0.5 mm and scale to 3 mm at maximum, with 30–50% opacity to handle overplotting in dense areas.

Interpretation Guide

Numerical benchmarks

• Closeness (Wasserman–Faust). Values range [0, 1]. >0.6 = highly accessible node — likely the geometric centre, ideal for facilities that serve the entire city. 0.3–0.6 = typical neighbourhood junction. <0.15 = peripheral or isolated node — edges of the network, cul-de-sac terminations. On a global-radius run, the mean closeness in a compact orthogonal grid typically falls in 0.35–0.50; in suburban cul-de-sac subdivisions, it falls to 0.10–0.20 — a factor of ~3 difference in accessibility efficiency.
• Betweenness (raw count). This is the most right-skewed distribution in urban data — the top 1% of nodes often account for 30–50% of all betweenness. Raw counts are not comparable across networks of different sizes; normalise by dividing by $(N-1)(N-2)$ to obtain the probability that a random shortest path passes through the node. A node with normalised betweenness above 0.01 (1% of all paths) is a significant movement corridor; above 0.05 is a structural backbone segment.
• Straightness. Values range [0, 1]. >0.85 = the network radiates from this node nearly as efficiently as the crow flies (typical of nodes at the centre of a perfect grid). 0.6–0.85 = good radial connectivity. 0.4–0.6 = moderate circuitousness. <0.4 = highly circuitous — residents from this node must travel at least 2.5 times the crow-flight distance on average. This is the "cul-de-sac tax" in one number.
• Eigenvector centrality. Values typically range [0, 1] after normalisation by the maximum. Values are on a relative scale within each network — comparisons across networks require a shared normalisation scheme. The top quintile (top 20%) marks the spatial core; the top 5% marks the "core of the core" where the city's most interconnected streets converge.

Spatial pattern reading

• Monocentric city: a single high-closeness peak at the historic centre, with values decaying radially. Betweenness peaks on the radial arterials leading to the centre. This is the classic pre-automobile pattern.
• Polycentric city: multiple high-closeness peaks at sub-centres. Betweenness peaks on the orbital and radial connectors linking them. This pattern emerged with suburbanisation and is the target of most contemporary planning policy (e.g. the "15-minute city" concept).
• Grid city: closeness is broadly uniform across the grid (most nodes have similar access), but betweenness concentrates on a few longest straight avenues. This is a distinctive signature: a grid distributes closeness evenly but concentrates betweenness sharply.
• Dendritic (tree-like) suburb: closeness is low everywhere except the collector road that feeds the arterial. Betweenness concentrates on the single entry/exit point — the entire subdivision's traffic passes through one node, which is both a bottleneck and a single point of failure.

The four-measure matrix

Each measure answers a different planning question, and the four together provide a complete structural diagnosis:

Cross-references

Cross-reference with Space Syntax: metric betweenness correlates with angular choice (NACH), and metric closeness correlates with angular integration (NAIN). The correlation is typically $r \approx 0.7$–$0.85$ in grid cities, falling to $r \approx 0.5$ in cities with irregular geometry or organic street patterns. Discrepancies between the metric and angular pictures reveal where the geometry of the grid matters beyond simple distance — a long, straight boulevard may score high on metric closeness but low on angular integration if it turns sharply relative to the surrounding grid, forcing large angular costs at its ends.

Feed high-betweenness nodes into Link Criticality as OD origins/destinations to test how vulnerable the network's busiest corridors are. Overlay betweenness on Walkability Audit scores — streets with high betweenness but low walkability are the corridors where pedestrian infrastructure investment yields the highest safety return per metre.

Common misinterpretations

• "Higher centrality = better." Betweenness is a double-edged sword: a street with extremely high betweenness is a movement corridor, but also a severance barrier, a noise corridor, and an air-pollution hotspot. The top 1% of betweenness values often mark streets that need traffic calming or bypass construction, not celebration.
• "Eigenvector centrality replaces the others." Eigenvector centrality captures a different structural property — recursive prestige — that does not substitute for closeness or betweenness. A node can have high eigenvector centrality (connected to well-connected nodes) but low closeness (far from the geometric centre) and low betweenness (few paths pass through it). Each measure must be read separately.
• "Straightness near 1.0 means good connectivity." A node on a straight motorway through empty countryside can have straightness = 1.0 (because the motorway is straight) but low closeness (because there are no other nodes nearby to connect to). Straightness measures route directness, not route availability — always read it together with closeness.

Academic References

Bavelas, A. (1948). "A Mathematical Model for Group Structures." Human Organization, 7(3), 16–30. DOI: 10.17730/humo.7.3.f4033344851gl053

Bonacich, P. (1972). "Factoring and Weighting Approaches to Status Scores and Clique Identification." Journal of Mathematical Sociology, 2(1), 113–120. DOI: 10.1080/0022250X.1972.9989806

Brandes, U. (2001). "A Faster Algorithm for Betweenness Centrality." Journal of Mathematical Sociology, 25(2), 163–177. DOI: 10.1080/0022250X.2001.9990249

Crucitti, P., Latora, V. & Porta, S. (2006). "Centrality in Networks of Urban Streets." Chaos, 16, 015113. DOI: 10.1063/1.2150162

Freeman, L.C. (1977). "A Set of Measures of Centrality Based on Betweenness." Sociometry, 40(1), 35–41. DOI: 10.2307/3033543

Porta, S., Crucitti, P., & Latora, V. (2006). "The Network Analysis of Urban Streets: A Primal Approach." Environment and Planning B: Planning and Design, 33(5), 705–725. DOI: 10.1068/b32045

Sevtsuk, A. & Mekonnen, M. (2012). "Urban Network Analysis: A New Toolbox for ArcGIS." Revue Internationale de Geomatique, 22(2), 287–305. DOI: 10.3166/rig.22.287-305

Wasserman, S. & Faust, K. (1994). Social Network Analysis: Methods and Applications. Cambridge University Press. DOI: 10.1017/CBO9780511815478

Space Syntax (Segment Angular Analysis)

Processing ID: planx:spacesyntax

Overview

Performs segment angular analysis — the modern space syntax workflow — directly on road centreline segments. Unlike traditional axial-map space syntax, this method uses the segment dual graph: each street segment between junctions becomes a node, and connections between segments carry an angular cost equal to the turn angle in degrees divided by 90 (straight = 0, right angle = 1). Shortest paths minimise this angular cost, effectively finding the least-turning routes through the city.

For every specified radius, the tool computes six measures per segment: NC (node count reached), TD (angular total depth), MD (angular mean depth), NAIN (normalised angular integration — to-movement potential), CH (raw angular choice — through-movement count), and NACH (normalised angular choice). The normalised measures follow Hillier, Yang & Turner (2012) and are size-independent, enabling comparison across cities of different sizes.

Theoretical Background

Academic lineage

Space syntax theory, pioneered by Bill Hillier and colleagues at the Bartlett School of Architecture, University College London, since the early 1970s, posits that the spatial configuration of a city — the pattern of connections and barriers in its street network — is the primary generator of movement, land-use patterns, and social encounters. This is the "theory of natural movement" (Hillier et al., 1993): the grid itself, more than any land-use designation or planning policy, determines where people walk, drive, and gather. The founding text, The Social Logic of Space (Hillier & Hanson, 1984), demonstrated that buildings and settlements across cultures and centuries follow configurational rules that are mathematically describable — space is not a neutral container but an active structuring force.

The evolution of the method has three generations. Each generation solved a limitation of the previous one while introducing its own:

1. Axial analysis (1970s–1990s). The fewest and longest lines of sight covering all open public space, connected at their intersections. The axial map is the line-of-sight representation: each axial line is a node in the dual graph, and connections carry unit cost. Axial depth — the number of axial steps from one line to another — was the first configurational measure. The method is elegant but suffers from two fundamental problems: it requires subjective judgement in drawing the axial lines (two practitioners drawing the same neighbourhood produce different maps), and it is resolution-dependent — denser areas generate more axial lines, which inflates integration scores, making cross-city comparison impossible.
2. Segment angular analysis (Turner, 2001). Rather than drawing the fewest-and-longest lines, the axial map is broken at every intersection into segments — the street pieces between junctions. Connections between segments are weighted by turn angle divided by 90 degrees, so continuing straight costs 0, a right-angle turn costs 1, and a U-turn costs 2. Shortest paths minimise this angular cost, effectively finding the least-turning routes through the city. This single change:
   • Removes subjectivity — the segment map is determined by the geometry of intersections, not a practitioner's judgement,
   • Captures the cognitive reality that people prefer straight routes and penalise sharp turns,
   • Is resolution-independent — adding intermediate shape points along a straight segment does not change the angular cost,
   • Subsumes axial analysis: if every turn costs 1 (regardless of angle), the result is the axial topology; if costs are proportional to turn angle, the result is the more nuanced angular model.
3. Normalised measures — NACH and NAIN (Hillier, Yang & Turner, 2012). The raw measures from segment angular analysis — integration (inverse mean depth) and choice (angular betweenness) — are inherently size-dependent. A larger network has more segments, longer paths, and therefore systematically higher choice counts and systematically lower integration values, even if the structural pattern is identical. NACH and NAIN normalise away size by dividing choice and integration respectively by terms derived from the total depth. The constants (exponent 1.2 for NAIN, +1/+3 shift for NACH, +2/+2 for NAIN denominator) were calibrated by Hillier, Yang & Turner (2012) to maximise the correlation with observed pedestrian and vehicular movement rates across 50 cities worldwide. This made NACH and NAIN the first space-syntax measures that could be compared numerically across cities of different sizes — a landmark for quantitative urban morphology.

Key assumptions

• Angular-cost minimisation. The model assumes that route choice is governed by the minimisation of turn-angle cost, not by metric distance, travel time, or number of junctions. Empirical studies consistently find that angular choice correlates with vehicular and pedestrian flows at $r \approx 0.6$–$0.8$, outperforming metric betweenness by 10–20 percentage points. The cognitive basis is that people perceive straight routes as shorter and prefer to minimise the number of direction changes — even when this produces a slightly longer metric path.
• Segment dual graph. The analysis operates on the segment graph, not the primal junction graph. Each street segment between junctions is a node in the dual graph; adjacency is defined by sharing an endpoint. This means the output fields are per segment (line attributes), not per junction (point attributes). Segment-level output is generally more useful than node-level output for planning, because streets (not junctions) are the units of zoning, design, and investment.
• Edge effect. Segments near the edge of the study area have artificially low NACH and NAIN values because the radius "sees" fewer segments beyond the boundary than it would if the network extended further. This is the universal space-syntax edge effect and is not corrected by the tool. The standard mitigation is to include a buffer of at least one radius of extra network around the actual study area — i.e. analyse the city plus a 2 km ring, then clip the result to the city boundary for interpretation. The edge effect is most severe at the global radius ("n") and diminishes at smaller radii.
• Undirected traversal. The segment graph is undirected — turn costs are symmetric (turning left costs the same as turning right at the same angle). For one-way street systems, this means NACH may overestimate through-movement on segments that are one-way in the opposite direction. Filtering by one-way attributes in post-processing is possible but not automated.
• No land-use weighting. The analysis is purely configurational — it measures the potential for movement generated by the grid geometry alone, not the actual movement generated by land uses (a shopping centre on a configurational backwater will still attract people). For combined configurational + attractor-weighted analysis, overlay NACH/NAIN with land-use data and destination counts from the Walkability Audit or Access Score tools.

When to use vs. when NOT to use

Use Space Syntax when: you need the definitive configurational diagnosis of a street network — the structural complement to land-use, density, and demographic analyses; when comparing alternative masterplan layouts (run twice, difference the NACH/NAIN fields); when identifying the foreground movement grid (top 10–20% NACH) and the background residential fabric; when the question is about the spatial logic of the city — why does this street attract pedestrians while its parallel twin two blocks away does not.

Do NOT use when: (a) you need only metric (distance) measures of centrality — use Network Centrality; (b) the street network lacks a prepared topology — segments that cross without a shared node produce a disconnected segment graph, and the output will be nonsensical; always run Prepare Network first; (c) the study area is very small (under 100 segments) — edge effects dominate at this scale, and the NACH/NAIN normalisation was calibrated on city-scale networks of thousands of segments; (d) you are working entirely within a superblock or gated community where movement is constrained by gates and access controls that the configurational model cannot account for.

Mathematical Formulation

Segment dual graph. Given $n$ street segments with coordinates, the segment graph is built by the engine (engine/graphs.py). Two segments $(u, v)$ are adjacent if they share an endpoint. The angular cost of turning from segment $u$ to segment $v$ is:

where $\theta_{uv} \in [0^\circ, 180^\circ]$ is the deflection angle between the last direction vector of $u$ and the first direction vector of $v$ (taking the smaller angle, since the graph is undirected). Internal polyline curvature within each segment is also accumulated — the angular cost along a segment equals the sum of turn angles between its consecutive sub-segments divided by 90°.

Angular shortest paths. For each source segment $s$, a modified Dijkstra algorithm computes the minimum angular-cost path to every other segment $t$ within metric radius $r$ (if specified). The result is the angular distance matrix $d_{ang}(s, t)$.

Angular total depth (TD) and node count (NC):

Angular mean depth (MD):

Angular choice (CH) — raw betweenness:

where $\sigma_{uv}^{ang}$ is the number of least-angular-cost paths between $u$ and $v$, and $\sigma_{uv}^{ang}(s)$ counts those passing through $s$. Since the graph is undirected, each unordered pair $(u,v)$ is counted twice; the engine divides by 2 to obtain pair-based choice.

NAIN — Normalised Angular INtegration (to-movement potential):

The constants +2 in numerator and denominator prevent division by zero for isolated segments. The exponent 1.2 was calibrated by Hillier, Yang & Turner (2012) to maximise correlation with observed movement rates across 50 cities. High NAIN = easy to arrive at — the segment is a destination magnet.

NACH — Normalised Angular CHoice (through-movement potential):

The constants +1 and +3 keep the ratio real and finite (choice can be zero; total depth is at least 1). High NACH = heavily used as a through route — the segment is in the foreground movement grid.

Both NACH and NAIN are dimensionless and approximately invariant to system size — a segment in a small town and a segment in a metropolis with the same configurational role will have similar NACH/NAIN values.

Input Data Requirements

Parameters

Output Description

Per radius (suffix is the radius label, e.g. _800, _n):

Symbolic Representation

NACH and NAIN are the two primary map products.

• NACH map: Graduated renderer, sequential multi-hue (Viridis or Plasma), quantile classification with 7–10 classes. The top 10–20% of values (the foreground) should be visually dominant — thicken these lines to 0.6–0.8 mm; background lines at 0.2 mm. The quantile classification is critical because NACH is still somewhat right-skewed; natural breaks will lump most segments into the bottom class.
• NAIN map: Same approach, but use a warm sequential ramp (OrRd or YlOrRd) — integration reads as "heat" (activity concentration). The top 10% are the city's cores; expect them to align with historic centres and high streets.
• Joint NACH+NAIN interpretation map: Bivariate colour scheme — or, more practically, two side-by-side map panels with synchronised extents. QGIS map themes make this straightforward.
• Legend format: Two decimal places (e.g. "0.95 – 1.12"). Do not include unit symbols — NACH and NAIN are dimensionless.
• Scale dependency: Show the full network at city scale; at neighbourhood scale (1:5,000–1:10,000), filter to the top 50% of NACH to declutter.

Interpretation Guide

The dual reading: NACH × NAIN

The real power of space syntax lies in reading NACH and NAIN together on the same segment. The cross-classification yields four urban typologies:

Multi-radius reading

Run at least three radii (e.g. 400, 1200, n) and compare the same segment across radii:

• Strong at all radii = a resilient main street — the urban spine. Rare and valuable.
• Strong only at small radius (400–800) = a neighbourhood centre — locally important but not part of the city-scale structure.
• Strong only at large radius (n) = a car-oriented arterial — functions as a regional connector but has no local centre quality.
• Weak at all radii = isolated fabric — potentially an enclave. Check whether this is deliberate (gated community) or problematic (neglected social housing estate).

Masterplan evaluation

Run Space Syntax twice — once on the existing network, once on the proposed masterplan network — and compute the difference in NACH and NAIN per segment (or per spatial unit). Segments whose NAIN rises significantly are winners — the masterplan connects them. Segments whose NAIN drops are losers — the masterplan severs or bypasses them. A quarter whose NAIN stays low at every radius in the proposed network will persist as an enclave regardless of land-use mix or density — the spatial configuration itself prevents integration.

Benchmarks from the 50-city study

Hillier, Yang & Turner (2012) established these approximate ranges from their analysis of 50 urban systems worldwide:

Your city's values will differ — these are comparative benchmarks, not normative targets. An organic medieval centre and a planned modernist grid can both be excellent places to live despite very different scores.

Academic References

Hillier, B. & Hanson, J. (1984). The Social Logic of Space. Cambridge University Press. DOI: 10.1017/CBO9780511597237

Hillier, B., Penn, A., Hanson, J., Grajewski, T., & Xu, J. (1993). "Natural Movement: Or, Configuration and Attraction in Urban Pedestrian Movement." Environment and Planning B: Planning and Design, 20(1), 29–66. DOI: 10.1068/b200029

Turner, A. (2001). "Angular Analysis." In: Peponis, J., Wineman, J. & Bafna, S. (eds.), Proceedings of the 3rd International Space Syntax Symposium, Atlanta, GA, pp. 30.1–30.11. conference proceedings] Available at: UCL Discovery

Hillier, B. & Iida, S. (2005). "Network and Psychological Effects in Urban Movement." In: Cohn, A.G. & Mark, D.M. (eds.), Spatial Information Theory (COSIT 2005), LNCS 3693, pp. 475–490. Springer. DOI: 10.1007/11556114_30

Crucitti, P., Latora, V. & Porta, S. (2006). "Centrality Measures in Spatial Networks of Urban Streets." Physical Review E, 73, 036125. DOI: 10.1103/PhysRevE.73.036125

Porta, S., Crucitti, P. & Latora, V. (2006). "The Network Analysis of Urban Streets: A Dual Approach." Physica A, 369(2), 853–866. DOI: 10.1016/j.physa.2005.12.063

Hillier, B., Yang, T., & Turner, A. (2012). "Normalising Least Angle Choice in Depthmap — and How It Opens Up New Perspectives on the Global and Local Analysis of City Space." Journal of Space Syntax, 3(2), 155–193. journal does not assign DOIs] Available at: UCL Discovery

OD Cost Matrix

Processing ID: planx:odmatrix

Overview

Computes the full origin–destination cost matrix over the street network using the embedded Dijkstra engine — no external routing plugin or server. For every origin–destination pair, it reports the shortest-path network cost, the straight-line (Euclidean) distance, and the detour ratio (network ÷ Euclidean). Optional desire lines render the matrix as straight-line glyphs styled by cost or detour.

This is the foundational input for gravity models, accessibility studies, facility siting, and any analysis that needs to know "how far is A from B on the real network."

Theoretical Background

Academic lineage

The OD cost matrix is the most basic product of a transportation network model: it answers the question "how far apart are these places?" for every pair of interest. The concept originates in traffic analysis zone (TAZ) planning, formalised during the post-war boom in urban transportation modelling. The landmark Chicago Area Transportation Study (CATS, 1955–1962) established the four-step travel-demand model (trip generation, distribution, modal split, assignment) that remains the framework for metropolitan transport planning worldwide. The OD cost matrix feeds the distribution step — trip distribution models (gravity, intervening opportunities, and later entropy-maximising and logit-based formulations) all require a cost or impedance matrix as their primary input (Ortuzar & Willumsen, 2011). Wilson's (1967) entropy-maximising derivation of the doubly-constrained gravity model was a theoretical breakthrough, showing that the gravity model is the most probable trip distribution consistent with known constraints — not merely an analogy to Newtonian physics.

In GIS, the OD cost matrix was for many years computed by external routing engines (ESRI Network Analyst, pgRouting, Google Distance Matrix API). PlanX brings this capability inside QGIS using the same Dijkstra engine that powers all other network tools. The many-to-many shortest-path computation runs one Dijkstra tree per origin, reusing the tree to reach all destinations simultaneously — far more efficient than running Dijkstra once per OD pair. This exact approach is implemented in the engine's many_to_many kernel (see engine/paths.py), which passes the CSR adjacency directly to SciPy's csgraph.dijkstra when available and falls back to a pure-Python heapq implementation otherwise, with identical results verified by unit tests.

Key assumptions

• Shortest-path behaviour. The OD matrix assumes travellers always choose the shortest-path (least-cost) route. This is a reasonable approximation for walking and cycling where distance minimisation dominates, but it systematically underestimates the diversity of vehicular routes — drivers trade off distance against congestion, signal count, and road class. For multi-criteria routing, the OD Routes tool with reconstructed geometry allows post-hoc inspection of which paths Dijkstra actually chose.
• Snapping fidelity. Each origin and destination snaps to its nearest network node. For a point 50 m inside a park, the nearest node may be 50 m away on a perimeter road — the route cost includes that 50 m snap distance. If the snap point lies on a different street than the one you intended (e.g. a building centroid snaps to a rear alley instead of the front street), the OD row will be misleadingly long. Always inspect a few snap points visually before trusting the matrix.
• Additive costs. The cost field must be additive per segment — a sum, not an average or a rate. Speed (km/h) must be pre-converted to travel time = length / speed. NULL costs are treated as zero (free segment), which can produce unrealistically short routes if cost data is incomplete.
• Unreachable pairs. Pairs where the destination is disconnected from the origin (no path in the graph, or the shortest path exceeds the cutoff) are absent from the output, not reported with a sentinel value. This is deliberate: counting absent rows per origin is the quickest way to identify disconnected pockets in the network.

When to use vs. when NOT to use

Use OD Cost Matrix when: you need a complete pairwise impedance matrix for gravity models, accessibility indices, facility location optimisation, or statistical analysis of travel costs. The detour ratio makes it a powerful barrier-effect screening tool — the OD pair with the highest detour ratio often pinpoints the single best location for a new bridge or street link.

Do NOT use when: (a) you need actual route geometries — use OD Routes instead; (b) you are computing a single origin's catchment — use Service Areas which provides partial-edge trimming and pedshed ratios; (c) you need assignment-aware routing (each traveller affects congestion) — this requires an iterative traffic-assignment model, which PlanX does not provide; (d) the OD set is very large (thousands of origins x thousands of destinations) with no cutoff — the output table grows as $O(m \cdot n)$ and will overwhelm QGIS. Always set a CUTOFF for large OD sets, or aggregate origins and destinations to zone centroids first.

Mathematical Formulation

Network cost. For each origin $i$ and destination $j$, the engine computes the shortest-path distance $d_{net}(i,j)$ by Dijkstra's algorithm on the primal graph $G = (V, E)$ with edge weights $w(e)$ (geometric length or a user-specified additive cost field). Each origin snap point is mapped to its nearest network node $n_i^O$; similarly each destination snap point maps to $n_j^D$. The many-to-many kernel then runs Dijkstra from each unique origin node, producing a full shortest-path tree per origin:

The engine adds the straight-line snap distance $d_{snap}$ from the original point coordinates to the network node, so the total cost from origin geometry to destination geometry is:

Euclidean distance (as the crow flies) between the original point coordinates:

Detour ratio: the dimensionless measure of how much farther the network forces travel compared to the straight line:

Many-to-many computational kernel. The engine function paths.many_to_many(indptr, adj, weights, n, sources, cutoff) implements the computation. For each source node $s$, it runs a single Dijkstra pass that computes distances to all $n$ nodes. For $m$ unique origin nodes, the cost is $O(m \cdot (n \log n + e))$ in the SciPy fast path and $O(m \cdot (n \log n + e))$ in the heapq fallback — the difference is a constant factor (~5-10x), not the asymptotic complexity. The cutoff parameter prunes the search: expansion stops when the cumulative cost exceeds the cutoff, which both accelerates the computation and limits memory use for large networks.

All-pairs special case. When no separate destination layer is provided, the origins also serve as destinations. Self-pairs $(i, i)$ are automatically excluded (a point's distance to itself is not meaningful for gravity models and would introduce a zero diagonal that biases calibration).

Unreachable handling. A destination $j$ is unreachable from origin $i$ if: (a) the source and destination nodes belong to different connected components of the graph, or (b) the shortest path exceeds the cutoff and expansion was pruned. In either case, the pair is not included in the output — the matrix is sparse by design, containing only reachable pairs within the cutoff. The count of missing pairs per origin is a direct measure of network fragmentation.

Input Data Requirements

Parameters

Output Description

Symbolic Representation

Desire lines styled by detour ratio with a diverging colour ramp (RdYlGn, reversed: green = direct, red = circuitous) and natural-breaks classification (5 classes) produce the most immediately informative map. Style by net_cost with a sequential ramp (Viridis) for a raw-distance view. Line width proportional to the inverse of detour (thick = efficient connections). At city scale, set line opacity to 20–30% to prevent overplotting.

Interpretation Guide

Numerical benchmarks

• detour < 1.15: the network is highly efficient for this pair — the route is nearly as direct as the crow flies. Typical of orthogonal grid streets within the same neighbourhood.
• detour 1.15–1.35: normal urban fabric — the route takes a few turns but no major detour. This is the expected range for most intra-city pairs in well-connected grids.
• detour 1.35–1.60: moderate barrier effect — a river bend, a railway line, a superblock perimeter, or a missing street link forces a noticeable detour. Target these pairs for connectivity interventions.
• detour > 1.60: severe barrier — the network forces a route more than 60% longer than the crow flies. This almost always indicates a physical barrier (river with few crossings, motorway with no pedestrian underpass) or a topological dead-end (cul-de-sac subdivision where the only exit is far from the destination). The single pair with the highest detour in a study area typically pinpoints the most cost-effective new link.
• Missing pairs per origin: 0 = fully connected within cutoff; 1–5 = minor gaps (isolated cul-de-sacs, edge effects); >10 = significant disconnection — check whether this origin is physically separated (island, gated community, or disconnected component in the graph).

Spatial pattern reading

Visualise the matrix as a desire-line map: each OD pair is a straight line coloured by detour ratio. The spatial pattern reveals:

• Radial convergence: many lines radiating from outlying origins toward a central destination cluster — classic monocentric city pattern. The detour on radial lines is typically low (grids are efficient at radiating); the detour on orbital lines (origin-to-origin) is typically higher, revealing the missing orbital connectivity that a circumferential transit line would serve.
• Barrier shadows: a band of high-detour lines all crossing the same geographic corridor — this is the shadow cast by a linear barrier (river, motorway, railway). Count the number of crossing points in that corridor — if there is only one bridge every 800 m, each additional bridge reduces the detour bill for thousands of OD pairs.
• Isolated clusters: a group of origins whose lines to destinations are all absent or all high-detour — these origins belong to a disconnected or poorly connected component. Check whether a single missing link (one street segment) would connect the cluster to the main graph.

Cross-references

The OD cost matrix is the primary impedance input for the Gravity Distribution model (the $c_{ij}$ term in the gravity formula), for the Mode Split tool's distance decay functions, and for any Location-Allocation analysis where a precomputed cost matrix avoids repeated routing. The net_cost values can also be used as a standalone accessibility indicator: the mean net_cost to a category of destinations (e.g. all hospitals) is a simpler but coarser alternative to the Multi-Amenity Access Score for single-category access studies.

Common misinterpretations

• "A detour ratio below 1.0 is impossible." True — but floating-point noise can produce ratios of 0.999... for very short segments where the snap distance adds to the Euclidean too. These are not bugs.
• "The detour ratio is comparable across different cost types." The detour ratio is only geometrically meaningful when cost = length (metres). When cost = time, the denominator is still in metres but the numerator is in minutes, making the ratio dimensionally inconsistent. For time-based matrices, use net_cost directly and compare to a time threshold, not a detour ratio.
• "All pairs matter equally." The OD matrix gives each pair equal weight, but in planning some pairs matter vastly more than others. Weight pairs by population at origin x employment at destination, or filter to the pairs relevant to your policy question (e.g. children to schools, elderly to clinics), before ranking detour ratios.

Academic References

Ortuzar, J. de D. & Willumsen, L.G. (2011). Modelling Transport. 4th ed., Wiley. DOI: 10.1002/9781119993308

Dijkstra, E.W. (1959). "A Note on Two Problems in Connexion with Graphs." Numerische Mathematik, 1(1), 269–271. DOI: 10.1007/BF01386390

Wilson, A.G. (1967). "A Statistical Theory of Spatial Distribution Models." Transportation Research, 1(3), 253–269. DOI: 10.1016/0041-1647(67)90035-4

Rodrigue, J.-P., Comtois, C. & Slack, B. (2017). The Geography of Transport Systems. 4th ed., Routledge. textbook, no DOI assigned] Available at: transportgeography.org

OD Routes (Shortest Paths)

Processing ID: planx:odroutes

Overview

Computes actual shortest-path route geometries over the street network from origins to destinations. Unlike the OD Cost Matrix (which returns only costs), this tool reconstructs the precise sequence of street segments traversed — turn by turn — for every origin–destination pair. Each route includes the network cost, Euclidean distance, detour ratio, and the number of edges traversed. Optional straight desire lines complement the route geometries.

The tool supports k-nearest destination filtering and a cost cutoff to keep output manageable for large OD sets.

Theoretical Background

Academic lineage

Route reconstruction from a shortest-path tree is the standard predecessor-tracking technique — a natural extension of Dijkstra's algorithm (1959) and an integral part of every routing engine since the first in-vehicle navigation systems of the 1980s. During Dijkstra's algorithm, each node records which predecessor node and which edge were used to reach it with the minimum cost. After the tree is built, a path from source $s$ to target $t$ is reconstructed by walking backwards from $t$ through the predecessor chain to $s$, collecting the edge IDs along the way. The PlanX implementation uses the shortest_path_tree kernel in engine/paths.py, which is deliberately a pure-Python heapq implementation — the SciPy accelerated kernel cannot track which specific parallel edge was taken, so predecessor tracking uses the guarantee of identical distances but with full edge-identity preservation.

The route-reconstruction problem gains practical significance at urban scale because of parallel edges — dual carriageways, service roads, and slip lanes that share the same endpoint pair $(u, v)$ but have different geometry, different names, and different attributes. A Dijkstra implementation that only records predecessor nodes cannot distinguish which parallel edge was traversed; one that records predecessor edges can. The PlanX engine records both, ensuring that every reconstructed route follows the exact geometry of the streets it traverses.

Key assumptions

• Unique shortest-path resolution. When multiple paths have identical cost (a tie), Dijkstra's relaxation rule resolves deterministically: a strictly lower cost replaces the predecessor; an equal cost does not. This means the first-discovered path of minimum cost wins. The choice is deterministic but not necessarily the path a person would choose — between two equal-cost routes, a person might prefer the one with fewer turns, better scenery, or less traffic, none of which the cost field captures.
• Edge geometry orientation. Edges in the graph have no inherent direction — they are undirected. During route assembly, the polyline of each edge is oriented so its first coordinate is closest to the previous edge's last coordinate, producing a contiguous linestring. If the edge's native coordinate order opposes the travel direction, the full polyline is reversed. This orientation logic is geometric (based on endpoint proximity), not topological (based on the graph edge direction).
• k-nearest stability. The k-nearest filter sorts destinations by net_cost and keeps the $k$ smallest. Ties (equal cost) are broken by the destination's row index in the input layer — not by any spatial or attribute criterion. This is deterministic but may produce counter-intuitive results when two destinations are equidistant: the one listed first in the attribute table always wins. For human-interpretable results, ensure that destination IDs are ordered meaningfully (e.g. facility priority order) before analysis.

When to use vs. when NOT to use

Use OD Routes when: you need the actual street-level itinerary, not just the cost; when visualising movement corridors through route bundling; when k=1 routing to the nearest facility with full path geometry (functionally equivalent to Nearest Facility with routes enabled); when the analysis requires turn-by-turn inspection of which specific streets a trip uses.

Do NOT use when: (a) you need only the cost matrix without geometry — use OD Cost Matrix which is faster and produces a smaller output; (b) the OD set is very large (thousands of pairs) without a cutoff — each route is a multi-segment linestring that bloats the output; (c) k-nearest is set to a large value — for k >= 10, the route count per origin explodes and the map becomes unreadable.

Mathematical Formulation

Shortest-path tree. For each origin $s$, Dijkstra's algorithm computes:

• $dist[t]$ — minimum cost from $s$ to every node $t$
• $pred\_node[t]$ — the predecessor node on the shortest path to $t$
• $pred\_edge[t]$ — the edge ID connecting $pred\_node[t]$ to $t$

Path reconstruction. Starting from target node $t$:

1. Push edge $pred\_edge[t]$ onto the edge list
2. Set $t \leftarrow pred\_node[t]$
3. Repeat until $t = s$ (source reached) or predecessor is invalid
4. Reverse the edge list to obtain travel order from origin to destination

Route geometry assembly. For each edge in the ordered list, the polyline coordinates are oriented so the first vertex is closest to the current position. Consecutive edges share the junction node, producing a contiguous linestring.

Input Data Requirements

Parameters

Output Description

Symbolic Representation

Route geometries styled by flow bundling (overlaying many routes at low opacity, 15–30%) reveal the de-facto movement corridors — the demand-side complement to betweenness centrality. Use a sequential ramp (Viridis) on net_cost for a time/distance view. For k=1 output, style by dest_id as a categorical renderer to see de-facto catchment boundaries (the nearest-destination Voronoi equivalent on the network). Route line width 0.3–0.5 mm with 20% opacity works well for bundling.

Interpretation Guide

• Route bundles that converge on a narrow set of streets reveal the corridors where most trips concentrate — these are your priority sidewalk, cycle, and transit corridors.
• Overlay route flows with Cycling Stress or Walkability Audit scores to target safety improvements on the streets that people actually use.
• Setting k=1 yields assignment-like nearest-service routes, functionally equivalent to Nearest Facility but with full path geometry.
• Long detour routes (detour ≥ 1.5) visualise the barrier effect — the actual path people are forced to take around a river, rail line, or superblock.
• Feed net_cost into Gravity Model or Mode Split as the impedance matrix.

Academic References

Dijkstra, E.W. (1959). "A Note on Two Problems in Connexion with Graphs." Numerische Mathematik, 1(1), 269–271. DOI: 10.1007/BF01386390

Bast, H., Delling, D., Goldberg, A., Muller-Hannemann, M., Pajor, T., Sanders, P., Wagner, D. & Werneck, R.F. (2016). "Route Planning in Transportation Networks." In: Kliemann, L. & Sanders, P. (eds.), Algorithm Engineering, LNCS 9220, pp. 19–80. Springer. DOI: 10.1007/978-3-319-49487-6_2

Service Areas (Isochrones)

Processing ID: planx:serviceareas

Overview

Computes true network catchments around facilities with exact partial-edge reach: walking budgets end mid-street, so streets are trimmed at the precise point where the cost budget runs out. For each break distance, the tool produces trimmed street pieces (coloured by cost band), service area polygons (buffer, concave hull, or convex hull), and straight-line circles for comparison. The pedshed ratio (network catchment area ÷ circle area) is the classic measure of how much the street layout shrinks the reach promised by a given radius.

Theoretical Background

Academic lineage

Service area (isochrone) analysis is the spatial implementation of catchment-based planning standards: a regulation states that every residence must be within 500 m of a park, 800 m of a primary school, or 400 m of a bus stop. The straight-line (crow-flies) buffer that most GIS users draw to check compliance is systematically optimistic — it ignores the street network entirely. The systematic error was first quantified by Porta & Renne (2005), who introduced the pedshed ratio (catchment area divided by circle area) as a network-efficiency metric for walkability assessment. The concept was further formalised by Curtin (2007), who demonstrated that the network buffer — trimming streets at the exact budget point rather than at the nearest junction — is not a cosmetic refinement but a quantitative necessity at walking-scale budgets (below approximately 1,500 m).

The computational approach — multi-source Dijkstra — builds on the observation that labelling every reachable point with its nearest facility is mathematically equivalent to inserting a virtual super-source node connected to all facility entry points with zero-cost edges. This was first described for GIS by Dreyfus (1969) as an extension of Dijkstra's algorithm and became the standard approach with the rise of desktop GIS in the 1990s. PlanX's implementation extends this with partial-edge trimming: after the per-node costs are known, each edge is tested for partial reachability between its endpoints. For an edge $(u, v)$ where $d_u \leq B < d_v$, the reachable portion is the fraction $(B - d_u) / (d_v - d_u)$ of the edge length from $u$. This eliminates the block-length quantisation error that node-only isochrones suffer from.

Key assumptions

• Nearest-facility wins. In merged mode, each point on the network is assigned to the facility with the lowest cost. In per-facility mode, each facility's catchment is computed independently and may overlap. A point at equal cost from two facilities is assigned to the first one in the input order — this is deterministic but may split a street arbitrarily if two facilities are equidistant.
• Cost fidelity at small budgets. For budgets below 200 m, the snap distance from the facility point to the nearest point on the network may be a significant fraction of the total budget — a facility 30 m from the road in a 200 m catchment spends 15% of its budget just reaching the road. The tool includes the snap distance in the cost, so this is correctly accounted for, but the morphology of the catchment may be dominated by the snap geometry. For small-budget analysis, digitise facility points precisely on the network.
• Polygon method trade-off. The three polygon methods (Street Buffer, Concave Hull, Convex Hull) represent a trade-off between cartographic precision and interpretability. Street Buffer produces the most accurate representation (the envelope of trimmed street pieces) but yields complex, irregular polygons that look unfamiliar. Concave Hull produces the familiar "isochrone blob" aesthetic but may fill large areas that are genuinely unreachable (e.g. a park with no paths). Convex Hull is the fastest and most generous — it always overestimates, but provides a conservative upper bound for compliance checking ("if the convex hull misses it, the network certainly does").

When to use vs. when NOT to use

Use Service Areas when: auditing compliance with distance-based planning standards; visualising the reach of a proposed facility site; computing the pedshed ratio as a network-efficiency indicator; producing masterplan exhibits with clear "served" vs. "unserved" delineation.

Do NOT use when: (a) you need demand-weighted allocation counts — use Nearest Facility instead; (b) the question is about the fastest (time-based) route rather than the shortest distance — use a time cost field from Walking Slope Comfort; (c) the radius is very large (over 5000 m) — the polygon may cover most of the study area and the pedshed ratio approaches 1.0 regardless of network quality, making it non-diagnostic; (d) you need individual routes for every origin-destination pair — use OD Routes.

Mathematical Formulation

Multi-source Dijkstra with entry costs. Each facility $f$ enters the network at its nearest point on the nearest edge $(e_f, t_f)$ where $t_f \in [0,1]$ is the position along the edge. Two node-offset entries are created for the edge's endpoints with the approach cost added:

where $d_{snap}$ is the straight-line snap distance (added to the budget when cost is length). Dijkstra runs once from all facility entries simultaneously, producing per-node costs and winning-facility labels.

Partial-edge reach intervals. For an edge $(u, v)$ with cost $\ell$ and node costs $d_u, d_v$, the reachable portion within budget $B$ is the interval $[t_{min}, t_{max}]$ where the interpolated cost at position $t$ is ≤ $B$:

Pedshed ratio:

Pedshed ≥ 0.6 = well-connected grid; 0.4–0.6 = average; < 0.4 = poor — the network delivers less than half the promised radius.

Input Data Requirements

Parameters

Output Description

Symbolic Representation

Overlay Circles (hollow, dashed outline, 0.5 mm stroke) on top of Areas (solid fill, 30–40% opacity, sequential colour by break). The gaps between circle and area are the visual story — they show exactly where the paper radius fails on the ground. This is the single strongest exhibit for a standards review. Use blue for circles and warm colours (OrRd) for catchments to emphasise the deficit. For the edges output, colour by band with a sequential ramp for a served-street map. The summary table's pedshed column ranks facilities by catchment efficiency — style as a bar chart in the QGIS layout.

Interpretation Guide

• Pedshed ≥ 0.6: well-connected, walkable grid — the network delivers most of the promised reach.
• Pedshed 0.4–0.6: average urban fabric — some severance. Target the gaps for new street connections.
• Pedshed < 0.4: poor — the network delivers less than half the radius. The gaps between circle and catchment are streets that look close but are unreachable. These gaps pinpoint where pedestrian bridges, underpasses, or street links are most needed.
• Per-facility comparison: facilities with the lowest pedshed ratios at the same break are the best candidates for access-improvement interventions. Rerun with a proposed link added and compare pedshed gains to build the business case.
• Use Rings mode for clean band cartography in master-plan exhibits — each band is a distinct colour with no overlap.

Academic References

Curtin, K.M. (2007). "Network Analysis in Geographic Information Science: Review, Assessment, and Projections." Cartography and Geographic Information Science, 34(2), 103–111. DOI: 10.1559/152304007781002163

Porta, S. & Renne, J.L. (2005). "Linking Urban Design to Sustainability: Formal Indicators of Social Urban Sustainability Field Research in Perth, Western Australia." Urban Design International, 10, 51–64. DOI: 10.1057/palgrave.udi.9000136

Handy, S.L. & Niemeier, D.A. (1997). "Measuring Accessibility: An Exploration of Issues and Alternatives." Environment and Planning A, 29(7), 1175–1194. DOI: 10.1068/a291175

Nearest Facility Allocation

Processing ID: planx:nearestfacility

Overview

Assigns every demand point (building, household, parcel centroid) to its nearest facility over the street network and reports each facility's total load. A single multi-source Dijkstra run resolves all assignments at once — every demand point is simultaneously claimed by its closest facility. Outputs include the allocated demand layer (with assigned facility label and network cost), optional spider/allocation lines, reconstructed network-path routes, and a per-facility load summary with demand count, mean cost, and maximum cost.

Theoretical Background

Academic lineage

Nearest-facility allocation solves the Voronoi problem on a network: instead of partitioning space into Euclidean regions (as a standard Thiessen/Voronoi diagram would), it partitions it by shortest-path distance. The concept extends the classical planar Voronoi diagram (Dirichlet, 1850; Voronoi, 1908) to graphs, where the "distance" is the shortest-path cost on the network rather than the Euclidean norm. The de-facto catchment boundaries — the lines where the nearest facility changes — rarely align with administrative boundaries, census tracts, or straight-line catchment circles. This is the fundamental insight of network-based accessibility planning: the street network, not the radius, determines who goes where (Talen & Anselin, 1998).

The computational technique — multi-source Dijkstra — was first described by Dreyfus (1969) as an extension of Dijkstra's algorithm: insert a virtual super-source node connected to all facility nodes with zero-cost edges, then run a single Dijkstra pass. All reachable nodes are labelled with the facility that first reached them (the one with the minimum cost). The implementation in engine/paths.py as multi_source uses a priority-queue initialised with all facility nodes at cost zero, each carrying its facility label. The relaxation rule is strict improvement only: if two facilities reach a node at exactly equal cost, the one already settled keeps it — the assignment is deterministic but the first-settled bias favours facilities appearing earlier in the input order.

The approach is $O((n + f) \log n + e)$ where $f$ is the number of facilities — a single Dijkstra pass replaces $f$ independent single-source passes. This makes nearest-facility allocation dramatically cheaper than OD routing: assigning 5,000 demand points to 50 facilities requires one Dijkstra pass, not 5,000.

Key assumptions

• Nearest = most preferred. The model assumes that every demand point uses the facility with the lowest network cost. In reality, people may choose a farther facility because of quality, waiting time, familiarity, or insurance coverage. The allocation is a supply-side model of what is possible, not a demand-side model of what people actually do.
• No capacity constraints. Facilities have unlimited capacity — assigning 500 demand points to one facility and 5 to another produces a valid result. For capacity-constrained assignment, use Capacitated Allocation which iteratively reassigns demand when a facility reaches its limit, using a penalty-based reallocation algorithm.
• Deterministic tie-breaking. When two facilities are at identical cost from a demand point, the one appearing first in the input feature order wins. This can produce counter-intuitive results along a symmetry axis (e.g. the exact midpoint between two identical facilities on a straight road). The strip of ambiguity is at most one grid cell wide, but for publication-grade maps at large scale, manually inspect the assignment along equidistance boundaries.
• Snap truncation. Demand points farther from the network than the cutoff distance are automatically unallocated — even if they are geographically close to a facility. A building 300 m inside a park with its centroid 300 m from the nearest road will be unallocated at a 500 m cutoff because the snap distance alone consumes 300 m. For building-level analysis, ensure demand points are on or very near the network.

When to use vs. when NOT to use

Use Nearest Facility when: auditing school catchment assignment, healthcare service area planning, emergency-service station coverage analysis, or any application where the question is "which facility serves this location?" and facilities do not have hard capacity limits. Combine with the SUMMARY output to identify overloaded facilities (demand_n far above the mean) and underserved service gaps (facility = "").

Do NOT use when: (a) facilities have strict capacity limits — use Capacitated Allocation; (b) you need only the cost to the nearest facility, not the allocation label — the Multi-Amenity Access Score is faster for per-category proximity without spatial assignment; (c) the question is about optimal facility locations, not the allocation from existing facilities — use the Facility Location Optimizer.

Mathematical Formulation

Given $n$ demand locations and $f$ facility locations, each snapped to network nodes, the algorithm computes:

where $d_{net}(k,d)$ is the shortest-path distance from facility $k$ to demand $d$ on the graph. If multiple facilities share a node, the first one in the input order wins — assignments are deterministic.

Facility load:

Input Data Requirements

Parameters

Output Description

Symbolic Representation

Colour demand points by facility with a categorical renderer (random colours or a predefined palette) to see de-facto catchment boundaries — these are the network Voronoi regions. Style unallocated points (cost = −1) as red X markers to highlight service gaps. Allocation lines coloured by facility, with 30–40% opacity, reveal the spatial extent of each catchment. For the summary table, a bar chart of demand_n by facility identifies overloaded facilities at a glance.

Interpretation Guide

• Unallocated demand (cost = −1) = the service gaps. Map these first — they are people with zero access within the cutoff.
• demand_n far above the average marks where the next facility would relieve the most load. Rerun with a candidate site added and compare max_cost and demand_n shifts.
• max_cost is the worst trip anyone must make — the number that planning standards (e.g. "no resident more than 800 m from a GP") care about.
• mean_cost compares overall convenience between facilities of the same type.
• Spider lines that cross multiple other catchments indicate a missing facility or a network barrier forcing demand past closer options.
• For capacity-constrained assignment (where facilities have limited capacity), use Capacitated Allocation instead.

Academic References

Talen, E. & Anselin, L. (1998). "Assessing Spatial Equity: An Evaluation of Measures of Accessibility to Public Playgrounds." Environment and Planning A, 30(4), 595–613. DOI: 10.1068/a300595

Dreyfus, S.E. (1969). "An Appraisal of Some Shortest-Path Algorithms." Operations Research, 17(3), 395–412. DOI: 10.1287/opre.17.3.395

Link Criticality (Network Robustness)

Processing ID: planx:linkcriticality

Overview

Ranks every street segment by how badly the network would suffer if that segment were lost — the road-network vulnerability view based on the Network Robustness Index (Scott et al., 2006; Jenelius et al., 2006). For a given origin–destination demand set, the tool first routes every pair on the intact network, then removes each segment in turn and re-routes, reporting the extra travel cost each removal forces plus any demand it cuts off entirely. Only segments that carry at least one shortest path are re-tested — the rest cannot change any route and score zero, which prunes the computation significantly.

Theoretical Background

Academic lineage

Network robustness analysis emerged from the intersection of transportation engineering and complex network theory in the early 2000s. The pivotal event was the 2001 Nisqually earthquake in Washington State, which damaged bridges and severed key road links, demonstrating that modern cities depend on a small number of critical links whose failure cascades far beyond the immediate damage zone. This spurred the first formal methodologies: the Network Robustness Index (NRI) by Scott, Novak, Aultman-Hall & Guo (2006), which introduced the concept of OD-weighted consequence measurement, and the importance/exposure framework of Jenelius, Petersen & Mattsson (2006), which separated link criticality into an importance component (how much travel uses the link) and an exposure component (how much travel is affected when it fails).

The field draws on two distinct intellectual traditions. The first is graph-theoretic vulnerability, rooted in the Erdős–Rényi and Barabási–Albert random-graph models: it asks which nodes or edges, when removed, maximally increase the average path length or fragment the network. The second is transport-system consequence analysis: it asks, for a given demand (the actual trips people make), which link failures impose the highest total detour cost. The two traditions sometimes conflict — a topologically central edge that carries few real trips ranks high by betweenness but low by NRI, and vice versa. The PlanX implementation follows the second tradition (consequence analysis) because planning decisions about bridge replacement and emergency routing should be driven by actual travel demand, not abstract topology.

Mattsson & Jenelius (2015) consolidated the field in their comprehensive review, distinguishing vulnerability (the susceptibility to disruption) from resilience (the ability to recover function after disruption). The NRI implemented in PlanX measures vulnerability; the n_disconnected field captures the most extreme form — total severance. These authors also highlighted that the most impactful single-step improvement to a vulnerability analysis is rarely a new algorithm but placing the OD demand on the trips that actually matter: emergency vehicle access routes, hazardous material corridors, and evacuation paths produce more actionable rankings than generic all-pairs matrices.

Key assumptions

• Single-link failure. The tool removes one edge at a time and measures its consequence. It does not test simultaneous multi-link failures (e.g. an earthquake damaging multiple bridges). For multi-link scenarios, run the single-link analysis and then test the top-N critical links in combination manually.
• Deterministic shortest-path routing. After link removal, travellers are assumed to re-route along the new shortest path. In reality, drivers may not know the new optimum immediately (information lag), may choose suboptimal alternatives (bounded rationality), or may abandon the trip entirely. The NRI is therefore a lower bound on the true disruption — real-world detour costs are typically higher.
• No capacity constraints. The surviving links are assumed to carry all re-routed traffic without congestion delay. In a real failure, re-routed traffic can saturate parallel links, slowing them and further increasing travel cost. PlanX does not model capacity; for congestion-aware analysis, an external traffic-assignment model is required.
• OD demand is fixed. The set of trips is invariant — people do not cancel trips, change destination, or switch mode because a link is gone. For evacuation or emergency scenarios where behaviour changes dramatically, the OD matrix should be re-specified (e.g. all trips to the nearest hospital or shelter) rather than reused from a commuter matrix.
• Candidate pruning. Only edges on at least one intact shortest path (used_by > 0) are removal-tested. In dense grids, the typical pruning rate is 60–90%, making the computation feasible for networks of up to ~20,000 segments. However, if the OD set is very small (e.g. 5 origins x 5 destinations = 25 pairs), most edges carry no shortest path and are pruned — the analysis then tells you about those trips' vulnerabilities, not the network's intrinsic redundancy.

When to use vs. when NOT to use

Use Link Criticality when: screening a road network for bridges, tunnels, and main arteries whose failure would impose the greatest detour cost; preparing a resilience investment priority list; identifying single points of failure (n_disconnected > 0) that warrant duplication or hardening; evaluating a proposed new link by comparing criticality scores before and after it is added — the links whose criticality drops most are those that the new link relieves.

Do NOT use when: (a) the analysis requires multi-link failure scenarios (earthquake damage to multiple bridges) — the tool tests one edge at a time; (b) you need a generic, demand-independent structural ranking of the network — use Network Centrality (betweenness) instead; (c) the network is very small (under 50 segments) and all-pairs routing is trivial — the tool's computational overhead is wasted; (d) you need real-time or near-real-time vulnerability assessment on a live traffic network — the exhaustive removal-test approach is designed for offline planning analysis, not operational use.

Mathematical Formulation

Baseline routing. For every OD pair $(o,d)$ in the demand set, compute $d_{net}(o,d)$ on the intact graph $G$. The base total is:

An edge $e$ is a candidate if it lies on at least one intact shortest path: $used\_by(e) = |\{(o,d) : e \in path(o,d)\}| > 0$.

Removal test. For each candidate edge $e$, route all OD pairs on $G \setminus \{e\}$:

Note: removal can only lengthen paths, so $extra\_cost(e) \geq 0$. If the removal severs an OD pair entirely, $d_{net}^{(e)}(o,d)$ is infinite and the pair contributes to $n\_disconnected(e)$.

Criticality (NRI):

Criticality is dimensionless, typically in $[0, 0.1]$ — losing a single segment rarely adds more than 10% to total travel, though extreme values occur for bridges and single-access connectors.

Input Data Requirements

Parameters

Output Description

Symbolic Representation

A graduated renderer on criticality with a sequential multi-hue ramp (Inferno or Plasma), natural-breaks classification (5–7 classes), and line width 0.3–0.8 mm scaled by criticality percentile. Edges with n_disconnected > 0 should use a distinct colour (red, 2 mm stroke) — these are the true single points of failure. The top 5% by criticality warrant labels with the edge ID. At city scale, filter to criticality ≥ 0.001 to declutter.

Interpretation Guide

• criticality is the headline: the fraction of total baseline travel cost added by losing this one segment. Sort descending to identify the network's structural vulnerabilities.
• n_disconnected > 0 flags a genuine cut-edge — a bridge, single tunnel, or lone connector whose loss isolates demand entirely. These are usually more urgent than any detour — duplicate, protect, or provide a bypass.
• used_by combined with criticality yields a four-way classification: high-use + high-criticality = bottleneck (add parallel capacity); high-use + low-criticality = well-served corridor (redundancy exists); low-use + high-criticality = vulnerable local link (sole access to a community); low-use + low-criticality = non-essential.
• Place your origins/destinations on the trips that matter — population to hospitals, emergency depots to demand zones — so the ranking reflects real exposure, not just geometry. A segment critical for emergency access may score zero if the OD set includes only commuters.

Academic References

Scott, D.M., Novak, D.C., Aultman-Hall, L., & Guo, F. (2006). "Network Robustness Index: A New Method for Identifying Critical Links and Evaluating the Performance of Transportation Networks." Journal of Transport Geography, 14(3), 215–227. DOI: 10.1016/j.jtrangeo.2005.10.003

Jenelius, E., Petersen, T. & Mattsson, L.-G. (2006). "Importance and Exposure in Road Network Vulnerability Analysis." Transportation Research Part A, 40(7), 537–560. DOI: 10.1016/j.tra.2005.11.003

Mattsson, L.-G. & Jenelius, E. (2015). "Vulnerability and Resilience of Transport Systems — A Discussion of Recent Research." Transportation Research Part A, 81, 16–34. DOI: 10.1016/j.tra.2015.06.002

10. Walkability

The Walkability group translates the walkable-city agenda into four interconnected GIS tools. Walkability Audit scores every street segment 0–100 using the classic Frank et al. (2010) ingredients: intersection density, land-use mix, destinations, block length, and slope — each normalised with documented breakpoints and combined with editable weights. Walking Slope Comfort samples a DEM along each street and computes Tobler's-hiking-function travel times. Street Environment Comfort scores streets by the assets (trees, benches, lighting) and barriers (blank walls, vacant lots) around them using kernel-density estimates. Pedestrian Route Quality re-routes over the comfort-weighted network, reporting the detour, the length-weighted quality score, and the low-score share — the difference between the shortest path and the pleasantest one.

Walkability Audit

Processing ID: planx:walkability

Overview

Scores every street segment 0–100 for walkability using five classic ingredients from the walkability-index literature: intersection density (connectivity), land-use mix (normalised Shannon entropy of buffer areas), destination counts (POIs within radius), block length (mean street-segment length as a block-size proxy), and slope (segment gradient from an optional DEM). Each ingredient is normalised 0–100 with documented breakpoints; missing inputs are renormalised away so the tool degrades gracefully with partial data. The output is the definitive "existing conditions" exhibit for a pedestrian master plan.

Theoretical Background

The walkability index traces its lineage to urban planning's D-variables framework (Ewing & Cervero, 2010): Density, Diversity (land-use mix), Design (street connectivity), Destination accessibility, and Distance to transit. Frank et al. (2010) operationalised four of these for the Neighborhood Quality of Life Study. PlanX adapts this to the street-segment level — walkability is fundamentally a network property: a street is walkable not in isolation but by virtue of what it connects to. Breakpoints default to a comfortably walkable European urban fabric: 120 junctions/km², 80 m block length, 25 POIs, and 0% slope all score 100.

Mathematical Formulation

Intersection density. Junctions (degree ≥ 3) counted within radius $r$ of each segment midpoint:

Land-use mix. Normalised Shannon entropy of buffer land-use areas:

Destinations. POI count within radius: $s\_dest(s) = 100 \cdot \min(1, n\_pois(s) / 25)$.

Block length (smaller-is-better): $s\_block(s) = 100 \cdot \max(0, \min(1, (400 - blk\_len(s)) / (400 - 80)))$.

Slope: $slope\_pct(s) = |z_{end} - z_{start}| / \ell_s \cdot 100$, then $s\_slope(s) = 100 \cdot \max(0, 1 - slope\_pct(s) / 10)$.

Composite: $walk\_score(s) = \sum w_c \cdot s_c(s) / \sum w_c$ over available components, with missing weights renormalised.

Input Data Requirements

Parameters

Output Description

Symbolic Representation

Map walk_score with a diverging RdYlGn ramp (5 classes: 0–20, 20–40, 40–60, 60–80, 80–100). Green = walkable; red = car-dependent. Line width 0.5 mm. Map sub-scores as small multiples to reveal which deficiency drives each low-scoring corridor: low s_inter = coarse network (add cut-throughs); low s_mix = monofunctional zoning; low s_dest = nothing to walk TO; low s_block = oversized blocks; low s_slope = topography. Rank low-score corridors by adjacent population for the investment priority list.

Interpretation Guide

Walkability bands map to different remedies: low s_inter → new links and cut-throughs; low s_mix → permit corner commercial uses; low s_dest → ground-floor activation, kiosks, stops; low s_block → mid-block crossings; low s_slope → topography (route around, not fixable by zoning). A high-scoring segment next to very low ones reads as an island — walkability is a NETWORK property. Rerun after proposed interventions and difference the scores to show exactly which streets improve and by how much. Feed walk_score into Pedestrian Route Quality to find the pleasantest path, not just the shortest.

Academic References

Frank, L.D., Sallis, J.F., Saelens, B.E., Leary, L., Cain, K., Conway, T.L., & Hess, P.M. (2010). "The Development of a Walkability Index: Application to the Neighborhood Quality of Life Study." British Journal of Sports Medicine, 44(13), 924–933. DOI: 10.1136/bjsm.2009.058701

Ewing, R. & Cervero, R. (2010). "Travel and the Built Environment: A Meta-Analysis." Journal of the American Planning Association, 76(3), 265–294. DOI: 10.1080/01944361003766766

Appendix D: Complete Bibliography

Barabasi, A.-L. & Albert, R. (1999). "Emergence of Scaling in Random Networks." Science, 286(5439), 509–512. DOI: 10.1126/science.286.5439.509

Bast, H., Delling, D., Goldberg, A., Muller-Hannemann, M., Pajor, T., Sanders, P., Wagner, D. & Werneck, R.F. (2016). "Route Planning in Transportation Networks." In: Kliemann, L. & Sanders, P. (eds.), Algorithm Engineering, LNCS 9220, pp. 19–80. Springer. DOI: 10.1007/978-3-319-49487-6_2

Bavelas, A. (1948). "A Mathematical Model for Group Structures." Human Organization, 7(3), 16–30. DOI: 10.17730/humo.7.3.f4033344851gl053

Bonacich, P. (1972). "Factoring and Weighting Approaches to Status Scores and Clique Identification." Journal of Mathematical Sociology, 2(1), 113–120. DOI: 10.1080/0022250X.1972.9989806

Brandes, U. (2001). "A Faster Algorithm for Betweenness Centrality." Journal of Mathematical Sociology, 25(2), 163–177. DOI: 10.1080/0022250X.2001.9990249

Crucitti, P., Latora, V. & Porta, S. (2006). "Centrality Measures in Spatial Networks of Urban Streets." Physical Review E, 73, 036125. DOI: 10.1103/PhysRevE.73.036125

Crucitti, P., Latora, V. & Porta, S. (2006). "Centrality in Networks of Urban Streets." Chaos, 16, 015113. DOI: 10.1063/1.2150162

Curtin, K.M. (2007). "Network Analysis in Geographic Information Science: Review, Assessment, and Projections." Cartography and Geographic Information Science, 34(2), 103–111. DOI: 10.1559/152304007781002163

Dijkstra, E.W. (1959). "A Note on Two Problems in Connexion with Graphs." Numerische Mathematik, 1(1), 269–271. DOI: 10.1007/BF01386390

Dreyfus, S.E. (1969). "An Appraisal of Some Shortest-Path Algorithms." Operations Research, 17(3), 395–412. DOI: 10.1287/opre.17.3.395

Ewing, R. & Cervero, R. (2010). "Travel and the Built Environment: A Meta-Analysis." Journal of the American Planning Association, 76(3), 265–294. DOI: 10.1080/01944361003766766

Frank, L.D., Sallis, J.F., Saelens, B.E., Leary, L., Cain, K., Conway, T.L., & Hess, P.M. (2010). "The Development of a Walkability Index: Application to the Neighborhood Quality of Life Study." British Journal of Sports Medicine, 44(13), 924–933. DOI: 10.1136/bjsm.2009.058701

Freeman, L.C. (1977). "A Set of Measures of Centrality Based on Betweenness." Sociometry, 40(1), 35–41. DOI: 10.2307/3033543

Handy, S.L. & Niemeier, D.A. (1997). "Measuring Accessibility: An Exploration of Issues and Alternatives." Environment and Planning A, 29(7), 1175–1194. DOI: 10.1068/a291175

Hillier, B. & Hanson, J. (1984). The Social Logic of Space. Cambridge University Press. DOI: 10.1017/CBO9780511597237

Hillier, B., Penn, A., Hanson, J., Grajewski, T., & Xu, J. (1993). "Natural Movement: Or, Configuration and Attraction in Urban Pedestrian Movement." Environment and Planning B: Planning and Design, 20(1), 29–66. DOI: 10.1068/b200029

Hillier, B. & Iida, S. (2005). "Network and Psychological Effects in Urban Movement." In: Cohn, A.G. & Mark, D.M. (eds.), Spatial Information Theory (COSIT 2005), LNCS 3693, pp. 475–490. Springer. DOI: 10.1007/11556114_30

Hillier, B., Yang, T., & Turner, A. (2012). "Normalising Least Angle Choice in Depthmap — and How It Opens Up New Perspectives on the Global and Local Analysis of City Space." Journal of Space Syntax, 3(2), 155–193. journal does not assign DOIs] Available at: UCL Discovery

Jenelius, E., Petersen, T. & Mattsson, L.-G. (2006). "Importance and Exposure in Road Network Vulnerability Analysis." Transportation Research Part A, 40(7), 537–560. DOI: 10.1016/j.tra.2005.11.003

Mattsson, L.-G. & Jenelius, E. (2015). "Vulnerability and Resilience of Transport Systems — A Discussion of Recent Research." Transportation Research Part A, 81, 16–34. DOI: 10.1016/j.tra.2015.06.002

Ortuzar, J. de D. & Willumsen, L.G. (2011). Modelling Transport. 4th ed., Wiley. DOI: 10.1002/9781119993308

Porta, S. & Renne, J.L. (2005). "Linking Urban Design to Sustainability: Formal Indicators of Social Urban Sustainability Field Research in Perth, Western Australia." Urban Design International, 10, 51–64. DOI: 10.1057/palgrave.udi.9000136

Porta, S., Crucitti, P., & Latora, V. (2006). "The Network Analysis of Urban Streets: A Primal Approach." Environment and Planning B: Planning and Design, 33(5), 705–725. DOI: 10.1068/b32045

Porta, S., Crucitti, P. & Latora, V. (2006). "The Network Analysis of Urban Streets: A Dual Approach." Physica A, 369(2), 853–866. DOI: 10.1016/j.physa.2005.12.063

Scott, D.M., Novak, D.C., Aultman-Hall, L., & Guo, F. (2006). "Network Robustness Index: A New Method for Identifying Critical Links and Evaluating the Performance of Transportation Networks." Journal of Transport Geography, 14(3), 215–227. DOI: 10.1016/j.jtrangeo.2005.10.003

Sevtsuk, A. & Mekonnen, M. (2012). "Urban Network Analysis: A New Toolbox for ArcGIS." Revue Internationale de Geomatique, 22(2), 287–305. DOI: 10.3166/rig.22.287-305

Talen, E. & Anselin, L. (1998). "Assessing Spatial Equity: An Evaluation of Measures of Accessibility to Public Playgrounds." Environment and Planning A, 30(4), 595–613. DOI: 10.1068/a300595

Turner, A. (2001). "Angular Analysis." In: Peponis, J., Wineman, J. & Bafna, S. (eds.), Proceedings of the 3rd International Space Syntax Symposium, Atlanta, GA, pp. 30.1–30.11. conference proceedings] Available at: UCL Discovery

Wasserman, S. & Faust, K. (1994). Social Network Analysis: Methods and Applications. Cambridge University Press. DOI: 10.1017/CBO9780511815478

Wilson, A.G. (1967). "A Statistical Theory of Spatial Distribution Models." Transportation Research, 1(3), 253–269. DOI: 10.1016/0041-1647(67)90035-4

Walking Slope Comfort

Processing ID: planx:walkingslope

Overview

Profiles every street segment against a Digital Elevation Model (DEM) to compute slope statistics, comfort classes, and direction-aware walking times. The engine samples elevations at regular intervals along each segment and applies Tobler's hiking function — the canonical empirical model relating walking speed to terrain gradient. For each segment, it reports the length-weighted mean absolute slope, maximum slope, total vertical climb and descent, and estimated forward and reverse walking travel times. The output's time_fwd_min column is designed as a drop-in cost field for all PlanX network routing tools, enabling slope-aware catchments that price uphill walks honestly. The reverse time captures the directional asymmetry that flat-network models ignore.

The comfort classification uses editable breakpoints on the mean absolute slope percentage. The defaults (5%, 8%, 12%) map to established terrain-accessibility standards: 5% is the maximum running slope permitted for an accessible route under ADA/ABA guidelines without landings; 8.33% is the maximum for a short ramp with landings; and 12% is the threshold above which stairs or mechanical assistance is generally preferred. These are illustrative defaults — local standards and terrain conditions should override them.

Theoretical Background

Walking speed as a function of terrain gradient has been studied for over a century, from Naismith's rule-of-thumb (1892) for Scottish mountaineering to modern GPS-instrumented studies. The canonical empirical function in GIScience is Tobler's hiking function (Tobler, 1993):

where $m$ is the signed slope gradient as a fraction ($m = dz/dx$, so $m = +0.10$ is a 10% uphill, $m = -0.05$ a 5% downhill). The function is empirically calibrated from hiker data and has three key properties:

1. Peak speed: 6.0 km/h at $m = -0.05$ (a gentle 5% downhill), faster than level walking because gravity assists without braking.
2. Asymmetry: downhill speeds exceed uphill speeds for the same absolute gradient — the function is not symmetric about $m = 0$.
3. Exponential decay: speeds drop rapidly for steep grades. At $m = 0.10$ (10% uphill), speed is ~3.5 km/h; at $m = 0.20$ (20%), ~1.5 km/h — halving distance at double the time.

This asymmetry has profound implications for accessibility analysis. Consider a hill between a residential area and a train station: the uphill journey (home to station) takes substantially longer than the downhill return, yet standard network-cost models assume a symmetric edge weight. A catchment drawn with a flat-network budget of 800 m will systematically overestimate the reach from uphill origins and underestimate it from downhill origins. Walking Slope Comfort provides the direction-aware travel times needed to correct this error.

The method of profiling — sampling a raster at regular intervals along a polyline and computing length-weighted grade statistics — is standard in trail analysis and has been applied to urban networks by Iverson (1975) and others. The length-weighted mean ($\sum |dz| / \sum dx$) is preferred over the arithmetic mean because it correctly accounts for segments of varying length: a short, steep section contributes proportionally less to the mean than a long, gentle one.

The comfort classification breakpoints are grounded in accessibility standards but are illustrative. The Americans with Disabilities Act (ADA, 2010) specifies 5% (1:20) as the maximum running slope for an accessible route and 8.33% (1:12) for short ramps with landings. The UN Convention on the Rights of Persons with Disabilities (CRPD) uses similar thresholds internationally. At 12% mean slope, most jurisdictions would require stairs or mechanical assistance (lift, funicular). These breakpoints are user-editable: a municipality with steeper terrain (e.g., San Francisco, Istanbul) may adopt a more permissive classification calibrated to local topography.

Mathematical Formulation

Profile sampling. Given a polyline of length $L$ and a sample step $\Delta s$, the tool generates sample distances $d_k = k \cdot \Delta s$ for $k = 0, 1, \ldots, \lceil L / \Delta s \rceil$, with the final sample at $d = L$. At each distance, a point is interpolated along the geometry and the DEM is sampled at that coordinate:

Samples falling outside the DEM extent or on NoData cells are discarded. If fewer than two valid samples are obtained, the segment is treated as flat.

Grade statistics. For consecutive samples $k, k+1$, the signed grade (fraction) over interval $i$ is:

The length-weighted mean absolute grade is:

where $\Delta d_i = d_{i+1} - d_i$. The maximum absolute grade is $m_{\max} = \max_i |m_i|$. Total climb and descent ($\sum \max(0, \Delta z_i)$ and $\sum \max(0, -\Delta z_i)$ respectively) are reported in metres.

Direction-aware travel time. The forward travel time is computed segment by segment using Tobler's speed:

where $v(m_i)$ is Tobler's speed in km/h for the signed grade $m_i$. The reverse travel time is computed identically but with the grade sign flipped and the intervals processed in reverse order: $t_{\text{rev}} = \sum_i (\Delta d_{n-i} / 1000) / v(-m_{n-i}) \cdot 60$. The effective mean speed from the Tobler profile is reported as tobler_fwd_kmh and tobler_rev_kmh — these differ from the flat-network assumption of constant walking speed and are the key diagnostics for slope-aware routing.

Input Data Requirements

Parameters

Output Description

Symbolic Representation

Map slope_pct with a sequential multi-hue ramp (YlOrRd, 5 classes, natural breaks). Red segments (>8%) are walking barriers — these should be the narrowest line weight (0.3 mm) to avoid visual dominance. Map comfort_class as a categorical renderer with green (1), yellow (2), orange (3), red (4) for a standards-compliance heat map. For publication exhibits, use a two-panel layout: slope_pct on one map, time_fwd_min / time_rev_min ratio on the other to show the asymmetry effect.

Interpretation Guide

Primary uses

1. Slope-aware catchments. Feed time_fwd_min as the cost field into OD Cost Matrix, Nearest Facility Allocation, Service Areas, or the 15-Minute City Access Score. This is the single most important step in calibrating a walking accessibility model for hilly cities. A catchment drawn with flat-network costs can overestimate uphill reach by 30–50% on steep terrain.
2. Accessibility compliance audit. Map comfort_class ≥ 3 segments against the pedestrian network. These are the locations where wheelchair, stroller, or mobility-impaired continuity breaks. Overlay with census data on disability prevalence to identify the most exposed streets.
3. Intervention prioritisation. Rank segments by $\text{climb\_m} \times \text{pedestrian\_volume}$ (from OD matrix bundles or pedestrian counts). A segment with 10 m climb and 1000 daily pedestrians is a higher priority for ramps, handrails, or a funicular than a 30 m climb segment with 10 pedestrians.

Diagnostic patterns

• time_fwd_min > time_rev_min by 50%+: the segment has a significant sustained grade. The uphill direction (forward, by the line's digitising direction) is penalised. If the digitising direction is arbitrary (OSM conventions vary), treat both directions as candidate uphill costs.
• max_pct > 3x slope_pct: the segment has one or more discrete steep spots (a short ramp, an underpass approach) within an otherwise gentle profile. These are point-fix targets — a ramp regrade or a short staircase — rather than whole-segment interventions.
• climb_m + descent_m > net elevation change: the segment undulates (rolling terrain). This pattern, common in older organic street networks that follow topography, adds energy cost without visual steepness. Long undulating segments can be more tiring than a steady grade because the walker repeatedly accelerates and decelerates.
• All comfort class ≥ 3 at the perimeter of a city centre: the city grew from a flat basin up into surrounding hills. The steepest segments are at the periphery, where lower-income neighbourhoods often concentrate. This pattern is an equity concern — terrain compounds transport poverty.

Cross-references with other PlanX tools

• Walkability Audit: the slope component there uses segment-endpoint differencing for a quick estimate; Walking Slope Comfort gives the full profile. For a definitive audit, replace the Walkability Audit's slope scores with Walking Slope Comfort's slope_pct.
• Pedestrian Route Quality: use time_fwd_min as the base cost and the comfort score as the quality overlay — the router will price uphill segments for their Tobler time and avoid them further if the comfort score is also low.
• Accessibility Equity (Gini/Theil): if the equity analysis shows high between-group inequality in walking access to transit, overlay comfort_class ≥ 3 segments on the underserved group's neighbourhood — terrain may be the mechanism.
• GTFS Import / Transit Access: when computing walk-to-transit times, use Walking Slope Comfort's time_fwd_min as the edge weight in the street-network graph. The resulting transit access times will account for the terrain that flat-network models ignore.

Pitfalls

• DEM resolution vs. segment length. A 30 m DEM sampled every 10 m on a 50 m segment oversamples — the same DEM pixel is queried multiple times. The grade between two identical elevations reads as zero. Use a DEM at least 2–3x finer than the segment length for meaningful within-block grade variation.
• Digitising direction. The forward/reverse assignment follows the geometry's digitising order. In OSM extracts, this order is arbitrary and does not correspond to any real-world convention. Never interpret "forward = uphill" — check the actual elevation profile.
• Tobler is empirical, not physiological. Tobler's function was calibrated on hikers, not urban walkers in everyday clothing. It likely underestimates the penalty of steep urban grades (carrying groceries, pushing strollers) and overestimates speeds on flat terrain (crowds, crossings, signals intervene). Treat the times as comparative, not as literal door-to-door predictions.
• Insufficient DEM coverage. If fewer than 2 samples are valid along a segment, the tool treats it as flat and emits a warning. A large warning count means the DEM does not cover the network — check extents and CRS alignment.

Academic References

Tobler, W. (1993). "Three Presentations on Geographical Analysis and Modeling: Non-Isotropic Geographic Modeling; Speculations on the Geometry of Geography; and Global Spatial Analysis." NCGIA Technical Report, 93-1. University of California, Santa Barbara. technical report, no DOI assigned] Available at: eScholarship

Iverson, W.D. (1975). "Assessing terrain conditions for hiking and mountain recreation." Journal of Leisure Research, 7(1), 37–45.

Naismith, W.W. (1892). "Excursions. Cruach Ardran, Stobinian, and Ben More." Scottish Mountaineering Club Journal, 2(3), 136. historical mountaineering journal, no DOI assigned]

ADA Standards for Accessible Design (2010). Title III, 28 CFR Part 36, Section 405: Ramps. U.S. Department of Justice. regulatory standard, no DOI assigned] Available at: ada.gov

Moughtin, C. & Shirley, P. (2005). Urban Design: Green Dimensions. 2nd ed., Architectural Press. (Section 4.2: "Gradients and pedestrian movement" — practical urban-design treatment of slope thresholds.)

Street Environment Comfort

Processing ID: planx:streetcomfort

Overview

Scores every street segment 0–100 by aggregating the micro-scale environmental qualities that pedestrians experience at the street level. The tool models perception as a spatial kernel: assets and barriers do not affect only the point where they sit, but radiate influence over a distance — the bandwidth $h$ — that represents the pedestrian's awareness radius. Comfort assets (trees, benches, street lighting, active shopfronts) raise the score; comfort barriers (potholes, blank walls, vacant lots, construction hoardings) lower it. Optional raster layers (winter sun hours, heat risk index, road noise) add climatic and sensory dimensions.

Each component is aggregated via a kernel density estimate (KDE) at sample points along each segment, then min-max normalised to [0, 1] and orientation- flipped (higher density of barriers = lower comfort). The final index is a weighted mean of the oriented components, scaled 0–100. Missing components are gracefully excluded and weights renormalised; constant components (e.g., all segments have the same tree density) are dropped with a warning.

The index is relative to the study area: it ranks streets against each other, not against an absolute standard. A comfort score of 70 means the segment is in the 70th percentile of local conditions, not that it meets any external benchmark. This makes the tool an ideal comparative diagnostic for identifying the best and worst streets in a network, but unsuitable for compliance checking against a fixed standard.

Theoretical Background

Street-level environmental quality has been studied under several overlapping frameworks. Jan Gehl's decades of observational research in Copenhagen and elsewhere (Gehl, 2011) established that the "space between buildings" — the micro-scale qualities of pavements, facades, street furniture, and planting — determines whether a street invites lingering or merely permits passage. The concept of environmental affordance (Gibson, 1979; applied to urban design by Heft, 1988) argues that the physical environment does not determine behaviour but offers possibilities: a bench affords sitting, a tree affords shade, a blank wall affords nothing. The comfort score aggregates these affordances into a single continuous metric.

The kernel-density approach draws on spatial statistics (Silverman, 1986) and has been applied to urban perception in two influential papers. Ewing & Handy (2009) used expert panel ratings of street-view imagery to identify five urban design qualities — imageability, enclosure, human scale, transparency, and complexity — and then operationalised each with measurable spatial variables. Harvey et al. (2015) extended this with a streetscore algorithm that rated perceived safety from street-level images using a combination of computer vision features and crowd-sourced training data. The PlanX tool follows the same logic but uses vector-based KDE rather than image classification, making it applicable to any city with point-layer inventories (trees, lamps, benches) regardless of whether street-level imagery is available.

The kernel bandwidth $h$ is the critical calibration parameter. At $h = 50$ m (the default), a bench affects comfort out to roughly one block length — the range at which a pedestrian can see and decide to walk toward it. At $h = 25$ m, only very local assets count (the "immediate sidewalk" view). At $h = 100$ m, assets at the far end of a long block still contribute — relevant for assessing visual amenity rather than immediate physical comfort. The kernel shape controls how the influence decays with distance: Uniform (equal weight to $h$), Triangular (linear decay), Epanechnikov (quadratic decay, default — most statistical efficiency), Gaussian (exponential decay, tail extending beyond $h$ but truncated for computational practicality).

Mathematical Formulation

Kernel weights. For a candidate feature at distance $d$ from a sample point, with bandwidth $h > 0$ and normalised distance $u = d/h$:

All kernels are truncated at $u = 1$ ($d > h \Rightarrow K = 0$). The Gaussian kernel uses $\sigma = h/3$, so that $h$ acts as an approximate $3\sigma$ cutoff.

Segment density. For a segment with sample points $\{\mathbf{s}_1, \ldots, \mathbf{s}_m\}$ and a candidate feature set $\{\mathbf{p}_1, \ldots, \mathbf{p}_k\}$ with weights $w_j$, the segment-level density for this component is:

Candidates are pre-filtered by a spatial index (QgsSpatialIndex) on the bounding box of the segment grown by $h$ — only features within reach are evaluated. Sample points are placed at regular intervals (default 10 m) with midpoint offset: the first sample is at $step/2$ from the segment start, avoiding endpoint duplication at shared junctions.

Min-max normalisation and orientation. For component $c$ with raw values $\rho_c(s)$ across $n$ segments, the normalised and oriented value is:

If $\max = \min$ (the component is constant), it is dropped. Raster components are sampled at each sample point and the segment mean is used as $\rho_c(s)$.

Weighted comfort index. For used components $\mathcal{C}$ with weights $w_c$:

Component weights default to 1.0 each (equal) and are user-editable via a name=value syntax (e.g., positive=2, negative=1 doubles the asset weight). Absent components are renormalised away:

The min-max normalisation makes the index scale-dependent on the study area extent. A comfort score of 50 means the segment is at the median of the observed range — if the entire area is pleasant, "median" is still pleasant. For cross-city comparison, use the same component layers and a consistent bandwidth.

Input Data Requirements

Parameters

Output Description

Symbolic Representation

Map comfort with a diverging RdYlGn ramp (5 quantile classes). Green = pleasant; red = hostile. Line width 0.4–0.7 mm scaled by the absolute deviation of comfort from the network median — the best and worst streets are the widest lines. The raw density fields (pos_den, neg_den) are diagnostic: map neg_den in red alone to see the barrier landscape, then overlay high-pos_den segments in green to identify streets where assets and barriers coexist — a complex reading that the composite score alone would average away.

Interpretation Guide

The two-factor diagnostic

Read comfort scores as a two-by-two matrix with pos_den and neg_den:

Cross-references with other PlanX tools

• Walkability Audit: the walkability score captures the meso-scale structure (connectivity, mix, destinations); Street Environment Comfort captures the micro-scale experience. A street with a perfect walkability score can still score low on comfort if it is lined with blank walls and lacks shade. The two scores together give the complete pedestrian-quality picture.
• Pedestrian Route Quality: feed comfort as the custom score field. The quality-weighted router will avoid comfort-poor streets just as it avoids low-walkability streets. Run with both scores independently and compare the route geometries — where they diverge, meso-scale and micro-scale quality disagree about which route is better.
• Shadow Casting / Sun Hours: winter sun hours make an excellent RASTER_PLUS input — a street that receives zero winter sun is perceptibly colder and darker, and the comfort score will reflect this.
• Heat Island Risk Grid / Road Noise Screening: natural RASTER_MINUS inputs. Heat and noise are the two sensory stressors that pedestrians feel most acutely.

Pitfalls

• Relative scale. The score ranks within the study area. A score of 80 in a well-maintained historic centre may represent a higher absolute quality than a score of 80 in a neglected peripheral estate. Do not compare scores across study areas with different component inventories.
• Data completeness. The tool relies on point-inventory layers. If street trees have not been inventoried, pos_den will read zero everywhere — the tool cannot detect assets that are not in the data. Always audit the point layers against ground truth before interpreting comfort scores.
• Constant components. If every segment has exactly the same value for a component (e.g., every street has one streetlight), that component is dropped and does not contribute to the score. This is correct — a constant cannot discriminate between streets — but it means the absolute comfort level may be higher (or lower) than the 0–100 scale suggests.
• Bandwidth sensitivity. At very small bandwidths (e.g., 5 m), only features exactly on the segment influence it — a tree 6 m away is invisible. At very large bandwidths (e.g., 500 m), all segments converge to the same score because every street sees the same set of features. Test 2–3 bandwidths and check that the ranking is stable before proceeding with analysis.

Academic References

Gehl, J. (2011). Life Between Buildings: Using Public Space. 6th ed., Island Press. (The foundational observational study of micro-scale urban qualities that predict pedestrian presence and stationary activity.) architecture/design monograph, no DOI assigned]

Ewing, R. & Handy, S. (2009). "Measuring the Unmeasurable: Urban Design Qualities Related to Walkability." Journal of Urban Design, 14(1), 65–84. DOI: 10.1080/13574800802451155

Harvey, C., Aultman-Hall, L., Hurley, S.E., & Troy, A. (2015). "Effects of Skeletal Streetscape Design on Perceived Safety." Landscape and Urban Planning, 142, 18–28. DOI: 10.1016/j.landurbplan.2015.05.007

Silverman, B.W. (1986). Density Estimation for Statistics and Data Analysis. Chapman & Hall. (The canonical text on kernel density estimation, including the MSE optimality of the Epanechnikov kernel.) DOI: 10.1007/978-1-4899-3324-9

Gibson, J.J. (1979). The Ecological Approach to Visual Perception. Houghton Mifflin. (The theory of affordances — that the environment offers possibilities for action — which underpins the entire concept of "environmental comfort" as a measurable property.)

Pedestrian Route Quality

Processing ID: planx:routequality

Overview

Routes pedestrians over quality-weighted streets and reports what the walk is actually like — the complement to every shortest-path tool in PlanX. While OD Routes answers "how far is it," Pedestrian Route Quality answers "how good is the walk." The tool takes a street network with a per-segment quality score (0–100, typically the Walkability Audit output or Street Environment Comfort score) and a quality penalty $p$, reweights each segment's cost as:

With penalty $p = 1$, a segment scoring 0 costs double its length; a segment scoring 50 costs 1.5x; a perfect-100 segment costs exactly its length. With $p = 0$, the quality-weighted cost collapses to the plain geometric length — the tool reproduces the shortest path. For every origin–destination pair, the tool reports the quality-optimal route's length, the plain shortest-path length, the detour ratio between them (the price of pleasantness), the length-weighted mean walk score along the route, the share of route length on low-scoring segments (below a user-set threshold), and the number of edges traversed.

The pairing mode offers two strategies: Nearest destination finds the best-quality route from each origin to its single nearest destination (by quality-weighted cost), the natural mode for "which facility would a quality-conscious pedestrian choose"; All pairs computes routes to every destination, the mode for catchment-quality profiling.

Theoretical Background

The concept of quality-weighted routing originates in the observation that pedestrians do not minimise distance alone. A large body of stated-preference and revealed-preference research (Guo & Loo, 2013; Borst et al., 2009; Agrawal et al., 2008) demonstrates that pedestrians accept detours — often 10–30% — to walk through pleasant, shaded, or active streets rather than along noisy arterials or through dark underpasses. The detour they accept is the revealed value of environmental quality: if pedestrians consistently walk 250 m extra to use a tree-lined street rather than a 750 m arterial, they value the environmental quality at roughly $250/750 = 0.33$ — a 33% premium on the shortest distance.

The quality-penalty formulation used here is a generalised cost model from transport economics (Ortúzar & Willumsen, 2011): each link's perceived cost is the sum of its objective cost (length) and a penalty proportional to its quality deficit. This is structurally identical to how congestion charges, tolls, or "traffic stress" penalties are added to link costs in multi-modal transport models. The penalty $p$ calibrates how much the pedestrian values quality relative to distance: $p = 0.5$ means a score-0 street costs only 1.5x its length (the pedestrian is only mildly quality-sensitive); $p = 2.0$ means a score-0 street costs 3x its length (the pedestrian is highly quality-averse and will detour substantially).

This approach differs from the more common composite index weighting in walkability studies (Frank et al., 2010; Leslie et al., 2007), which produce a single per-segment score but do not model route choice. PlanX separates the two steps: Walkability Audit (or Street Environment Comfort) produces the score; Pedestrian Route Quality answers the behavioural question — given these scores, where would people actually walk?

The connection to Safe Routes to School (SRTS) programmes is direct and operational. SRTS programmes in the US (authorised under federal transportation legislation since 2005) and similar "School Streets" initiatives in the UK and Europe aim to identify and improve the routes children take to school. The standard SRTS audit rates every block on ~10 safety and comfort criteria. Pedestrian Route Quality operationalises this at city scale: run home-to-school pairs (using building centroids or address points), rank routes by low_share (the fraction of the route on streets scoring below, say, 50), and the worst-ranked routes are the SRTS priority list — every block on these routes that falls below the threshold is a candidate for sidewalk widening, crossing improvements, lighting, or traffic calming.

Mathematical Formulation

Quality-weighted edge cost. For edge $e$ with geometric length $\ell_e$ and quality score $\text{score}_e \in [0, 100]$:

Edges without a score (NULL or missing) are treated as neutral: $\text{score}_e = 100$, so $w_{\text{quality}}(e) = \ell_e$ — they contribute their geometric cost and no penalty.

Quality-optimal path. Given origins $\{o_1, \ldots, o_m\}$ and destinations $\{d_1, \ldots, d_n\}$, the quality-optimal route from $o_i$ to $d_j$ minimises:

This is solved by Dijkstra's algorithm on the quality-weighted adjacency matrix. The shortest-path (distance-only) route is solved on the original (unweighted) adjacency matrix, using the same engine (engine/paths.py) but with $\text{score}_e \equiv 100$ for all edges.

Detour ratio. For the quality-optimal route with total geometric length $L_{quality}$ and the shortest-path length $L_{shortest}$:

$\text{detour} \geq 1.0$ always (the shortest path cannot be longer than any other path). $\text{detour} = 1.0$ means the shortest path is also the best- quality path — the ideal outcome. $\text{detour} = 1.5$ means the pedestrian walks 50% further to avoid poor-quality streets.

Length-weighted mean score. For a route comprising edges $\{e_1, \ldots, e_k\}$ with lengths $\ell_1, \ldots, \ell_k$ and scores $s_1, \ldots, s_k$:

This is the experienced quality — unlike the simple mean over edges, a long edge with a low score weighs more heavily than a short edge.

Low-score share. The fraction of total route length on segments scoring below a user-defined threshold $s_{low}$ (default: 50):

Input Data Requirements

Parameters

Output Description

Symbolic Representation

Map routes by detour with a diverging RdYlGn ramp (reversed: green = detour ~1.0, red = detour ≥ 1.4). Line width 0.3 mm, opacity 40% for bundling. The visual story is the divergence between the shortest and quality paths — where many routes take the same detour onto a pleasant alternative, that alternative street emerges as a thick green bundle even if the underlying street network is thin. For the "all pairs" mode, filter to a single origin and colour by dest categorically to see which destinations a quality-conscious pedestrian at that origin would prefer.

Interpretation Guide

The three diagnostic regimes

Cross-references with other PlanX tools

• Walkability Audit / Street Environment Comfort: the quality score source. Run with both walk_score and comfort independently and compare — where routes diverge, meso-scale walkability and micro-scale comfort disagree about the best path.
• OD Cost Matrix / OD Routes: the plain shortest-path baseline. The shortest_m field in this tool's output matches net_cost in the OD Cost Matrix output for the same OD pair.
• Link Criticality: cross-reference trapped-route corridor segments with criticality scores. A segment that is both a quality trap AND a single point of failure (high criticality) is the highest-risk pedestrian infrastructure in the network.
• Space Syntax: high-NACH segments that score low on walkability and appear as trapped routes suggest a configurational problem — the grid naturally funnels movement onto a segment that is hostile to pedestrians. This is the severance pattern (a major through-route dividing a neighbourhood) and requires a structural response (crossings, median refuges, traffic calming) rather than a cosmetic one.

Pitfalls

• Penalty calibration. There is no universal "correct" penalty. $p = 0.5$ models a mildly quality-sensitive pedestrian; $p = 2.0$ models someone who will go far out of their way to avoid poor streets. For planning purposes, test $p \in \{0.5, 1.0, 2.0\}$ and report the range: "between X% and Y% of school routes are trapped regardless of penalty." Stable findings across the range are robust; findings that flip at a threshold need sensitivity analysis.
• Score provenance. The quality score inherits all limitations of the tool that produced it. If the Walkability Audit was run without a land-use layer, the s_mix component was skipped and walk_score may overrate streets in monofunctional areas. If Street Environment Comfort was run without tree-point data, it cannot penalise treeless streets. Audit the score's component completeness before interpreting routes.
• Network completeness. A "trapped" finding may be an artefact of an incomplete network: if the only quality alternative uses a footpath that is not in the network, the router cannot find it and declares a trap where none exists on the ground. Always verify trapped findings with field observation or aerial imagery before recommending major investments.
• Edge effects. Routes near the network boundary may appear trapped because alternatives lie outside the study area. Buffer the network by at least one neighbourhood beyond the actual study area.

Academic References

Guo, Z. & Loo, B.P.Y. (2013). "Pedestrian Environment and Route Choice: Evidence from New York City and Hong Kong." Journal of Transport Geography, 28, 124–136. DOI: 10.1016/j.jtrangeo.2012.11.010

Agrawal, A.W., Schlossberg, M., & Irvin, K. (2008). "How Far, by Which Route and Why? A Spatial Analysis of Pedestrian Preference." Journal of Urban Design, 13(1), 81–98. DOI: 10.1080/13574800701804074

Leslie, E., Coffee, N., Frank, L., Owen, N., Bauman, A., & Hugo, G. (2007). "Walkability of Local Communities: Using Geographic Information Systems to Objectively Assess Relevant Environmental Attributes." Health & Place, 13(1), 111–122. DOI: 10.1016/j.healthplace.2005.11.001

Borst, H.C., de Vries, S.I., Graham, J.M.A., van Dongen, J.E.F., Bakker, I., & Miedema, H.M.E. (2009). "Influence of Environmental Street Characteristics on Walking Route Choice of Elderly People." Journal of Environmental Psychology, 29(4), 477–484. DOI: 10.1016/j.jenvp.2009.08.002

Ortúzar, J. de D. & Willumsen, L.G. (2011). Modelling Transport. 4th ed., Wiley. (Chapter 7: "Route Choice and Traffic Assignment" — the generalised-cost framework from which the quality-penalty model is derived.) DOI: 10.1002/9781119993308

3. Urban Morphology

The Urban Morphology group quantifies the physical form of the city at three scales: the building (shape metrics, orientation, courtyard index, shared-wall ratio), the plot (morphological tessellation as a cadastral proxy via Voronoi partitioning), and the block (Spacematrix density indicators GSI/FSI/OSR/L and street-network morphology via orientation entropy, meshedness indices, and junction typology).

Building Form Metrics

Processing ID: planx:buildingformmetrics

1. Theoretical Background

1.1 Academic Lineage

Building form metrics translate the geometric properties of individual footprint polygons into numerical descriptors of typology, construction era, and spatial organisation. The intellectual foundation draws from three traditions. First, classical Euclidean geometry contributed the isoperimetric inequality — the circle maximises area for a given perimeter, giving rise to the isoperimetric quotient (IPQ) as a compactness measure that has been used in urban morphology since at least the 1960s (Haggett & Chorley, 1969). Second, computational geometry furnished efficient algorithms for the minimum bounding rectangle via Toussaint's (1983) rotating calipers, enabling orientation and rectangularity to be computed in $O(k)$ time on a convex hull of $k$ vertices. Third, Batty & Longley (1994) demonstrated that fractal geometry could quantify the complexity of building footprints — their observation that organic urban fabric yields higher fractal dimensions than planned modernist fabric remains the standard interpretive frame.

1.2 Methodology Evolution

The systematic computation of building-level morphology metrics was catalysed by the release of open building footprint datasets (OpenStreetMap, national cadastral agencies) and the development of the momepy toolkit (Fleischmann, 2019). Prior to momepy, researchers computed these metrics in ad-hoc scripts; momepy standardised the vocabulary and computation. Fleischmann, Romice & Porta (2020) later provided the theoretical framework connecting single-building metrics to multi-scale urban form analysis, arguing that "spatial signatures" — combinations of metrics across scales — are the proper unit of morphological comparison rather than any single indicator.

1.3 Key Assumptions and Limitations

All metrics operate on the largest part of multi-polygon footprints, discarding detached annexes. Metrics are scale-invariant (ratios of areas and lengths) except area and perimeter which are absolute. The shared-wall computation uses a simple spatial index intersection test; it does not detect topological adjacency from a common cadastral polygon, so it may over-count walls separated by narrow gaps. The fractal dimension formula $D = 2\ln(P/4)/\ln(A)$ is valid for simple closed shapes but produces unreliable values for highly irregular perimeters below ~1 m². All metrics require a projected CRS; results in geographic coordinates are meaningless.

1.4 Use Cases

• Building typology classification: cluster on (compact, elongation, sharedwall, court_idx) to produce unsupervised typology maps.
• Energy modelling: IPQ and elongation are strong predictors of heating/cooling load per m² — complex envelopes lose more energy.
• Historical fabric detection: fractal dimension and corner count identify organic pre-industrial fabric versus planned grid fabric.
• Data quality audit: anomalously high corner counts on simple buildings flag over-digitised data; missing courtyards flag incomplete data.
• Plan analysis: compare mean metrics between existing fabric and proposed fabric to quantify morphological change.

2. Mathematical Formulation

Let $R = \{(x_1, y_1), \ldots, (x_n, y_n)\}$ denote the exterior ring of a building footprint, with $x_{n+1} = x_1$ and $y_{n+1} = y_1$ for closure. Let interior rings (courtyards) be denoted $I_1, \ldots, I_m$. All metrics are computed in projected map units (metres).

where $A_{hull}$ is the area of the convex hull computed via Andrew's monotone chain algorithm; $L$ and $W$ are the length and width of the minimum-area rotated rectangle obtained by the rotating calipers method on the convex hull; the orientation $\theta \in [0, 180)$ is the angle of $L$ from the positive $x$-axis; $D_{fractal}$ is set to 0 when the logarithm arguments are invalid; $\partial B_i$ denotes the boundary of building $i$; $N(i)$ is the set of neighbour buildings whose bounding box intersects building $i$; and $\ell$ measures the intersection length of boundary curves.

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Benchmark Ranges

5.2 Spatial Patterns

• Orientation clustering: strong uni-modal peaks in orient_deg at street-parallel angles indicate grid-aligned fabric; uniform distributions indicate free-form layouts (post-war estates, organic growth). Style orient_deg with a categorical colour ramp to detect fabric boundaries where the prevailing grain shifts.
• Compactness core-periphery: historic cores typically show low compact (complex footprints, wings and annexes); post-war suburbs show high compact (simple rectangular slabs). A gradient from low to high compactness moving outward marks the morphological frontier between pre-modern and modern fabric.
• Shared-wall gradients: continuous high sharedwall in a district = attached terraced fabric; sudden drops to zero = morphological boundary (gap sites, detached infill, or a new development regime).

5.3 Cross-References

• Feed area_m2 and perim_m into energy models (envelope-to-floor ratio = perim / area, a proxy for heat loss per m²).
• Combine orient_deg with Street Network Morphology orientation order: buildings with orientation diverging from the street grid identify morphological outliers.
• Use sharedwall with Morphological Tessellation cell area to distinguish organic medieval fabric (small cells, high sharedwall) from modernist estates (large cells, zero sharedwall).
• Feed the full metric set into Spacematrix Density as building attributes; the typology classification adds a qualitative layer to the quantitative GSI/FSI/OSR indicators.

5.4 Common Pitfalls

• Geographic CRS: using lat/lon produces area and perimeter values in decimal-degree units, which are meaningless. The tool emits a warning but does not block execution.
• Over-digitised data: hundreds of corners on a simple rectangular house indicate a CAD import that preserved every curve vertex. Filter using corners < 6 AND rectangularity > 0.95: buildings passing this test should have 4 corners; any with > 20 corners are over-digitised.
• Multi-polygon buildings: only the largest part is measured. Detached garages and outbuildings are ignored. If these are critical, split the building into separate features first.
• Shared-wall false positives: walls separated by < 1 mm due to digitising tolerance will register as shared. Check anomalously high sharedwall on detached villas by inspecting the source data.

6. Symbolic Representation

Recommended QGIS styling:

• compact: Graduated, 5 classes (Jenks), green (high) to red (low). Low compactness = complex footprints = higher envelope cost.
• elongation: Graduated, blue ramp. High elongation = long bars. Add a rotation marker symbol sized by elongation, rotated by orient_deg, to visualise grain.
• sharedwall: Categorised: 0 = grey (detached), 0–0.1 = light blue (touching), 0.1–0.3 = medium blue (semi-detached), >0.3 = dark blue (attached/terraced).
• court_idx: Graduated, 0 = transparent, >0.05 = orange. Identifies courtyard-typology buildings at a glance.
• orient_deg: Categorised into 8 compass sectors (N, NE, E, SE, S, SW, W, NW) using a qualitative colour scheme (Set3 or Pastel1).

7. Literature

✓ Fleischmann, M. (2019). "momepy: Urban Morphology Measuring Toolkit." Journal of Open Source Software, 4(43), 1807. DOI: 10.21105/joss.01807

✓ Fleischmann, M., Romice, O. & Porta, S. (2020). "Measuring urban form: Overcoming terminological inconsistencies for a quantitative and comprehensive morphologic analysis of cities." Environment and Planning B, 48(8), 2133–2150. DOI: 10.1177/2399808320910444

✓ Toussaint, G.T. (1983). "Solving geometric problems with the rotating calipers." Proceedings of IEEE MELECON '83, Athens, A10.02/1–4.

✓ Batty, M. & Longley, P. (1994). Fractal Cities: A Geometry of Form and Function. Academic Press. ISBN: 978-0124555709.

✓ Haggett, P. & Chorley, R.J. (1969). Network Analysis in Geography. Edward Arnold. ISBN: 978-0713154597.

✓ Steadman, P. (2014). "Building types and built forms." Journal of Space Syntax, 5(1), 1–22.

Morphological Tessellation

Processing ID: planx:morphologicaltessellation

1. Theoretical Background

1.1 Academic Lineage

Morphological tessellation addresses a fundamental data problem in urban morphology: cadastral plot boundaries are often unavailable, proprietary, or inconsistent across jurisdictions, yet they are the natural analysis unit for density, coverage, and typology studies. The method implemented here follows the momepy toolkit (Fleischmann, 2019), which in turn builds on the concept of "spatial proximity polygons" from computational geometry. The core idea — partitioning space so that every point is assigned to its nearest building — originates from Voronoi (1908) but gained urban application through the work of Boffet & Rocca Serra (2001) on "morphological envelopes" and was systematised by Fleischmann, Romice & Porta (2020) into the standard momepy workflow: shrink buildings to prevent gap competition, densify boundaries to generate smooth partitioning lines, construct the Voronoi diagram, dissolve cells per building, and clip to a study area boundary.

1.2 Methodology and Key Decisions

Three design choices critically affect the output. Shrink distance: buildings are buffered inward before seeding to prevent adjacent buildings whose footprints nearly touch from competing over the narrow gap between them — without shrinking, the tessellation boundary bisects the gap, producing implausibly thin cells. A typical shrink of 0.4 m works for modern cadastral data; increase to 1–2 m for hand-digitised historic maps where buildings bleed into each other. Densify spacing: the Voronoi diagram is computed from boundary seed points, not from building centroids, so the cell boundaries can follow the shape of the building. Denser seeds produce cells that more closely approximate a setback-based plot proxy but increase computation time quadratically. Clip mask: cells at the study area edge are artificially truncated. For any cell-level statistic (mean area, Gini of cell sizes), exclude the outer ring of border-touching cells, or supply a study area generously larger than the analysis area.

1.3 Use Cases and Limitations

• Plot-proxy construction: the primary use — enable plot-level analysis (GSI, FSI, coverage ratios) when cadastral data is unavailable.
• Grain analysis: cell area distribution quantifies urban grain. Uniform small cells = organic medieval or fine-grained gridded fabric; a few giant cells amid many small = campus or estate typology; uniform large cells = modernist superblock planning.
• Limitations: (a) tessellation cannot detect administrative plot boundaries — two buildings on one legal plot will be separated; (b) buildings very close together (< 2x shrink distance) may produce degenerate cells; (c) the method assumes buildings are the primary spatial organisers — large open spaces (parks, brownfields, water) must be supplied via the mask layer; (d) industrial sheds with complex footprints produce fragmented seed patterns; increase densify spacing for these.

2. Mathematical Formulation

Let $B = \{b_1, \ldots, b_n\}$ be the set of building footprint polygons in a projected CRS. For each building $b_k$, let $\partial b_k$ denote its exterior ring. The workflow proceeds in five stages:

Let $P = \bigcup_{k=1}^{n} S_k$ be the set of all seed points, with each point $p \in P$ tagged by its originating building index $k(p)$. The standard Voronoi tessellation assigns each point in the plane to its nearest seed:

Cells belonging to the same building are dissolved (union), then clipped to the study area mask $M$:

where the study area mask $M$ is either a user-supplied boundary polygon or the convex hull of all building seed points buffered by $d_{limit}$:

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Benchmark Patterns

• Uniform small cells (50–300 m²): fine-grained organic or grid fabric, buildings closely spaced, narrow gaps. Typical of historic centres.
• Uniform medium cells (300–1000 m²): planned gridded fabric, regular setbacks. Typical of 19th–early 20th century expansion districts.
• Mixed small + a few giant cells (> 5000 m²): campuses, shopping centres, or estate buildings in an otherwise fine-grained context. The giant cells flag institutional or commercial land-uses.
• Uniform large cells (1000–5000 m²): modernist superblock planning with generous setbacks. Low coverage ratios expected.

5.2 Cross-References

• Feed cells directly into Spacematrix Density as the BLOCKS input: tessellation cells + Spacematrix = plot-level GSI/FSI without cadastral data.
• Combine cell_m2 with Building Form Metrics area_m2 to compute cell-level coverage ratio (area_m2 / cell_m2), a proxy for plot coverage.
• Use cells as the denominator for dasymetric population distribution — more accurate than administrative units because cells respect building geometry.
• Feed cell geometry into Street Network Morphology contextual analysis: cell size variance between districts quantifies morphological grain.

5.3 Common Pitfalls

• Edge effect: cells intersecting the study area boundary are artificially truncated. Always identify and exclude border cells before computing cell area statistics. A practical rule: exclude cells whose cell_m2 is less than 50% of the median interior cell area.
• Too many seeds: with small densify spacing and large building footprints, seed counts can exceed 100,000. The QGIS Voronoi implementation may fail silently. Start with the default 2.0 m and only reduce if cell boundaries are visibly jagged.
• Degenerate shrink: buildings smaller than 2x shrink distance may disappear after shrinking. The tool falls back to the original geometry, but such buildings will produce disproportionately large cells.
• Multi-part buildings: each part is processed independently. A building with detached annexes will generate multiple cells. This is typically desired behaviour but be aware when computing per-building statistics.

6. Symbolic Representation

Recommended QGIS styling:

• cell_m2: Graduated, 5 classes (Natural Breaks), light yellow (small) to dark brown (large). Small cells = fine grain; large cells = coarse grain. Add 50% transparency to see the underlying buildings.
• Coverage ratio (calculated): Graduated, 5 classes, green (low coverage, porous) to red (high coverage, compact). Over 0.5 = dense urban; under 0.15 = suburban or campus.
• Edge detection: select cells where cell_m2 < 0.5 * median cell area; style these with a dashed outline to flag them for exclusion from statistics.

7. Literature

✓ Fleischmann, M. (2019). "momepy: Urban Morphology Measuring Toolkit." Journal of Open Source Software, 4(43), 1807. DOI: 10.21105/joss.01807

✓ Fleischmann, M., Romice, O. & Porta, S. (2020). "Measuring urban form: Overcoming terminological inconsistencies for a quantitative and comprehensive morphologic analysis of cities." Environment and Planning B, 48(8), 2133–2150. DOI: 10.1177/2399808320910444

✓ Boffet, A. & Rocca Serra, S. (2001). "Identification of spatial structures within urban blocks for town characterisation." Proceedings of the 20th International Cartographic Conference, Beijing, 1974–1983.

✓ Voronoi, G. (1908). "Nouvelles applications des parametres continus a la theorie des formes quadratiques." Journal fur die Reine und Angewandte Mathematik, 134, 198–287.

✓ Aurenhammer, F. (1991). "Voronoi diagrams — a survey of a fundamental geometric data structure." ACM Computing Surveys, 23(3), 345–405. DOI: 10.1145/116873.116880

Spacematrix Density

Processing ID: planx:spacematrixdensity

1. Theoretical Background

1.1 Academic Lineage

The Spacematrix method was developed by Meta Berghauser Pont and Per Haupt at TU Delft, first published in their 2010 book Spacematrix: Space, Density and Urban Form and revised in an open-access 2023 edition. The method addresses a long-standing problem in urban planning: density is typically regulated through a single number (Floor Area Ratio, FAR, or Floor Space Index, FSI), but a given FSI can describe completely different urban forms depending on how much ground the building occupies (GSI) and how tall it is (L). By jointly analysing FSI, GSI, OSR (Open Space Ratio), and L (mean number of floors), the Spacematrix captures four independent degrees of freedom that together define the built density typology of any urban fabric.

1.2 The Spacematrix Diagram

The method's central analytical device is the Spacematrix diagram: a scatter plot with GSI on the horizontal axis and FSI on the vertical axis. Any built form occupies a single point. Lines of constant L radiate from the origin (FSI = L * GSI). Curves of constant OSR are hyperbolic. The diagram reveals that planning codes which only specify FSI and GSI implicitly fix L (since L = FSI/GSI), and vice versa: a plan demanding FSI 2.0 at GSI 0.2 silently demands 10 storeys (L = 10), which may conflict with height limits or neighbourhood character policies. OSR = (1 - GSI)/FSI measures the open space cost of each built square metre: OSR < 0.5 signals pressure on public space; OSR > 1.5 signals spacious suburban fabric.

1.3 Typology Classification

The 10-class Spacematrix label combines a height category (Low-rise: L < 3; Mid-rise: 3 <= L <= 6; High-rise: L > 6) with a coverage category (compact: GSI >= 0.35; moderate: 0.15 <= GSI < 0.35; spacious: GSI < 0.15). The three by three grid produces nine built classes plus "Unbuilt" for blocks with no intersection area. The labels provide a standardised vocabulary: "Mid-rise compact" describes the classic European perimeter block (4-6 storeys, 40-60% coverage); "High-rise spacious" describes tower-in-park Modernist schemes; "Low-rise spacious" describes detached suburban housing.

1.4 Key Assumptions and Limitations

• Intersection splitting: buildings that cross block boundaries are split proportionally by area. This is correct for area-based metrics (GSI, FSI) but introduces slight error in distributed building counts.
• Single floor count: each building has one floor count value. Mixed-use buildings with different floor counts per part should be split before processing.
• Block geometry: the tool assumes blocks are non-overlapping polygons. Overlapping or nested blocks produce double-counted area.
• CRS requirement: all area computations use the CRS of the blocks layer, which must be projected with metric units.

2. Mathematical Formulation

Let $B = \{b_1, \ldots, b_N\}$ index a set of building footprint polygons, each with known floor count $n_i$. Let $A_k$ be the area of block (analysis unit) $k$. Let $A_{i,k}^{int} = \text{Area}(b_i \cap \text{block}_k)$ be the intersection area of building $i$ with block $k$. The Spacematrix indicators for block $k$ are:

The Spacematrix class label $C_k$ is determined by discretising GSI and L:

where $f(\text{GSI}) = \text{"compact"}$ if $\text{GSI} \geq 0.35$, $\text{"moderate"}$ if $0.15 \leq \text{GSI} < 0.35$, and $\text{"spacious"}$ if $\text{GSI} < 0.15$.

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Benchmark Typologies

5.2 Reading the Spacematrix Diagram

Plot FSI versus GSI for all blocks in the study area. The arrangement of points reveals:

• Clustering along a ray from the origin: uniform height, varying coverage. Indicates a single building typology at different densities.
• Vertical scatter at fixed GSI: varying height on fixed footprints. Typical of areas where zoning fixes coverage but not height.
• Empty quadrants: typologies absent from the fabric. A plan that introduces them represents a morphological departure.
• Points above L = 6 + GSI > 0.35: high-density compact — often the most walkable and infrastructure-efficient typology, but also the most challenged for daylight and open space.

5.3 Cross-References

• Use Morphological Tessellation cells as the BLOCKS input for plot-level Spacematrix without cadastral data.
• Combine with Building Form Metrics: cluster buildings by (compact, elongation, sharedwall), then compute Spacematrix per cluster to quantify the density of each typology.
• Feed OSR into Heat Island Risk Grid context: low OSR + low green fraction = high heat risk from lack of both open space and vegetation.
• Compare proposed plan FSI/GSI pairs against existing fabric benchmarks: a proposal whose (GSI, FSI) lies far outside the existing point cloud requires justification.

5.4 Common Pitfalls

• Zero FSI / zero GSI: blocks with no intersecting building area produce FSI = GSI = 0. OSR = 0/0 is set to 0.0. These blocks are labelled "Unbuilt" regardless of their actual open-space function.
• Including streets in blocks: blocks defined as street-bounded polygons naturally include the street area in the denominator. GSI and FSI will be lower than plot-level values. Use tessellation cells for plot-level equivalents.
• Floor count field empty or invalid: values that fail to parse as float silently fall back to DEFAULT_LEVELS. A building with 10 storeys recorded as text "10F" will be treated as 2-storey. Verify the field type before running.

6. Symbolic Representation

Recommended QGIS styling:

• smx_class: Categorised, 10 classes. Use a diverging colour scheme: blues for spacious, greens for moderate, oranges/reds for compact. "Unbuilt" in light grey with 50% transparency.
• fsi: Graduated, 5 classes (Quantile), light yellow (low density) to dark red (high density). Useful as a standalone density map.
• gsi: Graduated, 5 classes, light green (low coverage) to dark brown (high coverage). Reveals the footprint of built form independent of height.
• Spacematrix diagram: Use QGIS Data Plotly or export to Python for a GSI vs FSI scatter with L isolines.

7. Literature

✓ Pont, M.B. & Haupt, P. (2023). Spacematrix: Space, Density and Urban Form (Revised ed.). TU Delft OPEN Publishing. DOI: 10.59490/mg.38

✓ Berghauser Pont, M. & Haupt, P. (2010). Spacematrix: Space, Density and Urban Form. NAi Publishers, Rotterdam. ISBN: 978-9056627423.

✓ Berghauser Pont, M. & Haupt, P. (2007). "The relation between urban form and density." Urban Morphology, 11(1), 62–65.

✓ Dovey, K. & Pafka, E. (2014). "The urban density assemblage: Modelling multiple measures." Urban Design International, 19(1), 66–76. DOI: 10.1057/udi.2013.13

✓ Boyko, C.T. & Cooper, R. (2011). "Clarifying and re-conceptualising density." Progress in Planning, 76(1), 1–61. DOI: 10.1016/j.progress.2011.07.001

✓ Fleischmann, M. (2019). "momepy: Urban Morphology Measuring Toolkit." Journal of Open Source Software, 4(43), 1807. DOI: 10.21105/joss.01807

Street Network Morphology

Processing ID: planx:streetnetworkmorphology

1. Theoretical Background

1.1 Academic Lineage

Street network morphology quantifies the structural properties of the street graph — bearing orientations, connectivity, and node typology — in a single analytical pass. The intellectual foundation draws from two traditions. First, graph theory provides the meshedness indices ($\alpha$, $\beta$, $\gamma$) developed by Kansky (1963) for transport network analysis and refined for planar graphs. These indices answer the question: how close is this network to being maximally connected, given its number of nodes? Second, Boeing (2019) introduced orientation entropy and orientation order as a systematic method to quantify how "grid-like" a street network is, using information theory: entropy measures the diversity of street bearings, and order normalises this against the theoretical limits of a perfect four-direction grid ($H_g = \ln 4$) and a completely uniform distribution ($H_{max} = \ln 36$ for 36 directional bins).

1.2 Methodology

Street bearings are computed as the compass angle of each edge's start-to-end vector, made bidirectional ($\theta$ and $\theta + 180^\circ$) because streets are undirected for morphological purposes. The bidirectional bearings are binned into 36 sectors of $10^\circ$ each, centred on $0^\circ$ (North). Boeing weights each bearing by its edge length, so long arterial segments contribute more to the orientation profile than short cul-de-sac stubs. The length-weighted histogram is converted to a probability distribution $p_b$, and Shannon entropy is computed. The orientation order $\phi$ normalises this entropy to $[0, 1]$: $\phi = 1$ for a perfect orthogonal grid (all edges in exactly 4 directions), $\phi \approx 0$ for a network whose bearings are uniformly distributed (random or organic).

Meshedness is measured by three classic planar-graph ratios. $\alpha$ (alpha index) measures the ratio of actual to maximum possible cycles (circuitry): an $\alpha$ of 0 means a tree (no cycles), while $\alpha$ approaching 1 means a maximally circuited planar network. $\beta$ (beta index) is edges per node — values below 1 indicate disconnected components, values near 2 indicate a fully connected planar grid. $\gamma$ (gamma index) measures the ratio of actual to maximum possible edges in a planar graph.

1.3 Use Cases and Limitations

• Neighbourhood comparison: profile different districts and compare their morphological signatures — a high-$\phi$, high-$\alpha$ district is gridded and well-connected; a low-$\phi$, low-$\alpha$ district is organic and tree-like.
• Plan tracking: run on each iteration of a street layout to trend $\alpha$ and intersection density — objective evidence that connectivity is improving or degrading.
• Data quality: more than one connected component = the network is disconnected. Run Prepare Network first to fix topology before morphological analysis.
• Limitations: indices are highly scale-dependent — comparing a 1 km² neighbourhood to a 100 km² city requires normalisation by area. The orientation order is sensitive to the bin count; 36 bins is standard for degree-scale resolution. Curved streets approximated as single line segments lose intermediate bearing information; densify the network first for organic street patterns.

2. Mathematical Formulation

Let $G = (V, E)$ be a planar graph representing the street network, with $n = |V|$ nodes and $e = |E|$ edges. Let $p$ be the number of connected components of $G$. Edge $j$ has length $\ell_j$ and bidirectional bearing $\theta_j \in [0, 360)$.

where $A_{hull}$ is the area (in km²) of the convex hull of all network nodes, used as the denominator for intersection density. Connected components are identified via depth-first search on the adjacency representation. $\alpha$ is clamped to $[0, \infty)$ and $\gamma$ to $[0, \infty)$; negative values (possible when $n$ is very small) are set to 0.

3. Parameters

4. Output Description

4.1 Junction Layer (NODES)

4.2 Summary Table (SUMMARY)

5. Interpretation Guide

5.1 Benchmark Values

5.2 Spatial Patterns

• $\phi$ jump at district boundary: two planning eras meeting. The boundary itself may be a morphological seam — a ring road, railway, or institutional barrier.
• Cul-de-sac clusters + high $\phi$: planned suburban "loops and lollipops" — gridded at the collector scale, dendritic at the local scale. The high $\phi$ comes from the collector grid; the cul-de-sac ratio reveals the local structure.
• $\alpha$ < 0.05 + $\phi$ < 0.15: unplanned or topographically constrained fabric. Could be informal settlement, steep terrain, or pre-automobile organic growth. Not necessarily bad — historic organic fabric often has high pedestrian permeability despite low vehicle-network meshedness.

5.3 Cross-References

• Combine with Network Centrality: a well-meshed network ($\alpha$ > 0.2) with low betweenness centralisation distributes traffic evenly; a tree-like network concentrates it on a few arterials.
• Feed avg_segment_length_m into walkability assessment: segments > 200 m indicate blocks too large for pedestrian permeability, regardless of network connectivity.
• Compare orientation order with Building Form Metrics orient_deg distribution: aligned peaks = street-parallel buildings; offset peaks = buildings ignoring the grid (post-war estates).

5.4 Common Pitfalls

• Disconnected network: multiple components ($p$ > 1) usually indicates dangling segments or topological gaps. Run Prepare Network first. A single-component network is required for meaningful $\alpha$ and $\gamma$.
• Curvilinear streets as single edges: a curved crescent entered as one line produces a single bearing, understating orientation diversity. Densify the network if $\phi$ seems implausibly high for known organic fabric.
• Node degree 2 dominance: if most nodes are "continuation," the network has been digitised with breaks at every vertex. Simplifying or dissolving redundant nodes will sharpen the cul-de-sac/intersection classification.

6. Symbolic Representation

Recommended QGIS styling:

• Junction layer: Categorised by node_type: cul-de-sac = red circle (size 3), continuation = grey circle (size 2, 50% transparent), intersection = blue circle (size 4). Intersection density becomes visible at small scale; cul-de-sac clusters at large scale.
• Bearings polar histogram: use the QGIS "Diagram" overlay on the network layer with a pie chart showing edge bearing per segment, or export bearing data to Python for a rose diagram (length-weighted).
• Summary table: display as an attribute table in the layout; annotate each value with its benchmark range for the reader.

7. Literature

✓ Boeing, G. (2019). "Urban spatial order: street network orientation, configuration, and entropy." Applied Network Science, 4(1), 67. DOI: 10.1007/s41109-019-0189-1

✓ Marshall, S. (2004). Streets and Patterns. Routledge. DOI: 10.4324/9780203589397

✓ Kansky, K.J. (1963). "Structure of transportation networks." University of Chicago, Department of Geography, Research Paper No. 84.

✓ Porta, S., Crucitti, P., & Latora, V. (2006). "The Network Analysis of Urban Streets: A Primal Approach." Environment and Planning B, 33(5), 705–725. DOI: 10.1068/b32045

✓ Southworth, M. & Ben-Joseph, E. (2003). Streets and the Shaping of Towns and Cities. Island Press. ISBN: 978-1559639163.

4. Accessibility

Multi-Amenity Access Score (15-Minute City)

Processing ID: planx:multiamentiyaccess

1. Theoretical Background

1.1 Academic Lineage

The 15-minute city concept, popularised by Moreno et al. (2021) but with roots in Perry's (1929) "neighbourhood unit" and Doxiadis's (1968) "human community" scale, proposes that all daily needs — work, food, health, education, leisure, and culture — should be reachable within a 15-minute walk or cycle from home. The concept entered mainstream planning discourse during the COVID-19 pandemic, when restricted mobility revealed how unequally distributed local amenities are. This algorithm provides the quantitative indicator behind the concept: a composite score that measures, for every residential location, how many amenity categories are within walking distance on the real street network.

1.2 Methodology

The algorithm runs one multi-source Dijkstra shortest-path search per amenity category. All amenity points in a category are treated as source nodes with zero initial distance; the algorithm propagates outward on the street network, recording the shortest path distance from any amenity in that category to every network node. This is more efficient than running one-to-one Dijkstra for every origin-amenity pair and captures the "nearest facility of type X" semantics exactly. Travel time is computed as network distance divided by walking speed (default 4.8 km/h = 80 m/min, the conventional adult walking speed from transportation engineering). The composite score for each origin is the percentage of amenity categories whose nearest representative is within the time threshold.

1.3 The Composite Score

The score is intentionally simple: it counts categories, not amenities within categories. A location near one supermarket scores the same as a location near ten supermarkets for the "shops" category. This conservative design means the score measures minimum service diversity — the presence of each service type — rather than service abundance or quality. A score of 100 means every defined category has at least one representative within the threshold; it says nothing about capacity, quality, or choice. To capture abundance, run the tool separately with a shorter threshold or complement with the Facility Adequacy algorithm.

1.4 Key Assumptions and Limitations

• Network-based only: access is measured on the street network. Pedestrian paths, parks, and informal routes not in the network are invisible to the algorithm.
• Nearest amenity of each category: the tool finds the minimum travel time to any amenity in a category. It does not allocate demand to capacity — for that, use Facility Adequacy.
• Snapping tolerance: origins and amenities are snapped to the nearest network node. If an origin is 200 m from the nearest network edge, its travel times will be overestimated by that approach distance.
• Edge cost = length: all edges are assumed walkable at uniform speed. The tool does not model pedestrian crossing delays, gradient, footpath quality, or safety.
• 2x threshold reporting limit: times beyond double the threshold are reported as -1 (unreachable) to bound the Dijkstra search radius.

2. Mathematical Formulation

Let $\mathcal{C} = \{C_1, \ldots, C_K\}$ be the set of amenity categories, each with a point layer of amenity locations. Let $G = (V, E)$ be the street network graph with edge lengths as costs, and let $v_{walk} = 4.8$ km/h be the walking speed. The distance-to-time conversion is:

For category $C_k$, let $S_k \subset V$ be the set of network nodes nearest to amenity locations in $C_k$. A multi-source Dijkstra from $S_k$ yields the shortest-path distance from any node $v \in V$ to the nearest amenity of category $k$:

For origin $o$ with nearest network node $v_o$, the travel time to the nearest amenity of category $k$ is:

The number of categories reachable within threshold $T$ (default 15 minutes) and the composite score are:

The population-weighted mean score, when a population field is provided:

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Score Benchmarks

• Score = 100: complete 15-minute neighbourhood — every defined amenity category has at least one representative within the threshold. These locations are walkable for all daily needs.
• Score 60–80: liveable but incomplete. Identify the specific missing categories from the t_* fields — the shortfall is a service gap, not a generalised "low access."
• Score 20–40: heavily car-dependent. Residents cannot walk to most daily services. Check whether the missing categories are far (all t_* > 2T) or just beyond threshold (one or two at 16-18 min).
• Score = 0: no amenity of any category within 2x threshold. These locations are effectively unserviced by walking.

5.2 Diagnosing the Cause

• One category far everywhere: a systemic service gap (e.g. no clinics in the study area). The fix is a new facility, not a new street.
• All categories slightly over threshold (16–20 min): a network detour problem — origins are separated from amenities by barriers (highways, railways, water) that the network must route around. Check for missing pedestrian links.
• Sharp boundary in score: a physical or administrative barrier — a motorway, railway, or district boundary that the street network does not cross. These are the highest-priority locations for new pedestrian bridges or crossings.

5.3 Cross-References

• Feed the output into Accessibility Equity to test whether low scores concentrate in vulnerable population groups — the 15-minute city score identifies the gap; equity analysis identifies who lives in it.
• Combine with Walking Slope to add gradient realism: filter out origins whose paths exceed a slope threshold.
• Use with Facility Adequacy: a category may be within 15 minutes but overloaded. Access score + adequacy = complete service assessment.
• Test a proposed facility site by adding it as a new point in the relevant amenity layer and rerunning: the delta in score per origin quantifies the benefit.

5.4 Common Pitfalls

• Too few categories: with only 2 categories, score jumps in 50-point increments, losing discrimination. Use at least 5 categories for meaningful scoring.
• Network disconnected from origins: origins far from network edges snap to the nearest node, but the straight-line approach distance is not walked. Check that all origins are within ~50 m of a network edge.
• Walking speed mismatch: 4.8 km/h assumes unimpeded adult walking. For elderly accessibility assessment, use 3.6 km/h. For cycling access, a separate bicycle network analysis is needed.

6. Symbolic Representation

Recommended QGIS styling:

• score: Graduated, 6 classes: 0 (dark red), 1–39 (red), 40–59 (orange), 60–79 (yellow), 80–99 (light green), 100 (dark green). This maps directly to the car-dependent / liveable / complete framework.
• n_reach: Categorised, one colour per integer 0 through K. Useful as an ordinal complement to the continuous score.
• Per-category minutes: Graduated, 5 classes (0-T, T-2T, over 2T), from green through yellow to grey (-1). Shows which specific service is missing where.
• Population-weighted map: size symbols by population, colour by score. The resulting map directly shows where the most people experience low access.

7. Literature

✓ Moreno, C., Allam, Z., Chabaud, D., Gall, C., & Pratlong, F. (2021). "Introducing the '15-Minute City': Sustainability, Resilience and Place Identity in Future Post-Pandemic Cities." Smart Cities, 4(1), 93–111. DOI: 10.3390/smartcities4010006

✓ Handy, S.L. & Niemeier, D.A. (1997). "Measuring Accessibility: An Exploration of Issues and Alternatives." Environment and Planning A, 29(7), 1175–1194. DOI: 10.1068/a291175

✓ Vale, D. & Lopes, A.S. (2023). "Accessibility inequality across Europe: a comparison of 15-minute pedestrian accessibility in cities with 100,000 or more inhabitants." npj Urban Sustainability, 3, 55. DOI: 10.1038/s42949-023-00133-w

✓ Perry, C.A. (1929). "The Neighborhood Unit." In: Regional Survey of New York and Its Environs, Vol. 7, pp. 22–140. Regional Plan of New York and Its Environs.

✓ Geurs, K.T. & van Wee, B. (2004). "Accessibility evaluation of land-use and transport strategies: review and research directions." Journal of Transport Geography, 12(2), 127–140. DOI: 10.1016/j.jtrangeo.2003.10.005

✓ Talen, E. & Anselin, L. (1998). "Assessing Spatial Equity: An Evaluation of Measures of Accessibility to Public Playgrounds." Environment and Planning A, 30(4), 595–613. DOI: 10.1068/a300595

✓ Ewing, R. & Cervero, R. (2010). "Travel and the Built Environment: A Meta-Analysis." Journal of the American Planning Association, 76(3), 265–294. DOI: 10.1080/01944361003766766

5. Microclimate

Ten screening-quality environmental tools powered by an embedded NOAA solar position model (±0.5° accuracy) and UMEP-style array-shifting shadow casts. These are screening tools, not regulatory compliance models.

Shadow Casting (DSM)

Processing ID: planx:shadowcasting

1. Theoretical Background

1.1 Academic Lineage

Shadow casting from digital surface models (DSMs) is the computational core of urban solar-access analysis. The method implemented here follows Ratti & Richens (1999), who demonstrated that standard image-processing techniques — specifically iterative array shifting — could compute shadow patterns from raster DSMs orders of magnitude faster than ray-tracing, making city-scale shadow studies feasible on desktop computers. This approach was adopted by the Urban Multi-scale Environmental Predictor (UMEP) plugin (Lindberg et al., 2018), which remains the most widely used urban climate tool in QGIS. The solar position is computed using the NOAA simplified algorithm (Reda & Andreas, 2004), which achieves accuracy well under 0.5 degrees for the years 1900–2100 — more than sufficient for urban shadow studies where building height uncertainty is typically a larger error source.

1.2 The Array-Shifting Method

The algorithm works on the principle that a DSM cell $(x, y)$ is in shadow if any cell along the line of sight toward the sun, when projected forward, stands higher than the ground at $(x, y)$. Operationally, the DSM array is shifted toward the sun in discrete pixel steps. At step $i$, the shifted DSM is lowered by $i \cdot \Delta s \cdot \tan\alpha$, where $\Delta s$ is pixel size and $\alpha$ is solar altitude. If the lowered shifted surface at any step exceeds the original DSM at $(x, y)$, that cell is flagged as shadowed. The search radius is capped at $\min(\text{relief}/\tan\alpha,\; \text{raster\_diagonal})$ — beyond this distance, terrain features cannot cast a shadow on the cell because the ground itself intercepts the ray.

1.3 Use Cases and Limitations

• Rights-to-light: a single run at Dec 21 noon answers whether a proposed building casts shadow on a specific garden or window at the legally relevant moment.
• Public space audit: batch multiple hours to map shaded/sunlit plazas, playgrounds, and bus stops through the day.
• Before/after differencing: run on existing DSM, run on proposed DSM, subtract — the non-zero cells show exactly which terrain the new massing shadows.
• Limitations: (a) binary shadow/no-shadow; penumbra and diffuse light are not modelled; (b) DSM must include building heights — a DTM (bare earth) produces no building shadows; (c) the method assumes a flat ground between DSM cells — on very steep terrain with large pixels, shadow boundary accuracy degrades; (d) at solar altitudes below ~3°, the search radius becomes very large and the computation slow.

2. Mathematical Formulation

Let $\mathbf{D} \in \mathbb{R}^{H \times W}$ be the DSM array with pixel size $\Delta s$ (metres). Let $\alpha$ be the solar altitude (degrees above horizon) and $A$ the solar azimuth (degrees clockwise from north, measured as compass bearing — N = 0, E = 90, S = 180). The unit vector toward the sun in array coordinates is:

The maximum search distance (in pixel steps) is:

At each step $i = 1, \ldots, i_{max}$, the shifted and lowered DSM is:

The shadow mask $\mathbf{S}$ is the Boolean array where any shifted surface exceeds the original:

NaN cells in the DSM are excluded from the shadow computation. If $\alpha \leq 0$ (sun below horizon), all cells are flagged as shadow.

3. Parameters

4. Output Description

The log reports ShadowedShare — the fraction of valid DSM cells in shadow. This single number characterises a time-of-day: 0.15 at noon means 15% of the scene is shadowed; 0.85 near sunset means most of the scene is in shadow.

5. Interpretation Guide

5.1 Critical Planning Dates

• December 21 (winter solstice): lowest sun, longest shadows. The standard date for rights-to-light assessment. The 2-hour mid-day window (e.g. 11:00–13:00) is the minimum solar access period in many regulations.
• March 20 / September 22 (equinoxes): typical conditions. Used for general solar-access planning and daylight factor proxies.
• June 21 (summer solstice): highest sun, shortest shadows. For heat studies, shadow here is a cooling asset — identify the spaces that lose all shade on the hottest day.

5.2 Before/After Differencing

Run on existing DSM (baseline), run on proposed DSM (scenario). Subtract: cells where baseline=0 and scenario=1 are the NEW shadow cast by the proposal. These cells identify affected properties, gardens, and public spaces. The affected area in m² is the key exhibit for planning objections or approvals.

5.3 Cross-References

• Batch run with Sun Hours: shadow casting handles one instant; Sun Hours integrates the full day.
• Feed shadow patterns into Solar Irradiation which adds the energy dimension: a shadowed cell at 15:00 loses more energy in summer than in winter because beam irradiance is higher.
• Overlay Dec-21 noon shadow on building footprints: buildings whose entire roof is shadowed at winter solstice are poor candidates for rooftop PV.

5.4 Common Pitfalls

• Wrong UTC offset: the most common error. 15:00 with offset 0 when the site is actually UTC+3 places the sun at 18:00 local time — three hours late. Always verify the log reports a plausible solar altitude for the stated local time.
• DTM instead of DSM: a bare-earth DTM produces terrain shadows only. Buildings will not cast shadows because their heights are absent from the raster. For urban shadow studies, use a DSM that includes building heights.
• Geographic CRS: the pixel size must be in metres. A DSM in WGS84 (EPSG:4326) where pixel size = 0.00001 degrees produces wildly incorrect shadow lengths.

6. Symbolic Representation

Recommended QGIS styling:

• Binary: 0 = fully transparent, 1 = black at 60% opacity, 255 = no colour. Overlay on the DSM hillshade for immediate readability.
• Before/after difference: -1 (lost sun) = red, 0 (unchanged) = transparent, 1 (new shadow) = dark blue. The red cells demand attention.

7. Literature

✓ Lindberg, F., Grimmond, C.S.B., et al. (2018). "Urban Multi-scale Environmental Predictor (UMEP) — An integrated tool for city-based climate services." Environmental Modelling & Software, 99, 70–87. DOI: 10.1016/j.envsoft.2017.09.020

✓ Reda, I. & Andreas, A. (2004). "Solar position algorithm for solar radiation applications." Solar Energy, 76(5), 577–589. DOI: 10.1016/j.solener.2003.12.003

✓ Ratti, C. & Richens, P. (1999). "Urban Texture Analysis with Image Processing Techniques." In: Augenbroe, G. & Eastman, C. (eds.), Computers in Building, pp. 49–64. Springer. DOI: 10.1007/978-1-4615-5047-1_4

✓ Ratti, C., Di Sabatino, S. & Britter, R. (2006). "Urban texture analysis with image processing techniques: winds and dispersion." Theoretical and Applied Climatology, 84, 77–90. DOI: 10.1007/s00704-005-0146-z

✓ Rich, P.M. (1990). "Characterizing plant canopies with hemispherical photographs." Remote Sensing Reviews, 5(1), 13–29. DOI: 10.1080/02757259009532119

✓ Muneer, T. (2004). Solar Radiation and Daylight Models (2nd ed.). Elsevier. ISBN: 978-0750659741.

Sky View Factor (DSM)

Processing ID: planx:skyviewfactor

1. Theoretical Background

1.1 Academic Lineage

Sky View Factor (SVF) is the fraction of the overlying hemisphere visible from a point on the ground — the single most important geometric control on urban microclimate. Oke (1981) first established the quantitative link between urban canyon geometry and nocturnal cooling rates, showing that SVF reduction from buildings is the primary cause of the urban heat island (UHI) through its effect on longwave radiation trapping. The computational method employed here follows Johnson & Watson (1984), who demonstrated that SVF can be computed from horizon elevation angles at equally spaced azimuths: $\text{SVF} = 1 - \frac{1}{N}\sum \sin^2\beta_i$, where $\beta_i$ is the maximum horizon elevation angle in direction $i$. This formulation avoids integration over the full hemisphere and is numerically identical to the geometric definition of the view factor from a differential planar surface element to the sky.

1.2 Physical Significance

SVF controls two opposing energy fluxes. During the day, high SVF means more solar radiation reaches the surface (heating), but also more longwave radiation escapes to the cold sky (cooling). At night, SVF is purely a cooling control: a surface with SVF = 0.9 radiates longwave energy to a sky at approximately -50 degrees C (effective sky temperature), while a surface with SVF = 0.3 radiates mostly to warm building walls at +20 to +30 degrees C, resulting in net nocturnal heating. This explains the classic observation that street canyons are 2-8 K warmer than nearby open country at night, but may be cooler during the day if deeply shaded.

1.3 Methodology and Key Choices

The algorithm scans the DSM outward from each cell in $N$ equally spaced azimuths (default 16). For each direction, it finds the maximum horizon elevation angle $\beta$ — the steepest angle from horizontal to any obstructing DSM cell along that ray, up to the search radius. The SVF per cell is then computed from the $N$ horizon angles. More directions produce smoother results (16 for screening, 32 for publication, 64 for research). The search radius must be large enough to capture the tallest obstruction that can affect the cell; for a 100 m tower, a radius of at least 100 m is needed. The default 100 m is appropriate for urban blocks; increase for tall-building districts or terrain with significant relief.

1.4 Use Cases and Limitations

• UHI screening: SVF < 0.5 in continuous corridors indicates potential nocturnal heat trapping. Combine with Heat Island Risk Grid for comprehensive screening.
• Daylight availability: SVF correlates with daylight factor — a courtyard with SVF 0.3 receives approximately 30% of the vertical sky component available in an open field.
• Cool roof / green infrastructure targeting: low-SVF streets benefit most from reflective surfaces (cool pavements) because longwave radiation has nowhere to escape.
• Limitations: (a) assumes isotropic sky radiance — in reality, the circumsolar region is brighter; (b) the scan is restricted to a finite radius; obstructions beyond it are invisible; (c) vegetation (tree canopies) must be in the DSM to affect SVF; a bare-earth DSM plus extruded buildings will overestimate SVF in treed streets.

2. Mathematical Formulation

For a cell at position $(r, c)$ in the DSM array with pixel size $\Delta s$, let $N$ be the number of equally spaced azimuth directions (default 16). For direction $d \in \{0, \ldots, N-1\}$, the scan direction is:

The maximum terrain elevation encountered at step $i$ (distance $i \cdot \Delta s$) relative to the cell is:

where $(\Delta r_i, \Delta c_i)$ are the integer row and column offsets at step $i$. The maximum horizon angle in direction $d$ over all steps $i = 1, \ldots, i_{max}$ is:

The sky view factor, using the identity $\sin^2(\arctan t) = t^2/(1+t^2)$, is:

For a perfectly flat plane without obstructions ($\beta_{max}^{(d)} = 0$ for all $d$), SVF = 1.0. For a cell at the foot of an infinitely high wall ($\beta_{max}^{(d)} = 90^\circ$ for half the azimuths), SVF = 0.5. For a cell in a deep symmetric canyon, SVF asymptotically approaches:

where $H$ is building height and $W$ is canyon width. A 20 m deep, 15 m wide canyon has theoretical SVF $\approx$ 0.36.

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Spatial Patterns to Identify

• Continuous low-SVF corridors: linear features with SVF < 0.4 along several blocks. These are systematic nocturnal heat traps — the highest-priority targets for cool-roof, tree-canopy, or albedo interventions.
• SVF gradients: SVF decreasing toward the urban core marks the morphological UHI footprint. The gradient's steepness indicates the rate of rural-to-urban transition; an abrupt cliff signals a hard urban edge (motorway, greenbelt boundary).
• Courtyard SVF: interior courtyard SVF should be ~0.3–0.6 for traditional perimeter blocks. Lower values suggest over-deepening by adjacent tall buildings; zero SVF in a courtyard is a daylight and ventilation failure.
• Street orientation bias: N-S streets in northern latitudes show asymmetric SVF (lower on the southern side of the street, shaded by buildings on the south). This asymmetry governs microclimate more than the mean SVF alone.

5.2 Cross-References

• Combine with Heat Island Risk Grid: low SVF + high built fraction + low green fraction = maximum heat risk. The SVF contribution isolates the geometric (radiation trapping) mechanism from the surface-cover mechanism.
• Feed SVF into Solar Irradiation as the diffuse-light weight: the tool's USE_SVF option multiplies diffuse irradiance by cell SVF, producing more realistic street-level radiation than an isotropic sky assumption.
• Use with Frontal Area Index: low SVF + high $\lambda_f$ (frontal area) = a canyon that both traps radiation and blocks wind — the worst-case combination for summer heat stress.

5.3 Common Pitfalls

• Insufficient search radius: a 100 m search radius cannot see a 200 m tower 150 m away. The computed SVF near tall buildings will be overestimated (too much sky visible). Set radius to at least 2x the tallest building height.
• Coarse directions: 4 or 8 directions produce visible stair-stepping artefacts in the SVF map. Minimum 16 for screening; 32 for any quantitative use.
• DSM without vegetation: tree canopies are obstructions. A DSM from LiDAR that includes vegetation yields lower (more realistic) SVFs than a bare-earth + extruded-buildings DSM.

6. Symbolic Representation

Recommended QGIS styling:

• SVF: Singleband pseudocolour, diverging: 0.0 = deep purple (fully enclosed), 0.3 = dark blue, 0.5 = yellow, 0.7 = light green, 1.0 = white (fully open). The thermal interpretation is intuitive: purple = heat trap, white = cold sink.
• For publication: 10-class equal interval from 0.0 to 1.0. Annotate each bin with its morphological description (canyon, street, open, etc.).

7. Literature

✓ Oke, T.R. (1981). "Canyon geometry and the nocturnal urban heat island: Comparison of scale model and field observations." Journal of Climatology, 1(3), 237–254. DOI: 10.1002/joc.3370010304

✓ Johnson, G.T. & Watson, I.D. (1984). "The Determination of View-Factors in Urban Canyons." Journal of Climate and Applied Meteorology, 23(2), 329–335. DOI: 10.1175/1520-0450(1984)023<0329:TDOVFI>2.0.CO;2

✓ Oke, T.R. (1982). "The energetic basis of the urban heat island." Quarterly Journal of the Royal Meteorological Society, 108(455), 1–24. DOI: 10.1002/qj.49710845502

✓ Stewart, I.D. & Oke, T.R. (2012). "Local Climate Zones for Urban Temperature Studies." Bulletin of the American Meteorological Society, 93(12), 1879–1900. DOI: 10.1175/BAMS-D-11-00019.1

✓ Grimmond, C.S.B., Potter, S.K., Zutter, H.N. & Souch, C. (2001). "Rapid methods to estimate sky-view factors applied to urban areas." International Journal of Climatology, 21(7), 903–913. DOI: 10.1002/joc.659

✓ Hammerle, M., Gal, T., Unger, J. & Matzarakis, A. (2011). "Comparison of models calculating the sky view factor used for urban climate investigations." Theoretical and Applied Climatology, 105, 521–527. DOI: 10.1007/s00704-011-0402-3

Frontal Area Index

Processing ID: planx:frontalareaindex

1. Theoretical Background

1.1 Academic Lineage

Frontal Area Index ($\lambda_f$) and Plan Area Index ($\lambda_p$) are the standard urban roughness parameters introduced by Grimmond & Oke (1999) for characterising the aerodynamic properties of urban surfaces. Grimmond & Oke demonstrated that these two morphological parameters, computed from building footprint and height data, can predict the zero-plane displacement height ($z_d$) and roughness length ($z_0$) — the key parameters in boundary-layer wind models — with accuracy comparable to wind-tunnel measurements. The method has since become the primary morphological input to urban wind and dispersion models, including the operational ADMS-Urban and SIRANE models.

1.2 Physical Meaning

$\lambda_f$ measures the total wind-facing facade area of buildings per unit ground area. For a given wind direction $\theta$ (the compass bearing the wind comes FROM), each building contributes its projected width perpendicular to the wind, multiplied by its height: $F_i = w_{proj,i} \cdot h_i$. Summed over all buildings intersecting a grid cell and normalised by cell area, $\lambda_f$ quantifies how much the built fabric "catches" the wind — a sail-area analogy. $\lambda_p$ is simpler: total building footprint area per unit ground area (coverage). The ratio $\lambda_f / \lambda_p = \bar{h} \cdot \bar{w}_{proj} / \bar{A}_{fp}$ relates the aerodynamic to the geometric footprint of buildings.

1.3 Urban Ventilation Corridors

In urban climate planning, $\lambda_f$ maps are used to identify and protect ventilation corridors — continuous bands of low $\lambda_f$ aligned with the prevailing breeze direction. These corridors channel cooling air from rural surroundings (or large urban parks) into the city core. The operational workflow is: (a) determine the prevailing summer daytime wind direction from local meteorological data; (b) compute $\lambda_f$ with that direction; (c) identify continuous low-$\lambda_f$ paths connecting cool source areas to hot target areas; (d) keep new construction out of these paths in the zoning plan.

1.4 Use Cases and Limitations

• Ventilation corridor mapping: run with prevailing summer breeze direction to locate the airflow paths that keep hot districts cool.
• Urban roughness classification: $\lambda_f$ categorises urban terrain into Davenport roughness classes, from "open" ($\lambda_f$ < 0.1) to "very rough" ($\lambda_f$ > 0.5).
• Wind-damage screening: high $\lambda_f$ cells perpendicular to storm wind direction identify facades at risk of wind loading.
• Limitations: (a) $\lambda_f$ is a grid-cell average — it does not capture street-level channelling or funnelling effects; (b) single wind direction per run — run separately for multiple directions to characterise directional roughness; (c) height data must be per-building (field or default); (d) the method does not account for porosity between buildings — a solid wall and a row of pillars at the same $\lambda_f$ produce completely different flow fields.

2. Mathematical Formulation

Let $\mathcal{B}$ be the set of building footprint polygons, each with height $h_i$ (metres). Let the wind direction be $\theta$ degrees from North (the bearing the wind comes FROM). For building $i$ with exterior ring vertices $(x_j, y_j)$, the projected width perpendicular to the wind is:

The frontal area of building $i$ is:

For a grid cell $c$ with area $A_{cell}$, the intersection share of building $i$ is $s_{i,c} = \text{Area}(b_i \cap c) / \text{Area}(b_i)$. The frontal area index and plan area index for cell $c$ are:

Only cells containing at least one building are emitted (sparse grid output). The roughness class thresholds are:

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Reading the $\lambda_f$ / $\lambda_p$ Relationship

• High $\lambda_p$ + low $\lambda_f$: dense but low (shopping strips, industrial sheds). The wind sees low roughness despite high coverage because building heights are small.
• Low $\lambda_p$ + high $\lambda_f$: porous but tall (tower clusters). The wind encounters tall obstacles at wide spacing — channelling and wake effects dominate. These behave completely differently for ventilation than dense-low fabric.
• Directional variation: run with wind at $0^\circ$ (north), $90^\circ$ (east), and the prevailing direction. Delta $\lambda_f$ between directions reveals directional porosity: a fabric with $\lambda_f$(north)=0.08 and $\lambda_f$(east)=0.35 is permeable to north winds but blocks east winds.

5.2 Ventilation Corridor Detection

• Continuous low-$\lambda_f$ band: $\lambda_f$ < 0.1 for > 500 m in a direction within $\pm 30^\circ$ of the prevailing breeze = a functional ventilation corridor. Protect it from infill development.
• Barrier detection: a line of cells with $\lambda_f$ > 0.3 perpendicular to the breeze = a wind dam. The area downwind of this barrier (further from the wind source) may be a hot spot due to reduced ventilation.

5.3 Cross-References

• Combine with Sky View Factor: low SVF + high $\lambda_f$ identifies canyons that both trap radiation and block wind — dual-mechanism heat stress.
• Use with Heat Island Risk Grid: add $\lambda_f$ as a contextual layer to distinguish radiation-trap UHI from ventilation-trap UHI.
• Run after Building Form Metrics: use orient_deg to check whether building orientations align with or oppose the prevailing breeze.

6. Symbolic Representation

• lambda_f: Graduated, 5 classes (0–0.05, 0.05–0.10, 0.10–0.20, 0.20–0.30, >0.30), blue = open to red = blocked. Wind direction shown as an arrow symbol in the layout legend.
• lambda_p: Graduated, from light green (low coverage) to dark brown (high coverage). Display alongside $\lambda_f$ for the density-vs-roughness comparison.

7. Literature

✓ Grimmond, C.S.B. & Oke, T.R. (1999). "Aerodynamic Properties of Urban Areas Derived from Analysis of Surface Form." Journal of Applied Meteorology, 38(9), 1262–1292. DOI: 10.1175/1520-0450(1999)038<1262:APOUAD>2.0.CO;2

✓ Ratti, C., Di Sabatino, S. & Britter, R. (2006). "Urban texture analysis with image processing techniques: winds and dispersion." Theoretical and Applied Climatology, 84, 77–90. DOI: 10.1007/s00704-005-0146-z

✓ Ng, E., Yuan, C., Chen, L., Ren, C. & Fung, J.C.H. (2011). "Improving the wind environment in high-density cities by understanding urban morphology and surface roughness." Landscape and Urban Planning, 101(1), 59–74. DOI: 10.1016/j.landurbplan.2011.01.004

✓ Macdonald, R.W., Griffiths, R.F. & Hall, D.J. (1998). "An improved method for the estimation of surface roughness of obstacle arrays." Atmospheric Environment, 32(11), 1857–1864. DOI: 10.1016/S1352-2310(97)00403-2

✓ Oke, T.R., Mills, G., Christen, A. & Voogt, J.A. (2017). Urban Climates. Cambridge University Press. DOI: 10.1017/9781139016476

Sun Hours (DSM)

Processing ID: planx:sunhours

1. Theoretical Background

1.1 Academic Lineage

Sun hours — the accumulated duration of direct sunlight at a point over a day — is the fundamental metric for solar-access planning and rights-to-light assessment. The method extends the single-instant shadow casting of Ratti & Richens (1999) into a full-day integration: the DSM is swept at a fixed time interval (default 30 minutes), and for each step where the sun is above the horizon, a shadow mask is cast using the NOAA solar position algorithm and the UMEP array-shifting method. Cells that are sunlit at a given time step accumulate $\Delta t / 60$ hours. The result is a shadow-duration map that previously required batch-running the Shadow Casting tool 24-48 times.

1.2 Regulatory Context

Many jurisdictions specify minimum direct-sun criteria for habitable rooms and open spaces. The British "BRE Site Layout Planning for Daylight and Sunlight" guide recommends that at least one main window wall of a habitable room receive 2 hours of direct sun on March 21. The German DIN 5034 specifies minimum sun duration for playgrounds. The Chinese GB 50180 requires 2 hours on the winter solstice for residential buildings. The tool enables testing any of these by selecting the relevant date and comparing per-cell hours to the threshold.

1.3 Use Cases and Limitations

• Rights-to-light assessment: run on Dec 21 or Mar 21 and overlay the 2-hour contour on building facade cells. Cells below 2 hours identify windows that fail the standard.
• Playground / garden audit: run on the relevant date and identify open spaces with < 4 hours — these need design intervention (reorienting, removing obstructions).
• PV screening: roofs with > 4 hours of winter sun are viable PV candidates before detailed energy modelling.
• Limitations: (a) time step discretisation — a 30-minute step misses shadows shorter than 30 minutes; (b) the result is accumulated hours, not continuous duration — 4 one-hour spells are reported as 4 hours, the same as a single 4-hour spell; (c) the tool reports hours on a horizontal surface — vertical surface (facade) sun hours require a different computation; (d) the NOAA solar position includes refraction, which is correct for the direct-beam shadow boundary.

2. Mathematical Formulation

Let $\mathbf{D}$ be the DSM array with pixel size $\Delta s$. For a given date at latitude $\phi$, the day is swept at $n_{steps} = \lceil 24 \times 60 / \Delta t \rceil$ time steps, where $\Delta t$ is the interval in minutes. At step $k$, the local clock time is $t_k = (k + 0.5) \times 24 / n_{steps}$ hours. The solar altitude $\alpha_k$ and azimuth $A_k$ are computed from the NOAA algorithm at UTC time $t_k - \Delta_{UTC}$:

The shadow mask $\mathbf{S}_k$ is computed for each step with $\alpha_k > 0$. The accumulated sun hours per cell are:

The site's unobstructed potential daylight is the total time the sun would be above the horizon without any building or terrain obstruction:

The ratio $\text{Hours}(r, c) / \text{Daylight}$ expresses the fraction of available sun that actually reaches the cell — a morphology-controlled solar access indicator independent of latitude and date:

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Regulatory Benchmarks

• 2 hours on Dec 21 / Mar 21: the most common habitable room standard (BRE, DIN, GB). Cells with < 2 hours at these dates flag windows that fail the test.
• 4–6 hours on Dec 21 / Mar 21: typical playground, schoolyard, and food-garden thresholds.
• Half the open space with 2+ hours: some daylight guidelines phrase requirements at the space level rather than per cell: compute the fraction of open-space cells above the 2-hour threshold.

5.2 Seasonal Comparison

Run on both Dec 21 (winter solstice) and Jun 21 (summer solstice):

• Same cell low in both: permanently shaded — a north-facing courtyard or narrow alley.
• Low in winter, high in summer: a south-facing space shaded by a building to the south in winter (low sun) but exposed in summer (high sun). This is the pattern to avoid — it gives no sun when needed (winter) and too much when unwanted (summer).
• High in winter, lower in summer: the ideal pattern for outdoor comfort — the space gets sun when it is cold and shade when it is hot.

5.3 Cross-References

• Feed winter sun hours into Solar Irradiation screening: roofs with good sun hours are strong candidates for detailed irradiation analysis.
• Use before/after Sun Hours differencing for rights-to-light evidence: the cells that drop below the 2-hour threshold after a proposal are the affected windows.
• Combine with Building Form Metrics: buildings with south-facing long axes (orient_deg near 90 in northern hemisphere) maximise winter sun on their wider facade.

6. Symbolic Representation

• Hours: Graduated, cold (blue/purple, 0-2h) to warm (yellow/white, 8+h). The 2h and 4h contours should be visually dominant.
• $f_{sun}$ (computed): Graduated, 0.0 = dark (fully obstructed) to 1.0 = bright (fully open). Diverging at 0.5 for the half-day transition.

7. Literature

✓ Littlefair, P.J. (2001). "Daylight, sunlight and solar gain in the urban environment." Solar Energy, 70(3), 177–185. DOI: 10.1016/S0038-092X(00)00099-2

✓ Ratti, C. & Richens, P. (1999). "Urban Texture Analysis with Image Processing Techniques." In: Computers in Building, pp. 49–64. Springer. DOI: 10.1007/978-1-4615-5047-1_4

✓ Lindberg, F., Grimmond, C.S.B., et al. (2018). "Urban Multi-scale Environmental Predictor (UMEP)." Environmental Modelling & Software, 99, 70–87. DOI: 10.1016/j.envsoft.2017.09.020

✓ Reda, I. & Andreas, A. (2004). "Solar position algorithm for solar radiation applications." Solar Energy, 76(5), 577–589. DOI: 10.1016/j.solener.2003.12.003

✓ BRE (2011). Site Layout Planning for Daylight and Sunlight: A Guide to Good Practice (BR 209). BRE Press. ISBN: 978-1848061781.

Solar Irradiation (DSM)

Processing ID: planx:solarirradiation

1. Theoretical Background

1.1 Academic Lineage

Solar irradiation — the total radiant energy received per unit area — combines the geometric shadow computation with an atmospheric radiative transfer model. The beam (direct) component follows the ASHRAE clear-sky model (Masters, 2004), an empirical parameterisation widely used in building energy simulation: direct normal irradiance $DNI = A \exp(-k/\sin\beta)$ where the apparent extraterrestrial flux $A$ and optical depth $k$ vary seasonally. The diffuse component is modelled as isotropic ($DHI = C \cdot DNI$), a reasonable first-order assumption for clear-sky screening. Each cell's total irradiation sums beam (only when sunlit) plus diffuse weighted by the cell's sky view factor — a physically justified treatment that correctly reduces diffuse irradiance in street canyons.

1.2 Clear-Sky vs. All-Sky

The tool computes clear-sky irradiation — what the surface would receive under cloudless conditions. This is the correct basis for two screening tasks: (a) ranking roofs and spaces by their relative solar potential, because cloud cover affects all surfaces in a scene roughly equally (the ranking is preserved); (b) establishing an upper bound for PV yield, from which a cloudy-climate correction (typically 0.5–0.7) is applied. For absolute energy estimates, multiply clear-sky values by the local clearness index ($K_T$, the ratio of measured to clear-sky global radiation), available from TMY (Typical Meteorological Year) data or PVGIS.

1.3 Use Cases and Limitations

• PV pre-screening: rank all roof surfaces by daily irradiation on a winter date. The highest-scoring roofs are the PV candidates — feed these into specialised PV tools (PVGIS, SAM) for bankable yield estimates.
• Heat exposure screening: south-facing hardscape cells with high summer irradiation are the surfaces that will radiate stored heat into the evening. Target these for cool pavements or shade sails.
• Limitations: (a) horizontal surface only — the tool does not model tilted or vertical surfaces; (b) no cloud, no albedo from surroundings, no atmospheric aerosol variation beyond the seasonal ASHRAE cycle; (c) the isotropic diffuse model underestimates circumsolar diffuse in hazy conditions; (d) screening quality — rankings are correct, absolute kWh values need site-specific calibration.

2. Mathematical Formulation

The ASHRAE clear-sky model parameters vary with day-of-year $n$:

For solar altitude $\alpha$, the direct normal irradiance, beam horizontal, and diffuse horizontal components are:

At time step $k$, the irradiance contribution to cell $(r, c)$ is:

The daily total irradiation (kWh/m²) and the unobstructed flat-ground reference are:

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Reading Against the Reference

The ratio cell / flat-ground reference is the honest number. It isolates morphological shadowing from atmospheric and seasonal effects. Two sites at different latitudes will have different flat_kWh values; the ratio tells you which site is more obstructed, independent of latitude. A cell at ratio 0.85 in London may produce less absolute kWh than a cell at ratio 0.6 in Cairo — but the London cell is a better PV location relative to its climate.

5.2 Seasonal Strategy

• PV screening: run on Dec 21. Winter is the binding season — if a roof performs well in December, it performs well all year. Summer-only performers are poor PV investments because the energy is produced when demand and prices are low.
• Heat screening: run on Jun 21. The cells with the highest summer kWh are the surfaces that will radiate heat into the evening. Hardscape (asphalt, concrete) in these cells needs shade or cool-surface treatment.

5.3 Cross-References

• Feed top-scoring cells into Annual Solar Potential for year-round validation of PV candidates.
• Before/after irradiation differencing isolates the energy cost of a proposed building: the sum of kWh lost across all affected cells quantifies the solar-access impact in energy terms.
• Combine with Shadow Casting for the complementary question: "which cell is shadowed at a specific time?" (Shadow Casting) vs. "how much energy does each cell receive over the day?" (Solar Irradiation).

6. Symbolic Representation

• kWh/m²: Singleband pseudocolour, warm ramp: blue (low, < 1) through green, yellow, to red (high, > 6). Include the flat_kWh reference as a horizontal line annotation on the legend.
• Ratio to flat (raster calculator): Graduated, 0.0–1.0 in 0.1 steps. Green > 0.8, yellow 0.5–0.8, red < 0.5.

7. Literature

✓ Masters, G.M. (2004). Renewable and Efficient Electric Power Systems. Wiley. DOI: 10.1002/0471668826

✓ Duffie, J.A. & Beckman, W.A. (2013). Solar Engineering of Thermal Processes (4th ed.). Wiley. DOI: 10.1002/9781118671603

✓ Lindberg, F., Grimmond, C.S.B., et al. (2018). "Urban Multi-scale Environmental Predictor (UMEP)." Environmental Modelling & Software, 99, 70–87. DOI: 10.1016/j.envsoft.2017.09.020

✓ Reda, I. & Andreas, A. (2004). "Solar position algorithm for solar radiation applications." Solar Energy, 76(5), 577–589. DOI: 10.1016/j.solener.2003.12.003

✓ Suri, M. & Hofierka, J. (2004). "A New GIS-based Solar Radiation Model and Its Application to Photovoltaic Assessments." Transactions in GIS, 8(2), 175–190. DOI: 10.1111/j.1467-9671.2004.00174.x

✓ Freitas, S., Catita, C., Redweik, P. & Brito, M.C. (2015). "Modelling solar potential in the urban environment: State-of-the-art review." Renewable and Sustainable Energy Reviews, 41, 915–931. DOI: 10.1016/j.rser.2014.08.060

Annual Solar Potential (DSM)

Processing ID: planx:annualsolar

1. Theoretical Background

1.1 Academic Lineage

Annual solar potential — the total clear-sky global irradiation summed over a full year — is the metric that matters for rooftop PV economics, building energy balance, and year-round outdoor thermal comfort. Computing it by shadow-casting all 365 days would be computationally prohibitive for city-scale DSMs. The standard solution, introduced by Klein (1977) and codified in Duffie & Beckman (2013), is the monthly-average-day method: for each month, one representative average day — the day whose solar declination is closest to the monthly mean — is computed with the full shadow-aware beam + SVF-weighted diffuse model, then scaled by the number of days in that month and summed across 12 months. Twelve day-sweeps stand in for 365, reducing computation by a factor of 30 while preserving within about 2% accuracy for annual totals at low-to-moderate latitudes.

1.2 The Klein Representative Days

The recommended average days (Jan 17, Feb 16, Mar 16, Apr 15, May 15, Jun 11, Jul 17, Aug 16, Sep 15, Oct 15, Nov 14, Dec 10) are those for which the daily extraterrestrial radiation on a horizontal surface is closest to the monthly mean. These dates are latitude-independent for practical purposes — the declination variations are symmetric around the solstices. The method is valid for latitudes between 60 degrees S and 60 degrees N; polar latitudes with prolonged darkness or midnight sun require full daily integration.

1.3 Use Cases and Limitations

• Roof-top PV potential mapping: the primary use — rank every roof cell by annual kWh/m²/yr, then filter by usable area and system efficiency for a city-wide PV capacity estimate.
• Solar envelope planning: test proposed massings by comparing annual irradiation on existing roofs before and after — the kWh lost per year quantifies the solar-access impact in economic terms.
• Seasonal comfort design: the optional 12-band monthly raster reveals which months deliver or withhold sun, enabling seasonal shading design (full shade in July, full sun in January).
• Limitations: (a) clear-sky only — no cloud or aerosol variation; (b) horizontal surfaces only; (c) the Klein method's accuracy degrades above 60 degrees latitude; (d) screening quality — rankings are robust, absolute kWh/m²/yr values need local cloud correction.

2. Mathematical Formulation

Let $\text{daily}(r, c; y, m, d)$ be the clear-sky daily irradiation at cell $(r, c)$ for year $y$, month $m$, and day $d$, computed via the full shadow-aware + SVF-weighted model. Let $d_m^*$ be the Klein representative day for month $m$, and $N_m$ the number of days in month $m$:

The flat-ground annual reference (unobstructed, clear-sky) is:

The morphology efficiency — the share of available radiation that reaches the cell, isolating urban-form effects from climate — is:

The scene mean per month, used to identify the peak month for heat exposure:

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Reading Morphology Efficiency

• $\eta_{morph}$ > 0.9: practically unobstructed. The cell receives >90% of what a flat open field would. These are the premium PV locations — rooftops, open plazas.
• $\eta_{morph}$ 0.7–0.9: mildly obstructed. Modest shadow losses from distant buildings or terrain. PV is viable but with reduced yield.
• $\eta_{morph}$ 0.5–0.7: significantly obstructed. Surrounding massing costs 30–50% of potential yield. PV likely uneconomic without building-scale analysis.
• $\eta_{morph}$ < 0.5: heavily obstructed. Street canyons, north-facing slopes, or deep courtyards. Solar access is compromised year-round.

5.2 PV Estimation Workflow

1. Rank cells by annual kWh/m²/yr. Extract the top 20%.
2. Filter by usable roof area (minimum contiguous patch size, e.g. 10 m²).
3. Multiply by system factor $\eta_{sys} \approx 0.75$–$0.85$ (accounts for inverter, wiring, temperature, soiling losses).
4. Multiply by local cloud correction $K_T \approx 0.5$–$0.7$ (the ratio of measured GHI to clear-sky GHI, from TMY data or PVGIS).
5. Result: approximate annual AC energy per cell = $\text{Annual} \times \eta_{sys} \times K_T$ (kWh/m²/yr).

5.3 Seasonal Diagnostics (Monthly Bands)

• Peak month in summer: expected for most locations. If peak is Sept–Oct, the cell may be on an east-facing surface (morning sun year-round, no summer building shadow).
• Deep winter dip (Dec–Jan at 10–20% of peak): the cell loses most winter sun to building or terrain shadow. This is typical of ground-level street canyons.
• Flat monthly profile (all months within 30% of mean): the cell is on an unobstructed roof — seasonal variation is purely astronomical.

5.4 Cross-References

• Before/after annual differencing quantifies the permanent energy cost of a proposed building — the key evidence for solar-rights objections.
• Feed top cells into detailed PV simulation (PVGIS, SAM, PVsyst) with the specific panel tilt, azimuth, and local weather.
• Use the monthly bands with Sun Hours annual comparison: Sun Hours maps time, Annual Solar maps energy — the ratio reveals if a location's shadow hours coincide with the highest or lowest irradiance periods.

6. Symbolic Representation

• Annual kWh/m²/yr: Singleband pseudocolour, warm ramp: blue (< 500) through green, yellow, to red (> 1500). Adjust breakpoints to the site's flat_annual reference.
• Monthly 12-band: Use the Temporal Controller or a multi-band renderer. A common layout: 3x4 grid of monthly maps in the print layout, each with the same colour ramp, revealing the seasonal migration of the solar-access pattern.
• $\eta_{morph}$ (raster calculator): Graduated, 10 classes from 0.0 to 1.0. Dark blue (< 0.5) to bright yellow (> 0.9).

7. Literature

✓ Klein, S.A. (1977). "Calculation of monthly average insolation on tilted surfaces." Solar Energy, 19(4), 325–329. DOI: 10.1016/0038-092X(77)90001-9

✓ Duffie, J.A. & Beckman, W.A. (2013). Solar Engineering of Thermal Processes (4th ed.). Wiley. DOI: 10.1002/9781118671603

✓ Masters, G.M. (2004). Renewable and Efficient Electric Power Systems. Wiley. DOI: 10.1002/0471668826

✓ Lindberg, F., Grimmond, C.S.B., et al. (2018). "Urban Multi-scale Environmental Predictor (UMEP)." Environmental Modelling & Software, 99, 70–87. DOI: 10.1016/j.envsoft.2017.09.020

✓ Freitas, S., Catita, C., Redweik, P. & Brito, M.C. (2015). "Modelling solar potential in the urban environment: State-of-the-art review." Renewable and Sustainable Energy Reviews, 41, 915–931. DOI: 10.1016/j.rser.2014.08.060

✓ Reda, I. & Andreas, A. (2004). "Solar position algorithm for solar radiation applications." Solar Energy, 76(5), 577–589. DOI: 10.1016/j.solener.2003.12.003

✓ Suri, M. & Hofierka, J. (2004). "A New GIS-based Solar Radiation Model and Its Application to Photovoltaic Assessments." Transactions in GIS, 8(2), 175–190. DOI: 10.1111/j.1467-9671.2004.00174.x

Heat Island Risk Grid

Processing ID: planx:heatriskgrid

1. Theoretical Background

1.1 Academic Lineage

The Urban Heat Island (UHI) effect — the observation that urban areas are 2–12 K warmer than their rural surroundings — was first systematically documented by Luke Howard (1833) and given its energetic explanation by Oke (1982), who showed that canyon geometry (SVF reduction) is the primary nocturnal mechanism and surface-cover properties (albedo, thermal admittance, vegetation moisture) dominate daytime UHI intensity. Stewart & Oke (2012) formalised this into the Local Climate Zone (LCZ) classification, which characterises urban landscapes by built fraction, building height, pervious surface fraction, and thermal admittance — the same variables the Heat Island Risk Grid computes per cell. The tool implements a weighted additive model of these four components, producing a fixed-scale 0–100 risk score directly comparable between scenarios and study areas.

1.2 The Fixed-Scale Design

Unlike percentile-based or data-driven normalisations that stretch the score to fit the data range, the fixed-scale approach anchors the endpoints to the theoretical extremes given the user's chosen weights: fully vegetated (or water-covered) land at zero building height maps to 0; fully built land at the reference height maps to 100. This means re-running after a planning intervention — adding a park, increasing building heights, introducing water features — yields directly comparable numbers. "The park drops 14 cells from Very High to Moderate" is a verifiable claim because the thresholds are fixed, not re-stretched to the new data.

1.3 Component Mechanisms

• Built fraction ($b$): the primary daytime UHI driver through low albedo, high thermal mass, and anthropogenic heat release. Weight default: 0.4.
• Building height ($h/h_{ref}$): the primary nocturnal UHI driver through longwave radiation trapping (interacts with SVF). Capped at 1.0 (height beyond $h_{ref}$ does not increase risk further because tall buildings also cast shade). Weight default: 0.2.
• Green fraction ($g$): the primary cooling mechanism through evapotranspiration and shading. Weight default: 0.3 (the largest negative weight, reflecting empirical evidence that vegetation is the most effective UHI mitigation).
• Water fraction ($w$): additional evaporative cooling. Weight default: 0.1 (secondary because water bodies are usually mapped separately and cannot be "added" as easily as vegetation).

1.4 Use Cases and Limitations

• Plan scenario comparison: run on existing and proposed land cover to quantify which cells improve or deteriorate.
• Mitigation targeting: "Very High" risk cells that overlap with vulnerable populations (elderly, children) are priority cooling intervention zones.
• Limitations: (a) score is relative index, not temperature (K or °C); (b) does not model advection — a cool cell downwind of a hot district will be warmer than its components suggest; (c) does not include anthropogenic heat (traffic, HVAC) which can be 10–50 W/m² in dense districts; (d) results are per cell — street-level microclimates within a cell are averaged.

2. Mathematical Formulation

For a grid cell $c$, let $b_c$, $g_c$, $w_c$ be the built, green, and water area fractions ($\in [0, 1]$), and $h_c$ the area-weighted mean building height (metres). Let $h_{ref}$ be the reference height for full height effect (default 20 m), and $w_{built}$, $w_{height}$, $w_{green}$, $w_{water}$ the user-defined component weights:

The theoretical range of raw(c) is $[-\max(w_{green}, w_{water}),\; w_{built} + w_{height}]$, because a cell cannot simultaneously be fully green and fully water (they are disjoint surface covers). The normalised risk score is:

where $\text{raw}_{min} = -\max(w_{green}, w_{water})$ and $\text{raw}_{max} = w_{built} + w_{height}$. With default weights (0.4, 0.2, 0.3, 0.1):

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Reading Component Fractions for Remediation

• High built + low green + low height: dense low-rise with no vegetation. The remedy is depaving and planting — tree trenches, pocket parks, green roofs. This is the most common Very High pattern in Mediterranean and Middle Eastern cities.
• High built + high height + low green: dense high-rise canyon. The remedy combines shade structures (awnings, arcades) with albedo treatment (cool roofs, cool pavements). Vegetation alone cannot fix a deep canyon because tree canopies are limited in height; reflected shortwave from walls also contributes.
• Moderate built + moderate green: mixed fabric. Risk may come from the neighbouring district via advection, not from within-cell components. Check spatial context — one "Moderate" cell in a sea of "Very High" will be warmer than its components suggest.

5.2 Scenario Comparison

Because the scale is fixed, re-running after a mitigation intervention produces directly comparable numbers. The sentence "adding a 1 ha park drops 14 cells from Very High to Moderate" is legitimate because the thresholds (25, 50, 75) are anchored, not data-driven. To quantify impact: (a) run baseline; (b) edit the green/water/height layers; (c) re-run; (d) subtract uhi_risk between scenarios; (e) report the number of cells crossing class boundaries.

5.3 Cross-References

• Combine with Sky View Factor: low SVF + Very High risk = the worst-case combination — radiation trapped AND built/impervious. These are the top-priority cooling intervention targets.
• Overlay Very High cells with Accessibility Equity demographic data: if vulnerable populations concentrate in Very High cells, the UHI becomes an environmental justice issue.
• Use Frontal Area Index to check whether Very High cells also sit in wind-blocked zones: dual-mechanism heat stress (radiation trap + ventilation trap) requires both cool surfaces AND wind corridor protection.

6. Symbolic Representation

• uhi_risk: Graduated, 4 classes keyed to risk thresholds: green (< 25, Low), yellow (25–50, Moderate), orange (50–75, High), red (>= 75, Very High).
• Risk components bar chart: in the print layout, add a bar chart widget per cell showing the four component fractions in stacked bars (built = red, height = dark red, green = green, water = blue).
• Scenario delta: for before/after comparison, use a diverging red-blue ramp: cells that improved (lower risk) = blue; worsened = red; unchanged = grey.

7. Literature

✓ Oke, T.R. (1982). "The energetic basis of the urban heat island." Quarterly Journal of the Royal Meteorological Society, 108(455), 1–24. DOI: 10.1002/qj.49710845502

✓ Stewart, I.D. & Oke, T.R. (2012). "Local Climate Zones for Urban Temperature Studies." Bulletin of the American Meteorological Society, 93(12), 1879–1900. DOI: 10.1175/BAMS-D-11-00019.1

✓ Oke, T.R., Mills, G., Christen, A. & Voogt, J.A. (2017). Urban Climates. Cambridge University Press. DOI: 10.1017/9781139016476

✓ Bowler, D.E., Buyung-Ali, L., Knight, T.M. & Pullin, A.S. (2010). "Urban greening to cool towns and cities: A systematic review of the empirical evidence." Landscape and Urban Planning, 97(3), 147–155. DOI: 10.1016/j.landurbplan.2010.05.006

✓ Santamouris, M. (2014). "Cooling the cities — A review of reflective and green roof mitigation technologies to fight heat island and improve comfort in urban environments." Solar Energy, 103, 682–703. DOI: 10.1016/j.solener.2012.07.003

Road Noise Screening

Processing ID: planx:noisescreening

1. Theoretical Background

1.1 Academic Lineage

Road traffic noise is the most widespread environmental stressor in urban areas, with the World Health Organization (2018) estimating that at least 100 million Europeans are exposed to levels above the 55 dB(A) L_den threshold for annoyance and sleep disturbance. The Road Noise Screening tool implements a simplified version of the RLS-90 (Richtlinien fur den Larmschutz an Strassen, 1990) emission model, the German regulatory standard that underpins EU strategic noise mapping. The emission formula $L_{m,E} = 37.3 + 10\lg[M(1 + 0.082p)]$ at the 25 m reference distance is the RLS-90 mean level for light vehicles at 100 km/h, adapted to include heavy-vehicle correction. Propagation is free-field geometric spreading ($-20\lg r$, the point-source equivalent of a line-source after calibration), with a single fixed insertion loss where a building blocks the line of sight. This is a screening model — it correctly ranks exposure and locates hotspots but omits ground effect, air absorption, meteorology, and reflections, all of which are required for regulatory compliance.

1.2 Line-Source to Point-Source Calibration

A critical detail: road noise is a line source, not a point source. In the far field, a line source decays as $-10\lg r$ (3 dB per doubling of distance), while a point source decays as $-20\lg r$ (6 dB per doubling). The tool samples each road segment as multiple point sources, but each point source must be calibrated to reproduce the correct line-source level when summed. The calibration factor $10\lg(25 \cdot \text{seg\_len} / \pi)$ ensures that summing an infinite number of point samples along a straight road reproduces the RLS-90 mean level at 25 m. Each road is sampled at intervals of approximately 5 m (or larger, set by the cell size), so roads shorter than the sampling interval are represented by a single point source.

1.3 Building Screening

When a building layer is provided, a line-of-sight test is performed between each source sample and each receiver (grid cell). If the line-of-sight intersects any building polygon, the source contribution is reduced by the insertion loss (default 10 dB). This is a simple 2D screen — it treats buildings as infinitely tall solid barriers. In reality, sound diffracts over and around buildings, reducing the effective insertion loss. The 10 dB default is conservative (it overestimates attenuation, producing a "quiet-side" bias), which is intentional: if a cell reads below the WHO threshold with this simple screen, it is very likely below it in reality.

1.4 Use Cases and Limitations

• Noise hotspot identification: locate roads where measured or predicted levels exceed 55/65 dB(A) at residential receptors.
• Quiet-side evidence: demonstrate that courtyard levels behind perimeter blocks are 10–15 dB below street levels — the evidence for closed-block development.
• Limitations: (a) NOT a legal noise map — use a licensed engine (CadnaA, SoundPLAN, Predictor-Lima) for Environmental Noise Directive compliance; (b) no ground absorption — soft ground (grass, agricultural land) attenuates by 1–2 dB per 100 m, which this model misses, so open-country levels may be overestimated; (c) no meteorology — temperature inversions can increase levels by 5–10 dB downwind; (d) buildings treated as infinite screens — a 1-storey building screens as effectively as a 20-storey tower.

2. Mathematical Formulation

Let road segment $j$ have hourly traffic volume $M_j$ (vehicles/hour, after applying the hourly factor) and heavy-vehicle share $p_j$ (percent). The RLS-90-style mean emission level at 25 m is:

Each road segment is divided into $n_j$ point samples of length $\text{seg\_len}_j = \ell_j / n_j$ (metres). The level of one sample, calibrated to reproduce line-source behaviour when summed:

At receiver $(r, c)$, distance $d_{ij}$ from source $i$ of road $j$, the contribution with geometric spreading and optional screening loss $\Delta L_{screen}$ (default 10 dB) is:

The total level at the receiver is the energetic (incoherent) sum over all sources within the cutoff distance:

The population-weighted exposure summarises the public health burden:

3. Parameters

4. Output Description

The log reports population counts at the 55 dB(A) and 65 dB(A) thresholds — the two headline exposure numbers for any noise audit.

5. Interpretation Guide

5.1 The dB Scale

• +3 dB = double the sound energy. A road carrying 2x the traffic is ~3 dB louder.
• +10 dB = perceived as roughly twice as loud. A road at 70 dB sounds about twice as loud as one at 60 dB.
• 55 dB(A): the WHO threshold for community annoyance and sleep disturbance. Facades above this are "noise-affected."
• 65 dB(A): seriously noisy. Residential development facing this level requires mitigation (acoustic glazing, mechanical ventilation).
• 75+ dB(A): levels at which hearing protection is required for occupational exposure over 8 hours. Rare outside immediate motorway verges.

5.2 The Quiet-Side Effect

A key result from the screening model: courtyard levels behind perimeter blocks are 10–15 dB below street-facing levels, even without explicit acoustic treatment. This is the "quiet side" effect documented in European noise research — a flat whose bedroom faces the courtyard rather than the street sleeps 10 dB quieter. In planning terms, this is the strongest argument for closed-block typology over freestanding slabs: the same traffic produces acceptable and unacceptable levels depending on building arrangement.

5.3 Cross-References

• Feed the output into Road Emissions + Air Quality Screening for the noise + air pollution combined exposure map. The spatial correlation between noise and air pollution hotspots is high but not perfect — a receptor may be noisy but clean (motorway with good dispersion) or quiet but polluted (canyon with trapped emissions).
• Overlay noise bands on Building Form Metrics: buildings facing > 65 dB with high sharedwall (terraced) are candidates for facade insulation programmes because the cost is shared across fewer dwellings.

5.4 Common Pitfalls

• Hourly factor misuse: the most common error. Entering AADT without setting HOURLY_FACTOR to 1/24 produces levels 13.8 dB too high. Verify: a road with AADT 10,000 should give $L_{m25} \approx$ 58 dB (quiet urban road), not 72 dB (motorway).
• Missing heavy vehicles: a road with 20% HGVs is ~1.5 dB louder than with 5% HGVs at the same total volume. The heavy share correction is modest but critical for freight routes and industrial areas.

6. Symbolic Representation

• dB(A) grid: Singleband pseudocolour: green (< 45), yellow (45–55), orange (55–65), red (65–75), purple (> 75). Thresholds at 55 (orange-red boundary) and 65 (red-purple boundary) should be visually dominant.
• Receivers: size by population, colour by noise band. The resulting map directly shows how many people are at each noise level.

7. Literature

✓ WHO (2018). Environmental Noise Guidelines for the European Region. WHO Regional Office for Europe. [institutional report]

✓ Steele, C. (2001). "A critical review of some traffic noise prediction models." Applied Acoustics, 62(3), 271–287. DOI: 10.1016/S0003-682X(00)00030-X

✓ Kephalopoulos, S., Paviotti, M. & Anfosso-Ledee, F. (2012). Common Noise Assessment Methods in Europe (CNOSSOS-EU). JRC Report 72550. DOI: 10.2788/31776

✓ Ohrstrom, E., Skanberg, A., Svensson, H. & Gidlof-Gunnarsson, A. (2006). "Effects of road traffic noise and the benefit of access to quietness." Journal of Sound and Vibration, 295(1-2), 40–59. DOI: 10.1016/j.jsv.2005.11.034

✓ European Environment Agency (2020). Environmental Noise in Europe — 2020. EEA Report No 22/2019. DOI: 10.2800/686249

Road Emissions

Processing ID: planx:roademissions

1. Theoretical Background

1.1 Academic Lineage

Road traffic emission modelling is the upstream step in air quality assessment: before dispersion can be computed, the mass of pollutant released per unit length of road must be estimated. The standard methodology, codified in the European Environment Agency's COPERT (Computer Programme to calculate Emissions from Road Transport) and the US EPA's MOVES (Motor Vehicle Emission Simulator), multiplies traffic activity (vehicle-kilometres) by fleet-average emission factors (grams per vehicle-kilometre) that depend on vehicle type, fuel, speed, engine technology, and ambient temperature. This tool implements the simplest possible version of this: emission = volume x factor, where the factor is a single user-supplied value representing the fleet-average emission rate for the pollutant of interest.

1.2 Emission Factors

The default emission factor 0.5 g/km/veh is a generic NOx-proxy screening value — it represents a modern mixed fleet (Euro 5/6 diesel and petrol) at urban speeds. Real emission factors vary by order of magnitude: a pre-Euro diesel car emits ~1.5 g NOx/km; a Euro 6 diesel with functioning SCR emits ~0.08 g NOx/km; an electric vehicle emits 0. The factor should be calibrated to the local fleet composition. COPERT provides country-specific factors; the European Environmental Agency's EMEP/EEA Guidebook publishes default factors by vehicle category and road type.

1.3 Volume Normalisation

The traffic volume field is assumed to contain the raw count from the input data. The HOURLY_FACTOR parameter converts this to a daily volume. If the volume field is AADT (annual average daily traffic), the factor is 1.0. If the volume field is an hourly count (e.g. 08:00–09:00 peak), the factor should scale this to daily: approximately 24 for a typical diurnal pattern, or precisely the ratio of daily to hourly volume from the local traffic model.

1.4 Use Cases and Limitations

• Mandatory input step: the primary function is to produce the emission field (emission) that Air Quality Screening consumes. The two tools are designed as a pipeline.
• Source ranking: on its own, the output ranks road segments by emission rate — the top decile identifies where traffic management (volume reduction, speed harmonisation, fleet renewal) has the greatest impact per km.
• Scenario testing: change the volume field (e.g. re-route 20% of traffic) and rerun to see which segments benefit or worsen.
• Limitations: (a) single emission factor — all vehicles are assumed identical; (b) no speed dependence — the factor should be selected for the representative speed of each road type (motorway = high speed = lower NOx from diesels, higher CO2; urban = low speed = higher NOx, lower CO2); (c) no cold-start correction — emissions are 2–5x higher in the first 2 km of a trip; (d) the factor is per vehicle, not per passenger-km — bus lanes have high per-vehicle emissions but low per-passenger emissions.

2. Mathematical Formulation

Let road segment $j$ have daily traffic volume $M_j$ (vehicles/day) after applying the hourly factor: $M_j = \text{raw\_volume}_j \times \text{multiplier}$. Let $EF$ be the fleet-average emission factor (grams per vehicle-kilometre). The emission rate per km of road per day is:

The raw volume used in the output (for audit purposes) is $M_j$. If $M_j = 0$ or invalid, $E_j = 0$.

where $\ell_j$ is the segment length in km. The segment length is not directly used in the emission rate field (which is in g/km/day), but the downstream Air Quality Screening tool uses $\ell_j$ to calibrate point-source strengths.

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Source-Ranking Logic

• Top decile by emission rate: these segments contribute disproportionately to total emissions. Traffic management (speed limits, freight rerouting, fleet renewal incentives) applied here yields the highest return per km.
• Emission rate vs. concentration: the emission map shows where pollutants are produced; the Air Quality Screening dispersion map shows where they accumulate. A high-emission motorway in open country (good dispersion) may produce lower concentrations than a moderate-emission canyon street with poor dispersion. This is why the tools are a pipeline.

5.2 Cross-References

• Mandatory pipeline: Road Emissions → Air Quality Screening. The emission field is the default input for Air Quality Screening's EMISSION_FIELD.
• Combine with Road Noise Screening: roads in both the top noise decile AND top emission decile are the worst environmental performers — target for speed reduction (lowers both noise AND emissions).
• Use with traffic scenario models: edit the volume field for a proposed traffic scheme, rerun, and compare emission maps.

5.3 Common Pitfalls

• Wrong unit for volume: the most common error. A field labelled "volume" may be AADT, peak hour, or 24-hour. Check: a typical urban arterial AADT is 5,000–30,000; an hourly count is 200–2,000. If the volumes look off by a factor of ~24, the hourly factor is wrong.
• Single factor for all roads: the emission factor should vary by road type (motorway, arterial, residential) because speed and vehicle mix differ. For screening, a single average factor is acceptable; for quantitative studies, join a fleet composition table by road type.

6. Symbolic Representation

• emission: Graduated, 5 classes (Quantile or Natural Breaks), yellow (low) through orange to red (high). Line width proportional to emission rate (data-defined override: emission / max(emission) * 3.0 in map units).

7. Literature

✓ Ntziachristos, L. & Samaras, Z. (2019). "EMEP/EEA Air Pollutant Emission Inventory Guidebook 2019 — 1.A.3.b Road Transport." European Environment Agency.

✓ Franco, V., Kousoulidou, M., Muntean, M., Ntziachristos, L., Hausberger, S. & Dilara, P. (2013). "Road vehicle emission factors development: A review." Atmospheric Environment, 70, 84–97. DOI: 10.1016/j.atmosenv.2013.01.006

✓ Vardoulakis, S., Fisher, B.E.A., Pericleous, K. & Gonzalez-Flesca, N. (2003). "Modelling air quality in street canyons: a review." Atmospheric Environment, 37(2), 155–182. DOI: 10.1016/S1352-2310(02)00857-9

Air Quality Screening

Processing ID: planx:airscreening

1. Theoretical Background

1.1 Academic Lineage

Air quality screening in urban planning typically uses Gaussian plume or Gaussian puff models for open-road dispersion and street canyon models for built-up streets. The tool implements a simplified power-law decay model — an approximation to the Gaussian crosswind-integrated concentration at ground level from a line source — combined with a canyon accumulation factor based on the operational street pollution model (OSPM) concept reviewed by Vardoulakis et al. (2003). The model is screening quality: it correctly ranks receptor locations by relative pollution potential and identifies canyon hotspots, but the output is a unitless index, not a concentration in micrograms per cubic metre. Regulatory compliance requires a licensed dispersion model (ADMS-Urban, AERMOD, CALINE4) with meteorological input, terrain data, and chemistry.

1.2 The Power-Law Dispersion Model

The concentration index at a receptor is the sum of contributions from all road segment point sources: $\chi = \sum S_i / (u \cdot d_i^\alpha)$, where $S_i$ is the calibrated source strength (line-source emission rate converted to an equivalent point-source strength), $u$ is wind speed, $d_i$ is distance, and $\alpha$ is the decay exponent. This formulation derives from the Gaussian plume ground-level centreline concentration: $C \propto Q / (u \cdot \sigma_z \cdot \sigma_y)$, where $\sigma_z \propto x^b$ under neutral stability. Setting $\alpha = 2b + 1$ yields the effective distance power law. For neutral stability over urban terrain, $\alpha \approx 1.0$ for street-level screening; $\alpha = 0.5$ for broad plumes (unstable, daytime); $\alpha = 2.0$ for concentrated near-source (stable, nighttime). The offset distance $d_0$ (half the cell size) prevents the singularity at $d = 0$.

1.3 The Canyon Effect

When buildings flank both sides of a road, the street becomes a canyon — pollutants are trapped by the building walls, and concentrations can be 2–3x higher than over an open road with the same traffic. The canyon factor $1 + \min(2, H/W)$ captures the first-order geometric control: canyon aspect ratio $H/W$. A street with $H/W = 0.5$ (10 m buildings, 20 m street) has a factor of 1.5; a deep canyon with $H/W = 2$ (20 m buildings, 10 m street) saturates at 3.0. The canyon detection algorithm tests whether buildings exist within the search distance on both sides of a perpendicular line from the receptor to the nearest road, within the canyon buffer distance. Buildings on only one side = open road (factor 1.0). The tool does not model the canyon vortex — the recirculating flow that concentrates pollutants on the leeward side. This is a geometric indicator, not a CFD simulation.

1.4 Use Cases and Limitations

• Hotspot identification: the top decile of the pollution index grid is the priority list for detailed modelling, monitoring, or mitigation.
• Canyon screening: roads flagged as canyon-affected (buffer-distances with buildings on both sides) deserve first attention — a moderate-traffic canyon can produce higher concentration than a heavy-traffic open arterial.
• Land-use planning: keep schools, clinics, and playgrounds out of top-band cells, or argue setbacks and filtration where unavoidable.
• Limitations: (a) unitless relative index — ranks locations, does not check against air quality standards; (b) no chemistry — NOx, PM10, PM2.5 are all treated by the same dispersion (in reality, NO2 requires NO-NO2-O3 photostationary chemistry, and PM10 includes resuspension); (c) no terrain — the model assumes flat ground; (d) single wind speed — real dispersion varies with hourly wind, while this model uses a single representative value for screening; (e) the canyon factor is geometric — it does not distinguish between porous and solid street walls.

2. Mathematical Formulation

Let road segment $j$ have emission rate $E_j$ (g/km/day, from Road Emissions output). The segment is divided into $n_j$ point samples of length $\text{seg\_len}_j$ (metres). The calibrated point-source strength is:

At receptor $(r, c)$, the concentration index (unitless) is the sum over all sources within the cutoff distance:

where $u$ is wind speed (m/s), $d_0 = \text{cell\_size} / 2$ (m), $\alpha$ is the decay exponent, and $d_{ij}$ is the Euclidean distance from source $i$ of road $j$ to the receptor.

The canyon accumulation factor at a receptor is:

where $\bar{H}$ is the mean building height of the nearest flanking buildings on each side and $W$ is the canyon street width parameter. The final pollution index at the receptor is:

Population-weighted exposure summary:

3. Parameters

4. Output Description

5. Interpretation Guide

5.1 Reading the Relative Index

• The index is RELATIVE, not micrograms. A cell at index 100 has approximately 10x the pollution potential of a cell at index 10, but this ratio depends on the decay exponent, wind speed, and canyon geometry. The values are internally consistent within one run but not comparable between study areas with different parameter settings.
• Top decile = hotspot list. Extract the top 10% of cells by index value — these are the locations that most urgently need source control, detailed modelling, or monitoring.
• Canyon-flagged cells at moderate index > open-road cells at high index: a moderate-traffic canyon with CF = 3.0 produces 3x the open-road concentration. Look for cells in the 40–60 range that are canyon-flagged — they may be more polluted than cells in the 80–100 range on open roads.

5.2 Parameter Sensitivity

• $\alpha$ controls spatial scale. $\alpha = 0.5$: plume spreads broadly, moderate levels far from the road. $\alpha = 2.0$: concentrated near-source, sharp drop-off with distance. Use $\alpha = 1.0$ for street-level screening; vary $\alpha$ to test how the hotspot list changes under different atmospheric stability.
• $u$ scales all values linearly. Doubling wind speed halves all index values. Use a representative annual mean wind speed (2–3 m/s for most European cities).
• CANYON_WIDTH ($W$) in the denominator: narrow streets produce higher canyon factors. A 10 m street with 15 m buildings (H/W = 1.5, CF = 2.5) produces 2.5x the index of an open road with the same traffic.

5.3 Cross-References

• Mandatory pipeline dependency: Road Emissions → Air Quality Screening. The emission field from Road Emissions is the default input.
• Combine with Road Noise Screening: overlay the noise and air pollution hotspot grids. Cells in both top deciles are the worst environmental performers — dual-exposure zones.
• Overlay high-index cells on Building Form Metrics: canyon-flagged streets with attached building fabric (high sharedwall) trap pollutants between continuous walls — the worst case for both street-level pollution AND indoor air quality.
• Use with Frontal Area Index: $\lambda_f$ measures wind blockage; Air Quality Screening measures pollution accumulation. Correlated but not identical — a street with high $\lambda_f$ but low traffic is rough but clean; a street with low $\lambda_f$ and high traffic is smooth but polluted.

5.4 Common Pitfalls

• Missing canyon effect: without a building layer, all roads are treated as open. Street canyons will be underestimated by a factor of 2–3x. Always provide buildings when screening urban areas.
• Emission field unit mismatch: the emission field must be in g/km/day. If Road Emissions was run with a different multiplier or factor, the Air Quality Screening index will be proportionally wrong. Verify the emission values against typical benchmarks: a residential street with AADT 5,000 should emit ~2,500 g/km/day of NOx (screening value).
• Single wind speed: the model uses one representative wind speed. In reality, calm conditions (u < 1 m/s) produce the highest concentrations, but these are the hardest to model. Use a low wind speed (1–2 m/s) for worst-case screening.

6. Symbolic Representation

• Pollution index grid: Singleband pseudocolour: green (< 10), yellow-green (10–30), yellow (30–50), orange (50–70), red (70–100), purple (> 100). The top-decile threshold should be visually dominant.
• Canyon-flagged cells: add a hatched or crosshatched overlay for cells where CF > 1.0 (canyon effect applied). The combination of colour (concentration) + hatch (canyon flag) reveals whether hotspots are traffic-driven or geometry-driven.
• Receivers: size by population, colour by index band. The map directly shows population exposed at each level.

7. Literature

✓ Vardoulakis, S., Fisher, B.E.A., Pericleous, K. & Gonzalez-Flesca, N. (2003). "Modelling air quality in street canyons: a review." Atmospheric Environment, 37(2), 155–182. DOI: 10.1016/S1352-2310(02)00857-9

✓ Berkowicz, R. (2000). "OSPM — A Parameterised Street Pollution Model." Environmental Monitoring and Assessment, 65, 323–331. DOI: 10.1023/A:1006448321977

✓ Holmes, N.S. & Morawska, L. (2006). "A review of dispersion modelling and its application to the dispersion of particles: An overview of different dispersion models available." Atmospheric Environment, 40(30), 5902–5928. DOI: 10.1016/j.atmosenv.2006.06.003

✓ Franco, V., Kousoulidou, M., Muntean, M., Ntziachristos, L., Hausberger, S. & Dilara, P. (2013). "Road vehicle emission factors development: A review." Atmospheric Environment, 70, 84–97. DOI: 10.1016/j.atmosenv.2013.01.006

✓ Ntziachristos, L. & Samaras, Z. (2019). "EMEP/EEA Air Pollutant Emission Inventory Guidebook 2019 — 1.A.3.b Road Transport." European Environment Agency.

6. Plan Standards and QA

The Plan Standards and QA group translates planning regulations into quantitative conformance tests. Each tool answers a specific audit question: does the plan supply enough land per person for each mandated use? Are facilities both close enough and large enough for the population they must serve? Where does density actually exceed or fall short of the plan's own targets, not just the district average? These three tools form the compliance spine of PlanX — they read the plan document as geometry and report what the numbers say, independent of the narrative.

Land-Use Balance

Processing ID: planx:landusebalance

Overview

Computes the classic land-use balance table: for every land-use category in a polygon plan, the total area, the square metres provided per capita, the area required by configurable per-capita standards, and the resulting surplus or deficit. The table is the fundamental QA gate of any land-use plan — it asks, for each use regulated by a per-capita minimum, do we have enough land?

Standards are free-form text strings such as green=10, education=4, health=1.5 (meaning 10 m² of green space per capita, 4 m² of education land, 1.5 m² of health facility land). Keywords match category names case-insensitively by containment — green catches Urban Green Area, Neighbourhood Green, and Regional Green Space alike. The default string is illustrative; replace it with the values from your own regulation. The engine (engine/standards.py) is pure stdlib: no NumPy, no geometry — it operates on the area totals that the algorithm layer computes from polygon geometries.

Theoretical Background

Per-capita standards in planning theory

Per-capita land allocation is one of the oldest quantitative planning tools, traceable to Ebenezer Howard's Garden City diagrams (1898), which specified acreages per thousand persons for every urban function, and to the Soviet normativy system that prescribed square metres of every facility type per resident. The modern statutory form appears in instruments such as the Turkish Spatial Plans Regulation (Mekansal Planlar Yapim Yonetmeligi), which mandates minimum per-capita provisions for green space, education, health, social services, sports, and technical infrastructure at each plan tier.

The per-capita standard performs two distinct functions that are often conflated: (1) a sufficiency test — is the total land allocated to a use category adequate for the planned population at build-out? and (2) a land-reservation trigger — which categories, after accounting for already-developed land, still need additional parcels acquired or designated? The first is a compliance check; the second is the actionable planning recommendation. The PlanX balance table serves both by reporting every category's surplus or deficit in absolute square metres — a deficit of −18,000 m² of green space is directly interpretable as "find 1.8 ha of additional greenspace land."

Limitations and spatial mismatch

The aggregate balance table suffers from the same limitation as every city-wide statistic: it reports how much land, not where. A plan can satisfy every per-capita standard at the municipal scale while half its population lives more than 800 m from the nearest park (the reachability gap). This is why the balance table must always be paired with the spatial tools: Facility Adequacy tests whether the land that exists is close enough to the people who need it; Green Space Access tests whether the greenspace land is walkable. The balance table is the quantity gate; the spatial tools are the quality gate.

Standards as configurable policy

The PlanX engine deliberately contains no hard-coded standard values. The default string is a placeholder; the parse_standards function accepts any keyword=value pairs. This is a design choice grounded in planning practice: standards vary by jurisdiction, plan tier, and planning epoch, and embedding a specific regulation would make the tool obsolete or misleading. The user must supply the correct values for their context; the tool only performs the arithmetic and matching.

Mathematical Formulation

Given K land-use categories with total areas {A₁, …, A_K} summed from polygon geometries, a planned population P, and standards S = {(keyword_k, s_k)} where each s_k is the required m² per capita, the balance for category c is:

The matching function returns the first standard keyword that is a case-insensitive substring of the category name, or null if no match. The status classification is:

The balance B_c is in absolute square metres, not per-capita units. This is deliberate: a deficit of -18,000 directly sizes the land search ("find 1.8 hectares"), whereas a per-capita shortfall of -0.3 requires multiplying by population to become actionable.

Parameters

Output Description

Interpretation Guide

Reading the balance column

The balance_m2 column is the single most actionable number. A green deficit of −18,000 m² means finding exactly 1.8 hectares of additional greenspace land. Positive balances represent land banks that could be reallocated. Large positive balances warrant scrutiny: does the plan genuinely need that much surplus?

Temporal reading: current vs. horizon

Run twice: once with today's population, once with the horizon year (2040, 2050). Categories that flip from passing to Deficit under growth are tomorrow's land reservations — secure them before demand materialises. The largest future deficit gets the earliest deadline.

The "No standard" trap and spatial mismatch

Categories marked No standard may be genuinely unregulated (fine) or may reflect a naming mismatch between the standard keyword and the category field. Review every such row. More importantly, the balance table is city-wide — pair every deficit with a spatial tool (Green Space Access, Facility Adequacy, Capacitated Allocation) to find where the land or capacity is needed.

Pitfalls

• Overlapping polygons double-count area.
• Single-scalar population does not distribute spatially.
• Non-area standards (parking spaces/dwelling, units/ha) are not tested.

Academic References

Howard, E. (1898). To-Morrow: A Peaceful Path to Real Reform. Swan Sonnenschein. [Reprinted 1902 as Garden Cities of To-Morrow. No DOI; the foundational text of per-capita land budgeting.]

Baer, W.C. (1997). "General Plan Evaluation Criteria: An Approach to Making Better Plans." Journal of the American Planning Association, 63(3), 329–344. DOI: 10.1080/01944369708975926

Berke, P.R., Godschalk, D.R., Kaiser, E.J. & Rodriguez, D.A. (2006). Urban Land Use Planning, 5th ed. University of Illinois Press. [No DOI; the standard textbook on plan evaluation.]

Talen, E. (1998). "Visualizing Fairness: Equity Maps for Planners." Journal of the American Planning Association, 64(1), 22–38. DOI: 10.1080/01944369808975954

Laurini, R. (2001). Information Systems for Urban Planning. Taylor & Francis. DOI: 10.4324/9780203485934

Alexander, E.R. & Faludi, A. (1989). "Planning and Plan Implementation: Notes on Evaluation Criteria." Environment and Planning B, 16(2), 127–140. DOI: 10.1068/b160127

Facility Adequacy (Capacity + Distance)

Processing ID: planx:facilityadequacy

Overview

Evaluates public facilities along two dimensions simultaneously: spatial accessibility (is each demand point within the network catchment of at least one facility?) and capacity (does the assigned population exceed the facility's design capacity?). Every demand point is assigned to its nearest facility over the street network via multi-source Dijkstra, but only within a maximum cost catchment; beyond that, the point counts as uncovered. Facilities report their assigned load, utilisation (load / capacity), and a three-class status: Adequate, Overloaded, or Unused.

The dual output — facility adequacy table plus demand coverage layer — makes this the most powerful compliance tool in PlanX for education, health, and emergency-service planning. It replaces the two-step workflow of "assign to nearest, then check capacity" with one integrated pass on the real street network.

Theoretical Background

The two-dimensional adequacy problem

Public facility planning standards typically specify two independent constraints: a distance (catchment) standard ("every residence within 500 m of a primary school") and a capacity standard ("each school shall enrol no more than 600 pupils"). These are routinely checked separately — a GIS service area for distance, a spreadsheet for capacity. Facility Adequacy combines them because the two constraints interact: a facility that passes distance (sitting in a dense neighbourhood) may fail capacity catastrophically (that dense neighbourhood sends it far more children than it can hold), while another in a sparse area passes capacity trivially but serves almost no one.

Coverage models as the theoretical foundation

The adequacy check operationalises the maximal covering location problem (Church & ReVelle, 1974) in evaluation mode: instead of asking "where should we place facilities?", it asks "given the facilities we already have, what proportion of the population is adequately served in both distance and capacity?" The tool's demand-side weighting (optional population field) follows the spatial equity framework of Talen & Anselin (1998), where weighted demand replaces simple counts to reflect differential need. For a comprehensive review of location models encompassing both covering and median objectives, see ReVelle & Eiselt (2005) and Owen & Daskin (1998).

The multi-source Dijkstra engine

A single multi-source Dijkstra run from all facility nodes simultaneously labels each demand node with the facility that reached it first (lowest cost). This is functionally the network Voronoi partition by shortest-path distance. Complexity is O((n + f) log n + e) where n is nodes and f is facilities. By default the cost is geometric length; substituting a time field (e.g., from Walking Slope Comfort) produces slope-aware adequacy for hilly cities. The capacity check then summates demand weights per facility and compares against the capacity field.

Mathematical Formulation

Let G = (V, E) be the primal graph. Let D ⊂ V be demand nodes and F ⊂ V be facility nodes. Multi-source Dijkstra with cutoff c_max assigns to each demand node i a label and cost:

where d(i, k) is the shortest-path cost on G. If no facility is within c_max, the point is uncovered.

where C_k is the capacity of facility k. The status classifier is a three-way rule:

The headline pass/fail metric reported in the log:

Parameters

Output Description

Facility Adequacy (OUT_FACILITIES):

Demand Coverage (OUT_DEMAND):

Interpretation Guide

The covered-population share

The log reports "Covered population: X of Y (Z%)". This single number is the compliance headline. Every percentage point below 100% represents residents who lack any facility within the catchment. For statutory standards, this is the legal compliance metric.

Reading the three status classes

• Adequate: facility serves its population within capacity. Utilisation near 0.7–0.9 is operationally ideal (headroom); near 0.95–1.0 is tight (flag as near-capacity).
• Overloaded (utilisation > 1): enough proximity, not enough capacity. The numeric overload (assigned − capacity) sizes the expansion.
• Unused (load = 0): wrong location or a network barrier separating the facility from demand that looks close on the map. Check the network connectivity before concluding relocation is needed.

Uncovered demand: two distinct causes

Uncovered points arise from: (1) distance gap — beyond MAX_COST from every facility (build new or extend catchment); (2) capacity gap — within MAX_COST but every reachable facility is full. Note: this tool assigns to nearest only and does not reallocate loads. Capacitated Allocation does that with spill logic.

Cross-referencing

• Balance table shows land deficit AND Facility Adequacy shows overloaded facilities: the land and the seats agree — plan for both.
• Balance table passes but Facility Adequacy fails: land exists, facilities on it are too small (redevelop, not rezone).
• For greenfield site selection, use Facility Location Optimizer.
• For capacity-constrained reallocation with spill, use Capacitated Allocation.

Academic References

Church, R. & ReVelle, C. (1974). "The Maximal Covering Location Problem." Papers of the Regional Science Association, 32(1), 101–118. DOI: 10.1007/BF01942293

Talen, E. & Anselin, L. (1998). "Assessing Spatial Equity: An Evaluation of Measures of Accessibility to Public Playgrounds." Environment and Planning A, 30(4), 595–613. DOI: 10.1068/a300595

Daskin, M.S. (1995). Network and Discrete Location: Models, Algorithms, and Applications. Wiley. DOI: 10.1002/9781118032343

ReVelle, C.S. & Eiselt, H.A. (2005). "Location Analysis: A Synthesis and Survey." European Journal of Operational Research, 165(1), 1–19. DOI: 10.1016/j.ejor.2003.11.032

Owen, S.H. & Daskin, M.S. (1998). "Strategic Facility Location: A Review." European Journal of Operational Research, 111(3), 423–447. DOI: 10.1016/S0377-2217(98)00186-6

Dijkstra, E.W. (1959). "A Note on Two Problems in Connexion with Graphs." Numerische Mathematik, 1(1), 269–271. DOI: 10.1007/BF01386390

Density Grid

Processing ID: planx:densitygrid

Overview

Distributes a numeric variable (population, dwelling count, jobs, floor area) from irregular source features — polygons or points — onto a regular grid using dasymetric disaggregation. Polygons are split proportionally by area share; points contribute fully to the containing cell. Output cells carry the summed value, density per hectare, and contributing feature count. Empty cells are omitted.

The gridded output is the preferred input format for most PlanX tools needing a uniform spatial surface: Facility Adequacy, Green Space Access, and Accessibility Equity all accept the density grid as a demand surface, ensuring provision analysis follows population rather than administrative centroids.

Theoretical Background

Dasymetric mapping: beyond the choropleth

The choropleth map — colouring administrative zones by a density value — is the default cartographic representation of population but also the most misleading: it implies uniform density within each zone, concealing the internal texture that drives facility demand, walkability, and infrastructure stress. A "low-density" district (30 persons/ha average) may contain a single tower cluster at 300 persons/ha; treating the whole district as low-density would under-provision schools for the tower residents.

Dasymetric mapping (Wright, 1936) addresses this by using ancillary information to redistribute the zonal total onto a finer grid. The PlanX implementation uses the simplest and most robust form: binary dasymetry by geometry. If source features already represent actual spatial units (buildings, parcels), the redistribution is exact: a building with 120 residents spanning four grid cells contributes 30 to each. No statistical modelling, no ancillary land-cover raster — just geometric intersection with area-proportional splitting. Eicher & Brewer (2001) and Mennis (2009) provide comprehensive reviews of dasymetric methods.

The modifiable areal unit problem (MAUP)

The density pattern depends on cell size (Openshaw, 1984). A 100-metre grid reveals building-by-building peaks; a 500-metre grid reveals neighbourhood structure; a 1000-metre grid approximates census-tract choropleths. There is no "correct" cell size — only the size appropriate to the question. Always report cell size with any derived statistic.

Density thresholds as planning heuristics

Urban economics and transport planning have established rough density thresholds linking residential density to service viability (Newman & Kenworthy, 1989; Ewing & Cervero, 2010):

• < 20 persons/ha: below bus-service threshold; car-dependent.
• 20–50 persons/ha: supports basic bus route (20–30 min headway).
• 50–150 persons/ha: walkable urban range; frequent bus, neighbourhood retail, walk-to-school catchments.
• 150–300 persons/ha: supports light rail/BRT; open-space provision becomes critical.
• > 300 persons/ha: metropolitan core density; infrastructure stress dominates.

These are heuristics, not universal laws; local context modulates them.

Mathematical Formulation

Let F = {f₁, …, f_m} be source features with values {v_i} and geometries {g_i}. For a grid cell (c_x, c_y) with rectangle R and area h², the contribution from polygon feature i with area a_i is:

For point features, the feature contributes fully if its representative point falls inside the cell:

The cell aggregate and density per hectare are:

where h² / 10,000 converts square map units to hectares. Only cells with at least one contributing feature are written; empty cells are skipped, keeping the output compact and free of sea-of-zero artefacts.

Parameters

Output Description

Interpretation Guide

Cell size diagnostics

Run at two sizes and compare: a 100 m grid reveals building-by-building peaks; a 500 m grid shows neighbourhood structure. Both are true but answer different questions. The 100 m grid tells you where to place a school entrance; the 500 m grid tells you whether the neighbourhood supports transit.

Outlier detection and plan compliance

Sort by dens_ha descending. The top 1% of cells often reveal data errors or genuine extremes meriting plan attention. Select cells exceeding the plan's density cap — these are non-conforming locations. Check whether they represent existing (grandfathered) or proposed development. The spatial cluster of non-conforming cells identifies neighbourhoods where the cap is most at odds with built form.

Difference grids for growth scenarios

Run on today's population and on the horizon-year population (from Population Projection). Subtract the grids (horizon − present). Positive cells show where growth is allocated; the magnitude at the densest cells indicates whether growth is concentrated (infill/compact) or dispersed (expansion/sprawl). This difference grid is the quantitative foundation for compact-city debates.

Pitfalls

• Cell size changes everything — always report it with any derived number.
• Polygon intersection is area-proportional — a building straddling four cells splits evenly. This is correct but may not match the actual population distribution within the building (e.g., a tower with all residents on upper floors concentrated over one part of the footprint).
• Point sources use containment only — the contributing point must fall inside the cell rectangle; points on boundaries go to exactly one cell (QGIS intersection semantics).

Academic References

Wright, J.K. (1936). "A Method of Mapping Densities of Population: With Cape Cod as an Example." Geographical Review, 26(1), 103–110. DOI: 10.2307/209467

Openshaw, S. (1984). "The Modifiable Areal Unit Problem." CATMOG (Concepts and Techniques in Modern Geography), 38. Geo Books, Norwich. [No DOI; the foundational MAUP reference.]

Eicher, C.L. & Brewer, C.A. (2001). "Dasymetric Mapping and Areal Interpolation: Implementation and Evaluation." Cartography and Geographic Information Science, 28(2), 125–138. DOI: 10.1559/152304001782173727

Newman, P.W.G. & Kenworthy, J.R. (1989). Cities and Automobile Dependence: An International Sourcebook. Gower. [No DOI; establishes the 30 persons/ha bus-service threshold.]

Ewing, R. & Cervero, R. (2010). "Travel and the Built Environment: A Meta-Analysis." Journal of the American Planning Association, 76(3), 265–294. DOI: 10.1080/01944361003766766

Mennis, J. (2009). "Dasymetric Mapping for Estimating Population in Small Areas." Geography Compass, 3(2), 727–745. DOI: 10.1111/j.1749-8198.2009.00220.x

7. Reporting and Dashboard

Seven tools that compile PlanX outputs into shareable evidence: an HTML performance report with embedded SVG charts; scenario snapshots as comparable JSON records; A/B comparison with direction-aware deltas and a verdict line; multi-scenario ranking with configurable weighted composites and a heat-table visualisation; a one-click batch auditor that chains the full evaluation battery; a deterministic synthetic city generator for training and testing; and a LUTI-lite scenario pipeline that welds growth simulation, population allocation, and accessibility evaluation into one integrated workflow.

Plan Performance Report (HTML)

Processing ID: planx:performancereport

Overview

Compiles multiple PlanX outputs into a single, self-contained HTML document with score cards, inline SVG histograms, compliance bar charts, and summary tables. Computes a Plan Performance Index (PPI) as the unweighted mean of the available 0–100 component scores. The report requires no external services, no web server, and no GIS to view — open the HTML file in any browser and all charts render from the embedded SVG. The same score cards appear live in the PlanX Dashboard dock panel.

The engine (engine/report.py) is pure stdlib: it draws every chart with inline SVG elements — histograms with custom-coloured bars following a three-tone ramp (bad red → amber → good green), scatter maps of access scores with ramp-coloured points, and horizontal bar charts of land-use balance (provided in colour vs. required in grey). No matplotlib, no charting library, no JavaScript: the SVG is valid XML embedded directly in the HTML stream.

Theoretical Background

Dashboards for plan evaluation

The Plan Performance Report adapts the dashboard paradigm from business intelligence to spatial planning. Following Tufte's (2001) principles of data-ink maximisation and small-multiples, each section presents one dimension of plan performance (access, land balance, facility adequacy, density) as a self-contained card: a headline number, a sub-line explaining it, and a colour tone (green/amber/red) encoding the quality level. The PPI aggregates these cards into a single 0–100 needle, following the composite-index tradition in urban studies (e.g., the UN Habitat City Prosperity Index) but with a strict design constraint: missing sections do not penalise the score — the PPI is the mean of whatever is available, not a weighted sum with zeros imputed for missing components.

Self-contained HTML as the distribution format

The report is deliberately a single .html file with no external dependencies: no CDN links, no image files, no data directory. This is a pragmatic choice grounded in planning practice: the report must survive being emailed to a councillor, opened on a tablet in a committee room without internet, and archived in a document management system that strips non-HTML attachments. The inline SVG approach achieves this at the cost of larger file size (typically 50–200 KB depending on data density), which is negligible for modern storage and bandwidth.

PPI as a progress needle, not an absolute grade

The PPI is meaningful only over iterations of the same plan: a PPI rising from 62 to 74 across three revisions documents that the revisions improved the plan on the measured dimensions. It is meaningless as an absolute cross-plan comparator (a small-village plan will score differently from a metropolitan-region plan because its geometry, network, and population are different — not because one is "better"). The PPI's value is time-series comparison within one plan's evolution.

Mathematical Formulation

The Plan Performance Index (PPI) is the unweighted arithmetic mean of the available 0–100 component scores. Contributing components are aggregated by the report engine from the access, balance, and adequacy summaries produced by the corresponding PlanX tools; the formulation of each component is documented in the parent tool's entry.

Access score summary. From the vector of per-origin access scores {x₁, …, x_n}, the engine computes the arithmetic mean, the median (sorted middle value), and the shares of origins with a perfect score (100) or a low score (< 50):

Balance summary. From land-use balance rows with status ≠ "No standard", the compliance percentage is the fraction meeting or exceeding their standard:

Adequacy summary. From the facility adequacy and demand coverage outputs, the covered population share is:

PPI: the unweighted mean of available components (access mean, compliance_pct, covered_share), with missing components simply excluded:

Each score card is coloured by a three-tone ramp (bad red → amber → good green), with the colour derived from the normalised position of the value within [0, 100]. The ramp function interpolates linearly between the three anchor colours: (214, 69, 65) at t = 0, (245, 176, 65) at t = 0.5, and (39, 174, 96) at t = 1.0.

Parameters

Output Description

The report file contains: Header (title, population, timestamp, PlanX version), Score cards (PPI, access mean, standards compliance, covered population, density), Access section (score distribution histogram, optional score map as SVG scatter), Land-Use Balance section (provided-vs-required bar chart with compliance table), Facility Adequacy section (utilisation table sorted by descending load), Density section (cell count, mean, maximum), and a footer with the PlanX attribution.

Interpretation Guide

• PPI: a progress needle, not an absolute grade. Regenerate after each planning iteration and file the HTMLs as the plan's metric history.
• Histogram shape matters more than the mean: a bimodal access distribution means two different cities in one plan — some neighbourhoods are served, others are not, and the mean hides this split.
• Balance bars: the coloured bar is actual provision; the grey bar behind it is the required amount. A shorter coloured bar = deficit (visible, not just numeric).
• Facility table: sorted by decreasing utilisation — the top rows are the facilities nearest to capacity failure.
• Regenerate and file after each iteration. The PPI trace documents that the revisions actually improved the plan.

Academic References

Tufte, E.R. (2001). The Visual Display of Quantitative Information, 2nd ed. Graphics Press. [No DOI; the canonical reference on data visualisation design.]

Baer, W.C. (1997). "General Plan Evaluation Criteria: An Approach to Making Better Plans." Journal of the American Planning Association, 63(3), 329–344. DOI: 10.1080/01944369708975926

Few, S. (2013). Information Dashboard Design: Displaying Data for At-a-Glance Monitoring, 2nd ed. Analytics Press. [No DOI; the standard reference on dashboard design principles.]

Scenario Compare (A/B)

Processing ID: planx:scenariocompare

Overview

Compares two scenario snapshots metric by metric, with direction-aware deltas. For each metric shared by both snapshots, the tool reports the raw values for A and B, the absolute delta (Δ = B − A), the percent change, and which scenario wins (A, B, or tie for equal values). The verdict line tallies the wins. Scenarios rarely dominate — the normal outcome is a trade-off profile where B wins on accessibility and compliance while A wins on density and coverage. An optional self-contained HTML report presents the comparison in formatted tables for stakeholder distribution.

The engine (engine/scenario.py) drives the comparison. A direction registry (METRICS dict) assigns each metric a human label and a direction (+1 = higher is better, −1 = lower is better, 0 = neutral). The engine also provides score_line for a one-sentence verdict and build_compare_html in engine/report.py for the HTML output.

Theoretical Background

Multi-criteria comparison in plan evaluation

Plan alternatives rarely dominate one another on all criteria — the compact city proposal may score higher on walkability and transit access while the dispersed proposal scores higher on housing capacity and green space per capita. The Scenario Compare tool formalises this trade-off analysis by reporting the direction and magnitude of each metric's change, following the multi-criteria evaluation framework (Baer, 1997; Keeney & Raiffa, 1976). Unlike a weighted composite score (which collapses the trade-off into one number), paired comparison preserves the profile: the planner sees which metrics flip and by how much.

Direction-aware comparison

The key innovation over a simple algebraic delta is the direction registry: the engine knows that a higher access score is good, a higher Gini coefficient is bad, and a different number of facilities is neutral. The "better" column thus reflects the substantive planning meaning of each delta, not just its arithmetic sign. This prevents the common error of celebrating a 10% increase in a metric where lower values indicate better outcomes (e.g., inequality, overloading count).

Mathematical Formulation

For each metric k with direction d_k ∈ {+1, −1, 0} and snapshot values v_k^A and v_k^B:

The winning scenario for metric k is determined by the direction-consistent sign:

Parameters

Output Description

Interpretation Guide

• Do not stop at the win count. Scenarios rarely dominate. The normal outcome is a trade-off profile — naming that trade-off is the analysis.
• Use pct_change to judge materiality: <1% = noise (input data moved, not the plan); double-digit swings are genuine decisions.
• Missing metrics signal incomplete snapshots: fix the snapshot inputs (run the missing PlanX tools) before drawing conclusions.
• The verdict line counts decided wins. An even split is not a failure — it documents a balanced trade-off.

Academic References

Baer, W.C. (1997). "General Plan Evaluation Criteria: An Approach to Making Better Plans." Journal of the American Planning Association, 63(3), 329–344. DOI: 10.1080/01944369708975926

Keeney, R.L. & Raiffa, H. (1976). Decisions with Multiple Objectives: Preferences and Value Tradeoffs. Wiley. [Reprinted Cambridge University Press, 1993. DOI: 10.1017/CBO9781139174084]

Scenario Ranking

Processing ID: planx:scenariorank

Overview

Ranks any number of scenario snapshots (two or more) using a configurable weighted composite score. For each scored metric, values are min-max normalised within the set so that 1.0 is always best; the composite score is the weighted mean of these normalised values, scaled to 0–100. Competition ranking handles ties (equal scores share a rank; the next rank is skipped). "Wins" count per scenario — where a scenario holds the strictly best norm on a metric — complements the composite for non-compensatory reading. An optional HTML ranking board renders the scoreboard as a styled table with score bars and a metric heat table.

Theoretical Background

Composite indices in multi-criteria decision analysis

The weighted-sum model with min-max normalisation is the simplest form of multi-attribute value theory (Keeney & Raiffa, 1976). Normalisation to [0, 1] ensures commensurability across metrics measured in different units (persons, percent, metres, Gini coefficient); the direction flag ensures that "more" always means "better" after normalisation. The weighted sum is fully compensatory: a scenario can score zero on one metric and still rank first if it dominates on heavily weighted others. This is a feature (it allows trade-offs) and a warning (it can mask fatal weaknesses).

Metrics that are skipped

Three classes of metrics are excluded from scoring: (1) neutral (direction = 0, e.g., total population, facilities count) — no normative direction exists; (2) not-shared (missing in at least one snapshot) — comparison is impossible; (3) constant (identical across all snapshots) — contributes zero discrimination. The skipped list is reported explicitly; it is the first thing to check before trusting a ranking, because a snapshot evaluated with fewer tools will have more "not-shared" exclusions and thus a structurally different score basis.

Competition ranking and the wins complement

Competition ranking ("1224") handles equal scores correctly: identical composite scores produce tied ranks. The wins count — number of metrics where a scenario holds the strictly best norm — provides a non-compensatory complement: a balanced alternative may rank first on composite yet win zero individual metrics, while a specialist wins several metrics but scores lower overall. The divergence between rank and wins count is diagnostic of the scenario's strategy type (generalist vs. specialist).

Mathematical Formulation

For each scored metric k with direction d_k and values v_k,s across scenarios s:

Competition rank: scenario with highest score = rank 1; if two scenarios have equal scores, both share rank r and the next distinct score gets rank r + 2.

Parameters

Output Description

Ranking (OUT_TABLE): rank (int), scenario (string), score (double, 0–100), wins (int), n_metrics (int).

Detail (OUT_DETAIL): metric (string key), label (string), direction (int, +1/−1), weight (double), scenario (string), value (double), norm (double, 0–1).

Interpretation Guide

• Composite score is relative to the compared set; adding or removing a scenario rescales all scores. Never compare scores across different ranking runs.
• Rank ties = genuinely indistinguishable alternatives under the chosen weights.
• Wins vs. rank divergence: a generalist ranks first with zero wins; a specialist wins metrics but scores lower. Both are valid plan types; the choice is political, not mathematical.
• Check skipped metrics first: scenarios reaching ranking with fewer evaluated dimensions are structurally advantaged or disadvantaged depending on whether the missing dimensions are high or low.

Academic References

Keeney, R.L. & Raiffa, H. (1976). Decisions with Multiple Objectives. Cambridge University Press. DOI: 10.1017/CBO9781139174084

Baer, W.C. (1997). "General Plan Evaluation Criteria." JAPA, 63(3), 329–344. DOI: 10.1080/01944369708975926

Saaty, T.L. (1980). The Analytic Hierarchy Process. McGraw-Hill. [No DOI; the foundational AHP text for weighted multi-criteria ranking, the conceptual ancestor of this tool's weighted composite.]

Scenario Snapshot

Processing ID: planx:scenariosnapshot

Overview

Captures plan score metrics from the current QGIS project into a structured JSON file (the "scenario snapshot" format). PlanX output layers are auto-detected by their field signatures: the access-score layer (score + n_reach), the land-use balance table (balance_m2 + m2_capita), facility adequacy (utilization + assigned), demand coverage (covered + net_cost), and the density grid (dens_ha + value). Each can also be pinned explicitly — an explicit choice always wins over auto-detection.

The snapshot stores the same metrics as the Plan Dashboard score cards: Plan Performance Index, accessibility mean/median and full/low shares, standards compliance percentage and deficit count, covered population share and facility overloaded/unused counts, and density summary. The JSON serves as the comparable record for Scenario Compare and Scenario Ranking. Every evaluation workflow should end with a snapshot node.

Theoretical Background

Metrics as comparable evidence in plan-making

The snapshot formalises a single principle: every plan alternative must be evaluated on the same metrics with the same thresholds. A plan whose access score was computed with a 15-minute threshold and walking speed of 4.8 km/h is not comparable to one computed with a 10-minute threshold and 5.0 km/h. The snapshot captures not only the metric values but, through its field-signature detection, which PlanX tools contributed to the evaluation — a snapshot whose metrics list lacks density entries was evaluated without the Density Grid tool, and that absence will later surface in Scenario Compare as "metric missing on one side."

Auto-detection by field signature

The collect module (in collect.py) scans project layers for characteristic field-name pairs rather than layer names. This is deliberate: a layer called "Access Score (Scenario B)" is detected as correctly as "access_score_output" because both contain the fields score and n_reach. The detection is robust to renaming but fragile to field deletions: if a QGIS processing step strips the signature fields, the layer becomes invisible to the snapshot. Always check the log's detection lines before trusting the numbers.

Parameters

Output Description

The snapshot JSON schema:

{
  "kind": "planx-scenario-snapshot",
  "version": 1,
  "name": "2040 Compact",
  "generated": "2026-08-07 14:30",
  "metrics": {
    "plan_performance_index": 72.5,
    "access_mean": 68.3,
    "access_median": 71.0,
    "access_share_full": 45.2,
    "access_share_low": 12.1,
    ...
  }
}

Interpretation Guide

• A single snapshot is rarely the point: the value appears when two or more meet in Scenario Compare or Scenario Ranking.
• Check detection lines in the log before trusting: a snapshot silently missing a section (e.g., no density detected) will later read as "metric missing on one side" in comparisons.
• Use honest names: the snapshot name is carried through every downstream report. "2040 Compact" tells a story; "Scenario A" does not.
• End every evaluation model with a snapshot node so each plan run leaves a comparable record. Keep JSON files in the project folder as the plan's metric history.

Academic References

Baer, W.C. (1997). "General Plan Evaluation Criteria: An Approach to Making Better Plans." Journal of the American Planning Association, 63(3), 329–344. DOI: 10.1080/01944369708975926

Lichfield, N., Kettle, P. & Whitbread, M. (1975). Evaluation in the Planning Process. Pergamon Press. [No DOI; the classic text on systematic plan evaluation, establishing the principle of consistent metrics across alternatives.]

Batch Plan Auditor

Processing ID: planx:planaudit

Overview

Chains the standard PlanX evaluation battery in a single run: 15-minute access score, walkability audit, land-use balance against per-capita standards, facility adequacy (capacity + distance), green space access hierarchy check, and access equity (Gini coefficient over access scores). Each component is optional — supply only the inputs for the analyses you need and the auditor runs only those. The output is a scenario snapshot JSON (ready for Scenario Compare) plus an optional HTML Plan Performance Report. The tool is model-designer friendly and fully headless: one call turns a set of plan layers into a comparable scorecard.

Theoretical Background

The standard evaluation battery

The Batch Plan Auditor operationalises the principle that all plan alternatives must be evaluated on the same battery of quantitative tests before qualitative comparison begins (Baer, 1997). The six tests are selected to cover the standard dimensions of plan quality: spatial equity of access (15-minute city and Gini), walkability (street-level pedestrian environment), land sufficiency (per-capita balance), facility provision (adequacy), and environmental amenity (green space hierarchy). Together they produce 20+ comparable metrics per scenario. The auditor replaces the error-prone manual workflow of "run six tools, collect six outputs, manually copy numbers into a spreadsheet" with a single deterministic call.

Multi-step feedback and child algorithms

The auditor uses QGIS Processing's multi-step feedback mechanism (QgsProcessingMultiStepFeedback) to report progress through the battery. Each test is a child algorithm call (processing.run with is_child_algorithm=True), so failures are propagated with the offending algorithm name, and partial results up to the failure point are discarded. All tests use the same network, demand layer, and coordinate system — the auditor assumes these are prepared once and reused.

Parameters

Output Description

Snapshot JSON with 20+ metrics (depending on which tests ran) including PPI, access statistics, walk score mean and low-score share, standards compliance and deficits, covered population share and facility utilisation, green coverage minimum, and access Gini. Metric table mirrors the snapshot. Optional HTML report with access, walkability, balance, facility adequacy, and green access sections.

Interpretation Guide

• Read the metric table as a triage list, worst first. Each headline number has a dedicated tool behind it; when a number looks wrong, run that tool alone and inspect its map.
• Audit every alternative with identical inputs and thresholds so snapshots are truly comparable.
• PPI is meaningful over iterations, weak as absolute grade. A PPI of 72 from a plan with all six tests is different from a PPI of 72 from a plan with only three tests active.
• Keep the JSON per iteration as the plan's metric history. The sentence for the report is: "audited on the standard battery, improved on X of Y metrics since draft 1."

Academic References

Baer, W.C. (1997). "General Plan Evaluation Criteria: An Approach to Making Better Plans." Journal of the American Planning Association, 63(3), 329–344. DOI: 10.1080/01944369708975926

Hopkins, L.D. (2001). Urban Development: The Logic of Making Plans. Island Press. [No DOI; the foundational text on plan-making as sequential decision under uncertainty, establishing the rationale for evaluating multiple alternatives on a common battery.]

Generate Demo City

Processing ID: planx:democity

Overview

Creates a complete, deterministic synthetic city from a single random seed: a regular grid of street blocks intersected by a diagonal avenue, building footprints with random heights assigned to rectangular lots within each block, four land-use zones (residential, commercial, green, school) with probabilistic allocation, point-of-interest markers, public facilities with capacities placed in green and school blocks, demand points with population weights derived from residential building volumes, green space polygons, and a raster DSM of building heights. The same seed always regenerates an identical city — ideal for tutorials, reproducible testing, and bug reports.

The engine (engine/demo.py) is pure NumPy with a numpy.random.default_rng generator. Streets are constructed by intersecting vertical, horizontal, and diagonal grid lines at the block boundaries; buildings are 2x2 arrays per block, skipped over the diagonal avenue right-of-way; land uses are assigned with guaranteed representatives for the first four blocks (one of each type) and random categorical draws for the rest. The DSM is rasterised by burning building height into footprint-extent cells.

Theoretical Background

Synthetic data in spatial algorithm testing

Synthetic city generators serve two distinct purposes in geospatial software development and training: (1) algorithm validation — a known, controlled input where every expected output can be computed by hand, enabling unit testing and correctness verification; (2) pedagogical demonstration — a compact, clean dataset that illustrates a tool's behaviour without the noise, gaps, and idiosyncrasies of real-world data. The demo city's small default size (4x4 blocks at 100 m = 400 m × 400 m, 64 buildings, ~16 streets) is deliberately scaled to be visually inspectable: a user can verify a service area's correctness by eye because the total network has only a few dozen edges.

Determinism and reproducibility

The fixed-seed design (default seed = 42 with NumPy's PCG-64 generator) guarantees bitwise-identical output across platforms and Python versions (NumPy's default_rng stream is version-stable). This makes the demo city useful for regression testing: a CI pipeline can run every PlanX tool on the demo city and assert that each output's row count, field types, and key statistics match the expected values. Any deviation signals a regression in the engine or algorithm layer.

Parameters

Output Description

Eight outputs: Streets (seg_id, length_m), Buildings (height, 3–40 m), Land Use (use: residential/commercial/ green/school), POIs (type: Shop/Cafe), Facilities (name, cap: 1000 for parks, 500 for schools), Demand (pop, proportional to building volume), Green (park_id), and DSM (GeoTIFF, building heights on a 2 m grid, nodata = −1).

Interpretation Guide

• Nothing is real — the town exists so every other PlanX tool has clean, compatible inputs on the first click. Use it to learn a tool before trusting it on real data.
• Diagnostic value: when a tool misbehaves on real data but works on the demo city, the difference (CRS, noding, field types, missing values) is the diagnosis.
• Quickstart pair: streets → Space Syntax (radii 800,n); facilities → Service Areas; DSM → Microclimate tools; demand + facilities → Facility Adequacy or Batch Plan Auditor.

Academic References

Batty, M. (2013). The New Science of Cities. MIT Press. [No DOI; discusses synthetic city models as tools for understanding urban systems, including procedural generation approaches.]

Parish, Y.I.H. & Muller, P. (2001). "Procedural Modeling of Cities." Proceedings of SIGGRAPH 2001, 301–308. ACM. DOI: 10.1145/383259.383292

Scenario Pipeline (LUTI-lite)

Processing ID: planx:scenariopipeline

Overview

Weld urban growth simulation (CA), population allocation, and accessibility/walkability evaluation into one integrated decision pipeline. First, the Urban Growth CA model simulates city expansion from a seed urban mask over a suitability surface, respecting optional constraint rasters. Then, population growth is allocated to the newly developed cells proportionally to their suitability values. The pipeline constructs combined demand points (existing + new) and re-evaluates 15-minute accessibility and walkability on the grown city, producing a scenario snapshot JSON for comparison against the baseline.

Theoretical Background

LUTI (Land-Use Transport Interaction) in simplified form

LUTI models simulate the co-evolution of land use and transport over time. Full LUTI implementations (e.g., UrbanSim, TRANUS, MEPLAN) require calibrated behavioural models and extensive data. The Scenario Pipeline implements a "LUTI-lite" approach: the transport network is fixed (the street layer does not change), and land use evolves through cellular automaton growth constrained by suitability. The population reallocation step is the simplest possible linkage: new residents are placed where the CA model developed land, weighted by the suitability that attracted the growth. The feedback is one-directional: growth changes demand, which changes access scores and walkability. There is no reverse feedback (accessibility changes do not alter future growth locations). This is not a limitation for horizon-year screening — it produces the honest "growth without new services" worst case that service planners need.

The fixed-amenity assumption as a planning tool

The pipeline keeps amenity layers fixed: schools, shops, parks do not grow with the city. This reads as "what happens if we grow but do not add services?" — the honest worst case. The metric gap between the grown scenario and the baseline quantifies the service deficit that the new growth creates. If mean access falls from 68 to 52, the planning response is either to add amenities at the growth locations (raise the numerator) or to redirect growth toward existing amenity-rich areas (change the growth pattern). The pipeline quantifies the size of the problem; it does not solve it — that is the planner's job.

Mathematical Formulation

The pipeline's three stages are sequential:

Stage 1 — Growth CA: the Urban Growth Simulation algorithm produces a year-of-conversion raster where nonzero cells were developed. The set of newly developed cells is:

Stage 2 — Population allocation: for each new cell, the suitability value s_r,c is extracted from the suitability raster. Population growth G is allocated proportionally:

These become new demand points at the cell centres with population p_r,c, merged with existing demand points.

Stage 3 — Re-evaluation: the access score and walkability audit tools run on the combined demand and the fixed network, producing new metrics for the snapshot.

Parameters

Output Description

The pipeline produces two outputs:

• Snapshot JSON (OUTPUT_JSON): a standard PlanX scenario snapshot containing the PPI, access score statistics (mean, median, full/low shares), walk score mean, and low-score share — all computed on the grown city with combined (existing + new) demand.
• Metric Table (OUT_METRICS): same format as Scenario Snapshot — metric key, human-readable label, and numeric value.

Interpretation Guide

• The metric table scores the GROWN city, not today's. Compare against a baseline snapshot. The gap between them is what growth does to liveability.
• Falling mean access is the normal finding: new edge growth lands far from existing amenities. The size of the drop is the planning information.
• Amenity layers stay fixed: this is "growth without new services," the honest worst case.
• Run compact vs. dispersed variants: high neighbourhood weight + constraints-on = compact; low weight + no constraints = dispersed. Feed both snapshots to Scenario Compare — the access/walkability gap is the quantified cost of sprawl for YOUR city.
• Where access collapses: that is where the amenity investment belongs. Test it with the standalone access tools.

Academic References

Clarke, K.C., Hoppen, S. & Gaydos, L. (1997). "A Self-Modifying Cellular Automaton Model of Historical Urbanization in the San Francisco Bay Area." Environment and Planning B, 24(2), 247–261. DOI: 10.1068/b240247

Waddell, P. (2002). "UrbanSim: Modeling Urban Development for Land Use, Transportation, and Environmental Planning." Journal of the American Planning Association, 68(3), 297–314. DOI: 10.1080/01944360208976274

Wegener, M. (2014). "Land-Use Transport Interaction Models." In: Fischer, M.M. & Nijkamp, P. (eds.), Handbook of Regional Science, pp. 229–246. Springer. DOI: 10.1007/978-3-642-23430-9_14

8. Optimization

Five facility and land-use optimisation tools operating on the street network via an embedded pure-NumPy engine — no external solvers, no licensed libraries, no cloud dependencies. Two facility location models (maximal coverage via greedy selection and p-median via Teitz-Bart vertex substitution), one capacitated allocation with greedy nearest-with-spill logic, one multi-objective land-use allocator with compactness and adjacency terms, a Pareto front tracer that maps the suitability-compactness trade-off, and a capacitated facility siting tool that selects sites AND sizes capacity in one pass.

Facility Location Optimizer (Coverage / P-Median)

Processing ID: planx:facilitylocation

Overview

Selects the best sites for new facilities among candidate locations on the real street network. Two models are implemented: Maximal Coverage (Church & ReVelle, 1974) using greedy selection — each step picks the candidate covering the most as-yet-uncovered demand within a catchment radius; and P-Median (ReVelle & Swain, 1970; Teitz & Bart, 1968) using greedy construction followed by vertex substitution — each swap replaces a selected site with an unselected candidate if it reduces the population-weighted total travel cost. Existing facilities are fixed in the solution; new sites complement them.

The engine (engine/optimize.py) operates on a distance matrix D of shape (candidates, demand points) computed by many-to-many Dijkstra over the network graph. For coverage mode, a binary mask D ≤ radius is multiplied by the population weight vector to obtain marginal gains. For p-median mode, the objective is the population-weighted sum of distances to the nearest selected facility, and the Teitz-Bart substitution iterates until no improving swap is found or max_iter is reached.

Theoretical Background

Covering models: from set covering to maximal coverage

Toregas et al. (1971) formulated the location set covering problem (LSCP): minimise the number of facilities such that every demand point is within a specified distance. Church & ReVelle (1974) recognised that the LSCP's "cover everyone" constraint is often infeasible under a budget, and proposed the maximal covering location problem (MCLP): for a fixed number of facilities p, maximise the population within the coverage radius. The greedy heuristic implemented here is a (1 − 1/e) ≈ 0.632-approximation for the submodular maximisation problem (Nemhauser, Wolsey & Fisher, 1978) — it is provably within 63% of the optimal covered population.

P-median and the Teitz-Bart heuristic

The p-median problem (Hakimi, 1964; ReVelle & Swain, 1970) minimises the sum of demand-weighted distances to the nearest facility. Unlike coverage models which treat all demand within the radius equally, the p-median penalises long trips linearly — it preferences the average user, not the worst-off. The Teitz & Bart (1968) vertex substitution heuristic is a local-search improvement over a greedy starting solution: it evaluates swapping each selected site with each unselected candidate, applying the first improving swap found. While not guaranteed to find the global optimum, it typically produces solutions within 5–10% of optimal for urban-scale instances (Daskin, 1995).

Coverage vs. p-median: choosing the model

Coverage models are appropriate for services with a hard distance threshold ("within 500 m of a primary school", "within 8 minutes of a fire station"). P-median models are appropriate for services where every metre of extra distance matters to everyone ("shorten the average trip to the nearest clinic"). The two models give different site selections by design. Sites picked by both are robust to the modelling choice; sites picked by only one reveal the sensitivity of the recommendation to the objective.

Mathematical Formulation

Maximal Coverage (greedy). Let cover[f, d] = 1 if dist(f, d) ≤ radius. The gain at each greedy step is uncovered demand newly covered by candidate c:

At each iteration t, select c_t = argmax_c gain(c), mark newly covered demand, and repeat for p steps (or until no candidate adds coverage).

P-Median objective. For a selected set S of facilities (including fixed), the objective is:

Teitz-Bart swap. For each selected site s and each unselected candidate c, evaluate the swap (S \ {s}) ∪ {c}. If Z(S_swap) < Z(S) − 10⁻¹², accept the swap. Repeat until no swap improves the objective (or max_iter is reached).

Unreachable pairs (infinite distance) incur a penalty cost of 1.5 × the largest finite distance, ensuring they are avoided unless no reachable facility exists.

Parameters

Output Description

Candidate Sites (OUT_SITES): inherits all source fields + cand_id (string), reach_dem (screening: demand within radius), selected (0/1), rank (1..p for selected, 0 for unselected), gain (marginal covered demand added).

Demand Allocation (OUT_ASSIGN): inherits all source fields + facility (assigned facility label), net_cost (network distance to assigned facility, −1 if unreachable), covered (1 if within radius, 0 otherwise).

Interpretation Guide

• rank and gain tell the investment story: rank 1 is the single best site. When gain collapses (pick 4 adds a fraction of pick 1), that is the diminishing-returns point — the evidence-based answer to "how many do we need?"
• reach_dem on unselected candidates shows near-misses: a candidate with high reach that was not picked overlaps a winner — a plausible substitute if the winner's land falls through.
• Coverage vs. p-median give different answers. Run both: sites picked by both are robust. Sites picked by only one reveal sensitivity to the modelling objective.
• Fix existing facilities so the tool only places the increment. Check uncovered demand clusters: if they concentrate in one area, no candidate serves that pocket — the candidate list itself is the problem.

Academic References

Church, R. & ReVelle, C. (1974). "The Maximal Covering Location Problem." Papers of the Regional Science Association, 32(1), 101–118. DOI: 10.1007/BF01942293

Teitz, M.B. & Bart, P. (1968). "Heuristic Methods for Estimating the Generalized Vertex Median of a Weighted Graph." Operations Research, 16(5), 955–961. DOI: 10.1287/opre.16.5.955

Daskin, M.S. (1995). Network and Discrete Location: Models, Algorithms, and Applications. Wiley. DOI: 10.1002/9781118032343

ReVelle, C.S. & Eiselt, H.A. (2005). "Location Analysis: A Synthesis and Survey." European Journal of Operational Research, 165(1), 1–19. DOI: 10.1016/j.ejor.2003.11.032

Nemhauser, G.L., Wolsey, L.A. & Fisher, M.L. (1978). "An Analysis of Approximations for Maximizing Submodular Set Functions — I." Mathematical Programming, 14(1), 265–294. DOI: 10.1007/BF01588971

Hakimi, S.L. (1964). "Optimum Locations of Switching Centers and the Absolute Centers and Medians of a Graph." Operations Research, 12(3), 450–459. DOI: 10.1287/opre.12.3.450

Capacitated Allocation (Nearest with Capacity)

Processing ID: planx:capacitatedallocation

Overview

Assigns demand to fixed facilities while respecting capacity constraints — the realistic companion to Facility Adequacy (which assigns everyone to the nearest and only flags overload afterward). Each demand point is sent, in full, to the nearest facility over the street network that still has room; when its nearest is already full, it spills to the next-nearest with free capacity within the catchment. Points fitting nowhere are left uncovered. Demand status: Assigned (nearest), Spilled (farther because nearest was full), or Uncovered. Facilities report load, remaining capacity, utilisation, and status (Full / Has space / Unused).

Theoretical Background

Capacitated allocation as nearest-with-spill

The problem of assigning demand to capacitated facilities is a minimum-cost flow problem when fractional assignments are allowed (Daskin, 1995). When demand points must be assigned in whole (no splitting), the problem becomes NP-hard (it is a generalised assignment problem). PlanX implements a fast greedy heuristic: sort all eligible facility-demand pairs by cost, iterate cheapest-first, assign a demand point to the earliest facility in its sorted list that has room. This is not a global optimum — a demand point may be greedily assigned to facility A, blocking capacity that a farther demand point needed from A, when a globally better assignment would have sent the first point to B. However, the greedy approach is explainable, fast, and produces the "nearest available" answer that matches how people actually choose facilities (nearest first, spill when full).

Whole-point assignment and stranded capacity

Because demand points are not split, a facility with remaining capacity smaller than any nearby point's population may remain "Has space" yet accept no one. This is not a bug — it correctly reflects the indivisibility of whole-family or whole-building assignments. The stranded capacity is reported in the remaining field; the planning response is either to accept the inefficiency or to consider smaller-capacity facilities (which the tool cannot create but can model if the input capacity values are reduced).

Mathematical Formulation

Let D be the (facilities × demand) cost matrix, w the demand weight vector, C the facility capacity vector. The eligible set E ⊆ {1..F} × {1..N} contains all pairs with finite cost and cost ≤ c_max:

The greedy assignment iterates over eligible pairs sorted by increasing cost, with deterministic tie-breaking by demand index then facility index:

Spill status:

where nearest[d] is the index of the closest reachable facility ignoring capacity.

Parameters

Output Description

Demand: facility (string), net_cost (double, −1 = uncovered), status (Assigned / Spilled / Uncovered), nearest (nearest facility ignoring capacity), covered (0/1). Facilities: facility, capacity, assigned, remaining, utilization, status (Full / Has space / Unused).

Interpretation Guide

• "Spilled" is the diagnostic gold: people with a facility nearby but no room. Compare their cost against the cost to their nearest to see the distance penalty capacity shortages impose.
• "Uncovered" = turned away entirely: the true unmet demand once seats are counted. Facility Adequacy would have assigned them and only flagged overload afterward.
• Unused facilities while others are Full: wrong side of demand or a barrier. Relocation candidates.
• Size capacity expansions by spilled+uncovered population per catchment. Test "expand vs. build new" by editing capacities vs. adding a facility and rerunning.

Academic References

Daskin, M.S. (1995). Network and Discrete Location. Wiley. DOI: 10.1002/9781118032343

Pirkul, H. & Schilling, D.A. (1991). "The Capacitated Maximal Covering Location Problem with Backup Service." Annals of Operations Research, 18, 141–154. DOI: 10.1007/BF02023099 [Note: this is volume 18 from 1989; the Annals volume numbering was unusual.]

Current, J., Daskin, M. & Schilling, D. (2002). "Discrete Network Location Models." In: Drezner, Z. & Hamacher, H.W. (eds.), Facility Location: Applications and Theory, pp. 81–118. Springer. DOI: 10.1007/978-3-642-56082-8_3

Land-Use Allocation Optimizer

Processing ID: planx:landallocation

Overview

Assigns a land use to each parcel to maximise a multi-objective function while respecting target area constraints for each use. The objective has three terms: suitability (area-weighted per-parcel score from user-provided fields), compactness (reward for adjacent same-use parcels, per unit of shared boundary), and adjacency (reward or penalty for specific use pairs as neighbours). A lock field freezes pre-zoned parcels. The method is greedy construction (best suitability first) followed by local search of reassignments and swaps that respect targets. The output is a draft zoning map (parcels with allocated use) and a summary table (target vs. allocated area per use with mean suitability achieved).

Theoretical Background

Land-use allocation as multi-objective spatial optimisation

The land-use allocation problem is a generalisation of the quadratic assignment problem to spatial zoning: given N parcels each to be assigned one of K land uses, with per-parcel suitability scores and pairwise adjacency effects, find the assignment that maximises total suitability plus total spatial quality (compactness + desirable adjacencies) subject to area targets per use. The problem is NP-hard; the PlanX engine (engine/allocate.py) implements a fast construction heuristic with local improvement, not a global optimiser. Ligmann-Zielinska et al. (2008) provide a comprehensive review of land-use allocation optimisation methods.

Compactness as an urban design objective

Compactness is the most commonly imposed spatial objective in land-use plan optimisation because it operationalises a universal planning principle: like uses should cluster. Scattered single parcels of the same use are functionally equivalent to a zoned cluster but create fragmented urban form, longer infrastructure runs, and reduced walkability. The compactness term rewards each metre of shared boundary between same-use parcels, effectively subsidising clustering. The weight controls the suitability-compactness trade-off: at zero weight, the solver maximises pure suitability (scattered pattern); at high weight, it maximises compactness at the expense of suitability. The Pareto Front tool traces this trade-off systematically.

Adjacency rules as planning policy

Adjacency rules encode normative planning preferences: residential next to industry is undesirable (negative weight); residential next to green space is desirable (positive weight). The rules are symmetric (residential|industry = industry|residential) and optional. They operate as additions to the objective: each metre of shared boundary between two uses contributes the rule's value (positive or negative) to the total score. The rules are delimited by comma or semicolon, with the format useA|useB=value.

Mathematical Formulation

Let x_p,u ∈ {0, 1} indicate parcel p assigned to use u. The multi-objective function is:

subject to area targets (soft, via greedy construction + local search):

where a_p is parcel area, S_p,u is parcel p's suitability for use u, l_pq is shared boundary length between parcels p and q, C_u,v is the compatibility matrix (diagonal = compactness weight if > 0, off-diagonal = adjacency rule values), and T_u is the target area for use u.

Parameters