windwhisper.ambient_noise
=========================

.. py:module:: windwhisper.ambient_noise

.. autoapi-nested-parse::

   This module fetches existing sources of noise from teh EU Noise maps, to figure out whether
   implementing one or several wind turbines in a given area would be a net contribution to the
   ambient noise level or not. Source: https://www.eea.europa.eu/en/datahub/datahubitem-view/c952f520-8d71-42c9-b74c-b7eb002f939b



Attributes
----------

.. autoapisummary::

   windwhisper.ambient_noise.NOISE_MAPS_URLS_LDEN
   windwhisper.ambient_noise.NOISE_MAPS_URLS_LNIGHT
   windwhisper.ambient_noise.PIXEL_VALUE_TO_LDEN


Functions
---------

.. autoapisummary::

   windwhisper.ambient_noise.get_noise_values
   windwhisper.ambient_noise.combine_noise_levels
   windwhisper.ambient_noise.get_ambient_noise_levels
   windwhisper.ambient_noise.create_xarray_from_raster


Module Contents
---------------

.. py:data:: NOISE_MAPS_URLS_LDEN

.. py:data:: NOISE_MAPS_URLS_LNIGHT

.. py:data:: PIXEL_VALUE_TO_LDEN

.. py:function:: get_noise_values(url, x_min, x_max, y_min, y_max, resolution)

   Fetch an EU noise raster for the requested bounding box.

   The EU services accept bounding boxes in the European LAEA CRS (EPSG:3035).
   The raster is requested as a GeoTIFF and converted to Lden or Lnight values
   according to the ``PIXEL_VALUE_TO_LDEN`` lookup table.

   :param url: Service endpoint returning the GeoTIFF noise map.
   :type url: str
   :param x_min: Minimum easting of the bounding box in EPSG:3035.
   :type x_min: float
   :param x_max: Maximum easting of the bounding box in EPSG:3035.
   :type x_max: float
   :param y_min: Minimum northing of the bounding box in EPSG:3035.
   :type y_min: float
   :param y_max: Maximum northing of the bounding box in EPSG:3035.
   :type y_max: float
   :param resolution: Grid resolution as ``(rows, columns)``.
   :type resolution: tuple[int, int]
   :returns: Raster values converted to Lden/Lnight when the request succeeds
       or ``None`` when the remote service responds with an error.
   :rtype: numpy.ndarray | None


.. py:function:: combine_noise_levels(noise_layers)

   Combine multiple Lden/Lnight rasters into a single layer.

   :param noise_layers: Collection of rasters to combine. ``None`` elements are
       ignored.
   :type noise_layers: list[numpy.ndarray | None]
   :returns: Combined Lden/Lnight raster in dB.
   :rtype: numpy.ndarray


.. py:function:: get_ambient_noise_levels(latitudes, longitudes, resolution, lden=True)

   Retrieve the combined ambient noise level for a target grid.

   :param latitudes: Latitude coordinates defining the output grid.
   :type latitudes: numpy.ndarray
   :param longitudes: Longitude coordinates defining the output grid.
   :type longitudes: numpy.ndarray
   :param resolution: Output resolution expressed as ``(rows, columns)``.
   :type resolution: tuple[int, int]
   :param lden: When ``True`` request Lden rasters, otherwise request Lnight.
   :type lden: bool
   :returns: Ambient noise interpolated on the requested grid.
   :rtype: xarray.DataArray | None


.. py:function:: create_xarray_from_raster(data, x_min, x_max, y_min, y_max)

   Convert a raster array into an ``xarray.DataArray`` in EPSG:4326.

   :param data: Raster values in an evenly spaced grid in EPSG:3035.
   :type data: numpy.ndarray
   :param x_min: Minimum easting of the bounding box in EPSG:3035.
   :type x_min: float
   :param x_max: Maximum easting of the bounding box in EPSG:3035.
   :type x_max: float
   :param y_min: Minimum northing of the bounding box in EPSG:3035.
   :type y_min: float
   :param y_max: Maximum northing of the bounding box in EPSG:3035.
   :type y_max: float
   :returns: Raster with latitude/longitude coordinates.
   :rtype: xarray.DataArray