| Name | voxelcity JSON |
| Version |
0.1.81
JSON |
| download |
| home_page | None |
| Summary | voxelcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data |
| upload_time | 2024-12-15 05:36:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.13,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.python.org/pypi/voxelcity)
[](https://pypi.org/project/voxelcity/)
[](https://colab.research.google.com/drive/1Lofd3RawKMr6QuUsamGaF48u2MN0hfrP?usp=sharing)
[](https://pypi.org/project/voxelcity/)
[](https://pepy.tech/project/voxelcity)
<!-- [](https://creativecommons.org/licenses/by-sa/4.0/) -->
# VoxelCity
**VoxelCity** is a Python package that facilitates the creation of voxel-based 3D urban environments and related geospatial analyses. It integrates various geospatial datasets—such as building footprints, land cover, canopy height, and digital elevation models (DEMs)—to generate 2D and 3D representations of urban areas. It can export data in formats compatible with popular simulation tools like ENVI-MET, as well as visualization tools like MagicaVoxel, and supports simulations such as sky view index and green view index calculations.
<!-- <p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/kunifujiwara/VoxCity/blob/main/images/concept.png">
<img src="https://github.com/kunifujiwara/VoxCity/blob/main/images/concept.png" alt="Conceptual Diagram of VoxelCity" width="800">
</picture>
</p> -->
<p align="center">
<img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/concept.png" alt="Conceptual Diagram of VoxelCity" width="800">
</p>
## Key Features
- **Integration of Multiple Data Sources:**
Combines building footprints, land cover data, canopy height maps, and DEMs to generate a consistent 3D voxel representation of an urban scene.
- **Flexible Input Sources:**
Supports various building and terrain data sources including:
- Building Footprints: OpenStreetMap, Overture, EUBUCCO, Microsoft Building Footprints, OpenMapTiles, Open Building 2.5D
- Land Cover: UrbanWatch, OpenEarthMap Japan, ESA WorldCover, ESRI Land Cover, Dynamic World, OpenStreetMap
- Canopy Height: High Resolution 1m Global Canopy Height Maps, ETH Global Sentinel-2 10m
- DEM: DeltaDTM, FABDEM, NASA, COPERNICUS, and more
*Detailed information about each data source can be found in the [References of Data Sources](#references-of-data-sources) section.*
- **Customizable Domain and Resolution:**
Easily define a target area by drawing a rectangle on a map or specifying center coordinates and dimensions. Adjust the mesh size to meet resolution needs.
- **Integration with Earth Engine:**
Leverages Google Earth Engine for large-scale geospatial data processing (authentication and project setup required).
- **Output Formats:**
- **ENVI-MET**: Export INX and EDB files suitable for ENVI-MET microclimate simulations.
- **MagicaVoxel**: Export vox files for 3D editing and visualization in MagicaVoxel.
- **OBJ**: Export wavefront OBJ for rendering and integration into other workflows.
- **Analytical Tools:**
- **View Index Simulations**: Compute sky view index (SVI) and green view index (GVI) from a specified viewpoint.
- **Landmark Visibility Maps**: Assess the visibility of selected landmarks within the voxelized environment.
## Installation
Make sure you have Python 3.12 installed. Install VoxelCity with:
### For Local Environment
```bash
conda create --name voxelcity python=3.12
conda activate voxelcity
conda install -c conda-forge gdal
pip install voxelcity
```
### For Google Colab
```python
!pip install voxelcity
```
## Setup for Earth Engine
To use Earth Engine data, set up your Earth Engine enabled Cloud Project by following the instructions here:
https://developers.google.com/earth-engine/cloud/earthengine_cloud_project_setup
After setting up, authenticate and initialize Earth Engine:
### For Local Environment
```bash
earthengine authenticate
```
### For Google Colab
```python
# Click displayed link, generate token, copy and paste the token
!earthengine authenticate --auth_mode=notebook
```
## Usage Overview
### 1. Authenticate Earth Engine
```python
import ee
ee.Authenticate()
ee.Initialize(project='your-project-id')
```
### 2. Define Target Area
You can define your target area in three ways:
#### Option 1: Direct Coordinate Input
Define the target area by directly specifying the coordinates of the rectangle vertices.
```python
rectangle_vertices = [
(47.59830044521263, -122.33587348582083), # Southwest corner (latitude, longitude)
(47.60279755390168, -122.33587348582083), # Northwest corner (latitude, longitude)
(47.60279755390168, -122.32922451417917), # Northeast corner (latitude, longitude)
(47.59830044521263, -122.32922451417917) # Southeast corner (latitude, longitude)
]
```
#### Option 2: Draw a Rectangle (for Jupyter Notebook)
Use the GUI map interface to draw a rectangular domain of interest.
```python
from voxelcity.geo.draw import draw_rectangle_map_cityname
cityname = "tokyo"
m, rectangle_vertices = draw_rectangle_map_cityname(cityname, zoom=15)
m
```
#### Option 3: Specify Center and Dimensions (for Jupyter Notebook)
Choose the width and height in meters and select the center point on the map.
```python
from voxelcity.geo.draw import center_location_map_cityname
width = 500
height = 500
m, rectangle_vertices = center_location_map_cityname(cityname, width, height, zoom=15)
m
```
<p align="center">
<img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/draw_rect.png" alt="Draw Rectangle on Map GUI" width="400">
</p>
### 3. Set Parameters
Define data sources and mesh size (m):
```python
building_source = 'OpenStreetMap' # Building footprint and height data source
land_cover_source = 'OpenStreetMap' # Land cover classification data source
canopy_height_source = 'High Resolution 1m Global Canopy Height Maps' # Tree canopy height data source
dem_source = 'DeltaDTM' # Digital elevation model data source
meshsize = 5 # Grid cell size in meters
kwargs = {
"output_dir": "output", # Directory to save output files
"dem_interpolation": True # Enable DEM interpolation
}
```
### 4. Get VoxelCity Output
Generate voxel data grids and corresponding building geoJSON:
```python
from voxelcity import get_voxelcity
voxelcity_grid, building_height_grid, building_min_height_grid, \
building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, \
building_geojson = get_voxelcity(
rectangle_vertices,
building_source,
land_cover_source,
canopy_height_source,
dem_source,
meshsize,
**kwargs
)
```
### 5. Exporting Files
#### ENVI-MET INX/EDB Files:
[ENVI-MET](https://www.envi-met.com/) is an advanced microclimate simulation software specialized in modeling urban environments. It simulates the interactions between buildings, vegetation, and various climate parameters like temperature, wind flow, humidity, and radiation. The software is used widely in urban planning, architecture, and environmental studies (Commercial, offers educational licenses).
```python
from voxelcity.file.envimet import export_inx, generate_edb_file
envimet_kwargs = {
"output_directory": "output", # Directory where output files will be saved
"author_name": "your name", # Name of the model author
"model_description": "generated with VoxelCity", # Description text for the model
"domain_building_max_height_ratio": 2, # Maximum ratio between domain height and tallest building height
"useTelescoping_grid": True, # Enable telescoping grid for better computational efficiency
"verticalStretch": 20, # Vertical grid stretching factor (%)
"min_grids_Z": 20, # Minimum number of vertical grid cells
"lad": 1.0 # Leaf Area Density (m2/m3) for vegetation modeling
}
export_inx(building_height_grid, building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, meshsize, land_cover_source, rectangle_vertices, **envimet_kwargs)
generate_edb_file(**envimet_kwargs)
```
<p align="center">
<img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/envimet.png" alt="Generated 3D City Model on Envi-MET GUI" width="600">
</p>
<p align="center">
<em>Example Output Exported in INX and Inported in ENVI-met</em>
</p>
#### OBJ Files:
```python
from voxelcity.file.obj import export_obj
output_directory = "output" # Directory where output files will be saved
output_file_name = "voxcity" # Base name for the output OBJ file
export_obj(voxelcity_grid, output_directory, output_file_name, meshsize)
```
The generated OBJ files can be opened and rendered in the following 3D visualization software:
- [Twinmotion](https://www.twinmotion.com/): Real-time visualization tool (Free for personal use)
- [Blender](https://www.blender.org/): Professional-grade 3D creation suite (Free)
- [Rhino](https://www.rhino3d.com/): Professional 3D modeling software (Commercial, offers educational licenses)
<p align="center">
<img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/obj.png" alt="OBJ 3D City Model Rendered in Rhino" width="600">
</p>
<p align="center">
<em>Example Output Exported in OBJ and Rendered in MagicaVoxel</em>
</p>
#### MagicaVoxel VOX Files:
[MagicaVoxel](https://ephtracy.github.io/) is a lightweight and user-friendly voxel art editor. It allows users to create, edit, and render voxel-based 3D models with an intuitive interface, making it perfect for modifying and visualizing voxelized city models. The software is free and available for Windows and Mac.
```python
from voxelcity.file.magicavoxel import export_magicavoxel_vox
output_path = "output"
base_filename = "voxelcity"
export_magicavoxel_vox(voxelcity_grid, output_path, base_filename=base_filename)
```
<p align="center">
<img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/vox.png" alt="Generated 3D City Model on MagicaVoxel GUI" width="600">
</p>
<p align="center">
<em>Example Output Exported in VOX and Rendered in MagicaVoxel</em>
</p>
### 6. Additional Use Cases
#### Compute Green View Index (GVI) and Sky View Index (SVI):
```python
from voxelcity.sim.view import get_green_view_index, get_sky_view_index
# Dictionary of parameters for view index analysis
view_kwargs = {
"view_point_height": 1.5, # Height of observer viewpoint in meters
"dem_grid": dem_grid, # Digital elevation model grid
"colormap": "viridis", # Colormap for visualization
"obj_export": True, # Whether to export as OBJ file
"output_directory": "output", # Directory to save output files
"output_file_name": "gvi" # Base filename for outputs
}
gvi_grid = get_green_view_index(voxelcity_grid, meshsize, **view_kwargs)
view_kwargs["colormap"] = "BuPu_r"
view_kwargs["output_file_name"] = "svi"
svi_grid = get_sky_view_index(voxelcity_grid, meshsize, **view_kwargs)
```
<p align="center">
<img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/view_index.png" alt="View Index Maps Rendered in Rhino" width="800">
</p>
<p align="center">
<em>Example Results Saved as OBJ and Rendered in Rhino</em>
</p>
#### Landmark Visibility Map:
```python
from voxelcity.sim.view import get_landmark_visibility_map
# Dictionary of parameters for landmark visibility analysis
landmark_kwargs = {
"view_point_height": 1.5, # Height of observer viewpoint in meters
"rectangle_vertices": rectangle_vertices, # Vertices defining simulation domain boundary
"dem_grid": dem_grid, # Digital elevation model grid
"colormap": "cool", # Colormap for visualization
"obj_export": True, # Whether to export as OBJ file
"output_directory": "output", # Directory to save output files
"output_file_name": "landmark_visibility" # Base filename for outputs
}
landmark_vis_map = get_landmark_visibility_map(voxelcity_grid, building_id_grid, building_geojson, meshsize, **landmark_kwargs)
```
<p align="center">
<img src="https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/landmark.png" alt="Landmark Visibility Map Rendered in Rhino" width="500">
</p>
<p align="center">
<em>Example Result Saved as OBJ and Rendered in Rhino</em>
</p>
## References of Data Sources
### Building
| Dataset | Spatial Coverage | Source/Data Acquisition |
|---------|------------------|------------------------|
| [OpenStreetMap](https://www.openstreetmap.org) | Worldwide (24% completeness in city centers) | Volunteered / updated continuously |
| [Global ML Building Footprints](https://github.com/microsoft/GlobalMLBuildingFootprints) | North America, Europe, Australia | Prediction from satellite or aerial imagery / 2018-2019 for majority of the input imagery |
| [Open Buildings 2.5D Temporal Dataset](https://sites.research.google/gr/open-buildings/temporal/) | Africa, Latin America, and South and Southeast Asia | Prediction from satellite imagery / 2016-2023 |
| [EUBUCCO v0.1](https://eubucco.com/) | 27 EU countries and Switzerland (378 regions and 40,829 cities) | OpenStreetMap, government datasets / 2003-2021 (majority is after 2019) |
| [UT-GLOBUS](https://zenodo.org/records/11156602) | Worldwide (more than 1200 cities or locales) | Prediction from building footprints, population, spaceborne nDSM / not provided |
| [Overture Maps](https://overturemaps.org/) | Worldwide | OpenStreetMap, Esri Community Maps Program, Google Open Buildings, etc. / updated continuously |
### Tree Canopy Height
| Dataset | Coverage | Resolution | Source/Data Acquisition |
|---------|-----------|------------|------------------------|
| [High Resolution 1m Global Canopy Height Maps](https://sustainability.atmeta.com/blog/2024/04/22/using-artificial-intelligence-to-map-the-earths-forests/) | Worldwide | 1 m | Prediction from satellite imagery / 2009 and 2020 (80% are 2018-2020) |
| [ETH Global Sentinel-2 10m Canopy Height (2020)](https://langnico.github.io/globalcanopyheight/) | Worldwide | 10 m | Prediction from satellite imagery / 2020 |
### Land Cover
| Dataset | Spatial Coverage | Resolution | Source/Data Acquisition |
|---------|------------------|------------|----------------------|
| [ESA World Cover 10m 2021 V200](https://zenodo.org/records/7254221) | Worldwide | 10 m | Prediction from satellite imagery / 2021 |
| [ESRI 10m Annual Land Cover (2017-2023)](https://www.arcgis.com/home/item.html?id=cfcb7609de5f478eb7666240902d4d3d) | Worldwide | 10 m | Prediction from satellite imagery / 2017-2023 |
| [Dynamic World V1](https://dynamicworld.app) | Worldwide | 10 m | Prediction from satellite imagery / updated continuously |
| [OpenStreetMap](https://www.openstreetmap.org) | Worldwide | - (Vector) | Volunteered / updated continuously |
| [OpenEarthMap Japan](https://www.open-earth-map.org/demo/Japan/leaflet.html) | Japan | ~1 m | Prediction from aerial imagery / 1974-2022 (mostly after 2018 in major cities) |
| [UrbanWatch](https://urbanwatch.charlotte.edu/) | 22 major cities in the US | 1 m | Prediction from aerial imagery / 2014–2017 |
### Terrain Elevation
| Dataset | Coverage | Resolution | Source/Data Acquisition |
|---------|-----------|------------|------------------------|
| [FABDEM](https://doi.org/10.5523/bris.25wfy0f9ukoge2gs7a5mqpq2j7) | Worldwide | 30 m | Correction of Copernicus DEM using canopy height and building footprints data / 2011-2015 (Copernicus DEM) |
| [DeltaDTM](https://gee-community-catalog.org/projects/delta_dtm/) | Worldwide (Only for coastal areas below 10m + mean sea level) | 30 m | Copernicus DEM, spaceborne LiDAR / 2011-2015 (Copernicus DEM) |
| [USGS 3DEP 1m DEM](https://www.usgs.gov/3d-elevation-program) | United States | 1 m | Aerial LiDAR / 2004-2024 (mostly after 2015) |
| [England 1m Composite DTM](https://environment.data.gov.uk/dataset/13787b9a-26a4-4775-8523-806d13af58fc) | England | 1 m | Aerial LiDAR / 2000-2022 |
| [Australian 5M DEM](https://ecat.ga.gov.au/geonetwork/srv/eng/catalog.search#/metadata/89644) | Australia | 5 m | Aerial LiDAR / 2001-2015 |
| [RGE Alti](https://geoservices.ign.fr/rgealti) | France | 1 m | Aerial LiDAR |
## Citation
Please cite the [paper](https://doi.org) if you use `voxelcity` in a scientific publication:
Fujiwara, K., XXX. XXX. XXX, XXX, XXX.
```bibtex
@article{,
author = {Fujiwara, Kunihiko and XXX, XXX and XXX, XXX and XXX, XXX},
doi = {XXX},
journal = {XXX},
pages = {XXX},
title = {XXX},
volume = {XXX},
year = {XXX}
}
```
## Credit
This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [`audreyr/cookiecutter-pypackage`](https://github.com/audreyr/cookiecutter-pypackage) project template.
--------------------------------------------------------------------------------
<br>
<br>
<p align="center">
<a href="https://ual.sg/">
<img src="https://raw.githubusercontent.com/winstonyym/urbanity/main/images/ualsg.jpeg" width = 55% alt="Logo">
</a>
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "voxelcity",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": "Kunihiko Fujiwara <kunihiko@nus.edu.sg>",
"keywords": null,
"author": null,
"author_email": "Kunihiko Fujiwara <kunihiko@nus.edu.sg>",
"download_url": "https://files.pythonhosted.org/packages/c9/04/fb0c8b8aebe82516dccebb30239a97e27dea892d48ad5c0e697a6359e4ba/voxelcity-0.1.81.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/voxelcity)\r\n[](https://pypi.org/project/voxelcity/)\r\n[](https://colab.research.google.com/drive/1Lofd3RawKMr6QuUsamGaF48u2MN0hfrP?usp=sharing)\r\n[](https://pypi.org/project/voxelcity/)\r\n[](https://pepy.tech/project/voxelcity)\r\n<!-- [](https://creativecommons.org/licenses/by-sa/4.0/) -->\r\n\r\n\r\n# VoxelCity\r\n\r\n**VoxelCity** is a Python package that facilitates the creation of voxel-based 3D urban environments and related geospatial analyses. It integrates various geospatial datasets\u2014such as building footprints, land cover, canopy height, and digital elevation models (DEMs)\u2014to generate 2D and 3D representations of urban areas. It can export data in formats compatible with popular simulation tools like ENVI-MET, as well as visualization tools like MagicaVoxel, and supports simulations such as sky view index and green view index calculations.\r\n\r\n<!-- <p align=\"center\">\r\n <picture>\r\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/kunifujiwara/VoxCity/blob/main/images/concept.png\">\r\n <img src=\"https://github.com/kunifujiwara/VoxCity/blob/main/images/concept.png\" alt=\"Conceptual Diagram of VoxelCity\" width=\"800\">\r\n </picture>\r\n</p> -->\r\n<p align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/concept.png\" alt=\"Conceptual Diagram of VoxelCity\" width=\"800\">\r\n</p>\r\n\r\n\r\n## Key Features\r\n\r\n- **Integration of Multiple Data Sources:** \r\n Combines building footprints, land cover data, canopy height maps, and DEMs to generate a consistent 3D voxel representation of an urban scene.\r\n \r\n- **Flexible Input Sources:** \r\n Supports various building and terrain data sources including:\r\n - Building Footprints: OpenStreetMap, Overture, EUBUCCO, Microsoft Building Footprints, OpenMapTiles, Open Building 2.5D\r\n - Land Cover: UrbanWatch, OpenEarthMap Japan, ESA WorldCover, ESRI Land Cover, Dynamic World, OpenStreetMap\r\n - Canopy Height: High Resolution 1m Global Canopy Height Maps, ETH Global Sentinel-2 10m\r\n - DEM: DeltaDTM, FABDEM, NASA, COPERNICUS, and more\r\n\r\n *Detailed information about each data source can be found in the [References of Data Sources](#references-of-data-sources) section.*\r\n \r\n- **Customizable Domain and Resolution:** \r\n Easily define a target area by drawing a rectangle on a map or specifying center coordinates and dimensions. Adjust the mesh size to meet resolution needs.\r\n \r\n- **Integration with Earth Engine:** \r\n Leverages Google Earth Engine for large-scale geospatial data processing (authentication and project setup required).\r\n \r\n- **Output Formats:**\r\n - **ENVI-MET**: Export INX and EDB files suitable for ENVI-MET microclimate simulations.\r\n - **MagicaVoxel**: Export vox files for 3D editing and visualization in MagicaVoxel.\r\n - **OBJ**: Export wavefront OBJ for rendering and integration into other workflows.\r\n\r\n- **Analytical Tools:**\r\n - **View Index Simulations**: Compute sky view index (SVI) and green view index (GVI) from a specified viewpoint.\r\n - **Landmark Visibility Maps**: Assess the visibility of selected landmarks within the voxelized environment.\r\n\r\n## Installation\r\n\r\nMake sure you have Python 3.12 installed. Install VoxelCity with:\r\n\r\n### For Local Environment\r\n\r\n```bash\r\nconda create --name voxelcity python=3.12\r\nconda activate voxelcity\r\nconda install -c conda-forge gdal\r\npip install voxelcity\r\n```\r\n\r\n### For Google Colab\r\n\r\n```python\r\n!pip install voxelcity\r\n```\r\n\r\n## Setup for Earth Engine\r\n\r\nTo use Earth Engine data, set up your Earth Engine enabled Cloud Project by following the instructions here:\r\nhttps://developers.google.com/earth-engine/cloud/earthengine_cloud_project_setup\r\n\r\nAfter setting up, authenticate and initialize Earth Engine:\r\n\r\n### For Local Environment\r\n\r\n```bash\r\nearthengine authenticate\r\n```\r\n\r\n### For Google Colab\r\n\r\n```python\r\n# Click displayed link, generate token, copy and paste the token\r\n!earthengine authenticate --auth_mode=notebook\r\n```\r\n\r\n## Usage Overview\r\n\r\n### 1. Authenticate Earth Engine\r\n\r\n```python\r\nimport ee\r\nee.Authenticate()\r\nee.Initialize(project='your-project-id')\r\n```\r\n\r\n### 2. Define Target Area\r\n\r\nYou can define your target area in three ways:\r\n\r\n#### Option 1: Direct Coordinate Input\r\nDefine the target area by directly specifying the coordinates of the rectangle vertices.\r\n\r\n```python\r\nrectangle_vertices = [\r\n (47.59830044521263, -122.33587348582083), # Southwest corner (latitude, longitude)\r\n (47.60279755390168, -122.33587348582083), # Northwest corner (latitude, longitude)\r\n (47.60279755390168, -122.32922451417917), # Northeast corner (latitude, longitude)\r\n (47.59830044521263, -122.32922451417917) # Southeast corner (latitude, longitude)\r\n]\r\n```\r\n\r\n#### Option 2: Draw a Rectangle (for Jupyter Notebook)\r\nUse the GUI map interface to draw a rectangular domain of interest.\r\n\r\n```python\r\nfrom voxelcity.geo.draw import draw_rectangle_map_cityname\r\n\r\ncityname = \"tokyo\"\r\nm, rectangle_vertices = draw_rectangle_map_cityname(cityname, zoom=15)\r\nm\r\n```\r\n\r\n#### Option 3: Specify Center and Dimensions (for Jupyter Notebook)\r\nChoose the width and height in meters and select the center point on the map.\r\n\r\n```python\r\nfrom voxelcity.geo.draw import center_location_map_cityname\r\n\r\nwidth = 500\r\nheight = 500\r\nm, rectangle_vertices = center_location_map_cityname(cityname, width, height, zoom=15)\r\nm\r\n```\r\n<p align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/draw_rect.png\" alt=\"Draw Rectangle on Map GUI\" width=\"400\">\r\n</p>\r\n\r\n### 3. Set Parameters\r\n\r\nDefine data sources and mesh size (m):\r\n\r\n```python\r\nbuilding_source = 'OpenStreetMap' # Building footprint and height data source\r\nland_cover_source = 'OpenStreetMap' # Land cover classification data source\r\ncanopy_height_source = 'High Resolution 1m Global Canopy Height Maps' # Tree canopy height data source\r\ndem_source = 'DeltaDTM' # Digital elevation model data source\r\nmeshsize = 5 # Grid cell size in meters\r\n\r\nkwargs = {\r\n \"output_dir\": \"output\", # Directory to save output files\r\n \"dem_interpolation\": True # Enable DEM interpolation\r\n}\r\n```\r\n\r\n### 4. Get VoxelCity Output\r\n\r\nGenerate voxel data grids and corresponding building geoJSON:\r\n\r\n```python\r\nfrom voxelcity import get_voxelcity\r\n\r\nvoxelcity_grid, building_height_grid, building_min_height_grid, \\\r\nbuilding_id_grid, canopy_height_grid, land_cover_grid, dem_grid, \\\r\nbuilding_geojson = get_voxelcity(\r\n rectangle_vertices,\r\n building_source,\r\n land_cover_source,\r\n canopy_height_source,\r\n dem_source,\r\n meshsize,\r\n **kwargs\r\n)\r\n```\r\n\r\n### 5. Exporting Files\r\n\r\n#### ENVI-MET INX/EDB Files:\r\n[ENVI-MET](https://www.envi-met.com/) is an advanced microclimate simulation software specialized in modeling urban environments. It simulates the interactions between buildings, vegetation, and various climate parameters like temperature, wind flow, humidity, and radiation. The software is used widely in urban planning, architecture, and environmental studies (Commercial, offers educational licenses).\r\n\r\n```python\r\nfrom voxelcity.file.envimet import export_inx, generate_edb_file\r\n\r\nenvimet_kwargs = {\r\n \"output_directory\": \"output\", # Directory where output files will be saved\r\n \"author_name\": \"your name\", # Name of the model author\r\n \"model_description\": \"generated with VoxelCity\", # Description text for the model\r\n \"domain_building_max_height_ratio\": 2, # Maximum ratio between domain height and tallest building height\r\n \"useTelescoping_grid\": True, # Enable telescoping grid for better computational efficiency\r\n \"verticalStretch\": 20, # Vertical grid stretching factor (%)\r\n \"min_grids_Z\": 20, # Minimum number of vertical grid cells\r\n \"lad\": 1.0 # Leaf Area Density (m2/m3) for vegetation modeling \r\n}\r\n\r\nexport_inx(building_height_grid, building_id_grid, canopy_height_grid, land_cover_grid, dem_grid, meshsize, land_cover_source, rectangle_vertices, **envimet_kwargs)\r\ngenerate_edb_file(**envimet_kwargs)\r\n```\r\n<p align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/envimet.png\" alt=\"Generated 3D City Model on Envi-MET GUI\" width=\"600\">\r\n</p>\r\n<p align=\"center\">\r\n <em>Example Output Exported in INX and Inported in ENVI-met</em>\r\n</p>\r\n\r\n#### OBJ Files:\r\n\r\n```python\r\nfrom voxelcity.file.obj import export_obj\r\n\r\noutput_directory = \"output\" # Directory where output files will be saved\r\noutput_file_name = \"voxcity\" # Base name for the output OBJ file\r\nexport_obj(voxelcity_grid, output_directory, output_file_name, meshsize)\r\n```\r\nThe generated OBJ files can be opened and rendered in the following 3D visualization software:\r\n\r\n- [Twinmotion](https://www.twinmotion.com/): Real-time visualization tool (Free for personal use)\r\n- [Blender](https://www.blender.org/): Professional-grade 3D creation suite (Free)\r\n- [Rhino](https://www.rhino3d.com/): Professional 3D modeling software (Commercial, offers educational licenses)\r\n\r\n<p align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/obj.png\" alt=\"OBJ 3D City Model Rendered in Rhino\" width=\"600\">\r\n</p>\r\n<p align=\"center\">\r\n <em>Example Output Exported in OBJ and Rendered in MagicaVoxel</em>\r\n</p>\r\n\r\n#### MagicaVoxel VOX Files:\r\n\r\n[MagicaVoxel](https://ephtracy.github.io/) is a lightweight and user-friendly voxel art editor. It allows users to create, edit, and render voxel-based 3D models with an intuitive interface, making it perfect for modifying and visualizing voxelized city models. The software is free and available for Windows and Mac.\r\n\r\n```python\r\nfrom voxelcity.file.magicavoxel import export_magicavoxel_vox\r\n\r\noutput_path = \"output\"\r\nbase_filename = \"voxelcity\"\r\nexport_magicavoxel_vox(voxelcity_grid, output_path, base_filename=base_filename)\r\n```\r\n<p align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/vox.png\" alt=\"Generated 3D City Model on MagicaVoxel GUI\" width=\"600\">\r\n</p>\r\n<p align=\"center\">\r\n <em>Example Output Exported in VOX and Rendered in MagicaVoxel</em>\r\n</p>\r\n\r\n### 6. Additional Use Cases\r\n\r\n#### Compute Green View Index (GVI) and Sky View Index (SVI):\r\n\r\n```python\r\nfrom voxelcity.sim.view import get_green_view_index, get_sky_view_index\r\n\r\n# Dictionary of parameters for view index analysis\r\nview_kwargs = {\r\n \"view_point_height\": 1.5, # Height of observer viewpoint in meters\r\n \"dem_grid\": dem_grid, # Digital elevation model grid\r\n \"colormap\": \"viridis\", # Colormap for visualization\r\n \"obj_export\": True, # Whether to export as OBJ file\r\n \"output_directory\": \"output\", # Directory to save output files\r\n \"output_file_name\": \"gvi\" # Base filename for outputs\r\n}\r\ngvi_grid = get_green_view_index(voxelcity_grid, meshsize, **view_kwargs)\r\n\r\nview_kwargs[\"colormap\"] = \"BuPu_r\"\r\nview_kwargs[\"output_file_name\"] = \"svi\"\r\nsvi_grid = get_sky_view_index(voxelcity_grid, meshsize, **view_kwargs)\r\n```\r\n<p align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/view_index.png\" alt=\"View Index Maps Rendered in Rhino\" width=\"800\">\r\n</p>\r\n<p align=\"center\">\r\n <em>Example Results Saved as OBJ and Rendered in Rhino</em>\r\n</p>\r\n\r\n#### Landmark Visibility Map:\r\n\r\n```python\r\nfrom voxelcity.sim.view import get_landmark_visibility_map\r\n\r\n# Dictionary of parameters for landmark visibility analysis\r\nlandmark_kwargs = {\r\n \"view_point_height\": 1.5, # Height of observer viewpoint in meters\r\n \"rectangle_vertices\": rectangle_vertices, # Vertices defining simulation domain boundary\r\n \"dem_grid\": dem_grid, # Digital elevation model grid\r\n \"colormap\": \"cool\", # Colormap for visualization\r\n \"obj_export\": True, # Whether to export as OBJ file\r\n \"output_directory\": \"output\", # Directory to save output files\r\n \"output_file_name\": \"landmark_visibility\" # Base filename for outputs\r\n}\r\nlandmark_vis_map = get_landmark_visibility_map(voxelcity_grid, building_id_grid, building_geojson, meshsize, **landmark_kwargs)\r\n```\r\n<p align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/kunifujiwara/VoxCity/main/images/landmark.png\" alt=\"Landmark Visibility Map Rendered in Rhino\" width=\"500\">\r\n</p>\r\n<p align=\"center\">\r\n <em>Example Result Saved as OBJ and Rendered in Rhino</em>\r\n</p>\r\n\r\n## References of Data Sources\r\n\r\n### Building \r\n\r\n| Dataset | Spatial Coverage | Source/Data Acquisition |\r\n|---------|------------------|------------------------|\r\n| [OpenStreetMap](https://www.openstreetmap.org) | Worldwide (24% completeness in city centers) | Volunteered / updated continuously |\r\n| [Global ML Building Footprints](https://github.com/microsoft/GlobalMLBuildingFootprints) | North America, Europe, Australia | Prediction from satellite or aerial imagery / 2018-2019 for majority of the input imagery |\r\n| [Open Buildings 2.5D Temporal Dataset](https://sites.research.google/gr/open-buildings/temporal/) | Africa, Latin America, and South and Southeast Asia | Prediction from satellite imagery / 2016-2023 |\r\n| [EUBUCCO v0.1](https://eubucco.com/) | 27 EU countries and Switzerland (378 regions and 40,829 cities) | OpenStreetMap, government datasets / 2003-2021 (majority is after 2019) |\r\n| [UT-GLOBUS](https://zenodo.org/records/11156602) | Worldwide (more than 1200 cities or locales) | Prediction from building footprints, population, spaceborne nDSM / not provided |\r\n| [Overture Maps](https://overturemaps.org/) | Worldwide | OpenStreetMap, Esri Community Maps Program, Google Open Buildings, etc. / updated continuously |\r\n\r\n### Tree Canopy Height\r\n\r\n| Dataset | Coverage | Resolution | Source/Data Acquisition |\r\n|---------|-----------|------------|------------------------|\r\n| [High Resolution 1m Global Canopy Height Maps](https://sustainability.atmeta.com/blog/2024/04/22/using-artificial-intelligence-to-map-the-earths-forests/) | Worldwide | 1 m | Prediction from satellite imagery / 2009 and 2020 (80% are 2018-2020) |\r\n| [ETH Global Sentinel-2 10m Canopy Height (2020)](https://langnico.github.io/globalcanopyheight/) | Worldwide | 10 m | Prediction from satellite imagery / 2020 |\r\n\r\n### Land Cover\r\n\r\n| Dataset | Spatial Coverage | Resolution | Source/Data Acquisition |\r\n|---------|------------------|------------|----------------------|\r\n| [ESA World Cover 10m 2021 V200](https://zenodo.org/records/7254221) | Worldwide | 10 m | Prediction from satellite imagery / 2021 |\r\n| [ESRI 10m Annual Land Cover (2017-2023)](https://www.arcgis.com/home/item.html?id=cfcb7609de5f478eb7666240902d4d3d) | Worldwide | 10 m | Prediction from satellite imagery / 2017-2023 |\r\n| [Dynamic World V1](https://dynamicworld.app) | Worldwide | 10 m | Prediction from satellite imagery / updated continuously |\r\n| [OpenStreetMap](https://www.openstreetmap.org) | Worldwide | - (Vector) | Volunteered / updated continuously |\r\n| [OpenEarthMap Japan](https://www.open-earth-map.org/demo/Japan/leaflet.html) | Japan | ~1 m | Prediction from aerial imagery / 1974-2022 (mostly after 2018 in major cities) |\r\n| [UrbanWatch](https://urbanwatch.charlotte.edu/) | 22 major cities in the US | 1 m | Prediction from aerial imagery / 2014\u20132017 |\r\n\r\n### Terrain Elevation\r\n\r\n| Dataset | Coverage | Resolution | Source/Data Acquisition |\r\n|---------|-----------|------------|------------------------|\r\n| [FABDEM](https://doi.org/10.5523/bris.25wfy0f9ukoge2gs7a5mqpq2j7) | Worldwide | 30 m | Correction of Copernicus DEM using canopy height and building footprints data / 2011-2015 (Copernicus DEM) |\r\n| [DeltaDTM](https://gee-community-catalog.org/projects/delta_dtm/) | Worldwide (Only for coastal areas below 10m + mean sea level) | 30 m | Copernicus DEM, spaceborne LiDAR / 2011-2015 (Copernicus DEM) |\r\n| [USGS 3DEP 1m DEM](https://www.usgs.gov/3d-elevation-program) | United States | 1 m | Aerial LiDAR / 2004-2024 (mostly after 2015) |\r\n| [England 1m Composite DTM](https://environment.data.gov.uk/dataset/13787b9a-26a4-4775-8523-806d13af58fc) | England | 1 m | Aerial LiDAR / 2000-2022 |\r\n| [Australian 5M DEM](https://ecat.ga.gov.au/geonetwork/srv/eng/catalog.search#/metadata/89644) | Australia | 5 m | Aerial LiDAR / 2001-2015 |\r\n| [RGE Alti](https://geoservices.ign.fr/rgealti) | France | 1 m | Aerial LiDAR |\r\n\r\n\r\n## Citation\r\n\r\nPlease cite the [paper](https://doi.org) if you use `voxelcity` in a scientific publication:\r\n\r\nFujiwara, K., XXX. XXX. XXX, XXX, XXX.\r\n\r\n```bibtex\r\n@article{,\r\n author = {Fujiwara, Kunihiko and XXX, XXX and XXX, XXX and XXX, XXX},\r\n doi = {XXX},\r\n journal = {XXX},\r\n pages = {XXX},\r\n title = {XXX},\r\n volume = {XXX},\r\n year = {XXX}\r\n}\r\n```\r\n\r\n## Credit\r\n\r\nThis package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [`audreyr/cookiecutter-pypackage`](https://github.com/audreyr/cookiecutter-pypackage) project template.\r\n\r\n--------------------------------------------------------------------------------\r\n<br>\r\n<br>\r\n<p align=\"center\">\r\n <a href=\"https://ual.sg/\">\r\n <img src=\"https://raw.githubusercontent.com/winstonyym/urbanity/main/images/ualsg.jpeg\" width = 55% alt=\"Logo\">\r\n </a>\r\n</p>\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "voxelcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data",
"version": "0.1.81",
"project_urls": {
"bugs": "https://github.com/kunifujiwara/voxelcity/issues",
"changelog": "https://github.com/kunifujiwara/voxelcity/blob/master/changelog.md",
"homepage": "https://github.com/kunifujiwara/voxelcity"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12ce78cc2ef738a93a8d75d50ab584ebc7775c0f0fe8210e45db1f030f9ff53f",
"md5": "e1cde1371d9846bead8c74fdba0fe8c7",
"sha256": "aa1a0b18e37380f8f155fcaac1df809c47cda423bf4bee091b1d277144d3889a"
},
"downloads": -1,
"filename": "voxelcity-0.1.81-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e1cde1371d9846bead8c74fdba0fe8c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 96159,
"upload_time": "2024-12-15T05:36:41",
"upload_time_iso_8601": "2024-12-15T05:36:41.797725Z",
"url": "https://files.pythonhosted.org/packages/12/ce/78cc2ef738a93a8d75d50ab584ebc7775c0f0fe8210e45db1f030f9ff53f/voxelcity-0.1.81-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c904fb0c8b8aebe82516dccebb30239a97e27dea892d48ad5c0e697a6359e4ba",
"md5": "580b02cd0a4787a7ec9ed6f28a4c926d",
"sha256": "7e5297e50dff4192906df80cb68811e1b6355a030d9db70b88226b8ee0a66d05"
},
"downloads": -1,
"filename": "voxelcity-0.1.81.tar.gz",
"has_sig": false,
"md5_digest": "580b02cd0a4787a7ec9ed6f28a4c926d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 99279,
"upload_time": "2024-12-15T05:36:49",
"upload_time_iso_8601": "2024-12-15T05:36:49.666388Z",
"url": "https://files.pythonhosted.org/packages/c9/04/fb0c8b8aebe82516dccebb30239a97e27dea892d48ad5c0e697a6359e4ba/voxelcity-0.1.81.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 05:36:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kunifujiwara",
"github_project": "voxelcity",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "voxelcity"
}
