{ "cells": [ { "cell_type": "markdown", "id": "09e18cef", "metadata": {}, "source": [ "# šŸ™ļø VoxCity Quick Start Guide\n", "\n", "Welcome to **VoxCity** ā€” a Python package for generating and analyzing 3D voxel-based urban models.\n", "\n", "This notebook will get you up and running in **under 5 minutes** with automatic data source selection.\n", "\n", "## What You'll Learn\n", "1. āœ… Install VoxCity\n", "2. āœ… Define your area of interest\n", "3. āœ… Generate a 3D city model automatically\n", "4. āœ… Visualize the result\n", "5. āœ… Export to common formats" ] }, { "cell_type": "markdown", "id": "af181352", "metadata": {}, "source": [ "## šŸ“¦ Step 1: Installation\n", "\n", "Run the cell below to install VoxCity. Skip if already installed." ] }, { "cell_type": "code", "execution_count": null, "id": "11e843f7", "metadata": {}, "outputs": [], "source": [ "# Uncomment and run if you need to install VoxCity\n", "# %pip install voxcity" ] }, { "cell_type": "markdown", "id": "a04b9574", "metadata": {}, "source": [ "## šŸŒ Step 2: Define Your Area of Interest\n", "\n", "VoxCity needs a rectangular area defined by 4 corner coordinates in **(longitude, latitude)** format.\n", "\n", "Here's an example for **Tokyo, Japan**. Replace with your own coordinates!" ] }, { "cell_type": "code", "execution_count": null, "id": "44052ef2", "metadata": {}, "outputs": [], "source": [ "# Define the area of interest as a rectangle\n", "# Format: (longitude, latitude) for each corner\n", "rectangle_vertices = [\n", " (139.760, 35.680), # Southwest corner\n", " (139.760, 35.690), # Northwest corner\n", " (139.770, 35.690), # Northeast corner\n", " (139.770, 35.680) # Southeast corner\n", "]\n", "\n", "# Set the voxel resolution in meters\n", "meshsize = 5 # 5m resolution - smaller = more detail but slower\n", "\n", "print(f\"Area defined: ~{abs(rectangle_vertices[2][0] - rectangle_vertices[0][0]) * 111320:.0f}m x {abs(rectangle_vertices[1][1] - rectangle_vertices[0][1]) * 111320:.0f}m\")\n", "print(f\"Voxel size: {meshsize}m\")" ] }, { "cell_type": "markdown", "id": "fec0610e", "metadata": {}, "source": [ "### šŸ’” Tip: Interactive Area Selection\n", "\n", "If you want to draw a rectangle on an interactive map instead:\n", "\n", "```python\n", "from voxcity.geoprocessor.draw import draw_rectangle_map_cityname\n", "\n", "cityname = \"Tokyo, Japan\"\n", "m, rectangle_vertices = draw_rectangle_map_cityname(cityname, zoom=15)\n", "m # Display the map, then draw a rectangle\n", "```" ] }, { "cell_type": "markdown", "id": "3d130dc4", "metadata": {}, "source": [ "## šŸš€ Step 3: Generate the 3D City Model\n", "\n", "VoxCity will **automatically select the best data sources** for your location!" ] }, { "cell_type": "code", "execution_count": null, "id": "e079a71c", "metadata": {}, "outputs": [], "source": [ "from voxcity.generator import get_voxcity\n", "\n", "# Generate the city model with AUTO data source selection\n", "city = get_voxcity(\n", " rectangle_vertices,\n", " meshsize=meshsize,\n", " output_dir='output/quickstart' # Where to save intermediate files\n", ")\n", "\n", "# Show what we got\n", "print(f\"\\nāœ… City model generated!\")\n", "print(f\" Voxel grid shape: {city.voxels.classes.shape}\")\n", "print(f\" (rows Ɨ cols Ɨ height levels)\")" ] }, { "cell_type": "markdown", "id": "9e604849", "metadata": {}, "source": [ "### What's in the VoxCity object?\n", "\n", "The `city` object contains several data grids:\n", "\n", "| Attribute | Description |\n", "|-----------|-------------|\n", "| `city.voxels.classes` | 3D voxel grid (0=air, 1=ground, 2=tree, 3=building) |\n", "| `city.buildings.heights` | 2D grid of building heights |\n", "| `city.buildings.ids` | 2D grid of building IDs |\n", "| `city.land_cover.classes` | 2D land cover classification |\n", "| `city.dem.elevation` | 2D digital elevation model |\n", "| `city.tree_canopy.top` | 2D canopy height grid |" ] }, { "cell_type": "code", "execution_count": null, "id": "62e63a4f", "metadata": {}, "outputs": [], "source": [ "# Quick look at the data\n", "import numpy as np\n", "\n", "voxels = city.voxels.classes\n", "print(\"Voxel statistics:\")\n", "print(f\" Air cells: {np.sum(voxels == 0):,}\")\n", "print(f\" Ground cells: {np.sum(voxels == 1):,}\")\n", "print(f\" Tree cells: {np.sum(voxels == 2):,}\")\n", "print(f\" Building cells: {np.sum(voxels == 3):,}\")" ] }, { "cell_type": "markdown", "id": "0693f82d", "metadata": {}, "source": [ "## šŸ‘ļø Step 4: Visualize the 3D Model" ] }, { "cell_type": "code", "execution_count": null, "id": "2a293913", "metadata": {}, "outputs": [], "source": [ "from voxcity.visualizer import visualize_voxcity\n", "\n", "# Static visualization (saves an image)\n", "visualize_voxcity(\n", " city,\n", " mode=\"static\", # 'static' for image, 'interactive' for 3D viewer\n", " output_directory=\"output/quickstart\"\n", ")" ] }, { "cell_type": "markdown", "id": "1fede664", "metadata": {}, "source": [ "### Interactive 3D Visualization\n", "\n", "For an interactive view you can rotate and zoom:" ] }, { "cell_type": "code", "execution_count": null, "id": "b8e9ae0f", "metadata": {}, "outputs": [], "source": [ "# Interactive visualization using Plotly\n", "# (Requires plotly: pip install plotly)\n", "fig = visualize_voxcity(city, mode=\"interactive\", show=False, return_fig=True)\n", "fig.show()" ] }, { "cell_type": "markdown", "id": "121639dc", "metadata": {}, "source": [ "## šŸ’¾ Step 5: Export the Model\n", "\n", "VoxCity supports multiple export formats for different use cases." ] }, { "cell_type": "code", "execution_count": null, "id": "cd2c9cec", "metadata": {}, "outputs": [], "source": [ "# Export to OBJ (for Blender, Rhino, 3D viewers)\n", "from voxcity.exporter.obj import export_obj\n", "\n", "export_obj(city, output_dir='output/quickstart', file_name='my_city')\n", "print(\"āœ… Exported: output/quickstart/my_city.obj\")" ] }, { "cell_type": "code", "execution_count": null, "id": "b9d45de4", "metadata": {}, "outputs": [], "source": [ "# Export to MagicaVoxel VOX format (for voxel art editors)\n", "from voxcity.exporter.magicavoxel import export_magicavoxel_vox\n", "\n", "export_magicavoxel_vox(city, \"output/quickstart\")\n", "print(\"āœ… Exported: output/quickstart/voxcity.vox\")" ] }, { "cell_type": "code", "execution_count": null, "id": "d691aef2", "metadata": {}, "outputs": [], "source": [ "# Save/Load VoxCity object for later use\n", "from voxcity.generator import save_voxcity, load_voxcity\n", "\n", "save_voxcity('output/quickstart/city.pkl', city)\n", "print(\"āœ… Saved city object\")\n", "\n", "# Later, load it back:\n", "# city = load_voxcity('output/quickstart/city.pkl')" ] }, { "cell_type": "markdown", "id": "3fb1c809", "metadata": {}, "source": [ "## šŸŽ‰ You're Done!\n", "\n", "You've successfully:\n", "- Generated a 3D voxel city model\n", "- Visualized it in 2D and 3D\n", "- Exported it to multiple formats\n", "\n", "## What's Next?\n", "\n", "Explore more advanced features in other tutorials:\n", "\n", "| Notebook | Description |\n", "|----------|-------------|\n", "| `demo_basic.ipynb` | Complete guide to all data sources and options |\n", "| `demo_view.ipynb` | Green View Index & Sky View Index analysis |\n", "| `demo_solar.ipynb` | Solar irradiance simulation |\n", "| `demo_landmark.ipynb` | Landmark visibility analysis |\n", "| `demo_3d_visualization.ipynb` | Advanced 3D visualization options |\n", "| `demo_envi-met.ipynb` | Export for ENVI-met CFD simulations |" ] } ], "metadata": { "language_info": { "name": "python" } }, "nbformat": 4, "nbformat_minor": 5 }