deploy: fd13aba31f

2026-10-04 12:07:46 +08:00 · 2026-01-04 01:12:38 +00:00
parent 0771e0b0c9
commit 220b4ea0dd
481 changed files with 21273 additions and 31092 deletions
@@ -10,11 +10,5 @@ OrbbecSDK V2 ROS2 Wrapper documentation
    :maxdepth: 3
    :numbered:

-    source/1_overview/overview.rst
-    source/2_installation/installation.rst
-    source/3_quickstarts/quickstarts.rst
-    source/4_application_guide/application_guide.rst
-    source/5_advanced_guide/advanced_guide.rst
-    source/6_benchmark/benchmark.rst
-    source/7_developer_guide/developer_guide.rst
-    source/8_FAQ/FAQ.rst
+    source/camera_devices/index.rst
+    source/lidar_devices/index.rst
@@ -1,6 +1,5 @@
-### Binary Installation
+### Environment configuration

-#### Environment

 Install ROS 2 according to the official guide:

@@ -22,7 +21,7 @@ Enable ROS 2 auto-completion:
 eval "$(register-python-argcomplete3 ros2)"
 eval "$(register-python-argcomplete3 colcon)"
 ```
-#### Linux Binary Package Installation
+### Linux Binary Package Installation

 Check available packages:

@@ -43,7 +42,6 @@ After installation, you can use it directly without compilation.

 ### Build from Source

-#### Linux ROS2 Wrapper Compilation

 Create a `colcon` workspace:

@@ -41,6 +41,10 @@ The following are the launch parameters available:
    *   Enable Left IR image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`.
 *   **`right_ir.image_raw.enable_pub_plugins`**
    *   Enable Right IR image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`.
+*   **`point_cloud_decimation_filter_factor`**
+    *   Point cloud downsampling factor. Range: `1–8`. `1` means no downsampling; larger values apply stronger decimation.
+*   **`preset_resolution_config`**
+    * Preset resolution configuration for the camera device. Format: "width,height,ir_decimation_factor,depth_decimation_factor". Example: "1280,720,4,4". Only supported on specific devices like Gemini2. Leave empty to disable.

 ### Sensor Controls

@@ -181,7 +185,7 @@ The following are the launch parameters available:
  *   `COLOR`: Align depth to color.
  *   `DEPTH`: Align color to depth.
 - **`intra_camera_sync_reference`**
-  - Sets the reference point for intra-camera synchronization. Applicable for Gemini 330 series devices when `sync_mode` is set to **software** or **hardware trigger** mode. **Options:** `Start`, `Middle`, `End`. **Default:** `Middle`
+  - Sets the reference point for intra-camera synchronization. Applicable for Gemini 330 series devices when `sync_mode` is set to **software** or **hardware trigger** mode. **Options:** `Start`, `Middle`, `End`. When set to empty, the long baseline device defaults to End, and the short baseline device defaults to Middle.

 ### Basic & General Parameters

@@ -224,6 +228,8 @@ The following are the launch parameters available:
 #### Logging & Diagnostics
 *   **`log_level`**
    *   SDK log level. Default is `info`. Optional values: `debug`, `info`, `warn`, `error`, `fatal`.
+* **`log_file_name`**
+    * Saved SDK log file name. Effective when `log_level` is `debug`.
 *   **`diagnostic_period`**
    *   Diagnostic period in seconds.
 *   **`enable_heartbeat`**
@@ -256,3 +256,13 @@
                    -6.804073229432106e-06]}'
    ros2 service call /camera/get_user_calib_params orbbec_camera_msgs/srv/GetUserCalibParams '{}'
    ```
