Skip to main content
Loss of provenance

A previous release had provenance metadata, but this release does not. View details.

skyview icon

skyview

PyPI version Python versions pipeline status License: MIT DOI Downloads

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.2},
  doi     = {10.5281/zenodo.24122219},
  url     = {https://gitlab.com/geophilo1/skyview_sdk}
}
  • urbanshadow: building shadows and sun-hours analysis from footprints and heights.
  • heatstress: heat-stress indices (UTCI, WBGT, heat index) that use sky view and radiation inputs.
  • lczlite: Local Climate Zone classification from urban canopy parameters, including SVF.
  • streetform: street-network form and connectivity metrics.
  • isovist: isovists and visibility graph analysis.

License

MIT. See LICENSE.

Metadata

Release files for skyview 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Loss of provenance

These files do not have provenance metadata, despite files in a prior release including this data.

We recommend further investigation before installing these files. View details.

Source distribution (sdist)

Source distribution for skyview 0.1.2
File Size Uploaded Provenance Actions
skyview-0.1.2.tar.gz 40.2 kB Without provenance Details for skyview-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for skyview 0.1.2
File Interpreter ABI Platform Actions
skyview-0.1.2-py3-none-any.whl Python 3 none any Details for skyview-0.1.2-py3-none-any.whl

Total release size: 69.4 kB

Release files / skyview-0.1.2.tar.gz

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL skyview-0.1.2.tar.gz
Size 40.2 kB
Tags Source
SHA-256 checksum
How to use checksums
4f3708c0384768814f8028b966bb7639c4b9bb4ca917d9a8f2e8d56bd6f4d04f
BLAKE2b-256 checksum
How to use checksums
3643e1575a6f415c1a7696f38ae067c7e4b8b8b1e52c7bcfe7f989892feb8e7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / skyview-0.1.2-py3-none-any.whl

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL skyview-0.1.2-py3-none-any.whl
Size 29.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
71e4b72153b4a9df79debb1e40a21003cfa010785e81f7c0a382baff85d743ec
BLAKE2b-256 checksum
How to use checksums
f3e4a90c09686b6c94806e69365a96499cb166e1a90776205d53e33013cc40e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Security for skyview 0.1.2

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.

Loss of provenance

A previous release of these files had provenance metadata, but this release does not.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Release comparison

  • Removed 0.1.1 2 files With provenance
  • Added 0.1.2 2 files Without provenance

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