Experimental

`rerun.experimental`

Experimental features for Rerun.

These features are not yet stable and may change in future releases without going through the normal deprecation cycle.

`class Chunk`

A single chunk of data from a recording.

`entity_path: str` `property`

The entity path this chunk belongs to.

`id: str` `property`

The unique ID of this chunk.

`is_empty: bool` `property`

Whether the chunk has zero rows.

`is_static: bool` `property`

Whether the chunk contains only static data (no timelines).

`num_columns: int` `property`

The number of columns in this chunk.

`num_rows: int` `property`

The number of rows in this chunk.

`timeline_names: list[str]` `property`

The names of all timelines in this chunk.

`def apply_lenses(lenses)`

Apply one or more lenses to this chunk, returning transformed chunks.

Each lens matches by input component. Columns not consumed by any matching lens are forwarded unchanged as a separate chunk. A single lens with multiple LensOutput groups may produce multiple output chunks (e.g., with different target entities).

If no lens matches the chunk (including when an empty list of lenses is passed), the original chunk is returned unchanged.

PARAMETER	DESCRIPTION
`lenses`	Zero or more `Lens` objects to apply. TYPE: `Sequence[Lens] \| Lens`

RETURNS	DESCRIPTION
A list of [`Chunk`][rerun.experimental.Chunk] objects. Contains the original chunk if no
`lens matched, or one or more transformed chunks (optionally`
`preceded by a chunk with the untouched forwarded columns)`
`otherwise.`

RAISES	DESCRIPTION
`ValueError`	If a lens produces a partial result (e.g., a selector fails to evaluate on the input data, or a lens produces no output columns).

`def apply_selector(source, selector)`

Apply a selector to a single component, returning a new chunk with the component transformed.

All other columns (timelines, other components) are preserved unchanged. The source component's existing descriptor is preserved.

PARAMETER	DESCRIPTION
`source`	A `ComponentDescriptor` or component identifier string for the input column to transform. TYPE: `ComponentDescriptor \| str`
`selector`	A `Selector` or selector query string to apply to the component. TYPE: `Selector \| str`

RETURNS	DESCRIPTION
A new [`Chunk`][rerun.experimental.Chunk] with the component transformed.

RAISES	DESCRIPTION
`ValueError`	If the source component is not found in the chunk or the selector fails to evaluate.

`def format(*, width=240, redact=False)`

Format this chunk as a human-readable table string.

PARAMETER	DESCRIPTION
`width`	Fixed width for the table. Default: 240. TYPE: `int` DEFAULT: `240`
`redact`	If True, redact non-deterministic values (RowIds, ChunkIds, etc.) for stable snapshot testing. Default: False. TYPE: `bool` DEFAULT: `False`

`def from_columns(entity_path, indexes, columns)` `classmethod`

Create a Chunk from columns, mirroring the rerun.send_columns API.

A fresh chunk ID and sequential row IDs are auto-generated.

PARAMETER	DESCRIPTION
`entity_path`	The entity path for this chunk (e.g., "/camera/image"). TYPE: `str`
`indexes`	The time columns for this chunk. Each `TimeColumnLike` provides a timeline name and a PyArrow array of timestamps. You typically use `TimeColumn` here. Pass an empty iterable for static data. TYPE: `Iterable[TimeColumnLike]`
`columns`	The component columns for this chunk. Each `ComponentColumn` provides a component descriptor and a PyArrow array of component data. TYPE: `Iterable[ComponentColumn]`

RAISES	DESCRIPTION
`ValueError`	If timeline and component column lengths don't match.

Example

chunk = Chunk.from_columns(
    "/robots/arm",
    indexes=[rr.TimeColumn("frame", sequence=[0, 1, 2])],
    columns=rr.Points3D.columns(positions=[[1, 2, 3], [4, 5, 6], [7, 8, 9]]),
)

`def from_record_batch(record_batch)` `classmethod`

Create a Chunk from a PyArrow RecordBatch with Rerun schema metadata.

The RecordBatch must have Rerun metadata in its schema, as produced by to_record_batch. This enables round-tripping through PyArrow transforms. The original chunk ID and row IDs are preserved.

PARAMETER	DESCRIPTION
`record_batch`	A PyArrow RecordBatch with Rerun schema metadata. TYPE: `RecordBatch`

