Split the API examples into sub-pages

Cargo.toml

@@ -3,6 +3,7 @@ resolver = "2"
 members = [
   "crates/*",
   "examples/rust/*",
+  "docs/code-examples",
   "rerun_py",
   "run_wasm",
   "tests/rust/*",

docs/code-examples/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "code_examples"
+version = "0.7.0-alpha.0"
+edition = "2021"
+rust-version = "1.69"
+license = "MIT OR Apache-2.0"
+publish = false
+
+[[bin]]
+name = 'point2d_simple'
+path = 'point2d_simple.rs'
+
+[dependencies]
+rerun = { path = "../../crates/rerun", features = ["native_viewer"] }

docs/code-examples/point2d_random.py

@@ -0,0 +1,15 @@
+"""Log some random points with color and radii."""
+import rerun as rr
+from numpy.random import default_rng
+
+rr.init("points", spawn=True)
+rng = default_rng(12345)
+
+positions = rng.uniform(-3, 3, size=[10, 2])
+colors = rng.uniform(0, 255, size=[10, 3])
+radii = rng.uniform(0, 1, size=[10])
+
+rr.log_points("random", positions=positions, colors=colors, radii=radii)
+
+# Log an extra rect to set the view bounds
+rr.log_rect("bounds", [0, 0, 8, 6], rect_format=rr.RectFormat.XCYCWH)

docs/code-examples/point2d_simple.py

@@ -0,0 +1,9 @@
+"""Log some very simple points."""
+import rerun as rr
+
+rr.init("points", spawn=True)
+
+rr.log_points("simple", positions=[[0, 0], [1, 1]])
+
+# Log an extra rect to set the view bounds
+rr.log_rect("bounds", [0, 0, 4, 3], rect_format=rr.RectFormat.XCYCWH)

docs/code-examples/point2d_simple.rs

@@ -0,0 +1,29 @@
+//! Log some very simple points.
+use rerun::{
+    components::{Point2D, Rect2D, Vec4D},
+    MsgSender, RecordingStreamBuilder,
+};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let (rec_stream, storage) = RecordingStreamBuilder::new("points").memory()?;
+
+    let points = [[0.0, 0.0], [1.0, 1.0]]
+        .into_iter()
+        .map(Point2D::from)
+        .collect::<Vec<_>>();
+
+    MsgSender::new("points")
+        .with_component(&points)?
+        .send(&rec_stream)?;
+
+    // Log an extra rect to set the view bounds
+    MsgSender::new("bounds")
+        .with_component(&[Rect2D::XCYCWH(Vec4D([0.0, 0.0, 4.0, 3.0]))])?
+        .send(&rec_stream)?;
+
+    rec_stream.flush_blocking();
+
+    rerun::native_viewer::show(storage.take())?;
+
+    Ok(())
+}

docs/code-examples/point3d_random.py

@@ -0,0 +1,12 @@
+"""Log some random points with color and radii."""
+import rerun as rr
+from numpy.random import default_rng
+
+rr.init("points", spawn=True)
+rng = default_rng(12345)
+
+positions = rng.uniform(-5, 5, size=[10, 3])
+colors = rng.uniform(0, 255, size=[10, 3])
+radii = rng.uniform(0, 1, size=[10])
+
+rr.log_points("random", positions=positions, colors=colors, radii=radii)

docs/code-examples/point3d_simple.py

@@ -0,0 +1,6 @@
+"""Log some very simple points."""
+import rerun as rr
+
+rr.init("points", spawn=True)
+
+rr.log_points("simple", positions=[[0, 0, 0], [1, 1, 1]])

docs/content/concepts/entity-component.md

@@ -32,9 +32,9 @@ Primitives do not have any significance to the data model itself, but are import
 how data should be displayed.
 
 The assorted logging APIs all simply set different combinations of components on some specified entity, and the
-corresponding space views look for entities with these components in the data store.  
+corresponding space views look for entities with these components in the data store.
 For more information on the different primitives and how they relate to components see the
-[Primitives reference](../reference/primitives.md).
+[Data Types](../reference/data_types.md) reference.
 
 ### Extension Components
 Your entity could have any number of other components as well. This isn't a problem. Any components that
@@ -51,7 +51,7 @@ code-example: extension-components
 ### Empty Entities
 An Entity, without Components, is nothing more than an identity (represented by its Entity
 Path). It contains no data, and has no type. When you log a piece of data, all that you are doing is setting the values
-of one or more *Components* associated with that *Entity*. 
+of one or more *Components* associated with that *Entity*.
 
 ## ECS Systems
 In most ECS architectures, there is a third concept we haven't touched on: Systems are processes which operate on the

docs/content/getting-started/viewer-walkthrough.md

