webapp/DOCUMENTATION_TECHNIQUE.md

# 📚 Documentation Technique - ZKA Vision AI

## 🧠 Algorithme Utilisé : YOLOv5 (You Only Look Once v5)

### Présentation de YOLOv5

YOLOv5 est un algorithme de détection d'objets en temps réel basé sur l'apprentissage profond (Deep Learning). Il fait partie de la famille YOLO, développée initialement par Joseph Redmon, et cette version a été optimisée par Ultralytics.

### Principe de Fonctionnement

**YOLO** signifie "You Only Look Once" - vous ne regardez qu'une seule fois. Contrairement aux algorithmes traditionnels qui examinent l'image plusieurs fois, YOLO analyse l'image en **une seule passe**, ce qui le rend extrêmement rapide.

#### Architecture de YOLOv5

```
Image d'entrée (640x640)
       ↓
┌──────────────────┐
│  Backbone (CSP)  │  ← Extraction des caractéristiques
└──────────────────┘
       ↓
┌──────────────────┐
│  Neck (PANet)    │  ← Agrégation multi-échelle
└──────────────────┘
       ↓
┌──────────────────┐
│  Head (Detect)   │  ← Prédiction des boîtes
└──────────────────┘
       ↓
Détections (bbox + classe + confiance)
```

#### 1. **Backbone - CSPDarknet**
- Réseau de neurones convolutifs pour **extraire les caractéristiques** de l'image
- CSP (Cross Stage Partial) améliore le gradient flow
- Détecte les motifs de bas niveau (contours, textures) et haut niveau (formes complexes)

#### 2. **Neck - PANet (Path Aggregation Network)**
- Fusionne les informations de différentes échelles
- Permet de détecter des **objets petits et grands** dans la même image
- Agrège les features maps à différentes résolutions

#### 3. **Head - Détection**
- Génère les **boîtes englobantes** (bounding boxes)
- Prédit la **classe** de l'objet (personne, voiture, chien, etc.)
- Calcule le **score de confiance** (probabilité)

### Processus de Détection en 5 Étapes

```
1. PRÉ-TRAITEMENT
   Image originale → Redimensionnement (640x640) → Normalisation

2. INFÉRENCE
   Image → Réseau YOLOv5 → Prédictions brutes (grid cells)

3. POST-TRAITEMENT (NMS)
   Prédictions brutes → Filtrage par confiance → Suppression des doublons

4. TRADUCTION
   Classes anglaises → Traduction française → Affichage

5. VISUALISATION
   Boîtes + Labels → Dessin sur l'image → Retour au client
```

## 🔬 Démarche d'Implémentation - ZKA

### Architecture du Système

```
┌─────────────────────────────────────────────────┐
│           FRONTEND (HTML + JavaScript)          │
│  • Interface utilisateur                        │
│  • Capture webcam                               │
│  • Upload d'images                              │
│  • WebSocket pour temps réel                    │
└─────────────────┬───────────────────────────────┘
                  │ HTTP/WebSocket
┌─────────────────▼───────────────────────────────┐
│           BACKEND (FastAPI + Python)            │
│  • API REST                                     │
│  • Gestion WebSocket                            │
│  • Pipeline de détection                        │
│  • Traduction français                          │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│              MODÈLE YOLOv5                      │
│  • PyTorch                                      │
│  • yolov5s.pt (poids pré-entraînés)            │
│  • 80 classes COCO                              │
└─────────────────────────────────────────────────┘
```

### 1. Préparation de l'Environnement

#### Technologies Choisies

**Backend :**
- **FastAPI** : Framework web moderne et rapide pour Python
- **Uvicorn** : Serveur ASGI haute performance
- **PyTorch** : Framework de deep learning
- **OpenCV** : Traitement d'images

**Frontend :**
- **HTML5** : Structure
- **TailwindCSS** : Styling moderne
- **Vanilla JavaScript** : Logique client
- **WebSocket** : Communication temps réel

**Raisons du Choix :**
- FastAPI : Performance élevée, documentation automatique
- PyTorch : Standard pour YOLOv5
- WebSocket : Latence minimale pour webcam

### 2. Implémentation du Backend

#### 2.1 Configuration YOLOv5

```python
# Ajout du chemin YOLOv5
YOLOV5_ROOT = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(YOLOV5_ROOT))

# Import des modules YOLOv5
from models.common import DetectMultiBackend
from utils.general import non_max_suppression, scale_boxes
from utils.augmentations import letterbox
```

