Crate rerun

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 --locked.

§Feature flags

analytics (enabled by default) — Enable telemetry using our analytics SDK.
clap — Integration with clap.
data_loaders (enabled by default) — Support for using Rerun’s data-loaders directly from the SDK.

See our log_file example and https://www.rerun.io/docs/reference/data-loaders/overview for more information.
demo (enabled by default) — Demo helpers for examples.
dataframe (enabled by default) — Access to Rerun’s dataframe API and related types.
glam (enabled by default) — Add support for some math operations using glam. Only relevant if feature sdk is enabled.
mint — Add support for math type conversions using mint. Only relevant if feature sdk is enabled.
image (enabled by default) — Integration with the image crate, plus JPEG support.
ecolor — Integration with the ecolor crate.
log (enabled by default) — Integration with the log crate.
nasm — Enable faster native video decoding with assembly. You need to install nasm to compile with this feature.
native_viewer — Support spawning a native viewer. This adds a lot of extra dependencies, so only enable this feature if you need it!
map_view (enabled by default) — Support the map view. This adds a lot of extra dependencies.
run — Add support for the run() function, which acts like a main-function for a CLI, acting the same as the rerun binary.
server (enabled by default) — Support for running a gRPC 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.

§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 --locked.

Running just rerun will start the viewer, waiting for the logging library to connect using RecordingStreamBuilder::connect_grpc (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_grpc()?;

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::from_color_model_and_tensor(rerun::ColorModel::RGB, 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(main_thread_token, storage.take());

cargo install rerun --locked
rerun --help

§Forwarding text log events to Rerun

See Logger.

Re-exports§

pub use log_integration::Logger;

Modules§

archetypes: Archetype are the high-level things you can log, like Image, Points3D, etc.
clap: Integration with integration with the clap command line argument parser.
components: Components are the basic building blocks of archetypes.
coordinates: Coordinate system helpers, for use with components::ViewCoordinates.
dataframe: All the types required by the dataframe API.
datatypes: The low-level datatypes that components are built from.
demo_util: This module contains utilities to support Rerun examples.
external: Re-exports of other crates.
grpc_server: Method for spawning a gRPC server and streaming the SDK log stream to it.
log: Things directly related to logging.
log_integration: Integrates the Rerun SDK with the log crate.
native_viewer: Methods for spawning the native viewer and streaming the SDK log stream to it.
sink: Different destinations for log messages.
time: Time-related types.
transform: Transform helpers, for use with archetypes::Transform3D.
web_viewer: Methods for spawning the web viewer and streaming the SDK log stream to it.

Macros§

entity_path: Build an EntityPath from parts that are not escaped:

Structs§

AlbedoFactor: Component: A color multiplier, usually applied to a whole entity, e.g. a mesh.
Angle: Datatype: Angle in radians.
AnnotationContext: Archetype: The annotation context provides additional information on how to display entities.
AnnotationInfo: Datatype: Annotation info annotating a class id or key-point id.
ApplicationId: The user-chosen name of the application doing the logging.
ArchetypeName: The fully-qualified name of an Archetype, e.g. rerun.archetypes.Points3D.
Arrows2D: Archetype: 2D arrows with optional colors, radii, labels, etc.
Arrows3D: Archetype: 3D arrows with optional colors, radii, labels, etc.
Asset3D: Archetype: A prepacked 3D asset (.gltf, .glb, .obj, .stl, etc.).
AssetVideo: Archetype: A video binary.
BarChart: Archetype: A bar chart.
Boxes2D: Archetype: 2D boxes with half-extents and optional center, colors etc.
Boxes3D: Archetype: 3D boxes with half-extents and optional center, rotations, colors etc.
Capsules3D: Archetype: 3D capsules; cylinders with hemispherical caps.
ChunkStore: Everything needed to build custom ChunkStoreSubscribers. A complete chunk store: covers all timelines, all entities, everything.
ChunkStoreConfig: Everything needed to build custom ChunkStoreSubscribers.
ChunkStoreDiff: Everything needed to build custom ChunkStoreSubscribers. Describes an atomic change in the Rerun ChunkStore: a chunk has been added or deleted.
ChunkStoreEvent: Everything needed to build custom ChunkStoreSubscribers. The atomic unit of change in the Rerun ChunkStore.
ChunkStoreGeneration: Everything needed to build custom ChunkStoreSubscribers. Incremented on each edit.
ChunkStoreHandle: Everything needed to build custom ChunkStoreSubscribers. A ref-counted, inner-mutable handle to a ChunkStore.
ClassDescription: Datatype: The description of a semantic Class.
Clear: Archetype: Empties all the components of an entity.
Color: Component: An RGBA color with unmultiplied/separate alpha, in sRGB gamma space with linear alpha.
ComponentDescriptor: A ComponentDescriptor fully describes the semantics of a column of data.
ComponentName: The fully-qualified name of a Component, e.g. rerun.components.Position2D.
DataLoaderSettings: Recommended settings for the DataLoader.
DatatypeName: The fully-qualified name of a [Datatype], e.g. rerun.datatypes.Vec2D.
DepthImage: Archetype: A depth image, i.e. as captured by a depth camera.
Ellipsoids3D: Archetype: 3D ellipsoids or spheres.
EncodedImage: Archetype: An image encoded as e.g. a JPEG or PNG.
EntityPath: The unique identifier of an entity, e.g. camera/3/points
EntityPathPart: The different parts that make up an EntityPath.
Float32: Datatype: A single-precision 32-bit IEEE 754 floating point number.
GenericIndicatorComponent: A generic indicator component that can be specialized for any Archetype.
GeoLineStrings: Archetype: Geospatial line strings with positions expressed in EPSG:4326 altitude and longitude (North/East-positive degrees), and optional colors and radii.
GeoPoints: Archetype: Geospatial points with positions expressed in EPSG:4326 latitude and longitude (North/East-positive degrees), and optional colors and radii.
GraphEdges: Archetype: A list of edges in a graph.
GraphNodes: Archetype: A list of nodes in a graph with optional labels, colors, etc.
HalfSize2D: Component: Half-size (radius) of a 2D box.
HalfSize3D: Component: Half-size (radius) of a 3D box.
Image: Archetype: A monochrome or color image.
ImageFormat: Component: The metadata describing the contents of a components::ImageBuffer.
Instance: A unique numeric index for each individual instance within a batch.
InstancePoses3D: Archetype: One or more transforms between the current entity and its parent. Unlike archetypes::Transform3D, it is not propagated in the transform hierarchy.
KeypointPair: Datatype: A connection between two datatypes::KeypointIds.
LineStrip2D: Component: A line strip in 2D space.
LineStrip3D: Component: A line strip in 3D space.
LineStrips2D: Archetype: 2D line strips with positions and optional colors, radii, labels, etc.
LineStrips3D: Archetype: 3D line strips with positions and optional colors, radii, labels, etc.
MainThreadToken: A token that (almost) proves we are on the main thread.
Mat3x3: Datatype: A 3x3 Matrix.
MediaType: Component: A standardized media type (RFC2046, formerly known as MIME types), encoded as a string.
MemoryLimit: Represents a limit in how much RAM to use for the entire process.
Mesh3D: Archetype: A 3D triangle mesh as specified by its per-mesh and per-vertex properties.
NamedIndicatorComponent: An arbitrary named indicator component.
Pinhole: Archetype: Camera perspective projection (a.k.a. intrinsics).
Points2D: Archetype: A 2D point cloud with positions and optional colors, radii, labels, etc.
Points3D: Archetype: A 3D point cloud with positions and optional colors, radii, labels, etc.
Position2D: Component: A position in 2D space.
Position3D: Component: A position in 3D space.
Quaternion: Datatype: A Quaternion represented by 4 real numbers.
Radius: Component: The radius of something, e.g. a point.
RecordingProperties: Archetype: A list of properties associated with a recording.
RecordingStream: A RecordingStream handles everything related to logging data into Rerun.
RecordingStreamBuilder: Construct a RecordingStream.
Rgba32: Datatype: An RGBA color with unmultiplied/separate alpha, in sRGB gamma space with linear alpha.
RotationAxisAngle: Datatype: 3D rotation represented by a rotation around a given axis.
ScalarDeprecated: Archetype: A double-precision scalar, e.g. for use for time-series plots.
Scalars: Archetype: One or more double-precision scalar values, e.g. for use for time-series plots.
Scale3D: Component: A 3D scale factor.
SegmentationImage: Archetype: An image made up of integer components::ClassIds.
SerializedComponentBatch: The serialized contents of a ComponentBatch with associated ComponentDescriptor.
SerializedComponentColumn: A column’s worth of component data.
SeriesLineDeprecated: Archetype: Define the style properties for a line series in a chart.
SeriesLines: Archetype: Define the style properties for one or more line series in a chart.
SeriesPointDeprecated: Archetype: Define the style properties for a point series in a chart.
SeriesPoints: Archetype: Define the style properties for one or more point series (scatter plot) in a chart.
SpawnOptions: Options to control the behavior of spawn.
StoreId: A unique id per store.
Tensor: Archetype: An N-dimensional array of numbers.
TensorData: Datatype: An N-dimensional array of numbers.
Text: Component: A string of text, e.g. for labels and text documents.
TextDocument: Archetype: A text element intended to be displayed in its own text box.
TextLog: Archetype: A log entry in a text log, comprised of a text body and its log level.
TextLogLevel: Component: The severity level of a text log message.
TimeCell: An typed cell of an index, e.g. a point in time on some unknown timeline.
TimeColumn
TimePoint: A point in time on any number of Timelines.
Timeline: A time frame/space, e.g. log_time or frame_nr, coupled with the type of time it keeps.
Transform3D: Archetype: A transform between two 3D spaces, i.e. a pose.
TriangleIndices: Component: The three indices of a triangle in a triangle mesh.
Vec2D: Datatype: A vector in 2D space.
Vec3D: Datatype: A vector in 3D space.
Vec4D: Datatype: A vector in 4D space.
Vector2D: Component: A vector in 2D space.
Vector3D: Component: A vector in 3D space.
VideoFrameReference: Archetype: References a single video frame.
ViewCoordinates: Archetype: How we interpret the coordinate system of an entity/space.

Enums§

CallSource: Where are we calling run from?
ChannelDatatype: Datatype: The innermost datatype of an image.
ChunkStoreDiffKind: Everything needed to build custom ChunkStoreSubscribers. Is it an addition or a deletion?
ColorModel: Datatype: Specified what color components are present in an archetypes::Image.
DataLoaderError: Errors that might happen when loading data through a DataLoader.
DeserializationError
FillMode: Component: How a geometric shape is drawn and colored.
LoadedData: What DataLoaders load.
PixelFormat: Datatype: Specifieds a particular format of an archetypes::Image.
RecordingStreamError: Errors that can occur when creating/manipulating a RecordingStream.
Rotation3D: A 3D rotation.
SerializationError
SpawnError: Errors that can occur when spawning a Rerun Viewer.
StoreKind: What kind of Store this is.
TensorBuffer: Datatype: The underlying storage for archetypes::Tensor.
TransformRelation: Component: Specifies relation a spatial transform describes.

Constants§

DEFAULT_CONNECT_URL: The default URL of a Rerun gRPC /proxy server.
DEFAULT_SERVER_PORT: The default port of a Rerun gRPC /proxy server.
EXTERNAL_DATA_LOADER_INCOMPATIBLE_EXIT_CODE: When an external DataLoader is asked to load some data that it doesn’t know how to load, it should exit with this exit code.
EXTERNAL_DATA_LOADER_PREFIX: To register a new external data loader, simply add an executable in your $PATH whose name starts with this prefix.

Traits§

Archetype: An archetype is a high-level construct that represents a set of Components that usually play well with each other (i.e. they compose nicely).
AsComponents: Describes the interface for interpreting an object as a bundle of Components.
ChunkStoreSubscriber: Everything needed to build custom ChunkStoreSubscribers. A ChunkStoreSubscriber subscribes to atomic changes from all ChunkStores through ChunkStoreEvents.
Component: A Component describes semantic data that can be used by any number of Archetypes.
ComponentBatch: A ComponentBatch represents an array’s worth of Component instances.
DataLoader: A DataLoader loads data from a file path and/or a file’s contents.
Loggable: A Loggable represents a single instance in an array of loggable data.
LoggableBatch: A LoggableBatch represents an array’s worth of Loggable instances, ready to be serialized.
SizeBytes: Approximations of stack and heap size for both internal and external types.

Functions§

build_info: The version of the Rerun SDK.
cleanup_if_forked_child: Check whether we are the child of a fork.
decide_logging_enabled: Checks the RERUN environment variable. If not found, returns the argument.
default_flush_timeout: The default amount of time to wait for the gRPC connection to resume during a flush
default_log_filter: Determines the default log filter.
default_server_addrDeprecated: The default address of a Rerun gRPC server which an SDK connects to.
forced_sink_path: Returns path for force sink if private environment variable _RERUN_TEST_FORCE_SAVE is set
new_store_info: Creates a new re_log_types::StoreInfo which can be used with RecordingStream::new.
run: Run the Rerun application and return an exit code.
serve_web_viewer: Serves the Rerun Web Viewer (HTML+JS+Wasm) over http.
spawn: Spawns a new Rerun Viewer process ready to listen for connections.

Type Aliases§

DeserializationResult
RecordingStreamResult: Results that can occur when creating/manipulating a RecordingStream.
SerializationResult

Crate rerunCopy item path