Add incremental_logging example (#5462)

Showcases how to incrementally log data belonging to the same archetype,
and re-use some or all of it across frames.

Turns out the first thing I immediately wanted was clamping-edge
semantics 🥲

### 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 newly built examples:
[app.rerun.io](https://app.rerun.io/pr/5462/index.html)
* Using examples from latest `main` build:
[app.rerun.io](https://app.rerun.io/pr/5462/index.html?manifest_url=https://app.rerun.io/version/main/examples_manifest.json)
* Using full set of examples from `nightly` build:
[app.rerun.io](https://app.rerun.io/pr/5462/index.html?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)!

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

examples/cpp/CMakeLists.txt

@@ -2,6 +2,7 @@ add_subdirectory(clock)
 add_subdirectory(custom_collection_adapter)
 add_subdirectory(dna)
 add_subdirectory(external_data_loader)
+add_subdirectory(incremental_logging)
 add_subdirectory(log_file)
 add_subdirectory(minimal)
 add_subdirectory(shared_recording)
@@ -13,6 +14,7 @@ add_custom_target(examples)
 add_dependencies(examples example_clock)
 add_dependencies(examples example_custom_collection_adapter)
 add_dependencies(examples example_dna)
+add_dependencies(examples example_incremental_logging)
 add_dependencies(examples example_log_file)
 add_dependencies(examples example_minimal)
 add_dependencies(examples example_shared_recording)

examples/cpp/incremental_logging/CMakeLists.txt

@@ -0,0 +1,27 @@
+cmake_minimum_required(VERSION 3.16...3.27)
+
+# If you use the example outside of the Rerun SDK you need to specify
+# where the rerun_c build is to be found by setting the `RERUN_CPP_URL` variable.
+# This can be done by passing `-DRERUN_CPP_URL=<path to rerun_sdk_cpp zip>` to cmake.
+if(DEFINED RERUN_REPOSITORY)
+    add_executable(example_incremental_logging main.cpp)
+    rerun_strict_warning_settings(example_incremental_logging)
+else()
+    project(example_incremental_logging LANGUAGES CXX)
+
+    add_executable(example_incremental_logging main.cpp)
+
+    # Set the path to the rerun_c build.
+    set(RERUN_CPP_URL "https://github.com/rerun-io/rerun/releases/latest/download/rerun_cpp_sdk.zip" CACHE STRING "URL to the rerun_cpp zip.")
+
+    # Download the rerun_sdk
+    include(FetchContent)
+    FetchContent_Declare(rerun_sdk URL ${RERUN_CPP_URL})
+    FetchContent_MakeAvailable(rerun_sdk)
+
+    # Rerun requires at least C++17, but it should be compatible with newer versions.
+    set_property(TARGET example_incremental_logging PROPERTY CXX_STANDARD 17)
+endif()
+
+# Link against rerun_sdk.
+target_link_libraries(example_incremental_logging PRIVATE rerun_sdk)

examples/cpp/incremental_logging/README.md

@@ -0,0 +1,27 @@
+<!--[metadata]
+title = "Incremental Logging"
+tags = ["3d", "api-example"]
+description = "Showcases how to incrementally log data belonging to the same archetype."
+thumbnail = "https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/480w.png"
+thumbnail_dimensions = [480, 285]
+channel = "main"
+-->
+
+
+<picture>
+  <img src="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/full.png" alt="">
+  <source media="(max-width: 480px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/480w.png">
+  <source media="(max-width: 768px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/768w.png">
+  <source media="(max-width: 1024px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/1024w.png">
+  <source media="(max-width: 1200px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/1200w.png">
+</picture>
+
+Showcases how to incrementally log data belonging to the same archetype, and re-use some or all of it across frames.
+
+
+To build it from a checkout of the repository (requires a Rust toolchain):
+```bash
+cmake .
+cmake --build . --target example_incremental_logging
+./examples/cpp/incremental/example_incremental_logging
+```

examples/cpp/incremental_logging/main.cpp

@@ -0,0 +1,38 @@
+// Showcase how to incrementally log data belonging to the same archetype, and re-use some or all
+// of it across frames.
+
+#include <rerun.hpp>
+
+#include <algorithm>
+#include <random>
+
+int main() {
+    const auto rec = rerun::RecordingStream("rerun_example_incremental_logging");
+    rec.spawn().exit_on_failure();
+
+    // TODO(#5264): just log one once clamp-to-edge semantics land.
+    std::vector<rerun::Color> colors(10, rerun::Color(255, 0, 0));
+    std::vector<rerun::Radius> radii(10, rerun::Radius(0.1f));
+
+    // Only log colors and radii once.
+    rec.set_time_sequence("frame_nr", 0);
+    rec.log("points", colors, radii);
+    // Logging timelessly with `RecordingStream::log_timeless` would also work.
+    // rec.log_timeless("points", colors, radii);
+
+    std::default_random_engine gen;
+    std::uniform_real_distribution<float> dist_pos(-5.0f, 5.0f);
+
+    // Then log only the points themselves each frame.
+    //
+    // They will automatically re-use the colors and radii logged at the beginning.
+    for (int i = 0; i < 10; ++i) {
+        rec.set_time_sequence("frame_nr", i);
+
+        std::vector<rerun::Position3D> points(10);
+        std::generate(points.begin(), points.end(), [&] {
+            return rerun::Position3D(dist_pos(gen), dist_pos(gen), dist_pos(gen));
+        });
+        rec.log("points", rerun::Points3D(points));
+    }
+}

examples/python/incremental_logging/README.md

@@ -0,0 +1,25 @@
+<!--[metadata]
+title = "Incremental Logging"
+tags = ["3d", "api-example"]
+description = "Showcases how to incrementally log data belonging to the same archetype."
+thumbnail = "https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/480w.png"
+thumbnail_dimensions = [480, 301]
+channel = "main"
+-->
+
+
+<picture>
+  <img src="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/full.png" alt="">
+  <source media="(max-width: 480px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/480w.png">
+  <source media="(max-width: 768px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/768w.png">
+  <source media="(max-width: 1024px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/1024w.png">
+  <source media="(max-width: 1200px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/1200w.png">
+</picture>
+
+Showcases how to incrementally log data belonging to the same archetype, and re-use some or all of it across frames.
+
+
+To build it from a checkout of the repository (requires a Rust toolchain):
+```bash
+python examples/python/incremental_logging/main.py
+```

examples/python/incremental_logging/main.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Showcases how to incrementally log data belonging to the same archetype, and re-use some or all of it across frames."""
+from __future__ import annotations
+
+import argparse
+
+import numpy as np
+import rerun as rr
+from numpy.random import default_rng
+
+parser = argparse.ArgumentParser(description="Showcases how to incrementally log data belonging to the same archetype.")
+rr.script_add_args(parser)
+args = parser.parse_args()
+
+rr.script_setup(args, "rerun_example_incremental_logging")
+
+# TODO(#5264): just log one once clamp-to-edge semantics land.
+colors = rr.components.ColorBatch(np.repeat(0xFF0000FF, 10))
+radii = rr.components.RadiusBatch(np.repeat(0.1, 10))
+
+# Only log colors and radii once.
+rr.set_time_sequence("frame_nr", 0)
+rr.log_components("points", [colors, radii])
+# Logging timelessly would also work.
+# rr.log_components("points", [colors, radii], timeless=True)
+
+rng = default_rng(12345)
+
+# Then log only the points themselves each frame.
+#
+# They will automatically re-use the colors and radii logged at the beginning.
+for i in range(10):
+    rr.set_time_sequence("frame_nr", i)
+    rr.log("points", rr.Points3D(rng.uniform(-5, 5, size=[10, 3])))
+
+rr.script_teardown(args)

examples/python/incremental_logging/requirements.txt

@@ -0,0 +1,2 @@
+numpy
+rerun-sdk

examples/python/requirements.txt

@@ -11,6 +11,7 @@
 -r face_tracking/requirements.txt
 -r gesture_detection/requirements.txt
 -r human_pose_tracking/requirements.txt
+-r incremental_logging/requirements.txt
 -r lidar/requirements.txt
 -r live_camera_edge_detection/requirements.txt
 -r live_depth_sensor/requirements.txt

examples/rust/incremental_logging/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "incremental_logging"
+version = "0.15.0-alpha.2"
+edition = "2021"
+rust-version = "1.74"
+license = "MIT OR Apache-2.0"
+publish = false
+
+[dependencies]
+rerun = { path = "../../../crates/rerun", features = ["web_viewer", "clap"] }
+
+anyhow = "1.0"
+clap = { version = "4.0", features = ["derive"] }
+glam = "0.22"
+rand = "0.8"

examples/rust/incremental_logging/README.md

@@ -0,0 +1,24 @@
+<!--[metadata]
+title = "Incremental Logging"
+tags = ["3d", "api-example"]
+description = "Showcases how to incrementally log data belonging to the same archetype."
+thumbnail = "https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/480w.png"
+thumbnail_dimensions = [480, 285]
+channel = "main"
+-->
+
+
+<picture>
+  <img src="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/full.png" alt="">
+  <source media="(max-width: 480px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/480w.png">
+  <source media="(max-width: 768px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/768w.png">
+  <source media="(max-width: 1024px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/1024w.png">
+  <source media="(max-width: 1200px)" srcset="https://static.rerun.io/incremental_logging/b7a2bd889b09c3840f56dc31bd6d677934ab3126/1200w.png">
+</picture>
+
+Showcases how to incrementally log data belonging to the same archetype, and re-use some or all of it across frames.
+
+
+```bash
+cargo run --release
+```

examples/rust/incremental_logging/src/main.rs

@@ -0,0 +1,66 @@
+//! Showcase how to incrementally log data belonging to the same archetype, and re-use some or all
+//! of it across frames.
+//!
+//! Usage:
+//! ```
+//! cargo run -p incremental -- --help
+//! ```
+
+use rand::{distributions::Uniform, Rng as _};
+use rerun::external::re_log;
+
+#[derive(Debug, clap::Parser)]
+#[clap(author, version, about)]
+struct Args {
+    #[command(flatten)]
+    rerun: rerun::clap::RerunArgs,
+}
+
+fn main() -> anyhow::Result<()> {
+    re_log::setup_logging();
+
+    use clap::Parser as _;
+    let args = Args::parse();
+
+    let (rec, _serve_guard) = args.rerun.init("rerun_example_incremental_logging")?;
+    run(&rec)
+}
+
+fn run(rec: &rerun::RecordingStream) -> anyhow::Result<()> {
+    // TODO(#5264): just log one once clamp-to-edge semantics land.
+    let colors = [rerun::Color::from_rgb(255, 0, 0); 10];
+    let radii = [rerun::Radius(0.1); 10];
+
+    // Only log colors and radii once.
+    rec.set_time_sequence("frame_nr", 0);
+    rec.log_component_batches(
+        "points",
+        false, /* timeless */
+        [&colors as &dyn rerun::ComponentBatch, &radii],
+    )?;
+    // Logging timelessly would also work.
+    // rec.log_component_batches(
+    //     "points",
+    //     true, /* timeless */
+    //     [&colors as &dyn rerun::ComponentBatch, &radii],
+    // )?;
+
+    let mut rng = rand::thread_rng();
+    let dist = Uniform::new(-5., 5.);
+
+    // Then log only the points themselves each frame.
+    //
+    // They will automatically re-use the colors and radii logged at the beginning.
+    for i in 0..10 {
+        rec.set_time_sequence("frame_nr", i);
+
+        rec.log(
+            "points",
+            &rerun::Points3D::new(
+                (0..10).map(|_| (rng.sample(dist), rng.sample(dist), rng.sample(dist))),
+            ),
+        )?;
+    }
+
+    Ok(())
+}