RCS-3000/docs/custom_path/PROJECT_STRUCTURE.md

AGV自定义路径功能 - 项目结构

📁 完整目录结构

agv_path_tracking/
│
├── 📄 CUSTOM_PATH_README.md        # 快速导航（从这里开始）
├── 📄 README.md                     # 项目主README
├── 📄 QUICKSTART.md                 # 原有快速开始
├── 📄 CMakeLists.txt                # 需要修改：添加path_curve_custom.cpp
│
├── 📂 src/                          # 源代码
│   ├── agv_model.cpp
│   ├── path_curve.cpp              # 原有路径实现
│   ├── path_curve_custom.cpp       # ⭐ 新增：自定义路径实现
│   ├── control_generator.cpp
│   └── path_tracker.cpp
│
├── 📂 include/                      # 头文件
│   ├── agv_model.h
│   ├── path_curve.h                # ⚠️ 需要修改：添加3个方法声明
│   ├── control_generator.h
│   └── path_tracker.h
│
├── 📂 examples/                     # 示例程序
│   ├── demo.cpp                    # 原有命令行demo
│   ├── generate_data.cpp
│   ├── gui_demo.cpp
│   ├── qt_gui_demo.cpp             # ⚠️ 可修改：添加自定义路径选项
│   ├── qt_gui_enhanced.cpp         # 参考实现
│   ├── custom_path.csv             # ⭐ 示例：基础路径
│   └── warehouse_path.csv          # ⭐ 示例：仓库路径
│
├── 📂 docs/                         # 📚 文档目录
│   └── custom_path/                # 🎯 自定义路径功能文档（所有文档在这里）
│       ├── README.md               # 📖 文档导航（从这里开始！）
│       │
│       ├── 🚀 快速开始
│       ├── FINAL_SUMMARY.md        # ⭐ 功能总览（推荐首读）
│       ├── QUICKSTART_CUSTOM_PATH.md # 3分钟快速上手
│       │
│       ├── 📖 详细教程
│       ├── CUSTOM_PATH_GUIDE.md    # 完整使用指南
│       │
│       ├── 🖥️ QT界面集成
│       ├── apply_qt_modifications.md # ⭐ 快速修改步骤
│       ├── QT_GUI_CUSTOM_PATH_GUIDE.md # 详细修改指南
│       ├── qt_gui_custom_code_snippet.cpp # 完整代码示例
│       │
│       ├── 🔧 安装和配置
│       ├── install_custom_path.sh  # 自动安装脚本
│       ├── path_curve.h.patch      # 头文件修改补丁
│       │
│       ├── 💻 开发文档
│       ├── CUSTOM_PATH_IMPLEMENTATION_SUMMARY.txt # 实现细节
│       ├── REFERENCE_PATH_SUMMARY.txt # 原系统分析
│       └── PROJECT_STRUCTURE.md    # 本文件（项目结构）
│
├── 📂 build/                        # 编译输出目录
│   ├── agv_demo                    # 可执行文件
│   ├── agv_qt_gui
│   └── ...
│
└── 📂 output/                       # 运行结果（自动生成）
    ├── trajectory.csv
    ├── control_sequence.csv
    └── ...

🎯 核心文件说明

⭐ 必须了解的文件

文件	位置	说明	优先级
CUSTOM_PATH_README.md	根目录	快速导航	⭐⭐⭐
docs/custom_path/README.md	docs/custom_path/	文档导航	⭐⭐⭐
FINAL_SUMMARY.md	docs/custom_path/	功能总览	⭐⭐⭐

📝 文档文件（docs/custom_path/）

文件名	大小	用途	适合人群
README.md	4.2KB	文档导航	所有人 ⭐
FINAL_SUMMARY.md	6.9KB	功能总览	新手 ⭐⭐⭐
QUICKSTART_CUSTOM_PATH.md	5.9KB	快速上手	新手 ⭐⭐⭐
CUSTOM_PATH_GUIDE.md	8.2KB	完整教程	深入学习 ⭐⭐
apply_qt_modifications.md	2.0KB	QT快速修改	QT用户 ⭐⭐⭐
QT_GUI_CUSTOM_PATH_GUIDE.md	7.9KB	QT详细指南	QT用户 ⭐⭐
qt_gui_custom_code_snippet.cpp	7.2KB	QT代码示例	QT开发 ⭐⭐
install_custom_path.sh	2.1KB	安装脚本	所有人 ⭐⭐⭐
path_curve.h.patch	1.4KB	头文件补丁	开发者 ⭐
CUSTOM_PATH_IMPLEMENTATION_SUMMARY.txt	8.4KB	实现细节	开发者 ⭐
REFERENCE_PATH_SUMMARY.txt	8.7KB	原系统分析	背景知识 ⭐
PROJECT_STRUCTURE.md	本文件	项目结构	开发者 ⭐

