# 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*) | | Éclairage | soleil rasant, nuit, reflet | FAQ (*Error Value*, *Peak Intensity*) | **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`). - `docs/displacement/` : ce cadrage, `domaine/point-de-depart.md` (exploration), `analyses/` (fiches), `domaine/questions-pour-l-expert.md`. - Pas de couleur du jour ni de notification au départ : on verra si un événement mérite une notification une fois la détection fiable. ## 5. Données nécessaires Il faut : 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 (D-045)** : PS des Coudres, `data/PS_DES_COUDRES/displacement/`, du 08/10 au 14/10. 1. oui : l'export « advanced », à la cadence native (15 min), en UTC ; un export horaire en plus ; 2. non : seulement le contexte de l'utilisateur (système sain, sans doute de la buée le matin) ; 3. inconnu ; 4. en partie : les références (`global_ref`) et le seuil de chaque capteur sont dans l'export ; les distances manquent. **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. ## 6. Démarrage par étapes Chaque étape décide si la suivante est nécessaire. 0. **Obtenir les données** (§5). Fait pour une station, sans événement annoté (D-045). 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. ## 7. Questions ouvertes 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`). ## 8. Options écartées pour l'instant - **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.