Metadata-Version: 2.4
Name: cvbridge_python
Version: 0.0.3
Summary: Minimal Python-only replacement for cv_bridge. Converts between ROS Image/CompressedImage messages and NumPy arrays.
License: MIT
License-File: LICENSE
Keywords: ros,cv_bridge,opencv,image-conversion,robotics
Author: medusai
Author-email: courriel@medusai.ca
Requires-Python: >=3.11,<3.15
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: numpy (>=2.4.1)
Requires-Dist: opencv-python (>=4.13.0)
Project-URL: Bug Tracker, https://gitea.moyskleytech.com//MedusAI/cvbridge_python/issues
Project-URL: Documentation, https://cvbridge_python.readthedocs.io
Project-URL: Homepage, https://gitea.moyskleytech.com//MedusAI/cvbridge_python
Project-URL: Repository, https://gitea.moyskleytech.com//MedusAI/cvbridge_python
Description-Content-Type: text/markdown

# 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:

```bash
pip install cvbridge_python
```

### Install via Poetry

If you prefer Poetry for dependency management:

```bash
poetry add cvbridge_python
```

### Verify Installation

Confirm the package is installed correctly:

```bash
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:

```python
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

```python
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

```python
# 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

```python
# 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`):

```bash
# Run the example
python examples/example.py
```

For more detailed examples, see the [documentation](https://cvbridge_python.readthedocs.io/).

## 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:
   ```bash
   git clone https://gitea.moyskleytech.com/MedusAI/cvbridge_python.git
   cd cvbridge_python
   ```

2. Install dependencies with Poetry:
   ```bash
   poetry install --with dev,test,docs
   ```

3. Activate the virtual environment:
   ```bash
   poetry shell
   ```

### Running Tests

Run the test suite:

```bash
poetry run pytest
```

Run with coverage:

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

### Building Documentation

Build the documentation locally:

```bash
poetry run sphinx-build docs docs/_build
```

