docs: describe Nav2 observation demo

Signed-off-by: SamuelFoo <fooenzesamuel@gmail.com>

Author: SamuelFoo

discourse/3-layered-global-occupancy-map.md

@@ -2,138 +2,122 @@
 
 # Layered Global Map Observations
 
-This post describes the observation interface for contributing temporary map
-information to the next generation Open-RMF prototype.
+This post describes the implemented observation interface and demos for contributing temporary map information to the next generation Open-RMF prototype.
 
-The goal is to let robots and perception systems publish what they currently
-observe without tying them to a specific central map implementation. The first
-prototype consumes sparse 2D occupancy regions because that is enough for the
-current global planning grid, but the interface is intentionally isolated in
-`rmf_layered_map_msgs` so richer representations, such as height-aware or voxel
-observations, can be added later.
+The goal is to let robots and perception systems publish what they currently observe without tying them to a specific central map implementation. The first prototype consumes sparse 2D occupancy regions because that is enough for the current global planning grid, but the interface is isolated in `rmf_layered_map_msgs` so richer representations, such as height-aware or voxel observations, can be added later.
 
 # Quick Summary
 
 * Observation sources publish sparse temporary map patches
-* One message can contain both clear-space and occupied-space patches from the
-  same sensor snapshot
+* One message can contain both clear-space and occupied-space patches from the same sensor snapshot
 * Clear-space patches have TTLs, just like obstacle patches
 * A source can reset its previous observations without using a TTL
-* Robot-mounted sources can include the robot pose at observation time
-* The observation messages live in `rmf_layered_map_msgs`, leaving
-  `rmf_prototype_msgs` unchanged
+* Robot-mounted sources include the observation-frame pose at observation time
+* The Rust map server composes a static occupancy grid and active observations into `/map`
+* The Nav2 demo converts scans from three robots into point regions and displays the combined map
+* The observation messages live in `rmf_layered_map_msgs`, leaving `rmf_prototype_msgs` unchanged
 
-# Observation Topic
+# Observation Topics
 
-Observation sources publish dynamic map observations on:
+The layered map server uses these topics:
 
+* `/map/static` - static `nav_msgs/OccupancyGrid`
 * `/map/region_updates` - [`MapRegionUpdate.msg`](../rmf_layered_map_msgs/msg/MapRegionUpdate.msg)
+* `/map` - composed `nav_msgs/OccupancyGrid`
 
-The topic is an event stream. Updates are not latched because expired
-observations should not be replayed to a restarted map service as if they were
-current.
+The observation topic is an event stream. Updates are not latched because expired observations should not be replayed to a restarted map service as if they were current.
 
-Each observation stream should use a stable `source_id`, such as
-`robot_1/local_costmap`, `robot_1/front_lidar`, or `door_sensor/west_lobby`.
-The map service tracks each source independently so one robot can update or
-reset its own temporary observations without disturbing observations from other
-sources.
+Each observation stream uses a stable `source_id`, such as `robot_1/local_costmap`, `robot_1/front_lidar`, or `door_sensor/west_lobby`. The map service tracks each source independently so one robot can update or reset its temporary observations without disturbing observations from other sources.
 
 # Messages
 
 ## `MapObservationSource`
 
-[`MapObservationSource.msg`](../rmf_layered_map_msgs/msg/MapObservationSource.msg)
-describes where an observation came from.
+[`MapObservationSource.msg`](../rmf_layered_map_msgs/msg/MapObservationSource.msg) describes where an observation came from.
 
 Important fields:
 
-* `header`: global frame for the observation and its required, non-zero
-  timestamp
-* `source_id`: stable source identifier, usually the robot namespace plus the
-  local source name
-* `robot_name`: robot that produced this observation, if the source is mounted
-  on a robot. This can be empty for fixed sensors or synthetic map layers
+* `header`: global frame for the observation and its required, non-zero timestamp
+* `source_id`: stable source identifier, usually the robot namespace plus the local source name
+* `robot_name`: robot that produced this observation, if the source is mounted on a robot; this can be empty for fixed sensors or synthetic map layers
 * `map_name`: map or level that the observations belong to
