pathviz 0.1.0__tar.gz

pathviz-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/

pathviz-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matej Jelisavac
+
+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.

pathviz-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: pathviz
+Version: 0.1.0
+Summary: Maze generation, pathfinding and visualisation connected only by a plain adjacency list
+Project-URL: Source, https://github.com/matejjelisavac/PathfindingVisualizer
+Project-URL: Issues, https://github.com/matejjelisavac/PathfindingVisualizer/issues
+Author-email: Matej Jelisavac <matej.jelisavac@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: astar,dijkstra,maze,pathfinding,visualisation
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: pygame>=2.6
+Description-Content-Type: text/markdown
+
+# pathviz
+
+Generate mazes, run pathfinding algorithms on them, and watch the search happen.
+
+Maze generation, search and drawing are three independent modules. The only thing
+they share is a plain adjacency list, `dict[(x, y), set[(x, y)]]`, so you can use
+any one of them without the other two, and drop your own algorithm in anywhere.
+
+## Install
+
+```bash
+pip install pathviz
+```
+
+pygame comes with it, for the visualiser. Everything else is standard library.
+
+## A path
+
+```python
+from pathviz.maze import recursive_backtracker
+from pathviz.search import astar
+
+maze = recursive_backtracker(40, 40, braid=0.2)
+path = astar((0, 0), (39, 39), maze)
+```
+
+`braid` is the fraction of dead ends removed, so `0` is a perfect maze with exactly
+one route between any two cells, and `1` is a maze with no dead ends at all.
+
+## Watching it search
+
+Every algorithm has a `_steps` twin that yields one `Step` per expansion instead of
+returning a path. You write the loop, so what gets drawn is entirely up to you:
+
+```python
+from pathviz.maze import recursive_backtracker
+from pathviz.search import astar_steps, trace_path
+from pathviz.visualizer import Visualizer
+
+maze = recursive_backtracker(60, 60, braid=0.2)
+start, end = (0, 0), (59, 59)
+
+vis = Visualizer(maze)
+vis.draw_maze()
+
+for step in astar_steps(start, end, maze):
+    vis.fill_cell(step.current, "Blue")
+    vis.present()
+
+for coord in trace_path(step.predecessors, end):
+    vis.fill_cell(coord, "Orange")
+vis.present()
+vis.sleep(2000)
+```
+
+Drawing writes to a surface and nothing appears until `present()`, so one frame can
+be built from as many `fill_cell` calls as you like.
+
+A `Step` carries `current`, `discovered` (the cells first reached this expansion),
+and live references to the search's own `distances` and `predecessors`. Reading them
+is free, but they mutate as the search runs, so copy anything you want to keep.
+
+## Your own algorithm
+
+Nothing in pathviz requires a `Step`. Yield whatever you measure and draw it however
+you want. The visualiser only ever sees coordinates and colours:
+
+```python
+from collections import deque
+
+def bfs(start, end, adjacency_list):
+    queue, seen = deque([start]), {start}
+    while queue:
+        current = queue.popleft()
+        yield current, len(queue)          # your own shape
+        if current == end:
+            return
+        for neighbor in adjacency_list[current]:
+            if neighbor not in seen:
+                seen.add(neighbor)
+                queue.append(neighbor)
+
+for current, fringe_size in bfs(start, end, maze):
+    vis.fill_cell(current, (0, min(fringe_size * 8, 255), 120))
+    vis.present()
+```
+
+The same is true going the other way: any `dict[node, set[node]]` works as input, so
+`astar` and `dijkstra` will run on a graph that has nothing to do with a grid.
+
+## Modules
+
+| Module | What it does | Depends on |
+| --- | --- | --- |
+| `pathviz.graph` | `GridGraph`, used to build an adjacency list | stdlib only |
+| `pathviz.maze` | `recursive_backtracker`, `fully_connected` | `pathviz.graph` |
+| `pathviz.search` | `dijkstra`, `astar`, their `_steps` twins, `trace_path` | stdlib only |
+| `pathviz.visualizer` | `Visualizer`, draws mazes, cells and numbers | `pygame` |
+
+Nothing is re-exported from the top level, so importing one module doesn't drag in
+the others. `pathviz.search` imports nothing but the standard library, and code that
+never touches `pathviz.visualizer` never loads pygame.
+
+Both import forms work, whichever reads better where you are:
+
+```python
+from pathviz.search import astar          # astar(...)
+from pathviz import search                # search.astar(...)
+```
+
+## Examples
+
+```bash
+python examples/animate.py
+```

