ROS

3dvisionlabs offers a Robot Operating System (ROS) proxy to integrate the HemiStereo NX into ROS software libraries and tools. The proxy provides a ROS 2 node to publish the point cloud and image.

For ROS (1) support, the ROS (1) Bridge is a network bridge which enables the exchange of messages between ROS 1 and ROS 2.

The code of the ROS 2 proxy is open source and available here.

Getting Started

The ROS 2 proxy can be run on the Hemistereo NX. Alternatively, the proxy should be executable on any other Linux system that meets the following requirements:

Docker version 19.03 or later.
ROS 2 supported the architecture.
Hemistereo NX is reachable over the network.

Prebuild Images for arm64 and amd64 are provided over Docker Hub.

System setup

To get started you need the Docker Engine and optional but recommended Docker Compose, both should be present at the Hemistereo NX, if you use another PC you have to install them.

Node/Proxy setup

Following instruction, download the required Docker image and launch the ROS 2 proxy:

Download the Docker Compose and configuration files

Where necessary, tools for downloading and unpacking must be installed or other tools must be used
```
$ sudo apt install unzip wget
```
Download and unzip
```
$ wget https://files.3dvisionlabs.com/hemistereo/support/ros2_docker-compose_setup.zip
$ unzip ros2_docker-compose_setup.zip
```
Change to the unzipped folder
```
$ cd ros2_hemistereo_proxy
```
Adjust the IP address and port to your environment. If the ROS 2 node is running on the Hemistereo NX, the default value localhost:8888 should work. Edit the config/hemistereo.yaml regarding your needs with an editor of your choice
```
$ nano config/hemistereo.yaml
```

Pull the image

$ docker-compose pull

Or if you do not want to use Docker Compose

$ docker pull 3dvl/hemistereo-ros2:latest

Run the container in background

$ docker-compose up -d

Without Docker Compose

$ docker run -it \
    --network host \
    -v <pwd>/config/hemistereo.yaml:/opt/hemistereo/config/hemistereo.yaml \
    3dvl/hemistereo-ros2:latest

Note

Docker volume path must be absolute, adjust <pwd>.

Usage

Available topics

topics	message type
`/hemistereo/image`	sensor_msgs/msg/Image
`/hemistereo/pointcloud`	sensor_msgs/msg/PointCloud2
`/hemistereo/distancecolored`	sensor_msgs/msg/Image

Rviz2

Launch Rviz2 on any PC at the same network. Select the menu item File -> Open Config and choose the hemistereo.rviz file, which is in the ros2_hemistereo_proxy folder, available here.

Parameters and configuration

The ROS2 parameters are mostly generated automatically from the parameters provided by Hemistereo NX.

List parameters

To display all available parameters, use the following command

$ ros2 param list

Describe parameters

In order to get a more detailed description of the parameter and existing constraints

$ ros2 param describe node_name parameter_names

For example

$ ros2 param describe hemistereo ip_address
Parameter name: ip_address
Type: string
Description: IP address and port on which the Hemistereo sensor is reached, default is "localhost:8888".
Constraints:
  Read only: true
  Additional constraints: Changing the IP address and port is only possible by restarting, please use "config/hemistereo.yaml" to do so.

Get parameters

If you wish to read a parameter use:

$ ros2 param get node_name parameter_name

For example

$ ros2 param get hemistereo stereo_matching_image_width

Set parameters

To change a parameter you can use:

$ ros2 param set node_name parameter_name value

For example

$ ros2 param set hemistereo stereo_matching_image_width 1024

Alternatively, many of the settings can be easily accessed via the HemiStereo Viewer.

Save your configuration

It is possible to save your current parameters with:

$ ros2 param dump hemistereo

This will save your confirmation to ./hemistereo.yaml, which you can use to replace the config/hemistereo.yaml.

Building

Clone this Repo

$ git clone --recursive https://git.3dvisionlabs.com/3dvisionlabs/software/hemistereo/apps/stereo/ros2.git

Switch to the cloned directory
```
$ cd ros2
```

Run

$ docker-compose build

or

$ docker build -t 3dvl/hemistereo

Logging

ROS 2 provices serveral log levels. The Hemistereo ROS 2 node uses the WARN log level by default, if you want to change this you have to change the following line in the docker file and rebuild the docker image:

ENTRYPOINT . install/setup.bash \
    && ros2 run hemistereo publisher --ros-args --params-file /opt/hemistereo/config/hemistereo.yaml --log-level warn