RAISES	DESCRIPTION
`ValueError`	If the RecordBatch lacks required Rerun schema metadata.

`def to_record_batch()`

Convert this chunk to an Arrow RecordBatch.

`class Lens`

A lens that transforms component data from one form to another.

Lenses extract, transform, and restructure component data. They are applied to chunks whose entity path matches the content filter and that contain the specified input component.

Example usage::

lens = Lens(
    "example:Instruction:text",
    LensOutput()
    .to_component("rerun.components.TextDocument:text", Selector(".")),
)

To write to explicit target entities::

lens = Lens(
    "Imu:accel",
    to_entity={
        "/out/x": LensOutput().to_component(desc, ".x"),
        "/out/y": LensOutput().to_component(desc, ".y"),
    },
)

To restrict which entities a lens applies to, use stream.filter(content=...) before .lenses().

`def init(input_component, output=None, *, to_entity=None)`

Create a new lens.

PARAMETER	DESCRIPTION
`input_component`	The component identifier to match in input chunks. TYPE: `str`
`output`	A `LensOutput` for the same entity as the input. At most one is allowed. TYPE: `LensOutput \| None` DEFAULT: `None`
`to_entity`	A dict mapping entity paths to `LensOutput` objects for writing to explicit target entities. TYPE: `Mapping[str, LensOutput] \| None` DEFAULT: `None`

`class LensOutput`

Describes one output group of a lens.

Each input row produces exactly one output row (1:1 mapping). Times are inherited from the input chunk unchanged.

Example usage::

output = (
    LensOutput()
    .to_component("rerun.components.TextDocument:text", Selector("."))
)

`def init()`

Create a new output group.

`def to_component(component, selector)`

Add a component output column.

PARAMETER	DESCRIPTION
`component`	A `ComponentDescriptor` or a component identifier string for the output column (e.g. `"Scalars:scalars"`). Using a full `ComponentDescriptor` preserves archetype and component type metadata in the output. TYPE: `ComponentDescriptor \| str`
`selector`	A `Selector` or selector query string to apply to the input column. TYPE: `Selector \| str`

RETURNS	DESCRIPTION
A new [`LensOutput`][rerun.experimental.LensOutput] with the component added.

`def to_timeline(timeline_name, timeline_type, selector)`

Add a time extraction column.

PARAMETER	DESCRIPTION
`timeline_name`	Name of the timeline to create. TYPE: `str`
`timeline_type`	Type of the timeline: `"sequence"`, `"duration_ns"`, or `"timestamp_ns"`. TYPE: `Literal['sequence', 'duration_ns', 'timestamp_ns']`
`selector`	A `Selector` or selector query string to extract time values (must produce `Int64` arrays). TYPE: `Selector \| str`

RETURNS	DESCRIPTION
A new [`LensOutput`][rerun.experimental.LensOutput] with the time column added.

`class Selector`

A jq-like query selector for Arrow arrays.

Selectors provide a path-based query language (inspired by jq) that operates on Arrow arrays in a columnar fashion.

Syntax overview:

.field — access a named field in a struct
[] — iterate over every element of a list
[N] — index into a list by position
? — error suppression / optional operator
! — assert non-null
| — pipe the output of one expression to another

Example usage::

selector = Selector(".location")
result = selector.execute(my_struct_array)

Selectors can also be piped into Python functions::

selector = Selector(".values").pipe(lambda arr: pa.compute.multiply(arr, 2))
result = selector.execute(my_struct_array)

`def init(query)`

Parse a selector from a query string.

PARAMETER	DESCRIPTION
`query`	The selector query string (e.g. ".field", ".foo \| .bar"). TYPE: `str`

`def execute(source)`

Execute this selector against a pyarrow array.

PARAMETER	DESCRIPTION
`source`	The input Arrow array to query. TYPE: `Array`

RETURNS	DESCRIPTION
`The result array, or None if the selector's error was suppressed.`

`def execute_per_row(source)`

Execute this selector against each row of a pyarrow list array.

The output is guaranteed to have the same number of rows as the input.

PARAMETER	DESCRIPTION
`source`	The input Arrow list array to query. TYPE: `Array`

RETURNS	DESCRIPTION
`The result list array, or None if the selector's error was suppressed.`

