ROS 1 Platform

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

Setting Up the ROS 1 Development Environment

Install the corresponding ROS 1 development platform based on your Ubuntu version.

  • Ubuntu 16.04: ROS Kinetic

  • Ubuntu 18.04: ROS Melodic

  • Ubuntu 20.04: ROS Noetic

Download Camport ROS 1 SDK

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

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

  • Download via browser: https://github.com/percipioxyz/camport_ros.git.

  • Use git command to get a local copy: Open a terminal, navigate to the working directory where you want to store the SDK, and enter the git clone command to clone the remote repository.

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

The src source code directory of the Camport ROS 1 SDK contains the following two core modules:

  1. percipio_camera: The core camera driver module, including source files and configuration files.

    percipio_camera/
├── 📂 camport4/                   # Camport4 SDK
├── 📂 cfg/                        # Dynamic configuration
├── 📂 include/                    # Header files
├── 📂 ros/                        # ROS configuration
├── 📂 src/                        # Source code
├── 📂 srv/                        # Service definitions
├── 📂 test/                       # Testing
├── 📄 .travis.yml                 # CI configuration
├── 📄 CHANGELOG.rst              # Changelog
├── 📄 CMakeLists.txt             # Build configuration
├── 📄 package.xml                # ROS package definition
├── 📄 percipio_nodelets.xml      # Nodelet configuration
└── 📄 README.md                  # Documentation

  2. percipio_launch: Launch configuration module, including the launch package.

    This package implements ROS node startup and configuration through XML configuration files, supporting attributes such as node name, type, and parameters. Additionally, its launch files support the declaration of service nodes, facilitating the integration of subscription service functionality. Python example programs are provided within the package. For specific usage, refer to Subscribe to Topics.

    percipio_launch/
├── 📂 launch/                    # ROS launch configuration file directory
│   ├── 📂 includes/              # Common include files
│   ├── 📄 percipio.launch       # Single camera launch configuration
│   └── 📄 percipio_multi.launch # Multiple camera launch configuration
├── 📄 CHANGELOG.rst             # Version changelog
├── 📄 cloud.py                  # Point cloud display and save script
├── 📄 CMakeLists.txt            # CMake build configuration
├── 📄 color.py                  # Color image display script
├── 📄 depth.py                  # Depth image display script
├── 📄 depthcloud.py             # Colored point cloud display and save script
├── 📄 device_event_listen.py    # Camera event monitoring script
├── 📄 dynamic_config.py         # Dynamic parameter configuration script
├── 📄 package.xml               # ROS package definition file
├── 📄 parameters.xml            # Camera parameter configuration file
├── 📄 reset.py                  # Camera software reset script
└── 📄 soft_trigger.py           # Software trigger control script

Compilation

Execute the following commands in the root directory of the development package for compilation:

catkin_make -DCMAKE_BUILD_TYPE=Release
catkin_make install

After compilation, a build folder (containing intermediate files) and a devel folder (containing final files: header files, dynamic/static libraries, executables) will be generated.

Note

If compilation fails on Ubuntu 16.04, refer to Ubuntu 16.04 compilation of ROS 1 SDK failed.

Configure Environment Variables

Execute the following commands in the root directory of the development package to configure environment variables:

echo "source <Development package storage path>/camport_ros/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

Modify Camera Parameters

ROS 1 supports three ways to modify camera parameters.

Method 1: Pre-configure parameters using Viewer software and save them to the camera (Recommended)

  • GigE2.1 Cameras (PMD Series and GM Series Cameras)

    Use Viewer software to save parameter settings to a UserSet attribute group and set this group as the default User Set attribute group to load. The camera will automatically load the parameter configuration from this User Set attribute group upon power-up.

  • GigE2.0 Cameras (Cameras other than PMD Series and GM Series)

    Use Percipio Viewer software to save parameter settings to the camera’s Storage area. ROS will automatically load the parameter configuration from the Storage area upon startup and begin image acquisition.

Method 2: Edit percipio.launch configuration file

Configure parameters to be loaded when the camera node starts in the percipio.launch file. This method is only applicable to parameters included in the configuration file.

Specific steps are as follows:

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

