scientific_documentation.md

-tbd
\ No newline at end of file
+# Introduction
+This program  extracts the maximal flood area from either ASCII grid, DHI dfs2 files or DHI dfsu files, intersects these with building and street features and computes flood damage based on damage functions for residential and commercial buildings as well as streets. The tool is currently split into a version reading dfsu files and applying depth-damage functions based on this [report](https://watersensitivecities.org.au/content/flood-damage-assessment-literature-review-recommended-procedure/), and a version reading dfs2-files or ASCII rasters and applying depth damage functions in accordance with this [article](http://www.mdpi.com/2073-4441/7/1/255) (with slight modifications for the computation of damages from roads and green areas). A major difference is that the dfsu version applies per-sqm damages for commercial buildings, while the raster-based version applies unit damages for all building types. It is foreseen that the 2 code versions will be merged in the future.
+
+# General approach
+On a general level, the tool executes the following steps:
+1. Load flood maps and land-use data into temporary layers in memory.
+2. For buildings: create a unique ID for each building feature.
+3. Convert flood depth and land use layers to rasters with the same extent and pixel size.
+4. Overlay the land-use rasters and the flood depth raster. 
+5. Apply the pre-defined stage depth - damage functions and compute the total damages.
+
+# Details
+## Data loading and creation of identifiers
+GDAL is applied to read the geodata and to create raster representations. The identifiers in GIS layers are sometime corrupted, so the program creates unique identifiers as a first step.
+
+## Rasterizing layers
+To perform the damage analysis, all layers are converted to rasters. This is to avoid time-consuming vector operations on, potentially, large datasets and to avoid problems with corrupted vector geometries.
+As a default, the raster resolution used in the damage analysis is `Dx/2`, where Dx is the pixel size of the flood depth layer. The analysis resolution can be adjusted by modifying variable `resfactor` in the main script.
+
+### Land-use layers
+The land-use layers are converted to rasters using the GDAL function `RasterizeLayer`. The extent of the output raster is taken from the layer defined under "EXTENT" in the config file. The raster resolution is computed as specified above.
+
+For buildings, the output raster consists of the specific building ID's (see image), while for roads and green areas a constant value is written into the raster in the locations where roads and green areas are present and 0 is applied otherwise. A separate building raster is created for each building type, because the computation of flood damages is performed separately for each type.
+
+![Example raster created from building layer, containing a separate value for each building, and 0 otherwise.](img/BuildingRaster2.png "Example raster created from building layer, containing a separate value for each building, and 0 otherwise.")
+
+Performing the damage analysis with a raster resolution of `Dx/2` is usually sufficient. The largest contributions to total flood damages typically originate from buildings. The assessment whether a building is flooded is performed using a neighborhood filter which size depends on the pixel size (see below). Thus, once a sufficient accuracy is reached, further reductions in analysis resolution will typically no longer affect the computed damages.
+
+![This image shows a vector building geometry and the corresponding raster representation for a pixel size of 0.8m.](img/BuildingRaster.png "This image shows a vector building geometry and the corresponding raster representation for a pixel size of 0.8m")
+
+### Flood depth layer
+The flood depth layer is converted to rasters using the nearest neighbor method implemented in the scipy function `griddata`. The motiviation is that the damage computation tool is intended to also be able to handle flood maps originating from simulations with unstructured meshes in the MIKE 21 FM engine. In this case, the flood depth layer can contain data points at irregularly spaced intervals. 
+
+If the flood depth layer used as input to the tool is a raster, the nearest neighborhood approach will essentially reproduce the same raster. However, some small spatial displacements are possible, if the extents of the "EXTENT" layer and the flood raster are not the same.
+
+The figures below illustrate the effect of clipping on the flood raster used for analysis, as well as the analysis raster resulting from a grid-based input raster.
+
+![The input raster (left) is clipped to the analysis extent, resulting in a flood raster of reduced extent (right).](img/FloodRaster.png "The input raster (left) is clipped to the analysis extent, resulting in a flood raster of reduced extent (right).")
+
+![Converting grid-based flood depth layers using a nearest neighborhood approach, essentially reproduces the input raster.](img/FloodRaster2.png "Converting grid-based flood depth layers using a nearest neighborhood approach, essentially reproduces the input raster.")
+
+
+#Finding flooded features
+## Finding flooded buildings
+3x3 filter
+
+## Computing flooded area
+
+resfactor
\ No newline at end of file