Rerun C++ SDK

https://ref.rerun.io/docs/cpp/
Admin
The Rerun C++ SDK enables developers to log data directly from C++ applications to the Rerun viewer,...
Tokens:963,854
Snippets:5,658
Trust Score:8.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Simple Tensor Example

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1Tensor.html

Example demonstrating how to log a simple tensor using the Rerun SDK.

```APIDOC
## Simple Tensor Example

```cpp
#include <rerun.hpp>
#include <algorithm> // std::generate
#include <random>
#include <vector>

int main(int argc, char* argv[]) {
    const auto rec = rerun::RecordingStream("rerun_example_tensor");
    rec.spawn().exit_on_failure();

    std::default_random_engine gen;
    // On MSVC uint8_t distributions are not supported.
    std::uniform_int_distribution<int> dist(0, 255);

    std::vector<uint8_t> data(8 * 6 * 3 * 5);
    std::generate(data.begin(), data.end(), [&] { return static_cast<uint8_t>(dist(gen)); });

    rec.log(
        "tensor",
        rerun::Tensor({8, 6, 3, 5}, data).with_dim_names({"width", "height", "channel", "batch"})
    );

    return 0;
}
```
```

--------------------------------

### Run Rerun Example with Pixi

Source: https://ref.rerun.io/docs/cpp/md__2home_2runner_2__work_2reality_2reality_2rerun_2rerun__cpp_2arrow__cpp__install.html

Clone a Rerun C++ example project that uses Pixi for dependency management and run the example using Pixi's task runner.

```shell
git clone https://github.com/rerun-io/cpp-example-opencv-eigen
cd cpp-example-opencv-eigen
pixi run example
```

--------------------------------

### Depth to 3D Example

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1DepthImage.html

Example demonstrating how to log a depth image and back-project it to 3D by providing a pinhole camera model.

```APIDOC
## Depth to 3D Example

### Description
This example shows how to create and log a synthetic depth image. By logging a `rerun::Pinhole` camera model alongside the `rerun::DepthImage`, Rerun automatically back-projects the depth data into 3D space.

### Code
```cpp
#include <rerun.hpp>
#include <algorithm> // fill_n
#include <vector>

int main(int argc, char* argv[]) {
    const auto rec = rerun::RecordingStream("rerun_example_depth_image_3d");
    rec.spawn().exit_on_failure();

    // Create a synthetic depth image.
    const int HEIGHT = 200;
    const int WIDTH = 300;
    std::vector<uint16_t> data(WIDTH * HEIGHT, 65535);

    // Add some depth values
    for (auto y = 50; y < 150; ++y) {
        std::fill_n(data.begin() + y * WIDTH + 50, 100, static_cast<uint16_t>(20000));
    }
    for (auto y = 130; y < 180; ++y) {
        std::fill_n(data.begin() + y * WIDTH + 100, 180, static_cast<uint16_t>(45000));
    }

    // Log the pinhole camera model
    rec.log(
        "world/camera",
        rerun::Pinhole::from_focal_length_and_resolution(
            200.0f,
            {static_cast<float>(WIDTH), static_cast<float>(HEIGHT)}
        )
    );

    // Log the depth image with meter and colormap
    rec.log(
        "world/camera/depth",
        rerun::DepthImage(data.data(), {WIDTH, HEIGHT})
            .with_meter(10000.0)
            .with_colormap(rerun::components::Colormap::Viridis)
    );

    return 0;
}
```

### Explanation
- The `rerun::RecordingStream` is initialized and spawned.
- A synthetic depth image `data` is created using `std::vector<uint16_t>`.
- A `rerun::Pinhole` camera model is logged to the entity path `"world/camera"`. This provides the intrinsic parameters of the camera.
- The depth image is logged to `"world/camera/depth"` using `rerun::DepthImage`. The constructor takes a pointer to the raw pixel data and the image resolution.
- `.with_meter(10000.0)` sets the scale for depth units (10000 native units = 1 meter).
- `.with_colormap(rerun::components::Colormap::Viridis)` applies the Viridis colormap for visualization.
```

--------------------------------

### Install Pixi Package Manager

Source: https://ref.rerun.io/docs/cpp/md__2home_2runner_2__work_2reality_2reality_2rerun_2rerun__cpp_2arrow__cpp__install.html

Instructions for installing the Pixi package manager on different operating systems. Pixi simplifies cross-platform dependency management.

```shell
curl -fsSL https://pixi.sh/install.sh | bash
```

```powershell
iwr -useb https://pixi.sh/install.ps1 | iex
```

```shell
cargo install pixi
```

--------------------------------

### Try Send Recording Start Time (Nanos)

Source: https://ref.rerun.io/docs/cpp/recording__stream_8hpp_source.html

Attempts to set the start time of a recording in nanoseconds, returning an Error for explicit handling.

```cpp
Error try_send_recording_start_time_nanos(int64_t nanos) const;
```

--------------------------------

### Example Usage

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1CoordinateFrame.html

An example demonstrating how to use CoordinateFrame to change the coordinate system for logged entities.

```APIDOC
## Example: Change coordinate frame to different built-in frames

```cpp
#include <rerun.hpp>

