William Zhang2026-09-28

基于 MediaPipe Hand Landmarker 的单手捏合 3×3 拼图游戏

使用 MediaPipe Tasks 版 Hand Landmarker 模型上\实时检测单手 21 个关键点与捏合状态，把「拇指 + 食指捏合」直接映射为「拖动 / 释放」语义——玩家在摄像头前用捏合手势完成 ROI 绘制与拼图操作，整个交互链路无键鼠、无触屏。

CVHand TrackingGithub

基于 reComputer-RK / Docker / RKNN / YOLO 的单手捏合拼图游戏

https://github.com/doublelf/puzzle_game

项目简介

本项目构建一个 217 行的纯拼图项目：gesture.py 检测捏合 → drawing.RectDrawer 收两个矩形 → puzzle_game.PuzzleGame 打乱成 3×3 → 同状态机用捏合拖动拼图。

puzzle-draw

快速开始

1. 获取并进入项目目录

bash
git clone https://github.com/doublelf/puzzle_game 
cd puzzle_game

2. 安装依赖

bash
pip install -r requirements.txt

requirements.txt 固定四个依赖：

text
opencv-python>=4.8.0
mediapipe>=0.10.14
numpy>=1.26.0
Pillow>=10.4.0

3. 启动游戏

bash
python main.py                  # 默认摄像头 0，水平镜像开启
python main.py --cam 1          # 使用第 2 个摄像头
python main.py --no-flip        # 关闭水平镜像
python main.py --no-landmarks   # 关闭关键点叠加层（默认开启）
python main.py --hide-trails    # 关闭手势拖尾（默认开启）

启动后会先看到「Pinch-Puzzle」菜单画面，按任意键进入游戏。

4. 操作说明

阶段玩家动作程序反馈
DRAW拇指+食指捏合拖动 → 松开，绘制第一个矩形矩形填充半透明绿色，左上角 Draw rectangles: 1/2
DRAW重复一次，绘制第二个矩形2/2 → READY - generating puzzle...，自动进入 PLAY
PLAY捏合吸附最近拼图块（金色脉冲边框）Toast Tile #N selected + drag toward blank tile 提示
PLAY拖动指尖至邻接空白格附近两块同时绿色闪光 + Toast SWAP!，moves 自增
PLAY9 块归位中央爆裂 80 颗彩虹粒子 + 大字 Toast SOLVED!
全程R 重置当前拼图回到 DRAW 阶段，矩形清空
全程M 返回菜单摄像头持续采集，仅关掉游戏循环
全程ESC 退出释放摄像头、关闭 MediaPipe、销毁窗口

无摄像头环境运行

recomputer-rk3576-devkit 出厂默认没有 USB 摄像头插入；本项目附带三个工具保证在无摄像头下也能端到端跑通：

tools/verify_all.py —— 8 步验证套件

bash
cd /home/seeed/hand/puzzle_game
python3 -m tools.verify_all

逐项打印：

  • 模块导入（gesture / drawing / puzzle_game / overlay / utils）
  • utils 几何 + 文本函数
  • RectDrawer.update(None) 不抛异常
  • shuffle_solvable 产出合法棋盘
  • 真实 MediaPipe Hand Landmarker 在 aarch64 上加载模型（XNNPACK delegate，约 110 ms 预热）
  • HandOverlay.add_event + 渲染
  • 合成 pipeline 60 帧跑完不出错

tools/run_synthetic.py —— 离线渲染到 PNG

bash
python3 -m tools.run_synthetic --frames 180 --out /tmp/puzzle_demo
ls /tmp/puzzle_demo | wc -l      # → 180

驱动完整的 PuzzleGame + HandOverlay，把每一帧写到 out/puzzle_XXXX.png。在无摄像头场景下用 feh / eog / 图片浏览器逐帧查看，或用 ffmpeg 拼成 mp4：

bash
ffmpeg -framerate 30 -i /tmp/puzzle_demo/puzzle_%04d.png -c:v libx264 -pix_fmt yuv420p puzzle.mp4

tools/synthetic_source.py + tools/fake_tracker.py

合成视频源与合成 HandTracker，以接口完全等价于 cv2.VideoCapture / gesture.HandTracker 的形式存在；如果未来要接入真实摄像头，只需把这两行替换为：

python
cap = cv2.VideoCapture(args.cam)               # 替换 SyntheticHandSource
tracker = HandTracker(num_hands=2)              # 替换 SyntheticHandTracker

即可让 tools/run_synthetic.py 升级为真实摄像头驱动脚本。