Population Density Map

3D population density maps from Kontur population data, in two forms:

• Rendered maps: ray-traced images made in R with Rayshader (gallery below).
• Interactive explorer: the same hexagons as 3D columns in the browser. Pick a country, fly between its regions, tilt the view and hover any column for its location and people per km². 33 countries are live, from Bangladesh and Pakistan to most of Europe, Japan and Nigeria; more plug in with one download and one export command.

Both read the same country list in scripts/countries.R, but they run independently: making a rendered map never touches web/, and the explorer never needs Rayshader.

Project Structure

Population/
├── run_country.R          # Entry point for rendered maps
├── scripts/
│   ├── countries.R        # All country configs (both outputs read this)
│   ├── helpers.R          # Palette creation utilities
│   ├── create_pop_matrix.R
│   ├── plot_population_3d.R
│   ├── annotate_population_map.R
│   ├── export_web_data.R  # Country data + pages for the explorer (web/)
│   ├── templates/         # explorer.html: template for every explorer page
│   ├── download_kontur.R  # Fetch Kontur files by ISO code into data/kontur/
│   ├── setup_packages.R   # Run once to install dependencies
│   └── legacy/            # Old per-country scripts (reference only)
├── data/                  # Kontur .gpkg population + boundary files
│   └── kontur/            # Downloaded by download_kontur.R (gitignored)
├── output/
│   ├── plots/             # Raw 3D renders
│   └── annotated/         # Final annotated maps
├── web/                   # Interactive explorer (static, deployed to GitHub Pages)
│   ├── app.js, style.css
│   ├── index.html         # Landing page (generated)
│   ├── <country>/         # One page per country, e.g. sri-lanka/ (generated)
│   ├── sitemap.xml        # Every page, for search engines (generated)
│   └── data/
│       ├── countries.json # Search index: countries + their views (generated)
│       └── <country>/     # hexes.json + boundaries.geojson (generated)
└── .github/workflows/pages.yml  # Deploys web/ on push to main

Setup

1. Install R Download from cran.r-project.org (v4.4+)

2. Install XQuartz (macOS only — required for rgl) Download from xquartz.org, install, then restart Mac.

3. Install R packages Open scripts/setup_packages.R and run it once.

Running a Map

Open run_country.R, uncomment the country you want, and source the file:

run_country("bangladesh")
# run_country("finland")
# run_country("india")
# ... etc

Output saves automatically to output/annotated/<Country>_population_density.png.

Adding a New Country

1. Download the Kontur population and boundary files by ISO 3166 code:

   Rscript scripts/download_kontur.R GB DE    # → data/kontur/
   

   This fetches kontur_population_XX_20231101.gpkg and kontur_boundaries_XX_20230628.gpkg from Kontur's public bucket (the same files HDX links to) and skips files you already have. data/kontur/ is gitignored: some files are over GitHub's 100 MB limit, and a fresh clone can re-download them.

2. Add a config block to scripts/countries.R:

my_country = list(
  name       = "My Country",
  hex_file   = "data/kontur/kontur_population_XX_20231101.gpkg",
  admin_file = "data/kontur/kontur_boundaries_XX_20230628.gpkg",
  crs        = 3857,        # find at epsg.io
  size       = 3000,
  palette    = list(source = "metbrewer", name = "Benedictus", direction = -1),
  zscale     = 40,
  camera     = list(theta = 0, phi = 55, zoom = 0.75, fov = 100),
  light_dir  = 315,
  width      = 1400, height = 1800,
  solid      = FALSE, shadow_depth = 0
)

3. Uncomment in run_country.R:

run_country("my_country")

See the comment block at the top of scripts/countries.R for what each parameter does.

Web Explorer

web/ is a static page with no build step. deck.gl draws each Kontur H3 hexagon (about 0.74 km²) as a 3D column over a MapLibre basemap from OpenFreeMap. The page reads web/data/countries.json for the search box (every country plus its cities and regions, so typing "Dhaka" offers Dhaka city in Bangladesh), then loads one country's folder at a time. Every country has its own page, so links are shareable and search engines can find each one: bangladesh/, bangladesh/#dhaka-city. Old #bangladesh links still work.

scripts/export_web_data.R writes that data. For each country it:

• tags every hexagon with its subdistrict, district and region (for the hover tooltip)
• turns the country, its regions and any extra presets into views (the chips under the search box)
• writes region and district outlines and labels, clipped to land: Kontur's boundaries include sea areas, so they are cut to Natural Earth land plus the populated hexagons

Rscript scripts/export_web_data.R bangladesh          # one country
Rscript scripts/export_web_data.R bangladesh nepal    # several

Each run rebuilds countries.json and the pages (web/index.html, web/<country>/index.html, from scripts/templates/explorer.html) from the folders in web/data/, so search always matches what's exported. To rebuild only those, run Rscript scripts/export_web_data.R --manifest. Edit the template, not the generated pages.

Preview locally: python3 -m http.server -d web, then open localhost:8000.

Publish: push changes under web/ to main. The workflow deploys them to niloy.tech/Population-Density-Map.

This is the beginning of the README. Read the rest at the original. Read the full README ↗