{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# 🏛️ VoxCity Landmark Visibility Analysis\n",
        "\n",
        "Analyze **visibility** of specific landmarks (buildings) from all locations in your study area using 3D ray-casting.\n",
        "\n",
        "## Use Cases\n",
        "\n",
        "- **Wayfinding research** - Which landmarks are visible from different locations?\n",
        "- **Urban planning** - Assess visual impact of new buildings\n",
        "- **Real estate** - Evaluate views from different properties\n",
        "- **Tourism** - Map visibility of attractions\n",
        "\n",
        "## Landmark Selection Methods\n",
        "\n",
        "| Method | When to Use |\n",
        "|--------|-------------|\n",
        "| `landmark_building_ids` | You know specific building IDs |\n",
        "| `landmark_polygon` | Define custom area containing landmarks |\n",
        "| Auto-select (center) | Let VoxCity pick buildings near center |\n",
        "\n",
        "## Prerequisites\n",
        "\n",
        "```python\n",
        "pip install voxcity\n",
        "```"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# %pip install voxcity\n",
        "\n",
        "from voxcity.generator import get_voxcity\n",
        "from voxcity.geoprocessor.draw import draw_rectangle_map_cityname\n",
        "from voxcity.simulator.view import get_landmark_visibility_map\n",
        "\n",
        "meshsize = 5\n",
        "cityname = \"Tokyo, Japan\"\n",
        "\n",
        "rectangle_vertices = [\n",
        "    (139.760, 35.680),  # SW\n",
        "    (139.760, 35.690),  # NW\n",
        "    (139.770, 35.690),  # NE\n",
        "    (139.770, 35.680)   # SE\n",
        "]\n",
        "\n",
        "city = get_voxcity(\n",
        "    rectangle_vertices,\n",
        "    meshsize=meshsize,\n",
        "    building_source='OpenStreetMap',\n",
        "    land_cover_source='OpenStreetMap',\n",
        "    canopy_height_source='High Resolution 1m Global Canopy Height Maps',\n",
        "    dem_source='DeltaDTM',\n",
        "    output_dir='output/landmark_demo'\n",
        ")\n",
        "\n",
        "# Access building_gdf from the VoxCity object\n",
        "building_gdf = city.extras.get('building_gdf', None)\n",
        "len(building_gdf) if building_gdf is not None else 0\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "---\n",
        "## 🎯 Select Landmarks\n",
        "\n",
        "Three ways to specify which buildings are \"landmarks\":\n",
        "\n",
        "1. **By IDs**: Provide `landmark_building_ids` - list of building indices from GeoDataFrame\n",
        "2. **By Polygon**: Provide `landmark_polygon` - GeoJSON-style polygon, all buildings inside become landmarks\n",
        "3. **Auto-center**: Omit both parameters - function picks buildings at rectangle center"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "landmark_kwargs = {\n",
        "    \"view_point_height\": 1.5,\n",
        "    \"colormap\": \"cool\",\n",
        "    \"obj_export\": True,\n",
        "    \"output_directory\": \"output/landmark_demo\",\n",
        "    \"output_file_name\": \"landmark_visibility\",\n",
        "    \"alpha\": 1.0,\n",
        "}\n",
        "\n",
        "# Example 1: Pick by IDs (take first few as sample)\n",
        "ids_sample = building_gdf.head(3).index.tolist() if building_gdf is not None else []\n",
        "\n",
        "landmark_vis_map, voxcity_grid_marked = get_landmark_visibility_map(\n",
        "    city,\n",
        "    building_gdf=building_gdf,\n",
        "    landmark_building_ids=ids_sample,\n",
        "    **landmark_kwargs\n",
        ")\n",
        "\n",
        "landmark_vis_map.shape\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Example 2: Auto-select using rectangle center (omit IDs and polygon)\n",
        "landmark_vis_map_auto, _ = get_landmark_visibility_map(\n",
        "    city,\n",
        "    building_gdf=building_gdf,\n",
        "    rectangle_vertices=rectangle_vertices,\n",
        "    **landmark_kwargs\n",
        ")\n",
        "\n",
        "landmark_vis_map_auto.shape\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "---\n",
        "## 📊 Interpreting Results\n",
        "\n",
        "- **Visibility values**: 0 = not visible, 1 = fully visible\n",
        "- **Output**: Colored OBJ mesh showing visibility from each location\n",
        "- **`voxcity_grid_marked`**: 3D voxel grid with landmarks highlighted\n",
        "\n",
        "## Next Steps\n",
        "\n",
        "- `demo_view.ipynb` - Green View Index & Sky View Index\n",
        "- `demo_solar.ipynb` - Solar irradiance simulation\n",
        "- `demo_3d_visualization.ipynb` - Advanced 3D visualization"
      ]
    }
  ],
  "metadata": {
    "language_info": {
      "name": "python"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 2
}