Merge branch 'main' into feat/toolbox-remove-data-source

Author: facontidavide

docs/builtin_type.md

@@ -150,6 +150,7 @@ messages.
 | `anchor` | `BufferAnchor` | Keeps `data` alive when it references shared storage. |
 | `compressed_depth_min` | `std::optional<float>` | ROS compressed-depth quantization metadata, when present. |
 | `compressed_depth_max` | `std::optional<float>` | ROS compressed-depth quantization metadata, when present. |
+| `frame_id` | `std::string` | Source coordinate frame (ROS `sensor_msgs/Image` and `foxglove.CompressedImage` both carry it). Lets a consumer match the image to the `CameraInfo` of the same `frame_id` (calibration / native resolution), e.g. to rectify lens distortion so 2D annotations align with the image. Empty when the producer has no frame information. |
 
 Common raw encodings are `rgb8`, `rgba8`, `bgr8`, `bgra8`, `mono8`, and
 `mono16`. Common compressed encodings are `jpeg`, `png`, and `qoi`.

pj_base/include/pj_base/builtin/image.hpp

@@ -150,6 +150,13 @@ struct Image {
   std::optional<float> compressed_depth_max;
 
   Timestamp timestamp_ns = 0;
+
+  /// Source coordinate frame (ROS sensor_msgs/Image and foxglove.CompressedImage
+  /// both carry it). Lets a consumer match the image to the CameraInfo of the same
+  /// frame_id (calibration / native resolution), e.g. to rectify lens distortion so
+  /// 2D annotations align with the image. Empty when the producer has no frame
+  /// information.
+  std::string frame_id;
 };
 
 }  // namespace sdk

pj_base/proto/pj/Image.proto

@@ -57,4 +57,9 @@ message Image {
   // ROS compressedDepth quantization maximum; set together with `compressed_depth_min` when `encoding ==
   // "compressedDepth"`.
   optional float compressed_depth_max = 9;
+
+  // Source coordinate frame (ROS sensor_msgs/Image, foxglove.CompressedImage). Lets a consumer match the image to the
+  // CameraInfo of the same frame_id (calibration / native resolution), e.g. to rectify lens distortion so 2D
+  // annotations align with the image. Empty when the producer has no frame information.
+  string frame_id = 10;
 }

pj_base/src/builtin/image_codec.cpp

@@ -53,6 +53,7 @@ std::vector<uint8_t> serializeImage(const Image& image) {
   if (image.compressed_depth_max.has_value()) {
     writer.floatField(9, *image.compressed_depth_max);
   }
+  writer.string(10, image.frame_id);
 
   return out;
 }
@@ -139,6 +140,8 @@ Expected<sdk::Image> deserializeImage(const uint8_t* data, size_t size) {
         image.compressed_depth_max = v;
         return true;
       }
+      case 10:
+        return tag.type == WireType::kLengthDelimited && r.readString(image.frame_id);
       default:
         return false;
     }

pj_base/tests/image_codec_test.cpp

@@ -33,6 +33,7 @@ TEST(ImageCodecTest, RoundTripRawRGB8) {
   in.encoding = "rgb8";
   in.row_step = 6;  // 2 px * 3 bytes
   in.is_bigendian = false;
+  in.frame_id = "camera_front";
   const std::vector<uint8_t> pixels = {255, 0, 0, 0, 255, 0, 0, 0, 255, 128, 128, 128};
   in.data = Span<const uint8_t>(pixels.data(), pixels.size());
 
@@ -45,6 +46,7 @@ TEST(ImageCodecTest, RoundTripRawRGB8) {
   EXPECT_EQ(out->encoding, in.encoding);
   EXPECT_EQ(out->row_step, in.row_step);
   EXPECT_FALSE(out->is_bigendian);
+  EXPECT_EQ(out->frame_id, "camera_front");
   EXPECT_FALSE(out->compressed_depth_min.has_value());
   EXPECT_FALSE(out->compressed_depth_max.has_value());
   ASSERT_EQ(out->data.size(), pixels.size());
@@ -70,6 +72,7 @@ TEST(ImageCodecTest, RoundTripCompressedDepthWithRange) {
   ASSERT_TRUE(out->compressed_depth_max.has_value());
   EXPECT_FLOAT_EQ(*out->compressed_depth_min, 0.5f);
   EXPECT_FLOAT_EQ(*out->compressed_depth_max, 10.0f);
+  EXPECT_TRUE(out->frame_id.empty());  // unset frame_id round-trips as empty
 }
 
 }  // namespace

pj_plugins/CLAUDE.md

@@ -35,9 +35,11 @@ submodule-internal modules; `pj_base` carries none).
   only `MessageParserPluginBase` + `object_ingest_policy.hpp` live here under
   `pj_plugins/sdk/`. (The `docs/ARCHITECTURE.md` §2 diagram is stale on this.)
 - **Handles keep the DSO mapped.** Every handle holds a `shared_ptr<void>`
-  library token, so destroying/hot-reloading the loader cannot `dlclose` a live
-  plugin. Dialog handles add a non-owning `borrowed()` form for source/toolbox
-  embedded dialogs — those must not outlive the owning handle.
+  library token (exposed via `libraryOwner()`), so destroying/hot-reloading the
+  loader cannot `dlclose` a live plugin — and a lazy ObjectStore payload anchor,
+  whose `release` fn is plugin code, can capture that token to stay safe past the
+  handle's own lifetime. Dialog handles add a non-owning `borrowed()` form for
+  source/toolbox embedded dialogs — those must not outlive the owning handle.
 
 ## Read deeper
 | For | Read |

pj_plugins/docs/ARCHITECTURE.md

@@ -359,7 +359,10 @@ Each family has a move-only RAII handle:
 - Destructor calls `vt->destroy(ctx)`.
 - Handles created by a loader retain a shared DSO owner; destroying or
   hot-reloading the loader/catalog entry cannot `dlclose` the plugin while
-  live handles still call its vtable.
+  live handles still call its vtable. `DataSourceHandle` exposes this token via
+  `libraryOwner()` so it can be captured anywhere plugin code may outlive the
+  handle — e.g. a lazy `ObjectStore` payload anchor whose `release` fn lives in
+  the plugin `.so` — keeping the DSO mapped until that captor is gone too.
 - No copy, move-only semantics.
 - Methods delegate to vtable functions with the stored context pointer.
 

pj_plugins/include/pj_plugins/host/data_source_handle.hpp

@@ -73,6 +73,14 @@ class DataSourceHandle {
     return vt_ != nullptr && ctx_ != nullptr;
   }
 
+  // The shared library token that keeps this plugin's DSO mapped. Capture a copy
+  // anywhere a callback or payload anchor PRODUCED BY the plugin may outlive this
+  // handle (e.g. lazy ObjectStore payloads): the .so must not be dlclosed while
+  // plugin code (a payload anchor's release fn) can still run.
+  [[nodiscard]] std::shared_ptr<void> libraryOwner() const {
+    return library_owner_;
+  }
+
   [[nodiscard]] std::string manifest() const {
     return vt_->manifest_json != nullptr ? std::string(vt_->manifest_json) : std::string();
   }