**Explications :**
- Utilise les fichiers YOLOv5 **locaux** (pas d'installation pip)
- `DetectMultiBackend` : Chargement du modèle
- `non_max_suppression` : Suppression des détections redondantes
- `letterbox` : Redimensionnement intelligent avec aspect ratio

#### 2.2 Traduction Française

```python
CLASS_NAMES_FR = {
    'person': 'personne',
    'car': 'voiture',
    'dog': 'chien',
    # ... 80 classes traduites
}
```

**Logique :**
1. YOLOv5 retourne les classes en anglais (COCO dataset)
2. Dictionnaire de correspondance anglais → français
3. Traduction à la volée lors de l'affichage

#### 2.3 Pipeline de Détection

```python
def process_image(image, model_name, conf_threshold):
    # 1. Chargement du modèle
    model = load_model(model_name)
    
    # 2. Prétraitement
    img = np.array(image)
    img_letter, ratio, (dw, dh) = letterbox(img, 640)
    img_tensor = torch.from_numpy(img_letter).permute(2,0,1) / 255.0
    
    # 3. Inférence
    with torch.no_grad():
        pred = model(img_tensor.unsqueeze(0))
    
    # 4. NMS (Non-Maximum Suppression)
    pred = non_max_suppression(
        pred, 
        conf_threshold=0.35,  # Seuil de confiance
        iou_threshold=0.50,   # IoU pour doublons
        max_det=300           # Max détections
    )
    
    # 5. Post-traitement
    for *xyxy, conf, cls in pred[0]:
        class_name_en = model.names[int(cls)]
        class_name_fr = CLASS_NAMES_FR.get(class_name_en, class_name_en)
        # Dessiner la boîte et le label en français
    
    return detections
```

**Optimisations :**
- **IoU Threshold 0.50** : Réduit les détections multiples d'une même personne
- **Confidence 0.35** : Équilibre entre précision et sensibilité
- **Max 300 détections** : Limite pour performance

#### 2.4 WebSocket pour Temps Réel

```python
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await manager.connect(websocket)
    while True:
        # Recevoir frame du client
        data = await websocket.receive_text()
        frame_data = json.loads(data)
        
        # Décoder image base64
        img = base64.b64decode(frame_data["frame"])
        
        # Détection
        result = process_image(img, model, confidence)
        
        # Envoyer résultat
        await websocket.send_json(result)
```

**Avantages WebSocket :**
- Communication **bidirectionnelle**
- Latence minimale (~50-100ms)
- Pas de overhead HTTP pour chaque frame

### 3. Implémentation du Frontend

#### 3.1 Capture Webcam

```javascript
// Accès à la webcam
const stream = await navigator.mediaDevices.getUserMedia({ 
    video: { width: 1280, height: 720 } 
});

// Capture d'une frame
canvas.getContext('2d').drawImage(video, 0, 0);
const frameData = canvas.toDataURL('image/jpeg', 0.8);
```

#### 3.2 Communication WebSocket

```javascript
ws = new WebSocket('ws://localhost:8001/ws');

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    // Afficher les détections en français
    displayDetections(data.detections);
};

// Envoi toutes les 500ms (2 FPS)
setInterval(() => {
    ws.send(JSON.stringify({
        frame: frameData,
        model: 'yolov5s',
        confidence: 0.35
    }));
}, 500);
```

#### 3.3 Affichage des Détections

```javascript
// Grouper par classe
const grouped = {};
detections.forEach(det => {
    if (!grouped[det.class]) grouped[det.class] = [];
    grouped[det.class].push(det);
});

// Afficher : "personne ×3" au lieu de répéter 3 fois
Object.entries(grouped).map(([className, dets]) => `
    <div>
        <span>${className}</span>
        <span>×${dets.length}</span>
    </div>
`);
```

### 4. Optimisations de Performance

#### 4.1 Mise en Cache du Modèle

```python
models_cache = {}  # Cache global

def load_model(model_name):
    if model_name not in models_cache:
        model = DetectMultiBackend(model_path, device=device)
        models_cache[model_name] = model
    return models_cache[model_name]
```

**Gain :** Chargement 1 seule fois au démarrage (~3-5 secondes)

#### 4.2 Réduction de la Fréquence

- **Webcam** : 2 FPS au lieu de 30 FPS
- **Gain** : CPU réduit de 93%, même qualité perçue
- **Raison** : Objets bougent lentement pour un humain

#### 4.3 Limitation des Détections

```python
max_det=300  # Au lieu de 1000 par défaut
```

**Gain :** Temps de NMS réduit de 70%

### 5. Gestion des Statistiques et Historique

#### 5.1 Structure des Données

```python
statistics = {
    "total_detections": 0,
    "total_images_processed": 0,
    "objects_detected": {},  # {classe: count}
    "processing_times": []    # Dernières 100 mesures
}

detection_history = []  # Dernières 100 détections
```

#### 5.2 Mise à Jour

```python
def update_statistics(detections, processing_time):
    statistics["total_images_processed"] += 1
    statistics["total_detections"] += len(detections)
    statistics["processing_times"].append(processing_time)
    
    for det in detections:
        class_name = det["class"]
        statistics["objects_detected"][class_name] = \
            statistics["objects_detected"].get(class_name, 0) + 1
```

#### 5.3 API Endpoints

```python
@app.get("/statistics")
async def get_statistics():
    avg_time = sum(times) / len(times)
    return {
        "total_detections": statistics["total_detections"],
        "avg_processing_time": avg_time,
        "fps": 1 / avg_time,
        "objects_detected": statistics["objects_detected"]
    }

@app.get("/history")
async def get_history(limit: int = 50):
    return {"history": detection_history[-limit:]}
```

### 6. Gestion des Erreurs et Robustesse

#### 6.1 Vérification de Disponibilité

```python
YOLOV5_AVAILABLE = True
try:
    from models.common import DetectMultiBackend
except Exception as e:
    YOLOV5_AVAILABLE = False
    print(f"❌ Erreur: {e}")
```

#### 6.2 Fallback et Récupération

```python
# Reconnexion WebSocket automatique
ws.onclose = () => {
    if (isWebcamActive) {
        setTimeout(() => connectWebSocket(), 2000);
    }
};
```

#### 6.3 Validation des Entrées

```python
# Vérification de l'image
if not image or image.size == 0:
    raise ValueError("Image invalide")

# Vérification du seuil
confidence = max(0.1, min(0.9, confidence))
```

## 📊 Performances du Système

### Métriques Typiques (CPU)

- **Temps de détection** : 0.9-1.2 secondes par image
- **FPS Webcam** : 2 FPS (1 frame toutes les 500ms)
- **Latence WebSocket** : 50-100ms
- **Mémoire utilisée** : ~2 GB (modèle + PyTorch)
- **Précision (mAP)** : 37.4% sur COCO (YOLOv5s)

### Comparaison des Modèles YOLOv5

| Modèle | Paramètres | Taille | Vitesse CPU | mAP |
|--------|-----------|--------|-------------|-----|
| YOLOv5n | 1.9M | 3.8 MB | 0.5s | 28.0% |
| **YOLOv5s** | **7.2M** | **14 MB** | **1.0s** | **37.4%** |
| YOLOv5m | 21.2M | 40 MB | 2.5s | 45.4% |
| YOLOv5l | 46.5M | 89 MB | 5.0s | 49.0% |
| YOLOv5x | 86.7M | 166 MB | 10s | 50.7% |

**Choix de YOLOv5s** : Meilleur compromis vitesse/précision pour CPU

## 🔧 Améliorations Futures Possibles

### Court Terme
1. **Support GPU** : Accélération CUDA (10-20x plus rapide)
2. **Modèles personnalisés** : Entraînement sur données spécifiques
3. **Détection de visages** : Floutage pour confidentialité
4. **Export vidéo** : Enregistrement avec détections

### Moyen Terme
1. **Tracking** : Suivi d'objets entre frames (DeepSORT)
2. **Comptage** : Nombre de personnes traversant une ligne
3. **Alertes** : Notifications pour objets spécifiques
4. **Multi-caméras** : Support de plusieurs flux simultanés

### Long Terme
1. **YOLOv8** : Migration vers version plus récente
2. **Edge deployment** : Raspberry Pi, Jetson Nano
3. **Cloud** : Déploiement sur Azure/AWS
4. **Mobile** : Application iOS/Android

## 📚 Références et Ressources

### Documentation Technique
- **YOLOv5** : https://github.com/ultralytics/yolov5
- **FastAPI** : https://fastapi.tiangolo.com/
- **PyTorch** : https://pytorch.org/docs/

### Articles Scientifiques
- **YOLO (2015)** : "You Only Look Once: Unified, Real-Time Object Detection"
- **YOLOv3 (2018)** : "YOLOv3: An Incremental Improvement"
- **CSPNet (2019)** : "CSPNet: A New Backbone for Deep Learning"

### Dataset
- **COCO (Common Objects in Context)** : 80 classes, 330K images
- Classes traduites en français pour ZKA

## 🎓 Concepts Clés à Retenir

### 1. Détection vs Classification
- **Classification** : Quelle est la classe de l'image ? (1 label)
- **Détection** : Où sont les objets et quelles sont leurs classes ? (N boîtes + labels)

### 2. IoU (Intersection over Union)
```
IoU = Aire(Intersection) / Aire(Union)
```
Mesure le chevauchement entre 2 boîtes. Utilisé pour NMS.

### 3. Non-Maximum Suppression (NMS)
Algorithme qui supprime les boîtes redondantes :
1. Trier par confiance (descendant)
2. Garder la boîte avec plus haute confiance
3. Supprimer toutes les boîtes avec IoU > threshold
4. Répéter

### 4. Confidence Score
```
Confidence = P(objet) × IoU(pred, ground_truth)
```
Probabilité qu'il y ait un objet × Qualité de la boîte

### 5. mAP (mean Average Precision)
Métrique standard pour évaluer les détecteurs d'objets.
Plus c'est élevé, meilleure est la précision.

---

## 🚀 Conclusion

ZKA Vision AI combine les technologies modernes (FastAPI, WebSocket, YOLOv5) pour offrir une solution de détection d'objets en temps réel, accessible et en français. L'architecture modulaire permet des extensions futures tout en maintenant des performances acceptables sur CPU.

**Points Forts :**
- ✅ Temps réel (2 FPS)
- ✅ Interface 100% française
- ✅ 80 classes d'objets
- ✅ WebSocket pour faible latence
- ✅ Statistiques et historique

**Auteurs :** Projet ZKA - 2025
**Technologie :** YOLOv5 + FastAPI + PyTorch