What this is: A written agreement — a data contract — describing how a drone’s sensor “dots”, “scans” and “generations of dots” are shaped, stored and edited, so a human can replay a flight or tidy up a single scan in an editor. Why it’s here: Every dot a human straightens by hand quietly becomes a perfect before/after lesson for the mapping model. I wrote this contract specifically so we never throw those lessons away.
Date: 2026-06-16 Ticket: rl-lab dev-log #35
Glossary
- Point scan — a single measurement the drone takes, either as a fan of rays or as one targeted shot. Think of it like one camera flash in a dark room: a single press of the button that lights up a cluster of nearby surfaces all at once. One scan returns a batch of dots.
- Dot — a single hit against an obstacle: its x, y, z coordinates plus a note of who produced it. If a scan is the flash, a dot is one bright speck the flash revealed.
- Generation — the processing stage of a dot. Generation 0 is raw, exactly as the sensor saw it; generation 1 is hand-corrected by a person; generation 2 has been calibrated in bulk. Picture the same photo saved three times: the camera original, your retouch, and the batch-color-graded export. Same picture, three states.
- Calibration (sweep) — a single shift-and-rotate recipe applied to a whole group of dots at once, to cancel out the drift the drone accumulated while flying. Rather than nudging fifty dots one by one, you grab the whole cluster and slide it back into place in one motion.
- PPO — Proximal Policy Optimization, the reinforcement-learning algorithm the flight policy is trained with. It is not the consumer of this data; the mapping model is.
- Mapper / cartographer model — the neighbouring model that turns dots into a usable map. It needs well-labelled dots to learn from, and it is the customer this whole contract was designed to serve.
1. What I wanted
I wanted to stop being vague. Up to now “we store the scan points somewhere” was a hand-wave, and the interface agent could not build anything solid on top of a hand-wave. So I wrote down a contract: what fields a dot has, what a scan is, what the editor is allowed to do to them, and how all of it lands both in memory and on disk.
The end goals were concrete:
- Load a pile of scans and inspect one scan or one generation in the editor.
- Or press play and replay the map over time, watching dots appear in the order the drone actually measured them.
I want to be clear about my role here: I did not build any of this. This document is the blueprint the interface agent will code against. I am the downstream consumer — I take the resulting dots and feed them to the mapper.
2. The core idea (why versioning matters)
While a drone flies, it slowly loses precise certainty about where it is. That accumulated drift means the raw dots wander a little — a wall that is dead straight in reality comes back gently bowed, like a row of fence posts photographed through warped glass.
When you sit in the editor and slide or rotate a group of older dots so they line up cleanly again, you are correcting that drift by hand. And here is the part I care about: the pair “was crooked → now straight” is an excellent training example for the mapper. The model can learn to straighten warped scans on its own — but only if we keep the crooked version and the corrected version side by side.
So in the contract I insisted on two things: never sever the link between the raw and the corrected version of a dot, and always record where the drone believed it was at the moment of the scan. Lose either, and the lesson evaporates.
3. What I proposed (and any of it can be overruled)
- A dot keeps the same identity number across every generation, so you can always trace “raw → corrected” for that exact point.
- Calibration is stored as a shift-and-rotate recipe, not as a permanent rewrite of the coordinates. That means it can be undone — the original is never destroyed.
- The bulk of the mapper’s training data comes from simulation, where the ground truth is known and we can label thousands of dots perfectly and for free. The hand-corrections are a smaller but very precious “gold standard” set, plus a reality check against the real world.
- Each dot gains a “who produced it” field (sensor / human / simulation ground-truth) and a “what is it” field (corner / passage / wall / …).
4. What I added to the existing schema
- I split the single “type” field into two genuinely different ideas: “which kind of scan produced it” (fan sweep vs. targeted shot) and “do we trust it”. Conflating those is a trap — a high-confidence guess and a low-confidence ground-truth are not the same animal. Targeted shots also carry the ray angle, which is why they get the violet outline in the editor.
- The dot file is line-based, ordered by time → trivially “play back over time”, and carries identity numbers → trivially “open one scan”. The flight itself (immutable) and the edits to the dots live in separate layers, so editing never corrupts the source recording.
Here is how the generations line up:
| Generation | Meaning | Produced by | Reversible? |
|---|---|---|---|
| 0 | Raw measurement | Sensor | n/a (source) |
| 1 | Hand-corrected | Human in editor | Yes |
| 2 | Bulk-calibrated | Sweep recipe | Yes |
5. Open questions for Aleks (visual nitpicks)
- How should we draw raw dots (generation 0)? I suggested pale, hollow markers — present but clearly “untouched”.
- Do we keep “trust” as a filter rather than a colour, so colour stays free to mean something else?
- Dot size should mean “what to look at right now” (current things bigger), not “how accurate it is”. Is that the intent?
6. Sources
- rl-lab dev-log #35 (this contract), source of record.
- The mapper-model training notes, which set the requirement that raw and corrected dots stay linked.
7. What’s next
The interface agent codes the classes, the storage layer and the file format once Aleks gives the go. We finalise the category list (“corner / passage / …”) together. I stay on the receiving end, turning these labelled dots into training material for the mapper.