Files
aimsight-labeling/reading-rules.md
T

100 lines
12 KiB
Markdown
Raw Normal View History

# Reading rules
What the data of a station mean: where each cause enters the measurement, what it touches, and the rules and false friends that the expert and the reviewed labels have established. What the files and columns are: `tools/DATA.md`. How to place a label: `labeling-rules.md`; the families and their boundaries: `families.md`, whose rules are not repeated here.
Cases are cited by label id (`NORDEND-80`, in `auto/<STATION>.jsonl`; `precedents.py` finds others); `[expert]`: the expert's word, from a label that is not in `auto/`. Maintained by hand.
## 1. How a measurement is made
1. **The scene**: targets on the structure, references around it, assumed fixed.
2. **The view**: the air between the camera and the targets, and what can pass or settle in front.
3. **The image**: the lens, then the capture (IRON, or DIFF which combines several captures).
4. **The pattern measurement**: each sensor is found in the image: `x`, `y`, `error_value`; on recent cameras, the image quality. Above `error_threshold`, the measurement is rejected.
5. **The compensation**: a 2D similarity (translation, rotation, scale) fitted on the references (`global_ref`) gives the camera pose (`pan`, `tilt`, `rotation`, `scale`, `sigma0`) and, per reference, `reproj_err` and `inlier`.
6. **The corrected curve**: `corr_x`, `corr_y`, the position of the target once the estimated camera movement is removed.
A displayed value is the end of this chain: find the stage that gave way.
## 2. Where each cause enters, and what it touches
| Stage | Cause | What it touches | Time | Witnesses |
|---|---|---|---|---|
| View (air) | fog, rain, condensation: **reduced visibility** | a homogeneous drop in flux; `error_value` rises, rejections; raw positions without a step | hours | quality (`flux`), images |
| View (air) | **heat haze** (turbulence) | a fast noise; only when the structure really heats up; not under a bridge | the hot hours | temperature, `error_value` by day versus night |
| View (obstacle) | object, leaves, snow on a target: **occultation**; a passage | one or a few targets; on a recent camera, their flux cut, the neighbours intact (LENZSPITZE-9); a passage: one measurement | from one measurement to weeks | quality, images |
| Target | problem target (badly oriented, dirty, glued) | one target, lastingly | days and more | `error_value` of the target alone |
| Lens | **thermal deformation of the optics** (sun on the station) | the whole image deforms, which a similarity cannot represent | short: follows the sun on the station | housing temperature |
| Camera and mount | **expansion of the mount**; wind, jolt, shock | raw positions of all sensors, references included, together; the compensation absorbs it (`corr` flat) or badly: `corr` follows the inflections of the camera movement | specific to the mount | camera pose, housing temperature |
| References | **reference hidden or less well seen** | the transformation is redone without it: points shifted at once, often grouped in one part of the image, the shift growing with the distance to the references; back when it returns: reversible | the time of the nuisance | `error_value`, `reproj_err` of the references, `sigma0`, camera pose |
| References | a reference moved | the `corr` of the targets shifted lastingly | lasting | `reproj_err` of the reference |
| Structure | **thermal expansion of the structure** | `corr`, an amplitude specific to each target, references stable | the longest: slow heating, late cooling | no air temperature (section 3) |
| Structure | real movement | `corr` of one or several targets, which lasts; references and pose stable, good image quality | lasting | all of the above, at calm |
**A jump that returns** to normal is not serious: the return is what makes it benign. Saying "jump" is not enough; the question is its cause, quite often a reference hidden or less well seen.
## 3. Thermal effects
- **Three movement effects**: the lens, the mount, the structure, told apart by their heating and cooling times; the structure is the slowest. Heat haze is apart: a noise, not a movement.
- **The cases cross**: a camera on a bridge has two structures, the one that carries it (the mount) and the one it monitors.
- **In waves**: expansion, then contraction; often stronger in Y than in X, depending on the orientation.
- **The kind of structure says whether a thermal movement is possible**: a bridge yes; a rock face, too massive, or a road, no: the movement is then that of the camera (`stations.md`). [expert]
- **The camera can move through a thermal effect at a different rhythm from the structure**, not having the same heating time. [expert]
- **The temperature that counts is that of the camera housing, not that of the air around**, even sheltered. The temperatures available are those of the compute board (`sensor_*_deg_c`), inside the housing, heated by the sun and by the computing, as hourly means: a witness for the lens and the mount, not for the structure nor the air. `temperature_deg_c`, on a few stations: unknown sensor. [expert, BREITHORN-14]
- **A change of regime is understood through the temperature**: look at it. [expert]
- **The direction of a thermal movement is read on the housing temperature, not on the hour**; when the scale of the camera follows it, the effect is on the camera. [NORDEND-294]
## 4. Gaps
- **A gap is not necessarily an outage**: acquisition, transmission, ingestion and display are distinct layers.
- At the end of a file, empty values can be only a synchronization delay (`last_sync`): a delay only if the other stations do not have their data yet either.
- At the start of a file, empty values precede the first measurement: not an outage.
- A gap surrounded by a normal voltage is not an energy problem.
- **A gap is read with the other stations and the metrics** (the boundary "A gap" of `families.md`). [JUNGFRAU-52, NORDEND-50, WILDSTRUBEL-201, CLARIDEN-56]
- **A power cut leaves a signature**: the voltage below the knee (about 12.8 V) just before or just after the gap; the temperature drops during the gap more than at the same hours on nights without a gap, which alone does not settle it (a common gap can do the same, an outage that comes back after sunrise shows nothing).
- **A station on mains that comes back with its battery drawn down has lost the mains.**
- **A `NaN` or `inf` value** in an export is an absence of measurement.
## 5. Reading rules
- **What moves in the image is read before the cause, on the raw positions against the overall movement** (`overview.py --rigid`): the targets do not move relative to each other, it is the camera [BREITHORN-2]; targets move alone, a movement is not excluded [CLARIDEN-14]; nothing moves and the curves jump, it is the base or the configuration [WILDSTRUBEL-136, CLARIDEN-65].
- **A jump is judged against the neighbours**: if it brings the target back toward them, it is a return to normal, and the artifact was before; if it takes it away from them, it is to be treated quite differently. [expert]
- **A level is also judged against the past of the target, over weeks**: a jump that brings it back to an old level is a return. [NORDEND-94, NORDEND-169]
- **A high `error_value` is not a problem in itself: its variations count.** [expert]
- **A very stable `error_value` says the targets stay well visible**: while they move, it rather suggests a poor compensation than an obstruction of the view. [expert]
- **A rejected measurement is removed from the display, not a measurement just under the threshold**: a target left under the threshold keeps its jump. [expert, NIEDERHORN-143]
- **At least three references are needed; dropping a single one is enough to distort everything**: a kind of triangulation. **The position of the targets rests on the network of references**: references badly seen, targets badly anchored. [expert]
- **The reprojection error says how many references hold**: at zero, only two remain, a very bad sign, not a perfect measurement; absent, only one, and no measurement is possible. Except on a station built with two references, where it is always at zero. [JUNGFRAU-22, FLORIDA-65, expert]
- **The pose of the camera is reliable only if the references hold**: a reference rejected, dropped or sliding against the targets distorts it; a single hindered target does not. [FLORIDA-58]
- **A drift specific to a few targets that follows the camera, on the same dates, is the scene deforming with it**, not a second movement; it is separate only if it has its own dates. [NEBRASKA-6, NEBRASKA-5]
- **Neighbouring cameras are read together**: the same movement, the same loss or the same gap on the cameras of one building have a common cause; what touches only one is on its line of sight. [MICHIGAN-3, BREITHORN-20]
## 6. False friends
- **Jumps of many targets, all in the same direction, are not a movement** when they fall at the reference switches: raw positions without a step, daily cycle that continues. [expert]
- **A target that slides slowly away from its neighbours is not moving** when its `error_value` rises with the sliding and a step brings it back toward them. [expert]
- **A rise over several days is not necessarily a real movement**: it may follow a lasting drop in temperature. [expert]
- **Corrections stuck at zero are not a failure**: a twin of a reference. [expert]
- **No signal does not mean no obstruction**: only the images show the web. [expert]
- **A web is not the spider**: the web veils in part for hours or days; the spider hides everything for the length of one measurement. [expert]
- **References that do not move in the rain do not contradict the rain**: higher up, they suffer it less. [NIEDERHORN-141]
- **The step of a real movement is not its amplitude** when the camera and the references have moved too. [expert]
- **A swarm of insects is not a train**: same signature; only the image tells them apart. [NIEDERHORN-66]
- **In a tunnel, a temperature drop at the same moment does not make a thermal effect**: the bump of a group comes with the `error_value` and returns before the scale of the camera. [CLARIDEN-12]
- **The return of the `error_value` is not the end of an obstruction**: after a mark on the glass, the curves stay shifted. [NORDEND-169]
- **A spot on a thumbnail that follows the measurement is not necessarily there**: the frame follows a measurement perhaps latched onto the neighbour; only a fixed frame shows it. [expert]
## 7. Non-negotiable rules
- Judge nothing on a binary `inlier`: use continuous weights, residuals, influence.
- Neither `sigma0` alone nor the number of references is ever a sufficient criterion.
- The image quality of a target is not the quality of the reference network; a small residual is not a well-constrained transformation.
- A common-mode movement is not a structural movement; coherent references are not physically fixed references: the camera cannot prove that a network moving as a block is fixed.
## 8. Lessons from cases outside the labels
- **When everything moves together, the measurements alone do not separate the structure from the camera** (Barcelona, a bridge whose vault subsided: the references, the camera and the structure moved; the expert called it a real movement, confirmed by other monitoring systems of the site). An unstable compensation then distorts the amplitude of a real movement: the movement is reported, its amplitude is not established. [expert]
- **Two prisms too close interfere**: a 24 h cycle correlated between the two, or isolated peaks on one target at a time, too large for the structure, with no obstruction on the images; a neighbour much brighter than the others. On a recent camera, `dominance` shows it. [client report]
- **Vegetation grows over days and weeks**: a partial, progressive occultation, not reversible from one measurement to the next like a passage; the hardest obstruction according to the expert. [client report]
- **References masked (two of four, by vegetation)**: a 24 h cycle on pan, roll and tilt, badly compensated, is then not a movement of the camera but a base too weak for the transformation. [client report]
- **A target of low contrast**: by day, square waves on one axis, back at night, `error_value` rising by day without reaching the threshold. [client report]
- **Snow**: noise and apparent movements on all sensors and the camera, a brief loss of data, the signal quickly back. [client report]