Merge pull request #440 from csiro-internal/bugfix/roi-and-docs

Minor bugfixes and docs update

Updated merged submodule and changelog. Rod approved over slack.

Author: aluu-csiro

docs/user/Alignment.md

@@ -5,16 +5,16 @@ The use cases are as follows:
 - FA position: arbitrary or from Spatial Fuel Map.
 - Align to: nothing, centre of geometry or centre of collimation.
 
-First, the position of the FA to go to is either arbitrary (as in: `Go to FA by pose` when `Spatial Fuel Map` is unchecked; `ROI - Square Grid`) or retrieved from the Spatial Fuel Map (as in: `Go to FA by index`; `Go to FA by pose` when `Spatial Fuel Map` is checked; `ROI - List`). Based on these, the following topics are published:
+First, the position of the FA to go to is either arbitrary (as in: `Go to FA by pose` when `Spatial Fuel Map` is unchecked; `ROI - Square Grid`) or retrieved from the Spatial Fuel Map (as in: `Go to FA by index`; `Go to FA by pose` when `Spatial Fuel Map` is checked; `ROI - List`). Regardless of what it's based on, this is the target's expected position. Based on these, the following topics are published:
 
 - `/rcvd/target_fa/index` (`std_msgs/String`): If FA is in Spatial Fuel Map, this is the index. Otherwise, this starts with `closest`.
 - `/rcvd/target_fa/position` (`geometry_msgs/PointStamped`): If FA is in Spatial Fuel Map and this is not provided it is retrieved from SFM. Otherwise, this is the arbitrary position that an FA is expected to be found at.
 
-At the same time, the target position is given as a goal to the local path planning system via the topic `/rcvd/local_goal` (`rasg_nav_msgs/LocalNavigationGoal`). The RCVD moves toward the target position.
+At the same time, the target's expected position is given as a goal to the local path planning system via the topic `/rcvd/local_goal` (`rasg_nav_msgs/LocalNavigationGoal`). The RCVD moves toward the target position.
 
 The alignment target is published to `/rcvd/target_fa/align_to` (`std_msgs/String`).
 
-If the RCVD has not been requested to align to anything (`Align to` is `Nothing`) then once it reaches the target position, it is complete.
+If the RCVD has not been requested to align to anything (`Align to` is `Nothing`) then once it reaches the target's expected position, it is complete.
 
 If the RCVD has been requested to align to the centre of geometry or collimation, then the Computer Vision (CV) system will try to find the target FA within the Optical Payload image. This is performed by:
 
@@ -24,7 +24,7 @@ If the RCVD has been requested to align to the centre of geometry or collimation
 
 Locating the grid cell containing the target position is performed by using the following information to transform the target position in metres from the fixed `map` frame into a position in pixels in the `cvd` frame. The following information is used for this:
 
-- Target position (relative to `map` frame).
+- Target expected position (relative to `map` frame).
 - Global SLAM (pose of `odom` frame origin relative to `map` frame).
 - Local SLAM (pose of `slam_base_link` frame origin relative to `odom` frame).
 - Optical Payload pose in CV configuration (pose of `cvd` frame origin relative to `slam_base_link` frame).
@@ -37,4 +37,18 @@ Once the target FA has been located within the Optical Payload image, the positi
 
 This position is published to the topic `/rcvd/align_feedback` (`rcvd_msgs/AlignFeedback`).
 
-After the alignment feedback has started to be published, the local path planner will switch to a mode where it uses the feedback to align to the target. Once the magnitude of the feedback has stayed below the required value for the required duration, it is complete.
+Once the alignment feedback has started to be published, the local path planner will switch to a mode where it uses the feedback to align to the target. Once the magnitude of the feedback has stayed below the required value for the required duration, it is complete.
+
+## Success on completing the target
+
+Regardless of alignment method, the RCVD has to meet both autonomy thresholds and alignment thresholds to succeed. These are all configured in `Settings > Autonomy`, `Settings > Autonomy - Thresholds/Distances`, `Settings > Autonomy - Timeouts`.
+
+The alignment thresholds are time based.
+
+If the RCVD has been requested to align to nothing, then the goal position is successful when:
+
+- `Settings > Autonomy > Required aligned duration`
+
+If the RCVD has been requested to align to geometry or collimation, then the goal position is successful when:
+
+- `Settings > Autonomy > Max time between alignment`

