Metadata-Version: 2.4
Name: isovist
Version: 0.1.1
Summary: Exact 2D isovists, isovist shape measures, point-to-point intervisibility and visibility graph analysis (VGA) for urban design, with GeoJSON in/out and a CLI.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/YusufEminoglu/isovist_sdk
Project-URL: Repository, https://github.com/YusufEminoglu/isovist_sdk
Project-URL: Issues, https://github.com/YusufEminoglu/isovist_sdk/issues
Project-URL: Changelog, https://github.com/YusufEminoglu/isovist_sdk/blob/main/CHANGELOG.md
Keywords: isovist,visibility,visibility-graph-analysis,vga,space-syntax,urban-design,architecture,intervisibility,viewshed,geojson,gis,computational-geometry
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# isovist

[![PyPI version](https://img.shields.io/pypi/v/isovist.svg)](https://pypi.org/project/isovist/)
[![Python versions](https://img.shields.io/pypi/pyversions/isovist.svg)](https://pypi.org/project/isovist/)
[![CI](https://github.com/YusufEminoglu/isovist_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/isovist_sdk/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/isovist_sdk/blob/main/LICENSE)

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

```bash
pip install isovist
```

Requires Python 3.9 or newer.

---

## Quick start (Python)

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

```bash
# 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

```bash
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`):

```bibtex
@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](LICENSE).
