403 lines
12 KiB
Markdown
403 lines
12 KiB
Markdown
# 项目结构说明
|
||
|
||
本文档详细说明项目的目录结构和主要文件的作用。
|
||
|
||
## 📁 目录结构
|
||
|
||
```
|
||
rebuild1002/
|
||
├── 📄 主要应用文件
|
||
│ ├── app_main.py # 主应用入口（FastAPI 服务）
|
||
│ ├── navigation_master.py # 导航统领器（状态机）
|
||
│ ├── workflow_blindpath.py # 盲道导航工作流
|
||
│ ├── workflow_crossstreet.py # 过马路导航工作流
|
||
│ └── yolomedia.py # 物品查找工作流
|
||
│
|
||
├── 🎙️ 语音处理模块
|
||
│ ├── asr_core.py # 语音识别核心
|
||
│ ├── omni_client.py # Qwen-Omni 客户端
|
||
│ ├── qwen_extractor.py # 标签提取（中文->英文）
|
||
│ ├── audio_player.py # 音频播放器
|
||
│ └── audio_stream.py # 音频流管理
|
||
│
|
||
├── 🤖 模型相关
|
||
│ ├── yoloe_backend.py # YOLO-E 后端（开放词汇）
|
||
│ ├── trafficlight_detection.py # 红绿灯检测
|
||
│ ├── obstacle_detector_client.py # 障碍物检测客户端
|
||
│ └── models.py # 模型定义
|
||
│
|
||
├── 🎥 视频处理
|
||
│ ├── bridge_io.py # 线程安全的帧缓冲
|
||
│ ├── sync_recorder.py # 音视频同步录制
|
||
│ └── video_recorder.py # 视频录制（旧版）
|
||
│
|
||
├── 🌐 Web 前端
|
||
│ ├── templates/
|
||
│ │ └── index.html # 主界面 HTML
|
||
│ ├── static/
|
||
│ │ ├── main.js # 主 JS 脚本
|
||
│ │ ├── vision.js # 视觉流处理
|
||
│ │ ├── visualizer.js # 数据可视化
|
||
│ │ ├── vision_renderer.js # 渲染器
|
||
│ │ ├── vision.css # 样式表
|
||
│ │ └── models/ # 3D 模型（IMU 可视化）
|
||
│
|
||
├── 🎵 音频资源
|
||
│ ├── music/ # 系统提示音
|
||
│ │ ├── converted_向上.wav
|
||
│ │ ├── converted_向下.wav
|
||
│ │ └── ...
|
||
│ └── voice/ # 预录语音
|
||
│ ├── voice_mapping.json
|
||
│ └── *.wav
|
||
│
|
||
├── 🧠 模型文件
|
||
│ └── model/
|
||
│ ├── yolo-seg.pt # 盲道分割模型
|
||
│ ├── yoloe-11l-seg.pt # YOLO-E 开放词汇模型
|
||
│ ├── shoppingbest5.pt # 物品识别模型
|
||
│ ├── trafficlight.pt # 红绿灯检测模型
|
||
│ └── hand_landmarker.task # MediaPipe 手部模型
|
||
│
|
||
├── 📹 录制文件
|
||
│ └── recordings/ # 自动保存的视频和音频
|
||
│ ├── video_*.avi
|
||
│ └── audio_*.wav
|
||
│
|
||
├── 🛠️ ESP32 固件
|
||
│ └── compile/
|
||
│ ├── compile.ino # Arduino 主程序
|
||
│ ├── camera_pins.h # 摄像头引脚定义
|
||
│ ├── ICM42688.cpp/h # IMU 驱动
|
||
│ └── ESP32_VIDEO_OPTIMIZATION.md
|
||
│
|
||
├── 🧪 测试文件
|
||
│ ├── test_recorder.py # 录制功能测试
|
||
│ ├── test_traffic_light.py # 红绿灯检测测试
|
||
│ ├── test_cross_street_blindpath.py # 导航测试
|
||
│ └── test_crosswalk_awareness.py # 斑马线检测测试
|
||
│
|
||
├── 📚 文档
|
||
│ ├── README.md # 项目主文档
|
||
│ ├── INSTALLATION.md # 安装指南
|
||
│ ├── CONTRIBUTING.md # 贡献指南
|
||
│ ├── FAQ.md # 常见问题
|
||
│ ├── CHANGELOG.md # 更新日志
|
||
│ ├── SECURITY.md # 安全政策
|
||
│ └── PROJECT_STRUCTURE.md # 本文件
|
||
│
|
||
├── 🐳 Docker 相关
|
||
│ ├── Dockerfile # Docker 镜像定义
|
||
│ ├── docker-compose.yml # Docker Compose 配置
|
||
│ └── .dockerignore # Docker 忽略文件
|
||
│
|
||
├── ⚙️ 配置文件
|
||
│ ├── .env.example # 环境变量模板
|
||
│ ├── .gitignore # Git 忽略文件
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ ├── setup.sh # Linux/macOS 安装脚本
|
||
│ └── setup.bat # Windows 安装脚本
|
||
│
|
||
├── 📄 许可证
|
||
│ └── LICENSE # MIT 许可证
|
||
│
|
||
└── 🔧 GitHub 相关
|
||
└── .github/
|
||
├── ISSUE_TEMPLATE/
|
||
│ ├── bug_report.md
|
||
│ └── feature_request.md
|
||
└── pull_request_template.md
|
||
```
|
||
|
||
## 🔑 核心文件说明
|
||
|
||
### 主应用层
|
||
|
||
#### `app_main.py`
|
||
- **作用**: FastAPI 主服务，处理所有 WebSocket 连接
|
||
- **主要功能**:
|
||
- WebSocket 路由管理（/ws/camera, /ws_audio, /ws/viewer 等）
|
||
- 模型加载与初始化
|
||
- 状态协调与管理
|
||
- 音视频流分发
|
||
- **依赖**: 所有其他模块
|
||
- **入口点**: `python app_main.py`
|
||
|
||
#### `navigation_master.py`
|
||
- **作用**: 导航统领器，管理整个系统的状态机
|
||
- **主要状态**:
|
||
- IDLE: 空闲
|
||
- CHAT: 对话模式
|
||
- BLINDPATH_NAV: 盲道导航
|
||
- CROSSING: 过马路
|
||
- TRAFFIC_LIGHT_DETECTION: 红绿灯检测
|
||
- ITEM_SEARCH: 物品查找
|
||
- **核心方法**:
|
||
- `process_frame()`: 处理每一帧
|
||
- `start_blind_path_navigation()`: 启动盲道导航
|
||
- `start_crossing()`: 启动过马路模式
|
||
- `on_voice_command()`: 处理语音命令
|
||
|
||
### 工作流模块
|
||
|
||
#### `workflow_blindpath.py`
|
||
- **作用**: 盲道导航核心逻辑
|
||
- **主要功能**:
|
||
- 盲道分割与检测
|
||
- 障碍物检测
|
||
- 转弯检测
|
||
- 光流稳定
|
||
- 方向引导生成
|
||
- **状态机**:
|
||
- ONBOARDING: 上盲道
|
||
- NAVIGATING: 导航中
|
||
- MANEUVERING_TURN: 转弯
|
||
- AVOIDING_OBSTACLE: 避障
|
||
|
||
#### `workflow_crossstreet.py`
|
||
- **作用**: 过马路导航逻辑
|
||
- **主要功能**:
|
||
- 斑马线检测
|
||
- 方向对齐
|
||
- 引导生成
|
||
- **核心方法**:
|
||
- `_is_crosswalk_near()`: 判断是否接近斑马线
|
||
- `_compute_angle_and_offset()`: 计算角度和偏移
|
||
|
||
#### `yolomedia.py`
|
||
- **作用**: 物品查找工作流
|
||
- **主要功能**:
|
||
- YOLO-E 文本提示检测
|
||
- MediaPipe 手部追踪
|
||
- 光流目标追踪
|
||
- 手部引导（方向提示）
|
||
- 抓取动作检测
|
||
- **模式**:
|
||
- SEGMENT: 检测模式
|
||
- FLASH: 闪烁确认
|
||
- CENTER_GUIDE: 居中引导
|
||
- TRACK: 手部追踪
|
||
|
||
### 语音模块
|
||
|
||
#### `asr_core.py`
|
||
- **作用**: 阿里云 Paraformer ASR 实时语音识别
|
||
- **主要功能**:
|
||
- 实时语音识别
|
||
- VAD（语音活动检测）
|
||
- 识别结果回调
|
||
- **关键类**: `ASRCallback`
|
||
|
||
#### `omni_client.py`
|
||
- **作用**: Qwen-Omni-Turbo 多模态对话客户端
|
||
- **主要功能**:
|
||
- 流式对话生成
|
||
- 图像+文本输入
|
||
- 语音输出
|
||
- **核心函数**: `stream_chat()`
|
||
|
||
#### `audio_player.py`
|
||
- **作用**: 统一的音频播放管理
|
||
- **主要功能**:
|
||
- TTS 语音播放
|
||
- 多路音频混音
|
||
- 音量控制
|
||
- 线程安全播放
|
||
- **核心函数**: `play_voice_text()`, `play_audio_threadsafe()`
|
||
|
||
### 模型后端
|
||
|
||
#### `yoloe_backend.py`
|
||
- **作用**: YOLO-E 开放词汇检测后端
|
||
- **主要功能**:
|
||
- 文本提示设置
|
||
- 实时分割
|
||
- 目标追踪
|
||
- **核心类**: `YoloEBackend`
|
||
|
||
#### `trafficlight_detection.py`
|
||
- **作用**: 红绿灯检测模块
|
||
- **检测方法**:
|
||
1. YOLO 模型检测
|
||
2. HSV 颜色分类（备用）
|
||
- **输出**: 红灯/绿灯/黄灯/未知
|
||
|
||
#### `obstacle_detector_client.py`
|
||
- **作用**: 障碍物检测客户端
|
||
- **主要功能**:
|
||
- 白名单类别过滤
|
||
- 路径掩码内检测
|
||
- 物体属性计算（面积、位置、危险度）
|
||
|
||
### 视频处理
|
||
|
||
#### `bridge_io.py`
|
||
- **作用**: 线程安全的帧缓冲与分发
|
||
- **主要功能**:
|
||
- 生产者-消费者模式
|
||
- 原始帧缓存
|
||
- 处理后帧分发
|
||
- **核心函数**:
|
||
- `push_raw_jpeg()`: 接收 ESP32 帧
|
||
- `wait_raw_bgr()`: 取原始帧
|
||
- `send_vis_bgr()`: 发送处理后的帧
|
||
|
||
#### `sync_recorder.py`
|
||
- **作用**: 音视频同步录制
|
||
- **主要功能**:
|
||
- 同步录制视频和音频
|
||
- 自动文件命名（时间戳）
|
||
- 线程安全
|
||
- **输出**: `recordings/video_*.avi`, `audio_*.wav`
|
||
|
||
### 前端
|
||
|
||
#### `templates/index.html`
|
||
- **作用**: Web 监控界面
|
||
- **主要区域**:
|
||
- 视频流显示
|
||
- 状态面板
|
||
- IMU 3D 可视化
|
||
- 语音识别结果
|
||
|
||
#### `static/main.js`
|
||
- **作用**: 主 JavaScript 逻辑
|
||
- **主要功能**:
|
||
- WebSocket 连接管理
|
||
- UI 更新
|
||
- 事件处理
|
||
|
||
#### `static/vision.js`
|
||
- **作用**: 视觉流处理
|
||
- **主要功能**:
|
||
- WebSocket 接收视频帧
|
||
- Canvas 渲染
|
||
- FPS 计算
|
||
|
||
#### `static/visualizer.js`
|
||
- **作用**: IMU 3D 可视化（Three.js）
|
||
- **主要功能**:
|
||
- 接收 IMU 数据
|
||
- 实时渲染设备姿态
|
||
- 动态灯光效果
|
||
|
||
## 🔄 数据流
|
||
|
||
### 视频流
|
||
```
|
||
ESP32-CAM
|
||
→ [JPEG] WebSocket /ws/camera
|
||
→ bridge_io.push_raw_jpeg()
|
||
→ yolomedia / navigation_master
|
||
→ bridge_io.send_vis_bgr()
|
||
→ [JPEG] WebSocket /ws/viewer
|
||
→ Browser Canvas
|
||
```
|
||
|
||
### 音频流（上行）
|
||
```
|
||
ESP32-MIC
|
||
→ [PCM16] WebSocket /ws_audio
|
||
→ asr_core
|
||
→ DashScope ASR
|
||
→ 识别结果
|
||
→ start_ai_with_text_custom()
|
||
```
|
||
|
||
### 音频流（下行）
|
||
```
|
||
Qwen-Omni / TTS
|
||
→ audio_player
|
||
→ [PCM16] audio_stream
|
||
→ [WAV] HTTP /stream.wav
|
||
→ ESP32-Speaker
|
||
```
|
||
|
||
### IMU 数据流
|
||
```
|
||
ESP32-IMU
|
||
→ [JSON] UDP 12345
|
||
→ process_imu_and_maybe_store()
|
||
→ [JSON] WebSocket /ws
|
||
→ visualizer.js (Three.js)
|
||
```
|
||
|
||
## 🎯 关键设计模式
|
||
|
||
### 1. 状态机模式
|
||
- **位置**: `navigation_master.py`
|
||
- **作用**: 管理系统状态转换
|
||
- **状态**: IDLE → CHAT / BLINDPATH_NAV / CROSSING / ...
|
||
|
||
### 2. 生产者-消费者模式
|
||
- **位置**: `bridge_io.py`
|
||
- **作用**: 解耦视频接收与处理
|
||
- **实现**: 线程 + 队列
|
||
|
||
### 3. 策略模式
|
||
- **位置**: 各 `workflow_*.py`
|
||
- **作用**: 不同导航策略的实现
|
||
- **实现**: 统一的 `process_frame()` 接口
|
||
|
||
### 4. 单例模式
|
||
- **位置**: 模型加载
|
||
- **作用**: 全局共享模型实例
|
||
- **实现**: 全局变量 + 初始化检查
|
||
|
||
### 5. 观察者模式
|
||
- **位置**: WebSocket 通信
|
||
- **作用**: 多客户端订阅视频流
|
||
- **实现**: `camera_viewers: Set[WebSocket]`
|
||
|
||
## 📦 依赖关系
|
||
|
||
```
|
||
app_main.py
|
||
├── navigation_master.py
|
||
│ ├── workflow_blindpath.py
|
||
│ │ ├── yoloe_backend.py
|
||
│ │ └── obstacle_detector_client.py
|
||
│ ├── workflow_crossstreet.py
|
||
│ └── trafficlight_detection.py
|
||
├── yolomedia.py
|
||
│ └── yoloe_backend.py
|
||
├── asr_core.py
|
||
├── omni_client.py
|
||
├── audio_player.py
|
||
├── audio_stream.py
|
||
├── bridge_io.py
|
||
└── sync_recorder.py
|
||
```
|
||
|
||
## 🚀 启动流程
|
||
|
||
1. **初始化阶段** (`app_main.py`)
|
||
- 加载环境变量
|
||
- 加载导航模型（YOLO、MediaPipe）
|
||
- 初始化音频系统
|
||
- 启动录制系统
|
||
- 预加载红绿灯模型
|
||
|
||
2. **服务启动** (FastAPI)
|
||
- 注册 WebSocket 路由
|
||
- 挂载静态文件
|
||
- 启动 UDP 监听（IMU）
|
||
- 启动 HTTP 服务（8081 端口）
|
||
|
||
3. **运行阶段**
|
||
- 等待 ESP32 连接
|
||
- 接收视频/音频/IMU 数据
|
||
- 处理用户语音指令
|
||
- 实时推送处理结果
|
||
|
||
4. **关闭阶段**
|
||
- 停止录制（保存文件）
|
||
- 关闭所有 WebSocket 连接
|
||
- 释放模型资源
|
||
- 清理临时文件
|
||
|
||
---
|
||
|
||
**提示**: 如需了解某个模块的详细实现，请查看相应源文件的注释和 docstring。
|
||
|