cvbridge_python

cvbridge_python is a minimal Python-only replacement for cv_bridge. It converts between ROS Image/CompressedImage messages and NumPy arrays, supporting encoding conversion and image compression.

This library provides a lightweight alternative to the standard cv_bridge package, eliminating ROS dependencies while maintaining compatibility with ROS message formats.

Features

• ROS Message Conversion: Convert between ROS Image messages and NumPy arrays
• Compressed Image Support: Handle JPEG, PNG, and TIFF compressed images
• Encoding Conversion: Automatic conversion between various image encodings (RGB ↔ BGR, mono ↔ color, 8 ↔ 16-bit)
• Minimal Dependencies: Only requires NumPy and OpenCV
• Type-Safe: Fully typed for robust development
• Well-Documented: Comprehensive docstrings and examples
• Easy to Use: Simple, intuitive API similar to cv_bridge

Supported Encodings

• Monochrome: mono8, mono16
• Color: rgb8, bgr8, rgba8, bgra8
• Float: 32FC1, 32FC3, 64FC1

Supported Compression Formats

• JPEG: Lossy compression with configurable quality
• PNG: Lossless compression
• TIFF: Lossless compression

Installation

Prerequisites

• Python: Version 3.9 or higher.
• pip or Poetry: For dependency management and installation.

Install via pip

To install cvbridge_python from PyPI:

pip install cvbridge_python

Install via Poetry

If you prefer Poetry for dependency management:

poetry add cvbridge_python

Verify Installation

Confirm the package is installed correctly:

python -c "import cvbridge_python; print(cvbridge_python.__version__)"

This should output the installed version (e.g., 0.0.1).

Quick Start

Here's a basic example of using cvbridge_python to convert between ROS messages and NumPy arrays:

from cvbridge_python import RosImageBridge

# Initialize the bridge
bridge = RosImageBridge()

# Convert ROS Image to NumPy
img_np = bridge.imgmsg_to_cv2(ros_msg, desired_encoding='rgb8')

# Convert NumPy to ROS Image
ros_msg_out = bridge.cv2_to_imgmsg(img_np)

# Convert CompressedImage to NumPy
img_np = bridge.compressed_imgmsg_to_cv2(comp_msg, desired_encoding='bgr8')

# Convert NumPy to CompressedImage
comp_msg_out = bridge.cv2_to_compressed_imgmsg(img_np, format='jpeg')

Examples

Basic Image Conversion

from cvbridge_python import RosImageBridge
import numpy as np

bridge = RosImageBridge()

# Convert ROS Image to NumPy (keeping original encoding)
img_array = bridge.imgmsg_to_cv2(image_msg)

# Convert with encoding conversion
rgb_array = bridge.imgmsg_to_cv2(image_msg, desired_encoding='rgb8')

# Convert NumPy back to ROS Image
new_msg = bridge.cv2_to_imgmsg(img_array, encoding='bgr8')

# Use passthrough encoding (auto-inferred)
auto_msg = bridge.cv2_to_imgmsg(img_array)

Compressed Images

# Decompress a JPEG CompressedImage
img_array = bridge.compressed_imgmsg_to_cv2(compressed_msg)

# Compress to JPEG with quality setting
jpeg_msg = bridge.cv2_to_compressed_imgmsg(
    img_array, 
    format='jpeg', 
    quality=90
)

# Compress to PNG (lossless)
png_msg = bridge.cv2_to_compressed_imgmsg(
    img_array,
    format='png'
)

Encoding Conversion

# RGB ↔ BGR conversion
bgr_img = bridge.convert_encoding(rgb_img, 'rgb8', 'bgr8')

# Mono to color
rgb_img = bridge.convert_encoding(mono_img, 'mono8', 'rgb8')

# Color to mono (averaging)
mono_img = bridge.convert_encoding(rgb_img, 'rgb8', 'mono8')

# 8-bit to 16-bit
mono16 = bridge.convert_encoding(mono8, 'mono8', 'mono16')

Using the Example Script

The package includes a comprehensive example script (examples/example.py):

# Run the example
python examples/example.py

For more detailed examples, see the documentation.

API Reference

RosImageBridge

Main class for converting between ROS messages and NumPy arrays.

Methods

• imgmsg_to_cv2(msg, desired_encoding=None): Convert ROS Image message to NumPy array
• cv2_to_imgmsg(arr, encoding='passthrough'): Convert NumPy array to ROS Image message
• compressed_imgmsg_to_cv2(msg, desired_encoding=None): Convert ROS CompressedImage to NumPy array
• cv2_to_compressed_imgmsg(arr, format='jpeg', quality=90): Convert NumPy array to ROS CompressedImage
• convert_encoding(arr, src, dst): Convert array between different encodings
• infer_encoding(arr): Infer ROS encoding from NumPy array

Development

Setting Up the Development Environment

1. Clone the repository:

   git clone https://gitea.moyskleytech.com/MedusAI/cvbridge_python.git
   cd cvbridge_python
   

2. Install dependencies with Poetry:

   poetry install --with dev,test,docs
   

3. Activate the virtual environment:

   poetry shell
   

Running Tests

Run the test suite:

poetry run pytest

Run with coverage:

poetry run pytest --cov=cvbridge_python --cov-report=html

Building Documentation

Build the documentation locally:

poetry run sphinx-build docs docs/_build