English: tools renamed and translated (same numbers as before), options and printed names in English; the guide translated

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-11-16 12:40:03 +01:00
1 parent 67c88625c5
commit f28bd19e04
25 files changed
+2764 -2762

No files matched your search

+44 -44
View File
@@ -1,64 +1,64 @@
# Lire les données
# Reading the data
Le guide du harnais de lecture : suivi par l'analyste ; amélioré par le tool-builder (dépôt agents), seul à écrire ici.
The guide to the reading harness: followed by the analyst; improved by the tool-builder (agents repository), the only one that writes here.
Une caméra suit des cibles (réflecteurs) fixées sur un ouvrage ; son propre mouvement est compensé grâce à des cibles de référence, supposées fixes. Ce mouvement, la **pose de la caméra** (`pan`, `tilt`, `rotation` en degrés, `scale`, `sigma0` du recalage, dans `camera/`), se lit avant les capteurs : il explique une grande part de ce qui bouge sur les courbes (D-073). Ce guide dit comment lire les données d'une station : ce que montrent les courbes et les images, moment par moment. Il ne dit pas ce qu'elles veulent dire : catégorie, event connu, hypothèse et verdict sont l'affaire de celui qui t'appelle.
A camera tracks targets (reflectors) fixed on a structure; its own movement is compensated thanks to reference targets, assumed fixed. This movement, the **camera pose** (`pan`, `tilt`, `rotation` in degrees, `scale`, `sigma0` of the registration, in `camera/`), is read before the sensors: it explains a large part of what moves on the curves (D-073). This guide says how to read a station's data: what the curves and the images show, moment by moment. It does not say what they mean: family, known event, hypothesis and verdict are the business of whoever calls you.
## À lire d'abord
## Read first
- `labeling/connaissances/colonnes-des-deplacements.md` : formats des exports et sens des colonnes (**en premier**) ;
- `labeling/connaissances/les-trous.md` ;
- sur une station dont l'export porte les métriques de qualité d'image (`peak` à `snr` : la ligne « Qualité d'image de l'export » d'`inventaire.py`), `labeling/connaissances/metriques-de-qualite.md`.
- `labeling/knowledge/displacement-columns.md`: formats of the exports and meaning of the columns (**first**);
- `labeling/knowledge/gaps.md`;
- on a station whose export carries the image quality metrics (`peak` to `snr`: the "Export image quality" line of `inventory.py`), `labeling/knowledge/quality-metrics.md`.
## Les outils
## The tools
Lance-les depuis la racine du dépôt appelant, où `tools/`, `data/` et `labeling/` sont des liens. Ils rendent des valeurs, jamais des verdicts : c'est toi qui juges.
Run them from the root of the calling repository, where `tools/`, `data/` and `labeling/` are links. They return values, never verdicts: you judge.
| Commande | Ce qu'elle rend |
| Command | What it returns |
|---|---|
| `python3 tools/scripts/inventaire.py <dossier> [--debut T] [--fin T] [--fichiers]` | Fichiers par type (au-delà de 5 par type : le nombre, le premier et le dernier ; `--fichiers` pour la liste complète, à n'utiliser que pour chercher un fichier précis), **ce que contient chaque source** sur la fenêtre (colonnes de l'export, de la pose et de `quality/`, avec le nombre de lignes qui ont une valeur, « vide » sinon ; noms des métriques système de `metrics/` ; images et images différentielles ; des noms et des comptes, jamais de valeurs), images : par suites d'écarts égaux entre deux images (à 5 min près, sur la fenêtre si elle est donnée ; une ligne par changement d'écart : un trou se date par ses deux images), poses de la caméra (nombre, période, instants de mesure sans recalage), période, cadence, mesures manquantes, capteurs (référence ou cible, seuil d'erreur, mesures rejetées) : ces comptes portent sur **toute la période**. Avec `--debut`/`--fin` (sur un lot : ceux du lot), une section de plus pour la fenêtre : les pas absents datés (pour tous les capteurs, ou lesquels manquent), par capteur, les mesures rejetées datées (suites de pas consécutifs), puis le **nombre de références retenues par la compensation** (`inlier` = 1) à chaque instant et les suites datées où des références ne le sont pas, lesquelles et pourquoi (`r` rejetée, `0` écartée par la compensation, `vide`). Une mesure est rejetée quand son `error_value` dépasse le seuil du capteur, **références comprises**. Quand `pattern_type` est vide, un capteur est une référence s'il porte `reproj_err` ou `inlier` (la ligne « pattern_type vide pour N capteurs » le dit) ; une colonne de l'export que tous les capteurs ne portent pas dit combien la portent. Quand `inlier` est vide sur la fenêtre, les références retenues sont lues sur `reproj_err` rempli (le titre le dit) ; une marque autre que `r` ou `vide` est la valeur d'`inlier` (ex. `-1`). « Relevés en double » : un export (souvent nommé d'après le projet du client) dont les relevés sont déjà dans les autres ; avec 0 valeur différente, il ne change rien à la lecture, sinon les outils gardent celui du dernier fichier dans l'ordre des noms. Une suite qui finit le même jour n'écrit que l'heure de sa fin. La ligne « Qualité d'image de l'export (peak à snr) » dit si les six métriques de qualité sont remplies (alors `qualite.py`) ou vides. Sur un mois, la sortie avec `--debut`/`--fin` dépasse ce qu'un appel affiche : lis chaque section par un tube vers `grep` (ex. `| grep -A40 '^Références retenues'`, `| grep '^ PR04 '`) |
| `python3 tools/scripts/resume.py <dossier> [--colonne C] [--stat median\|min\|max] [--pas 1h] [--niveau periode\|fenetre] [--capteurs A,B] [--debut T] [--fin T] [--instants T1,T2] [--marque]` | Niveau habituel de chaque capteur (médiane, MAD, min, max) sur toute la période, ou sur la fenêtre `--debut`/`--fin` avec `--niveau fenetre` (pour un lot : un changement de niveau dans le lot ne se compare pas à des semaines d'autres mesures), puis un tableau par pas de temps. Colonnes : `error_value`, `corr_x`, `corr_y`, `relative_x`, `relative_y`, `x`, `y`, `sigma0`, `reproj_err`, et les six métriques de qualité d'image `peak`, `flux`, `sharpness`, `fwhm`, `dominance`, `snr` (valeurs brutes ; face à une référence calme, `qualite.py`). L'en-tête des capteurs se répète toutes les 24 lignes. `--marque` : `*` après la valeur quand une mesure du pas est rejetée (`x`, `y`, `error_value` d'une mesure rejetée restent remplis), `o` quand une mesure du pas a inlier = 0. `--instants T1,T2` : seulement les pas qui contiennent ces instants (les valeurs de tous les capteurs à quelques heures choisies). Avec `--pas` égal à la cadence, `--niveau fenetre --marque`, c'est la table par instant et par capteur d'une colonne : une colonne par lancement |
| `.venv/bin/python tools/scripts/graphique.py <dossier> [--capteurs A,B] [--colonnes C1,C2] [--debut T] [--fin T] [--zone T1/T2 ...] [--sortie D]` | Un PNG des séries ; chaque `--zone` est grisée ; il imprime son chemin. Colonnes : celles de `resume.py`, métriques de qualité comprises (valeurs brutes). **Regarde-le avec Read** : tu lis mieux un graphique qu'un tableau |
| `.venv/bin/python tools/scripts/ensemble.py <dossier> [--colonnes x,y,sigma0] [--colonne error_value] [--pas 15min] [--k 5] [--min 5] [--residus corr_x,corr_y,error_value|non] [--hors T1/T2] [--autres] [--rigide BASE [--sans A,B] [--suivre A,B]] [--table T1/T2|non] [--capteurs A,B] [--debut T] [--fin T] [--sortie D]` | Tous les capteurs ensemble, chacun face à sa médiane et sa MAD sur la fenêtre. Deux PNG : **commun** (médiane entre capteurs de `x`, `y`, `sigma0` : avec la dispersion entre capteurs en bande grise ; sur les panneaux `x`, `y`, en plus, **chaque référence globale à part** (un trait chacune) et la **médiane des cibles seules** (trait noir) ; et, à chaque pas, le nombre de capteurs dont `--colonne` dépasse sa médiane de plus de `--k` MAD ; en tête, si le dossier a `camera/`, la **pose de la caméra**, valeurs brutes, un point par recalage, le trait coupé aux instants de mesure sans recalage) et **multiples** (un petit graphique par capteur, une échelle chacun : un palier d'un seul capteur s'y voit). Imprime aussi la **table de la médiane commune** (une ligne par pas de `--pas` : l'heure et l'écart à la médiane de la fenêtre de `x`, `y`, `sigma0`, puis `x_cibles`, `y_cibles` (médiane des cibles seules), puis la pose brute de la caméra, colonnes `cam_pan`, `cam_tilt`, `cam_rotation`, `cam_scale`, `cam_sigma0`, vides sans recalage) avec le minimum et le maximum de chaque colonne et leur instant, puis ceux de `x`, `y` de chaque référence globale (marqués `(rejetée)` quand la mesure l'est, avec le nombre de mesures rejetées de la référence), puis les instants de mesure sans pose (suites datées), puis les instants où au moins `--min` capteurs dépassent ensemble, avec leurs noms. Trois PNG de plus, **residus-corr_x**, **residus-corr_y**, **residus-error_value** (`--residus`) : un petit graphique par capteur de la colonne moins le niveau propre du capteur (sa médiane sur la fenêtre ; avec `--hors T1/T2`, celle du reste de la fenêtre, hors du moment lu), une échelle chacun, zéro en pointillé : un écart de quelques centièmes sur `corr`, caché dans les bandes parallèles de `graphique.py`, s'y voit ; imprime pour chaque capteur le niveau, le bruit propre (médiane des écarts entre deux mesures) et l'écart min/max par pas avec leur instant, en unités et en bruits ; `--residus non` : aucun de ces PNG ni de ces tables. Avec `--autres`, des PNG **residus-…-autres** de plus : chaque capteur moins sa propre médiane **et moins la médiane des autres capteurs au même instant** (ce que tous partagent, le reste de la compensation d'un mouvement commun, s'annule ; ce qui est propre reste), et, par capteur, la pente et la corrélation r de ce résidu sur la médiane commune de `x`, `y`, `sigma0` : un creux qui reste après `--autres` n'est pas un reste partagé par tous ; une pente élevée avec r proche de ±1 sur `y` commun dit qu'il est proportionnel au mouvement commun (gain propre au capteur), sans r ni pente il est indépendant du mouvement. Avec `--rigide BASE`, un PNG **rigide** de plus : à chaque mesure, le mouvement d'ensemble des cibles depuis l'instant `BASE` (translation, rotation, échelle, estimé par médianes : une cible qui saute seule ne le tire pas ; `--sans A,B` en retire des cibles), et, pour chaque capteur, le **résidu** `dx`, `dy` (position brute moins sa position à `BASE` transportée par ce mouvement, en px) ; panneaux : `dx`, `dy` de chaque référence globale face à la médiane et au 10e-90e centile des cibles, `|résidu|` des cibles (médiane, 90e centile), rotation et échelle ajustées, `reproj_err` des références ; imprime la table au pas (`rot_deg`, `echelle`, `tx`, `ty`, `cib_med`, `cib_max`, `dx`, `dy` de chaque référence, et de chaque capteur de `--suivre A,B` : la suite pas à pas d'une cible) et, par capteur, min, max et valeur au dernier instant de `dx`, `dy`. Les mesures rejetées n'entrent ni dans l'ajustement, ni dans la bande des cibles, `cib_med`, `cib_max`, ni dans les colonnes de la table : sur plusieurs jours, des voitures garées ou des rejets de nuit ne noient plus le reste ; sur le PNG, une référence rejetée est une croix (l'échelle est celle des mesures acceptées, une croix loin est hors cadre) ; le résumé par capteur les donne à part (`; N rejetées : min …, max …`, et `(rejetée)` après une dernière valeur rejetée). Contrairement à l'écart à la médiane, ce résidu ne dépend pas de la place du capteur dans l'image quand la scène tourne ou change d'échelle. Les tables par pas (médiane commune, `--rigide`) répètent leur en-tête toutes les 24 lignes ; `--table T1/T2` ne les imprime qu'entre T1 et T2 (`non` : pas du tout), niveaux, min, max, PNG et le reste restant sur toute la fenêtre : sur un lot d'un mois, lis d'abord avec `--table non`, puis relance avec `--table` sur le jour d'un moment (mêmes niveaux, ce que ne donnerait pas une fenêtre `--debut`/`--fin` plus courte). Les graduatLine truncated
| `python3 tools/scripts/plages.py <dossier> [--colonnes error_value,corr_x,corr_y] [--k 5] [--fusion 1h] [--min-mesures 1] [--hors T1/T2] [--glissant N|DUREE] [--instants N] [--capteurs A,B] [--debut T] [--fin T]` | Par colonne et par capteur, aux mesures (pas natif, jamais moyennées) : niveau (médiane de la fenêtre), bruit propre, **plus grand saut** d'une mesure à la suivante (valeur, en bruits, les deux instants) ; puis les **plages** où le capteur s'écarte de son niveau de plus de `--k` bruits : début, fin, nombre de mesures, extrême (signé, en unités et en bruits) et son instant ; deux plages du même sens à moins de `--fusion` n'en font qu'une, les mesures rejetées ne coupent pas une plage ; colonne `rejetées` : combien des mesures de la plage le sont (et `extrême rejetée`), `(rejetée : …)` après un plus grand saut dont un bout l'est. Sert à dater le début et la fin d'un moment d'un capteur sans relancer dix tableaux. Un bruit `0` (et « - » en bruits, aucune plage) : les valeurs sont constantes à l'arrondi près (écarts sous 1e-9), comme le `corr` des références quand la compensation n'en retient que deux (voir Conventions) ; même chose dans `ensemble.py --residus` et `jours.py`. Quand un épisode long fausse la médiane de la fenêtre (le capteur y passe la moitié du lot), `--hors T1/T2` calcule niveau et bruit hors de l'épisode ; une plage qui touche le bord de la fenêtre est datée au bord. `--min-mesures N` n'imprime que les plages d'au moins N mesures (et dit combien sur le total) : sur un lot de plusieurs jours, les plages d'un pas se comptent par centaines et noient les paliers longs ; lis d'abord avec `--min-mesures 6`, puis sans. `--glissant N` (N mesures de part et d'autre) ou `--glissant 1d` (les mesures à moins d'une durée) : le niveau de chaque mesure est la médiane de ses voisines, sans elle ; une dérive longue ou un palier suivent ce niveau local, seuls restent les écarts plus brefs que la fenêtre (la colonne niveau du tableau et le bruit ne changent pas ; avec `--hors`, seul le bruit se calcule hors de l'épisode). `--instants N` : à la fin, les instants où au moins N capteurs sont hors niveau sur l'une des colonnes, avec chaque capteur et son écart signé en bruits (`cx` corr_x, `cy` corr_y, `ev` error_value), les capteurs rejetés à cet instant (parmi `--capteurs` : en retirer les capteurs toujours rejetés allège la liste), et chaque référence : `error_value` (`r` si rejetée) / inlier |
| `.venv/bin/python tools/scripts/jours.py <dossier> [--colonnes corr_x,corr_y,error_value] [--nuit 20-3] [--k 5] [--jours 2] [--pas 15min] [--capteurs A,B] [--bornes [--lissage N] [--fraction F]] [--debut T] [--fin T] [--sortie D]` | Ce qui revient d'un jour à l'autre, sur les mesures acceptées seulement. 1. **Niveau de chaque nuit** (heures `--nuit` H1-H2 UTC, à cheval sur minuit, datée du jour où elle commence), par capteur et par colonne : médiane, MAD, nombre de mesures, et le bruit propre ; puis, d'une nuit à la suivante, la **marche** (différence des médianes, en unités et en bruits) et **où elle se place** (« entre A et B » : là où la suite des mesures de nuit des deux nuits se coupe le mieux entre les deux niveaux ; B au début de la nuit suivante : la coupure tombe de jour, entre les deux nuits). Une marche de quelques bruits, une dérive d'une nuit à l'autre, et deux colonnes qui marchent au même instant s'y lisent, même quand le capteur a plusieurs niveaux dans le lot. 2. **Jours superposés** : PNG **parheure-<colonne>**, un petit graphique par capteur, en abscisse l'heure du jour, une courbe par jour, chaque mesure moins le niveau de la dernière nuit commencée (nuit grisée, cadre du 1er au 99e centile, le titre dit combien de mesures sortent du cadre) ; table : par créneau de `--pas` de l'heure du jour, les capteurs dont l'écart dépasse `--k` bruits, du même côté, au moins `--jours` jours, avec le nombre de jours et la médiane de ces écarts. Ce qui revient chaque jour à la même heure, sur un capteur ou plusieurs, s'y groupe, même quand cela ne dure qu'une à trois mesures. 3. **Bornes de chaque jour**, avec `--bornes` : pour la médiane des cibles de chaque colonne et pour la pose de la caméra (`pan`, `tilt`, `rotation`, `scale`, `sigma0`, si `camera/` existe), l'écart au niveau de la nuit qui précède chaque jour (un jour va de la fin d'une nuit à la fin de la suivante ; avec `--capteurs`, la médiane de ces capteurs, avec un seul, le sien). Par jour : nombre de mesures, la première et la dernière ; premier et dernier instant au-delà de `--k` bruits, avec la mesure juste avant et juste après, au pas natif ; max et min signés avec leur instant ; la suite de mesures au-delà de `--k` bruits qui entoure le plus grand des deux ; la nuit suivante moins la nuit de référence. Un jour sans mesure le dit ; une nuit de référence qui n'est pas la précédente est nommée. Chaque ligne de jour commence par le nom court de sa suite (`corr_x`, `pose_tilt`…) : sur un mois, `| grep '^pose_tilt '` en lit une, `| grep ' 12/10 '` un jour. `--lissage N` : l'écart de chaque mesure est la médiane des N mesures du jour centrées sur elle (bruit et `--k` inchangés ; PNG : lissé en bleu, brut en gris) : un point isolé ne coupe plus la suite autour de l'extrême et ne fait plus un premier ou un dernier dépassement. `--fraction F` : le seuil de chaque jour est F fois le plus grand |écart| de ce jour (imprimé sur sa ligne, `seuil …`), au lieu de `--k` bruits : quand le bruit au pas natif est sans rapport avec l'ampleur du cycle (pose très bruitée, ou très lisse). PNG **bornes** : l'écart sur le lot, premier → dernier dépassement grisé clair, suite autour de l'extrême grisée foncé, max et min marqués. Le choix de `--nuit` : des heures où le cycle du jour (`error_value`, pose de la caméra) est retombé. **Regarde les PNG avec Read** |
| `.venv/bin/python tools/scripts/metriques.py <dossier> [--noms A,B] [--pas 1h] [--stat median\|min\|max] [--contre temperature] [--lissage 24h] [--metriques-seules] [--debut T] [--fin T] [--sortie D]` | Les métriques système de `metrics/` (une valeur par heure), jamais les identifiants (`SIM_CCID`, `ip*`). Imprime les métriques disponibles avec leur nombre de valeurs sur la fenêtre (« vide » : aucune), puis une table par pas de `--pas` : `temperature` (médiane des composants `sensor_*_deg_c`, celle que lisent les détecteurs), chaque métrique de `--noms` (défaut : les `*_deg_c` et `BusVoltage`), puis, sauf `--metriques-seules`, `cib_corr_x`, `cib_corr_y` (médiane sur les cibles de `corr` moins le niveau propre de chaque cible, mesures acceptées) et la pose brute de la caméra (`cam_pan` … `cam_sigma0`) ; une case vide est sautée, une métrique texte (`link`, `BatteryState`, `last_sync`) est rendue telle quelle. Puis, par colonne : pas remplis, min et max avec leur instant ; la corrélation r et la pente de chaque colonne sur `--contre` (avec `--lissage 24h`, sur sa moyenne glissante, colonne `<contre>_lisse`) ; les suites datées de pas sans aucune métrique. Un PNG : températures sur un panneau (médiane en noir), chaque autre métrique sur le sien, puis `cib_corr_x`, `cib_corr_y` et la pose, trait coupé sur un trou. **Regarde-le avec Read** |
| `.venv/bin/python tools/scripts/stations.py <dossier> <dossier> [...] [--colonnes temperature,cam_tilt,cam_rotation,cam_scale,cib_corr_x,cib_corr_y] [--pas 1h] [--stat median\|min\|max] [--table T1/T2\|non] [--debut T] [--fin T] [--sortie D]` | **Plusieurs stations sur une même ligne de temps** (stations voisines, même bâtiment). Colonnes possibles : `temperature` (comme `metriques.py`), `cam_pan` … `cam_sigma0` (pose brute), `cib_corr_x`, `cib_corr_y` (comme `metriques.py`), `rej_cibles`, `rej_refs` (nombre de cibles, de références rejetées, le plus grand du pas). Imprime par station la période, la cadence et le nombre d'instants ; puis les **trous** : les suites de pas sans mesure ou sans température, avec les stations où elles manquent (un trou commun à plusieurs stations sur une seule ligne) ; puis la table par pas (une colonne `STATION:colonne` chacune, tabulations ; `--table` comme `ensemble.py`) ; puis, par colonne et par paire de stations, r des valeurs et r des pas d'une valeur à la suivante (un mouvement commun se voit sur les pas, une tendance commune sur les valeurs), avec n. PNG **stations** : un panneau par colonne, un trait par station (température brute, le reste moins sa médiane), et une bande par station des pas sans mesure. Prends `--pas` égal à la cadence la plus lente des stations ; sur un mois à `1h`, lis d'abord avec `--table non`. **Regarde-le avec Read** |
| `python3 tools/scripts/qualite.py <dossier> [--calme T1/T2,T3/T4] [--commun] [--table M] [--pas 15min] [--seuil 0.5] [--capteurs A,B] [--debut T] [--fin T]` ; `... --etiquettes F [--numeros 3,7] [--marge 60] [--bords]` ; `... --etiquettes F --hors [--min 1] [--sauf "Thermal displacement"]` ; `.venv/bin/python tools/scripts/qualite.py <dossier> --figure [--metriques flux,snr,dominance] [--etiquettes F] [--zone T1/T2 ...] [--sortie D]` ; `python3 tools/scripts/qualite.py --essai` | Les six **métriques de qualité d'image** (`peak`, `flux`, `sharpness`, `fwhm`, `dominance`, `snr` ; définitions : `labeling/connaissances/metriques-de-qualite.md`), sur les stations qui les ont (sinon : « Aucune métrique de qualité », et rien d'autre). Chaque mesure devient un **rapport** à la **référence calme** de son capteur : la médiane de la métrique sur ses mesures des fenêtres `--calme`, à la même heure UTC du jour (sans `--calme` : tout le dossier) ; 1 = comme la référence, < 1 plus bas, > 1 plus haut ; pour `fwhm` et `dominance`, c'est la hausse qui dit une image dégradée ; mesures rejetées comprises. Sans option : le `peak` maximal du dossier, puis par capteur (`r` = référence) les mesures rejetées, `pk/max` (peak médian sur la fenêtre divisé par ce maximum : à 1, la tache touche le plafond de l'image, son `peak` ne bouge plus et sa `sharpness` suit l'exposition : lis plutôt `flux`, `snr`), et pour chaque métrique le rapport médian et l'extrême avec son instant ; puis la médiane des cibles et des références. `--commun` : par pas, la médiane des rapports des cibles / des références pour chaque métrique (ce qui touche toute la scène, visibilité ou turbulence ; `--pas 1d` pour voir en un écran sur quels jours la référence tient). `--table M` : par pas, le rapport de `M` de chaque capteur (`*` : une mesure rejetée), leur médiane et combien passent `--seuil` (sous, ou au-dessus de 1/`--seuil` pour `fwhm`, `dominance`) : une cible qui s'éteint et revient. `--etiquettes F` (un JSON par ligne, `debut`, `fin`, `categorie`) : par étiquette numérotée, le rapport médian des cibles et des références sur l'heure d'avant, la plage et l'heure d'après (`cib 0.96\|0.26\|0.79`, `--marge` minutes), puis les capteurs **touchés** sur la plage (flux ou snr sous `--seuil`, ou dominance au-dessus de 1/`--seuil`), avec leur pire flux, du plus bas au plus haut ; `--bords` : par instant de la plage élargie, le nombre de capteurs touchés et la médiane des cibles de flux, snr, dominance (`<` dans la plage), pour dater le premier et le dernier instant dégradé. `--hors` : les suites d'instants qu'aucune étiquette ne couvre (hors familles `--sauf`) où au moins `--min` capteurs sont touchés, avec les capteurs et leur pire flux : des candidats aux étiquettes oubliées, à vérifier sur `corr_x`, `corr_y`. `--figure` (au lieu des tables) : PNG **qualite-commun** (un panneau par métrique, échelle log : médiane des cibles en noir, des références en rouge, bande grise du 10e au 90e centile des cibles : une gêne de toute la scène déplace la médiane, une occultation de quelques cibles ne déplace que le bas de la bande) et un PNG **qualite-<métrique>** par `--metriques` (un petit graphique par capteur, références en rouge) ; `--etiquettes` y grise chaque étiquette d'une couleur par famille, `--zone` des plages. **Regarde les PNG avec Read** |
| `.venv/bin/python tools/scripts/vignettes.py <dossier> --capteurs A,B --heures T1,T2 [--rayon 100] [--contraste [MIN,MAX]] [--fixe] [--zone X,Y,L,H] [--sortie D]` | Une planche de vignettes à pleine résolution : une ligne par capteur, une colonne par heure, centrées sur la position brute (`x`, `y`) du capteur à chaque heure (le centre du cadre est écrit sous chaque vignette : quand `x`, `y` sautent, le cadre se déplace d'autant, et une tache qui entre dans le cadre semble apparaître) ; `--fixe` garde pour chaque capteur le cadre de la première heure et marque d'une croix rouge les `x`, `y` de chaque heure ; pixels non retouchés, l'éclat se compare d'une vignette à l'autre ; imprime pour chaque vignette le fond (médiane), le 99e centile et le pic (niveaux de gris 0 à 255) ; sans image à l'heure demandée, prend la plus proche et imprime l'écart (l'heure réelle est dans le titre). Une tache faible ou déformée est invisible telle quelle : `--contraste MIN,MAX` met toutes les vignettes en gris avec le même étirement (sans valeur : du 1er centile au maximum de la planche, écrasé par un pixel saturé ; choisis alors MIN,MAX d'après le fond et le pic imprimés, ex. `10,40`), `--rayon 30` à `50` grossit ; compare la forme et le pic avant, pendant et après un épisode, à la même heure de la journée. **Regarde-la avec Read** : une image entière lue par Read est réduite, un petit réflecteur y devient illisible. Un cadre que le bord de l'image coupe est signalé (« cadre coupé par le bord de l'image (L × H px) ») : sur certaines stations, `x`, `y` ne sont pas des pixels (valeurs proches de 0) et le cadre tombe dans le coin ; regarde alors la scène par `--zone`. `--zone X,Y,L,H` (pixels de l'image d'origine : coin haut gauche, largeur, hauteur, comme `gif.py`) : la même zone à chaque heure, côte à côte (jusqu'à 4 par ligne), même étirement avec `--contraste` ; `--capteurs` devient facultatif, et ceux qui sont donnés sont marqués d'une croix et de leur nom. Pour la scène autour des cibles (objet au premier plan, phares, éclairage), préfère-la à un grand `--rayon`. Chaque vignette est rendue un pixel pour un pixel jusqu'à 1000 px de côté, mais Read réduit un PNG large : avec un grand `--rayon` ou une grande `--zone`, trois ou quatre heures par planche |
| `.venv/bin/python tools/scripts/gif.py <dossier> --debut T --fin T [--largeur 720] [--duree 700] [--max 150] [--zone X,Y,L,H] [--sortie D]` | Un GIF des images de la caméra entre `--debut` et `--fin` inclus, recadrées au besoin sur `--zone`, mises à `--largeur` px, date et heure UTC écrites en bas à droite ; au-delà de `--max` images, `--max` à intervalle régulier ; imprime l'heure de chaque image, puis le chemin et la taille du GIF. Sert à joindre la scène à une réponse au client ; Read ne lit pas un GIF : pour regarder, `vignettes.py --zone` |
| `ls <dossier>/images/ \| grep <AAAAMMJJ>T<HHMM>Z`, puis Read sur le fichier trouvé (Read ne prend pas de motif) | L'image entière de la caméra à cette heure (UTC), pour la scène (occultation, éclairage, météo) |
| `python3 tools/scripts/inventory.py <folder> [--start T] [--end T] [--files]` | Files by type (beyond 5 per type: the count, the first and the last; `--files` for the full list, to be used only to look for a specific file), **what each source contains** over the window (columns of the export, of the pose and of `quality/`, with the number of rows that have a value, "empty" otherwise; names of the system metrics of `metrics/`; images and difference images; names and counts, never values), images: by runs of equal gaps between two images (within 5 min, over the window if given; one line per change of gap: a hole is dated by its two images), camera poses (count, period, measurement instants without registration), period, cadence, missing measurements, sensors (reference or target, error threshold, rejected measurements): these counts cover the **whole period**. With `--start`/`--end` (on a batch: those of the batch), one more section for the window: the missing steps, dated (for all the sensors, or which ones are missing), by sensor, the rejected measurements, dated (runs of consecutive steps), then the **number of references retained by the compensation** (`inlier` = 1) at each instant and the dated runs where some references are not, which ones and why (`r` rejected, `0` discarded by the compensation, `empty`). A measurement is rejected when its `error_value` exceeds the sensor's threshold, **references included**. When `pattern_type` is empty, a sensor is a reference if it carries `reproj_err` or `inlier` (the "pattern_type empty for N sensors" line says so); a column of the export that not all sensors carry says how many carry it. When `inlier` is empty over the window, the retained references are read from the filled `reproj_err` (the title says so); a mark other than `r` or `empty` is the value of `inlier` (e.g. `-1`). "Duplicate readings": an export (often named after the customer's project) whose readings are already in the others; with 0 different values, it changes nothing to the reading, otherwise the tools keep the one of the last file in name order. A run that ends the same day writes only the time of its end. The "Export image quality (peak to snr)" line says whether the six quality metrics are filled (then `quality.py`) or empty. Over a month, the output with `--start`/`--end` exceeds what a call displays: read each section through a pipe to `grep` (e.g. `\| grep -A40 '^Retained references'`, `\| grep '^ PR04 '`) |
| `python3 tools/scripts/summary.py <folder> [--column C] [--stat median\|min\|max] [--step 1h] [--level period\|window] [--sensors A,B] [--start T] [--end T] [--instants T1,T2] [--mark]` | Usual level of each sensor (median, MAD, min, max) over the whole period, or over the `--start`/`--end` window with `--level window` (for a batch: a level change within the batch is not compared with weeks of other measurements), then a table by time step. Columns: `error_value`, `corr_x`, `corr_y`, `relative_x`, `relative_y`, `x`, `y`, `sigma0`, `reproj_err`, and the six image quality metrics `peak`, `flux`, `sharpness`, `fwhm`, `dominance`, `snr` (raw values; against a calm reference, `quality.py`). The sensor header is repeated every 24 lines. `--mark`: `*` after the value when a measurement of the step is rejected (`x`, `y`, `error_value` of a rejected measurement stay filled), `o` when a measurement of the step has inlier = 0. `--instants T1,T2`: only the steps that contain these instants (the values of all the sensors at a few chosen times). With `--step` equal to the cadence, `--level window --mark`, it is the per-instant, per-sensor table of one column: one column per run |
| `.venv/bin/python tools/scripts/plot.py <folder> [--sensors A,B] [--columns C1,C2] [--start T] [--end T] [--zone T1/T2 ...] [--out D]` | A PNG of the series; each `--zone` is greyed; it prints its path. Columns: those of `summary.py`, quality metrics included (raw values). **Look at it with Read**: you read a chart better than a table |
| `.venv/bin/python tools/scripts/overview.py <folder> [--columns x,y,sigma0] [--column error_value] [--step 15min] [--k 5] [--min 5] [--residuals corr_x,corr_y,error_value\|no] [--outside T1/T2] [--others] [--rigid BASE [--without A,B] [--follow A,B]] [--table T1/T2\|no] [--sensors A,B] [--start T] [--end T] [--out D]` | All the sensors together, each against its median and its MAD over the window. Two PNGs: **common** (median across sensors of `x`, `y`, `sigma0`: with the dispersion across sensors as a grey band; on the `x`, `y` panels, in addition, **each global reference separately** (one line each) and the **median of the targets alone** (black line); and, at each step, the number of sensors whose `--column` exceeds its median by more than `--k` MAD; at the top, if the folder has `camera/`, the **camera pose**, raw values, one point per registration, the line cut at measurement instants without registration) and **multiples** (a small chart per sensor, one scale each: a step of a single sensor shows there). It also prints the **common median table** (one line per `--step`: the time and the deviation from the window median of `x`, `y`, `sigma0`, then `x_targets`, `y_targets` (median of the targets alone), then the raw camera pose, columns `cam_pan`, `cam_tilt`, `cam_rotation`, `cam_scale`, `cam_sigma0`, empty without registration) with the minimum and the maximum of each column and their instant, then those of `x`, `y` of each global reference (marked `(rejected)` when the measurement is, with the number of rejected measurements of the reference), then the measurement instants without pose (dated runs), then the instants where at least `--min` sensors exceed together, with their names. Three more PNGs, **residuals-corr_x**, **residuals-corr_y**, **residuals-error_value** (`--residuals`): a small chart per sensor of the column minus the sensor's own level (its median over the window; with `--outside T1/T2`, that of the rest of the window, outside the moment read), one scale each, zero dotted: a deviation of a few hundredths on `corr`, hidden in the parallel bands of `plot.py`, shows there; for each sensor it prints the level, the own noise (median of the differences between two measurements) and the min/max deviation per step with their instant, in units and in noises; `--residuals no`: none of these PNGs nor these tables. With `--others`, more **residuals-…-others** PNGs: each sensor minus its own median **and minus the median of the other sensors at the same instant** (what all share, the remainder of the compensation of a common movement, cancels; what is specific remains), and, per sensor, the slope and the correlation r of this residual on the common median of `x`, `y`, `sigma0`: a dip that remains after `--others` is not a remainder shared by all; a high slope with r close to ±1 on common `y` says it is proportional to the common movement (gain specific to the sensor), without r or slope it is independent of the movement. With `--rigid BASE`, one more **rigid** PNG: at each measurement, the overall movement of the targets since the instant `BASE` (translation, rotation, scale, estimated by medians: a target that jumps alone does not pull it; `--without A,B` removes targets from it), and, for each sensor, the **residual** `dx`, `dy` (raw position minus its position at `BASE` carried by this movement, in px); panels: `dx`, `dy` of each global reference against the median and the 10th-90th percentile of the targets, `|residual|` of the targets (median, 90th percentile), fitted rotation and scale, `reproj_err` of the references; it prints the table by step (`rot_deg`, `scale`, `tx`, `ty`, `tgt_med`, `tgt_max`, `dx`, `dy` of each reference, and of each sensor of `--follow A,B`: the step-by-step sequence of a target) and, per sensor, min, max and value at the last instant of `dx`, `dy`. Rejected measurements enter neither the fit, nor the band of the targets, `tgt_med`, `tgt_max`, nor the columns of the table: over several days, parked cars or night rejections no longer drown the rest; on the PNG, a rejected reference is a cross (the scale is that of the accepted measurements, a far cross is out of frame); the per-sensor summary gives them separately (`; N rejected: min …, max …`, and `(rejected)` after a last value that is rejected). Unlike the deviation from the median, this residual does not depend on the sensor's place in the image when the scene rotates or changes scale. The tables by step (common median, `--rigid`) repeat their header every 24 lines; `--table T1/T2` prints them only between T1 and T2 (`no`: not at all), levels, min, max, PNGs and the rest remaining over the whole window: over a one-month batch, first read with `--table no`, then rerun with `--table` on the day of a moment (same levels, which a shorter `--start`/`--end` window would not give). The ticks of the "common" PNG are every 1 to 12 h depending on the window, every n days beyond 20 days. The default step is 15 min, tLine truncated
| `python3 tools/scripts/ranges.py <folder> [--columns error_value,corr_x,corr_y] [--k 5] [--merge 1h] [--min-measurements 1] [--outside T1/T2] [--rolling N\|DURATION] [--instants N] [--sensors A,B] [--start T] [--end T]` | By column and by sensor, at the measurements (native step, never averaged): level (median of the window), own noise, **largest jump** from one measurement to the next (value, in noises, the two instants); then the **ranges** where the sensor deviates from its level by more than `--k` noises: start, end, number of measurements, extreme (signed, in units and in noises) and its instant; two ranges of the same sign less than `--merge` apart make only one, rejected measurements do not cut a range; column `rejected`: how many of the range's measurements are (and `rejected extreme`), `(rejected: …)` after a largest jump of which one end is. Used to date the start and the end of a sensor's moment without rerunning ten tables. A noise of `0` (and "-" in noises, no range): the values are constant to rounding (deviations below 1e-9), like the `corr` of the references when the compensation retains only two (see Conventions); the same in `overview.py --residuals` and `days.py`. When a long episode skews the window median (the sensor spends half the batch there), `--outside T1/T2` computes level and noise outside the episode; a range that touches the edge of the window is dated at the edge. `--min-measurements N` prints only the ranges of at least N measurements (and says how many out of the total): over a batch of several days, the one-step ranges number in the hundreds and drown the long steps; first read with `--min-measurements 6`, then without. `--rolling N` (N measurements on each side) or `--rolling 1d` (the measurements within a duration): the level of each measurement is the median of its neighbours, without it; a long drift or a step follows this local level, only the deviations shorter than the window remain (the level column of the table and the noise do not change; with `--outside`, only the noise is computed outside the episode). `--instants N`: at the end, the instants where at least N sensors are out of level on one of the columns, with each sensor and its signed deviation in noises (`cx` corr_x, `cy` corr_y, `ev` error_value), the sensors rejected at that instant (among `--sensors`: removing the always-rejected sensors lightens the list), and each reference: `error_value` (`r` if rejected) / inlier |
| `.venv/bin/python tools/scripts/days.py <folder> [--columns corr_x,corr_y,error_value] [--night 20-3] [--k 5] [--days 2] [--step 15min] [--sensors A,B] [--bounds [--smoothing N] [--fraction F]] [--start T] [--end T] [--out D]` | What comes back from one day to the next, on accepted measurements only. 1. **Level of each night** (hours `--night` H1-H2 UTC, straddling midnight, dated from the day it starts), by sensor and by column: median, MAD, number of measurements, and the own noise; then, from one night to the next, the **step** (difference of the medians, in units and in noises) and **where it falls** ("between A and B": where the sequence of night measurements of the two nights splits best between the two levels; B at the start of the following night: the cut falls by day, between the two nights). A step of a few noises, a drift from one night to the next, and two columns that step at the same instant read there, even when the sensor has several levels in the batch. 2. **Superimposed days**: PNG **byhour-<column>**, a small chart per sensor, hour of the day on the x axis, one curve per day, each measurement minus the level of the last night started (night greyed, frame from the 1st to the 99th percentile, the title says how many measurements fall outside the frame); table: per `--step` slot of the hour of the day, the sensors whose deviation exceeds `--k` noises, on the same side, at least `--days` days, with the number of days and the median of these deviations. What comes back every day at the same hour, on one sensor or several, groups there, even when it lasts only one to three measurements. 3. **Bounds of each day**, with `--bounds`: for the median of the targets of each column and for the camera pose (`pan`, `tilt`, `rotation`, `scale`, `sigma0`, if `camera/` exists), the deviation from the level of the night that precedes each day (a day goes from the end of one night to the end of the next; with `--sensors`, the median of these sensors, with a single one, its own). Per day: number of measurements, the first and the last; first and last instant beyond `--k` noises, with the measurement just before and just after, at the native step; signed max and min with their instant; the sequence of measurements beyond `--k` noises that surrounds the larger of the two; the following night minus the reference night. A day without measurement says so; a reference night that is not the previous one is named. Each day line starts with the short name of its series (`corr_x`, `pose_tilt`…): over a month, `\| grep '^pose_tilt '` reads one, `\| grep ' 12/10 '` one day. `--smoothing N`: the deviation of each measurement is the median of the N measurements of the day centred on it (noise and `--k` unchanged; PNG: smoothed in blue, raw in grey): an isolated point no longer cuts the sequence around the extreme and no longer makes a first or a last exceedance. `--fraction F`: the threshold of each day is F times the largest |deviation| of that day (printed on its line, `threshold …`), instead of `--k` noises: when the noise at the native step is unrelated to the amplitude of the cycle (very noisy or very smooth pose). PNG **bounds**: the deviation over the batch, first → last exceedance light grey, sequence around the extreme dark grey, max and min marked. The choice of `--night`: hours where the day cycle (`error_value`, camera pose) has subsided. **Look at the PNGs with Read** |
| `.venv/bin/python tools/scripts/metrics.py <folder> [--names A,B] [--step 1h] [--stat median\|min\|max] [--against temperature] [--smoothing 24h] [--metrics-only] [--start T] [--end T] [--out D]` | The system metrics of `metrics/` (one value per hour), never the identifiers (`SIM_CCID`, `ip*`). Prints the available metrics with their number of values over the window ("empty": none), then a table per `--step`: `temperature` (median of the `sensor_*_deg_c` components, the one the detectors read), each metric of `--names` (default: the `*_deg_c` and `BusVoltage`), then, unless `--metrics-only`, `tgt_corr_x`, `tgt_corr_y` (median over the targets of `corr` minus each target's own level, accepted measurements) and the raw camera pose (`cam_pan` … `cam_sigma0`); an empty cell is skipped, a text metric (`link`, `BatteryState`, `last_sync`) is returned as it is. Then, per column: filled steps, min and max with their instant; the correlation r and the slope of each column on `--against` (with `--smoothing 24h`, on its rolling mean, column `<against>_smooth`); the dated runs of steps without any metric. A PNG: temperatures on one panel (median in black), each other metric on its own, then `tgt_corr_x`, `tgt_corr_y` and the pose, line cut on a gap. **Look at it with Read** |
| `.venv/bin/python tools/scripts/stations.py <folder> <folder> [...] [--columns temperature,cam_tilt,cam_rotation,cam_scale,tgt_corr_x,tgt_corr_y] [--step 1h] [--stat median\|min\|max] [--table T1/T2\|no] [--start T] [--end T] [--out D]` | **Several stations on the same timeline** (neighbouring stations, same building). Possible columns: `temperature` (as in `metrics.py`), `cam_pan` … `cam_sigma0` (raw pose), `tgt_corr_x`, `tgt_corr_y` (as in `metrics.py`), `rej_targets`, `rej_refs` (number of rejected targets, of rejected references, the largest of the step). Prints per station the period, the cadence and the number of instants; then the **gaps**: the runs of steps without measurement or without temperature, with the stations where they are missing (a gap common to several stations on a single line); then the table by step (one `STATION:column` column each, tabs; `--table` as in `overview.py`); then, per column and per pair of stations, r of the values and r of the steps from one value to the next (a common movement shows on the steps, a common trend on the values), with n. PNG **stations**: a panel per column, a line per station (raw temperature, the rest minus its median), and a band per station of the steps without measurement. Take `--step` equal to the slowest cadence of the stations; over a month at `1h`, first read with `--table no`. **Look at it with Read** |
| `python3 tools/scripts/quality.py <folder> [--calm T1/T2,T3/T4] [--common] [--table M] [--step 15min] [--threshold 0.5] [--sensors A,B] [--start T] [--end T]` ; `... --labels F [--numbers 3,7] [--margin 60] [--edges]` ; `... --labels F --outside [--min 1] [--except "Thermal displacement"]` ; `.venv/bin/python tools/scripts/quality.py <folder> --figure [--metrics flux,snr,dominance] [--labels F] [--zone T1/T2 ...] [--out D]` ; `python3 tools/scripts/quality.py --self-test` | The six **image quality metrics** (`peak`, `flux`, `sharpness`, `fwhm`, `dominance`, `snr`; definitions: `labeling/knowledge/quality-metrics.md`), on the stations that have them (otherwise: "No quality metrics", and nothing else). Each measurement becomes a **ratio** to the **calm reference** of its sensor: the median of the metric over its measurements in the `--calm` windows, at the same UTC hour of the day (without `--calm`: the whole folder); 1 = like the reference, < 1 lower, > 1 higher; for `fwhm` and `dominance`, it is the rise that says a degraded image; rejected measurements included. Without options: the folder's maximal `peak`, then per sensor (`r` = reference) the rejected measurements, `pk/max` (median peak over the window divided by this maximum: at 1, the spot touches the image ceiling, its `peak` no longer moves and its `sharpness` follows the exposure: read `flux`, `snr` instead), and for each metric the median ratio and the extreme with its instant; then the median of the targets and of the references. `--common`: per step, the median of the ratios of the targets / of the references for each metric (what affects the whole scene, visibility or turbulence; `--step 1d` to see on one screen on which days the reference holds). `--table M`: per step, the ratio of `M` of each sensor (`*`: a rejected measurement), their median and how many pass `--threshold` (below, or above 1/`--threshold` for `fwhm`, `dominance`): a target that goes out and comes back. `--labels F` (one JSON per line, `start`, `end`, `family`): per numbered label, the median ratio of the targets and of the references over the hour before, the range and the hour after (`tgt 0.96\|0.26\|0.79`, `--margin` minutes), then the sensors **affected** over the range (flux or snr below `--threshold`, or dominance above 1/`--threshold`), with their worst flux, from lowest to highest; `--edges`: per instant of the widened range, the number of affected sensors and the median of the targets of flux, snr, dominance (`<` within the range), to date the first and the last degraded instant. `--outside`: the runs of instants that no label covers (outside `--except` families) where at least `--min` sensors are affected, with the sensors and their worst flux: candidates for forgotten labels, to check on `corr_x`, `corr_y`. `--figure` (instead of the tables): PNG **quality-common** (a panel per metric, log scale: median of the targets in black, of the references in red, grey band from the 10th to the 90th percentile of the targets: a disturbance of the whole scene moves the median, an occultation of a few targets moves only the bottom of the band) and a PNG **quality-<metric>** per `--metrics` (a small chart per sensor, references in red); `--labels` greys each label there in one colour per family, `--zone` ranges. **Look at the PNGs with Read** |
| `.venv/bin/python tools/scripts/thumbnails.py <folder> --sensors A,B --times T1,T2 [--radius 100] [--contrast [MIN,MAX]] [--fixed] [--zone X,Y,W,H] [--out D]` | A sheet of full-resolution thumbnails: one row per sensor, one column per time, centred on the sensor's raw position (`x`, `y`) at each time (the centre of the frame is written under each thumbnail: when `x`, `y` jump, the frame moves by as much, and a spot that enters the frame seems to appear); `--fixed` keeps for each sensor the frame of the first time and marks with a red cross the `x`, `y` of each time; unretouched pixels, the brightness can be compared from one thumbnail to the next; prints for each thumbnail the background (median), the 99th percentile and the peak (grey levels 0 to 255); without an image at the requested time, takes the nearest and prints the gap (the actual time is in the title). A faint or deformed spot is invisible as it is: `--contrast MIN,MAX` puts all the thumbnails in grey with the same stretch (without value: from the 1st percentile to the sheet's maximum, crushed by a saturated pixel; then choose MIN,MAX from the printed background and peak, e.g. `10,40`), `--radius 30` to `50` magnifies; compare the shape and the peak before, during and after an episode, at the same hour of the day. **Look at it with Read**: a whole image read by Read is reduced, a small reflector becomes illegible in it. A frame that the image edge cuts is flagged ("frame cut by the image edge (W × H px)"): on some stations, `x`, `y` are not pixels (values close to 0) and the frame falls in the corner; then look at the scene through `--zone`. `--zone X,Y,W,H` (pixels of the original image: top left corner, width, height, as in `gif.py`): the same zone at each time, side by side (up to 4 per row), same stretch with `--contrast`; `--sensors` becomes optional, and those that are given are marked with a cross and their name. For the scene around the targets (foreground object, headlights, lighting), prefer it to a large `--radius`. Each thumbnail is rendered pixel for pixel up to 1000 px a side, but Read reduces a wide PNG: with a large `--radius` or a large `--zone`, three or four times per sheet |
| `.venv/bin/python tools/scripts/gif.py <folder> --start T --end T [--width 720] [--duration 700] [--max 150] [--zone X,Y,W,H] [--out D]` | A GIF of the camera images between `--start` and `--end` inclusive, cropped to `--zone` if needed, set to `--width` px, UTC date and time written at the bottom right; beyond `--max` images, `--max` at regular intervals; prints the time of each image, then the path and the size of the GIF. Used to attach the scene to a reply to the customer; Read does not read a GIF: to look, `thumbnails.py --zone` |
| `ls <folder>/images/ \| grep <YYYYMMDD>T<HHMM>Z`, then Read on the file found (Read takes no pattern) | The whole camera image at that time (UTC), for the scene (occultation, lighting, weather) |
`--sortie <dossier>` : là où celui qui t'appelle range tes figures ; il te le donne.
`--out <folder>`: where whoever calls you stores your figures; they give it to you.
## Conventions
- Instants : `2026-01-01T00:00Z` ; une heure sans fuseau est lue en UTC ; `--fin` inclut la minute indiquée. Sur un lot, `--debut` et `--fin` du lot.
- Bash ne sert qu'à lancer ces outils, `ls`, `grep` et `date`, une commande par appel, sans boucle `for` (un tube vers `grep` est permis) : les permissions sont accordées commande par commande. Si le répertoire courant n'est pas la racine du dépôt, `cd <racine> && <commande>` compte pour une commande. N'écris aucun autre script. Celui qui t'appelle peut ajouter des commandes à cette liste.
- **Une sortie trop longue pour un appel** (au-delà de quelques centaines de lignes, coupée à l'affichage) : raccourcis-la d'abord par les options de l'outil (`--table non` puis `--table T1/T2`, `--min-mesures`, `--capteurs`, `--colonnes`, une fenêtre plus courte), ou lis-en une section par un tube vers `grep` (`| grep -A40 '^Titre'`, `| grep '^pose_tilt '`). Si tu dois la relire plusieurs fois, range-la dans le dossier de sortie dans le même appel (`<commande> > <sortie>/<nom>.txt`) et lis ce fichier par Read (`offset`, `limit`) ou par `grep` : pas de `head`, `tail`, `sed`, `cut`. Les outils créent eux-mêmes leur dossier de sortie : pas de `mkdir`.
- Un nom de capteur qui porte une apostrophe (`COLH20'''`, `REFP''21`) se met entre guillemets doubles dans le shell : `--capteurs "COLH20'''",COLI22`.
- Chaque PNG se regarde avec Read : un PNG que tu n'as pas regardé n'a rien montré.
- **Métriques de qualité d'image** (`qualite.py`) : elles disent **pourquoi** une mesure se dégrade, là où `error_value` dit seulement qu'elle se dégrade ; elles prouvent une cause et nomment les cibles touchées. Ce qu'elles ont montré sur LENZSPITZE (à confirmer sur chaque station) : `flux` coupé (près de 0) sur un groupe de cibles, les autres intactes, le temps d'une à quelques mesures : ces cibles sont cachées (la liste se lit sur le flux à chaque fois, pas sur la liste habituelle ; une cible cachée peut rester sous son seuil d'erreur, et son point est faux) ; `flux` en baisse sur toute la scène, plus fort sur les cibles lointaines : visibilité réduite ; `sharpness` en baisse et `dominance` en hausse, `flux` entier : l'image tremble (turbulence) ; rien ne bouge : ni l'image ni la vue, à chercher dans le mouvement. Un flux entier dément une occultation. `fwhm`, tronquée au disque, bouge peu ; sur une tache au plafond (`pk/max` à 1), elle baisse quand la tache s'assombrit. **La référence calme décide de tout** : prends `--calme` sur des heures calmes du **même régime de l'image** que la plage lue. Quand l'éclairage ou l'exposition change (après un trou, une intervention), une référence de l'autre côté fausse les rapports d'un facteur deux ou trois : `--commun --pas 1d` sur le lot montre ce changement (médianes des cibles et des références loin de 1 des jours entiers, puis à 1) ; prends alors une référence de chaque côté et lis chaque côté avec la sienne. Les jours calmes sont souvent des jours de cycle thermique : une lecture du thermique contre eux est circulaire.
- Une mesure rejetée (`error_value` au-dessus du seuil) n'est pas une mesure : la station vide les `corr` d'une cible rejetée, mais laisse ceux d'une **référence** rejetée, souvent absurdes ; les outils les vident (`corr`, plages, résidus, sauts ne portent que sur les mesures acceptées). Quand la compensation ne retient que **deux références**, leur `corr` vaut 0 (à 1e-13 près) : elle passe exactement par elles ; leur bruit s'imprime `0` et leurs écarts en bruits « - » ; ne lis rien dans ces valeurs, lis les références par `x`, `y` (`ensemble.py --rigide`) et `error_value`. Ses `x`, `y` restent : avant de citer un saut de `x`, `y`, regarde s'il est marqué `(rejetée)` ; une mesure rejetée ne se cite pas comme un mouvement.
- Instants: `2026-01-01T00:00Z`; a time without time zone is read as UTC; `--end` includes the minute given. On a batch, `--start` and `--end` of the batch.
- Bash is used only to run these tools, `ls`, `grep` and `date`, one command per call, without a `for` loop (a pipe to `grep` is allowed): permissions are granted command by command. If the current directory is not the root of the calling repository, `cd <root> && <command>` counts as one command. Write no other script. Whoever calls you may add commands to this list.
- **An output too long for one call** (beyond a few hundred lines, cut at display): shorten it first with the tool's options (`--table no` then `--table T1/T2`, `--min-measurements`, `--sensors`, `--columns`, a shorter window), or read a section of it through a pipe to `grep` (`| grep -A40 '^Title'`, `| grep '^pose_tilt '`). If you have to reread it several times, store it in the output folder in the same call (`<command> > <out>/<name>.txt`) and read that file with Read (`offset`, `limit`) or with `grep`: no `head`, `tail`, `sed`, `cut`. The tools create their output folder themselves: no `mkdir`.
- A sensor name that carries an apostrophe (`COLH20'''`, `REFP''21`) goes in double quotes in the shell: `--sensors "COLH20'''",COLI22`.
- Each PNG is looked at with Read: a PNG you have not looked at has shown nothing.
- **Image quality metrics** (`quality.py`): they say **why** a measurement degrades, where `error_value` says only that it degrades; they prove a cause and name the affected targets. What they showed on LENZSPITZE (to be confirmed on each station): `flux` cut (close to 0) on a group of targets, the others intact, for one to a few measurements: these targets are hidden (the list is read on the flux each time, not on the usual list; a hidden target can stay under its error threshold, and its point is wrong); `flux` down over the whole scene, stronger on the distant targets: reduced visibility; `sharpness` down and `dominance` up, `flux` whole: the image shakes (turbulence); nothing moves: neither the image nor the view, to be looked for in the movement. A whole flux refutes an occultation. `fwhm`, truncated to the disc, moves little; on a spot at the ceiling (`pk/max` at 1), it goes down when the spot darkens. **The calm reference decides everything**: take `--calm` on calm hours of the **same image regime** as the range read. When the lighting or the exposure changes (after a gap, an intervention), a reference on the other side skews the ratios by a factor of two or three: `--common --step 1d` over the batch shows this change (medians of the targets and of the references far from 1 for whole days, then at 1); then take a reference on each side and read each side with its own. Calm days are often days of thermal cycle: a reading of the thermal against them is circular.
- A rejected measurement (`error_value` above the threshold) is not a measurement: the station empties the `corr` of a rejected target, but leaves those of a rejected **reference**, often absurd; the tools empty them (`corr`, ranges, residuals, jumps cover only accepted measurements). When the compensation retains only **two references**, their `corr` is 0 (to 1e-13): it passes exactly through them; their noise prints as `0` and their deviations in noises as "-"; read nothing into these values, read the references through `x`, `y` (`overview.py --rigid`) and `error_value`. Its `x`, `y` remain: before citing a jump of `x`, `y`, check whether it is marked `(rejected)`; a rejected measurement is not cited as a movement.
## La méthode
## The method
1. **Inventaire** : ce qui est disponible, ce qui manque (fichiers, ce que contient chaque source, images, poses de la caméra, période, cadence, capteurs). Une colonne remplie que les outils ne montrent pas ou une source qu'aucun outil ne lit (`images_diff/`) reste une donnée : sache qu'elle existe. Les six colonnes de qualité d'image (`peak` à `snr`), remplies sur les caméras récentes, se lisent par `qualite.py`. `metrics/` se lit par `metriques.py` : une coupure des mesures se lit face aux pas sans métrique et à la tension (`--noms BusVoltage,BusCurrent,Power,BatteryPercent --metriques-seules` sur la coupure) ; des métriques toutes vides (« vide » sur chaque nom) sont une donnée absente, pas une température stable. Sur un lot, relance-le avec `--debut`/`--fin` du lot : les pas absents et les rejets du lot, datés ; ceux de la période entière ne disent rien du lot. Lis les rejets des **références** autant que ceux des cibles : un capteur rejeté aux mêmes heures chaque jour fait un moment à lui seul (dis sa part de mesures rejetées et ses heures, jour par jour) ; quand c'est une référence, dis avec combien de références la compensation tourne alors (la liste des références retenues). Quand plusieurs cibles sautent ensemble d'un pas, ou que la compensation tombe (pas de pose), regarde d'abord dans cette liste quelles références ont été perdues à cet instant.
2. **Large d'abord** : `ensemble.py` sur le lot, d'abord (sur un lot de plus de quelques jours, avec `--table non`, puis `--table T1/T2` sur les jours à lire) ; **la pose de la caméra en premier** (panneaux du haut, colonnes `cam_` de la table) : quand la caméra tourne (`pan`, `tilt`, `rotation`), change d'échelle (`scale`), quand son recalage se dégrade (`sigma0`) et quand elle n'est pas recalée (trait coupé, instants sans pose), datés au pas natif ; chaque moment des capteurs se lit ensuite face à elle : pendant un mouvement ou un trou de recalage, ou caméra immobile. La pose est calculée à partir des références globales : un changement de pose (ou une montée de `sigma0`) ne se lit comme un mouvement de la caméra que si **les cibles bougent aussi dans l'image** ; regarde, sur les panneaux `x`, `y`, les traits des références face au trait noir des cibles seules (et la colonne `x_cibles`, `y_cibles` de la table). Si seules des références bougent dans l'image et que les cibles restent immobiles, ce sont ces références qui ont bougé : la pose et les `corr` de toutes les cibles en sont faussés, sans mouvement brut des cibles ; dis quelles références et de combien. Si tout bouge ensemble, références et cibles, c'est la caméra ou la scène ; regarde alors si les `corr` reviennent. Dès que la pose tourne ou change d'échelle, l'écart à la médiane ne dit plus qui bouge seul (chaque capteur s'en écarte selon sa place dans l'image) : avant d'écrire « tout bouge ensemble », relance avec `--rigide BASE`, `BASE` un instant calme avant le premier mouvement, et lis le PNG **rigide** et sa table : une référence dont le résidu reste loin du 10e-90e centile des cibles, ou un `reproj_err` des références qui ne revient pas, veut dire que la compensation reste faussée par ces références et que les paliers de `corr` en viennent en partie ; dis lesquelles, de combien, jusqu'à quand ; un `|résidu|` des cibles qui monte dit qu'elles ne bougent pas comme un bloc. Puis la médiane de `x`, `y` (position brute, références comprises), les références une à une, les cibles seules et `sigma0` disent ce qui bouge dans l'image, avant de lire `corr` ; lis la table imprimée (heure, valeur) pour dater le début, la fin et le retour du mouvement et pour voir un niveau qui ne revient pas, et ne les devine pas sur l'axe du PNG : un creux de `corr` qui suit un mouvement de la médiane brute est le reste de la compensation, pas un mouvement propre des capteurs touchés ; les petits multiples d'`error_value` montrent un palier durable d'un capteur, le compte les instants où beaucoup de capteurs montent ensemble. Sur tout lot, sans attendre un soupçon, regarde les PNG **residus** (`corr_x`, `corr_y`, `error_value`) : chaque capteur face à son propre niveau, c'est là que se voient un capteur seul qui monte ou descend, un `corr` qui dérive de quelques centièmes, un palier propre à un capteur sous un mouvement commun ; la table dit de combien (en bruits) et quand. Pour séparer, sur une cible dont `corr` baisse sous un mouvement commun fort, un reste de compensation d'un mouvement propre, relance avec `--autres` (le reste partagé disparaît, la pente sur `x`, `y` commun dit s'il est proportionnel). Sur un lot de plus de deux jours, lance ensuite `jours.py` (avant de lire les pas isolés de `plages.py`) : ce qui revient chaque jour à la même heure se lit d'abord sur ses PNG **parheure** et sa table par créneau, et fait un moment par heure du jour (dis quels capteurs, combien de jours sur combien, l'ampleur, ce que fait la pose de la caméra à cette heure-là), pas un moment par jour ni rien du tout parce que chaque pas est court ; puis lis sa table des **niveaux de nuit**, pour tout capteur qui a déjà fait un palier ou dont `--hors` ne suffit pas (plusieurs niveaux dans le lot) : chaque marche d'une nuit à l'autre se date par son « entre A et B », et une marche d'`error_value` et une de `corr` au même instant se relient ; une dérive lente se lit d'une nuit à l'autre. Pour ce qui revient chaque jour et s'étiquette jour par jour (cycle thermique, réchauffement et refroidissement), relance `jours.py --bornes` plutôt que de fixer les mêmes heures pour tous les jours : chaque jour se date sur sa ligne, la suite autour de l'extrême pour le cycle, le max et le min pour un aller et un retour (le matin et l'après-midi) ; les mesures « avant » et « après » donnent les bornes au pas natif (à une cadence de 1 h ou de 4 h, un événement va de la mesure d'avant à celle d'après). Prends `--nuit` sur des heures où la pose et `error_value` sont retombées (figure **parheure**) : si le premier dépassement tombe au début du jour (« avant - ») et le dernier à sa fin chaque jour, la nuit choisie n'est pas calme ; change `--nuit` ou passe à `--capteurs` pour les cibles qui portent le cycle. Quand la caméra dérive toute la nuit, prends une nuit courte juste avant le matin (`--nuitLine truncated
3. **Puis zoome** : `resume.py` à 15min (`--stat max` pour le pic réel d'un capteur), et `graphique.py` sur les fenêtres et les capteurs qui bougent.
4. **Chaque capteur face à son propre niveau habituel** (sa médiane et sa MAD), jamais à un seuil absolu ; sur un lot, le niveau se calcule sur le lot (`--niveau fenetre`, `ensemble.py`), pas sur la période entière.
5. **Chaque moment retenu se date et se mesure au pas natif de 15 min** : début, fin et maximum lus sur la table à 15 min (`ensemble.py` par défaut, `resume.py --pas 15min`), jamais sur un tableau à l'heure ; lis aussi `ensemble.py --min 1` pour les capteurs seuls, et `plages.py` sur le lot (d'abord avec `--min-mesures 6`) pour avoir, par capteur, début, fin, extrême et plus grand saut au pas natif (relance-le avec `--hors` autour d'un épisode long pour dater son retour au niveau, ne conclus pas « ne revient pas » sans l'avoir lu ; quand le lot a une dérive longue ou plusieurs paliers (les plages se comptent par centaines, ou une moitié du lot est « hors niveau »), relance-le avec `--glissant` (quelques mesures, ou une durée de quelques heures à un jour selon la cadence) et `--instants 2` : les écarts brefs sous la dérive sortent seuls, et la liste par instant dit quels capteurs s'écartent ensemble, lesquels sont rejetés et ce que font les références à cet instant ; un écart de toutes les cibles avec les références au même instant se lit face à la pose de la caméra), et les tables de `x`, `y` sur les fenêtres où ils s'agitent. Sur une station qui a les métriques de qualité, pour chaque moment : `qualite.py --table flux --capteurs …` (ou `--etiquettes F --numeros N --bords` sur une étiquette) dit quelles cibles sont cachées (flux coupé) ou voilées, de quel instant à quel instant ; écris-les par leur nom.
6. **Les images** : vignettes (avec `--contraste` pour une cible faible) espacées, une toutes les 2 à 3 h, plus serrées là où les courbes bougent, toujours avec un capteur témoin non touché, à une heure avant, pendant et après (à la même heure de la journée si possible) ; quand `x`, `y` d'un capteur sautent entre deux vignettes (centre du cadre écrit sous chacune), relance avec `--fixe` avant de dire qu'une tache apparaît ou disparaît ; l'image entière pour la scène (occultation, éclairage, météo).
1. **Inventory**: what is available, what is missing (files, what each source contains, images, camera poses, period, cadence, sensors). A filled column that the tools do not show or a source that no tool reads (`images_diff/`) remains data: know that it exists. The six image quality columns (`peak` to `snr`), filled on recent cameras, are read through `quality.py`. `metrics/` is read through `metrics.py`: a cut of the measurements is read against the steps without metric and the voltage (`--names BusVoltage,BusCurrent,Power,BatteryPercent --metrics-only` on the cut); metrics that are all empty ("empty" on each name) are an absent datum, not a stable temperature. On a batch, rerun it with the batch's `--start`/`--end`: the absent steps and the rejections of the batch, dated; those of the whole period say nothing about the batch. Read the rejections of the **references** as much as those of the targets: a sensor rejected at the same hours every day makes a moment on its own (say its share of rejected measurements and its hours, day by day); when it is a reference, say with how many references the compensation then runs (the list of retained references). When several targets jump together by one step, or the compensation drops (no pose), look first in that list at which references were lost at that instant.
2. **Wide first**: `overview.py` on the batch, first (on a batch of more than a few days, with `--table no`, then `--table T1/T2` on the days to read); **the camera pose first** (top panels, `cam_` columns of the table): when the camera rotates (`pan`, `tilt`, `rotation`), changes scale (`scale`), when its registration degrades (`sigma0`) and when it is not registered (line cut, instants without pose), dated at the native step; each moment of the sensors is then read against it: during a movement or a registration gap, or camera still. The pose is computed from the global references: a change of pose (or a rise of `sigma0`) reads as a camera movement only if **the targets also move in the image**; look, on the `x`, `y` panels, at the lines of the references against the black line of the targets alone (and the `x_targets`, `y_targets` column of the table). If only references move in the image and the targets stay still, it is these references that moved: the pose and the `corr` of all the targets are skewed by it, without raw movement of the targets; say which references and by how much. If everything moves together, references and targets, it is the camera or the scene; then look whether the `corr` come back. As soon as the pose rotates or changes scale, the deviation from the median no longer says who moves alone (each sensor deviates from it according to its place in the image): before writing "everything moves together", rerun with `--rigid BASE`, `BASE` a calm instant before the first movement, and read the **rigid** PNG and its table: a reference whose residual stays far from the 10th-90th percentile of the targets, or a `reproj_err` of the references that does not come back, means that the compensation remains skewed by these references and that the steps of `corr` partly come from it; say which ones, by how much, until when; a `|residual|` of the targets that rises says they do not move as a block. Then the median of `x`, `y` (raw position, references included), the references one by one, the targets alone and `sigma0` say what moves in the image, before reading `corr`; read the printed table (time, value) to date the start, the end and the return of the movement and to see a level that does not come back, and do not guess them on the PNG axis: a dip of `corr` that follows a movement of the raw median is the remainder of the compensation, not a movement of the affected sensors themselves; the small multiples of `error_value` show a lasting step of a sensor, the count shows the instants where many sensors rise together. On every batch, without waiting for a suspicion, look at the **residuals** PNGs (`corr_x`, `corr_y`, `error_value`): each sensor against its own level, that is where a single sensor that rises or falls, a `corr` that drifts by a few hundredths, a step specific to one sensor under a common movement are seen; the table says by how much (in noises) and when. To separate, on a target whose `corr` goes down under a strong common movement, a remainder of the compensation from a movement of its own, rerun with `--others` (the shared remainder disappears, the slope on common `x`, `y` says whether it is proportional). On a batch of more than two days, then run `days.py` (before reading the isolated steps of `ranges.py`): what comes back every day at the same hour is read first on its **byhour** PNGs and its table by slot, and makes one moment per hour of the day (say which sensors, how many days out of how many, the amplitude, what the camera pose does at that hour), not one moment per day nor nothing at all because each step is short; then read its **night levels** table, for any sensor that has already made a step or for which `--outside` is not enough (several levels in the batch): each step from one night to the next is dated by its "between A and B", and a step of `error_value` and one of `corr` at the same instant are linked; a slow drift reads from one night to the next. For what comes back every day and is labelled day by day (thermal cycle, warming and cooling), rerun `days.py --bounds` rather than fixing the same hours for all the days: each day is dated on its line, the sequence around the extreme for the cycle, the max and the min for a go and a return (morning and afternoon); the "before" and "after" measurements give the bounds at the native step (at a cadence of 1 h or 4 h, an event goes from the measurement before to the one after). Take `--night` on hours where the pose and `error_value` have subsided (**byhour** figure): if the first exceedance falls at the start of the day ("before -") and the last at its end every day, the chosen night is not calm; change `--night` or switch to `--sensors` for the targets that carry the cycle. When the camera drifts all night, take a short night just before the morning (`--night 3-5`: the level is that of the rest that precedes the start); on a noisy series or one spiked with isolated points, add `--smoothing 5`; when the threshold in noiseLine truncated
3. **Then zoom**: `summary.py` at 15min (`--stat max` for the real peak of a sensor), and `plot.py` on the windows and the sensors that move.
4. **Each sensor against its own usual level** (its median and its MAD), never against an absolute threshold; on a batch, the level is computed on the batch (`--level window`, `overview.py`), not on the whole period.
5. **Each retained moment is dated and measured at the native 15 min step**: start, end and maximum read on the 15 min table (`overview.py` by default, `summary.py --step 15min`), never on an hourly table; also read `overview.py --min 1` for single sensors, and `ranges.py` on the batch (first with `--min-measurements 6`) to get, per sensor, start, end, extreme and largest jump at the native step (rerun it with `--outside` around a long episode to date its return to the level, do not conclude "does not come back" without having read it; when the batch has a long drift or several steps (the ranges number in the hundreds, or one half of the batch is "out of level"), rerun it with `--rolling` (a few measurements, or a duration of a few hours to a day depending on the cadence) and `--instants 2`: the brief deviations under the drift come out alone, and the list per instant says which sensors deviate together, which are rejected and what the references do at that instant; a deviation of all the targets with the references at the same instant is read against the camera pose), and the tables of `x`, `y` on the windows where they stir. On a station that has the quality metrics, for each moment: `quality.py --table flux --sensors …` (or `--labels F --numbers N --edges` on a label) says which targets are hidden (flux cut) or veiled, from which instant to which instant; write them by their name.
6. **The images**: thumbnails (with `--contrast` for a faint target) spaced, one every 2 to 3 h, tighter where the curves move, always with an unaffected witness sensor, at a time before, during and after (at the same hour of the day if possible); when `x`, `y` of a sensor jump between two thumbnails (centre of the frame written under each), rerun with `--fixed` before saying that a spot appears or disappears; the whole image for the scene (occultation, lighting, weather).
## Ce que la lecture rend
## What the reading returns
Une ligne par moment. Un moment : un capteur ou un groupe de capteurs qui sort de son niveau habituel pendant une fenêtre que tu peux dater.
One line per moment. A moment: a sensor or a group of sensors that leaves its usual level during a window you can date.
| Début | Fin | Capteurs | Colonnes | Ce que je vois | Images |
| Start | End | Sensors | Columns | What I see | Images |
|---|---|---|---|---|---|
- **Capteurs** : références ou cibles, combien, lesquels.
- **Ce que je vois** : la forme (pic d'un pas, palier, montée lente, agitation), l'ampleur face au niveau habituel (en MAD ou en fois la médiane), le retour à la normale ou non, ce que font les autres capteurs, **ce que fait la caméra** au même moment (pose qui bouge, de combien, ou immobile ; recalage absent ; « pas de `camera/` » si le dossier n'en a pas).
- **Images** : ce que montrent les vignettes et l'image entière à ce moment, ou « pas d'image ».
- **Sensors**: references or targets, how many, which ones.
- **What I see**: the shape (one-step peak, step, slow rise, agitation), the amplitude against the usual level (in MAD or in times the median), the return to normal or not, what the other sensors do, **what the camera does** at the same moment (pose moving, by how much, or still; registration absent; "no `camera/`" if the folder has none).
- **Images**: what the thumbnails and the whole image show at that moment, or "no image".
Heures en UTC.
Times in UTC.