floodresilience.flood_model.process_hydro_dem
=============================================

.. py:module:: floodresilience.flood_model.process_hydro_dem

.. autoapi-nested-parse::

   This script fetches LiDAR terrain data for a region of interest and creates a hydrologically-conditioned DEM.
   It provides functions to retrieve information about the hydrologically-conditioned DEM and extract its boundary lines.



Attributes
----------

.. autoapisummary::

   floodresilience.flood_model.process_hydro_dem.log


Functions
---------

.. autoapisummary::

   floodresilience.flood_model.process_hydro_dem.retrieve_hydro_dem_info
   floodresilience.flood_model.process_hydro_dem.get_hydro_dem_boundary_lines
   floodresilience.flood_model.process_hydro_dem.ensure_lidar_datasets_initialised
   floodresilience.flood_model.process_hydro_dem.process_dem
   floodresilience.flood_model.process_hydro_dem.refresh_lidar_datasets
   floodresilience.flood_model.process_hydro_dem.main


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

.. py:data:: log

.. py:function:: retrieve_hydro_dem_info(engine: sqlalchemy.engine.Engine, catchment_area: geopandas.GeoDataFrame) -> Tuple[xarray.Dataset, shapely.LineString, Union[int, float]]

   Retrieve the Hydrologically Conditioned DEM (Hydro DEM) data, along with its spatial extent and resolution,
   for the specified catchment area.

   :param engine: The engine used to connect to the database.
   :type engine: Engine
   :param catchment_area: A GeoDataFrame representing the catchment area.
   :type catchment_area: gpd.GeoDataFrame

   :returns: A tuple containing the Hydro DEM data as a xarray Dataset, the spatial extent of the Hydro DEM as a LineString,
             and the resolution of the Hydro DEM as either an integer or a float.
   :rtype: Tuple[xr.Dataset, LineString, Union[int, float]]


.. py:function:: get_hydro_dem_boundary_lines(engine: sqlalchemy.engine.Engine, catchment_area: geopandas.GeoDataFrame) -> geopandas.GeoDataFrame

   Get the boundary lines of the Hydrologically Conditioned DEM.

   :param engine: The engine used to connect to the database.
   :type engine: Engine
   :param catchment_area: A GeoDataFrame representing the catchment area.
   :type catchment_area: gpd.GeoDataFrame

   :returns: A GeoDataFrame containing the boundary lines of the Hydrologically Conditioned DEM.
   :rtype: gpd.GeoDataFrame


.. py:function:: ensure_lidar_datasets_initialised() -> None

   Check if LiDAR datasets table is initialised.
   This table holds URLs to data sources for LiDAR.
   If it is not initialised, then it initialises it by web-scraping OpenTopography which takes a long time.


.. py:function:: process_dem(selected_polygon_gdf: geopandas.GeoDataFrame) -> None

   Ensure hydrologically-conditioned DEM is processed for the given area and added to the database.

   :param selected_polygon_gdf: The polygon defining the selected area to process the DEM for.
   :type selected_polygon_gdf: gpd.GeoDataFrame


.. py:function:: refresh_lidar_datasets() -> None

   Web-scrapes OpenTopography metadata to create the datasets table containing links to LiDAR data sources.
   Takes a long time to run but needs to be run periodically so that the datasets are up to date.


.. py:function:: main(selected_polygon_gdf: geopandas.GeoDataFrame, log_level: src.digitaltwin.utils.LogLevel = LogLevel.DEBUG) -> None

   Retrieve LiDAR data for the selected polygon and processes it into a hydrologically-conditioned DEM.

   :param selected_polygon_gdf: A GeoDataFrame representing the selected polygon, i.e., the catchment area.
   :type selected_polygon_gdf: gpd.GeoDataFrame
   :param log_level: The log level to set for the root logger. Defaults to LogLevel.DEBUG.
                     The available logging levels and their corresponding numeric values are:
                     - LogLevel.CRITICAL (50)
                     - LogLevel.ERROR (40)
                     - LogLevel.WARNING (30)
                     - LogLevel.INFO (20)
                     - LogLevel.DEBUG (10)
                     - LogLevel.NOTSET (0)
   :type log_level: LogLevel = LogLevel.DEBUG