02Morphometrics - Urban Morphometrics Lab

User manual, version 0.1.2 (2026-11-16). QGIS 3.28 to 4.x. GPL-2.0-or-later. Yusuf Eminoğlu (Geophilo).

1. What the plugin does

02Morphometrics carries a morphometric study from building footprints to a documented urban-fabric typology inside QGIS. It follows the numerical-taxonomy workflow of Fleischmann et al. (2022): the space is partitioned into one tessellation cell per building; primary characters are measured at five scales (building, cell, block, street segment, street node) and linked to the cells; each character is described over a kk-order neighbourhood of the cell (contextual characters); the contextual columns are standardised, reduced by principal components and clustered; every cluster becomes a type card with a name, its share of the area and its distinctive characters.

The same chain is available in two ways: the lab dock (step by step, with charts and a styled map) and the Processing provider (one algorithm per step plus a whole-chain algorithm, usable in models and batch runs). Only qgis.core, NumPy and PyQt are required; SciPy is used for a faster nearest-neighbour search when present, with identical results without it.

Why it exists: momepy is the reference toolkit for quantitative urban morphology but lives in Python notebooks on GeoPandas, outside QGIS. QGIS tools such as PlanX, MORPHINT, UrbanMorphoBox, MorphAL and AwaP each cover one slice (single tessellation or form tools, parcel intensity, footprint download, block measures). None carries a study from footprints to a documented typology.

2. Install

  1. QGIS: Plugins > Manage and Install Plugins, search 02Morphometrics, install. Or Install from ZIP with a release zip.
  2. A toolbar button and the menu Plugins > 02Morphometrics open the lab; the Processing toolbox lists the provider 02Morphometrics.
  3. Nothing else needs to be installed: NumPy ships with QGIS, and SciPy is used for a faster nearest-neighbour search when present.

3. Units and working CRS

All measures are in metres and square metres. If the building layer is geographic, its map units are not metres, or it is Web Mercator (EPSG:3857 family, whose metres are stretched by 1/cos⁡φ1/\cos\varphi, φ\varphi the latitude), every input is reprojected to the UTM zone of the building layer's extent centre (EPSG:326xx north, 327xx south). Otherwise the input CRS is kept. Outputs are written in the working CRS, and the Data page badge, the run log and the report say which CRS was used and why.

4. The lab dock, page by page

Data

Pick the building footprints (polygons), optional street centre lines, optional study-limit polygon layer, the building id field (unique integers are used as uid; anything else is kept as src_id and 1,…,n1, \dots, n is used) and the height field (metres). The CRS badge shows the working CRS. Load demo town adds the synthetic town of section 10. KPI cards: buildings, mean footprint, total footprint, extent. Run all steps runs the whole chain with the settings of every page.

Tessellation

Mode: morphological (one Voronoi cell per building inside a limit) or enclosed (the same inside every street enclosure; needs streets). Limit: buffer distance around the footprints (default 100 m), or the limit layer. Shrink (0.4 m) and segment (0.5 m) control the seed points. KPI cards: cells, coverage ratio, cells without a building.

Characters

A searchable checklist grouped by level and category. Hover an item for its label, formula, unit and reference. Presets: Core 20, Full, Shape only, Street & network. Characters needing heights or streets are skipped (and listed in the log) when the input is missing. After the run up to 40 characters linked to the cells get a small distribution bar (2nd–98th percentile, with the median) and the cell map can be coloured by any character (graduated).

Context

Contiguity (queen: cells sharing a vertex; rook: sharing an edge), order kk (default k=3k = 3: the cell, its neighbours, their neighbours and the next ring) and the statistics. Section 7 gives the formulas.

Typology

Range of kk (kmin⁡=2k_{\min} = 2 to kmax⁡=12k_{\max} = 12), method (k-means or Ward), PCA variance (0.95). Find kk computes the diagnostics and draws silhouette, Calinski-Harabasz, Davies-Bouldin and within-cluster sum of squares curves with the chosen kk highlighted. Classify uses that kk (or the kk typed in) and fills the card gallery: colour swatch, name, share of the area, and the three most distinctive characters with up and down bars. The cell layer is styled by type with the card colours.

Report

Writes the HTML report (types, profiles, diagnostics, characters with formulas, parameters, timings, log, references), a CSV of the cells and a GeoPackage with every layer; a link opens the report in the browser.

Sprawl

Rasterises the footprints at a chosen cell size (default 10 m) and measures them around a centre (the densest cell, the footprint-weighted centroid or the map canvas centre): built share (cells whose centre lies in a footprint), patches (8-connected groups of built cells), the share of the largest patch nmax⁡/nbuiltn_{\max} / n_{\mathrm{built}} (cells of the largest patch over built cells), the density gradient β\beta (least-squares slope of the built share brb_r of ring rr against its mid-distance ρr\rho_r, br≈β0+βρrb_r \approx \beta_0 + \beta \rho_r, in percentage points per km) and the built share in eight concentric rings.

Help

A short guide, the method references and links to this manual and the repository.

Each page button runs only its own step and keeps the earlier results, so changing the context order and running the context step again does not recompute the tessellation. Every step runs in a QGIS background task with a progress bar and a Cancel button; the dock stays responsive.

5. Processing algorithms

Provider zero2morphometrics. Every algorithm copies its inputs, reprojects them to the working CRS (section 3) and writes its outputs with real field types (integers for ids, doubles for characters, NULL where a value is undefined). Parameters marked advanced are under Advanced parameters in the dialog. From Python: processing.run("zero2morphometrics:<id>", {...}).

Morphological tessellation Tessellation

Id: zero2morphometrics:morphological_tessellation

Partitions the space around building footprints into one cell per building: the Voronoi diagram of points placed along the (slightly shrunk) footprint outlines, dissolved by building and clipped to a limit. The limit is a study-area polygon layer, or the union of the footprints buffered by the buffer distance (momepy buffered_limit).

Shrink moves each footprint outline inward before seeding so adjacent buildings do not share seed points; segment is the densification step of the outlines (smaller = closer to the exact skeleton, slower).

Output fields: uid (building id), cell_id, and src_id when the id field is not a unique integer. Geographic or Web Mercator input is reprojected to its UTM zone.

ParameterDescriptionTypeDefaultNotes
BUILDINGSBuilding footprints Vector features-
ID_FIELDBuilding id field (empty: 1,…,n1, \dots, n) optionalField-
LIMITStudy limit polygons (empty: buffer) optionalVector features-
BUFFERLimit buffer around buildings (m) Number100.0Min 0.1.
SHRINKInward shrink before seeding (m) advancedNumber0.4Min 0.
SEGMENTDensification segment (m) advancedNumber0.5Min 0.01.
OUTPUTTessellation Feature sink (output)-
CELLSNumber of cellsOutput number-Returned in the result dictionary.

Enclosures (street blocks) Tessellation

Id: zero2morphometrics:enclosures

Polygons fully enclosed by the street network (and by the boundary of the study limit when one is given): the street lines are noded, unioned and polygonised (momepy enclosures). Without a limit only street-closed polygons are returned. Output field: eid.

ParameterDescriptionTypeDefaultNotes
STREETSStreet centre lines Vector features-
LIMITStudy limit polygons (optional) optionalVector features-
OUTPUTEnclosures Feature sink (output)-
ENCLOSURESNumber of enclosuresOutput number-Returned in the result dictionary.

Enclosed tessellation Tessellation

Id: zero2morphometrics:enclosed_tessellation

Morphological tessellation run separately inside every enclosure, so cell edges follow the streets. A building belongs to the enclosure that contains its point on surface; an enclosure with one building is that building's cell; an enclosure without buildings is kept as an empty cell (uid NULL).

Shrink moves each footprint outline inward before seeding so adjacent buildings do not share seed points; segment is the densification step of the outlines (smaller = closer to the exact skeleton, slower).

Output fields: uid, cell_id, eid (and src_id).