-* `robot_pose`: pose of the robot-local observation frame in `header.frame_id`
-  when the observation was produced, so consumers do not need to reconstruct
-  it from a separate TF-like lookup
+* `robot_pose`: pose of the robot-local observation frame in `header.frame_id` when the observation was produced, so consumers do not need to reconstruct it from a separate TF-like lookup
 * `default_ttl_sec`: fallback TTL in seconds for patches from this source
 
 ## `MapRegionUpdate`
 
-[`MapRegionUpdate.msg`](../rmf_layered_map_msgs/msg/MapRegionUpdate.msg)
-describes one observation snapshot from a source.
+[`MapRegionUpdate.msg`](../rmf_layered_map_msgs/msg/MapRegionUpdate.msg) describes one observation snapshot from a source.
 
 Important fields:
 
 * `source`: metadata for the observation source
-* `reset_source`: remove active observations from the same `source_id` and
-  `map_name` before applying the new patches
+* `reset_source`: remove active observations from the same `source_id` and `map_name` before applying the new patches
 * `patches`: clear-space and occupied-space patches from this snapshot
 
-`reset_source` is useful when a source publishes replacement snapshots, changes
-maps, shuts down, or knows its previous observation state is no longer valid. It
-does not have a TTL because it is a bookkeeping operation, not an active map
-observation.
+`reset_source` is useful when a source publishes replacement snapshots, changes maps, shuts down, or knows its previous observation state is no longer valid. It does not have a TTL because it is a bookkeeping operation, not an active map observation.
 
 ## `MapRegionPatch`
 
-[`MapRegionPatch.msg`](../rmf_layered_map_msgs/msg/MapRegionPatch.msg)
-describes one group of regions with the same action and TTL.
+[`MapRegionPatch.msg`](../rmf_layered_map_msgs/msg/MapRegionPatch.msg) describes one group of regions with the same action and TTL.
 
 Patch types:
 
 * `UPDATE_CLEAR`: regions are temporary free space
 * `UPDATE_OBSTACLE`: regions are temporary occupied space
 
-Clear patches and obstacle patches both require a TTL because both describe
-temporary observations. If a patch TTL is zero or negative, the source
-`default_ttl_sec` is used. If that is also zero or negative, the map service's
-configured default TTL is used.
+Clear patches and obstacle patches both require a TTL because both describe temporary observations. If a patch TTL is zero or negative, the source `default_ttl_sec` is used. If that is also zero or negative, the map server's configured default TTL is used.
 
-When a sensor snapshot includes both clear and occupied regions, publish them in
-one `MapRegionUpdate` message. The map service applies clear patches before
-obstacle patches, which gives deterministic "clear then mark" behavior without
-relying on the arrival order of separate ROS messages.
+When a sensor snapshot includes both clear and occupied regions, publish them in one `MapRegionUpdate` message. The map server applies clear patches before obstacle patches, which gives deterministic "clear then mark" behavior without relying on the arrival order of separate ROS messages.
 
-The first prototype uses `rmf_prototype_msgs/Region` for sparse 2D geometry so
-robots can publish compact patches. Region coordinates are robot-local. The map
-service transforms them through `source.robot_pose` into
-`source.header.frame_id` before rasterizing them. Fixed sensors can publish
-sensor-local regions with their sensor pose, while synthetic sources whose
-regions are already global can use the identity pose. The first implementation
-accepts point and axis-aligned rectangle regions.
+The first prototype uses `rmf_prototype_msgs/Region` for sparse 2D geometry. Region coordinates are robot-local, and the map server transforms them through `source.robot_pose` into `source.header.frame_id` before rasterizing them. Fixed sensors can publish sensor-local regions with their sensor pose, while synthetic sources whose regions are already global can use the identity pose. The current implementation accepts point and axis-aligned rectangle regions.
+
+# Layered Map Server
+
+`rmf_layered_map_server` keeps the static occupancy grid separate from dynamic observations and publishes their composition on `/map`. It validates source timestamps and frames, ignores updates that are older than the latest accepted update from the same source, supports source resets, and removes observations after their TTL expires.
+
+The server applies clear patches before obstacle patches from the same update. During composition, obstacle observations win over clear observations so occupied space is not accidentally erased by another active source.
+
+# Three-Robot Nav2 Demo
+
+The committed Nav2 demo can be launched with:
+
+```bash
+ros2 launch rmf_layered_map_server_demo nav2_observations.launch.py
+```
+
+The launch file starts three stationary robots in different free corners of the warehouse and spawns one deterministic Gazebo box near each robot. Each observation node subscribes to its robot's local `sensor_msgs/LaserScan`, filters invalid or out-of-range returns, and publishes the remaining scan endpoints as point regions.
+
+Each scan is a replacement snapshot: `reset_source` removes the source's preceding points before the new points are added, and a short TTL removes the source if it stops publishing. The observation-frame pose is recorded in the shared `map` frame so the map server can transform the scan-local regions before rasterizing them.
+
+The demo launches Nav2 localization but does not launch Nav2 planning or control components, RMF planning, or navigation goals. Three robot-local RViz windows are enabled by default, and another RViz window displays the combined global `/map`.
+
+The scan-to-region conversion is deliberately simple so its information loss and publication cost are visible. `beam_stride` reduces the number of point regions, `publish_period_sec` throttles replacement snapshots, and `max_observation_range` limits represented returns. The current demo publishes occupied endpoints only; it does not convert raycast clearing into free-space regions or compress adjacent points into larger regions.
 
 # Example Flow
 
