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,
.npyor GeoTIFF, and askyviewcommand 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. It works from the same
footprints-and-heights input.
pip install skyview # numpy only
pip install "skyview[raster]" # + GeoTIFF I/O via rasterio
Requires Python 3.9 or newer.
Quick start (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 for the same canyon computed in three
ways.
Quick start (command line)
# 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) and1 − (arctan(H/a) + arctan(H/b))/π(isotropic). - floor-averaged
√(1+(H/W)²) − H/Wand 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_sizepasses 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 bymax_radius.- The street-canyon summary uses the first building hit on each side. Setbacks,
gaps and intersections reduce
enclosurebut 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
@software{eminoglu_skyview,
author = {Eminoğlu, Yusuf},
title = {skyview},
year = {2026},
version = {0.1.1},
url = {https://github.com/YusufEminoglu/skyview_sdk}
}
License
MIT. See LICENSE.
Metadata
Release files for skyview 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| skyview-0.1.1.tar.gz | 38.8 kB | With provenance | Details for skyview-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| skyview-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for skyview-0.1.1-py3-none-any.whl |
Total release size: 67.6 kB
Release files / skyview-0.1.1.tar.gz
| Download URL | skyview-0.1.1.tar.gz |
|---|---|
| Size | 38.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8d3e1a75b33eabb53ff4f6f3aaede50b6b3bc2fc259a15aecda9c0e41bcf77f6
|
|
BLAKE2b-256 checksum How to use checksums |
71bd4a6289bd49189004add5ed11cb615929f2f3993a786a6361b5b19ffd67f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / skyview-0.1.1-py3-none-any.whl
| Download URL | skyview-0.1.1-py3-none-any.whl |
|---|---|
| Size | 28.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac3fa887afe143ffa3b40e901e6d10d602ea77d486eb6695a9b6ec0039b2f21f
|
|
BLAKE2b-256 checksum How to use checksums |
ac25dc7350514b9cc485f04ee4a1401f5bb326607f8fa3c635badf58170e7d5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for skyview 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for skyview-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.