.. _dsm_filling_app:

DSM Filling
===========

**Name**: "dsm_filling"

**Description**

Fill classified values or missing values with one the three avalable methods.

.. note::

    Filling can be configured directly in the :ref:`input <running_cars_with_sensor_images_as_input>` configuration. Each method combines several available filling applications.

**Configuration**

+-------------------------------------+---------------------------------+---------+----------------------------------------------------------+--------------------+----------+
| Name                                | Description                     | Type    | Available value                                          | Default value      | Required |
+=====================================+=================================+=========+==========================================================+====================+==========+
| method                              | Method for hole detection       | string  | "exogenous_filling", "bulldozer", "border_interpolation" |                    | Yes      |
+-------------------------------------+---------------------------------+---------+----------------------------------------------------------+--------------------+----------+
| save_intermediate_data              | Save disparity map              | boolean |                                                          | False              | No       |
+-------------------------------------+---------------------------------+---------+----------------------------------------------------------+--------------------+----------+


**Method exogenous_filling:**

Method "exogenous_filling" fills with altitude of exogenous data (DEM/geoid).

+-------------------------------------+----------------------------------------------------+-------------+-------------------------+--------------------+----------+
| Name                                | Description                                        | Type        | Available value         | Default value      | Required |
+=====================================+====================================================+=============+=========================+====================+==========+
| fill_classification                 | Values of classes to fill                          | List[str]   |                         | "nodata"           | No       |
+-------------------------------------+----------------------------------------------------+-------------+-------------------------+--------------------+----------+
| fill_nodata                         | Values of the invalidity_mask to fill              | List[str]   |                         | None               | No       |
+-------------------------------------+----------------------------------------------------+-------------+-------------------------+--------------------+----------+
| fill_with_geoid                     | Classes to fill with geoid                         | List[str]   |                         | None               | No       |
+-------------------------------------+----------------------------------------------------+-------------+-------------------------+--------------------+----------+
| interpolation_method                | Interpolation method for DEM and geoid resampling  | List[str]   | "bilinear", "cubic"     | "bilinear"         | No       |
+-------------------------------------+----------------------------------------------------+-------------+-------------------------+--------------------+----------+


**Method bulldozer:**

Method "bulldozer" converts the DSM to a DTM and fills the pixels with the output DTM.

+-------------------------------------+---------------------------------------+-----------+-------------------------+--------------------+----------+
| Name                                | Description                           | Type      | Available value         | Default value      | Required |
+=====================================+=======================================+===========+=========================+====================+==========+
| fill_classification                 | Values of classes to fill             | List[str] |                         | "nodata"           | No       |
+-------------------------------------+---------------------------------------+-----------+-------------------------+--------------------+----------+
| fill_nodata                         | Values of the invalidity_mask to fill | List[str] |                         | None               | No       |
+-------------------------------------+---------------------------------------+-----------+-------------------------+--------------------+----------+


**Method border_interpolation:**

Method "border_interpolation" use the border of every component to compute the altitude to fill.

+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| Name                                | Description                              | Type      | Available value         | Default value      | Required |
+=====================================+==========================================+===========+=========================+====================+==========+
| fill_classification                 | Values of classes to fill                | List[str] |                         | "nodata"           | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| fill_nodata                         | Values of the invalidity_mask to fill    | List[str] |                         | None               | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| component_min_size                  | Minimal size (pixels) of feature to fill | int       |                         | 5                  | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| border_size                         | Size of border used to estimate altitude | int       |                         | 10                 | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| percentile                          | Percentile of border taken for altitude  | float     |                         | 10                 | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+

**Method interpolation:**

Method "interpolation" reconstruct invalid or missing pixels in a raster by interpolating neighboring valid values.

+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| Name                                | Description                              | Type      | Available value         | Default value      | Required |
+=====================================+==========================================+===========+=========================+====================+==========+
| fill_classification                 | Values of classes to fill                | List[str] |                         | "nodata"           | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| fill_nodata                         | Values of the invalidity_mask to fill    | List[str] |                         | None               | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| tile_size                           | The size of tiles                        | int       |                         | 2000               | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| margin                              | The margin used for tiling               | int       |                         | 100                | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+
| percentile                          | Percentile of border taken for altitude  | float     |                         | 10                 | No       |
+-------------------------------------+------------------------------------------+-----------+-------------------------+--------------------+----------+


.. note::
    - If the keyword "nodata" is added to the classification parameter, nodata pixels of the classification will be filled. If no classification is given, nodata pixels of DSM will be filled.
    - The values available in fill_nodata are 1 and 2, which correspond to occlusion and mismatch, respectively.

.. warning::

    There is a particular case with the *dsm_filling* application because it can be called any number of times.
    Because it is not possible to define three times the *dsm_filling* in your yaml/json configuration file, you can add an identifier after *dsm_filling* to differentiate each application :

    * *dsm_filling.border_interp*
    * *dsm_filling.two*
    * *dsm_filling.with_bulldozer*

    It is recommended to run bulldozer before border_interpolation in order for border_interpolation to get a DTM. If no DTM is found, border_interpolation will use the DSM.
    The execution order is determined by the order of the applications in the configuration file.

**Example**

.. include-cars-config:: ../../example_configs/configuration/applications_dsm_filling_1

.. include-cars-config:: ../../example_configs/configuration/applications_dsm_filling_2

.. include-cars-config:: ../../example_configs/configuration/applications_dsm_filling_3