streetform 0.1.0__tar.gz

streetform-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- `build_graph`: street graph from GeoJSON LineStrings (projected metres or lon/lat with a
+  local equirectangular projection), node snapping within a tolerance, splitting at
+  crossings, T-junctions and undershoots (or only at shared vertices with
+  `split_crossings=False`), duplicate removal and degree-2 simplification.
+- Connectivity metrics: node degree distribution, intersection, node and street density,
+  link-node ratio, connected node ratio, cul-de-sac share, mean degree.
+- Kansky alpha, beta, gamma and cyclomatic number (planar and non-planar maxima).
+- Street orientation histogram, entropy and orientation order phi (Boeing 2019), unweighted
+  or length-weighted, by link end points or by segments; `order_from_entropy`.
+- Blocks as bounded faces of the planar graph (half-edge face tracing, island holes,
+  cul-de-sacs excluded from perimeter) with area, perimeter and compactness summaries.
+- Circuity: average link circuity, sampled node-pair circuity and route directness with a
+  pure-Python Dijkstra (`heapq`), and route directness for explicit OD pairs.
+- Zone summaries by polygon layer or square grid; GeoJSON and CSV writers.
+- `streetform` CLI with `metrics`, `export` and `zones` commands.

streetform-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "streetform"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/streetform_sdk"
+url: "https://pypi.org/project/streetform/"
+abstract: "Street-network form and connectivity metrics from GeoJSON LineStrings: planar graph building with snapping and splitting at intersections, intersection density, node degree distribution, link-node and connected node ratios, cul-de-sac share, Kansky alpha/beta/gamma indices, street orientation entropy and order (Boeing 2019), block size from polygonized faces, circuity and route directness, summarised by zone polygons or a grid."
+keywords:
+  - street network
+  - urban form
+  - connectivity
+  - orientation entropy
+  - circuity
+  - urban planning
+  - gis

streetform-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

streetform-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/streetform/py.typed
+recursive-include src/streetform *.py
+recursive-include tests *.py
+recursive-include examples *.py *.geojson

streetform-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: streetform
+Version: 0.1.0
+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.0},
+  url     = {https://github.com/YusufEminoglu/streetform_sdk}
+}
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE). Contact: geospacephilo@gmail.com

streetform-0.1.0/README.md

@@ -0,0 +1,212 @@
+# 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.0},
+  url     = {https://github.com/YusufEminoglu/streetform_sdk}
+}
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE). Contact: geospacephilo@gmail.com

streetform-0.1.0/examples/quickstart.py

@@ -0,0 +1,74 @@
+"""streetform quick start.
+
+Runs on the bundled sample (a 4 x 4 block grid cut by a diagonal boulevard,
+with two cul-de-sacs; projected coordinates in metres):
+
+    python examples/quickstart.py
+
+Writes nodes, links, blocks and a 200 m grid summary to ``examples/out/``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from streetform import (
+    blocks_to_geojson,
+    build_graph,
+    edges_to_geojson,
+    grid_zones,
+    network_metrics,
+    nodes_to_geojson,
+    read_lines,
+    route_directness,
+    summarize_zones,
+    write_csv,
+    write_geojson,
+)
+
+HERE = Path(__file__).resolve().parent
+OUT = HERE / "out"
+
+
+def main() -> None:
+    lines = read_lines(HERE / "sample_streets.geojson")
+    graph = build_graph(lines, crs="projected", tolerance=0.5)
+    print(graph)
+
+    m = network_metrics(graph, n_pairs=300, seed=42)
+    keys = [
+        "intersections",
+        "dead_ends",
+        "intersection_density_per_km2",
+        "link_node_ratio",
+        "connected_node_ratio",
+        "cul_de_sac_share",
+        "alpha",
+        "beta",
+        "gamma",
+        "orientation_entropy",
+        "orientation_order",
+        "edge_circuity",
+        "network_circuity",
+        "route_directness_index",
+        "blocks",
+        "block_area_mean_m2",
+    ]
+    print(json.dumps({k: m[k] for k in keys}, indent=2))
+
+    # corner to corner: along the boulevard vs. around the grid
+    od = [((500000.0, 4540000.0), (500400.0, 4540400.0))]
+    print("RDI corner to corner:", route_directness(graph, od)[0]["rdi"])
+
+    OUT.mkdir(exist_ok=True)
+    write_geojson(nodes_to_geojson(graph), OUT / "nodes.geojson")
+    write_geojson(edges_to_geojson(graph), OUT / "links.geojson")
+    write_geojson(blocks_to_geojson(graph), OUT / "blocks.geojson")
+    rows = summarize_zones(graph, grid_zones(graph, 200.0))
+    write_csv(rows, OUT / "grid_200m.csv")
+    print(f"wrote {len(rows)} grid cells and GeoJSON layers to {OUT}")
+
+
+if __name__ == "__main__":
+    main()