A previous release had provenance metadata, but this release does not. View details.
isovist
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
isovistcommand-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 ofknodes, from breadth-first search. - relative asymmetry is
RA = 2(MD−1)/(k−2). - integration is
D_k / RA, withD_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 × nmatrix: a few thousand points is practical, but tens of thousands is not. Use a coarser grid, a sub-area ormax_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 = 0and integrationinf(written asnull). - Geometric tolerance defaults to
1e-9 ×the extent of the data. PassEnvironment(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}
}
Related Geophilo SDKs
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.