From db5404d1febd2969dd64b2184272fc214549a1fd Mon Sep 17 00:00:00 2001 From: ob-yalian Date: Mon, 28 Sep 2026 17:46:08 +0800 Subject: [PATCH] docs: update example READMEs for clarity and consistency, add usage guides in multiple languages --- orbbec_camera/examples/README.MD | 24 ++--- orbbec_camera/examples/ae_awb_lock/README.md | 46 ++------- .../examples/gige_action_command/README.md | 94 ++----------------- .../examples/gmsl_multi_camera_sync/README.md | 22 ++--- .../multi_camera_shared_container/README.md | 29 ++---- 5 files changed, 47 insertions(+), 168 deletions(-) diff --git a/orbbec_camera/examples/README.MD b/orbbec_camera/examples/README.MD index 424a3418..118ed5e0 100644 --- a/orbbec_camera/examples/README.MD +++ b/orbbec_camera/examples/README.MD @@ -1,20 +1,22 @@ # OrbbecSDK ROS2 Examples -This directory contains practical launch and tool examples. Full usage, -configuration, and troubleshooting are maintained on the official documentation -site so that instructions have a single source of truth. +This directory contains practical launch and tool examples. Most example READMEs +contain local setup and run commands; their full usage, configuration, and +troubleshooting are maintained on the official documentation site. The Gemini +435Le example keeps its complete instructions next to its source code. For command-line maintenance and diagnostic utilities, see the official [Tool Index](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/6_benchmark/tools.html). ## Example Index -| Source | Purpose | Experience Level | Official Guide | +| Source | Purpose | Experience Level | Usage Guide | | :---: | --- | :---: | --- | -| [Multi-camera network](./multi_net_camera) | Launch multiple supported Orbbec network cameras. | ⭐️ | [Network camera guide](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/configuration/net_camera.html) | -| [GigE Action Command](./gige_action_command) | Configure and trigger a Gemini 335Le camera group over GVCP. | ⭐️⭐️ | [README](./gige_action_command/README.md) | -| [GMSL camera](./gmsl_multi_camera_sync) | Synchronize two GMSL-connected Gemini 330 Series cameras. | ⭐️⭐️ | [README](./gmsl_multi_camera_sync/README.md) | -| [Shared component container](./multi_camera_shared_container) | Load multiple Gemini 330 Series cameras into one component container. | ⭐️⭐️ | [README](./multi_camera_shared_container/README.md) | -| [AE/AWB lock test](./ae_awb_lock) | Verify AE/AWB convergence, frame-metadata capture, and manual lock-in through ROS 2. | ⭐️⭐️ | [README](./ae_awb_lock/README.md) | -| [Benchmark](./benchmark) | Benchmark the performance of different camera configurations. | ⭐️⭐️ | [Performance benchmark tools](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/6_benchmark/benchmark_tools.html) | -| [Multi-camera synchronization verification](./multi_camera_synced_verification_tool) | Verify synchronization accuracy across multiple cameras. | ⭐️⭐️⭐️ | [Synchronization verification guide](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/multi_camera_synced_verification_tool.html) | +| [Multi-camera network](./multi_net_camera) | Launch multiple supported Orbbec network cameras. | ⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/configuration/net_camera.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/configuration/net_camera.html) | +| [GigE Action Command](./gige_action_command) | Configure and trigger a Gemini 335Le camera group over GVCP. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.html) | +| [GMSL camera](./gmsl_multi_camera_sync) | Synchronize two GMSL-connected Gemini 330 Series cameras. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.html) | +| [Shared component container](./multi_camera_shared_container) | Load multiple Gemini 330 Series cameras into one component container. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.html) | +| [AE/AWB lock test](./ae_awb_lock) | Verify AE/AWB convergence, frame-metadata capture, and manual lock-in through ROS 2. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/4_application_guide/examples/ae_awb_lock.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/4_application_guide/examples/ae_awb_lock.html) | +| [Gemini 435Le example node](./Gemini_435Le_example_node) | Try camera services and inspect device status through an interactive menu. | ⭐️⭐️ | [Example README](./Gemini_435Le_example_node/README.MD) | +| [Benchmark](./benchmark) | Benchmark the performance of different camera configurations. | ⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/6_benchmark/benchmark_tools.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/6_benchmark/benchmark_tools.html) | +| [Multi-camera synchronization verification](./multi_camera_synced_verification_tool) | Verify synchronization accuracy across multiple cameras. | ⭐️⭐️⭐️ | [EN](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/multi_camera_synced_verification_tool.html) / [中文](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/multi_camera_synced_verification_tool.html) | diff --git a/orbbec_camera/examples/ae_awb_lock/README.md b/orbbec_camera/examples/ae_awb_lock/README.md index 2812a166..57b392e7 100644 --- a/orbbec_camera/examples/ae_awb_lock/README.md +++ b/orbbec_camera/examples/ae_awb_lock/README.md @@ -1,46 +1,20 @@ # AE/AWB Lock Test -This sample exposes a test-only ROS 2 action that verifies the AE/AWB capture and manual -lock-in flow through the camera driver's services and color-frame metadata. +This test-only ROS 2 action checks the AE/AWB capture and manual lock-in flow through the camera driver's services and color-frame metadata. -Run the camera driver and this sample in the same namespace: +## Before running + +Start the camera driver with the color stream enabled. The sample must run in the same namespace as the driver, and `color/metadata` must be available. + +## Run ```bash ros2 run orbbec_camera ae_awb_lock_test_node --ros-args -r __ns:=/camera -``` - -Send a goal and print feedback: - -```bash -ros2 action send_goal \ - /camera/run_ae_awb_lock_test \ +ros2 action send_goal /camera/run_ae_awb_lock_test \ orbbec_camera_msgs/action/RunAeAwbLockTest \ - "{timeout_ms: 10000}" \ - --feedback + "{timeout_ms: 10000}" --feedback ``` -The sample subscribes to the relative `color/metadata` topic. It enables auto exposure and auto -white balance, waits until the SDK status equals `1`, captures exposure, color gain, and color -temperature from the latest color-frame metadata, and reads AWB R/B/G gains through the structured -property service. It then disables the auto controls and writes the captured values back in this -order: +## Full guide -1. Color exposure -2. Color gain -3. AWB R/B/G gains -4. Color temperature - -The final AWB gain readback must exactly match the captured value. Other readback differences are -reported as warnings because the device may quantize those controls. On failure or cancellation, -the sample restores auto exposure and auto white balance. - -Every feedback phase contains a fresh status value read from the camera service. The -`waiting_for_services` feedback is published after all required services become available, because -the status cannot be read before its service is ready. - -The color stream must be enabled, and `/camera/color/metadata` must be available when using the -`/camera` namespace. The action fails instead of writing default values if no metadata arrives -before the goal timeout or if `exposure`, `gain`, or `white_balance` is missing. The goal timeout -covers the main workflow, including service discovery, service calls, convergence, capture, -writeback, and verification. Restoring auto exposure and auto white balance after a failure uses a -separate best-effort timeout. +[AE/AWB lock test (English)](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/4_application_guide/examples/ae_awb_lock.html) · [中文指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/4_application_guide/examples/ae_awb_lock.html) diff --git a/orbbec_camera/examples/gige_action_command/README.md b/orbbec_camera/examples/gige_action_command/README.md index 1526c9de..2883f016 100644 --- a/orbbec_camera/examples/gige_action_command/README.md +++ b/orbbec_camera/examples/gige_action_command/README.md @@ -1,99 +1,17 @@ # GigE Action Command -This example starts two Gemini 335Le cameras in Group Actions synchronization mode and one -host-side Action Command sender. The sender is intentionally created once at the top level because -a GVCP Action Command can trigger multiple cameras. +This example starts two Gemini 335Le cameras in Group Actions synchronization mode and one host-side Action Command sender. -## Requirements +## Before running -- Gemini 335Le firmware 1.8.24 or later -- Orbbec SDK 2.10.2 or later -- Both cameras and the host on the same network +Use Gemini 335Le firmware 1.8.24 or later and Orbbec SDK 2.10.2 or later. Connect both cameras and the host to the same network, then set the two `net_device_ip` values in `multi_gige_action_command.launch.py` to the camera IP addresses. -Before running the example, change the two `net_device_ip` values in -`multi_gige_action_command.launch.py` to match the cameras. - -## Start the cameras and sender +## Run ```bash ros2 launch orbbec_camera multi_gige_action_command.launch.py ``` -The launch file creates these device-scoped configuration services and one network-scoped sender: +## Full guide -```text -/camera_01/get_action_config -/camera_01/set_action_config -/camera_02/get_action_config -/camera_02/set_action_config -/gige_action_command_node/send_action_command -``` - -## Configure the cameras - -Configure Action Signal block 0 on both cameras with matching keys and masks: - -```bash -ros2 service call /camera_01/set_action_config \ - orbbec_camera_msgs/srv/SetActionConfig \ - "{device_key: 1, selector: 0, group_key: 1, group_mask: 1}" - -ros2 service call /camera_02/set_action_config \ - orbbec_camera_msgs/srv/SetActionConfig \ - "{device_key: 1, selector: 0, group_key: 1, group_mask: 1}" -``` - -Read the configuration back when needed: - -```bash -ros2 service call /camera_01/get_action_config \ - orbbec_camera_msgs/srv/GetActionConfig \ - "{selector: 0}" -``` - -## Trigger the group - -The service exposes three trigger modes. Every camera whose device key, group key, and group mask -match the request will be triggered. - -### Immediate trigger - -Set `trigger_mode` to `0`. The delay and scheduled time fields must be zero: - -```bash -ros2 service call /gige_action_command_node/send_action_command \ - orbbec_camera_msgs/srv/SendActionCommand \ - "{device_key: 1, group_key: 1, group_mask: 1, broadcast_ip: '255.255.255.255', trigger_mode: 0, delay_ms: 0, scheduled_time: 0}" -``` - -### Relative-delay trigger - -Set `trigger_mode` to `1` and provide a positive delay in milliseconds. The node reads the host -system clock, adds the delay, and converts the result to the absolute GVCP/PTP timestamp expected by -the SDK. This example schedules the command one second in the future: - -```bash -ros2 service call /gige_action_command_node/send_action_command \ - orbbec_camera_msgs/srv/SendActionCommand \ - "{device_key: 1, group_key: 1, group_mask: 1, broadcast_ip: '255.255.255.255', trigger_mode: 1, delay_ms: 1000, scheduled_time: 0}" -``` - -The host `CLOCK_REALTIME` must be synchronized to the same PTP domain as the cameras, for example -by using `phc2sys`. The launch file enables camera PTP synchronization, but it does not configure -the host PTP services. Choose a delay long enough for the command to reach the cameras before its -target time. - -### Absolute PTP-time trigger - -Set `trigger_mode` to `2`, leave `delay_ms` at zero, and provide a future encoded PTP timestamp. The -upper 32 bits contain seconds and the lower 32 bits contain nanoseconds: - -```bash -ros2 service call /gige_action_command_node/send_action_command \ - orbbec_camera_msgs/srv/SendActionCommand \ - "{device_key: 1, group_key: 1, group_mask: 1, broadcast_ip: '255.255.255.255', trigger_mode: 2, delay_ms: 0, scheduled_time: }" -``` - -The response returns `encoded_scheduled_time`, the exact 64-bit value sent to the SDK. For delayed -triggering this is the timestamp calculated by the node. `success: true` means the host dispatched -the GVCP command; the protocol does not return a device acknowledgment. +[GigE Action Command (English)](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.html) · [中文指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/gige_action_command.html) diff --git a/orbbec_camera/examples/gmsl_multi_camera_sync/README.md b/orbbec_camera/examples/gmsl_multi_camera_sync/README.md index 33bb4b8f..ad426fae 100644 --- a/orbbec_camera/examples/gmsl_multi_camera_sync/README.md +++ b/orbbec_camera/examples/gmsl_multi_camera_sync/README.md @@ -1,22 +1,18 @@ # GMSL Multi-Camera Synchronization -This example starts two GMSL-connected Gemini 330 Series cameras in hardware synchronization -mode. It uses the package's standard `gemini_330_series.launch.py` file. +This example synchronizes two GMSL-connected Gemini 330 Series cameras using the standard `gemini_330_series.launch.py` file. -Before starting the cameras, grant access to the camera synchronization device: +## Before running + +Grant access to `/dev/camsync` and update the `usb_port` values in `multi_gmsl_camera_synced.launch.py` to match your GMSL links. The default ports are `gmsl2-1` and `gmsl2-3`. + +## Run ```bash sudo chmod 777 /dev/camsync -``` - -Before starting the example, update the `usb_port` values in -`multi_gmsl_camera_synced.launch.py` if your system reports different GMSL links. The default -values are `gmsl2-1` and `gmsl2-3`. - -```bash ros2 launch orbbec_camera multi_gmsl_camera_synced.launch.py ``` -Both cameras use `secondary_synced` mode. `camera_01` enables the host-side GMSL trigger at -30 fps (`gmsl_trigger_fps=3000`), while `camera_02` receives the same trigger. The receiving -camera is started first, followed by the trigger-generating camera after two seconds. +## Full guide + +[GMSL multi-camera synchronization (English)](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.html) · [中文指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.html) diff --git a/orbbec_camera/examples/multi_camera_shared_container/README.md b/orbbec_camera/examples/multi_camera_shared_container/README.md index 857d0964..42aa1e48 100644 --- a/orbbec_camera/examples/multi_camera_shared_container/README.md +++ b/orbbec_camera/examples/multi_camera_shared_container/README.md @@ -1,28 +1,17 @@ -# Attach Cameras to a Shared Component Container +# Shared Component Container -This example shows how to load two Gemini 330 Series camera components into one externally -created ROS 2 component container. +This example loads two Gemini 330 Series camera components into one ROS 2 component container. -Before starting the example, update the `usb_port` values in -`multi_camera_shared_container.launch.py` to match your two cameras. The default values are -`2-1` and `2-2`. +## Before running + +Update both `usb_port` values in `multi_camera_shared_container.launch.py` to match your cameras. The defaults are `2-1` and `2-2`. Give each camera a unique `camera_name`. + +## Run ```bash ros2 launch orbbec_camera multi_camera_shared_container.launch.py ``` -The example performs three steps: +## Full guide -1. Starts one multithreaded component container named `shared_orbbec_container`. -2. Includes the example-specific `gemini_330_series_shared_container.launch.py` once for each - camera. -3. Passes `attach_to_shared_component_container=true` and the same - `component_container_name` to both includes, so neither include creates its own container. - -`use_intra_process_comms=true` enables intra-process communication for the loaded camera -components. Keep every `camera_name` unique, and make sure the shared container is running -before a camera component is loaded. - -The package's main `launch/gemini_330_series.launch.py` is not modified by this example. The -example-specific launcher mirrors its Gemini 330 Series parameters and adds only the component -container selection controls needed for this demonstration. +[Efficient intra-process communication (English)](https://orbbec.github.io/OrbbecSDK_ROS2/en/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.html) · [中文指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/performance/efficient_intra_process_communication.html)