ROS1 Platform

ROS (Robot Operating System, hereinafter referred to as ROS) is an open-source meta-operating system suitable for robots. It provides the services that an operating system should have, including hardware abstraction, underlying device control, implementation of common functions, inter-process messaging, and package management.

Set up ROS1 Development Environment

Install the corresponding ROS1 development platform according to the Ubuntu version.

  • Ubuntu16.04: ROS Kinetic

  • Ubuntu18.04: ROS Melodic

  • Ubuntu20.04: ROS Noetic

Download Camport ROS1 SDK

ROS1 SDK supports the ROS Kinetic, ROS Melodic and ROS Noetic platforms.

Choose any of the following methods to download Camport ROS1 SDK:

  • Access https://github.com/percipioxyz/camport_ros.git using a browser and download the Camport ROS1 SDK.

  • Use the git command to obtain a local copy: Open the terminal, switch to the working directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

    git clone https://github.com/percipioxyz/camport_ros.git

The directory of Camport ROS1 SDK is shown in the following figure:

Camport ROS1 SDK目录

Camport ROS1 SDK directory

  • percipio_camera: includes source files and configuration files.

  • percipio_launch: launch package.

Compile Sample Programs

To compile the sample programs, execute the following command in the root directory of the development package:

catkin_make

Tip

If the catkin command is not installed, you need to install catkin first.

After compilation, the build folder (containing intermediate files) and the devel folder (containing header files, dynamic/static libraries and executable files) will be generated.

Configure Environment Variables

To configure the environment variables, execute the following command in the root directory of the development package:

echo "source <the root directory of the development package>/camport_ros/devel/setup.bash" >> ~/.bashrc

Modify Configurations in Launch File

To configure the parameters loaded when the camera starts in the percipio.launch file, do the following:

  1. Execute the following command to open the percipio.launch file:

cd src/percipio_launch/launch/
gedit percipio.launch

  1. Modify the configuration as needed.

  • Specify camera SN in default:

<arg name="device_id" default="207000106930" />

Tip

The device_id is set to #1 by default, which means the first camera found will be opened by default.

  • Set the switch for exposure synchronization of left and right infrared images in the default:

<arg name="cmos-sync" default="true" />

  • Set the switch for alignment of depth and color images in the default:

<arg name="depth_registration" default="true" />

Note

This enable switch will only take effect when the color image and the depth maps are both captured. This setting is invalid for cameras without the color component.

List of Configurable Parameters in Launch

Component

Argument

Description

Device

device_id

Camera serial number/ camera IP address

gvsp_resend

Data Resend

cmos-sync

Image synchronization

packet-delay

Packet delay

packet-size

Packet size

time-sync

Time synchronization

NTP server IP

NTP server IP

Device reconnection

device_reconnection

Depth

Depth resolution

depth_resolution

scale_unit

The scale unit for the depth measurement values

ToF Features

tof_channel

Modulation channel

tof_depth_quality

Image Quality of Depth Map

tof_filter_threshold

Outlier Filter Threshold

tof_modulation_thresho

Modulated Laser Light Intensity

tof_jitter_threshold

Jitter Filter Threshold

tof_hdr_ratio

HDR Ratio (High Dynamic Range Ratio)

tof_anti_sunlight_index

Anti-Sunlight Index

tof_anti_interference

Anti-Multi-Camera Interference

SGBM Features

sgbm_match_window_height

The height of the disparity matching window

sgbm_match_window_width

The width of the disparity matching window

sgbm_disparity_num

The disparity search range

sgbm_disparity_offset

The starting value for the disparity search

sgbm_image_channel_number

The number of grayscale images for depth calculation

sgbm_semi_global_param_p1

The penalty parameter P1 for disparity changes

between neighboring pixels (+/-1).

sgbm_semi_global_param_p1_scale

the scaling factor for the penalty parameter P1

for disparity changes between neighboring pixels (+/-1).

sgbm_semi_global_param_p2

The penalty parameter P2 for disparity changes

between surrounding pixels.

sgbm_enable_half_window_size

The switch for search filter

sgbm_uniqueness_factor_param

The percentage of the best and second-best match points

uniqueness_min_absolute_diff

The absolute difference between

the best and second-best match points

sgbm_enable_lrc_check

The left and right consistency check switch

sgbm_lrc_max_diff

Left and right consistency check parameters

sgbm_enable_median_filter

Median filter switch

sgbm_median_filter_thresh

Median filter threshold

Color

color_resolution

Color Resolution

Modify Configurations in Percipio.cfg File

The parameters in the Percipio.cfg file support dynamic adjustment. After modifying the maximum and minimum values of the Percipio.cfg parameters, refer to the Run section to bring up the rqt_reconfigure_Param page and make adjustments.

  1. Execute the following command in the root directory of the software package to open the Percipio.cfg file.

    cd src/percipio_camera/cfg/
