From 3eb08b71c850abcc968211ae5fe20ea95a84c7c6 Mon Sep 17 00:00:00 2001 From: Clement Rey Date: Wed, 23 Oct 2024 09:16:18 +0200 Subject: [PATCH] Finish dataframe reference page (#7865) We were missing a bunch of features and assets to be able to finish this, but now we have it all. --- docs/content/reference/dataframes.md | 43 ++++++++++++++++--- .../snippets/all/reference/dataframe_query.rs | 6 +-- .../all/reference/dataframe_save_blueprint.py | 17 ++++++++ .../all/reference/dataframe_view_query.py | 24 +++++++++++ .../dataframe_view_query_external.cpp | 27 ++++++++++++ .../dataframe_view_query_external.py | 19 ++++++++ .../dataframe_view_query_external.rs | 20 +++++++++ docs/snippets/snippets.toml | 17 +++++++- 8 files changed, 162 insertions(+), 11 deletions(-) create mode 100644 docs/snippets/all/reference/dataframe_save_blueprint.py create mode 100644 docs/snippets/all/reference/dataframe_view_query.py create mode 100644 docs/snippets/all/reference/dataframe_view_query_external.cpp create mode 100644 docs/snippets/all/reference/dataframe_view_query_external.py create mode 100644 docs/snippets/all/reference/dataframe_view_query_external.rs diff --git a/docs/content/reference/dataframes.md b/docs/content/reference/dataframes.md index 469c25ef79a1..e2e83606a7e0 100644 --- a/docs/content/reference/dataframes.md +++ b/docs/content/reference/dataframes.md @@ -21,25 +21,54 @@ For an in-depth introduction to the dataframe API and the possible workflows it ### Using the dataframe API -The following snippet demonstrates how to query the first 10 rows in a Rerun recording: +The following snippet demonstrates how to query the first 10 rows in a Rerun recording using latest-at (i.e. time-aligned) semantics: snippet: reference/dataframe_query Check out the API reference to learn more about all the ways that data can be searched and filtered: * [🐍 Python API reference](https://ref.rerun.io/docs/python/stable/common/dataframe/) -* [🐍 Python example](https://github.com/rerun-io/rerun/blob/c00a9f649fd4463f91620e8e2eac11355b245ac5/examples/python/dataframe_query/dataframe_query.py) -* [🦀 Rust API reference](https://docs.rs/crate/rerun/latest) -* [🦀 Rust example](https://github.com/rerun-io/rerun/blob/c00a9f649fd4463f91620e8e2eac11355b245ac5/examples/rust/dataframe_query/src/main.rs) + * [Example](https://github.com/rerun-io/rerun/blob/c00a9f649fd4463f91620e8e2eac11355b245ac5/examples/python/dataframe_query/dataframe_query.py) +* [🦀 Rust API reference](https://docs.rs/rerun/latest/rerun/dataframe/index.html) + * [Example](https://github.com/rerun-io/rerun/blob/c00a9f649fd4463f91620e8e2eac11355b245ac5/examples/rust/dataframe_query/src/main.rs) ### Using the blueprint API to configure a dataframe view -TODO(cmc): incoming. +The following snippet demonstrates how visualize an entire Rerun recording using latest-at (i.e. time-aligned) semantics by displaying the results in a [dataframe view](types/views/dataframe_view): -Check out the blueprint API reference to learn more about all the ways that data can be searched and filtered: +snippet: reference/dataframe_view_query + + + + + + + + + +#### Aside: re-using blueprint files from other SDKs + +While the blueprint APIs are currently only available in Python, blueprints can be saved and re-logged as needed from any language our SDKs support. + +First, save the blueprint to a file (`.rbl` by convention) using either the viewer (`Menu > Save blueprint`) or the python API: + +snippet: reference/dataframe_save_blueprint + +Then log that blueprint file in addition to the data itself: + +snippet: reference/dataframe_view_query_external + +Check out the blueprint API and `log_file_from_path` references to learn more: * [🐍 Python blueprint API reference](https://ref.rerun.io/docs/python/latest/common/blueprint_apis/) +* [🐍 Python `log_file_from_path`](https://ref.rerun.io/docs/python/latest/common/logging_functions/#rerun.log_file_from_path) +* [🦀 Rust `log_file_from_path`](https://docs.rs/rerun/latest/rerun/struct.RecordingStream.html#method.log_file_from_path) +* [🌊 C++ `log_file_from_path`](https://ref.rerun.io/docs/cpp/stable/classrerun_1_1RecordingStream.html#a20798d7ea74cce5c8174e5cacd0a2c47) ### Setting up dataframe view manually in the UI -TODO(cmc): incoming. +The same [dataframe view](types/views/dataframe_view) shown above can be configured purely from the UI: + + diff --git a/docs/snippets/all/reference/dataframe_query.rs b/docs/snippets/all/reference/dataframe_query.rs index ed3002500955..92f3ef90df7c 100644 --- a/docs/snippets/all/reference/dataframe_query.rs +++ b/docs/snippets/all/reference/dataframe_query.rs @@ -1,7 +1,5 @@ //! Query and display the first 10 rows of a recording. -#![allow(clippy::unwrap_used)] - use rerun::{ dataframe::{QueryCache, QueryEngine, QueryExpression, SparseFillStrategy, Timeline}, ChunkStore, ChunkStoreConfig, VersionPolicy, @@ -18,7 +16,9 @@ fn main() -> Result<(), Box> { path_to_rrd, VersionPolicy::Warn, )?; - let (_, store) = stores.first_key_value().unwrap(); + let Some((_, store)) = stores.first_key_value() else { + return Ok(()); + }; let query_cache = QueryCache::new(store); let query_engine = QueryEngine { diff --git a/docs/snippets/all/reference/dataframe_save_blueprint.py b/docs/snippets/all/reference/dataframe_save_blueprint.py new file mode 100644 index 000000000000..dc85e0bd42d6 --- /dev/null +++ b/docs/snippets/all/reference/dataframe_save_blueprint.py @@ -0,0 +1,17 @@ +"""Craft a blueprint with the python API and save it to a file for future use.""" + +import sys + +import rerun.blueprint as rrb + +path_to_rbl = sys.argv[1] + +rrb.Blueprint( + rrb.DataframeView( + origin="/", + query=rrb.archetypes.DataframeQuery( + timeline="log_time", + apply_latest_at=True, + ), + ), +).save("rerun_example_dataframe_view_query", path_to_rbl) diff --git a/docs/snippets/all/reference/dataframe_view_query.py b/docs/snippets/all/reference/dataframe_view_query.py new file mode 100644 index 000000000000..3d6068fd18fb --- /dev/null +++ b/docs/snippets/all/reference/dataframe_view_query.py @@ -0,0 +1,24 @@ +"""Query and display the first 10 rows of a recording in a dataframe view.""" + +import sys + +import rerun as rr +import rerun.blueprint as rrb + +path_to_rrd = sys.argv[1] + +rr.init("rerun_example_dataframe_view_query", spawn=True) + +rr.log_file_from_path(path_to_rrd) + +blueprint = rrb.Blueprint( + rrb.DataframeView( + origin="/", + query=rrb.archetypes.DataframeQuery( + timeline="log_time", + apply_latest_at=True, + ), + ), +) + +rr.send_blueprint(blueprint) diff --git a/docs/snippets/all/reference/dataframe_view_query_external.cpp b/docs/snippets/all/reference/dataframe_view_query_external.cpp new file mode 100644 index 000000000000..14710a46a9dc --- /dev/null +++ b/docs/snippets/all/reference/dataframe_view_query_external.cpp @@ -0,0 +1,27 @@ +//! Query and display the first 10 rows of a recording in a dataframe view. +//! +//! The blueprint is being loaded from an existing blueprint recording file. + +// ./dataframe_view_query_external /tmp/dna.rrd /tmp/dna.rbl + +#include + +#include + +int main(int argc, char** argv) { + if (argc < 3) { + return 1; + } + + std::string path_to_rrd = argv[1]; + std::string path_to_rbl = argv[2]; + + const auto rec = rerun::RecordingStream("rerun_example_dataframe_view_query_external"); + rec.spawn().exit_on_failure(); + + // Log the files + rec.log_file_from_path(path_to_rrd); + rec.log_file_from_path(path_to_rbl); + + return 0; +} diff --git a/docs/snippets/all/reference/dataframe_view_query_external.py b/docs/snippets/all/reference/dataframe_view_query_external.py new file mode 100644 index 000000000000..cc91fb651f48 --- /dev/null +++ b/docs/snippets/all/reference/dataframe_view_query_external.py @@ -0,0 +1,19 @@ +""" +Query and display the first 10 rows of a recording in a dataframe view. + +The blueprint is being loaded from an existing blueprint recording file. +""" + +# python dataframe_view_query_external.py /tmp/dna.rrd /tmp/dna.rbl + +import sys + +import rerun as rr + +path_to_rrd = sys.argv[1] +path_to_rbl = sys.argv[2] + +rr.init("rerun_example_dataframe_view_query_external", spawn=True) + +rr.log_file_from_path(path_to_rrd) +rr.log_file_from_path(path_to_rbl) diff --git a/docs/snippets/all/reference/dataframe_view_query_external.rs b/docs/snippets/all/reference/dataframe_view_query_external.rs new file mode 100644 index 000000000000..2e13a27cae77 --- /dev/null +++ b/docs/snippets/all/reference/dataframe_view_query_external.rs @@ -0,0 +1,20 @@ +//! Query and display the first 10 rows of a recording in a dataframe view. +//! +//! The blueprint is being loaded from an existing blueprint recording file. + +// cargo r -p snippets -- dataframe_view_query_external /tmp/dna.rrd /tmp/dna.rbl + +fn main() -> Result<(), Box> { + let args = std::env::args().collect::>(); + + let path_to_rrd = &args[1]; + let path_to_rbl = &args[2]; + + let rec = rerun::RecordingStreamBuilder::new("rerun_example_dataframe_view_query_external") + .spawn()?; + + rec.log_file_from_path(path_to_rrd, None /* prefix */, false /* static */)?; + rec.log_file_from_path(path_to_rbl, None /* prefix */, false /* static */)?; + + Ok(()) +} diff --git a/docs/snippets/snippets.toml b/docs/snippets/snippets.toml index 476f30b79ae3..a877b9623605 100644 --- a/docs/snippets/snippets.toml +++ b/docs/snippets/snippets.toml @@ -42,7 +42,22 @@ views = [ "rust", "py", ] -"reference/dataframe_query" = [ # Requires RRD files, which are unstable +"reference/dataframe_query" = [ # No output + "cpp", + "rust", + "py", +] +"reference/dataframe_save_blueprint" = [ # No output + "cpp", + "rust", + "py", +] +"reference/dataframe_view_query" = [ # No output + "cpp", + "rust", + "py", +] +"reference/dataframe_view_query_external" = [ # No output "cpp", "rust", "py",