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
|
||||
|
||||
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.
|
||||
|
||||
SITULITUPU
|
||||
Reference in New Issue
Block a user