cd src/percipio_launch/launch/
gedit percipio.launch

  1. Adjust parameter values in the configuration file according to actual needs.

    Example: Specifying a Camera

    Find the device_id parameter in the file and modify its default value.

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

    Tip

    • The default value for device_id is #1, meaning the first camera found will be opened by default.

    • Setting default to a camera SN means opening the camera by specifying its serial number.

    • Setting default to a camera IP means opening the camera by specifying its IP address.

    For more parameter configuration descriptions, refer to the table below.

    Configurable Parameters in percipio.launch

    Attribute Name

    Description

    Value Range

    device_id

    Specify camera

    #1 / Camera SN / Camera IP

    device_reconnection

    Camera reconnection switch

    true/false

    device_log_enable

    Enable/Disable camera Log

    true/false

    device_log_level

    Set camera Log level

    VERBOSE/DEBUG/INFO/WARNING/ERROR

    device_log_server_port

    Set server port

    Default: 9001

    frame_rate_control

    Frame rate control switch

    true/false

    frame_rate

    Set output frame rate

    Float, Default: 5.0

    trigger_mode

    Trigger mode switch

    true/false

    frame_rate_control and trigger_mode cannot be enabled simultaneously.

    If both are enabled, frame_rate_control takes effect, trigger_mode does not.

    rgb_resolution

    Color resolution

    Width x Height of color image

    depth_resolution

    Depth resolution

    Width x Height of depth image

    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

    Depth and color image alignment switch

    true/false

    This enable switch only takes effect when both color and depth images are enabled simultaneously.

    This setting is invalid for cameras without an RGB component.

    color_undistortion

    Color image distortion correction switch

    true/false

    ir_undistortion

    Infrared image distortion correction switch

    true/false

    depth_speckle_filter

    Depth image speckle filter switch

    true/false

    max_speckle_size

    Speckle filter area threshold

    Default: 150, Range: 10-3000

    max_speckle_diff

    Speckle filter clustering

    Default: 64, Range: 5-1500

    max_physical_size

    Maximum physical size

    Default: 20.0

    depth_time_domain_filter

    Temporal filter switch

    true/false

    depth_time_domain_num

    Temporal filter count

    Default: 3, Range: 2-10

    ir_enhancement

    Infrared enhancement mode

    off/linear/multi_linear/std_linear/log/hist

    ir_enhancement_coefficient

    Infrared enhancement coefficient

    Default: 6; multi_linear: 1-20; std_linear: 3-10; log: 10-30

    use_device_time

    Controls timestamp source.

    true/false

    • true means using device hardware time

    • false means using ROS host system time.

    Note

    If a camera outputs images with a format or resolution not supported as configured in the percipio.launch file, the camera will output images with the default configuration.

Method 3: Edit parameters.xml configuration file

Navigate to “src/percipio_launch” to configure parameters loaded when the camera node starts. This method is only applicable to parameters included in the configuration file.

Parameter setting instructions are as follows:

  1. Float type parameter

<feature name="DepthScaleUnit">0.125</feature> // Replace 0.125 with the target parameter value

  1. Int type parameter

<feature name="DepthSgbmImageNumber">1</feature> // Replace 1 with the target parameter value

  1. Bool type parameter

<feature name="ExposureAuto">1</feature> // Replace with 1 or 0, do not use true or false

  1. Enum type parameter

<feature name="DepthStreamTofChannel">0</feature> // Replace 0 with the integer value corresponding to the enumeration value

Launch Camera Node

Execute the following command in the root directory of the development package to start the camera node:

roslaunch percipio_launch percipio.launch

If the camera node starts normally, the terminal will print information such as camera IP, SN, depth and color image formats and resolutions.

Attention

Do not close the service terminal during operation.

Subscribe to Topics

Available Topics

  • /camera/PercipioDeviceEvent

  • /camera/Pointcloud2

  • /camera/camera_nodelet_manager/bond

  • /camera/depth/camera_info

  • /camera/depth/image

  • /camera/dynamic_config

  • /camera/ir/camera_info

  • /camera/ir/image

  • /camera/percipio_camera/parameter_descriptions

  • /camera/percipio_camera/parameter_updates

  • /camera/reset

  • /camera/rgb/camera_info

  • /camera/rgb/image

  • /rosout

  • /rosout_agg

  • /tf_static

Preview Images

The “src/percipio_launch” path contains Python example programs, such as viewing depth images, color images, point clouds, and colored point clouds.

  • depth.py: Enables the specified camera to acquire depth images with a specified format and resolution.

    a. Open Terminal 1, run roslaunch percipio_launch percipio.launch to start the camera node.
    b. Open Terminal 2, navigate to the “src/percipio_launch” path. Enter python3 depth.py and run it.
    A window will pop up, displaying the depth image from the specified camera in real-time.
    depth.py run result

    depth.py run result

  • color.py: Enables the specified camera to acquire color images with a specified format and resolution.

    a. Open Terminal 1, run roslaunch percipio_launch percipio.launch to start the camera node.
    b. Open Terminal 2, navigate to the “src/percipio_launch” path. Enter python3 color.py and run it.
    A window will pop up, displaying the color image from the specified camera in real-time.
    color.py run result

    color.py run result

  • cloud.py: Enables the specified camera to acquire a point cloud with a specified format and resolution, and save it.

    a. Open Terminal 1, run roslaunch percipio_launch percipio.launch to start the camera node.
    b. Open Terminal 2, navigate to the “src/percipio_launch” path. Enter python3 cloud.py and run it.
    A window will pop up, displaying the raw point cloud from the specified camera in real-time. Simultaneously, Terminal 2 will print the point cloud save path and point count.
    cloud.py run result

    cloud.py run result

  • depthcloud.py: Enables the specified camera to acquire a colored point cloud with a specified format and resolution, and save it.

    a. In the percipio.launch file, set depth_registration to true and save.
    b. Open Terminal 1, run roslaunch percipio_launch percipio.launch to start the camera node.
    c. Open Terminal 2, navigate to the “src/percipio_launch” path. Enter python3 depthcloud.py and run it.
    A window will pop up, displaying the colored point cloud from the specified camera in real-time. Simultaneously, Terminal 2 will print the point cloud save path and point count.
    depthcloud.py run result

    depthcloud.py run result

