wehub-resource-sync
168 lines
9.9 KiB
Markdown
168 lines
9.9 KiB
Markdown
---
|
|
title: Blueprints
|
|
order: 100
|
|
---
|
|
|
|
## What are Blueprints?
|
|
|
|
When you work with the Rerun Viewer, understanding blueprints is important if you want to build consistency around your Viewer experience.
|
|
|
|
*For a video overview, check out the [Blueprints video](https://www.youtube.com/embed/kxbkbFVAsBo?si=k2JPz3RbhR1--pcw) on YouTube.*
|
|
|
|
<iframe width="560" height="315" src="https://www.youtube.com/embed/kxbkbFVAsBo?si=k2JPz3RbhR1--pcw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
|
|
|
|
|
A way to think about the Rerun View is that
|
|
|
|
- The **recording** provides the actual data you are visualizing
|
|
- The **blueprint** determines how that data is displayed
|
|
|
|
Both pieces are crucial. Without a recording there is nothing to show. Without a blueprint there is no way to show it. Even when you use Rerun without explicitly loading a blueprint, the Viewer creates one automatically for you.
|
|
|
|
## What blueprints control
|
|
|
|
Blueprints give you complete control over the Viewer's layout and configuration:
|
|
|
|
- **Panel visibility**: Whether panels like the blueprint panel, selection panel, and time panel are expanded or collapsed
|
|
- **Layout structure**: How views are arranged using containers (Grid, Horizontal, Vertical, Tabs)
|
|
- **View types and configuration**: What kind of views display your data (2D/3D spatial, maps, charts, text logs, etc.) and their specific settings
|
|
- **Visual properties**: Styling like backgrounds, colors, zoom levels, time ranges, and visual bounds
|
|
|
|
In general, if you can modify an aspect of how something looks through the Viewer, you are actually modifying the blueprint.
|
|
|
|
## Application IDs: binding blueprints to data
|
|
|
|
The [Application ID](../logging-and-ingestion/recordings.md) is how blueprints connect to your data. This is a critical concept:
|
|
|
|
**All recordings that share the same Application ID will use the same blueprint.**
|
|
|
|
This loose coupling between blueprints and recordings means:
|
|
- You can keep the blueprint constant while changing the recording to compare different datasets with consistent views
|
|
- You can change the blueprint while keeping a recording constant to view the same data in different ways
|
|
- When you save blueprint changes with the Viewer, those changes apply to all recordings with that Application ID
|
|
|
|
Think of the Application ID as the "key" that binds a blueprint to a specific type of recording. If you want recordings to share the same layout, give them the same Application ID.
|
|
|
|
## Reset behavior: heuristic vs default
|
|
|
|
The Viewer provides two types of blueprint reset, accessible from the blueprint panel:
|
|
|
|
<picture>
|
|
<img src="https://static.rerun.io/blueprint-reset/c52e124cc4d0109b672264357b0193f7f7c8d6c5/full.png" alt="">
|
|
<source media="(max-width: 480px)" srcset="https://static.rerun.io/blueprint-reset/c52e124cc4d0109b672264357b0193f7f7c8d6c5/480w.png">
|
|
<source media="(max-width: 768px)" srcset="https://static.rerun.io/blueprint-reset/c52e124cc4d0109b672264357b0193f7f7c8d6c5/768w.png">
|
|
<source media="(max-width: 1024px)" srcset="https://static.rerun.io/blueprint-reset/c52e124cc4d0109b672264357b0193f7f7c8d6c5/1024w.png">
|
|
<source media="(max-width: 1200px)" srcset="https://static.rerun.io/blueprint-reset/c52e124cc4d0109b672264357b0193f7f7c8d6c5/1200w.png">
|
|
</picture>
|
|
|
|
### Reset to heuristic blueprint
|
|
This generates a new blueprint automatically based on your current data. The Viewer analyzes what you've logged and creates an appropriate layout using built-in heuristics. This is useful when you want to start fresh and let Rerun figure out a reasonable layout.
|
|
|
|
### Reset to default blueprint
|
|
This returns to your programmatically specified blueprint (sent from code) or a saved blueprint file (`.rbl`). If you've sent a blueprint using `rr.send_blueprint()` or loaded a `.rbl` file, this becomes your "default." The reset button in the blueprint panel will restore this default whenever you need it.
|
|
|
|
When no default blueprint has been set, the reset button will use the heuristic blueprint instead.
|
|
|
|
<picture>
|
|
<source media="(max-width: 480px)" srcset="https://static.rerun.io/fe1fcf086752f5d7cdd64b195fb3a6cb99c50737_current_default_heuristic.png">
|
|
<img src="https://static.rerun.io/fe1fcf086752f5d7cdd64b195fb3a6cb99c50737_current_default_heuristic.png" width="550px" alt="Current, default, and heuristic blueprints">
|
|
</picture>
|
|
|
|
## Three ways to work with blueprints
|
|
|
|
There are three complementary approaches to creating and modifying blueprints:
|
|
|
|
### 1. Interactively
|
|
Modify blueprints directly in the Viewer UI:
|
|
- Drag and drop views to rearrange them
|
|
- Add new views or containers with the "+" button
|
|
- Split views horizontally, vertically, or into grids
|
|
- Change container types (Grid, Horizontal, Vertical, Tabs)
|
|
- Rename views and containers
|
|
- Show, hide, or remove elements
|
|
|
|
This is the fastest way to experiment with layouts. See [Configure the Viewer](../../getting-started/configure-the-viewer.md) for a complete guide.
|
|
|
|
### 2. Save and load files
|
|
Save your blueprint configuration to `.rbl` files:
|
|
- Use "Save blueprint…" from the file menu to save your current layout
|
|
- Load blueprints with "Open…" or by dragging `.rbl` files into the Viewer
|
|
- Share blueprint files with teammates to ensure everyone sees data the same way
|
|
- Reuse blueprints across sessions and different recordings (with the same Application ID)
|
|
|
|
Blueprint files are portable and can be version-controlled alongside your code.
|
|
|
|
### 3. Programmatically
|
|
Write blueprint code that configures the Viewer automatically:
|
|
- Define layouts in Python using `rerun.blueprint` APIs
|
|
- Send blueprints with `rr.send_blueprint()` or via `default_blueprint` parameter
|
|
- Generate layouts dynamically based on your data
|
|
- Perfect for creating consistent views for specific debugging scenarios
|
|
|
|
For example, you might send different blueprints automatically based on detected issues in your application (e.g., a robot enters an error state and surfaces the correct blueprint to help you debug that)
|
|
|
|
```python
|
|
import rerun as rr
|
|
import rerun.blueprint as rrb
|
|
|
|
if robot_error:
|
|
# Show diagnostic views for debugging
|
|
blueprint = rrb.Grid(
|
|
rrb.Spatial3DView(name="Robot view", origin="/world/robot"),
|
|
rrb.TextLogView(name="Error Logs", origin="/diagnostics"),
|
|
rrb.TimeSeriesView(name="Sensor Data", origin="/sensors"),
|
|
)
|
|
rr.send_blueprint(blueprint, make_active=True)
|
|
```
|
|
|
|
See [Configure the Viewer](../../getting-started/configure-the-viewer/navigating-the-viewer.md#programmatic-blueprints) for detailed examples and our guide on how to [build a blueprint programmatically](../../howto/visualization/build-a-blueprint-programmatically.md).
|
|
|
|
## Common use cases
|
|
|
|
### Debugging specific scenarios
|
|
Create blueprints optimized for diagnosing particular issues. For example, when debugging robot perception, you might want a blueprint that shows:
|
|
- The camera view in 2D
|
|
- The 3D world with detected objects
|
|
- Detection confidence scores in a time series chart
|
|
- Error logs in a text panel
|
|
|
|
### Sharing layouts with teams
|
|
Save a blueprint file and share it with your team. Everyone loading that blueprint with matching recordings will see the data the same way, making it easier to discuss findings and collaborate.
|
|
|
|
### Templating for different data types
|
|
Create different blueprint templates for different types of recordings. For example:
|
|
- A blueprint for autonomous vehicle data that focuses on map views and sensor fusion
|
|
- A blueprint for robotics manipulation that emphasizes joint angles and gripper cameras
|
|
- A blueprint for computer vision that shows side-by-side comparisons of different models
|
|
|
|
### Dynamic Viewer configuration
|
|
Generate blueprints programmatically based on runtime conditions. For instance, automatically create one view per detected anomaly, or adjust the layout based on how many data sources are active.
|
|
|
|
## Blueprint architecture
|
|
|
|
Under the hood, blueprints are just data. They are structured using the same [Entity Component System](../logging-and-ingestion/entity-component.md) as your recordings, but with blueprint-specific archetypes and a separate blueprint timeline. This architecture provides several advantages:
|
|
|
|
- **Anything you modify in the Viewer can be saved and shared** as a blueprint file
|
|
- **Blueprints can be produced programmatically** using just the Rerun SDK without depending on the Viewer
|
|
- **Blueprint data is fully expressive**, enabling [blueprint overrides](customize-views.md#component-mappings) that are as powerful as logged data
|
|
- **The full time-series nature** simplifies future features like snapshots and undo/redo
|
|
- **Debugging tools for Rerun data** can inspect blueprint state just like recording data
|
|
|
|
### Viewer operation
|
|
|
|
The Viewer is designed to be deterministic. Every frame, the Viewer:
|
|
1. Takes the active blueprint and active recording
|
|
2. Queries container and view archetypes from the blueprint at the current blueprint timeline revision
|
|
3. Uses those view specifications to query the data needed from the recording
|
|
4. Renders the results
|
|
5. Queues any user interactions as new blueprint events on the blueprint timeline
|
|
|
|
This means the Viewer output is a deterministic function of the blueprint and the recording, with minimal persisted state between frames.
|
|
|
|
## Next steps
|
|
|
|
- **Learn to use blueprints**: See [Configure the Viewer](../../getting-started/configure-the-viewer.md) for hands-on tutorials covering interactive, file-based, and programmatic workflows
|
|
- **Understand the UI**: Check the [Blueprint Panel Reference](../../reference/viewer/blueprints.md) for details on UI controls
|
|
- **Customize visualizations**: Learn about [Visualizers and Overrides](customize-views.md) for advanced per-entity customization
|
|
- **Explore the API**: Browse the [Blueprint API Reference](https://ref.rerun.io/docs/python/stable/common/blueprint_apis/) for programmatic control (Python)
|