Very WIP blueprint docs

docs/content/concepts/blueprint.md

@@ -0,0 +1,17 @@
+---
+title: Blueprint
+order: 8
+---
+
+## Blueprint
+
+The Blueprint is the concept in Rerun that controls all aspects of how the viewer is laid out and how the data is presented.
+
+-   TODO(jleibs): More details
+    -   Philosophy
+        -   Blueprints are just data
+    -   Blueprint Parts:
+        -   Viewport
+        -   Container
+        -   SpaceView
+        -   Queries

docs/content/concepts/entity-queries.md

@@ -0,0 +1,23 @@
+---
+title: Entity Queries
+order: 9
+---
+
+TODO(jleibs): flesh this out with more details/examples
+
+The contents of a space view are found by combining a collection of `QueryExpression`s.
+
+```diff
++ /world/**           # add everything…
+- /world/roads/**     # …but remove all roads…
++ /world/roads/main   # …but show main road
+```
+
+-   If there is multiple matching rules, the most specific rule wins.
+-   If there are multiple rules of the same specificity, the last one wins.
+-   If no rules match, the path is excluded.
+
+The`/**` suffix matches the whole subtree, i.e. self and any child, recursively
+(`/world/**`matches both`/world`and`/world/car/driver`).
+
+Other uses of `*` are not yet supported.

docs/content/howto/configuring-the-viewer.md

@@ -0,0 +1,25 @@
+---
+title: Configuring the Viewer
+order: 10
+---
+
+Although the Rerun Viewer tries to do a reasonable job of using heuristics to automatically determine
+an appropriate layout given the data that you provide, there will always be situations where the heuristic
+results don't match the needs of a particular use-case.
+
+Fortunately, almost all aspects of the viewer can be configured via the [Blueprint](../concepts/blueprint.md).
+
+The viewer Blueprint completely determines:
+
+-   What contents are included in each view
+-   The type of view used to visualize the data
+-   The organizational layout and names of the different view panels and containers
+-   Configuration and styling properties of the individual data visualizers
+
+There are a few different ways to work with Blueprints:
+
+-   [Blueprints can be modified directly through the UI](./configuring-the-viewer/blueprint-ui.md)
+-   [Blueprint files (.rbl) can be saved and loaded from disk](./configuring-the-viewer/rbl-files.md)
+-   [Blueprints can be generated direct from code](./configuring-the-viewer/blueprint-apis.md)
+
+For a hands on example, you can also follow the [Blueprint API Tutorial](./configuring-the-viewer/blueprint-api-tutorial.md).

docs/content/howto/configuring-the-viewer/blueprint-api-tutorial.md

@@ -0,0 +1,6 @@
+---
+title: Blueprint UI
+order: 4
+---
+
+TODO(jleibs): walk through using: https://github.com/rerun-io/rerun/tree/main/examples/python/blueprint_stocks?speculative-link

docs/content/howto/configuring-the-viewer/blueprint-apis.md

@@ -0,0 +1,146 @@
+---
+title: Blueprint APIs
+order: 2
+---
+
+As of Rerun 0.15, the state of the [Blueprint](../../concepts/blueprint.md) can be directly manipulated using
+"Blueprint APIs" in the 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` 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.SpaceView(rrb.BarChartView()),
+        rrb.Vertical(
+            rrb.SpaceView(rrb.Spatial2DView()),
+            rrb.SpaceView(rrb.Spatial3DView()),
+        ),
+    ),
+)
+```
+
+## Sending the Blueprint to the Viewer
+
+To use a blueprint, simply pass it to either `init` or `connect`:
+
+If you use `init` with the `spawn=True` option, you should pass the blueprint as an argument:
+
+```python
+my_blueprint = rrb.Blueprint(...)
+
+rr.init("rerun_example_my_blueprint", spawn=True, blueprint=my_blueprint)
+```
+
+Or if you use `connect` separate from `init`, you should pass blueprint when you call `connect`:
+
+```python
+my_blueprint = rrb.Blueprint(...)
+
+rr.init("rerun_example_my_blueprint")
+
+...
+
+rr.connect(blueprint=my_blueprint)
+```
+
+## Customizing Space Views
+
+If you create a space view with no arguments, by default it will try to include all compatible entities
+in the entire tree.
+
+There are 3 parameters you may want to specify for a space view: `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`
+
+TODO(jleibs): this explanation probably belongs somewhere else?
+
+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.
+TODO(jleibs): Re-review spaces-and-transforms for correctness
+
+For example:
+
+```python
+my_blueprint = 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](../../concepts/entity-queries.md) 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
+my_blueprint = rrb.Blueprint(
+    rrb.Horizontal(
+        rrb.Spatial3DView(
+            origin="/world",
+            contents=[
+                "+ $origin/robot/**",
+                "- $origin/map/**",
+            ],
+        ),
+        rrb.Spatial2DView(
+            origin="/world/robot/camera",
+            contents=[
+                "+ $origin/**",
+                "+ /world/robot/actuator/**",
+            ],
+        ),
+    )
+)
+
+```

