roadnoise 0.1.0__tar.gz

roadnoise-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
+- CNOSSOS-EU road traffic source model (Directive 2002/49/EC Annex II as amended by
+  Directive (EU) 2021/1226): Table F-1 (2021) coefficients for categories 1, 2, 3, 4a
+  and 4b, Table F-4 (2021) road surfaces, Table F-2 studded tyres and Table F-3
+  acceleration corrections (2015), temperature and gradient corrections, line-source
+  emission per metre, user CSV tables for coefficients (including category 5) and
+  road surfaces.
+- ISO 9613-1 atmospheric absorption; CNOSSOS-EU and ISO 9613-2 flat-ground ground
+  effect; CNOSSOS-EU, ISO 9613-2 and Maekawa single-edge diffraction.
+- Road segmentation, receiver grids, facade receivers, barriers and buildings as
+  diffracting edges, long-term levels and L_day / L_evening / L_night / L_den.
+- END exposure statistics per 5 dB band.
+- UK CRTN (1988) quick method.
+- GeoJSON input, ESRI ASCII grid, GeoTIFF (optional rasterio) and GeoJSON output,
+  geopandas helpers, and the `roadnoise` command line (`emission`, `grid`,
+  `receivers`, `crtn`, `surfaces`).

roadnoise-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+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: "yusufeminoglu@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "roadnoise"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/roadnoise_sdk"
+url: "https://pypi.org/project/roadnoise/"
+abstract: "Transparent, screening-level road traffic noise in Python: CNOSSOS-EU road source model (Directive (EU) 2015/996 as amended by Delegated Directive (EU) 2021/1226), ISO 9613 and CNOSSOS-EU flat-ground propagation, END indicators (Lden, Lnight) and exposure statistics, plus the UK CRTN quick method."
+keywords:
+  - noise
+  - road traffic noise
+  - CNOSSOS-EU
+  - Environmental Noise Directive
+  - noise mapping

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

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

