Roughness Maps#

Roughness maps store surface roughness length (z0) values. For vector format with lines, values are stored on both sides of each line (roughness change lines).

Data Structure#

Vector Format - Lines (geopandas.GeoDataFrame)

Columns:
    z0_left   - roughness on left side of line (meters)
    z0_right  - roughness on right side of line (meters)
    geometry  - LINESTRING (roughness change boundaries)

Vector Format - Polygons (geopandas.GeoDataFrame)

Columns:
    z0        - roughness value (meters)
    geometry  - POLYGON (roughness areas)

Raster Format (xarray.DataArray)

DataArray:
    name: roughness
    dims: (south_north, west_east)
    dtype: float (meters)

Roughness Values#

Typical roughness length values:

Surface Type

z0 (meters)

Water (sea, lakes)

0.0 (uses 0.0002 internally)

Sand, snow

0.0003

Short grass

0.01 - 0.03

Agricultural land

0.05 - 0.1

Suburban

0.3 - 0.5

Forest

0.5 - 1.0

Urban / City

1.0 - 2.0

Note

Water bodies should have roughness 0.0, which signals to WAsP that the surface is water. During calculations, WAsP replaces 0.0 with the configured water roughness (default 0.0002).

I/O#

Reading:

windkit.read_roughness_map() reads roughness from vector or raster files:

roughness = wk.read_roughness_map("rgh.map")

Converting to Land Cover:

Roughness maps can be converted to land cover format for use with WAsP 12.7+. This works with roughness maps that have z0_left/z0_right columns (change lines):

# Convert roughness to land cover
lc_map, lc_tbl = wk.roughness_to_landcover(roughness)
print(f"Land cover map: {len(lc_map)} features")
print(f"Land cover table: {len(lc_tbl)} classes")

Writing:

windkit.roughness_map_to_file() writes roughness maps:

wk.roughness_map_to_file(roughness_raster, "output.tif")

Best Practices#

  1. Water bodies: Use roughness 0.0 for water to trigger WAsP’s stability model for water surfaces.

  2. Value range: Land roughness should be in [0.0002, 5.0]. Values outside this range can cause problems.

  3. Number of classes: Keep unique roughness values reasonable (typically 5-50). Too many classes don’t add value since WAsP uses a limited number of roughness-change events per sector.

  4. Preprocessing: Use QGIS, xarray, or other GIS tools to clean roughness maps before use.