[#1385] support shallow camera image payload change recording

Author: schaubh

docs/source/Learn/bskPrinciples/bskPrinciples-4.rst

@@ -61,7 +61,7 @@ The recorder can also be configured to record only when the message payload cont
 
 To turn off this mode use ``scRec.recordOnChange(False)``.  The default argument of this method is ``True``.
 
-This change-only mode is only available for message payload types that support field-wise equality comparison.  Basilisk generates this support for payloads whose fields can be compared directly.  If a payload contains an unknown field type, or a pointer field that cannot be compared safely, then ``recordOnChange()`` emits an error instead of silently falling back to normal interval recording.  Use the regular recorder mode for these payloads, or add a ``PayloadEqualityTraits`` specialization when the payload can be compared safely.
+This change-only mode is only available for message payload types that support field-wise equality comparison.  Basilisk generates this support for payloads whose fields can be compared directly.  If a payload contains an unknown field type, or a pointer field without explicit comparison semantics, then ``recordOnChange()`` emits an error instead of silently falling back to normal interval recording.  Use the regular recorder mode for these payloads, or add a ``PayloadEqualityTraits`` specialization only when the payload comparison behavior can be defined safely.  For example, ``CameraImageMsgPayload`` supports change-only recording through a shallow metadata comparison.  Its image pointer is compared by address, but the pointed-to image buffer is not deep-copied or compared by the recorder.
 
 That is all that is required to set up message recording.  Next the code initializes the simulation and executes it.
 

docs/source/Support/bskReleaseNotesSnippets/recorder-update-time-interval.rst

@@ -1,3 +1,4 @@
 - Updated message recorders so ``updateTimeInterval()`` reschedules the next recording opportunity when the minimum update time is changed between simulation runs.
 - Added a message recorder mode to record only when message payload content changes after the minimum update time has elapsed.
 - Added explicit errors when change-only recording is requested for payload types without supported equality comparison.
+- Added shallow metadata comparison support for ``CameraImageMsgPayload`` without comparing pointed-to image bytes.

src/architecture/messaging/_UnitTest/test_RecorderUpdateTimeInterval.py

@@ -177,61 +177,70 @@ def test_record_on_change_unsupported_payload():
 
 
 def test_record_on_change_camera_image_payload():
-    """CameraImageMsgPayload has a hand-written PayloadEqualityTraits specialization.
+    """Test CameraImageMsgPayload change-only recording with shallow metadata equality.
 
-    recordOnChange() should only store a frame when the scalar fields differ from the
-    last recorded payload. imagePointer is left null here, so equality reduces to
-    comparing timeTag, valid, cameraID, imageType, and imageBufferLength.
+    CameraImageMsgPayload equality compares payload fields, including the image
+    pointer address, but it does not compare the pointed-to image bytes.
     """
 
     sc_sim = SimulationBaseClass.SimBaseClass()
     sim_process = sc_sim.CreateNewProcess("testProcess")
-    sim_process.addTask(sc_sim.CreateNewTask("testTask", macros.sec2nano(1.0)))
+
+    task_time = macros.sec2nano(1.0)  # [ns]
+    sim_process.addTask(sc_sim.CreateNewTask("testTask", task_time))
 
     test_module = ChangingCameraModule()
     sc_sim.AddModelToTask("testTask", test_module)
 
-    minimum_record_time = macros.sec2nano(4.0)
+    minimum_record_time = macros.sec2nano(4.0)  # [ns]
     msg_recorder = test_module.cameraOutMsg.recorder(minimum_record_time)
     msg_recorder.recordOnChange()
     sc_sim.AddModelToTask("testTask", msg_recorder)
 
     sc_sim.InitializeSimulation()
-    sc_sim.ConfigureStopTime(macros.sec2nano(10.0))
+
+    final_stop_time = macros.sec2nano(10.0)  # [ns]
+    sc_sim.ConfigureStopTime(final_stop_time)
     sc_sim.ExecuteSimulation()
 
-    # cameraID changes at t = 5 s. With a 4 s minimum interval:
-    #   t = 0: recorded (cameraID = 0), next eligible = t = 4 s
-    #   t = 4: payload unchanged → skipped,  next eligible = t = 8 s
-    #   t = 8: payload changed (cameraID = 1) → recorded
+    first_record_time = macros.sec2nano(0.0)  # [ns]
+    first_eligible_change_time = macros.sec2nano(8.0)  # [ns]
     expected_times = np.array([
+        first_record_time,
+        first_eligible_change_time,
+    ])  # [ns]
+    expected_time_tags = np.array([
         macros.sec2nano(0.0),
-        macros.sec2nano(8.0),
-    ])
-    expected_camera_ids = np.array([0, 1])
+        test_module.image_time_tag,
+    ])  # [ns]
 
     np.testing.assert_array_equal(msg_recorder.times(), expected_times)
-    np.testing.assert_array_equal(msg_recorder.cameraID, expected_camera_ids)
+    np.testing.assert_array_equal(msg_recorder.timeTag, expected_time_tags)
 
 
 class ChangingCameraModule(sysModel.SysModel):
-    """Write a CameraImageMsgPayload whose cameraID steps up at a fixed simulation time."""
+    """Write a CameraImageMsgPayload whose metadata changes at a fixed time."""
 
     def __init__(self):
         super().__init__()
         self.cameraOutMsg = messaging.CameraImageMsg()
-        self.change_time = macros.sec2nano(5.0)
+        self.change_time = macros.sec2nano(5.0)  # [ns]
+        self.image_time_tag = macros.sec2nano(5.0)  # [ns]
 
     def Reset(self, CurrentSimNanos):
-        self._write(CurrentSimNanos)
+        self.write_payload(CurrentSimNanos)
 
     def UpdateState(self, CurrentSimNanos):
-        self._write(CurrentSimNanos)
+        self.write_payload(CurrentSimNanos)
 
-    def _write(self, CurrentSimNanos):
+    def write_payload(self, CurrentSimNanos):
         payload = self.cameraOutMsg.zeroMsgPayload
-        payload.cameraID = 1 if CurrentSimNanos >= self.change_time else 0
         payload.valid = 1
+        payload.cameraID = 7
+        payload.imageBufferLength = 10  # [bytes]
+        payload.imageType = 1
+        if CurrentSimNanos >= self.change_time:
+            payload.timeTag = self.image_time_tag
         self.cameraOutMsg.write(payload, CurrentSimNanos, self.moduleID)
 
 

src/architecture/messaging/msgAutoSource/generatePayloadEqualityHeader.py

@@ -163,5 +163,6 @@ def generateEqualityHeader(meta: dict, payloadType: str, searchDir: str) -> str
                 "// one or more fields have unsupported types (e.g., raw pointers).\n"
                 "// To support recordOnChange() for this payload, add a manual\n"
                 f"// PayloadEqualityTraits<{payloadTypeName}> specialization\n"
-                "// in the payload header file, guarded by #ifdef __cplusplus.\n"
+                "// in the payload header file, guarded by #ifdef __cplusplus, only\n"
+                "// when the comparison semantics can be defined safely.\n"
             )

src/architecture/messaging/payloadEqualityTraits.h

@@ -24,7 +24,7 @@ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  *  To enable recordOnChange() for a payload type, provide a specialization either:
  *   - automatically, via generatePayloadEqualityHeader.py (for fully-supported struct fields), or
  *   - manually, as a PayloadEqualityTraits<T> specialization in the payload header file
- *     (guarded by \#ifdef __cplusplus).
+ *     (guarded by \#ifdef __cplusplus) when the comparison semantics can be defined safely.
  */
 template<typename T>
 struct PayloadEqualityTraits {

src/architecture/msgPayloadDefC/CameraImageMsgPayload.h

@@ -36,24 +36,30 @@ typedef struct {
     int8_t imageType;         //!< -- Number of channels in each pixel, RGB = 3, RGBA = 4
 }CameraImageMsgPayload;
 
-#ifdef __cplusplus
-#include <cstring>
+#if defined(__cplusplus) && !defined(SWIG)
 #include "architecture/messaging/payloadEqualityTraits.h"
 
+/*! @brief Enable shallow payload equality for CameraImageMsgPayload.
+ *
+ * The image pointer is compared by address only.  The recorder stores this
+ * payload structure, but it does not deep-copy or compare the pointed-to image
+ * buffer.  Thus, recordOnChange() detects changes in image metadata, such as
+ * timeTag, cameraID, imageBufferLength, imageType, valid, or imagePointer
+ * address, but it does not detect in-place changes to image bytes behind a
+ * reused imagePointer.
+ */
 template<>
 struct PayloadEqualityTraits<CameraImageMsgPayload> {
     static constexpr bool supported = true;
     static bool equal(const CameraImageMsgPayload& lhs, const CameraImageMsgPayload& rhs) {
-        if (lhs.timeTag != rhs.timeTag)                     return false;
-        if (lhs.valid != rhs.valid)                         return false;
-        if (lhs.cameraID != rhs.cameraID)                   return false;
-        if (lhs.imageType != rhs.imageType)                 return false;
-        if (lhs.imageBufferLength != rhs.imageBufferLength) return false;
-        if (lhs.imagePointer == rhs.imagePointer)           return true;
-        if (!lhs.imagePointer || !rhs.imagePointer)         return false;
-        return std::memcmp(lhs.imagePointer, rhs.imagePointer, lhs.imageBufferLength) == 0;
+        return lhs.timeTag == rhs.timeTag
+            && lhs.valid == rhs.valid
+            && lhs.cameraID == rhs.cameraID
+            && lhs.imagePointer == rhs.imagePointer
+            && lhs.imageBufferLength == rhs.imageBufferLength
+            && lhs.imageType == rhs.imageType;
     }
 };
-#endif /* __cplusplus */
+#endif /* defined(__cplusplus) && !defined(SWIG) */
 
 #endif