zero2geospatial3d-sdk 0.1.0__tar.gz

zero2geospatial3d_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-08
+### Added
+- First release: a headless, numpy-only Python port of the 02 Geo3D Analyzer QGIS plugin
+  (`zero2geospatial3d`).
+- `grid.Grid`: north-up raster in local metres with bilinear sampling, shared by every module.
+- `scene`: `Scene`, `Building`, `Tree` and `Road`; footprint rasterisation into a height surface
+  and building-id grid; read and write the plugin's scene package (`scene.json`, `terrain.bin`,
+  `L*.geojson`) so scenes move freely between the plugin, the SDK and the viewer.
+- `solar`: NOAA sun position, sunrise and sunset, sun paths and Fibonacci sky sampling.
+- `shading`: shadow masks, sun hours, shadow studies, horizon angles, sky view factor,
+  viewshed, direct + diffuse + reflected solar irradiation and rooftop PV yield on a 2.5-D
+  height field (the plugin computes these on the GPU).
+- `comfort`: UTCI (Bröde et al. 2012 polynomial), PET, mean radiant temperature, sky
+  temperature and the comfort categories.
+- `weather` and `epw`: EPW parsing, monthly summaries, wind roses, an ASHRAE clear-sky year,
+  annual sun-direction bins, and nearest-station lookup in a bundled index of about 17,000
+  TMYx stations, with downloads from climate.onebuilding.org.
+- `microclimate`: surface temperature (energy balance with Bowen ratio), canopy
+  transmittance, downwind evapotranspiration cooling and 24-hour diurnal profiles.
+- `wind` and `morphology`: pedestrian wind ratio with wakes, Lawson classes, distance to
+  buildings, Macdonald roughness, block indicators and Local Climate Zones.
+- `dispersion` and `acoustics`: street-canyon ventilation efficiency and air age, traffic
+  NO2/PM2.5 dispersion with tree filtration, Maekawa barrier diffraction, noise propagation and
+  quiet-facade detection, plus road and street-centreline sources (`road_sources`).
+- `daylight`: BRE 209 25-degree and Vertical Sky Component rules with party-wall handling.
+- `urban_form`: panoramic Green View Index and solar envelopes.
+- `walkability`: pedestrian walkability index and cool-route search.
+- `terrain`: slope and aspect, hillshade, contours, profiles (sections), bathtub and seeded
+  flooding, cut/fill with balanced level, curvature, TPI, TRI, aspect classes, flow
+  accumulation and topographic wetness.
+- `classify` (equal, quantile and Jenks breaks, colour ramps) and `nsga2` (seeded,
+  deterministic NSGA-II).
+- `osm` and `osm_tags`: Overpass download with mirror fail-over, timeouts and a one-week cache,
+  and Simple 3D Buildings height rules.
+- `results`: per-building aggregation, ESRI ASCII / `.npy` / GeoTIFF output and viewer
+  payload decoding.
+- `server`: the plugin's browser viewer (three.js r160) bundled as package data, served on
+  127.0.0.1 with results posted back to disk.
+- Command line `zero2geospatial3d` with `sun`, `stations`, `epw`, `comfort`, `osm`, `demo`,
+  `analyze` and `view`.
+- Test suite reproducing the numeric assertions of the plugin's JavaScript tests.

zero2geospatial3d_sdk-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "yusufeminoglu@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "zero2geospatial3d-sdk"
+version: "0.1.0"
+date-released: "2026-11-08"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/zero2geospatial3d_sdk"
+url: "https://pypi.org/project/zero2geospatial3d-sdk/"
+abstract: "Headless 3D terrain and building analysis in Python: sun hours, shadows, sky view factor, solar PV, UTCI/PET thermal comfort, wind, noise and air-quality screening, daylight rules, terrain sections, flooding and cut/fill. A numpy port of the 02 Geo3D Analyzer (zero2geospatial3d) QGIS plugin."
+keywords:
+  - gis
+  - urban climate
+  - solar
+  - thermal comfort
+  - terrain analysis

zero2geospatial3d_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoglu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zero2geospatial3d_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include LICENSE
+include THIRD_PARTY_NOTICES.md
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/zero2geospatial3d/py.typed
+recursive-include src/zero2geospatial3d *.py
+include src/zero2geospatial3d/data/epw_stations.json.gz
+recursive-include src/zero2geospatial3d/web *.html *.js *.css
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod]

