Files
aimsight-detectors/categories.py
T

247 lines
16 KiB
Python

"""Journal du matin : des épisodes des détecteurs aux événements, un par famille.
Un détecteur par famille des étiquettes (labeling/familles.md) : visibility.py, obstruction.py, target_issue.py,
thermal_displacement.py, no_data.py, displacement.py. La catégorie d'un événement est sa famille, le champ kind de ses
épisodes ; leur label en dit la sorte (Poor visibility, Heat shimmer, Brief obstruction, Slow drift…). Règles :
- un saut revenu à la normale (SAUT) qui chevauche un épisode de HOTES (perte de visibilité, passage, turbulence, et en
dernier l'effet thermique, s'il touche plusieurs cibles) y est absorbé : il en prend la cause et la famille ; sinon il
reste Displacement, sans cause établie, à vérifier sur les images (familles.md, « Un saut puis le retour ») ; un passage
(Brief obstruction, un seul instant) n'absorbe que les sauts qui commencent à son instant, pas ceux de plusieurs jours
qu'il croise (/detector-learner Displacement, modification 1, S5) ;
- une dérive lente ou un saut revenu dont toutes les cibles sont dans un épisode Target issue qui le chevauche y est absorbé
(la courbe d'une cible à problème est à ignorer, familles.md) ;
- un décalage qui dure, ou trop récent pour savoir (DECALAGES), n'est jamais absorbé ;
- une turbulence qui chevauche un décalage de plusieurs cibles n'est pas gardée : un vrai mouvement agite aussi les courbes ;
le décalage d'une seule cible ne retire pas la turbulence de toute la scène, et une turbulence n'absorbe que les sauts
revenus qui commencent pendant elle, pas celui de la veille qui revient dans sa journée (/detector-learner Visibility,
modification 1, S1 : WILDSTRUBEL) ;
- deux événements de même sorte à moins de MERGE n'en font qu'un ; deux Obstruction (Target obscured, Brief
obstruction), seulement s'ils partagent un capteur (/detector-learner Obstruction, modification 1 : S1, des cibles
différentes enchaînées en un événement de plusieurs jours ; S3, des passages de quelques minutes en une heure entière) ;
deux Target issue aussi : chaque cible à problème garde ses bornes (/detector-learner Target issue, modification 1, S3) ;
un passage n'absorbe que les sauts revenus dans MERGE après son instant (S3 : pas le saut de 30 h d'une autre cible).
Chaque événement reçoit sa phrase, en anglais (le site) : ce qui s'est passé et quoi en faire, comme le dit la colonne
« Pour le client » de familles.md ; la cause n'est dite que si la sorte l'établit, sinon les images la montrent.
Pas de fonction detect : le chargeur ne prend pas ce fichier pour un détecteur.
Usage : python3 detectors/categories.py <dossier de station> (une ligne par événement : famille, sorte, capteurs)
... <dossier> [--du AAAA-MM-JJ] [--au AAAA-MM-JJ] [--tranche 3] [--historique N] (tri en lot : chaque tranche
de N jours classée seule, avec les jours d'historique d'avant s'ils existent ; seuls les événements qui touchent
la tranche sont montrés ; « rien » pour une tranche calme)
"""
import functools
import importlib.util
import inspect
import os
import sys
from datetime import datetime, timedelta, timezone
from pathlib import Path
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) # donnees.py, à côté
from donnees import charger, charger_camera, charger_metriques, charger_temperature, iso # noqa: E402
# Ce qu'un détecteur peut lire de la station en plus des mesures, s'il le déclare dans detect (D-124, D-134) :
# temperature [(t, °C)], médiane horaire des composants ; camera [pose] (pan, tilt, rotation, scale, sigma0) ;
# metriques {nom: [(t, valeur)]}, toutes les métriques numériques (sensor_CPU_deg_c, sensor_GPU_deg_c, BusVoltage…).
CONTEXTE = {"temperature": charger_temperature, "camera": charger_camera, "metriques": charger_metriques}
@functools.lru_cache(maxsize=None)
def _contexte(dossier, cle):
return CONTEXTE[cle](dossier)
# Les familles de labeling/familles.md, dans l'ordre des lignes de la frise ; ignore : zone grisée (None : comme le
# disent ses épisodes : une perte de visibilité totale, une turbulence forte) ; process : bouton Images, rien, ou Images
# et lien vers Diagnosis.
CATEGORIES = {
"Visibility": {"ignore": None, "process": "images"},
"Obstruction": {"ignore": True, "process": "images"},
"Target issue": {"ignore": True, "process": "images"},
"Thermal displacement": {"ignore": False, "process": "aucun"},
"No data": {"ignore": False, "process": "aucun"},
"Displacement": {"ignore": False, "process": "verifier"},
}
SAUT = "Sudden jump, back to normal" # un saut revenu : sa cause, s'il chevauche un hôte ; sinon Displacement
DECALAGES = {"Lasting shift", "Jump, not back yet", "Large shift"} # à vérifier : jamais absorbés
HOTES = {"Poor visibility", "Brief obstruction", "Heat shimmer", "Thermal expansion", "Thermal contraction",
"Camera thermal expansion", "Camera thermal contraction", "Camera thermal movement"} # disent la cause d'un saut revenu qui les chevauche
MERGE = timedelta(hours=1) # même sorte à moins d'une heure : un seul événement (règle validée, 2026-10-24)
def detecteurs():
"""Modules de detectors/*.py qui ont detect ; un fichier qui ne se charge pas est sauté avec un
message."""
mods = []
for path in sorted(Path(__file__).resolve().parent.glob("*.py")):
if path == Path(__file__).resolve():
continue
try:
spec = importlib.util.spec_from_file_location(f"journal_{path.stem}", path)
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
except Exception as e: # noqa: BLE001 (prototype : un détecteur cassé ne bloque pas la page)
print(f"Journal : {path.name} sauté ({type(e).__name__}: {e})", file=sys.stderr)
continue
if hasattr(mod, "detect"):
mods.append(mod)
return mods
def categorie(ep):
return ep["kind"]
def sorte(ep):
"""La sorte d'un épisode dans sa famille : les décalages ensemble, l'effet thermique sans « Camera », la perte de
visibilité par niveau."""
label = "shift" if ep["label"] in DECALAGES else ep["label"].removeprefix("Camera ").capitalize()
return ep["kind"], label, ep.get("level")
def thermique(ep):
return ep["kind"] == "Thermal displacement"
def overlap(a, b):
return a["start"] <= b["end"] and a["end"] >= b["start"] # heures donnees.iso : l'ordre du texte est celui du temps
def targets(n):
return "one target" if n == 1 else f"{n} targets"
def phrase(groupe, sensors, references):
"""Phrase du journal d'un événement (validées par l'utilisateur le 2026-10-24), d'après la sorte de son épisode
principal ; un saut absorbé ajoute qu'il a la même cause."""
n, one, ep = len(sensors), len(sensors) == 1, groupe[0]
sauts = [e for e in groupe[1:] if e["label"] == SAUT]
jumped = len({s for e in sauts for s in e["sensors"]})
lasting = len({s for e in groupe if e["label"] in DECALAGES for s in e.get("lasting", [])})
refs = ", including the reference targets" if references & set(sensors) else ""
camera = ep["label"].startswith("Camera")
large = any(e["label"] == "Large shift" for e in groupe)
sort = "shift" if ep["label"] in DECALAGES else f"{ep['label']} {ep['level']}" if ep.get("level") else ep["label"]
text = {
"Poor visibility none": f"The camera could not see {targets(n)} clearly{refs}. "
"The curves in this period are not reliable: ignore them.",
"Poor visibility reduced": f"The camera saw {targets(n)} less clearly than usual{refs}. "
"The data in this period are less precise: use them with care.",
"Brief obstruction": f"Something passed in front of {targets(n)} for a single measurement. Ignore this point on the curves.",
"Target obscured": f"{', '.join(sensors)} {'was' if one else 'were'} hidden several times while the targets around "
f"{'it' if one else 'them'} stayed clear. Ignore {'its curve' if one else 'their curves'} in this period.",
"Heat shimmer": "Warm air made the readings shake. The small fast wiggles are not movement.",
"expansion": ("The camera support expands in the day heat; the curves are corrected for it."
if camera else "The structure expands in the day heat.") + " This daily wave is normal: nothing to do.",
"contraction": ("The camera support contracts as it cools down; the curves are corrected for it."
if camera else "The structure contracts as it cools down.") + " This daily wave is normal: nothing to do.",
SAUT: f"{targets(n).capitalize()} jumped and came back. The cause is not established: look at the images.",
"shift": (f"{targets(n).capitalize()}, most of the targets, shifted together: everything moved." if large
else f"{targets(n).capitalize()} shifted and {'has' if one else 'have'} not come back yet." if not lasting
else f"{targets(n).capitalize()} shifted and stayed shifted." if lasting == n
else f"{targets(n).capitalize()} shifted; {lasting} of them stayed shifted.")
+ " Check whether the structure moved: look at the images.",
}.get(sort.split()[-1] if thermique(ep) else sort, ep["text"]) # No data, Target issue, Slow drift : le texte du détecteur
if ep["kind"] == "Target issue":
text += f" Ignore {'its curve' if one else 'their curves'} in this period and look at the images of the target."
if not jumped:
return text
return text + (f" The jump of {targets(jumped)} in this period has the same cause." if len(sauts) == 1
else f" The jumps of {targets(jumped)} in this period have the same cause.")
def evenement(groupe, references):
"""Épisodes d'un même événement, le principal en tête -> événement."""
cat, so = categorie(groupe[0]), sorte(groupe[0])
c = CATEGORIES.get(cat, {"ignore": None, "process": "aucun"})
sensors = [] if any(not e["sensors"] for e in groupe) else list(dict.fromkeys(s for e in groupe for s in e["sensors"]))
main = [e for e in groupe if sorte(e) == so] # la durée est celle des épisodes principaux, pas des sauts absorbés
return {"start": min(e["start"] for e in main), "end": max(e["end"] for e in main), "category": cat,
"label": cat, "text": phrase(groupe, sensors, references),
"ignore": c["ignore"] if c["ignore"] is not None else any(e["ignore"] for e in main),
"sensors": sensors, "process": c["process"], "episodes": groupe}
def classer(episodes, references=frozenset()):
"""Épisodes de tous les détecteurs -> événements triés par début (règles : docstring du module) ; references : les
capteurs global_ref, pour la phrase."""
eps = sorted(episodes, key=lambda e: e["start"])
# un vrai mouvement n'est jamais pris pour de la turbulence ; le décalage d'une seule cible n'est pas un mouvement de la scène
checks = [e for e in eps if e["label"] in DECALAGES and len(e["sensors"]) > 1]
eps = [e for e in eps if e["label"] != "Heat shimmer" or not any(overlap(e, c) for c in checks)]
# la vague thermique n'absorbe qu'en dernier (un saut d'un passage ou d'une pluie va à eux), et que les sauts de
# plusieurs cibles : la vague les fait bouger ensemble, une cible seule qui saute n'est pas la vague (C2 de E-003)
hosts = sorted((e for e in eps if e["label"] in HOTES), key=thermique)
host = {id(e): next((h for h in hosts if overlap(e, h) and (len(e["sensors"]) > 1 or not thermique(h))
and (h["label"] != "Heat shimmer" or h["start"] <= e["start"])
and (h["label"] != "Brief obstruction" or e["start"] == h["start"]
and datetime.fromisoformat(e["end"]) - datetime.fromisoformat(h["start"]) <= MERGE)), None)
for e in eps if e["label"] == SAUT}
# une dérive ou un saut revenu dont toutes les cibles sont dans un épisode Target issue qui le chevauche : sa courbe
# est à ignorer, il en prend la famille (/detector-learner Displacement, modification 1, S6)
host.update({id(e): h for e in eps if e["label"] in (SAUT, "Slow drift") and not host.get(id(e))
and (h := next((h for h in eps if h["kind"] == "Target issue" and overlap(e, h)
and set(e["sensors"]) <= set(h["sensors"])), None))})
groupes = {id(e): [e] for e in eps if not host.get(id(e))}
for e in eps:
if host.get(id(e)):
groupes[id(host[id(e)])].append(e)
merged = []
for g in groupes.values():
prev = next((m for m in reversed(merged) if sorte(m[0]) == sorte(g[0]) and (g[0]["kind"] not in ("Obstruction", "Target issue")
or set(g[0]["sensors"]) & {s for e in m for s in e["sensors"]})), None)
end = max((e["end"] for e in prev if sorte(e) == sorte(g[0])), default=None) if prev else None
if end and datetime.fromisoformat(g[0]["start"]) - datetime.fromisoformat(end) < MERGE:
prev += g
else:
merged.append(g)
return sorted((evenement(g, references) for g in merged), key=lambda v: v["start"])
def evenements(mesures, fin=None, dossier=None):
"""Mesures (donnees.charger) -> événements de tous les détecteurs : ce que la page reçoit dans D.journal. Un détecteur
reçoit en plus ce que sa fonction detect déclare : fin, la fin de la fenêtre lue (tri en lot), pour un trou qui la
touche ; une clé de CONTEXTE, lue dans le dossier de la station (une fois par dossier), vide sans dossier."""
episodes = []
for mod in detecteurs():
try:
params = inspect.signature(mod.detect).parameters
kw = {k: _contexte(dossier, k) if dossier else {} if k == "metriques" else [] for k in CONTEXTE if k in params}
if "fin" in params:
kw["fin"] = fin
episodes += mod.detect(mesures, **kw)
except Exception as e: # noqa: BLE001
print(f"Journal : {mod.__name__} sauté ({type(e).__name__}: {e})", file=sys.stderr)
return classer(episodes, {s for s, ms in mesures.items() if ms[0]["pattern_type"] == "global_ref"})
if __name__ == "__main__":
import argparse
p = argparse.ArgumentParser(description="Une ligne par événement ; --tranche : chaque tranche classée seule.")
p.add_argument("dossier")
p.add_argument("--du", help="premier jour UTC, AAAA-MM-JJ (défaut : début des données)")
p.add_argument("--au", help="dernier jour UTC exclu, AAAA-MM-JJ (défaut : fin des données)")
p.add_argument("--tranche", type=int, default=0, help="jours par tranche (défaut : un seul passage)")
# sans historique, une tranche qui commence juste avant un vrai saut le prend pour un saut revenu (PR17 à NORDEND,
# le 08/10 à 02:30 : absorbé dans la buée) ; 3 jours le rendent ; règle de l'utilisateur (2026-10-24) : 3 jours
# d'historique par défaut, dans la boucle comme dans la vraie application
p.add_argument("--historique", type=int, default=3, help="jours de mesures d'avant donnés aux détecteurs (défaut 3)")
a = p.parse_args()
mesures = charger(a.dossier)
ts = [m["t"] for ms in mesures.values() for m in ms]
jour = lambda d: datetime.strptime(d[:10], "%Y-%m-%d").replace(tzinfo=timezone.utc) # noqa: E731
debut = jour(a.du) if a.du else min(ts).replace(hour=0, minute=0, second=0, microsecond=0)
fin = jour(a.au) if a.au else max(ts) + timedelta(seconds=1)
t = debut
while t < fin:
b = min(t + timedelta(days=a.tranche), fin) if a.tranche else fin
h = t - timedelta(days=a.historique)
tranche = {s: k for s, ms in mesures.items() if (k := [m for m in ms if h <= m["t"] < b])}
evs = [v for v in evenements(tranche, b, a.dossier) if v["end"] >= iso(t)] if tranche else []
if a.tranche:
print(f"== {iso(t)} → {iso(b)} : {len(evs) or 'rien'}")
for v in evs:
print(v["start"], "→", v["end"], f"{v['category']:<20}", "grisé" if v["ignore"] else "gardé",
f"| {v['episodes'][0]['label']}", # la sorte : la règle du détecteur de la famille
f"| {len(v['sensors']) or 'tous les'} capteurs", "| absorbés :", ", ".join(
f"{e['label']} {e['start'][5:16]}" for e in v["episodes"][1:]) or "—")
t = b