contributions(clean-and-map): pointer to yugeeklab's coverage-while-mapping implementation

[yugeeklab]

Description

Hi, @makers-pet Claims a second track on the clean-and-map module and adds a pointer to my
self-hosted implementation, per CONTRIBUTING: the code lives in my repo, with a
link in-tree. One file, contributions/clean-and-map/yugeeklab/README.md.

This replaces #71. I closed it thinking the module was taken, and its branch is
gone. Thank you for the note there. What #71 said is below, updated.

Self-hosted repository: https://github.com/yugeeklab/oomwoo-clean-and-map
Discussion: #66

Approach

Coverage while mapping. The robot starts with no map, sweeps the floor slam_toolbox
has drawn so far, replans as more of the room appears, decides it is finished and
saves the map. It is a separate node, so it stays out of the way of @Arkz-Deepak's
work on coverage_planner.

Against the acceptance criteria

Criterion	State
Full coverage of the reachable floor, from multiple initial poses	yes: five start poses on living_room, all five cross 0.90
A complete map of the reachable area	yes: map completeness 0.985 to 0.994 across the five
A clear done condition, and the map saved	yes: defined in the repo README, and the scorer checks the map reached disk
Robust to a dynamic obstacle in the path	yes: a box crossed the robot's floor four times in one session, and the scorer's four checks all passed
LiDAR-invisible obstacles: bumper, mark, replan, never stuck	partly, see Known limits
Left / right / front bumper	yes: oomwoo_one's two contact sensors are the two halves of the front bumper, and both are handled
Headless regression of coverage and map completeness	yes: map_completeness_meter, plus regression.sh and score_run.py, which give one session a pass/fail exit code
Additional multi-room / different floorplan world	yes: a new studio.sdf of 19.4 m², and oomwoo_gazebo's multi_room.sdf of 52.0 m²
Documented, reproducible by someone else	the repo README and docs/

Where it stands on living_room

No map at start, headless, scored by coverage_meter at cleaning_radius 0.20,
which is what coverage_regression.launch.py uses. Five start poses:

start	crossing 0.90 at	efficiency there	final coverage	map
0.32, 1.59	58.5 m	0.582	0.951	0.987
-1.30, 1.64	63.4 m	0.537	0.967	0.990
1.85, 1.14	53.1 m	0.641	0.934	0.994
-1.85, -0.31	64.0 m	0.532	0.928	0.985
1.80, -0.46	46.2 m	0.737	0.928	0.990

deploy/run_coverage_livingroom.sh with the stock coverage_planner, same world,
same harness: coverage 0.8772, target never crossed. This node crosses 0.90 from
every start pose tried, where upstream's does not reach it. Neither meets the
runner's 0.80 efficiency_target on this world, and I think the reason is the most
useful thing in this PR.

Same code and parameters on the other two worlds:

world	reachable floor	crossing 0.90 at	efficiency there
living_room	13.6 m²	46.2 to 64.0 m	0.532 to 0.737
studio	19.4 m²	89.1 m	0.545
multi_room	52.0 m²	143.5 m	0.906

Why neither planner makes 0.80 on living_room

At the 0.90 crossing the robot has driven 47.2 m against the 42.6 m the gate allows:
35.2 m of sweeping, 6.1 m of turn-arounds, and 5.9 m between the pieces furniture
cuts the passes into.

The passes are 0.35 m apart rather than the full 0.40 m swath, because localisation
error is 11 mm mean and 26 mm at p90, and passes exactly one swath apart leave strips
of floor between them. coverage_regression.launch.py sets row_overlap 0.05, which
on a 0.05 m grid rounds to exactly one swath. Upstream takes the wide spacing and
falls short on coverage. This node takes the narrow one and falls short on
efficiency. On multi_room, where a pass runs about 6 m against living_room's 2.5 m, the
same node reaches 0.906.

Known limits

• Repeated contacts with LiDAR-invisible obstacles. On studio a session
  escapes 63 to 112 times, most of them at the two 7 cm boxes. The saved SLAM map
  has every cell of both free, so a pass that grazes one is planned again after each
  escape. The robot never wedges, but it costs distance. I tried keeping a
  twice-bumped spot as an obstacle the planner sees. It cut escapes by about a
  third, but it sent the hops it blocked to Nav2, which stalled on short tight ones,
  and one session in six ended at 0.83. Giving Nav2 the spots through a
  KeepoutFilter as well stalled one session in two. Both were measured and neither
  was merged, and the repo's run record has the numbers. oomwoo_clean's
  bump_map_node already builds a tactile layer and is the natural source if this
  comes back.
• Simulation only, with no real-robot runs.

[yugeeklab]

Pictures from one session on each world, on the code this PR points at. They are
gallery sessions, so a camera was rendering throughout, and the numbers in the tables
above come from separate runs.

	living_room	studio	multi_room
floor swept
path, dark to light along its length

Swept 93.0 %, 98.2 % and 99.6 % of the reachable floor. On studio the knots in the
path are the escapes at the two low boxes described under Known limits.

All twelve pictures, and how they are made:
https://github.com/yugeeklab/oomwoo-clean-and-map/tree/main/docs/results/arm64-mac/gallery