# 实时手部检测Web服务系统

一个基于MediaPipe的实时手部检测系统，支持WebSocket通信、实时视频流处理和机械臂控制。

## 快速开始

### 方式一：使用启动脚本（推荐）

#### Linux/Mac:
```bash
# 启动Web服务器（自动创建虚拟环境并安装依赖）
./start_service.sh

# 启动机械臂客户端（新终端窗口）
./start_robot_client.sh
```

#### Windows:
```batch
# 启动Web服务器（自动创建虚拟环境并安装依赖）
start_service.bat

# 启动机械臂客户端（新命令行窗口）
start_robot_client.bat
```

### 方式二：手动启动

#### 1. 创建虚拟环境并安装依赖

```bash
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows
pip install -r requirements.txt
```

#### 2. 启动Web服务器

```bash
python run_web_service.py
```

#### 3. 启动机械臂客户端（可选）

```bash
cd src
python robot_client.py --mock
```

### 3. 访问Web界面

打开浏览器访问: `http://localhost:5000`

## 启动脚本选项

### Web服务器启动选项:
```bash
./start_service.sh --help                    # 查看帮助
./start_service.sh                           # 基本启动
./start_service.sh --host 0.0.0.0 --port 8080  # 自定义地址和端口
./start_service.sh --debug                   # 调试模式
./start_service.sh --test-video data/videos/test.mp4  # 本地视频测试
```

### 机械臂客户端启动选项:
```bash
./start_robot_client.sh --help               # 查看帮助
./start_robot_client.sh                      # 基本启动（模拟模式）
./start_robot_client.sh --server http://192.168.1.100:5000  # 连接远程服务器
./start_robot_client.sh --real               # 真实机械臂模式
```

## 功能特性

- ✅ 使用MediaPipe进行实时手部检测  
- ✅ WebSocket实时通信
- ✅ 3D坐标计算（X、Y、Z轴角度）
- ✅ Web预览界面
- ✅ 机械臂控制接口
- ✅ 本地视频测试支持

## 系统架构

```
视频客户端 → Web服务器 → MediaPipe → 3D坐标计算 → 客户端(Web预览/机械臂)
```

## 控制信号格式

```json
{
  "x_angle": 90.0,      // X轴角度 (0-180°)
  "y_angle": 90.0,      // Y轴角度 (0-180°)  
  "z_angle": 90.0,      // Z轴角度 (0-180°)
  "grip": 0,            // 抓取状态 (0=松开, 1=抓取)
  "action": "none",     // 当前动作
  "speed": 5            // 移动速度 (1-10)
}
```