|
|
--- |
|
|
license: mit |
|
|
--- |
|
|
Here's a comprehensive Hugging Face Model Card for your Interactive PyQt5 A* Algorithm Game: |
|
|
|
|
|
```markdown |
|
|
--- |
|
|
language: |
|
|
- en |
|
|
tags: |
|
|
- game |
|
|
- pathfinding |
|
|
- algorithm |
|
|
- a-star |
|
|
- pyqt5 |
|
|
- visualization |
|
|
- educational |
|
|
- interactive |
|
|
- python |
|
|
widget: |
|
|
- video_path: demo.mp4 |
|
|
example_title: A* Algorithm Demo |
|
|
--- |
|
|
|
|
|
# Interactive A* Pathfinding Algorithm Game |
|
|
|
|
|
## Model Overview |
|
|
|
|
|
An interactive educational game that visually demonstrates the A* pathfinding algorithm using PyQt5. This application provides a hands-on way to understand how one of the most popular pathfinding algorithms works through real-time visualization. |
|
|
|
|
|
## What is A* Algorithm? |
|
|
|
|
|
A* (A-Star) is a graph traversal and path search algorithm that finds the shortest path between nodes. It combines the strengths of Dijkstra's Algorithm (guaranteed shortest path) and Greedy Best-First Search (efficiency) by using both: |
|
|
|
|
|
- **g(n)**: Actual cost from start node to current node |
|
|
- **h(n)**: Heuristic estimated cost from current node to goal |
|
|
- **f(n) = g(n) + h(n)**: Total estimated cost |
|
|
|
|
|
## Features |
|
|
|
|
|
### 🎮 Interactive Gameplay |
|
|
- Set custom start and end positions |
|
|
- Place and remove obstacles in real-time |
|
|
- Visualize algorithm execution step-by-step |
|
|
- Adjustable animation speed |
|
|
|
|
|
### 🎨 Visual Elements |
|
|
- **Green**: Start node |
|
|
- **Red**: End node |
|
|
- **Gray**: Obstacles/walls |
|
|
- **Yellow**: Open set (nodes being considered) |
|
|
- **Light Red**: Closed set (evaluated nodes) |
|
|
- **Blue**: Final optimal path |
|
|
|
|
|
### ⚙️ Technical Features |
|
|
- 20×20 grid system with 8-directional movement |
|
|
- Real-time cost display (g, h, f values) |
|
|
- Manhattan distance heuristic |
|
|
- Pause/Resume functionality |
|
|
- Reset and clear options |
|
|
|
|
|
## Quick Start |
|
|
|
|
|
### Installation |
|
|
```bash |
|
|
pip install PyQt5 |
|
|
``` |
|
|
|
|
|
### Run the Game |
|
|
```bash |
|
|
python astar_game.py |
|
|
``` |
|
|
|
|
|
### Usage Instructions |
|
|
1. Select "Start Point" mode and click a grid cell to set start position |
|
|
2. Select "End Point" mode and set destination |
|
|
3. Use "Obstacles" mode to add walls |
|
|
4. Click "Start" to run the algorithm |
|
|
5. Watch the visualization and learn! |
|
|
|
|
|
## Educational Value |
|
|
|
|
|
This game is perfect for: |
|
|
- 🎓 Computer Science students learning algorithms |
|
|
- 🎮 Game developers implementing pathfinding |
|
|
- 🔍 Anyone curious about how navigation algorithms work |
|
|
- 💡 Understanding heuristic search methods |
|
|
|
|
|
## Algorithm Details |
|
|
|
|
|
### Heuristic Function |
|
|
Uses Manhattan distance: `h(n) = |x₁ - x₂| + |y₁ - y₂|` |
|
|
|
|
|
### Cost Calculation |
|
|
- **Movement Cost**: Euclidean distance between nodes |
|
|
- **Total Cost**: f(n) = g(n) + h(n) |
|
|
- **Node Expansion**: Always expands node with lowest f(n) first |
|
|
|
|
|
### Key Properties |
|
|
- **Complete**: Always finds a solution if one exists |
|
|
- **Optimal**: Always finds the shortest path |
|
|
- **Efficient**: Explores fewer nodes than Dijkstra's algorithm |
|
|
|
|
|
## File Structure |
|
|
``` |
|
|
astar-game/ |
|
|
├── astar_game.py # Main game implementation |
|
|
├── requirements.txt # Dependencies |
|
|
├── README.md # This file |
|
|
└── demo.mp4 # Demonstration video |
|
|
``` |
|
|
|
|
|
## Requirements |
|
|
|
|
|
```txt |
|
|
PyQt5>=5.15.0 |
|
|
``` |
|
|
|
|
|
## Compatibility |
|
|
|
|
|
- **Python**: 3.6+ |
|
|
- **OS**: Windows, macOS, Linux |
|
|
- **Dependencies**: PyQt5 only |
|
|
|
|
|
## Try It Yourself! |
|
|
|
|
|
### Example Maze Challenge: |
|
|
``` |
|
|
S = Start, E = End, # = Obstacle |
|
|
|
|
|
S . . # . . . . . . |
|
|
. # . # . # # # . . |
|
|
. # . . . # . . . . |
|
|
. # # # . # . # # . |
|
|
. . . # . # . # . . |
|
|
# # . # . # . # . . |
|
|
. . . # . . . # . . |
|
|
. # # # # # # # . . |
|
|
. . . . . . . . . E |
|
|
``` |
|
|
|
|
|
Can you predict the path the algorithm will find? |
|
|
|
|
|
## Contributing |
|
|
|
|
|
Feel free to contribute by: |
|
|
- Adding different heuristic functions |
|
|
- Implementing other pathfinding algorithms |
|
|
- Improving the UI/UX |
|
|
- Adding level challenges |
|
|
|
|
|
## License |
|
|
|
|
|
This project is open source and available under the MIT License. |
|
|
|
|
|
## Citation |
|
|
|
|
|
If you use this in an educational setting or project, please credit: |
|
|
|
|
|
```bibtex |
|
|
@software{astar_pyqt_game, |
|
|
title = {Interactive A* Pathfinding Algorithm Game}, |
|
|
author = {Your Name}, |
|
|
year = {2024}, |
|
|
url = {https://huggingface.co/your-username/astar-game} |
|
|
} |
|
|
``` |
|
|
|
|
|
## Related Algorithms |
|
|
|
|
|
- Dijkstra's Algorithm |
|
|
- Breadth-First Search (BFS) |
|
|
- Depth-First Search (DFS) |
|
|
- Greedy Best-First Search |
|
|
- Jump Point Search |
|
|
|
|
|
--- |
|
|
|
|
|
**Happy pathfinding!** 🚀 |
|
|
``` |
|
|
|
|
|
This model card includes all the essential sections that Hugging Face expects: |
|
|
|
|
|
1. **Metadata** (language, tags, widget) |
|
|
2. **Overview** and algorithm explanation |
|
|
3. **Features** and technical details |
|
|
4. **Installation** and usage instructions |
|
|
5. **Educational value** |
|
|
6. **Technical specifications** |
|
|
7. **Compatibility** information |
|
|
8. **Interactive examples** |
|
|
9. **Citation** template |
|
|
10. **Related content** |
|
|
|
|
|
The card is structured to be both informative for technical users and accessible for learners new to pathfinding algorithms. You can save this as `README.md` in your Hugging Face model repository. |