gedit Percipio.cfg
    Percipio.cfg

  2. Set the minimum and maximum values for the parameters in gen.add( ).

    Tip

    1. gen.add (name, type, level, description, default, min, max) represents the feature name, type, level, description, default value, minimum value, and maximum value.

    2. Boolean values must be written as True or False (with the first letter capitalized).

    Note

    1. If you don’t know the minimum and maximum values of camera features, you can view the supported components and features of the camera by one of the following steps:

      • Run the SDK sample program DumpAllFeatures to view the components and features supported by the camera in the listed information.

      • Run the SDK sample program DumpAllFeatures -d and check the supported components and features of the camera in the generated fetch_config.xml file.

    2. The setting range of the following parameters can be customized:

      • depth_speckle_filter: Switch for the Remove Outlier function. After enabling this function, adjust max_speckle_size and max_speckle_diff to reduces outliers and mismatched points in the point cloud. For more details, refer to the description for Remove Outlier.

      • max_speckle_size: If the number of points in a region is less than the spk size setting, the points in that region are considered outliers and will be removed. It is recommended to set this value within the range of [10, 3000].

      • max_speckle_diff: If the depth difference between adjacent pixels in a region is less than the spk diff setting, the adjacent pixels in that region are considered part of the same outlier. It is recommended to set this value within the range of [10, 1500].

      • data_skip: Frame skipping interval. For example, if the Percipio Camera’s publishing node operates at 30 fps, but the ROS receiving node only needs 10 fps, you can set data_skip to 3. It is recommended to set this value within the range of [0,20].

      • z_scaling: The depth value unit of the pixels in the depth map. It is recommended to set this value within the range of [0,8].

      • use_device_time: The default setting is True, indicating using the camera’s internal timestamp. When it is set to False, it indicates using ROS timestamp.

  3. Execute the following command to recompile. After compilation, the changes made to Percipio.cfg will take effect.

    catkin_make
List of Configurable Parameters in Percipio.cfg

Parameter Name

Data Type

Description

laser_power

int

Laser Intensity

auto_exposure

bool

The switch of laser auto-adjustment function

auto_exposure_p1_x

double

X-coordinate of the auto-exposure ROI start point

auto_exposure_p1_y

double

Y-coordinate of the auto-exposure ROI start point

auto_exposure_p2_x

double

X-coordinate of the auto-exposure ROI end point

auto_exposure_p2_y

double

Y-coordinate of the auto-exposure ROI end point

auto_white_balance

bool

Auto white balance (AWB)

rgb_exposure_time

int

Color(RGB) exposure time

rgb_analog_gain

int

Color(RGB) analog gain

rgb_r_gain

int

Digital gain of the color channel R

rgb_g_gain

int

Digital gain of the color channel G

rgb_b_gain

int

Digital gain of the color channel B

rgb_aec_target_v

int

The target brightness for auto-exposure

ir_exposure_time

int

IR exposure time

ir_analog_gain

int

IR analog gain

ir_gain

int

IR digital gain

tof_hw_speckle_size

int

Speckle filter size threshold for the TM26x camera series

tof_hw_speckle_diff

int

The maximum depth difference between adjacent pixels

in the same speckle block of the TM26x camera series.

depth_speckle_filter

bool

Switch for the Remove Noise function

max_speckle_size

int

If the number of points in a region is less than the spk size setting,

the points in that region are considered outliers and will be removed

max_speckle_diff

int

If the depth difference between adjacent pixels in a region is

less than the spk diff setting, the adjacent pixels

in that region are considered part of the same outlier.

data_skip

int

Frame skipping interval

z_scaling

double

The depth value unit of the pixels in the depth map.

use_device_time

bool

Switch for using the camera’s timestamp

Subscribe

Execute the following command in the root directory of the development package to subscribe to the service:

roslaunch percipio_launch percipio.launch

Note

During operation, please do not close this service terminal.

Run

  1. Open a new terminal and execute the following command to run RViz:

    rosrun rviz rviz

  2. Add image display.

    1. In the left side of the page, in the Global Options settings, set Fixed Frame to camera_depth_frame.

      Global Options Settings

    2. Add depth map display by the following steps:

      • Click on add, add Camera, name it Depth Camera.

        Add Depth Camera

      • In the newly added Depth Camera settings on the left side of the page, set Image Topic to /camera/depth/image.

        Add Depth Camera

    3. Add color image display by the following steps:

      • Click on add, add Camera, and name it Color Camera.

      • Check the newly added Color Camera on the left side of the page and set the Image Topic to /camera/rgb/image in the settings.

    4. Add IR image display by the following steps:

      • Click on add, add Image, name it IR Camera.

      • Check the newly added IR Camera on the left side of the page and set the Image Topic to /camera/ir/image in the settings.

    5. Add point cloud display by the following steps:

      (i). Add DepthCloud display

      Note

      DepthCloud is a point cloud generated internally by ROS by inputting a depth map and intrinsic parameters, which is then transformed via rgbd_launch within ROS.

      • Click on add, add DepthCloud, name it Depth Cloud.

      • Check the newly added Depth Cloud on the left side of the page and set the Depth Map Topic to /camera/depth/image.

      (ii). Add PointCloud2 display

      Note

      PointCloud2 is a point cloud displayed by ROS when point cloud data is input into ROS.

      • Click on add, add PointCloud2, name it Point Cloud 2.

      • Check the newly added Point Cloud 2 on the left side of the page and set the Topic to /camera/PointCloud2.

  3. Dynamically adjust the camera parameters according to the imaging situation, .

    Execute the following command to bring up the rqt_reconfigure_Param page. Select driver and adjust the parameters on the page.

    rosrun rqt_reconfigure  rqt_reconfigure
    ROS Configure Parameter

Solution for Multi-Device Simultaneous Access

  1. Edit .launch file.

    Refer to the percipio.launch document to create multiple .launch files. Configure camera and device_id with different values in each .launch file. For example, to run two devices simultaneously, create two .launch files, such as percipio_camera1.launch and percipio_camera2.launch.

    percipio_camera1.launch contains the following content:

    <arg name="camera" default="camera1">
......
<arg name="device_id" default="207000010443">
......

    percipio_camera2.launch contains the following content:

    <arg name="camera" default="camera2">
......
<arg name="device_id" default="207000010113">
......

  2. Execute the following command in the root directory of the development package to reconfigure the environment variables:

    source ./devel/setup.bash

  3. Open the device with serial number 207000010443 by running the command roslaunch percipio_launch percipio_camera1.launch.

    Open the device with serial number 207000010113 by running the command roslaunch percipio_launch percipio_camera2.launch.