-A local costmap or LiDAR observation node can publish a replacement snapshot by:
+A local costmap, LiDAR, or other observation node can publish a replacement snapshot by:
 
-1. Stamping the observation source with the global frame and observation time,
-   and including the pose of the robot-local observation frame.
-2. Setting `reset_source` if the new snapshot replaces the source's previous
-   temporary observations.
+1. Stamping the observation source with the global frame and observation time, and including the pose of the robot-local observation frame.
+2. Setting `reset_source` if the new snapshot replaces the source's previous temporary observations.
 3. Adding one or more clear patches for free space seen by the sensor.
 4. Adding one or more obstacle patches for occupied space seen by the sensor.
-5. Giving each patch a TTL long enough to survive normal publication jitter but
-   short enough to decay when the observation is no longer refreshed.
+5. Giving each patch a TTL long enough to survive normal publication jitter but short enough to decay when the observation is no longer refreshed.
 
-The map service should ignore snapshots from a source if their timestamp is
-older than a newer snapshot that has already been accepted. This prevents a late
-clear/reset message from removing obstacle information that came from a newer
-observation.
+The map server ignores snapshots from a source if their timestamp is older than a newer snapshot that has already been accepted. This prevents a late clear or reset message from removing obstacle information that came from a newer observation.
 
 # Implemented Test Coverage
 
-The first server tests cover:
+The committed server and demo tests cover:
 
 * composing obstacle regions over a static planning grid
 * point regions with non-zero map origins and non-1.0 resolutions
 * transforming robot-local regions into the global map frame
 * out-of-bounds regions, malformed point arrays, and unsupported region types
-* rejecting updates without a timestamp
+* rejecting updates without a timestamp or in a different global frame
 * pruning expired observations by TTL
 * clear and obstacle patches in the same update
 * late older snapshots being ignored
 * reset updates removing observations from the same source and map
 * multiple robot sources being stitched into one composed grid
+* filtering invalid and out-of-range laser returns
+* preserving original beam angles when scan points are sampled

map_server/README.md

