checkhand/LOCAL_TEST_GUIDE.md

📹 本地测试指南

🎯 测试视频文件放置位置

推荐目录结构：

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

🚀 快速开始本地测试

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

# 生成测试视频
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秒（测试用）

放置你的视频：

# 1. 将视频文件复制到测试目录
cp /path/to/your/video.mp4 data/videos/

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

🎬 创建自定义测试视频

使用脚本生成：

# 生成基础移动测试视频（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秒即可

录制内容示例：

• 手掌张开和握拳
• 手指抓取动作
• 手部左右移动
• 手部上下移动
• 手部前后移动（改变大小）

文件转换：

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

🔧 测试步骤

1. 准备测试环境

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

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

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

2. 启动测试服务

# 方式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. 测试机械臂客户端

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

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

📊 测试检查项

✅ 视频显示检查：

• 视频正常播放
• 手部检测框显示正确
• 关键点连接线正常
• 坐标轴指示器显示

✅ 数据输出检查：

• X、Y、Z角度值变化
• 抓取状态检测
• 动作识别正确
• FPS显示正常

✅ 通信检查：

• WebSocket连接正常
• 机械臂客户端接收信号
• 控制信号格式正确
• 实时性满足要求

🛠️ 常见问题排查

问题1：视频无法播放

# 检查视频文件
file data/videos/your_video.mp4

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

问题2：检测效果不佳

• 检查视频光线条件
• 确认手部在画面中央
• 尝试不同的视频文件
• 调整MediaPipe参数

问题3：性能问题

# 降低视频分辨率
ffmpeg -i input.mp4 -vf scale=640:480 output.mp4

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

📈 性能测试

测试延迟：

# 启动服务器
./start_service.sh --test-video data/videos/test_basic.mp4

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

测试负载：

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

🎯 高级测试

使用真实摄像头：

# 创建摄像头测试脚本
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)

性能监控：

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

# 监控网络流量
netstat -i

🎉 测试完成

测试完成后，你应该能看到：

• 实时视频流处理
• 准确的手部检测
• 正确的3D坐标计算
• 稳定的WebSocket通信
• 机械臂控制信号输出

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