Monitor Camera Events

device_event_listen.py: Used to monitor camera events, such as disconnection, camera coming online, etc.

a. Open Terminal 1, run roslaunch percipio_launch percipio.launch to start the camera node.
b. Open Terminal 2, navigate to the “src/percipio_launch” path. Run python3 device_event_listen.py.
Terminal 2 will display monitored events (e.g., camera disconnection and reconnection after power cycling).
device_event_listen.py run result

device_event_listen.py run result

Dynamically Modify Camera Parameters

dynamic_config.py: Camera parameters can be dynamically modified during operation using this script.

a. Open Terminal 1, run roslaunch percipio_launch percipio.launch to start the camera node.
b. Navigate to the “src/percipio_launch” path, modify parameters in the dynamic_config.py file.

Note

Dynamically configured parameters can only be those that can be modified during camera acquisition, such as exposure time, gain, analog gain, laser brightness, etc.

c. Open Terminal 2, enter python3 dynamic_config.py and run it.
d. Run python3 color.py to view the effect after parameter adjustment.
dynamic_config.py file

dynamic_config.py file

dynamic_config.py run result

dynamic_config.py run result

Camera Software Reset

reset.py: When a camera encounters an error during operation and it’s inconvenient to power cycle the camera, you can use this script to reset the camera.

a. Open Terminal 1, run roslaunch percipio_launch percipio.launch to start the camera node.
b. Open Terminal 2, navigate to the “src/percipio_launch” path. Enter python3 color.py and run it to enable camera image acquisition.
c. Open Terminal 3, navigate to the “src/percipio_launch” path, enter python3 reset.py and run it to reset the camera.
d. Return to Terminal 2, observe the output information. If the camera successfully resets and begins acquiring images again, it indicates the reset operation is complete.
reset.py run result

reset.py run result

color.py run result (camera reset and reacquiring images)

color.py run result (camera reset and reacquiring images)

Send Software Trigger Signal

soft_trigger.py: Used to send software trigger signals. The camera will capture an image upon receiving the signal.

a. Open the percipio.launch file and set the trigger_mode parameter to true.
b. Open Terminal 1, run roslaunch percipio_launch percipio.launch to start the camera node.
c. Open Terminal 2, navigate to the “src/percipio_launch” path, enter python3 soft_trigger.py camera 10 and run it to send 10 software trigger commands to the camera.
d. Return to Terminal 1, it will display that 10 software trigger commands have been received.
soft_trigger.py run result

soft_trigger.py run result

Terminal starting camera node (receiving software trigger commands)

Terminal starting camera node (receiving software trigger commands)

Auxiliary Tools Description

list_devices Enumerate Cameras

Run the following code to enumerate Percipio cameras connected to the computer.

rosrun percipio_camera list_devices

network_ip_config Set Camera IP Address

Run the following code and follow the prompts to set the camera IP address. Supports setting static and dynamic IP addresses.

rosrun percipio_camera network_ip_config

Multiple Camera Configuration and Startup

ROS 1 supports multiple cameras working simultaneously. Follow these steps to configure and start a multi-camera system:

  1. Navigate to “/src/percipio_launch/launch”, open the percipio_multi.launch file and complete the multi-camera configuration.

percipio_multi.launch file

percipio_multi.launch file

  1. Open a terminal and run the following code to start the camera node.

    roslaunch percipio_launch percipio_multi.launch

    After successful startup, the terminal will show that the two cameras have been configured and opened.

Starting camera node

Terminal display after node startup (configuring cameras)

Starting camera node

Terminal display after node startup (opening cameras)

  1. Subscribe to topics and acquire images.

Frequently Asked Questions

Ubuntu 16.04 compilation of ROS 1 SDK failed

Problem Description

The following error occurs during compilation of ROS 1 SDK on Ubuntu 16.04.

Error message

Error message

Solution

Modify the following two files, then recompile.

  • src/percipio_camera/CMakeLists.txt add “set(CMAKE_CXX_STANDARD 11)”.

    CMakeLists.txt modification

    CMakeLists.txt

  • src/percipio_camera/src/DepthStreamProc.cpp add “#include <cstdlib>”.

    DepthStreamProc.cpp modification

    DepthStreamProc.cpp

No depth image output immediately when running python3 depth.py after enabling temporal filtering

The temporal filtering function requires collecting 2-10 frames of raw depth data to fill the buffer (specific frame count configurable). Depth images are output after multi-frame temporal fusion calculation. Therefore, there will be a brief delay after program startup.

Camera output image format or resolution does not follow UserSet preset parameters or Storage area configuration

If the camera storage area or UserSet has set the image format and resolution, and the percipio.launch file also configures the image resolution and format, ROS will dynamically set these parameters via the launch file with priority.