@@ -11,3 +11,13 @@ ros2 launch rmf_layered_map_server_demo demo.launch.py
 ```
 
 Use `use_rviz:=False` for a headless run.
+
+## Nav2 Observations
+
+The three-robot demo converts local laser observations into point regions and combines them into the global `/map`. It launches three robots in warehouse corners, deterministic clutter for each robot to observe, the layered map server, and a separate RViz window for the combined map. It does not launch RMF or Nav2 planning components.
+
+```bash
+ros2 launch rmf_layered_map_server_demo nav2_observations.launch.py
+```
+
+See [`rmf_layered_map_server_demo/README.md`](rmf_layered_map_server_demo/README.md) for launch arguments and the current scan-to-region limitations.

map_server/rmf_layered_map_server/README.md

@@ -12,19 +12,9 @@ Default topics:
 
 Dynamic observations expire according to their TTL, so transient local obstacles do not remain in the global planning map forever. A LiDAR or local costmap observer can keep refreshing an obstacle while it is still seen, then let the server decay it after the TTL.
 
-`MapRegionUpdate` messages contain a list of `MapRegionPatch` entries. A sensor
-snapshot that clears freespace and marks obstacles can publish clear and obstacle
-patches in the same message. The server applies clear patches before obstacle
-patches. If the snapshot replaces the source's previous observation state, set
-`reset_source` so the server removes old observations from that `source_id` and
-`map_name` before adding the new patches. Resetting has no TTL. Clear and
-obstacle patches both use TTLs in seconds.
-
-Patch regions are expressed in the robot-local observation frame. The server
-uses `source.robot_pose` to transform them into `source.header.frame_id`, which
-must match the static occupancy grid frame. Updates need a non-zero source
-timestamp. The current implementation accepts point and axis-aligned rectangle
-regions. It logs and ignores other region types.
+`MapRegionUpdate` messages contain a list of `MapRegionPatch` entries. A sensor snapshot that clears free space and marks obstacles can publish clear and obstacle patches in the same message. The server applies clear patches before obstacle patches. If the snapshot replaces the source's previous observation state, set `reset_source` so the server removes old observations from that `source_id` and `map_name` before adding the new patches. Resetting has no TTL. Clear and obstacle patches both use TTLs in seconds.
+
+Patch regions are expressed in the robot-local observation frame. The server uses `source.robot_pose` to transform them into `source.header.frame_id`, which must match the static occupancy grid frame. Updates need a non-zero source timestamp. The current implementation accepts point and axis-aligned rectangle regions. It logs and ignores other region types.
 
 ## Visualization Smoke Test
 
@@ -43,3 +33,13 @@ ros2 launch rmf_layered_map_server_demo demo.launch.py
 ```
 
 The launch file starts RViz with a `Map` display on `/map` and the fixed frame set to `map`. The demo publisher sends a bordered static map and a temporary obstacle region with a 5 second TTL. The obstacle should appear in the composed map and then disappear when the TTL expires.
+
+## Nav2 Observation Demo
+
+To combine observations from three Nav2 robots without starting RMF or Nav2 planning, launch:
+
+```bash
+ros2 launch rmf_layered_map_server_demo nav2_observations.launch.py
+```
+
+Each robot converts valid laser endpoints into point regions. A separate RViz window displays the composed `/map`; see the demo package README for the fidelity and publication-rate tuning arguments.

map_server/rmf_layered_map_server_demo/README.md

@@ -0,0 +1,34 @@
+# Layered Map Server Demos
+
+This package contains two demonstrations of the layered map server.
+
+## TTL Smoke Test
+
+The small smoke test publishes a synthetic static grid and a temporary rectangle with a five-second TTL:
+
+```bash
+ros2 launch rmf_layered_map_server_demo demo.launch.py
+```
+
+## Three-Robot Nav2 Observation Demo
+
+The Nav2 demo starts three stationary robots in free corners of the warehouse map and spawns one deterministic box near each robot. Each robot's observation node subscribes to its `sensor_msgs/LaserScan`, represents valid scan endpoints as point `Region` messages, and publishes a replacing `MapRegionUpdate` snapshot. The layered map server transforms and combines all three sources over the static map.
+
+No RMF planning components or navigation goals are required. By default the Nav2 launch opens three robot-local RViz windows, and the demo opens another RViz window showing the combined `/map`:
+
+```bash
+ros2 launch rmf_layered_map_server_demo nav2_observations.launch.py
+```
+
+Use `use_nav2_rviz:=False` to open only the combined-map view. Use `spawn_clutter:=False` to run against the unmodified warehouse world.
+
+The initial implementation deliberately keeps the scan-to-region conversion simple so its cost and information loss are visible. `beam_stride` samples fewer endpoints, `publish_period_sec` throttles snapshots, `max_observation_range` limits represented returns, and `ttl_sec` controls how quickly stale snapshots expire. For example:
+
+```bash
+ros2 launch rmf_layered_map_server_demo nav2_observations.launch.py \
+  beam_stride:=4 publish_period_sec:=1.0
+```
+
+Each publisher logs the number of input beams and output regions. This makes it possible to compare message density and global-map update rate against the visual fidelity in RViz.
+
+The prototype publishes occupied endpoints only. It does not yet turn clearing rays into free-space regions or compress adjacent endpoints into larger region primitives. `reset_source` removes the previous snapshot before each new scan, and TTL expiry removes observations if a robot stops publishing.