grepros

grep for ROS bag files and live topics

Index
Installation
Using the program
Example usage
Inputs
bag
live
Matching and filtering
Outputs
Command-line options
Plugins
Changelog

API documentation
View the Project on GitHub suurjaak/grepros

Using the program

Example usage

Search for "my text" in all bags under current directory and subdirectories:

grepros -r "my text"

Print 30 lines of the first message from each live ROS topic:

grepros --max-per-topic 1 --lines-per-message 30 --live

Find first message containing "future" (case-sensitive) in my.bag:

grepros future -I --max-count 1 --name my.bag

Find 10 messages, from geometry_msgs package, in "map" frame, from bags in current directory, reindexing any unindexed bags:

grepros frame_id=map --type geometry_msgs/* --max-count 10 --reindex-if-unindexed

Pipe all diagnostics messages with "CPU usage" from live ROS topics to my.bag:

grepros "CPU usage" --type *DiagnosticArray --no-console-output --write my.bag

Find messages with field "key" containing "0xA002", in topics ending with "diagnostics", in bags under "/tmp":

grepros key=0xA002 --topic *diagnostics --path /tmp

Find diagnostics_msgs messages in bags in current directory, containing "navigation" in fields "name" or "message", print only header stamp and values:

grepros --type diagnostic_msgs/* --select-field name message \
        --emit-field header.stamp status.values -- navigation

Print first message from each lidar topic on ROS1 host 1.2.3.4, without highlight:

ROS_MASTER_URI=http://1.2.3.4::11311 \
grepros --live --topic *lidar* --max-per-topic 1 --no-highlight

Export all bag messages to SQLite and Postgres, print only export progress:

grepros -n my.bag --write my.bag.sqlite --no-console-output --no-verbose --progress

grepros -n my.bag --write postgresql://user@host/dbname \
        --no-console-output --no-verbose --progress

Patterns use Python regular expression syntax, message matches if all match. * wildcards use simple globbing as zero or more characters, target matches if any value matches.

More on matching and filtering.

Note that some expressions may need to be quoted to avoid shell auto-unescaping or auto-expanding them, e.g. linear.x=2.?5 should be given as "linear.x=2\.?5".

Care must also be taken with unquoted wildcards, as they will auto-expanded by shell if they happen to match paths on disk.

Inputs

Input is either from one or more ROS bag files (default), or from live ROS topics.

bag

Read messages from ROS bag files, by default all in current directory.

For reading bags in MCAP format, see the MCAP plugin.

Recurse into subdirectories when looking for bagfiles:

-r
--recursive

Read specific filenames (supports * wildcards):

--n        /tmp/*.bag
--filename my.bag 2021-11-*.bag

Scan specific paths instead of current directory (supports * wildcards):

-p     /home/bags/2021-11-*
--path my/dir

Reindex unindexed ROS1 bags before processing
(note: creates backup copies of files, into same directory as file):

--reindex-if-unindexed
--reindex-if-unindexed --progress

Decompress archived ROS bags before processing (.zst .zstd extensions, requires zstandard Python package)
(note: unpacks archived file to disk, into same directory as file):

--decompress
--decompress --progress

Order bag messages first by topic or type, and only then by time:

--order-bag-by topic
--order-bag-by type

live

--live

Read messages from live ROS topics instead of bagfiles.

Requires ROS_MASTER_URI and ROS_ROOT to be set in environment if ROS1.

Set custom queue size for subscribing (default 10):

--queue-size-in 100

Use ROS time instead of system time for incoming message timestamps:

--ros-time-in