ParameterDescriptionTypeDefaultNotes
BUILDINGSBuilding footprints Vector features-
ID_FIELDBuilding id field (empty: 1,…,n1, \dots, n) optionalField-
ENCLOSURESEnclosures Vector features-
SHRINKInward shrink before seeding (m) advancedNumber0.4Min 0.
SEGMENTDensification segment (m) advancedNumber0.5Min 0.01.
OUTPUTEnclosed tessellation Feature sink (output)-
CELLSNumber of cellsOutput number-Returned in the result dictionary.

Building characters Characters

Id: zero2morphometrics:building_characters

Dimension and shape characters of every footprint, computed in the working CRS (metres). Characters that need heights are computed only when a height field is given; a value that is undefined for a footprint is NULL, never 0 or -1. The output keeps the source fields and adds uid.

Characters: see section 6.

ParameterDescriptionTypeDefaultNotes
BUILDINGSBuilding footprints Vector features-
ID_FIELDBuilding id field (empty: 1,…,n1, \dots, n) optionalField-
HEIGHT_FIELDHeight field in metres (optional) optionalField-
CHARACTERSCharacters (empty: the default set) optionalChoicethe default set25 options (the characters of this level, see section 6). Several allowed.
OUTPUTBuildings with characters Feature sink (output)-

Cell characters Characters

Id: zero2morphometrics:cell_characters

Characters of the tessellation cells and of the building neighbourhood they define. The cell layer needs a uid field linking each cell to a building (as written by the tessellation algorithms); the building id field must hold the same values (empty: 1,…,n1, \dots, n in feature order, which matches a tessellation run without an id field). Neighbour characters use queen or rook contiguity of the cells.

Characters: see section 6.

ParameterDescriptionTypeDefaultNotes
CELLSTessellation cells Vector features-
BUILDINGSBuilding footprints Vector features-
ID_FIELDBuilding id field matching the cell uid (empty: 1,…,n1, \dots, n) optionalField-
CONTIGUITYContiguity ChoicequeenOptions: queen, rook.
CHARACTERSCharacters (empty: the default set) optionalChoicethe default set15 options (the characters of this level, see section 6). Several allowed.
OUTPUTCells with characters Feature sink (output)-

Block characters Characters

Id: zero2morphometrics:block_characters

Characters of blocks (for example the output of Enclosures) and of the buildings inside them; a building belongs to the block containing its point on surface. With a cell layer the cell-weighted characters are also computed.

Characters: see section 6.

ParameterDescriptionTypeDefaultNotes
BLOCKSBlocks or enclosures Vector features-
BUILDINGSBuilding footprints Vector features-
CELLSTessellation cells (optional) optionalVector features-
CHARACTERSCharacters (empty: the default set) optionalChoiceblk_area - Block area, blk_perimeter - Block perimeter, blk_circ_compact - Block circular compactness, blk_elongation - Block elongation, blk_cwa - Compactness-weighted axis, blk_buildings - Buildings in block, blk_coverage - Block coverage, blk_cells_ha - Weighted cell countOptions: blk_area - Block area, blk_perimeter - Block perimeter, blk_circ_compact - Block circular compactness, blk_elongation - Block elongation, blk_cwa - Compactness-weighted axis, blk_buildings - Buildings in block, blk_coverage - Block coverage, blk_cells_ha - Weighted cell count. Several allowed.
OUTPUTBlocks with characters Feature sink (output)-

Street segment characters Characters

Id: zero2morphometrics:street_segment_characters

The street lines are noded at every crossing and false nodes (degree 2) are merged; each resulting segment gets the selected characters. Street-profile characters cast perpendicular ticks every 10 m10\,\mathrm{m}, each 50 m50\,\mathrm{m} long, reaching 25 m25\,\mathrm{m} on each side and need the building layer (height-to-width also needs the height field). Output fields: edge_id, node_u, node_v and the characters.

Characters: see section 6.

ParameterDescriptionTypeDefaultNotes
STREETSStreet centre lines Vector features-
BUILDINGSBuilding footprints (optional) optionalVector features-
HEIGHT_FIELDHeight field in metres (optional) optionalField-
CHARACTERSCharacters (empty: the default set) optionalChoicethe default set9 options (the characters of this level, see section 6). Several allowed.
OUTPUTStreet segments Feature sink (output)-
SEGMENTSNumber of segmentsOutput number-Returned in the result dictionary.

Street node characters Characters

Id: zero2morphometrics:street_node_characters

Nodes of the noded, false-node-merged street network with degree and the local network characters, measured in the subgraph Gr(u)G_r(u) within rr = radius topological steps of each node uu. Output fields: node_id and the characters.

Characters: see section 6.

ParameterDescriptionTypeDefaultNotes
STREETSStreet centre lines Vector features-
RADIUSLocal radius (topological steps) Number5Min 1. Max 50.
CHARACTERSCharacters (empty: the default set) optionalChoicenode_degree - Node degree, node_mean_dist - Mean node distance, node_meshedness - Local meshedness, node_gamma - Local gamma, node_cds_share - Cul-de-sac share, node_closeness - Local closenessOptions: node_degree - Node degree, node_mean_dist - Mean node distance, node_meshedness - Local meshedness, node_gamma - Local gamma, node_cds_share - Cul-de-sac share, node_closeness - Local closeness. Several allowed.
OUTPUTStreet nodes Feature sink (output)-
NODESNumber of nodesOutput number-Returned in the result dictionary.

Contextual characters Context

Id: zero2morphometrics:contextual_characters

For every selected field, statistics of the values over each feature's neighbourhood Nk(i)N_k(i): the feature itself and every feature within kk = order steps of queen or rook contiguity (kk-order contiguity of the tessellation in the momepy workflow). Each statistic is written as field_suffix:

Run it on the cell layer after the character algorithms.

ParameterDescriptionTypeDefaultNotes
INPUTCells (or any polygon layer) Vector features-
FIELDSFields Field-
CONTIGUITYContiguity ChoicequeenOptions: queen, rook.
ORDERNeighbourhood order kk (topological steps) Number3Min 1. Max 10.
STATSStatistics Choicemean, interquartile range, Simpson diversityOptions: mean, median, interquartile range, interdecile range, Simpson diversity, Theil index, Gini coefficient. Several allowed.
OUTPUTContextual characters Feature sink (output)-

Urban fabric typology (classify) Typology

Id: zero2morphometrics:typology

Clusters the features (normally tessellation cells with contextual characters) into urban fabric types and adds cluster (1,…,k1, \dots, k, types numbered by decreasing size) and cluster_name, a short plain-English name read from the type's median characters.

The clustering columns are standardised (z-scores (x−xˉ)/s(x - \bar x)/s, or robust (x−x~)/(IQR/1.349)(x - \tilde x) / (\mathrm{IQR} / 1.349), section 8), missing values set to the column centre, and reduced by principal components to the share of variance given. With k=0k = 0 the number of types is chosen over kmin⁡,…,kmax⁡k_{\min}, \dots, k_{\max}: elbow of the within-cluster sum of squares over the tested kk (Kneedle, Satopaa et al. 2011: after min-max scaling both axes, the kk farthest below the chord joining the first and last point, eq. (21)); ties to the smaller kk. Silhouette, Calinski-Harabasz and Davies-Bouldin are reported alongside to judge the choice. k-means uses k-means++ seeding and 10 restarts; Ward is agglomerative on micro-clusters for large layers. Results are deterministic for a fixed seed.

ParameterDescriptionTypeDefaultNotes
INPUTCells with characters Vector features-
FIELDSClustering fields (empty: every contextual column, else every character) optionalField-
KNumber of types kk (0: choose from the diagnostics) Number0Min 0. Max 30.
K_MINSmallest kk tested, kmin⁡k_{\min} advancedNumber2Min 2. Max 30.
K_MAXLargest kk tested, kmax⁡k_{\max} advancedNumber12Min 2. Max 30.
METHODMethod Choicek-meansOptions: k-means, Ward.
STANDARDISEStandardisation advancedChoicez-scoresOptions: z-scores, robust.
PCA_VARIANCEVariance share kept by PCA, τ\tau advancedNumber0.95Min 0.5. Max 1.
SEEDRandom seed advancedNumber42Min 0.
OUTPUTTypology Feature sink (output)-
CHOSEN_KNumber of typesOutput number-Returned in the result dictionary.
SILHOUETTESilhouette sˉ\bar s of the chosen kkOutput number-Returned in the result dictionary.

