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