int main(int argc, char* argv[]) {
    const auto rec = rerun::RecordingStream("rerun_example_transform3d_hierarchy");
    rec.spawn().exit_on_failure();
    rec.set_time_sequence("time", 0);

    rec.log(
        "red_box",
        rerun::Boxes3D::from_half_sizes({{0.5f, 0.5f, 0.5f}})
            .with_colors({rerun::Color(255, 0, 0)}),
        // Use Transform3D to place the box, so we actually change the underlying coordinate frame and not just the box's pose.
        rerun::Transform3D::from_translation({2.0f, 0.0f, 0.0f})
    );

    rec.log(
        "blue_box",
        rerun::Boxes3D::from_half_sizes({{0.5f, 0.5f, 0.5f}})
            .with_colors({rerun::Color(0, 0, 255)}),
        // Use Transform3D to place the box, so we actually change the underlying coordinate frame and not just the box's pose.
        rerun::Transform3D::from_translation({-2.0f, 0.0f, 0.0f})
    );

    rec.log("point", rerun::Points3D({{0.0f, 0.0f, 0.0f}}).with_radii({0.5f}));

    // Change where the point is located by cycling through its coordinate frame.
    const char* frame_ids[] = {"tf#/red_box", "tf#/blue_box"};
    for (int t = 0; t < 2; t++) {
        rec.set_time_sequence("time", t + 1); // leave it untouched at t==0.
        rec.log("point", rerun::CoordinateFrame(frame_ids[t]));
    }
}
```
```

--------------------------------

### Create RecordingInfo with Start Time

Source: https://ref.rerun.io/docs/cpp/recording__info_8hpp_source.html

Creates a RecordingInfo object and sets its start time. This method is intended for logging a single row's worth of data.

```cpp
RecordingInfo with_start_time(const rerun::components::Timestamp& _start_time) && {
 start_time =
 ComponentBatch::from_loggable(_start_time, Descriptor_start_time).value_or_throw();
 return std::move(*this);
 }
```

--------------------------------

### Clear Usage Example (C++)

Source: https://ref.rerun.io/docs/cpp/clear_8hpp_source.html

A C++ example demonstrating how to use the `Clear` API to remove logged arrows.

```APIDOC
## POST /api/examples/clear

### Description
This example demonstrates logging several 3D arrows and then clearing them one by one using the `rerun::Clear::FLAT` option.

### Method
POST

### Endpoint
`/api/examples/clear`

### Parameters
This endpoint does not have explicit parameters in the request body or path. The clearing logic is defined within the code.

### Request Example
```cpp
#include <rerun.hpp>
#include <cmath>
#include <numeric>
#include <string> // to_string
#include <vector>

int main(int argc, char* argv[]) {
    const auto rec = rerun::RecordingStream("rerun_example_clear");
    rec.spawn().exit_on_failure();

    std::vector<rerun::Vector3D> vectors = {
        {1.0, 0.0, 0.0},
        {0.0, -1.0, 0.0},
        {-1.0, 0.0, 0.0},
        {0.0, 1.0, 0.0},
    };
    std::vector<rerun::Position3D> origins = {
        {-0.5, 0.5, 0.0},
        {0.5, 0.5, 0.0},
        {0.5, -0.5, 0.0},
        {-0.5, -0.5, 0.0},
    };
    std::vector<rerun::Color> colors = {
        {200, 0, 0},
        {0, 200, 0},
        {0, 0, 200},
        {200, 0, 200},
    };

    // Log a handful of arrows.
    for (size_t i = 0; i < vectors.size(); ++i) {
        auto entity_path = "arrows/" + std::to_string(i);
        rec.log(
            entity_path,
            rerun::Arrows3D::from_vectors(vectors[i])
            .with_origins(origins[i])
            .with_colors(colors[i])
        );
    }

    // Now clear them, one by one on each tick.
    for (size_t i = 0; i < vectors.size(); ++i) {
        auto entity_path = "arrows/" + std::to_string(i);
        rec.log(entity_path, rerun::Clear::FLAT);
    }
}
```

### Response
This example does not explicitly define a response body. The effect is observed in the Rerun viewer.
```

--------------------------------

### Install Rerun SDK via Package Managers

Source: https://ref.rerun.io/docs/cpp/index.html

Commands to install the Rerun SDK and Viewer using conda or pixi.

```bash
conda install -c conda-forge librerun-sdk rerun-sdk
```

```bash
pixi add librerun-sdk rerun-sdk
```

--------------------------------

### RecordingInfo::with_start_time

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1RecordingInfo.html

Sets the start time for the recording.

```APIDOC
## with_start_time

### Description
Sets the start time for the recording. This should be an absolute time relative to the Unix Epoch.

### Parameters
#### Request Body
- **_start_time** (rerun::components::Timestamp) - Required - The start time of the recording.
```

--------------------------------

### Send Recording Start Time (Nanos) with Error Handling

Source: https://ref.rerun.io/docs/cpp/recording__stream_8hpp_source.html

Sets the start time of a recording in nanoseconds. Serialization errors are handled automatically.

```cpp
void send_recording_start_time_nanos(int64_t nanos) const {
try_send_recording_start_time_nanos(nanos).handle();
}
```

--------------------------------

### Install Rerun C++ SDK with CMake

