| # 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) |
|
|
| 1. **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/`. |
| 2. **VIIRS:** register at https://eogdata.mines.edu/products/vnl/, then download the annual |
| `*average_masked*.tif.gz` file for each year 2012–2024 into `data/darksky/raw/viirs/`. The file |
| name must contain the year (the build reads the first `20xx` in the name). Each global file is |
| large: build after each download and delete it if disk is short (`build` only needs the files |
| present at build time, so build once with all years). |
| 3. **GeoNames:** no account. `https://download.geonames.org/export/dump/<CC>.zip` for |
| ZW ZA ZM MZ BW NA MW LS SZ; unzip `<CC>.txt` into `data/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`). |
|
|
