This tool can be used to fill all of the depressions in a digital elevation model (DEM) and to remove the flat areas. This is a common pre-processing step required by many flow-path analysis tools to ensure continuous flow from each grid cell to an outlet located along the grid edge. The fill_depressions algorithm operates by first identifying single-cell pits, that is, interior grid cells with no lower neighbouring cells. Each pit cell is then visited from highest to lowest and a priority region-growing operation is initiated. The area of monotonically increasing elevation, starting from the pit cell and growing based on flood order, is identified. Once a cell, that has not been previously visited and possessing a lower elevation than its discovering neighbour cell, is identified the discovering neighbour is labelled as an outlet (spill point) and the outlet elevation is noted. The algorithm then back-fills the labelled region, raising the elevation in the output DEM (output) to that of the outlet. Once this process is completed for each pit cell (noting that nested pit cells are often solved by prior pits) the flat regions of filled pits are optionally treated (fix_flats) with an applied small slope gradient away from outlets (note, more than one outlet cell may exist for each depression). The user may optionally specify the size of the elevation increment used to solve flats (flat_increment), although it is best to not specify this optional value and to let the algorithm determine the most suitable value itself. The flat-fixing method applies a small gradient away from outlets using another priority region-growing operation (i.e. based on a priority queue operation), where priorities are set by the elevations in the input DEM (input). This in effect ensures a gradient away from outlet cells but also following the natural pre-conditioned topography internal to depression areas. For example, if a large filled area occurs upstream of a damming road-embankment, the filled DEM will possess flow directions that are similar to the un-flooded valley, with flow following the valley bottom. In fact, the above case is better handled using the breach_depressions_least_cost tool, which would simply cut through the road embankment at the likely site of a culvert. However, the flat-fixing method of fill_depressions does mean that this common occurrence in LiDAR DEMs is less problematic.

The breach_depressions_least_cost, while slightly less efficient than either other hydrological preprocessing methods, often provides a lower impact solution to topographic depressions and should be preferred in most applications. In comparison with the breach_depressions_least_cost tool, the depression filling method often provides a less satisfactory, higher impact solution. It is advisable that users try the breach_depressions_least_cost tool to remove depressions from their DEMs before using fill_depressions. Nonetheless, there are applications for which full depression filling using the fill_depressions tool may be preferred.

Note that this tool will not fill in NoData regions within the DEM. It is advisable to remove such regions using the fill_missing_data tool prior to application.

See Also

breach_depressions_least_cost, breach_depressions_least_cost, sink, depth_in_sink, fill_missing_data

Function Signature

def fill_depressions(self, dem: Raster, fix_flats: bool = True, flat_increment: float = float('nan'), max_depth: float = float('inf')) -> Raster: ...

Project Links

WbW Homepage User Manual Support WbW