Frame optical series work: detect external events, correct the curves (D-044)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-14 10:41:47 +02:00
1 parent 997e842568
commit 60ed5c85ed
3 files changed
+162 -1

No files matched your search

+3 -1
View File
@@ -14,6 +14,7 @@ L'état courant seulement ; l'historique est dans `git log` et `docs/decisions.m
- **Energy, comparaison seulement** : les deux moyennes glissantes sur 7 jours. Point ouvert : l'accoutumance après ~30 jours de déficit (fiche `moving_average_7_days_drop`).
- **Maquettes du site (D-022, D-039)** : client « System Summary », une page par station de `data/`, un bloc par domaine mesuré dans la section Diagnostic (Energy, Storage, Cellular, Temperature) ; support « Home » (section Status, une notification par station et par domaine Orange ou Red, lien vers la vue client de la station, D-025).
- **Agents LLM côté serveur (D-027)** : rapport exploratoire seulement, rien n'est construit.
- **Séries optiques (D-044)** : détecter les événements externes (occlusion, pluie, turbulence) dans les déplacements et produire une courbe corrigée, la brute gardée ; cadrage seulement, en attente d'un export de déplacements avec des événements connus (`docs/displacement/cadrage.md`, §5 et §7).
- **Enquête à la demande (D-042)** : approche auxiliaire pour les données de mesure : un agent enquête sur un événement (outils typés, réfutation obligatoire, preuves tracées), support d'abord puis client ; document seulement, rien n'est construit.
- **Storage (D-030, D-034, D-035)** : jeu de travail WEISSHORN seul (NORDEND n'a pas les mesures de `/data`) ; `DAILY_STORAGE_STATE` et `DAYS_UNTIL_STORAGE_FULL` en prototype, sans cas de l'expert ; couleur du jour codée (`src/storage/day_color.py`, matrice état × horizon `docs/storage/matrice-etat-horizon.drawio`, la pire des deux) ; seuils arbitraires (20 % / 10 % libres, 60 / 14 jours) ; questions en suspens dans `docs/storage/domaine/questions-pour-l-expert.md` ; livré en prototype (D-039) : figure du site `src/storage/final.py`, bloc de la vue client, notification support, guide `docs/storage/guide/`.
- **Cellular (D-030 à D-032, D-037), en pause en attendant le spécialiste** : WEISSHORN (mise en service le 19/08, puis quelques incidents isolés) et NORDEND (109 jours, 11 coupures de la liaison) explorés ; `DAILY_LINK_STATE` et `DAILY_SIGNAL_STATE` en prototype, sans cas de l'expert ; deux corrections de `DAILY_LINK_STATE` retenues sur le principe mais non codées ; couleur du jour codée (`src/cellular/day_color.py`, matrice lien × signal `docs/cellular/matrice-lien-signal.drawio` : Red si des envois manquent et que le signal n'est pas mesuré 20 h sur 24) ; livré en prototype avant les réponses du spécialiste (D-039) : figure du site `src/cellular/final.py`, bloc de la vue client, notification support, guide `docs/cellular/guide/`. Reprise : `docs/cellular/domaine/questions-pour-l-expert.md`.
@@ -107,7 +108,7 @@ python3 -m venv .venv && .venv/bin/pip install plotly # recréer .venv
### Fichiers
- `README.md` (40 l) : point d'entrée pour un humain.
- `docs/decisions.md` (476 l, D-001 à D-043) : décisions **projet**, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). À consulter avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée.
- `docs/decisions.md` (487 l, D-001 à D-044) : décisions **projet**, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). À consulter avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée.
- `docs/domaine/` : savoir métier commun, une note courte (< 50 l) par question.
- `ce-que-mesure-la-station.md` : format CSV, métriques et unités, consommation mesurée mais pas l'apport.
- `pieges-des-donnees.md` : trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit.
@@ -121,6 +122,7 @@ python3 -m venv .venv && .venv/bin/pip install plotly # recréer .venv
- `docs/temperature/` : domaine Temperature (D-040), sans matrice ; guide dans `guide/` (D-041). `domaine/point-de-depart.md` : zones thermiques, carte supposée (Jetson Nano) et ses limites, constats sur trois stations, pistes, questions au spécialiste ; fiche dans `analyses/`.
- `docs/agents/rapport-exploratoire.md` (290 l) : cadre d'agents LLM (D-027) : choix retenus, architecture, démarrage par étapes (§6) ; annexe A : pistes à revoir étape par étape. Le code d'agent vivra à part (`agents/`, proposé, pas créé).
- `docs/agents/enquete-a-la-demande.md` (233 l) : enquête à la demande sur un événement de mesure (D-042), même cadre ; harnais (§3), déroulé (§4), sortie et règle d'asymétrie (§5), étapes (§6), questions ouvertes (§9).
- `docs/displacement/cadrage.md` (148 l) : séries optiques (D-044) : événements externes et correction des courbes ; règles de correction (§3), chaîne en trois étapes (§4), données nécessaires (§5), étapes (§6), questions ouvertes (§7).
- `docs/aimsight/` : documentation AIMsight d'origine, en anglais, non modifiée. À lire avant de concevoir, **par section** ; ne pas re-demander à l'utilisateur ce qui y figure.
- `AIMsight_reference_quality_event_explainer_roadmap.md` (1 180 l) : **référence qui fait autorité** : couche diagnostique commune, explainer d'événements, classifications (§4.3), API indépendante de l'estimateur (§10).
- `AIMsight_agentic_support_project_context.md` (2 090 l) : extension support : chaîne de dépendance (§4), domaines dont la santé système (§5.1, le cas d'usage actuel), règles épistémiques (§10), familles d'hypothèses (§12), format de sortie (§14-15), cas de régression (§16-17), cas d'usage (§23).
+11
View File
@@ -474,3 +474,14 @@ Règles du journal :
- **Pourquoi** : demande de l'utilisateur. Sur secteur, la batterie sert d'UPS et reste pleine : la matrice lit le jour de la perte `FULL_CHARGE` (vert) et ne passe au rouge que 29 à 40 h plus tard (MISSISSIPPI), alors qu'une batterie de 7 Ah tient ~15 h. La règle secteur donne le rouge 1 à 2 h après la perte.
- **Options écartées** : perte = une heure sous 14,0 V (WEISSHORN aurait été rouge 31 jours sur 52 sans coupure, ses moyennes horaires descendent à 13,9 V, celles de NORDEND à 13,65 V) ; une fenêtre qui inclut l'heure courante (la coupure ferait perdre le statut en ~12 h) ; un statut collant pendant la coupure (reporté, fiche « Pistes »).
- **Conséquence** : `day_color.run()` fusionne les faits des trois analyses (`power`, `hours_lost` en plus) ; `focus_jour.py` cite la règle secteur quand elle a décidé ; limites dans la fiche `docs/energy/analyses/daily_power_source.md`, dont 3 jours sans statut après chaque coupure.
## D-044 — 2026-10-14 — Séries optiques : détecter les événements externes et corriger les courbes (cadrage)
- **Statut** : active, cadrage (`docs/displacement/cadrage.md`, rien n'est construit).
- **Décision** :
- nouveau chantier, premier du cas d'usage « déplacements » : détecter dans les séries optiques les événements externes à l'ouvrage (occlusion passagère, eau ou neige, turbulence, éclairage), les expliquer, et produire une courbe corrigée ;
- couche déterministe, analytique et embarquable (D-003), domaine `displacement` (`src/displacement/`, `docs/displacement/`, D-026) ; chaîne en trois étapes : qualifier chaque observation (poids continu), détecter et classer les événements, corriger ;
- la série brute n'est jamais remplacée : la corrigée est une série dérivée, chaque point modifié porte sa raison ; on ne corrige que si la cause externe est au moins `strongly supported` ;
- démarrage par étapes : données, exploration, occlusion passagère, médiane glissante, précipitation, turbulence (HDF5), puis branchement sur l'enquête à la demande (D-042).
- **Pourquoi** : demande de l'utilisateur. Les événements externes laissent des pics, du bruit ou des trous que le client peut prendre pour un mouvement. La station filtre déjà par un seuil d'erreur muet (0,7) ; la valeur ajoutée est de dire pourquoi, de graduer et de signaler sans qu'on le demande.
- **Options écartées** : remplacer la série brute ; lisser sans détecter ; modèle appris ou LLM dans cette couche ; données synthétiques ; décision sur `inlier` binaire.
- **Conséquence** : prérequis bloquant : un export de déplacements à la cadence native avec des événements connus (`data/` n'a que des métriques système), idéalement le HDF5. Questions ouvertes : §7 du cadrage.
+148
View File
@@ -0,0 +1,148 @@
# 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 le CSV de déplacements, qui a plusieurs colonnes par cible dans un même fichier (les métriques système ont un fichier par métrique).
- `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
Aujourd'hui, `data/` ne contient **que des métriques système**, aucune série de déplacement. 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é.
## 6. Démarrage par étapes
Chaque étape décide si la suivante est nécessaire.
0. **Obtenir les données** (§5). Prérequis bloquant.
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) ?
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 ?
3. L'export HDF5 est-il disponible pour cette station ?
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 ?
## 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.