Improve rerun.notebook.Viewer constructor (#9495)

For a while now, the `use_global_recording` param of
`rr.notebook.Viewer` didn't actually do as advertised. Setting it to
`False` would make the `Viewer` constructor ignore (almost) all other
parameters.

The original intent for that parameter was to allow creating a
completely empty Viewer. The new behavior is:
- `use_global_recording` defaults to `False` if a `url` is provided.
- `use_global_recording` defaults to `True` otherwise.
- If no explicit recording is provided, and `use_global_recording` is
`True`, then we use `get_data_recording` to pick up either the
thread-local or global recording.

This means it is now possible to create a completely empty Viewer, and
that is the default behavior given no params, and no global recording:
```python
import rerun as rr

rr.notebook.Viewer()
```

If a `url` is provided, then by default we only show that `url`:
```python
import rerun as rr

rr.notebook.Viewer(url="https://app.rerun.io/version/nightly/examples/arkit_scenes.rrd")
```

Using both a `url` and either an explicit/global `recording` is still
possible:
```python
import rerun as rr

rec = rr.RecordingStream("rerun_example_dual_recording")
rr.notebook.Viewer(
  url="https://app.rerun.io/version/nightly/examples/arkit_scenes.rrd",
  recording=rec,
)

# alternatively, call `add_recording` later:
rec = rr.RecordingStream("rerun_example_dual_recording")
viewer = rr.notebook.Viewer(
  url="https://app.rerun.io/version/nightly/examples/arkit_scenes.rrd",
)
viewer.add_recording(rec)
viewer.display()

# or just let it pick up the global recording:
rr.init("rerun_example_global_recording_notebook")
rr.notebook.Viewer(
  url="https://app.rerun.io/version/nightly/examples/arkit_scenes.rrd",
  use_global_recording=True,
)
```

If no `url` is provided, we pick up the global recording by default, but
it can be turned off:
```python
import rerun as rr

rr.init("rerun_example_global_recording_notebook")
rr.notebook.Viewer() # uses global recording

rr.init("rerun_example_global_recording_notebook")
rr.notebook.Viewer(use_global_recording=False) # will be empty
```

Author: jprochazk

examples/python/notebook/cube.ipynb

@@ -191,7 +191,7 @@
    "source": [
     "## Starting a new recording\n",
     "\n",
-    "You can always start another recording by calling `rr.init(...)` again to reset the global stream, or alternatively creating a separate recording stream using `rr.new_recording` (discussed more below)"
+    "You can always start another recording by calling `rr.init(...)` again to reset the global stream, or alternatively creating a separate recording stream using the `rr.RecordingStream` constructor (discussed more below)"
    ]
   },
   {
@@ -316,7 +316,7 @@
     "STEPS = 100\n",
     "twists = math.pi * np.sin(np.linspace(0, math.tau, STEPS)) / 4\n",
     "for t in range(STEPS):\n",
-    "    rr.set_time_sequence(\"step\", t)\n",
+    "    rr.set_time(\"step\", sequence=t)\n",
     "    h_grid = build_color_grid(10, 3, 3, twist=twists[t])\n",
     "    rr.log(\"h_grid\", rr.Points3D(h_grid.positions, colors=h_grid.colors, radii=0.5))\n",
     "    v_grid = build_color_grid(3, 3, 10, twist=twists[t])\n",
@@ -347,7 +347,7 @@
     "STEPS = 100\n",
     "twists = math.pi * np.sin(np.linspace(0, math.tau, STEPS)) / 4\n",
     "for t in range(STEPS):\n",
-    "    rr.set_time_sequence(\"step\", t)\n",
+    "    rr.set_time(\"step\", sequence=t)\n",
     "    h_grid = build_color_grid(10, 3, 3, twist=twists[t])\n",
     "    rr.log(\"h_grid\", rr.Points3D(h_grid.positions, colors=h_grid.colors, radii=0.5))\n",
     "    v_grid = build_color_grid(3, 3, 10, twist=twists[t])\n",
@@ -363,7 +363,7 @@
    "source": [
     "## Working with non-global streams\n",
     "\n",
-    "Sometimes it can be more explicit to work with specific (non-global recording) streams via the `new_recording` method.\n",
+    "Sometimes it can be more explicit to work with specific (non-global recording) streams via `rr.RecordingStream` constructor.\n",
     "\n",
     "In this case, remember to call `notebook_show` directly on the recording stream. As noted above, there is no way to use a bare Blueprint object in conjunction with a non-global recording."
    ]
@@ -375,7 +375,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "rec = rr.new_recording(\"rerun_example_cube_flat\")\n",
+    "rec = rr.RecordingStream(\"rerun_example_cube_flat\")\n",
     "\n",
     "bp = rrb.Blueprint(collapse_panels=True)\n",
     "\n",
@@ -404,7 +404,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "rec = rr.new_recording(\"rerun_example_multi_recording\", recording_id=uuid.uuid4())\n",
+    "rec = rr.RecordingStream(\"rerun_example_multi_recording\", recording_id=uuid.uuid4())\n",
     "\n",
     "flat_grid = build_color_grid(20, 20, 1, twist=0)\n",
     "rec.log(\"flat_grid\", rr.Points3D(flat_grid.positions, colors=flat_grid.colors, radii=0.5))\n",
@@ -416,19 +416,19 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 15,
    "id": "40354733-7feb-45fe-8ba6-dbbdbc070983",
    "metadata": {},
    "outputs": [],
    "source": [
-    "rec = rr.new_recording(\"rerun_example_multi_recording\", recording_id=uuid.uuid4())\n",
+    "rec = rr.RecordingStream(\"rerun_example_multi_recording\", recording_id=uuid.uuid4())\n",
     "\n",
     "viewer.add_recording(rec)\n",
     "\n",
     "STEPS = 100\n",
     "twists = math.pi * np.sin(np.linspace(0, math.tau, STEPS)) / 4\n",
     "for t in range(STEPS):\n",
-    "    rr.set_time(\"step\", sequence=t)\n",
+    "    rec.set_time(\"step\", sequence=t)\n",
     "    cube = build_color_grid(10, 10, 10, twist=twists[t])\n",
     "    rec.log(\"cube\", rr.Points3D(cube.positions, colors=cube.colors, radii=0.5))"
    ]
@@ -450,12 +450,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "viewer = rr.notebook.Viewer(use_global_recording=False)\n",
+    "viewer = rr.notebook.Viewer()\n",
     "viewer.display()\n",
     "\n",
     "recordings = [\n",
-    "    rr.new_recording(\"rerun_example_time_ctrl\", recording_id=\"example_a\"),\n",
-    "    rr.new_recording(\"rerun_example_time_ctrl\", recording_id=\"example_b\"),\n",
+    "    rr.RecordingStream(\"rerun_example_time_ctrl\", recording_id=\"example_a\"),\n",
+    "    rr.RecordingStream(\"rerun_example_time_ctrl\", recording_id=\"example_b\"),\n",
     "]\n",
     "\n",
     "rec_colors = {\"example_a\": [0, 255, 0], \"example_b\": [255, 0, 0]}\n",
@@ -465,10 +465,10 @@
     "\n",
     "STEPS = 100\n",
     "twists = math.pi * np.sin(np.linspace(0, math.tau, STEPS)) / 4\n",
-    "for t in range(STEPS):\n",
-    "    cube = build_color_grid(10, 10, 10, twist=twists[t])\n",
-    "    for rec in recordings:\n",
-    "        rr.set_time(\"step\", sequence=t)\n",
+    "for rec in recordings:\n",
+    "    for t in range(STEPS):\n",
+    "        cube = build_color_grid(10, 10, 10, twist=twists[t])\n",
+    "        rec.set_time(\"step\", sequence=t)\n",
     "        rec.log(\"cube\", rr.Points3D(cube.positions, colors=rec_colors[rec.get_recording_id()], radii=0.5))"
    ]
   },