+
+### Point cloud decimation
+*   `/camera/set_point_cloud_decimation`
+    ```bash
+    ros2 service call /camera/set_point_cloud_decimation orbbec_camera_msgs/srv/SetInt32 '{data: 8}'
+    ```
+*   `/camera/get_point_cloud_decimation`
+    ```bash
+    ros2 service call /camera/get_point_cloud_decimation orbbec_camera_msgs/srv/GetInt32 '{}'
+    ```
@@ -62,3 +62,16 @@ Multi-camera systems place high demands on USB bandwidth and device initializati
  When invoking stream control services (such as `set_streams_enable`, `toggle_depth`, and `toggle_color`), avoid triggering multiple service calls at the same time. Instead, introduce a reasonable interval between operations (e.g., **20 ms**) to ensure reliable stream state transitions.

 Following these timing control guidelines can significantly improve the stability of multi-camera systems during startup and runtime, reducing errors and unexpected behavior.
+### femto bolt depth stream no data
+
+This module depends on the OpenGL library at runtime. If OpenGL is not installed or the graphics driver is incomplete, the depth stream may output no data. Please make sure to install the necessary OpenGL libraries first (Ubuntu example below):
+
+```bash
+  sudo apt update && sudo apt install -y mesa-utils libgl1-mesa-glx libglu1-mesa
+```
+
+  After installation, you can check whether OpenGL is available through the following command:
+
+```bash
+  glxinfo -B
+```
@@ -0,0 +1,16 @@
+Camera Devices
+=======================================
+
+.. toctree::
+    :maxdepth: 3
+    :numbered:
+
+    1_overview/overview.rst
+    2_installation/installation.rst
+    3_quickstarts/quickstarts.rst
+    4_application_guide/application_guide.rst
+    5_advanced_guide/advanced_guide.rst
+    6_benchmark/benchmark.rst
+    7_developer_guide/developer_guide.rst
+    8_FAQ/FAQ.rst
+
@@ -0,0 +1,8 @@
+Lidar Devices
+=======================================
+
+.. toctree::
+    :maxdepth: 1
+    :numbered:
+
+    lidar.md
@@ -0,0 +1,208 @@
+This ROS2 driver supports your use of Orbbec single-line/multi-line LiDAR. This document provides installation instructions## 4. IMU Data
+
+## Installation
+
+### Prerequisites
+
+Before using the OrbbecSDK ROS2 LiDAR driver, please ensure that the following dependencies are installed on your system:
+
+- **ROS2**: A valid installation of ROS2 (Humble, Jazzy, or other supported distributions).
+  - If you need help, please refer to the [ROS2 Installation Guide](https://docs.ros.org/en/foxy/Installation.html).
+
+### Install deb Dependencies
+
+```bash
+# assume you have sourced ROS environment, same blow
+sudo apt install libgflags-dev nlohmann-json3-dev  \
+ros-$ROS_DISTRO-image-transport ros-${ROS_DISTRO}-image-transport-plugins ros-${ROS_DISTRO}-compressed-image-transport \
+ros-$ROS_DISTRO-image-publisher ros-$ROS_DISTRO-camera-info-manager \
+ros-$ROS_DISTRO-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs ros-$ROS_DISTRO-statistics-msgs \
+ros-$ROS_DISTRO-backward-ros libdw-dev
+```
+
+### Install udev Rules
+
+```bash
+cd  ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
+sudo bash install_udev_rules.sh
+sudo udevadm control --reload-rules && sudo udevadm trigger
+```
+
+### Build the Package
+
+```bash
+cd ~/ros2_ws/
+# Build release version, default is Debug
+colcon build --event-handlers  console_direct+  --cmake-args  -DCMAKE_BUILD_TYPE=Release
+```
+
+### Launch the LiDAR Node
+
+* First terminal
+
+```bash
+. ./install/setup.bash
+ros2 launch orbbec_camera lidar.launch.py
+```
+
+* Second terminal
+
+```bash
+. ./install/setup.bash
+rviz2
+```
+
+1. Open Rviz2.
+2. Add a `PointCloud2` or `LaserScan` display.
+3. For `PointCloud2`, select the `/lidar/cloud/points` topic; for `LaserScan`, select the `/lidar/scan/points` topic.
+4. Set the `Fixed Frame` to `lidar_lidar_frame` to properly align the data.
+
+* `PointCloud2` visualization example:
+
+![module in rviz2](./docs/images/lidar0.jpg)
+
+* `LaserScan` visualization example:
+
+![module in rviz2](./docs/images/lidar1.png)
+
+## Usage
+
+### Running the Driver
+
+To start the driver, launch the provided ROS2 launch file:
+
+```bash
+source install/setup.bash
+# Launch the driver with point cloud data
+ros2 launch orbbec_camera lidar.launch.py lidar_format:=LIDAR_POINT
+# Launch the driver with sphere point cloud data
+ros2 launch orbbec_camera lidar.launch.py lidar_format:=LIDAR_SPHERE_POINT
+# Launch the driver with laser scan data
+ros2 launch orbbec_camera lidar.launch.py lidar_format:=LIDAR_SCAN
+# Launch the driver with IMU enabled
+ros2 launch orbbec_camera lidar.launch.py enable_imu:=true imu_rate:=50hz
+# Launch the driver with both point cloud and IMU data
+ros2 launch orbbec_camera lidar.launch.py lidar_format:=LIDAR_POINT enable_imu:=true imu_rate:=100hz
+```
+
+This command will start the node that interfaces with the Orbbec LiDAR device. Please ensure that the LiDAR hardware is properly connected before running this command.
+
+### Get Device Information for Connected LiDARs
+
+```bash
+ros2 run orbbec_camera list_devices_node
+```
+
+This command will list the connected LiDAR devices and display their respective IP addresses and ports. You can use this information to configure the driver to connect to specific devices.
+
+### Check Which Configurations the LiDAR Supports
+
+```bash
+ros2 run orbbec_camera list_camera_profile_mode_node
+```
+
+### Parameters and Configuration
+
+The `lidar.launch.py` file contains default parameters for the driver. You can customize these settings by modifying the launch file or creating a custom configuration file. Key parameters include:
+
+- **device_type**: The type of device to launch. Optional values: `lidar`, `camera`. Setting this parameter to `lidar` launches the LiDAR device, setting it to `camera` launches the camera device.
+- **camera_name**: Launch node namespace.
+- **device_num**: Number of devices. This must be filled if you need to launch multiple devices.
+- **upgrade_firmware**: Firmware upgrade function. The input parameter is the firmware path.
+- **connection_delay**: Delay time (in milliseconds) for reopening the device. Immediately reopening the device during hot-plugging may cause firmware crashes.
+- **publish_tf**: Enable TF publishing.
+- **tf_publish_rate**: TF publishing frequency.
+- **lidar_format**: Data format for the LiDAR. Optional values: `LIDAR_POINT`, `LIDAR_SPHERE_POINT`, `LIDAR_SCAN`
+- **lidar_rate**: Scan rate of the LiDAR.
+- **publish_n_pkts**: Number of frames to accumulate before publishing merged point cloud. Range: 1-12000. Only effective when lidar_format is `LIDAR_POINT` or `LIDAR_SPHERE_POINT`, used to merge specified number of frames before publishing. Default value: `1`
+- **enable_scan_to_point**: Enable conversion of scan data to point cloud data, publishing PointCloud2 data type topics.
+- **repetitive_scan_mode**: Repetitive scan mode parameter.
+- **filter_level**: Add filter level parameter.
+- **vertical_fov**: Vertical angle parameter.
+- **min_angle**: Minimum angle of the LiDAR scan range in degrees (e.g., `-135.0`). Default value: `-135.0`.
+- **max_angle**: Maximum angle of the LiDAR scan range in degrees (e.g., `135.0`). Default value: `135.0`.
+- **min_range**: Minimum distance the LiDAR can measure in meters. Default value: `0.05`.
+- **max_range**: Maximum distance the LiDAR can measure in meters. Default value: `30.0`.
+- **echo_mode**: Echo mode of the LiDAR. Optional values: `Last Echo`, `First Echo`
+- **point_cloud_qos**: ROS 2 message Quality of Service (QoS) settings. Possible values include `SYSTEM_DEFAULT`, `DEFAULT`, `PARAMETER_EVENTS`, `SERVICES_DEFAULT`, `PARAMETERS`, and `SENSOR_DATA`, and are case-insensitive. These values correspond to `rmw_qos_profile_system_default`, `rmw_qos_profile_default`, `rmw_qos_profile_parameter_events`, `rmw_qos_profile_services_default`, `rmw_qos_profile_parameters`, and `SENSOR_DATA` respectively.
+- **enumerate_net_device**: Enable automatic enumeration of network devices.
+- **net_device_ip**: IP address of the network device.
+- **net_device_port**: Port number on the network side.
+- **log_level**: SDK log level, default value is `none`, optional values are `debug`, `info`, `warn`, `error`, `fatal`
+- **time_domain**: Timestamp type of the device. Optional values are `device`, `global`, `system`
+- **config_file_path**: Path to the YAML configuration file. Default value is "". If no configuration file is specified, default parameters from the launch file will be used.
+- **enable_heartbeat**: Enable heartbeat function, default is `false`. If set to `true`, the camera node will send heartbeat signals to the firmware; this should also be set to `true` if hardware logging is required.
+- **enable_imu**: Enable IMU (accelerometer + gyroscope) and output unified IMU topic data.
+- **imu_rate**: Unified frequency of the IMU (both accelerometer and gyroscope).
+- **accel_range**: Range of the accelerometer.
+- **gyro_range**: Range of the gyroscope.
+- **linear_accel_cov**: Linear acceleration covariance value, default is `0.0001`.
+- **angular_vel_cov**: Angular velocity covariance value, default is `0.0001`.
+
+## Point Cloud Data Details
+
+### Point Cloud Format
+
+PointCloud2 (PointXYZITO) point cloud format is as follows:
+
+```
+float32 x               # X axis, unit: meters
+float32 y               # Y axis, unit: meters
+float32 z               # Z axis, unit: meters
+uint8   intensity       # LiDAR intensity
+uint8   tag             # LiDAR tag
+uint32  offset_time     # Point cloud offset relative to topic time, unit nanoseconds
+```
+
+### Point Cloud Aggregation Functionality
+
+The `publish_n_pkts` parameter enables point cloud aggregation functionality, which allows the LiDAR to accumulate a specified number of frames before publishing, then merge these frames into a larger point cloud data package for publishing.
+
+#### Features:
+
+- **Parameter Range**: 1-12000 frames
+- **Applicable Formats**: Only effective when lidar format is `LIDAR_POINT` or `LIDAR_SPHERE_POINT`
+- **Default Value**: 1 (no aggregation, each frame published individually)
+- **Purpose**: Improve point cloud density, suitable for applications requiring denser point cloud data
+
+#### Usage Examples:
+
+```bash
+# Aggregate 10 frames before publishing
+ros2 launch orbbec_camera lidar.launch.py lidar_format:=LIDAR_POINT publish_n_pkts:=10
+
+# Aggregate 100 frames before publishing
+ros2 launch orbbec_camera lidar.launch.py lidar_format:=LIDAR_SPHERE_POINT publish_n_pkts:=100
+```
+
+**Note**: Increasing the `publish_n_pkts` value will improve point cloud density but will also increase latency and memory usage. Please adjust according to actual application requirements.
+
+## IMU Data
+
+### IMU Topics
+
+When IMU is enabled, the following topics will be published:
+
+- **`/lidar/imu/sample`**: Unified IMU topic containing synchronized accelerometer and gyroscope data in `sensor_msgs/Imu` format.
+- **`/lidar/lidar_to_imu`**: Transform from LiDAR frame to IMU frame.
+
+### Using IMU Data
+
+To enable IMU data collection:
+
+```bash
+# Launch with IMU enabled
+ros2 launch orbbec_camera lidar.launch.py enable_imu:=true imu_rate:=50hz
+
+# Check IMU topics
+ros2 topic list | grep imu
+
+# View IMU data
+ros2 topic echo /lidar/imu/sample
+```
+
+The IMU data includes:
+
+- **linear_acceleration**: 3D acceleration data (x, y, z) in m/s²
+- **angular_velocity**: 3D angular velocity data (x, y, z) in rad/s
+- **orientation**: Quaternion orientation (not provided by hardware, set to zero)