# AGV 路径跟踪控制系统 - 快速入门指南

本指南将帮助您快速上手 AGV 路径跟踪控制系统。

## 1. 编译项目

### Windows 用户

使用 PowerShell：
```powershell
.\build.ps1
```

或手动编译：
```powershell
mkdir build
cd build
cmake ..
cmake --build . --config Release
```

### Linux/MacOS 用户

```bash
chmod +x build.sh
./build.sh
```

或手动编译：
```bash
mkdir build
cd build
cmake ..
make
```

## 2. 运行程序

### 命令行演示程序

Windows:
```powershell
cd build\Release
.\agv_demo.exe
```

Linux/MacOS:
```bash
cd build
./agv_demo
```

### 控制台 GUI 程序

Windows:
```powershell
cd build\Release
.\agv_gui.exe
```

Linux/MacOS:
```bash
cd build
./agv_gui
```

### Qt 图形界面程序

Windows:
```powershell
cd build\Release
.\agv_qt_gui.exe
```

Linux/MacOS:
```bash
cd build
./agv_qt_gui
```

## 3. 使用示例

运行 `agv_demo` 后，您将看到交互式菜单：

1. **选择路径类型**
   - 1: 直线路径
   - 2: 圆弧路径
   - 3: 贝塞尔曲线
   - 4: S形曲线

2. **选择控制算法**
   - 1: Pure Pursuit（推荐用于平滑路径）
   - 2: Stanley（推荐用于高精度跟踪）

3. **查看结果**
   - 程序会在控制台显示控制序列
   - 可选择保存为CSV文件

## 4. 可视化结果

如果保存了CSV文件，可以使用Python脚本可视化：

```bash
python visualize.py
```

需要安装的依赖：
```bash
pip install pandas matplotlib numpy
```

## 5. 输出文件说明

生成的 CSV 文件包含：

- **control_sequence.csv**: 时间、速度、转向角（弧度和角度）
- **trajectory.csv**: AGV 的预测轨迹（x, y, θ）

文件格式示例：
```csv
# AGV Control Sequence
# Time(s), Velocity(m/s), Steering(rad), Steering(deg)
0.000000, 1.000000, 0.732770, 41.984039
0.100000, 1.000000, 0.732933, 41.993384
```

## 6. 自定义使用

参考 `examples/demo.cpp` 中的代码，您可以：

```cpp
// 创建自定义路径
PathCurve my_path;
my_path.generateLine(PathPoint(0, 0), PathPoint(10, 5), 100);

// 调整 AGV 参数
AGVModel my_agv(
    1.5,        // 轴距 1.5m
    3.0,        // 最大速度 3.0 m/s
    M_PI/3      // 最大转向角 60 度
);

// 生成控制序列
tracker.generateControlSequence("pure_pursuit", 0.05, 15.0);
```

## 常见问题

### Q: 编译时找不到 cmake？
**A:** 请安装 CMake：https://cmake.org/download/

### Q: Windows 下编译失败？
**A:** 确保安装了以下之一：
- Visual Studio（推荐 2019 或更新版本）
- MinGW-w64

### Q: 如何修改路径参数？
**A:** 编辑 `examples/demo.cpp` 或参考完整 README 文档自定义路径

### Q: 控制序列太长或太短？
**A:** 调整 `generateControlSequence` 的 `horizon` 参数（时域长度）

### Q: Pure Pursuit 和 Stanley 算法有什么区别？
**A:**
- **Pure Pursuit**：适合平滑路径，计算简单，跟踪稳定
- **Stanley**：适合高精度跟踪，对横向误差更敏感

### Q: 如何调整可视化参数？
**A:** 编辑 `visualize.py` 文件中的绘图参数，如箭头间隔、线宽等

## 下一步

- 阅读完整的 [README.md](README.md) 了解详细 API 和算法原理
- 查看 `examples/` 目录下的示例代码学习使用方法
- 尝试不同的路径类型和控制算法组合
- 调整 AGV 参数观察对控制效果的影响
- 集成到您自己的项目中

## 技术支持

如有问题或建议，请在代码仓库中创建 issue。

祝使用愉快！