C++: Allow creating Image/Tensor/DepthImage/SegmentationImage directl…

…y from shape & pointer (#4345)

### What

* Fixes #4343

Also a bunch of doc polish in related areas on the way.

Collection now has an `empty` method.


### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested [app.rerun.io](https://app.rerun.io/pr/4345) (if
applicable)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG

- [PR Build Summary](https://build.rerun.io/pr/4345)
- [Docs
preview](https://rerun.io/preview/2453dd78db2a0a8139b1a00060304d97eeef36fe/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/2453dd78db2a0a8139b1a00060304d97eeef36fe/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

crates/re_types/definitions/rerun/archetypes/depth_image.fbs

@@ -11,6 +11,10 @@ namespace rerun.archetypes;
 /// The shape of the `TensorData` must be mappable to an `HxW` tensor.
 /// Each pixel corresponds to a depth value in units specified by `meter`.
 ///
+/// \cpp Since the underlying `rerun::datatypes::TensorData` uses `rerun::Collection` internally,
+/// \cpp data can be passed in without a copy from raw pointers or by reference from `std::vector`/`std::array`/c-arrays.
+/// \cpp If needed, this "borrow-behavior" can be extended by defining your own `rerun::CollectionAdapter`.
+///
 /// \example depth_image_simple !api title="Simple example" image="https://static.rerun.io/depth_image_simple/9598554977873ace2577bddd79184ac120ceb0b0/1200w.png"
 /// \example depth_image_3d title="Depth to 3D example" image="https://static.rerun.io/depth_image_3d/f78674bdae0eb25786c6173307693c5338f38b87/1200w.png"
 table DepthImage (

crates/re_types/definitions/rerun/archetypes/image.fbs

@@ -16,6 +16,10 @@ namespace rerun.archetypes;
 /// Leading and trailing unit-dimensions are ignored, so that
 /// `1x640x480x3x1` is treated as a `640x480x3` RGB image.
 ///
+/// \cpp Since the underlying `rerun::datatypes::TensorData` uses `rerun::Collection` internally,
+/// \cpp data can be passed in without a copy from raw pointers or by reference from `std::vector`/`std::array`/c-arrays.
+/// \cpp If needed, this "borrow-behavior" can be extended by defining your own `rerun::CollectionAdapter`.
+///
 /// \example image_simple image="https://static.rerun.io/image_simple/06ba7f8582acc1ffb42a7fd0006fad7816f3e4e4/1200w.png"
 table Image (
   "attr.rust.derive": "PartialEq",

crates/re_types/definitions/rerun/archetypes/segmentation_image.fbs

@@ -17,6 +17,10 @@ namespace rerun.archetypes;
 /// \py See also [`AnnotationContext`][rerun.archetypes.AnnotationContext] to associate each class with a color and a label.
 /// \rs See also [`AnnotationContext`][crate::archetypes::AnnotationContext] to associate each class with a color and a label.
 ///
+/// \cpp Since the underlying `rerun::datatypes::TensorData` uses `rerun::Collection` internally,
+/// \cpp data can be passed in without a copy from raw pointers or by reference from `std::vector`/`std::array`/c-arrays.
+/// \cpp If needed, this "borrow-behavior" can be extended by defining your own `rerun::CollectionAdapter`.
+///
 /// \example segmentation_image_simple title="Simple segmentation image" image="https://static.rerun.io/segmentation_image_simple/eb49e0b8cb870c75a69e2a47a2d202e5353115f6/1200w.png"
 table SegmentationImage (
   "attr.rust.derive": "PartialEq",

crates/re_types/definitions/rerun/archetypes/tensor.fbs

@@ -8,6 +8,10 @@ namespace rerun.archetypes;
 
 /// A generic n-dimensional Tensor.
 ///
+/// \cpp Since the underlying `rerun::datatypes::TensorData` uses `rerun::Collection` internally,
+/// \cpp data can be passed in without a copy from raw pointers or by reference from `std::vector`/`std::array`/c-arrays.
+/// \cpp If needed, this "borrow-behavior" can be extended by defining your own `rerun::CollectionAdapter`.
+///
 /// \example tensor_simple title="Simple Tensor" image="https://static.rerun.io/tensor_simple/baacb07712f7b706e3c80e696f70616c6c20b367/1200w.png"
 table Tensor (
   "attr.rust.derive": "PartialEq"

crates/re_types_builder/src/codegen/cpp/mod.rs

@@ -1995,7 +1995,8 @@ fn lines_from_docs(docs: &Docs) -> Vec<String> {
             if let Some(title) = title {
                 lines.push(format!("### {title}"));
             } else {
-                lines.push(format!("### `{name}`:"));
+                // Other languages put the name in backticks but doxygen doesn't support this on headings.
+                lines.push(format!("### {name}:"));
             }
 
             if let Some(image) = image {

docs/code-examples/depth_image_3d.cpp

@@ -29,8 +29,5 @@ int main() {
         )
     );
 
-    rec.log(
-        "world/camera/depth",
-        rerun::DepthImage({HEIGHT, WIDTH}, std::move(data)).with_meter(10000.0)
-    );
+    rec.log("world/camera/depth", rerun::DepthImage({HEIGHT, WIDTH}, data).with_meter(10000.0));
 }

docs/code-examples/depth_image_simple.cpp

@@ -20,5 +20,5 @@ int main() {
         std::fill_n(data.begin() + y * WIDTH + 100, 180, static_cast<uint16_t>(45000));
     }
 
-    rec.log("depth", rerun::DepthImage({HEIGHT, WIDTH}, std::move(data)).with_meter(10000.0));
+    rec.log("depth", rerun::DepthImage({HEIGHT, WIDTH}, data).with_meter(10000.0));
 }

docs/code-examples/image_simple.cpp

@@ -23,5 +23,5 @@ int main() {
         }
     }
 
-    rec.log("image", rerun::Image({HEIGHT, WIDTH, 3}, std::move(data)));
+    rec.log("image", rerun::Image({HEIGHT, WIDTH, 3}, data));
 }

docs/code-examples/segmentation_image_simple.cpp

@@ -29,5 +29,5 @@ int main() {
         })
     );
 
-    rec.log("image", rerun::SegmentationImage({HEIGHT, WIDTH}, std::move(data)));
+    rec.log("image", rerun::SegmentationImage({HEIGHT, WIDTH}, data));
 }

