oc-p08-street-vision/README.MD

🚗 Segmentation Multi-Classes pour Véhicules Autonomes

Source de vérité : Forgejo (auto-hébergé).

git clone https://git.gregoiremureau.com/grgmro/oc-p08-street-vision.git
git clone https://git.gregoiremureau.com/grgmro/oc-p08-street-vision.git

Prod : https://api.gregoiremureau.com/ml/street-vision/

Dataset complet : ./fetch-data.sh (Cityscapes hors git ; petit échantillon déjà dans notebooks/content/data/).

📋 Description du Projet

Ce projet développe un système de segmentation sémantique d'images de rue destiné aux véhicules autonomes. Il permet l'identification et la segmentation automatique de différents éléments urbains : véhicules, piétons, mobilier urbain, infrastructure routière, etc.

Le système s'inscrit dans une chaîne complète de vision par ordinateur embarquée pour l'automobile autonome, traitant les images en temps réel pour alimenter les systèmes de décision.

🗂️ Structure du Projet

├── notebooks/
│   ├── p8_notebook.ipynb       # Notebook principal d'entraînement des modèles
│   └── content/
│       └── data/
│           ├── new_images_to_predict/     # Images diverses pour tests d'inférence
│           └── test_images_sample/        # Échantillon Cityscapes avec masques
├── utils/
│   └── utils.py                # Fonctions communes (prétraitement, chargement, inférence)
├── app/                        # API et Interface Web
│   ├── main.py                 # API FastAPI avec routes de segmentation
│   ├── streamlit_app.py        # Interface web interactive
│   └── requirements.txt        # Dépendances pour l'API et l'interface
├── cityscapes_config.json      # Configuration des classes Cityscapes
├── .env.example                # Template de variables d'environnement
├── Dockerfile                  # Configuration Docker
├── docker-compose.yml.example  # Template Docker Compose
├── nginx.conf                  # Configuration reverse proxy
├── start.sh                    # Script de démarrage des services
├── .dockerignore              # Optimisation du build Docker
└── README.md

Note

: Les modèles entraînés sont stockés et versionnés via MLFlow avec artefacts sur MinIO, pas en local.

État actuel du développement :

• ✅ Entraînement des modèles : Complet (notebook + MLFlow + MinIO)
• ✅ Fonctions d'inférence : Développées et prêtes
• ✅ API FastAPI : API complète avec endpoints de segmentation
• ✅ Interface Web : Interface Streamlit pour upload et visualisation
• ✅ Déploiement : Conteneurisation Docker complète + reverse proxy nginx

🏷️ Classes de Segmentation

Le modèle identifie 8 catégories principales :

1. Route - Chaussée et surfaces roulantes
2. Trottoir - Zones piétonnes
3. Bâtiments - Structures architecturales
4. Végétation - Arbres, buissons, espaces verts
5. Véhicules - Voitures, camions, bus
6. Personnes - Piétons, cyclistes
7. Signalisation - Panneaux, feux de circulation
8. Mobilier urbain - Poteaux, barrières, abribus

🧠 Architecture Technique

Modèles Implémentés

Utilisation de la bibliothèque segmentation_models de qubvel pour l'implémentation des architectures.

Architectures principales :

• U-Net : Architecture encoder-decoder classique
• FPN (Feature Pyramid Network) : Réseau à pyramide de caractéristiques

Backbones testés :

# Modèles avec backbones par défaut
('U-Net', None)     # Backbone U-Net intégré
('FPN', None)       # Backbone VGG16 par défaut

# Modèles avec backbones pré-entraînés (encodeurs gelés)
('U-Net', 'mobilenetv2')
('U-Net', 'efficientnetb0') 
('FPN', 'mobilenetv2')
('FPN', 'efficientnetb0')
('FPN', 'resnet34')

# Fine-tuning sélectif (encodeurs entraînables)
('U-Net', 'mobilenetv2')
('FPN', 'efficientnetb0') 
('FPN', 'resnet34')

Stratégies d'entraînement :

• Encodeurs gelés : Transfer learning avec features pré-entraînées figées
• Fine-tuning : Ajustement fin des encodeurs pré-entraînés
• Entraînement from scratch : Sans pré-entraînement (backbones par défaut)

Stack Technologique

• Framework : Keras/TensorFlow
• Architectures : segmentation_models (qubvel)
• Gestion des expériences : MLFlow
• Stockage des artefacts : MinIO (S3-compatible)
• API : FastAPI avec validation Pydantic
• Interface : Streamlit pour l'interaction utilisateur
• Reverse Proxy : nginx pour routage API/Interface
• Déploiement : Docker + NAS personnel (solutions souveraines)

📊 Dataset

• Source : Cityscapes Dataset
• Organisation locale :
  • notebooks/content/data/test_images_sample/ : Échantillon avec masques de vérité pour tests d'inférence
  • notebooks/content/data/new_images_to_predict/ : Images de test diverses pour validation

🚀 Installation et Configuration

