# 平滑路径生成器使用说明

## 📁 文件位置

- **源代码**: `examples/generate_smooth_path.cpp`
- **可执行文件**: `build/Debug/generate_smooth_path.exe` 或 `build/Release/generate_smooth_path.exe`

## 🚀 快速开始

### 1. 编译程序

```bash
# 进入 build 目录
cd build

# 编译 Debug 版本
cmake --build . --target generate_smooth_path --config Debug

# 或编译 Release 版本
cmake --build . --target generate_smooth_path --config Release
```

### 2. 运行程序

```bash
# 运行 Debug 版本
./build/Debug/generate_smooth_path.exe

# 或运行 Release 版本
./build/Release/generate_smooth_path.exe
```

运行后会自动生成 6 个 CSV 文件在当前目录：

- ✅ `smooth_path.csv` - 默认平滑路径（5个关键点）
- ✅ `smooth_path_arc.csv` - 圆弧路径
- ✅ `smooth_path_scurve.csv` - S型曲线
- ✅ `smooth_path_complex.csv` - 复杂路径（10个关键点）
- ✅ `smooth_path_loop.csv` - 环形路径
- ✅ `smooth_path_figure8.csv` - 8字形路径

## 📚 类方法说明

`SmoothPathGenerator` 类提供以下静态方法：

### 1. `generateCircleArc()` - 生成圆弧路径

```cpp
SmoothPathGenerator::generateCircleArc(
    "output.csv",     // 输出文件名
    5.0, 0.0,        // 圆心坐标 (center_x, center_y)
    5.0,             // 半径
    M_PI, M_PI/2,    // 起始角度和终止角度（弧度）
    150              // 路径点数量
);
```

### 2. `generateSCurve()` - 生成S型曲线

```cpp
SmoothPathGenerator::generateSCurve(
    "scurve.csv",    // 输出文件名
    0.0, 0.0,        // 起点 (start_x, start_y)
    10.0, 0.0,       // 终点 (end_x, end_y)
    2.5,             // 控制点偏移量
    200              // 路径点数量
);
```

### 3. `generateSpline()` - 生成样条曲线

```cpp
std::vector<PathPoint> key_points = {
    PathPoint(0.0, 0.0),
    PathPoint(3.0, 1.0),
    PathPoint(6.0, 3.0),
    PathPoint(9.0, 3.5),
    PathPoint(12.0, 3.0)
};

SmoothPathGenerator::generateSpline(
    "spline.csv",     // 输出文件名
    key_points,       // 关键点数组
    200,              // 生成的总路径点数
    0.5               // 张力参数 (0-1, 越大越紧)
);
```

### 4. `generateComplexPath()` - 生成复杂路径

```cpp
// 自动生成一个包含10个关键点的复杂路径
SmoothPathGenerator::generateComplexPath("complex.csv", 300);
```

### 5. `generateLoop()` - 生成环形路径

```cpp
SmoothPathGenerator::generateLoop(
    "loop.csv",      // 输出文件名
    5.0,             // 半径
    300              // 路径点数量
);
```

### 6. `generateFigure8()` - 生成8字形路径

```cpp
SmoothPathGenerator::generateFigure8(
    "figure8.csv",   // 输出文件名
    4.0,             // 8字大小
    400              // 路径点数量
);
```

## 🎯 自定义使用示例

### 示例1：创建自己的平滑路径

```cpp
#include "path_curve.h"
#include <vector>

int main() {
    // 定义你的关键点
    std::vector<PathPoint> my_points = {
        PathPoint(0.0, 0.0),     // 起点
        PathPoint(2.0, 3.0),     // 第一个转折点
        PathPoint(5.0, 4.0),     // 第二个转折点
        PathPoint(8.0, 2.0),     // 第三个转折点
        PathPoint(10.0, 0.0)     // 终点
    };

    // 生成样条曲线
    PathCurve path;
    path.generateSpline(my_points, 250, 0.4);  // 250个点，张力0.4

    // 保存为CSV
    path.saveToCSV("my_custom_path.csv");

    return 0;
}
```

### 示例2：在代码中调用生成器

```cpp
#include "examples/generate_smooth_path.cpp"  // 或者定义成头文件

int main() {
    // 快速生成一个S型路径
    SmoothPathGenerator::generateSCurve(
        "warehouse_path.csv",
        0.0, 0.0,      // 从原点开始
        20.0, 5.0,     // 到达(20, 5)
        5.0,           // 较大的弯曲
        300            // 高精度
    );

    return 0;
}
```

