{"id":16130743,"url":"https://github.com/hjweide/pyastar2d","last_synced_at":"2026-02-22T02:15:58.994Z","repository":{"id":40309808,"uuid":"75500943","full_name":"hjweide/pyastar2d","owner":"hjweide","description":"A very simple A* implementation in C++ callable from Python for pathfinding on a two-dimensional grid.","archived":false,"fork":false,"pushed_at":"2026-02-02T01:37:41.000Z","size":7241,"stargazers_count":154,"open_issues_count":4,"forks_count":65,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-02-02T11:31:33.628Z","etag":null,"topics":["2d-grid","astar-algorithm","astar-pathfinding","cplusplus","pathfinding","python","shortest-path"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hjweide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-03T21:19:29.000Z","updated_at":"2026-02-02T01:37:47.000Z","dependencies_parsed_at":"2024-06-18T22:36:46.254Z","dependency_job_id":"25c94f19-d5e3-4a0a-a7f0-e243ad69f216","html_url":"https://github.com/hjweide/pyastar2d","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/hjweide/pyastar2d","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hjweide%2Fpyastar2d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hjweide%2Fpyastar2d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hjweide%2Fpyastar2d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hjweide%2Fpyastar2d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hjweide","download_url":"https://codeload.github.com/hjweide/pyastar2d/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hjweide%2Fpyastar2d/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29703396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T23:35:04.139Z","status":"online","status_checked_at":"2026-02-22T02:00:08.193Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2d-grid","astar-algorithm","astar-pathfinding","cplusplus","pathfinding","python","shortest-path"],"created_at":"2024-10-09T22:17:30.656Z","updated_at":"2026-02-22T02:15:58.949Z","avatar_url":"https://github.com/hjweide.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/hjweide/pyastar2d.svg?branch=master)](https://travis-ci.com/hjweide/pyastar2d)\n[![Coverage Status](https://coveralls.io/repos/github/hjweide/pyastar2d/badge.svg?branch=master)](https://coveralls.io/github/hjweide/pyastar2d?branch=master)\n[![PyPI version](https://badge.fury.io/py/pyastar2d.svg)](https://badge.fury.io/py/pyastar2d)\n# PyAstar2D\nThis is a very simple C++ implementation of the A\\* algorithm for pathfinding\non a two-dimensional grid.  The solver itself is implemented in C++, but is\ncallable from Python.  This combines the speed of C++ with the convenience of\nPython.\n\nI have not done any formal benchmarking, but the solver finds the solution to a\n1802 by 1802 maze in 0.29s and a 4008 by 4008 maze in 0.83s when running on my\nnine-year-old Intel(R) Core(TM) i7-2630QM CPU @ 2.00GHz.  See [Example\nResults](#example-results) for more details.\n\nSee `src/cpp/astar.cpp` for the core C++ implementation of the A\\* shortest\npath search algorithm, `src/pyastar2d/astar_wrapper.py` for the Python wrapper\nand `examples/example.py` for example usage.\n\nWhen determining legal moves, 4-connectivity is the default, but it is possible\nto set `allow_diagonal=True` for 8-connectivity.\n\n## Installation\nInstructions for installing `pyastar2d` are given below.\n\n### From PyPI\nThe easiest way to install `pyastar2d` is directly from the Python package index:\n```\npip install pyastar2d\n```\n\n### From source\nYou can also install `pyastar2d` by cloning this repository and building it\nyourself.  If running on Linux or MacOS, simply run\n```bash\npip install .\n````\nfrom the root directory.  If you are using Windows you may have to install Cython manually first:\n```bash\npip install Cython\npip install .\n```\nTo check that everything worked, run the example:\n```bash\npython examples/example.py\n```\n\n### As a dependency\nInclude `pyastar2d` in your `requirements.txt` to install from `pypi`, or add\nthis line to `requirements.txt`:\n```\npyastar2d @ git+git://github.com/hjweide/pyastar2d.git@master#egg=pyastar2d\n```\n\n## Usage\nA simple example is given below:\n```python\nimport numpy as np\nimport pyastar2d\n# The minimum cost must be 1 for the heuristic to be valid.\n# The weights array must have np.float32 dtype to be compatible with the C++ code.\nweights = np.array([[1, 3, 3, 3, 3],\n                    [2, 1, 3, 3, 3],\n                    [2, 2, 1, 3, 3],\n                    [2, 2, 2, 1, 3],\n                    [2, 2, 2, 2, 1]], dtype=np.float32)\n# The start and goal coordinates are in matrix coordinates (i, j).\npath = pyastar2d.astar_path(weights, (0, 0), (4, 4), allow_diagonal=True)\nprint(path)\n# The path is returned as a numpy array of (i, j) coordinates.\narray([[0, 0],\n       [1, 1],\n       [2, 2],\n       [3, 3],\n       [4, 4]])\n```\nNote that all grid points are represented as `(i, j)` coordinates.  An example\nof using `pyastar2d` to solve a maze is given in `examples/maze_solver.py`.\n\n## Example Results\n\u003ca name=\"example-results\"\u003e\u003c/a\u003e\nTo test the implementation, I grabbed two nasty mazes from Wikipedia.  They are\nincluded in the ```mazes``` directory, but are originally from here:\n[Small](https://upload.wikimedia.org/wikipedia/commons/c/cf/MAZE.png) and\n[Large](https://upload.wikimedia.org/wikipedia/commons/3/32/MAZE_2000x2000_DFS.png).\nI load the ```.png``` files as grayscale images, and set the white pixels to 1\n(open space) and the black pixels to `INF` (walls).\n\nTo run the examples specify the input and output files using the `--input` and\n`--output` flags.  For example, the following commands will solve the small and\nlarge mazes:\n```\npython examples/maze_solver.py --input mazes/maze_small.png --output solns/maze_small.png\npython examples/maze_solver.py --input mazes/maze_large.png --output solns/maze_large.png\n```\n\n### Small Maze (1802 x 1802): \n```bash\ntime python examples/maze_solver.py --input mazes/maze_small.png --output solns/maze_small.png\nLoaded maze of shape (1802, 1802) from mazes/maze_small.png\nFound path of length 10032 in 0.292794s\nPlotting path to solns/maze_small.png\nDone\n\nreal\t0m1.214s\nuser\t0m1.526s\nsys\t0m0.606s\n```\nThe solution found for the small maze is shown below:\n\u003cimg src=\"https://github.com/hjweide/pyastar2d/raw/master/solns/maze_small_soln.png\" alt=\"Maze Small Solution\" style=\"width: 100%\"/\u003e\n\n### Large Maze (4002 x 4002): \n```bash\ntime python examples/maze_solver.py --input mazes/maze_large.png --output solns/maze_large.png\nLoaded maze of shape (4002, 4002) from mazes/maze_large.png\nFound path of length 783737 in 0.829181s\nPlotting path to solns/maze_large.png\nDone\n\nreal\t0m29.385s\nuser\t0m29.563s\nsys\t0m0.728s\n```\nThe solution found for the large maze is shown below:\n\u003cimg src=\"https://github.com/hjweide/pyastar2d/raw/master/solns/maze_large_soln.png\" alt=\"Maze Large Solution\" style=\"width: 100%\"/\u003e\n\n## Motivation\nI recently needed an implementation of the A* algorithm in Python to find the\nshortest path between two points in a cost matrix representing an image.\nNormally I would simply use [networkx](https://networkx.github.io/), but for\ngraphs with millions of nodes the overhead incurred to construct the graph can\nbe expensive.  Considering that I was only interested in graphs that may be\nrepresented as two-dimensional grids, I decided to implement it myself using\nthis special structure of the graph to make various optimizations.\nSpecifically, the graph is represented as a one-dimensional array because there\nis no need to store the neighbors.  Additionally, the lookup tables for\npreviously-explored nodes (their costs and paths) are also stored as\none-dimensional arrays.  The implication of this is that checking the lookup\ntable can be done in O(1), at the cost of using O(n) memory.  Alternatively, we\ncould store only the nodes we traverse in a hash table to reduce the memory\nusage.  Empirically I found that replacing the one-dimensional array with a\nhash table (`std::unordered_map`) was about five times slower.\n\n## Tests\nThe default installation does not include the dependencies necessary to run the\ntests.  To install these, first run\n```bash\npip install -r requirements-dev.txt\n```\nbefore running\n```bash\npy.test\n```\nThe tests are fairly basic but cover some of the\nmore common pitfalls.  Pull requests for more extensive tests are welcome.\n\n## References\n1. [A\\* search algorithm on Wikipedia](https://en.wikipedia.org/wiki/A*_search_algorithm#Pseudocode)\n2. [Pathfinding with A* on Red Blob Games](http://www.redblobgames.com/pathfinding/a-star/introduction.html)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhjweide%2Fpyastar2d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhjweide%2Fpyastar2d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhjweide%2Fpyastar2d/lists"}