mirror of
https://github.com/maoakeEnterprise/amazing.git
synced 2026-04-28 16:04:35 +02:00
need to be merge
This commit is contained in:
maoake
@@ -1,250 +1 @@
|
|||||||
# A Maze Ing
|
SITULITUPU
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user