[skip ci] publish latest

Signed-off-by: fmrico <fmrico@gmail.com>

Author: fmrico

_sources/index.rst.txt

@@ -44,4 +44,5 @@ If you use this software in your work, please consider citing our next paper.
    getting_started/index.rst
    design/index.rst
    software/index.rst
+   tutorials/index.rst
    about/index.rst

_sources/software/blackboard.rst.txt

@@ -0,0 +1,137 @@
+.. _blackboard:
+
+How to use the NavState BlackBoard
+##################################
+
+The `NavState` class is a central component in the EasyNav architecture. It implements a **shared blackboard**, which allows all modules (localizers, planners, controllers, etc.) to **read and write shared data without using ROS 2 communication mechanisms** internally. This design improves **determinism**, simplifies debugging, and avoids unnecessary overhead.
+
+Overview
+--------
+
+All information needed or produced by EasyNav modules flows through the `NavState`. Examples include:
+
+- the robot's estimated pose (`robot_pose`),
+- a list of navigation goals (`goals`),
+- a path to follow (`path`),
+- environment maps (e.g., `map`, `map.dynamic`, `map.static`),
+- control commands (`cmd_vel`),
+- perception data (`points`, `image`, etc.).
+
+The `NavState` provides a simple API to check for, retrieve, and update entries using keys.
+
+Basic API
+---------
+
+To **check whether a value is available**, use:
+
+.. code-block:: cpp
+
+   if (nav_state.has("robot_pose")) {
+     // do something
+   }
+
+To **read a value**, use the templated `get` method:
+
+.. code-block:: cpp
+
+   const auto odom = nav_state.get<nav_msgs::msg::Odometry>("robot_pose");
+
+To **write a value**, use:
+
+.. code-block:: cpp
+
+   nav_state.set("cmd_vel", computed_twist);
+
+Values are stored under a string key and must be copyable. You can store standard ROS messages, custom types, or even nested structures. Keys can use dot notation (e.g., `"map.static"`, `"map.dynamic"`).
+
+Examples from Plugins
+---------------------
+
+**Planner Example**
+
+A planner typically requires the robot’s pose, a goal, and a map. It writes back a path:
+
+.. code-block:: cpp
+
+   if (!nav_state.has("robot_pose") || !nav_state.has("goals") || !nav_state.has("map")) return;
+
+   auto pose = nav_state.get<nav_msgs::msg::Odometry>("robot_pose");
+   auto goal = nav_state.get<nav_msgs::msg::Goals>("goals").goals.front().pose;
+   auto map = nav_state.get<grid_map::GridMap>("map");
+
+   auto path = compute_path(map, pose.pose.pose, goal);
+
+   nav_state.set("path", path);
+
+**Controller Example**
+
+A controller reads the current pose and planned path, and outputs a velocity command:
+
+.. code-block:: cpp
+
+   if (!nav_state.has("path") || !nav_state.has("robot_pose")) return;
+
+   const auto path = nav_state.get<nav_msgs::msg::Path>("path");
+   const auto pose = nav_state.get<nav_msgs::msg::Odometry>("robot_pose").pose.pose;
+
+   geometry_msgs::msg::TwistStamped cmd_vel = compute_control(path, pose);
+
+   nav_state.set("cmd_vel", cmd_vel);
+
+**Localization Example**
+
+A localizer typically updates the estimated pose:
+
+.. code-block:: cpp
+
+   nav_state.set("robot_pose", latest_odom);
+
+Advanced Features
+-----------------
+
+**Namespacing**
+
+You can organize data hierarchically by using dots in keys:
+
+- `"map.static"` vs `"map.dynamic"`
+- `"perception.lidar"` vs `"perception.camera"`
+
+**Debugging**
+
+You can inspect the contents of the blackboard as a string:
+
+.. code-block:: cpp
+
+   std::cout << nav_state.debug_string();
+
+**Custom Printers**
+
+You can register pretty-printers for your own types using:
+
+.. code-block:: cpp
+
+   NavState::register_printer<MyType>(
+     [](const MyType & value) {
+       std::ostringstream out;
+       out << "MyType: " << value.to_string();
+       return out.str();
+     });
+
+This improves the output of `debug_string()` for non-standard types.
+
+Best Practices
+--------------
+
+- Always check `has(key)` before `get<T>(key)` to avoid exceptions.
+- Use descriptive keys, preferably documented.
+- When designing a plugin, clearly define which `NavState` keys it consumes and which ones it produces.
+- Avoid storing large or non-copyable data unless necessary.
+
+Conclusion
+----------
+
+The `NavState` blackboard is a powerful and lightweight alternative to traditional ROS 2 message passing. It simplifies integration between modules and improves runtime performance by avoiding queues and callback latencies.
+
+It is the recommended mechanism for **all internal data exchange** in EasyNav.
+
+

