greenrule 0.1.0__tar.gz

greenrule-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-15
+### Added
+- 3-30-300 rule (Konijnendijk 2023) per home: visible-tree counts from user visibility
+  inputs (counts or home-tree pairs; a labelled radius proxy), neighbourhood canopy share
+  from rasters, canopy polygons or precomputed values (zones or circular buffers), and
+  Euclidean or network distance to the nearest green space with an optional minimum size.
+- WHO Regional Office for Europe (2016) Urban Green Space Indicator: 300 m linear distance
+  to the green-space boundary, 0.5 ha core and 1 ha additional minimum sizes.
+- Green space per capita and green share by zone (centroid assignment or grid sampling).
+- NDVI computation and circular-buffer NDVI exposure (mean, median, SD, green fraction).
+- Equity: weighted Gini coefficient, Lorenz curve, population share meeting each
+  criterion overall and by zone, Gini of per-zone shares.
+- Built-in street graph from GeoJSON lines with multi-source Dijkstra, point snapping and a
+  Euclidean fallback.
+- One-call `assess()`; GeoJSON/CSV input and output.
+- Command line: `greenrule who | rule | exposure | provision | equity`.
+
+### Fixed
+- Raster buffer and polygon statistics no longer copy the whole raster for every home or
+  zone (only the window around it is read), which made large rasters very slow.
+- `trees_within_radius` sizes its blocks by the number of trees, so large tree inventories
+  no longer allocate multi-gigabyte distance arrays.
+- 3-30-300 description aligned with Konijnendijk (2023): well-established trees, and the
+  article's 1 ha park mention is not part of the rule; citation gives the issue number;
+  Gini (1912) title spelled with its accents.

greenrule-0.1.0/CITATION.cff

@@ -0,0 +1,23 @@
+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: "greenrule"
+version: "0.1.0"
+date-released: "2026-11-15"
+license: "MIT"
+repository-code: "https://gitlab.com/geophilo1/greenrule_sdk"
+url: "https://pypi.org/project/greenrule/"
+abstract: "Urban green space provision and exposure indicators: the 3-30-300 rule per home (visible trees, neighbourhood canopy cover, distance to the nearest green space), the WHO Regional Office for Europe (2016) 300 m green space proximity indicator, green space per capita, NDVI buffer exposure and equity summaries (Gini coefficient, population shares meeting each criterion), with a built-in network shortest path on GeoJSON lines and a Euclidean fallback."
+keywords:
+  - green space
+  - 3-30-300
+  - tree canopy
+  - NDVI
+  - accessibility
+  - environmental justice
+  - urban planning
+  - gis

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

greenrule-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/greenrule/py.typed
+recursive-include src/greenrule *.py
+recursive-include tests *.py
+recursive-include examples *.py

greenrule-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: greenrule
+Version: 0.1.0
+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)
+
+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.0},
+  url     = {https://gitlab.com/geophilo1/greenrule_sdk}
+}
+```
+
+See also [CITATION.cff](CITATION.cff).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

greenrule-0.1.0/README.md

@@ -0,0 +1,195 @@
+# 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)
+
+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.0},
+  url     = {https://gitlab.com/geophilo1/greenrule_sdk}
+}
+```
+
+See also [CITATION.cff](CITATION.cff).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

greenrule-0.1.0/examples/quickstart.py

@@ -0,0 +1,74 @@
+"""greenrule quickstart on a synthetic district (no input files needed).
+
+Run:  python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import json
+
+import numpy as np
+
+import greenrule as gr
+
+
+def rect(x0: float, y0: float, x1: float, y1: float) -> dict:
+    return {"type": "Polygon", "coordinates": [[[x0, y0], [x1, y0], [x1, y1], [x0, y1], [x0, y0]]]}
+
+
+def main() -> None:
+    rng = np.random.default_rng(1)
+    # 200 homes in a 1.2 km x 0.8 km district (metres, projected CRS)
+    homes = np.column_stack([rng.uniform(0, 1200, 200), rng.uniform(0, 800, 200)])
+    residents = rng.integers(1, 6, 200)
+    greens = gr.GreenSpaces.from_geojson(
+        {
+            "type": "FeatureCollection",
+            "features": [
+                {
+                    "type": "Feature",
+                    "id": "pocket",
+                    "properties": {},
+                    "geometry": rect(100, 100, 180, 180),
+                },
+                {
+                    "type": "Feature",
+                    "id": "park",
+                    "properties": {},
+                    "geometry": rect(700, 300, 820, 420),
+                },
+            ],
+        }
+    )
+    # canopy raster, 5 m cells: denser canopy in the east
+    canopy = (rng.random((160, 240)) < np.linspace(0.1, 0.5, 240)).astype(np.uint8)
+    canopy_r = gr.Raster(canopy, x0=0, y0=800, dx=5, dy=5)
+    # a simple street grid every 200 m
+    lines = [[[x, 0], [x, 800]] for x in range(0, 1201, 200)]
+    lines += [[[0, y], [1200, y]] for y in range(0, 801, 200)]
+    net = gr.Network(lines)
+    # visible-tree counts would come from street-level imagery or a viewshed analysis
+    visible = rng.integers(0, 7, 200)
+    zones = np.where(homes[:, 0] < 600, "west", "east")
+
+    res = gr.assess(
+        homes,
+        greens,
+        residents,
+        tree_counts=visible,
+        canopy=canopy_r,
+        canopy_radius=250,
+        network=net,
+        max_snap=150,
+        zones=zones,
+    )
+    s = res.summary()
+    print(json.dumps(s["rule_3_30_300"], indent=1))
+    print("WHO 2016 (0.5 ha, 300 m):", round(s["who_2016"]["share_within"], 3))
+    print("Gini of zone shares:", s["equity"]["gini_between_zones"])
+    both = gr.who_proximity_both(homes, greens, population=residents)
+    print({k: round(v.share, 3) for k, v in both.items()})
+
+
+if __name__ == "__main__":
+    main()