From 816396d35dffade2f053c3639c11dcddb873a940 Mon Sep 17 00:00:00 2001
From: Huang77 <2366619700@qq.com>
Date: Wed, 12 Aug 2026 19:27:41 +0800
Subject: [PATCH] update adapter

---
 src/ros_viz_adapter/CMakeLists.txt           | 17 ++++
 src/ros_viz_adapter/README.md                | 89 ++++++++++++++++++++
 src/ros_viz_adapter/launch/adapter.launch.py | 17 ++++
 src/ros_viz_adapter/package.xml              | 15 ++++
 4 files changed, 138 insertions(+)
 create mode 100644 src/ros_viz_adapter/CMakeLists.txt
 create mode 100644 src/ros_viz_adapter/README.md
 create mode 100644 src/ros_viz_adapter/launch/adapter.launch.py
 create mode 100644 src/ros_viz_adapter/package.xml

diff --git a/src/ros_viz_adapter/CMakeLists.txt b/src/ros_viz_adapter/CMakeLists.txt
new file mode 100644
index 0000000..57421b4
--- /dev/null
+++ b/src/ros_viz_adapter/CMakeLists.txt
@@ -0,0 +1,17 @@
+cmake_minimum_required(VERSION 3.8)
+project(ros_viz_adapter)
+
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 17)
+endif()
+find_package(ament_cmake REQUIRED)
+find_package(rclcpp REQUIRED)
+find_package(sensor_msgs REQUIRED)
+find_package(image_transport REQUIRED)
+
+add_executable(adapter src/adapter.cpp)
+ament_target_dependencies(adapter rclcpp sensor_msgs image_transport)
+install(TARGETS adapter DESTINATION lib/${PROJECT_NAME})
+install(DIRECTORY launch DESTINATION share/${PROJECT_NAME})
+install(FILES README.md DESTINATION share/${PROJECT_NAME})
+ament_package()
diff --git a/src/ros_viz_adapter/README.md b/src/ros_viz_adapter/README.md
new file mode 100644
index 0000000..9ded79e
--- /dev/null
+++ b/src/ros_viz_adapter/README.md
@@ -0,0 +1,89 @@
+# ros_viz_adapter
+
+通用 ROS 2 可视化发布适配器，不需要用户修改原始话题名称，也不需要
+YAML 配置文件。节点自动发现 `sensor_msgs/msg/Image` 和
+`sensor_msgs/msg/PointCloud2`，并把结果发布到 `/viz` 命名空间。
+
+## 输出
+
+- RGB：通过 `image_transport` 发布 base topic `/viz/<source>/rgb`。
+  安装 `compressed_image_transport` 后，平台订阅其 `/compressed` 传输。
+- 深度：通过 `image_transport` 发布 base topic `/viz/<source>/depth`。
+  安装 `compressed_depth_image_transport` 后，平台订阅其 `/compressedDepth`。
+- 点云：`/viz/<source>/points`，消息仍为 `sensor_msgs/msg/PointCloud2`，但只保留
+  `x/y/z`，去除 NaN，执行体素降采样、最大点数限制和限频。
+
+图像依据 `encoding` 分类：`rgb8/bgr8/rgba8/bgra8/mono8` 为 RGB，
+`16UC1/32FC1/mono16/32SC1` 为深度。RGB、深度、点云各使用一个独立处理线程；
+不存在对应数据类型时，不创建该线程。
+
+## 运行
+
+```bash
+ros2 launch ros_viz_adapter adapter.launch.py
+```
+
+参数：
+
+```text
+output_namespace      默认 /viz
+input_fps_limit       默认 30，回调入口丢弃超频帧
+output_fps            默认 10，处理线程输出上限
+voxel_size_m          默认 0.05
+max_points            默认 100000
+```
+
+QoS 为 `BEST_EFFORT + KEEP_LAST + depth=1`。限频降低的是适配器处理、网络和
+平台负载；如果还要降低源容器 CPU，应同时调整相机/上游发布频率。
+
+## 在其他项目中接入
+
+### 同一个 colcon 工作空间
+
+把本包目录放到项目工作空间的 `src/` 下，然后正常构建：
+
+```bash
+cd <workspace>
+colcon build --symlink-install
+source install/setup.bash
+ros2 launch ros_viz_adapter adapter.launch.py
+```
+
+不需要修改原始 RGB、深度或点云节点。适配器会在同一个 ROS domain 中发现传感器话题，
+并发布 `/viz/...`。
+
+### 在项目 launch 中启动
+
+也可以在项目自己的 launch 文件中包含适配器：
+
+```python
+from launch.actions import IncludeLaunchDescription
+from launch.launch_description_sources import PythonLaunchDescriptionSource
+from launch_ros.substitutions import FindPackageShare
+
+viz_adapter = IncludeLaunchDescription(
+    PythonLaunchDescriptionSource([
+        FindPackageShare('ros_viz_adapter'), '/launch/adapter.launch.py'
+    ])
+)
+```
+
+将 `viz_adapter` 放入项目的 `LaunchDescription` 即可。也可以直接运行：
+
+```bash
+ros2 run ros_viz_adapter adapter
+```
+
+### 独立 ROS 容器或 sidecar
+
+适配器容器与用户容器必须使用相同的 `ROS_DOMAIN_ID`、`RMW_IMPLEMENTATION` 和可互相发现的
+ROS 2 网络。适配器容器只需安装本包及 image_transport 压缩插件，不需要复制用户项目代码。
+
+### 多容器隔离
+
+为避免不同容器输出重名，可以指定不同 namespace：
+
+```bash
+ros2 launch ros_viz_adapter adapter.launch.py \
+  output_namespace:=/viz/robot_01
+```
diff --git a/src/ros_viz_adapter/launch/adapter.launch.py b/src/ros_viz_adapter/launch/adapter.launch.py
new file mode 100644
index 0000000..f822e51
--- /dev/null
+++ b/src/ros_viz_adapter/launch/adapter.launch.py
@@ -0,0 +1,17 @@
+from launch import LaunchDescription
+from launch.actions import DeclareLaunchArgument
+from launch.substitutions import LaunchConfiguration
+from launch_ros.actions import Node
+
+
+def generate_launch_description():
+    return LaunchDescription([
+        DeclareLaunchArgument('output_namespace', default_value='/viz'),
+        Node(
+            package='ros_viz_adapter', executable='adapter',
+            name='ros_viz_adapter', output='screen',
+            parameters=[{
+                'output_namespace': LaunchConfiguration('output_namespace'),
+            }],
+        ),
+    ])
diff --git a/src/ros_viz_adapter/package.xml b/src/ros_viz_adapter/package.xml
new file mode 100644
index 0000000..de2964a
--- /dev/null
+++ b/src/ros_viz_adapter/package.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<package format="3">
+  <name>ros_viz_adapter</name>
+  <version>0.2.0</version>
+  <description>Rate-limited ROS 2 visualization publishers for images and point clouds.</description>
+  <maintainer email="platform@example.com">Platform Team</maintainer>
+  <license>Apache-2.0</license>
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <depend>rclcpp</depend>
+  <depend>sensor_msgs</depend>
+  <depend>image_transport</depend>
+  <exec_depend>compressed_image_transport</exec_depend>
+  <exec_depend>compressed_depth_image_transport</exec_depend>
+  <export><build_type>ament_cmake</build_type></export>
+</package>