{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# 🌳 VoxCity View Index Analysis\n",
        "\n",
        "Analyze **Green View Index (GVI)** and **Sky View Index (SVI)** using 3D ray-casting through your voxel city model.\n",
        "\n",
        "## What are View Indices?\n",
        "\n",
        "| Index | Description | Use Case |\n",
        "|-------|-------------|----------|\n",
        "| **GVI** | Percentage of view occupied by vegetation | Urban greenery assessment |\n",
        "| **SVI** | Percentage of visible sky | Urban canyon analysis, thermal comfort |\n",
        "\n",
        "## Key Features\n",
        "\n",
        "- Ray-casting from observer viewpoint through 3D voxel model\n",
        "- Configurable azimuth and elevation sampling\n",
        "- Tree transmissivity modeling (light passes through tree canopy)\n",
        "- Export results as colored OBJ meshes\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_view_index\n",
        "\n",
        "cityname = \"Tokyo, Japan\"\n",
        "meshsize = 5\n",
        "\n",
        "# m, rectangle_vertices = draw_rectangle_map_cityname(cityname, zoom=15)\n",
        "# m\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/view_demo'\n",
        ")\n",
        "\n",
        "city.voxels.classes.shape\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "---\n",
        "## 🌳 Green View Index (GVI)\n",
        "\n",
        "Calculate the percentage of visible vegetation from each grid cell.\n",
        "\n",
        "### Advanced Parameters\n",
        "\n",
        "| Parameter | Description | Default |\n",
        "|-----------|-------------|---------|\n",
        "| `N_azimuth` | Number of azimuth angles | 72 |\n",
        "| `N_elevation` | Number of elevation angles | 12 |\n",
        "| `elevation_min_degrees` | Minimum elevation angle | -15° |\n",
        "| `elevation_max_degrees` | Maximum elevation angle | 30° |\n",
        "| `ray_sampling` | Sampling method: 'grid' or 'fibonacci' | 'fibonacci' |\n",
        "| `tree_k` | Extinction coefficient for tree canopy | 0.5 |\n",
        "| `tree_lad` | Leaf Area Density (LAD) | 1.0 |"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "gvi_kwargs = {\n",
        "    \"view_point_height\": 1.5,\n",
        "    \"colormap\": \"Greens\",\n",
        "    \"obj_export\": True,\n",
        "    \"output_directory\": \"output/view_demo\",\n",
        "    \"output_file_name\": \"gvi\",\n",
        "    \"alpha\": 1.0,\n",
        "    # Ray sampling controls\n",
        "    \"N_azimuth\": 72,\n",
        "    \"N_elevation\": 12,\n",
        "    \"elevation_min_degrees\": -15,\n",
        "    \"elevation_max_degrees\": 30,\n",
        "    \"ray_sampling\": \"fibonacci\",  # 'grid' or 'fibonacci'\n",
        "    # Tree transmittance controls\n",
        "    \"tree_k\": 0.5,\n",
        "    \"tree_lad\": 1.0,\n",
        "}\n",
        "\n",
        "gvi_grid = get_view_index(city, mode='green', **gvi_kwargs)\n",
        "\n",
        "gvi_grid.shape\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "---\n",
        "## 🌤️ Sky View Index (SVI)\n",
        "\n",
        "Calculate the percentage of visible sky from each grid cell.\n",
        "\n",
        "For SVI, the elevation range is typically from horizon (0°) to zenith (90°)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "svi_kwargs = gvi_kwargs.copy()\n",
        "svi_kwargs[\"colormap\"] = \"BuPu_r\"\n",
        "svi_kwargs[\"output_file_name\"] = \"svi\"\n",
        "svi_kwargs[\"elevation_min_degrees\"] = 0\n",
        "svi_kwargs[\"elevation_max_degrees\"] = 90\n",
        "\n",
        "svi_grid = get_view_index(city, mode='sky', **svi_kwargs)\n",
        "\n",
        "svi_grid.shape\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "---\n",
        "## 📊 Interpreting Results\n",
        "\n",
        "- **GVI values** range from 0 to 1 (0% to 100% vegetation visibility)\n",
        "- **SVI values** range from 0 to 1 (0% to 100% sky visibility)\n",
        "- Results are exported as colored OBJ files for visualization in Blender/Rhino\n",
        "- Higher `N_azimuth` and `N_elevation` values give more accurate but slower results\n",
        "\n",
        "## Next Steps\n",
        "\n",
        "- `demo_solar.ipynb` - Solar irradiance simulation\n",
        "- `demo_landmark.ipynb` - Landmark visibility analysis\n",
        "- `demo_3d_visualization.ipynb` - Advanced 3D visualization"
      ]
    }
  ],
  "metadata": {
    "language_info": {
      "name": "python"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 2
}