Skip to main content

streetform

PyPI version Python versions CI License: MIT

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. streetform is 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

  1. 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.
  2. Nodes are created at line ends, at shared vertices, where a line end lies within tolerance of another line (T-junctions, undershoots) and, with split_crossings=True (default), at every crossing. Candidate pairs are found with a uniform grid index.
  3. Node candidates closer than tolerance are merged (grid hashing + union-find); lines are split at the merged nodes.
  4. 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; pass crs="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=True grade-separated crossings (bridges, tunnels) become intersections; use split_crossings=False when 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.0},
  url     = {https://github.com/YusufEminoglu/streetform_sdk}
}

License

MIT, see LICENSE. Contact: geospacephilo@gmail.com

Metadata

Release files for streetform 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for streetform 0.1.0
File Size Uploaded Provenance Actions
streetform-0.1.0.tar.gz 44.7 kB With provenance Details for streetform-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for streetform 0.1.0
File Interpreter ABI Platform Actions
streetform-0.1.0-py3-none-any.whl Python 3 none any Details for streetform-0.1.0-py3-none-any.whl

Total release size: 78.4 kB

Release files / streetform-0.1.0.tar.gz

Download URL streetform-0.1.0.tar.gz
Size 44.7 kB
Tags Source
SHA-256 checksum
How to use checksums
4634f3ebfdd15a07314f5d0a131268f2352167da18a1d011b9f6aefebf6f3fe4
BLAKE2b-256 checksum
How to use checksums
ffb6b78bdc4846f3b373186820f1d90b324e2bdab6a0fbca69871f3220ed192f
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 log

Release files / streetform-0.1.0-py3-none-any.whl

Download URL streetform-0.1.0-py3-none-any.whl
Size 33.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9d90662808572547d9d152c36d4c8f2f26e90f35d293eb9a5ffa17ec2aaa3ca0
BLAKE2b-256 checksum
How to use checksums
1a623e8e6aec24bfba908b4454110bb9af886a3b1591ed3adb5e4bde048de6a6
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 log

Security for streetform 0.1.0

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.

Select from 2 files

Attestation for streetform-0.1.0.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page