Experimental python API for taking viewer screenshots (#12405)

### Related

* Fixes #2305
* it's not perfect, comes with #12481
* #12482

### What

Users long wanted to programmatically write out screenshots from Rerun for all sort of purposes. This is now possible!

Usage

```py
"""Take screenshots of the viewer or specific views from code."""

import rerun as rr
import rerun.blueprint as rrb
from rerun.experimental import ViewerClient

# Setup a viewer with a known blueprint.
rr.init("rerun_example_screenshot", spawn=True)
rr.connect_grpc()
view = rrb.Spatial3DView(name="my blue 3D", background=[100, 149, 237])
rr.send_blueprint(rrb.Blueprint(view, collapse_panels=True))

# Connect to a local viewer.
viewer = ViewerClient()

# Screenshot the entire viewer.
viewer.save_screenshot("entire_viewer.jpg")

# Screenshot only the view we created earlier.
viewer.save_screenshot("my_view.png", view_id=view.id)

```

https://github.com/user-attachments/assets/ddb7d0dd-574a-4412-9c8e-3eabf77ad482


To make this _really_ useful a few more things need to be done - future work:
* allow blocking on when the screenshot is done
* improve `send_blueprint` ergonomics a little bit
* provide an example screenshotting out a camera path (needs above items)
* not directly related but makes this much more powerful: allow setting time cursor from viewer client
* work with a windows-less (headless) viewer
* address views by name rather than id (best effort?)



Draft TODOs:
* [x] a few code todos
* [x] take uuid argument on view_id so we don't have to call `str(view.id)`
* [x] put the above snippet into some docs
* [x] make future work items an issue, check if #2305 is really to be closed fully already and whether there's other issues

Source-Ref: 0bb67f5af9231fc6e1f599d4c9f49e72906914bd

Author: Wumpf

Cargo.lock

@@ -9076,6 +9076,7 @@ dependencies = [
 name = "re_log_channel"
 version = "0.29.0-alpha.1+dev"
 dependencies = [
+ "camino",
  "crossbeam",
  "parking_lot",
  "re_byte_size",
@@ -10444,6 +10445,7 @@ dependencies = [
  "bit-vec",
  "bitflags 2.9.4",
  "bytemuck",
+ "camino",
  "crossbeam",
  "datafusion",
  "directories",

crates/store/re_grpc_server/src/lib.rs

@@ -7,7 +7,7 @@ use std::net::SocketAddr;
 use std::pin::Pin;
 
 use re_byte_size::SizeBytes;
-use re_log_channel::DataSourceMessage;
+use re_log_channel::{DataSourceMessage, DataSourceUiCommand};
 use re_log_encoding::{ToApplication as _, ToTransport as _};
 use re_log_types::TableMsg;
 use re_protos::common::v1alpha1::{
@@ -16,8 +16,8 @@ use re_protos::common::v1alpha1::{
 use re_protos::log_msg::v1alpha1::LogMsg as LogMsgProto;
 use re_protos::sdk_comms::v1alpha1::{
     ReadMessagesRequest, ReadMessagesResponse, ReadTablesRequest, ReadTablesResponse,
-    WriteMessagesRequest, WriteMessagesResponse, WriteTableRequest, WriteTableResponse,
-    message_proxy_service_server,
+    SaveScreenshotRequest, SaveScreenshotResponse, WriteMessagesRequest, WriteMessagesResponse,
+    WriteTableRequest, WriteTableResponse, message_proxy_service_server,
 };
 use tokio::net::TcpListener;
 use tokio::sync::{broadcast, mpsc, oneshot};
@@ -413,6 +413,8 @@ pub fn spawn_with_recv(
                     }
                 },
 
+                Ok(LogOrTableMsgProto::UiCommand(cmd)) => Ok(DataSourceMessage::UiCommand(cmd)),
+
                 Err(broadcast::error::RecvError::Closed) => {
                     re_log::debug!("message proxy server shut down, closing receiver");
                     channel_log_tx.quit(None).ok();
@@ -474,20 +476,21 @@ struct TableMsgProto {
     id: TableIdProto,
     data: DataframePartProto,
 }
-
 // -----------------------------------------------------------------------------------
 
 #[derive(Clone)]
 enum LogOrTableMsgProto {
     LogMsg(LogMsgProto),
     Table(TableMsgProto),
+    UiCommand(DataSourceUiCommand),
 }
 
 impl LogOrTableMsgProto {
     fn total_size_bytes(&self) -> u64 {
         match self {
             Self::LogMsg(log_msg) => log_msg.total_size_bytes(),
             Self::Table(table) => table.total_size_bytes(),
+            Self::UiCommand(cmd) => cmd.total_size_bytes(),
         }
     }
 }
@@ -504,6 +507,12 @@ impl From<TableMsgProto> for LogOrTableMsgProto {
     }
 }
 
+impl From<DataSourceUiCommand> for LogOrTableMsgProto {
+    fn from(value: DataSourceUiCommand) -> Self {
+        Self::UiCommand(value)
+    }
+}
+
 // -----------------------------------------------------------------------------------
 
 #[derive(Default)]
@@ -611,6 +620,9 @@ impl MessageBuffer {
             LogOrTableMsgProto::Table(msg) => {
                 self.disposable.push_back(msg.into());
             }
+            LogOrTableMsgProto::UiCommand(msg) => {
+                self.disposable.push_back(msg.into());
+            }
         }
     }
 
@@ -826,6 +838,10 @@ impl MessageProxy {
         self.event_tx.send(Event::Message(table.into())).await.ok();
     }
 
+    async fn push_ui_command(&self, cmd: DataSourceUiCommand) {
+        self.event_tx.send(Event::Message(cmd.into())).await.ok();
+    }
+
     async fn new_client_message_stream(&self) -> ReadMsgStream {
         let (sender, receiver) = oneshot::channel();
         if let Err(err) = self.event_tx.send(Event::NewClient(sender)).await {
@@ -869,6 +885,10 @@ impl MessageProxy {
                         re_log::warn_once!("A log stream got a TableMsg");
                         None
                     }
+                    Ok(ReadLogOrTableMsgResponse::UiCommand) => {
+                        re_log::warn_once!("A log stream got a UiCommandMsg");
+                        None
+                    }
                     Err(err) => Some(Err(err)),
                 }),
         )
@@ -884,6 +904,10 @@ impl MessageProxy {
                         None
                     }
                     Ok(ReadLogOrTableMsgResponse::TableMsg(msg)) => Some(Ok(msg)),
+                    Ok(ReadLogOrTableMsgResponse::UiCommand) => {
+                        re_log::warn_once!("A log stream got a UiCommandMsg");
+                        None
+                    }
                     Err(err) => Some(Err(err)),
                 }),
         )
