Dam outlines: how they are made
===============================

Unmapped Dataworks shows, on each dam's page, the dam's water surface measured from space (dataset
dam-surface-from-space), next to the Department of Water and Sanitation's weekly levels (dataset dam-levels). DWS
names each dam and its river but gives no position or outline, so each dam's full-supply outline comes from
OpenStreetMap water polygons.

OpenStreetMap data is (c) OpenStreetMap contributors and available under the Open Database License (ODbL) 1.0:
https://www.openstreetmap.org/copyright and https://opendatacommons.org/licenses/odbl/1-0/

As the ODbL asks, we offer here, free, both the derived data and the method of making it:

  dam-outlines.geojson    one outline per DWS dam station, with how it was matched and the OpenStreetMap ids (ODbL 1.0)
  outline-selection.json  which OpenStreetMap polygons are each dam, how each was matched, and the dams left unmatched
  outline-match.sql       loads the candidates (named water polygons, dam walls, river lines) into PostGIS
  outline-match.py        matches DWS names to OpenStreetMap names, alternative names and dam walls
  outlines.py             builds dam-outlines.geojson from the selection and checks each against DWS's capacity

How a dam is matched: by name (with OpenStreetMap's alternative, old, English and Afrikaans names), inside the
province DWS gives; then by a named dam wall (waterway=dam) and the water polygon at it; then by river and province;
a few by an OpenStreetMap point named for the dam. Every outline is checked against DWS's full supply capacity: the
implied mean depth (capacity / area) must be 0.5 to 120 m, and those outside are looked at by hand. A dam with no
clean match is left without an outline rather than guessed (Katse and Mohale in Lesotho and Maguga in Eswatini lie
outside the South Africa extract).

To rebuild it: download Geofabrik's South Africa extract (https://download.geofabrik.de/africa/south-africa.html),
load its multipolygons and lines into PostGIS with ogr2ogr (schema dams_tmp, tables osm_water and osm_lines, water
polygons only), run outline-match.sql and outline-match.py, then outlines.py.

dam-outlines.geojson is under the ODbL 1.0: you may use, share and adapt it, if you credit OpenStreetMap contributors
and share anything you derive from it under the same licence.

The scripts: MIT licence. Copyright (c) 2026 Unmapped Dataworks. Permission is hereby granted, free of charge, to any
person obtaining a copy of this software, to deal in the software without restriction, including the rights to use,
copy, modify, merge, publish, distribute, sublicense and/or sell copies of it, provided this notice is included. The
software is provided "as is", without warranty of any kind.

This README: CC BY 4.0, Unmapped Dataworks.