Skip to content

Commit

Permalink
Reorganize getting-started and blueprint tutorials (rerun-io#5762)
Browse files Browse the repository at this point in the history 
### What

Strips out some gratuitous hierarchy.
Moves the blueprint guides into getting-started.

### 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:
[rerun.io/viewer](https://rerun.io/viewer/pr/5762)
* Using examples from latest `main` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/5762?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/5762?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/5762)
- [Docs
preview](https://rerun.io/preview/214057272e4b01359946488cd8227e689e94fd70/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/214057272e4b01359946488cd8227e689e94fd70/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

---------

Co-authored-by: Antoine Beyeler <[email protected]>
  • Loading branch information
@jleibs @abey79
jleibs and abey79 authored Apr 4, 2024
1 parent a5df691 commit 0d145eb
Show file tree
Hide file tree
Showing 22 changed files with 754 additions and 489 deletions.
92 changes: 92 additions & 0 deletions docs/content/concepts/blueprint.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
---
title: Blueprint
order: 9
---

## Blueprints and Recordings

When you are working with the Rerun viewer, there are two separate pieces that
combine to produce what you see: the "recording" and the "blueprint."

- The recording provides the actual data you are visualizing.
- 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
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
for the viewer to display.

## Loose coupling

The blueprint and the recording are only loosely coupled. Rerun uses the
"application ID" to determine whether a blueprint and a recording should be used
together, but they are not directly linked beyond that.

This means that either can be changed independently of the other. Keeping the
blueprint constant while changing the recording will allow you to compare
different datasets using a consistent set of views. On the other hand, changing
the blueprint while keeping a recording constant will allow you to view the same
data in different ways.

## What the blueprint controls

Every aspect of what the viewer displays is controlled by the blueprint. This
includes the type and content of the different views, the organization and
layout of the different containers, and the configuration and styling properties
of the individual data visualizers.

In general, if you can modify an aspect of how something looks through the
viewer, you are actually modifying the blueprint. (Note that while there may be
some exceptions to this rule at the moment, the intent is to eventually migrate
all state to the blueprint.)

## What is a blueprint

Under the hood, the blueprint is just data. It is represented by a
[time-series ECS](./entity-component.md), just like a recording. The only
difference is that it uses a specific set of blueprint archetypes and a special
blueprint timeline. Note that even though the blueprint may be sent over the
same connection, blueprint data is kept in an isolated store and is not mixed
together with your recording data.

Although the Rerun APIs for working with blueprint may look different from the
regular logging APIs, they are really just syntactic sugar for logging a
collection of blueprint-specific archetypes to a separate blueprint stream.

Furthermore, when you make any change to the viewer in the UI, what is actually
happening is the viewer is creating a new blueprint event and adding it to the
end of the blueprint timeline in the blueprint store.

## Viewer operation

Outside of caching that exists primarily for performance reasons, the viewer
persists very little state frame-to-frame. The goal is for the output of the
viewer to be a deterministic function of the blueprint and the recording.

Every frame, the viewer starts with a minimal context of an "active" blueprint,
and an "active" recording. The viewer then uses the current revision on the
blueprint timeline to query the container and space-view archetypes from the
blueprint store. The space-view archetypes, in turn, specify the paths types
that need to be queried from the recording store in order to render the views.

Any user interactions that modify the blueprint are queued and written back to
the blueprint using the next revision on the blueprint timeline.

## Blueprint architecture motivation

Although this architecture adds some complexity and indirection, the fact that
the viewer stores all of its meaningful frame-to-frame state in a structured
blueprint data-store has several advantages:

- Anything you modify in the viewer can be saved and shared as a blueprint.
- A blueprint can be produced programmatically using just the Rerun SDK without
a dependency on the viewer libraries.
- The blueprint is capable of representing any data that a recording can
represent. This means in the future, blueprint-sourced data overrides will
be just as expressive as any logged data.
- The blueprint is actually stored as a full time-series, simplifying future
implementations of things like snapshots and undo/redo mechanisms.
- Debugging tools for inspecting generic Rerun data can be used to inspect
internal blueprint state.
52 changes: 26 additions & 26 deletions docs/content/concepts/spaces-and-transforms.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,32 +3,33 @@ title: Spaces and Transforms
order: 2
---

## The Definition of Spaces
## The definition of a space

Every Entity in Rerun exists in some *space*. This is at the core of how Rerun organizes the visualizations of the data
that you have logged. In the [Rerun Viewer](../reference/viewer.md) you view data by configuring a *space view*, which is a view
of a set of entities *as seen from a particular space.*
Every entity in Rerun exists in some _space_. This is at the core of how Rerun organizes the visualizations of the data
that you have logged. In the [Rerun Viewer](../reference/viewer.md) you view data by configuring a _space view_, which is a view
of a set of entities _as seen from a particular origin._

A space is, very loosely, a generalization of the idea of a "coordinate system" (sometimes known as a "coordinate frame") to arbitrary data. If a collection of
entities are part of the same space, it means they can be rendered together in the same "coordinate system".
The origin of a space is, very loosely, a generalization of the idea of a "coordinate system" (sometimes known as a "coordinate frame") to arbitrary data. If a collection of
entities are part of the same space, it means they can be rendered together.

For examples:
- For 2D and 3D geometric primitives this means they share the same origin and coordinate system.
- For scalar plots it means they share the same plot axes.
- For text logs, it means they share the same conceptual stream.
For example:

As explained bellow, a space view *may* display data belonging to multiple spaces, but its coordinate system is defined
by a specific space, and the other spaces must have well-defined transforms to that space to be displayed in the same view.
- For 2D and 3D geometric primitives this means they share the same coordinate system.
- For scalar plots it means they share the same plot axes.
- For text logs, it means they share the same conceptual stream.

As explained below, a space view _may_ display data belonging to multiple spaces, but there must be a well-defined
means of transforming the data from one space to another.

Which entities belong to which spaces is a function of the transform system, which uses the following rules to define
the space connectivity:

1. Every unique entity path defines a potentially unique space.
1. Unless otherwise specified, every path is trivially connected to its parent by the identity transform.
1. Logging a transform to a path defines the relationship between that path and its parent (replacing the identity
connection).
connection).
1. Only paths which are connected by the identity transform are effectively considered to be part of the same
space. All others are considered to be disjoint.
space. All others are considered to be disjoint.

Note that in the absence of transforms, all entity paths are fully connected by the identity transform, and therefore
share the same space. However, as soon as you begin to log transforms, you can end up with additional spaces.
Expand All @@ -43,10 +44,10 @@ rr.log("world/robot", rr.Transforms3D(…))

There are 4 parent/child entity relationships represented in this hierarchy.

- `(root)` -> `world`
- `world` -> `world/mapped_keypoints`
- `world` -> `world/robot`
- `world/robot` -> `world/robot/observed_features`
- `(root)` -> `world`
- `world` -> `world/mapped_keypoints`
- `world` -> `world/robot`
- `world/robot` -> `world/robot/observed_features`

The call: `rr.log("world/robot", rr.Transforms3D(…))` only applies to the relationship: `world` -> `world/robot` because the
logged transform (`world/robot`) describes the relationship between the entity and its _parent_ (`world`). All other
Expand All @@ -60,7 +61,6 @@ from `world/robot/observed_features` are not directly comparable. If you were to
coordinate system the results would be meaningless. As noted above, Rerun can still display these entities in the same
space view because it is able to automatically transform data between different spaces.


## Space Transformations

In order to correctly display data from different spaces in the same view, Rerun uses the information from logged
Expand All @@ -71,15 +71,15 @@ of transformations to the component data when building the scene.
Rerun transforms are currently limited to connections between _spatial_ views of 2D or 3D data. There are 3 types of
transforms that can be logged:

- Affine 3D transforms, which can define any combination of translation, rotation, and scale relationship between two paths (see
[`rr.Transform3D`](https://ref.rerun.io/docs/python/stable/common/archetypes/#rerun.archetypes.Transform3D)).
- Pinhole transforms define a 3D -> 2D camera projection (see
[`rr.Pinhole`](https://ref.rerun.io/docs/python/stable/common/archetypes/#rerun.archetypes.Pinhole)).
- A disconnected space specifies that the data cannot be transformed (see [`rr.DisconnectedSpace`](https://ref.rerun.io/docs/python/stable/common/archetypes/#rerun.archetypes.DisconnectedSpace)). In this case it will not be possible to combine the data into a single view, and you will need to create two separate views to explore the data.
- Affine 3D transforms, which can define any combination of translation, rotation, and scale relationship between two paths (see
[`rr.Transform3D`](https://ref.rerun.io/docs/python/stable/common/archetypes/#rerun.archetypes.Transform3D)).
- Pinhole transforms define a 3D -> 2D camera projection (see
[`rr.Pinhole`](https://ref.rerun.io/docs/python/stable/common/archetypes/#rerun.archetypes.Pinhole)).
- A disconnected space specifies that the data cannot be transformed (see [`rr.DisconnectedSpace`](https://ref.rerun.io/docs/python/stable/common/archetypes/#rerun.archetypes.DisconnectedSpace)). In this case it will not be possible to combine the data into a single view, and you will need to create two separate views to explore the data.

In the future, Rerun will be adding support for additional types of transforms.
- [#349: Log 2D -> 2D transformations in the transform hierarchy](https://github.com/rerun-io/rerun/issues/349)

- [#349: Log 2D -> 2D transformations in the transform hierarchy](https://github.com/rerun-io/rerun/issues/349)

## Examples

Expand All @@ -106,8 +106,8 @@ Rerun will from this understand how the `world` space and the two image spaces (

Note that none of the names in the paths are special.


## View coordinates

You can use [`rr.ViewCoordinates`](https://ref.rerun.io/docs/python/stable/common/archetypes/#rerun.archetypes.ViewCoordinates) to set your preferred view coordinate systems, giving semantic meaning to the XYZ axes of the space.

For 3D spaces it can be used to log what the up-axis is in your coordinate system. This will help Rerun set a good default view of your 3D scene, as well as make the virtual eye interactions more natural. This can be done with `rr.log("world", rr.ViewCoordinates(up="+Z"), timeless=True)`.
Expand Down
6 changes: 2 additions & 4 deletions docs/content/howto/configure-the-viewer.md → ...t/getting-started/configure-the-viewer.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Configure the Viewer
order: 10
order: 5
---

Although the Rerun Viewer tries to do a reasonable job of using heuristics to automatically determine
Expand All @@ -20,6 +20,4 @@ There are a few different ways to work with Blueprints:

- [Blueprints can be modified interactively](./configure-the-viewer/interactively.md)
- [Blueprint files (.rbl) can be saved and loaded from disk](./configure-the-viewer/save-and-load.md)
- [Blueprints can be controlled directly from code](./configure-the-viewer/through-code.md)

For a hands on example, you can also follow the [Blueprint API Tutorial](./configure-the-viewer/blueprint-api-tutorial.md).
- [Blueprints can be controlled directly from code](./configure-the-viewer/through-code-tutorial.md)
158 changes: 158 additions & 0 deletions docs/content/getting-started/configure-the-viewer/interactively.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
---
title: Configure the viewer interactively
order: 1
---

The Rerun Viewer is configurable directly through the UI itself.

## Viewer overview

<picture>
<img src="https://static.rerun.io/overview/158a13691fe0364ed5d4dc420f5b2c39b60705cd/full.png" alt="">
<source media="(max-width: 480px)" srcset="https://static.rerun.io/overview/158a13691fe0364ed5d4dc420f5b2c39b60705cd/480w.png">
<source media="(max-width: 768px)" srcset="https://static.rerun.io/overview/158a13691fe0364ed5d4dc420f5b2c39b60705cd/768w.png">
<source media="(max-width: 1024px)" srcset="https://static.rerun.io/overview/158a13691fe0364ed5d4dc420f5b2c39b60705cd/1024w.png">
<source media="(max-width: 1200px)" srcset="https://static.rerun.io/overview/158a13691fe0364ed5d4dc420f5b2c39b60705cd/1200w.png">
</picture>


The central part is known as the viewport and contains the various views displaying the data.

The left panel of the viewer is the "Blueprint Panel". It shows a visual tree view representing
the contents of the current blueprint.

The right panel of the viewer is the "Selection Panel" this panel allows you to configure
specific blueprint properties of the currently selected element.

The blueprint defines the structure, the type of views, and their content in the viewport. Changing the content of the viewport is done by editing the blueprint.

After editing the viewer you may want to [save or share the blueprint](./save-and-load.md).

## Configuring the view hierarchy

The viewport is made of various views, laid out hierarchically with nested containers of various kinds: vertical, horizontal, grid, and tabs. This hierarchy is represented in the blueprint panel, with the top container corresponding to the viewport. In this section, we cover the various ways this view hierarchy can be interactively created and modified.

### Show or hide parts of the blueprint

Any container or view can be hidden or shown by clicking the "eye" icon.

<picture>
<img src="https://static.rerun.io/show_hide_btn/bbca385d4898ec220bfb91c430ea52d59553913e/full.png" alt="">
</picture>


### Add new Containers or Views

Adding a container or a view to the view port can be done by clicking the "+" at the top of the blueprint panel.

<picture>
<img src="https://static.rerun.io/add_view/3933d7096846594304ddec2d51dda9c434d763bf/full.png" alt="">
</picture>


If a container (or the viewport) is already selected, a "+" button will also be available in the selection panel.

<picture>
<img src="https://static.rerun.io/add_view_selection_panel/e3355e61a8ec8f2e7860968f91032f7f7bf6ab6e/full.png" alt="">
<source media="(max-width: 480px)" srcset="https://static.rerun.io/add_view_selection_panel/e3355e61a8ec8f2e7860968f91032f7f7bf6ab6e/480w.png">
</picture>


### Remove a View or Container

Removing a view or a container can be done by clicking the "-" button next to it:

<picture>
<img src="https://static.rerun.io/remove/6b9d97e4297738b8aad89158e4d15420be362b4a/full.png" alt="">
</picture>


### Re-arrange existing Containers or Views

The viewport hierarchy can be reorganized by drag-and-dropping containers or views in the blueprint panel. It ssi also possible to drag views directly in the viewport by using their title tab:

<picture>
<img src="https://static.rerun.io/drag_and_drop_viewport/8521fda375a2f6af15628b04ead4ba848cb8bc27/full.png" alt="">
<source media="(max-width: 480px)" srcset="https://static.rerun.io/drag_and_drop_viewport/8521fda375a2f6af15628b04ead4ba848cb8bc27/480w.png">
</picture>


### Rename a View or Container

Both views and containers may be assigned a custom name. This can be done by selecting the view or container, and editing the name at the top of the selection panel.

<picture>
<img src="https://static.rerun.io/rename/94be9e29a0120fbab1a7c07a8952f2cba4dcea68/full.png" alt="">
</picture>

### Change a Container kind

Containers come in four different kinds: vertical, horizontal, grid, and tabs. To change an existing container's kind, select it and change the value from the dropdown menu in the selection panel:

<picture>
<img src="https://static.rerun.io/container_kind/44fea90f2b3e5a699549c204948f677fc95e2157/full.png" alt="">
<source media="(max-width: 480px)" srcset="https://static.rerun.io/container_kind/44fea90f2b3e5a699549c204948f677fc95e2157/480w.png">
</picture>


### Using context menus

The context menu is accessed by right-clicking on a container or view in the blueprint panel. Many of the previous operations are also available there:

<picture>
<img src="https://static.rerun.io/context_menu_container/e90e4688f306187d902467b452fb7146eec1bf4b/full.png" alt="">
</picture>


One key advantage of using the context menu is that it enable operations on multiple items at once. For example, you may select several views (ctrl-click, or cmd-click on Mac), and remove them all in a single operation using the context menu.


## Configuring the content of a view

The content of a view is determined by its entity query, which can be manually edited in the selection panel when the view is selected (see [Entity Queries](../../reference/entity-queries.md) for more information). This section covers the interactive means of manipulating the view content (which typically operate by actually modifying the query).


### Show or hide view content

Like containers and views, any entity in a view may be shown and hidden with the "eye" icon or the context menu.

<picture>
<img src="https://static.rerun.io/show_hide_entity/587a5d8fd763c0bade461bc54a66a4acdd087821/full.png" alt="">
</picture>


### Remove Data from a View

Likewise, entities may be removed from a view by clicking the "-" next to it:

<picture>
<img src="https://static.rerun.io/remove_entity/ec0447ca7e420bc9d19a7bf015cc39f88b42598a/full.png" alt="">
</picture>


### Using the query editor

A visual query editor is available from the selection panel when a view is selected. Click the "Edit" button next to the entity query:

<picture>
<img src="https://static.rerun.io/add_remove_entity/9b7b29b3be4816d5d42e66549d899039235b10ee/full.png" alt="">
<source media="(max-width: 480px)" srcset="https://static.rerun.io/add_remove_entity/9b7b29b3be4816d5d42e66549d899039235b10ee/480w.png">
</picture>

The query editor allows visually adding and removing entities and entity trees from the query.

### Adding entities to a new view with context menu

Like with viewport hierarchy, most operations on view data are available from the context menu. In particular, a new view can be created with custom content by selecting one or more entities (either in existing views in the blueprint panel, or in the time panel's streams), and clicking "Add to new space view" in the context menu:

<picture>
<img src="https://static.rerun.io/add_to_new_view/87f2d5ffb3ef896c82f398cd3c3d1c7321d59073/full.png" alt="">
<source media="(max-width: 480px)" srcset="https://static.rerun.io/add_to_new_view/87f2d5ffb3ef896c82f398cd3c3d1c7321d59073/480w.png">
<source media="(max-width: 768px)" srcset="https://static.rerun.io/add_to_new_view/87f2d5ffb3ef896c82f398cd3c3d1c7321d59073/768w.png">
<source media="(max-width: 1024px)" srcset="https://static.rerun.io/add_to_new_view/87f2d5ffb3ef896c82f398cd3c3d1c7321d59073/1024w.png">
</picture>

When using one of the recommended views with this method, the view's origin will automatically be set to a sensible default based on the actual data.



Loading

0 comments on commit 0d145eb

Please sign in to comment.