vfmap

vfmap is a Python package for delineating valley floors from digital elevation models (DEMs).

Valley floors are the topographic region between valley walls shaped mainly by fluvial processes, composed of floodplains, terraces, alluvial fans, and channels. From a hydrologically conditioned DEM and a reach-labeled channel network, vfmap produces a binary valley floor raster.

The method combines two components:

1. Region growing — low-slope pixels connected to the channel network. Captures wider, unconfined valley floors with multiple channels and floodplains.
2. Reach flooding — reach-specific relative elevation thresholds derived from cross-section analysis. Captures narrow, confined valley floors bounded by steep hillslopes.

Installation

pip install vfmap

Usage

With your own conditioned DEM and channel network (both xarray.DataArrays on the same grid). dem must be hydrologically conditioned - D8 flow directions are computed from it internally, channel_network (a reach-labeled raster) must align with the hydro conditioned dem.

from vfmap import map_valley_floor, Parameters

valley_floor = map_valley_floor(
    dem=dem,
    channel_network=channel_network,
    params=Parameters(),   # optional; defaults shown in the table below
)

Parameters

from vfmap import Parameters

params = Parameters(
    region_slope_threshold=2.0,   # degrees, tighter region growing
    flood_percentile=90.0,        # higher flood threshold per reach
    min_hole_size=20_000,         # m², smaller holes filled
)
valley_floor = map_valley_floor(dem, channel_network, params=params)

Parameters can be saved and reloaded as JSON with params.to_json(path) and Parameters.from_json(path).

Configuration parameters

All parameters live on the Parameters dataclass, grouped by pipeline stage.

Headwater filtering

Region growing

Cross-section sampling

Reach flooding

Postprocessing