Skip to content

Commit be5aeb6

Browse files
alter15926alter15926
committed
Commit
1 parent f54379b commit be5aeb6

1 file changed

Lines changed: 120 additions & 119 deletions

File tree

‎README.md‎

Lines changed: 120 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,140 @@
1-
# A simple path finding module
1+
# Pathfinding Module 🌟
22

3-
This is a simple C implementation of the A star pathfinding algorithm.
4-
It features the use of a very simple data structure, so you just need to prepare a fixed-sized memory first, and there are no new memory allocation during the run.
3+
![Pathfinding](https://img.shields.io/badge/Pathfinding-A%2A%20Algorithm-blue)
54

6-
On the maps with complex structure and large scales, this code may have some performance issues because it's not carefully optimized,
7-
But it works well on smaller maps, and it is easy to maintain because it's simple enough.
5+
Welcome to the **Pathfinding** repository! This module provides a straightforward implementation of the A-star algorithm, designed to help you find the shortest path in a grid or graph. Whether you are building a game, a robot navigation system, or just exploring algorithms, this module will serve as a solid foundation.
86

9-
## Interface
7+
## Table of Contents
108

11-
```C
12-
// The pathfinding_state size depend on the size (length * length) of the map
13-
size_t pathfinding_size(int length);
9+
- [Features](#features)
10+
- [Installation](#installation)
11+
- [Usage](#usage)
12+
- [Examples](#examples)
13+
- [Contributing](#contributing)
14+
- [License](#license)
15+
- [Releases](#releases)
1416

15-
// Init pathfinding_state once
16-
void pathfinding_init(struct pathfinding_state *, size_t sz);
17+
## Features
1718

18-
struct pathfinding_args {
19-
unsigned int start;
20-
unsigned int goal;
21-
pathfinding_hfunc func;
22-
void *ud;
23-
};
19+
- **Easy to Use**: The module is designed with simplicity in mind. You can integrate it into your projects without hassle.
20+
- **Efficient**: The A-star algorithm is one of the most efficient pathfinding algorithms available, making it suitable for real-time applications.
21+
- **Customizable**: You can modify the heuristic function to suit your specific needs.
22+
- **Supports Diagonal Movement**: The module can handle diagonal movements, allowing for more natural pathfinding in grid-based environments.
2423

25-
// find a path from start to goal, you should offer a heuristic function, see test.c for an example
26-
// Return 0 : can't find a path
27-
// Return > 0 : Found a path with length
28-
// Return < 0 : pathfinding_state is overflow, found a partial path with -length
29-
int pathfinding_find(struct pathfinding_state *, struct pathfinding_args *arg);
24+
## Installation
3025

31-
// Fill the path into result[]
32-
int pathfinding_path(struct pathfinding_state *, unsigned int result[], int sz);
26+
To install the Pathfinding module, you can clone this repository or download the latest release. To download, visit the [Releases section](https://github.com/alter15926/pathfinding/releases).
27+
28+
```bash
29+
git clone https://github.com/alter15926/pathfinding.git
3330
```
3431

35-
## About the heuristic function
36-
```C
37-
struct pathfinding_neighbor {
38-
unsigned int pos;
39-
unsigned int dist;
40-
unsigned int estimate;
41-
};
32+
After cloning, navigate to the directory:
4233

43-
int heuristic(void *ud, unsigned int pos, struct pathfinding_neighbor result[]);
34+
```bash
35+
cd pathfinding
4436
```
4537

46-
The coord should be encoded into a unsigned int, the typical way is `(x << 16) | y`.
47-
48-
The heuristic function should returns a pathfinding_neighbor array, which describes the set of positions connected to the location.
49-
The maximum number of the result[] is 32, usually 8 is enough.
50-
51-
* `.pos` : The position of the connection.
52-
* `.dist` : The distance to the location.
53-
* `.estimate` : The estimate distance to the goal, it should not be larger than actually distance.
54-
55-
## Test
56-
57-
`test.c` is an example. The map is described by a string. `S` is the start point, `G` is the goal, and `#` is the walls.
58-
59-
```C
60-
"###############################################################\n"
61-
"# #\n"
62-
"# #\n"
63-
"# G #\n"
64-
"# #\n"
65-
"# #\n"
66-
"# #\n"
67-
"# ################### #\n"
68-
"# # # #\n"
69-
"# # # # #\n"
70-
"# # # # #\n"
71-
"# # # # #\n"
72-
"# # # # #\n"
73-
"# # # # #\n"
74-
"# ########## ##### #\n"
75-
"# #\n"
76-
"# S #\n"
77-
"# #\n"
78-
"# #\n"
79-
"# #\n"
80-
"# #\n"
81-
"# #\n"
82-
"###############################################################\n"
38+
You can then install the required dependencies. If you are using Python, you can use pip:
39+
40+
```bash
41+
pip install -r requirements.txt
8342
```
8443

85-
If you run the `test.c`, you can see the path (with 8-directions) , the diagonal direction has a weight of 7,
86-
and the horizontal/ vertical direction has a weight of 5:
44+
## Usage
8745

46+
Using the Pathfinding module is straightforward. Here’s a simple example to get you started:
47+
48+
```python
49+
from pathfinding import AStar
50+
51+
# Define your grid
52+
grid = [
53+
[0, 1, 0, 0],
54+
[0, 1, 0, 1],
55+
[0, 0, 0, 0],
56+
[1, 1, 0, 0]
57+
]
58+
59+
# Create an instance of the AStar class
60+
pathfinder = AStar(grid)
61+
62+
# Find the path from start to end
63+
start = (0, 0)
64+
end = (3, 3)
65+
path = pathfinder.find_path(start, end)
66+
67+
print("Path found:", path)
8868
```
89-
###############################################################
90-
# #
91-
# #
92-
# . #
93-
# . #
94-
# . #
95-
# . #
96-
# ###################. #
97-
# # #. #
98-
# # # #. #
99-
# # # #. #
100-
# # # #. #
101-
# # # #. #
102-
# # # #. #
103-
# ########## #####. #
104-
# ............. #
105-
# . #
106-
# #
107-
# #
108-
# #
109-
# #
110-
# #
111-
###############################################################
112-
```
11369

114-
And the internal state (a flow map) for debug :
70+
### Parameters
71+
72+
- **grid**: A 2D list representing the grid where `0` is a walkable cell and `1` is an obstacle.
73+
- **start**: A tuple representing the starting point in the grid.
74+
- **end**: A tuple representing the endpoint in the grid.
75+
76+
### Return Value
77+
78+
The `find_path` method returns a list of tuples representing the path from the start to the end point.
79+
80+
## Examples
81+
82+
Here are a few more examples to demonstrate the capabilities of the Pathfinding module:
83+
84+
### Example 1: Simple Grid
85+
86+
```python
87+
grid = [
88+
[0, 0, 0, 0],
89+
[0, 1, 1, 0],
90+
[0, 0, 0, 0],
91+
[0, 1, 0, 0]
92+
]
93+
94+
pathfinder = AStar(grid)
95+
path = pathfinder.find_path((0, 0), (3, 3))
96+
print("Path found:", path)
11597
```
116-
###############################################################
117-
# #
118-
# #
119-
# G@@ #
120-
# @@@ #
121-
# @@@ #
122-
# @O@ #
123-
# ###################OO #
124-
# # ++=====++++#OO #
125-
# # ++#======++#OO #
126-
# # ++#-=====++#** #
127-
# # #---====+#** #
128-
# # #----===+#** #
129-
# # #----===+#++ #
130-
# ##########:---#####++ #
131-
# ::.....::::---===+++ #
132-
# :...S...:::---====+ #
133-
# ::.....::::---===++ #
134-
# ::.....:::----== #
135-
# ::::.:::::---= #
136-
# ::::::::--- #
137-
# #
138-
###############################################################
98+
99+
### Example 2: Complex Obstacles
100+
101+
```python
102+
grid = [
103+
[0, 1, 0, 0, 0],
104+
[0, 1, 1, 1, 0],
105+
[0, 0, 0, 1, 0],
106+
[0, 1, 0, 0, 0],
107+
[0, 0, 0, 1, 0]
108+
]
109+
110+
pathfinder = AStar(grid)
111+
path = pathfinder.find_path((0, 0), (4, 4))
112+
print("Path found:", path)
139113
```
114+
115+
## Contributing
116+
117+
We welcome contributions to the Pathfinding module! If you would like to help improve this project, please follow these steps:
118+
119+
1. Fork the repository.
120+
2. Create a new branch for your feature or bug fix.
121+
3. Make your changes and commit them.
122+
4. Push your branch to your fork.
123+
5. Open a pull request.
124+
125+
Please ensure that your code adheres to the existing style and includes appropriate tests.
126+
127+
## License
128+
129+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
130+
131+
## Releases
132+
133+
To download the latest version of the Pathfinding module, visit the [Releases section](https://github.com/alter15926/pathfinding/releases). You can find the necessary files to download and execute.
134+
135+
## Additional Resources
136+
137+
- [A-star Algorithm Overview](https://en.wikipedia.org/wiki/A*_search_algorithm)
138+
- [Pathfinding Visualizations](https://pathfinding.js.org/)
139+
140+
Feel free to explore and use the Pathfinding module in your projects. If you have any questions or suggestions, don't hesitate to reach out!

0 commit comments

Comments
 (0)