feat: Q10 map layers, calibration, path & no-go zones (+ Q7 layer reuse)

[tubededentifrice]

Summary

Adds structured Q10 map layers, calibration, path placement, and vector overlays on top of #847. It also reuses the shared B01 grid-layer code for Q7 maps.

This PR is stacked on #847. Until #847 merges, GitHub will show those commits here too; the incremental work starts with feat: decompose Q10 map into separable layers.

Changes

• Split Q10 occupancy grids into separable background, wall, floor, and per-room layers. Each layer can be rendered as a transparent PNG for frontend compositing.
• Add GridCalibration and solve_calibration() to fit Q10 world coordinates to grid pixels from an active cleaning path.
• Populate MapData.path, vacuum_position, and charger position once calibration is available.
• Decode Q10 restricted-zone blobs into no-go, no-mop, and virtual-wall overlays in MapData.
• Decode and apply Q10 erase zones from the map packet tail so erased cells are removed from rendered maps and layers.
• Reuse the shared layer/calibration abstractions for Q7 SCMap payloads.
• Preserve existing overlays on partial status updates and keep path/position overlays after reparsing a calibrated map.

Notes

• Virtual walls, zoned-clean areas, and carpets remain best-effort until non-empty captures are available for each data point.
• Q10 calibration currently needs a sufficiently dense current-session path; no-clean calibration is left for a later PR.

Testing

• uv run pytest — 543 passed on the rebased stack
• uv run pre-commit run --all-files
• Focused coverage for Q10 layers, calibration, overlays, erase zones, parser edge cases, and Q7 layer reuse
• Live checked against Q10 captures for map layers, calibration fit, path placement, and no-go/no-mop zones

[allenporter]

If there are low level map parsing parts, you could send them out in parallel without blocking on the other changes if that would be helpful to parallelize review. otherwise, we can mark this in draft until the other blocking parts are reviewed and merged.

[tubededentifrice]

@allenporter ok, #850 is the standalone part

[andrewlyeats]

Really nice to see the Q10 calibration and layer work coming together here.

One thing that might help the no-clean calibration you've flagged as a follow-up: on our Q10 S5+ (ss07, fw 03.11.24) captures, the calibration data appears to be transmitted in the 0101 grid-frame header, so a GridCalibration can be derived without a session path (i.e. without solve_calibration's dense-path requirement). The header fields we see (absolute byte offsets in the 0101 frame, sub-type at 0–1; verified across our captures, scoped to ss07):

• bytes 11–12 x_min, 13–14 y_min (s16 BE) — the map origin, in 5 mm units (= 0.1 grid-px; ÷10 gives grid-pixel coordinates). This is the value solve_calibration is recovering by fitting.
• bytes 15–16 resolution (u16 BE) — reads 5 universally for us → 0.05 m/px (the 50 mm/px you use).
• bytes 17–22 charger x / y / phi — the dock position and orientation, as an alternative to inferring the charger from the path's first point.

