skyview 0.1.0__tar.gz

skyview-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- Raster sky view factor from a DSM or building-height array: horizon search in N azimuths
+  (Zakšek et al., 2011), isotropic (`1 - mean sin γ`) and cosine-weighted
+  (`1 - mean sin² γ`) variants, observer height, edge handling, nodata.
+- Positive and negative topographic openness (Yokoyama et al., 2002).
+- Exact vector SVF at points from building footprints and heights (ray / edge
+  intersection, holes, points on roofs), point grids and footprint rasterisation.
+- Analytic infinite-canyon SVF (Oke, 1981) at any cross-street position, both weightings,
+  plus floor- and wall-averaged view factors (Johnson & Watson, 1984).
+- Street-canyon width, height, H/W, enclosure and axial bearing from footprints and
+  centrelines; Boeing (2019) orientation histogram, entropy and orientation order.
+- GeoJSON output, `.npy` raster I/O and GeoTIFF I/O through the optional `raster` extra.
+- `skyview` command line tool: `raster`, `openness`, `points`, `streets`, `canyon`.

skyview-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: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "skyview"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/skyview_sdk"
+url: "https://pypi.org/project/skyview/"
+abstract: "Sky view factor, topographic openness and street-canyon H/W metrics from DSM rasters or building footprints, validated against Oke's analytic canyon formula."
+keywords:
+  - sky view factor
+  - urban canyon
+  - openness
+  - urban climate
+  - gis

skyview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+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.

skyview-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/skyview/py.typed
+recursive-include src/skyview *.py
+recursive-include tests *.py
+recursive-include examples *.py

