r.hydro.flatten: separate footprint of the impoundment from the downstream river

[dnewcomb]

Name of the addon
r.hydro.flatten (manual)

Describe the bug
At dams where the water flows over the top of the dam, or at a waterfall, there are no ground points to "break" between the impoundment and the stream. The water surface of the impoundment cannot be calculated correctly if the edges of the stream below the impoundment are included in the calculation. Similarly, if a stream that feeds into an impoundment is wide enough to leave a void in the ground points, the existing method will include the edges of that stream upstream to the next break in the impoundment water level.

To overcome this limitation, the optional inclusion of a 2Dvector line "breakline" layer where lines are placed across the void areas at dams and waterfalls where there are no LiDAR ground points between the impoundment surface and the upstream and downstream void areas representing rivers.

These 2D lines would be converted to raster data at a width of 2 cells, and be used as an inverse mask to be created just before the clumping operation which determines the extent of area of each impoundment for which the edge values are statistically analyzed ( line 137).

After the edge statistics have been calculated, the inverse mask would be removed and the gaps in the water surface could be "healed" with r.fill.stats on just the water surfaces masked to the final water extent.

To Reproduce
Steps to reproduce the behavior:

1. Run r.hydro.flatten in an area with an impoundment where there is a continuous void between the surface of the impoundment and the stream draining the impoundment
2. The resulting water body elevation will be based on the elevation of the edges of both the impoundment and the downstream river, not just the impoundment and will encompass both the impoundment and the downstream river.

Expected behavior
With the " breaklines" used as described above, the footprint of the impoundment will be separated from the downstream river , so that the elevation of the impoundment can be correctly calculated.

Screenshots
Image of 1m resolution mean ground from 2014 NC LiDAR data for Neuse River at Milburne Dam, east of Raleigh,NC

Result of r.hydro.flatten showing water level above and below dam at same elevation

Simulating the effect of a "breakline" by placing the region boundary just above the dam gives a difference in water level above the dam of 11 cm .

Simulating the effect of a "breakline" by setting the region boundary below the dam gives an elevation of the rivere below the dam of 11 meters lower than the original calculation.

System description (please complete the following information):

• Operating System: All
• GRASS GIS version 8.2.1

Additional context
This is a proposed enhancement to more completely separate impounded water bodies from non-impounded water bodies in mean ground raster layers created from LiDAR ground points.