docs/content/howto/configuring-the-viewer/blueprint-ui.md

@@ -0,0 +1,85 @@
+---
+title: Blueprint UI
+order: 1
+---
+
+The Rerun Viewer is configurable directly through the UI itself.
+
+## Viewer overview
+
+TODO(#5636): Screenshot of the viewer, with the blueprint and selection panels highlighted.
+
+The left panel of the viewer is the "Blueprint Panel" this shows a visual tree view representing
+the contents of the current blueprint.
+
+The right panel of the viewer is the "Selection Panel" this panels allows you to configure
+specific blueprint properties of the currently selected element.
+
+After editing the viewer you may want to [save or share the blueprint](./rbl-files.md).
+
+## Configuring Layout and Contents
+
+### Show or hide parts of the blueprint
+
+Click the "eye" icon next to the container, view, or entity in the blueprint panel.
+TODO(#5636): show_hide
+
+### Add new Containers or Views
+
+Clicking the "+" at the top of the blueprint panel.
+TODO(#5636): add_1
+
+Selecting a Container and clicking the "+" in the selection panel.
+TODO(#5636): add_2
+
+### Remove a View or Container
+
+Click the "-" button next to the container or view in the blueprint panel.
+TODO(#5636): remove
+
+### Re-arrange existing Containers or Views
+
+Drag and drop the container or view in the blueprint panel.
+TODO(#5636): drag_1
+
+Drag and drop containers or views directly in the viewport
+TODO(#5636): drag_2
+
+### Change the size of Contaainers or Views
+
+Click and drag the edge of a view or container to resize it
+TODO(#5636): resize
+
+### Rename a View or Container
+
+Select the Container or View and enter a name at the top of the selection panel
+TODO(#5636): rename
+
+### Change the type of a Container
+
+Select the Container and choose a new type from the dropdown in the selection panel
+TODO(#5636): change_type
+
+### Add a new Data to a View
+
+Select the view and click "edit" to bring up the entity editor
+TODO(#5636): add_data_1
+
+Select the view and directly edit the entity query
+See [Entity Queries](../../concepts/entity-queries.md) for more information on how to write queries.
+
+TODO(#5636): add_data_2
+
+### Remove Data from a View
+
+Click the "-" next to the entity in the blueprint panel
+TODO(#5636): remove_data_1
+
+### Change the origin of a View
+
+Select the view, then click the "Space Origin" field and type or select a new origin
+TODO(#5636): change_origin
+
+## Overriding Properties
+
+TODO(jleibs): do we include this now or wait for generalized component overrides?

docs/content/howto/configuring-the-viewer/rbl-files.md

@@ -0,0 +1,24 @@
+---
+title: Using .rbl Files
+order: 1
+---
+
+If you have made changes to your blueprint and you would like to save or share these changes,
+you can do so by saving your blueprint to an `.rbl` file.
+
+## Saving a blueprint
+
+To save your blueprint, go to the file-menu and choose "Save Blueprint…"
+TODO(#5636): save
+
+## Loading a blueprint
+
+Once you have saved a blueprint, you can load it again.
+
+When loading a blueprint, it must match the "application_id" used by the recording.
+
+To load a blueprint, go to the file-menu and choose "Open…" and select the `.rbl` file you would like to load.
+TODO(#5636): open_1
+
+You can also drag and drop an `.rbl` file directly into the viewer
+TODO(#5636): open_2