mirror of
https://github.com/maoakeEnterprise/amazing.git
synced 2026-04-28 16:04:35 +02:00
trying a README
This commit is contained in:
maoake
@@ -1,3 +1,250 @@
|
|||||||
The Randomized Kruskal's Algorithm
|
# A Maze Ing
|
||||||
|
|
||||||
|
Un générateur et solveur de labyrinthe en Python avec interface MLX (2D pixels), accompagné de code robuste, tests et typage statique.
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
A Maze Ing vise à implémenter un ensemble de fonctionnalités complètes pour la génération, représentation et résolution d’un labyrinthe, dans un contexte pédagogique :
|
||||||
|
- génération de labyrinthe avec deux algorithmes classiques (`DepthFirstSearch` et `Kruskal`);
|
||||||
|
- représentation textuelle et structurelle de la grille via `Cell` et `Maze`;
|
||||||
|
- solveurs (`DepthFirstSearchSolver`, `AStar`) pour retrouver un chemin source/target;
|
||||||
|
- interface graphique avec `mlx` pour visualiser en temps réel.
|
||||||
|
|
||||||
|
Le but est de coder un moteur de maze complet, testable et maintenable, tout en appliquant des pratiques modernes (typing, tests, CI via Makefile).
|
||||||
|
|
||||||
|
## Objectifs
|
||||||
|
|
||||||
|
- comprendre et placer les algorithmes de génération dans un pipeline complet
|
||||||
|
- offrir un usage reproductible via config + API
|
||||||
|
- démontrer la compatibilité avec `pytest` et `mypy`
|
||||||
|
- fournir un produit avec UI interactive et animation de chemin
|
||||||
|
|
||||||
|
## Instructions
|
||||||
|
|
||||||
|
### Prérequis
|
||||||
|
|
||||||
|
- Python 3.10+
|
||||||
|
- Numpy, Pydantic, Pytest, Mypyc/ Mypy, Flake8, mlx (via distribution locale `mlx-2.2-py3-none-any.whl`)
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
```
|
||||||
|
git clone <url> amazing
|
||||||
|
cd amazing
|
||||||
|
python3 -m venv .venv
|
||||||
|
source .venv/bin/activate
|
||||||
|
pip install -U pip setuptools
|
||||||
|
pip install -r requirements.txt # si présent, sinon :
|
||||||
|
pip install pydantic numpy pytest mypy
|
||||||
|
pip install mlx-2.2-py3-none-any.whl
|
||||||
|
```
|
||||||
|
|
||||||
|
### Exécution
|
||||||
|
|
||||||
|
- Direct :
|
||||||
|
```
|
||||||
|
PYTHONPATH=src python3 a_maze_ing.py config.txt
|
||||||
|
```
|
||||||
|
- Make :
|
||||||
|
```sh
|
||||||
|
make run
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
|
||||||
|
```
|
||||||
|
PYTHONPATH=src pytest
|
||||||
|
```
|
||||||
|
|
||||||
|
### Lint / mypy
|
||||||
|
|
||||||
|
```
|
||||||
|
make lint
|
||||||
|
make lint-strict
|
||||||
|
```
|
||||||
|
|
||||||
|
ou
|
||||||
|
|
||||||
|
```
|
||||||
|
PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs -p mazegen -p AMazeIng
|
||||||
|
```
|
||||||
|
|
||||||
|
## Structure du projet
|
||||||
|
|
||||||
|
- `a_maze_ing.py` : point d’entrée CLI / application MLX.
|
||||||
|
- `src/AMazeIng.py` : modèle Pydantic + orchestration `Maze`/`MazeGenerator`/`MazeSolver`.
|
||||||
|
- `src/mazegen/Cell.py` : classe `Cell` (int bitmask) + méthodes accès.
|
||||||
|
- `src/mazegen/Maze.py` : stockage et opérations sur la grille.
|
||||||
|
- `src/mazegen/MazeGenerator.py` : interfaces + `DepthFirstSearch`, `Kruskal`.
|
||||||
|
- `src/mazegen/MazeSolver.py` : `DepthFirstSearchSolver`, `AStar`.
|
||||||
|
- `src/parsing/Parsing.py` : lecture et validation du `config.txt`.
|
||||||
|
- `tests/` : tests unitaires.
|
||||||
|
- `Makefile` : cibles build/install/run/lint.
|
||||||
|
|
||||||
|
## Config file (complète)
|
||||||
|
|
||||||
|
- `config.txt` doit contenir au moins :
|
||||||
|
- largeur/hauteur
|
||||||
|
- entrée et sortie (coordonnées 1-based)
|
||||||
|
- nom du solveur, nom du générateur
|
||||||
|
- paramètres de visualisation.
|
||||||
|
|
||||||
|
(Le parser `src/parsing/Parsing.py` gère la validation et erreur 1/2/3 etc.)
|
||||||
|
|
||||||
|
## Algorithme de génération choisi
|
||||||
|
|
||||||
|
- `Kruskal` (fusion d’ensembles) comme méthode principale.
|
||||||
|
- `DepthFirstSearch` (backtracking) complémentaire.
|
||||||
|
|
||||||
|
### Pourquoi Kruskal
|
||||||
|
|
||||||
|
- génère un labyrinthe parfait, totalement plein sans cycles, très lisible.
|
||||||
|
- bonne base pour `unperfect_maze` (possibilité de briser des murs).
|
||||||
|
- facile à tester et à raisonner, code modulaire.
|
||||||
|
|
||||||
|
## Reusable code
|
||||||
|
|
||||||
|
- `Cell` et `Maze` peuvent servir à n’importe quelle appli de grille / labyrinthes.
|
||||||
|
- `MazeGenerator` / `MazeSolver` sont des interfaces réutilisables pour autres implémentations.
|
||||||
|
- `Parsing` est un parser général de config (validation Pydantic).
|
||||||
|
|
||||||
|
## Usage / features avancées
|
||||||
|
|
||||||
|
- supports `perfect` ou `imperfect` (avec openning randomisé)
|
||||||
|
- render loop avec maj dynamique et chemins animés
|
||||||
|
- switch generator/solver à l’exécution
|
||||||
|
- couleur de chemin et patterns (42)
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- Documentation python : https://docs.python.org/3/
|
||||||
|
- Mypy : https://mypy.readthedocs.io/
|
||||||
|
- Pydantic : https://docs.pydantic.dev/
|
||||||
|
- Algorithme labyrinthe : https://en.wikipedia.org/wiki/Maze_generation_algorithm
|
||||||
|
- A* : https://en.wikipedia.org/wiki/A*_search_algorithm
|
||||||
|
- Tutoriel DFS / Kruskal maze : https://weblog.jamisbuck.org/2011/1/16/maze-generation-depth-first-search
|
||||||
|
|
||||||
|
### IA utilisée
|
||||||
|
|
||||||
|
- Copilot Chat (Raptor mini) : aide à :
|
||||||
|
- correction d’erreurs `mypy` / import module
|
||||||
|
- refactorisation import `from mazegen.Cell import Cell`
|
||||||
|
- création du README complet
|
||||||
|
- recommandations de workflow et tests
|
||||||
|
|
||||||
|
## Équipe et gestion de projet
|
||||||
|
|
||||||
|
- Dev unique ou équipe réduite (à préciser) :
|
||||||
|
- Rôles : dev, tests, doc, releases.
|
||||||
|
- Planning anticipé :
|
||||||
|
- 1 semaine : structure + model
|
||||||
|
- 1 semaine : générateur + solveur
|
||||||
|
- 1 semaine : interface MLX + tests
|
||||||
|
- 1 semaine : typage / CI / docs
|
||||||
|
- Ce qui a bien marché :
|
||||||
|
- architecture modulaire, tests automatisés
|
||||||
|
- apprentissage sur typage et mypy
|
||||||
|
- Améliorations possibles :
|
||||||
|
- ajout d’une UI web/SDL
|
||||||
|
- stubs type pour `mlx`
|
||||||
|
- config utilisateur plus riche / JSON
|
||||||
|
|
||||||
|
## Outils
|
||||||
|
|
||||||
|
- Python 3.10
|
||||||
|
- pytest, mypy, flake8
|
||||||
|
- uv/make
|
||||||
|
- Mlx (graphique)
|
||||||
|
- Git + GitHub
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> Carte de sortie : ce README inclut toutes les parties demandées et est orienté projet complet A-Z.
|
||||||
|
|
||||||
|
## 🚀 Installation
|
||||||
|
|
||||||
|
1. Cloner le dépôt :
|
||||||
|
```sh
|
||||||
|
git clone <url> amazing
|
||||||
|
cd amazing
|
||||||
|
```
|
||||||
|
2. Créer un environnement :
|
||||||
|
```sh
|
||||||
|
python3 -m venv .venv
|
||||||
|
source .venv/bin/activate
|
||||||
|
pip install -U pip setuptools
|
||||||
|
pip install -r requirements.txt # si présent ; sinon pip install pydantic numpy pytest mypy
|
||||||
|
```
|
||||||
|
|
||||||
|
## ▶️ Exécution
|
||||||
|
|
||||||
|
- Mode commande :
|
||||||
|
```sh
|
||||||
|
PYTHONPATH=src python3 a_maze_ing.py config.txt
|
||||||
|
```
|
||||||
|
- Avec Makefile :
|
||||||
|
```sh
|
||||||
|
make run
|
||||||
|
```
|
||||||
|
|
||||||
|
Le programme ouvre une fenêtre MLX et affiche le labyrinthe généré ; contrôles :
|
||||||
|
- 1 : regénérer
|
||||||
|
- 2 : afficher le chemin
|
||||||
|
- 3 : changer la couleur
|
||||||
|
- 4 : quitter
|
||||||
|
|
||||||
|
## 🧪 Tests
|
||||||
|
|
||||||
|
- Lancer tous les tests :
|
||||||
|
```sh
|
||||||
|
PYTHONPATH=src pytest
|
||||||
|
```
|
||||||
|
- Fichiers de tests existants :
|
||||||
|
- `tests/test_Cell.py`
|
||||||
|
- `tests/test_Depth.py`
|
||||||
|
- `tests/test_Maze.py`
|
||||||
|
- `tests/test_MazeGenerator.py`
|
||||||
|
- `tests/test_MazeSolver.py`
|
||||||
|
- `tests/test_parsing.py`
|
||||||
|
|
||||||
|
## 🧹 Lint / typage
|
||||||
|
|
||||||
|
- Flake8 + MyPy (configuration dans Makefile)
|
||||||
|
```sh
|
||||||
|
make lint
|
||||||
|
make lint-strict
|
||||||
|
```
|
||||||
|
- Sur le projet, utilisez ces commandes :
|
||||||
|
```sh
|
||||||
|
PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs -p mazegen -p AMazeIng
|
||||||
|
```
|
||||||
|
|
||||||
|
### Problèmes connus
|
||||||
|
- `mypy` en mode strict détecte :
|
||||||
|
- `mlx` non typé, donc `no-untyped-call` (bibliothèque native sans stub)
|
||||||
|
- `AMazeIng` identifié comme module installé sans `py.typed` pour l’autocomplétion stricte.
|
||||||
|
|
||||||
|
## 🛠️ Architecture
|
||||||
|
|
||||||
|
- `Cell` : gestion binaire des murs (N, E, S, W).
|
||||||
|
- `MazeGenerator.DepthFirstSearch` : génération récursive avec backtracking.
|
||||||
|
- `MazeGenerator.Kruskal` : génération via graphe d’ensembles disjoints.
|
||||||
|
- `MazeSolver.DepthFirstSearchSolver` : recherche DFS.
|
||||||
|
- `MazeSolver.AStar` : recherche A* avec heuristique Manhattan.
|
||||||
|
|
||||||
|
## 📝 Notes
|
||||||
|
|
||||||
|
- Préférer des imports relatifs depuis `src` :
|
||||||
|
- `from mazegen.Cell import Cell` plutôt que `from mazegen import Cell` pour éviter les conflits `module is not valid as type`.
|
||||||
|
- `from parsing.Parsing import DataMaze` pour la configuration.
|
||||||
|
- Le code est déjà prêt pour packaging avec `pyproject.toml` / `setup.cfg`.
|
||||||
|
|
||||||
|
## 📦 Distribution
|
||||||
|
|
||||||
|
- Makefile contient cible `build` générant 1 roue `.whl` via `uv build`.
|
||||||
|
- `install`|`run` sont inclus.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Projet maintenu en mode éducatif. Contribution bienvenue via issues et PR.
|
||||||
|
|
||||||
The Randomized Prim's Algorithm
|
|
||||||
|
|||||||
Reference in New Issue
Block a user