Blame for code/docs/data/darksky.md

# 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`).