From ac06d5ec0d36bd99473b9e788e8e88466d5892cf Mon Sep 17 00:00:00 2001 From: Clement Rey Date: Fri, 25 Oct 2024 15:26:25 +0200 Subject: [PATCH] Docs: "How-to: reuse blueprints across languages" (#7886) By popular demand. * Fixes #7858 * DNM: requires #7882 --- docs/content/concepts/blueprint.md | 2 +- .../configure-viewer-through-code.md | 2 +- .../howto/visualization/reuse-blueprints.md | 44 +++++++++++++++++++ docs/content/reference/dataframes.md | 4 +- .../tutorials/visualization/load_blueprint.py | 12 +++++ .../tutorials/visualization/save_blueprint.py | 23 ++++++++++ 6 files changed, 84 insertions(+), 3 deletions(-) create mode 100644 docs/content/howto/visualization/reuse-blueprints.md create mode 100644 docs/snippets/all/tutorials/visualization/load_blueprint.py create mode 100644 docs/snippets/all/tutorials/visualization/save_blueprint.py diff --git a/docs/content/concepts/blueprint.md b/docs/content/concepts/blueprint.md index 6233a3ace4db..3034d82d1134 100644 --- a/docs/content/concepts/blueprint.md +++ b/docs/content/concepts/blueprint.md @@ -1,5 +1,5 @@ --- -title: Blueprint +title: Blueprints order: 600 --- diff --git a/docs/content/howto/visualization/configure-viewer-through-code.md b/docs/content/howto/visualization/configure-viewer-through-code.md index 5ff10d00de1c..75126bae68d8 100644 --- a/docs/content/howto/visualization/configure-viewer-through-code.md +++ b/docs/content/howto/visualization/configure-viewer-through-code.md @@ -1,5 +1,5 @@ --- -title: Configure the Viewer through code +title: Configure the Viewer through code (Blueprints) order: 100 --- diff --git a/docs/content/howto/visualization/reuse-blueprints.md b/docs/content/howto/visualization/reuse-blueprints.md new file mode 100644 index 000000000000..ee4c6f8fcb67 --- /dev/null +++ b/docs/content/howto/visualization/reuse-blueprints.md @@ -0,0 +1,44 @@ +--- +title: Re-use blueprints across sessions and SDKs +order: 150 +--- + +While the [blueprint APIs](configure-viewer-through-code) are currently only available through [🐍 Python](https://ref.rerun.io/docs/python/stable/common/blueprint_apis/), blueprints can be saved to file and then re-logged as needed from any language our SDKs support. + +This enables you to re-use your saved blueprints both from any language we support as well as across different recordings that share a similar-enough structure, and makes it possible to share those blueprints with other users. + +For this you'll need to 1) create a blueprint file and B) _import_ that file when needed. + + +## Creating a blueprint file + +Blueprint files (`.rbl`, by convention) can currently be created in two ways. + +One is to use the Rerun viewer to interactively build the blueprint you want (e.g. by moving panels around, changing view settings, etc), and then using `Menu > Save blueprint` (or the equivalent palette command) to save the blueprint as a file. + +The other is to use the [🐍 Python blueprint API](https://ref.rerun.io/docs/python/stable/common/blueprint_apis/) to programmatically build the blueprint, and then use the [`Blueprint.save`](https://ref.rerun.io/docs/python/0.19.0/common/blueprint_apis/#rerun.blueprint.Blueprint.save) method to save it as a file: + +snippet: tutorials/visualization/save_blueprint + + +## (Re)Using a blueprint file + +There are two ways to re-use a blueprint file. + +The interactive way is to import the blueprint file directly into the Rerun viewer, using either `Menu > Import…` (or the equivalent palette command) or simply by drag-and-dropping the blueprint file into your recording. + +The programmatic way works by calling `log_file_from_path`: +* [🐍 Python `log_file_from_path`](https://ref.rerun.io/docs/python/stable/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) + +This method allows you to log any file that contains data that Rerun understands (in this case, blueprint data) as part of your current recording: + +snippet: tutorials/visualization/load_blueprint + + +## Limitation: dynamic blueprints + +Sometimes, you might need your blueprint to dynamically react to the data you receive at runtime (e.g. you want to create one view per anomaly detected, and there is no way of knowing how many anomalies you're going to detect until the program actually runs). + +The only way to deal with these situations today is to use the [🐍 Python](https://ref.rerun.io/docs/python/stable/common/blueprint_apis/) API. diff --git a/docs/content/reference/dataframes.md b/docs/content/reference/dataframes.md index a9349a8cd994..ede4aaf5a2b0 100644 --- a/docs/content/reference/dataframes.md +++ b/docs/content/reference/dataframes.md @@ -48,7 +48,7 @@ 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. +While the blueprint APIs are currently only available through 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: @@ -64,6 +64,8 @@ Check out the blueprint API and `log_file_from_path` references to learn more: * [πŸ¦€ 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) +You can learn more in our [dedicated page about blueprint re-use](../howto/visualization/reuse-blueprints). + ### Setting up dataframe view manually in the UI diff --git a/docs/snippets/all/tutorials/visualization/load_blueprint.py b/docs/snippets/all/tutorials/visualization/load_blueprint.py new file mode 100644 index 000000000000..8b8df583a816 --- /dev/null +++ b/docs/snippets/all/tutorials/visualization/load_blueprint.py @@ -0,0 +1,12 @@ +"""Demonstrates how to programmatically re-use a blueprint stored in a file.""" + +import sys + +import rerun as rr + +path_to_rbl = sys.argv[1] + +rr.init("rerun_example_reuse_blueprint_file", spawn=True) +rr.log_file_from_path(path_to_rbl) + +# … log some data as usual … diff --git a/docs/snippets/all/tutorials/visualization/save_blueprint.py b/docs/snippets/all/tutorials/visualization/save_blueprint.py new file mode 100644 index 000000000000..6c6896915f92 --- /dev/null +++ b/docs/snippets/all/tutorials/visualization/save_blueprint.py @@ -0,0 +1,23 @@ +"""Craft an example 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.Horizontal( + rrb.Grid( + rrb.BarChartView(name="Bar Chart", origin="/bar_chart"), + rrb.TimeSeriesView( + name="Curves", + origin="/curves", + ), + ), + rrb.TextDocumentView(name="Description", origin="/description"), + column_shares=[3, 1], + ), + rrb.SelectionPanel(state="collapsed"), + rrb.TimePanel(state="collapsed"), +).save("your_blueprint_name", path_to_rbl)