Option 1: Déploiement Docker (Recommandé)

Configuration rapide

# Cloner le projet
git clone https://git.gregoiremureau.com/grgmro/oc-p08-street-vision.git
cd oc-p08-street-vision

# Copier et adapter la configuration
cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

# Éditer les variables d'environnement
nano .env

Variables d'environnement requises

# Configuration du serveur
NGINX_PORT=8080

# Configuration MLflow
MLFLOW_TRACKING_URI=http://localhost:5000
MLFLOW_S3_ENDPOINT_URL=http://localhost:9000
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key

# URL de base de l'API (pour Streamlit)
MULTISEG_API_BASE_URL=http://localhost:8080/api

Déploiement

# Construction et lancement
docker-compose up --build

# Ou en arrière-plan
docker-compose up -d --build

# Accès à l'application
# Interface web: http://localhost:8080
# API docs: http://localhost:8080/api/docs
# Health check: http://localhost:8080/health

Test local sans docker-compose

# Lancement avec port personnalisé
docker build -t multiseg-api .
docker run -p 3000:3000 \
  -e NGINX_PORT=3000 \
  -e MLFLOW_TRACKING_URI=http://host.docker.internal:5000 \
  -e MULTISEG_API_BASE_URL=http://localhost:3000/api \
  multiseg-api

Option 2: Installation Locale (Développement)

Pour l'expérimentation et l'entraînement

cd notebooks
pip install -r requirements.txt

Pour l'API uniquement

cd app
pip install -r requirements.txt

# Lancement manuel des services
# Terminal 1: FastAPI
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Terminal 2: Streamlit  
streamlit run app/streamlit_app.py --server.port 8501

🌐 Utilisation de l'API

Endpoints Principaux

Segmentation d'image

# Upload et segmentation via curl
curl -X POST "http://localhost:8080/api/segment" \
  -F "file=@image.jpg" \
  -F "model_name=unet_mobilenetv2" \
  -F "confidence_threshold=0.5"

Informations sur les modèles

# Liste des modèles disponibles
curl "http://localhost:8080/api/models"

# Détails d'un modèle
curl "http://localhost:8080/api/models/unet_mobilenetv2"

Monitoring

# Health check
curl "http://localhost:8080/health"

# Métriques API
curl "http://localhost:8080/api/metrics"

Interface Web

L'interface Streamlit accessible sur http://localhost:8080 permet :

• Upload d'images par glisser-déposer ou sélection
• Sélection du modèle parmi les modèles disponibles
• Ajustement des paramètres (seuil de confiance, etc.)
• Visualisation des résultats avec overlay des segmentations
• Téléchargement des masques de segmentation

🔧 Architecture de Déploiement

Structure des Services

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   nginx:8080    │────│  FastAPI:8000    │────│   MLFlow/MinIO  │
│  (Reverse Proxy)│    │  (API Backend)   │    │ (Model Storage) │
└─────────┬───────┘    └──────────────────┘    └─────────────────┘
          │
┌─────────▼───────┐
│  Streamlit:8501 │
│ (Web Interface) │
└─────────────────┘

Volumes et Persistance

• Modèles : Téléchargés depuis MLFlow/MinIO au démarrage
• Uploads temporaires : Stockage en mémoire (pas de persistance)
• Logs : Accessibles via docker-compose logs

Monitoring et Logs

# Logs en temps réel
docker-compose logs -f

# Logs d'un service spécifique
docker-compose logs -f multiseg-api

# Métriques de performance
curl http://localhost:8080/api/metrics

🔮 Améliorations Futures

Modèles et Performance

• Prétraitement adaptatif : Prétraitement spécifique à chaque backbone au lieu de la normalisation générique
• Optimisation temps réel : Amélioration des performances d'inférence pour déploiement embarqué
• Résolution d'entraînement améliorée : L'API accepte toutes les résolutions d'images, mais l'entraînement a été effectué sur des images redimensionnées à 224x224. Un réentraînement sur des résolutions supérieures (512x512, 1024x1024) pourrait améliorer la précision en capturant plus de détails fins, au prix d'une augmentation des besoins en puissance de calcul
• Transfer learning ciblé : Utilisation de backbones pré-entraînés sur Mapillary Vistas

Infrastructure et Déploiement

• Scaling horizontal : Support Kubernetes pour déploiement multi-instances
• Cache intelligent : Mise en cache des prédictions pour images similaires
• API Gateway : Intégration d'un gateway pour authentification et rate limiting
• Monitoring avancé : Intégration Prometheus/Grafana pour métriques détaillées

Données et Généralisation

• Généralisation des conditions : Extension au-delà des conditions urbaines de Cityscapes
• Segmentation des personnes : Amélioration de l'IoU via data augmentation (IA générative)
• Datasets additionnels : Intégration de datasets complémentaires pour robustesse

---

Projet développé dans une approche de souveraineté technologique, privilégiant les solutions open-source et l'hébergement sur infrastructure personnelle.