pathviz-0.1.0/README.md

@@ -0,0 +1,115 @@
+# pathviz
+
+Generate mazes, run pathfinding algorithms on them, and watch the search happen.
+
+Maze generation, search and drawing are three independent modules. The only thing
+they share is a plain adjacency list, `dict[(x, y), set[(x, y)]]`, so you can use
+any one of them without the other two, and drop your own algorithm in anywhere.
+
+## Install
+
+```bash
+pip install pathviz
+```
+
+pygame comes with it, for the visualiser. Everything else is standard library.
+
+## A path
+
+```python
+from pathviz.maze import recursive_backtracker
+from pathviz.search import astar
+
+maze = recursive_backtracker(40, 40, braid=0.2)
+path = astar((0, 0), (39, 39), maze)
+```
+
+`braid` is the fraction of dead ends removed, so `0` is a perfect maze with exactly
+one route between any two cells, and `1` is a maze with no dead ends at all.
+
+## Watching it search
+
+Every algorithm has a `_steps` twin that yields one `Step` per expansion instead of
+returning a path. You write the loop, so what gets drawn is entirely up to you:
+
+```python
+from pathviz.maze import recursive_backtracker
+from pathviz.search import astar_steps, trace_path
+from pathviz.visualizer import Visualizer
+
+maze = recursive_backtracker(60, 60, braid=0.2)
+start, end = (0, 0), (59, 59)
+
+vis = Visualizer(maze)
+vis.draw_maze()
+
+for step in astar_steps(start, end, maze):
+    vis.fill_cell(step.current, "Blue")
+    vis.present()
+
+for coord in trace_path(step.predecessors, end):
+    vis.fill_cell(coord, "Orange")
+vis.present()
+vis.sleep(2000)
+```
+
+Drawing writes to a surface and nothing appears until `present()`, so one frame can
+be built from as many `fill_cell` calls as you like.
+
+A `Step` carries `current`, `discovered` (the cells first reached this expansion),
+and live references to the search's own `distances` and `predecessors`. Reading them
+is free, but they mutate as the search runs, so copy anything you want to keep.
+
+## Your own algorithm
+
+Nothing in pathviz requires a `Step`. Yield whatever you measure and draw it however
+you want. The visualiser only ever sees coordinates and colours:
+
+```python
+from collections import deque
+
+def bfs(start, end, adjacency_list):
+    queue, seen = deque([start]), {start}
+    while queue:
+        current = queue.popleft()
+        yield current, len(queue)          # your own shape
+        if current == end:
+            return
+        for neighbor in adjacency_list[current]:
+            if neighbor not in seen:
+                seen.add(neighbor)
+                queue.append(neighbor)
+
+for current, fringe_size in bfs(start, end, maze):
+    vis.fill_cell(current, (0, min(fringe_size * 8, 255), 120))
+    vis.present()
+```
+
+The same is true going the other way: any `dict[node, set[node]]` works as input, so
+`astar` and `dijkstra` will run on a graph that has nothing to do with a grid.
+
+## Modules
+
+| Module | What it does | Depends on |
+| --- | --- | --- |
+| `pathviz.graph` | `GridGraph`, used to build an adjacency list | stdlib only |
+| `pathviz.maze` | `recursive_backtracker`, `fully_connected` | `pathviz.graph` |
+| `pathviz.search` | `dijkstra`, `astar`, their `_steps` twins, `trace_path` | stdlib only |
+| `pathviz.visualizer` | `Visualizer`, draws mazes, cells and numbers | `pygame` |
+
+Nothing is re-exported from the top level, so importing one module doesn't drag in
+the others. `pathviz.search` imports nothing but the standard library, and code that
+never touches `pathviz.visualizer` never loads pygame.
+
+Both import forms work, whichever reads better where you are:
+
+```python
+from pathviz.search import astar          # astar(...)
+from pathviz import search                # search.astar(...)
+```
+
+## Examples
+
+```bash
+python examples/animate.py
+```