@@ -112,12 +112,12 @@ Feel free to move the views around until you are happy with the layout.
 ## Exploring data
 The space views are where you can see the data that was actually logged. This scene has streams of data for 6 different
 primitives, also known as [entities](../concepts/entity-component.md):
-* [images](../reference/primitives.md#tensors--images) that were captured from a camera.
-* [2d keypoints](../reference/primitives.md#point-2d) that were detected and tracked in those images.
-* a [camera](../reference/primitives.md#pinhole) model that describes the relationship between 2D and 3D space.
-* [3d points](../reference/primitives.md#point-3d) that were computed by the COLMAP slam pipeline.
-* A sequence of [transforms](../reference/primitives.md#rigid3d) describing the 3D location of the camera in space.
-* A [scalar](../reference/primitives.md#scalar) error metric that was computed by the algorithm for each frame.
+* [images](../reference/data_types/image.md) that were captured from a camera.
+* [2d keypoints](../reference/data_types/point2d.md) that were detected and tracked in those images.
+* a [pinhole](../reference/data_types/pinhole.md) camera model that describes the relationship between 2D and 3D space.
+* [3d points](../reference/data_types/point3d.md) that were computed by the COLMAP slam pipeline.
+* A sequence of [transforms](../reference/data_types/transform3d.md) describing the 3D location of the camera in space.
+* A [scalar](../reference/data_types/scalar.md) error metric that was computed by the algorithm for each frame.
 
 ### Hover and selection
 You can find out more about these entities by hovering over them in the different views. Hovering will bring up a
@@ -237,7 +237,6 @@ car. Leave the visible history with a value of 50.
   <source media="(max-width: 1200px)" srcset="https://static.rerun.io/be10b402dedc476ee1ac4d11402de6331b82fd83_viewer_walkthrough8_history_1200w.png">
   <img src="https://static.rerun.io/9c6a01f4dd2059641d92d121f8f2772203c56cfa_viewer_walkthrough8_history_full.png" alt="viewer walkthrough adjusting visible history screenshot">
 </picture>
-)
 
 ### Modifying the contents of a space view
 Now select the `/ (Spatial)` view itself. We will start by giving this space view a different name. At the very

docs/content/howto/ros2-nav-turtlebot.md

@@ -2,10 +2,10 @@
 title: Using Rerun with ROS 2
 order: 2
 ogImageUrl: /docs-media/og-howto-ros.jpg
-description: Rerun does not yet have native ROS support, but many of the concepts in ROS and Rerun line up fairly well. In this guide, you will learn how to write a simple ROS 2 python node that subscribes to some common ROS topics and logs them to Rerun. 
+description: Rerun does not yet have native ROS support, but many of the concepts in ROS and Rerun line up fairly well. In this guide, you will learn how to write a simple ROS 2 python node that subscribes to some common ROS topics and logs them to Rerun.
 ---
 
-Rerun does not yet have native ROS support, but many of the concepts in ROS and Rerun 
+Rerun does not yet have native ROS support, but many of the concepts in ROS and Rerun
 line up fairly well. In this guide, you will learn how to write a simple ROS 2 python node
 that subscribes to some common ROS topics and logs them to Rerun.
 
@@ -103,25 +103,25 @@ the environment.
 If you are familiar with the turtlebot nav example and rviz, this view will likely be familiar:
 
  * `map/box` is a placeholder for the map. (This will eventually be a map: [#1531](https://github.com/rerun-io/rerun/issues/1531).)
- * `map/robot` is a transform representing the robot pose logged as a [rigid3 transform](../reference/primitives.md#transform).
- * `map/robot/urdf` contains the `URDF` logged as a [mesh3d](../reference/primitives.md#mesh).
- * `map/robot/scan` contains a `LaserScan` msg logged as a [linestrip3d](../reference/primitives.md#line-3d). (This will eventually be a
+ * `map/robot` is a transform representing the robot pose logged as a rigid [transform3d](../reference/data_types/transform3d.md).
+ * `map/robot/urdf` contains the `URDF` logged as a [mesh](../reference/data_types/mesh.md).
+ * `map/robot/scan` contains a `LaserScan` msg logged as a [linestrip3d](../reference/data_types/linestrip3d.md). (This will eventually be a
    native type: [#1534](https://github.com/rerun-io/rerun/issues/1534).)
- * `map/robot/camera` contains a `CameraInfo` msg logged as a [pinhole transform](../reference/primitives.md#transform).
- * `map/robot/camera/img` contains an `Image` msg logged as an [image](../reference/primitives.md#tensors--images).
- * `map/robot/camera/points` contains a `PointCloud2` msg logged as a [point3d batch](../reference/primitives.md#point-3d).
+ * `map/robot/camera` contains a `CameraInfo` msg logged as a [pinhole](../reference/data_types/pinhole.md) transform.
+ * `map/robot/camera/img` contains an `Image` msg logged as an [image](../reference/data_types/image.md).
+ * `map/robot/camera/points` contains a `PointCloud2` msg logged as a [point3d](../reference/data_types/point3d.md).
  * `map/points` contains a second copy of `PointCloud2` with a different transform.  (This is a workaround until Rerun
    has support for ROS-style fixed frames [#1522](https://github.com/rerun-io/rerun/issues/1522).)
- * `odometry/vel` is a plot of the linear velocity of the robot.
- * `odometry/ang_vel` is a plot of the angular velocity of the robot.
+ * `odometry/vel` is a plot of the linear velocity of the robot logged as a [scalar](../reference/data_types/scalar.md).
+ * `odometry/ang_vel` is a plot of the angular velocity of the robot logged as a [scalar](../reference/data_types/scalar.md).
 
 ## Code Explanation
 
 It may be helpful to open [rerun/examples/python/ros_node/main.py](https://github.com/rerun-io/rerun/blob/main/examples/python/ros_node/main.py)
 to follow along.
 
 Outside of TF, the node is mostly stateless. At a very high level, for each ROS message we are interested in, we create a
-subscriber with a callback that does some form of data transformation and then logs the data to Rerun. 
+subscriber with a callback that does some form of data transformation and then logs the data to Rerun.
 
 For simplicity, this example uses the rosclpy `MultiThreadedExecutor` and `ReentrantCallbackGroup` for each topic. This
 allows each callback thread to do TF lookups without blocking the other incoming messages. More advanced ROS execution
@@ -383,7 +383,7 @@ not respecting the scale hint.  To accommodate this, we manually re-scale the
 camera link.
 
 Once we have correctly re-scaled the camera component, we can send the whole scene to rerun with
-`rerun_urdf.log_scene`. 
+`rerun_urdf.log_scene`.
 ```python
 def urdf_callback(self, urdf_msg: String) -> None:
     """Log a URDF using `log_scene` from `rerun_urdf`."""

docs/content/reference/data_types.md

@@ -0,0 +1,43 @@
+---
+title: Loggable Data Types
+order: 2
+---
+
+Rerun comes with built-in support for a number of different types that can be logged via the Python and Rust Logging
+APIs and then visualized in the [Viewer](viewer.md).
+
+The top-level types are called **archetypes** to differentiate them from the lower-level **data types** that make up the
+individual components.  For more information on the relationship between **archetypes** and **components**, check out
+the concept page on [Entities and Components](../concepts/entity-component.md).
+
+In [Python](https://ref.rerun.io) every **archetype** is typically backed by one or more function calls. In
+contrast, the [Rust API](https://docs.rs/rerun/) works by building up entities of a given archetype explicitly by
+assembling the required components.
+
+## Spatial **Archetypes**
+The spatial archetypes represent 2d and 3d spatial data. These types have some notion of a coordinate system and
+generally support spatial transformations. All of these types can be visualized by the `Spatial` space view.
+* [Arrow3D](data_types/arrow3d.md)
+* [Rect2D](data_types/rect2d.md)
+* [Box3D](data_types/box3d.md)
+* [Linestrip2D](data_types/linestrip2d.md)
+* [Linestrip3D](data_types/linestrip3d.md)
+* [Mesh](data_types/mesh.md)
+* [Point2D](data_types/point2d.md)
+* [Point3D](data_types/point3d.md)
+* [Transform3D](data_types/transform3d.md)
+* [Pinhole](data_types/pinhole.md)
+
+## Image & Tensor **Archetypes**
+Image and tensor archetypes all build on top of a common tensor component. The tensor component is a multi-dimensional
+generic container for arrays of data. Images are restricted to tensors of rank 2 or rank 3; these can be viewed in the
+`Spatial` space view. Generic tensors of greater rank can only be viewed in the specialized `Tensor` space view.
+* [Image](data_types/image.md)
+* [DepthImage](data_types/depth_image.md)
+* [SegmentationImage](data_types/segmentation_image.md)
+* [Tensor](data_types/tensor.md)
+
+## Other **Archetypes**
+* [Scalar](data_types/scalar.md): a single scalar / metric value. Can be viewed in the `TimeSeries` space view.
+* [TextEntry](data_types/text_entry.md): captures text data. Can be viewed in the `Text` space view.
+* [AnnotationContext](data_types/annotation_context.md): not viewed directly, but provides classes, labels, and connectivity information for other entities.

docs/content/reference/data_types/annotation_context.md

@@ -0,0 +1,10 @@
+---
+title: AnnotationContext
+order: 50
+---
+## Components and APIs
+Primary component: `annotation_context`
+
+Python APIs: [log_annotation_context](https://ref.rerun.io/docs/python/latest/common/annotations/#rerun.log_annotation_context)
+
+Rust API: [AnnotationContext](https://docs.rs/rerun/latest/rerun/components/struct.AnnotationContext.html)

docs/content/reference/data_types/arrow3d.md

@@ -0,0 +1,12 @@
+---
+title: Arrow3D
+order: 1
+---
+## Components and APIs
+Primary component: `arrow3d`
+
+Secondary components: `colorrgba`, `radius`, `label`
+
+Python APIs: [log_arrow](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_arrow)
+
+Rust API: [Arrow3D](https://docs.rs/rerun/latest/rerun/components/struct.Arrow3D.html)

docs/content/reference/data_types/box3d.md

@@ -0,0 +1,12 @@
+---
+title: Box3D
+order: 3
+---
+## Components and APIs
+Primary component: `box3d`,
+
+Secondary components: `vec3d`, `quaternion`, `colorrgba`, `radius`, `label`, `classid`
+
+Python APIs: [log_obb](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_obb)
+
+Rust API: [Box3D](https://docs.rs/rerun/latest/rerun/components/struct.Box3D.html)

docs/content/reference/data_types/depth_image.md

@@ -0,0 +1,12 @@
+---
+title: DepthImage
+order: 21
+---
+## Components and APIs
+Primary component: `tensor`
+
+Secondary components: `draw_order`
+
+Python APIs: [log_depth_image](https://ref.rerun.io/docs/python/latest/common/images/#rerun.log_depth_image**),
+
+Rust API: [Tensor](https://docs.rs/rerun/latest/rerun/components/struct.Tensor.html)

docs/content/reference/data_types/image.md

@@ -0,0 +1,18 @@
+---
+title: Image
+order: 20
+---
+
+## Components and APIs
+## Components and APIs
+Primary component: `tensor`
+
+Secondary components: `colorrgba`, `draw_order`
+
+Python APIs: [log_image](https://ref.rerun.io/docs/python/latest/common/images/#rerun.log_image**), [log_image_file](https://ref.rerun.io/docs/python/latest/common/images/#rerun.log_image_file**),
+
+Rust API: [Tensor](https://docs.rs/rerun/latest/rerun/components/struct.Tensor.html)
+
+`colorrgba` is currently only supported for images,
+i.e. tensors with 2 dimensions and an optional 3rd that can be interpreted as color channels.
+Furthermore, only the spatial Space View is able to use the color component.

docs/content/reference/data_types/linestrip2d.md

@@ -0,0 +1,13 @@
+---
+title: Linestrip2D
+order: 4
+---
+
+## Components and APIs
+Primary component: `linestrip2d`
+
+Secondary components: `colorrgba`, `radius`, `draw_order`
+
+Python APIs: [log_line_strip](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_line_strip), [log_line_segments](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_line_segments)
+
+Rust API: [LineStrip2D](https://docs.rs/rerun/latest/rerun/components/struct.LineStrip2D.html)

docs/content/reference/data_types/linestrip3d.md

@@ -0,0 +1,12 @@
+---
+title: Linestrip3D
+order: 5
+---
+## Components and APIs
+Primary component: `linestrip3d`
+
+Secondary components: `colorrgba`, `radius`
+
+Python APIs: [log_line_strip](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_line_strip), [log_line_segments](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_line_segments)
+
+Rust API: [LineStrip3D](https://docs.rs/rerun/latest/rerun/components/struct.LineStrip3D.html)

docs/content/reference/data_types/mesh.md

@@ -0,0 +1,12 @@
+---
+title: Mesh
+order: 6
+---
+## Components and APIs
+Primary component: `mesh3d`
+
+Secondary components: `colorrgba`
+
+Python APIs: [log_mesh](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_mesh), [log_meshes](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_meshes), [log_mesh_file](https://ref.rerun.io/docs/python/latest/common/spatial_primitives/#rerun.log_mesh_file)
+
+Rust API: [Mesh3D](https://docs.rs/rerun/latest/rerun/components/enum.Mesh3D.html)

docs/content/reference/data_types/pinhole.md

@@ -0,0 +1,10 @@
+---
+title: Pinhole
+order: 10
+---
+## Components and APIs
+Primary component: `pinhole`
+
+Python APIs: [log_pinhole](https://ref.rerun.io/docs/python/latest/common/transforms/#rerun.log_pinhole)
+
+Rust API: [Pinhole](https://docs.rs/rerun/latest/rerun/components/struct.Pinhole.html)