Metadata-Version: 2.4
Name: streetform
Version: 0.1.1
Summary: Street-network form and connectivity metrics from GeoJSON lines: planar graph building, intersection density, link-node and connected node ratios, Kansky alpha/beta/gamma, orientation entropy and order, block size, circuity and route directness, by zone or grid.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/YusufEminoglu/streetform_sdk
Project-URL: Repository, https://github.com/YusufEminoglu/streetform_sdk
Project-URL: Issues, https://github.com/YusufEminoglu/streetform_sdk/issues
Project-URL: Changelog, https://github.com/YusufEminoglu/streetform_sdk/blob/main/CHANGELOG.md
Keywords: street-network,urban-form,connectivity,intersection-density,link-node-ratio,kansky,orientation-entropy,circuity,route-directness,urban-blocks,walkability,urban-planning,geojson,gis
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# streetform

[![PyPI version](https://img.shields.io/pypi/v/streetform.svg)](https://pypi.org/project/streetform/)
[![Python versions](https://img.shields.io/pypi/pyversions/streetform.svg)](https://pypi.org/project/streetform/)
[![CI](https://github.com/YusufEminoglu/streetform_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/streetform_sdk/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/streetform_sdk/blob/main/LICENSE)

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

```bash
pip install streetform
```

Requires Python 3.9 or newer.

> **Need more?** [OSMnx](https://github.com/gboeing/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

```python
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`](https://github.com/YusufEminoglu/streetform_sdk/blob/main/examples/quickstart.py).

### Command line

```bash
# 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

```bibtex
@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](LICENSE). Contact: geospacephilo@gmail.com
