seevol 0.1.0__tar.gz

seevol-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+tests/* linguist-vendored
+benchmarks/* linguist-vendored

seevol-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+uv-cheatsheet.md
+__pycache__
+.venv
+/build
+initial_trials/
+*.npy
+.DS_Store
+benchmarks/

seevol-0.1.0/CMakeLists.txt

@@ -0,0 +1,33 @@
+cmake_minimum_required(VERSION 3.15)
+project(seevol)
+
+# C++ 17 standard
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# require pybind  
+find_package(pybind11 REQUIRED)
+
+# create module from .cpp
+pybind11_add_module(voxel_occlusion src/seevol/occlusion.cpp)
+
+# for multi-threading the hot loop in is_visible:
+# macOS: auto-locate Homebrew's libomp (no-op elsewhere)
+if(APPLE)
+    execute_process(COMMAND brew --prefix libomp
+                    OUTPUT_VARIABLE HOMEBREW_LIBOMP
+                    OUTPUT_STRIP_TRAILING_WHITESPACE
+                    ERROR_QUIET)
+    if(HOMEBREW_LIBOMP)
+        list(APPEND CMAKE_PREFIX_PATH "${HOMEBREW_LIBOMP}")
+    endif()
+endif()
+find_package(OpenMP)
+if(OpenMP_CXX_FOUND)
+    target_link_libraries(voxel_occlusion PRIVATE OpenMP::OpenMP_CXX)
+else()
+    message(WARNING "OpenMP not found: building serial (non-threaded and slower) version. Please install!")
+endif()
+
+# once compiled so an .so, add to the seevol package folder  
+install(TARGETS voxel_occlusion DESTINATION seevol)

seevol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Archie Benn]
+
+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.

seevol-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: seevol
+Version: 0.1.0
+Summary: All-pairs visibility analysis on voxel volumes (Amanatides & Woo, C++)
+Author-Email: Archie Benn <sj19031@bristol.ac.uk>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Project-URL: Repository, https://github.com/archiebenn/seeVol
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: pyvista
+Description-Content-Type: text/markdown
+
+# seeVol
+
+<p align="center">
+  <img src="images/readme_banner.png" alt="3D visualisation of an artificial ant nest volume coloured by voxel visibility" width="800">
+</p>
+
+`seevol` analyses line-of-sight visibility in 3D binary volumes, where 0 represents a solid/opaque voxel, and 1 represents open/transparent voxels. 
+
+The core functionality is based on the Amanatides & Woo voxel traversal algorithm <sup>1</sup> and is implemented in C++ to compute straight line visibility between all pairs of open (non solid) voxels in a given volume.  
+
+This tool tests visibility between **all** open pairs throughout the volume, which permits per-voxel visibility analysis metrics to be calculated downstream for every open voxel.
+
+> [!WARNING]
+> `seevol` computes all-pairs visibility, which scales as O(open_voxels<sup>2</sup>). This becomes slow or memory-limiting beyond a few hundred thousand open voxels — see [Limitations](#limitations) before running on large volumes. Downsampling the volume is likely to help but will impact results.  
+
+## Dependencies
+
+A C++17 or greater build toolchain is required for source installation, alongside Python >=3.10.  
+
+Pyvista is a dependency for visualisations of the visibility metrics output onto the 3D volume itself (see [this visual example](examples/visualiser_example.py) for use).
+
+## Installation
+
+To install seevol:
+
+```bash
+pip install seevol
+```
+
+or for uv users:
+
+```bash
+uv pip install seevol
+```
+
+## Usage
+
+The core function `visible_pairs()` accepts a 3D binary (0 = solid, 1 = open) NumPy array as input and outputs two NumPy arrays:
+
+- `coords` — shape (N, 3), the open voxel coordinates in the volume  
+- `edges` — shape (M, 2), pairs of indices into `coords` for voxels that are mutually visible  
+
+For example, if `edges[0]` is `[2, 7]`,the visibility edge connects `coords[2]` and `coords[7]` and these two voxels are visible to each other via direct line of sight.  
+
+Users can load .npy files in Python using `np.load()` and pass the result to `visible_pairs()`.  
+
+Downstream analyses or visualisations are then possible from this output, such as visualising a 'visibility heatmap' using Pyvista (see below) 
+
+## Limitations  
+
+This tool currently uses all-pair calculation using voxel ray traversal. Because of this, the ray traversal algorithm scales as O(open_voxels<sup>2</sup>) and is therefore quickly unusable for large volumes.  
+
+A hard limit is imposed in the C++ source file which limits open voxels to 1,000,000. In reality, volumes with over 500,000 open voxels are likely to significant memory issues as very large visible edges will be stored. Methods to reduce this runtime will hopefully be introduced over time.
+
+## Minimal example
+
+The [quickstart example](examples/quickstart.py) creates a small volume of open voxels with one solid voxel blocking visibility:
+
+```python
+import numpy as np
+import seevol 
+
+# 1 = open, 0 = solid
+volume = np.ones((3, 3, 3), dtype=np.uint8)
+
+# adds an obstruction
+volume[1, 1, 1] = 0  
+
+# calculate pairwise voxel visibility
+coords, edges = seevol.visible_pairs(volume)
+
+print(f"{len(coords)} open voxels containing {len(edges)} visible pairs")
+```
+
+It prints the number of open voxels and visible pairs:
+
+```
+26 open voxels containing 214 visible pairs
+```
+
+### Using .npy files 
+
+> [!IMPORTANT]
+> NumPy array volumes as .npy files must be 3D and contain binary values, with 0 = solid and 1 = open voxels.
+
+To import your own 3D NumPy volume and calculate visibility as with the above example:
+
+```python
+import numpy as np
+import seevol 
+
+# load your own 3D NumPy volume: 0 = solid, 1 = open
+volume = np.load("my_volume.npy")
+
+# calculate pairwise voxel visibility
+coords, edges = seevol.visible_pairs(volume)
+
+print(f"{len(coords)} open voxels containing {len(edges)} visible pairs")
+```
+
+## Visualisation examples on large artificial volumes
+
+Below shows an example output of the visibility score per voxel as a heatmap within an intricate 150x150x150 volume, generated using `tunnel_excavator()` to mimic an ant-nest structure and visualised with Pyvista using `visibility_visualiser()`:  
+
+![150_cubed](images/realistic_nest.png "150^3 ant excavation example volume")
+
+A visibility scored volume using a generated `porespy` volume:
+
+![150_cubed](images/porespy.png "150^3 ant excavation example volume")
+
+
+## References
+
+> 1. Amanatides, J., & Woo, A. (1987, August). A fast voxel traversal algorithm for ray tracing. In Eurographics (Vol. 87, No. 3, pp. 3-10).
+
+

seevol-0.1.0/README.md

@@ -0,0 +1,116 @@
+# seeVol
+
+<p align="center">
+  <img src="images/readme_banner.png" alt="3D visualisation of an artificial ant nest volume coloured by voxel visibility" width="800">
+</p>
+
+`seevol` analyses line-of-sight visibility in 3D binary volumes, where 0 represents a solid/opaque voxel, and 1 represents open/transparent voxels. 
+
+The core functionality is based on the Amanatides & Woo voxel traversal algorithm <sup>1</sup> and is implemented in C++ to compute straight line visibility between all pairs of open (non solid) voxels in a given volume.  
+
+This tool tests visibility between **all** open pairs throughout the volume, which permits per-voxel visibility analysis metrics to be calculated downstream for every open voxel.
+
+> [!WARNING]
+> `seevol` computes all-pairs visibility, which scales as O(open_voxels<sup>2</sup>). This becomes slow or memory-limiting beyond a few hundred thousand open voxels — see [Limitations](#limitations) before running on large volumes. Downsampling the volume is likely to help but will impact results.  
+
+## Dependencies
+
+A C++17 or greater build toolchain is required for source installation, alongside Python >=3.10.  
+
+Pyvista is a dependency for visualisations of the visibility metrics output onto the 3D volume itself (see [this visual example](examples/visualiser_example.py) for use).
+
+## Installation
+
+To install seevol:
+
+```bash
+pip install seevol
+```
+
+or for uv users:
+
+```bash
+uv pip install seevol
+```
+
+## Usage
+
+The core function `visible_pairs()` accepts a 3D binary (0 = solid, 1 = open) NumPy array as input and outputs two NumPy arrays:
+
+- `coords` — shape (N, 3), the open voxel coordinates in the volume  
+- `edges` — shape (M, 2), pairs of indices into `coords` for voxels that are mutually visible  
+
+For example, if `edges[0]` is `[2, 7]`,the visibility edge connects `coords[2]` and `coords[7]` and these two voxels are visible to each other via direct line of sight.  
+
+Users can load .npy files in Python using `np.load()` and pass the result to `visible_pairs()`.  
+
+Downstream analyses or visualisations are then possible from this output, such as visualising a 'visibility heatmap' using Pyvista (see below) 
+
+## Limitations  
+
+This tool currently uses all-pair calculation using voxel ray traversal. Because of this, the ray traversal algorithm scales as O(open_voxels<sup>2</sup>) and is therefore quickly unusable for large volumes.  
+
+A hard limit is imposed in the C++ source file which limits open voxels to 1,000,000. In reality, volumes with over 500,000 open voxels are likely to significant memory issues as very large visible edges will be stored. Methods to reduce this runtime will hopefully be introduced over time.
+
+## Minimal example
+
+The [quickstart example](examples/quickstart.py) creates a small volume of open voxels with one solid voxel blocking visibility:
+
+```python
+import numpy as np
+import seevol 
+
+# 1 = open, 0 = solid
+volume = np.ones((3, 3, 3), dtype=np.uint8)
+
+# adds an obstruction
+volume[1, 1, 1] = 0  
+
+# calculate pairwise voxel visibility
+coords, edges = seevol.visible_pairs(volume)
+
+print(f"{len(coords)} open voxels containing {len(edges)} visible pairs")
+```
+
+It prints the number of open voxels and visible pairs:
+
+```
+26 open voxels containing 214 visible pairs
+```
+
+### Using .npy files 
+
+> [!IMPORTANT]
+> NumPy array volumes as .npy files must be 3D and contain binary values, with 0 = solid and 1 = open voxels.
+
+To import your own 3D NumPy volume and calculate visibility as with the above example:
+
+```python
+import numpy as np
+import seevol 
+
+# load your own 3D NumPy volume: 0 = solid, 1 = open
+volume = np.load("my_volume.npy")
+
+# calculate pairwise voxel visibility
+coords, edges = seevol.visible_pairs(volume)
+
+print(f"{len(coords)} open voxels containing {len(edges)} visible pairs")
+```
+
+## Visualisation examples on large artificial volumes
+
+Below shows an example output of the visibility score per voxel as a heatmap within an intricate 150x150x150 volume, generated using `tunnel_excavator()` to mimic an ant-nest structure and visualised with Pyvista using `visibility_visualiser()`:  
+
+![150_cubed](images/realistic_nest.png "150^3 ant excavation example volume")
+
+A visibility scored volume using a generated `porespy` volume:
+
+![150_cubed](images/porespy.png "150^3 ant excavation example volume")
+
+
+## References
+
+> 1. Amanatides, J., & Woo, A. (1987, August). A fast voxel traversal algorithm for ray tracing. In Eurographics (Vol. 87, No. 3, pp. 3-10).
+
+

seevol-0.1.0/examples/quickstart.py

@@ -0,0 +1,17 @@
+# quickstart.py - minimal python example of seevol 
+# date: 02-11-2026
+# author: Archie Benn sj19031@bristol.ac.uk 
+
+import numpy as np
+import seevol 
+
+# 1 = open, 0 = solid
+volume = np.ones((3, 3, 3), dtype=np.uint8)
+
+# adds an obstruction
+volume[1, 1, 1] = 0  
+
+# calculate pairwise voxel visibility
+coords, edges = seevol.visible_pairs(volume)
+
+print(f"{len(coords)} open voxels containing {len(edges)} visible pairs")

seevol-0.1.0/examples/visualiser_example.py

@@ -0,0 +1,11 @@
+# example.py - imports functions to view visibility scored in 3D excavated space  
+# date: 02-11-2026
+# author: Archie Benn sj19031@bristol.ac.uk
+
+import seevol
+
+# create example NumPy volume with excavator
+example_nest = seevol.tunnel_excavator(size=180, seed=14, n_steps=18000, branch_prob=1e-5, radius=1)
+
+# view visibility in pyvista window
+seevol.visibility_visualiser(example_nest, verbose=True)

seevol-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["scikit-build-core", "pybind11"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "seevol"
+version = "0.1.0"
+authors = [
+  { name="Archie Benn", email="sj19031@bristol.ac.uk" },
+]
+description = "All-pairs visibility analysis on voxel volumes (Amanatides & Woo, C++)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: C++",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = ["numpy", "pyvista"]
+
+[project.urls]
+Repository = "https://github.com/archiebenn/seeVol"
+
+[tool.scikit-build]
+wheel.packages = ["src/seevol"]
+sdist.exclude = ["tests", "development_log.md", "uv-cheatsheet.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+]

seevol-0.1.0/src/seevol/__init__.py

@@ -0,0 +1,11 @@
+from .generator import tunnel_excavator
+from .voxel_occlusion import get_voxel_value, is_visible, visible_pairs
+from .visualiser import visibility_visualiser
+
+__all__ = [
+    "get_voxel_value",
+    "is_visible",
+    "tunnel_excavator",
+    "visible_pairs",
+    "visibility_visualiser",
+]

seevol-0.1.0/src/seevol/generator.py

@@ -0,0 +1,74 @@
+# generator.py - generates example volumes to simulate ant nest excavations and intricate structures
+# date: 28-10-2026  
+# author: Archie Benn sj19031@bristol.ac.uk 
+
+import numpy as np
+import random
+
+def tunnel_excavator(size = 100, n_steps = 20000, branch_prob = 1e-5, radius = 1, seed=0):
+    """
+    Creates empty grid volume (default volume 100^3 voxels).
+
+    Produces a volume with fully-connected and randomly carved tunnels within that grid volume.
+    """
+
+    rng = random.Random(seed)
+
+    # fill size^3 volume with 0s (represents solid/non-open e.g soil within an excavated ant nest)
+    vol = np.zeros((size,size,size), dtype=np.uint8)
+
+    def excavate(position):
+        """
+        Takes current position and excavates by the radius provided (radius = 1 -> 3x3 excavation). 
+        
+        Sets 'excavated' voxel cells to 1.
+        """
+
+        # get current coordinates of 'position'
+        x,y,z = position
+        # define low and high positions for carving given radius
+        low = [max(0, x-radius), max(0, y-radius), max(0, z-radius)]
+        high = [min(size, x + radius + 1), min(size, y + radius + 1), min(size, z + radius + 1)]
+
+        # ****actual excavation step i.e. set carved voxel(s) == 1**** 
+        vol[low[0]:high[0], low[1]:high[1], low[2]:high[2]] = 1
+
+    # begin 'excavation' with starting position near top in centre (1 down in y plane)    
+    start = (size //2, size-1, size//2)
+    excavate(start)
+
+    # active walker list (e.g an ant excavating)
+    heads = [start]
+    
+    # apply a slight y and x bias for increased chance of moving down/sideways (more ant-like)  
+    # change these values in each axes to adjust excavation shapes  
+    moves = (
+        [(1,0,0)] * 21 + [(-1,0,0)] * 21 + # x
+        [(0,1,0)] * 20 + [(0,-1,0)] * 22 + # y  
+        [(0,0,1)] * 20 + [(0,0,-1)] * 20 # z
+        )
+
+    for _ in range(n_steps):
+
+        head_idx = rng.randrange(len(heads))
+        x,y,z = heads[head_idx]
+
+        # movement selector
+        dx,dy,dz = rng.choice(moves)
+
+        # new head coordinates after move
+        nx,ny,nz = x + dx, y + dy, z + dz
+
+        # only excavates if the new coordinates are within size of voluem
+        # i.e if new position does not fall outside the defined volume zone 'size'
+        if 0 <= nx < size and 0 <= ny < size and 0 <= nz < size:
+
+            # excavate and move head/ant
+            excavate((nx,ny,nz))
+            heads[head_idx] = (nx,ny,nz)
+
+            # occasionally spawn new branch form current position
+            if rng.random() < branch_prob:
+                heads.append((nx,ny,nz))
+
+    return vol