roadnoise-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: roadnoise
+Version: 0.1.0
+Summary: Transparent screening-level road traffic noise in Python: CNOSSOS-EU source model, ISO 9613 propagation, END indicators (Lden, Lnight) and exposure statistics.
+Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YusufEminoglu/roadnoise_sdk
+Project-URL: Repository, https://github.com/YusufEminoglu/roadnoise_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/roadnoise_sdk/issues
+Project-URL: Changelog, https://github.com/YusufEminoglu/roadnoise_sdk/blob/main/CHANGELOG.md
+Keywords: noise,road-traffic-noise,cnossos-eu,environmental-noise-directive,noise-mapping,lden,iso-9613,acoustics,crtn,gis,urban-planning
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Physics
+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.20.0
+Provides-Extra: geo
+Requires-Dist: geopandas>=0.12.0; extra == "geo"
+Requires-Dist: shapely>=2.0.0; extra == "geo"
+Provides-Extra: raster
+Requires-Dist: rasterio>=1.3.0; extra == "raster"
+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
+
+# roadnoise
+
+Transparent, **screening-level** road traffic noise in Python for environmental-noise
+consultants, planners and researchers working in the context of the EU Environmental
+Noise Directive (END, Directive 2002/49/EC).
+
+* **CNOSSOS-EU road source model** – Directive 2002/49/EC Annex II as introduced by
+  Commission Directive (EU) 2015/996 and amended by Commission Delegated Directive
+  (EU) 2021/1226: vehicle categories 1, 2, 3, 4a, 4b (5 reserved), rolling and
+  propulsion noise per octave band 63 Hz – 8 kHz, speed laws, road-surface,
+  studded-tyre, temperature, gradient and acceleration corrections, line-source
+  emission per metre.
+* **Propagation (screening)** – geometric divergence, ISO 9613-1 atmospheric
+  absorption at any temperature / humidity, flat-ground ground effect (CNOSSOS-EU
+  homogeneous + favourable, or ISO 9613-2 general method), single-edge diffraction
+  (CNOSSOS-EU Δdif with ground terms, ISO 9613-2 D<sub>z</sub>, or Maekawa), optional
+  +3 dB facade reflection.
+* **Receivers** – segmentation of road lines into point sources, regular grids,
+  facade receivers.
+* **Indicators** – L<sub>day</sub>, L<sub>evening</sub>, L<sub>night</sub>,
+  L<sub>den</sub> (5/10 dB penalties, 12/4/8 h or Member-State variants) and END
+  exposure statistics (people per 5 dB band, optional rounding to hundreds).
+* **CRTN** – the UK *Calculation of Road Traffic Noise* (1988) as an independent
+  quick check.
+* **I/O** – GeoJSON in, ESRI ASCII grid / GeoJSON out; GeoTIFF with the `raster`
+  extra; geopandas helpers with the `geo` extra. Only `numpy` is required.
+
+> **Scope.** `roadnoise` is a screening tool. It is **not** a certified or
+> conformance-tested CNOSSOS-EU implementation and must not be used on its own for
+> strategic noise maps reported under the END. See
+> [Differences to full CNOSSOS-EU](#differences-to-full-cnossos-eu).
+
+## Installation
+
+```bash
+pip install roadnoise              # numpy only
+pip install "roadnoise[raster]"    # + rasterio for GeoTIFF output
+pip install "roadnoise[geo]"       # + geopandas/shapely helpers
+```
+
+Python 3.9 – 3.13.
+
+## Quick start
+
+```python
+import roadnoise as rn
+
+# Emission per metre of 1104 cars/h + 96 heavy vehicles/h at 50 km/h
+lw = rn.line_sound_power({"1": 1104, "3": 96}, 50)      # dB re 1 pW/m, 8 bands
+print(rn.a_weighted(lw))                                 # ~84.1 dB(A)
+
+# A road from AADT, a barrier, a building, facade receivers
+road = rn.Road.from_aadt([(0, 0), (400, 0)], aadt=24000, speed=50, heavy=0.08)
+barrier = rn.Barrier([(50, 12), (350, 12)], height=3.0)
+building = rn.Building([(150, 40), (250, 40), (250, 60), (150, 60)], height=12.0)
+pts, _ = rn.facade_receivers(building.footprint, spacing=5.0)
+
+res = rn.compute_levels([road], pts, receiver_height=4.0,
+                        barriers=[barrier], buildings=[building])
+res.lden, res.lnight          # dB(A) per receiver
+
+grid = rn.compute_grid([road], cell=10.0, margin=100.0, barriers=[barrier])
+grid.levels["lden"]           # (nrows, ncols), north-up
+
+table = rn.exposure_statistics(res.lden, population=3.0, round_to=100)
+print(table.to_text("People per Lden band"))
+```
+
+See `examples/quickstart.py` for a complete script.
+
+## Command line
+
+```bash
+roadnoise emission --flow 1200 --speed 50 --heavy 0.08
+roadnoise emission --flow 1200 --speed 90 --heavy 0.15 --surface "2-layer ZOAB" --json
+roadnoise grid roads.geojson --cell 10 -o lden.asc            # ESRI ASCII grid
+roadnoise grid roads.geojson --cell 10 -o lden.tif            # needs roadnoise[raster]
+roadnoise grid roads.geojson --cell 10 -o map.asc --indicator all --barriers walls.geojson
+roadnoise receivers roads.geojson dwellings.geojson -o out.geojson \
+          --population-field population --round-to 100
+roadnoise crtn --flow 20000 --speed 75 --heavy-pct 10 --distance 20
+roadnoise surfaces
+```
+
+Common propagation options: `--method cnossos|iso9613`, `--ground G`,
+`--temperature`, `--humidity`, `--max-distance`, `--segment`, `--facade`,
+`--buildings`, `--barriers`, `--assume-projected`.
+
+### GeoJSON input
+
+Coordinates must be in a projected CRS in metres. Files without a legacy `crs`
+member whose coordinates look like longitude/latitude are rejected (override with
+`--assume-projected`). Road properties (case-insensitive):
+
+| property | meaning |
+|---|---|
+| `AADT` | annual average daily traffic (veh/day); or give `q_day`, `q_evening`, `q_night` (veh/h) |
+| `heavy` / `heavy_pct` | heavy-vehicle fraction (0–1) / percentage |
+| `speed`, `speed_heavy` | km/h (default 50; heavy defaults to `speed`) |
+| `medium_share` | share of heavy vehicles that are category 2 (default 0 → all category 3) |
+| `two_wheeler` | motorcycle fraction (category 4b) |
+| `surface` | Table F-4 surface name (`roadnoise surfaces`) |
+| `gradient` | % (applied half uphill, half downhill) |
+| `temperature`, `studded_ratio`, `studded_months` | emission corrections |
+
+Barriers: LineStrings with `height` (m). Buildings: Polygons with `height` (m).
+Receivers: Points with optional `height` (m) or a Z coordinate.
+
+## What is implemented, and how it was checked
+
+### Coefficient tables (all shipped, none are placeholders)
+
+| table | source | verification |
+|---|---|---|
+| F-1 A<sub>R</sub>, B<sub>R</sub>, A<sub>P</sub>, B<sub>P</sub> (cat. 1, 2, 3, 4a, 4b) | Directive (EU) 2021/1226, Annex point (19)(a) | 160 values machine-compared with the EUR-Lex text of the directive |
+| F-4 road surfaces α<sub>i,m</sub>, β<sub>m</sub>, validity speeds (15 surfaces) | Directive (EU) 2021/1226, Annex point (19)(b) | 540 values machine-compared with the EUR-Lex text |
+| F-2 studded tyres a<sub>i</sub>, b<sub>i</sub> | Directive (EU) 2015/996, Appendix F (not replaced in 2021) | transcribed from the Official Journal PDF and checked by hand |
+| F-3 acceleration C<sub>R</sub>, C<sub>P</sub> | Directive (EU) 2015/996, Appendix F (not replaced in 2021) | transcribed from the Official Journal PDF and checked by hand |
+| K<sub>m</sub> temperature coefficients | Annex II §2.2.3, formula (2.2.10) | from the text |
+| A-weighting AWC<sub>f,i</sub> | Directive (EU) 2021/1226, amendment to §2.5.5 | from the text |
+
+Note that the 2021 Table F-1 differs from the 2015 one (e.g. category 1
+A<sub>R</sub> at 1 kHz is 100.1 dB, not 97.3 dB) – older tools may still use the
+2015 numbers. Category 5 has no coefficients in either directive: it raises an error
+unless you supply coefficients with `load_coefficients_csv()` (format:
+`category,coefficient,63,…,8000` with rows `AR, BR, AP, BP`; values are range-checked).
+National road surfaces can be loaded with `load_surface_csv()`
+(`name,category,63,…,8000,beta[,v_min,v_max]`).
+
+### Emission formulas (Annex II §2.2)
+
+(2.2.1) line source, (2.2.2)–(2.2.3) total power and the 20 km/h floor, (2.2.4)–(2.2.5)
+rolling noise, (2.2.6)–(2.2.9) studded tyres, (2.2.10) temperature, (2.2.11)–(2.2.12)
+propulsion, (2.2.13)–(2.2.16) gradient, (2.2.17)–(2.2.18) acceleration near junctions,
+(2.2.19)–(2.2.20) road surface (with a warning outside the validity speed range).
+
+### Propagation
+
+* A<sub>div</sub> = 20 lg d + 11 (2.5.12); A<sub>atm</sub> = α d / 1000 (2.5.13).
+* α from the ISO 9613-1 pure-tone formulae at exact band mid-frequencies. The
+  implementation reproduces **ISO 9613-2 Table 2** (e.g. 20 °C / 70 %:
+  0.1, 0.3, 1.1, 2.8, 5.0, 9.0, 22.9, 76.6 dB/km) at all six tabulated
+  temperature/humidity pairs to the printed precision (unit-tested).
+* CNOSSOS-EU ground effect (2.5.14)–(2.5.20) for homogeneous and favourable
+  conditions with G<sub>s</sub> = 0 for the road platform; long-term level (2.5.9)
+  with an occurrence p per period.
+* CNOSSOS-EU diffraction (2.5.21) with C″ = 1 (single edge), Δ<sub>ground</sub>(S,O)
+  and Δ<sub>ground</sub>(O,R) as amended in 2021, curved-ray path differences in
+  favourable conditions (2.5.24)–(2.5.27), and the 2021 diffraction criterion
+  (δ > −λ/20 and the Rayleigh criterion δ > λ/4 − δ*).
+* ISO 9613-2: general ground method (Table 3), alternative A-weighted method
+  (eq. 10), D<sub>z</sub> with K<sub>met</sub> (eq. 14, 18) capped at 20 dB,
+  A<sub>bar</sub> = D<sub>z</sub> − A<sub>gr</sub> ≥ 0, optional C<sub>met</sub>.
+* Maekawa barrier attenuation in the Kurze–Anderson closed form.
+
+The 2015/2021 Official Journal prints the ground-effect and diffraction equations as
+images. They were implemented from the published formula structure (term names,
+bounds, special cases quoted in the text) together with the standard CNOSSOS-EU
+formulation, and are unit-tested against independent hand calculations of those
+equations – but they could not be compared character-by-character with the OJ text.
+
+### CRTN (UK, 1988)
+
+Basic noise level (18 h and 1 h), speed and % heavy correction, gradient (+0.3 dB/%),
+road surface, distance, ground cover, angle of view and +2.5 dB facade. **Not
+implemented:** the barrier chart, the gradient speed reduction, the low-flow
+correction and conversions from L<sub>A10</sub> to L<sub>den</sub>. CRTN predicts
+L<sub>A10,18h</sub>, not an END indicator; use it as a cross-check only. The Nordic
+prediction methods are **not** included.
+
+### Validation in the test suite
+
+ISO 9613-2 Table 2 absorption values; hand calculations of every emission correction
+and of the ground and diffraction equations; energetic summation (60 ⊕ 60 =
+63.01 dB, ten equal sources +10 dB); L<sub>den</sub> (equal levels give L + 6.39 dB,
+Member-State period variants); flow doubling +3.01 dB; a long, finely segmented road
+over hard ground matches the analytic line-source integral L = L<sub>W</sub>′ −
+10 lg(4d) + 3 within 0.05 dB; symmetry and monotonic decay with distance; higher
+barriers shield more; CRTN reference point (75 km/h, 0 % heavy gives a 0 dB speed
+correction; 20 000 veh/18 h gives a basic noise level of 72.1 dB(A)). Coverage is
+above 95 %.
+
+## Differences to full CNOSSOS-EU
+
+`roadnoise` deliberately simplifies the propagation part. Results can differ
+significantly from a conformant CNOSSOS-EU implementation, in particular in
+built-up areas:
+
+* **Flat ground only.** No digital terrain model, no mean ground plane per path, no
+  equivalent heights, no embankments or cuttings; ground factor G is uniform.
+* **No path finding.** One straight vertical propagation plane per source–receiver
+  pair; no "rubber-band" convex hull and **no multiple diffraction**: only the single
+  most effective edge (largest path difference) is used, so thick buildings and
+  double barriers are under-estimated.
+* **No lateral (vertical-edge) diffraction** and **no reflections** from facades or
+  barriers (image sources). The optional +3 dB facade term is a flat correction.
+* Barriers and building walls are thin edges at their top height; absorption of
+  barrier surfaces is ignored.
+* The favourable-condition occurrences p (defaults day 0.5, evening 0.75, night 1.0)
+  are screening assumptions, not directional meteorological statistics.
+* The AADT → hourly-flow split (default 70 % day / 20 % evening / 10 % night) and the
+  heavy-vehicle split (default all category 3) are **placeholder assumptions**;
+  provide `q_day`/`q_evening`/`q_night`, `medium_share` and counts where available.
+* No statistical urban approach, no population/dwelling assignment rules of Annex II
+  §2.8 beyond the facade receiver helper and the per-band exposure table.
+* Sound power is computed once per road and per END period; there is no hourly
+  traffic model.
+
+## Citation
+
+If you use `roadnoise`, please cite it via `CITATION.cff`. Key references:
+
+* Directive 2002/49/EC of the European Parliament and of the Council relating to the
+  assessment and management of environmental noise (OJ L 189, 18.7.2002).
+* Commission Directive (EU) 2015/996 establishing common noise assessment methods
+  (OJ L 168, 1.7.2015).
+* Commission Delegated Directive (EU) 2021/1226 amending, for the purposes of
+  adapting to scientific and technical progress, Annex II to Directive 2002/49/EC as
+  regards common noise assessment methods (OJ L 269, 28.7.2021).
+* Kephalopoulos S., Paviotti M., Anfosso-Lédée F. (2012). *Common noise assessment
+  methods in Europe (CNOSSOS-EU)*. JRC Reference Report EUR 25379 EN.
+* ISO 9613-1:1993 *Acoustics – Attenuation of sound during propagation outdoors –
+  Part 1: Calculation of the absorption of sound by the atmosphere*.
+* ISO 9613-2:1996 *Part 2: General method of calculation*.
+* Maekawa Z. (1968). Noise reduction by screens. *Applied Acoustics* 1(3), 157–173;
+  Kurze U. J., Anderson G. S. (1971). Sound attenuation by barriers. *Applied
+  Acoustics* 4(1), 35–53.
+* Department of Transport and Welsh Office (1988). *Calculation of Road Traffic
+  Noise*. HMSO, London.
+
+## License
+
+MIT © Yusuf Eminoğlu

roadnoise-0.1.0/README.md

@@ -0,0 +1,233 @@
+# roadnoise
+
+Transparent, **screening-level** road traffic noise in Python for environmental-noise
+consultants, planners and researchers working in the context of the EU Environmental
+Noise Directive (END, Directive 2002/49/EC).
+
+* **CNOSSOS-EU road source model** – Directive 2002/49/EC Annex II as introduced by
+  Commission Directive (EU) 2015/996 and amended by Commission Delegated Directive
+  (EU) 2021/1226: vehicle categories 1, 2, 3, 4a, 4b (5 reserved), rolling and
+  propulsion noise per octave band 63 Hz – 8 kHz, speed laws, road-surface,
+  studded-tyre, temperature, gradient and acceleration corrections, line-source
+  emission per metre.
+* **Propagation (screening)** – geometric divergence, ISO 9613-1 atmospheric
+  absorption at any temperature / humidity, flat-ground ground effect (CNOSSOS-EU
+  homogeneous + favourable, or ISO 9613-2 general method), single-edge diffraction
+  (CNOSSOS-EU Δdif with ground terms, ISO 9613-2 D<sub>z</sub>, or Maekawa), optional
+  +3 dB facade reflection.
+* **Receivers** – segmentation of road lines into point sources, regular grids,
+  facade receivers.
+* **Indicators** – L<sub>day</sub>, L<sub>evening</sub>, L<sub>night</sub>,
+  L<sub>den</sub> (5/10 dB penalties, 12/4/8 h or Member-State variants) and END
+  exposure statistics (people per 5 dB band, optional rounding to hundreds).
+* **CRTN** – the UK *Calculation of Road Traffic Noise* (1988) as an independent
+  quick check.
+* **I/O** – GeoJSON in, ESRI ASCII grid / GeoJSON out; GeoTIFF with the `raster`
+  extra; geopandas helpers with the `geo` extra. Only `numpy` is required.
+
+> **Scope.** `roadnoise` is a screening tool. It is **not** a certified or
+> conformance-tested CNOSSOS-EU implementation and must not be used on its own for
+> strategic noise maps reported under the END. See
+> [Differences to full CNOSSOS-EU](#differences-to-full-cnossos-eu).
+
+## Installation
+
+```bash
+pip install roadnoise              # numpy only
+pip install "roadnoise[raster]"    # + rasterio for GeoTIFF output
+pip install "roadnoise[geo]"       # + geopandas/shapely helpers
+```
+
+Python 3.9 – 3.13.
+
+## Quick start
+
+```python
+import roadnoise as rn
+
+# Emission per metre of 1104 cars/h + 96 heavy vehicles/h at 50 km/h
+lw = rn.line_sound_power({"1": 1104, "3": 96}, 50)      # dB re 1 pW/m, 8 bands
+print(rn.a_weighted(lw))                                 # ~84.1 dB(A)
+
+# A road from AADT, a barrier, a building, facade receivers
+road = rn.Road.from_aadt([(0, 0), (400, 0)], aadt=24000, speed=50, heavy=0.08)
+barrier = rn.Barrier([(50, 12), (350, 12)], height=3.0)
+building = rn.Building([(150, 40), (250, 40), (250, 60), (150, 60)], height=12.0)
+pts, _ = rn.facade_receivers(building.footprint, spacing=5.0)
+
+res = rn.compute_levels([road], pts, receiver_height=4.0,
+                        barriers=[barrier], buildings=[building])
+res.lden, res.lnight          # dB(A) per receiver
+
+grid = rn.compute_grid([road], cell=10.0, margin=100.0, barriers=[barrier])
+grid.levels["lden"]           # (nrows, ncols), north-up
+
+table = rn.exposure_statistics(res.lden, population=3.0, round_to=100)
+print(table.to_text("People per Lden band"))
+```
+
+See `examples/quickstart.py` for a complete script.
+
+## Command line
+
+```bash
+roadnoise emission --flow 1200 --speed 50 --heavy 0.08
+roadnoise emission --flow 1200 --speed 90 --heavy 0.15 --surface "2-layer ZOAB" --json
+roadnoise grid roads.geojson --cell 10 -o lden.asc            # ESRI ASCII grid
+roadnoise grid roads.geojson --cell 10 -o lden.tif            # needs roadnoise[raster]
+roadnoise grid roads.geojson --cell 10 -o map.asc --indicator all --barriers walls.geojson
+roadnoise receivers roads.geojson dwellings.geojson -o out.geojson \
+          --population-field population --round-to 100
+roadnoise crtn --flow 20000 --speed 75 --heavy-pct 10 --distance 20
+roadnoise surfaces
+```
+
+Common propagation options: `--method cnossos|iso9613`, `--ground G`,
+`--temperature`, `--humidity`, `--max-distance`, `--segment`, `--facade`,
+`--buildings`, `--barriers`, `--assume-projected`.
+
+### GeoJSON input
+
+Coordinates must be in a projected CRS in metres. Files without a legacy `crs`
+member whose coordinates look like longitude/latitude are rejected (override with
+`--assume-projected`). Road properties (case-insensitive):
+
+| property | meaning |
+|---|---|
+| `AADT` | annual average daily traffic (veh/day); or give `q_day`, `q_evening`, `q_night` (veh/h) |
+| `heavy` / `heavy_pct` | heavy-vehicle fraction (0–1) / percentage |
+| `speed`, `speed_heavy` | km/h (default 50; heavy defaults to `speed`) |
+| `medium_share` | share of heavy vehicles that are category 2 (default 0 → all category 3) |
+| `two_wheeler` | motorcycle fraction (category 4b) |
+| `surface` | Table F-4 surface name (`roadnoise surfaces`) |
+| `gradient` | % (applied half uphill, half downhill) |
+| `temperature`, `studded_ratio`, `studded_months` | emission corrections |
+
+Barriers: LineStrings with `height` (m). Buildings: Polygons with `height` (m).
+Receivers: Points with optional `height` (m) or a Z coordinate.
+
+## What is implemented, and how it was checked
+
+### Coefficient tables (all shipped, none are placeholders)
+
+| table | source | verification |
+|---|---|---|
+| F-1 A<sub>R</sub>, B<sub>R</sub>, A<sub>P</sub>, B<sub>P</sub> (cat. 1, 2, 3, 4a, 4b) | Directive (EU) 2021/1226, Annex point (19)(a) | 160 values machine-compared with the EUR-Lex text of the directive |
+| F-4 road surfaces α<sub>i,m</sub>, β<sub>m</sub>, validity speeds (15 surfaces) | Directive (EU) 2021/1226, Annex point (19)(b) | 540 values machine-compared with the EUR-Lex text |
+| F-2 studded tyres a<sub>i</sub>, b<sub>i</sub> | Directive (EU) 2015/996, Appendix F (not replaced in 2021) | transcribed from the Official Journal PDF and checked by hand |
+| F-3 acceleration C<sub>R</sub>, C<sub>P</sub> | Directive (EU) 2015/996, Appendix F (not replaced in 2021) | transcribed from the Official Journal PDF and checked by hand |
+| K<sub>m</sub> temperature coefficients | Annex II §2.2.3, formula (2.2.10) | from the text |
+| A-weighting AWC<sub>f,i</sub> | Directive (EU) 2021/1226, amendment to §2.5.5 | from the text |
+
+Note that the 2021 Table F-1 differs from the 2015 one (e.g. category 1
+A<sub>R</sub> at 1 kHz is 100.1 dB, not 97.3 dB) – older tools may still use the
+2015 numbers. Category 5 has no coefficients in either directive: it raises an error
+unless you supply coefficients with `load_coefficients_csv()` (format:
+`category,coefficient,63,…,8000` with rows `AR, BR, AP, BP`; values are range-checked).
+National road surfaces can be loaded with `load_surface_csv()`
+(`name,category,63,…,8000,beta[,v_min,v_max]`).
+
+### Emission formulas (Annex II §2.2)
+
+(2.2.1) line source, (2.2.2)–(2.2.3) total power and the 20 km/h floor, (2.2.4)–(2.2.5)
+rolling noise, (2.2.6)–(2.2.9) studded tyres, (2.2.10) temperature, (2.2.11)–(2.2.12)
+propulsion, (2.2.13)–(2.2.16) gradient, (2.2.17)–(2.2.18) acceleration near junctions,
+(2.2.19)–(2.2.20) road surface (with a warning outside the validity speed range).
+
+### Propagation
+
+* A<sub>div</sub> = 20 lg d + 11 (2.5.12); A<sub>atm</sub> = α d / 1000 (2.5.13).
+* α from the ISO 9613-1 pure-tone formulae at exact band mid-frequencies. The
+  implementation reproduces **ISO 9613-2 Table 2** (e.g. 20 °C / 70 %:
+  0.1, 0.3, 1.1, 2.8, 5.0, 9.0, 22.9, 76.6 dB/km) at all six tabulated
+  temperature/humidity pairs to the printed precision (unit-tested).
+* CNOSSOS-EU ground effect (2.5.14)–(2.5.20) for homogeneous and favourable
+  conditions with G<sub>s</sub> = 0 for the road platform; long-term level (2.5.9)
+  with an occurrence p per period.
+* CNOSSOS-EU diffraction (2.5.21) with C″ = 1 (single edge), Δ<sub>ground</sub>(S,O)
+  and Δ<sub>ground</sub>(O,R) as amended in 2021, curved-ray path differences in
+  favourable conditions (2.5.24)–(2.5.27), and the 2021 diffraction criterion
+  (δ > −λ/20 and the Rayleigh criterion δ > λ/4 − δ*).
+* ISO 9613-2: general ground method (Table 3), alternative A-weighted method
+  (eq. 10), D<sub>z</sub> with K<sub>met</sub> (eq. 14, 18) capped at 20 dB,
+  A<sub>bar</sub> = D<sub>z</sub> − A<sub>gr</sub> ≥ 0, optional C<sub>met</sub>.
+* Maekawa barrier attenuation in the Kurze–Anderson closed form.
+
+The 2015/2021 Official Journal prints the ground-effect and diffraction equations as
+images. They were implemented from the published formula structure (term names,
+bounds, special cases quoted in the text) together with the standard CNOSSOS-EU
+formulation, and are unit-tested against independent hand calculations of those
+equations – but they could not be compared character-by-character with the OJ text.
+
+### CRTN (UK, 1988)
+
+Basic noise level (18 h and 1 h), speed and % heavy correction, gradient (+0.3 dB/%),
+road surface, distance, ground cover, angle of view and +2.5 dB facade. **Not
+implemented:** the barrier chart, the gradient speed reduction, the low-flow
+correction and conversions from L<sub>A10</sub> to L<sub>den</sub>. CRTN predicts
+L<sub>A10,18h</sub>, not an END indicator; use it as a cross-check only. The Nordic
+prediction methods are **not** included.
+
+### Validation in the test suite
+
+ISO 9613-2 Table 2 absorption values; hand calculations of every emission correction
+and of the ground and diffraction equations; energetic summation (60 ⊕ 60 =
+63.01 dB, ten equal sources +10 dB); L<sub>den</sub> (equal levels give L + 6.39 dB,
+Member-State period variants); flow doubling +3.01 dB; a long, finely segmented road
+over hard ground matches the analytic line-source integral L = L<sub>W</sub>′ −
+10 lg(4d) + 3 within 0.05 dB; symmetry and monotonic decay with distance; higher
+barriers shield more; CRTN reference point (75 km/h, 0 % heavy gives a 0 dB speed
+correction; 20 000 veh/18 h gives a basic noise level of 72.1 dB(A)). Coverage is
+above 95 %.
+
+## Differences to full CNOSSOS-EU
+
+`roadnoise` deliberately simplifies the propagation part. Results can differ
+significantly from a conformant CNOSSOS-EU implementation, in particular in
+built-up areas:
+
+* **Flat ground only.** No digital terrain model, no mean ground plane per path, no
+  equivalent heights, no embankments or cuttings; ground factor G is uniform.
+* **No path finding.** One straight vertical propagation plane per source–receiver
+  pair; no "rubber-band" convex hull and **no multiple diffraction**: only the single
+  most effective edge (largest path difference) is used, so thick buildings and
+  double barriers are under-estimated.
+* **No lateral (vertical-edge) diffraction** and **no reflections** from facades or
+  barriers (image sources). The optional +3 dB facade term is a flat correction.
+* Barriers and building walls are thin edges at their top height; absorption of
+  barrier surfaces is ignored.
+* The favourable-condition occurrences p (defaults day 0.5, evening 0.75, night 1.0)
+  are screening assumptions, not directional meteorological statistics.
+* The AADT → hourly-flow split (default 70 % day / 20 % evening / 10 % night) and the
+  heavy-vehicle split (default all category 3) are **placeholder assumptions**;
+  provide `q_day`/`q_evening`/`q_night`, `medium_share` and counts where available.
+* No statistical urban approach, no population/dwelling assignment rules of Annex II
+  §2.8 beyond the facade receiver helper and the per-band exposure table.
+* Sound power is computed once per road and per END period; there is no hourly
+  traffic model.
+
+## Citation
+
+If you use `roadnoise`, please cite it via `CITATION.cff`. Key references:
+
+* Directive 2002/49/EC of the European Parliament and of the Council relating to the
+  assessment and management of environmental noise (OJ L 189, 18.7.2002).
+* Commission Directive (EU) 2015/996 establishing common noise assessment methods
+  (OJ L 168, 1.7.2015).
+* Commission Delegated Directive (EU) 2021/1226 amending, for the purposes of
+  adapting to scientific and technical progress, Annex II to Directive 2002/49/EC as
+  regards common noise assessment methods (OJ L 269, 28.7.2021).
+* Kephalopoulos S., Paviotti M., Anfosso-Lédée F. (2012). *Common noise assessment
+  methods in Europe (CNOSSOS-EU)*. JRC Reference Report EUR 25379 EN.
+* ISO 9613-1:1993 *Acoustics – Attenuation of sound during propagation outdoors –
+  Part 1: Calculation of the absorption of sound by the atmosphere*.
+* ISO 9613-2:1996 *Part 2: General method of calculation*.
+* Maekawa Z. (1968). Noise reduction by screens. *Applied Acoustics* 1(3), 157–173;
+  Kurze U. J., Anderson G. S. (1971). Sound attenuation by barriers. *Applied
+  Acoustics* 4(1), 35–53.
+* Department of Transport and Welsh Office (1988). *Calculation of Road Traffic
+  Noise*. HMSO, London.
+
+## License
+
+MIT © Yusuf Eminoğlu

roadnoise-0.1.0/examples/quickstart.py

@@ -0,0 +1,35 @@
+"""Minimal end-to-end example: emission, receivers, a noise map and exposure.
+
+Run from the repository root:  python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+import roadnoise as rn
+
+# 1. Emission of a traffic flow (CNOSSOS-EU, Table F-1 of Directive (EU) 2021/1226).
+lw = rn.line_sound_power({"1": 1104, "3": 96}, 50)
+print("L_W' per band:", np.round(lw, 1), f"-> {float(rn.a_weighted(lw)):.1f} dB(A) re 1 pW/m")
+
+# 2. Two roads from AADT (projected coordinates in metres).
+main = rn.Road.from_aadt([(0, 0), (400, 0)], aadt=24000, speed=50, heavy=0.08)
+side = rn.Road.from_aadt([(200, -150), (200, -10)], aadt=4000, speed=30, heavy=0.02)
+barrier = rn.Barrier([(50, 12), (350, 12)], height=3.0)
+building = rn.Building([(150, 40), (250, 40), (250, 60), (150, 60)], height=12.0)
+
+# 3. Facade receivers of the building, 4 m high, 0.1 m in front of each wall.
+pts, _ = rn.facade_receivers(building.footprint, spacing=5.0)
+res = rn.compute_levels([main, side], pts, 4.0, barriers=[barrier], buildings=[building])
+print(f"Facade L_den: {np.nanmin(res.lden):.1f} - {np.nanmax(res.lden):.1f} dB(A)")
+
+# 4. Exposure: 60 residents in the building, assigned to the most exposed facade.
+table = rn.exposure_statistics([res.lden.max()], [60])
+print(table.to_text("Residents per L_den band"))
+
+# 5. A 10 m noise map.
+grid = rn.compute_grid(
+    [main, side], cell=10.0, margin=60.0, barriers=[barrier], buildings=[building]
+)
+print("grid shape", grid.levels["lden"].shape)