A terminal-based, real-time plotting tool for ROS2 topics. Ros2Plot automatically introspects ROS2 message types to extract numeric fields (int, float, bool) and plots them as time series. It uses asciimatics for the UI and braille characters for high-definition plots, supporting custom x-axes and interactive controls.

Ros2Plot is highly optimized internally, and designed to deal with large data sizes. When new data is appended, Plots only process the new entries, re-using internal buffers for rendering. Buffers are only refreshed when axes are resized beyond thresholds to preserve visual accuracy.

It also provides some baseline memory guarantees (if you leave it running in a terminal forever...) by pruning FIFO the stored topic data to cap total memory usage at 2% of free memory.

By default, all fields will be plotted against a default X-axis key. For topic data, it will use the timestamp at which the callback triggered. For csv data, it will attempt to look for a 'timestamp' label in the CSV. Custom x-axis fields can be selected either via the Selector UI or by specifying a field via the manual input. If the selected X-field is incompatible wth any existing Plot (y and x data size mismatches) then the Plot will automatically be marked invisible.

Here's a quick demo showcasing key features of runtime subscription, Plot value inspection & Plot Display region resizing.

• Features
• Installation
• Usage
• Hotkeys
• Command-Line Arguments

• Real-Time Plotting: Subscribe to ROS2 topics and plot numeric fields dynamically.
• High-Definition Display: Uses braille characters for 2x4 pixel resolution.
• Interactive UI: Pause, zoom, inspect, and select plots with hotkeys.
• Customizable Axes: Choose any stored field for the x-axis.

• ROS2 (e.g., Jazzy or later) installed and sourced.
• Python 3.8+ with pip.
• For colcon compilation, ensure environment has:
  • setuptools
  • colcon-common-extensions

• asciimatics
• numpy
• attrs
• pyyaml
• psutil

Install via pip or ROS2 package.

For standalone use:

cd ros2graph  # Or your project root
python3 -m venv venv
source venv/bin/activate  
pip install -r requirements.txt
pip install .
source /opt/ros/<distro>/setup.bash  # Replace <distro> with your ROS2 version
ros2plot

If necessary, source your python venv before proceeding.
PSA: If using a python venv, it must be outside your workspace folder.

For integration with ROS2 workspaces:

cd <your_ws>
pip install -r src/ros2plot/requirements.txt
colcon build --symlink-install --packages-select ros2plot
source install/setup.bash
ros2 run ros2plot ros2plot
# If import issues: python3 -m ros2plot.main

Run ros2plot after installation. The app starts with a blank screen; use hotkeys to subscribe and plot.

If using ROS2 installation, append the following for the subsequent examples:

ros2 run ros2plot

Example: Plot all data from a topic.

ros2plot /robot/pose

Example: Visualize coordinate data from a topic by plotting Y against X.

ros2plot /robot/pose geometry_msgs/PoseStamped --fields pose/position/y --x-field pose/position/y

Example: Plot all data inside a csv

ros2plot --csv filename.csv

Example: Plot specific fields in a csv against another as the X-Axis

ros2plot --csv filename.csv --fields field_1 field_2 --x-field field_x

Example: Same as above, but additionally all CSVs will use field_x as the default X axis for future loading

ros2plot --csv filename.csv --fields field_1 field_2 --csv-default-x-key field_x

Control the UI with these keys.

Select fields for plotting or x-axis.

Controls two points (green when selected).

Select fields for plotting or x-axis.

Define initial subscriptions via CLI or in-app input.

Usage: ros2plot <topic> [type] [--fields <fields>] [--x-field <field>]