Files
aimsight-labeling/docs/superpowers/specs/2026-11-18-displacement-split-design.md
T

10 KiB

Displacement split: Displacement and Perturbation

Status: draft, to be approved by the user. Nothing applied yet (families.md is read live by aimsight-app).

Why

Displacement today is the bin of D-074 ("À vérifier", 2026-10-27): "a lasting jump, a slow drift, and anything that changes the corrected curves without an established cause". Of its 63 labels in auto/, 50 say in their own text that the structure did not move, or that a movement is not established. The user: a displacement is a movement, a real one; families must stay simple.

Goals

  • Displacement = something moved (a jump or a drift) and never came back.
  • One new family, Perturbation, for what changes the corrected curves, comes back, and no other family explains: cause unclear or several factors; nothing to do.
  • Simple families: two keys where there was one, no family per mechanism.

Non-goals: changing the other families; reworking Thermal displacement (its camera labels keep it); touching manual/.

Anti-goal: a Perturbation that hides a movement. What has not come back stays Displacement.

Approaches

  • A. One catch-all (Unexplained) for the 50 non-movement labels. Dropped: the old bin under a new name.
  • B. By what moves (Displacement targets, Camera movement, Artifact base and spikes). Dropped: three keys; the user wants simple families.
  • C. By permanence (chosen by the user). A camera movement is usually thermal: Thermal displacement, as today. Otherwise, the family follows whether the movement is permanent: it stays, Displacement; it comes back, Perturbation. The same rule for a target, a reference or the camera. It is also the line the detector already draws (displacement.py: "back" against "lasting" / "recent").

The families

Proposed rows for families.md (main table):

Key Detector What happens For the client
Displacement displacement.py (lasting shift, jump not back yet, slow drift) something moved, by a jump or a drift, and has not come back by the end of the range: one or more targets, a reference, or the camera outside a thermal effect; the description says what moved check what moved: the structure (look at the images, check on site) or the camera (check its mount)
Perturbation displacement.py (jump back to normal) the corrected curves move beyond their noise and come back, and no other family explains it: a jolt of the camera, a reference or the base shifted for a while, a single point, targets that wander and come back; the cause is not established or several factors mix nothing to do: the curves came back; ignore these points

Varieties:

Variety Family For the client
Sudden jump, back to normal Perturbation (was Displacement) nothing to do: it came back; ignore these points
Lasting shift Displacement check what moved: look at the images
Jump, not back yet Displacement check what moved: look at the images
Slow drift Displacement keep watching it

Boundaries, in families.md:

  • New, Displacement or Perturbation: decided by the return, not by the cause. What moved and has not come back by the end of the range (a target, a reference, the camera outside a thermal effect) is Displacement; what comes back, even after days, is Perturbation. A camera that moves and stays is Displacement even when the compensation absorbs it afterwards; the description says it is the camera. A partial return is not a return.
  • Thermal displacement or Displacement (line 33): unchanged; add that what does not follow the temperature and comes back is Perturbation.
  • A jump then the return (line 32): "Without an established cause: Displacement" becomes "Perturbation".
  • A hindered reference (line 31): "Visibility, or Displacement without a cause" becomes "Visibility, or Perturbation without a cause; Displacement if the base stays changed".
  • Target issue or Displacement (line 37): unchanged.

Phenomena: since the cases work of 2026-11-18 (2026-11-18-cases-design.md), they are the cases of auto/cases/, no longer a section of families.md. The cases of family Displacement that come back move to Perturbation; the rest is as first drafted here: the Displacement section keeps the movements that stay ("a real movement of the structure", "a target or a small group jumps and stays shifted", "a step taken during a measurement outage", "the camera tilts little by little", "a step of the camera that the compensation does not erase", when it stays); a new Perturbation section takes "targets move slowly, alone, then come back", "the base changes without a reference lost" (with its return), and adds "a jolt of the camera, back at the next measurement", "a reference measured shifted alone, then back", "a single point of one or a few targets, back at once".

labeling-rules.md: line 63, the list of keys gains Perturbation; line 86 is rewritten: a Displacement says what moved and that it has not come back, and concludes "the targets moved: to check on site, monitor" or "the camera moved and stays: check its mount"; a Perturbation says what moved, that it came back and when, and concludes "nothing to do: points to ignore". A Perturbation states its cause in the three ways of line 99, like any label; "nothing to do" rests on the return seen, not on a cause (line 102).

The 63 labels

By the rule above (return judged on the whole range of the analysis):

