Skip to main content

greenrule

PyPI Python pipeline License: MIT DOI

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_radius counts 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).
  • Network splits GeoJSON lines at every vertex and merges vertices within node_tolerance. Homes and green-space access points are attached to the nearest segment by a perpendicular access leg (up to max_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 every entrance_spacing metres (default 25) along the boundary.
  • Homes without a network connection get their Euclidean distance (method = "euclidean") unless fallback=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_summary reports 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.1},
  doi     = {10.5281/zenodo.24235574},
  url     = {https://gitlab.com/geophilo1/greenrule_sdk}
}

See also CITATION.cff.

License

MIT, see LICENSE.

Metadata

Release files for greenrule 0.1.1

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

Source distribution (sdist)

Source distribution for greenrule 0.1.1
File Size Uploaded Provenance Actions
greenrule-0.1.1.tar.gz 48.2 kB Without provenance Details for greenrule-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 90.1 kB

Release files / greenrule-0.1.1.tar.gz

Download URL greenrule-0.1.1.tar.gz
Size 48.2 kB
Tags Source
SHA-256 checksum
How to use checksums
22fca6f5cea7228bc8053362bc266709f769ec4703d41a59ac9e15feba3f02e0
BLAKE2b-256 checksum
How to use checksums
0392615f4bf2ba2ecb58b226894025167e1286cde2c5e251f79c356fc7d13dc3
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.1-py3-none-any.whl

Download URL greenrule-0.1.1-py3-none-any.whl
Size 41.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
abdd18c81572de23e391e578ce9bbce4d4cbbb94cc97efc6e5a8562b6c879072
BLAKE2b-256 checksum
How to use checksums
8844fc9473e5002edecaeddcf10387b5b2f61b4819359eba599985f3b01512bc
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.1

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.

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