build-tiles

Prompt file imported from willhs/footsteps (.windsurf/workflows/build-tiles.md). Copyright stays with the author.

• Objective

  • Generate humans_{year}_lod_{lod}.mbtiles and combined humans_{year}.mbtiles in data/tiles/humans/ using footstep-generator/make_tiles.py.

• Prerequisites

  • HYDE ASCII grids present under footstep-generator/data/raw/hyde-3.5/ (files like popd_*.asc)
  • tippecanoe + tile-join installed (macOS): brew install tippecanoe

• Set paths (run from repo root) // turbo

export RAW_DIR="$(pwd)/footstep-generator/data/raw/hyde-3.5"
export TILES_DIR="$(pwd)/data/tiles/humans"
mkdir -p "$TILES_DIR"

• Build all found years (scans RAW_DIR for popd_*.asc) // turbo

poetry run python footstep-generator/make_tiles.py \
  --raw-dir "$RAW_DIR" \
  --tiles-dir "$TILES_DIR"

• Build specific years (BCE is negative) // turbo

poetry run python footstep-generator/make_tiles.py \
  --raw-dir "$RAW_DIR" \
  --tiles-dir "$TILES_DIR" \
  --years -1000 0 1500 2020

• Overwrite existing outputs // turbo

poetry run python footstep-generator/make_tiles.py \
  --raw-dir "$RAW_DIR" \
  --tiles-dir "$TILES_DIR" \
  --years 2020 \
  --force

• Verify outputs // turbo

ls -lh "$TILES_DIR" | grep humans_ | sort
# Inspect per-zoom tile counts in a combined tileset
sqlite3 "$TILES_DIR/humans_2020.mbtiles" "select zoom_level, count(*) from tiles group by zoom_level;"

• Serve in dev // turbo

export HUMANS_TILES_DIR="$TILES_DIR"
cd footsteps-web && pnpm dev -p 4444

• LOD zoom ranges (must match generator + frontend)
  • LOD 0: z0–3, LOD 1: z4, LOD 2: z5, LOD 3: z6–12
  • Source of truth: footstep-generator/make_tiles.py#LOD_ZOOM_RANGES, footsteps-web/lib/lod.ts#getLODLevel