Home Articles ROS support for Tara

Articles

[+] Articles

ROS support for Tara

by Dilip Kumar J - Camera Team

Introduction

Tara is a UVC-Compliant 3D Stereo camera based on MT9V024 stereo sensor from onsemi® which supports WVGA((2*752)x480) at 60fps over USB 3.0 in uncompressed format. This Stereo camera provides two synchronized sensor frame data interleaved side by side to the host machine over USB 3.0 interface. It also houses an inbuilt IMU chip which allows the user to read the 3D space inclination of the camera in real-time.

Tara can be used by customers to develop their Stereo Camera algorithms and also by customers who would want to integrate Stereo Camera in their product design.

e-con Systems 3D Stereo camera is ideal for applications such as Depth Sensing, Disparity Map, Point Cloud, Machine vision, Drones, 3D video recording, Surgical robotics, etc.

This document explains about the following:

How to use the image data from a See3CAM_Stereo USB camera in a system running ROS.
How to build a sample ROS based application.
How to identify the current camera properties.
How to change the camera properties such as exposure, brightness.

Scope

This document is intended as a getting started guide for application developers who wish to use the images from See3CAM_Stereo camera on a system running ROS.

Prerequisites

The current ROS distribution (Jade) must be installed on a PC running ubuntu 14.04. The installation instructions can be found here. The system should also have provision for connecting a USB3.0 device. Make sure that the See3CAM_Stereo USB camera is working fine with some of the sample apps present in the Tara-SDK which is also provided by e-con.

The developer is also required to have some basic knowledge about ROS and its core working concepts. To read more about the basics of ROS and creating a sample application in ROS, refer to the following link.

Note:
Installing the ros-jade-ros-base package should do fine. But installing ros-jade-desktop-full package will remove the need to install dependencies at a later stage.

Installing the ROS camera driver

Before installing the camera driver for ROS, create a workspace directory where all the ROS related work is going to be done.

$ mkdir ~/ROS_WS/src -p
$ cd ~/ROS_WS/src

Install a modified version of uvc_camera driver for ROS which has support for HID extension unit. It can be installed using the following commands:

$ git clone https://github.com/dilipkumar25/see3cam
$ cd see3cam
$ git checkout tara_v1.2
$ sudo apt-get install ros-jade-camera-info-manager
$ sudo apt-get install libudev-dev
$ cd ~/ROS_WS/
$ catkin_make

The installed package has to be added to the .bashrc file. This can be done by adding the following lines to the end of .bashrc file.

#Setup environment for uvc_camera driver for ROS
source ~/ROS_WS/devel/setup.bash

The udev rules have to be updated to provide read access to HID interface which is necessary for some of the functionality of the driver to work. This can be done using the following commands:

$ cd ~/ROS_WS/src/see3cam
$ sudo cp udev/99-uvc.rules /etc/udev/rules.d/
$ sudo udevadm trigger

Camera streaming

Once the camera driver for Tara is installed, it has to be launched using a sample launch file which is also present along with the driver. The following command will launch the camera and expose a few ROS topics which can be used for camera streaming.

$ roslaunch uvc_camera tara_launch.launch

The preview from the camera can be viewed using your one code or using a sample application such as rqt_image_view which is provided in ROS Jade by default. Install and run it using the commands in a separate terminal.

$ sudo apt-get install ros-jade-rqt-image-view
$ rqt_image_view

Fig 6.1 List of supported streaming topics

The ROS driver for Tara USB camera supports two topics for streaming both the left and right images simultaneously. The following are all the topics which are created when the camera driver is launched.

/stereo/concat
/stereo/image_raw
/stereo/left/image_raw
/stereo/left/camera_info
/stereo/right/image_raw
/stereo/right/camera_info

The rqt_image_view application supports viewing the camera stream using the concat or image_raw nodes.

Fig 6.2 Camera preview showing both frames

Fig 6.3 Camera preview showing only left frame

Changing camera parameters

The exposure and brightness of the camera can be configured dynamically during run time. Use the following commands to get the brightness and exposure of the connected Tara USB camera.

$ rostopic echo -n 1 /stereo/get_exposure
$ rostopic echo -n 1 /stereo/get_brightness

Use the following commands to set the brightness and exposure of the connected Tara USB camera.

$ rostopic pub -1 /stereo/set_exposure std_msgs/Float64 "data:<value>"
Example
$ rostopic pub -1 /stereo/set_exposure std_msgs/Float64 "data: 20000"

$ rostopic pub -1 /stereo/set_brightness std_msgs/Float64 "data:<value>"
Example
$ rostopic pub -1 /stereo/set_brightness std_msgs/Float64 "data: 6"

Use the following command to get the X,Y,Z co-ordinates of the connected Tara USB camera.

$ rostopic echo /stereo/get_IMU

Additional features

The ROS camera driver for Tara USB camera has been designed in such a way that it creates a stereo node pair of topics for camera streaming as well as getting the camera info. So other modules/drivers which are designed to be compatible with stereo cameras should work with this driver. One such untested example driver is stereo_image_proc.

Also the camera comes pre-calibrated and the data can be used by other ROS drivers using the corresponding camera_info topics for the left and right sensors as they are also exposed by the driver. There is no need to calibrate the cameras manually once again using a checkerboard pattern.

Known Issues and Limitation

This documentation provides instructions to use the camera driver in ROS version Jade only.
The above procedure is tested on a system running Ubuntu 14.04 64 bit only.
The directory which stores the camera config files (yaml) has to be created manually for the first time after driver installation (catkin_make). Use the following command to create it.
- $ mkdir ~/.ros/camera_info -p

Support

Please contact sales@e-consystems.com for further support.

Conclusion

This document should be helpful for customers in using Tara in any ROS based system.