pathviz-0.1.0/examples/animate.py

@@ -0,0 +1,32 @@
+from pathviz import maze, search
+from pathviz.visualizer import Visualizer
+
+
+def animate(adjacency_list, start, end, steps):
+	vis = Visualizer(adjacency_list, 800, 1000)
+	vis.draw_maze()
+	vis.fill_cell(start, "Orange")
+	vis.fill_cell(end, "Orange")
+	vis.present()
+
+	for step in steps:
+		vis.fill_cell(step.current, (100, min(step.distances[step.current], 255), 100))
+		vis.present()
+
+	# predecessors is live, so the last step already holds the finished search
+	for coord in search.trace_path(step.predecessors, end):
+		vis.fill_cell(coord, "Orange")
+	vis.present()
+
+	vis.sleep(250)
+
+
+if __name__ == "__main__":
+	width = 120
+	height = 120
+	start, end = (0,0), (width-1, height-1)
+
+	adjacency_list = maze.recursive_backtracker(width, height, 1)
+
+	animate(adjacency_list, start, end, search.astar_steps(start, end, adjacency_list))
+	animate(adjacency_list, start, end, search.dijkstra_steps(start, end, adjacency_list))

pathviz-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pathviz"
+dynamic = ["version"]
+description = "Maze generation, pathfinding and visualisation connected only by a plain adjacency list"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Matej Jelisavac", email = "matej.jelisavac@gmail.com" }]
+keywords = ["pathfinding", "astar", "dijkstra", "maze", "visualisation"]
+classifiers = [
+	"Programming Language :: Python :: 3",
+	"Operating System :: OS Independent",
+	"Topic :: Scientific/Engineering :: Visualization",
+	"Intended Audience :: Education",
+]
+
+dependencies = ["pygame>=2.6"]
+
+[project.urls]
+Source = "https://github.com/matejjelisavac/PathfindingVisualizer"
+Issues = "https://github.com/matejjelisavac/PathfindingVisualizer/issues"
+
+[tool.hatch.version]
+path = "src/pathviz/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pathviz"]

pathviz-0.1.0/src/pathviz/__init__.py

@@ -0,0 +1,11 @@
+"""Maze generation, pathfinding and visualisation, connected only by a plain
+adjacency list: dict[Coord, set[Coord]].
+
+Nothing is re-exported here on purpose. Import the module you want and you pay
+for that one alone:
+
+	from pathviz import maze, search
+	from pathviz.visualizer import Visualizer
+"""
+
+__version__ = "0.1.0"

pathviz-0.1.0/src/pathviz/graph.py

@@ -0,0 +1,25 @@
+Coord = tuple[int, int]
+
+class GridGraph:
+	width: int
+	height: int
+	adjacency_list: dict[Coord, set[Coord]]
+
+
+	def __init__(self, width, height, adjacency_list):
+		self.width, self.height, self.adjacency_list = width, height, adjacency_list
+
+	@classmethod
+	def empty(cls, width, height):
+		nodes = [(x, y) for x in range(width) for y in range(height)]
+		return cls(width, height, {n: set() for n in nodes})
+
+	def add_edge(self, a, b):
+		# sets make a repeated edge a no-op rather than a duplicate
+		self.adjacency_list[a].add(b)
+		self.adjacency_list[b].add(a)
+
+	def grid_neighbors(self, node):   # adjacent in space — what generators consider
+		x, y = node
+		return [(nx, ny) for nx, ny in ((x, y-1), (x-1, y), (x+1, y), (x, y+1))
+				if 0 <= nx < self.width and 0 <= ny < self.height]

pathviz-0.1.0/src/pathviz/maze.py