Urban morphometrics lab (whole chain) Typology

Id: zero2morphometrics:urban_morphometrics_lab

The whole numerical-taxonomy chain of Fleischmann et al. (2022) in one run: morphological or enclosed tessellation, primary characters at five scales (building, cell, block, street segment, street node; block, street and node characters need the street layer) linked to the cells, contextual characters over kk-order contiguity, standardisation and PCA, the number of types from the diagnostics, k-means or Ward clustering, and type names. The same function runs the dock's Run all steps.

Outputs: cells with every primary and contextual character, cluster, cluster_name and cluster_margin; buildings with their characters and cluster; with streets also the noded street segments, nodes and blocks; optionally a self-contained HTML report.

The clustering columns are standardised (z-scores (x−xˉ)/s(x - \bar x)/s, or robust (x−x~)/(IQR/1.349)(x - \tilde x) / (\mathrm{IQR} / 1.349), section 8), missing values set to the column centre, and reduced by principal components to the share of variance given. With k=0k = 0 the number of types is chosen over kmin⁡,…,kmax⁡k_{\min}, \dots, k_{\max}: elbow of the within-cluster sum of squares over the tested kk (Kneedle, Satopaa et al. 2011: after min-max scaling both axes, the kk farthest below the chord joining the first and last point, eq. (21)); ties to the smaller kk. Silhouette, Calinski-Harabasz and Davies-Bouldin are reported alongside to judge the choice. k-means uses k-means++ seeding and 10 restarts; Ward is agglomerative on micro-clusters for large layers. Results are deterministic for a fixed seed.

ParameterDescriptionTypeDefaultNotes
BUILDINGSBuilding footprints Vector features-
STREETSStreet centre lines (optional) optionalVector features-
LIMITStudy limit polygons (optional) optionalVector features-
ID_FIELDBuilding id field (empty: 1,…,n1, \dots, n) optionalField-
HEIGHT_FIELDHeight field in metres (optional) optionalField-
TESS_MODETessellation ChoiceMorphologicalOptions: Morphological, Enclosed (needs streets).
BUFFERLimit buffer around buildings (m) advancedNumber100.0Min 0.1.
SHRINKInward shrink before seeding (m) advancedNumber0.4Min 0.
SEGMENTDensification segment (m) advancedNumber0.5Min 0.01.
PRESETCharacters ChoiceDefault setOptions: Default set, Core 20, Full, Shape only, Street & network.
CONTIGUITYContiguity advancedChoicequeenOptions: queen, rook.
ORDERContext order kk (topological steps) Number3Min 1. Max 10.
STATSContextual statistics advancedChoicemean, interquartile range, Simpson diversityOptions: mean, median, interquartile range, interdecile range, Simpson diversity, Theil index, Gini coefficient. Several allowed.
KNumber of types kk (0: choose from the diagnostics) Number0Min 0. Max 30.
K_MINSmallest kk tested, kmin⁡k_{\min} advancedNumber2Min 2. Max 30.
K_MAXLargest kk tested, kmax⁡k_{\max} advancedNumber12Min 2. Max 30.
METHODMethod Choicek-meansOptions: k-means, Ward.
STANDARDISEStandardisation advancedChoicez-scoresOptions: z-scores, robust.
PCA_VARIANCEVariance share kept by PCA, τ\tau advancedNumber0.95Min 0.5. Max 1.
SEEDRandom seed advancedNumber42Min 0.
CELLSTypology (tessellation cells) Feature sink (output)-
BUILDINGS_OUTBuildings with characters Feature sink (output)-
STREETS_OUTStreet segments optionalFeature sink (output)-
NODES_OUTStreet nodes optionalFeature sink (output)-
BLOCKS_OUTBlocks optionalFeature sink (output)-
REPORTHTML report optionalFile (output)-
CHOSEN_KNumber of typesOutput number-Returned in the result dictionary.
CELL_COUNTNumber of cellsOutput number-Returned in the result dictionary.

Typology report (HTML) Report

Id: zero2morphometrics:html_report

A self-contained HTML report (inline CSS and SVG, no external resources) of a classified cell layer: one card per type with its distinctive characters (median robust z-scores ζc,f\zeta_{c,f}, eq. (26)), a type-profile heat table, the formula, unit and reference of every character found in the layer, and the full references. Features without a cluster value are left out. For the diagnostics curves and run log, use the HTML report output of the whole-chain algorithm.

ParameterDescriptionTypeDefaultNotes
INPUTClassified cells Vector features-
CLUSTER_FIELDCluster field Fieldcluster
BUILDINGSBuildings (optional, for the count) optionalVector features-
NOTENote shown under the title optionalText-
OUTPUTHTML report File (output)-
TYPESNumber of typesOutput number-Returned in the result dictionary.

Chaining the step algorithms

import processing
t = processing.run("zero2morphometrics:morphological_tessellation",
                   {"BUILDINGS": b, "ID_FIELD": "bid", "OUTPUT": "TEMPORARY_OUTPUT"})["OUTPUT"]
c = processing.run("zero2morphometrics:cell_characters",
                   {"CELLS": t, "BUILDINGS": b, "ID_FIELD": "bid", "OUTPUT": "TEMPORARY_OUTPUT"})["OUTPUT"]
x = processing.run("zero2morphometrics:contextual_characters",
                   {"INPUT": c, "FIELDS": ["cell_area", "cell_coverage", "nbr_distance"],
                    "ORDER": 3, "STATS": [0, 2, 4], "OUTPUT": "TEMPORARY_OUTPUT"})["OUTPUT"]
r = processing.run("zero2morphometrics:typology", {"INPUT": x, "K": 0, "OUTPUT": "TEMPORARY_OUTPUT"})
print(r["CHOSEN_K"], r["SILHOUETTE"])

The cell layer links to the buildings through uid. Run the tessellation and the cell characters with the same building id field (or both without one, which numbers the buildings 1,…,n1, \dots, n in feature order). The statistics indices are 0 mean, 1 median, 2 IQR, 3 IDR, 4 Simpson, 5 Theil, 6 Gini.

6. Characters

63 primary characters. Default marks the set used when nothing is selected; characters that need heights or streets are used only when that input is given. Every value that is undefined for a unit (for example the orientation of a circle) is NULL, never 0 or -1.

Constants: storey height for floor area 3 m3\,\mathrm{m}; corner threshold ε=10∘\varepsilon = 10^\circ (momepy corners, squareness); centroid-corner threshold ε=5∘\varepsilon = 5^\circ; building neighbourhood for adjacency, interbuilding distance and reach N3(i)N_3(i), 3 topological steps; street profile ticks every 10 m10\,\mathrm{m}, 50 m50\,\mathrm{m} long, 25 m25\,\mathrm{m} on each side; node radius r=5r = 5 steps.

Notation

AA is the footprint area and PP its perimeter over all rings (exterior and holes); HH the height and V=AHV = AH the volume. MRR is the minimum rotated rectangle of the convex hull, with length lMRR≥l_{\mathrm{MRR}} \ge width wMRRw_{\mathrm{MRR}}, area AMRRA_{\mathrm{MRR}} and perimeter PMRR=2(lMRR+wMRR)P_{\mathrm{MRR}} = 2(l_{\mathrm{MRR}} + w_{\mathrm{MRR}}); AhullA_{\mathrm{hull}} is the convex hull area. SEC is the smallest enclosing circle, radius rSECr_{\mathrm{SEC}}, and LAL=2rSEC\mathrm{LAL} = 2 r_{\mathrm{SEC}} the longest axis length. θv∈[0∘,180∘]\theta_v \in [0^\circ, 180^\circ] is the angle between the two edges meeting at vertex vv; a vertex is a corner when θv≤180∘−ε\theta_v \le 180^\circ - \varepsilon. N(i)N(i) is the set of contiguity neighbours of cell ii and Nk(i)N_k(i) the cells within kk topological steps, focal cell included; BiB_i is the footprint of cell ii. For streets, LL is the segment length and Gr(u)G_r(u) the subgraph of the nodes within rr steps of node uu, with vv nodes and ee edges. An undefined value (zero denominator, missing input) is NULL.

