greenrule
Urban green space provision and exposure indicators for homes, neighbourhoods and zones.
greenrule computes the green-space measures that planning and public-health studies
report most often: the 3-30-300 rule per home, the WHO Europe 300 m proximity indicator,
green space per capita, NDVI greenness in buffers around homes, and how evenly all of these
are distributed across zones. Distances are straight-line or along a street network built
from GeoJSON lines. It needs only NumPy.
Installation
pip install greenrule
Requires Python 3.9 or newer. Coordinates must be in a projected CRS in metres.
Quickstart
import greenrule as gr
greens = gr.GreenSpaces.from_geojson(gr.read_geojson("parks.geojson"))
homes = gr.read_points("buildings.geojson") # points, or polygons -> centroids
pop = homes.column("residents")
# WHO Europe (2016): 300 m linear distance, 0.5 ha core and 1 ha additional indicator
both = gr.who_proximity_both(homes.xy, greens, population=pop)
both["core_0.5ha"].share, both["additional_1ha"].share
# 3-30-300 per home
canopy = gr.Raster(canopy_array, x0=500000, y0=4300000, dx=1, dy=1) # 1 = tree canopy
net = gr.Network([gr.read_geojson("streets.geojson")])
res = gr.assess(
homes.xy, greens, pop,
tree_counts=homes.column("visible_trees"), # from street-view or viewshed work
canopy=canopy, canopy_radius=250, # neighbourhood = 250 m buffer (your choice)
network=net, max_snap=100, # network distance, Euclidean fallback
zones=homes.labels("district"),
)
res.summary()["rule_3_30_300"]["share_all_three"]
res.summary()["equity"]["gini_between_zones"]
gr.write_json(gr.points_to_geojson(homes, res.to_rows()), "homes_green.geojson")
Single pieces are plain functions: evaluate_3_30_300, who_proximity,
euclidean_distance, network_distance, green_provision, ndvi, ndvi_exposure,
gini, lorenz_curve, equity_summary. See examples/quickstart.py for a run on
synthetic data.
Features
| Area | Functions | Notes |
|---|---|---|
| 3-30-300 | evaluate_3_30_300 -> Rule333Result, visible_tree_counts, trees_within_radius, canopy_share_zones, canopy_share_buffers |
thresholds 3 / 30 % / 300 m; visibility is a user input |
| WHO Europe 2016 | who_proximity, who_proximity_both -> ProximityResult |
300 m linear distance; 0.5 ha core, 1 ha additional |
| Distances | euclidean_distance, network_distance -> GreenDistance, Network |
boundary distance; entrances or boundary access points; Euclidean fallback |
| Provision | green_provision -> Provision |
green m2, green share, m2 per resident by zone |
| Exposure | ndvi, ndvi_exposure -> Exposure, Raster |
mean, median, SD, share of cells above a threshold |
| Equity | gini, lorenz_curve, share_meeting, equity_summary |
population-weighted |
| One call | assess -> Assessment |
rows per home and a summary |
| I/O | read_geojson, read_points, areas_from_geojson, points_to_geojson, write_csv, write_json |
GeoJSON and CSV |
Methods
The 3-30-300 rule
Konijnendijk (2023) proposes that everyone should see at least 3 well-established
trees from their home (and school or workplace), that every neighbourhood should have at
least 30 % tree canopy cover, and that every residence should lie no more than
300 m from the nearest public green space. The article mentions a park of at least
1 ha (after WHO) but the rule itself sets no minimum size, and it does not say whether
the 300 m is straight-line or walking distance. These three thresholds are the defaults
(MIN_TREES, MIN_CANOPY, MAX_DISTANCE_M). The rule leaves several choices open, so
they are explicit parameters here and should be reported:
- Visible trees need street-level imagery, a viewshed or a survey; give per-home counts
(
tree_counts) or home-tree visibility pairs (visible_pairs).trees_within_radiuscounts trees within a distance and is labelled as a proxy in the results. - Neighbourhood: polygons (with canopy from a raster, from canopy polygons by grid sampling, or precomputed shares) or a circular buffer around each home on a canopy raster. Rasters can be binary (non-zero = canopy) or hold a cover fraction per cell.
- Green space: optional minimum size
min_green_area_ha(none by default). - Distance: Euclidean to the green-space boundary, or along the street network.
WHO Europe (2016) Urban Green Space Indicator
WHO Regional Office for Europe (2016, chapter 4) defines the indicator as the proportion of
the population living within 300 m linear distance to the boundary of a green space,
with two recommended alternative minimum sizes: 0.5 ha (core indicator) and 1 ha
(additional indicator), and recommends reporting both. Linear distance from the green-space
edge is treated there as an appropriate proxy for walking distance; additional runs with
other distances (for example 200 m and 500 m) are recommended. who_proximity follows this
definition (default 0.5 ha); who_proximity_both returns both sizes. Selecting the green
spaces (the report uses Urban Atlas class 1.4.1 "Green urban areas") is up to the user.
Distances and the network
- Euclidean distance runs from the home to the nearest point of the green-space boundary (0 inside).
Networksplits GeoJSON lines at every vertex and merges vertices withinnode_tolerance. Homes and green-space access points are attached to the nearest segment by a perpendicular access leg (up tomax_snap); one multi-source Dijkstra (1959) search from all access points gives every home its nearest green space.- Access points are mapped entrances (
GreenSpaces.set_entrances) or, failing that, points everyentrance_spacingmetres (default 25) along the boundary. - Homes without a network connection get their Euclidean distance (
method = "euclidean") unlessfallback=None.
Provision, exposure and equity
- Green space per capita = green area in a zone / residents (m2 per person), with green areas assigned by centroid or by grid sampling. No benchmark is built in. A "9 m2 per person" figure is often attributed to the WHO, but WHO Europe (2016) does not contain it.
- NDVI = (NIR - Red) / (NIR + Red) (Rouse et al. 1974). Buffer exposure uses cells whose centre lies within the radius; the radius and any greenness threshold are study choices (Markevych et al. 2017) and have no defaults.
- Gini coefficient from the population-weighted Lorenz curve by the trapezoid rule
(Gini 1912); with equal weights it equals the mean absolute difference over twice the
mean.
equity_summaryreports the population share meeting each criterion overall and by zone, and the Gini of the per-zone shares. Wolch, Byrne & Newell (2014) review the environmental-justice context.
Command line
greenrule who homes.geojson parks.geojson --population-field pop --both --summary who.json
greenrule rule homes.geojson parks.geojson --population-field pop --trees-field visible_trees \
--canopy canopy.npy --transform=500000,4300000,1,1 --canopy-radius 250 \
--network streets.geojson --max-snap 100 --zone-field district \
-o homes_333.geojson --csv homes_333.csv --summary rule.json
greenrule exposure homes.csv --ndvi ndvi.npy --transform=500000,4300000,10,10 --radius 300
greenrule provision districts.geojson parks.geojson --population-field pop --method sample \
--resolution 5 --csv provision.csv
greenrule equity homes_333.csv --criteria meets_3,meets_30,meets_300 --population population \
--zone district --value green_distance
Homes can be GeoJSON or CSV with x,y columns. Rasters are 2-D .npy arrays with
--transform x0,y0_top,dx,dy (write it with = when x0 is negative). Summaries go to
stdout as JSON unless --summary or -o is given.
Limitations
- Planar coordinates only; no reprojection.
- Tree visibility is not modelled; it must come from the user.
- Canopy and green overlap from polygons are grid-sampled; choose a resolution that is small relative to the features.
- The network is undirected and unweighted by mode; there is no turn or barrier model.
- Polygon-to-polygon intersections are not computed exactly.
References
- Dijkstra, E. W. (1959). A note on two problems in connexion with graphs. Numerische Mathematik 1, 269-271.
- Gini, C. (1912). Variabilità e mutabilità. Bologna: Tipografia di Paolo Cuppini.
- Konijnendijk, C. C. (2023). Evidence-based guidelines for greener, healthier, more resilient neighbourhoods: introducing the 3-30-300 rule. Journal of Forestry Research 34(3), 821-830. https://doi.org/10.1007/s11676-022-01523-z
- Markevych, I., Schoierer, J., Hartig, T., Chudnovsky, A., Hystad, P., Dzhambov, A. M., et al. (2017). Exploring pathways linking greenspace to health: theoretical and methodological guidance. Environmental Research 158, 301-317. https://doi.org/10.1016/j.envres.2017.06.028
- Rouse, J. W., Haas, R. H., Schell, J. A. & Deering, D. W. (1974). Monitoring vegetation systems in the Great Plains with ERTS. Third ERTS Symposium, NASA SP-351, 309-317.
- WHO Regional Office for Europe (2016). Urban green spaces and health: a review of evidence. Copenhagen: WHO Regional Office for Europe.
- Wolch, J. R., Byrne, J. & Newell, J. P. (2014). Urban green space, public health, and environmental justice: the challenge of making cities "just green enough". Landscape and Urban Planning 125, 234-244. https://doi.org/10.1016/j.landurbplan.2014.01.017
Citation
@software{eminoglu_greenrule,
author = {Eminoğlu, Yusuf},
title = {greenrule},
year = {2026},
version = {0.1.0},
url = {https://gitlab.com/geophilo1/greenrule_sdk}
}
See also CITATION.cff.
License
MIT, see LICENSE.
Metadata
Release files for greenrule 0.1.0
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 |
|---|---|---|---|---|
| greenrule-0.1.0.tar.gz | 48.2 kB | Without provenance | Details for greenrule-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| greenrule-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for greenrule-0.1.0-py3-none-any.whl |
Total release size: 90.0 kB
Release files / greenrule-0.1.0.tar.gz
| Download URL | greenrule-0.1.0.tar.gz |
|---|---|
| Size | 48.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
343e0ec6feb04972d62f400502e5d906b314b988b75ca85efd0b649f43050720
|
|
BLAKE2b-256 checksum How to use checksums |
68bd68e46c24f2b50df2170866ecffd2f5514cfd21392124e9ff898744fe3f34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / greenrule-0.1.0-py3-none-any.whl
| Download URL | greenrule-0.1.0-py3-none-any.whl |
|---|---|
| Size | 41.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7ca0f9f082fe1e2e4f0367f596a9f2818084d9897f73885325e04bc72be2c5c9
|
|
BLAKE2b-256 checksum How to use checksums |
f64e70018e999378bb2a7818cbb7d089e72a55e38cbc0d17133ad6f1e1edebbb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for greenrule 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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.