@@ -893,6 +917,7 @@ impl MessageProxy {
 enum ReadLogOrTableMsgResponse {
     LogMsg(ReadMessagesResponse),
     TableMsg(ReadTablesResponse),
+    UiCommand,
 }
 
 impl From<LogOrTableMsgProto> for ReadLogOrTableMsgResponse {
@@ -905,6 +930,7 @@ impl From<LogOrTableMsgProto> for ReadLogOrTableMsgResponse {
                 id: Some(table_msg.id),
                 data: Some(table_msg.data),
             }),
+            LogOrTableMsgProto::UiCommand(_ui_command) => Self::UiCommand,
         }
     }
 }
@@ -982,6 +1008,20 @@ impl message_proxy_service_server::MessageProxyService for MessageProxy {
     ) -> tonic::Result<tonic::Response<Self::ReadTablesStream>> {
         Ok(tonic::Response::new(self.new_client_table_stream().await))
     }
+
+    async fn save_screenshot(
+        &self,
+        request: tonic::Request<SaveScreenshotRequest>,
+    ) -> tonic::Result<tonic::Response<SaveScreenshotResponse>> {
+        let SaveScreenshotRequest { view_id, file_path } = request.into_inner();
+        self.push_ui_command(DataSourceUiCommand::SaveScreenshot {
+            file_path: file_path.into(),
+            view_id,
+        })
+        .await;
+
+        Ok(tonic::Response::new(SaveScreenshotResponse {}))
+    }
 }
 
 #[cfg(test)]

crates/store/re_log_channel/Cargo.toml

@@ -26,6 +26,7 @@ re_quota_channel.workspace = true
 re_tracing.workspace = true
 re_uri.workspace = true
 
+camino.workspace = true
 crossbeam.workspace = true
 parking_lot.workspace = true
 serde.workspace = true

crates/store/re_log_channel/src/data_source_message.rs

@@ -77,4 +77,29 @@ pub enum DataSourceUiCommand {
         // Not using `re_uri::Fragment` to avoid further dependency entanglement.
         fragment: String, //re_uri::Fragment,
     },
+
+    /// Save a screenshot to a file.
+    SaveScreenshot {
+        /// File path to save the screenshot to.
+        // TODO(#12482): Returning the screenshot to the caller would be more flexible and useful.
+        file_path: camino::Utf8PathBuf,
+
+        /// Optional view id to screenshot a specific view.
+        ///
+        /// If none is provided, the entire viewer is screenshotted.
+        view_id: Option<String>,
+    },
+}
+
+impl re_byte_size::SizeBytes for DataSourceUiCommand {
+    fn heap_size_bytes(&self) -> u64 {
+        match self {
+            Self::SetUrlFragment { store_id, fragment } => {
+                store_id.heap_size_bytes() + fragment.heap_size_bytes()
+            }
+            Self::SaveScreenshot { file_path, view_id } => {
+                file_path.capacity() as u64 + view_id.heap_size_bytes()
+            }
+        }
+    }
 }

crates/store/re_protos/proto/rerun/v1alpha1/sdk_comms.proto

@@ -22,6 +22,8 @@ service MessageProxyService {
 
   rpc WriteTable(WriteTableRequest) returns (WriteTableResponse) {}
   rpc ReadTables(ReadTablesRequest) returns (stream ReadTablesResponse) {}
+
+  rpc SaveScreenshot(SaveScreenshotRequest) returns (SaveScreenshotResponse) {}
 }
 
 // WriteMessages
@@ -57,3 +59,16 @@ message ReadTablesResponse {
   rerun.common.v1alpha1.TableId id = 1;
   rerun.common.v1alpha1.DataframePart data = 2;
 }
+
+// SaveScreenshot
+
+message SaveScreenshotRequest {
+  // Optional view ID to screenshot. If omitted, screenshots the entire viewer.
+  optional string view_id = 1;
+
+  // Path at which the screenshot will be saved.
+  // This path is relative to the current working directory of the viewer process.
+  string file_path = 2;
+}
+
+message SaveScreenshotResponse {}