FarZenith dark-sky data (Southern Africa)
Built with python -m zenith.darksky.build --raw data/darksky/raw --out data/darksky (needs
pip install -e '.[darksky]'). Outputs, all git-ignored: data/darksky/darksky_sa.npz,
places_sa.json, manifest.json (source files, sha256, years). scripts/export_model.py copies the
first two into the export directory; the engine finds them through ZENITH_DARKSKY.
Map area: lat −35…−8, lon 10…41 (Zimbabwe, South Africa, Zambia, Mozambique, Botswana, Namibia, Malawi, Lesotho, Eswatini, and parts of their neighbours).
Sources
| Layer | Source | Licence | Stored grid |
|---|---|---|---|
| Artificial zenith sky brightness (mcd/m²) | Falchi, F. et al. 2016, The new world atlas of artificial night sky brightness, GFZ Data Services, doi:10.5880/GFZ.1.4.2016.001 | CC BY-NC 4.0 | 1′ (~1.8 km), float16 |
| Night-light radiance (nW/cm²/sr), one map per year 2012–2024 | Earth Observation Group (Payne Institute, Colorado School of Mines), VIIRS annual VNL v2.x, average_masked |
see EOG terms (attribution required) | 2.5′ (~4.6 km), float32 |
| Place names | GeoNames country dumps | CC BY 4.0 | towns ≥ 1,000 people, capitals, parks/reserves, observatories |
Non-commercial restriction. The Falchi layer is CC BY-NC 4.0, so a FarZenith deployment that
answers dark-sky questions may not be used commercially without the authors' permission. Every
darksky API response carries an attribution string naming all three sources.
Downloading (needs the user's accounts)
- Falchi atlas: request access through the form on https://doi.org/10.5880/GFZ.1.4.2016.001,
download the world GeoTIFF (~2.9 GB) and put it in
data/darksky/raw/falchi/. - VIIRS: register at https://eogdata.mines.edu/products/vnl/, then download the annual
*average_masked*.tif.gzfile for each year 2012–2024 intodata/darksky/raw/viirs/. The file name must contain the year (the build reads the first20xxin the name). Each global file is large: build after each download and delete it if disk is short (buildonly needs the files present at build time, so build once with all years). - GeoNames: no account.
https://download.geonames.org/export/dump/<CC>.zipfor ZW ZA ZM MZ BW NA MW LS SZ; unzip<CC>.txtintodata/darksky/raw/geonames/.
How the engine uses the layers
- Sky quality: SQM = −2.5·log10((artificial + 0.171 mcd/m²) / 1000 / 108000) mag/arcsec²; Bortle class from SQM (≥21.99 → 1, ≥21.89 → 2, ≥21.69 → 3, ≥20.49 → 4, ≥19.50 → 5, ≥18.94 → 6, ≥18.38 → 7, ≥17.80 → 8, else 9); Milky Way visible at Bortle ≤ 4, faint at 5, hidden at ≥ 6.
- Darkest sites: cells within the radius whose SQM is within 0.1 mag of the darkest, nearest first, at least 25 km apart, named by the nearest GeoNames place.
- Trends: VIIRS radiance of the cell containing the point in two years.
Build record
Filled in when the real maps are built (Task 9 of docs/superpowers/plans/2026-10-30-satellites-darksky.md).