LIBRARY.md

Using as API

grepros can also be used as a Python library for reading, matching and writing ROS messages, with functionality for converting and exporting messages in various formats.

Full API documentation available at https://suurjaak.github.io/grepros.

Convenience entrypoint functions

import grepros
grepros.init()

# Print first message from each bag under path:
for topic, msg, stamp, *_ in grepros.grep(path="my/path", max_count=1):
    print(topic, stamp, msg)

# Write one message from each live topic to an HTML file:
with grepros.source(live=True, max_per_topic=1) as source, \
     grepros.sink("my.html") as sink:
    for topic, msg, stamp in source: sink.emit(topic, msg, stamp)

Working with bags

import grepros
grepros.init()

# Read and write bags:
with grepros.Bag("my.bag") as inbag, grepros.Bag("my.mcap", mode="w") as outbag:
    for topic, msg, stamp in inbag:
        outbag.write(topic, msg, stamp)  # Convert ROS1 bag to MCAP

# Find messages in bag:
bag  = grepros.Bag("my.bag")
scan = grepros.Scanner(topic="/diagnostics", pattern="temperature")
for topic, msg, stamp, match in scan.find(bag, highlight=True):
    print("MATCH: ", topic, stamp, match)

# Write live topics to bag, no more than once a minute per topic:
with grepros.Bag("my.bag", "w") as bag:
    for topic, msg, stamp, *_ in grepros.grep(live=True, nth_interval=60):
        bag.write(topic, msg, stamp)

# Find messages +- 2 minutes around first pointcloud message in bag:
with grepros.Bag("my.bag") as bag:
    _, _, stamp, *_ = next(grepros.grep(bag, type="*/pointcloud*"))
    delta = grepros.api.make_duration(secs=120)
    args = dict(start_time=stamp - delta, end_time=stamp + delta)
    for topic, msg, stamp, *_ in grepros.grep(bag, **args):
        print("%s [%s] %s" % (topic, stamp, msg))

# Bag API conveniences:
with grepros.Bag("my.bag") as bag:
    print("Messages in bag: ", len(bag))
    if "/my/topic" in bag:
        print("/my/topic messages in bag: ", len(bag["/my/topic"]))
    for topic in bag.topics:
        print("Topic: ", topic)
        for topic, msg, stamp in bag[topic]:
            print(msg)

Sources and sinks

import grepros
grepros.init()

# Write all bags in directory to Postgres database:
with grepros.PostgresSink("username=postgres dbname=postgres") as sink:
    for data in grepros.BagSource(path="/tmp/bags"):
        sink.emit(*data)

# Grep live topics:
for topic, msg, stamp, match, index in grepros.LiveSource(topic="/diagnostics", pattern="cpu"):
    print("MESSAGE #%s MATCH: " % index, match)

# Subscribe to live topics and write to bag:
with grepros.LiveSource(topic="/rosout") as source, \
     grepros.Bag("my.bag", "w") as bag:
    for topic, msg, stamp, *_ in grepros.Scanner(pattern="error").find(source)
        bag.write(topic, msg, stamp)

# Write all pointclouds from bags in directory to SQLite database:
with grepros.BagSource(path="/tmp/bags") as source, \
     grepros.SqliteSink("my.sqlite") as sink:
    total = grepros.Scanner(type="*/pointcloud*").work(source, sink)
    print("Messages written: %s" % total)

Output sink write_options arguments can be given with underscores instead of dashes, e.g. "rollover_size" instead of "rollover-size".

Main classes

Source classes:

• grepros.AppSource: produces messages from iterable or pushed data
• grepros.BagSource: produces messages from ROS bagfiles
• grepros.LiveSource: produces messages from live ROS topics

Sink classes:

• grepros.AppSink: provides messages to callback function
• grepros.BagSink: writes messages to bagfile
• grepros.ConsoleSink: prints messages to console
• grepros.CsvSink: writes messages to CSV files, each topic to a separate file
• grepros.HtmlSink: writes messages to an HTML file
• grepros.LiveSink: publishes messages to live ROS topics
• grepros.McapSink: writes messages to an MCAP file
• grepros.MultiSink: combines any number of sinks
• grepros.ParquetSink: writes messages to Apache Parquet files
• grepros.PostgresSink: writes messages to a Postgres database
• grepros.SqliteSink: writes messages to an SQLite database
• grepros.SqlSink: writes an SQL schema file for message type tables and topic views

grepros.Bag: generic ROS bag interface.
grepros.Scanner: ROS message grepper.

Format-specific bag classes:

• grepros.ros1.Bag: ROS1 bag reader and writer in .bag format
• grepros.ros2.Bag: ROS2 bag reader and writer in .db3 SQLite format
• grepros.plugins.embag.EmbagReader: ROS1 bag reader using the embag library
• grepros.plugins.mcap.McapBag: ROS1/ROS2 bag reader and writer in MCAP format