IntelRealSense · SamerKhshiboun · Mar 26, 2024
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,26 @@
+* Before opening a new issue, we wanted to provide you with some useful suggestions (Click "Preview" above for a better view):
+
+    * Consider checking our ROS RealSense Wrapper documentation [README](https://github.com/IntelRealSense/realsense-ros/blob/ros2-development/README.md).
+    * Have you looked in our [Discussions](https://github.com/IntelRealSense/realsense-ros/discussions)?
+    * Try [searching our GitHub Issues](https://github.com/IntelRealSense/realsense-ros/issues) (open and closed) for a similar issue.
+
+* All users are welcomed to report bugs, ask questions, suggest or request enhancements and generally feel free to open new issue, even if they haven't followed any of the suggestions above :)
+
+----------------------------------------------------------------------------------------------------
+
+| Required Info                         |                                                                                         |
+|---------------------------------|------------------------------------------------------------ |
+| Camera Model                       | { D405 / D415 / D435 / D435i / D455 / D457 }                          | 
+| Firmware Version                   | (Open RealSense Viewer --> Click info)                          | 
+| Operating System & Version |   { Win (10/11) / Linux (Ubuntu 18/20/22) / MacOS } | 
+| Kernel Version (Linux Only)    |  (e.g. 5.4)                                                                       | 
+| Platform                                 | PC/Raspberry Pi/ NVIDIA Jetson / etc..                           |
+| Librealsense SDK Version       |  { 2.<?>.<?> }                                                    | 
+| Language                               |  {C/C#/labview/opencv/pcl/python/unity }         | 
+| Segment			         |  {Robot/Smartphone/VR/AR/others }                             | 
+| ROS Distro			         |  {Iron/Humble/Rolling/etc.. }                                           | 
+| RealSense ROS Wrapper Version   |  {4.51.1, 4.54.1, etc..}                                                  | 
+
+
+### Issue Description
+<Describe your issue / question / feature request / etc..>
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -13,6 +13,8 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+permissions: read-all
+
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 # This workflow contains a single job called "build"
 
@@ -35,10 +37,10 @@ jobs:
     steps:
 
     - name: Setup ROS2 Workspace
-      run: | 
+      run: |
         mkdir -p ${{github.workspace}}/ros2/src
 
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         path: 'ros2/src/realsense-ros'
 

diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml
@@ -23,6 +23,7 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+permissions: read-all
 
 jobs:
   build:
@@ -44,6 +45,6 @@ jobs:
       BASEDIR: ${{ github.workspace }}/.work
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: industrial_ci
         uses: ros-industrial/industrial_ci@master
diff --git a/.github/workflows/static_analysis.yaml b/.github/workflows/static_analysis.yaml
@@ -6,6 +6,8 @@ on:
   pull_request:
     branches: ['**']
 
+permissions: read-all
+
 jobs:
   cppcheck:
     name: cppcheck

diff --git a/README.md b/README.md
@@ -1,3 +1,4 @@
+
 <h1 align="center">
    <img src="https://www.intelrealsense.com/wp-content/uploads/2020/09/intel-realsense-logo-360px.png" alt="Intel® RealSense™" title="Intel® RealSense™" />
 </h1>
@@ -24,7 +25,8 @@
 
 ## Table of contents
   * [ROS1 and ROS2 legacy](#ros1-and-ros2-legacy)
-  * [Installation](#installation)
+  * [Installation on Ubuntu](#installation-on-ubuntu)
+  * [Installation on Windows](#installation-on-windows)
   * [Usage](#usage)
      * [Starting the camera node](#start-the-camera-node)
      * [Camera name and namespace](#camera-name-and-camera-namespace)
@@ -78,7 +80,7 @@
 </details>
 
 
-# Installation
+# Installation on Ubuntu
 
 <details>
   <summary>
@@ -88,14 +90,14 @@
 - #### Ubuntu 22.04:
   - [ROS2 Iron](https://docs.ros.org/en/iron/Installation/Ubuntu-Install-Debians.html)
   - [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html)
-
 </details>
 
 <details>
   <summary>
     Step 2: Install latest Intel&reg; RealSense&trade; SDK 2.0
   </summary>
-
+  **Please choose only one option from the 3 options below (in order to prevent multiple versions installation and workspace conflicts)**
+
 - #### Option 1: Install librealsense2 debian package from Intel servers
   - Jetson users - use the [Jetson Installation Guide](https://github.com/IntelRealSense/librealsense/blob/master/doc/installation_jetson.md)
   - Otherwise, install from [Linux Debian Installation Guide](https://github.com/IntelRealSense/librealsense/blob/master/doc/distribution_linux.md#installing-the-packages)
@@ -161,6 +163,76 @@
 
 <hr>
 
+# Installation on Windows
+  **PLEASE PAY ATTENTION: RealSense ROS2 Wrapper is not meant to be supported on Windows by our team, since ROS2 and its packages are still not fully supported over Windows. We added these installation steps below in order to try and make it easier for users who already started working with ROS2 on Windows and want to take advantage of the capabilities of our RealSense cameras**
+
+<details>
+  <summary>
+    Step 1: Install the ROS2 distribution 
+  </summary>
+
+- #### Windows 10/11
+  **Please choose only one option from the two options below (in order to prevent multiple versions installation and workspace conflicts)**
+  - Manual install from ROS2 formal documentation:
+    - [ROS2 Iron](https://docs.ros.org/en/iron/Installation/Windows-Install-Binary.html)
+    - [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Windows-Install-Binary.html)
+  - Microsoft IOT binary installation:
+    - https://ms-iot.github.io/ROSOnWindows/GettingStarted/SetupRos2.html
+    - Pay attention that the examples of install are for Foxy distro (which is not supported anymore by RealSense ROS2 Wrapper)
+	- Please replace the word "Foxy" with Humble or Iron, as you choose
+</details>
+
+<details>
+  <summary>
+    Step 2: Download RealSense&trade; ROS2 Wrapper and RealSense&trade; SDK 2.0 source code from github:
+  </summary>
+
+- Download Intel&reg; RealSense&trade; ROS2 Wrapper source code from [Intel&reg; RealSense&trade; ROS2 Wrapper Releases](https://github.com/IntelRealSense/realsense-ros/releases)
+- Download the corrosponding supported Intel&reg; RealSense&trade; SDK 2.0 source code from the **"Supported RealSense SDK" section** of the specific release you chose fronm the link above
+- Place the librealsense folder inside the realsense-ros folder, to make the librealsense package set beside realsense2_camera, realsense2_camera_msgs and realsense2_description packages
+</details>
+
+<details>
+  <summary>
+    Step 3: Build
+  </summary>
+
+1. Before starting building of our packages, make sure you have OpenCV for Windows installed on your machine. If you choose the Microsoft IOT way to install it, it will be installed automatically. Later, when colcon build, you might need to expose this installation folder by setting CMAKE_PREFIX_PATH, PATH, or OpenCV_DIR environment variables
+2. Run "x64 Native Tools Command Prompt for VS 2019" as administrator
+3. Setup ROS2 Environment (Do this for every new terminal/cmd you open):
+    - If you choose the Microsoft IOT Binary option for installation
+      ```
+	  > C:\opt\ros\humble\x64\setup.bat
+	  ```
+
+    - If you choose the ROS2 formal documentation:
+      ```
+	  > call C:\dev\ros2_iron\local_setup.bat
+	  ```   
+4.  Change directory to realsense-ros folder
+      ```bash
+      > cd C:\ros2_ws\realsense-ros
+      ```
+5. Build librealsense2 package only
+      ```bash
+      > colcon build --packages-select librealsense2 --cmake-args -DBUILD_EXAMPLES=OFF -DBUILD_WITH_STATIC_CRT=OFF -DBUILD_GRAPHICAL_EXAMPLES=OFF
+      ```
+	  - User can add `--event-handlers console_direct+` parameter to see more debug outputs of the colcon build
+6. Build the other packages
+	```bash
+	> colcon build --packages-select realsense2_camera_msgs realsense2_description realsense2_camera
+	```
+	- User can add `--event-handlers console_direct+` parameter to see more debug outputs of the colcon build
+
+7. Setup environment with new installed packages (Do this for every new terminal/cmd you open):
+      ```bash
+      > call install\setup.bat
+      ```
+</details>
+
+<hr>
+
+
 # Usage
 
 ## Start the camera node
@@ -172,7 +244,7 @@
 
   #### with ros2 launch:
     ros2 launch realsense2_camera rs_launch.py
-    ros2 launch realsense2_camera rs_launch.py depth_module.profile:=1280x720x30 pointcloud.enable:=true
+    ros2 launch realsense2_camera rs_launch.py depth_module.depth_profile:=1280x720x30 pointcloud.enable:=true
 
 <hr>
 
@@ -251,10 +323,10 @@ User can set the camera name and camera namespace, to distinguish between camera
 #### Parameters that can be modified during runtime:
 - All of the filters and sensors inner parameters.
 - Video Sensor Parameters: (```depth_module``` and ```rgb_camera```)
-  - They have, at least, the **profile** parameter.
+  - They have, at least, the **<stream_type>_profile** parameter.
     - The profile parameter is a string of the following format: \<width>X\<height>X\<fps> (The dividing character can be X, x or ",". Spaces are ignored.)
-    - For example: ```depth_module.profile:=640x480x30 rgb_camera.profile:=1280x720x30```
-    - Since infra, infra1, infra2 and depth are all streams of the depth_module, their width, height and fps are defined by the same param **depth_module.profile**
+    - For example: ```depth_module.depth_profile:=640x480x30 depth_module.infra_profile:=640x480x30 rgb_camera.color_profile:=1280x720x30```
+    - Note: The param **depth_module.infra_profile** is common for all infra streams. i.e., infra 0, 1 & 2.
     - If the specified combination of parameters is not available by the device, the default or previously set configuration will be used.
       - Run ```ros2 param describe <your_node_name> <param_name>``` to get the list of supported profiles.
     - Note: Should re-enable the stream for the change to take effect.
@@ -281,6 +353,7 @@ User can set the camera name and camera namespace, to distinguish between camera
   - <stream_type> can be any of *infra, infra1, infra2, color, depth, gyro, accel*.
   -  Available values are the following strings: `SYSTEM_DEFAULT`, `DEFAULT`, `PARAMETER_EVENTS`, `SERVICES_DEFAULT`, `PARAMETERS`, `SENSOR_DATA`.
   - For example: ```depth_qos:=SENSOR_DATA```
+  - Pointcloud QoS is controlled with the `pointcloud.pointcloud_qos` parameter in the pointcloud filter, refer to the Post-Processing Filters section for details.
   - Reference: [ROS2 QoS profiles formal documentation](https://docs.ros.org/en/rolling/Concepts/About-Quality-of-Service-Settings.html#qos-profiles)
 - **Notice:** ***<stream_type>*_info_qos** refers to both camera_info topics and metadata topics.
 - **tf_publish_rate**: 
@@ -305,6 +378,17 @@ User can set the camera name and camera namespace, to distinguish between camera
     - 1 -> **copy**: Every gyro message will be attached by the last accel message.
     - 2 -> **linear_interpolation**: Every gyro message will be attached by an accel message which is interpolated to gyro's timestamp.
   - Note: When the param *unite_imu_method* is dynamically updated, re-enable either gyro or accel stream for the change to take effect.
+- **accelerate_gpu_with_glsl**:
+  - Boolean: GPU accelerated with GLSL for processing PointCloud and Colorizer filters.
+  - Note:
+    - To have smooth transition between the processing blocks when this parameter is updated dynamically, the node will:
+      - Stop the video sensors
+      - Do necessary GLSL configuration
+      - And then, start the video sensors
+    - To enable GPU acceleration, turn ON `BUILD_ACCELERATE_GPU_WITH_GLSL` during build:
+    ```bash
+    colcon build --cmake-args '-DBUILD_ACCELERATE_GPU_WITH_GLSL=ON'
+    ```
 - **safety_camera.safety_mode**:
   - 0 -> **Run** mode
   - 1 -> **Standby** mode
@@ -505,18 +589,32 @@ The following post processing filters are available:
     * The texture of the pointcloud can be modified using the `pointcloud.stream_filter` parameter.</br>
     * The depth FOV and the texture FOV are not similar. By default, pointcloud is limited to the section of depth containing the texture. You can have a full depth to pointcloud, coloring the regions beyond the texture with zeros, by setting `pointcloud.allow_no_texture_points` to true.
     * pointcloud is of an unordered format by default. This can be changed by setting `pointcloud.ordered_pc` to true.
+    * The QoS of the pointcloud topic is independent from depth and color streams and can be controlled with the `pointcloud.pointcloud_qos` parameter.
+      - The same set of QoS values are supported as other streams, refer to <stream_type>_qos in the Parameters section of this page.
+      - The launch file should include the parameter with initial QoS value, for example,`{'name': 'pointcloud.pointcloud_qos',    'default': 'SENSOR_DATA', 'description': 'pointcloud qos'}`
+      - The QoS value can also be overridden at launch with command option, for example, `pointcloud.pointcloud_qos:=SENSOR_DATA`
+      - At runtime, the QoS can be changed dynamically but require the filter re-enable for the change to take effect, for example,
+        ```bash
+        ros2 param set /camera/camera pointcloud.pointcloud_qos SENSOR_DATA
+        ros2 param set /camera/camera pointcloud.enable false
+        ros2 param set /camera/camera pointcloud.enable true
+        ```
  - ```hdr_merge```: Allows depth image to be created by merging the information from 2 consecutive frames, taken with different exposure and gain values.
-  - `depth_module.hdr_enabled`: to enable/disable HDR
-  - The way to set exposure and gain values for each sequence in runtime is by first selecting the sequence id, using the `depth_module.sequence_id` parameter and then modifying the `depth_module.gain`, and `depth_module.exposure`.
-    - From FW versions 5.14.x.x and above, if HDR is enabled, the preset configs (like exposure, gain, etc.,) cannot be updated.
-      - Disable the HDR first using `depth_module.hdr_enabled` parameter and then, update the required presets.
-  - To view the effect on the infrared image for each sequence id use the `filter_by_sequence_id.sequence_id` parameter.
-  - To initialize these parameters in start time use the following parameters:
-    - `depth_module.exposure.1`
-    - `depth_module.gain.1`
-    - `depth_module.exposure.2`
-    - `depth_module.gain.2`
-  - For in-depth review of the subject please read the accompanying [white paper](https://dev.intelrealsense.com/docs/high-dynamic-range-with-stereoscopic-depth-cameras).
+ - `depth_module.hdr_enabled`: to enable/disable HDR. The way to set exposure and gain values for each sequence:
+   -  during Runtime:
+      - is by first selecting the sequence id, using the `depth_module.sequence_id` parameter and then modifying the `depth_module.gain`, and `depth_module.exposure`.
+      - From FW versions 5.14.x.x and above, if HDR is enabled, the preset configs (like exposure, gain, etc.,) cannot be updated.
+        - Disable the HDR first using `depth_module.hdr_enabled` parameter and then, update the required presets.
+    - during Launch time of the node:
+      - is by setting below parameters
+        - `depth_module.exposure.1`
+        - `depth_module.gain.1`
+        - `depth_module.exposure.2`
+        - `depth_module.gain.2`
+      - Make sure to set `depth_module.hdr_enabled` to true, otherwise these parameters won't be considered.
+    - To view the effect on the infrared image for each sequence id use the `filter_by_sequence_id.sequence_id` parameter.
+    - For in-depth review of the subject please read the accompanying [white paper](https://dev.intelrealsense.com/docs/high-dynamic-range-with-stereoscopic-depth-cameras).
+    - **Note**: Auto exposure functionality is not supported when HDR is enabled. i.e., Auto exposure will be auto-disabled if HDR is enabled.
 
   - The following filters have detailed descriptions in : https://github.com/IntelRealSense/librealsense/blob/master/doc/post-processing-filters.md
     - ```disparity_filter``` - convert depth to disparity before applying other filters and back.

diff --git a/realsense2_camera/CMakeLists.txt b/realsense2_camera/CMakeLists.txt
@@ -114,15 +114,21 @@ find_package(nav_msgs REQUIRED)
 find_package(tf2_ros REQUIRED)
 find_package(tf2 REQUIRED)
 find_package(diagnostic_updater REQUIRED)
+find_package(OpenCV REQUIRED COMPONENTS core)
 
 find_package(realsense2 2.55.0)
+if (BUILD_ACCELERATE_GPU_WITH_GLSL)
+  find_package(realsense2-gl 2.55.0)
+endif()
 if(NOT realsense2_FOUND)
     message(FATAL_ERROR "\n\n Intel RealSense SDK 2.0 is missing, please install it from https://github.com/IntelRealSense/librealsense/releases\n\n")
 endif()
 
 #set(CMAKE_NO_SYSTEM_FROM_IMPORTED true)
 include_directories(include)
 
+include_directories(${OpenCV_INCLUDE_DIRS})  # add OpenCV includes to the included dirs
+
 set(node_plugins "")
 
 set(SOURCES
@@ -140,6 +146,10 @@ set(SOURCES
     src/tfs.cpp
   )
 
+if (BUILD_ACCELERATE_GPU_WITH_GLSL)
+  list(APPEND SOURCES src/gl_gpu_processing.cpp)
+endif()
+
 if(NOT DEFINED ENV{ROS_DISTRO})
   message(FATAL_ERROR "ROS_DISTRO is not defined." )
 endif()
@@ -170,6 +180,10 @@ if(${rclcpp_VERSION} VERSION_GREATER_EQUAL "17.0")
   set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DRCLCPP_HAS_OnSetParametersCallbackType")
 endif()
 
+if (BUILD_ACCELERATE_GPU_WITH_GLSL)
+  add_definitions(-DACCELERATE_GPU_WITH_GLSL)
+endif()
+
 set(INCLUDES
     include/constants.h
     include/realsense_node_factory.h
@@ -183,6 +197,9 @@ set(INCLUDES
     include/profile_manager.h
     include/image_publisher.h)
 
+if (BUILD_ACCELERATE_GPU_WITH_GLSL)
+  list(APPEND INCLUDES include/gl_window.h)
+endif()
 
 if (BUILD_TOOLS)
 
@@ -199,9 +216,17 @@ add_library(${PROJECT_NAME} SHARED
     ${SOURCES}
 )
 
+if (BUILD_ACCELERATE_GPU_WITH_GLSL)
+  set(link_libraries ${realsense2-gl_LIBRARY})
+else()
+  set(link_libraries ${realsense2_LIBRARY})
+endif()
+
+list(APPEND link_libraries ${OpenCV_LIBS})  # add OpenCV libs to link_libraries
+
 target_link_libraries(${PROJECT_NAME}
-    ${realsense2_LIBRARY}
-    )
+    ${link_libraries}
+)
 
 set(dependencies
   cv_bridge
@@ -213,11 +238,16 @@ set(dependencies
   sensor_msgs
   nav_msgs
   tf2
-  realsense2
   tf2_ros
   diagnostic_updater
 )
 
+if (BUILD_ACCELERATE_GPU_WITH_GLSL)
+  list(APPEND dependencies realsense2-gl)
+else()
+  list(APPEND dependencies realsense2)
+endif()
+
 ament_target_dependencies(${PROJECT_NAME}
   ${dependencies}
 )