Command-line utility for converting images to ROS2 bag files
Quickstart
·
Report Bug
·
Request Feature
Table of Contents
With the use of the rosbag2_py library, you will need to have a ROS2 distribution installed on your system. Additionally, img2bag requires an installation of Python 3.8+ and pip, along with the following ROS2 packages:
ros-${ROS_DISTRO}-ros2bag ros-${ROS_DISTRO}-rosbag2-storage-mcap
To install img2bag using pip:
- locate and download the latest
.whlfile from the GitHub releases - run:
python3 -m pip install img2bag-<version>-py3-none-any.whl
- or without downloading:
python3 -m pip install https://github.com/bplus-group/img2bag/releases/download/<version>/img2bag-<version>-py3-none-any.whl
Note
Replace <version> with the latest version number from the GitHub releases
From source:
python3 -m pip install git+https://github.com/bplus-group/img2bag
basic example
img2bag --directories=[./images] --topics=[/image] --output mybag
Note
Images within the directories are sorted using natural order respecting the file paths with OS-Generated names.
e.g.:
img2bag --directories=[./images] --topics=[/image] --recursive-dirs --output mybag
./images/1.png
./images/2.png
./images/3.png
./images/subfolder/subfolder_2/001.png
./images/subfolder/subfolder_2/2.png
./images/subfolder/subfolder_2/03.png
./images/subfolder/subfolder_3/1.png
./images/subfolder/subfolder_3/image2.png
./images/subfolder/subfolder_3/image 3.png
./images/subfolder/subfolder (4)/1738915422.288516.png
./images/subfolder/subfolder (4)/1738915434.2312446.png
./images/subfolder/subfolder (4)/1738915444.8668082.png
Working on topic '/image' ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:17
Saved ROS bag file to '/mybag'.
advanced example
- process images from multiple directories
- upscale/downscale images to a width of 1280 pixels while maintaining aspect ratio
- publish images at a rate of 5 Hz
- save the bag file in SQLite3 format
img2bag --directories=[./images_1,./images_2] \ --topics=[/sensor/camera_1/image,/sensor/camera_2/image] \ --image-size=1280 \ --rate=5 \ --format SQLITE3 \ --output mybag
[INFO] [1738647810.973381809] [rosbag2_storage]: Opened database '/mybag/mybag_0.db3' for READ_WRITE.
Working on topic '/sensor/camera_1/image' ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:09
Working on topic '/sensor/camera_2/image' ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:10
Saved ROS bag file to '/mybag'.
Instead of specifying parameters in the command line, you can define them in a configuration file for easier reuse and better readability.
To create a template configuration file, run:
img2bag --print_config > config.yamlExample configuration file (config.yaml):
verbose: false # Enable verbose output (optional) directories: null # List of image directories (required) topics: null # List of ROS topics to publish images under (required) camera_info_topic: camera_info # Topic for camera info messages (optional) image_size: null # Resize images (e.g., 1280 or 1920x1080, optional) timestamp: 1738648875 # Timestamp for images [Unix epoch time] (optional) rate: 1.0 # Image publishing rate [Hz] (optional) recursive_dirs: false # Recursively search directories for images (optional) output: null # output bag file name (required) format: MCAP # Storage format [SQLITE3, MCAP] (optional)
Once configured, run the following command to generate a bag file using the settings from config.yaml:
img2bag --config config.yaml
You can override specific parameters from the configuration file by passing them as command-line arguments.
For example, to change the image size and output filename while keeping other settings from config.yaml:
config.yaml:
directories: - ./images_1 - ./images_2 topics: - /sensor/camera_1/image - /sensor/camera_2/image format: MCAP
img2bag --config config.yaml --image-size=1920x1080 --output mybag
For more advanced options while converting:
-h, --help Show this help message and exit.
--version Print version and exit.
--verbose Enable verbose output. (default: False)
--config CONFIG Path to a configuration file in JSON or YAML format. This file can contain predefined arguments.
--print_config[=flags]
Print the configuration after applying all other arguments and exit. The optional flags
customizes the output and are one or more keywords separated by comma. The supported flags are:
comments, skip_default, skip_null.
--directories DIRECTORIES, --directories+ DIRECTORIES
List of directories containing images to be processed. The number of directories must match the
number of '--topics'. Usage: '--directories=[dir1,dir2]' or '--directories+=dir3' to append
another directory. Images within the directories are sorted using natural order respecting the
file paths with OS-Generated names. Quoting is required when specifying multiple directories
that are separated by commas and spaces. (required, type: List[Path_dr])
--topics TOPICS, --topics+ TOPICS
List of topics to publish images under. Each topic corresponds to a directory specified in '--
directories'. Usage: '--topics=[topic1,topic2]' or '--topics+=topic3' to append another topic.
Quoting is required when specifying multiple topics that are separated by commas and spaces.
(required, type: List[str])
-c CAMERA_INFO_TOPIC, --camera-info-topic CAMERA_INFO_TOPIC
Name of the camera info topic to include in the bag file. (type: CameraInfoTopicType, default:
camera_info)
-s IMAGE_SIZE, --image-size IMAGE_SIZE
Specify image size. Use "WIDTH" to maintain aspect ratio, or "WIDTHxHEIGHT" | "WIDTH,HEIGHT" to
specify dimensions. Both WIDTH and HEIGHT must be positive integers greater than zero. (type:
ImageSizeType, default: null)
-ts TIMESTAMP, --timestamp TIMESTAMP
Starting timestamp (Unix epoch time in seconds) for the bag file. Defaults to the current system
time. (type: PositiveInt, default: 1739166685)
-r RATE, --rate RATE Playback rate of the image topics in frames per second (Hz). (type: PositiveFloat, default: 1.0)
-rd, --recursive-dirs
Recursively search directories for images. (default: False)
-o OUTPUT, --output OUTPUT
Path to save the output bag file. (required, type: Path_fc)
-f {SQLITE3,MCAP}, --format {SQLITE3,MCAP}
Storage format for the output bag file. (type: StorageID, default: MCAP)
If you have a suggestion that would improve this, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/NewFeature) - Commit your Changes (
git commit -m 'Add some NewFeature') - Push to the Branch (
git push origin feature/NewFeature) - Open a Pull Request
All code, unless otherwise noted, is licensed under the MIT License. See LICENSE for more information.