checkhand/LOCAL_TEST_GUIDE.md

# 📹 本地测试指南

## 🎯 测试视频文件放置位置

### 推荐目录结构：
```
checkHand/
├── data/
│   └── videos/          # 测试视频目录
│       ├── test_basic.mp4      # 基础移动测试视频
│       ├── test_gesture.mp4    # 手势测试视频
│       ├── your_video.mp4      # 你的自定义视频
│       └── real_hand.mp4       # 真实手部动作视频
```

## 🚀 快速开始本地测试

### 1. 使用自动生成的测试视频

```bash
# 生成测试视频
python create_test_video.py

# 使用基础移动测试视频
./start_service.sh --test-video data/videos/test_basic.mp4

# 使用手势测试视频
./start_service.sh --test-video data/videos/test_gesture.mp4
```

### 2. 使用你自己的视频文件

#### 支持的视频格式：
- MP4 (推荐)
- AVI
- MOV
- MKV

#### 推荐视频参数：
- 分辨率：640x480 或 1280x720
- 帧率：30 FPS
- 编码：H.264
- 时长：10-60秒（测试用）

#### 放置你的视频：
```bash
# 1. 将视频文件复制到测试目录
cp /path/to/your/video.mp4 data/videos/

# 2. 启动服务器并使用你的视频
./start_service.sh --test-video data/videos/your_video.mp4
```

## 🎬 创建自定义测试视频

### 使用脚本生成：
```bash
# 生成基础移动测试视频（10秒）
python create_test_video.py --type basic --duration 10

# 生成手势测试视频（15秒）
python create_test_video.py --type gesture --duration 15

# 生成两种类型的视频
python create_test_video.py --type both --duration 12

# 自定义帧率和输出目录
python create_test_video.py --fps 60 --output-dir my_videos/
```

### 使用手机录制真实手部视频：

#### 录制建议：
1. **光线充足** - 避免阴影和反光
2. **背景简单** - 纯色背景最佳
3. **手部清晰** - 确保手部在画面中央
4. **动作缓慢** - 便于算法跟踪
5. **时长适中** - 10-30秒即可

#### 录制内容示例：
- 手掌张开和握拳
- 手指抓取动作
- 手部左右移动
- 手部上下移动
- 手部前后移动（改变大小）

#### 文件转换：
```bash
# 如果需要转换格式，可以使用 ffmpeg
ffmpeg -i input.mov -c:v libx264 -c:a aac data/videos/output.mp4
```

## 🔧 测试步骤

### 1. 准备测试环境

```bash
# 1. 确保虚拟环境已激活
source venv/bin/activate

# 2. 检查测试视频是否存在
ls -la data/videos/

# 3. 运行系统测试
python test_system.py
```

### 2. 启动测试服务

```bash
# 方式1：使用启动脚本
./start_service.sh --test-video data/videos/test_basic.mp4

# 方式2：手动启动
python run_web_service.py --test-video data/videos/test_basic.mp4
```

### 3. 访问测试界面

1. 打开浏览器访问：`http://localhost:5000`
2. 观察Web界面显示：
   - 实时视频预览
   - 手部检测结果
   - 3D坐标值
   - 控制信号

### 4. 测试机械臂客户端

```bash
# 新开一个终端窗口
./start_robot_client.sh

# 或者手动启动
cd src
python robot_client.py --mock
```

## 📊 测试检查项

### ✅ 视频显示检查：
- [ ] 视频正常播放
- [ ] 手部检测框显示正确
- [ ] 关键点连接线正常
- [ ] 坐标轴指示器显示

### ✅ 数据输出检查：
- [ ] X、Y、Z角度值变化
- [ ] 抓取状态检测
- [ ] 动作识别正确
- [ ] FPS显示正常

### ✅ 通信检查：
- [ ] WebSocket连接正常
- [ ] 机械臂客户端接收信号
- [ ] 控制信号格式正确
- [ ] 实时性满足要求

## 🛠️ 常见问题排查

### 问题1：视频无法播放
```bash
# 检查视频文件
file data/videos/your_video.mp4

# 检查视频信息
ffmpeg -i data/videos/your_video.mp4 2>&1 | head -20
```

### 问题2：检测效果不佳
- 检查视频光线条件
- 确认手部在画面中央
- 尝试不同的视频文件
- 调整MediaPipe参数

### 问题3：性能问题
```bash
# 降低视频分辨率
ffmpeg -i input.mp4 -vf scale=640:480 output.mp4

# 减少帧率
ffmpeg -i input.mp4 -r 15 output.mp4
```

## 📈 性能测试

### 测试延迟：
```bash
# 启动服务器
./start_service.sh --test-video data/videos/test_basic.mp4

# 在另一个终端查看延迟
curl -s http://localhost:5000/api/status | jq .fps
```

### 测试负载：
```bash
# 启动多个机械臂客户端
for i in {1..5}; do
    python src/robot_client.py --mock &
done
```

## 🎯 高级测试

### 使用真实摄像头：
```python
# 创建摄像头测试脚本
import cv2
import socketio
import base64

sio = socketio.Client()
sio.connect('http://localhost:5000')
sio.emit('register_client', {'type': 'video_source'})

cap = cv2.VideoCapture(0)
while True:
    ret, frame = cap.read()
    if ret:
        _, buffer = cv2.imencode('.jpg', frame)
        frame_data = base64.b64encode(buffer).decode('utf-8')
        sio.emit('video_frame', {'frame': frame_data})
    time.sleep(1/30)
```

### 性能监控：
```bash
# 监控资源使用
top -p $(pgrep -f "python run_web_service.py")

# 监控网络流量
netstat -i
```

## 🎉 测试完成

测试完成后，你应该能看到：
- 实时视频流处理
- 准确的手部检测
- 正确的3D坐标计算
- 稳定的WebSocket通信
- 机械臂控制信号输出

现在你可以将真实的视频流连接到系统，或者集成到你的机械臂控制系统中！