isovist 0.1.0__tar.gz

isovist-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- `Environment` of obstacle polygons (with holes, overlaps allowed) and an optional
+  enclosing boundary; exact point location with a data-scaled tolerance.
+- Exact isovist polygon by an angular sweep over critical directions (edge endpoints,
+  polygon crossings, view-distance circle crossings, field-of-view limits) with exact
+  ray/edge-line intersections; optional `max_radius`, `fov` and `direction`.
+- Isovist measures with closed-form integrals: area, perimeter, compactness,
+  jaggedness, occlusivity and number of occluding edges, drift (distance and angle),
+  min/max/mean/std radial length.
+- Exact point-to-point intervisibility (corner grazing allowed, interior crossings
+  blocked) and a vectorised intervisibility matrix.
+- Visibility graph analysis on grids or explicit points: connectivity, clustering
+  coefficient, mean depth, relative asymmetry and Hillier-Hanson integration.
+- GeoJSON input/output for projected coordinates; `isovist` command line tool with
+  `compute`, `vga` and `visible` sub-commands.

isovist-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "isovist"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/isovist_sdk"
+url: "https://pypi.org/project/isovist/"
+abstract: "Exact 2D isovists from a viewpoint among obstacle polygons (angular sweep with exact edge intersections, optional view distance and field of view), isovist shape measures (area, perimeter, compactness, occlusivity, drift, radial statistics, jaggedness), exact point-to-point intervisibility and visibility graph analysis (connectivity, clustering coefficient, mean depth, integration), with GeoJSON input/output and a command-line tool."
+keywords:
+  - isovist
+  - visibility graph analysis
+  - space syntax
+  - urban design
+  - gis

isovist-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

isovist-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/isovist/py.typed
+recursive-include src/isovist *.py
+recursive-include tests *.py
+recursive-include examples *.py *.geojson

isovist-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: isovist
+Version: 0.1.0
+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.0},
+  url     = {https://github.com/YusufEminoglu/isovist_sdk}
+}
+```
+
+## License
+
+MIT © 2026 Yusuf Eminoğlu. See [LICENSE](LICENSE).

isovist-0.1.0/README.md

@@ -0,0 +1,223 @@
+# 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.0},
+  url     = {https://github.com/YusufEminoglu/isovist_sdk}
+}
+```
+
+## License
+
+MIT © 2026 Yusuf Eminoğlu. See [LICENSE](LICENSE).

isovist-0.1.0/examples/plaza.geojson

@@ -0,0 +1,104 @@
+{
+ "type": "FeatureCollection",
+ "features": [
+  {
+   "type": "Feature",
+   "properties": {
+    "name": "pavilion west"
+   },
+   "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+     [
+      [
+       15,
+       8
+      ],
+      [
+       27,
+       8
+      ],
+      [
+       27,
+       16
+      ],
+      [
+       15,
+       16
+      ],
+      [
+       15,
+       8
+      ]
+     ]
+    ]
+   }
+  },
+  {
+   "type": "Feature",
+   "properties": {
+    "name": "pavilion east"
+   },
+   "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+     [
+      [
+       34,
+       24
+      ],
+      [
+       46,
+       24
+      ],
+      [
+       46,
+       33
+      ],
+      [
+       34,
+       33
+      ],
+      [
+       34,
+       24
+      ]
+     ]
+    ]
+   }
+  },
+  {
+   "type": "Feature",
+   "properties": {
+    "name": "column"
+   },
+   "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+     [
+      [
+       30,
+       12
+      ],
+      [
+       31,
+       12
+      ],
+      [
+       31,
+       13
+      ],
+      [
+       30,
+       13
+      ],
+      [
+       30,
+       12
+      ]
+     ]
+    ]
+   }
+  }
+ ]
+}