ROS2 NDArray Message

A ROS2 package for transmitting NumPy ndarrays between ROS2 nodes.

Features

• Custom ROS2 message type for numpy.ndarray
• Bi-directional conversion between NumPy arrays and ROS2 messages
• Multi-dimensional array support with various data types
• Type-safe Python utilities with full type hints

Requirements

• ROS2 Humble or higher
• Python 3.10+

Installation

cd ~/ros2_ws/src
git clone https://github.com/Geson-anko/numpy_ndarray_msgs.git
cd ../
colcon build --packages-select numpy_ndarray_msgs
source install/setup.sh

Install Python Utility Package

pip install ros2-ndarray-msg-utils

Usage

Python Utility Package

import numpy as np
from ndarray_msg_utils import to_ros_msg, from_ros_msg, NDArray
from rclpy.clock import ROSClock

# Convert NumPy array to ROS2 message
array = np.array([[1, 2], [3, 4]], dtype=np.float32)

# Type Hint
msg: NDArray

msg = to_ros_msg(array)

# with Header
msg = to_ros_msg(array, timestamp=ROSClock().now(), frame_id="array_frame")

# Convert back to NumPy array
restored = from_ros_msg(msg)

PyTorch Support

pip install "ros2-ndarray-msg-utils[torch]"

import torch
from ndarray_msg_utils.torch import to_ros_msg, from_ros_msg

# Convert PyTorch tensor to ROS2 message
tensor = torch.tensor([[1, 2], [3, 4]], dtype=torch.float32)
msg = to_ros_msg(tensor)

# Convert back to PyTorch tensor
restored = from_ros_msg(msg)

License

MIT License

Contributing Guide

Development Environment

This project uses Visual Studio Code’s devcontainer feature for consistent development environments.

Docker and VS Code with the “Dev Containers” extension are required.

Setup

1. Install prerequisites:

   • Docker
   • Visual Studio Code
   • VS Code “Dev Containers” extension

2. Clone and open the repository:

git clone https://github.com/Geson-anko/numpy_ndarray_msgs.git
cd numpy_ndarray_msgs
code .

1. When prompted by VS Code, click “Reopen in Container” or press F1 and select “Dev Containers: Reopen in Container”

Development Workflow

Building

The ROS2 message interface can be built using:

./build.sh

Testing

Run tests with:

make test

Code Style

We use pre-commit hooks for code formatting and linting:

make format  # Run pre-commit hooks

Code style is enforced by:

• Ruff for Python linting and formatting
• Type hints are required for public interfaces
• Google style docstrings required for public classes and methods
• Simple, readable code structure

Making Changes

1. Create a new branch for your changes:

git checkout -b feature/your-feature-name

1. Make your changes, ensuring:

   • All tests pass
   • Code is formatted
   • Type hints are added
   • Docstrings are added for public interfaces
   • Tests are added for new features

2. Commit your changes:

git add .
git commit -m "feat: your descriptive commit message"

Pull Request Guidelines

• One feature/fix per PR
• Update documentation if needed
• Add tests for new features
• Follow the existing code style
• Keep commits clean and descriptive

Project Structure

.
├── msg/              # ROS2 message definitions
├── src/              # Source code
│   └── ndarray_msg_utils/
├── tests/            # Test files
└── .devcontainer/    # Development container configuration

Documentation

• Add docstrings following Google style
• Type hints are required
• Keep documentation updated with changes
• English only

Need Help?

Feel free to open an issue for questions or problems.