Merge remote-tracking branch 'ifsttar/4.X' into 4.X_TraficProba

# Conflicts:
#	pom.xml
#	wps_scripts/build.gradle
#	wps_scripts/src/main/groovy/org/noise_planet/noisemodelling/wps/Experimental_Matsim/Noise_From_Attenuation_Matrix_MatSim.groovy
#	wps_scripts/src/main/groovy/org/noise_planet/noisemodelling/wps/NoiseModelling/Traffic_Probabilistic_Modelling.groovy

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation with MkDocs
+#mkdocs:
+# configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+ - pdf
+ - htmlzip
+ - epub
+
+build:
+ os: "ubuntu-22.04"
+ tools:
+ python: "3.11"

Docs/Input_acoustics.rst

@@ -0,0 +1,123 @@
+Acoustic parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the different WPS scripts of NoiseModelling, you will find many input parameters, mandatory or optional. 
+
+Below we list the most important ones, indicating, where necessary, the default values and those we recommend (from an acoustic point of view).
+
+.. figure:: images/Input_tables/acoustics_parameters_banner.png
+ :align: center
+
+
+
+The following parameters may be found in the scripts dealing with noise emission or propagation (*e.g* ``Noise_level_from_traffic``, ``Noise_level_from_source```, ...)
+
+
+Probability of occurrences
+--------------------------------
+
+* Parameter name: ``confFavorableOccurrencesXXXXX`` (with ``XXXXX`` = evening, day, night, ...)
+* Description: Comma-delimited string containing the probability ([0,1]) of occurrences of favourable propagation conditions. Follow the clockwise direction. The north slice is the last array index (n°16 in the schema below) not the first one
+* Type: Double
+* Default value: ``0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5``
+* Recommanded value: 
+
+.. figure:: images/Input_tables/acoustics_parameters_confFavorableOccurrences.png
+ :align: center
+
+Relative humidity
+--------------------------------
+
+* Parameter name: ``confHumidity``
+* Description: Humidity for noise propagation (%) [0,100]
+* Type: Double
+* Default value: ``70``
+* Recommanded value: depends on the average conditions at the location where you perform the simulation
+
+Air temperature
+--------------------------------
+
+* Parameter name: ``confTemperature``
+* Description: Air temperature (°C)
+* Type: Double
+* Default value: ``15``
+* Recommanded value: depends on the average conditions at the location where you perform the simulation
+
+Order of reflexion
+--------------------------------
+
+* Parameter name: ``confReflOrder``
+* Description: Maximum number of reflections to be taken into account. Warning: adding 1 order increases the processing time significantly
+* Type: Integer
+* Default value: ``1``
+* Recommanded value: ``1`` or ``2``
+
+Diffraction on horizontal edges
+--------------------------------
+
+* Parameter name: ``confDiffHorizontal``
+* Description: Compute or not the diffraction on horizontal edges
+* Type: Boolean
+* Default value: ``False``
+* Recommanded value: ``True``
+
+Diffraction on vertical edges
+--------------------------------
+
+* Parameter name: ``confDiffVertical``
+* Description: Compute or not the diffraction on vertical edges. Following Directive 2015/996, enable this option for rail and industrial sources only
+* Type: Boolean
+* Default value: ``False``
+* Recommanded value: 
+
+Maximum source-receiver distance
+----------------------------------
+
+* Parameter name: ``confMaxSrcDist``
+* Description: Maximum distance between source and receiver (meters)
+* Type: Double
+* Default value: ``150``
+* Recommanded value: Between ``500`` and ``800``
+
+.. figure:: images/Input_tables/acoustics_parameters_confMaxSrcDist.png
+ :align: center
+
+Maximum source-reflexion distance
+------------------------------------
+
+* Parameter name: ``confMaxReflDist``
+* Description: Maximum search distance of walls / facades from the "Source-Receiver" segment, for the calculation of specular reflections (meters)
+* Type: Double
+* Default value: ``50``
+* Recommanded value: Between ``350`` and ``800``
+
+.. figure:: images/Input_tables/acoustics_parameters_confMaxReflDist.png
+ :align: center
+
+
+Wall absorption coefficient
+--------------------------------
+
+* Parameter name: ``paramWallAlpha``
+* Description: Wall absorption coefficient [0,1] (between ``0`` : "fully absorbent" and ``1`` : "fully reflective")
+* Type: Double
+* Default value: ``0.1``
+* Recommanded value: ``0.1``
+
+Separate receiver level by source identifier
+---------------------------------------------
+
+* Parameter name: ``confExportSourceId``
+* Description: Keep source identifier in output in order to get noise contribution of each noise source
+* Type: Boolean
+* Default value: ``False``
+* Recommanded value: 
+
+Thread number
+--------------------------------
+
+* Parameter name: ``confThreadNumber``
+* Description: Number of thread to use on the computer
+* Type: Integer
+* Default value: ``0`` (``0`` = Automatic. Will check the number of cores and apply -1. (*e.g*: 8 cores = 7 cores will be used))
+* Recommanded value: ``0``

Docs/Input_buildings.rst

@@ -0,0 +1,138 @@
+Buildings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+NoiseModelling is a tool for producing noise maps. To do so, at different stages of the process, the application needs input data, respecting a strict formalism.
+
+Below we describe the table ``BUILDINGS``, dealing with buildings. 
+
+The other tables are accessible via the left menu in the ``Input tables & parameters`` section.
+
+.. figure:: images/Input_tables/building_banner.png
+ :align: center
+
+Table definition
+---------------------
+
+.. warning::
+ In the list below, the columns noted with ``*`` are mandatory
+
+* ``THE_GEOM`` *
+ * Description: building's geometry. It can be in 2D (stuck to the ground) or in 3D (see :ref:`Geometry modelling` section below)
+ * Type: Geometry (``POLYGON`` or ``MULTIPOLYGON``)
+* ``HEIGHT`` *
+ * Description: building's height *(in meters)* 
+ * Type: Double
+* ``POP``
+ * Description: number of inhabitant in the building 
+ * Type: Double
+
+.. note::
+ If you want to generate a scene without buildings, create two fictitious buildings, placed in two corners of the scene, and assign them a height of 0 meter.
+
+Geometry modelling
+---------------------
+
+In NoiseModelling, the geometry of the building is used to calculate the 3D ray path of the acoustic wave. Therefore, we need to know the footprint of the building as well as the points in height (at the roof, the gutter, ...)
+
+To determine the 3D shape of the building we can use some of the following elements:
+
+* ``Zground`` : The ground altitude, exprimed in meters and based on the 0 sea level
+* ``Zobject`` : The altitude in the air, exprimed in meters and based on the 0 sea level
+* ``HEIGHT``: The height, equal to the diffirence between ``Zobject`` and ``Zground``
+
+.. figure:: images/Input_tables/building_z_z_h.png
+ :align: center
+
+In this context, geometry coordinates have to be in 3D, with:
+
+* ``X`` and ``Y`` coordinates corresponding to the building's footprint (or the gutter/roof projection to the ground)
+* ``Z`` = ``Zobject`` : coordinate corresponding to the gutter or the roof altitude(s), ...
+
+
+
+Z coordinate deduction
+-----------------------
+
+Depending on the information you have, NoiseModelling will adpat the process to deduce the ``Zobject`` information and therefore the 3D frame of the building.
+
+Two cases are possible:
+
+1. The geometry has no Z coordinate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is a DEM layer
+***********************
+
+The DEM is triangulated. Then, all the vertices of the building are projected onto the triangle below it in order to determine their altitudes. Finally, the minimum altitude is taken and assigned to the whole building: ``Zground`` = Minimum DEM Z value. Then:
+
+* If ``HEIGHT`` > 0 then ``Zobject`` = ``Zground`` + ``HEIGHT``
+* If ``HEIGHT`` = 0 then ``Zobject`` = ``Zground`` and Warning message *"Be carreful, some buildings are 0 meter high"*
+* If ``HEIGHT`` null or < 0 then Error message *"Not possible to determine Z coordinates"*
+
+There is no DEM layer
+***********************
+
+* If ``HEIGHT`` > 0 then ``Zobject`` = ``HEIGHT``
+* If ``HEIGHT`` = 0 then ``Zobject`` = 0 and Warning message *"Be carreful, some buildings are 0 meter high"*
+* If ``HEIGHT`` null or < 0 then Error message *"Not possible to determine Z coordinates"*
+
+
+2. The geometry has a Z coordinate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* The Z coordinate correspond to ``Zobject``
+ * It's ok, your data is already ready to be used by NoiseModelling
+* The Z coordinate correspond to ``Zground``
+ * You are invited to correct ``Z`` value(s) by changing the information by yourself or by using the dedicated WPS block called ``Correct_building_altitude``
+
+Below is an example with a initial geometry (coordinates are exprimed in French Lambert 93 (`EPSG:2154`_) system) with a ``Zground`` value coupled with ``HEIGHT`` information. After correction, the geometry has a correct Z value, which corresponds to ``Zobject``.
+
+
+.. figure:: images/Input_tables/building_zground.png
+ :align: center
+
+.. _EPSG:2154 : https://epsg.io/2154
+
+Ray path 
+-----------------------
+
+Depending on the building modelisation and the ``Zobject`` you have, the acoustic wave path will differ.
+
+In the 4 examples below, 
+
+* the left-hand side is dealing with the building's modelisation. Pink circles represents the vertices of the geometry
+* the right-hand side represents the corresponding path of the ray (in red), from the sound source (S) to the receiver (R) and how the building (in grey) is "understood" by NoiseModelling.
+
+Case 1 : there is no roof
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: images/Input_tables/building_case_1.png
+ :align: center
+
+Case 2 : ``Zobject`` is on the gutter level
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: images/Input_tables/building_case_2.png
+ :align: center
+
+Case 3 : ``Zobject`` is on top ot the roof
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: images/Input_tables/building_case_3.png
+ :align: center
+
+Case 4 : Complex roof shape
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: images/Input_tables/building_case_4.png
+ :align: center
+
+Topology
+-----------------------
+
+In the table ``BUILDINGS`` there is no topological constraint. Even if it is not recommended, this means that NoiseModelling accepts that the buildings overlap. In this case, the highest points and edges will be retained for the determination of the wave path.
+
+The figure below illustrate this possibility with two buildings that overlaps. The wave is going from the source ``S`` to the receveiver ``R``.
+
+.. figure:: images/Input_tables/building_topology.png
+ :align: center

Docs/Input_dem.rst

@@ -0,0 +1,48 @@
+DEM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+NoiseModelling is a tool for producing noise maps. To do so, at different stages of the process, the application needs input data, respecting a strict formalism.
+
+Below we describe the table ``DEM``, dealing with the Digital Elevation Model matrix. 
+
+The other tables are accessible via the left menu in the ``Input tables & parameters`` section.
+
+
+.. figure:: images/Input_tables/dem_banner.png
+ :align: center
+
+.. note::
+ If your DEM is in raster, please use the ``Import_Asc_File`` WPS script which will format your DEM in the right format
+
+
+Table definition
+---------------------
+
+.. warning::
+ In the list below, the column noted with ``*`` is mandatory
+
+* ``THE_GEOM`` *
+ * Description: 3D point of the matrix (``POINT`` or ``MULTIPOINT``). Z coordinate represent the altitude from the 0 sea level.
+ * Type: Geometry
+
+
+DEM enrichment
+---------------------
+
+If you have input data with a good elevation quality (better than the DEM one) / higher density and if you are comfortable with GIS tools, you are invited to enrich your DEM so that it takes into account the structuring elements of the territory.
+
+.. note::
+ You can find dedicated scripts (*e.g* ``Enrich_DEM_with_lines``, ...) in the ``Geometric Tools`` section of the left-side menu of NoiseModelling
+
+Below is an example of DEM enrichment using road network:
+
+#. Roads (red lines) are inserted into the DEM (blue points),
+#. Roads are densified in order to have more points (red) (for example a new point every 5m along the road). For each new point, the altitude (``Za1``, ``Za2``, ...) is deduced from a linear interpolation between input vertices (``Za``, ``Zb``, ``Zc``, ...),
+#. We generate the road platform (pink area), using the road's width or an arbitrary distance (*e.g* 3m). The densified points (green), which keep the interpolated altitudes, are placed along this new plateform,
+#. All the DEM points that intersects the road platform are removed from the layer.
+
+.. figure:: images/Input_tables/dem_enrichment.png
+ :align: center
+ :width: 70%
+
+

Docs/Input_directivity.rst

@@ -0,0 +1,54 @@
+Directivity
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+NoiseModelling is a tool for producing noise maps. To do so, at different stages of the process, the application needs input data, respecting a strict formalism.
+
+Below we describe the table ``DIRECTIVITY``, containing all the directivity parameters. 
+
+The other tables are accessible via the left menu in the ``Input tables`` section.
+
+.. figure:: images/Input_tables/directivity_banner.png
+ :align: center
+
+.. note::
+ If you want to see how to use this table, have a look to the tutorial ":doc:`Noise_Map_From_Point_Source`" , in the section ``Step 5 (bonus): Change the directivity``
+
+Table definition
+---------------------
+
+.. warning::
+ In the list below, the columns noted with ``*`` are mandatory
+
+* ``DIR_ID`` *
+ * Description: identifier of the directivity sphere
+ * Type: Integer
+* ``THETA``
+ * Description: vertical angle in degrees, 0 (front), -90 (bottom), 90 (top), from -90 to 90
+ * Type: Double
+* ``PHI``
+ * Description: horizontal angle in degrees, 0 (front) / 90 (right), from 0 to 360
+ * Type: Double
+* ``LW63``
+ * Description: attenuation levels in dB for 63 Hz
+ * Type: Double
+* ``LW125``
+ * Description: attenuation levels in dB for 125 Hz
+ * Type: Double
+* ``LW250``
+ * Description: attenuation levels in dB for 250 Hz
+ * Type: Double
+* ``LW500``
+ * Description: attenuation levels in dB for 500 Hz
+ * Type: Double
+* ``LW1000``
+ * Description: attenuation levels in dB for 1000 Hz
+ * Type: Double
+* ``LW2000``
+ * Description: attenuation levels in dB for 2000 Hz
+ * Type: Double
+* ``LW4000``
+ * Description: attenuation levels in dB for 4000 Hz
+ * Type: Double
+* ``LW8000``
+ * Description: attenuation levels in dB for 8000 Hz
+ * Type: Double