Source: https://ref.rerun.io/docs/cpp/md__2home_2runner_2__work_2reality_2reality_2rerun_2rerun__cpp_2cmake__setup__in__detail.html

Commands to configure, build, and install the Rerun C++ SDK from a source distribution.

```bash
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
```

```bash
cmake --build build --config Release --target rerun_sdk
```

```bash
cmake --install build
```

--------------------------------

### Create RecordingInfo with Multiple Start Times

Source: https://ref.rerun.io/docs/cpp/recording__info_8hpp_source.html

Creates a RecordingInfo object and sets multiple start times in a single component batch. This is useful when used in conjunction with `columns`.

```cpp
RecordingInfo with_many_start_time(
 const Collection<rerun::components::Timestamp>& _start_time
 ) && {
 start_time =
 ComponentBatch::from_loggable(_start_time, Descriptor_start_time).value_or_throw();
 return std::move(*this);
 }
```

--------------------------------

### Rerun Text Log Integration Example

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1TextLog.html

This C++ example demonstrates logging text messages to Rerun. It includes direct logging of a text entry with a specific log level and setting up a Loguru callback to forward all logs.

```cpp
#include <loguru.hpp>
#include <rerun.hpp>
void loguru_to_rerun(void* user_data, const loguru::Message& message) {
// NOTE: `rerun::RecordingStream` is thread-safe.
const rerun::RecordingStream* rec = reinterpret_cast<const rerun::RecordingStream*>(user_data);
rerun::TextLogLevel level;
if (message.verbosity == loguru::Verbosity_FATAL) {
level = rerun::TextLogLevel::Critical;
} else if (message.verbosity == loguru::Verbosity_ERROR) {
level = rerun::TextLogLevel::Error;
} else if (message.verbosity == loguru::Verbosity_WARNING) {
level = rerun::TextLogLevel::Warning;
} else if (message.verbosity == loguru::Verbosity_INFO) {
level = rerun::TextLogLevel::Info;
} else if (message.verbosity == loguru::Verbosity_1) {
level = rerun::TextLogLevel::Debug;
} else if (message.verbosity == loguru::Verbosity_2) {
level = rerun::TextLogLevel::Trace;
} else {
level = rerun::TextLogLevel(std::to_string(message.verbosity));
}
rec->log(
"logs/handler/text_log_integration",
rerun::TextLog(message.message).with_level(level)
);
}
int main(int argc, char* argv[]) {
const auto rec = rerun::RecordingStream("rerun_example_text_log_integration");
rec.spawn().exit_on_failure();
// Log a text entry directly:
rec.log(
"logs",
rerun::TextLog("this entry has loglevel TRACE").with_level(rerun::TextLogLevel::Trace)
);
loguru::add_callback(
"rerun",
loguru_to_rerun,
const_cast<void*>(reinterpret_cast<const void*>(&rec)),
loguru::Verbosity_INFO
);
LOG_F(INFO, "This INFO log got added through the standard logging interface");
loguru::remove_callback("rerun"); // we need to do this before `rec` goes out of scope
}
```

--------------------------------

### Logging a 3D Asset from File

Source: https://ref.rerun.io/docs/cpp/asset3d_8hpp_source.html

Example of how to log a 3D asset from a file path using the C++ SDK.

