# 项目结构说明

本文档详细说明项目的目录结构和主要文件的作用。

## 📁 目录结构

```
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。

