# Explore population atlas This atlas contains **60 rectangular map windows, 10 per inhabited continent**. Windows cover cross-border regions, metropolitan corridors, coasts and island groups. They are not restricted to the countries offered by the country mode. Every country inside a window contributes to its scoring population. The curated base windows are intended for **deterministic, grid-aligned crops** in the browser. Different seeds can select a base window and vary its position and extent between 65% and 100% of the base frame. This provides controlled variation while retaining meaningful land and population distributions. ## Sources and license - **Population:** European Commission Joint Research Centre, **GHS-POP R2023A, epoch 2020**, original 30-arcsecond (~1 km at equator) WGS84 population counts. These are modelled residential estimates, not a live count or exact census. - Dataset: Schiavina M., Freire S., Carioli A., MacManus K. (2023), . - Source documentation: . - Population license: **CC BY 4.0**, . These files are adapted rectangular subsets, land-masked, spatially summed and rounded. - **Maps:** Natural Earth 1:10 million countries, physical lakes and populated places; **public domain**, . The source is pinned to Natural Earth Git commit `ca96624a56bd078437bca8184e78163e5039ad19`. - Exact source URLs, sizes, SHA-256 hashes and base windows: `provenance.json`. Suggested visible attribution: **Population: GHSL/JRC 2020 (CC BY 4.0), adapted. Maps: Natural Earth. Estimates.** Link the source and license. ## Geometry and scoring Every base window is snapped outward to the population source grid. The scoring outline is the union of all country polygons inside its rectangular frame, **minus Natural Earth physical-lake polygons**. Borders do not restrict scoring. Population includes original GHSL cells whose centers fall inside that land mask. Native values are summed into regular blocks; integer rounding preserves the window total to the nearest person. Urban and rural values both come from the population raster. No artificial city weighting is used. The per-window JSON uses the same normalized map contract as the country data: | Field | Meaning | | --- | --- | | `id`, `group` | Stable `explore-*` ID; `group` is `explore`. | | `bbox` | `[west,south,east,north]` in longitude/latitude degrees. | | `requestedBbox` | Curated rectangle before outward source-grid alignment. | | `aspect` | Width/height ratio with longitude scaled by cosine of midpoint latitude. | | `outline` | Normalized scoring-land rings. Use even-odd fill to preserve lakes and other holes. | | `cells` | Flat `[x,y,integerPopulation,...]`, with cell-center coordinates and zero cells omitted. | | `cellSize` | Shared normalized `[width,height]` of complete rectangular cells. | | `gridSize` | Number of columns and rows in the complete regular frame. | | `population`, `totalPopulation` | Sum of all exported cell weights. | | `borders` | Country records `{name,code,outline}` clipped to the frame. They are all part of the scoring land. | | `context` | Empty; there is no non-scoring neighboring country inside the frame. | | `cities`, `countryLabels` | Names and normalized coordinates for the reveal. | | `kind` | `cross-border`, `cities`, `coast` or `islands`; useful for balanced selection. | | `quality` | Land fraction, populated-cell fraction, largest cell's population share, effective populated-cell count, country count. | | `cropSupport` | Grid alignment and recommended 0.65–1.0 scale range. | The catalog uses `regions` and paths such as `explore/explore-english-channel.json`, **relative to `public/data/`**. Country files and the country catalog are independent of this atlas. ## Browser crop contract Choose integer grid edges `(column0,row0,column1,row1)`, with each retained dimension between 65% and 100% of its source dimension. The crop's source normalized bounds are `[column0/width,row0/height,column1/width,row1/height]`. Keep complete cells inside that crop and transform their centers, outlines, borders and label coordinates into the new normalized frame. The crop's new `cellSize` is `[1/(column1-column0),1/(row1-row0)]`; its population is the sum of the retained cell weights. Clip all geometry to the new frame, and calculate its geographic bounding box and aspect from the retained grid edges. Use bounded deterministic retries to reject near-empty or overly concentrated crops. Inspect population, land fraction and largest-cell share. Island groups can legitimately have only about **3% land**; apply an island-specific land threshold together with population and spatial-spread checks. Falling back to the original frame retains a valid reproducible challenge. The crop seed and grid edges must be shared for friends to receive identical rounds. Scoring integrates the fraction of each aggregate cell on either side of the player's line. This avoids center-to-center jumps, while treating population as uniform within each aggregate cell. Coastlines and density patterns remain approximate. The heatmap should be clipped to the scoring land outline. ## Build and verify With Python packages `numpy`, `rasterio` and `shapely` installed: ```sh python scripts/data-explore-build.py --cache /path/to/population-data-cache python scripts/data-explore-verify.py ``` The cache uses the same ~425 MB population GeoTIFF and Natural Earth source files as other data pipelines. A partial rebuild accepts, for example, `--windows english-channel great-lakes`, and refreshes those atlas catalog entries. This pipeline writes only `public/data/explore/`.