Displacement, 27 (family unchanged, description unchanged but NORDEND-250):

  • targets that moved and stay: CLARIDEN-9, CLARIDEN-23, FLORIDA-46, NEBRASKA-5, NIEDERHORN-131, NIEDERHORN-167, NIEDERHORN-168, NORDEND-94, WILDSTRUBEL-89, WILDSTRUBEL-120, WILDSTRUBEL-173, WILDSTRUBEL-183;
  • camera that moved and stays: BREITHORN-43, BREITHORN-39, BREITHORN-44, CLARIDEN-74, MICHIGAN-19, NEBRASKA-1, NEBRASKA-6, NORDEND-250, NORDEND-309, SNCF01-7, SNCF01-42, SNCF01-102, SNCF01-132, WILDSTRUBEL-200;
  • base that stays changed: NORDEND-276.

Perturbation, 36 (family changes):

  • base or a reference shifted, then back: ALASKA-1, ALASKA-3, ALASKA-5, ALASKA-6, ALASKA-9, FLORIDA-18, FLORIDA-72, JUNGFRAU-110, JUNGFRAU-112, LENZSPITZE-105, LENZSPITZE-106, LENZSPITZE-108, MICHIGAN-8, NIEDERHORN-126, NORDEND-112, NORDEND-279, WILDSTRUBEL-136, WILDSTRUBEL-153, WYOMING-9, WYOMING-13, WYOMING-17;
  • camera jolt or shift, then back: LENZSPITZE-84, NEBRASKA-3, NORDEND-80, NORDEND-243, NORDEND-278, NORDEND-310, WYOMING-11, WYOMING-16;
  • single points, back at once: ALASKA-2, LENZSPITZE-98, NIEDERHORN-144, NIEDERHORN-157, NORDEND-251, NORDEND-271;
  • a target that moved, then came back: NORDEND-257.

Calls made by the drafter (to check):

  • A partial return is not a return: BREITHORN-39 (inside the camera drift of BREITHORN-43 and -44), NEBRASKA-5 (COLJ19 comes back only in part), NIEDERHORN-131 (three targets come back in part, two stay): Displacement.
  • NORDEND-94: its text says the curves of PR17 came back neither to their level before the jump nor to the plateau, to the end of the batch: Displacement (the first draft had it as Perturbation).
  • NORDEND-250: the camera keeps its step, the curves come back at the next measurement: Displacement, following "the permanent movement of the camera".
  • NORDEND-276: the base stays changed to the end of the range, the targets do not move in the image: Displacement (something stays moved, possibly a reference).
  • WILDSTRUBEL-120 mixes a return (PB_5) and a lasting shift (PA3_2): Displacement for the shift that stays.
  • No Displacement label becomes Thermal displacement: none comes back with the housing temperature (families.md, line 33).

Descriptions to reword, their conclusion contradicting their new family: NEBRASKA-3, NORDEND-257, NORDEND-310, FLORIDA-18, WILDSTRUBEL-136 (Perturbation, but "to be monitored", "to be checked"), and NORDEND-250 (Displacement of the camera, but "point to ignore"). Only the closing sentence changes; the plan gives each.

The copies in auto/analyses/*/labels.jsonl follow the same change.

What it touches

  • aimsight-labeling: families.md, labeling-rules.md, scripts/validate.py (FAMILIES), scripts/client.py (its check), the 38 labels in auto/ and their copies in the analyses; ids.py untouched, ids never change.
  • aimsight-detectors: scripts/displacement.py, a "back" episode gets kind Perturbation (one line); scripts/categories.py, CATEGORIES gains Perturbation (greyed, nothing to do), and host() keeps joining a jump back to the Visibility or Obstruction around it.
  • aimsight-app: app/web/src/pages/Data.jsx, FAMILIES gains Perturbation and its colour (the Category menu and the timeline follow).
  • The agents' instructions: aimsight-agents/agents/analyst.md (the list of family keys); Support-Agent/.claude/skills/support/rapport.md (the order of the families for the client). The etiqueteur and detectors-critic of Support-Agent still speak the old format (familles.md, categorie): left as they are.
  • The detectors' docs: "the six families" in aimsight-detectors/CLAUDE.md and README.md, and in the comment of Data.jsx, become seven.
  • aimsight-optimizer: nothing in code; its benchmark reads auto/, so the Displacement scores change meaning from the relabel on.
  • manual/: the expert's labels keep the old meaning of Displacement; to tell the expert, not to change.

Open, for the user

  1. The review dates. All 63 labels carry a review (2026-11-17, 2026-11-18), and any change removes it (README.md). Approved: keep review on a change of family made at the user's request, remove it on the 6 reworded descriptions.
  2. The return window of the detector. The labels judge the return on the whole range; the detector on 24 hours (BACK_H): a shift back after two to six days (ALASKA-9, FLORIDA-18, NEBRASKA-3, WILDSTRUBEL-136, WILDSTRUBEL-153) is Perturbation in the labels and Displacement for the detector. Approved: leave BACK_H to the optimizer, which learns from the labels.

Left to the builder

The exact wording of the phenomena lines; the colour of Perturbation in aimsight-app; the order of the commits across the three repositories (labeling first, then detectors and app, the same day: aimsight-app rejects a label whose family validate.py does not know).