Skip to main content

isovist

PyPI version Python versions CI License: MIT

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.1},
  url     = {https://github.com/YusufEminoglu/isovist_sdk}
}

License

MIT © 2026 Yusuf Eminoğlu. See LICENSE.

Metadata

Release files for isovist 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 isovist 0.1.1
File Size Uploaded Provenance Actions
isovist-0.1.1.tar.gz 43.4 kB With provenance Details for isovist-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 74.9 kB

Release files / isovist-0.1.1.tar.gz

Download URL isovist-0.1.1.tar.gz
Size 43.4 kB
Tags Source
SHA-256 checksum
How to use checksums
4997573115c54e0fabb216ef0ea2b491200f86c3d347cab35422560578d9b6fb
BLAKE2b-256 checksum
How to use checksums
dd029c9bafc489fcdea7313c92bf60329f4b236b87bf9af73c5e0ea969e2b4d8
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 / isovist-0.1.1-py3-none-any.whl

Download URL isovist-0.1.1-py3-none-any.whl
Size 31.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3e11aa6549aeed539b52ecef6f7b699ebf411b7d63a82a43936138407b8b1da5
BLAKE2b-256 checksum
How to use checksums
6d5d3b9ddb4b51fcbd44170cc837f061a8a11bce65b467ceddfa2427eee0dee4
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 isovist 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 isovist-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