# tracker_benchmark

**Repository Path**: tiderfang/tracker_benchmark

## Basic Information

- **Project Name**: tracker_benchmark
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-06
- **Last Updated**: 2026-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AGV Tracker Benchmark

面向 AGV 跟踪算法开发的桌面测试平台,Windows 端通过 SSH(文件推送/远端命令/rosbridge 启动)与 Rosbridge WebSocket(类 Foxglove 接入,服务调用与话题订阅)接入远端 ROS1 Melodic 控制系统,提供"路径设计 → 下发监控 → 误差评估 → 报告归档"一站式工作流。

## 功能模块

1. **测试用例设计**:直线 + B 样条曲线绘制,曲线按曲率色带可视化,段间切线平滑衔接,段速度/方向/初始横向误差/航向角可配置。
2. **测试用例管理**:JSON 入库,按名称/标签/时间检索,选中预览(只读路径 + 运动剖面表),加载到编辑器与删除。
3. **任务下发与监控**:双传输并存(SSH 负责文件推送与 rosbridge 启动;Rosbridge 负责服务调用与话题订阅)。实时显示 lat/lon/yaw 误差、目标轨迹、线速度/角速度指令与反馈、舵角反馈曲线。
4. **误差评估与报告**:自动判定任务结束(FSM:FINISH/CANCEL/IDLE+reach_end/超时),生成 HTML 报告(轨迹叠加/误差曲线/速度/角速度/舵角/分布直方图)。报告按「用例分组 / 用例 / 报告分组 / 测试报告」四级归档;报告分组名在监控页「本次备注」面板设置,用过的名称会存进配置,下次可从下拉直接复用。

### 反向下发

监控页「下发设置」勾选 **反向下发(沿原路返回)** 后,路线由 A→B→C 变为
C→B→A:段顺序与每段控制点顺序全部反转,每段前进/后退方向互换(`SpeedProfile.direction`
取反)。用于执行完正向路线后沿原路返回起点;仅本次下发生效,不修改用例文件。
记录 `meta.reversed` 并在 HTML 报告头部标注下发方向,便于区分同一用例的正/反向报告。
若需精确回到用例原始坐标,请取消勾选「起点对齐车体当前位姿」(该选项会按车体当前
航向旋转整条轨迹)。

### 监控曲线数据来源

| 曲线 | 数据来源 |
| --- | --- |
| 线速度指令 / 反馈 | `/waypoint_tracker/cmd_vel.linear.x` / `/control_actuator.walking_speed` |
| 角速度指令 / 反馈 | `/control.angle_speed` / `/control_actuator.angle_speed` |
| 舵角反馈 | `/control_actuator.steers_state[0].steer_angle` |

角速度指令话题可在「配置 → 话题配置」中修改(默认 `/control`)。`/control` 通常是
含 `angle_speed` 的复合自定义消息,**类型请留空**:连接时用 `rostopic info` 探测
真实类型(不依赖 rosapi),探测不到则由 rosbridge 按发布者推断;若按
`std_msgs/Float32` 订阅,类型不符会被 rospy 拒绝,`raw_control.jsonl` 为空、
角速度指令曲线恒为 0(旧配置中的该值会自动按空类型处理)。若机器人把角速度
单独发布成标量话题,填 `/control/angle_speed` 与 `std_msgs/Float32` 即可。
三类数据写入 `track.csv` 的 `angle_speed_cmd` / `angle_speed_fb` / `steer_angle`
列,实时曲线、报告曲线查看器与 HTML 报告均可查看。若连接后其他话题有数据而
`/control` 一帧未收到,界面会给出诊断提示,避免角速度指令静默显示为全 0。

## 环境要求

- Python 3.9 – 3.12(推荐 3.11 / 3.12,64 位)。3.13+ / 32 位 / ARM 环境可能没有依赖的 wheel。
- 支持 Windows / Linux / macOS。程序不依赖任何硬编码绝对路径,可放在任意目录、任意盘符,
  也能从任意工作目录启动。

## 快速启动

**Windows**(双击 `run.bat`,或 PowerShell):

```powershell
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

# 或一键脚本(自动建 venv / 装依赖 / 启动)
.\scripts\activate_and_run.ps1
```

**Linux / macOS**:

```bash
chmod +x scripts/run.sh
./scripts/run.sh

# 或手动:
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
./venv/bin/python main.py
```