Key equations

ERI=AAMRR  PMRRP(1)\mathrm{ERI} = \sqrt{\frac{A}{A_{\mathrm{MRR}}}}\;\frac{P_{\mathrm{MRR}}}{P} \tag{1} Ccirc=Aπ rSEC2(2)C_{\mathrm{circ}} = \frac{A}{\pi\, r_{\mathrm{SEC}}^{2}} \tag{2} Csq=(4AP)2(3)C_{\mathrm{sq}} = \left(\frac{4\sqrt{A}}{P}\right)^{2} \tag{3} SI=A/πLAL/2=A/πrSEC(4)\mathrm{SI} = \frac{\sqrt{A/\pi}}{\mathrm{LAL}/2} = \frac{\sqrt{A/\pi}}{r_{\mathrm{SEC}}} \tag{4} Df=2ln⁡(P/4)ln⁡A,A>1 m2(5)D_f = \frac{2 \ln (P/4)}{\ln A}, \qquad A > 1\,\mathrm{m^2} \tag{5} FF=PH+AV2/3(6)\mathrm{FF} = \frac{P H + A}{V^{2/3}} \tag{6} CWA=LAL(4π−16AP2)(7)\mathrm{CWA} = \mathrm{LAL} \left(\frac{4}{\pi} - \frac{16 A}{P^{2}}\right) \tag{7}

where, in (1) to (7), the symbols are those of the notation above; (7) is applied to blocks, with AA, PP and LAL\mathrm{LAL} of the enclosure.

