Metadata-Version: 2.4
Name: skyview
Version: 0.1.2
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://gitlab.com/geophilo1/skyview_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/skyview_sdk
Project-URL: Documentation, https://gitlab.com/geophilo1/skyview_sdk#readme
Project-URL: Issues, https://gitlab.com/geophilo1/skyview_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/skyview_sdk/-/blob/main/CHANGELOG.md
Project-URL: SDK dashboard, https://geophilo.com/sdk-dashboard/
Project-URL: DOI, https://doi.org/10.5281/zenodo.24122219
Keywords: sky-view-factor,svf,urban-canyon,street-canyon,aspect-ratio,topographic-openness,dsm,horizon-angle,urban-climate,urban-heat-island,building-footprints,geotiff,geojson,gis,urban-planning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
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

<p align="center">
  <a href="https://geophilo.com/sdk-dashboard/"><img src="https://geophilo.com/assets/sdk_icons/skyview_sdk.svg" width="120" height="120" alt="skyview icon"></a>
</p>

# 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/)
[![pipeline status](https://gitlab.com/geophilo1/skyview_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/skyview_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/geophilo1/skyview_sdk/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24122219.svg)](https://doi.org/10.5281/zenodo.24122219)
[![Downloads](https://static.pepy.tech/badge/skyview/month)](https://pepy.tech/project/skyview)

**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`](https://gitlab.com/geophilo1/skyview_sdk/-/blob/main/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.2},
  doi     = {10.5281/zenodo.24122219},
  url     = {https://gitlab.com/geophilo1/skyview_sdk}
}
```


## Related Geophilo SDKs

- [urbanshadow](https://pypi.org/project/urbanshadow/): building shadows and sun-hours analysis from footprints and heights.
- [heatstress](https://pypi.org/project/heatstress/): heat-stress indices (UTCI, WBGT, heat index) that use sky view and radiation inputs.
- [lczlite](https://pypi.org/project/lczlite/): Local Climate Zone classification from urban canopy parameters, including SVF.
- [streetform](https://pypi.org/project/streetform/): street-network form and connectivity metrics.
- [isovist](https://pypi.org/project/isovist/): isovists and visibility graph analysis.

## License

MIT. See [LICENSE](https://gitlab.com/geophilo1/skyview_sdk/-/blob/main/LICENSE).