zero2geospatial3d_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: zero2geospatial3d-sdk
+Version: 0.1.0
+Summary: Headless 3D urban and terrain analysis in Python: sun hours, shadows, sky view factor, solar PV, UTCI/PET comfort, noise, dispersion, flooding and cut/fill.
+Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://geophilo.com/
+Project-URL: Repository, https://github.com/YusufEminoglu/zero2geospatial3d_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/zero2geospatial3d_sdk/issues
+Project-URL: Documentation, https://github.com/YusufEminoglu/zero2geospatial3d_sdk#readme
+Project-URL: Changelog, https://github.com/YusufEminoglu/zero2geospatial3d_sdk/blob/main/CHANGELOG.md
+Project-URL: QGIS plugin, https://github.com/YusufEminoglu/zero2geospatial3d
+Keywords: gis,3d,urban-planning,urban-climate,solar,sun-hours,shadow,sky-view-factor,photovoltaic,daylight,bre-209,utci,pet,thermal-comfort,microclimate,wind-comfort,noise,air-quality,viewshed,terrain,dem,flood,cut-and-fill,epw,openstreetmap,walkability
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: geo
+Requires-Dist: shapely>=2.0.0; extra == "geo"
+Requires-Dist: rasterio>=1.3.0; extra == "geo"
+Requires-Dist: pyproj>=3.3.0; extra == "geo"
+Requires-Dist: matplotlib>=3.5.0; extra == "geo"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# zero2geospatial3d-sdk
+
+[![PyPI version](https://img.shields.io/pypi/v/zero2geospatial3d-sdk.svg?color=10b981)](https://pypi.org/project/zero2geospatial3d-sdk/)
+[![Python version support](https://img.shields.io/pypi/pyversions/zero2geospatial3d-sdk.svg?color=3b82f6)](https://pypi.org/project/zero2geospatial3d-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/YusufEminoglu/zero2geospatial3d_sdk/blob/main/LICENSE)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-D7FF64.svg)](https://docs.astral.sh/ruff/)
+[![Test Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](#development-and-testing)
+
+**Headless 3D terrain and building analysis in Python: sun hours, shadows, sky view factor, solar PV, UTCI/PET comfort, wind, noise and air-quality screening, daylight rules, terrain sections, flooding and cut/fill.**
+
+[PyPI Package](https://pypi.org/project/zero2geospatial3d-sdk/) • [GitHub](https://github.com/YusufEminoglu/zero2geospatial3d_sdk) • [Issue Tracker](https://github.com/YusufEminoglu/zero2geospatial3d_sdk/issues) • [QGIS plugin](https://github.com/YusufEminoglu/zero2geospatial3d)
+
+</div>
+
+`zero2geospatial3d-sdk` is the scriptable, QGIS-free engine behind the
+**02 Geo3D Analyzer** QGIS plugin (`zero2geospatial3d`). The plugin runs its
+analyses on the GPU in a browser; this package ports the same mathematics to
+NumPy so they run in notebooks, batch jobs, servers and CI pipelines. Scene
+packages are interchangeable: a scene exported by the plugin loads in Python,
+and a scene built in Python opens in the bundled browser viewer.
+
+## Installation
+
+```bash
+# Core: NumPy only
+pip install zero2geospatial3d-sdk
+
+# Optional geospatial extras (GeoTIFF output with rasterio, pyproj, shapely, matplotlib)
+pip install "zero2geospatial3d-sdk[geo]"
+```
+
+Python 3.9 to 3.13. The import name is `zero2geospatial3d`.
+
+## Quickstart (runs offline)
+
+```python
+import numpy as np
+from zero2geospatial3d import Building, Scene, shading, comfort, terrain
+from zero2geospatial3d.results import aggregate_by_id
+
+# A 200 m x 200 m level site in Izmir (UTC+3) with a 2 m grid and two buildings.
+scene = Scene.flat(200, 200, cell=2.0, lat=38.42, lon=27.14, utc_offset=3.0)
+for cx, h in ((-30, 24.0), (30, 12.0)):
+    ring = [[cx - 15, -10], [cx + 15, -10], [cx + 15, 10], [cx - 15, 10], [cx - 15, -10]]
+    scene.buildings.append(Building([[ring]], height=h))
+
+surface = scene.surface()                     # terrain + buildings as a Grid
+_, ids = scene.building_rasters()             # building id per cell (0 = ground)
+
+# BRE 209: sun hours on 21 March
+hours = shading.sun_hours(surface, scene.lat, scene.lon, scene.utc_offset, month=3, day=21)
+open_ground = hours[ids == 0]
+print(f"open ground with >= 2 h of sun: {100 * np.mean(open_ground >= 2):.0f} %")
+
+# Sky view factor and per-building roof statistics
+svf = shading.sky_view_factor(surface, n_azimuths=16)
+print(aggregate_by_id(ids, svf, cell_area=4.0)[1]["mean"])
+
+# Thermal comfort for one set of conditions
+print(comfort.utci(32.0, 55.0, 1.5, 40.0), comfort.pet(32.0, 55.0, 1.5, 40.0))
+
+# Terrain: slope, flooding and earthworks on the DEM
+slope, aspect = terrain.slope_aspect(scene.terrain)
+pad = [[-20, -20], [20, -20], [20, 20], [-20, 20], [-20, -20]]
+print(terrain.cut_fill(scene.terrain, pad, design_level=0.5).fill)
+```
+
+## Command line
+
+```bash
+zero2geospatial3d sun --lat 38.42 --lon 27.14 --date 2026-06-21 --tz 3
+zero2geospatial3d comfort --ta 32 --tr 55 --v 1.5 --rh 40
+zero2geospatial3d stations --lat 41.01 --lon 28.97 -n 3          # nearest TMYx stations
+zero2geospatial3d epw --lat 41.01 --lon 28.97 --out istanbul.epw   # download the nearest one
+
+zero2geospatial3d demo --out demo_scene                            # synthetic scene package
+zero2geospatial3d osm --lat 38.4237 --lon 27.1428 --half-size 250 --out izmir_scene
+zero2geospatial3d analyze demo_scene sun-hours --date 2026-03-21 --out sun.asc
+zero2geospatial3d analyze demo_scene svf --azimuths 36 --out svf.npy
+zero2geospatial3d analyze demo_scene irradiation --epw istanbul.epw --out kwh.tif   # .tif needs [geo]
+zero2geospatial3d analyze demo_scene flood --level 12 --out depth.asc
+zero2geospatial3d view demo_scene --results results/                 # bundled 3D viewer
+```
+
+`analyze` supports `sun-hours`, `shadow`, `svf`, `viewshed`, `irradiation`,
+`slope`, `aspect`, `hillshade` and `flood`, and prints summary statistics as
+JSON. `view` serves the plugin's three.js viewer on `127.0.0.1` (your data
+stays on your computer); results sent from the viewer are saved to `--results`.
+
+## How the 3D analyses work headlessly
+
+The plugin renders depth maps of the full 3D scene on the GPU. The SDK works on
+a 2.5-D **surface**: the DEM plus the heights of buildings (and optionally tree
+crowns) rasterised onto the same grid. Sun visibility is tested by marching
+rays across this surface with bilinear sampling, the sky view factor is
+`1 - mean(sin^2(horizon))` over azimuth sectors, and irradiation combines
+direct sun (from EPW or clear-sky sun-direction bins), isotropic diffuse sky
+and ground reflection, exactly as the plugin's `solarRadiation` runner does.
+Overhangs and facade receivers are not represented in 2.5-D.
+
+## Public API
+
+| Module | Main contents |
+|---|---|
+| `grid` | `Grid` (values, cell, min_x, max_y; `sample`, `coords`, `index_of`), `make_grid` |
+| `scene` | `Scene` (`flat`, `from_osm`, `surface`, `building_rasters`, `tree_raster`, `export`), `Building`, `Tree`, `Road`, `load_scene`, `rasterize_polygons` |
+| `solar` | `solar_position`, `sunrise_sunset`, `sun_path`, `sky_hemisphere`, `sun_vector`, `day_of_year` |
+| `shading` | `shadow_mask`, `sun_hours`, `shadow_study`, `horizon_angles`, `sky_view_factor`, `viewshed`, `directional_irradiation`, `solar_irradiation`, `pv_yield` |
+| `comfort` | `utci`, `pet`, `mean_radiant_temperature`, `sky_temperature`, `projected_area_factor`, `utci_category`, `pet_category` |
+| `weather` | `Weather`, `parse_epw`, `read_epw`, `monthly_summary`, `wind_rose`, `clear_sky_year`, `annual_sun_bins`, `conditions_at`, `typical_doy` |
+| `epw` | `nearest_stations`, `load_index`, `download_station`, `extract_epw`, `read_header` |
+| `microclimate` | `surface_temperature`, `canopy_transmittance`, `canopy_cooling_grid`, `diurnal_point_profile`, `SURFACE_MATERIALS` |
+| `wind` | `wind_ratio`, `lawson_class`, `OPEN_PEDESTRIAN_FACTOR` |
+| `morphology` | `distance_to_built`, `macdonald`, `classify_lcz`, `block_indicators` |
+| `dispersion` | `ventilation_efficiency`, `pollutant_dispersion`, `ventilation_class`, `air_quality_class` |
+| `acoustics` | `noise_propagation`, `building_facade_noise`, `maekawa_diffraction`, `noise_class` |
+| `road_sources` | `sample_road_lines`, `street_centrelines`, `road_weight` |
+| `daylight` | `prepare_rule`, `check_rule`, `vsc_long`, `allowed_angle`, `reach25`, `wall_samples` (BRE 209) |
+| `urban_form` | `green_view_index`, `solar_envelope`, `gvi_class` |
+| `walkability` | `pedestrian_walkability_index`, `find_cool_route`, subscores |
+| `terrain` | `slope_aspect`, `hillshade`, `contours`, `profile`, `flood`, `cut_fill`, `balanced_level`, `curvature`, `tpi`, `ruggedness`, `aspect_classes`, `flow_accumulation`, `wetness`, `crop_grid` |
+| `classify` | `equal_breaks`, `quantile_breaks`, `jenks_breaks`, `ramp_stops`, `ramp_color`, `RAMPS` |
+| `nsga2` | `Problem`, `nsga2`, `dominates`, `non_dominated_sort`, `crowding_distance` |
+| `osm`, `osm_tags` | `fetch` (Overpass, timeouts, cache), `payload_to_features`, `building_height`, `road_traffic` |
+| `geo` | `lonlat_to_local`, `local_to_lonlat`, `bbox_around`, `utm_epsg_for`, `grid_shape` |
+| `results` | `aggregate_by_id`, `grid_stats`, `write_ascii_grid`, `write_grid_npy`, `write_geotiff`, `save_result` |
+| `server` | `serve_scene`, `ViewerServer`, `viewer_root` |
+
+All grids are NumPy arrays of shape `(rows, cols)` with row 0 at the north
+edge; coordinates are local metres (x east, y north). Angles from `solar` are
+radians with azimuth clockwise from north.
+
+## Validation
+
+The test suite reproduces the numeric assertions of the plugin's JavaScript
+tests (`tests/js/*.test.mjs`): the NREL SPA reference sun position, UTCI and
+PET reference values, EPW parsing and wind roses, surface energy balance and
+canopy cooling, Maekawa diffraction and traffic-noise scaling, ventilation and
+dispersion, BRE 209 VSC closed forms, solar envelopes and green view, terrain
+curvature, TPI, TRI, flow accumulation and wetness, flood and cut/fill
+volumes, Jenks breaks, and the seeded NSGA-II run. The shading engines are
+checked against closed forms (canyon sky view factor, wall shadow length).
+
+## Development and testing
+
+```bash
+git clone https://github.com/YusufEminoglu/zero2geospatial3d_sdk.git
+cd zero2geospatial3d_sdk
+pip install -e ".[dev]"
+python -m pytest --cov=zero2geospatial3d
+python -m ruff check .
+python -m mypy src
+```
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_zero2geospatial3d_sdk,
+  author  = {Eminoğlu, Yusuf},
+  title   = {zero2geospatial3d-sdk: headless 3D terrain and building analysis in Python},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/zero2geospatial3d_sdk}
+}
+```
+
+See also `CITATION.cff`.
+
+## License
+
+MIT, see [LICENSE](LICENSE). The bundled viewer includes three.js (MIT) and the
+UTCI polynomial follows pythermalcomfort (MIT); the station index credits
+Climate.OneBuilding.Org. Details in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

zero2geospatial3d_sdk-0.1.0/README.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# zero2geospatial3d-sdk
+
+[![PyPI version](https://img.shields.io/pypi/v/zero2geospatial3d-sdk.svg?color=10b981)](https://pypi.org/project/zero2geospatial3d-sdk/)
+[![Python version support](https://img.shields.io/pypi/pyversions/zero2geospatial3d-sdk.svg?color=3b82f6)](https://pypi.org/project/zero2geospatial3d-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/YusufEminoglu/zero2geospatial3d_sdk/blob/main/LICENSE)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-D7FF64.svg)](https://docs.astral.sh/ruff/)
+[![Test Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](#development-and-testing)
+
+**Headless 3D terrain and building analysis in Python: sun hours, shadows, sky view factor, solar PV, UTCI/PET comfort, wind, noise and air-quality screening, daylight rules, terrain sections, flooding and cut/fill.**
+
+[PyPI Package](https://pypi.org/project/zero2geospatial3d-sdk/) • [GitHub](https://github.com/YusufEminoglu/zero2geospatial3d_sdk) • [Issue Tracker](https://github.com/YusufEminoglu/zero2geospatial3d_sdk/issues) • [QGIS plugin](https://github.com/YusufEminoglu/zero2geospatial3d)
+
+</div>
+
+`zero2geospatial3d-sdk` is the scriptable, QGIS-free engine behind the
+**02 Geo3D Analyzer** QGIS plugin (`zero2geospatial3d`). The plugin runs its
+analyses on the GPU in a browser; this package ports the same mathematics to
+NumPy so they run in notebooks, batch jobs, servers and CI pipelines. Scene
+packages are interchangeable: a scene exported by the plugin loads in Python,
+and a scene built in Python opens in the bundled browser viewer.
+
+## Installation
+
+```bash
+# Core: NumPy only
+pip install zero2geospatial3d-sdk
+
+# Optional geospatial extras (GeoTIFF output with rasterio, pyproj, shapely, matplotlib)
+pip install "zero2geospatial3d-sdk[geo]"
+```
+
+Python 3.9 to 3.13. The import name is `zero2geospatial3d`.
+
+## Quickstart (runs offline)
+
+```python
+import numpy as np
+from zero2geospatial3d import Building, Scene, shading, comfort, terrain
+from zero2geospatial3d.results import aggregate_by_id
+
+# A 200 m x 200 m level site in Izmir (UTC+3) with a 2 m grid and two buildings.
+scene = Scene.flat(200, 200, cell=2.0, lat=38.42, lon=27.14, utc_offset=3.0)
+for cx, h in ((-30, 24.0), (30, 12.0)):
+    ring = [[cx - 15, -10], [cx + 15, -10], [cx + 15, 10], [cx - 15, 10], [cx - 15, -10]]
+    scene.buildings.append(Building([[ring]], height=h))
+
+surface = scene.surface()                     # terrain + buildings as a Grid
+_, ids = scene.building_rasters()             # building id per cell (0 = ground)
+
+# BRE 209: sun hours on 21 March
+hours = shading.sun_hours(surface, scene.lat, scene.lon, scene.utc_offset, month=3, day=21)
+open_ground = hours[ids == 0]
+print(f"open ground with >= 2 h of sun: {100 * np.mean(open_ground >= 2):.0f} %")
+
+# Sky view factor and per-building roof statistics
+svf = shading.sky_view_factor(surface, n_azimuths=16)
+print(aggregate_by_id(ids, svf, cell_area=4.0)[1]["mean"])
+
+# Thermal comfort for one set of conditions
+print(comfort.utci(32.0, 55.0, 1.5, 40.0), comfort.pet(32.0, 55.0, 1.5, 40.0))
+
+# Terrain: slope, flooding and earthworks on the DEM
+slope, aspect = terrain.slope_aspect(scene.terrain)
+pad = [[-20, -20], [20, -20], [20, 20], [-20, 20], [-20, -20]]
+print(terrain.cut_fill(scene.terrain, pad, design_level=0.5).fill)
+```
+
+## Command line
+
+```bash
+zero2geospatial3d sun --lat 38.42 --lon 27.14 --date 2026-06-21 --tz 3
+zero2geospatial3d comfort --ta 32 --tr 55 --v 1.5 --rh 40
+zero2geospatial3d stations --lat 41.01 --lon 28.97 -n 3          # nearest TMYx stations
+zero2geospatial3d epw --lat 41.01 --lon 28.97 --out istanbul.epw   # download the nearest one
+
+zero2geospatial3d demo --out demo_scene                            # synthetic scene package
+zero2geospatial3d osm --lat 38.4237 --lon 27.1428 --half-size 250 --out izmir_scene
+zero2geospatial3d analyze demo_scene sun-hours --date 2026-03-21 --out sun.asc
+zero2geospatial3d analyze demo_scene svf --azimuths 36 --out svf.npy
+zero2geospatial3d analyze demo_scene irradiation --epw istanbul.epw --out kwh.tif   # .tif needs [geo]
+zero2geospatial3d analyze demo_scene flood --level 12 --out depth.asc
+zero2geospatial3d view demo_scene --results results/                 # bundled 3D viewer
+```
+
+`analyze` supports `sun-hours`, `shadow`, `svf`, `viewshed`, `irradiation`,
+`slope`, `aspect`, `hillshade` and `flood`, and prints summary statistics as
+JSON. `view` serves the plugin's three.js viewer on `127.0.0.1` (your data
+stays on your computer); results sent from the viewer are saved to `--results`.
+
+## How the 3D analyses work headlessly
+
+The plugin renders depth maps of the full 3D scene on the GPU. The SDK works on
+a 2.5-D **surface**: the DEM plus the heights of buildings (and optionally tree
+crowns) rasterised onto the same grid. Sun visibility is tested by marching
+rays across this surface with bilinear sampling, the sky view factor is
+`1 - mean(sin^2(horizon))` over azimuth sectors, and irradiation combines
+direct sun (from EPW or clear-sky sun-direction bins), isotropic diffuse sky
+and ground reflection, exactly as the plugin's `solarRadiation` runner does.
+Overhangs and facade receivers are not represented in 2.5-D.
+
+## Public API
+
+| Module | Main contents |
+|---|---|
+| `grid` | `Grid` (values, cell, min_x, max_y; `sample`, `coords`, `index_of`), `make_grid` |
+| `scene` | `Scene` (`flat`, `from_osm`, `surface`, `building_rasters`, `tree_raster`, `export`), `Building`, `Tree`, `Road`, `load_scene`, `rasterize_polygons` |
+| `solar` | `solar_position`, `sunrise_sunset`, `sun_path`, `sky_hemisphere`, `sun_vector`, `day_of_year` |
+| `shading` | `shadow_mask`, `sun_hours`, `shadow_study`, `horizon_angles`, `sky_view_factor`, `viewshed`, `directional_irradiation`, `solar_irradiation`, `pv_yield` |
+| `comfort` | `utci`, `pet`, `mean_radiant_temperature`, `sky_temperature`, `projected_area_factor`, `utci_category`, `pet_category` |
+| `weather` | `Weather`, `parse_epw`, `read_epw`, `monthly_summary`, `wind_rose`, `clear_sky_year`, `annual_sun_bins`, `conditions_at`, `typical_doy` |
+| `epw` | `nearest_stations`, `load_index`, `download_station`, `extract_epw`, `read_header` |
+| `microclimate` | `surface_temperature`, `canopy_transmittance`, `canopy_cooling_grid`, `diurnal_point_profile`, `SURFACE_MATERIALS` |
+| `wind` | `wind_ratio`, `lawson_class`, `OPEN_PEDESTRIAN_FACTOR` |
+| `morphology` | `distance_to_built`, `macdonald`, `classify_lcz`, `block_indicators` |
+| `dispersion` | `ventilation_efficiency`, `pollutant_dispersion`, `ventilation_class`, `air_quality_class` |
+| `acoustics` | `noise_propagation`, `building_facade_noise`, `maekawa_diffraction`, `noise_class` |
+| `road_sources` | `sample_road_lines`, `street_centrelines`, `road_weight` |
+| `daylight` | `prepare_rule`, `check_rule`, `vsc_long`, `allowed_angle`, `reach25`, `wall_samples` (BRE 209) |
+| `urban_form` | `green_view_index`, `solar_envelope`, `gvi_class` |
+| `walkability` | `pedestrian_walkability_index`, `find_cool_route`, subscores |
+| `terrain` | `slope_aspect`, `hillshade`, `contours`, `profile`, `flood`, `cut_fill`, `balanced_level`, `curvature`, `tpi`, `ruggedness`, `aspect_classes`, `flow_accumulation`, `wetness`, `crop_grid` |
+| `classify` | `equal_breaks`, `quantile_breaks`, `jenks_breaks`, `ramp_stops`, `ramp_color`, `RAMPS` |
+| `nsga2` | `Problem`, `nsga2`, `dominates`, `non_dominated_sort`, `crowding_distance` |
+| `osm`, `osm_tags` | `fetch` (Overpass, timeouts, cache), `payload_to_features`, `building_height`, `road_traffic` |
+| `geo` | `lonlat_to_local`, `local_to_lonlat`, `bbox_around`, `utm_epsg_for`, `grid_shape` |
+| `results` | `aggregate_by_id`, `grid_stats`, `write_ascii_grid`, `write_grid_npy`, `write_geotiff`, `save_result` |
+| `server` | `serve_scene`, `ViewerServer`, `viewer_root` |
+
+All grids are NumPy arrays of shape `(rows, cols)` with row 0 at the north
+edge; coordinates are local metres (x east, y north). Angles from `solar` are
+radians with azimuth clockwise from north.
+
+## Validation
+
+The test suite reproduces the numeric assertions of the plugin's JavaScript
+tests (`tests/js/*.test.mjs`): the NREL SPA reference sun position, UTCI and
+PET reference values, EPW parsing and wind roses, surface energy balance and
+canopy cooling, Maekawa diffraction and traffic-noise scaling, ventilation and
+dispersion, BRE 209 VSC closed forms, solar envelopes and green view, terrain
+curvature, TPI, TRI, flow accumulation and wetness, flood and cut/fill
+volumes, Jenks breaks, and the seeded NSGA-II run. The shading engines are
+checked against closed forms (canyon sky view factor, wall shadow length).
+
+## Development and testing
+
+```bash
+git clone https://github.com/YusufEminoglu/zero2geospatial3d_sdk.git
+cd zero2geospatial3d_sdk
+pip install -e ".[dev]"
+python -m pytest --cov=zero2geospatial3d
+python -m ruff check .
+python -m mypy src
+```
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_zero2geospatial3d_sdk,
+  author  = {Eminoğlu, Yusuf},
+  title   = {zero2geospatial3d-sdk: headless 3D terrain and building analysis in Python},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/zero2geospatial3d_sdk}
+}
+```
+
+See also `CITATION.cff`.
+
+## License
+
+MIT, see [LICENSE](LICENSE). The bundled viewer includes three.js (MIT) and the
+UTCI polynomial follows pythermalcomfort (MIT); the station index credits
+Climate.OneBuilding.Org. Details in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

zero2geospatial3d_sdk-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party notices
+
+zero2geospatial3d-sdk (a Python port of the 02 Geo3D Analyzer QGIS plugin) ships or
+derives from the following works. Paths are relative to `src/zero2geospatial3d/`.
+
+## Three.js r160
+
+Source: <https://github.com/mrdoob/three.js>
+
+The MIT License
+
+Copyright © 2010-2023 Three.js Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Files: `web/vendor/three/three.module.js` and the add-ons under `web/vendor/three/addons/`
+(bundled browser viewer).
+
+## pythermalcomfort (UTCI polynomial)
+
+Source: <https://github.com/CenterForTheBuiltEnvironment/pythermalcomfort>, `models/utci.py`.
+The UTCI regression polynomial and the saturation vapour pressure function in
+`web/src/core/comfort.js` and its Python port `comfort.py` are transcribed from it. The polynomial itself is the
+operational approximation of Bröde et al. (2012), Int J Biometeorol 56:481-494,
+doi:10.1007/s00484-011-0454-1.
+
+MIT License, Copyright (c) 2019 Federico Tartarini. The full MIT text is the
+same as the one above, with that copyright line.
+
+## climate.onebuilding.org station index
+
+`data/epw_stations.json.gz` lists station names, coordinates, time zones,
+elevations and download paths taken from the TMYx location indexes published
+at <https://climate.onebuilding.org/> (built with the plugin's `tools/build_epw_index.py`).
+Weather files are downloaded from that site at the user's request; they are
+not bundled. Credit: Climate.OneBuilding.Org.