ROS 1 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 Development Environment

Install the corresponding ROS 1 development platform according to the Ubuntu version.

  • Ubuntu16.04: ROS Kinetic

  • Ubuntu18.04: ROS Melodic

  • Ubuntu20.04: ROS Noetic

Download Camport ROS 1 SDK

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

Choose any of the following methods to download Camport ROS 1 SDK:

  • Access https://github.com/percipioxyz/camport_ros.git using a browser and download the Camport ROS 1 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 Camport ROS 1 SDK directory contains src (source code) and multiple packages.

The src contains the following two folders:

  1. percipio_camera: Includes source files and configuration files.

    Camport ROS 1 SDK folder

    Camport ROS 1 SDK src folder

  2. percipio_launch: Launch package.

    This package implements ROS node startup and configuration through XML configuration files, supporting the definition of node names, types, parameters, and other attributes.

    Additionally, its launch files support service node declaration, facilitating the integration of subscription service functionality.

    The package also provides four image display scripts: depth.py, color.py, depthcloud.py, and cloud.py. For detailed usage instructions, please refer to Subscribe to Topics.

    Camport ROS 1 SDK launch Package

    Camport ROS 1 SDK launch Package

Compile ROS 1 SDK

To compile the ROS 1 SDK, 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 final output such as 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 Camera Parameter Configuration

ROS 1 supports two parameter modification methods.

Method 1

Configure parameters directly in the percipio.launch file (only for parameters available in this file). The steps are as follows:

  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:

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

Tip

  • The device_id is set to #1 by default, and the system will open the first camera found.

  • If device_id is set to the camera SN, the system will open the corresponding camera using the specified SN.

  • If default_id is set to the camera’s IP address, the system will open the camera using the specified IP.

  • 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

Argument

Description

Value Range

device_id

Camera SN / Camera IP

–

device_reconnection

Enable/disable camera reconnection function

true/false

rgb_resolution

Color resolution

Color image length x width

depth_resolution

Depth resolution

Depth image length x width

rgb_format

Color image format

mono/bayer/bgr/yuv/jpeg

bayer: includes CSI_BAYER10GRBG, BAYER8GB, BAYER8BG, CSI_BAYER12GBRG

mono: includes MONO10

yuv: includes YUYV, YCbCr

depth_format

Depth image format

depth16/xyz48

depth_registration

Enable/disable depth-to-color registration

true/false

color_undistortion

Enable/disable color image distortion correction

true/false

depth_speckle_filter

Enable/disable depth image speckle filter

true/false

max_speckle_size

Speckle filter area threshold

Default: 150, Range: 10-3000

max_speckle_diff

Speckle filter clustering threshold

Default: 64, Range: 5-1500

depth_time_domain_filter

Enable/disable time domain filter

true/false

depth_time_domain_num

Time domain filter image count

Default: 3, Range: 2-10

use_device_time

Controls the source of the timestamp

true: Uses the device’s hardware time

false: Uses the host system (ROS) time

true/false

Note

  • The TL460-S1-E1 camera supports two bayer format color image outputs: CSI_BAYER8RGGB and CSI_BAYER12RGGB. If the camera is set to output bayer format color images by modifying the percipio.launch file, the default output is CSI_BAYER8RGGB, and it is not possible to switch to CSI_BAYER12RGGB by modifying this file.

  • If the camera format or resolution configured through the percipio.launch file is not supported by the camera, the system will use the default configuration for image output.

Method 2

Set Camera Parameters Using Percipio Viewer Software and Camport SDK.

  • GigE 2.0 Cameras (all models except PMD series and GM series)

    Use Percipio Viewer or Camport SDK 3.X.X to save parameters to the camera’s Storage area. The ROS system will automatically load the parameter configuration from the Storage area at startup and begin capturing images.

  • GigE 2.1 Cameras (PMD series and GM series models)

    Use Camport SDK 4.X.X or the latest version of Percipio Viewer to set the target User Set as the default parameter group at camera startup. The camera will automatically load the configuration of the selected User Set after power-on.

Launch Camera Node

To launch the camera node, execute the following command in the root directory of the development package:

roslaunch percipio_launch percipio.launch

If the camera node starts successfully, the terminal will display information such as the camera IP address, SN, depth map format & resolution, and color image format & resolution.

Note

Do not close the terminal running this service during operation.

Subscribe to Topics

The src/percipio_launch directory contains the following sample Python scripts for camera node subscription:

  • depth.py: Enables the specified camera to capture depth maps in the designated format and resolution.

    After launching the camera node, open a new terminal and navigate to src/percipio_launch. Execute python3 depth.py to run the script, which will display real-time depth maps from the specified camera in a pop-up window, as shown below:

    depth.py Execution Result

    depth.py Execution Result

  • color.py: Enables the specified camera to capture color images in the designated format and resolution.

    After launching the camera node, open a new terminal and navigate to src/percipio_launch. Execute python3 color.py to run the script, which will display real-time color images from the specified camera in a pop-up window, as shown below:

    color.py Execution Result

    color.py Execution Result

  • cloud.py: Enables the specified camera to capture and save point clouds in the designated format and resolution.

    After launching the camera node, open a new terminal and navigate to src/percipio_launch. Execute python3 cloud.py to run the script, which will:

    • Display real-time raw point clouds from the specified camera

    • Print the point cloud save path and point count in the terminal

    cloud.py Execution Result

    cloud.py Execution Result

  • depthcloud.py: Enables the specified camera to capture and save colored point clouds in the designated format and resolution.

    After setting depth_registration to true in percipio.launch and launching the camera node, open a new terminal and navigate to src/percipio_launch. Execute python3 depthcloud.py to run the script, which will:

    • Display real-time colored point clouds from the specified camera

    • Print the point cloud save path and point count in the terminal

    depthcloud.py Execution Result

    depthcloud.py Execution Result

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.