|
1 | 1 | --- |
2 | 2 | title: Configure the Viewer through code |
3 | | -order: 100 |
| 3 | +hidden: true |
| 4 | +redirect: howto/visualization/configure-viewer-through-code |
4 | 5 | --- |
5 | | - |
6 | | -As of Rerun 0.15, the state of the [blueprint](../reference/viewer/blueprint.md) can be directly manipulated using the |
7 | | -Rerun SDK. |
8 | | - |
9 | | -In the initial 0.15 release, the APIs are still somewhat limited and only available in the Python SDK. |
10 | | -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). |
11 | | - |
12 | | -## Blueprint API overview |
13 | | - |
14 | | -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: |
15 | | - |
16 | | -```python |
17 | | -import rerun.blueprint as rrb |
18 | | -``` |
19 | | - |
20 | | -The Python blueprint API is declarative and object-centric. There are 3 main types of blueprint objects you will |
21 | | -encounter: |
22 | | - |
23 | | -- `Blueprint`: The root object that represents the entire Viewer layout. |
24 | | -- `Container`: A layout object that contains other containers or views. |
25 | | -- `SpaceView`: A view object that represents a single view of the data. |
26 | | - |
27 | | -Both containers and spaceviews should be used via typed subclasses instead.: |
28 | | - |
29 | | -- `Container` has subclasses: `Horizontal`, `Vertical`, `Grid`, and `Tabs`. |
30 | | -- `SpaceView` has subclasses: `BarChartView`, `Spatial2DView`, `Spatial3DView`, `TensorView`, |
31 | | - `TextDocumentView`, `TextLogView`, and `TimeSeriesView`. |
32 | | - |
33 | | -These paths can be combined hierarchically to create a complex Viewer layout. |
34 | | - |
35 | | -For example: |
36 | | - |
37 | | -```python |
38 | | -my_blueprint = rrb.Blueprint( |
39 | | - rrb.Horizontal( |
40 | | - rrb.BarChartView(), |
41 | | - rrb.Vertical( |
42 | | - rrb.Spatial2DView(), |
43 | | - rrb.Spatial3DView(), |
44 | | - ), |
45 | | - ), |
46 | | -) |
47 | | -``` |
48 | | - |
49 | | -## Sending the blueprint to the Viewer |
50 | | - |
51 | | -To provide a blueprint, simply pass it to either `init` or `connect` using the `default_blueprint` |
52 | | -parameter. |
53 | | - |
54 | | -Using `init` with `spawn=True`: |
55 | | - |
56 | | -```python |
57 | | -my_blueprint = rrb.Blueprint(...) |
58 | | - |
59 | | -rr.init("rerun_example_my_blueprint", spawn=True, default_blueprint=my_blueprint) |
60 | | -``` |
61 | | - |
62 | | -Or if you use `connect` separate from `init`: |
63 | | - |
64 | | -```python |
65 | | -my_blueprint = rrb.Blueprint(...) |
66 | | - |
67 | | -rr.init("rerun_example_my_blueprint") |
68 | | - |
69 | | -... |
70 | | - |
71 | | -rr.connect(default_blueprint=my_blueprint) |
72 | | -``` |
73 | | - |
74 | | -## Activating the default blueprint |
75 | | - |
76 | | -Just like the Viewer can store many different recordings internally, it can also |
77 | | -store many different blueprints. For each `application_id` in the viewer, are two |
78 | | -particularly important blueprints: the "default blueprint" and the "active blueprint". |
79 | | - |
80 | | -When a recording is selected, the active blueprint for the corresponding |
81 | | -`application_id` will completely determine what is displayed by the viewer. |
82 | | - |
83 | | -When you send a blueprint to the viewer, it will not necessarily be |
84 | | -activated immediately. The standard behavior is to only update the "default |
85 | | -blueprint" in the viewer. This minimizes the chance that you accidentally |
86 | | -overwrite blueprint edits you may have made locally. |
87 | | - |
88 | | -If you want to start using the new blueprint, after sending it, you will need to |
89 | | -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 |
90 | | -current default. |
91 | | - |
92 | | -## Always activating the blueprint |
93 | | - |
94 | | -If you want to always activate the blueprint as soon as it is received, you can instead use the `send_blueprint` |
95 | | -API. This API has two flags `make_active` and `make_default`, both of which default to `True`. |
96 | | - |
97 | | -If `make_active` is set, the blueprint will be activated immediately. Exercise care in using this API, as it can be |
98 | | -surprising for users to have their blueprint changed without warning. |
99 | | - |
100 | | -```python |
101 | | -my_blueprint = rrb.Blueprint(...) |
102 | | - |
103 | | -rr.init("rerun_example_my_blueprint", spawn=True) |
104 | | - |
105 | | -rr.send_blueprint(my_blueprint, make_active=True) |
106 | | - |
107 | | -``` |
108 | | - |
109 | | -## Customizing space views |
110 | | - |
111 | | -Any of the space views (`BarChartView`, `Spatial2DView`, `Spatial3DView`, `TensorView`, |
112 | | -`TextDocumentView`, `TextLogView`, or `TimeSeriesView`) can be instantiated with no arguments. |
113 | | -By default these views try to include all compatible entities. |
114 | | - |
115 | | -For example, the following blueprint creates a single 3D view that includes all the 3D content |
116 | | -you have logged to the entity tree: |
117 | | - |
118 | | -```python |
119 | | -rrb.Blueprint( |
120 | | - rrb.Spatial3DView() |
121 | | -) |
122 | | -``` |
123 | | - |
124 | | -Beyond instantiating the space views, there are 3 parameters you may want to specify: `name`, `origin`, and `contents`. |
125 | | - |
126 | | -`name` is simply the name of the view used as a label in the viewer. |
127 | | - |
128 | | -However, both `origin` and `contents` play an important role in determining what data is included in the view. |
129 | | - |
130 | | -### `origin` |
131 | | - |
132 | | -The `origin` of a space-view is a generalized "frame of reference" for the view. We think of showing all data |
133 | | -in the space view as relative to the `origin`. |
134 | | - |
135 | | -By default, only data that is under the `origin` will be included in the view. As such this is one of the most |
136 | | -convenient ways of restricting a space-view to a particular subtree. |
137 | | - |
138 | | -Because the data in the space-view is relative to the `origin`, the `origin` will be the first entity displayed |
139 | | -in the blueprint tree, with all entities under the origin shown using relative paths. |
140 | | - |
141 | | -For Spatial views such as `Spatial2DView` and `Spatial3DView`, the `origin` plays an additional role with respect |
142 | | -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. |
143 | | - |
144 | | -For example: |
145 | | - |
146 | | -```python |
147 | | -rrb.Blueprint( |
148 | | - rrb.Horizontal( |
149 | | - rrb.Spatial3DView(origin="/world"), |
150 | | - rrb.Spatial2DView(origin="/world/robot/camera"), |
151 | | - ) |
152 | | -) |
153 | | -``` |
154 | | - |
155 | | -### `contents` |
156 | | - |
157 | | -If you need to further modify the contents of a space view, you can use the `contents` parameter. This parameter is |
158 | | -a list of [entity query expressions](../reference/) that are either included or excluded from the |
159 | | -view. |
160 | | - |
161 | | -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. |
162 | | - |
163 | | -When combining multiple expressions, the "most specific" rule wins. |
164 | | - |
165 | | -Additionally, these expressions can reference `$origin` to refer to the origin of the space view. |
166 | | - |
167 | | -For example: |
168 | | - |
169 | | -```python |
170 | | -rrb.Blueprint( |
171 | | - rrb.Horizontal( |
172 | | - rrb.Spatial3DView( |
173 | | - origin="/world", |
174 | | - contents=[ |
175 | | - "+ $origin/robot/**", |
176 | | - ], |
177 | | - ), |
178 | | - rrb.Spatial2DView( |
179 | | - origin="/world/robot/camera", |
180 | | - contents=[ |
181 | | - "+ $origin/**", |
182 | | - "+ /world/robot/actuator/**", |
183 | | - ], |
184 | | - ), |
185 | | - ) |
186 | | -) |
187 | | -``` |
188 | | - |
189 | | -## Implicit conversion |
190 | | - |
191 | | -For convenience all of the blueprint APIs take a `BlueprintLike` rather than requiring a `Blueprint` object. |
192 | | -Both `SpaceView`s and `Containers` are considered `BlueprintLike`. Similarly, the `Blueprint` object can |
193 | | -take a `SpaceView` or `Container` as an argument. |
194 | | - |
195 | | -All of the following are equivalent: |
196 | | - |
197 | | -```python |
198 | | -rr.send_blueprint(rrb.Spatial3DView()) |
199 | | -``` |
200 | | - |
201 | | -```python |
202 | | -rr.send_blueprint( |
203 | | - rrb.Grid( |
204 | | - Spatial3DView(), |
205 | | - ) |
206 | | -) |
207 | | -``` |
208 | | - |
209 | | -```python |
210 | | -rr.send_blueprint( |
211 | | - rrb.Blueprint( |
212 | | - Spatial3DView(), |
213 | | - ), |
214 | | -) |
215 | | - |
216 | | -``` |
217 | | - |
218 | | -```python |
219 | | -rr.send_blueprint( |
220 | | - rrb.Blueprint( |
221 | | - rrb.Grid( |
222 | | - Spatial3DView(), |
223 | | - ) |
224 | | - ), |
225 | | -) |
226 | | -``` |
227 | | - |
228 | | -## Customizing the top-level blueprint |
229 | | - |
230 | | -The top-level `Blueprint` object can also be customized. |
231 | | - |
232 | | -### Controlling the panel state |
233 | | - |
234 | | -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. |
235 | | - |
236 | | -```python |
237 | | -rrb.Blueprint( |
238 | | - rrb.TimePanel(state="collapsed") |
239 | | -) |
240 | | -``` |
241 | | - |
242 | | -As an convenience, you can also use the blueprint argument: `collapse_panels=True` as a short-hand for: |
243 | | - |
244 | | -```python |
245 | | -rrb.Blueprint( |
246 | | - rrb.TimePanel(state="collapsed"), |
247 | | - rrb.SelectionPanel(state="collapsed"), |
248 | | - rrb.BlueprintPanel(state="collapsed"), |
249 | | -) |
250 | | -``` |
251 | | - |
252 | | -### Controlling the auto behaviors |
253 | | - |
254 | | -The blueprint has two additional parameters that influence the behavior of the viewer: |
255 | | - |
256 | | -- `auto_space_views` controls whether the Viewer will automatically create space views for entities that are not explicitly included in the blueprint. |
257 | | -- `auto_layout` controls whether the Viewer should automatically layout the containers when introducing new space-views. |
258 | | - |
259 | | -If you pass in your own `SpaceView` or `Container` objects, these will both default to `False` so that the Blueprint |
260 | | -you get is exactly what you specify. Otherwise they will default to `True` so that you will still get content (this |
261 | | -matches the default behavior of the Viewer if no blueprint is provided). |
262 | | - |
263 | | -This means that: |
264 | | - |
265 | | -```python |
266 | | -rrb.Blueprint() |
267 | | -``` |
268 | | - |
269 | | -and |
270 | | - |
271 | | -```python |
272 | | -rrb.Blueprint( |
273 | | - auto_space_views=True, |
274 | | - auto_layout=True |
275 | | -) |
276 | | -``` |
277 | | - |
278 | | -are both equivalent to the viewer's default behavior. |
279 | | - |
280 | | -If you truly want to create an empty blueprint, you must set both values to `False`: |
281 | | - |
282 | | -```python |
283 | | -rrb.Blueprint( |
284 | | - auto_space_views=False, |
285 | | - auto_layout=False |
286 | | -), |
287 | | -``` |
0 commit comments