@@ -482,7 +482,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": 22,
    "id": "3d6804d6",
    "metadata": {},
    "outputs": [],
@@ -500,7 +500,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 28,
+   "execution_count": 23,
    "id": "30d0107b",
    "metadata": {},
    "outputs": [],

rerun_py/rerun_sdk/rerun/notebook.py

@@ -87,7 +87,7 @@ def __init__(
         url: str | None = None,
         blueprint: BlueprintLike | None = None,
         recording: RecordingStream | None = None,
-        use_global_recording: bool = True,
+        use_global_recording: bool | None = None,
     ) -> None:
         """
         Create a new Rerun viewer widget for use in a notebook.
@@ -115,10 +115,12 @@ def __init__(
 
             Setting this is equivalent to calling [`rerun.send_blueprint`][] before initializing the viewer.
         use_global_recording:
-            Whether or not the Viewer should default to the global recording in case no explicit `recording`
-            is specified.
+            If no explicit `recording` is provided, the Viewer uses the thread-local/global recording created by `rr.init`
+            or set explicitly via `rr.set_thread_local_data_recording`/`rr.set_global_data_recording`.
 
-            If this is set to `False`, then `blueprint` is ignored.
+            Settings this to `False` causes the Viewer to not pick up the global recording.
+
+            Defaults to `False` if `url` is provided, and `True` otherwise.
 
         """
 
@@ -150,24 +152,27 @@ def __init__(
             url=url,
         )
 
+        # By default, we use the global recording only if no `url` is provided.
+        if use_global_recording is None:
+            use_global_recording = url is None
+
         if use_global_recording:
             recording = get_data_recording(recording)
-            if recording is None:
-                if url is None:
-                    raise ValueError("No recording or url specified and no active recording found")
-                elif blueprint is not None:
-                    raise ValueError(
-                        "Can only set a blueprint if there's either an active recording or a recording passed in"
-                    )
+
+        if recording is not None:
+            bindings.set_callback_sink(
+                recording=recording.to_native(),
+                callback=self._flush_hook,
+            )
+
+        if blueprint is not None:
+            if recording is not None:
+                recording.send_blueprint(blueprint)
             else:
-                bindings.set_callback_sink(
-                    recording=recording.to_native(),
-                    callback=self._flush_hook,
+                raise ValueError(
+                    "Can only set a blueprint if there's either an active recording or a recording passed in"
                 )
 
-                if blueprint is not None:
-                    recording.send_blueprint(blueprint)
-
     def add_recording(
         self,
         recording: RecordingStream | None = None,