MedusAI
Repositories
4
 Projects
1
 Packages
4

cvbridge-python (0.0.2)

Published 2025-12-04 19:36:51 +01:00 by MedusTechnical in MedusAI/cvbridge_python

Installation

pip install --index-url  cvbridge-python

About this package

Minimal Python-only replacement for cv_bridge. Converts between ROS Image/CompressedImage messages and NumPy arrays.

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

Requirements

Requires Python: >=3.11,<3.15
Details
PyPI
MedusAI/cvbridge_python
2025-12-04 19:36:51 +01:00
71
medusai
Project website
MIT
19 KiB
Assets (2)
cvbridge_python-0.0.2-py3-none-any.whl 9.5 KiB
cvbridge_python-0.0.2.tar.gz 10 KiB
Versions (3) View all
0.0.3 2026-04-01
0.0.2 2025-12-04
0.0.1 2025-10-08
Issues