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 & built-in types and re-export all of their 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()?;
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
.
Re-exports
pub use log_integration::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.
- Integrates the Rerun SDK with the
log
crate. - 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.
Macros
- Build an
EntityPath
from parts that are not escaped:
Structs
- Archetype: The
AnnotationContext
provides additional information on how to display entities. - Datatype: Annotation info annotating a class id or key-point id.
- The user-chosen name of the application doing the logging.
- The fully-qualified name of an
Archetype
, e.g.rerun.archetypes.Points3D
. - Archetype: 2D arrows with optional colors, radii, labels, etc.
- 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
. - Everything needed to build custom
StoreSubscriber
s. A complete data store: covers all timelines, all entities, everything. - 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/3/points
- The different parts that make up an
EntityPath
. - 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
. - Component: A line strip in 2D space.
- Component: A line strip in 3D space.
- Archetype: 2D line strips with positions and optional colors, radii, labels, etc.
- Archetype: 3D line strips with positions and optional colors, radii, labels, etc.
- 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.
- Represents a limit in how much RAM to use for the entire process.
- 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 2D space.
- 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.
- Options to control the behavior of
spawn
. - Everything needed to build custom
StoreSubscriber
s. Describes an atomic change in the RerunDataStore
: a row has been added or deleted. - Everything needed to build custom
StoreSubscriber
s. The atomic unit of change in the RerunDataStore
. - Everything needed to build custom
StoreSubscriber
s. Incremented on each edit. - A unique id per store.
- Archetype: A generic n-dimensional Tensor.
- Datatype: A multi-dimensional
Tensor
of data. - Datatype: A single dimension within a multi-dimensional tensor.
- Component: A string of text, e.g. for labels and text documents.
- 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.
- Datatype: A vector in 2D space.
- Datatype: A vector in 3D space.
- Datatype: A vector in 4D space.
- Component: A vector in 2D space.
- 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.
- Errors that can occur when
spawn
ing a Rerun Viewer. - Everything needed to build custom
StoreSubscriber
s. Is it an addition or a deletion? - What kind of Store this is.
- Datatype: The underlying storage for a
Tensor
.
Constants
- When an external
crate::DataLoader
is asked to load some data that it doesn’t know how to load, it should exit with this exit code. - To register a new external data loader, simply add an executable in your $PATH whose name starts with this prefix.
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. - Everything needed to build custom
StoreSubscriber
s. AStoreSubscriber
subscribes to atomic changes from allDataStore
s throughStoreEvent
s.
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.
- Spawns a new Rerun Viewer process ready to listen for TCP connections.
Type Aliases
- Results that can occur when creating/manipulating a
RecordingStream
.