streetform
Street-network form and connectivity metrics from GeoJSON lines.
streetform turns a layer of street centrelines (GeoJSON LineStrings, in a
projected CRS in metres or in lon/lat) into a clean planar graph and reports
the indicators planners use to describe urban grain and connectivity:
- node degree distribution, intersection density, street density
- link-node ratio, connected node ratio, cul-de-sac share
- Kansky's alpha, beta, gamma indices and the cyclomatic number
- street orientation entropy and orientation order phi (Boeing 2019)
- blocks from the faces of the planar graph: mean/median area and perimeter
- circuity (link-level and between sampled node pairs) and the route directness index
- all of the above per zone polygon or per grid cell, written to CSV or GeoJSON
It runs on the Python standard library alone (shortest paths are a
heapq Dijkstra), so it installs anywhere, including inside QGIS.
pip install streetform
Requires Python 3.9 or newer.
Need more? OSMnx (Boeing 2017) is the much fuller alternative: it downloads OpenStreetMap networks, keeps one-way and attribute information, and computes these and many more statistics on top of NetworkX.
streetformis a small, dependency-free tool for your own line data (survey plans, municipal centrelines, design proposals) that only needs GeoJSON in and CSV/GeoJSON out.
Quick start
from streetform import build_graph, read_lines, network_metrics, grid_zones, summarize_zones
lines = read_lines("streets.geojson") # LineString / MultiLineString
g = build_graph(lines, crs="auto", tolerance=0.5) # metres
print(g) # StreetGraph(nodes=..., edges=..., length=... m, planar=True)
m = network_metrics(g, n_pairs=500, seed=0)
print(m["intersection_density_per_km2"], m["connected_node_ratio"])
print(m["alpha"], m["gamma"], m["orientation_order"], m["block_area_mean_m2"])
rows = summarize_zones(g, grid_zones(g, cell_size=250)) # one dict per cell
A runnable example with a bundled sample network is in
examples/quickstart.py.
Command line
# network-wide metrics as JSON (or a one-row CSV with -o metrics.csv)
streetform metrics streets.geojson --tolerance 0.5 --pairs 500
# nodes (with degree), links (length, bearing, circuity) and blocks as GeoJSON
streetform export streets.geojson --nodes nodes.geojson --edges links.geojson --blocks blocks.geojson
# per-zone summaries: zone polygons or a square grid (metres)
streetform zones streets.geojson --zones districts.geojson --id-field code -o districts.csv
streetform zones streets.geojson --grid 500 -o grid.geojson
Common options: --crs auto|projected|lonlat, --no-split (do not create
nodes at crossings, e.g. to keep bridges unconnected), --keep-degree2
(skip simplification).
API overview
| Function / class | Purpose |
|---|---|
read_lines(path_or_dict, where=None) |
LineString/MultiLineString coordinates from GeoJSON, optional attribute filter |
build_graph(lines, crs, tolerance, split_crossings, simplify, drop_duplicates) |
build a StreetGraph |
StreetGraph |
nodes, edges, degrees(), adjacency(), components(), simplified(), nearest_node() |
connectivity_metrics(g, area_m2=None) |
counts, densities, link-node ratio, connected node ratio, cul-de-sac share |
degree_distribution(g) |
{degree: count} |
kansky_indices(g, planar=True) |
cyclomatic number, alpha, beta, gamma |
orientation_histogram / orientation_entropy / orientation_order(g, ...) |
Boeing (2019) orientation measures; order_from_entropy(H) |
polygonize(g), block_metrics(g) |
blocks (bounded faces) and their size statistics |
edge_circuity(g) |
sum of link lengths / sum of straight end-to-end distances |
sampled_circuity(g, n_pairs, seed) |
network vs Euclidean distance over random node pairs |
route_directness(g, pairs) |
RDI and circuity for explicit origin-destination points |
shortest_path_lengths(g, source, targets) |
Dijkstra distances |
network_metrics(g) |
everything above in one JSON-serialisable dict |
read_zones, grid_zones, summarize_zones, zones_to_geojson |
zone/grid summaries |
nodes_to_geojson, edges_to_geojson, blocks_to_geojson, write_geojson, write_csv |
output |
Method and sources
Graph building
- Coordinates are projected to a planar metric frame. Lon/lat input uses a
local equirectangular projection centred on the data extent
(
x = R·Δλ·cos φ0,y = R·Δφ,R= 6 371 008.8 m); projected input is used as is and assumed to be in metres. - Nodes are created at line ends, at shared vertices, where a line end
lies within
toleranceof another line (T-junctions, undershoots) and, withsplit_crossings=True(default), at every crossing. Candidate pairs are found with a uniform grid index. - Node candidates closer than
toleranceare merged (grid hashing + union-find); lines are split at the merged nodes. - Exact duplicate links are dropped and, with
simplify=True, chains of degree-2 nodes are dissolved so that nodes are only intersections and dead ends, as in the simplified graphs of OSMnx (Boeing 2017, 2019).
Indicators
| Indicator | Definition | Source |
|---|---|---|
| Intersection density | nodes with degree ≥ 3 per km² | Dill (2004); Cervero & Kockelman (1997) |
| Street density | km of street per km² | Dill (2004) |
| Link-node ratio | links / nodes; Ewing (1996) suggests 1.4 as a target | Dill (2004) |
| Connected node ratio | intersections / (intersections + cul-de-sacs); INDEX model: avoid < 0.5, favour ≥ 0.7 | Dill (2004) |
| Cul-de-sac share | dead-end nodes / all nodes (Boeing's P_de) | Boeing (2019) |
| Cyclomatic number μ | e − v + p | Kansky (1963) |
| Alpha | μ / (2v − 5) (planar) | Kansky (1963); Dill (2004) |
| Beta | e / v | Kansky (1963) |
| Gamma | e / 3(v − 2) (planar) | Kansky (1963); Dill (2004) |
| Orientation entropy H | −Σ P(oᵢ) ln P(oᵢ) over 36 bins of 10°, shifted by −5°, every bearing plus its reciprocal | Boeing (2019), eq. 1–2 |
| Orientation order φ | 1 − ((H − H_g)/(H_max − H_g))², H_g = ln 4 ≈ 1.386, H_max = ln 36 ≈ 3.584 | Boeing (2019), eq. 3 |
| Average circuity | Σ link lengths / Σ straight distances between adjacent nodes | Boeing (2019), eq. 4 |
| Pair circuity | Σ network / Σ Euclidean distance over sampled node pairs | Giacomin & Levinson (2015) |
| Route directness | Euclidean / network distance (0–1); its reciprocal is Dill's "pedestrian route directness" (Portland Metro max 1.5; INDEX 1.2–1.5) | Dill (2004) |
| Block size | area and perimeter of bounded faces of the planar graph | Dill (2004), Table 1 (Hess et al. 1999; Song 2003) |
The orientation measures were checked against the published values: the
(H_o, φ) pairs in Table 1 of Boeing (2019) are reproduced by
order_from_entropy in the test suite.
Blocks
Faces are traced on the half-edge structure of the planar embedding: at each node the next half-edge is the one immediately clockwise of the incoming one, so bounded faces are counter-clockwise rings with positive area. A street component lying entirely inside a face becomes a hole of that face. A cul-de-sac reaching into a block is part of its ring (as a zero-width spike) but not of its perimeter.
Zones
Nodes are assigned to zones by location, links by their mid-point (half their length) and blocks by an interior point. Node degree is taken from the whole network, so a street that leaves a zone does not create a false dead end at the zone boundary. Densities use the zone area.
Limitations
- Coordinates in a projected CRS are assumed to be metres; there is no CRS
database.
crs="auto"treats data as lon/lat when every coordinate lies in ±180/±90, so a small local dataset in metres may be misread; passcrs="projected"explicitly. - The lon/lat projection is equirectangular: scale error grows with the north-south extent (about 0.15 % at ±0.1° around 41° N). Reproject large study areas first.
- Undirected graph only: one-way streets, turn restrictions and travel speeds are ignored; circuity and directness are geometric.
- With
split_crossings=Truegrade-separated crossings (bridges, tunnels) become intersections; usesplit_crossings=Falsewhen the data shares vertices at real junctions (as OpenStreetMap does). Blocks need the planar mode. - Collinear overlapping lines are not merged unless they are exact duplicates between the same nodes; snapping can chain nearby nodes when the tolerance is large compared to the street spacing.
- Kansky's planar maxima (3v − 6 links, 2v − 5 circuits) assume one connected simple graph; with several components or parallel links they are approximations, and gamma/alpha can exceed 1 for multigraphs.
- Default study area for densities is the convex hull of the network; pass
area_m2(or use zones) for a meaningful denominator. - Pure Python: networks of tens of thousands of links take seconds; for metropolitan networks use OSMnx/NetworkX or a compiled library.
References
- Boeing, G. (2017). OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks. Computers, Environment and Urban Systems 65, 126–139.
- Boeing, G. (2019). Urban spatial order: street network orientation, configuration, and entropy. Applied Network Science 4, 67. https://doi.org/10.1007/s41109-019-0189-1
- Cervero, R. & Kockelman, K. (1997). Travel demand and the 3Ds: density, diversity, and design. Transportation Research Part D 2(3), 199–219.
- Dill, J. (2004). Measuring network connectivity for bicycling and walking. 83rd Annual Meeting of the Transportation Research Board, Washington, DC.
- Ewing, R. (1996). Best Development Practices. Chicago: APA Planners Press.
- Giacomin, D. J. & Levinson, D. M. (2015). Road network circuity in metropolitan areas. Environment and Planning B 42(6), 1040–1053.
- Kansky, K. J. (1963). Structure of Transportation Networks. University of Chicago, Department of Geography, Research Paper 84.
Academic citation
@software{eminoglu_streetform,
author = {Eminoğlu, Yusuf},
title = {streetform},
year = {2026},
version = {0.1.1},
url = {https://github.com/YusufEminoglu/streetform_sdk}
}
License
MIT, see LICENSE. Contact: geospacephilo@gmail.com
Metadata
Release files for streetform 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| streetform-0.1.1.tar.gz | 44.8 kB | With provenance | Details for streetform-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| streetform-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for streetform-0.1.1-py3-none-any.whl |
Total release size: 78.5 kB
Release files / streetform-0.1.1.tar.gz
| Download URL | streetform-0.1.1.tar.gz |
|---|---|
| Size | 44.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7e0d0baebef92c72a74a023532d1f1b613a19b73b6c13c7ee4078741cae1716a
|
|
BLAKE2b-256 checksum How to use checksums |
496038b818a8aaa6422f42be6737a3e8698bdbf10af2e3d6256561b4712c8e40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / streetform-0.1.1-py3-none-any.whl
| Download URL | streetform-0.1.1-py3-none-any.whl |
|---|---|
| Size | 33.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d44d6b0aac61826c3b34693b666f0e2b08861c368b841d4dbf982e00a587b021
|
|
BLAKE2b-256 checksum How to use checksums |
c2caca54279d308df028feb90626209b59db64087836dd901854190a13ebadc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for streetform 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for streetform-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.