Metadata-Version: 2.4
Name: greenrule
Version: 0.1.1
Summary: Urban green space provision and exposure indicators: the 3-30-300 rule, the WHO Europe 300 m green space proximity indicator, green space per capita, NDVI buffer exposure and equity summaries.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/greenrule_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/greenrule_sdk
Project-URL: Issues, https://gitlab.com/geophilo1/greenrule_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/greenrule_sdk/-/blob/main/CHANGELOG.md
Keywords: green-space,urban-green,3-30-300,tree-canopy,ndvi,greenness-exposure,accessibility,network-distance,environmental-justice,gini,urban-planning,public-health,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: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
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

# greenrule

[![PyPI](https://img.shields.io/pypi/v/greenrule.svg)](https://pypi.org/project/greenrule/)
[![Python](https://img.shields.io/pypi/pyversions/greenrule.svg)](https://pypi.org/project/greenrule/)
[![pipeline](https://gitlab.com/geophilo1/greenrule_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/greenrule_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/greenrule_sdk/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24235574.svg)](https://doi.org/10.5281/zenodo.24235574)

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

```bash
pip install greenrule
```

Requires Python 3.9 or newer. Coordinates must be in a projected CRS in metres.

## Quickstart

```python
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

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

```bibtex
@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](CITATION.cff).

## License

MIT, see [LICENSE](LICENSE).