`def pipe(func)`

Pipe the output of this selector through a transformation function or another selector.

Returns a new selector; the original is not modified.

PARAMETER	DESCRIPTION
`func`	A callable that accepts a `pyarrow.Array` and returns a `pyarrow.Array` or `None`, or another `Selector` to chain. TYPE: `Callable[[Array], Array \| None] \| Selector`

RETURNS	DESCRIPTION
A new [`Selector`][rerun.experimental.Selector] with the transformation applied.

`class ViewerClient`

A connection to an instance of a Rerun viewer.

Warning

This API is experimental and may change or be removed in future versions.

`def init(addr='127.0.0.1:9876')`

Create a new viewer client connection.

PARAMETER	DESCRIPTION
`addr`	The address of the viewer to connect to, in the format "host:port". Defaults to "127.0.0.1:9876" for a local viewer. TYPE: `str` DEFAULT: `'127.0.0.1:9876'`

`def save_screenshot(file_path, view_id=None)`

Save a screenshot to a file.

Warning

This API is experimental and may change or be removed in future versions.

PARAMETER	DESCRIPTION
`file_path`	The path where the screenshot will be saved. Important This path is relative to the viewer's filesystem, not the client's. If your viewer runs on a different machine, the screenshot will be saved there. TYPE: `str`
`view_id`	Optional view ID to screenshot. If None, screenshots the entire viewer. TYPE: `str \| UUID \| None` DEFAULT: `None`

`def send_table(name, table)`

Send a table to the viewer.

A table is represented as a dataframe defined by an Arrow record batch.

PARAMETER	DESCRIPTION
`name`	The table name. Note The table name serves as an identifier. If you send a table with the same name twice, the second table will replace the first one. TYPE: `str`
`table`	The Arrow RecordBatch containing the table data to send. TYPE: `RecordBatch \| list[RecordBatch] \| DataFrame`

`def send_chunk(chunk, *, recording=None)`

Send a pre-built Chunk to a recording stream.

PARAMETER	DESCRIPTION
`chunk`	The chunk to send. TYPE: `Chunk`
`recording`	Specifies the `rerun.RecordingStream` to use. If left unspecified, defaults to the current active data recording. TYPE: `RecordingStream \| None` DEFAULT: `None`

Experimental

rerun.experimental

class Chunk

entity_path: str property

id: str property

is_empty: bool property

is_static: bool property

num_columns: int property

num_rows: int property

timeline_names: list[str] property

def apply_lenses(lenses)

def apply_selector(source, selector)

def format(*, width=240, redact=False)

def from_columns(entity_path, indexes, columns) classmethod

def from_record_batch(record_batch) classmethod

def to_record_batch()

class Lens

def __init__(input_component, output=None, *, to_entity=None)

class LensOutput

def __init__()

def to_component(component, selector)

def to_timeline(timeline_name, timeline_type, selector)

class Selector

def __init__(query)

def execute(source)

def execute_per_row(source)

def pipe(func)

class ViewerClient

def __init__(addr='127.0.0.1:9876')

def save_screenshot(file_path, view_id=None)

def send_table(name, table)

def send_chunk(chunk, *, recording=None)

`rerun.experimental`

`class Chunk`

`entity_path: str` `property`

`id: str` `property`

`is_empty: bool` `property`

`is_static: bool` `property`

`num_columns: int` `property`

`num_rows: int` `property`

`timeline_names: list[str]` `property`

`def apply_lenses(lenses)`

`def apply_selector(source, selector)`

`def format(*, width=240, redact=False)`

`def from_columns(entity_path, indexes, columns)` `classmethod`

`def from_record_batch(record_batch)` `classmethod`

`def to_record_batch()`

`class Lens`

`def init(input_component, output=None, *, to_entity=None)`

`class LensOutput`

`def init()`

`def to_component(component, selector)`

`def to_timeline(timeline_name, timeline_type, selector)`

`class Selector`

`def init(query)`

`def execute(source)`

`def execute_per_row(source)`

`def pipe(func)`

`class ViewerClient`

`def init(addr='127.0.0.1:9876')`

`def save_screenshot(file_path, view_id=None)`

`def send_table(name, table)`

`def send_chunk(chunk, *, recording=None)`