docs/user/CV.md

@@ -7,6 +7,8 @@ Primarily, CV is used when aligning to the centre of collimation.
 
 ## <a href="#parameters" id="parameters" name="parameters">Parameters</a>
 
+What these parameters mean and how to configure them in a real deployment is outlined in [Tuning.md](./Tuning.md).
+
 <!-- prettier-ignore-start -->
 
 | Parameter                      | Olkiluoto/2022-08 | Olkiluoto/2022-08 | QCAT/2025-03 | Unknown/2022-11 |
@@ -29,6 +31,22 @@ Primarily, CV is used when aligning to the centre of collimation.
 | Luminosity filter size (px)    |   100           |
 | Pixel size (m)                 |   0.00046       |
 
+**The values below are not to be used in a real deployment.**
+
+Below are records of CV parameters that are only relevant for testing at CSIRO with fiducial markers.
+Grid detection is not used, so grid buffer, grid padding and grid size settings are irrelevant.
+FA size and pixel size are the only two that matter in this setup.
+
+| Parameter                      | big-tags     | small-tags   |
+|-------------------------------:|:-------------|:-------------|
+| FA size (m)                    |   0.06500    |   0.03000    |
+| FA grid buffer (m)             |   0.00450    |   0.00450    |
+| FA grid padding (m)            |   0.01500    |   0.01500    |
+| FA grid size (m)               |   0.12000    |   0.12000    |
+| Luminosity filter padding (px) |   5          |   5          |
+| Luminosity filter size (px)    |   100        |   100        |
+| Pixel size (m)                 |   0.00017    |   0.00017    |
+
 <!-- prettier-ignore-end -->
 
 ## <a href="#visualisations" id="visualisations" name="visualisations">Visualisations</a>

src/CHANGELOG.md

@@ -22,10 +22,14 @@ This file is to document the high level changes to the RCVD project from release
 ### Changed
 
 - Updated `session.py` to forward `fa_size` and `pixel_size` to two topics, CV (original) and camerafirmware (new).
+- Updated `docs/user/Alignment.md` and `docs/user/CV.md`.
+- Throttles logging output from `HeightmapToCostmap.cpp`.
 
 ### Fixed
 
 - Fixed bug where `slamcomms.cpp` was only writing x values for `slam_orientation_euler_scaled`.
+- Fixed bug where GoToFA commands would trigger trying to update ROI progress.
+- Fixed mistake in log output about ROI Square Grid minimum number of indices.
 
 ## 1.18.13 - 2026-04-14
 

src/heightmap_to_costmap

@@ -322,6 +322,11 @@ bool ROI::resetSquareGrid(const Config & config, const rcvd_msgs::Command & comm
 
 void ROI::onAlignFeedback(const rcvd_msgs::AlignFeedback & align_feedback)
 {
+  // Only update if ROI is active
+  if (!is_active_) {
+    return;
+  }
+
   if (
     (roi_ != nullptr) && align_feedback.target_fa.has_index &&
     (align_feedback.target_fa.align_to.data == align_to_)) {

src/rcvd_executive/src/ROI.cpp

@@ -84,6 +84,10 @@ class Config(rcvd_csiro_py.Config):
             "debug", default=True, type=bool, help="Execute debug functionality?"
         )
 
+        # NOTE: fiducial_cv_node does not use grid detection, so grid_buffer, grid_pad and
+        # grid_size are all irrelevant in this configuration. it's fa_size and pixel_size that
+        # are significant for testing @ CSIRO
+
         # fmt: off
         yield rcvd_csiro_py.Parameter("base_link_frame_id", default="base_link", type=str, help="Dynamic RCVD tf frame id.")
         yield rcvd_csiro_py.Parameter("collimation_offset_mean", default=0.01, type=float, help="Offset from FA position to centre of collimation (mean).")
@@ -760,6 +764,8 @@ class Node:
         # Annotate command type
         self.__vis_img_texts.append("Command type: {}".format(self.__check_command_type()))
 
+        # NOTE: fiducial_cv_node does not do grid detection
+
         # Get expected centre of target FA
         target_fa_position_in_image = map_to_image(
             rcvd_csiro_py.Vec3(target_fa_position_in_map.x, target_fa_position_in_map.y, 0.0)