Expand description
Rerun - Visualize streams of multimodal data.
Add the rerun
library to your crate with cargo add rerun
.
There is also a rerun
binary.
The binary is required in order to stream log data
over the networks, and to open our .rrd
data files.
If you need it, install the rerun
binary with cargo install rerun-cli
.
Feature flags
-
analytics
(enabled by default) — Enable telemetry using our analytics SDK. -
demo
(enabled by default) — Demo helpers for examples. -
glam
(enabled by default) — Add support for some math operations usingglam
. Only relevant if featuresdk
is enabled. -
image
(enabled by default) — Integration with theimage
crate, plus JPEG support. -
log
(enabled by default) — Integration with thelog
crate. -
native_viewer
— Support spawning a native viewer. This adds a lot of extra dependencies, so only enable this feature if you need it! -
server
(enabled by default) — Support for running a TCP server that listens to incoming log messages from a Rerun SDK. -
sdk
(enabled by default) — Embed the Rerun SDK and re-export all of its public symbols. -
web_viewer
— Support serving a web viewer over HTTP.Enabling this inflates the binary size quite a bit, since it embeds the viewer wasm.
For faster & easier builds, a pre-built web-views comes bundled with the crate as a Wasm binary. Enabling this feature will embed this pre-built web viewer.
However, when building from source in the repository, this feature adds quite a bit to the compile time since it requires compiling and bundling the viewer as wasm. You also need to install some additional tools, which you can do by running
scripts/setup_web.sh
.
Links
There are many different ways of sending data to the Rerun Viewer depending on what you’re trying to achieve and whether the viewer is running in the same process as your code, in another process, or even as a separate web application.
Checkout SDK Operating Modes for an overview of what’s possible and how.
If you get stuck on anything, open an issue at https://github.com/rerun-io/rerun/issues. You can also ask questions on the Rerun Discord.
Using the rerun
binary
The rerun
binary is required in order to stream log data
over the networks, and to open our .rrd
data files.
The binary can act either as a server, a viewer, or both, depending on which options you use when you start it.
Install it with cargo install rerun-cli
.
Running just rerun
will start the viewer, waiting for the logging library to connect
using RecordingStreamBuilder::connect
(see below).
You can run rerun --help
for more info.
Using the rerun
library
Logging
You first create a RecordingStream
using RecordingStreamBuilder
.
You then use it to log some archetypes
to a given EntityPath
using RecordingStream::log
:
// Stream log data to an awaiting `rerun` process.
let rec = rerun::RecordingStreamBuilder::new("rerun_example_app")
.connect(rerun::default_server_addr(), rerun::default_flush_timeout())?;
let points: Vec<rerun::Position3D> = positions();
let colors: Vec<rerun::Color> = colors();
let image: image::DynamicImage = capture_image();
rec.set_time_sequence("frame", 42);
rec.log("path/to/points", &rerun::Points3D::new(points).with_colors(colors))?;
rec.log("path/to/image", &rerun::Image::try_from(image)?)?;
Streaming to disk
Streaming data to a file on disk using the .rrd
format:
let rec = rerun::RecordingStreamBuilder::new("rerun_example_app").save("my_data.rrd")?;
Buffering
You can buffer the log messages in memory and then show them in an embedded viewer:
let (rec, storage) = rerun::RecordingStreamBuilder::new("rerun_example_app").memory()?;
log_to(&rec);
// Will block program execution!
rerun::native_viewer::show(storage.take());
cargo install rerun
rerun --help
Forwarding text log events to Rerun
See Logger
.
Modules
- Integration with integration with the
clap
command line argument parser. - Components are the basic building blocks of
archetypes
. - Coordinate system helpers, for use with
components::ViewCoordinates
. - The low-level datatypes that
components
are built from. - This module contains utilities to support Rerun examples.
- Re-exports of other crates.
- Things directly related to logging.
- Methods for spawning the native viewer and streaming the SDK log stream to it.
- Different destinations for log messages.
- Time-related types.
- Transform helpers, for use with
components::Transform3D
. - Methods for spawning the web viewer and streaming the SDK log stream to it.
Structs
- Archetype: The
AnnotationContext
provides additional information on how to display entities. - The user-chosen name of the application doing the logging.
- The fully-qualified name of an
Archetype
, e.g.rerun.archetypes.Points3D
. - Archetype: 3D arrows with optional colors, radii, labels, etc.
- Archetype: A prepacked 3D asset (
.gltf
,.glb
,.obj
, etc.). - Archetype: A bar chart.
- Archetype: 2D boxes with half-extents and optional center, rotations, rotations, colors etc.
- Archetype: 3D boxes with half-extents and optional center, rotations, rotations, colors etc.
- Datatype: The description of a semantic Class.
- Archetype: Empties all the components of an entity.
- Component: An RGBA color with unmultiplied/separate alpha, in sRGB gamma space with linear alpha.
- The fully-qualified name of a
Component
, e.g.rerun.components.Position2D
. - The fully-qualified name of a
Datatype
, e.g.rerun.datatypes.Vec2D
. - Archetype: A depth image.
- Archetype: Specifies that the entity path at which this is logged is disconnected from its parent.
- The unique identifier of an entity, e.g.
camera/"ACME Örnöga"/points
- Datatype: A single-precision 32-bit IEEE 754 floating point number.
- A generic indicator component that can be specialized for any
Archetype
. - Component: Half-sizes (extents) of a 2D box along its local axis, starting at its local origin/center.
- Component: Half-sizes (extents) of a 3D box along its local axis, starting at its local origin/center.
- Archetype: A monochrome or color image.
- Component: A unique numeric identifier for each individual instance within a batch.
- Datatype: A connection between two
Keypoints
. - Archetype: 2D line strips with positions and optional colors, radii, labels, etc.
- Archetype: 3D line strips with positions and optional colors, radii, labels, etc.
- Implements a
log::Log
that forwards all events to the Rerun SDK. - Datatype: A 3x3 Matrix.
- Component: Material properties of a mesh.
- Component: A standardized media type (RFC2046, formerly known as MIME types), encoded as a utf8 string.
- Archetype: A 3D triangle mesh as specified by its per-mesh and per-vertex properties.
- Component: Optional triangle indices for a mesh.
- An arbitrary named indicator component.
- Component: An out-of-tree affine transform between two 3D spaces, represented in a given direction.
- Archetype: Camera perspective projection (a.k.a. intrinsics).
- Archetype: A 2D point cloud with positions and optional colors, radii, labels, etc.
- Archetype: A 3D point cloud with positions and optional colors, radii, labels, etc.
- Component: A position in 3D space.
- Datatype: A Quaternion represented by 4 real numbers.
- Component: A Radius component.
- A
RecordingStream
handles everything related to logging data into Rerun. - Construct a
RecordingStream
. - Datatype: An RGBA color with unmultiplied/separate alpha, in sRGB gamma space with linear alpha.
- Datatype: 3D rotation represented by a rotation around a given axis.
- Archetype: An image made up of integer class-ids
- A unique id per store.
- Archetype: A generic n-dimensional Tensor.
- Archetype: A text element intended to be displayed in its own text-box.
- Archetype: A log entry in a text log, comprised of a text body and its log level.
- Component: The severity level of a text log message.
- A date-time represented as nanoseconds since unix epoch
- A point in time on any number of
Timeline
s. - Archetype: Log a double-precision scalar that will be visualized as a time-series plot.
- A time frame/space, e.g.
log_time
orframe_nr
, coupled with the type of time it keeps. - Archetype: A 3D transform.
- Datatype: Representation of an affine transform via a 3x3 affine matrix paired with a translation.
- Datatype: Representation of an affine transform via separate translation, rotation & scale.
- Component: A vector in 3D space.
- Archetype: How we interpret the coordinate system of an entity/space.
Enums
- Datatype: Angle in either radians or degrees.
- Where are we calling
run
from? - Holds either an owned
ComponentBatch
that lives on heap, or a reference to one. - Errors that can occur when creating/manipulating a
RecordingStream
. - Datatype: A 3D rotation.
- Datatype: 3D scaling factor, part of a transform representation.
- What kind of Store this is.
Traits
- An archetype is a high-level construct that represents a set of
Component
s that usually play well with each other (i.e. they compose nicely). - Describes the interface for interpreting an object as a bundle of
Component
s. - A
ComponentBatch
represents an array’s worth ofComponent
instances. - A
DatatypeBatch
represents an array’s worth ofDatatype
instances. - A
Loggable
represents a single instance in an array of loggable data. - A
LoggableBatch
represents an array’s worth ofLoggable
instances, ready to be serialized.
Functions
- The version of the Rerun SDK.
- Check whether we are the child of a fork.
- Checks the
RERUN
environment variable. If not found, returns the argument. - The default amount of time to wait for the TCP connection to resume during a flush
- Get
RUST_LOG
environment variable orinfo
, if not set. - The default address of a Rerun TCP server which an SDK connects to.
- Creates a new
re_log_types::StoreInfo
which can be used withRecordingStream::new
. - Run the Rerun application and return an exit code.
Type Aliases
- Results that can occur when creating/manipulating a
RecordingStream
.