```APIDOC
## POST /log/asset3d

### Description
Logs a 3D asset to the Rerun stream from a local file path.

### Method
POST

### Endpoint
`/log/asset3d`

### Parameters
#### Query Parameters
- **entity_path** (string) - Required - The entity path to log the asset to.

#### Request Body
- **file_path** (string) - Required - The path to the 3D asset file (e.g., .gltf, .glb, .obj, .stl).
- **media_type** (string) - Optional - The media type of the asset (e.g., `model/gltf-binary`). If omitted, Rerun will attempt to guess.
- **albedo_factor** (object) - Optional - A color multiplier for the asset. Example: `{"r": 1.0, "g": 0.5, "b": 0.2, "a": 1.0}`.

### Request Example
```json
{
  "entity_path": "world/asset",
  "file_path": "path/to/your/model.glb",
  "media_type": "model/gltf-binary",
  "albedo_factor": {
    "r": 1.0,
    "g": 0.5,
    "b": 0.2,
    "a": 1.0
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful logging of the asset.

#### Response Example
```json
{
  "message": "Asset logged successfully"
}
```
```

--------------------------------

### Log a directed graph in C++

Source: https://ref.rerun.io/docs/cpp/graph__edges_8hpp_source.html

Example showing how to log a directed graph using the GraphEdges archetype and the RecordingStream.

```cpp
#include <rerun.hpp>

int main(int argc, char* argv[]) {
const auto rec = rerun::RecordingStream("rerun_example_graph_directed");
rec.spawn().exit_on_failure();

rec.log(
"simple",
rerun::GraphNodes({"a", "b", "c"})
.with_positions({{0.0, 100.0}, {-100.0, 0.0}, {100.0, 0.0}})
.with_labels({"A", "B", "C"}),
rerun::GraphEdges({{"a", "b"}, {"b", "c"}, {"c", "a"}})
// Graphs are undirected by default.
.with_graph_type(rerun::components::GraphType::Directed)
);
}
```

--------------------------------

### Demo Utilities Header

Source: https://ref.rerun.io/docs/cpp/demo__utils_8hpp_source.html

Utility functions for linear interpolation and 3D grid generation used in Rerun C++ SDK examples.

```cpp
#pragma once

// Utilities used in examples.

#include <algorithm>
#include <cmath>
#include <vector>

#include "components/color.hpp"
#include "components/position3d.hpp"

namespace rerun {
 namespace demo {
 constexpr float PI = 3.14159265358979323846264338327950288f;
 constexpr float TAU = 6.28318530717958647692528676655900577f;

 /// A linear interpolator that bounces between `a` and `b` as `t` goes above `1.0`.
 inline float bounce_lerp(float a, float b, float t) {
 auto tf = t - floorf(t);
 if (static_cast<int32_t>(t) % 2 == 0) {
 return (1.0f - tf) * a + tf * b;
 } else {
 return tf * a + (1.0f - tf) * b;
 }
 }

 /// Linearly interpolates from `a` through `b` in `n` steps, returning the intermediate result at
 /// each step.
 template <typename T>
 inline std::vector<T> linspace(T start, T end, size_t num) {
 std::vector<T> linspaced(num);
 std::generate(linspaced.begin(), linspaced.end(), [&, i = 0]() mutable {
 return static_cast<T>(
 start + static_cast<T>(i++) * (end - start) / static_cast<T>(num - 1)
 );
 });
 return linspaced;
 }

 /// Given a range `from`-`to`, linearly interpolates between them in `n` steps along
 /// three axes each, returning the intermediate result at each step.
 template <typename T, typename Elem>
 std::vector<T> grid3d(Elem from, Elem to, size_t n) {
 std::vector<T> output;
 for (Elem z : linspace(from, to, n)) {
 for (Elem y : linspace(from, to, n)) {
 for (Elem x : linspace(from, to, n)) {
 output.emplace_back(
 static_cast<Elem>(x),
 static_cast<Elem>(y),
 static_cast<Elem>(z)
 );
 }
 }
 }
 return output;
 }

 /// Create a spiral of points with colors along the Z axis.
 ///
 /// * `num_points`: Total number of points.
 /// * `radius`: The radius of the spiral.
 /// * `angular_step`: The factor applied between each step along the trigonometric circle.
 /// * `angular_offset`: Offsets the starting position on the trigonometric circle.
 /// * `z_step`: The factor applied between each step along the Z axis.
```

--------------------------------

### Logging a 3D Asset from Bytes

Source: https://ref.rerun.io/docs/cpp/asset3d_8hpp_source.html

Example of how to log a 3D asset directly from byte data using the C++ SDK.

```APIDOC
## POST /log/asset3d/bytes

### Description
Logs a 3D asset to the Rerun stream directly from its byte data.

### Method
POST

### Endpoint
`/log/asset3d/bytes`

### Parameters
#### Query Parameters
- **entity_path** (string) - Required - The entity path to log the asset to.

#### Request Body
- **bytes** (string) - Required - The raw byte data of the 3D asset, typically base64 encoded.
- **media_type** (string) - Optional - The media type of the asset (e.g., `model/gltf-binary`). If omitted, Rerun will attempt to guess.
- **albedo_factor** (object) - Optional - A color multiplier for the asset. Example: `{"r": 1.0, "g": 0.5, "b": 0.2, "a": 1.0}`.

### Request Example
```json
{
  "entity_path": "world/asset_from_bytes",
  "bytes": "SU5WQUxJRF9EQVRB==", // Base64 encoded asset data
  "media_type": "model/obj",
  "albedo_factor": {
    "r": 0.8,
    "g": 0.8,
    "b": 0.8,
    "a": 1.0
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful logging of the asset.

#### Response Example
```json
{
  "message": "Asset logged successfully from bytes"
}
```
```

--------------------------------

### Log Images with Various Formats

Source: https://ref.rerun.io/docs/cpp/image_8hpp_source.html

Demonstrates logging images in different formats including RGB, luminance (green channel only), BGR, and YUV422. This example requires the Rerun viewer to be running.

```cpp
#include <algorithm>
#include <cstdint>
#include <vector>

#include <rerun.hpp>

int main(int argc, char* argv[]) {
const auto rec = rerun::RecordingStream("rerun_example_image_formats");
rec.spawn().exit_on_failure();

// Simple gradient image
std::vector<uint8_t> image(256 * 256 * 3);
for (size_t y = 0; y <256; ++y) {
for (size_t x = 0; x <256; ++x) {
image[(y * 256 + x) * 3 + 0] = static_cast<uint8_t>(x);
image[(y * 256 + x) * 3 + 1] = static_cast<uint8_t>(std::min<size_t>(255, x + y));
image[(y * 256 + x) * 3 + 2] = static_cast<uint8_t>(y);
}
}

// RGB image
rec.log("image_rgb", rerun::Image::from_rgb24(image, {256, 256}));

// Green channel only (Luminance)
std::vector<uint8_t> green_channel(256 * 256);
for (size_t i = 0; i <256 * 256; ++i) {
green_channel[i] = image[i * 3 + 1];
}
rec.log(
"image_green_only",
rerun::Image(rerun::borrow(green_channel), {256, 256}, rerun::ColorModel::L)
);

// BGR image
std::vector<uint8_t> bgr_image(256 * 256 * 3);
for (size_t i = 0; i <256 * 256; ++i) {
bgr_image[i * 3 + 0] = image[i * 3 + 2];
bgr_image[i * 3 + 1] = image[i * 3 + 1];
bgr_image[i * 3 + 2] = image[i * 3 + 0];
}
rec.log(
"image_bgr",
rerun::Image(rerun::borrow(bgr_image), {256, 256}, rerun::ColorModel::BGR)
);

// New image with Separate Y/U/V planes with 4:2:2 chroma downsampling
std::vector<uint8_t> yuv_bytes(256 * 256 + 128 * 256 * 2);
std::fill_n(yuv_bytes.begin(), 256 * 256, static_cast<uint8_t>(128)); // Fixed value for Y
size_t u_plane_offset = 256 * 256;
size_t v_plane_offset = u_plane_offset + 128 * 256;
for (size_t y = 0; y <256; ++y) {
for (size_t x = 0; x <128; ++x) {
auto coord = y * 128 + x;
yuv_bytes[u_plane_offset + coord] = static_cast<uint8_t>(x * 2); // Gradient for U
yuv_bytes[v_plane_offset + coord] = static_cast<uint8_t>(y); // Gradient for V
}
}
rec.log(
"image_yuv422",
rerun::Image(rerun::borrow(yuv_bytes), {256, 256}, rerun::PixelFormat::Y_U_V16_FullRange)
);

return 0;
}
```

--------------------------------

### Segmentation Example

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1AnnotationContext.html

Example demonstrating how to use AnnotationContext with SegmentationImage.

```APIDOC
## Segmentation Example

### Description
This example demonstrates how to create an annotation context to describe classes and then log a segmentation image using these annotations.

### Code
```cpp
#include <rerun.hpp>
#include <algorithm> // fill_n
#include <vector>

int main(int argc, char* argv[]) {
    const auto rec = rerun::RecordingStream("rerun_example_annotation_context_segmentation");
    rec.spawn().exit_on_failure();

    // create an annotation context to describe the classes
    rec.log_static(
        "segmentation",
        rerun::AnnotationContext({
            rerun::AnnotationInfo(1, "red", rerun::Rgba32(255, 0, 0)),
            rerun::AnnotationInfo(2, "green", rerun::Rgba32(0, 255, 0)),
        })
    );

    // create a segmentation image
    const int HEIGHT = 200;
    const int WIDTH = 300;
    std::vector<uint8_t> data(WIDTH * HEIGHT, 0);

    for (auto y = 50; y < 100; ++y) {
        std::fill_n(data.begin() + y * WIDTH + 50, 70, static_cast<uint8_t>(1));
    }
    for (auto y = 100; y < 180; ++y) {
        std::fill_n(data.begin() + y * WIDTH + 130, 150, static_cast<uint8_t>(2));
    }

    rec.log("segmentation/image", rerun::SegmentationImage(data.data(), {WIDTH, HEIGHT}));

    return 0;
}
```

### Related Types
- `rerun::RecordingStream`: A `RecordingStream` handles everything related to logging data into Rerun.
- `rerun::archetypes::AnnotationContext`: Archetype: The annotation context provides additional information on how to display entities.
- `rerun::archetypes::SegmentationImage`: Archetype: An image made up of integer components::ClassIds.
- `rerun::datatypes::AnnotationInfo`: Datatype: Annotation info annotating a class id or key-point id.
- `rerun::datatypes::Rgba32`: Datatype: An RGBA color with unmultiplied/separate alpha, in sRGB gamma space with linear alpha.
```

--------------------------------

### Logging Randomly Distributed 2D Points

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1Points2D.html

This example demonstrates how to log a collection of 2D points with random positions, colors, and radii.

```APIDOC
## Log Random 2D Points

### Description
Logs a batch of 2D points with randomly generated positions, colors, and radii.

### Method
`rec.log()`

### Endpoint
`"random"`

### Parameters
#### Request Body
- **`rerun::Points2D`** (object) - Required - A `Points2D` object configured with positions, colors, and radii.
  - **`positions`** (array of `rerun::Position2D`) - Required - The 2D coordinates of the points.
  - **`colors`** (array of `rerun::Color`) - Optional - The colors for each point.
  - **`radii`** (array of `rerun::Radius`) - Optional - The radii for each point.

### Request Example
```cpp
const auto rec = rerun::RecordingStream("rerun_example_points2d_random");
rec.spawn().exit_on_failure();
std::vector<rerun::Position2D> points2d(10);
std::generate(points2d.begin(), points2d.end(), [&] { return rerun::Position2D(dist_pos(gen), dist_pos(gen)); });
std::vector<rerun::Color> colors(10);
std::generate(colors.begin(), colors.end(), [&] { return rerun::Color(static_cast<uint8_t>(dist_color(gen)), static_cast<uint8_t>(dist_color(gen)), static_cast<uint8_t>(dist_color(gen))); });
std::vector<rerun::Radius> radii(10);
std::generate(radii.begin(), radii.end(), [&] { return dist_radius(gen); });
rec.log("random", rerun::Points2D(points2d).with_colors(colors).with_radii(radii));
```

### Response
#### Success Response (200)
Data logged successfully to the Rerun recording stream.

#### Response Example
(No specific response body for logging operations, success is indicated by the absence of errors.)
```

--------------------------------

### Options Class Constructor and Configuration Methods

Source: https://ref.rerun.io/docs/cpp/cxxopts_8hpp_source.html

Initializes the Options class with program name and help string, and provides methods to configure positional help, custom help, and option parsing behavior.

```cpp
class Options {
    public:
    explicit Options(std::string program_name, std::string help_string = "")
    : m_program(std::move(program_name)),
      m_help_string(toLocalString(std::move(help_string))),
      m_custom_help("[OPTION...]"),
      m_positional_help("positional parameters"),
      m_show_positional(false),
      m_allow_unrecognised(false),
      m_width(76),
      m_tab_expansion(false),
      m_options(std::make_shared<OptionMap>()) {}

    Options& positional_help(std::string help_text) {
    m_positional_help = std::move(help_text);
    return *this;
    }

    Options& custom_help(std::string help_text) {
    m_custom_help = std::move(help_text);
    return *this;
    }

    Options& show_positional_help() {
    m_show_positional = true;
    return *this;
    }

    Options& allow_unrecognised_options() {
    m_allow_unrecognised = true;
    return *this;
    }

    Options& set_width(std::size_t width) {
    m_width = width;
    return *this;
    }

    Options& set_tab_expansion(bool expansion = true) {
    m_tab_expansion = expansion;
    return *this;
    }

    ParseResult parse(int argc, const char* const* argv);

    OptionAdder add_options(std::string group = "");

    void add_options(const std::string& group, std::initializer_list<Option> options);

    void add_option(const std::string& group, const Option& option);

    void add_option(
    const std::string& group, const std::string& s, const OptionNames& l, std::string desc,
    const std::shared_ptr<const Value>& value, std::string arg_help
    );

    void add_option(
    const std::string& group, const std::string& short_name,
    const std::string& single_long_name, std::string desc,
    const std::shared_ptr<const Value>& value, std::string arg_help
    ) {
    OptionNames long_names;
    long_names.emplace_back(single_long_name);
    add_option(group, short_name, long_names, desc, value, arg_help);
    }
    };
```

--------------------------------

### Combine Regular and Instance Transforms in C++

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1InstancePoses3D.html

Demonstrates logging a 3D box and points, then applying both a regular transform and an instance pose to the box over time.

```cpp
#include <rerun.hpp>
#include <rerun/demo_utils.hpp>
int main(int argc, char* argv[]) {
const auto rec = rerun::RecordingStream("rerun_example_instance_pose3d_combined");
rec.set_time_sequence("frame", 0);
// Log a box and points further down in the hierarchy.
rec.log("world/box", rerun::Boxes3D::from_half_sizes({{1.0, 1.0, 1.0}}));
rec.log(
"world/box/points",
rerun::Points3D(rerun::demo::grid3d<rerun::Position3D, float>(-10.0f, 10.0f, 10))
);
for (int i = 0; i <180; ++i) {
rec.set_time_sequence("frame", i);
// Log a regular transform which affects both the box and the points.
rec.log(
"world/box",
rerun::Transform3D::from_rotation(rerun::RotationAxisAngle{
{0.0f, 0.0f, 1.0f},
rerun::Angle::degrees(static_cast<float>(i) * 2.0f)})
);
// Log an instance pose which affects only the box.
rec.log(
"world/box",
rerun::InstancePoses3D().with_translations(
{{0.0f, 0.0f, std::abs(static_cast<float>(i) * 0.1f - 5.0f) - 5.0f}}
)
);
}
}
```

--------------------------------

### ComponentBatch Creation

Source: https://ref.rerun.io/docs/cpp/text__document_8hpp_source.html

Demonstrates how to create a ComponentBatch from a collection of component instances.

```APIDOC
## ComponentBatch::from_loggable

### Description
Creates a new component batch from a collection of component instances.

### Method
`static Result<ComponentBatch> from_loggable<T>(const Collection<T>& components, const ComponentDescriptor& descriptor)`

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "components": "[component instances]",
  "descriptor": "component descriptor"
}
```

### Response
#### Success Response (200)
- **ComponentBatch** (ComponentBatch) - A newly created component batch.

#### Response Example
```json
{
  "component_batch": "[component batch data]"
}
```
```

--------------------------------

### Get Scalars Component Descriptor

Source: https://ref.rerun.io/docs/cpp/scalars_8hpp_source.html

Access `Descriptor_scalars` to get the `ComponentDescriptor` for the scalars field, used for schema definition.

```cpp
rerun::archetypes::Scalars::Descriptor_scalars
static constexpr auto Descriptor_scalars
ComponentDescriptor for the scalars field.
**Definition** scalars.hpp:89
```

--------------------------------

### Use Installed Rerun SDK in CMake Projects

Source: https://ref.rerun.io/docs/cpp/md__2home_2runner_2__work_2reality_2reality_2rerun_2rerun__cpp_2cmake__setup__in__detail.html

How to locate and include the installed Rerun SDK in external CMake projects.

```cmake
find_package(rerun_sdk REQUIRED)
```

--------------------------------

### Demonstrates Manual Use of Video Frame References

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1AssetVideo.html

This example shows how to log a video asset and then reference specific frames manually using their timestamps.

```APIDOC
## POST /api/videos/manual_frames

### Description
Logs a video asset and then logs specific frames from that asset using manual timestamp references.

### Method
POST

### Endpoint
/api/videos/manual_frames

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the video file.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "video_path": "/path/to/your/video.mp4"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful logging of the video asset and frame references.

#### Response Example
```json
{
  "message": "Video asset and frame references logged successfully."
}
```
```

--------------------------------

### Log a 3D asset from a file

Source: https://ref.rerun.io/docs/cpp/asset3d_8hpp_source.html

Demonstrates how to load a 3D model from a file path and log it to a Rerun recording stream.

```cpp
#include <rerun.hpp>

#include <iostream>

int main(int argc, char* argv[]) {
if (argc <2) {
std::cerr <<"Usage: " <<argv[0] <<" <path_to_asset.[gltf|glb|obj|stl]>" <<std::endl;
return 1;
}

const auto path = argv[1];

const auto rec = rerun::RecordingStream("rerun_example_asset3d");
rec.spawn().exit_on_failure();

rec.log_static("world", rerun::ViewCoordinates::RIGHT_HAND_Z_UP); // Set an up-axis
rec.log("world/asset", rerun::Asset3D::from_file_path(path).value_or_throw());
}
```

--------------------------------

### Log data to Rerun

Source: https://ref.rerun.io/docs/cpp/index.html

Initialize a recording stream, spawn a viewer, and log archetypes like points and images to specific entity paths.

```cpp
// Create a recording stream.
rerun::RecordingStream rec("rerun_example_app");
// Spawn the viewer and connect to it.
rec.spawn().exit_on_failure();
std::vector<rerun::Position3D> points = create_positions();
std::vector<rerun::Color> colors = create_colors();
std::vector<uint8_t> image_data = create_image();
// Log a batch of points.
rec.log("path/to/points", rerun::Points3D(points).with_colors(colors));
// Log an image.
rec.log("path/to/image", rerun::Image::from_rgba32(image_data, {786, 1024}));
```

--------------------------------

### ComponentBatch Creation

Source: https://ref.rerun.io/docs/cpp/line__strips2d_8hpp_source.html

Demonstrates how to create a ComponentBatch from a collection of components.

```APIDOC
## ComponentBatch Creation

### Description
Creates a new component batch from a collection of component instances.

### Method
```cpp
static Result<ComponentBatch> from_loggable(const rerun::Collection<T>& components, const ComponentDescriptor& descriptor);
```

### Parameters

- **components** (rerun::Collection<T>) - Required - The collection of component instances.
- **descriptor** (rerun::ComponentDescriptor) - Required - The descriptor for the component type.

### Returns

- `Result<ComponentBatch>` - A result containing the created ComponentBatch on success, or an error on failure.
```

--------------------------------

### Log Points and Ellipsoids with Rerun

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1Ellipsoids3D.html

This example demonstrates logging both 3D points and 3D ellipsoids using the Rerun SDK. It includes generating random points and defining ellipsoids with specific centers, half-sizes, and colors. Ensure the Rerun SDK is initialized and a stream is available.

```cpp
#include <rerun.hpp>
#include <algorithm>
#include <random>
#include <vector>
int main(int argc, char* argv[]) {
const auto rec = rerun::RecordingStream("rerun_example_ellipsoid_simple");
rec.spawn().exit_on_failure();
const float sigmas[3] = {5.0f, 3.0f, 1.0f};
std::default_random_engine gen;
std::normal_distribution<float> dist(0.0, 1.0f);
std::vector<rerun::Position3D> points3d(50000);
std::generate(points3d.begin(), points3d.end(), [&] {
return rerun::Position3D(
sigmas[0] * dist(gen),
sigmas[1] * dist(gen),
sigmas[2] * dist(gen)
);
});
rec.log(
"points",
rerun::Points3D(points3d).with_radii(0.02f).with_colors(rerun::Rgba32(188, 77, 185))
);
rec.log(
"ellipsoid",
rerun::Ellipsoids3D::from_centers_and_half_sizes(
{
{0.0f, 0.0f, 0.0f},
{0.0f, 0.0f, 0.0f},
},
{
{sigmas[0], sigmas[1], sigmas[2]},
{3.0f * sigmas[0], 3.0f * sigmas[1], 3.0f * sigmas[2]},
}
)
.with_colors({
rerun::Rgba32(255, 255, 0),
rerun::Rgba32(64, 64, 0),
})
);
}
```

--------------------------------

### Log files from path

Source: https://ref.rerun.io/docs/cpp/classrerun_1_1RecordingStream.html

Logs a file from a filesystem path using available importers.

```cpp
void | log_file_from_path (const std::filesystem::path &filepath, std::string_view entity_path_prefix=std::string_view(), bool static_=false) const
```

```cpp
Error | try_log_file_from_path (const std::filesystem::path &filepath, std::string_view entity_path_prefix=std::string_view(), bool static_=false) const
```

--------------------------------

### Depth to 3D Example

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1DepthImage.html

Logs a synthetic depth image and a pinhole camera model to reconstruct a 3D scene. Ensure the data pointer outlives the DepthImage object.

```cpp
#include <rerun.hpp>
#include <algorithm> // fill_n
#include <vector>
int main(int argc, char* argv[]) {
const auto rec = rerun::RecordingStream("rerun_example_depth_image_3d");
rec.spawn().exit_on_failure();
// Create a synthetic depth image.
const int HEIGHT = 200;
const int WIDTH = 300;
std::vector<uint16_t> data(WIDTH * HEIGHT, 65535);
for (auto y = 50; y <150; ++y) {
std::fill_n(data.begin() + y * WIDTH + 50, 100, static_cast<uint16_t>(20000));
}
for (auto y = 130; y <180; ++y) {
std::fill_n(data.begin() + y * WIDTH + 100, 180, static_cast<uint16_t>(45000));
}
// If we log a pinhole camera model, the depth gets automatically back-projected to 3D
rec.log(
"world/camera",
rerun::Pinhole::from_focal_length_and_resolution(
200.0f,
{static_cast<float>(WIDTH), static_cast<float>(HEIGHT)}
)
);
rec.log(
"world/camera/depth",
rerun::DepthImage(data.data(), {WIDTH, HEIGHT})
.with_meter(10000.0)
.with_colormap(rerun::components::Colormap::Viridis)
);
}
```

--------------------------------

### rerun::components::Timestamp

Source: https://ref.rerun.io/docs/cpp/recording__info_8hpp_source.html

Represents the time when a recording started.

```APIDOC
## rerun::components::Timestamp

### Description
Component: When the recording started.

### Definition
`timestamp.hpp:16`
```

--------------------------------

### Logging a GridMap

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1GridMap.html

Example of how to log a GridMap archetype to a Rerun RecordingStream.

```APIDOC
## Logging a GridMap

### Description
This example demonstrates how to create and log a `GridMap` archetype, simulating an occupancy grid map.

### Method
POST (Implicitly via `rec.log`)

### Endpoint
`/world/map` (Example path)

### Parameters
#### Request Body (Implicitly constructed by `rerun::archetypes::GridMap()`)
- **data** (rerun::components::ImageBuffer) - Required - The raw grid data.
- **format** (rerun::components::ImageFormat) - Required - The format of the grid's image data.
- **cell_size** (float) - Required - The scene unit size of a single grid cell.
- **translation** (rerun::components::Translation3D) - Optional - Translation of the lower-left corner of the grid map.

### Request Example
```cpp
#include <rerun.hpp>
#include <vector>

int main(int argc, char* argv[]) {
    const auto rec = rerun::RecordingStream("rerun_example_grid_map");
    rec.spawn().exit_on_failure();

    const size_t width = 64;
    const size_t height = 64;
    const float cell_size = 0.1f;

    // Create a synthetic image with ROS `nav_msgs/OccupancyGrid` cell value conventions:
    // -1 (255) unknown, 0 free, 100 occupied.
    std::vector<uint8_t> grid(width * height, 255);
    for (size_t y = 8; y < 56; ++y) {
        for (size_t x = 8; x < 56; ++x) {
            grid[y * width + x] = 0;
        }
    }
    for (size_t y = 20; y < 44; ++y) {
        for (size_t x = 20; x < 44; ++x) {
            grid[y * width + x] = 100;
        }
    }

    rec.log(
        "world/map",
        rerun::archetypes::GridMap()
            .with_data(rerun::components::ImageBuffer(grid))
            .with_format(rerun::components::ImageFormat(
                {width, height},
                rerun::ColorModel::L,
                rerun::ChannelDatatype::U8
            ))
            .with_cell_size(cell_size)
            .with_translation({
                -(static_cast<float>(width) * cell_size) / 2.0f,
                -(static_cast<float>(height) * cell_size) / 2.0f,
                0.0f
            })
    );

    return 0;
}
```

### Response
(Rerun logs data asynchronously, no direct response to `log` calls. Success is indicated by lack of errors.)
```

--------------------------------

### Get Collection Size

Source: https://ref.rerun.io/docs/cpp/classrerun_1_1Collection.html

Returns the number of elements currently in the collection.

```cpp
size_t size() const
```

--------------------------------

### Log file from path

Source: https://ref.rerun.io/docs/cpp/recording__stream_8hpp_source.html

Ingests a file using available importers, blocking until streaming begins or all importers fail.

```cpp
void log_file_from_path(
const std::filesystem::path& filepath,
std::string_view entity_path_prefix = std::string_view(), bool static_ = false
) const {
try_log_file_from_path(filepath, entity_path_prefix, static_).handle();
}
```

--------------------------------

### RecordingInfo::with_many_start_time

Source: https://ref.rerun.io/docs/cpp/structrerun_1_1archetypes_1_1RecordingInfo.html

Sets multiple start times for batch processing.

```APIDOC
## with_many_start_time

### Description
Allows packing multiple start_time values into a single component batch. This is intended for use with columnar data.

### Parameters
#### Request Body
- **_start_time** (Collection<rerun::components::Timestamp>) - Required - A collection of start times.
```

--------------------------------

### Get Program Name

Source: https://ref.rerun.io/docs/cpp/cxxopts_8hpp_source.html

Returns the program name. This is a const member function.

```cpp
const std::string& program() const {
return m_program;
}
```
Tokens:
Raw