Skip to content

Latest commit

 

History

History
117 lines (83 loc) · 5.42 KB

Python_Tools_CN.md

File metadata and controls

117 lines (83 loc) · 5.42 KB

MATRiX v1.1.2 Python 工具

返回中文主页 | 快速开始

v1.1.2 Linux 运行包在根目录提供 Tools/。以下脚本与本次 Release 中的版本一致;完整参数始终以 python3 Tools/<脚本>.py --help 为准。

工具源码也在本仓库的 Tools 中维护。运行时把完整 Tools/ 目录保留在解压的可执行包中,不能仅克隆此仓库就启动仿真。Python 3.10+,可用虚拟环境安装 Tools/requirements.txt;Tkinter 需系统提供。

初始 robot.sensors 为空,不会自动发布传感器数据;sensor_sync_mode=true。请在传感器设置中加载并应用 config_default.json(IMU、Odom、GPS、RGB、Depth、Airy)或其他方案,再进入仿真并创建机器人。

工具清单

脚本 用途 主要依赖
zenoh_topic_monitor.py 显示 Zenoh topic、频率、大小和延迟 eclipse-zenoh
zenoh_sensor_receiver.py 查看相机、深度和 LiDAR 数据 eclipse-zenoh、numpy、opencv-python
visualize_lidar_camera_projection.py 将 LiDAR 点云投影到 RGB 图像 eclipse-zenoh、numpy、opencv-python
visualize_lidar_fisheye_projection.py 四路鱼眼点云与世界包围盒叠加 eclipse-zenoh、numpy、opencv-python 及辅助模块
zenoh_bbox_lidar_recorder.py 原始消息录制、离线预览、回放 eclipse-zenoh、Tkinter、Pillow 及辅助模块
visualize_zenoh_bbox.py 显示分类 XY 包围盒、速度和目标详情 eclipse-zenoh、matplotlib
visualize_zenoh_bbox_2d.py 显示固定范围的 2D 俯视包围盒 eclipse-zenoh、matplotlib
matrix_mc_udp_test.py 内置运控起身、行走、转向和动作测试 Python 标准库
gimbal_udp_client.py 云台 UDP/JSON 命令行客户端 Python 标准库
gimbal_udp_ui.py 云台四方向图形测试工具 Python 标准库、Tkinter
send_spawn_udp.py 发送场景对象生成 UDP JSON Python 标准库
send_udp_voice.py 发送 JSON 或 MP3 UDP 数据 Python 标准库

安装常用依赖

python3 -m pip install eclipse-zenoh numpy opencv-python matplotlib

图形工具需要桌面显示环境。SSH 无图形会话不能直接显示 OpenCV、Matplotlib 或 Tkinter 窗口。

Zenoh topic 监控

UeSim 默认监听 tcp/0.0.0.0:7447,本机工具在 client 模式下默认连接 tcp/127.0.0.1:7447。

python3 Tools/zenoh_topic_monitor.py --key '**'
python3 Tools/zenoh_topic_monitor.py --key 'rt/**'
python3 Tools/zenoh_topic_monitor.py --connect tcp/192.168.1.100:7447

先订阅 ** 发现实际 key,再按传感器配置缩小范围。界面切换传感器预设后,活动 topic 可能发生变化。

传感器接收

python3 Tools/zenoh_sensor_receiver.py --key 'rt/**'
python3 Tools/zenoh_sensor_receiver.py --key 'rt/front_lidar' --stream-type lidar
python3 Tools/zenoh_sensor_receiver.py \
  --connect tcp/192.168.1.100:7447 \
  --key 'rt/**'

接收器可自动识别压缩图像、深度图和 ROS 2 PointCloud2。使用 --auto-range 调整深度显示,使用 --height-auto-range 调整 LiDAR 高度图。

LiDAR 到相机投影

使用前编辑 UeSim/Content/model/config/config.json:

"sensor_sync_mode": true

然后从发布包根目录运行:

python3 Tools/visualize_lidar_camera_projection.py --sensor-config UeSim/Content/model/config/sensors/config_default.json --check-only
python3 Tools/visualize_lidar_camera_projection.py

默认相机 key 为 rt/front_camera/image/compressed,LiDAR key 为 rt/front_lidar。按 S 保存,按 Q 或 Esc 退出。详细说明见 LiDAR 到相机投影。

包围盒查看

python3 Tools/visualize_zenoh_bbox.py --key rt/dynamicinfo
python3 Tools/visualize_zenoh_bbox_2d.py --key rt/dynamicinfo

2D 工具默认显示 X -250…150 m、Y -50…50 m 的 ROS FLU 世界坐标。详细消息格式见 Zenoh 2D 包围盒工具。

内置运控 UDP 测试

python3 Tools/matrix_mc_udp_test.py stand
python3 Tools/matrix_mc_udp_test.py walk --stand-first --forward 0.25 --duration 3
python3 Tools/matrix_mc_udp_test.py rotate --yaw 0.25 --duration 2
python3 Tools/matrix_mc_udp_test.py passive

远程控制增加 --host <仿真器IP>。默认 UDP 端口为 7447,速度输入超过 0.5 秒未刷新会失效。

云台工具

python3 Tools/gimbal_udp_client.py --port 8870 --gimbal-id camera_gimbal ping
python3 Tools/gimbal_udp_ui.py \
  --port 8870 \
  --state-port 8871 \
  --npc-state-port 8872 \
  --gimbal-id camera_gimbal

UeSim 中的 PTZRGB 云台 UDP 服务必须先启动。协议和 UI 操作见 云台 UDP/JSON 协议及图形测试工具。

排查

  • ModuleNotFoundError:使用运行脚本的同一个 Python 执行 python3 -m pip install ...。
  • 无 Zenoh 数据:先监控 **,再检查 UeSim 日志、IP、TCP 7447、防火墙和活动传感器。
  • 图形窗口无法打开:确认当前会话有桌面显示环境。
  • 参数不识别:运行对应脚本的 --help,不要照搬旧版本参数。

鱼眼与录制工具需连同辅助模块一起复制,详见工具清单、鱼眼说明和录制回放。