Add send_columns examples for images, fix rust send_columns handling of listarrays (#7172)

### What

* New `send_columns` snippets for image, demonstrating to send several
images at once efficiently
* C++ convenience methods for image format component
* Rust slicing of blobs
* Rust `send_columns` no longer assumes that an encountered `ListArray`
is already the list array for the column
* this broke any `send_columns` call for any component batch that's
internally a list array

Unfortunately, the snippet isn't fully deterministic and can't be
compared cross language since the due to the batcher on `log` calls, log
may arrive before or after `send_columns`


https://github.com/user-attachments/assets/c9af069e-cd64-40c5-b543-54055bea3e42


### 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 the web demo (if applicable):
* Using examples from latest `main` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/7172?manifest_url=https://app.rerun.io/version/main/examples_manifest.json)
* Using full set of examples from `nightly` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/7172?manifest_url=https://app.rerun.io/version/nightly/examples_manifest.json)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG
* [x] If applicable, add a new check to the [release
checklist](https://github.com/rerun-io/rerun/blob/main/tests/python/release_checklist)!
* [x] If have noted any breaking changes to the log API in
`CHANGELOG.md` and the migration guide

- [PR Build Summary](https://build.rerun.io/pr/7172)
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

To run all checks from `main`, comment on the PR with `@rerun-bot
full-check`.

Author: Wumpf

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

@@ -20,6 +20,7 @@ namespace rerun.archetypes;
 /// \cpp If needed, this "borrow-behavior" can be extended by defining your own `rerun::CollectionAdapter`.
 ///
 /// \example archetypes/image_simple image="https://static.rerun.io/image_simple/06ba7f8582acc1ffb42a7fd0006fad7816f3e4e4/1200w.png"
+/// \example archetypes/image_send_columns title= image="Advanced usage of `send_columns` to send multiple images at once" image="https://static.rerun.io/image_send_columns/321455161d79e2c45d6f5a6f175d6f765f418897/1200w.png"
 table Image (
   "attr.rust.derive": "PartialEq",
   "attr.cpp.no_field_ctors",

crates/store/re_types/definitions/rerun/components/blob.fbs

@@ -3,6 +3,7 @@ namespace rerun.components;
 // ---
 
 /// A binary blob of data.
+/// \rs Ref-counted internally and therefore cheap to clone.
 table Blob (
   "attr.arrow.transparent",
   "attr.python.aliases": "bytes, npt.NDArray[np.uint8]",

crates/store/re_types/definitions/rerun/datatypes/blob.fbs

@@ -3,6 +3,7 @@ namespace rerun.datatypes;
 // ---
 
 /// A binary blob of data.
+/// \rs Ref-counted internally and therefore cheap to clone.
 table Blob (
   "attr.docs.unreleased",
   "attr.arrow.transparent",

crates/store/re_types/src/archetypes/image.rs

@@ -0,0 +1,64 @@
+use super::ImageFormat;
+use crate::datatypes::{self, ChannelDatatype, ColorModel, PixelFormat};
+
+impl ImageFormat {
+    /// Create a new depth image format with the given resolution and datatype.
+    #[inline]
+    pub fn depth([width, height]: [u32; 2], datatype: ChannelDatatype) -> Self {
+        datatypes::ImageFormat::depth([width, height], datatype).into()
+    }
+
+    /// Create a new segmentation image format with the given resolution and datatype.
+    #[inline]
+    pub fn segmentation([width, height]: [u32; 2], datatype: ChannelDatatype) -> Self {
+        datatypes::ImageFormat::segmentation([width, height], datatype).into()
+    }
+
+    /// Create a new rgb image format with 8 bit per channel with the given resolution.
+    #[inline]
+    pub fn rgb8([width, height]: [u32; 2]) -> Self {
+        datatypes::ImageFormat::rgb8([width, height]).into()
+    }
+
+    /// Create a new rgba image format with 8 bit per channel with the given resolution.
+    #[inline]
+    pub fn rgba8([width, height]: [u32; 2]) -> Self {
+        datatypes::ImageFormat::rgba8([width, height]).into()
+    }
+
+    /// From a speicifc pixel format.
+    #[inline]
+    pub fn from_pixel_format([width, height]: [u32; 2], pixel_format: PixelFormat) -> Self {
+        datatypes::ImageFormat::from_pixel_format([width, height], pixel_format).into()
+    }
+
+    /// Determine if the image format has an alpha channel.
+    #[inline]
+    pub fn has_alpha(&self) -> bool {
+        self.0.has_alpha()
+    }
+
+    /// Determine if the image format represents floating point data.
+    #[inline]
+    pub fn is_float(&self) -> bool {
+        self.0.is_float()
+    }
+
+    /// Number of bytes for the whole image.
+    #[inline]
+    pub fn num_bytes(&self) -> usize {
+        self.0.num_bytes()
+    }
+
+    /// The color model represented by this image format.
+    #[inline]
+    pub fn color_model(&self) -> ColorModel {
+        self.0.color_model()
+    }
+
+    /// The datatype represented by this image format.
+    #[inline]
+    pub fn datatype(&self) -> ChannelDatatype {
+        self.0.datatype()
+    }
+}

crates/store/re_types/src/components/blob.rs

@@ -1,5 +1,19 @@
 use super::Blob;
 
+impl Blob {
+    /// Returns a new [`Blob`] that is a slice of this buffer starting at `offset`.
+    ///
+    /// Doing so allows the same memory region to be shared between buffers.
+    /// Note that you can beforehand `clone` the [`Blob`] to get a new buffer that shares the same memory.
+    ///
+    /// # Panics
+    /// Panics iff `offset + length` is larger than `len`.
+    #[inline]
+    pub fn sliced(self, range: std::ops::Range<usize>) -> Self {
+        self.0.sliced(range).into()
+    }
+}
+
 impl From<Vec<u8>> for Blob {
     fn from(bytes: Vec<u8>) -> Self {
         Self(bytes.into())

crates/store/re_types/src/components/image_format_ext.rs

@@ -25,6 +25,30 @@ impl ImageFormat {
         }
     }
 
+    /// Create a new rgb image format with 8 bit per channel with the given resolution.
+    #[inline]
+    pub fn rgb8([width, height]: [u32; 2]) -> Self {
+        Self {
+            width,
+            height,
+            pixel_format: None,
+            channel_datatype: Some(ChannelDatatype::U8),
+            color_model: Some(ColorModel::RGB),
+        }
+    }
+
+    /// Create a new rgba image format with 8 bit per channel with the given resolution.
+    #[inline]
+    pub fn rgba8([width, height]: [u32; 2]) -> Self {
+        Self {
+            width,
+            height,
+            pixel_format: None,
+            channel_datatype: Some(ChannelDatatype::U8),
+            color_model: Some(ColorModel::RGBA),
+        }
+    }
+
     /// From a speicifc pixel format.
     #[inline]
     pub fn from_pixel_format([width, height]: [u32; 2], pixel_format: PixelFormat) -> Self {

crates/store/re_types/src/components/mod.rs

@@ -54,6 +54,17 @@ impl<T> ArrowBuffer<T> {
     pub fn into_inner(self) -> Buffer<T> {
         self.0
     }
+
+    /// Returns a new [`Buffer`] that is a slice of this buffer starting at `offset`.
+    ///
+    /// Doing so allows the same memory region to be shared between buffers.
+    ///
+    /// # Panics
+    /// Panics iff `offset + length` is larger than `len`.
+    #[inline]
+    pub fn sliced(self, range: std::ops::Range<usize>) -> Self {
+        Self(self.0.sliced(range.start, range.len()))
+    }
 }
 
 impl<T: bytemuck::Pod> ArrowBuffer<T> {

crates/store/re_types/src/datatypes/blob.rs

@@ -894,13 +894,17 @@ impl RecordingStream {
     /// Lower-level logging API to provide data spanning multiple timepoints.
     ///
     /// Unlike the regular `log` API, which is row-oriented, this API lets you submit the data
-    /// in a columnar form. The lengths of all of the [`TimeColumn`] and the [`ArrowListArray`]s
+    /// in a columnar form. The lengths of all of the [`TimeColumn`] and the component batches
     /// must match. All data that occurs at the same index across the different time and components
     /// arrays will act as a single logical row.
     ///
     /// Note that this API ignores any stateful time set on the log stream via the
     /// [`Self::set_timepoint`]/[`Self::set_time_nanos`]/etc. APIs.
     /// Furthermore, this will _not_ inject the default timelines `log_tick` and `log_time` timeline columns.
+    ///
+    /// TODO(#7167): Unlike Python and C++, this API does not yet support arbitrary partitions of the incoming
+    /// component arrays. Each component will be individually associated with a single timepoint, rather
+    /// than offering how big the component arrays are that are associated with each timepoint.
     #[inline]
     pub fn send_columns<'a>(
         &self,
@@ -920,27 +924,21 @@ impl RecordingStream {
             .map(|batch| {
                 let array = batch.to_arrow()?;
 
-                let array = if let Some(array) =
-                    array.as_any().downcast_ref::<ArrowListArray<i32>>()
-                {
-                    array.clone()
-                } else {
-                    let offsets = Offsets::try_from_lengths(std::iter::repeat(1).take(array.len()))
-                        .map_err(|err| ChunkError::Malformed {
-                            reason: format!("Failed to create offsets: {err}"),
-                        })?;
-                    let data_type =
-                        ArrowListArray::<i32>::default_datatype(array.data_type().clone());
-                    ArrowListArray::<i32>::try_new(
-                        data_type,
-                        offsets.into(),
-                        array.to_boxed(),
-                        None,
-                    )
+                let offsets = Offsets::try_from_lengths(std::iter::repeat(1).take(array.len()))
                     .map_err(|err| ChunkError::Malformed {
-                        reason: format!("Failed to wrap in List array: {err}"),
-                    })?
-                };
+                        reason: format!("Failed to create offsets: {err}"),
+                    })?;
+                let data_type = ArrowListArray::<i32>::default_datatype(array.data_type().clone());
+
+                let array = ArrowListArray::<i32>::try_new(
+                    data_type,
+                    offsets.into(),
+                    array.to_boxed(),
+                    None,
+                )
+                .map_err(|err| ChunkError::Malformed {
+                    reason: format!("Failed to wrap in List array: {err}"),
+                })?;
 
                 Ok((batch.name(), array))
             })

crates/store/re_types/src/datatypes/blob_ext.rs

@@ -0,0 +1,50 @@
+// Send multiple images at once using `send_columns`.
+
+#include <numeric>
+#include <rerun.hpp>
+
+int main() {
+    auto rec = rerun::RecordingStream("rerun_example_image_send_columns");
+    rec.spawn().exit_on_failure();
+
+    // Timeline on which the images are distributed.
+    std::vector<int64_t> times(20);
+    std::iota(times.begin(), times.end(), 0);
+
+    // Create a batch of images with a moving rectangle.
+    const size_t width = 300, height = 200;
+    std::vector<uint8_t> images(times.size() * height * width * 3, 0);
+    for (size_t t = 0; t < times.size(); ++t) {
+        for (size_t y = 0; y < height; ++y) {
+            for (size_t x = 0; x < width; ++x) {
+                size_t idx = (t * height * width + y * width + x) * 3;
+                images[idx + 2] = 255; // Blue background
+                if (y >= 50 && y < 150 && x >= t * 10 && x < t * 10 + 100) {
+                    images[idx + 1] = 255; // Turquoise rectangle
+                }
+            }
+        }
+    }
+
+    // Log the ImageFormat and indicator once, as static.
+    auto format = rerun::components::ImageFormat(
+        {width, height},
+        rerun::ColorModel::RGB,
+        rerun::ChannelDatatype::U8
+    );
+    rec.log_static("images", rerun::borrow(&format), rerun::Image::IndicatorComponent());
+
+    // Split up the image data into several components referencing the underlying data.
+    const size_t image_size_in_bytes = width * height * 3;
+    std::vector<rerun::components::ImageBuffer> image_data(times.size());
+    for (size_t i = 0; i < times.size(); ++i) {
+        image_data[i] = rerun::borrow(images.data() + i * image_size_in_bytes, image_size_in_bytes);
+    }
+
+    // Send all images at once.
+    rec.send_columns(
+        "images",
+        rerun::TimeColumn::from_sequence_points("step", std::move(times)),
+        rerun::borrow(image_data)
+    );
+}