{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# 📦 VoxCity OBJ Export\n",
        "\n",
        "Export voxel city models and simulation results to Wavefront OBJ format for use in external 3D software.\n",
        "\n",
        "## Export Types\n",
        "\n",
        "| Export | Function | Description |\n",
        "|--------|----------|-------------|\n",
        "| **Voxel City** | `export_obj()` | Full 3D voxel model |\n",
        "| **Simulation Results** | `grid_to_obj()` | Value-mapped colored surface |\n",
        "\n",
        "## Use Cases\n",
        "\n",
        "- **Blender/Rhino integration** - Import for rendering and further modeling\n",
        "- **Presentation** - Create high-quality visualizations\n",
        "- **Analysis overlay** - View simulation results as colored 3D surfaces\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.exporter.obj import export_obj, grid_to_obj\n",
        "from voxcity.simulator.solar import get_global_solar_irradiance_using_epw\n",
        "from voxcity.simulator.view import get_view_index\n",
        "\n",
        "meshsize = 5\n",
        "rectangle_vertices = [\n",
        "    (139.760, 35.680),\n",
        "    (139.760, 35.690),\n",
        "    (139.770, 35.690),\n",
        "    (139.770, 35.680)\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/obj_demo'\n",
        ")\n",
        "\n",
        "# Access grids from the VoxCity object\n",
        "voxcity_grid = city.voxels.classes\n",
        "dem_grid = city.dem.elevation\n",
        "\n",
        "print(voxcity_grid.shape, dem_grid.shape)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "---\n",
        "## 🏙️ Export Voxel City\n",
        "\n",
        "Export the full 3D voxel city model as an OBJ file with materials."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "export_obj(city, output_dir='output/obj_demo', file_name='voxcity')\n",
        "print('Exported voxcity OBJ')\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "---\n",
        "## 📊 Export Simulation Results as Colored OBJ\n",
        "\n",
        "Export 2D analysis grids (solar, view indices) as colored 3D surfaces.\n",
        "\n",
        "### `grid_to_obj()` Parameters\n",
        "\n",
        "| Parameter | Description |\n",
        "|-----------|-------------|\n",
        "| `output_dir` | Output directory path |\n",
        "| `file_name` | Output file name (without extension) |\n",
        "| `cell_size` | Grid cell size (meshsize) |\n",
        "| `offset` | Height offset for surface (default: view_point_height) |\n",
        "| `colormap_name` | Matplotlib colormap name |\n",
        "| `vmin`/`vmax` | Value range for color mapping |\n",
        "| `alpha` | Transparency (0-1) |"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Instantaneous solar\n",
        "solar_kwargs = {\n",
        "    \"download_nearest_epw\": True,\n",
        "    \"rectangle_vertices\": rectangle_vertices,\n",
        "    \"calc_time\": \"01-01 12:00:00\",\n",
        "    \"view_point_height\": 1.5,\n",
        "}\n",
        "solar_grid = get_global_solar_irradiance_using_epw(\n",
        "    city, calc_type='instantaneous', **solar_kwargs\n",
        ")\n",
        "\n",
        "# Export instantaneous solar as colored OBJ\n",
        "grid_to_obj(\n",
        "    solar_grid, dem_grid,\n",
        "    output_dir='output/obj_demo', file_name='solar_instantaneous',\n",
        "    cell_size=meshsize, offset=1.5, colormap_name='magma', num_colors=10, alpha=1.0,\n",
        "    vmin=0\n",
        ")\n",
        "\n",
        "# Cumulative solar for a time window\n",
        "cum_kwargs = solar_kwargs.copy()\n",
        "cum_kwargs[\"start_time\"] = \"01-01 05:00:00\"\n",
        "cum_kwargs[\"end_time\"] = \"01-31 20:00:00\"\n",
        "\n",
        "cum_solar_grid = get_global_solar_irradiance_using_epw(\n",
        "    city, calc_type='cumulative', **cum_kwargs\n",
        ")\n",
        "\n",
        "grid_to_obj(\n",
        "    cum_solar_grid, dem_grid,\n",
        "    output_dir='output/obj_demo', file_name='solar_cumulative',\n",
        "    cell_size=meshsize, offset=1.5, colormap_name='viridis', num_colors=10, alpha=1.0\n",
        ")\n",
        "\n",
        "# View indices\n",
        "gvi = get_view_index(city, mode='green', obj_export=False)\n",
        "\n",
        "grid_to_obj(\n",
        "    gvi, dem_grid,\n",
        "    output_dir='output/obj_demo', file_name='gvi',\n",
        "    cell_size=meshsize, offset=1.5, colormap_name='Greens', num_colors=10, alpha=1.0,\n",
        "    vmin=0.0, vmax=1.0\n",
        ")\n"
      ]
    }
  ],
  "metadata": {
    "language_info": {
      "name": "python"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 2
}