Utils & snippets for manually logged VideoFrameReference (#7403)

### What

* Part of #7368 
* Based on:
   * #7401
   * #7402

A bit of a first: I'm referencing the same examples on both the
`AssetVideo` and the `VideoFrameReference` archetype, seems to make
sense :)


![screenshot](https://static.rerun.io/video_manual_frames/320a44e1e06b8b3a3161ecbbeae3e04d1ccb9589/1200w.png)


### 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/7403?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/7403?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
* [x] green main build

- [PR Build Summary](https://build.rerun.io/pr/7403)
- [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`.

crates/build/re_dev_tools/src/build_examples/snippets.rs

@@ -36,8 +36,11 @@ impl Snippets {
         let snippet_root = snippets_dir.join("all");
         let snippets = collect_snippets_recursively(&snippet_root, &config, &snippet_root)?;
 
-        println!("Running {} snippets…", snippets.len());
+        println!("Download test assets…");
         let progress = MultiProgress::new();
+        download_test_assets(&progress)?;
+
+        println!("Running {} snippets…", snippets.len());
         let results: Vec<anyhow::Result<PathBuf>> = snippets
             .into_par_iter()
             .map(|example| example.build(&progress, &self.output_dir))
@@ -190,3 +193,12 @@ struct OptOut {
     /// example name -> languages
     run: HashMap<String, Vec<String>>,
 }
+
+fn download_test_assets(progress: &MultiProgress) -> anyhow::Result<()> {
+    let download_script = re_build_tools::cargo_metadata()?
+        .workspace_root
+        .join("tests/assets/download_test_assets.py");
+    let mut cmd = Command::new("python3");
+    cmd.arg(download_script.as_str());
+    wait_for_output(cmd, "download test assets", progress)
+}

crates/store/re_data_loader/src/loader_archetype.rs

@@ -263,7 +263,7 @@ fn load_video(
             .flat_map(|segment| {
                 segment.samples.iter().map(|s| {
                     // TODO(andreas): Use sample indices instead of timestamps once possible.
-                    re_types::components::VideoTimestamp::new_nanoseconds(
+                    re_types::components::VideoTimestamp::from_nanoseconds(
                         s.timestamp.as_nanoseconds(),
                     )
                 })

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

@@ -7,7 +7,9 @@ namespace rerun.archetypes;
 /// Follow <https://github.com/rerun-io/rerun/issues/7298> for updates on the native support.
 ///
 /// In order to display a video, you need to log a [archetypes.VideoFrameReference] for each frame.
-// TODO(#7368): More docs and examples on how to use this.
+///
+/// \example archetypes/video_manual_frames title="Video with explicit frames" image="https://static.rerun.io/video_manual_frames/320a44e1e06b8b3a3161ecbbeae3e04d1ccb9589/1200w.png"
+// TODO(#7368): Example and reference to `send_video_frames` API.
 table AssetVideo (
   "attr.rerun.experimental"
 ) {

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

@@ -2,8 +2,11 @@ namespace rerun.archetypes;
 
 /// References a single video frame.
 ///
-/// Used to display video frames from a [archetypes.AssetVideo].
-// TODO(#7368): More docs and examples on how to use this.
+/// Used to display individual video frames from a [archetypes.AssetVideo].
+/// To show an entire video, a fideo frame reference for each frame of the video should be logged.
+///
+/// \example archetypes/video_manual_frames title="Video with explicit frames" image="https://static.rerun.io/video_manual_frames/320a44e1e06b8b3a3161ecbbeae3e04d1ccb9589/1200w.png"
+// TODO(#7368): Example and reference to `send_video_frames` API.
 table VideoFrameReference (
     "attr.rerun.experimental"
 ){
@@ -22,5 +25,9 @@ table VideoFrameReference (
     /// If none is specified, the video is assumed to be at the same entity.
     /// Note that blueprint overrides on the referenced video will be ignored regardless,
     /// as this is always interpreted as a reference to the data store.
+    ///
+    /// For a series of video frame references, it is recommended to specify this path only once
+    /// at the beginning of the series and then rely on latest-at query semantics to
+    /// keep the video reference active.
     video_reference: rerun.components.EntityPath ("attr.rerun.component_optional", nullable, order: 2000);
 }

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

@@ -1,9 +1,21 @@
 use super::VideoTimestamp;
 
 impl VideoTimestamp {
+    /// Create new timestamp from seconds since video start.
+    #[inline]
+    pub fn from_seconds(seconds: f64) -> Self {
+        crate::datatypes::VideoTimestamp::from_nanoseconds((seconds * 1e9) as i64).into()
+    }
+
+    /// Create new timestamp from milliseconds since video start.
+    #[inline]
+    pub fn from_milliseconds(milliseconds: f64) -> Self {
+        crate::datatypes::VideoTimestamp::from_nanoseconds((milliseconds * 1e6) as i64).into()
+    }
+
     /// Create new timestamp from nanoseconds since video start.
     #[inline]
-    pub fn new_nanoseconds(nanos: i64) -> Self {
-        crate::datatypes::VideoTimestamp::new_nanoseconds(nanos).into()
+    pub fn from_nanoseconds(nanos: i64) -> Self {
+        crate::datatypes::VideoTimestamp::from_nanoseconds(nanos).into()
     }
 }

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

@@ -3,7 +3,7 @@ use super::{VideoTimeMode, VideoTimestamp};
 impl VideoTimestamp {
     /// Create new timestamp from nanoseconds since video start.
     #[inline]
-    pub fn new_nanoseconds(nanos: i64) -> Self {
+    pub fn from_nanoseconds(nanos: i64) -> Self {
         Self {
             video_time: nanos,
             time_mode: VideoTimeMode::Nanoseconds,

crates/store/re_types_core/src/archetype.rs

@@ -194,6 +194,18 @@ impl<A: Archetype> GenericIndicatorComponent<A> {
     pub const DEFAULT: Self = Self {
         _phantom: std::marker::PhantomData::<A>,
     };
+
+    /// Create an array of indicator components of this type with the given length.
+    ///
+    /// This can be useful when sending columns of indicators with
+    /// `rerun::RecordingStream::send_columns`.
+    #[inline]
+    pub fn new_array(len: usize) -> GenericIndicatorComponentArray<A> {
+        GenericIndicatorComponentArray {
+            len,
+            _phantom: std::marker::PhantomData::<A>,
+        }
+    }
 }
 
 impl<A: Archetype> Default for GenericIndicatorComponent<A> {
@@ -221,6 +233,37 @@ impl<A: Archetype> crate::LoggableBatch for GenericIndicatorComponent<A> {
 
 impl<A: Archetype> crate::ComponentBatch for GenericIndicatorComponent<A> {}
 
+/// A generic [indicator component] array of a given length.
+///
+/// This can be useful when sending columns of indicators with
+/// `rerun::RecordingStream::send_columns`.
+///
+/// To create this type, call [`GenericIndicatorComponent::new_array`].
+///
+/// [indicator component]: [`Archetype::Indicator`]
+#[derive(Debug, Clone, Copy)]
+pub struct GenericIndicatorComponentArray<A: Archetype> {
+    len: usize,
+    _phantom: std::marker::PhantomData<A>,
+}
+
+impl<A: Archetype> crate::LoggableBatch for GenericIndicatorComponentArray<A> {
+    type Name = ComponentName;
+
+    #[inline]
+    fn name(&self) -> Self::Name {
+        GenericIndicatorComponent::<A>::DEFAULT.name()
+    }
+
+    #[inline]
+    fn to_arrow(&self) -> SerializationResult<Box<dyn arrow2::array::Array>> {
+        let datatype = arrow2::datatypes::DataType::Null;
+        Ok(arrow2::array::NullArray::new(datatype, self.len).boxed())
+    }
+}
+
+impl<A: Archetype> crate::ComponentBatch for GenericIndicatorComponentArray<A> {}
+
 // ---
 
 /// An arbitrary named [indicator component].

docs/snippets/all/archetypes/asset3d_simple.cpp

@@ -2,9 +2,7 @@
 
 #include <rerun.hpp>
 
-#include <filesystem>
 #include <iostream>
-#include <string>
 
 int main(int argc, char* argv[]) {
     if (argc < 2) {