pyastar2d 1.1.1__cp39-abi3-macosx_11_0_arm64.whl

pyastar2d/__init__.py

@@ -0,0 +1,3 @@
+from pyastar2d.astar_wrapper import Heuristic, astar_path
+
+__all__ = ['astar_path', 'Heuristic']

pyastar2d/astar_wrapper.py

@@ -0,0 +1,77 @@
+import ctypes
+from enum import IntEnum
+from typing import Optional, Tuple
+
+import numpy as np
+
+import pyastar2d.astar
+
+# Define array types
+ndmat_f_type = np.ctypeslib.ndpointer(dtype=np.float32, ndim=1, flags='C_CONTIGUOUS')
+ndmat_i2_type = np.ctypeslib.ndpointer(dtype=np.int32, ndim=2, flags='C_CONTIGUOUS')
+
+# Define input/output types
+pyastar2d.astar.restype = ndmat_i2_type  # Nx2 (i, j) coordinates or None
+pyastar2d.astar.argtypes = [
+    ndmat_f_type,  # weights
+    ctypes.c_int,  # height
+    ctypes.c_int,  # width
+    ctypes.c_int,  # start index in flattened grid
+    ctypes.c_int,  # goal index in flattened grid
+    ctypes.c_bool,  # allow diagonal
+    ctypes.c_int,  # heuristic_override
+]
+
+
+class Heuristic(IntEnum):
+    """The supported heuristics."""
+
+    DEFAULT = 0
+    ORTHOGONAL_X = 1
+    ORTHOGONAL_Y = 2
+
+
+def astar_path(
+    weights: np.ndarray,
+    start: Tuple[int, int],
+    goal: Tuple[int, int],
+    allow_diagonal: bool = False,
+    heuristic_override: Heuristic = Heuristic.DEFAULT,
+) -> Optional[np.ndarray]:
+    """
+    Run astar algorithm on 2d weights.
+
+    param np.ndarray weights: A grid of weights e.g. np.ones((10, 10), dtype=np.float32)
+    param Tuple[int, int] start: (i, j)
+    param Tuple[int, int] goal: (i, j)
+    param bool allow_diagonal: Whether to allow diagonal moves
+    param Heuristic heuristic_override: Override heuristic, see Heuristic(IntEnum)
+
+    """
+    assert (
+        weights.dtype == np.float32
+    ), f'weights must have np.float32 data type, but has {weights.dtype}'
+    # For the heuristic to be valid, each move must cost at least 1.
+    if weights.min(axis=None) < 1.0:
+        raise ValueError('Minimum cost to move must be 1, but got %f' % (weights.min(axis=None)))
+    # Ensure start is within bounds.
+    if start[0] < 0 or start[0] >= weights.shape[0] or start[1] < 0 or start[1] >= weights.shape[1]:
+        raise ValueError(f'Start of {start} lies outside grid.')
+    # Ensure goal is within bounds.
+    if goal[0] < 0 or goal[0] >= weights.shape[0] or goal[1] < 0 or goal[1] >= weights.shape[1]:
+        raise ValueError(f'Goal of {goal} lies outside grid.')
+
+    height, width = weights.shape
+    start_idx = np.ravel_multi_index(start, (height, width))
+    goal_idx = np.ravel_multi_index(goal, (height, width))
+
+    path = pyastar2d.astar.astar(
+        weights.flatten(),
+        height,
+        width,
+        start_idx,
+        goal_idx,
+        allow_diagonal,
+        int(heuristic_override),
+    )
+    return path

