# ros_viz_adapter

通用 ROS 2 可视化发布适配器，不需要用户修改原始话题名称，也不需要
YAML 配置文件。节点自动发现 `sensor_msgs/msg/Image` 和
`sensor_msgs/msg/PointCloud2`，并把结果发布到 `/viz` 命名空间。

## 输出

- RGB：直接加载 `image_transport/compressed_pub`，插件发布
  `/viz/<source>/rgb/compressed`，不创建 raw base topic。
- 深度：直接加载 `image_transport/compressedDepth_pub`，插件发布
  `/viz/<source>/depth/compressedDepth`，不创建 raw base topic。
- 点云：`/viz/<source>/points`，消息仍为 `sensor_msgs/msg/PointCloud2`，但只保留
  `x/y/z`，去除 NaN，执行体素降采样、最大点数限制和限频。

图像依据 `encoding` 分类：`rgb8/bgr8/rgba8/bgra8/mono8` 为 RGB，
`16UC1/32FC1/mono16/32SC1` 为深度。RGB、深度、点云各使用一个独立处理线程；
不存在对应数据类型时，不创建该线程。

## 运行

```bash
colcon build --packages-select ros_viz_adapter --symlink-install
ros2 launch ros_viz_adapter adapter.launch.py
```

参数：

```text
output_namespace      默认 /viz
input_fps_limit       默认 30，回调入口丢弃超频帧
output_fps            默认 10，处理线程输出上限
jpeg_quality          默认 80，范围 1-100
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 网络。适配器容器只需安装本包、`compressed_image_transport` 和
`compressed_depth_image_transport`，不需要复制用户项目代码。代码只加载上述两个
指定插件，不遍历或加载 Theora 插件。

### 多容器隔离

为避免不同容器输出重名，可以指定不同 namespace：

```bash
ros2 launch ros_viz_adapter adapter.launch.py \
  output_namespace:=/viz/robot_01
```