@@ -0,0 +1,45 @@
+from random import choice, sample
+
+from . import graph
+
+def recursive_backtracker(width, height, braid=0):
+
+	gr = graph.GridGraph.empty(width, height)
+
+	current = choice(list(gr.adjacency_list.keys()))
+	path, visited = [current], set([current])
+
+	while path:
+		neighbors = gr.grid_neighbors(current)
+		candidates = [neighbor for neighbor in neighbors if neighbor not in visited]
+
+		# If all neighbors already visited then backtrack
+		if not candidates:
+			visited.add(current)
+			current = path.pop()
+
+		# Otherwise, if at least 1 neighbor not visited
+		else:
+			next = choice(candidates)
+			gr.add_edge(current, next)
+			visited.add(current)
+			path.append(current)
+			current = next
+
+	# braid = fraction of dead ends removed, sampled uniformly at random.
+	# Snapshot the population first so the denominator can't shift as we add edges.
+	dead_ends = [coord for coord in gr.adjacency_list if len(gr.adjacency_list[coord]) == 1]
+
+	for coord in sample(dead_ends, round(braid * len(dead_ends))):
+		options = [neighbor for neighbor in gr.grid_neighbors(coord) if neighbor not in gr.adjacency_list[coord]]
+		if options:
+			gr.add_edge(coord, choice(options))
+
+	return gr.adjacency_list
+
+def fully_connected(width, height):
+	gr = graph.GridGraph.empty(width, height)
+	for coord in gr.adjacency_list:
+		for neighbor in gr.grid_neighbors(coord):
+			gr.add_edge(coord, neighbor)
+	return gr.adjacency_list

pathviz-0.1.0/src/pathviz/search.py

@@ -0,0 +1,89 @@
+from collections import deque
+from heapq import heappop, heappush
+from typing import NamedTuple
+from collections.abc import Callable
+
+Coord = tuple[int, int]
+AdjacencyList = dict[Coord, set[Coord]]
+
+
+class Step(NamedTuple):
+	current: Coord
+	discovered: list[Coord]                   # only this step's, freshly built
+	distances: dict[Coord, int]               # the search's own dicts, shared by
+	predecessors: dict[Coord, Coord | None]   # every step and mutated as it runs
+
+
+def trace_path(predecessors: dict[Coord, Coord | None], end: Coord) -> list[Coord]:
+	if end not in predecessors:
+		return []
+
+	path = list[Coord]()
+	curr = end
+	while curr is not None:
+		path.append(curr)
+		curr = predecessors[curr]
+
+	path.reverse()
+	return path
+
+
+def _search(start: Coord, end: Coord, adjacency_list: AdjacencyList, heuristic: Callable[[Coord], float]):
+
+	current = start
+	distances = dict[Coord, int]({start: 0})
+	queue = []
+	walked = set[Coord]()
+	predecessors = {start: None}
+
+	while True:
+
+		discovered = list[Coord]()
+
+		walked.add(current)
+		for neighbor in adjacency_list[current]:
+			if neighbor in walked:
+				continue
+			new_dist = distances[current] + 1
+			if neighbor not in distances or new_dist < distances[neighbor]:
+				discovered.append(neighbor)
+				distances[neighbor] = new_dist
+				# store g, prioritise by f = g + h
+				heappush(queue, (new_dist + heuristic(neighbor), -new_dist, neighbor))
+				predecessors[neighbor] = current
+
+		# yield before exiting so the goal expansion is the final frame
+		yield Step(current, discovered, distances, predecessors)
+
+		if current == end or not queue:
+			return
+
+		_weight, _tiebreak, current = heappop(queue)
+
+
+def _manhattan(end: Coord):
+	return lambda node: abs(end[0] - node[0]) + abs(end[1] - node[1])
+
+
+def _drain(steps, end: Coord) -> list[Coord]:
+	# maxlen=1 consumes at C speed, keeping only the finished search's state
+	last = deque(steps, maxlen=1)
+	return trace_path(last[0].predecessors, end) if last else []
+
+
+# *_steps yields a Step per expansion; the bare name just returns the path
+
+def dijkstra_steps(start: Coord, end: Coord, adjacency_list: AdjacencyList):
+	yield from _search(start, end, adjacency_list, lambda _: 0)
+
+
+def astar_steps(start: Coord, end: Coord, adjacency_list: AdjacencyList):
+	yield from _search(start, end, adjacency_list, _manhattan(end))
+
+
+def dijkstra(start: Coord, end: Coord, adjacency_list: AdjacencyList) -> list[Coord]:
+	return _drain(dijkstra_steps(start, end, adjacency_list), end)
+
+
+def astar(start: Coord, end: Coord, adjacency_list: AdjacencyList) -> list[Coord]:
+	return _drain(astar_steps(start, end, adjacency_list), end)