pyastar2d-1.1.1.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: pyastar2d
+Version: 1.1.1
+Summary: A simple implementation of the A* algorithm for path-finding on a two-dimensional grid.
+Home-page: https://github.com/hjweide/pyastar2d
+Author: Hendrik Weideman
+Author-email: hjweide@gmail.com
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: imageio
+Requires-Dist: numpy>=2.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+[![Build Status](https://github.com/hjweide/pyastar2d/actions/workflows/python-publish.yml/badge.svg)](https://github.com/hjweide/pyastar2d/actions/workflows/python-publish.yml)
+[![PyPI version](https://badge.fury.io/py/pyastar2d.svg)](https://badge.fury.io/py/pyastar2d)
+# PyAstar2D
+This is a very simple C++ implementation of the A\* algorithm for pathfinding
+on a two-dimensional grid.  The solver itself is implemented in C++, but is
+callable from Python.  This combines the speed of C++ with the convenience of
+Python.
+
+I have not done any formal benchmarking, but the solver finds the solution to a
+1802 by 1802 maze in 0.29s and a 4008 by 4008 maze in 0.83s when running on my
+nine-year-old Intel(R) Core(TM) i7-2630QM CPU @ 2.00GHz.  See [Example
+Results](#example-results) for more details.
+
+See `src/cpp/astar.cpp` for the core C++ implementation of the A\* shortest
+path search algorithm, `src/pyastar2d/astar_wrapper.py` for the Python wrapper
+and `examples/example.py` for example usage.
+
+When determining legal moves, 4-connectivity is the default, but it is possible
+to set `allow_diagonal=True` for 8-connectivity.
+
+## Installation
+Instructions for installing `pyastar2d` are given below.
+
+### From PyPI
+The easiest way to install `pyastar2d` is directly from the Python package index:
+```
+pip install pyastar2d
+```
+
+### From source
+You can also install `pyastar2d` by cloning this repository and building it
+yourself.  If running on Linux or MacOS, simply run
+```bash
+pip install .
+````
+from the root directory.  If you are using Windows you may have to install Cython manually first:
+```bash
+pip install Cython
+pip install .
+```
+To check that everything worked, run the example:
+```bash
+python examples/example.py
+```
+
+### As a dependency
+Include `pyastar2d` in your `requirements.txt` to install from `pypi`, or add
+this line to `requirements.txt`:
+```
+pyastar2d @ git+git://github.com/hjweide/pyastar2d.git@master#egg=pyastar2d
+```
+
+## Usage
+A simple example is given below:
+```python
+import numpy as np
+import pyastar2d
+# The minimum cost must be 1 for the heuristic to be valid.
+# The weights array must have np.float32 dtype to be compatible with the C++ code.
+weights = np.array([[1, 3, 3, 3, 3],
+                    [2, 1, 3, 3, 3],
+                    [2, 2, 1, 3, 3],
+                    [2, 2, 2, 1, 3],
+                    [2, 2, 2, 2, 1]], dtype=np.float32)
+# The start and goal coordinates are in matrix coordinates (i, j).
+path = pyastar2d.astar_path(weights, (0, 0), (4, 4), allow_diagonal=True)
+print(path)
+# The path is returned as a numpy array of (i, j) coordinates.
+array([[0, 0],
+       [1, 1],
+       [2, 2],
+       [3, 3],
+       [4, 4]])
+```
+Note that all grid points are represented as `(i, j)` coordinates.  An example
+of using `pyastar2d` to solve a maze is given in `examples/maze_solver.py`.
+
+## Example Results
+<a name="example-results"></a>
+To test the implementation, I grabbed two nasty mazes from Wikipedia.  They are
+included in the ```mazes``` directory, but are originally from here:
+[Small](https://upload.wikimedia.org/wikipedia/commons/c/cf/MAZE.png) and
+[Large](https://upload.wikimedia.org/wikipedia/commons/3/32/MAZE_2000x2000_DFS.png).
+I load the ```.png``` files as grayscale images, and set the white pixels to 1
+(open space) and the black pixels to `INF` (walls).
+
+To run the examples specify the input and output files using the `--input` and
+`--output` flags.  For example, the following commands will solve the small and
+large mazes:
+```
+python examples/maze_solver.py --input mazes/maze_small.png --output solns/maze_small.png
+python examples/maze_solver.py --input mazes/maze_large.png --output solns/maze_large.png
+```
+
+### Small Maze (1802 x 1802):
+```bash
+time python examples/maze_solver.py --input mazes/maze_small.png --output solns/maze_small.png
+Loaded maze of shape (1802, 1802) from mazes/maze_small.png
+Found path of length 10032 in 0.292794s
+Plotting path to solns/maze_small.png
+Done
+
+real	0m1.214s
+user	0m1.526s
+sys	0m0.606s
+```
+The solution found for the small maze is shown below:
+<img src="https://github.com/hjweide/pyastar2d/raw/master/solns/maze_small_soln.png" alt="Maze Small Solution" style="width: 100%"/>
+
+### Large Maze (4002 x 4002):
+```bash
+time python examples/maze_solver.py --input mazes/maze_large.png --output solns/maze_large.png
+Loaded maze of shape (4002, 4002) from mazes/maze_large.png
+Found path of length 783737 in 0.829181s
+Plotting path to solns/maze_large.png
+Done
+
+real	0m29.385s
+user	0m29.563s
+sys	0m0.728s
+```
+The solution found for the large maze is shown below:
+<img src="https://github.com/hjweide/pyastar2d/raw/master/solns/maze_large_soln.png" alt="Maze Large Solution" style="width: 100%"/>
+
+## Motivation
+I recently needed an implementation of the A* algorithm in Python to find the
+shortest path between two points in a cost matrix representing an image.
+Normally I would simply use [networkx](https://networkx.github.io/), but for
+graphs with millions of nodes the overhead incurred to construct the graph can
+be expensive.  Considering that I was only interested in graphs that may be
+represented as two-dimensional grids, I decided to implement it myself using
+this special structure of the graph to make various optimizations.
+Specifically, the graph is represented as a one-dimensional array because there
+is no need to store the neighbors.  Additionally, the lookup tables for
+previously-explored nodes (their costs and paths) are also stored as
+one-dimensional arrays.  The implication of this is that checking the lookup
+table can be done in O(1), at the cost of using O(n) memory.  Alternatively, we
+could store only the nodes we traverse in a hash table to reduce the memory
+usage.  Empirically I found that replacing the one-dimensional array with a
+hash table (`std::unordered_map`) was about five times slower.
+
+## Tests
+The default installation does not include the dependencies necessary to run the
+tests.  To install these, first run
+```bash
+pip install -r requirements-dev.txt
+```
+before running
+```bash
+pytest
+```
+The tests are fairly basic but cover some of the
+more common pitfalls.  Pull requests for more extensive tests are welcome.
+
+## Code Formatting
+
+It's recommended that you use `pre-commit` to ensure linting procedures are
+run on any code you write.  See [pre-commit.com](https://pre-commit.com/) for
+more information.
+
+Reference [pre-commit's installation instructions](https://pre-commit.com/#install)
+for software installation on your OS/platform. After you have the software
+installed, run `pre-commit install` on the command line. Now every time you commit
+to this project's code base the linter procedures will automatically run over the
+changed files.  To run pre-commit on files preemtively from the command line use:
+
+```bash
+pip install -r requirements-dev.txt
+pre-commit run --all-files
+```
+
+The code base has been formatted by [Black](https://black.readthedocs.io/en/stable/).
+Furthermore, try to conform to `PEP8`.  You should set up your preferred editor to
+use `flake8` as its Python linter, but pre-commit will ensure compliance before a
+git commit is completed.  This will use the `flake8` configuration within
+`.flake8`, which ignores several errors and stylistic considerations.
+
+## References
+1. [A\* search algorithm on Wikipedia](https://en.wikipedia.org/wiki/A*_search_algorithm#Pseudocode)
+2. [Pathfinding with A* on Red Blob Games](http://www.redblobgames.com/pathfinding/a-star/introduction.html)

pyastar2d-1.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyastar2d-1.1.1.dist-info/RECORD,,
+pyastar2d-1.1.1.dist-info/WHEEL,sha256=pHFP9OVYdvAmGoLnGMVqoQS_7dTsRftlr9dZNNewBVc,135
+pyastar2d-1.1.1.dist-info/top_level.txt,sha256=sirwTJoF4I2DthdhahGwb3hQxZRT8XbOhsNRdorJmXM,10
+pyastar2d-1.1.1.dist-info/METADATA,sha256=UA3EC6qXmJEdQF9nh9066wnmOfY_cbmyDIjlJZMNxLY,8068
+pyastar2d-1.1.1.dist-info/licenses/LICENSE,sha256=XKV3_2Un6l3Wj3fAb8Q_olyi5s3AfI_NqG98vbLGqgs,1073
+pyastar2d/__init__.py,sha256=_llpDHJfo_fzVW08m991vBF7Xeo_TfsdY3lbEPAmPog,97
+pyastar2d/astar.abi3.so,sha256=PDEUxBhYRW6I3oxM51sUKx_6nlApo03I6cevqJhPy0o,54608
+pyastar2d/astar_wrapper.py,sha256=tMXFGWQnq5wXSZs4LiaCfUBYUkoke7jTOvEEcxBURLU,2505

pyastar2d-1.1.1.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: false
+Tag: cp39-abi3-macosx_11_0_arm64
+Generator: delocate 0.13.0
+

pyastar2d-1.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Hendrik Weideman
+
+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.

pyastar2d-1.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyastar2d