### 示例3：批量生成多条路径

```cpp
int main() {
    // 生成多条不同参数的路径
    for (int i = 1; i <= 5; i++) {
        std::string filename = "path_" + std::to_string(i) + ".csv";
        double radius = i * 2.0;
        SmoothPathGenerator::generateLoop(filename, radius, 200);
    }

    return 0;
}
```

## 🖥️ 在Qt GUI中使用

1. 运行 Qt GUI 程序：
   ```bash
   ./build/Debug/agv_qt_gui.exe
   ```

2. 在界面中选择 **"Path Type"** → **"Load from CSV"**

3. 在文件对话框中选择生成的任意 CSV 文件

4. 点击 **"Generate Control"** 查看效果

## 📊 CSV 文件格式

生成的 CSV 文件格式如下：

```csv
# Custom Path Data
# x(m), y(m), theta(rad), kappa(1/m)
0.000000, 0.000000, 0.310064, 0.000000
0.015153, 0.004855, 0.299013, 1.369770
0.030624, 0.009440, 0.278105, 1.221140
...
```

- **x, y**: 路径点坐标（米）
- **theta**: 切线方向角（弧度）
- **kappa**: 曲率（1/米）

## 🔧 常见问题

### Q1: 如何调整路径的平滑度？

修改 `tension` 参数（0-1）：
- `0.0`: 非常平滑，接近直线
- `0.5`: 适中平滑（推荐）
- `1.0`: 紧贴关键点，更多曲折

### Q2: 如何增加路径精度？

增加 `num_points` 参数：
- 简单路径: 100-200 点
- 复杂路径: 300-500 点
- 高精度需求: 500+ 点

### Q3: 生成的路径在哪里？

路径文件生成在程序运行的当前目录。如果从 `build/Debug/` 运行，文件会在 `build/Debug/` 目录下。

建议运行时切换到项目根目录：
```bash
cd C:/work/AGV/AGV运动规划/agv_path_tracking
./build/Debug/generate_smooth_path.exe
```

### Q4: 如何只生成 smooth_path.csv？

修改 `main()` 函数，只保留需要的生成代码，或者创建自己的简化版本。

## 📝 完整调用示例

```cpp
#include "path_curve.h"
#include <iostream>
#include <vector>

int main() {
    // 方法1: 使用 PathCurve 类直接生成
    PathCurve path1;
    std::vector<PathPoint> points = {
        PathPoint(0, 0),
        PathPoint(5, 2),
        PathPoint(10, 0)
    };
    path1.generateSpline(points, 200, 0.5);
    path1.saveToCSV("method1.csv");

    // 方法2: 使用 SmoothPathGenerator 封装类
    SmoothPathGenerator::generateSCurve(
        "method2.csv",
        0, 0, 10, 0, 3.0, 200
    );

    std::cout << "Paths generated!" << std::endl;
    return 0;
}
```

## 🎓 进阶用法

### 自定义路径生成器

你可以继承或扩展 `SmoothPathGenerator` 类来添加更多路径类型：

```cpp
class MyPathGenerator : public SmoothPathGenerator {
public:
    // 添加自定义路径类型
    static bool generateZigZag(const std::string& filename,
                               int segments = 5,
                               double width = 2.0) {
        std::vector<PathPoint> points;
        for (int i = 0; i <= segments; i++) {
            double x = i * 2.0;
            double y = (i % 2) * width;
            points.push_back(PathPoint(x, y));
        }

        PathCurve path;
        path.generateSpline(points, segments * 50, 0.3);
        return path.saveToCSV(filename);
    }
};
```

## 📖 相关文档

- [PathCurve 类文档](include/path_curve.h)
- [Qt GUI 使用说明](QUICKSTART.md)
- [AGV 控制系统文档](README.md)

## ✅ 验证生成结果

使用 Python 可视化（如果安装了 matplotlib）：

```python
import pandas as pd
import matplotlib.pyplot as plt

# 读取CSV文件
df = pd.read_csv('smooth_path.csv', comment='#')

# 绘制路径
plt.figure(figsize=(10, 8))
plt.plot(df['x(m)'], df['y(m)'], 'b-', linewidth=2, label='Path')
plt.plot(df['x(m)'], df['y(m)'], 'ro', markersize=3)
plt.xlabel('X (m)')
plt.ylabel('Y (m)')
plt.title('Generated Smooth Path')
plt.grid(True)
plt.axis('equal')
plt.legend()
plt.show()
```

---

**作者**: AGV Path Tracking System
**最后更新**: 2025-11-13