Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs/howto: spring cleaning #7867

Open
wants to merge 3 commits into
base: cmc/dataframe_doc_final
Choose a base branch
from
+325 −320
Open

docs/howto: spring cleaning #7867

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4cf11bd
docs/howto: spring cleaning
teh-cmc Oct 22, 2024
7d0e005
repair legacy link
teh-cmc Oct 22, 2024
20bb706
wpp[s
teh-cmc Oct 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 0 additions & 13 deletions docs/content/howto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,3 @@ order: 1
---

Guides for using Rerun in more advanced ways.
- [Configure the Viewer through code](howto/configure-viewer-through-code.md)
- [Create a fixed-window plot](howto/fixed-window-plot.md)
- [Limit memory usage](howto/limit-ram.md)
- [Share recordings across multiple processes](howto/shared-recordings.md)
- [Clear out already logged data](howto/short-lived-entities.md)
- [Use Rerun with ROS2](howto/ros2-nav-turtlebot.md)
- [Embed Rerun in notebooks](howto/notebook.md)
- [Integrate Rerun with native loggers](howto/using-native-loggers.md)
- [Extend Rerun](howto/extend)
- [By logging custom data](howto/extend/custom-data.md)
- [By implementing custom visualizations (Rust only)](howto/extend/extend-ui.md)
- [Efficiently log time series data using `send_columns`](howto/send_columns.md)
- [Get data out from Rerun with code](howto/dataframe-api.md)
286 changes: 2 additions & 284 deletions docs/content/howto/configure-viewer-through-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,287 +1,5 @@
---
title: Configure the Viewer through code
order: 100
hidden: true
redirect: howto/visualization/configure-viewer-through-code
---

As of Rerun 0.15, the state of the [blueprint](../reference/viewer/blueprint.md) can be directly manipulated using the
Rerun SDK.

In the initial 0.15 release, the APIs are still somewhat limited and only available in the Python SDK.
Future releases will add support for the full scope of blueprint. See issues: [#5519](https://github.com/rerun-io/rerun/issues/5519), [#5520](https://github.com/rerun-io/rerun/issues/5520), [#5521](https://github.com/rerun-io/rerun/issues/5521).

## Blueprint API overview

All blueprint APIs are in the [`rerun.blueprint`](https://ref.rerun.io/docs/python/stable/common/blueprint_apis/) namespace. In our Python examples, we typically import this using the `rrb` alias:

```python
import rerun.blueprint as rrb
```

The Python blueprint API is declarative and object-centric. There are 3 main types of blueprint objects you will
encounter:

- `Blueprint`: The root object that represents the entire Viewer layout.
- `Container`: A layout object that contains other containers or views.
- `SpaceView`: A view object that represents a single view of the data.

Both containers and spaceviews should be used via typed subclasses instead.:

- `Container` has subclasses: `Horizontal`, `Vertical`, `Grid`, and `Tabs`.
- `SpaceView` has subclasses: `BarChartView`, `Spatial2DView`, `Spatial3DView`, `TensorView`,
`TextDocumentView`, `TextLogView`, and `TimeSeriesView`.

These paths can be combined hierarchically to create a complex Viewer layout.

For example:

```python
my_blueprint = rrb.Blueprint(
rrb.Horizontal(
rrb.BarChartView(),
rrb.Vertical(
rrb.Spatial2DView(),
rrb.Spatial3DView(),
),
),
)
```

## Sending the blueprint to the Viewer

To provide a blueprint, simply pass it to either `init` or `connect` using the `default_blueprint`
parameter.

Using `init` with `spawn=True`:

```python
my_blueprint = rrb.Blueprint(...)

rr.init("rerun_example_my_blueprint", spawn=True, default_blueprint=my_blueprint)
```

Or if you use `connect` separate from `init`:

```python
my_blueprint = rrb.Blueprint(...)

rr.init("rerun_example_my_blueprint")

...

rr.connect(default_blueprint=my_blueprint)
```

## Activating the default blueprint

Just like the Viewer can store many different recordings internally, it can also
store many different blueprints. For each `application_id` in the viewer, are two
particularly important blueprints: the "default blueprint" and the "active blueprint".

When a recording is selected, the active blueprint for the corresponding
`application_id` will completely determine what is displayed by the viewer.

When you send a blueprint to the viewer, it will not necessarily be
activated immediately. The standard behavior is to only update the "default
blueprint" in the viewer. This minimizes the chance that you accidentally
overwrite blueprint edits you may have made locally.

If you want to start using the new blueprint, after sending it, you will need to
click the reset button (<img src="https://static.rerun.io/b60eb3c4010e3ee46bbeeabf3da411fade2495b6_reset.png" alt="reset icon" style="display:inline; vertical-align: middle; height: 20px; margin: 0px"/>) in the blueprint panel. This resets the active blueprint to the
current default.

## Always activating the blueprint

If you want to always activate the blueprint as soon as it is received, you can instead use the `send_blueprint`
API. This API has two flags `make_active` and `make_default`, both of which default to `True`.

If `make_active` is set, the blueprint will be activated immediately. Exercise care in using this API, as it can be
surprising for users to have their blueprint changed without warning.

```python
my_blueprint = rrb.Blueprint(...)

rr.init("rerun_example_my_blueprint", spawn=True)

rr.send_blueprint(my_blueprint, make_active=True)

```

## Customizing space views

Any of the space views (`BarChartView`, `Spatial2DView`, `Spatial3DView`, `TensorView`,
`TextDocumentView`, `TextLogView`, or `TimeSeriesView`) can be instantiated with no arguments.
By default these views try to include all compatible entities.

For example, the following blueprint creates a single 3D view that includes all the 3D content
you have logged to the entity tree:

```python
rrb.Blueprint(
rrb.Spatial3DView()
)
```

Beyond instantiating the space views, there are 3 parameters you may want to specify: `name`, `origin`, and `contents`.

`name` is simply the name of the view used as a label in the viewer.

However, both `origin` and `contents` play an important role in determining what data is included in the view.

### `origin`

The `origin` of a space-view is a generalized "frame of reference" for the view. We think of showing all data
in the space view as relative to the `origin`.

By default, only data that is under the `origin` will be included in the view. As such this is one of the most
convenient ways of restricting a space-view to a particular subtree.

Because the data in the space-view is relative to the `origin`, the `origin` will be the first entity displayed
in the blueprint tree, with all entities under the origin shown using relative paths.

For Spatial views such as `Spatial2DView` and `Spatial3DView`, the `origin` plays an additional role with respect
to data transforms. All data in the view will be transformed to the `origin` space before being displayed. See [Spaces and Transforms](../concepts/spaces-and-transforms.md) for more information.

For example:

```python
rrb.Blueprint(
rrb.Horizontal(
rrb.Spatial3DView(origin="/world"),
rrb.Spatial2DView(origin="/world/robot/camera"),
)
)
```

### `contents`

If you need to further modify the contents of a space view, you can use the `contents` parameter. This parameter is
a list of [entity query expressions](../reference/) that are either included or excluded from the
view.

Each entity expressions starts with "+" for inclusion or "-" for an exclusion. The expressions can either be specific entity paths, or may end in a wildcard `/**` to include all entities under a specific subtree.

When combining multiple expressions, the "most specific" rule wins.

Additionally, these expressions can reference `$origin` to refer to the origin of the space view.

For example:

```python
rrb.Blueprint(
rrb.Horizontal(
rrb.Spatial3DView(
origin="/world",
contents=[
"+ $origin/robot/**",
],
),
rrb.Spatial2DView(
origin="/world/robot/camera",
contents=[
"+ $origin/**",
"+ /world/robot/actuator/**",
],
),
)
)
```

## Implicit conversion

For convenience all of the blueprint APIs take a `BlueprintLike` rather than requiring a `Blueprint` object.
Both `SpaceView`s and `Containers` are considered `BlueprintLike`. Similarly, the `Blueprint` object can
take a `SpaceView` or `Container` as an argument.

All of the following are equivalent:

```python
rr.send_blueprint(rrb.Spatial3DView())
```

```python
rr.send_blueprint(
rrb.Grid(
Spatial3DView(),
)
)
```

```python
rr.send_blueprint(
rrb.Blueprint(
Spatial3DView(),
),
)

```

```python
rr.send_blueprint(
rrb.Blueprint(
rrb.Grid(
Spatial3DView(),
)
),
)
```

## Customizing the top-level blueprint

The top-level `Blueprint` object can also be customized.

### Controlling the panel state

The `Blueprint` controls the default panel-state of the 3 panels: the `BlueprintPanel`, the `SelectionPanel`, and the `TimePanel`. These can be controlled by passing them as additional arguments to the `Blueprint` constructor.

```python
rrb.Blueprint(
rrb.TimePanel(state="collapsed")
)
```

As an convenience, you can also use the blueprint argument: `collapse_panels=True` as a short-hand for:

```python
rrb.Blueprint(
rrb.TimePanel(state="collapsed"),
rrb.SelectionPanel(state="collapsed"),
rrb.BlueprintPanel(state="collapsed"),
)
```

### Controlling the auto behaviors

The blueprint has two additional parameters that influence the behavior of the viewer:

- `auto_space_views` controls whether the Viewer will automatically create space views for entities that are not explicitly included in the blueprint.
- `auto_layout` controls whether the Viewer should automatically layout the containers when introducing new space-views.

If you pass in your own `SpaceView` or `Container` objects, these will both default to `False` so that the Blueprint
you get is exactly what you specify. Otherwise they will default to `True` so that you will still get content (this
matches the default behavior of the Viewer if no blueprint is provided).

This means that:

```python
rrb.Blueprint()
```

and

```python
rrb.Blueprint(
auto_space_views=True,
auto_layout=True
)
```

are both equivalent to the viewer's default behavior.

If you truly want to create an empty blueprint, you must set both values to `False`:

```python
rrb.Blueprint(
auto_space_views=False,
auto_layout=False
),
```
2 changes: 1 addition & 1 deletion docs/content/howto/extend.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Extend Rerun
order: 1000
---

There are currently two major ways of extending Rerun. You can use Rerun with [your own custom data](extend/custom-data.md), or [extend the Rerun Viewer](extend/extend-ui.md) (currently Rust only).
There are currently two major ways of extending Rerun. You can use Rerun with [your own custom data](logging/custom-data.md), or [extend the Rerun Viewer](visualization/extend-ui.md) (currently Rust only).

The goal is for Rerun to become easy to extend at every level. For example, with plugins for
- data sources
Expand Down
6 changes: 2 additions & 4 deletions docs/content/howto/dataframe-api.md → docs/content/howto/get-data-out.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
---
title: Get data out of Rerun with code
order: 1600
title: Get data out of Rerun
order: 0
---

Rerun comes with a Dataframe API, which enables getting data out of Rerun from code. This page provides an overview of the API, as well as recipes to load the data in popular packages such as [Pandas](https://pandas.pydata.org), [Polars](https://pola.rs), and [DuckDB](https://duckdb.org).

<!-- TODO(#7499): add links to the Python SDK documentation where appropriate -->

## The dataframe API

### Loading a recording
Expand Down
5 changes: 5 additions & 0 deletions docs/content/howto/integrations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: Integrations
order: 900
redirect: howto/integrations/embed-notebooks
---
2 changes: 1 addition & 1 deletion docs/content/howto/notebook.md → ...ent/howto/integrations/embed-notebooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Embed Rerun in notebooks
order: 600
order: 0
description: How to embed Rerun in notebooks like Jupyter or Colab
---

Expand Down
4 changes: 2 additions & 2 deletions docs/content/howto/embed-rerun-viewer.md → docs/content/howto/integrations/embed-web.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Embed a Rerun Viewer
order: 1500
title: Embed Rerun in Web pages
order: 100
---

Integrating the Rerun Viewer into your web application can be accomplished either by [utilizing an iframe](#embedding-apprerunio-using-an-iframe) or by using our [JavaScript package](#using-the-javascript-package).
Expand Down
2 changes: 1 addition & 1 deletion docs/content/howto/using-native-loggers.md → ...to/integrations/integrate-host-loggers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Integrate Rerun with native loggers
order: 700
order: 400
description: How to use the Rerun SDK as a native logger for the host language
---

Expand Down
2 changes: 1 addition & 1 deletion docs/content/howto/ros2-nav-turtlebot.md → .../howto/integrations/ros2-nav-turtlebot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Use Rerun with ROS 2
order: 500
order: 300
ogImageUrl: /docs-media/og-howto-ros.jpg
description: Rerun does not yet have native ROS support, but many of the concepts in ROS and Rerun line up fairly well. In this guide, you will learn how to write a simple ROS 2 Python node that subscribes to some common ROS topics and logs them to Rerun.
---
Expand Down
5 changes: 5 additions & 0 deletions docs/content/howto/logging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: Logging
order: 100
redirect: howto/logging/send-columns
---
4 changes: 2 additions & 2 deletions docs/content/howto/short-lived-entities.md → docs/content/howto/logging/clears.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Clear out already logged data
order: 400
title: Clear out data using tombstones
order: 300
description: How to log data that isn't valid for the whole recording
---
In order to create coherent views of streaming data, the Rerun Viewer shows the latest values for each visible entity at the current timepoint. But some data may not be valid for the entire recording even if there are no updated values. How do you tell Rerun that something you've logged should no longer be shown?
Expand Down
4 changes: 2 additions & 2 deletions docs/content/howto/extend/custom-data.md → docs/content/howto/logging/custom-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: By logging custom data
order: 100
title: Log arbitrary data
order: 200
description: How to use Rerun with custom data
---
Rerun comes with many pre-built [Types](../../reference/types.md) that you can use out of the box. As long as your own data can be decomposed into Rerun [components](../../reference/types/components.md) or can be serialized with [Apache Arrow](https://arrow.apache.org/), you can log it directly without needing to recompile Rerun.
Expand Down
Loading
Loading