# Module de Capture d'Écran

## Vue d'ensemble

Le module `screen_capturer` fournit une interface unifiée pour capturer des screenshots avec fallback automatique entre différentes bibliothèques.

## Fonctionnalités

- ✅ Capture d'écran rapide avec `mss` (méthode préférée)
- ✅ Fallback automatique vers `pyautogui` si mss n'est pas disponible
- ✅ Détection de la fenêtre active avec `pygetwindow`
- ✅ Conversion automatique au format RGB numpy
- ✅ Validation des images capturées
- ✅ Gestion propre des ressources

## Installation

```bash
# Installer les dépendances
cd rpa_vision_v3
./install_capture_deps.sh

# Ou manuellement
pip install mss>=9.0.0 pygetwindow>=0.0.9
```

## Utilisation

### Capture Simple

```python
from core.capture.screen_capturer import ScreenCapturer

# Initialiser le capturer
capturer = ScreenCapturer()

# Capturer l'écran
img = capturer.capture()  # numpy array (H, W, 3) RGB

# Vérifier la capture
if img is not None:
    print(f"Image capturée: {img.shape}")
```

### Détection de Fenêtre Active

```python
# Obtenir les infos de la fenêtre active
window = capturer.get_active_window()

if window:
    print(f"Fenêtre: {window['title']}")
    print(f"Position: ({window['x']}, {window['y']})")
    print(f"Taille: {window['width']}x{window['height']}")
```

### Intégration avec PIL

```python
from PIL import Image

# Capturer et convertir en PIL Image
img_array = capturer.capture()
img_pil = Image.fromarray(img_array)

# Sauvegarder
img_pil.save("screenshot.png")
```

## Architecture

```
ScreenCapturer
├── __init__()          # Initialise avec mss ou pyautogui
├── capture()           # Capture l'écran complet
├── get_active_window() # Détecte la fenêtre active
├── _capture_mss()      # Capture avec mss (rapide)
└── _capture_pyautogui()# Capture avec pyautogui (fallback)
```

## Performance

| Méthode | Temps moyen | Mémoire |
|---------|-------------|---------|
| mss | ~10-20ms | Faible |
| pyautogui | ~50-100ms | Moyenne |

**Recommandation**: Utiliser `mss` pour les captures fréquentes.

## Format de Sortie

- **Type**: `numpy.ndarray`
- **Shape**: `(hauteur, largeur, 3)`
- **Dtype**: `uint8`
- **Ordre des canaux**: RGB (pas BGR)
- **Valeurs**: 0-255

## Gestion d'Erreurs

```python
try:
    img = capturer.capture()
    if img is None:
        print("Capture a échoué")
except Exception as e:
    print(f"Erreur: {e}")
```

## Tests

```bash
# Tester le module
python examples/test_screen_capturer.py

# Résultat attendu:
# ✓ Méthode utilisée: mss
# ✓ Image capturée: (1080, 1920, 3)
# ✓ Format RGB valide
# ✓ Fenêtre active détectée
```

## Dépendances

### Obligatoires
- `numpy>=1.24.0`

### Optionnelles (au moins une requise)
- `mss>=9.0.0` (recommandé)
- `pyautogui>=0.9.54` (fallback)

### Pour détection de fenêtre
- `pygetwindow>=0.0.9`

## Limitations

1. **Multi-écrans**: Capture actuellement le moniteur principal uniquement
2. **Fenêtre active**: Peut ne pas fonctionner sur tous les gestionnaires de fenêtres Linux
3. **Permissions**: Peut nécessiter des permissions spéciales sur certains systèmes

## Compatibilité

- ✅ Linux (X11)
- ✅ Linux (Wayland) - avec limitations
- ✅ Windows
- ✅ macOS

## Troubleshooting

### Erreur: "Neither mss nor pyautogui available"

```bash
pip install mss pyautogui
```

### Erreur: "Captured image has invalid dimensions"

Vérifier que l'écran est bien détecté:
```python
import mss
with mss.mss() as sct:
    print(sct.monitors)
```

### Fenêtre active non détectée

Sur certains systèmes Linux, installer:
```bash
sudo apt-get install python3-xlib
```

## Exemples Avancés

### Capture d'une région spécifique

```python
# TODO: À implémenter
# capturer.capture_region(x, y, width, height)
```

### Capture avec timestamp

```python
from datetime import datetime

img = capturer.capture()
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
filename = f"screenshot_{timestamp}.png"

Image.fromarray(img).save(filename)
```

## Roadmap

- [ ] Support de capture de région spécifique
- [ ] Support multi-écrans avec sélection
- [ ] Cache de captures pour optimisation
- [ ] Compression automatique des images
- [ ] Support de formats de sortie alternatifs (JPEG, WebP)

## Contribution

Pour améliorer ce module, voir `rpa_vision_v3/docs/specs/tasks.md`.