On our decode, reading the origin straight from the header lands the path on-floor at the same rate as the auto-fit (they agree on ~29 of 31 captures; the two misses are null/keepalive frames where x_min == y_min == 0, which you'd just skip and fall back to a fit). So a header-derived calibration looks viable docked / pre-clean, which would drop the "needs a dense current-session path" requirement.

Happy to help — I can share scrubbed, annotated header captures, or sketch a PR against this branch if you'd like — and thanks for all the Q10 work. (Separately, the 0201 path header also carries a live SLAM heading field at bytes 10–11 if orientation is ever useful alongside vacuum_position — glad to detail that too.)

[tubededentifrice]

Thanks @andrewlyeats, this was really useful! I've implemented the header-origin part on this branch.

The 01 01 header now decodes into a Q10HeaderCalibration (x_min/y_min @11–14, resolution @15–16, charger @17–22), and origin_pixels() returns the grid-pixel origin (÷10, since the grid is 50 mm/px). Keep alive frames (x_min == y_min == 0) are detected and skipped > fall back to the path-fit, exactly as you described.

To use it, I added solve_calibration_with_origin(): with the origin fixed from the header, only the resolution + Y sign are fit, so it now confirms from a short path instead of needing a dense clean (the trait prefers the header origin at >=4 points, falls back to the full fit at ≥20).

One thing I couldn't pin down without your data: the header resolution reads 50 mm/px, but my path-fit lands at ~13-16 per pixel, i.e. the path coordinates don't look like millimeters, so I can't yet turn the header's 50 mm/px straight into the GridCalibration resolution. That's the only reason it isn't fully path-free yet (origin is exact; resolution still gets a quick on-floor validation against a short path).

So I'd love those scrubbed, annotated header captures, especially a few where you've noted the path/trace coordinate units alongside x_min/resolution. If I can confirm the path-unit <=> pixel relationship, I think the docked/pre-clean (zero-path) case falls out directly. And yes, please do detail the 0201 SLAM heading field too, orientation alongside vacuum_position would be nice to have.

Thanks again for the cross-capture validation here.

[andrewlyeats]

Glad the header origin helped. On your two questions:

1. Path-unit ↔ pixel. On our end res = 20 path-units/px lines the path up on the grid (~99.8% on floor), and our
byte-14 coords drop into your world_to_pixel as-is — per-axis scale + Y-flip, no transpose. So that's the resolution
that registers everything here, no fit needed.

The one open piece is the absolute scale: a path-unit isn't a millimeter, and we've only ever anchored 20 internally —
never ruler-measured it — so a constant scale factor could move the real-world number. Your 13–16/px isn't necessarily
wrong, it may just be that factor. Either way the divisor is a fixed constant, so once it's pinned the docked case
falls out; a single ruler-measured drive would settle the absolute. The captures let you check whether 20 registers your
path too.

2. I think that "stray leading point" is the robot's heading. Your 10-byte trace header starts the points at byte 10, so the
"first point" reads as bytes 10–13 = (heading, 0) — far enough from the real points (byte 14) that
_drop_stray_leading_point removes it. Bytes 10–11 are the 0201 SLAM heading (i16; 0 = +x / +90 = +y / ±180 = −x / −90 = −y); read it there, keep points from byte 14, and you recover orientation for free.

Two captures (ss07, fw 03.11.24). The code blocks are raw frame bytes; the two tables below decode every header byte
(A and B side by side).

Capture A — 2026-06-22.

0101 grid frame (header bytes 0–22; the rest of the frame is the LZ4-compressed grid):

01 01 6a 2b 59 80 01 00 db 00 fe 06 73 01 b2 00 05 03 82 03 3d 00 a7

0201 path frame (one stream — header, then (x,y) points from byte 14; first 110 of 5682 bytes):

02 01 00 a3 00 02 00 00 05 89 00 a8 00 00 00 05 00 4c f9 41 fc d8 f9 38 fc c7 f9 2c fc af f9 24 fc 9b f9 18 fc 87 f9 10 fc 77 f9 04 fc 63 f8 f8 fc 4f f8 f0 fc 3b f8 e8 fc 27 f8 dc fc 17 f8 d4 fc 03 f8 cc fb ef f8 cc fb db f8 c8 fb c3 f8 c8 fb af f8 c8 fb 97 f8 c8 fb 83 f8 c8 fb 6b f8 c4 fb 57 f8 c8 fb 3f f8 d4 fb 2f f8 e4 fb 23

Capture B — 2026-06-20.

0101 grid frame (header bytes 0–22):

01 01 6a 2b 59 80 01 00 dc 00 ff 06 73 01 bc 00 05 03 7f 03 3c 00 b1

0201 path frame (first 110 of 9862 bytes):

02 01 00 9b 00 02 00 00 09 9e 00 ac 00 00 ff fd 00 00 f9 55 fd 1c f9 68 fd 1b f9 7c fd 23 f9 94 fd 28 f9 b8 fd 28 f9 bc fd 3c f9 b8 fd 50 f9 a4 fd 58 f9 90 fd 58 f9 78 fd 58 f9 64 fd 58 f9 54 fd 64 f9 48 fd 78 f9 48 fd 88 f9 48 fd a0 f9 48 fd b4 f9 40 fd c4 f9 2c fd d0 f9 18 fd d0 f9 04 fd c8 f8 f0 fd c4 f8 f4 fd b0 f8 f0 fd 9c

0101 grid-frame header (all BE):

bytes	field	A	B	note
0–1	sub_type	0101	0101	grid-frame magic
2–5	map_id	6a2b5980	6a2b5980	per-map id (same map for both)
6	map_segmented	1	1	1 once finalized into rooms (0 while building)
7–8	width	219	220	grid px
9–10	height	254	255	grid px
11–12	x_min	1651	1651	origin; oy = −2·x_min = −3302
13–14	y_min	434	444	origin; ox = 2·y_min = 868 / 888
15–16	resolution	5	5	→ 50 mm/px
17–18	charge_x	898	895	dock X (same units as x_min)
19–20	charge_y	829	828	dock Y
21–22	charge_phi	−167°	−177°	dock heading (raw s16 negated)

0201 path-frame header (all BE; points then run from byte 14):

bytes	field	A	B	note
0–1	sub_type	0201	0201	path-frame magic
2–3	epoch	163	155	+1 per traversal (not per clean); power-cycle resets
4–7	const	00020000	00020000	constant; semantics unknown
8–9	point_count	1417	2462	may read one high
10–11	heading	168°	172°	i16; 0=+x / +90=+y / ±180=−x / −90=−y
12–13	const	0000	0000	constant
14 …	points	(5,76)* (−1727,−808) …	(−3,0)* (−1707,−740) …	BE int16 (x,y) path-units; *~origin sentinel; robot = last pt (A −1592,−753 → col 85,row 81 · B −1600,−761 → col 85,row 82)

3. One to glance at when the overlays render. On our ss07 a no-go (DP-55) and a wall (DP-57) only place right when
both keep their first wire coordinate on the same axis; your parse_virtual_wall_blob swaps DP-57 but parse_zone_blob
leaves DP-55, so if your device matches ours they'd come out transposed relative to each other. Easy to check once they
render — the #850 before/after is yours if it helps.

Thanks for folding the origin work so quickly!