From 91a27f51ebf38442dd39dfca1e62c21314d69535 Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Fri, 28 Jun 2024 19:18:39 +0200 Subject: [PATCH 01/12] Add a "Visualizers and Overrides" concept page --- .../concepts/visualizers-and-overrides.md | 111 ++++++++++++++++++ docs/snippets/all/concepts/viscomp-base.py | 12 ++ .../all/concepts/viscomp-component-default.py | 22 ++++ .../concepts/viscomp-component-override.py | 21 ++++ .../concepts/viscomp-visualizer-override.py | 23 ++++ docs/snippets/snippets.toml | 7 +- 6 files changed, 194 insertions(+), 2 deletions(-) create mode 100644 docs/content/concepts/visualizers-and-overrides.md create mode 100644 docs/snippets/all/concepts/viscomp-base.py create mode 100644 docs/snippets/all/concepts/viscomp-component-default.py create mode 100644 docs/snippets/all/concepts/viscomp-component-override.py create mode 100644 docs/snippets/all/concepts/viscomp-visualizer-override.py diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md new file mode 100644 index 000000000000..2ef7549126b2 --- /dev/null +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -0,0 +1,111 @@ +--- +title: Visualizer and Overrides +order: 650 +--- + +This section explains the process by which logged data is used to produce a visualization and how it can be customized via the user interface or code. + +*Note*: this area is under heavy development and subject to changes in future releases. + +## How are visualizations produced? + +[![image.png](https://i.postimg.cc/FRjRzX5g/image.png)](https://postimg.cc/47xZ2M3m) + +In the Rerun viewer, visualizations happen within _views_, which are defined by their [_blueprint_](blueprint.md). + +The first step for a view to display its content is to determine which entities are involved. This is determined +by the [entity query](../reference/entity-queries.md), which is part of the view blueprint. The query is run against the data store to generate the list of view entities. + +Views rely on visualizers to display each of their entities. For example, [3D views](../reference/types/views/spatial3d_view.md) use the `Points3D` visualizer to display 3D point clouds, and [time series views](../reference/types/views/time_series_view.md) use the `SeriesLine` visualizer to display time series line plots. Which visualizers are available is highly dependent on the specific kind of view. For example, the `SeriesLine` visualizer only exist for time series views—not, e.g., 3D views. + +For a given view, visualizers are selected for each of its entities based on their content. For example, in a 3D view, an entity containing a [`Position3D`](../reference/types/components/position3d.md) results in a `Points3D` visualizer being selected by default. (We will see that the visualizer selection process can be influenced by both the user interface and the blueprints.) + +Then, each selected visualizer determines the values for the components it supports. For example, the `Points3D` visualizer handles, among others, the [`Position3D`](../reference/types/components/position3d.md), [`Radius`](../reference/types/components/radius.md), and [`Color`](../reference/types/components/color.md) components. For each of these (and the others it also supports), the visualizer must determine a value. By default, it will use the value that was logged to the data store, if any. Otherwise, it will use some fallback value that + depends on the actual type of visualizer and view. (Again, we will see that this can be influenced by the user interface and the blueprint.) + +For an illustration, let's consider a simple example with just two [`Boxes2D`](../reference/types/archetypes/boxes2d.md): + +snippet: concepts/viscomp-base + +Here is how the user interface represents the `Boxes2D` visualizers in the selection panel, when the corresponding entity is selected: + + + + +All components used by the visualizer are represented, along with their corresponding values as determined by the visualizer. For the [`Color`](../reference/types/components/color.md) component, we can see both the store and fallback values, the former taking precedence over the latter. + + + +## Per-entity component override + +[![image.png](https://i.postimg.cc/s2t2cD4R/image.png)](https://postimg.cc/f3fZWsPH) + +To customize a visualization, the blueprint may override any component value for any view entity. This can be achieved either from the user interface or the logging SDK. When such an override is defined, it takes precedence over any value that might have been logged to the data store. + +This is how it is achieved with the blueprint API: + +snippet: concepts/viscomp-component-override + +The color of `/boxes/1` is overridden to green. Here is how the user interface represents the corresponding visualizer: + + + +The override is listed above the store and fallback value since it has precedence. It can also be edited or removed from the user interface. + + +## Per-view component default + +[![image.png](https://i.postimg.cc/prK2Wg4b/image.png)](https://postimg.cc/tnC0Dm92) + +The blueprint may also specify a default value for all components of a given type, should their value not be logged to the store or overridden for a given view entity. This makes it easy to configure visual properties for a potentially large number of entities a view may contain. + +This is how it is achieved with the blueprint API: + +snippet: concepts/viscomp-component-default + +Here, the `/boxes/2` entity is no longer logged with a color value, but a default color is added to the blueprint. Here is how the user interface represents its visualizer: + + + +The default color value is displayed above the fallback since it takes precedence. It can also be edited or removed from the user interface. + +All component default values are displayed in the selection panel when selecting the corresponding view: + +image + +Again, it is possible to manually add, edit, and remove component defaults from the user interface. + + +## Component value resolution order + +The previous sections showed that visualizers use a variety of sources to determine the values of the components they are interested in. Here is a summary of the priority order: + +1. **Override**: the per-entity override (the highest priority) +2. **Store**: the value that was logged to the data store (e.g., with the `rr.log()` API) +3. **Default**: the default value for this component type +4. **Fallback**: a context-specific fallback value which may depend on the specific visualizer and view type (the lowest priority) + +As an illustration, all four values are available for the `/boxes/1` entity of the previous example. Here is how its visualizer is represented in the user interface: + + + + +## Visualizer override + +So far, we discussed how visualizers determine values for the components they are interested in and how this can be customized. This section instead discusses the process of how visualizers themselves are determined and how to override this process. + +⚠️NOTE: the feature covered by this section, including its API, is very likely to change in future releases. TODO: link to GH issue. + +[![image.png](https://i.postimg.cc/rzXWP2XD/image.png)](https://postimg.cc/SYdJn5K4) + +In the previous examples, because [`Boxes2D`](../reference/types/archetypes/boxes2d.md) archetypes were used for logging then entities, `Boxes2D` visualizers were automatically selected. A key factor driving this behavior is the `Boxes2DIndicator` component, which is a data-less marker automatically inserted by the corresponding `Boxes2D` archetype. This is, however, not the only visualizer capable of displaying these entities. The `Point2D` visualizer can also be used, since it only requires [`Position2D`](../reference/types/components/position2d.md) components. + +Here is how to force a `Points2D` visualizer for `/boxes/1`, instead of the default `Boxes2D` visualizer: + +snippet: concepts/viscomp-visualizer-override + +The view now displays a point instead of the box. Here is how the visualizer is displayed in the user interface (note the visualizer of type `Points2D`): + + + +It is possible to add and remove visualizers from the user interface. It is also possible to have multiple visualizers for the same view entity. For example, if both a `Points2D` and `Boxes2D` visualizers are defined in this example, both a box and a point will be displayed. \ No newline at end of file diff --git a/docs/snippets/all/concepts/viscomp-base.py b/docs/snippets/all/concepts/viscomp-base.py new file mode 100644 index 000000000000..68660b3610b3 --- /dev/null +++ b/docs/snippets/all/concepts/viscomp-base.py @@ -0,0 +1,12 @@ +"""Base example.""" + +import rerun as rr +import rerun.blueprint as rrb + +rr.init("rerun_example_component_override", spawn=True) + +# Data logged to the data store. +rr.log("boxes/1", rr.Boxes2D(centers=[0, 0], sizes=[1, 1], colors=[255, 0, 0])) +rr.log("boxes/2", rr.Boxes2D(centers=[2, 0], sizes=[1, 1], colors=[255, 0, 0])) + +rr.send_blueprint(rrb.Spatial2DView()) diff --git a/docs/snippets/all/concepts/viscomp-component-default.py b/docs/snippets/all/concepts/viscomp-component-default.py new file mode 100644 index 000000000000..1dd3b53aa938 --- /dev/null +++ b/docs/snippets/all/concepts/viscomp-component-default.py @@ -0,0 +1,22 @@ +"""Add a component default.""" + +import rerun as rr +import rerun.blueprint as rrb + +rr.init("rerun_example_component_override", spawn=True) + +# Data logged to the data store. +rr.log("boxes/1", rr.Boxes2D(centers=[0, 0], sizes=[1, 1], colors=[255, 0, 0])) +rr.log("boxes/2", rr.Boxes2D(centers=[2, 0], sizes=[1, 1])) + +rr.send_blueprint( + rrb.Spatial2DView( + overrides={ + "boxes/1": [ + rr.components.Color([0, 255, 0]), + ] + }, + # Add a default value for all Color components in this view + defaults=[rr.components.Color([0, 0, 255])], + ), +) diff --git a/docs/snippets/all/concepts/viscomp-component-override.py b/docs/snippets/all/concepts/viscomp-component-override.py new file mode 100644 index 000000000000..bac270ad3f6a --- /dev/null +++ b/docs/snippets/all/concepts/viscomp-component-override.py @@ -0,0 +1,21 @@ +"""Override a component.""" + +import rerun as rr +import rerun.blueprint as rrb + +rr.init("rerun_example_component_override", spawn=True) + +# Data logged to the data store. +rr.log("boxes/1", rr.Boxes2D(centers=[0, 0], sizes=[1, 1], colors=[255, 0, 0])) +rr.log("boxes/2", rr.Boxes2D(centers=[2, 0], sizes=[1, 1], colors=[255, 0, 0])) + +rr.send_blueprint( + rrb.Spatial2DView( + # Override the values from the data store for the first box. + overrides={ + "boxes/1": [ + rr.components.Color([0, 255, 0]), + ] + }, + ), +) diff --git a/docs/snippets/all/concepts/viscomp-visualizer-override.py b/docs/snippets/all/concepts/viscomp-visualizer-override.py new file mode 100644 index 000000000000..9ce689515a6f --- /dev/null +++ b/docs/snippets/all/concepts/viscomp-visualizer-override.py @@ -0,0 +1,23 @@ +"""Override a visualizer.""" + +import rerun as rr +import rerun.blueprint as rrb + +rr.init("rerun_example_component_override", spawn=True) + +# Data logged to the data store. +rr.log("boxes/1", rr.Boxes2D(centers=[0, 0], sizes=[1, 1], colors=[255, 0, 0])) +rr.log("boxes/2", rr.Boxes2D(centers=[2, 0], sizes=[1, 1])) + +rr.send_blueprint( + rrb.Spatial2DView( + overrides={ + "boxes/1": [ + # Specify which visualizer(s) to use. + rrb.VisualizerOverrides(rrb.visualizers.Points2D), + rr.components.Color([0, 255, 0]), + ] + }, + defaults=[rr.components.Color([0, 0, 255])], + ), +) diff --git a/docs/snippets/snippets.toml b/docs/snippets/snippets.toml index 2b2ac4a2fffa..4eda8c027275 100644 --- a/docs/snippets/snippets.toml +++ b/docs/snippets/snippets.toml @@ -6,8 +6,11 @@ # for one or more specific SDKs. [opt_out.run] "archetypes/image_advanced" = ["cpp", "rust"] # Missing examples - -"tutorials/annotation-context" = [ # Not a complete examples +"concetps/viscomp-base" = ["cpp", "rust"] # Blueprint API doesn't exist for C++/Rust +"concetps/viscomp-component-default" = ["cpp", "rust"] # Blueprint API doesn't exist for C++/Rust +"concetps/viscomp-component-override" = ["cpp", "rust"] # Blueprint API doesn't exist for C++/Rust +"concetps/viscomp-visualizer-override" = ["cpp", "rust"] # Blueprint API doesn't exist for C++/Rustt +"tutorials/annotation-context" = [ # Not a complete example "cpp", "rust", "py", From 3e90a7e5024bf556f4dc6dae091be2fd504542be Mon Sep 17 00:00:00 2001 From: jprochazk <1665677+jprochazk@users.noreply.github.com> Date: Fri, 28 Jun 2024 23:23:54 +0200 Subject: [PATCH 02/12] trigger ci From 637c5ae52810cc5433823e3b1381d45be9432eac Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Mon, 1 Jul 2024 10:45:04 +0200 Subject: [PATCH 03/12] Address jeremy's feedback --- .../concepts/visualizers-and-overrides.md | 18 ++++++++++--- .../viscomp-visualizer-override-multiple.py | 26 +++++++++++++++++++ .../concepts/viscomp-visualizer-override.py | 2 +- 3 files changed, 41 insertions(+), 5 deletions(-) create mode 100644 docs/snippets/all/concepts/viscomp-visualizer-override-multiple.py diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md index 2ef7549126b2..66f62060dbc3 100644 --- a/docs/content/concepts/visualizers-and-overrides.md +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -18,7 +18,13 @@ by the [entity query](../reference/entity-queries.md), which is part of the view Views rely on visualizers to display each of their entities. For example, [3D views](../reference/types/views/spatial3d_view.md) use the `Points3D` visualizer to display 3D point clouds, and [time series views](../reference/types/views/time_series_view.md) use the `SeriesLine` visualizer to display time series line plots. Which visualizers are available is highly dependent on the specific kind of view. For example, the `SeriesLine` visualizer only exist for time series views—not, e.g., 3D views. -For a given view, visualizers are selected for each of its entities based on their content. For example, in a 3D view, an entity containing a [`Position3D`](../reference/types/components/position3d.md) results in a `Points3D` visualizer being selected by default. (We will see that the visualizer selection process can be influenced by both the user interface and the blueprints.) + +For a given view, visualizers are selected for each of its entities based on their content. +By default, visualizers are selected for entities logged with a corresponding archetype. +For example, in a 3D view, an entity logged with the [`PointsD`](../reference/types/archetypes/points3d.md) results in the `Points3D` visualizer being selected by default. +This happens because archetypes include an _indicator component_ to capture the intent of the logging code. +This indicator component in turn triggers the default activation of the associated visualizer. +(We will see that this process can be influenced by both the user interface and the blueprints.) Then, each selected visualizer determines the values for the components it supports. For example, the `Points3D` visualizer handles, among others, the [`Position3D`](../reference/types/components/position3d.md), [`Radius`](../reference/types/components/radius.md), and [`Color`](../reference/types/components/color.md) components. For each of these (and the others it also supports), the visualizer must determine a value. By default, it will use the value that was logged to the data store, if any. Otherwise, it will use some fallback value that depends on the actual type of visualizer and view. (Again, we will see that this can be influenced by the user interface and the blueprint.) @@ -29,7 +35,7 @@ snippet: concepts/viscomp-base Here is how the user interface represents the `Boxes2D` visualizers in the selection panel, when the corresponding entity is selected: - +basic exampleE All components used by the visualizer are represented, along with their corresponding values as determined by the visualizer. For the [`Color`](../reference/types/components/color.md) component, we can see both the store and fallback values, the former taking precedence over the latter. @@ -65,7 +71,7 @@ snippet: concepts/viscomp-component-default Here, the `/boxes/2` entity is no longer logged with a color value, but a default color is added to the blueprint. Here is how the user interface represents its visualizer: - +component override example The default color value is displayed above the fallback since it takes precedence. It can also be edited or removed from the user interface. @@ -108,4 +114,8 @@ The view now displays a point instead of the box. Here is how the visualizer is -It is possible to add and remove visualizers from the user interface. It is also possible to have multiple visualizers for the same view entity. For example, if both a `Points2D` and `Boxes2D` visualizers are defined in this example, both a box and a point will be displayed. \ No newline at end of file +It is also possible to have _multiple_ visualizers for the same view entity by using an array: + +snippet: concepts/viscomp-visualizer-override-multiple + +In this case, both a box and a point will be displayed. Adding and removing visualizers is also possible from the user interface. diff --git a/docs/snippets/all/concepts/viscomp-visualizer-override-multiple.py b/docs/snippets/all/concepts/viscomp-visualizer-override-multiple.py new file mode 100644 index 000000000000..ca162d30aad8 --- /dev/null +++ b/docs/snippets/all/concepts/viscomp-visualizer-override-multiple.py @@ -0,0 +1,26 @@ +"""Override a visualizer.""" + +import rerun as rr +import rerun.blueprint as rrb + +rr.init("rerun_example_component_override", spawn=True) + +# Data logged to the data store. +rr.log("boxes/1", rr.Boxes2D(centers=[0, 0], sizes=[1, 1], colors=[255, 0, 0])) +rr.log("boxes/2", rr.Boxes2D(centers=[2, 0], sizes=[1, 1])) + +rr.send_blueprint( + rrb.Spatial2DView( + overrides={ + "boxes/1": [ + # Specify multiple visualizers + rrb.VisualizerOverrides([ + rrb.visualizers.Boxes2D, + rrb.visualizers.Points2D, + ]), + rr.components.Color([0, 255, 0]), + ] + }, + defaults=[rr.components.Color([0, 0, 255])], + ), +) diff --git a/docs/snippets/all/concepts/viscomp-visualizer-override.py b/docs/snippets/all/concepts/viscomp-visualizer-override.py index 9ce689515a6f..2e3f48d5a69c 100644 --- a/docs/snippets/all/concepts/viscomp-visualizer-override.py +++ b/docs/snippets/all/concepts/viscomp-visualizer-override.py @@ -13,7 +13,7 @@ rrb.Spatial2DView( overrides={ "boxes/1": [ - # Specify which visualizer(s) to use. + # Specify which visualizer to use. rrb.VisualizerOverrides(rrb.visualizers.Points2D), rr.components.Color([0, 255, 0]), ] From fea85849dd3f44fe0f9559e7a38f5c8cbb2a4e0f Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Mon, 1 Jul 2024 11:04:06 +0200 Subject: [PATCH 04/12] Added info on indicator components in archetypes.md and added links to it --- crates/re_types_builder/src/codegen/docs/mod.rs | 8 +++++++- docs/content/concepts/entity-component.md | 3 ++- docs/content/concepts/visualizers-and-overrides.md | 4 ++-- docs/content/reference/types/archetypes.md | 8 +++++++- 4 files changed, 18 insertions(+), 5 deletions(-) diff --git a/crates/re_types_builder/src/codegen/docs/mod.rs b/crates/re_types_builder/src/codegen/docs/mod.rs index fcd8673bdbbd..a9fc8b6505cf 100644 --- a/crates/re_types_builder/src/codegen/docs/mod.rs +++ b/crates/re_types_builder/src/codegen/docs/mod.rs @@ -85,7 +85,13 @@ impl CodeGenerator for DocsCodeGenerator { ( ObjectKind::Archetype, 1, - "Archetypes are bundles of components. This page lists all built-in components.", + r"Archetypes are bundles of components for which the Rerun viewer has first-class +built-in support. When logged, each archetype also includes an _indicator component_ which captures +the intent of the logging code and triggers the activation of the corresponding visualizers. See +[Entities and Compponents](../../concepts/entity-component.md) and +[Visualizers and Overrides](../../concepts/visualizers-and-overrides.md) for more information., + +This page lists all built-in archetypes.", &archetypes, ), ( diff --git a/docs/content/concepts/entity-component.md b/docs/content/concepts/entity-component.md index 16554660a7c1..13f8df89cb80 100644 --- a/docs/content/concepts/entity-component.md +++ b/docs/content/concepts/entity-component.md @@ -37,7 +37,8 @@ Later, the Space View for spatial types queries the data store for all the entit In this case it would find the "my_point" entity. This query additionally returns the `Color` component because that component is associated with the same entity. These two components are recognized as corresponding to the `Points2D` archetype, which informs the Viewer on how to display the corresponding entity. -See the [Types](../reference/types.md) reference for a list of archetypes, components, and datatypes. +See the [Types](../reference/types.md) reference for a list of [archetypes](../reference/types/archetypes.md), +[components](../reference/types/components.md), and [datatypes](../reference/types/datatypes.md). ### Adding custom data diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md index 66f62060dbc3..4b953888cecb 100644 --- a/docs/content/concepts/visualizers-and-overrides.md +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -20,9 +20,9 @@ Views rely on visualizers to display each of their entities. For example, [3D vi For a given view, visualizers are selected for each of its entities based on their content. -By default, visualizers are selected for entities logged with a corresponding archetype. +By default, visualizers are selected for entities logged with a corresponding [archetype](../reference/types/archetypes.md). For example, in a 3D view, an entity logged with the [`PointsD`](../reference/types/archetypes/points3d.md) results in the `Points3D` visualizer being selected by default. -This happens because archetypes include an _indicator component_ to capture the intent of the logging code. +This happens because [archetypes](../reference/types/archetypes.md) include an _indicator component_ to capture the intent of the logging code. This indicator component in turn triggers the default activation of the associated visualizer. (We will see that this process can be influenced by both the user interface and the blueprints.) diff --git a/docs/content/reference/types/archetypes.md b/docs/content/reference/types/archetypes.md index 924fd01d3e7e..d657898e6479 100644 --- a/docs/content/reference/types/archetypes.md +++ b/docs/content/reference/types/archetypes.md @@ -4,7 +4,13 @@ order: 1 --- -Archetypes are bundles of components. This page lists all built-in components. +Archetypes are bundles of components for which the Rerun viewer has first-class +built-in support. When logged, each archetype also includes an _indicator component_ which captures +the intent of the logging code and triggers the activation of the corresponding visualizers. See +[Entities and Compponents](../../concepts/entity-component.md) and +[Visualizers and Overrides](../../concepts/visualizers-and-overrides.md) for more information., + +This page lists all built-in archetypes. ## Image & tensor From 6fb27d830f249706b58803c2779dda43564060ef Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Mon, 1 Jul 2024 11:12:23 +0200 Subject: [PATCH 05/12] Lints --- .../concepts/visualizers-and-overrides.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md index 4b953888cecb..4eb0827265f0 100644 --- a/docs/content/concepts/visualizers-and-overrides.md +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -13,17 +13,17 @@ This section explains the process by which logged data is used to produce a visu In the Rerun viewer, visualizations happen within _views_, which are defined by their [_blueprint_](blueprint.md). -The first step for a view to display its content is to determine which entities are involved. This is determined -by the [entity query](../reference/entity-queries.md), which is part of the view blueprint. The query is run against the data store to generate the list of view entities. +The first step for a view to display its content is to determine which entities are involved. +This is determined by the [entity query](../reference/entity-queries.md), which is part of the view blueprint. +The query is run against the data store to generate the list of view entities. Views rely on visualizers to display each of their entities. For example, [3D views](../reference/types/views/spatial3d_view.md) use the `Points3D` visualizer to display 3D point clouds, and [time series views](../reference/types/views/time_series_view.md) use the `SeriesLine` visualizer to display time series line plots. Which visualizers are available is highly dependent on the specific kind of view. For example, the `SeriesLine` visualizer only exist for time series views—not, e.g., 3D views. - For a given view, visualizers are selected for each of its entities based on their content. By default, visualizers are selected for entities logged with a corresponding [archetype](../reference/types/archetypes.md). For example, in a 3D view, an entity logged with the [`PointsD`](../reference/types/archetypes/points3d.md) results in the `Points3D` visualizer being selected by default. This happens because [archetypes](../reference/types/archetypes.md) include an _indicator component_ to capture the intent of the logging code. -This indicator component in turn triggers the default activation of the associated visualizer. +This indicator component in turn triggers the default activation of the associated visualizer. (We will see that this process can be influenced by both the user interface and the blueprints.) Then, each selected visualizer determines the values for the components it supports. For example, the `Points3D` visualizer handles, among others, the [`Position3D`](../reference/types/components/position3d.md), [`Radius`](../reference/types/components/radius.md), and [`Color`](../reference/types/components/color.md) components. For each of these (and the others it also supports), the visualizer must determine a value. By default, it will use the value that was logged to the data store, if any. Otherwise, it will use some fallback value that @@ -45,8 +45,10 @@ All components used by the visualizer are represented, along with their correspo ## Per-entity component override [![image.png](https://i.postimg.cc/s2t2cD4R/image.png)](https://postimg.cc/f3fZWsPH) - -To customize a visualization, the blueprint may override any component value for any view entity. This can be achieved either from the user interface or the logging SDK. When such an override is defined, it takes precedence over any value that might have been logged to the data store. + +To customize a visualization, the blueprint may override any component value for any view entity. +This can be achieved either from the user interface or the logging SDK. +When such an override is defined, it takes precedence over any value that might have been logged to the data store. This is how it is achieved with the blueprint API: @@ -63,7 +65,7 @@ The override is listed above the store and fallback value since it has precedenc [![image.png](https://i.postimg.cc/prK2Wg4b/image.png)](https://postimg.cc/tnC0Dm92) -The blueprint may also specify a default value for all components of a given type, should their value not be logged to the store or overridden for a given view entity. This makes it easy to configure visual properties for a potentially large number of entities a view may contain. +The blueprint may also specify a default value for all components of a given type, should their value not be logged to the store or overridden for a given view entity. This makes it easy to configure visual properties for a potentially large number of entities a view may contain. This is how it is achieved with the blueprint API: @@ -100,7 +102,8 @@ As an illustration, all four values are available for the `/boxes/1` entity of t So far, we discussed how visualizers determine values for the components they are interested in and how this can be customized. This section instead discusses the process of how visualizers themselves are determined and how to override this process. -⚠️NOTE: the feature covered by this section, including its API, is very likely to change in future releases. TODO: link to GH issue. +⚠️NOTE: the feature covered by this section, including its API, is very likely to change in future releases +(relevant [issue](https://github.com/rerun-io/rerun/issues/6626)). [![image.png](https://i.postimg.cc/rzXWP2XD/image.png)](https://postimg.cc/SYdJn5K4) From a66832df4945525a36ca10c8cddfe47899377a06 Mon Sep 17 00:00:00 2001 From: Antoine Beyeler <49431240+abey79@users.noreply.github.com> Date: Mon, 1 Jul 2024 14:29:49 +0200 Subject: [PATCH 06/12] Update docs/content/concepts/visualizers-and-overrides.md Co-authored-by: Clement Rey --- docs/content/concepts/visualizers-and-overrides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md index 4eb0827265f0..b4eaad5b3d18 100644 --- a/docs/content/concepts/visualizers-and-overrides.md +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -21,7 +21,7 @@ Views rely on visualizers to display each of their entities. For example, [3D vi For a given view, visualizers are selected for each of its entities based on their content. By default, visualizers are selected for entities logged with a corresponding [archetype](../reference/types/archetypes.md). -For example, in a 3D view, an entity logged with the [`PointsD`](../reference/types/archetypes/points3d.md) results in the `Points3D` visualizer being selected by default. +For example, in a 3D view, an entity logged with the [`Points3D`](../reference/types/archetypes/points3d.md) results in the `Points3D` visualizer being selected by default. This happens because [archetypes](../reference/types/archetypes.md) include an _indicator component_ to capture the intent of the logging code. This indicator component in turn triggers the default activation of the associated visualizer. (We will see that this process can be influenced by both the user interface and the blueprints.) From 0080331548c90ffe9a4a590227404b3b4ac2121e Mon Sep 17 00:00:00 2001 From: Antoine Beyeler <49431240+abey79@users.noreply.github.com> Date: Mon, 1 Jul 2024 14:29:59 +0200 Subject: [PATCH 07/12] Update docs/content/reference/types/archetypes.md Co-authored-by: Clement Rey --- docs/content/reference/types/archetypes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/reference/types/archetypes.md b/docs/content/reference/types/archetypes.md index d657898e6479..f80dcca99de5 100644 --- a/docs/content/reference/types/archetypes.md +++ b/docs/content/reference/types/archetypes.md @@ -8,7 +8,7 @@ Archetypes are bundles of components for which the Rerun viewer has first-class built-in support. When logged, each archetype also includes an _indicator component_ which captures the intent of the logging code and triggers the activation of the corresponding visualizers. See [Entities and Compponents](../../concepts/entity-component.md) and -[Visualizers and Overrides](../../concepts/visualizers-and-overrides.md) for more information., +[Visualizers and Overrides](../../concepts/visualizers-and-overrides.md) for more information. This page lists all built-in archetypes. From 4c8bda49bb486cf13526068a326cb49d42c17a7d Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Mon, 1 Jul 2024 15:44:23 +0200 Subject: [PATCH 08/12] final screenshot + design --- .../concepts/visualizers-and-overrides.md | 39 +++++++++++++++---- 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md index b4eaad5b3d18..9f5d39ce7191 100644 --- a/docs/content/concepts/visualizers-and-overrides.md +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -35,7 +35,10 @@ snippet: concepts/viscomp-base Here is how the user interface represents the `Boxes2D` visualizers in the selection panel, when the corresponding entity is selected: -basic exampleE + + + + All components used by the visualizer are represented, along with their corresponding values as determined by the visualizer. For the [`Color`](../reference/types/components/color.md) component, we can see both the store and fallback values, the former taking precedence over the latter. @@ -56,7 +59,10 @@ snippet: concepts/viscomp-component-override The color of `/boxes/1` is overridden to green. Here is how the user interface represents the corresponding visualizer: - + + + + The override is listed above the store and fallback value since it has precedence. It can also be edited or removed from the user interface. @@ -73,13 +79,19 @@ snippet: concepts/viscomp-component-default Here, the `/boxes/2` entity is no longer logged with a color value, but a default color is added to the blueprint. Here is how the user interface represents its visualizer: -component override example + + + + The default color value is displayed above the fallback since it takes precedence. It can also be edited or removed from the user interface. All component default values are displayed in the selection panel when selecting the corresponding view: -image + + + + Again, it is possible to manually add, edit, and remove component defaults from the user interface. @@ -95,7 +107,10 @@ The previous sections showed that visualizers use a variety of sources to determ As an illustration, all four values are available for the `/boxes/1` entity of the previous example. Here is how its visualizer is represented in the user interface: - + + + + ## Visualizer override @@ -105,7 +120,14 @@ So far, we discussed how visualizers determine values for the components they ar ⚠️NOTE: the feature covered by this section, including its API, is very likely to change in future releases (relevant [issue](https://github.com/rerun-io/rerun/issues/6626)). -[![image.png](https://i.postimg.cc/rzXWP2XD/image.png)](https://postimg.cc/SYdJn5K4) + + + + + + + + In the previous examples, because [`Boxes2D`](../reference/types/archetypes/boxes2d.md) archetypes were used for logging then entities, `Boxes2D` visualizers were automatically selected. A key factor driving this behavior is the `Boxes2DIndicator` component, which is a data-less marker automatically inserted by the corresponding `Boxes2D` archetype. This is, however, not the only visualizer capable of displaying these entities. The `Point2D` visualizer can also be used, since it only requires [`Position2D`](../reference/types/components/position2d.md) components. @@ -115,7 +137,10 @@ snippet: concepts/viscomp-visualizer-override The view now displays a point instead of the box. Here is how the visualizer is displayed in the user interface (note the visualizer of type `Points2D`): - + + + + It is also possible to have _multiple_ visualizers for the same view entity by using an array: From 0542883689479ee8aee049b87686623576791dd2 Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Mon, 1 Jul 2024 15:55:44 +0200 Subject: [PATCH 09/12] final screenshot + designs --- .../concepts/visualizers-and-overrides.md | 26 ++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md index 9f5d39ce7191..dd99e12adf9c 100644 --- a/docs/content/concepts/visualizers-and-overrides.md +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -9,7 +9,15 @@ This section explains the process by which logged data is used to produce a visu ## How are visualizations produced? -[![image.png](https://i.postimg.cc/FRjRzX5g/image.png)](https://postimg.cc/47xZ2M3m) + + + + + + + + + In the Rerun viewer, visualizations happen within _views_, which are defined by their [_blueprint_](blueprint.md). @@ -47,7 +55,13 @@ All components used by the visualizer are represented, along with their correspo ## Per-entity component override -[![image.png](https://i.postimg.cc/s2t2cD4R/image.png)](https://postimg.cc/f3fZWsPH) + + + + + + + To customize a visualization, the blueprint may override any component value for any view entity. This can be achieved either from the user interface or the logging SDK. @@ -69,7 +83,13 @@ The override is listed above the store and fallback value since it has precedenc ## Per-view component default -[![image.png](https://i.postimg.cc/prK2Wg4b/image.png)](https://postimg.cc/tnC0Dm92) + + + + + + + The blueprint may also specify a default value for all components of a given type, should their value not be logged to the store or overridden for a given view entity. This makes it easy to configure visual properties for a potentially large number of entities a view may contain. From f3d11cf00bdefa76ca85af2e038299009a272137 Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Tue, 2 Jul 2024 08:59:04 +0200 Subject: [PATCH 10/12] updated figure + review fixes --- docs/content/concepts/blueprint.md | 2 +- .../concepts/visualizers-and-overrides.md | 52 ++++++++++--------- 2 files changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/content/concepts/blueprint.md b/docs/content/concepts/blueprint.md index 5dd6d40c3fb3..d345f23ab021 100644 --- a/docs/content/concepts/blueprint.md +++ b/docs/content/concepts/blueprint.md @@ -15,7 +15,7 @@ combine to produce what you see: the "recording" and the "blueprint." - The blueprint is the configuration that determines how the data from the recording is displayed. -Both of these pieces are crucial -- without the recording there is nothing to +Both of these pieces are crucial—without the recording there is nothing to show, and without the blueprint there is no way to show it. Even if you have used Rerun before without explicitly loading a blueprint, the Viewer was actually creating one for you. Without a blueprint, there is literally nothing diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md index dd99e12adf9c..540f0e715fa4 100644 --- a/docs/content/concepts/visualizers-and-overrides.md +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -12,11 +12,11 @@ This section explains the process by which logged data is used to produce a visu - - - - - + + + + + In the Rerun viewer, visualizations happen within _views_, which are defined by their [_blueprint_](blueprint.md). @@ -25,17 +25,21 @@ The first step for a view to display its content is to determine which entities This is determined by the [entity query](../reference/entity-queries.md), which is part of the view blueprint. The query is run against the data store to generate the list of view entities. -Views rely on visualizers to display each of their entities. For example, [3D views](../reference/types/views/spatial3d_view.md) use the `Points3D` visualizer to display 3D point clouds, and [time series views](../reference/types/views/time_series_view.md) use the `SeriesLine` visualizer to display time series line plots. Which visualizers are available is highly dependent on the specific kind of view. For example, the `SeriesLine` visualizer only exist for time series views—not, e.g., 3D views. +Views rely on visualizers to display each of their entities. +For example, [3D views](../reference/types/views/spatial3d_view.md) use the `Points3D` visualizer to display 3D point clouds, +and [time series views](../reference/types/views/time_series_view.md) use the `SeriesLine` visualizer to display time series line plots. +Which visualizers are available is highly dependent on the specific kind of view. +For example, the `SeriesLine` visualizer only exist for time series views—not, e.g., for 3D views. For a given view, visualizers are selected for each of its entities based on their content. By default, visualizers are selected for entities logged with a corresponding [archetype](../reference/types/archetypes.md). -For example, in a 3D view, an entity logged with the [`Points3D`](../reference/types/archetypes/points3d.md) results in the `Points3D` visualizer being selected by default. +For example, in a 3D view, an entity logged with the [`Points3D`](../reference/types/archetypes/points3d.md) archetype results in the `Points3D` visualizer being selected by default. This happens because [archetypes](../reference/types/archetypes.md) include an _indicator component_ to capture the intent of the logging code. This indicator component in turn triggers the default activation of the associated visualizer. (We will see that this process can be influenced by both the user interface and the blueprints.) Then, each selected visualizer determines the values for the components it supports. For example, the `Points3D` visualizer handles, among others, the [`Position3D`](../reference/types/components/position3d.md), [`Radius`](../reference/types/components/radius.md), and [`Color`](../reference/types/components/color.md) components. For each of these (and the others it also supports), the visualizer must determine a value. By default, it will use the value that was logged to the data store, if any. Otherwise, it will use some fallback value that - depends on the actual type of visualizer and view. (Again, we will see that this can be influenced by the user interface and the blueprint.) + depends on the actual type of visualizer and view. For an illustration, let's consider a simple example with just two [`Boxes2D`](../reference/types/archetypes/boxes2d.md): @@ -56,11 +60,11 @@ All components used by the visualizer are represented, along with their correspo ## Per-entity component override - - - - - + + + + + To customize a visualization, the blueprint may override any component value for any view entity. @@ -84,14 +88,14 @@ The override is listed above the store and fallback value since it has precedenc ## Per-view component default - - - - - + + + + + -The blueprint may also specify a default value for all components of a given type, should their value not be logged to the store or overridden for a given view entity. This makes it easy to configure visual properties for a potentially large number of entities a view may contain. +The blueprint may also specify a default value for all components of a given type, should their value not be logged to the store or overridden for a given view entity. This makes it easy to configure visual properties for a potentially large number of entities. This is how it is achieved with the blueprint API: @@ -141,11 +145,11 @@ So far, we discussed how visualizers determine values for the components they ar (relevant [issue](https://github.com/rerun-io/rerun/issues/6626)). - - - - - + + + + + From 1b747045c05668c4fbea18af04e92bde81e3cdb8 Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Tue, 2 Jul 2024 09:02:51 +0200 Subject: [PATCH 11/12] more review fix --- docs/content/concepts/visualizers-and-overrides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/concepts/visualizers-and-overrides.md b/docs/content/concepts/visualizers-and-overrides.md index 540f0e715fa4..9a5c29b855ad 100644 --- a/docs/content/concepts/visualizers-and-overrides.md +++ b/docs/content/concepts/visualizers-and-overrides.md @@ -31,7 +31,7 @@ and [time series views](../reference/types/views/time_series_view.md) use the `S Which visualizers are available is highly dependent on the specific kind of view. For example, the `SeriesLine` visualizer only exist for time series views—not, e.g., for 3D views. -For a given view, visualizers are selected for each of its entities based on their content. +For a given view, each entity's components determine which visualizers are available. By default, visualizers are selected for entities logged with a corresponding [archetype](../reference/types/archetypes.md). For example, in a 3D view, an entity logged with the [`Points3D`](../reference/types/archetypes/points3d.md) archetype results in the `Points3D` visualizer being selected by default. This happens because [archetypes](../reference/types/archetypes.md) include an _indicator component_ to capture the intent of the logging code. From c7979037fa9500f7f5e58e211ed3e68e6bf01c59 Mon Sep 17 00:00:00 2001 From: Antoine Beyeler Date: Tue, 2 Jul 2024 09:28:27 +0200 Subject: [PATCH 12/12] fix typo in codegen --- crates/re_types_builder/src/codegen/docs/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/re_types_builder/src/codegen/docs/mod.rs b/crates/re_types_builder/src/codegen/docs/mod.rs index a9fc8b6505cf..6310784c46f9 100644 --- a/crates/re_types_builder/src/codegen/docs/mod.rs +++ b/crates/re_types_builder/src/codegen/docs/mod.rs @@ -89,7 +89,7 @@ impl CodeGenerator for DocsCodeGenerator { built-in support. When logged, each archetype also includes an _indicator component_ which captures the intent of the logging code and triggers the activation of the corresponding visualizers. See [Entities and Compponents](../../concepts/entity-component.md) and -[Visualizers and Overrides](../../concepts/visualizers-and-overrides.md) for more information., +[Visualizers and Overrides](../../concepts/visualizers-and-overrides.md) for more information. This page lists all built-in archetypes.", &archetypes,