_sources/software/index.rst.txt

@@ -5,6 +5,26 @@ EasyNav Software
 
 The EasyNav software is developed under the `EasyNavigation GitHub organization <https://github.com/EasyNavigation>`_, and it follows a **highly modular structure**. This modularity is reflected in the separation of functionality across multiple repositories, each dedicated to a specific role or typology:
 
+
+C++ API
+*******
+
+- `EasyNav Core <https://easynavigation.github.io/EasyNavigation/>`_
+- `EasyNav Simple Stack <https://easynavigation.github.io/easynav_simple_stack/>`_
+- `EasyNav GridMap Stack <https://easynavigation.github.io/easynav_gridmap_stack/>`_
+
+**HowTo's**:
+
+.. toctree::
+   :maxdepth: 1
+
+   ./blackboard.rst
+   ./perceptions.rst
+
+
+Repositories
+************
+
 Core
 ----
 

_sources/software/perceptions.rst.txt

@@ -0,0 +1,158 @@
+.. _perceptions:
+
+
+Sensor Input and Perception Handling
+####################################
+
+In EasyNav, **all sensor input flows through a single component**: the ``SensorsNode``. This node is responsible for:
+
+- subscribing to sensor topics defined in the parameter file,
+- converting sensor data into unified internal formats (e.g., point clouds, images),
+- organizing and storing perceptions into groups (e.g., `"points"`, `"image"`),
+- publishing a fused view (optional),
+- writing the current valid perceptions into the `NavState` under their corresponding group key.
+
+Sensor Configuration
+--------------------
+
+Sensors are defined via ROS 2 parameters under the `sensors_node` configuration. For example:
+
+.. code-block:: yaml
+
+   sensors_node:
+     ros__parameters:
+       use_sim_time: true
+       forget_time: 0.5
+       sensors: [laser1, camera1]
+       perception_default_frame: odom
+       laser1:
+         topic: /scan_raw
+         type: sensor_msgs/msg/LaserScan
+         group: points
+       camera1:
+         topic: /rgbd_camera/points
+         type: sensor_msgs/msg/PointCloud2
+         group: points
+
+All distance sensors (e.g., `LaserScan`, `PointCloud2`) must be grouped under the `"points"` group. These are converted internally into **`PointPerception`** instances and aggregated into a single structure called **`PointPerceptions`**, which is written into the `NavState` under the key `"points"`.
+
+If image data is included:
+
+.. code-block:: yaml
+
+   image1:
+     topic: /rgbd_camera/image_raw
+     type: sensor_msgs/msg/Image
+     group: image
+
+Then the group `"image"` will appear in the `NavState`, using the `ImagePerception` type.
+
+Processing Point Perceptions
+----------------------------
+
+To work with fused or filtered 3D points, EasyNav provides the utility class **`PointPerceptionsOpsView`**.
+
+You typically retrieve the `PointPerceptions` from the `NavState`:
+
+.. code-block:: cpp
+
+   if (!nav_state.has("points")) return;
+   const auto perceptions = nav_state.get<PointPerceptions>("points");
+
+Then create an operations view:
+
+.. code-block:: cpp
+
+   PointPerceptionsOpsView view(perceptions);
+
+The view provides a fluent interface to manipulate the point cloud. There are two kinds of operations:
+
+- **Lightweight operations**: these return a reference (`PointPerceptionsOpsView &`) and operate on views without copying data.
+- **Heavyweight operations**: these return a `std::shared_ptr<PointPerceptionsOpsView>` and typically involve transformations or filtering that produce new point sets.
+
+Common operations include:
+
+.. code-block:: cpp
+
+   auto downsampled = PointPerceptionsOpsView(perceptions)
+     .downsample(0.2);  // reduce density (heavy)
+
+   auto fused = downsampled
+     ->fuse("base_link");  // transform all points to base_link (heavy)
+
+   auto filtered = fused
+     ->filter({-1.0, -1.0, 0.0}, {1.0, 1.0, 2.0});  // spatial crop (heavy)
+
+   auto points = filtered->as_points();  // retrieve std::vector<Point3D>
+
+Operation Summary
+-----------------
+
++--------------------+----------------------------+------------------------------------------+
+| Operation          | Return Type                | Description                              |
++====================+============================+==========================================+
+| `filter(...)`      | `std::shared_ptr<...>`     | Filters points inside a bounding box     |
++--------------------+----------------------------+------------------------------------------+
+| `downsample(res)`  | `std::shared_ptr<...>`     | Voxel downsampling                       |
++--------------------+----------------------------+------------------------------------------+
+| `fuse(frame)`      | `std::shared_ptr<...>`     | Transforms all perceptions to a frame    |
++--------------------+----------------------------+------------------------------------------+
+| `collapse()`       | `std::shared_ptr<...>`     | Merge similar points into one            |
++--------------------+----------------------------+------------------------------------------+
+| `as_points()`      | `std::vector<Point3D>`     | Exports data as raw 3D point list        |
++--------------------+----------------------------+------------------------------------------+
+
+Example: Updating a Map
+-----------------------
+
+Many components use fused and filtered points to update occupancy or elevation maps:
+
+.. code-block:: cpp
+
+   const auto perceptions = nav_state.get<PointPerceptions>("points");
+
+   auto fused = PointPerceptionsOpsView(perceptions)
+     .downsample(dynamic_map_.resolution())  // reduce point density
+     .fuse("map")                             // transform to map frame
+     ->filter({NAN, NAN, 0.1}, {NAN, NAN, NAN})  // ignore ground clutter
+     .as_points();
+
+   for (const auto & p : fused) {
+     if (dynamic_map_.check_bounds_metric(p.x, p.y)) {
+       auto [cx, cy] = dynamic_map_.metric_to_cell(p.x, p.y);
+       dynamic_map_.at(cx, cy) = 1;
+     }
+   }
+
+Fused Visualization
+-------------------
+
+If the `SensorsNode` has subscribers on its output topic, it will publish the fused perception result after processing:
+
+.. code-block:: cpp
+
+   if (percept_pub_->get_subscription_count() > 0) {
+     auto fused = PointPerceptionsOpsView(perceptions)
+       .fuse(perception_default_frame_);
+
+     auto fused_points = fused->as_points();
+     auto msg = points_to_rosmsg(fused_points);
+
+     msg.header.frame_id = perception_default_frame_;
+     msg.header.stamp = fused->get_perceptions()[0]->stamp;
+     percept_pub_->publish(msg);
+   }
+
+Extending to Other Modalities
+-----------------------------
+
+In addition to `"points"` and `"image"`, developers can add new groups and corresponding `PerceptionBase`-derived classes. All perceptions:
+
+- inherit from `PerceptionBase`,
+- have a `stamp`, `frame_id`, and `valid` flag,
+- are grouped by semantic label (e.g., `"points"`),
+- are automatically managed by the `SensorsNode`.
+
+---
+
+This unified and extensible perception handling design allows plugins to focus on **what** data they need, not **how** it was acquired, filtered, or transformed.