rerun_cpp/src/rerun/archetypes/depth_image_ext.cpp

@@ -10,17 +10,35 @@ namespace rerun::archetypes {
 
     /// New depth image from height/width and tensor buffer.
     ///
+    /// \param shape
+    /// Shape of the image. Calls `Error::handle()` if the shape is not rank 2.
     /// Sets the dimension names to "height" and "width" if they are not specified.
-    /// Calls `Error::handle()` if the shape is not rank 2.
+    /// \param buffer
+    /// The tensor buffer containing the depth image data.
     DepthImage(Collection<datatypes::TensorDimension> shape, datatypes::TensorBuffer buffer)
         : DepthImage(datatypes::TensorData(std::move(shape), std::move(buffer))) {}
 
     /// New depth image from tensor data.
     ///
+    /// \param data_
+    /// The tensor buffer containing the depth image data.
     /// Sets the dimension names to "height" and "width" if they are not specified.
     /// Calls `Error::handle()` if the shape is not rank 2.
     explicit DepthImage(components::TensorData data_);
 
+    /// New depth image from dimensions and pointer to depth image data.
+    ///
+    /// Type must be one of the types supported by `rerun::datatypes::TensorData`.
+    /// \param shape
+    /// Shape of the image. Calls `Error::handle()` if the shape is not rank 2.
+    /// Sets the dimension names to "height", "width" and "channel" if they are not specified.
+    /// Determines the number of elements expected to be in `data`.
+    /// \param data_
+    /// Target of the pointer must outlive the archetype.
+    template <typename TElement>
+    explicit DepthImage(Collection<datatypes::TensorDimension> shape, const TElement* data_)
+        : DepthImage(datatypes::TensorData(std::move(shape), data_)) {}
+
     // </CODEGEN_COPY_TO_HEADER>
 #endif
 

rerun_cpp/src/rerun/archetypes/image_ext.cpp

@@ -13,16 +13,35 @@ namespace rerun::archetypes {
 
     /// New Image from height/width/channel and tensor buffer.
     ///
-    /// Sets the dimension names to "height",  "width" and "channel" if they are not specified.
-    /// Calls `Error::handle()` if the shape is not rank 2 or 3.
-    Image(Collection<datatypes::TensorDimension> shape, datatypes::TensorBuffer buffer)
+    /// \param shape
+    /// Shape of the image. Calls `Error::handle()` if the shape is not rank 2 or 3.
+    /// Sets the dimension names to "height", "width" and "channel" if they are not specified.
+    /// \param buffer
+    /// The tensor buffer containing the image data.
+    explicit Image(Collection<datatypes::TensorDimension> shape, datatypes::TensorBuffer buffer)
         : Image(datatypes::TensorData(std::move(shape), std::move(buffer))) {}
 
     /// New depth image from tensor data.
     ///
+    /// \param data_
+    /// The tensor buffer containing the image data.
     /// Sets the dimension names to "height",  "width" and "channel" if they are not specified.
     /// Calls `Error::handle()` if the shape is not rank 2 or 3.
     explicit Image(rerun::components::TensorData data_);
+
+    /// New image from dimensions and pointer to image data.
+    ///
+    /// Type must be one of the types supported by `rerun::datatypes::TensorData`.
+    /// \param shape
+    /// Shape of the image. Calls `Error::handle()` if the shape is not rank 2 or 3.
+    /// Sets the dimension names to "height", "width" and "channel" if they are not specified.
+    /// Determines the number of elements expected to be in `data`.
+    /// \param data_
+    /// Target of the pointer must outlive the archetype.
+    template <typename TElement>
+    explicit Image(Collection<datatypes::TensorDimension> shape, const TElement* data_)
+        : Image(datatypes::TensorData(std::move(shape), data_)) {}
+
     // </CODEGEN_COPY_TO_HEADER>
 #endif
 

rerun_cpp/src/rerun/archetypes/segmentation_image_ext.cpp

@@ -10,17 +10,35 @@ namespace rerun::archetypes {
 
     /// New segmentation image from height/width and tensor buffer.
     ///
+    /// \param shape
+    /// Shape of the image. Calls `Error::handle()` if the shape is not rank 2.
     /// Sets the dimension names to "height" and "width" if they are not specified.
-    /// Calls `Error::handle()` if the shape is not rank 2.
+    /// \param buffer
+    /// The tensor buffer containing the segmentation image data.
     SegmentationImage(Collection<datatypes::TensorDimension> shape, datatypes::TensorBuffer buffer)
         : SegmentationImage(datatypes::TensorData(std::move(shape), std::move(buffer))) {}
 
     /// New segmentation image from tensor data.
     ///
+    /// \param data_
+    /// The tensor buffer containing the segmentation image data.
     /// Sets the dimension names to "height" and "width" if they are not specified.
     /// Calls `Error::handle()` if the shape is not rank 2.
     explicit SegmentationImage(components::TensorData data_);
 
+    /// New segmentation image from dimensions and pointer to segmentation image data.
+    ///
+    /// Type must be one of the types supported by `rerun::datatypes::TensorData`.
+    /// \param shape
+    /// Shape of the image. Calls `Error::handle()` if the shape is not rank 2.
+    /// Sets the dimension names to "height", "width" and "channel" if they are not specified.
+    /// Determines the number of elements expected to be in `data`.
+    /// \param data_
+    /// Target of the pointer must outlive the archetype.
+    template <typename TElement>
+    explicit SegmentationImage(Collection<datatypes::TensorDimension> shape, const TElement* data_)
+        : SegmentationImage(datatypes::TensorData(std::move(shape), data_)) {}
+
     // </CODEGEN_COPY_TO_HEADER>
 #endif