Skip to main content

skyview

PyPI version Python versions CI License: MIT

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. 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) 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

@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)

Source distribution for skyview 0.1.1
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)

Table of built distributions (wheels) for skyview 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page