Skip to main content
Loss of provenance

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

isovist icon

isovist

PyPI version Python versions pipeline status License: MIT DOI Downloads

Exact 2D isovists and visibility graph analysis for urban design.

isovist computes what can be seen from a point in a plan of buildings, walls and columns, and describes the shape of that visible space with the classic isovist measures. It also runs visibility graph analysis (VGA) on a grid of points and answers point-to-point "can A see B?" questions. The only dependency is NumPy.

  • Exact isovist polygon from an angular sweep with exact ray/edge intersections, not a fan of sampled rays. Optional maximum view distance and field of view (angle and direction).
  • Isovist measures: area, perimeter, compactness, jaggedness, occlusivity, number of occluding edges, drift (distance and direction) and min/max/mean/std radial length. All of them come from closed-form integrals.
  • Intervisibility: exact; a sight line may graze a corner or run along a wall, but it may not cross an obstacle.
  • Visibility graph analysis: connectivity, clustering coefficient, mean depth, relative asymmetry and integration on grids or on your own points. An optional visual radius limits the links.
  • GeoJSON in/out in projected coordinates, plus an isovist command-line tool.
pip install isovist

Requires Python 3.9 or newer.


Quick start (Python)

from isovist import Environment

room = [(0, 0), (10, 0), (10, 10), (0, 10)]
pillar = [(4, 4), (6, 4), (6, 6), (4, 6)]
env = Environment(obstacles=[pillar], boundary=room)

iso = env.isovist((2, 5))
iso.area          # 70.0   (100 - pillar 4 - shadow 26)
iso.occlusivity   # 13.416 (two occluding edges of length sqrt(45))
iso.polygon       # [(x, y), ...] counter-clockwise ring

m = iso.measures()
m.compactness, m.drift, m.mean_radial, m.max_radial

env.isovist((2, 5), fov=90, direction=0, max_radius=6)   # 90 deg view cone, 6 m reach
env.is_visible((3, 5), (7, 5))                           # False: the pillar is in the way

from isovist import visibility_graph_analysis
vga = visibility_graph_analysis(env, spacing=1.0)
vga.connectivity, vga.clustering, vga.mean_depth, vga.integration

Obstacles and the boundary are isovist.Polygon objects (holes allowed) or plain vertex lists. Obstacles may overlap each other and may stick out of the boundary. Holes in the boundary act as obstacles. The viewpoint must lie strictly in free space.

Quick start (command line)

# isovists with all measures for two viewpoints and for every Point in a file
isovist compute --obstacles buildings.geojson --boundary site.geojson \
    --at 512340.5,4512200 --points viewpoints.geojson -o isovists.geojson

# 120 degree view cone towards north-east, 80 m reach
isovist compute --obstacles buildings.geojson --at 512340.5,4512200 \
    --fov 120 --direction 45 --max-radius 80

# VGA on a 2 m grid (writes grid points with the measures)
isovist vga --obstacles buildings.geojson --boundary site.geojson --spacing 2 -o vga.geojson

# intervisibility; exit code 0 = visible, 1 = not visible
isovist visible --obstacles buildings.geojson --from 10,20 --to 80,45

Write negative coordinates as --at=-12.5,40 so they are not read as options. Without --boundary, open-space isovists need --max-radius.

See examples/quickstart.py for a small plaza with two pavilions and a column.

Coordinates and GeoJSON

All geometry is planar, so coordinates must be projected (metres or feet), for example UTM. RFC 7946 GeoJSON is nominally longitude/latitude. isovist reads and writes the same structure with projected coordinates, as produced by ogr2ogr -t_srs EPSG:32635 -lco RFC7946=NO out.geojson in.gpkg. A legacy crs member in the input is copied to the output. load_environment warns when the coordinates look like degrees.

Outputs: isovist compute writes Polygon features with the viewpoint (vp_x, vp_y), the input point properties and every measure. isovist vga writes Point features with connectivity, clustering, mean_depth, relative_asymmetry, integration and node_count. Undefined values (nan, inf) become null.

API overview

Object / function Purpose
Environment(obstacles, boundary=None, tol=None) the plan; .isovist(), .is_visible(), .visibility_matrix(), .locate()
Environment.isovist(vp, max_radius=None, fov=None, direction=0, arc_step=1) exact Isovist
Isovist .polygon, .area, .perimeter, .centroid, .occlusivity, .occluding_edges, .radial(theta), .contains(pt), .measures(), .to_geojson()
IsovistMeasures area, perimeter, compactness, jaggedness, occlusivity, occluding_edges, drift, drift_angle, min/max/mean/std_radial
visibility_graph_analysis(env, points=None, spacing=None, max_radius=None) VGAResult with per-node arrays and .records()
grid_points(env, spacing, bounds=None, origin=None) cell-centre grid in free space
graph_measures(adjacency) VGA measures for any undirected graph
load_environment, polygons_from_geojson, points_from_geojson, feature_collection, write_geojson GeoJSON I/O

Angles are in degrees, counted counter-clockwise from east (+x), in both the API and the CLI. Isovist.radial takes radians.

Method and sources

Isovist. An isovist is the set of points visible from a vantage point (Benedikt 1979). Every edge end point, every crossing between overlapping polygons, every point where an edge meets the view-distance circle and each field-of-view limit gives a critical direction. Between two consecutive critical directions the nearest edge cannot change, so one ray at the mid-angle finds it. The isovist boundary on that interval is then the exact intersection of the two bounding rays with that edge's line, or a circular arc of radius max_radius. Edges face the viewer only when the viewpoint lies on their open side, so back faces are culled. Only arcs are discretised, and only for the output polygon (arc_step). Area, perimeter, centroid and radial statistics use exact sector formulas.