skyview-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: skyview
+Version: 0.1.0
+Summary: Sky view factor, topographic openness and street-canyon H/W metrics from DSM rasters or building footprints, validated against Oke's analytic canyon formula.
+Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YusufEminoglu/skyview_sdk
+Project-URL: Repository, https://github.com/YusufEminoglu/skyview_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/skyview_sdk/issues
+Project-URL: Changelog, https://github.com/YusufEminoglu/skyview_sdk/blob/main/CHANGELOG.md
+Keywords: sky-view-factor,svf,urban-canyon,street-canyon,aspect-ratio,openness,dsm,horizon,urban-climate,urban-heat-island,building-footprints,geojson,gis,urban-planning
+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: Environment :: Console
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: raster
+Requires-Dist: rasterio>=1.3; extra == "raster"
+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
+
+# skyview
+
+[![PyPI version](https://img.shields.io/pypi/v/skyview.svg)](https://pypi.org/project/skyview/)
+[![Python versions](https://img.shields.io/pypi/pyversions/skyview.svg)](https://pypi.org/project/skyview/)
+[![CI](https://github.com/YusufEminoglu/skyview_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/skyview_sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/skyview_sdk/blob/main/LICENSE)
+
+**Sky view factor and street-canyon geometry for urban planning and urban climate work.**
+
+`skyview` measures how much sky is visible from the ground and how enclosed
+streets are. It works from either a gridded surface model or from building
+footprints with heights:
+
+- **SVF from a raster.** Sky view factor of every cell of a DSM or
+  building-height array. Horizon angles are searched in N directions
+  (Zakšek et al., 2011). Isotropic and cosine-weighted variants.
+- **Topographic openness.** Positive and negative openness (Yokoyama et al., 2002).
+- **SVF at points from footprints.** The horizon is found exactly by casting rays against
+  footprint edges, with no rasterising. Holes (courtyards), observer height, and
+  points on roofs are supported.
+- **Analytic canyon formulas.** Oke's SVF for an infinite symmetric canyon at any
+  cross-street position, plus floor- and wall-averaged view factors. Use them to validate
+  your own numbers.
+- **Street-canyon metrics.** Width, height, H/W ratio, enclosure and axial bearing along
+  street centrelines. Street-orientation entropy and order (Boeing, 2019).
+- **Output** as numpy arrays, GeoJSON, `.npy` or GeoTIFF, and a `skyview` command line tool.
+
+numpy is the only required dependency. GeoTIFF reading and writing uses the
+optional `raster` extra (rasterio).
+
+For hours of direct sun and building shadows, use the companion package
+[`urbanshadow`](https://pypi.org/project/urbanshadow/). It works from the same
+footprints-and-heights input.
+
+```bash
+pip install skyview            # numpy only
+pip install "skyview[raster]"  # + GeoTIFF I/O via rasterio
+```
+
+Requires Python 3.9 or newer.
+
+---
+
+## Quick start (Python)
+
+```python
+import numpy as np
+from skyview import Building, BuildingSet, canyon_svf, sky_view_factor, street_canyon
+
+# Closed form: centre of an infinite canyon with H/W = 1 (Oke 1981)
+canyon_svf(1.0)                      # 0.4472  (cosine-weighted)
+canyon_svf(1.0, "isotropic")         # 0.2952
+
+# Raster: 1 m building-height grid
+dsm = np.zeros((200, 200))
+dsm[50:150, 60:90] = 24.0
+svf = sky_view_factor(dsm, pixel_size=1.0, n_directions=32, max_radius=150.0)
+
+# Footprints: exact horizon at points
+blocks = BuildingSet([
+    Building.box(-40, -300, -10, 300, 18.0),
+    Building.box(10, -300, 40, 300, 18.0),
+])
+blocks.sky_view_factor([0.0, 5.0], [0.0, 0.0], n_directions=360, weighting="cosine")
+
+# Street canyon along a centreline
+c = street_canyon([(0, -250), (0, 250)], blocks, spacing=25.0)
+c.width_mean, c.height_mean, c.hw_mean, c.bearing    # 20.0, 18.0, 0.9, 0.0
+```
+
+See [`examples/quickstart.py`](examples/quickstart.py) for the same canyon computed in three
+ways.
+
+## Quick start (command line)
+
+```bash
+# SVF raster from a DSM (GeoTIFF needs the raster extra; .npy needs --pixel-size)
+skyview raster dsm.tif -o svf.tif --directions 32 --radius 100 --weighting isotropic
+
+# Positive and negative openness
+skyview openness dsm.tif -o openness_pos.tif --negative openness_neg.tif
+
+# SVF at points, or on a grid over the buildings (projected GeoJSON, metres)
+skyview points buildings.geojson --points sensors.geojson -o sensors_svf.geojson
+skyview points buildings.geojson --grid 5 --observer-height 1.1 -o grid_svf.geojson
+
+# H/W and orientation for street centrelines
+skyview streets buildings.geojson streets.geojson -o canyons.geojson
+
+# Analytic reference values for a canyon
+skyview canyon 1.0
+```
+
+Building heights come from `--height-field` (default `height`). Storey counts
+can be used instead with `--levels-field` and `--floor-height`. `--default-height`
+fills any gaps.
+
+## API overview
+
+| Function / class | What it does |
+| --- | --- |
+| `sky_view_factor(dsm, pixel_size, n_directions, max_radius, weighting, observer_height, edge)` | SVF of every raster cell |
+| `horizon_angles(...)`, `elevation_angle_extremes(...)` | horizon angle stack `(n_dir, rows, cols)` |
+| `svf_from_horizon(angles, weighting)` | SVF from your own horizon angles |
+| `openness(dsm, pixel_size, n_directions=8, max_radius)` | positive / negative openness, degrees |
+| `Building`, `BuildingSet`, `buildings_from_geojson(...)` | footprint prisms and fast edge arrays |
+| `BuildingSet.sky_view_factor(x, y, ...)`, `BuildingSet.horizon_angles(x, y, ...)` | exact vector SVF at points |
+| `point_grid`, `points_in_buildings`, `rasterize_buildings` | grids, masks, footprints to a height raster |
+| `canyon_svf(hw, weighting, position)`, `canyon_floor_mean_svf`, `canyon_wall_mean_svf`, `canyon_horizon_angle` | analytic canyon |
+| `street_canyon`, `street_canyons` → `StreetCanyon` | width, height, H/W, enclosure, bearing per street |
+| `orientation_histogram`, `orientation_entropy`, `orientation_order` | street orientation statistics |
+| `read_raster`, `write_raster`, `read_geojson`, `write_geojson`, `points_to_geojson`, `canyons_to_geojson` | I/O |
+
+## Method and sources
+
+**Horizon search (raster).** Zakšek, Oštir and Kokalj (2011),
+*Remote Sensing* 3(2), 398–415, https://doi.org/10.3390/rs3020398, describe
+the search. From every cell, rays are cast in `n_directions` azimuths, measured
+clockwise from grid north, out to `max_radius`. Along each ray the elevation angle
+`atan((z − z0)/d)` is computed for every visited cell, and the maximum is the
+horizon angle γᵢ. The visited cells are those hit by sampling the ray every pixel
+and rounding to the nearest cell. `d` is the exact distance between the two cell
+centres.
+
+**Two SVF definitions.**
+
+- *Isotropic*: `SVF = 1 − (1/n) Σ sin γᵢ`. This is the share of the hemisphere's
+  solid angle that is visible. Zakšek et al. use this form for relief visualisation.
+- *Cosine-weighted*: `SVF = 1 − (1/n) Σ sin² γᵢ`. This is the radiative view factor
+  of a horizontal surface, the quantity in the urban-climate canyon literature
+  (Oke; Johnson & Watson).
+
+Both follow from integrating over the visible part of each azimuth slice:
+`∫ cos e de` and `∫ 2 sin e cos e de` from γ to 90°. Horizon angles below 0 are
+clamped, so SVF ≤ 1.
+
+**Analytic canyon** (`skyview.analytic`), for an infinite canyon of height H and
+width W:
+
+- centre-line cosine SVF: `cos(arctan(2H/W))`. Oke, T. R. (1981), *J. Climatology* 1,
+  237–254; Oke (1987), *Boundary Layer Climates*.
+- off-centre point at distances a and b from the walls: `(a/√(a²+H²) + b/√(b²+H²))/2`
+  (cosine) and `1 − (arctan(H/a) + arctan(H/b))/π` (isotropic).
+- floor-averaged `√(1+(H/W)²) − H/W` and wall-averaged `(1 + W/H − √(1+(W/H)²))/2`.
+  Johnson, G. T. and Watson, I. D. (1984), *J. Climate Appl. Meteorol.* 23, 329–335.
+  These are Hottel's crossed-strings rule.
+
+The test suite checks these closed forms against numerical integration of the
+horizon profile. It also checks that floor and wall factors close the energy
+balance of the canyon opening.
+
+**Openness.** Yokoyama, R., Shirasawa, M. and Pike, R. J. (2002),
+*Photogrammetric Engineering & Remote Sensing* 68(3), 257–265. Positive
+openness is the mean of `90° − max elevation angle` over the directions, and
+negative openness is the mean of `90° + min elevation angle`. Both equal 90° on
+flat ground.
+
+**Vector horizon.** Each ray is intersected with every footprint edge. A building
+prism has a constant height, so its highest elevation angle along a ray is at the
+edge where the ray enters it. Taking the maximum over all edge crossings is
+therefore exact for flat ground and prismatic buildings.
+
+**Street canyons.** Stations are placed every `spacing` metres along a centreline.
+Perpendicular rays find the first building on each side within `max_distance`.
+Per station, `W = d_left + d_right`, `H = (h_left + h_right)/2`, and the aspect
+ratio is H/W, the main canyon descriptor in Oke (1988), *Energy and Buildings* 11,
+103–113. The summary also gives `svf_oke`, Oke's centre-line SVF for the mean
+H/W, which is an idealised estimate.
+
+**Street orientation.** Boeing, G. (2019), *Applied Network Science* 4, 67,
+https://doi.org/10.1007/s41109-019-0189-1. The method uses 36 bins of 10°
+centred on 0°, 10°, … . Each segment is counted in both directions, weighted by
+length by default. The entropy is `H = −Σ P ln P`, and the orientation order is
+`φ = 1 − ((H − ln 4)/(ln 36 − ln 4))²`.
+
+## Validation
+
+- Flat ground gives SVF = 1 for both weightings and openness = 90°/90°.
+- Raster canyon (wall cells extended past the raster edge with `edge="nearest"`):
+  results are within 0.01 of Oke's formula for H/W from about 0.45 to 1.9.
+- Vector canyon with 720 directions: within 2·10⁻⁴ of the analytic value at the
+  centre and off-centre positions.
+- Exact hand-computed horizons for a single tower, a pit, a peak and a square
+  courtyard.
+
+## Limitations
+
+- Coordinates and pixel sizes must be in metres in a projected CRS. Geographic
+  (lon/lat) data must be reprojected first.
+- In the raster method, surfaces sit at cell centres and rays are sampled by
+  nearest-cell rounding. Walls are therefore effectively half a cell further away
+  than the footprint edge, and thin features may be missed between ray samples
+  at coarse direction counts. Use a fine pixel size and 32 or more directions in
+  dense fabric.
+- Raster run time grows with `n_directions × max_radius / pixel_size` passes over
+  the array. This is plain numpy and is meant for district-scale rasters, not whole
+  cities at 0.5 m.
+- The vector method assumes flat ground and flat-roofed prisms. Trees, terrain
+  and roof shapes are ignored, so use a DSM for those.
+- `edge="ignore"` treats space outside the raster as unobstructed, so SVF is
+  overestimated near the raster border. Pad your area of interest by `max_radius`.
+- The street-canyon summary uses the first building hit on each side. Setbacks,
+  gaps and intersections reduce `enclosure` but are not modelled in more detail.
+- Cosine weighting assumes a horizontal receiver and an isotropic sky radiance.
+  Anisotropic sky models are out of scope.
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_skyview,
+  author  = {Eminoğlu, Yusuf},
+  title   = {skyview},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/skyview_sdk}
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

skyview-0.1.0/README.md

@@ -0,0 +1,221 @@
+# skyview
+
+[![PyPI version](https://img.shields.io/pypi/v/skyview.svg)](https://pypi.org/project/skyview/)
+[![Python versions](https://img.shields.io/pypi/pyversions/skyview.svg)](https://pypi.org/project/skyview/)
+[![CI](https://github.com/YusufEminoglu/skyview_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/skyview_sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/skyview_sdk/blob/main/LICENSE)
+
+**Sky view factor and street-canyon geometry for urban planning and urban climate work.**
+
+`skyview` measures how much sky is visible from the ground and how enclosed
+streets are. It works from either a gridded surface model or from building
+footprints with heights:
+
+- **SVF from a raster.** Sky view factor of every cell of a DSM or
+  building-height array. Horizon angles are searched in N directions
+  (Zakšek et al., 2011). Isotropic and cosine-weighted variants.
+- **Topographic openness.** Positive and negative openness (Yokoyama et al., 2002).
+- **SVF at points from footprints.** The horizon is found exactly by casting rays against
+  footprint edges, with no rasterising. Holes (courtyards), observer height, and
+  points on roofs are supported.
+- **Analytic canyon formulas.** Oke's SVF for an infinite symmetric canyon at any
+  cross-street position, plus floor- and wall-averaged view factors. Use them to validate
+  your own numbers.
+- **Street-canyon metrics.** Width, height, H/W ratio, enclosure and axial bearing along
+  street centrelines. Street-orientation entropy and order (Boeing, 2019).
+- **Output** as numpy arrays, GeoJSON, `.npy` or GeoTIFF, and a `skyview` command line tool.
+
+numpy is the only required dependency. GeoTIFF reading and writing uses the
+optional `raster` extra (rasterio).
+
+For hours of direct sun and building shadows, use the companion package
+[`urbanshadow`](https://pypi.org/project/urbanshadow/). It works from the same
+footprints-and-heights input.
+
+```bash
+pip install skyview            # numpy only
+pip install "skyview[raster]"  # + GeoTIFF I/O via rasterio
+```
+
+Requires Python 3.9 or newer.
+
+---
+
+## Quick start (Python)
+
+```python
+import numpy as np
+from skyview import Building, BuildingSet, canyon_svf, sky_view_factor, street_canyon
+
+# Closed form: centre of an infinite canyon with H/W = 1 (Oke 1981)
+canyon_svf(1.0)                      # 0.4472  (cosine-weighted)
+canyon_svf(1.0, "isotropic")         # 0.2952
+
+# Raster: 1 m building-height grid
+dsm = np.zeros((200, 200))
+dsm[50:150, 60:90] = 24.0
+svf = sky_view_factor(dsm, pixel_size=1.0, n_directions=32, max_radius=150.0)
+
+# Footprints: exact horizon at points
+blocks = BuildingSet([
+    Building.box(-40, -300, -10, 300, 18.0),
+    Building.box(10, -300, 40, 300, 18.0),
+])
+blocks.sky_view_factor([0.0, 5.0], [0.0, 0.0], n_directions=360, weighting="cosine")
+
+# Street canyon along a centreline
+c = street_canyon([(0, -250), (0, 250)], blocks, spacing=25.0)
+c.width_mean, c.height_mean, c.hw_mean, c.bearing    # 20.0, 18.0, 0.9, 0.0
+```
+
+See [`examples/quickstart.py`](examples/quickstart.py) for the same canyon computed in three
+ways.
+
+## Quick start (command line)
+
+```bash
+# SVF raster from a DSM (GeoTIFF needs the raster extra; .npy needs --pixel-size)
+skyview raster dsm.tif -o svf.tif --directions 32 --radius 100 --weighting isotropic
+
+# Positive and negative openness
+skyview openness dsm.tif -o openness_pos.tif --negative openness_neg.tif
+
+# SVF at points, or on a grid over the buildings (projected GeoJSON, metres)
+skyview points buildings.geojson --points sensors.geojson -o sensors_svf.geojson
+skyview points buildings.geojson --grid 5 --observer-height 1.1 -o grid_svf.geojson
+
+# H/W and orientation for street centrelines
+skyview streets buildings.geojson streets.geojson -o canyons.geojson
+
+# Analytic reference values for a canyon
+skyview canyon 1.0
+```
+
+Building heights come from `--height-field` (default `height`). Storey counts
+can be used instead with `--levels-field` and `--floor-height`. `--default-height`
+fills any gaps.
+
+## API overview
+
+| Function / class | What it does |
+| --- | --- |
+| `sky_view_factor(dsm, pixel_size, n_directions, max_radius, weighting, observer_height, edge)` | SVF of every raster cell |
+| `horizon_angles(...)`, `elevation_angle_extremes(...)` | horizon angle stack `(n_dir, rows, cols)` |
+| `svf_from_horizon(angles, weighting)` | SVF from your own horizon angles |
+| `openness(dsm, pixel_size, n_directions=8, max_radius)` | positive / negative openness, degrees |
+| `Building`, `BuildingSet`, `buildings_from_geojson(...)` | footprint prisms and fast edge arrays |
+| `BuildingSet.sky_view_factor(x, y, ...)`, `BuildingSet.horizon_angles(x, y, ...)` | exact vector SVF at points |
+| `point_grid`, `points_in_buildings`, `rasterize_buildings` | grids, masks, footprints to a height raster |
+| `canyon_svf(hw, weighting, position)`, `canyon_floor_mean_svf`, `canyon_wall_mean_svf`, `canyon_horizon_angle` | analytic canyon |
+| `street_canyon`, `street_canyons` → `StreetCanyon` | width, height, H/W, enclosure, bearing per street |
+| `orientation_histogram`, `orientation_entropy`, `orientation_order` | street orientation statistics |
+| `read_raster`, `write_raster`, `read_geojson`, `write_geojson`, `points_to_geojson`, `canyons_to_geojson` | I/O |
+
+## Method and sources
+
+**Horizon search (raster).** Zakšek, Oštir and Kokalj (2011),
+*Remote Sensing* 3(2), 398–415, https://doi.org/10.3390/rs3020398, describe
+the search. From every cell, rays are cast in `n_directions` azimuths, measured
+clockwise from grid north, out to `max_radius`. Along each ray the elevation angle
+`atan((z − z0)/d)` is computed for every visited cell, and the maximum is the
+horizon angle γᵢ. The visited cells are those hit by sampling the ray every pixel
+and rounding to the nearest cell. `d` is the exact distance between the two cell
+centres.
+
+**Two SVF definitions.**
+
+- *Isotropic*: `SVF = 1 − (1/n) Σ sin γᵢ`. This is the share of the hemisphere's
+  solid angle that is visible. Zakšek et al. use this form for relief visualisation.
+- *Cosine-weighted*: `SVF = 1 − (1/n) Σ sin² γᵢ`. This is the radiative view factor
+  of a horizontal surface, the quantity in the urban-climate canyon literature
+  (Oke; Johnson & Watson).
+
+Both follow from integrating over the visible part of each azimuth slice:
+`∫ cos e de` and `∫ 2 sin e cos e de` from γ to 90°. Horizon angles below 0 are
+clamped, so SVF ≤ 1.
+
+**Analytic canyon** (`skyview.analytic`), for an infinite canyon of height H and
+width W:
+
+- centre-line cosine SVF: `cos(arctan(2H/W))`. Oke, T. R. (1981), *J. Climatology* 1,
+  237–254; Oke (1987), *Boundary Layer Climates*.
+- off-centre point at distances a and b from the walls: `(a/√(a²+H²) + b/√(b²+H²))/2`
+  (cosine) and `1 − (arctan(H/a) + arctan(H/b))/π` (isotropic).
+- floor-averaged `√(1+(H/W)²) − H/W` and wall-averaged `(1 + W/H − √(1+(W/H)²))/2`.
+  Johnson, G. T. and Watson, I. D. (1984), *J. Climate Appl. Meteorol.* 23, 329–335.
+  These are Hottel's crossed-strings rule.
+
+The test suite checks these closed forms against numerical integration of the
+horizon profile. It also checks that floor and wall factors close the energy
+balance of the canyon opening.
+
+**Openness.** Yokoyama, R., Shirasawa, M. and Pike, R. J. (2002),
+*Photogrammetric Engineering & Remote Sensing* 68(3), 257–265. Positive
+openness is the mean of `90° − max elevation angle` over the directions, and
+negative openness is the mean of `90° + min elevation angle`. Both equal 90° on
+flat ground.
+
+**Vector horizon.** Each ray is intersected with every footprint edge. A building
+prism has a constant height, so its highest elevation angle along a ray is at the
+edge where the ray enters it. Taking the maximum over all edge crossings is
+therefore exact for flat ground and prismatic buildings.
+
+**Street canyons.** Stations are placed every `spacing` metres along a centreline.
+Perpendicular rays find the first building on each side within `max_distance`.
+Per station, `W = d_left + d_right`, `H = (h_left + h_right)/2`, and the aspect
+ratio is H/W, the main canyon descriptor in Oke (1988), *Energy and Buildings* 11,
+103–113. The summary also gives `svf_oke`, Oke's centre-line SVF for the mean
+H/W, which is an idealised estimate.
+
+**Street orientation.** Boeing, G. (2019), *Applied Network Science* 4, 67,
+https://doi.org/10.1007/s41109-019-0189-1. The method uses 36 bins of 10°
+centred on 0°, 10°, … . Each segment is counted in both directions, weighted by
+length by default. The entropy is `H = −Σ P ln P`, and the orientation order is
+`φ = 1 − ((H − ln 4)/(ln 36 − ln 4))²`.
+
+## Validation
+
+- Flat ground gives SVF = 1 for both weightings and openness = 90°/90°.
+- Raster canyon (wall cells extended past the raster edge with `edge="nearest"`):
+  results are within 0.01 of Oke's formula for H/W from about 0.45 to 1.9.
+- Vector canyon with 720 directions: within 2·10⁻⁴ of the analytic value at the
+  centre and off-centre positions.
+- Exact hand-computed horizons for a single tower, a pit, a peak and a square
+  courtyard.
+
+## Limitations
+
+- Coordinates and pixel sizes must be in metres in a projected CRS. Geographic
+  (lon/lat) data must be reprojected first.
+- In the raster method, surfaces sit at cell centres and rays are sampled by
+  nearest-cell rounding. Walls are therefore effectively half a cell further away
+  than the footprint edge, and thin features may be missed between ray samples
+  at coarse direction counts. Use a fine pixel size and 32 or more directions in
+  dense fabric.
+- Raster run time grows with `n_directions × max_radius / pixel_size` passes over
+  the array. This is plain numpy and is meant for district-scale rasters, not whole
+  cities at 0.5 m.
+- The vector method assumes flat ground and flat-roofed prisms. Trees, terrain
+  and roof shapes are ignored, so use a DSM for those.
+- `edge="ignore"` treats space outside the raster as unobstructed, so SVF is
+  overestimated near the raster border. Pad your area of interest by `max_radius`.
+- The street-canyon summary uses the first building hit on each side. Setbacks,
+  gaps and intersections reduce `enclosure` but are not modelled in more detail.
+- Cosine weighting assumes a horizontal receiver and an isotropic sky radiance.
+  Anisotropic sky models are out of scope.
+
+## Academic citation
+
+```bibtex
+@software{eminoglu_skyview,
+  author  = {Eminoğlu, Yusuf},
+  title   = {skyview},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/skyview_sdk}
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

skyview-0.1.0/examples/quickstart.py

@@ -0,0 +1,61 @@
+"""skyview quick start: one street canyon, three ways.
+
+Run from a clone (no data files needed):
+
+    python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from skyview import (
+    Building,
+    BuildingSet,
+    canyon_svf,
+    rasterize_buildings,
+    sky_view_factor,
+    street_canyon,
+)
+
+
+def main() -> int:
+    # Two 18 m high blocks along a north-south street, building lines 20 m apart
+    # (H/W = 0.9). Coordinates are metres in a projected CRS.
+    blocks = BuildingSet(
+        [
+            Building.box(-40.0, -300.0, -10.0, 300.0, 18.0),
+            Building.box(10.0, -300.0, 40.0, 300.0, 18.0),
+        ]
+    )
+    hw = 18.0 / 20.0
+
+    # 1. Closed form (Oke 1981): centre of an infinite symmetric canyon.
+    print(f"analytic  cosine SVF   : {canyon_svf(hw, 'cosine'):.4f}")
+    print(f"analytic  isotropic SVF: {canyon_svf(hw, 'isotropic'):.4f}")
+
+    # 2. Exact vector horizon at the street centre line.
+    for w in ("cosine", "isotropic"):
+        v = blocks.sky_view_factor(0.0, 0.0, n_directions=360, weighting=w)[0]
+        print(f"footprints {w:9s} SVF: {v:.4f}")
+
+    # 3. Raster: burn the blocks into a 1 m height grid and search 32 directions.
+    dsm, transform = rasterize_buildings(blocks, (-60, -100, 60, 100), 1.0)
+    svf = sky_view_factor(dsm, 1.0, n_directions=32, max_radius=300.0, edge="nearest")
+    # Cell centre (0.5, -0.5), next to the centre line. Surfaces sit at cell
+    # centres, so the walls are effectively 21 m apart here: a little more sky.
+    row, col = 100, 60
+    print(f"raster    isotropic SVF: {svf[row, col]:.4f}  (grid {dsm.shape}, {transform[1]} m)")
+
+    # Street-canyon geometry along the centreline.
+    c = street_canyon([(0.0, -250.0), (0.0, 250.0)], blocks, spacing=25.0)
+    print(
+        f"street: W={c.width_mean:.1f} m  H={c.height_mean:.1f} m  H/W={c.hw_mean:.2f}  "
+        f"bearing={c.bearing:.0f} deg  enclosure={c.enclosure:.0%}"
+    )
+    print(f"mean SVF of the raster: {np.nanmean(svf):.3f}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())