可选环境变量:
- `TB_DATA_DIR`:指定运行时数据目录(用例 / 记录 / 日志 / 配置),便于便携盘或多实例部署。
- `TB_PIP_INDEX`:自定义 PyPI 镜像;镜像不可用时启动脚本自动回退官方 PyPI。
- `TB_USE_WEBENGINE=1`:用 `QWebEngineView` 渲染报告,需 `pip install -r requirements-webengine.txt`;
  默认用无 Chromium 依赖的 `QTextBrowser`。

## 路径与配置

- 所有运行时文件默认写在**程序根目录**下(相对 `main.py` 位置,由 `__file__` 推导):
  `data/cases`、`data/records`、`logs`、`config.json`、`key.bin`。
- 若程序根目录不可写(例如安装到 `Program Files`、只读共享目录),自动回退到当前用户的数据目录
  (Windows `%APPDATA%\tracker_benchmark`、macOS `~/Library/Application Support/tracker_benchmark`、
  Linux `$XDG_DATA_HOME/tracker_benchmark`),无需管理员权限。
- `config.example.json` 是随仓库分发的示例配置(不含真实凭据);`config.json` 与 `key.bin`
  **都是本机文件,不进版本库**。换一台电脑后会读取示例配置并弹出 `FirstRunWizard`,引导填写:
  1. 机器人 IP(SSH 与 Rosbridge 共用,只需填一次)+ SSH 端口 / 用户名 / 密码
  2. Rosbridge 端口(默认 9090),WebSocket 地址由该 IP 自动生成
  3. 消息类型探测(`/localization` 默认 `localization_msgs/localization_msg`)
- 「配置 → 连接配置」同样只在 SSH 页填一次机器人 IP,Rosbridge 页的 URL 是只读预览。
  配置文件内部仍保留 `ssh.host` 与 `rosbridge.url` 两个字段,以兼容旧 `config.json`
  与现有连接代码;保存时由 `utils/connection_settings.py` 统一派生。
- 密码使用 Fernet 加密写入 `config.json`,密钥为 `key.bin`(首次启动自动生成)。两者必须配套:
  只复制 `config.json` 而缺 `key.bin` 时,程序会判定配置不可用并重新弹出向导,
  而不是显示「已配置」却连不上。

## 目录结构

```
tracker_benchmark/
├── main.py                  # 程序入口
├── requirements.txt
├── requirements-webengine.txt  # 可选:QWebEngineView 渲染报告
├── config.example.json      # 示例配置(随仓库分发,无凭据)
├── config.json              # 本机配置(不进版本库)
├── key.bin                  # 本机 Fernet 密钥(不进版本库)
├── run.bat                  # Windows 一键启动
├── scripts/
│   ├── activate_and_run.ps1 # Windows / pwsh 一键启动
│   └── run.sh               # Linux / macOS 一键启动
├── data/                    # 运行时生成(不进版本库)
│   ├── cases/               # 测试用例库(*.json)
│   └── records/             # 任务记录(每次独立目录)
├── tests/                   # 单元 + 集成测试
└── tracker_benchmark/       # 主包
    ├── app.py               # QApplication 装配
    ├── core/                # 核心(几何/状态机/评估)
    ├── io/                  # YAML/Config/Record IO
    ├── remote/              # SSH + Rosbridge 客户端
    ├── ui/                  # PyQt 界面
    └── utils/               # 工具(日志/降采样/路径/qt 环境)
        └── paths.py         # 运行时路径解析(相对 __file__,可写回退)
```

## 测试

```bash
# 全部测试
pytest

# 单元测试
pytest tests/unit

# 集成测试(启动 mock server,较慢)
pytest tests/integration -m integration
```

## 关键设计

- **状态机**:应用级 FSM(Init/Ready/Dispatching/Monitoring/Evaluating/Completed/Error)防止并发下发;任务级 `EndDetector` 处理 FSM 6 状态(INIT/IDLE/WORK/PAUSE/FINISH/CANCEL)与超时。
- **双传输**:SSH(文件/命令)与 Rosbridge(服务/订阅)职责分离,通过 `RemoteServiceRunner` 显式组合。
- **线程模型**:SSH/roslibpy/ReportWorker 均在子线程,信号 `Qt.QueuedConnection` 投递到主线程。
- **性能**:pyqtgraph 实时曲线经 LTTB 降采样;matplotlib 报告生成在子线程。