💻 核心代码文件

文件	位置	说明	是否需要修改
path_curve_custom.cpp	src/	自定义路径实现	❌ 已实现
path_curve.h	include/	路径类声明	⚠️ 需添加3个方法
CMakeLists.txt	根目录	编译配置	⚠️ 需添加custom文件
qt_gui_demo.cpp	examples/	QT界面	🔧 可选修改

📄 示例文件

文件	位置	说明	格式
custom_path.csv	examples/	基础示例路径	x, y
warehouse_path.csv	examples/	仓库场景路径	x, y

🔄 文件依赖关系

CMakeLists.txt
    └── src/path_curve_custom.cpp
            └── include/path_curve.h (需要添加方法声明)
                    └── examples/qt_gui_demo.cpp (可选使用)
                            └── examples/custom_path.csv (示例数据)

📊 修改检查清单

必须修改（功能才能工作）

• include/path_curve.h

  • 添加 #include <string>
  • 添加 bool loadFromCSV(...)
  • 添加 bool saveToCSV(...) const
  • 添加 void generateSpline(...)
  • 参考：docs/custom_path/path_curve.h.patch

• CMakeLists.txt

  • 在SOURCES中添加：src/path_curve_custom.cpp
  • 位置：第19行附近

• 重新编译

  cd build
  cmake ..
  cmake --build .
  

可选修改（增强功能）

• examples/qt_gui_demo.cpp
  • 添加CSV加载选项
  • 添加样条插值选项
  • 参考：docs/custom_path/qt_gui_custom_code_snippet.cpp

🚀 使用流程

流程1: 自动安装（推荐）

# 1. 运行安装脚本
bash docs/custom_path/install_custom_path.sh

# 2. 编译
cd build && cmake .. && cmake --build .

# 3. 使用
./agv_demo

流程2: 手动安装

# 1. 查看文档
cat docs/custom_path/README.md

# 2. 阅读指南
cat docs/custom_path/QUICKSTART_CUSTOM_PATH.md

# 3. 修改文件（参考path_curve.h.patch）
vi include/path_curve.h
vi CMakeLists.txt

# 4. 编译测试
cd build && cmake .. && cmake --build .

📖 学习路径

路径1: 快速上手（15分钟）

1. CUSTOM_PATH_README.md        (根目录，2分钟)
   └─ 了解功能位置

2. docs/custom_path/FINAL_SUMMARY.md  (5分钟)
   └─ 功能总览

3. docs/custom_path/QUICKSTART_CUSTOM_PATH.md (5分钟)
   └─ 动手实践

4. bash docs/custom_path/install_custom_path.sh (3分钟)
   └─ 安装使用

路径2: QT界面集成（20分钟）

1. docs/custom_path/apply_qt_modifications.md (5分钟)
   └─ 了解需要修改什么

2. docs/custom_path/qt_gui_custom_code_snippet.cpp (10分钟)
   └─ 复制代码到qt_gui_demo.cpp

3. 编译运行 (5分钟)
   └─ 测试功能

路径3: 深入学习（1小时）

1. FINAL_SUMMARY.md (10分钟)
   └─ 整体了解

2. CUSTOM_PATH_GUIDE.md (30分钟)
   └─ 详细学习

3. CUSTOM_PATH_IMPLEMENTATION_SUMMARY.txt (20分钟)
   └─ 实现细节

🎯 常用命令

# 查看文档目录
ls docs/custom_path/

# 阅读文档导航
cat docs/custom_path/README.md

# 自动安装
bash docs/custom_path/install_custom_path.sh

# 查看示例路径
cat examples/custom_path.csv

# 编译项目
cd build && cmake .. && cmake --build .

# 运行demo
./build/agv_demo
./build/agv_qt_gui

💡 提示

• 📚 所有文档在：docs/custom_path/
• ⭐ 从这里开始：docs/custom_path/FINAL_SUMMARY.md
• 🚀 快速上手：docs/custom_path/QUICKSTART_CUSTOM_PATH.md
• 🖥️ QT修改：docs/custom_path/apply_qt_modifications.md
• 🔧 自动安装：bash docs/custom_path/install_custom_path.sh

---

最后更新: 2025-11-13
版本: 1.0