Skip to main content
Loss of provenance

A previous release had provenance metadata, but this release does not. View details.

streetform icon

streetform

PyPI version Python versions pipeline status License: MIT DOI Downloads

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. With id_field (--id-field), every zone must carry a unique value of that property, since the ids join the summary rows back to the polygons.


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.2},
  doi     = {10.5281/zenodo.24122217},
  url     = {https://gitlab.com/geophilo1/streetform_sdk}
}

See also CITATION.cff.

  • openwalkscore: open walkability scores from OpenStreetMap with street-connectivity penalties.
  • spacematrix: Spacematrix urban density indicators (FSI, GSI, OSR, L, network density).
  • parcelform: parcel and lot geometry metrics from GeoJSON polygons.
  • isovist: 2D isovists, intervisibility and visibility graph analysis for urban design.

License

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

Metadata

Release files for streetform 0.1.2

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

Loss of provenance

These files do not have provenance metadata, despite files in a prior release including this data.

We recommend further investigation before installing these files. View details.

Source distribution (sdist)

Source distribution for streetform 0.1.2
File Size Uploaded Provenance Actions
streetform-0.1.2.tar.gz 46.6 kB Without provenance Details for streetform-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 81.0 kB

Release files / streetform-0.1.2.tar.gz

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL streetform-0.1.2.tar.gz
Size 46.6 kB
Tags Source
SHA-256 checksum
How to use checksums
503a56ea176149ed753d4f23eb6333bab78843326806efa8f24f9c565700138c
BLAKE2b-256 checksum
How to use checksums
c1156e49cfd049ceffde255685c59cf3485a56ed638195f56012b189a4396a98
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

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

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL streetform-0.1.2-py3-none-any.whl
Size 34.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
35c5693fba02559a6490568e1850eb3fa81256b6403f68da8eb323906b8f6dc4
BLAKE2b-256 checksum
How to use checksums
9e880f27dcd55271c89b41dd62ee5684100bc96c5c4cd0c22d25419fcc5c9a5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Security for streetform 0.1.2

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.

Loss of provenance

A previous release of these files had provenance metadata, but this release does not.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Release comparison

  • Removed 0.1.1 2 files With provenance
  • Added 0.1.2 2 files Without provenance

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