Add a how-to guide for using Rerun with custom data

CHANGELOG.md

@@ -65,7 +65,7 @@
  - The visualizer can now show coordinate arrows for all affine transforms within the view. [#2577](https://github.com/rerun-io/rerun/pull/2577)
  - Linestrips and oriented bounding boxes can now be logged via batch APIs in python.
    - See: `log_linestrips_2d`, `log_linestrips_3d`, [#2822](https://github.com/rerun-io/rerun/pull/2822) and `log_obbs` [#2823](https://github.com/rerun-io/rerun/pull/2823)
- - Rust users that build their own Viewer applications can now add fully custom Space Views. Find more information [here](https://www.rerun.io/docs/howto/extend-ui#custom-space-views-classes).
+ - Rust users that build their own Viewer applications can now add fully custom Space Views. Find more information [here](https://www.rerun.io/docs/howto/extend/extend-ui#custom-space-views-classes).
  - New optional `flush_timeout` specifies how long Rerun will wait if a TCP stream is disconnected during a flush. [#2821](https://github.com/rerun-io/rerun/pull/2821)
    - In Rust, `RecordingStream::connect` now requires `flush_timeout` specified as an `Option<Duration>`.
      - To keep default behavior, this can be specified using the `rerun::default_flush_time()` helper.

docs/content/howto.md

@@ -7,4 +7,6 @@ Guides for using Rerun in more advanced ways.
  - [Limit RAM use](howto/limit-ram.md)
  - [Using Rerun with ROS2](howto/ros2-nav-turtlebot.md)
  - [Embedding Rerun within a Notebook](howto/notebook.md)
- - [Extend the Viewer UI using Rust](howto/extend-ui.md)
+ - [Extending Rerun](howto/extend)
+    - [By using custom data](howto/extend/custom-data.md)
+    - [By extending the Viewer in Rust](howto/extend/extend-ui.md)

docs/content/howto/extend.md

@@ -0,0 +1,15 @@
+---
+title: Extend Rerun
+order: 6
+---
+
+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 the Rerun Viewer](extend/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
+- data stores
+- data transforms
+- custom rendering
+- custom UI interactions
+
+If you're in need of a particular kind of extension mechanism that we don't yet support. Head over to [GitHub](https://github.com/rerun-io/rerun/issues) and either upvote an existing issue or open a new one.

docs/content/howto/extend/custom-data.md

@@ -0,0 +1,51 @@
+---
+title: Use custom data
+order: 2
+description: How to use Rerun with custom data
+---
+Rerun comes with many pre-built [loggable data types](../../reference/data_types.md) that you can use out of the box. As long as your own data can be decomposed into Rerun [components](../../reference/data_types/components.md) or can be serialized with [Apache Arrow](https://arrow.apache.org/), you can log it directly without needing to recompile Rerun.
+
+All you need to do is implement the `AsComponents` [Python protocol](https://ref.rerun.io/docs/python/prerelease/package/rerun/__init__/#rerun.AsComponents) or [Rust trait](https://docs.rs/rerun/0.9.0-alpha.6/rerun/trait.AsComponents.html), which means implementing the function, `as_component_batches()`.
+
+## Remapping to a Rerun archetype
+Let's start with a simple example where you have your own point cloud class that is perfectly representable as a Rerun archetype.
+```python
+@dataclass
+class LabeledPoints:
+    points: np.ndarray
+    labels: List[str])
+```
+
+If you implement `as_component_batches()` on `LabeledPoints`, you can pass it directly to `rr.log`. The simplest possible way is to use the matching Rerun archetype’s `as_component_batches` method.
+
+```python
+import rerun as rr  # pip install rerun-sdk
+
+@dataclass
+class LabeledPoints:
+    points: np.ndarray
+    labels: List[str])
+
+    def as_component_batches(self) -> Iterable[rr.ComponentBatch]:
+        return rr.Points3D(positions=self.points,
+                           labels=self.labels).as_component_batches()
+…
+# Somewhere deep in your code
+classified = my_points_classifier(…)  # type: LabeledPoints
+rr.log("points/classified", classified)
+```
+
+## Custom archetypes and components
+You can also define and log your own custom archetypes and components completely from user code, without rebuilding Rerun.
+
+In this example we extend the Rerun Points3D archetype with custom confidence and indicator components.
+
+code-example: custom_data
+
+<picture>
+  <img src="https://static.rerun.io/custom_data/7bb90e1ab4244541164775473c5106e15152b8d0/full.png" alt="">
+  <source media="(max-width: 480px)" srcset="https://static.rerun.io/custom_data/7bb90e1ab4244541164775473c5106e15152b8d0/480w.png">
+  <source media="(max-width: 768px)" srcset="https://static.rerun.io/custom_data/7bb90e1ab4244541164775473c5106e15152b8d0/768w.png">
+  <source media="(max-width: 1024px)" srcset="https://static.rerun.io/custom_data/7bb90e1ab4244541164775473c5106e15152b8d0/1024w.png">
+  <source media="(max-width: 1200px)" srcset="https://static.rerun.io/custom_data/7bb90e1ab4244541164775473c5106e15152b8d0/1200w.png">
+</picture>

docs/content/howto/extend-ui.md → docs/content/howto/extend/extend-ui.md

@@ -1,11 +1,9 @@
 ---
-title: Extend the Viewer UI in Rust
-order: 4
+title: Extend the Viewer in Rust
+order: 2
 description: How to extend the Rerun Viewer UI using Rust and egui
 ---
 
-# What you can build
-
 ## Custom UI embedding the Viewer
 
 ![The Rerun Viewer, extended with a custom panel to the right](https://github.com/rerun-io/rerun/assets/1148717/cbbad63e-9b18-4e54-bafe-b6ffd723f63e)