# Séries optiques : détecter les événements externes et corriger les courbes
- **Date** : 2026-10-14.
- **Statut** : cadrage. Rien n'est construit ; ce document fixe une direction et un démarrage par étapes. Décision liée : D-044 (`docs/decisions.md`).
- **Place** : premier chantier du cas d'usage suivant, les **déplacements** (`CLAUDE.md`, Principes). Couche déterministe : analytique, embarquable, sans LLM (D-003).
- **Principe de travail** : un socle minimal d'abord ; chaque étape décide si la suivante est nécessaire. Les détails proposés sont des pistes (annexe), pas des décisions.
---
## 1. Objet
Les domaines livrés portent sur les **états de la station** (batterie, disque, 4G, température). Ce chantier porte sur **ce qu'elle mesure** : les déplacements des cibles (`rch`, `rcv`, voir `docs/domaine/colonnes-des-deplacements.md`).
**Le besoin.** Des événements extérieurs à l'ouvrage perturbent la mesure : pluie, passage d'un véhicule, etc. Ils laissent sur les courbes des pics, du bruit ou des trous que le client peut prendre pour un mouvement. Il faut :
1.**détecter** ces événements et dire lesquels, avec preuves ;
2.**corriger** les courbes pour en compenser l'effet, sans effacer un mouvement réel.
**Ce qu'on appelle « événement externe »** : une cause hors de l'ouvrage et hors de la station qui change l'*image* de la cible.
| Famille | Exemples | Source qui la cite |
|---|---|---|
| Occlusion passagère | véhicule, personne, animal, végétation au vent, engin | FAQ (*Error Value*, *error column*), manuel p. 11 |
| Eau, neige, saleté | pluie, condensation, neige sur la cible ou la vitre de la caméra | FAQ (*Error Value*, *noisy or invalid*) |
| Turbulence, chaleur | brume de chaleur (*heat shimmer*) sur le trajet optique | FAQ (*atmospheric turbulence*), manuel (*Sharpness*) |
**Ce qui n'en est pas** (et reste hors correction) : mouvement réel de l'ouvrage, mouvement de la caméra (déjà compensé par la station), instabilité de la compensation, parallaxe. Ces causes se départagent ailleurs (`colonnes-des-deplacements.md`, enquête à la demande D-042).
## 2. Ce que la station fait déjà (à ne pas refaire)
- **Moyenne d'images** : chaque mesure combine ~20 à 40 images pour réduire la turbulence (FAQ).
- **Filtre d'obstruction** : une mesure dont l'`error` dépasse l'*Error Threshold* (0,7 par défaut) est jugée invalide (FAQ, manuel p. 11).
- **Data Exploration** : surligner, masquer ou interpoler les points à erreur élevée, appliquer une médiane glissante (manuel p. 13, FAQ).
- **Compensation caméra** : `rch` / `rcv` sont déjà corrigés du mouvement de la caméra.
**Notre valeur ajoutée** n'est donc pas un filtre de plus, mais :
- **dire pourquoi** un point est écarté ou corrigé (la cause, avec les faits), là où la station applique un seuil muet ;
- **graduer** au lieu d'un seuil binaire : un poids continu par observation (roadmap §5.2, *image_quality_weight*) ;
- **agir sans qu'on le demande** : les événements sont signalés avant que le client ne pose la question.
## 3. Règles qui encadrent la correction
Elles découlent des règles non négociables de `CLAUDE.md` et des anti-patterns du contexte support (§27).
- **La série brute n'est jamais remplacée.** La courbe corrigée est une série dérivée, affichée à côté de la brute. Chaque point modifié porte sa raison : la règle et les faits (contexte support §27 : *do not silently merge original and reprocessed data*).
- **Lecture seule** : on ne retraite rien sur la station et on ne touche pas à sa configuration.
- **Asymétrie du risque** : effacer un mouvement réel coûte plus cher que laisser du bruit. On ne corrige un point que si la cause externe est au moins `strongly supported` ; sinon on le signale sans le corriger. Une marche qui persiste reste un mouvement réel candidat tant qu'il n'est pas réfuté.
- **Calcul causal**, comme les autres analyses (`.claude/rules/analyses.md`) : le point t n'utilise que les données ≤ t.
- **Pas de décision sur `inlier` binaire** ; poids continus, résidus, `N_eff` (roadmap §5, §7).
- **Aucun seuil sans source**, **pas de données synthétiques** : validation sur des cas réels seulement.
## 4. Architecture proposée
Une chaîne en trois étapes, par cible et par époque de mesure :
```
export optique (CSV ; HDF5 plus tard)
│ chargement (src/common/) → séries par cible : rch, rcv, x, y, error, camera_*, sigma0
▼
1. Qualifier chaque observation → poids 0..1 + raison (roadmap §5.2, Stage A)
▼
2. Détecter et classer les événements → intervalles, cibles touchées, famille,
niveau de preuve, faits (contexte support §11.2, §11.3)
▼
3. Corriger → série corrigée ; pour chaque point :
gardé / masqué / lissé, et pourquoi
```
### 4.1 Signatures attendues
Hypothèses de départ, à confronter aux données (étape 1).
| Famille | Signature dans les données | Champs utiles | Correction envisagée |
|---|---|---|---|
| Occlusion passagère | 1 ou quelques cibles ; `error` monte d'un coup ; 1 à quelques époques ; revient à l'identique ; pas de mode commun | `error`, `rch`/`rcv`, `x`/`y` | masquer le point (interpolation pour l'affichage seulement, marquée) |
| Eau, neige | plusieurs cibles, toutes si c'est la vitre ; `error` haut et dispersion forte pendant des heures ; neige : des jours | `error` ; Flux, SNR (HDF5) | baisser le poids, masquer si la cible est couverte |
| Turbulence | toutes les cibles, surtout les lointaines ; dispersion forte l'après-midi ensoleillé ; cycle de 24 h | Sharpness, FWHM (HDF5) ; dispersion | lissage robuste sur la période |
| Éclairage | cycle de 24 h ; changement d'intensité | Peak Intensity, Flux (HDF5) | baisser le poids |
**Outils de détection du socle** : ceux que le contexte support liste déjà comme calculs déterministes (§11.2-11.3) : médiane et MAD locales, score z robuste, persistance, réversibilité, part des cibles touchées, composante commune.
**Outil de correction du socle** : le masque, puis une **médiane glissante** sur les points gardés. La station la propose déjà ; elle respecte mieux les marches qu'une moyenne. Sa fenêtre reste à choisir et à sourcer (étape 3).
### 4.2 Sortie
- Par cible : la série corrigée, et pour chaque point son statut (`kept`, `masked`, `smoothed`) avec le poids et la raison.
- Par événement : début, fin, cibles touchées, famille, vocabulaire de preuve (`consistent with` … `strongly supported`), faits calculés, règle.
- Les événements alimentent ensuite l'enquête à la demande (D-042) : son outil `get_series` rendrait la brute, la corrigée et les événements.
### 4.3 Place dans le dépôt (D-026)
-`src/displacement/` : calcul embarquable (bibliothèque standard, contrat `run(series)` par cible) ; page de comparaison `all_analyses.py` (brute contre corrigée, bandes d'événements).
-`src/common/stations.py` : un chargeur pour l'export « advanced » des déplacements, qui a une ligne par capteur et par mesure dans un même fichier (les métriques système ont un fichier par métrique ; formats : `colonnes-des-deplacements.md`).
1.**un export de déplacements** d'une station (colonnes de `colonnes-des-deplacements.md`), **à sa cadence native** : en moyenne horaire, un véhicule qui passe disparaît ;
2.**des événements connus** sur cette période : jours de pluie ou de neige, passages notés, images de la caméra. La météo publique du lieu peut servir à **valider**, pas d'entrée au départ (la station doit rester autonome) ;
3.**l'export HDF5**, idéalement (Sharpness, FWHM, Flux, SNR) : sans lui, `error` seul distingue mal l'eau, la turbulence et l'occlusion ;
4.**la configuration des cibles** : distances, cibles de référence, seuil d'erreur appliqué.
**Reçu le 2026-10-14 aussi** : deux rapports d'analyse AIMsight sur des murs de soutènement (GN-1.472 et GN-5.054, `docs/aimsight/`), résumés dans `domaine/cas-annotes-par-l-expert.md`. Des événements connus (point 2) et leur cause selon l'expert, mais sans les exports : un catalogue de signatures, pas un jeu de test.
1.**Explorer** : `domaine/point-de-depart.md` : cadence, bruit par cible, distribution d'`error`, export déjà filtré ou non, jours de pluie connus face aux jours secs.
2.**Occlusion passagère** : la plus simple et la mieux signée. Détecter (pic d'`error` ou score z robuste sur une cible, réversible, sans mode commun), masquer, afficher brute et corrigée. Vérifier sur les passages connus.
3.**Lissage robuste** : médiane glissante causale sur les points gardés. Mesurer ce qu'elle fait au bruit (dispersion avant et après) et à une marche réelle connue (retard, amplitude), puis choisir la fenêtre.
4.**Précipitation** : signature sur plusieurs cibles, validée contre la météo du lieu ; correction par le poids ou le masque.
5.**Turbulence et éclairage** : seulement avec le HDF5.
6.**Brancher** : outil de l'enquête à la demande (D-042) ; affichage sur le site, format à voir avec l'équipe du site.
1. Quelle station et quelle période, avec quels événements connus (§5) ? *Réponse (D-045) : PS des Coudres, du 08/10 au 14/10 ; aucun événement annoté, buée probable le matin.*
2. Quelle est la cadence native des mesures ? Les CSV exportés sont-ils déjà filtrés par le seuil d'erreur, ou interpolés ? *Réponse : 15 min ; ni filtré ni interpolé : une mesure rejetée garde sa ligne, déplacement vide.*
3. L'export HDF5 est-il disponible pour cette station ? *Inconnu de l'utilisateur.*
4. Qui voit la courbe corrigée : le client, le support, les deux ? Le client voit-il aussi la brute ?
5. Correction au fil de l'eau (causale, sur la station) seulement, ou aussi a posteriori (fenêtre centrée, meilleur lissage mais non causale) ?
6. La météo publique est-elle acceptable comme entrée plus tard, ou pour la validation seulement ?
7. Quelle est l'amplitude des mouvements réels attendus (mm par jour, marche brusque) face au bruit ? Elle borne la fenêtre de lissage.
8. La dilatation thermique de l'ouvrage est un mouvement réel, mais d'origine extérieure : la laisser telle quelle (choix par défaut) ou la proposer à part ?
9. Pourquoi le seuil d'erreur de PM_G (PS des Coudres) est-il à 0,3, contre 0,7 ailleurs et 0,45 pour `REF_CT` ? Avec une erreur médiane de 0,42, la cible est rejetée sur toute la plage.
10. Quelle est l'unité de `corr_x` / `corr_y` ? Le déplacement horaire en vaut 0,61 à 7,9 fois la moyenne selon le motif (`colonnes-des-deplacements.md`).
- **Remplacer la série brute par la corrigée** : perte de traçabilité, risque d'effacer un vrai mouvement (§3).
- **Lisser tout uniformément sans détecter** : n'explique rien et écrase les marches. Le lissage ne vient qu'après la détection.
- **Modèle appris ou LLM dans cette couche** : pas de cas annotés, non traçable, pas embarquable (D-003).
- **Données synthétiques pour valider** : refus de l'utilisateur (`CLAUDE.md`).
- **Décision sur `inlier` binaire** : RANSAC sera remplacé (roadmap §11).
## Annexe : pistes à revoir
À reprendre étape par étape, seulement si le besoin apparaît.
- **Filtre de Hampel** (médiane + MAD) pour l'étape 2 : c'est le score z robuste du §11.2, avec un remplacement par la médiane ; seuil à sourcer.
- **Filtre de Kalman** ou modèle d'état : lissage avec incertitude explicite, plus lourd ; utile si le §5.5 de la roadmap (incertitude par cible) devient disponible.
- **Météo externe en entrée** de la détection (précipitation horaire du lieu), si les signaux internes ne suffisent pas.
- **Images de la caméra** autour d'un événement, pour confirmer une occlusion (outil `get_image` de D-042).
- **Poids continu combiné** (qualité image × cohérence géométrique), comme la hiérarchie d'exclusion de la roadmap (§6).
- **Notification** d'un événement externe au client (« mesure perturbée par la pluie »), une fois la détection fiable.