mirror of
https://github.com/orbbec/OrbbecSDK_ROS2.git
synced 2026-09-13 19:40:19 +08:00
docs: enhance compressed image documentation with launch parameters and troubleshooting tips
This commit is contained in:
ob-yalian
@@ -1,11 +1,77 @@
|
||||
### Compressed Image
|
||||
|
||||
You can use `image_transport` to compress the image using `jpeg`. Below is an example of how to use it:
|
||||
OrbbecSDK ROS2 supports publishing compressed image topics through `image_transport`. This is useful for reducing network bandwidth, viewing images remotely, and subscribing to the compressed color image directly when `color_format:=MJPG` is used to reduce host-side decoding overhead.
|
||||
|
||||
To access the compressed color image, you can use the following command:
|
||||
## Related Launch Parameters
|
||||
|
||||
Compressed image publishing is controlled by the following launch parameters:
|
||||
|
||||
| Parameter | Default Value | Description |
|
||||
| --- | --- | --- |
|
||||
| `color.image_raw.enable_pub_plugins` | `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]` | Color image publishing plugins. |
|
||||
| `depth.image_raw.enable_pub_plugins` | `["image_transport/compressedDepth", "image_transport/raw"]` | Depth image publishing plugins. |
|
||||
| `left_ir.image_raw.enable_pub_plugins` | `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]` | Left IR image publishing plugins. |
|
||||
| `right_ir.image_raw.enable_pub_plugins` | `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]` | Right IR image publishing plugins. |
|
||||
|
||||
If you only need compressed color images, keep the `compressed` and `raw` plugins in the launch command, for example:
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_330_series.launch.py \
|
||||
color.image_raw.enable_pub_plugins:='["image_transport/compressed", "image_transport/raw"]'
|
||||
```
|
||||
|
||||
If you only need raw images, keep only the `raw` plugin, for example:
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_330_series.launch.py \
|
||||
color.image_raw.enable_pub_plugins:='["image_transport/raw"]'
|
||||
```
|
||||
|
||||
## Common Compressed Image Topics
|
||||
|
||||
The default camera namespace is `/camera`. If you change `camera_name` when launching the camera, replace `/camera` in the following topics with the actual namespace.
|
||||
|
||||
| Stream | Compressed Image Topic |
|
||||
| --- | --- |
|
||||
| Color image | `/camera/color/image_raw/compressed` |
|
||||
| Depth image | `/camera/depth/image_raw/compressedDepth` |
|
||||
| Left IR image | `/camera/left_ir/image_raw/compressed` |
|
||||
| Right IR image | `/camera/right_ir/image_raw/compressed` |
|
||||
|
||||
View compressed color image messages:
|
||||
|
||||
```bash
|
||||
ros2 topic echo /camera/color/image_raw/compressed --no-arr
|
||||
```
|
||||
|
||||
This command will allow you to receive the compressed color image from the specified topic.
|
||||
View compressed depth image messages:
|
||||
|
||||
```bash
|
||||
ros2 topic echo /camera/depth/image_raw/compressedDepth --no-arr
|
||||
```
|
||||
|
||||
## `color_format:=MJPG` Scenario
|
||||
|
||||
When the color stream uses `color_format:=MJPG`, the ROS wrapper directly publishes `/camera/color/image_raw/compressed`. Subscribing to this topic avoids extra host-side MJPG decoding and usually reduces CPU usage.
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_330_series.launch.py color_format:=MJPG
|
||||
```
|
||||
|
||||
In this case, subscribe to:
|
||||
|
||||
```bash
|
||||
ros2 topic echo /camera/color/image_raw/compressed --no-arr
|
||||
```
|
||||
|
||||
If you subscribe to `/camera/color/image_raw`, the MJPG image still needs to be decoded on the host, which increases CPU usage. For more low-CPU configuration suggestions, see [Reducing CPU Usage](../5_advanced_guide/performance/lower_cpu_usage.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you do not see compressed image topics, check the topic list first:
|
||||
|
||||
```bash
|
||||
ros2 topic list | grep image_raw
|
||||
```
|
||||
|
||||
Then confirm that the corresponding `*.image_raw.enable_pub_plugins` parameter has not been changed to enable only `raw`, and make sure the related `image_transport` plugins are installed.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
## Reducing CPU Usage with Orbbec ROS Package
|
||||
|
||||
You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
|
||||
You can refer to the low-CPU launch configuration in [gemini_330_series_low_cpu.launch.py](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v2-main/orbbec_camera/launch/gemini_330_series_low_cpu.launch.py).
|
||||
|
||||
This document outlines strategies for minimizing CPU usage in the **OrbbecSDK_ROS2 v2** environment when using **Gemini 330 series cameras**. The firmware version must be **no lower than 1.4.10**, and `device` should be set to **Default**.
|
||||
|
||||
|
||||
@@ -1,11 +1,77 @@
|
||||
### 压缩图像
|
||||
|
||||
您可以使用 `image_transport` 通过 `jpeg` 压缩图像。以下是使用示例：
|
||||
OrbbecSDK ROS2 支持通过 `image_transport` 发布压缩图像话题。常用场景包括降低网络传输带宽、远程查看图像，以及在 `color_format:=MJPG` 时直接订阅压缩彩色图像以降低主机端解码开销。
|
||||
|
||||
要访问压缩的彩色图像，可以使用以下命令：
|
||||
## 相关启动参数
|
||||
|
||||
压缩图像由以下 launch 参数控制：
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `color.image_raw.enable_pub_plugins` | `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]` | 彩色图像发布插件。 |
|
||||
| `depth.image_raw.enable_pub_plugins` | `["image_transport/compressedDepth", "image_transport/raw"]` | 深度图像发布插件。 |
|
||||
| `left_ir.image_raw.enable_pub_plugins` | `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]` | 左红外图像发布插件。 |
|
||||
| `right_ir.image_raw.enable_pub_plugins` | `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]` | 右红外图像发布插件。 |
|
||||
|
||||
如果只需要压缩彩色图像，可以在启动命令中保留 `compressed` 和 `raw` 插件，例如：
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_330_series.launch.py \
|
||||
color.image_raw.enable_pub_plugins:='["image_transport/compressed", "image_transport/raw"]'
|
||||
```
|
||||
|
||||
如果只需要原始图像，可以只保留 `raw` 插件，例如：
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_330_series.launch.py \
|
||||
color.image_raw.enable_pub_plugins:='["image_transport/raw"]'
|
||||
```
|
||||
|
||||
## 常用压缩图像话题
|
||||
|
||||
默认相机命名空间为 `/camera`。如果启动时修改了 `camera_name`，请将下面话题中的 `/camera` 替换为实际命名空间。
|
||||
|
||||
| 数据流 | 压缩图像话题 |
|
||||
| --- | --- |
|
||||
| 彩色图像 | `/camera/color/image_raw/compressed` |
|
||||
| 深度图像 | `/camera/depth/image_raw/compressedDepth` |
|
||||
| 左红外图像 | `/camera/left_ir/image_raw/compressed` |
|
||||
| 右红外图像 | `/camera/right_ir/image_raw/compressed` |
|
||||
|
||||
查看压缩彩色图像消息：
|
||||
|
||||
```bash
|
||||
ros2 topic echo /camera/color/image_raw/compressed --no-arr
|
||||
```
|
||||
|
||||
此命令将允许您从指定话题接收压缩的彩色图像。
|
||||
查看压缩深度图像消息：
|
||||
|
||||
```bash
|
||||
ros2 topic echo /camera/depth/image_raw/compressedDepth --no-arr
|
||||
```
|
||||
|
||||
## `color_format:=MJPG` 场景
|
||||
|
||||
当彩色流使用 `color_format:=MJPG` 时，ROS wrapper 会直接发布 `/camera/color/image_raw/compressed`，订阅该话题可以避免在主机侧额外解码 MJPG 图像，通常能降低 CPU 占用。
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_330_series.launch.py color_format:=MJPG
|
||||
```
|
||||
|
||||
此时建议订阅：
|
||||
|
||||
```bash
|
||||
ros2 topic echo /camera/color/image_raw/compressed --no-arr
|
||||
```
|
||||
|
||||
如果订阅 `/camera/color/image_raw`，MJPG 图像仍需要在主机侧解码，CPU 占用会更高。更多低 CPU 配置建议请参考 [降低 CPU 使用率](../5_advanced_guide/performance/lower_cpu_usage.md)。
|
||||
|
||||
## 排查方法
|
||||
|
||||
如果没有看到压缩图像话题，请先检查话题列表：
|
||||
|
||||
```bash
|
||||
ros2 topic list | grep image_raw
|
||||
```
|
||||
|
||||
然后确认对应的 `*.image_raw.enable_pub_plugins` 参数没有被改为只启用 `raw`，并确认系统已安装 `image_transport` 相关插件。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
## 使用Orbbec ROS包降低CPU使用率
|
||||
|
||||
您可以在 [示例](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples) 中找到使用示例代码。
|
||||
您可以参考 [gemini_330_series_low_cpu.launch.py](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v2-main/orbbec_camera/launch/gemini_330_series_low_cpu.launch.py) 中的低 CPU 启动配置。
|
||||
|
||||
本文档概述了在使用 **Gemini 330系列相机** 的 **OrbbecSDK_ROS2 v2** 环境中最小化CPU使用率的策略。固件版本必须 **不低于1.4.10**，且 `device` 应设置为 **Default**。
|
||||
|
||||
@@ -13,20 +13,18 @@
|
||||
| `uvc_backend` | `v4l2` | 与 `libuvc` 相比CPU使用率更低 |
|
||||
| `color_format` | `RGB` | CPU使用率低于 `MJPG` |
|
||||
| `filter` | 仅使用 `hardware_noise_removal_filter` | 其他滤波器会显著增加CPU使用率 |
|
||||
| `depth_registration` | `false` 或 `true` 配合 `align_mode=HW` | 软件对齐消耗更多CPU |
|
||||
| `enable_point_cloud` | `false` | 禁用点云可降低CPU使用率 |
|
||||
| `enable_colored_point_cloud` | `false` | 禁用彩色点云可降低CPU使用率 |
|
||||
|
||||
### 彩色流格式与订阅方式
|
||||
|
||||
v2.8.8 优化了彩色流图像发布流程：
|
||||
|
||||
- 当 `color_format` 为 RGB/YUYV 等非 MJPG 格式时，订阅 `/camera/color/image_raw`。
|
||||
- 当 `color_format:=MJPG` 时，建议订阅 `/camera/color/image_raw/compressed`。ROS wrapper 会直接发布压缩图像，避免额外解码，从而显著降低 MJPG 场景下的 CPU 占用。
|
||||
- 当 `color_format:=MJPG` 时，建议订阅 `/camera/color/image_raw/compressed`。ROS wrapper 会直接发布压缩图像，避免额外解码，从而显著降低 MJPG 场景下的 CPU 占用，甚至低于 RGB 格式。
|
||||
- 如果订阅 `/camera/color/image_raw`，MJPG 仍需要在主机侧解码，CPU 占用会更高。
|
||||
|
||||
### 用于测试的启动文件
|
||||
|
||||
* `gemini_330_series_lower_cpu_usage.launch.py`
|
||||
* `multi_camera_lower_cpu_usage.launch.py`
|
||||
|
||||
### 测试环境
|
||||
|
||||
**硬件配置**
|
||||
@@ -94,10 +92,3 @@ v2.8.8 优化了彩色流图像发布流程：
|
||||
|
||||
根据测试结果，仅使用 `hardware_noise_removal_filter` 相比无滤波器基准，对 `libuvc`（+3.5%）和 `v4l2`（-3.4%）的CPU使用率变化可以忽略不计，因为此滤波器在相机硬件内部运行。相比之下，其他滤波器在主机系统上执行。将 `spatial_filter` 添加到硬件滤波器会导致CPU使用率适度增加，而应用基于软件的 `noise_removal_filter`——无论是单独使用还是与 `spatial_filter` 结合——都会显著增加CPU负载。为保持较低的CPU使用率，建议避免使用基于软件的滤波器，仅依赖 `hardware_noise_removal_filter`。
|
||||
|
||||
### 进一步优化
|
||||
|
||||
| 参数 | 推荐值 | 说明 |
|
||||
| :----------------------------: | :----------------------------------------------: | :---------------------------------------------: |
|
||||
| `depth_registration` | `false` 或 `true` 配合 `align_mode=HW` | 软件对齐消耗更多CPU |
|
||||
| `enable_point_cloud` | `false` | 禁用点云可降低CPU使用率 |
|
||||
| `enable_colored_point_cloud` | `false` | 禁用彩色点云可降低CPU使用率 |
|
||||
|
||||
Reference in New Issue
Block a user