# 快速使用指南 - AGV Qt6 GUI

## 📌 更新说明
✅ **项目已升级到 Qt6！**（2025-11-27）
- Qt 版本: 6.10.1
- 编译器: MinGW 13.1.0
- 详细编译说明: [BUILD_INSTRUCTIONS.md](BUILD_INSTRUCTIONS.md)
- 部署指南: [QT6_DEPLOYMENT_GUIDE.md](QT6_DEPLOYMENT_GUIDE.md)

---

## 快速开始

### 1. 编译项目（首次使用）

```bash
# 配置（Windows MinGW）
cd build
cmake -G "MinGW Makefiles" \
  -DCMAKE_PREFIX_PATH=C:/Qt/6.10.1/mingw_64 \
  -DCMAKE_C_COMPILER=C:/Qt/Tools/mingw1310_64/bin/gcc.exe \
  -DCMAKE_CXX_COMPILER=C:/Qt/Tools/mingw1310_64/bin/g++.exe \
  -DCMAKE_MAKE_PROGRAM=C:/Qt/Tools/mingw1310_64/bin/mingw32-make.exe ..

# 编译
cmake --build . -j4
```

### 2. 运行程序

```bash
# 确保 Qt DLL 在 PATH 中
export PATH=/c/Qt/6.10.1/mingw_64/bin:$PATH

# 运行
./agv_qt_gui.exe
```

或使用以下命令一次性运行：
```bash
PATH=/c/Qt/6.10.1/mingw_64/bin:$PATH ./build/agv_qt_gui.exe
```

---

## 路径跟踪功能

### 问题
❌ trajectory路径只有一段，无法完整追踪reference path

## 解决方案
✅ **已修复并重新编译成功！**

## 立即测试

### 1. 运行程序
```bash
./build/Release/agv_qt_gui.exe
```

### 2. 检查Horizon参数
在GUI界面中找到：
```
Horizon (s): [     50.0     ]  ← 默认值已改为50秒
             范围: 1-100秒
```

### 3. 生成控制序列
- 选择任意路径类型（建议先测试 "Straight Line"）
- 点击 "Generate Control"
- 观察可视化窗口中的trajectory（绿色线）

### 4. 验证结果
✓ trajectory应该完整覆盖reference path（红色线）
✓ 不应该在中途停止
✓ 应该接近路径终点（0.5米范围内）

## 如果轨迹仍不完整

### 场景1: 路径很长（>50米）
**解决**: 手动增加Horizon值
```
路径长度: 80米
速度: 1.0 m/s
推荐Horizon: 80 × 1.5 = 120秒
但GUI最大值是100秒，所以设置为100秒
```

### 场景2: 速度很慢（<0.5 m/s）
**解决**: 同样需要增加Horizon
```
路径长度: 20米
速度: 0.5 m/s
推荐Horizon: 20 / 0.5 × 1.5 = 60秒
```

### 场景3: 路径超长（>100米）
**解决**: 需要修改代码中的最大值
在 `qt_gui_demo.cpp:294` 中将 100.0 改为更大的值（比如200.0）

## 计算Horizon公式

```
Horizon (秒) = 路径长度(米) / 期望速度(m/s) × 1.5
```

**示例**:
- 20米路径 @ 1.0 m/s → 30秒
- 50米路径 @ 1.0 m/s → 75秒
- 30米路径 @ 0.5 m/s → 90秒

## 修复对比

| 项目 | 修复前 | 修复后 |
|------|--------|--------|
| Horizon默认值 | 10秒 | **50秒** ✓ |
| Horizon最大值 | 30秒 | **100秒** ✓ |
| 终止阈值 | 0.1米 | **0.5米** ✓ |
| 默认可追踪距离 | 10米 | **50米** ✓ |

## 预设路径测试

| 路径类型 | 预估长度 | 推荐Horizon | 状态 |
|---------|---------|------------|------|
| Straight Line | ~14米 | 默认50秒即可 | ✓ |
| Circle Arc | ~15米 | 默认50秒即可 | ✓ |
| S-Curve | ~12米 | 默认50秒即可 | ✓ |
| Load from CSV | 视文件而定 | 可能需调整 | ✓ |
| Custom Spline | 视输入而定 | 可能需调整 | ✓ |

## 常见问题

### Q: 轨迹还是不完整？
A: 检查以下几点：
1. Horizon值是否足够大（建议设为路径长度的1.5倍所需时间）
2. 在控制台查看是否有错误信息
3. 确认路径点是否正确加载

### Q: 如何查看路径长度？
A: 在控制台中会输出：
```
Path length: 14.1421 m
Path points: 100
```

### Q: Horizon设太大会有问题吗？
A: 不会！程序会在到达终点时自动停止（distance < 0.5米）。Horizon只是最大时间限制。

### Q: 为什么编译时有警告？
A: C4267警告（size_t转int）是良性的，不影响功能，可以忽略。

## 技术支持

如有问题，检查文档：
- `TRAJECTORY_FIX.md` - 详细技术分析
- `TRAJECTORY_COMPLETE.md` - 完整修复报告
- `FIX_SUMMARY.md` - CSV加载修复
- `FINAL_REPORT.md` - 完整技术文档

---

**更新日期**: 2025-11-27
**版本**: v2.0
**状态**: ✅ Qt6 升级完成、已编译、已测试
**Qt 版本**: 6.10.1
**编译器**: MinGW 13.1.0