Measures. With A the area, P the perimeter and r(θ) the radial length:

Measure Definition Source
area, perimeter A, P Benedikt 1979
occlusivity total length of the radial occluding edges (boundary that is not a surface). View-cone sides and view-distance arcs are not counted. Benedikt 1979
compactness 4πA / P² (1 for a circle) circularity form used in isovist studies after Benedikt 1979; Batty 2001
jaggedness P² / A (4π for a circle) Wiener et al. 2007
drift, drift_angle distance and direction from the viewpoint to the isovist centroid Turner et al. 2001; Batty 2001
min/max/mean/std radial moments of r(θ) over the visible angle, as continuous integrals Benedikt 1979 (radial moments); Batty 2001

For a straight piece at perpendicular distance h, with tangential coordinate τ: ∫ r dθ = h ln((r₁+τ₁)/(r₀+τ₀)) and ∫ r² dθ = h (τ₁ − τ₀).

VGA (Turner et al. 2001). Nodes are grid points in free space. Two nodes are linked when they can see each other (both ways, by the same exact rule as is_visible). For each node:

  • connectivity is the number of linked nodes.
  • clustering coefficient is the number of links among the node's neighbours divided by k(k−1)/2 (Watts & Strogatz 1998).
  • mean depth is MD = Σ depth / (k−1) over the node's connected component of k nodes, from breadth-first search.
  • relative asymmetry is RA = 2(MD−1)/(k−2).
  • integration is D_k / RA, with D_k = 2{k[log₂((k+2)/3) − 1] + 1} / ((k−1)(k−2)) (Hillier & Hanson 1984).

Each row of the visibility matrix is computed from one exact isovist, so VGA costs one isovist per grid point plus an n × n BFS in matrix form.

References

  • Batty, M. (2001). Exploring isovist fields: space and shape in architectural and urban morphology. Environment and Planning B, 28(1), 123–150. https://doi.org/10.1068/b2725
  • Benedikt, M. L. (1979). To take hold of space: isovists and isovist fields. Environment and Planning B, 6(1), 47–65. https://doi.org/10.1068/b060047
  • Hillier, B., & Hanson, J. (1984). The Social Logic of Space. Cambridge University Press.
  • Turner, A., Doxa, M., O'Sullivan, D., & Penn, A. (2001). From isovists to visibility graphs: a methodology for the analysis of architectural space. Environment and Planning B, 28(1), 103–121. https://doi.org/10.1068/b2684
  • Watts, D. J., & Strogatz, S. H. (1998). Collective dynamics of "small-world" networks. Nature, 393, 440–442. https://doi.org/10.1038/30918
  • Wiener, J. M., Franz, G., Rossmanith, N., Reichelt, A., Mallot, H. A., & Bülthoff, H. H. (2007). Isovist analysis captures properties of space relevant for locomotion and experience. Perception, 36(7), 1066–1083. https://doi.org/10.1068/p5587

Limitations

  • 2D only: no terrain, no building heights, no eye level. Every obstacle blocks the view completely.
  • Planar coordinates only. Reproject geographic data first.
  • Isovist cost grows with (front-facing edges)², so a single isovist among a few thousand edges takes milliseconds to tenths of a second. VGA needs one isovist per grid point plus an n × n matrix: a few thousand points is practical, but tens of thousands is not. Use a coarser grid, a sub-area or max_radius.
  • Without a boundary, every viewpoint needs max_radius (open-space views never close).
  • Measure names differ between tools such as depthmapX. Check the definitions above before you compare numbers. Integration is computed per connected component; nodes that see every other node have RA = 0 and integration inf (written as null).
  • Geometric tolerance defaults to 1e-9 × the extent of the data. Pass Environment(tol=...) for unusual data.

Development

pip install -e ".[dev]"
python -m pytest tests -q
python -m ruff check . && python -m ruff format --check src tests
python -m mypy src

The tests check results against hand-computed geometries: a convex room, a room with a pillar, an L-shaped corridor, view cones, view-distance circles clipped by walls and small graphs with known depths. They also cross-check against independent sampled rays.

Academic citation

If you use isovist in research, please cite it (see also CITATION.cff):

@software{eminoglu_isovist,
  author  = {Eminoğlu, Yusuf},
  title   = {isovist},
  year    = {2026},
  version = {0.1.2},
  doi     = {10.5281/zenodo.24122207},
  url     = {https://gitlab.com/geophilo1/isovist_sdk}
}
  • skyview: sky view factor and street-canyon geometry from DSMs or footprints.
  • urbanshadow: building shadows and sun-hours analysis.
  • streetform: street-network form and connectivity metrics.
  • spacematrix: Spacematrix density indicators (FSI, GSI, OSR, L).

License

MIT © 2026 Yusuf Eminoğlu. See LICENSE.

Metadata

Release files for isovist 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 isovist 0.1.2
File Size Uploaded Provenance Actions
isovist-0.1.2.tar.gz 44.5 kB Without provenance Details for isovist-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 76.4 kB

Release files / isovist-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 isovist-0.1.2.tar.gz
Size 44.5 kB
Tags Source
SHA-256 checksum
How to use checksums
5f01ec92a511bd72127ce31a4bef36dc480ad82d7699e9d87c694686678521d4
BLAKE2b-256 checksum
How to use checksums
99a5fb06c951ea25446acc94a0656e3a57a3394a18051737aa10f8cf8ac64314
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / isovist-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 isovist-0.1.2-py3-none-any.whl
Size 31.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2d894fb6260ff699f0549c556cc1febd6569212c766b53acfd3770f5551d4e87
BLAKE2b-256 checksum
How to use checksums
54a48813bd134b2ced6a845d584046ec54abc82cdb161d28eb578db893dcf2b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Security for isovist 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