Add Chinese documentation for camera and lidar devices

2026-10-04 12:07:46 +08:00 · 2025-12-31 17:42:46 +08:00
parent c59af3d328
commit fd13aba31f
172 changed files with 466 additions and 8 deletions
@@ -0,0 +1,12 @@
+Benchmark
+======================================================
+
+This chapter introduces how to use the benchmark tool and provides test results for different cameras.
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction.md
+    benchmark_usage.md
+    benchmark_data.md
+    othertools.md
@@ -0,0 +1,19 @@
+# Benchmark Data
+
+This section records the data of using the benchmark tool to test different cameras. Click the link to download the xlsx data.
+
+
+## Common Benckmark Data
+
+Use the default launch file to run the `common_benchmark_node` and test for 1 hour of data.
+
+- [Common Benchmark Data](../../_static/ros2_common_benchmark_data.xlsx)
+
+
+## Service Benchmark Data
+
+Use the default launch file to run the `service_benchmark_node` and `service_benchmark_node.py` separately. Each service is called 10 times, and the data is recorded.
+
+- [Service Benchmark Data cpp](../../_static/ros2_service_benchmark_cpp.xlsx)
+- [Service Benchmark Data python](../../_static/ros2_service_benchmark_python.xlsx)
+
@@ -0,0 +1,119 @@
+# Benchmark Usage
+
+This section introduces how to use the benchmark tool in C++ and Python, and provides an example YAML configuration file.
+
+## Using common benchmark node
+
+```
+ros2 run orbbec_camera common_benchmark_node.py \
+    --run_time 2h  \
+    --csv_file /path/to/log.csv
+```
+
+
+
+* **Parameters**
+  * **--run_time**: Duration for monitoring, specified as time strings like `"10s"`, `"5m"`, `"1h"`, `"2d"`. Default is 10 seconds.
+  *  **--csv_file**: Path to the output CSV file. By default, it is saved in the workspace directory with the name "camera_monitor_log.csv".
+
+## Using service benchmark node
+
+### ROS2 C++
+
+* **Single service benchmark**
+
+```
+ros2 run orbbec_camera service_benchmark_node \
+    --ros-args \
+    -p service_name:=/camera/get_depth_gain \
+    -p service_type:=orbbec_camera_msgs/srv/GetInt32 \
+    -p count:=10
+```
+
+* ****Multiple services benchmark (YAML config)****
+
+```
+ros2 run orbbec_camera service_benchmark_node \
+    --ros-args \
+    -p yaml_file:=/path/to/default_service_cpp.yaml
+```
+
+### ROS2 Python
+
+* **Single service benchmark**
+
+```
+ros2 run orbbec_camera service_benchmark_node.py --service /camera/get_depth_gain --count 10
+```
+
+* ****Multiple services benchmark (YAML config)****
+
+```
+ros2 run orbbec_camera service_benchmark_node.py --yaml_file /path/to/default_service.yaml
+```
+
+
+
+### **Example YAML configuration**
+
+We provide an example YAML configuration, located in the `scripts` directory as `service_default.yaml`.
+
+```yaml
+default_count: 50
+
+services:
+- name: /camera/get_auto_white_balance
+  type: orbbec_camera_msgs/srv/GetInt32
+- name: /camera/get_color_exposure
+  type: orbbec_camera_msgs/srv/GetInt32
+- name: /camera/get_color_gain
+  type: orbbec_camera_msgs/srv/GetInt32
+- name: /camera/get_depth_exposure
+  type: orbbec_camera_msgs/srv/GetInt32
+- name: /camera/get_depth_gain
+  type: orbbec_camera_msgs/srv/GetInt32
+- name: /camera/get_device_info
+  type: orbbec_camera_msgs/srv/GetDeviceInfo
+- name: /camera/send_software_trigger
+  type: std_srvs/srv/SetBool
+  request: {data: false}
+- name: /camera/set_auto_white_balance
+  type: std_srvs/srv/SetBool
+  request: {data: false}
+- name: /camera/set_color_ae_roi
+  type: orbbec_camera_msgs/srv/SetArrays
+  request: {data_param: [0,1279,0,719]}
+- name: /camera/set_color_auto_exposure
+  type: std_srvs/srv/SetBool
+  request: {data: false}
+- name: /camera/set_color_exposure
+  type: orbbec_camera_msgs/srv/SetInt32
+  request: {data: 30}
+- name: /camera/set_color_flip
+  type: std_srvs/srv/SetBool
+  request: {data: false}
+- name: /camera/set_color_gain
+  type: orbbec_camera_msgs/srv/SetInt32
+  request: {data: 20}
+- name: /camera/set_color_mirror
+  type: std_srvs/srv/SetBool
+  request: {data: false}
+- name: /camera/set_color_rotation
+  type: orbbec_camera_msgs/srv/SetInt32
+  request: {data: 90}
+- name: /camera/set_depth_ae_roi
+  type: orbbec_camera_msgs/srv/SetArrays
+  request: {data_param: [0,1279,0,719]}
+- name: /camera/set_depth_auto_exposure
+  type: std_srvs/srv/SetBool
+  request: {data: false}
+- name: /camera/set_depth_exposure
+  type: orbbec_camera_msgs/srv/SetInt32
+  request: {data: 3000}
+- name: /camera/set_depth_flip
+  type: std_srvs/srv/SetBool
+  request: {data: false}
+- name: /camera/set_depth_gain
+  type: orbbec_camera_msgs/srv/SetInt32
+  request: {data: 200}
+```
@@ -0,0 +1,45 @@
+# Introduction
+
+This section introduces the benchmark tool, explaining its purpose, features, and what it can help you measure.
+
+## common benchmark node
+
+`common_benchmark_node.py` is a tool for monitoring the performance of Orbbec cameras running in a ROS environment. It collects and records key camera metrics such as frame rate, latency, system resource usage, and packet loss rate in real time, helping users evaluate the stability and performance of camera nodes (updated once per second).
+
+**Features**
+
+- Measure published image frame rate and latency (current, min, max, average)
+
+- Monitor the camera node's CPU/ARM usage (current, min, max, average)
+
+- Track frame drop rate (publisher) and packet loss rate (subscriber)
+
+- Print real-time statistics (1 Hz) to the terminal and save results to a CSV file
+
+- Support configurable runtime duration and CSV output path
+
+**Example**
+
+In ROS1, both frame drop rate and packet loss rate can be measured, while in ROS2, the header lacks the `seq` field, so only the publisher-side frame drop rate is calculated.
+
+![common_benchmark_ros1](../image/benchmark_images/common_benchmark_ros1.png "ROS1")
+
+![common_benchmark_ros2](../image/benchmark_images/common_benchmark_ros2.png "ROS2")
+
+## service benchmark node
+
+The `service_benchmark_node` tool is used to monitor the performance of service calls. It can measure the success rate of service calls and the time required to execute service.
+
+**Features**
+
+- Benchmark a single service call, measuring latency and success rate
+
+- Benchmark multiple services as defined in a YAML configuration file
+
+- Optionally save benchmark results to a CSV file
+
+**Example**
+
+![service benchmark](../image/benchmark_images/service_benchmark.png)
+
+When you need to collect data for multiple services, it is recommended to use a CSV file for analysis.
@@ -0,0 +1,52 @@
+# Other Tools
+
+## Ob_benchmark tool
+
+> The goal of this tool is to benchmark the performance of various OrbbecSDK_ROS2 camera configurations. The benchmark results depend on the camera and settings used.(Currently only works with ROS2 Humble)
+
+You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
+
+### Tool Configuration ([start_benchmark_params.json](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v2-main/orbbec_camera/config/tools/startbenchmark/start_benchmark_params.json))
+
+```json
+{
+    "start_benchmark_params": {
+        "camera_name": [
+            "camera_01",
+            "camera_02",
+            "camera_03",
+            "camera_04"
+        ],
+        "process_name": "component_conta",
+        "switch_cycle": 300,
+        "test_cycle": 1,
+        "skip_number": 30
+    }
+}
+```
+
+- `camera_name`: Names of the cameras to be configured. Example: `"camera_01"`, `"camera_02"`, etc.
+- `process_name`: The name of the process to be monitored. For example, `"component_conta"` will monitor the data of the container process.
+- `switch_cycle`: The cycle time for switching configurations, in seconds. For example, setting it to `300` means the configuration will switch every 300 seconds.
+- `test_cycle`: The testing cycle, in seconds. For example, setting it to `1` means the tool will collect data for the monitored process every 1 second.
+- `skip_number`: The number of data points to skip. For example, setting it to `30` means that the first 30 data points will be ignored.
+
+### Camera configuration (launch files)
+
+In the launch folder, there are multiple.launch.py files (`ob_benchmark_0.launch.py`, `ob_benchmark_1.launch.py`, ..., `ob_benchmark_19.launch.py`). Each file corresponds to a different camera configuration.
+
+### Running the ob_benchmark tool
+
+To run the tool, use the following commands:
+
+```bash
+source install/setup.bash
+ros2 run orbbec_camera ob_benchmark_node
+```
+
+### Output Data Files
+
+The output data files will be stored in the ob_benchmark folder with filenames like `0.csv`, `1.csv`, ..., 19.csv. For example:
+
+- `0.csv` contains data from the `ob_benchmark_0.launch.py` configuration.
+- `1.csv` contains data from the `ob_benchmark_1.launch.py` configuration.