pathviz-0.1.0/src/pathviz/visualizer.py

@@ -0,0 +1,80 @@
+import os as _os
+
+# pygame greets stdout on import unless this exists; it checks for the name, not a value
+_os.environ.setdefault("PYGAME_HIDE_SUPPORT_PROMPT", "1")
+
+import pygame as _pygame
+
+Coord = tuple[int, int]
+RGBValue = tuple[int,int,int]
+
+class Visualizer:
+	bg = "White"
+	wall = "Black"
+	font_color = "Black"
+
+	def __init__(self, adjacency_list, display_size=800, fps=60):
+		self.adjacency_list = adjacency_list
+		self.width  = max(x for x, _ in adjacency_list) + 1
+		self.height = max(y for _, y in adjacency_list) + 1
+		self.cell_size = round(display_size / max(self.width, self.height))
+
+		_pygame.init()
+		self.sc = _pygame.display.set_mode(
+			(self.width * self.cell_size, self.height * self.cell_size))
+		self.fps = fps
+		self._clock = _pygame.time.Clock()
+		self._font = _pygame.font.SysFont('Comic Sans MS', max(1, self.cell_size // 4))
+		# walls live on their own transparent layer so fills can't cover them
+		self._wall_surface = _pygame.Surface(self.sc.get_size(), _pygame.SRCALPHA)
+
+	# Drawing only writes to the surface; call present() to show a finished
+	# frame, so any number of draw calls can make up one frame.
+	def present(self):
+		for event in _pygame.event.get():
+			if event.type == _pygame.QUIT:
+				_pygame.quit()
+				raise SystemExit
+		self.sc.blit(self._wall_surface, (0, 0))
+		_pygame.display.flip()
+		self._clock.tick(self.fps)
+
+	def _get_cell(self, coords):
+		x,y = coords
+		left, top = x * self.cell_size, y * self.cell_size #a coordinate points to top left of the cell
+		right, bottom = left + self.cell_size, top + self.cell_size
+		return top, left, right, bottom
+
+	def draw_maze(self):
+		self.sc.fill(self.bg)
+		for coord in self.adjacency_list:
+			top, left, right, bottom = self._get_cell(coord)
+			neighbors = self.adjacency_list[coord]
+
+			# an unconnected neighbor means a wall on that side
+			x, y = coord
+			walls = (
+				((x, y - 1), (left, top), (right, top)),     #Move up
+				((x - 1, y), (left, top), (left, bottom)),   #Move left
+				((x + 1, y), (right, top), (right, bottom)),  #Move right
+				((x, y + 1), (left, bottom), (right, bottom)),  #Move down
+			)
+
+			for neighbor, start, end in walls:
+				if neighbor not in neighbors:
+					_pygame.draw.line(self._wall_surface, self.wall, start, end)
+
+	def fill_cell(self, coord: Coord, color: str | RGBValue):
+		top, left, _, _ = self._get_cell(coord)
+		_pygame.draw.rect(self.sc, color, (left, top, self.cell_size, self.cell_size))
+
+	def draw_number(self, coord: Coord, number):
+		top, left, _, _ = self._get_cell(coord)
+		text_surface = self._font.render(str(number), False, _pygame.Color(self.font_color))
+		self.sc.blit(text_surface, (left+self.cell_size/2, top+self.cell_size/2))
+
+	def sleep(self, ms):
+		# holds the last presented frame, staying responsive to window events
+		start = _pygame.time.get_ticks()
+		while _pygame.time.get_ticks() - start < ms:
+			self.present()