add example for testing with images, first step towards benchmarking

Author: brean

.gitignore

@@ -63,4 +63,6 @@ target/
 .ipynb_checkpoints
 
 # python virtual env
-venv/
+venv/
+
+examples/out.png

README.md

@@ -31,7 +31,13 @@ see [pathfinding on pypi](https://pypi.org/project/pathfinding/)
 
 ## Usage examples
 
-For usage examples with detailed descriptions take a look at the [docs](docs/) folder, also take a look at the [test/](test/) folder for more examples, e.g. how to use pandas
+For usage examples with detailed descriptions take a look at the [docs](docs/) folder, also take a look at the [test/](test/) folder for more examples, e.g. how to use pandas.
+
+*image_pathfinding.py* in the `examples/`-folder provides an example how to load an image with a start and goal point. You can all it with an input and output file like this:
+```
+cd examples/
+python3 image_pathfinding.py -i map.png -o foo.png
+```
 
 ## Rerun the algorithm
 

docs/03_graphs.md

@@ -1,15 +1,15 @@
 # Using a graph
 The default is to plan a path from one node of a grid to another but you can use any graph that has a weight (also known as cost) assigned to its edges.
 
+This is based on the animation at [Wikipedia about Dijkstra's algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm#/media/File:Dijkstra_Animation.gif)
+
 ```python
 from pathfinding.core.diagonal_movement import DiagonalMovement
 from pathfinding.core.graph import Graph
 from pathfinding.core.node import Node
 from pathfinding.finder.dijkstra import DijkstraFinder
 
-# based on the animation at [Wikipedia about Dijkstra's algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm#/media/File:Dijkstra_Animation.gif)
-
-# source node, target node, distance value
+# list values are: source node, target node, distance value
 edges = [
     [1, 2, 7],
     [1, 3, 9],

docs/04_images.md

@@ -0,0 +1,2 @@
+# Working with images as input
+Because its easier to visualize maps as pictures and to manipulate you often want to work on images instead of providing the map as big array.

docs/05_benchmarking.md

@@ -0,0 +1,10 @@
+# Benchmarking
+Many pathfinding algorithms need more system resources the bigger the input grid is, some are optimized for specific scenarios to (for example Jump-Point Search) for narrow passages, while others like Dijkstra are for a general solution that come at the cost of looking at all cells of the grid in the worst case.
+
+## Creating a benchmark
+
+## Record performance and visualize iterations
+
+http://jiffyclub.github.io/snakeviz/
+
+## Memory

examples/README.md

@@ -0,0 +1,10 @@
+# Example implementations using python-pathfinding
+
+## *image_pathfinding.py*
+Create a map from and image and run a path finding algorithm on it (requires PIL/Pillow).
+
+You can all it with an input and output file like this:
+```
+cd examples/
+python3 image_pathfinding.py -i map.png -o foo.png
+```

examples/image_pathfinding.py

@@ -0,0 +1,83 @@
+# Create a Map from an image
+import os
+from pathlib import Path
+import argparse
+
+# Pillow
+from PIL import Image
+
+# pathfinding
+from pathfinding.core.diagonal_movement import DiagonalMovement
+from pathfinding.core.grid import Grid
+from pathfinding.finder.a_star import AStarFinder
+
+
+# image file with the map
+BASE_PATH = Path(os.path.dirname(__file__))
+MAP_FILE = BASE_PATH / "map.png"
+OUT_FILE = BASE_PATH / "out.png"
+# color channel order, defaults to RGB
+RED, GREEN, BLUE = 0, 1, 2
+
+
+def green(pixel: list) -> bool: 
+    """Returns True if the pixel is green (the starting point)"""
+    return pixel[RED] < 10 and pixel[GREEN] > 250 and pixel[BLUE] < 10
+
+
+def red(pixel: list) -> bool:
+    """Returns True if the pixel is red (the goal position)"""
+    return pixel[RED] > 250 and pixel[GREEN] < 10 and pixel[BLUE] < 10
+
+
+def pixel_walkable(pixel, x, y):
+    """returns True if the pixel is walkable."""
+    return any([p > 50 for p in pixel])  # darker pixel are not walkable
+
+
+def main(filename_map: str = MAP_FILE, filename_out: str = OUT_FILE):
+    nodes = []
+    if not Path(filename_map).exists():
+        print(f'File {filename_map} does not exist.')
+        return
+    with Image.open(filename_map) as im:
+        width, height = im.size
+        for y in range(height):
+            nodes.append([])
+            for x in range(width):
+                pixel = im.getpixel((x, y))
+                node = pixel_walkable(pixel[:3], x, y)
+                nodes[y].append(node)
+                if red(pixel):
+                    _goal = (x, y)
+                if green(pixel):
+                    _start = (x, y)
+        grid = Grid(matrix=nodes)
+        end = grid.node(*_goal)
+        start = grid.node(*_start)
+
+        finder = AStarFinder(diagonal_movement=DiagonalMovement.never)
+        path, runs = finder.find_path(start, end, grid)
+
+        # print(grid.grid_str(path=path, end=end, start=start))
+        print('iterations:', runs, 'path length:', len(path))
+        out = im.copy()
+        for p in path[1:-1]:
+            out.putpixel((p.x, p.y), (255, 165, 0))
+        out.save(filename_out)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        prog='image_pathfinding',
+        description='find a path in an image from a green pixel to a red one')
+    parser.add_argument(
+        '-i', '--filename_map',
+        help='input file',
+        default=MAP_FILE)
+    parser.add_argument(
+        '-o', '--filename_out',
+        help='output file',
+        default=OUT_FILE)
+
+    main(**vars(parser.parse_args()))

examples/map.png

@@ -90,7 +90,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "venv",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -104,7 +104,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.6"
+   "version": "3.13.1"
   }
  },
  "nbformat": 4,