{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "eee9f384",
   "metadata": {},
   "source": [
    "# 🗂️ VoxCity Data Sources Guide\n",
    "\n",
    "This tutorial provides a comprehensive overview of all data sources available in VoxCity for building 3D urban voxel models.\n",
    "\n",
    "## Overview\n",
    "\n",
    "VoxCity can pull data from multiple global and regional sources:\n",
    "\n",
    "| Category | Sources |\n",
    "|----------|---------|\n",
    "| **Buildings** | OpenStreetMap, Overture, EUBUCCO, Open Building 2.5D, Microsoft Building Footprints |\n",
    "| **Terrain** | DeltaDTM, FABDEM, USGS 3DEP |\n",
    "| **Land Cover** | ESA WorldCover, OpenStreetMap |\n",
    "| **Vegetation** | High Resolution Canopy Height Maps, OpenStreetMap |\n",
    "| **Imagery** | Google Earth Engine (Sentinel-2, etc.) |"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a2f7649f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Setup\n",
    "from voxcity.geo.utils import get_rectangle_vertices\n",
    "\n",
    "# Example area: Marunouchi, Tokyo\n",
    "center = (139.7671, 35.6812)  # (lon, lat)\n",
    "rectangle_vertices = get_rectangle_vertices(center, 200, 200)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44be2aa3",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## 🏢 Building Data Sources\n",
    "\n",
    "### 1. OpenStreetMap (OSM)\n",
    "**Coverage:** Global | **Cost:** Free | **Recommended for:** General worldwide use\n",
    "\n",
    "OpenStreetMap provides crowd-sourced building footprints with optional height information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "96d6813f",
   "metadata": {},
   "outputs": [],
   "source": [
    "from voxcity.download.osm import get_building_data_from_osm\n",
    "\n",
    "# Download building footprints from OpenStreetMap\n",
    "gdf_buildings_osm = get_building_data_from_osm(rectangle_vertices)\n",
    "print(f\"Downloaded {len(gdf_buildings_osm)} buildings from OSM\")\n",
    "print(f\"Columns: {list(gdf_buildings_osm.columns)}\")\n",
    "gdf_buildings_osm.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "848436b4",
   "metadata": {},
   "source": [
    "### 2. Overture Maps\n",
    "**Coverage:** Global | **Cost:** Free | **Recommended for:** High-quality building data\n",
    "\n",
    "Overture Maps Foundation provides curated building data from multiple sources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5c160b27",
   "metadata": {},
   "outputs": [],
   "source": [
    "from voxcity.download.overture import get_building_data_from_overture\n",
    "\n",
    "# Download building footprints from Overture\n",
    "gdf_buildings_overture = get_building_data_from_overture(rectangle_vertices)\n",
    "print(f\"Downloaded {len(gdf_buildings_overture)} buildings from Overture\")\n",
    "gdf_buildings_overture.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99931aef",
   "metadata": {},
   "source": [
    "### 3. EUBUCCO v0.1\n",
    "**Coverage:** Europe only | **Cost:** Free | **Recommended for:** European cities\n",
    "\n",
    "EUBUCCO provides building footprints with height information for European countries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4616d859",
   "metadata": {},
   "outputs": [],
   "source": [
    "# EUBUCCO example (European location)\n",
    "# Note: This only works for European cities\n",
    "# center_europe = (13.4050, 52.5200)  # Berlin\n",
    "# rectangle_vertices_europe = get_rectangle_vertices(center_europe, 200, 200)\n",
    "# gdf_buildings_eubucco = get_building_data_from_eubucco(rectangle_vertices_europe)\n",
    "\n",
    "print(\"EUBUCCO is available for European cities only.\")\n",
    "print(\"Supported countries: Austria, Belgium, Czechia, Denmark, Finland, France,\")\n",
    "print(\"Germany, Italy, Netherlands, Poland, Slovakia, Slovenia, Spain, Sweden, Switzerland\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0b334368",
   "metadata": {},
   "source": [
    "### 4. Open Building 2.5D Temporal\n",
    "**Coverage:** Global | **Cost:** Free | **Recommended for:** Building height estimates\n",
    "\n",
    "Provides estimated building heights derived from satellite imagery."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a9c731af",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Open Building 2.5D requires Google Earth Engine authentication\n",
    "# from voxcity.download.gee import get_building_data_from_open_building_2_5d_temporal\n",
    "\n",
    "# gdf_buildings_ob25d = get_building_data_from_open_building_2_5d_temporal(rectangle_vertices)\n",
    "print(\"Open Building 2.5D requires Google Earth Engine authentication.\")\n",
    "print(\"See: https://developers.google.com/earth-engine/guides/python_install\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8eec9313",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## 🏔️ Terrain Data Sources (DEM/DTM)\n",
    "\n",
    "### 1. DeltaDTM\n",
    "**Coverage:** Global | **Resolution:** 30m | **Recommended for:** General use\n",
    "\n",
    "Global Digital Terrain Model derived from multiple sources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4df4e240",
   "metadata": {},
   "outputs": [],
   "source": [
    "from voxcity.download.dem import get_dem_from_deltadtm\n",
    "\n",
    "# Download terrain data from DeltaDTM\n",
    "dem_deltadtm = get_dem_from_deltadtm(rectangle_vertices, meshsize=1.0)\n",
    "print(f\"DeltaDTM shape: {dem_deltadtm.shape}\")\n",
    "print(f\"Elevation range: {dem_deltadtm.min():.1f}m to {dem_deltadtm.max():.1f}m\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e32dd34",
   "metadata": {},
   "source": [
    "### 2. FABDEM\n",
    "**Coverage:** Global | **Resolution:** 30m | **Recommended for:** Building-free terrain\n",
    "\n",
    "FABDEM removes buildings and trees from Copernicus DEM to provide bare-earth elevation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "304ca3ef",
   "metadata": {},
   "outputs": [],
   "source": [
    "# FABDEM requires registration at https://data.bris.ac.uk/data/\n",
    "# from voxcity.download.dem import get_dem_from_fabdem\n",
    "# dem_fabdem = get_dem_from_fabdem(rectangle_vertices, meshsize=1.0)\n",
    "print(\"FABDEM requires authentication.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "275df770",
   "metadata": {},
   "source": [
    "### 3. USGS 3DEP\n",
    "**Coverage:** USA only | **Resolution:** 1m-10m | **Recommended for:** High-resolution US terrain"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e3aa61f8",
   "metadata": {},
   "outputs": [],
   "source": [
    "# USGS 3DEP - USA only\n",
    "# from voxcity.download.dem import get_dem_from_usgs_3dep\n",
    "# center_us = (-122.4194, 37.7749)  # San Francisco\n",
    "# rectangle_vertices_us = get_rectangle_vertices(center_us, 200, 200)\n",
    "# dem_usgs = get_dem_from_usgs_3dep(rectangle_vertices_us, meshsize=1.0)\n",
    "print(\"USGS 3DEP provides high-resolution elevation data for the USA.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da36ce8f",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## 🌍 Land Cover Data Sources\n",
    "\n",
    "### ESA WorldCover\n",
    "**Coverage:** Global | **Resolution:** 10m | **Recommended for:** Land use classification\n",
    "\n",
    "ESA WorldCover provides global land cover classification at 10m resolution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11ffffc2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from voxcity.download.gee import get_land_cover_data_from_esaworldcover\n",
    "\n",
    "# Download land cover from ESA WorldCover\n",
    "# Note: Requires Google Earth Engine authentication\n",
    "# lc_grid = get_land_cover_data_from_esaworldcover(rectangle_vertices, meshsize=1.0)\n",
    "\n",
    "print(\"ESA WorldCover Classes:\")\n",
    "print(\"10: Tree cover | 20: Shrubland | 30: Grassland\")\n",
    "print(\"40: Cropland | 50: Built-up | 60: Bare/sparse vegetation\")\n",
    "print(\"70: Snow and ice | 80: Permanent water | 90: Herbaceous wetland\")\n",
    "print(\"95: Mangroves | 100: Moss and lichen\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1d3acdb",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## 🌳 Vegetation / Canopy Height Data\n",
    "\n",
    "### High Resolution 1m Global Canopy Height Maps\n",
    "**Coverage:** Global | **Resolution:** 1m | **Recommended for:** Detailed tree heights\n",
    "\n",
    "This dataset provides high-resolution canopy height estimates from satellite imagery."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "033a437d",
   "metadata": {},
   "outputs": [],
   "source": [
    "from voxcity.download.gee import get_canopy_height_from_high_resolution_canopy_height_maps\n",
    "\n",
    "# Download canopy height data\n",
    "# Note: Requires Google Earth Engine authentication\n",
    "# chm_grid = get_canopy_height_from_high_resolution_canopy_height_maps(rectangle_vertices, meshsize=1.0)\n",
    "\n",
    "print(\"High Resolution Canopy Height Maps provides 1m resolution tree heights.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "994979eb",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## 🔧 Using Data Sources with `get_voxcity()`\n",
    "\n",
    "The easiest way to use data sources is with the `get_voxcity()` function. It automatically combines multiple sources:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "be119922",
   "metadata": {},
   "outputs": [],
   "source": [
    "from voxcity.generator import get_voxcity\n",
    "\n",
    "# Specify data sources in source_dict\n",
    "source_dict = {\n",
    "    'building': 'osm',           # Options: 'osm', 'overture', 'eubucco', 'open_building_2.5d_temporal', 'microsoft_building'\n",
    "    'dem': 'deltadtm',           # Options: 'deltadtm', 'fabdem', 'usgs_3dep'\n",
    "    'land_cover': 'esaworldcover',  # Options: 'esaworldcover', 'osm'\n",
    "    'tree': 'high_resolution_canopy_height_maps',  # Options: 'high_resolution_canopy_height_maps', 'osm'\n",
    "}\n",
    "\n",
    "# Generate 3D voxel model using specified sources\n",
    "# city = get_voxcity(\n",
    "#     rectangle_vertices,\n",
    "#     source_dict=source_dict,\n",
    "#     meshsize=1.0\n",
    "# )\n",
    "print(\"Available building sources:\", ['osm', 'overture', 'eubucco', 'open_building_2.5d_temporal', 'microsoft_building'])\n",
    "print(\"Available DEM sources:\", ['deltadtm', 'fabdem', 'usgs_3dep'])\n",
    "print(\"Available land cover sources:\", ['esaworldcover', 'osm'])\n",
    "print(\"Available tree sources:\", ['high_resolution_canopy_height_maps', 'osm'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b29fe67d",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## 📊 Data Source Comparison Table\n",
    "\n",
    "| Source | Coverage | Resolution | Authentication | Best Use Case |\n",
    "|--------|----------|------------|----------------|---------------|\n",
    "| **OSM** | Global | Variable | None | General buildings worldwide |\n",
    "| **Overture** | Global | Variable | None | High-quality curated data |\n",
    "| **EUBUCCO** | Europe | ~10m | None | European cities with heights |\n",
    "| **Open Building 2.5D** | Global | ~1m | GEE | Building height estimates |\n",
    "| **Microsoft Building** | Global | Variable | None | Building footprints |\n",
    "| **DeltaDTM** | Global | 30m | None | General terrain |\n",
    "| **FABDEM** | Global | 30m | Registration | Bare-earth terrain |\n",
    "| **USGS 3DEP** | USA | 1-10m | None | High-res US terrain |\n",
    "| **ESA WorldCover** | Global | 10m | GEE | Land use classification |\n",
    "| **Canopy Height Maps** | Global | 1m | GEE | Tree height mapping |\n",
    "\n",
    "**GEE** = Google Earth Engine authentication required"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "efc6109e",
   "metadata": {},
   "source": [
    "## 🔑 Google Earth Engine Setup\n",
    "\n",
    "Some data sources require Google Earth Engine authentication:\n",
    "\n",
    "1. Create a GEE account at https://earthengine.google.com/\n",
    "2. Install the earthengine-api: `pip install earthengine-api`\n",
    "3. Authenticate: `earthengine authenticate`\n",
    "\n",
    "See the [official guide](https://developers.google.com/earth-engine/guides/python_install) for details."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd374843",
   "metadata": {},
   "source": [
    "## 📚 Next Steps\n",
    "\n",
    "Now that you understand the data sources, explore these tutorials:\n",
    "\n",
    "- **demo_quickstart.ipynb** - Quick start with default sources\n",
    "- **demo_basic.ipynb** - Complete workflow with all options\n",
    "- **demo_view.ipynb** - Green View Index analysis\n",
    "- **demo_solar.ipynb** - Solar irradiance simulation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ec60ef31",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Setup\n",
    "from voxcity.generator import get_voxcity, auto_select_data_sources\n",
    "\n",
    "# Example area for demonstrations\n",
    "rectangle_vertices = [\n",
    "    (139.760, 35.680),  # Tokyo area\n",
    "    (139.760, 35.690),\n",
    "    (139.770, 35.690),\n",
    "    (139.770, 35.680)\n",
    "]\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87d21b61",
   "metadata": {},
   "source": [
    "## 🏗️ Building Data Sources\n",
    "\n",
    "### Primary Building Sources\n",
    "\n",
    "| Source | Coverage | Heights | Best For |\n",
    "|--------|----------|---------|----------|\n",
    "| `OpenStreetMap` | Global | Partial | Most locations (default) |\n",
    "| `Overture` | Global | Partial | Alternative global coverage |\n",
    "| `EUBUCCO v0.1` | Europe | Yes | European cities |\n",
    "| `Open Building 2.5D Temporal` | Africa, Asia, Latin America | Yes | Developing regions |\n",
    "| `Microsoft Building Footprints` | USA, Europe, Australia | No | Footprint accuracy |\n",
    "| `Local file` | Any | Varies | Custom data |\n",
    "\n",
    "### Complementary Building Sources\n",
    "\n",
    "When the primary source lacks height data, use a complementary source:\n",
    "\n",
    "| Source | Provides |\n",
    "|--------|----------|\n",
    "| `Open Building 2.5D Temporal` | Heights from satellite imagery |\n",
    "| `Microsoft Building Footprints` | Additional footprints |\n",
    "| `England 1m DSM - DTM` | Heights from DSM-DTM difference |\n",
    "| `Netherlands 0.5m DSM - DTM` | Heights from DSM-DTM difference |\n",
    "| `None` | Use default height |\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fd70b7b0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example: Using OpenStreetMap with complementary source\n",
    "city_osm = get_voxcity(\n",
    "    rectangle_vertices,\n",
    "    meshsize=10,\n",
    "    building_source='OpenStreetMap',\n",
    "    building_complementary_source='None',\n",
    "    land_cover_source='OpenStreetMap',\n",
    "    canopy_height_source='Static',\n",
    "    dem_source='Flat',\n",
    "    output_dir='output/datasource_demo/osm'\n",
    ")\n",
    "print(f\"Building grid shape: {city_osm.buildings.heights.shape}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28e547cf",
   "metadata": {},
   "source": [
    "## 🌿 Land Cover Sources\n",
    "\n",
    "Land cover classification determines what's on the ground surface.\n",
    "\n",
    "| Source | Resolution | Coverage | Classes |\n",
    "|--------|------------|----------|---------|\n",
    "| `OpenStreetMap` | Vector | Global | Roads, grass, water, etc. |\n",
    "| `Urbanwatch` | 5m | USA | Urban-specific |\n",
    "| `OpenEarthMapJapan` | High | Japan | Detailed classification |\n",
    "| `ESA WorldCover` | 10m | Global | 11 classes |\n",
    "| `ESRI 10m Annual Land Cover` | 10m | Global | 10 classes |\n",
    "| `Dynamic World V1` | 10m | Global | 9 classes, time-series |\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b73e4406",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Land cover classes used in VoxCity\n",
    "from voxcity.utils.lc import get_land_cover_classes\n",
    "\n",
    "# OpenStreetMap land cover mapping\n",
    "osm_classes = {\n",
    "    0: \"Unclassified\",\n",
    "    1: \"Building\",\n",
    "    2: \"Road/pavement\",\n",
    "    3: \"Grass/vegetation\",\n",
    "    4: \"Tree\",\n",
    "    5: \"Water\",\n",
    "    6: \"Railway\",\n",
    "    7: \"Bare soil\"\n",
    "}\n",
    "\n",
    "print(\"Land cover classes (OSM):\")\n",
    "for code, name in osm_classes.items():\n",
    "    print(f\"  {code}: {name}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6648cec6",
   "metadata": {},
   "source": [
    "## 🌳 Canopy Height Sources\n",
    "\n",
    "Tree canopy heights for vegetation modeling.\n",
    "\n",
    "| Source | Resolution | Coverage | Notes |\n",
    "|--------|------------|----------|-------|\n",
    "| `High Resolution 1m Global Canopy Height Maps` | 1m | Global | Meta/WRI, most accurate |\n",
    "| `ETH Global Sentinel-2 10m Canopy Height (2020)` | 10m | Global | Good alternative |\n",
    "| `OpenStreetMap` | Vector | Global | Tree locations only |\n",
    "| `Static` | N/A | Any | Fixed height (default 10m) |\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a025a0a9",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Canopy height parameters\n",
    "canopy_params = {\n",
    "    \"min_canopy_height\": 2.0,      # Ignore trees shorter than this (meters)\n",
    "    \"trunk_height_ratio\": 0.59,    # Trunk height / total height\n",
    "    \"static_tree_height\": 10.0     # Default height for 'Static' source\n",
    "}\n",
    "\n",
    "print(\"Canopy configuration options:\")\n",
    "for param, value in canopy_params.items():\n",
    "    print(f\"  {param}: {value}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1634a9bb",
   "metadata": {},
   "source": [
    "## ⛰️ DEM (Digital Elevation Model) Sources\n",
    "\n",
    "Terrain elevation data for accurate 3D representation.\n",
    "\n",
    "| Source | Resolution | Coverage | Notes |\n",
    "|--------|------------|----------|-------|\n",
    "| `DeltaDTM` | ~30m | Global | Good default |\n",
    "| `FABDEM` | ~30m | Global | Forest/building removed |\n",
    "| `USGS 3DEP 1m` | 1m | USA | Highest quality for USA |\n",
    "| `England 1m DTM` | 1m | England | High resolution |\n",
    "| `DEM France 1m` | 1m | France | High resolution |\n",
    "| `DEM France 5m` | 5m | France | Good coverage |\n",
    "| `Netherlands 0.5m DTM` | 0.5m | Netherlands | Very high resolution |\n",
    "| `AUSTRALIA 5M DEM` | 5m | Australia | National coverage |\n",
    "| `Flat` | N/A | Any | No terrain (z=0) |\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "21c0e8c1",
   "metadata": {},
   "outputs": [],
   "source": [
    "# DEM parameters\n",
    "dem_params = {\n",
    "    \"dem_interpolation\": True,  # Smooth DEM when meshsize < DEM resolution\n",
    "    \"flat_dem\": 0.0            # Elevation for 'Flat' source\n",
    "}\n",
    "\n",
    "print(\"DEM configuration options:\")\n",
    "for param, value in dem_params.items():\n",
    "    print(f\"  {param}: {value}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa8d9cf4",
   "metadata": {},
   "source": [
    "## 🤖 Automatic Data Source Selection\n",
    "\n",
    "VoxCity can automatically select the best data sources based on location:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "790c1c53",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check what sources would be auto-selected for different locations\n",
    "\n",
    "locations = {\n",
    "    \"Tokyo, Japan\": [(139.76, 35.68), (139.76, 35.69), (139.77, 35.69), (139.77, 35.68)],\n",
    "    \"New York, USA\": [(-74.02, 40.70), (-74.02, 40.71), (-74.00, 40.71), (-74.00, 40.70)],\n",
    "    \"London, UK\": [(-0.13, 51.50), (-0.13, 51.51), (-0.11, 51.51), (-0.11, 51.50)],\n",
    "    \"Lagos, Nigeria\": [(3.38, 6.45), (3.38, 6.46), (3.40, 6.46), (3.40, 6.45)],\n",
    "}\n",
    "\n",
    "print(\"Auto-selected data sources by location:\\n\")\n",
    "for city_name, coords in locations.items():\n",
    "    sources = auto_select_data_sources(coords)\n",
    "    print(f\"📍 {city_name}\")\n",
    "    for source_type, source_name in sources.items():\n",
    "        print(f\"   {source_type}: {source_name}\")\n",
    "    print()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4980984d",
   "metadata": {},
   "source": [
    "## 🔧 Custom Configuration Examples\n",
    "\n",
    "### Example 1: High-Resolution USA City\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5231555",
   "metadata": {},
   "outputs": [],
   "source": [
    "# High-resolution configuration for US cities\n",
    "usa_config = {\n",
    "    \"building_source\": \"OpenStreetMap\",\n",
    "    \"building_complementary_source\": \"Microsoft Building Footprints\",\n",
    "    \"land_cover_source\": \"Urbanwatch\",\n",
    "    \"canopy_height_source\": \"High Resolution 1m Global Canopy Height Maps\",\n",
    "    \"dem_source\": \"USGS 3DEP 1m\"\n",
    "}\n",
    "\n",
    "print(\"USA high-resolution configuration:\")\n",
    "for key, value in usa_config.items():\n",
    "    print(f\"  {key}: {value}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d585fb13",
   "metadata": {},
   "source": [
    "### Example 2: European City with EUBUCCO\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1964432",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Configuration for European cities with EUBUCCO building data\n",
    "eu_config = {\n",
    "    \"building_source\": \"EUBUCCO v0.1\",  # European building footprints with heights\n",
    "    \"building_complementary_source\": \"None\",\n",
    "    \"land_cover_source\": \"ESA WorldCover\",\n",
    "    \"canopy_height_source\": \"High Resolution 1m Global Canopy Height Maps\",\n",
    "    \"dem_source\": \"FABDEM\"\n",
    "}\n",
    "\n",
    "print(\"European city configuration (EUBUCCO):\")\n",
    "for key, value in eu_config.items():\n",
    "    print(f\"  {key}: {value}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3dba90b",
   "metadata": {},
   "source": [
    "### Example 3: Developing Region with Google Open Buildings\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0b96776a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Configuration for Africa/Asia/Latin America\n",
    "developing_config = {\n",
    "    \"building_source\": \"OpenStreetMap\",\n",
    "    \"building_complementary_source\": \"Open Building 2.5D Temporal\",  # Google heights\n",
    "    \"land_cover_source\": \"ESA WorldCover\",\n",
    "    \"canopy_height_source\": \"High Resolution 1m Global Canopy Height Maps\",\n",
    "    \"dem_source\": \"DeltaDTM\"\n",
    "}\n",
    "\n",
    "print(\"Developing region configuration:\")\n",
    "for key, value in developing_config.items():\n",
    "    print(f\"  {key}: {value}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b599cf9a",
   "metadata": {},
   "source": [
    "### Example 4: Japan with OpenEarthMapJapan\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5ec3bc4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Optimized configuration for Japan\n",
    "japan_config = {\n",
    "    \"building_source\": \"OpenStreetMap\",\n",
    "    \"building_complementary_source\": \"None\",\n",
    "    \"land_cover_source\": \"OpenEarthMapJapan\",  # High-quality Japanese land cover\n",
    "    \"canopy_height_source\": \"High Resolution 1m Global Canopy Height Maps\",\n",
    "    \"dem_source\": \"DeltaDTM\"  # or 'FABDEM'\n",
    "}\n",
    "\n",
    "print(\"Japan configuration:\")\n",
    "for key, value in japan_config.items():\n",
    "    print(f\"  {key}: {value}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "822d9d29",
   "metadata": {},
   "source": [
    "## 📁 Using Local Files\n",
    "\n",
    "You can use your own geospatial files as data sources:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f3b0ae41",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example: Using local GeoPackage file for buildings\n",
    "local_config = {\n",
    "    \"building_source\": \"Local file\",\n",
    "    \"building_path\": \"path/to/buildings.gpkg\",  # GeoPackage, Shapefile, or GeoJSON\n",
    "    # Building GDF should have columns: 'geometry' (Polygon), 'height' (optional)\n",
    "}\n",
    "\n",
    "print(\"Local file requirements:\")\n",
    "print(\"  Supported formats: GeoPackage (.gpkg), Shapefile (.shp), GeoJSON (.geojson)\")\n",
    "print(\"  Required columns: 'geometry' (Polygon/MultiPolygon)\")\n",
    "print(\"  Optional columns: 'height', 'min_height', 'id'\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56051d50",
   "metadata": {},
   "source": [
    "## 🌐 Google Earth Engine Authentication\n",
    "\n",
    "Some data sources require Google Earth Engine. Here's how to authenticate:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "731c0f24",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Google Earth Engine authentication\n",
    "# Run this if you plan to use GEE-based sources\n",
    "\n",
    "# Option 1: Notebook authentication (Google Colab)\n",
    "# import ee\n",
    "# ee.Authenticate()\n",
    "# ee.Initialize(project='your-gcp-project-id')\n",
    "\n",
    "# Option 2: Command line authentication\n",
    "# !earthengine authenticate\n",
    "\n",
    "# GEE-dependent sources:\n",
    "gee_sources = [\n",
    "    \"Open Building 2.5D Temporal\",\n",
    "    \"England 1m DSM - DTM\",\n",
    "    \"Netherlands 0.5m DSM - DTM\",\n",
    "    \"High Resolution 1m Global Canopy Height Maps\",\n",
    "    \"ETH Global Sentinel-2 10m Canopy Height (2020)\",\n",
    "    \"Urbanwatch\",\n",
    "    \"ESA WorldCover\",\n",
    "    \"ESRI 10m Annual Land Cover\",\n",
    "    \"Dynamic World V1\",\n",
    "    \"USGS 3DEP 1m\",\n",
    "    \"DeltaDTM\",\n",
    "    \"FABDEM\",\n",
    "]\n",
    "\n",
    "print(\"Sources requiring Google Earth Engine:\")\n",
    "for src in gee_sources:\n",
    "    print(f\"  • {src}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3dc8a829",
   "metadata": {},
   "source": [
    "## 📚 Summary\n",
    "\n",
    "### Quick Reference\n",
    "\n",
    "| Location | Buildings | Land Cover | DEM |\n",
    "|----------|-----------|------------|-----|\n",
    "| USA | OSM + MBFP | Urbanwatch | USGS 3DEP |\n",
    "| Europe | OSM/EUBUCCO | OSM/ESA | FABDEM |\n",
    "| Japan | OSM | OpenEarthMapJapan | DeltaDTM |\n",
    "| Africa/Asia/LatAm | OSM + OB 2.5D | ESA WorldCover | DeltaDTM |\n",
    "| Global default | OSM | OSM | DeltaDTM |\n",
    "\n",
    "### Tips\n",
    "\n",
    "1. **Start with auto-selection**: Let VoxCity choose sources, then customize\n",
    "2. **Check GEE authentication**: Many high-quality sources need Earth Engine\n",
    "3. **Match resolution**: Use higher-res DEM when meshsize is small (<5m)\n",
    "4. **Local files**: Great for custom datasets or offline work\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}