wˉ=1m∑t=1m(dtL+dtR),dtL,R={distance to the first facade hitif one lies within 25 m25 motherwise(8)\bar w = \frac{1}{m} \sum_{t=1}^{m} \left(d^{\mathrm{L}}_t + d^{\mathrm{R}}_t\right), \qquad d^{\mathrm{L,R}}_t = \begin{cases} \text{distance to the first facade hit} & \text{if one lies within } 25\,\mathrm{m} \\ 25\,\mathrm{m} & \text{otherwise} \end{cases} \tag{8}

where mm is the number of ticks of the segment (placed at 5,15,25,… m5, 15, 25, \dots\,\mathrm{m} along it, perpendicular to it) and dtLd^{\mathrm{L}}_t, dtRd^{\mathrm{R}}_t the left and right distances of tick tt.

M(u)=e−v+12v−5(9)M(u) = \frac{e - v + 1}{2v - 5} \tag{9} γ(u)=e3(v−2)(10)\gamma(u) = \frac{e}{3(v - 2)} \tag{10} C(u)=v−1∑w∈G5(u)dL(u,w)(11)C(u) = \frac{v - 1}{\sum_{w \in G_5(u)} d_L(u, w)} \tag{11}

where vv and ee are the numbers of nodes and edges of the local subgraph G5(u)G_5(u) (nodes within 5 topological steps of uu and the edges between them), and dL(u,w)d_L(u, w) is the metric shortest-path length from uu to ww inside G5(u)G_5(u). Both MM and γ\gamma are NULL for v≤2v \le 2.

Building (25)

KeyLabelCategoryFormulaUnitReferenceDefaultNeeds
bld_areaFootprint areadimensionAAm2\mathrm{m^2}Fleischmann et al. 2021yes
bld_perimeterPerimeterdimensionPP (all rings)m\mathrm{m}Fleischmann et al. 2021yes
bld_lalLongest axis lengthdimensionLAL=2 rSEC\mathrm{LAL} = 2\,r_{\mathrm{SEC}} of the convex hullm\mathrm{m}Fleischmann 2019yes
bld_court_areaCourtyard areadimensionAcourt=∑Ahole=Aext−AA_{\mathrm{court}} = \sum A_{\mathrm{hole}} = A_{\mathrm{ext}} - Am2\mathrm{m^2}Schirmer & Axhausen 2016yes
bld_heightHeightdimensionHH (input field)m\mathrm{m}Schirmer & Axhausen 2016yesheight
bld_volumeVolumedimensionV=A HV = A\,Hm3\mathrm{m^3}Fleischmann et al. 2021yesheight
bld_floor_areaFloor areadimensionA⌊H/3 m⌋A \left\lfloor H / 3\,\mathrm{m} \right\rfloorm2\mathrm{m^2}Fleischmann et al. 2021yesheight
bld_eriEquivalent rectangular indexshapeA/AMRR  PMRR/P\sqrt{A / A_{\mathrm{MRR}}}\; P_{\mathrm{MRR}} / P, eq. (1)ratioBasaraner & Cetinkaya 2017yes
bld_circ_compactCircular compactnessshapeA/(π rSEC2)A / (\pi\, r_{\mathrm{SEC}}^{2}), eq. (2)ratioDibble et al. 2019yes
bld_sq_compactSquare compactnessshape(4A/P)2(4\sqrt{A} / P)^{2}, eq. (3)ratioFeliciotti 2018yes
bld_convexityConvexityshapeA/AhullA / A_{\mathrm{hull}}ratioDibble et al. 2019yes
bld_rectangularityRectangularityshapeA/AMRRA / A_{\mathrm{MRR}}ratioDibble et al. 2019yes
bld_elongationElongationshapewMRR/lMRRw_{\mathrm{MRR}} / l_{\mathrm{MRR}}ratioGil et al. 2012yes
bld_shape_indexShape indexshapeA/π / (0.5 LAL)\sqrt{A / \pi} \,/\, (0.5\,\mathrm{LAL}), eq. (4)ratioFleischmann et al. 2022yes
bld_fractalFractal dimensionshape2ln⁡(P/4)/ln⁡A2 \ln(P/4) / \ln A for A>1 m2A > 1\,\mathrm{m^2}, eq. (5)ratioMcGarigal & Marks 1995yes
bld_cornersCornersshape#{v:θv≤180∘−ε}\#\{v : \theta_v \le 180^\circ - \varepsilon\} over exterior vertices, ε=10∘\varepsilon = 10^\circcountSteiniger et al. 2008yes
bld_squarenessSquarenessshapemean⁡c ∣90∘−θc∣\operatorname{mean}_{c}\, \lvert 90^\circ - \theta_c \rvert over the corners cc (ε=10∘\varepsilon = 10^\circ)∘{}^\circDibble et al. 2019yes
bld_cc_meanCentroid-corner distance meanshapedˉ=mean⁡c ∥c−g∥\bar d = \operatorname{mean}_{c}\, \lVert \mathbf{c} - \mathbf{g} \rVert, g\mathbf{g} the centroid, corners with ε=5∘\varepsilon = 5^\circm\mathrm{m}Schirmer & Axhausen 2016yes
bld_cc_stdCentroid-corner distance deviationshapeσd=mean⁡c(∥c−g∥−dˉ)2\sigma_d = \sqrt{\operatorname{mean}_{c} (\lVert \mathbf{c} - \mathbf{g} \rVert - \bar d)^2} (population), ε=5∘\varepsilon = 5^\circm\mathrm{m}Schirmer & Axhausen 2016yes
bld_court_indexCourtyard indexshapeAcourt/AA_{\mathrm{court}} / AratioSchirmer & Axhausen 2016yes
bld_facade_ratioFacade ratioshapeA/PA / Pm\mathrm{m}Schirmer & Axhausen 2016yes
bld_form_factorForm factorshape(PH+A)/V2/3(P H + A) / V^{2/3}, eq. (6)ratioBourdic et al. 2012yesheight
bld_vfrVolume to facade ratioshapeV/(PH)V / (P H)m\mathrm{m}Schirmer & Axhausen 2016yesheight
bld_orientationOrientationdistributionmin⁡(α mod 90∘, 90∘−α mod 90∘)∈[0∘,45∘]\min(\alpha \bmod 90^\circ,\ 90^\circ - \alpha \bmod 90^\circ) \in [0^\circ, 45^\circ], α\alpha the direction of the MRR long side∘{}^\circSchirmer & Axhausen 2016yes
bld_shared_wallsShared walls ratiodistribution∑jLij/P\sum_j L_{ij} / P, LijL_{ij} the boundary length shared with touching building jjratioHamaina et al. 2012yes

Tessellation cell and neighbourhood (15)

KeyLabelCategoryFormulaUnitReferenceDefaultNeeds
cell_areaCell areadimensionAcellA_{\mathrm{cell}}m2\mathrm{m^2}Fleischmann et al. 2020yes
cell_circ_compactCell circular compactnessshapeAcell/(π rSEC2)A_{\mathrm{cell}} / (\pi\, r_{\mathrm{SEC}}^{2})ratioDibble et al. 2019yes
cell_elongationCell elongationshapewMRR/lMRRw_{\mathrm{MRR}} / l_{\mathrm{MRR}} of the cellratioGil et al. 2012yes
cell_orientationCell orientationdistributionmin⁡(α mod 90∘, 90∘−α mod 90∘)∈[0∘,45∘]\min(\alpha \bmod 90^\circ,\ 90^\circ - \alpha \bmod 90^\circ) \in [0^\circ, 45^\circ], α\alpha the direction of the cell MRR long side∘{}^\circFleischmann et al. 2022yes
cell_alignmentCell-building alignmentdistribution∣obld−ocell∣\lvert o_{\mathrm{bld}} - o_{\mathrm{cell}} \rvert, oo the orientation∘{}^\circFleischmann et al. 2022yes
cell_coverageCoverage ratiointensityAbld/AcellA_{\mathrm{bld}} / A_{\mathrm{cell}} (0 for a cell without a building)ratioSchirmer & Axhausen 2016yes
cell_farFloor area ratiointensityAbld⌊H/3 m⌋/AcellA_{\mathrm{bld}} \left\lfloor H / 3\,\mathrm{m} \right\rfloor / A_{\mathrm{cell}} (0 for a cell without a building)ratioSchirmer & Axhausen 2016yesheight
cell_neighboursNeighbouring cellsconnectivity∣N(i)∣\lvert N(i) \rvert (contiguity)countHermosilla et al. 2012yes
cell_coveredCovered areaintensity∑j∈{i}∪N(i)Acell,j\sum_{j \in \{i\} \cup N(i)} A_{\mathrm{cell},j}m2\mathrm{m^2}Fleischmann et al. 2022yes
cell_reach_nReached cellsintensity∣N3(i)∣\lvert N_3(i) \rvert, cells within 3 steps, focal cell includedcountFleischmann et al. 2022yes
cell_reach_areaReached areaintensity∑j∈N3(i)Acell,j\sum_{j \in N_3(i)} A_{\mathrm{cell},j}m2\mathrm{m^2}Fleischmann et al. 2022yes
nbr_alignmentAlignment with neighboursdistributionmean⁡j∈N(i)∣oi−oj∣\operatorname{mean}_{j \in N(i)} \lvert o_i - o_j \rvert over the neighbours jj with a building∘{}^\circGil et al. 2012yes
nbr_distanceNeighbour distancedistributionmean⁡j∈N(i)d(Bi,Bj)\operatorname{mean}_{j \in N(i)} d(B_i, B_j), dd the footprint-to-footprint distancem\mathrm{m}Schirmer & Axhausen 2016yes
nbr_mibdMean interbuilding distancedistributionmean⁡a,bd(Ba,Bb)\operatorname{mean}_{a, b} d(B_a, B_b) over all contiguous pairs a,b∈N3(i)a, b \in N_3(i)m\mathrm{m}Hamaina et al. 2012yes
nbr_adjacencyBuilding adjacencydistributions3(i)/n3(i)s_3(i) / n_3(i): joined structures (groups of touching footprints) over buildings in N3(i)N_3(i)ratioVanderhaegen & Canters 2017yes

Block (from enclosures; needs streets) (8)

KeyLabelCategoryFormulaUnitReferenceDefaultNeeds
blk_areaBlock areadimensionAblockA_{\mathrm{block}} (enclosure)m2\mathrm{m^2}Fleischmann et al. 2022yesstreets
blk_perimeterBlock perimeterdimensionPblockP_{\mathrm{block}}m\mathrm{m}Fleischmann et al. 2022yesstreets
blk_circ_compactBlock circular compactnessshapeAblock/(π rSEC2)A_{\mathrm{block}} / (\pi\, r_{\mathrm{SEC}}^{2})ratioDibble et al. 2019yesstreets
blk_elongationBlock elongationshapewMRR/lMRRw_{\mathrm{MRR}} / l_{\mathrm{MRR}} of the blockratioGil et al. 2012yesstreets
blk_cwaCompactness-weighted axisshapeLAL (4/π−16A/P2)\mathrm{LAL}\,(4/\pi - 16 A / P^{2}), eq. (7)m\mathrm{m}Dibble et al. 2019yesstreets
blk_buildingsBuildings in blockintensitynbldn_{\mathrm{bld}}: footprints whose point on surface lies in the blockcountFleischmann et al. 2022yesstreets
blk_coverageBlock coverageintensity∑Abld/Ablock\sum A_{\mathrm{bld}} / A_{\mathrm{block}}ratioSchirmer & Axhausen 2016yesstreets
blk_cells_haWeighted cell countintensityncell/(Ablock/104 m2)n_{\mathrm{cell}} / (A_{\mathrm{block}} / 10^{4}\,\mathrm{m^2}), cells in the block per hectareha−1\mathrm{ha^{-1}}Fleischmann et al. 2022yesstreets

Street segment (needs streets) (9)

KeyLabelCategoryFormulaUnitReferenceDefaultNeeds
str_lengthSegment lengthdimensionLLm\mathrm{m}Fleischmann et al. 2022yesstreets
str_linearityLinearityshape∥pend−pstart∥/L\lVert \mathbf{p}_{\mathrm{end}} - \mathbf{p}_{\mathrm{start}} \rVert / LratioAraldi & Fusco 2019yesstreets
str_widthStreet profile widthdimensionwˉ=1m∑t(dtL+dtR)\bar w = \frac{1}{m} \sum_{t} (d^{\mathrm{L}}_t + d^{\mathrm{R}}_t), eq. (8)m\mathrm{m}Araldi & Fusco 2019yesstreets
str_width_devProfile width deviationdiversityσw\sigma_w (population) of the tick widths wt=dtL+dtRw_t = d^{\mathrm{L}}_t + d^{\mathrm{R}}_tm\mathrm{m}Araldi & Fusco 2019yesstreets
str_opennessProfile opennessintensity#{tick sides without a facade within 25 m}/2m\#\{\text{tick sides without a facade within } 25\,\mathrm{m}\} / 2mratioAraldi & Fusco 2019yesstreets
str_heightProfile heightdimensionhˉ\bar h: mean height of the facades hit by the ticksm\mathrm{m}Araldi & Fusco 2019yesstreets, height
str_hwHeight-to-width ratioshapehˉ/wˉ\bar h / \bar wratioAraldi & Fusco 2019yesstreets, height
str_buildingsBuildings alongintensitynbldn_{\mathrm{bld}}: buildings whose nearest segment it iscountFleischmann et al. 2022yesstreets
str_reach_cellsCells reachedintensityncelln_{\mathrm{cell}}: cells attached to the segmentcountFleischmann et al. 2022yesstreets

Street node (needs streets) (6)

KeyLabelCategoryFormulaUnitReferenceDefaultNeeds
node_degreeNode degreeconnectivitydeg⁡(u)\deg(u): number of segment ends at the nodecountPorta et al. 2006yesstreets
node_mean_distMean node distancedimension1deg⁡(u)∑e∋uLe\frac{1}{\deg(u)} \sum_{e \ni u} L_em\mathrm{m}Fleischmann et al. 2022yesstreets
node_meshednessLocal meshednessconnectivity(e−v+1)/(2v−5)(e - v + 1) / (2v - 5) in G5(u)G_5(u), eq. (9)ratioBuhl et al. 2006; Feliciotti 2018yesstreets
node_gammaLocal gammaconnectivitye/(3(v−2))e / (3(v - 2)) in G5(u)G_5(u), eq. (10)ratioKansky 1963yesstreets
node_cds_shareCul-de-sac shareconnectivity#{w∈G5(u):deg⁡(w)=1}/v\#\{w \in G_5(u) : \deg(w) = 1\} / v, deg⁡\deg taken in the whole networkratioBoeing 2017yesstreets
node_closenessLocal closenessconnectivity(v−1)/∑w∈G5(u)dL(u,w)(v - 1) / \sum_{w \in G_5(u)} d_L(u, w), eq. (11)m−1\mathrm{m^{-1}}Porta et al. 2006yesstreets

Presets

How non-cell characters reach the cells: building characters through the cell's uid; block characters through the enclosure containing the building; street-segment characters through the segment nearest to the building (or to the cell for empty cells); node characters through that segment's end nearer to the building.

7. Contextual characters

For every character xx and every cell ii, the neighbourhood Nk(i)N_k(i) is the cell itself and every cell reachable in at most kk steps of queen (shared vertex) or rook (shared edge) contiguity:

Nk(i)={i}∪{ j:δ(i,j)≤k }(12)N_k(i) = \{i\} \cup \{\, j : \delta(i, j) \le k \,\} \tag{12}

where δ(i,j)\delta(i, j) is the number of contiguity steps on the shortest path from ii to jj. The statistics are computed over the nn non-NULL values xjx_j, j∈Nk(i)j \in N_k(i), and written as <key>_<suffix>. QpQ_p is the pp-th percentile with linear interpolation and μ=xˉ\mu = \bar x the neighbourhood mean.

IQR=Q75−Q25,IDR=Q90−Q10(13)\mathrm{IQR} = Q_{75} - Q_{25}, \qquad \mathrm{IDR} = Q_{90} - Q_{10} \tag{13} DSimpson=1−∑b=1Bpb2(14)D_{\mathrm{Simpson}} = 1 - \sum_{b=1}^{B} p_b^{2} \tag{14}

where pbp_b is the share of the neighbourhood values that fall in bin bb and the B≤7B \le 7 bins are cut at the 7-quantiles of xx over the whole layer (coinciding cut points are merged, so BB can be smaller than 7).

T=1n∑j=1nxjμln⁡xjμ(15)T = \frac{1}{n} \sum_{j=1}^{n} \frac{x_j}{\mu} \ln \frac{x_j}{\mu} \tag{15} G=∑j=1n∑l=1n∣xj−xl∣2n2μ=2∑r=1nr x(r)n∑jxj−n+1n(16)G = \frac{\sum_{j=1}^{n} \sum_{l=1}^{n} \lvert x_j - x_l \rvert}{2 n^{2} \mu} = \frac{2 \sum_{r=1}^{n} r\, x_{(r)}}{n \sum_{j} x_j} - \frac{n + 1}{n} \tag{16}

where x(r)x_{(r)} is the rr-th smallest value; 0ln⁡0=00 \ln 0 = 0 in (15). TT and GG are NULL when a neighbourhood holds a negative value, TT also when μ=0\mu = 0; G=0G = 0 when all values are 0. The second form of (16) is the one computed.

StatisticSuffixFormulaReference
mean_meanxˉ=1n∑jxj\bar x = \frac{1}{n}\sum_j x_jFleischmann et al. 2022
median_medQ50Q_{50}Fleischmann et al. 2022
interquartile range_iqrQ75−Q25Q_{75} - Q_{25} (linear interpolation), eq. (13)Fleischmann et al. 2022
interdecile range_idrQ90−Q10Q_{90} - Q_{10}, eq. (13)Fleischmann et al. 2022
Simpson diversity_simp1−∑bpb21 - \sum_{b} p_b^{2} over at most 7 quantile bins of xx over the whole layer, eq. (14)Simpson 1949
Theil index_theil1n∑jxjμln⁡xjμ\frac{1}{n} \sum_j \frac{x_j}{\mu} \ln \frac{x_j}{\mu}, μ\mu the mean; non-negative values, eq. (15)Theil 1967
Gini coefficient_gini∑j,l∣xj−xl∣/(2n2μ)\sum_{j,l} \lvert x_j - x_l \rvert / (2 n^{2} \mu); non-negative values, eq. (16)Gini 1912

Defaults: queen contiguity, order k=3k = 3, statistics mean, IQR and Simpson. Characters that are constant or empty on the data are kept in the layers but not used for clustering (the log lists them).

8. Clustering and typology

  1. Columns. Every varying contextual column (or, without context, every varying primary character).
  2. Standardisation. z-scores, eq. (17), by default; robust uses eq. (18). NULL becomes the column centre (0 after scaling); a constant column becomes 0. zif=xif−xˉfsf,sf=1n∑i(xif−xˉf)2(17)z_{if} = \frac{x_{if} - \bar x_f}{s_f}, \qquad s_f = \sqrt{\tfrac{1}{n} \textstyle\sum_i (x_{if} - \bar x_f)^2} \tag{17} zifrob=xif−x~fIQRf/1.349(18)z^{\mathrm{rob}}_{if} = \frac{x_{if} - \tilde x_f}{\mathrm{IQR}_f / 1.349} \tag{18} where xifx_{if} is the value of column ff for cell ii, xˉf\bar x_f, sfs_f the column mean and population standard deviation, x~f\tilde x_f the column median and IQRf=Q75−Q25\mathrm{IQR}_f = Q_{75} - Q_{25}; 1.3491.349 makes IQR/1.349\mathrm{IQR}/1.349 equal to ss for normal data. When IQRf=0\mathrm{IQR}_f = 0 the robust scale falls back to sfs_f.
  3. PCA. Singular value decomposition Zc=UΣV⊤Z_c = U \Sigma V^{\top} of the centred scores; the leading qq components holding the chosen share of variance τ=0.95\tau = 0.95 are kept; each component's largest loading is made positive so results are reproducible. q=min⁡{q′:∑c=1q′λc/∑cλc≥τ}(19)q = \min \Big\{ q' : \sum_{c=1}^{q'} \lambda_c \Big/ \sum_{c} \lambda_c \ge \tau \Big\} \tag{19} where λc=σc2\lambda_c = \sigma_c^{2} is the squared cc-th singular value (the variance of component cc up to a constant).
  4. Choosing kk. For every k∈{kmin⁡,…,kmax⁡}k \in \{k_{\min}, \dots, k_{\max}\} the method is fitted and four diagnostics are recorded. Rule: elbow of the within-cluster sum of squares over the tested kk (Kneedle, Satopaa et al. 2011: after min-max scaling both axes, the kk farthest below the chord joining the first and last point, eq. (21)); ties to the smaller kk. Silhouette, Calinski-Harabasz and Davies-Bouldin are reported alongside to judge the choice. When more than 10 000 cells are present, the curves are read on a seeded subsample of 10 000 cells; the final fit uses every cell. Wk=∑c=1k∑i∈c∥yi−μc∥2(20)W_k = \sum_{c=1}^{k} \sum_{i \in c} \lVert \mathbf{y}_i - \boldsymbol{\mu}_c \rVert^{2} \tag{20} k∗=arg⁡max⁡k[(1−k~)−W~k],k~=k−kmin⁡kmax⁡−kmin⁡,W~k=Wk−min⁡Wmax⁡W−min⁡W(21)k^{*} = \arg\max_{k} \left[ (1 - \tilde k) - \tilde W_k \right], \qquad \tilde k = \frac{k - k_{\min}}{k_{\max} - k_{\min}}, \quad \tilde W_k = \frac{W_k - \min W}{\max W - \min W} \tag{21} where yi\mathbf{y}_i is the PCA score vector of cell ii, μc\boldsymbol{\mu}_c the centroid of cluster cc, and min⁡W\min W, max⁡W\max W are taken over the tested kk; for the decreasing curve WkW_k, (1−k~)−W~k(1 - \tilde k) - \tilde W_k is proportional to the distance below the chord from the first to the last point.
  5. Fit. k-means with k-means++ seeding and 10 restarts (lowest inertia WkW_k kept), or Ward agglomerative clustering (exact up to 2 000 units, on 300 k-means micro-clusters above). Types are numbered 1,…,k1, \dots, k by decreasing size. A fixed seed gives identical results.
  6. Cards. For each type: number of cells, share of the total cell area, median of every character, median robust z-score of every character (the profile, eq. (26)), the five characters with the largest ∣ζc,f∣\lvert \zeta_{c,f} \rvert (distinctive), a name from fixed rules on coverage, height, footprint size, shared walls, elongation and alignment (for example Detached low-rise houses, High-rise point towers in open space), and a one-sentence description. ζc,f=median⁡i∈cxif−x~fIQRf/1.349(26)\zeta_{c,f} = \operatorname*{median}_{i \in c} \frac{x_{if} - \tilde x_f}{\mathrm{IQR}_f / 1.349} \tag{26} where x~f\tilde x_f and IQRf\mathrm{IQR}_f are taken over all cells (scale sfs_f when IQRf=0\mathrm{IQR}_f = 0).
DiagnosticFormulaBetterReference
Within-cluster sum of squaresWk=∑c∑i∈c∥yi−μc∥2W_k = \sum_{c} \sum_{i \in c} \lVert \mathbf{y}_i - \boldsymbol{\mu}_c \rVert^{2}, eq. (20)elbowMacQueen 1967; Satopaa et al. 2011
Silhouettesˉ=1n∑isi\bar s = \frac{1}{n}\sum_i s_i, eq. (22) (seeded sample of 4 000)higherRousseeuw 1987
Calinski-HarabaszB/(k−1)Wk/(n−k)\dfrac{B / (k - 1)}{W_k / (n - k)}, eq. (23)higherCalinski & Harabasz 1974
Davies-Bouldin1k∑cmax⁡c′≠cSc+Sc′∥μc−μc′∥\frac{1}{k} \sum_{c} \max_{c' \ne c} \frac{S_c + S_{c'}}{\lVert \boldsymbol{\mu}_c - \boldsymbol{\mu}_{c'} \rVert}, eq. (24)lowerDavies & Bouldin 1979
si=bi−aimax⁡(ai,bi),ai=1∣c(i)∣−1∑j∈c(i), j≠i∥yi−yj∥,bi=min⁡c≠c(i)1∣c∣∑j∈c∥yi−yj∥(22)s_i = \frac{b_i - a_i}{\max(a_i, b_i)}, \qquad a_i = \frac{1}{\lvert c(i) \rvert - 1} \sum_{j \in c(i),\, j \ne i} \lVert \mathbf{y}_i - \mathbf{y}_j \rVert, \quad b_i = \min_{c \ne c(i)} \frac{1}{\lvert c \rvert} \sum_{j \in c} \lVert \mathbf{y}_i - \mathbf{y}_j \rVert \tag{22} CH=B/(k−1)Wk/(n−k),B=∑c=1knc∥μc−μ∥2(23)\mathrm{CH} = \frac{B / (k - 1)}{W_k / (n - k)}, \qquad B = \sum_{c=1}^{k} n_c \lVert \boldsymbol{\mu}_c - \boldsymbol{\mu} \rVert^{2} \tag{23} DB=1k∑c=1kmax⁡c′≠cSc+Sc′∥μc−μc′∥,Sc=1nc∑i∈c∥yi−μc∥(24)\mathrm{DB} = \frac{1}{k} \sum_{c=1}^{k} \max_{c' \ne c} \frac{S_c + S_{c'}}{\lVert \boldsymbol{\mu}_c - \boldsymbol{\mu}_{c'} \rVert}, \qquad S_c = \frac{1}{n_c} \sum_{i \in c} \lVert \mathbf{y}_i - \boldsymbol{\mu}_c \rVert \tag{24}

where c(i)c(i) is the cluster of cell ii, ncn_c the size of cluster cc, μ\boldsymbol{\mu} the overall mean, nn the number of cells, and distances are Euclidean in the PCA space; si=0s_i = 0 for a cell alone in its cluster. Higher sˉ\bar s and CH and lower DB mean better separated types.

9. Output layers and fields

10. Worked example: the demo town

Load demo town builds a deterministic synthetic town in EPSG:32635, far from the projection origin: a 9×69 \times 6 grid of 140 m street blocks (120 m block plus a 20 m road reserve), grouped into six districts of 3×33 \times 3 blocks, one planted fabric per district: perimeter blocks, detached houses, slab estate, towers, industrial sheds and a historic core. It has 1 735 buildings with heights (field height), ids (bid) and the truth in fabric, 123 street lines and one limit polygon.

  1. Open the lab, press Load demo town. The id and height fields are set to bid and height; the badge reads Working CRS EPSG:32635 (input CRS kept, metres).
  2. Press Run all steps (about 5 to 6 s on a desktop machine).
  3. Tessellation: 1 735 cells, one per building. Characters: 63 primary characters (25 building, 15 cell, 8 block, 9 street, 6 node). Network: 119 segments after the four corner false nodes are merged; 54 blocks.
  4. Context: queen order 3, mean / IQR / Simpson: 168 contextual columns; 159 vary and enter the clustering.
  5. Typology: the elbow chooses k=5k = 5. Types: Irregular attached fine-grain low-rise fabric (the historic core), Detached low-rise houses, Attached low-rise street-front blocks (the mixed edge type, see section 11), High-rise point towers in open space (towers and slabs together), Attached mid-rise street-front blocks (perimeter blocks). Adjusted Rand index against fabric: 0.82.
  6. Report writes the HTML report; export writes the GeoPackage and CSV.

The same in Processing: run Urban morphometrics lab (whole chain) with Buildings = Demo buildings, Streets = Demo streets, id field bid, height field height, and a file for the HTML report. The result dictionary holds CHOSEN_K =5= 5 and CELL_COUNT =1735= 1735.

11. Limitations and planted-fabric recovery

The demo town was used to check how well the default chain recovers the six planted fabrics, and whether a different default does better. Purity is the share of a type's buildings that belong to its most common planted fabric, max⁡fncf/nc\max_f n_{cf} / n_c; ARI is the adjusted Rand index between types and fabrics over the buildings (Hubert & Arabie 1985), ARI=(RI−E[RI])/(max⁡RI−E[RI])\mathrm{ARI} = (\mathrm{RI} - \mathrm{E}[\mathrm{RI}]) / (\max \mathrm{RI} - \mathrm{E}[\mathrm{RI}]), 1 for identical partitions and about 0 for random ones.

Setting (others default)kk chosenARILowest type purityIndustrial fabric
Default: morphological, queen order 3, mean / IQR / Simpson, z-scores, k-means50.820.35 (mixed edge type)52 percent in the mixed type, 37 percent with towers
Enclosed tessellation50.850.18split
Enclosed, order 260.930.23split
kk forced to 660.820.35split
Robust standardisation40.430.33split
Ward50.710.40split
Order 250.850.38split
Order 150.930.3170 percent with perimeter blocks
Statistic mean only5 (4 with seed 1)0.90 (0.89)0.69merged with towers or perimeter blocks
Order 2, mean only50.940.6782 percent with perimeter blocks
Order 1, mean only60.950.6294 percent with perimeter blocks; detached houses split in two
kk forced to 7 or 87, 80.53, 0.510.29, 0.30split; the extra types divide the historic core and the detached houses
Log transform of right-skewed, non-negative columns (skewness above 1) before the z-scores50.780.40split
Log transform, mean only50.840.6352 percent with towers

Outcome. No setting tried recovers all six planted fabrics as six types. The 0.35 type of the default run is not noise: the dispersion statistics (IQR, Simpson) are high wherever two fabrics meet, so cells along district edges form their own transitional type, together with part of the industrial district, whose few large sheds (71 of 1 735 buildings) are too few to anchor a type of their own. Dropping the dispersion statistics or shrinking the neighbourhood removes the edge type and raises the ARI, but the industrial sheds then merge with the perimeter blocks or the towers, the chosen kk becomes less stable across seeds, and the description of heterogeneity that the method of Fleischmann et al. (2022) relies on is lost. Enclosed tessellation does not help on this grid. Height and volume characters are already in the default set whenever a height field is given, so they are not a missing input. Raising kk to 7 or 8 splits the largest fabrics before the industrial cells form a type, and a log transform of the skewed size columns does not separate them either: on this town the limit is the size of the industrial district, not the character set. The defaults are therefore kept.

Practical guidance: on a small study area with sharp boundaries between homogeneous fabrics (planned districts, synthetic data) try context order 1 or 2 with the mean statistic alone; on real, gradually changing urban fabric keep the defaults and read a mixed type as a transition zone. Compare the silhouette and Davies-Bouldin curves with the elbow before accepting kk.

Other limitations: each footprint is one feature (a multi-part footprint is one building); street characters assume a connected centre-line network (lines are noded at every crossing); the number of types is a modelling decision that the diagnostics support but do not replace.

12. References

  1. Araldi, A., Fusco, G. (2019). From the street to the metropolitan region: Pedestrian perspective in urban fabric analysis. Environment and Planning B: Urban Analytics and City Science 46(7), 1243-1263.
  2. Arthur, D., Vassilvitskii, S. (2007). k-means++: the advantages of careful seeding. Proceedings of the 18th ACM-SIAM Symposium on Discrete Algorithms, 1027-1035.
  3. Basaraner, M., Cetinkaya, S. (2017). Performance of shape indices and classification schemes for characterising perceptual shape complexity of building footprints in GIS. International Journal of Geographical Information Science 31(10), 1952-1977.
  4. Boeing, G. (2017). OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks. Computers, Environment and Urban Systems 65, 126-139.
  5. Bourdic, L., Salat, S., Nowacki, C. (2012). Assessing cities: a new system of cross-scale spatial indicators. Building Research & Information 40(5), 592-605.
  6. Buhl, J., Gautrais, J., Reeves, N., Sole, R. V., Valverde, S., Kuntz, P., Theraulaz, G. (2006). Topological patterns in street networks of self-organized urban settlements. The European Physical Journal B 49, 513-522.
  7. Calinski, T., Harabasz, J. (1974). A dendrite method for cluster analysis. Communications in Statistics 3(1), 1-27.
  8. Davies, D. L., Bouldin, D. W. (1979). A cluster separation measure. IEEE Transactions on Pattern Analysis and Machine Intelligence 1(2), 224-227.
  9. Dibble, J., Prelorendjos, A., Romice, O., Zanella, M., Strano, E., Pagel, M., Porta, S. (2019). On the origin of spaces: Morphometric foundations of urban form evolution. Environment and Planning B: Urban Analytics and City Science 46(4), 707-730.
  10. Feliciotti, A. (2018). Resilience and urban design: a systems approach to the study of resilience in urban form. PhD thesis, University of Strathclyde.
  11. Fleischmann, M. (2019). momepy: Urban Morphology Measuring Toolkit. Journal of Open Source Software 4(43), 1807.
  12. Fleischmann, M., Feliciotti, A., Romice, O., Porta, S. (2020). Morphological tessellation as a way of partitioning space: Improving consistency in urban morphology at the plot scale. Computers, Environment and Urban Systems 80, 101441.
  13. Fleischmann, M., Romice, O., Porta, S. (2021). Measuring urban form: Overcoming terminological inconsistencies for a quantitative and comprehensive morphologic analysis of cities. Environment and Planning B: Urban Analytics and City Science 48(8), 2133-2150.
  14. Fleischmann, M., Feliciotti, A., Romice, O., Porta, S. (2022). Methodological foundation of a numerical taxonomy of urban form. Environment and Planning B: Urban Analytics and City Science 49(4), 1283-1299.
  15. Gil, J., Beirao, J. N., Montenegro, N., Duarte, J. P. (2012). On the discovery of urban typologies: data mining the many dimensions of urban form. Urban Morphology 16(1), 27-40.
  16. Gini, C. (1912). Variabilita e mutabilita. Tipografia di Paolo Cuppini, Bologna.
  17. Hamaina, R., Leduc, T., Moreau, G. (2012). Towards urban fabrics characterization based on buildings footprints. In: Bridging the Geographic Information Sciences, Lecture Notes in Geoinformation and Cartography, Springer, 327-346.
  18. Hermosilla, T., Ruiz, L. A., Recio, J. A., Cambra-Lopez, M. (2012). Assessing contextual descriptive features for plot-based classification of urban areas. Landscape and Urban Planning 106(1), 124-137.
  19. Hubert, L., Arabie, P. (1985). Comparing partitions. Journal of Classification 2, 193-218.
  20. Kansky, K. J. (1963). Structure of Transportation Networks: Relationships between Network Geometry and Regional Characteristics. University of Chicago.
  21. MacQueen, J. (1967). Some methods for classification and analysis of multivariate observations. Proceedings of the 5th Berkeley Symposium on Mathematical Statistics and Probability 1, 281-297.
  22. McGarigal, K., Marks, B. J. (1995). FRAGSTATS: spatial pattern analysis program for quantifying landscape structure. USDA Forest Service General Technical Report PNW-GTR-351.
  23. 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.
  24. Rousseeuw, P. J. (1987). Silhouettes: a graphical aid to the interpretation and validation of cluster analysis. Journal of Computational and Applied Mathematics 20, 53-65.
  25. Satopaa, V., Albrecht, J., Irwin, D., Raghavan, B. (2011). Finding a 'Kneedle' in a haystack: detecting knee points in system behavior. 31st International Conference on Distributed Computing Systems Workshops, 166-171.
  26. Schirmer, P. M., Axhausen, K. W. (2016). A multiscale classification of urban morphology. Journal of Transport and Land Use 9(1), 101-130.
  27. Simpson, E. H. (1949). Measurement of diversity. Nature 163, 688.
  28. Steiniger, S., Lange, T., Burghardt, D., Weibel, R. (2008). An approach for the classification of urban building structures based on discriminant analysis techniques. Transactions in GIS 12(1), 31-59.
  29. Theil, H. (1967). Economics and Information Theory. North-Holland, Amsterdam.
  30. Vanderhaegen, S., Canters, F. (2017). Mapping urban form and function at city block level using spatial metrics. Landscape and Urban Planning 167, 399-409.
  31. Ward, J. H. (1963). Hierarchical grouping to optimize an objective function. Journal of the American Statistical Association 58(301), 236-244.

13. Citation, licence, links

Eminoğlu, Y. (2026). 02Morphometrics - Urban Morphometrics Lab (version 0.1.2) [QGIS plugin]. https://gitlab.com/geophilo1/zero2morphometrics. https://doi.org/10.5281/zenodo.24263495. The DOI 10.5281/zenodo.24263495 always resolves to the latest version; version 0.1.2 has DOI https://doi.org/10.5281/zenodo.24263496. Please also cite Fleischmann et al. (2022) and the references of the characters you use.

Licence: GPL-2.0-or-later. Copyright (C) 2026 Yusuf Eminoğlu (Geophilo).

Repository: gitlab.com/geophilo1/zero2morphometrics · Issues: work items · Homepage: geophilo.com/zero2morphometrics