Feat bioclip v4

.gitignore

@@ -165,4 +165,9 @@ cython_debug/
 nohup.out
 data/
 notebooks/
-.DS_Store
+.DS_Store
+images/
+labels/
+failed_downloads.csv
+metadata.csv
+data.yaml

ml/classification/BioCLIP/README.md

@@ -0,0 +1,105 @@
+# 🌊 Identification automatique des espèces avec système hybride BioCLIP + enrichissement taxonomique GBIF
+
+**84.1% accuracy · Top 100 espèces · 88% de couverture**
+
+---
+
+## Approche
+
+Le système repose sur [BioCLIP](https://huggingface.co/imageomics/bioclip), un modèle CLIP entraîné sur 10 millions d'images d'organismes vivants (TreeOfLife-10M). BioCLIP est utilisé comme **feature extractor gelé** (vecteurs 512d) — seule la tête de classification est adaptée aux données BioLit.
+
+Les données BioLit ont été enrichies via l'API GBIF pour récupérer la hiérarchie taxonomique complète (règne, embranchement, classe, ordre, famille, genre) de chaque espèce, utilisée notamment pour construire les descriptions textuelles des prototypes Proto-CLIP (`export_biolit_enriched.csv`).
+
+L'architecture finale est un **système hybride à deux composantes** :
+
+- Un **classifier MLP** entraîné sur les 50 espèces les plus représentées (>50 images), opérant sur les features BioCLIP 512d originales
+- Un **réseau prototypique** pour les 50 espèces rares (10–50 images), avec fusion visuel/textuel Proto-CLIP, opérant sur les features **whitened 256d**
+
+Le routing entre les deux est déterminé par des seuils de confiance calibrés sur le jeu de validation.
+
+Cette approche résout le déséquilibre fort des données BioLit : le classifier gère les espèces communes avec haute précision (89.7%), tandis que les prototypes permettent une classification few-shot des espèces rares sans surapprentissage (51.1%).
+
+**Références scientifiques :**
+- Prototypes pondérés par similarité : [arXiv:2110.11553](https://arxiv.org/abs/2110.11553)
+- Température apprise par descente de gradient : [arXiv:2108.00340](https://arxiv.org/abs/2108.00340)
+- Proto-CLIP (fusion visuel + textuel) : [arXiv:2307.03073](https://arxiv.org/abs/2307.03073)
+- Whitening + PCA sur features BioCLIP : Wu et al. ECCV2020 
+
+---
+
+## Résultats
+
+|                | Espèces communes (top 50) | Espèces rares (51–100) | Global     |
+|----------------|--------------------------|------------------------|------------|
+| Accuracy       | 89.7%                    | 51.1%                  | **84.1%**  |
+| Couverture     | —                        | —                      | 88.0%      |
+
+Le taux de rejet (12%) correspond aux images sous le seuil de confiance minimal — le modèle préfère ne pas répondre plutôt que de prédire avec une faible certitude.
+
+**Test terrain (40 images .webp)** : 72.5% classifiées, 27.5% rejetées — l'écart avec le benchmark est attendu vu la variabilité des conditions de prise de vue terrain.
+
+---
+
+## Modèles pré-entraînés
+
+| Fichier | Description |
+|---|---|
+| `best_model_top50.pth` | Classifier MLP — 50 espèces communes (features 512d) |
+| `prototypes_v4.pt` | Prototypes Proto-CLIP + transformation whitening — 100 espèces |
+
+---
+
+## Installation
+
+```bash
+pip install open-clip-torch torch torchvision pandas tqdm pillow
+```
+
+---
+
+## Inférence sur nouvelles images
+
+```bash
+python scripts/infer_local_v4.py \
+  --images     /chemin/vers/dossier/ \
+  --prototypes models/prototypes_v4.pt \
+  --classifier models/best_model_top50.pth \
+  --output     resultats_inference_biolit.csv \
+  --ext        webp        # ou jpg, png
+```
+
+**Colonnes du CSV de sortie :**
+
+| Colonne | Description |
+|---|---|
+| `espece_pred` | Espèce prédite (`?` si rejetée) |
+| `confiance` | Score de confiance [0–1] |
+| `methode` | `classifier_top50` / `classifier_top50_low` / `prototypical_rare` / `rejected` |
+| `top1_common` … `top3_proto` | Top 3 alternatives pour chaque composante |
+
+---
+
+## Structure des fichiers
+
+```
+models/
+├── best_model_top50.pth          # Classifier MLP 
+└── prototypes_v4.pt              # Prototypes + whitening transform
+└── README.md
+
+results/
+├── predictions_sample_test.csv   # Prédictions sur 40 images terrain
+└── export_biolit_enriched.csv    # Dataset BioLit enrichi GBIF
+└── README.md
+
+scripts/
+└── infer_local_v4.py         # Script d'inférence hybride v4 (CPU/GPU)
+
+README.md
+```
+
+---
+
+## Espèces couvertes
+
+Les 100 espèces correspondent aux espèces les plus observées dans la base BioLit au moment de l'entraînement (février 2026). La liste complète est disponible dans [`scripts/inference/infer_local_v4.py`](scripts/inference/infer_local_v4.py) (dictionnaire `SPECIES_DESCRIPTIONS`).

ml/classification/BioCLIP/models/README.md

@@ -0,0 +1,63 @@
+# Modèles pré-entraînés
+
+Ce dossier contient les deux modèles nécessaires à l'inférence du système hybride v4.
+
+---
+
+## Fichiers
+
+### `best_model_top50.pth`
+Classifier MLP entraîné sur les **50 espèces les plus représentées** dans BioLit (>50 images chacune).
+
+- **Architecture** : LayerNorm → Linear(512→512) → GELU → Dropout(0.5) → Linear(512→256) → GELU → Dropout(0.25) → Linear(256→50)
+- **Entrée** : features BioCLIP 512d (normalisées L2)
+- **Sortie** : logits sur 50 classes
+- **Accuracy** : 89.7% sur les espèces communes
+- **Entraîné sur** : GPU T4, dataset BioLit top100 (split 70/15/15)
+
+---
+
+### `prototypes_v4.pt`
+Prototypes Proto-CLIP pour les **100 espèces** (communes + rares), avec transformation whitening ..
+
+- **Prototypes visuels** : moyennes pondérées des features BioCLIP par espèce, 3 itérations de raffinement (arXiv:2110.11553)
+- **Fusion Proto-CLIP** : α=0.8 visuel + 0.2 textuel (arXiv:2307.03073)
+- **Espace** : features whitened 256d après PCA 
+- **Température** : T*=23.8, apprise par gradient (arXiv:2108.00340)
+- **Accuracy rares** : 51.1%
+
+**Clés contenues dans le `.pt` :**
+
+| Clé | Type | Description |
+|---|---|---|
+| `prototypes` | Tensor [100, 256] | Prototypes Proto-CLIP fusionnés |
+| `temperature` | float | Température T* apprise |
+| `idx_to_species` | dict | Index → nom espèce |
+| `species_to_idx` | dict | Nom espèce → index |
+| `whitening_mu` | numpy [1, 512] | Moyenne de centrage (whitening) |
+| `whitening_W` | numpy [512, 256] | Matrice de projection PCA |
+| `pca_dim` | int | Dimension cible (256) |
+| `alpha` | float | Coefficient fusion visuel/textuel (0.8) |
+| `seuil_top50` | float | Seuil confiance classifier (0.80) |
+| `seuil_proto` | float | Seuil confiance prototypes (0.40) |
+
+> **Important** : `whitening_mu` et `whitening_W` sont indispensables à l'inférence. Toute nouvelle image doit être projetée dans le même espace 256d avant comparaison aux prototypes. Le script `infer_local_v4.py` gère cela automatiquement.
+
+---
+
+## Chargement manuel
+
+```python
+import torch
+
+# Classifier
+ckpt = torch.load("best_model_top50.pth", map_location="cpu")
+# Clés : classifier_state_dict, idx_to_species, species_to_idx, num_species, feature_dim
+
+# Prototypes
+pt = torch.load("prototypes_v4.pt", map_location="cpu")
+prototypes  = pt["prototypes"]       # [100, 256]
+mu          = pt["whitening_mu"]     # numpy [1, 512]
+W           = pt["whitening_W"]      # numpy [512, 256]
+T           = pt["temperature"]      # float
+```

ml/classification/BioCLIP/results/README.md

@@ -0,0 +1,68 @@
+# Résultats
+
+Ce dossier contient les fichiers de sortie du système hybride v4 sur les données de test.
+
+---
+
+## Fichiers
+
+### `predictions_sample_test.csv`
+Prédictions du système hybride v4 sur **40 images terrain** (.webp), collectées sur le littoral français en conditions réelles après crop par Dino.
+
+**Colonnes :**
+
+| Colonne | Description |
+|---|---|
+| `image` | Nom du fichier image |
+| `espece_pred` | Espèce prédite (`?` si rejetée) |
+| `confiance` | Score de confiance de la prédiction retenue [0–1] |
+| `methode` | Composante ayant produit la prédiction finale |
+| `top1_common` | 1ère prédiction du classifier top50 |
+| `conf_common` | Confiance associée |
+| `top2_common` | 2ème alternative classifier |
+| `top3_common` | 3ème alternative classifier |
+| `top1_proto` | 1ère prédiction des prototypes |
+| `conf_proto` | Confiance associée |
+| `top2_proto` | 2ème alternative prototypes |
+| `top3_proto` | 3ème alternative prototypes |
+
+**Valeurs possibles de `methode` :**
+
+| Valeur | Signification |
+|---|---|
+| `classifier_top50` | Classifier confiant (conf ≥ 0.80) |
+| `classifier_top50_low` | Classifier accepté à confiance modérée (conf ≥ 0.40) |
+| `prototypical_rare` | Prototype confiant sur une espèce rare (conf ≥ 0.40) |
+| `rejected` | Les deux composantes sous le seuil — image non classifiée |
+
+**Résultats sur ces 40 images :**
+
+| Méthode | N | % | Conf. moy. |
+|---|---|---|---|
+| `classifier_top50` | 10 | 25.0% | 0.92 |
+| `classifier_top50_low` | 12 | 30.0% | 0.62 |
+| `prototypical_rare` | 7 | 17.5% | 0.86 |
+| `rejected` | 11 | 27.5% | — |
+
+- **Taux acceptées** : 72.5%
+- **Confiance moyenne (acceptées)** : 0.78
+
+> L'écart de couverture avec le benchmark (88%) est attendu : les images terrain présentent des conditions de prise de vue très variables (éclairage, angle, fond, espèces partiellement visibles) non représentées dans les données d'entraînement.
+
+---
+
+### `export_biolit_enriched.csv`
+Dataset BioLit enrichi via l'API GBIF avec la hiérarchie taxonomique complète de chaque espèce.
+
+**Colonnes ajoutées par enrichissement GBIF :**
+
+| Colonne | Description |
+|---|---|
+| `regne` | Règne (ex: Animalia, Plantae) |
+| `embranchement` | Embranchement (ex: Arthropoda) |
+| `classe` | Classe (ex: Malacostraca) |
+| `ordre` | Ordre |
+| `famille` | Famille |
+| `genre` | Genre |
+
+Ce fichier a servi à construire les descriptions textuelles utilisées dans les prototypes Proto-CLIP et à sélectionner les 100 espèces les plus représentées pour l'entraînement.